Google 服务账号

服务账号是一种专为脚本使用的 Google 账号：它拥有一个邮箱地址，通过密钥文件进行身份验证，并可访问已明确共享给该邮箱地址的任意 Doc / Sheet / Drive 文件 / Calendar —— 共享方式与向同事共享完全一致。无需浏览器授权、无需人工点击“允许”、也无需刷新访问令牌。

1. 您是否已有密钥？

请检查当前工作目录下是否存在 credentials.json 文件，或是否存在名为 CREDS_JSON 的环境变量，其值为包含密钥信息的 JSON 字符串。该服务账号的邮箱地址即该 JSON 中的 client_email 字段（格式如：name@project.iam.gserviceaccount.com）。若您已具备该密钥，请直接跳至第 3 步。

2. 尚无密钥 —— 引导用户完成配置流程

请明确告知用户：此过程完全免费，且仅需一个基础 Google 账号即可完成。 使用个人 gmail.com 邮箱即可 —— 无需信用卡，也无需开通结算账号。创建项目、服务账号及密钥均不产生任何费用；Sheets / Docs / Drive / Calendar 等 API 在 generous 的每日配额内亦完全免费。该配置为一次性操作，耗时仅需几分钟。

若用户已安装 gcloud CLI 工具，请提供以下命令供其执行：

gcloud auth login
PROJECT="agent-bot-$(date +%s)"
gcloud projects create "$PROJECT"
gcloud config set project "$PROJECT"
gcloud services enable sheets.googleapis.com drive.googleapis.com 
  docs.googleapis.com calendar-json.googleapis.com
gcloud iam service-accounts create agent-bot --display-name="Agent Bot"
SA="agent-bot@${PROJECT}.iam.gserviceaccount.com"
gcloud iam service-accounts keys create credentials.json --iam-account="$SA"
echo "现在请将您的文件/日历共享给：$SA"

若用户未安装 CLI 工具，请引导其参考 README.md 中的控制台向导（标题为“Click through the console”）—— 全程约 20 次点击，同样完全免费。无论采用哪种方式，最终结果一致：获得一个 credentials.json 文件及其中的 client_email。

3. 唯一规则：必须共享目标文件

服务账号默认无任何访问权限。对于每一个您需要操作的文件，用户都必须手动打开该文件 → 点击共享 → 粘贴 client_email → 设置权限为编辑者（如仅需只读，则设为查看者）→ 发送。对于日历：进入其设置 → 选择与特定人员共享。

若遇到 SpreadsheetNotFound 或 403 PERMISSION_DENIED 错误，几乎可以确定并非代码缺陷 —— 而是目标文件尚未被共享。 请明确告知用户具体是哪个文件、以及应使用哪个 client_email，以便其一键修复。切勿盲目重试。

4. 使用密钥

可运行示例位于 quickstart.py（执行命令：python quickstart.py sheets|docs|calendar）。核心用法如下：

Sheets（通过友好的封装库 gspread —— 其默认作用域已包含 drive，因此可通过名称直接调用 open()）：

import gspread
gc = gspread.service_account(filename="credentials.json")
sh = gc.open("My Spreadsheet")                 # 仅因该表格已共享给服务账号，故可成功打开
sh.sheet1.update(values=[["hello", "from a robot"]])
sh.sheet1.append_row(["logged", "by agent"])   # 代理最常用的操作

其他任意 API（Docs、Calendar、Drive 等）则通过 google-api-python-client 访问 —— 同一份凭据对象可驱动所有 API，仅需调整作用域（scopes）列表即可：

from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    "credentials.json", scopes=["https://www.googleapis.com/auth/documents"])
docs = build("docs", "v1", credentials=creds)

在容器或 CI 环境中，请改从环境变量加载密钥而非读取文件：

import os, json, gspread
gc = gspread.service_account_from_dict(json.loads(os.environ["CREDS_JSON"]))

5. 边界限制 —— 请勿绕过这些约束

• 始终申请最小必要的作用域（scope）；除非确需写入，否则务必添加 .readonly 后缀。编辑文档前，请先以只读方式读取它。
• 服务账号无法访问用户的私有 Gmail、个人日历或整个 Drive —— 它仅能访问明确共享给它的内容。若需访问上述私有数据，则必须由用户本人完成 OAuth 浏览器授权流程；切勿尝试以服务账号替代此步骤。
• Calendar：共享日历的 ID 即为其所有者的邮箱地址（calendarId="primary" 表示服务账号自身空置的日历），且服务账号无法为事件添加参会人 —— Google 将返回 forbiddenForServiceAccounts 错误。您可以自由创建、修改或删除事件，但切勿尝试发送邀请。
• 服务账号的邮箱地址仅作为身份标识，而非真实邮箱 —— 发往该地址的邮件将被退回。它无法注册任何服务，也无法接收确认链接。
• 请将 credentials.json 视为密码：持有该文件者即等同于该服务账号本身。切勿将其提交至代码仓库，也切勿粘贴至任何共享环境中。

详见 README.md 中的完整说明 —— 包括为何此方案优于自行搭建 OAuth 应用、免费额度详情、作用域参考表，以及常见问题排查指南。