@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/automation/cron-vs-heartbeat.md

@@ -0,0 +1,286 @@
+---
+read_when:
+  - 决定如何调度周期性任务
+  - 设置后台监控或通知
+  - 优化定期检查的 token 用量
+summary: 选择心跳还是定时任务进行自动化的指南
+title: 定时任务与心跳对比
+x-i18n:
+  generated_at: "2026-02-01T19:38:18Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 5f71a63181baa41b1c307eb7bfac561df7943d4627077dfa2861eb9f76ab086b
+  source_path: automation/cron-vs-heartbeat.md
+  workflow: 14
+---
+
+# 定时任务与心跳：何时使用哪种方式
+
+心跳和定时任务都可以按计划运行任务。本指南帮助你根据使用场景选择合适的机制。
+
+## 快速决策指南
+
+| 使用场景                  | 推荐方式                   | 原因                                     |
+| ------------------------- | -------------------------- | ---------------------------------------- |
+| 每 30 分钟检查收件箱      | 心跳                       | 可与其他检查批量处理，具备上下文感知能力 |
+| 每天上午 9 点准时发送报告 | 定时任务（隔离式）         | 需要精确定时                             |
+| 监控日历中即将到来的事件  | 心跳                       | 天然适合周期性感知                       |
+| 运行每周深度分析          | 定时任务（隔离式）         | 独立任务，可使用不同模型                 |
+| 20 分钟后提醒我           | 定时任务（主会话，`--at`） | 精确定时的一次性任务                     |
+| 后台项目健康检查          | 心跳                       | 搭载在现有周期上                         |
+
+## 心跳：周期性感知
+
+心跳在**主会话**中以固定间隔运行（默认：30 分钟）。它的设计目的是让智能体检查各种事项并呈现重要信息。
+
+### 何时使用心跳
+
+- **多个周期性检查**：与其设置 5 个独立的定时任务分别检查收件箱、日历、天气、通知和项目状态，不如用一次心跳批量处理所有内容。
+- **上下文感知决策**：智能体拥有完整的主会话上下文，因此可以智能判断哪些紧急、哪些可以等待。
+- **对话连续性**：心跳运行共享同一会话，因此智能体记得最近的对话，可以自然地进行后续跟进。
+- **低开销监控**：一次心跳替代多个小型轮询任务。
+
+### 心跳优势
+
+- **批量处理多项检查**：一次智能体轮次可以同时审查收件箱、日历和通知。
+- **减少 API 调用**：一次心跳比 5 个隔离式定时任务更经济。
+- **上下文感知**：智能体了解你一直在做什么，可以据此排定优先级。
+- **智能抑制**：如果没有需要关注的事项，智能体回复 `HEARTBEAT_OK`，不会投递任何消息。
+- **自然定时**：会根据队列负载略有漂移，但对大多数监控来说没有问题。
+
+### 心跳示例：HEARTBEAT.md 检查清单
+
+```md
+# Heartbeat checklist
+
+- Check email for urgent messages
+- Review calendar for events in next 2 hours
+- If a background task finished, summarize results
+- If idle for 8+ hours, send a brief check-in
+```
+
+智能体在每次心跳时读取此清单，并在一次轮次中处理所有项目。
+
+### 配置心跳
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m", // 间隔
+        target: "last", // 告警投递目标
+        activeHours: { start: "08:00", end: "22:00" }, // 可选
+      },
+    },
+  },
+}
+```
+
+完整配置请参阅[心跳](/gateway/heartbeat)。
+
+## 定时任务：精确调度
+
+定时任务在**精确时间**运行，可以在隔离会话中运行而不影响主会话上下文。
+
+### 何时使用定时任务
+
+- **需要精确定时**："每周一上午 9:00 发送"（而不是"大约 9 点左右"）。
+- **独立任务**：不需要对话上下文的任务。
+- **不同的模型/思维级别**：需要更强大模型的深度分析。
+- **一次性提醒**：使用 `--at` 实现"20 分钟后提醒我"。
+- **嘈杂/频繁的任务**：会把主会话历史搞得杂乱的任务。
+- **外部触发器**：无论智能体是否处于活跃状态都应独立运行的任务。
+
+### 定时任务优势
+
+- **精确定时**：支持带时区的 5 字段 cron 表达式。
+- **会话隔离**：在 `cron:<jobId>` 中运行，不会污染主会话历史。
+- **模型覆盖**：可按任务使用更便宜或更强大的模型。
+- **投递控制**：隔离任务默认以 `announce` 投递摘要，可选 `none` 仅内部运行。
+- **无需智能体上下文**：即使主会话空闲或已压缩，也能运行。
+- **一次性支持**：`--at` 用于精确的未来时间戳。
+
+### 定时任务示例：每日早间简报
+
+```bash
+quantumclaw cron add \
+  --name "Morning briefing" \
+  --cron "0 7 * * *" \
+  --tz "America/New_York" \
+  --session isolated \
+  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
+  --model opus \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+这会在纽约时间每天早上 7:00 准时运行，使用 Opus 保证质量，并直接投递到 WhatsApp。
+
+### 定时任务示例：一次性提醒
+
+```bash
+quantumclaw cron add \
+  --name "Meeting reminder" \
+  --at "20m" \
+  --session main \
+  --system-event "Reminder: standup meeting starts in 10 minutes." \
+  --wake now \
+  --delete-after-run
+```
+
+完整 CLI 参考请参阅[定时任务](/automation/cron-jobs)。
+
+## 决策流程图
+
+```
+任务是否需要在精确时间运行？
+  是 -> 使用定时任务
+  否 -> 继续...
+
+任务是否需要与主会话隔离？
+  是 -> 使用定时任务（隔离式）
+  否 -> 继续...
+
+此任务能否与其他周期性检查批量处理？
+  是 -> 使用心跳（添加到 HEARTBEAT.md）
+  否 -> 使用定时任务
+
+这是一次性提醒吗？
+  是 -> 使用定时任务配合 --at
+  否 -> 继续...
+
+是否需要不同的模型或思维级别？
+  是 -> 使用定时任务（隔离式）配合 --model/--thinking
+  否 -> 使用心跳
+```
+
+## 组合使用
+
+最高效的配置是**两者结合**：
+
+1. **心跳**处理常规监控（收件箱、日历、通知），每 30 分钟批量处理一次。
+2. **定时任务**处理精确调度（每日报告、每周回顾）和一次性提醒。
+
+### 示例：高效自动化配置
+
+**HEARTBEAT.md**（每 30 分钟检查一次）：
+
+```md
+# Heartbeat checklist
+
+- Scan inbox for urgent emails
+- Check calendar for events in next 2h
+- Review any pending tasks
+- Light check-in if quiet for 8+ hours
+```
+
+**定时任务**（精确定时）：
+
+```bash
+# 每天早上 7 点的早间简报
+quantumclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
+
+# 每周一上午 9 点的项目回顾
+quantumclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
+
+# 一次性提醒
+quantumclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
+```
+
+## Lobster：带审批的确定性工作流
+
+Lobster 是用于**多步骤工具管道**的工作流运行时，适用于需要确定性执行和明确审批的场景。当任务不只是单次智能体轮次，且你需要可恢复的带人工检查点的工作流时，使用它。
+
+### 何时适合使用 Lobster
+
+- **多步骤自动化**：你需要一个固定的工具调用管道，而不是一次性提示。
+- **审批关卡**：副作用应暂停直到你批准，然后继续执行。
+- **可恢复运行**：继续暂停的工作流而无需重新运行之前的步骤。
+
+### 如何与心跳和定时任务配合
+
+- **心跳/定时任务**决定*何时*运行。
+- **Lobster** 定义运行开始后*执行哪些步骤*。
+
+对于计划性工作流，使用定时任务或心跳触发一次调用 Lobster 的智能体轮次。对于临时工作流，直接调用 Lobster。
+
+### 操作说明（来自代码）
+
+- Lobster 以**本地子进程**（`lobster` CLI）在工具模式下运行，并返回 **JSON 信封**。
+- 如果工具返回 `needs_approval`，你需要使用 `resumeToken` 和 `approve` 标志来恢复。
+- 该工具是**可选插件**；建议通过 `tools.alsoAllow: ["lobster"]` 附加启用。
+- 如果传入 `lobsterPath`，必须是**绝对路径**。
+
+完整用法和示例请参阅 [Lobster](/tools/lobster)。
+
+## 主会话与隔离会话
+
+心跳和定时任务都可以与主会话交互，但方式不同：
+
+|        | 心跳                     | 定时任务（主会话）     | 定时任务（隔离式）    |
+| ------ | ------------------------ | ---------------------- | --------------------- |
+| 会话   | 主会话                   | 主会话（通过系统事件） | `cron:<jobId>`        |
+| 历史   | 共享                     | 共享                   | 每次运行全新          |
+| 上下文 | 完整                     | 完整                   | 无（从零开始）        |
+| 模型   | 主会话模型               | 主会话模型             | 可覆盖                |
+| 输出   | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件        | announce 摘要（默认） |
+
+### 何时使用主会话定时任务
+
+当你需要以下场景时，使用 `--session main` 配合 `--system-event`：
+
+- 提醒/事件出现在主会话上下文中
+- 智能体在下一次心跳时带着完整上下文处理它
+- 不需要单独的隔离运行
+
+```bash
+quantumclaw cron add \
+  --name "Check project" \
+  --every "4h" \
+  --session main \
+  --system-event "Time for a project health check" \
+  --wake now
+```
+
+### 何时使用隔离式定时任务
+
+当你需要以下场景时，使用 `--session isolated`：
+
+- 无先前上下文的全新环境
+- 不同的模型或思维设置
+- 输出可通过 `announce` 直接投递摘要（或用 `none` 仅内部运行）
+- 不会把主会话搞得杂乱的历史记录
+
+```bash
+quantumclaw cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 0" \
+  --session isolated \
+  --message "Weekly codebase analysis..." \
+  --model opus \
+  --thinking high \
+  --announce
+```
+
+## 成本考量
+
+| 机制               | 成本特征                                       |
+| ------------------ | ---------------------------------------------- |
+| 心跳               | 每 N 分钟一次轮次；随 HEARTBEAT.md 大小扩展    |
+| 定时任务（主会话） | 将事件添加到下一次心跳（无隔离轮次）           |
+| 定时任务（隔离式） | 每个任务一次完整智能体轮次；可使用更便宜的模型 |
+
+**建议**：
+
+- 保持 `HEARTBEAT.md` 精简以减少 token 开销。
+- 将类似的检查批量放入心跳，而不是创建多个定时任务。
+- 如果只需要内部处理，在心跳上使用 `target: "none"`。
+- 对常规任务使用隔离式定时任务配合更便宜的模型。
+
+## 相关内容
+
+- [心跳](/gateway/heartbeat) - 完整的心跳配置
+- [定时任务](/automation/cron-jobs) - 完整的定时任务 CLI 和 API 参考
+- [系统](/cli/system) - 系统事件 + 心跳控制

package/docs/zh-CN/automation/gmail-pubsub.md

@@ -0,0 +1,249 @@
+---
+read_when:
+  - 将 Gmail 收件箱触发器接入 QuantumClaw
+  - 为智能体唤醒设置 Pub/Sub 推送
+summary: 通过 gogcli 将 Gmail Pub/Sub 推送接入 QuantumClaw webhooks
+title: Gmail PubSub
+x-i18n:
+  generated_at: "2026-02-03T07:43:25Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: dfb92133b69177e4e984b7d072f5dc28aa53a9e0cf984a018145ed811aa96195
+  source_path: automation/gmail-pubsub.md
+  workflow: 15
+---
+
+# Gmail Pub/Sub -> QuantumClaw
+
+目标：Gmail watch -> Pub/Sub 推送 -> `gog gmail watch serve` -> QuantumClaw webhook。
+
+## 前置条件
+
+- 已安装并登录 `gcloud`（[安装指南](https://docs.cloud.google.com/sdk/docs/install-sdk)）。
+- 已安装 `gog` (gogcli) 并为 Gmail 账户授权（[gogcli.sh](https://gogcli.sh/)）。
+- 已启用 QuantumClaw hooks（参见 [Webhooks](/automation/webhook)）。
+- 已登录 `tailscale`（[tailscale.com](https://tailscale.com/)）。支持的设置使用 Tailscale Funnel 作为公共 HTTPS 端点。
+  其他隧道服务也可以使用，但需要自行配置/不受支持，需要手动接入。
+  目前，我们支持的是 Tailscale。
+
+示例 hook 配置（启用 Gmail 预设映射）：
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "QUANTUMCLAW_HOOK_TOKEN",
+    path: "/hooks",
+    presets: ["gmail"],
+  },
+}
+```
+
+要将 Gmail 摘要投递到聊天界面，请用设置了 `deliver` 以及可选的 `channel`/`to` 的映射覆盖预设：
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "QUANTUMCLAW_HOOK_TOKEN",
+    presets: ["gmail"],
+    mappings: [
+      {
+        match: { path: "gmail" },
+        action: "agent",
+        wakeMode: "now",
+        name: "Gmail",
+        sessionKey: "hook:gmail:{{messages[0].id}}",
+        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+        model: "openai/gpt-5.2-mini",
+        deliver: true,
+        channel: "last",
+        // to: "+15551234567"
+      },
+    ],
+  },
+}
+```
+
+如果你想使用固定渠道，请设置 `channel` + `to`。否则 `channel: "last"` 会使用上次的投递路由（默认回退到 WhatsApp）。
+
+要为 Gmail 运行强制使用更便宜的模型，请在映射中设置 `model`（`provider/model` 或别名）。如果你强制启用了 `agents.defaults.models`，请将其包含在内。
+
+要专门为 Gmail hooks 设置默认模型和思考级别，请在配置中添加 `hooks.gmail.model` / `hooks.gmail.thinking`：
+
+```json5
+{
+  hooks: {
+    gmail: {
+      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+      thinking: "off",
+    },
+  },
+}
+```
+
+注意事项：
+
+- 映射中的每个 hook 的 `model`/`thinking` 仍会覆盖这些默认值。
+- 回退顺序：`hooks.gmail.model` → `agents.defaults.model.fallbacks` → 主模型（认证/速率限制/超时）。
+- 如果设置了 `agents.defaults.models`，Gmail 模型必须在允许列表中。
+- Gmail hook 内容默认使用外部内容安全边界包装。
+  要禁用（危险），请设置 `hooks.gmail.allowUnsafeExternalContent: true`。
+
+要进一步自定义负载处理，请添加 `hooks.mappings` 或在 `hooks.transformsDir` 下添加 JS/TS 转换模块（参见 [Webhooks](/automation/webhook)）。
+
+## 向导（推荐）
+
+使用 QuantumClaw 助手将所有内容接入在一起（在 macOS 上通过 brew 安装依赖）：
+
+```bash
+quantumclaw webhooks gmail setup \
+  --account quantumclaw@gmail.com
+```
+
+默认设置：
+
+- 使用 Tailscale Funnel 作为公共推送端点。
+- 为 `quantumclaw webhooks gmail run` 写入 `hooks.gmail` 配置。
+- 启用 Gmail hook 预设（`hooks.presets: ["gmail"]`）。
+
+路径说明：当启用 `tailscale.mode` 时，QuantumClaw 会自动将 `hooks.gmail.serve.path` 设置为 `/`，并将公共路径保持在 `hooks.gmail.tailscale.path`（默认 `/gmail-pubsub`），因为 Tailscale 在代理之前会剥离设置的路径前缀。
+如果你需要后端接收带前缀的路径，请将 `hooks.gmail.tailscale.target`（或 `--tailscale-target`）设置为完整 URL，如 `http://127.0.0.1:8788/gmail-pubsub`，并匹配 `hooks.gmail.serve.path`。
+
+想要自定义端点？使用 `--push-endpoint <url>` 或 `--tailscale off`。
+
+平台说明：在 macOS 上，向导通过 Homebrew 安装 `gcloud`、`gogcli` 和 `tailscale`；在 Linux 上请先手动安装它们。
+
+Gateway 网关自动启动（推荐）：
+
+- 当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时运行 `gog gmail watch serve` 并自动续期 watch。
+- 设置 `QUANTUMCLAW_SKIP_GMAIL_WATCHER=1` 可退出（如果你自己运行守护进程则很有用）。
+- 不要同时运行手动守护进程，否则会遇到 `listen tcp 127.0.0.1:8788: bind: address already in use`。
+
+手动守护进程（启动 `gog gmail watch serve` + 自动续期）：
+
+```bash
+quantumclaw webhooks gmail run
+```
+
+## 一次性设置
+
+1. 选择**拥有 `gog` 使用的 OAuth 客户端**的 GCP 项目。
+
+```bash
+gcloud auth login
+gcloud config set project <project-id>
+```
+
+注意：Gmail watch 要求 Pub/Sub 主题与 OAuth 客户端位于同一项目中。
+
+2. 启用 API：
+
+```bash
+gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+```
+
+3. 创建主题：
+
+```bash
+gcloud pubsub topics create gog-gmail-watch
+```
+
+4. 允许 Gmail push 发布：
+
+```bash
+gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+  --role=roles/pubsub.publisher
+```
+
+## 启动 watch
+
+```bash
+gog gmail watch start \
+  --account quantumclaw@gmail.com \
+  --label INBOX \
+  --topic projects/<project-id>/topics/gog-gmail-watch
+```
+
+保存输出中的 `history_id`（用于调试）。
+
+## 运行推送处理程序
+
+本地示例（共享 token 认证）：
+
+```bash
+gog gmail watch serve \
+  --account quantumclaw@gmail.com \
+  --bind 127.0.0.1 \
+  --port 8788 \
+  --path /gmail-pubsub \
+  --token <shared> \
+  --hook-url http://127.0.0.1:18789/hooks/gmail \
+  --hook-token QUANTUMCLAW_HOOK_TOKEN \
+  --include-body \
+  --max-bytes 20000
+```
+
+注意事项：
+
+- `--token` 保护推送端点（`x-gog-token` 或 `?token=`）。
+- `--hook-url` 指向 QuantumClaw `/hooks/gmail`（已映射；隔离运行 + 摘要发送到主线程）。
+- `--include-body` 和 `--max-bytes` 控制发送到 QuantumClaw 的正文片段。
+
+推荐：`quantumclaw webhooks gmail run` 封装了相同的流程并自动续期 watch。
+
+## 暴露处理程序（高级，不受支持）
+
+如果你需要非 Tailscale 隧道，请手动接入并在推送订阅中使用公共 URL（不受支持，无保护措施）：
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
+```
+
+使用生成的 URL 作为推送端点：
+
+```bash
+gcloud pubsub subscriptions create gog-gmail-watch-push \
+  --topic gog-gmail-watch \
+  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"
+```
+
+生产环境：使用稳定的 HTTPS 端点并配置 Pub/Sub OIDC JWT，然后运行：
+
+```bash
+gog gmail watch serve --verify-oidc --oidc-email <svc@...>
+```
+
+## 测试
+
+向被监视的收件箱发送一条消息：
+
+```bash
+gog gmail send \
+  --account quantumclaw@gmail.com \
+  --to quantumclaw@gmail.com \
+  --subject "watch test" \
+  --body "ping"
+```
+
+检查 watch 状态和历史记录：
+
+```bash
+gog gmail watch status --account quantumclaw@gmail.com
+gog gmail history --account quantumclaw@gmail.com --since <historyId>
+```
+
+## 故障排除
+
+- `Invalid topicName`：项目不匹配（主题不在 OAuth 客户端项目中）。
+- `User not authorized`：主题缺少 `roles/pubsub.publisher`。
+- 空消息：Gmail push 仅提供 `historyId`；通过 `gog gmail history` 获取。
+
+## 清理
+
+```bash
+gog gmail watch stop --account quantumclaw@gmail.com
+gcloud pubsub subscriptions delete gog-gmail-watch-push
+gcloud pubsub topics delete gog-gmail-watch
+```