google-loops

Google Loops — 设置与日常运行

此连接器会将 Gmail 邮件会话、日历事件和联系人导入大脑，并维护 gbrain waiting 背后的未完成事项记录。完整参考文档：docs/guides/google-connect.md（设置及所有错误和修复方法）和 docs/guides/open-loops.md（检测工作原理）。

Harness 约定（请先阅读）

1. 原样转发 [SHOW USER] 区块。 设置命令会输出带围栏的 [SHOW USER] ... [/SHOW USER] 区块，其中包含带深层链接的编号步骤。请原样交给用户（改述会丢失“桌面应用，而非 Web 应用”等关键细节）。将所有内容合并为每个区块一条消息。
2. 整个设置过程恰好需要与用户交互两次。（1）提供 Google Cloud 检查清单，用户随后交回下载的客户端 JSON。（2）用户点击一个授权 URL。如果你发现自己要问第三个问题，请重新阅读你跳过的区块。
3. 尽可能不要在 argv 或聊天中放入密钥。 用户在聊天中发送 client_secret_*.json 时，将其保存到文件（模式为 0600），并传入路径：gbrain google connect --client-json <path>。也可以使用环境变量（GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET）。原始的 --client-id/--client-secret 标志应作为最后手段。
4. 每条命令都以 JSON 格式输出。 添加 --json 并读取 { ok, status, next_action: { command, user_message }, error }。存在 next_action.user_message 时，它就是要展示给用户的消息；存在 next_action.command 时，它就是下一条要调用的命令。错误包含 { code, problem, cause, fix, doc_url }——只向用户展示 problem + fix，不要展示其他内容。
5. 重新运行始终安全。 gbrain google connect 和 gbrain google setup 是幂等状态机；大多数错误的文档化修复方法都是“重新运行”。

设置（只需一条命令）

gbrain google setup --json

处理内容：凭据接收（没有已保存凭据时会输出 GCP 检查清单）→ 授权（本机通过 loopback 完成；通过 SSH/无头模式时会自动粘贴回传——非 TTY 流程会在第二次调用时完成： gbrain google connect --code "<pasted-redirect-url>"）→ 注册数据源 → 按预算执行首次同步（优先同步最新邮件；后续同步时会自动继续深度回填）→ 生成首份 gbrain waiting 摘要。

多个账号：使用 --account [email protected] 重复操作。

如果你已通过其他方式获得 Google 访问权限（使用自身身份验证的 Google CLI、gcloud、可签发令牌的凭据网关），可以跳过 OAuth，直接将数据源指向它——无需将凭据交给 gbrain：

gbrain sources add gmail-work --kind google --account [email protected] \
  --access command --token-command "<command that prints an access token>"

（--access env --token-env <VAR> 则会从环境变量读取外部刷新的令牌。）之后，gbrain sync --source gmail-work 和 gbrain waiting 的工作方式相同。

之后验证运行状况：gbrain google status --json（逐账号刷新探测）——gbrain doctor 还包含 google_oauth 检查项，如果处于 Testing 模式的账号连续 5 天以上未成功刷新，就会发出一次警告。正在积极同步的账号不会在 Testing 模式 7 天到期前收到预警——真正的修复方法是发布到 Production。

日常操作

gbrain waiting --json        # the killer output: ranked people waiting
gbrain loops done <id>       # user handled it
gbrain loops drop <id>       # user is not going to do it
gbrain loops mute sender <email>   # never track this sender again (closes its open reply-owed loops)
gbrain loops unmute sender <email> # undo; the loops it closed are re-checked on the next sync
gbrain loops drop sender <email> --dry-run   # preview closing one sender's reply-owed loops

• waiting 可能以 withheld_noise 结束：发件人邮件为自动邮件（银行或物流提醒）的待回复循环。向用户展示每个 preview_command 并运行它（--dry-run 不会更改任何内容）；只有在用户同意后才予以丢弃：丢弃后无法撤销。如果用户想停止但保留撤销选项，请提供 loops mute sender。

• 如果数据已过期（24 小时内没有成功同步），waiting 会拒绝执行，并指出确切的修复方法（gbrain sync --source <id>）。运行同步，然后重试。只有在用户明确接受过期结果时才使用 --stale-ok。

• completeness: "partial" 表示过去 14 天内有部分邮件因多次导入失败而被暂存（列于 held）。应将答案标明为不完整：逐项列出被暂存的邮件（发件人，以及显示时的主题）及其重试命令（gbrain sources retry-held <id>）。答案不完整时，绝不能说“你的邮件已全部处理完毕”。

• 展示循环时，请列出：对方、待处理事项（摘要）、证据引文、深层链接（可在正确的账号中打开对应的 Gmail 会话），以及适用时的截止日期。trusted-local 结果已包含可直接粘贴的 text 摘要，请直接复用。

• 对于“回复所需背景”：每个分组都包含对方的实体卡片（摘要、近期记录、其他未结会话）。如需更多信息，请使用对方的 slug 调用 context_pack。

• 用户表示已回复／处理某事后，请关闭该循环（loops done）；如果 Gmail 中已显示回复，会话循环也会在下次同步时自动关闭。

持续导入

Google 来源与其他来源一样同步：autopilot 和 gbrain sync --all 会自动处理它们。它没有自己的 cron。单独运行、不指定目标的 gbrain sync 不会处理它们——请使用 --source <id> 或 --all。

故障排除

每种故障都有对应的代码和附带的修复方法—— docs/guides/google-connect.md#troubleshooting 是权威的对照表。用户实际最可能遇到以下三种情况：

• 在授权过程中出现 “Google 尚未验证此应用” → 这是预期情况；这是用户自己的应用：选择 Advanced → Continue。点击 URL 之前，先提醒用户。
• access_denied_test_user → 用户忘了将自己添加为测试用户（错误中包含深层链接）。
• invalid_grant_testing_expiry（约第 7 天后一切悄然停止）→ 用户的授权同意屏幕仍处于 Testing 状态；将其发布到 Production，然后运行 gbrain google connect --reauth <email>。

成本说明

承诺提取会将近期邮件文本（≤30 天，≤50 个会话／每轮扫描）发送到已配置的聊天服务提供商。设置期间告知用户一次；关闭开关的命令为 gbrain config set loops.extraction_enabled false。未回复会话检测器免费且不受影响。

输出格式

转述 gbrain waiting 时，按对方分组，最紧急的排在前面，然后最后列出 ## No counterparty 部分（未指明具体人员的循环）：

## <Counterparty> (<N> open)
- [<loop_type>] <what's owed> (<age>) — due <date if any>
  > "<evidence quote>"
  <Gmail deep link>

trusted-local 的 --json 结果已包含可直接粘贴的 text 字段——优先转述该字段，而不要重新排版。对于设置命令，请原样转述 [SHOW USER] 区块；发生故障时，请提供 error.problem 和 error.fix；绝不要向用户输出原始 JSON 信封。

失败时

对于任何 gbrain 错误 code、退出代码、[AGENT] 块或通知块，请遵循Agent 操作员协议。此技能的具体说明：

• 设置过程会输出 [SHOW USER] 块：逐块原样转发，每个块单独发送一条消息。gbrain mcp expose 和 gbrain google 在需要用户确认时仍会以代码 2 退出（这是已记录的旧行为），因此要阅读块内容，不能只看退出代码。
• Google 凭据错误（invalid_grant_revoked、consent_timeout、wrong_account_consented 等）会附带 { code, problem, cause, fix }：向用户说明问题和修复方法；大多数情况下，修复方法是让用户“重新运行”。
• gbrain waiting 遇到过期数据时会拒绝执行，或报告因保留项目导致的部分覆盖率：运行它指定的同步命令，或运行 gbrain sources status <id>，然后在用户同意后运行 gbrain sources retry-held <id>。

反模式

• 改述 [SHOW USER] 块。 检查清单包含关键细节（“桌面应用，而非 Web 应用”、测试用户步骤）。请逐块原样转发，每个块单独发送一条消息。
• 在聊天中向用户索要 client_id/client_secret。 将下载的 JSON 作为 0600 权限文件传入（--client-json <path>），或使用环境变量；在命令行参数或聊天中提供机密信息只能作为最后手段，绝不能作为默认方式。
• 通过 query/search 回答“谁在等我”。 未完成事项记录在 open_loops / gbrain waiting 中；搜索结果没有未完成事项状态语义，并且可能会显示已有回复的对话。
• 遗漏 completeness: "partial"。 没有未完成事项的部分回答，并不代表收件箱为空；要说明哪些项目被保留，以及如何重新尝试处理。
• 不提示便通过 --stale-ok 绕过过期数据拒绝。 先运行指定的 gbrain sync --source <id>；只有当用户明确接受未完成事项可能已过期时，才传入 --stale-ok。
• 替用户将未完成事项标记为完成。 只有在用户表示已处理后，才运行关闭命令（gbrain loops done <id>）；当 Gmail 中可见回复时，对话中的未完成事项会在下次同步时自动关闭。