#Lark Agent Control Plane 设计

类型: High-level design, 不是 implementation plan 读者: 团队工程师 状态: 草稿待审 日期: 2026-06-10

#最终状态图

这份文档讨论的是一件事：怎么把现有的 GitHub、Sentry、Beads、botmux、Lark 和 AI agent 串起来，形成一个由 Lark 控制的 agent loop。系统负责把任务从“被发现”推进到“被验证”，人仍然在 Lark 里掌握高风险动作的批准权。

本文不覆盖具体文件改法、部署命令、账号配置或上线步骤。这些应该放到后续 implementation plan。

#1. 结论先说

这个方向是成立的，但第一阶段不应该直接做“全自动 agent factory”。更稳的起点是：

把 Lark 做成任务控制台，把 Beads 做成任务单一事实源，让 botmux 承接 Lark 指令，让 lark-dm-bot 继续负责通知，让 agent 在有权限、有 Measure、可回滚的边界里自动执行。

也就是这条链路：

GitHub / Sentry / 巡检
  -> Lark report 或 Beads task
  -> Lark 展示当前可做任务
  -> 必要时人在 Lark 批准
  -> agent 执行调查或代码改动
  -> 测试 / eval / 指标 / trace 验证结果
  -> 按任务类型产出 report / task / branch / draft PR
  -> 按风险分层：自动推进低风险 test lane，人批准 production lane

现在真正挡路的不是 Lark 或 agent 能不能跑，而是三个基础前提还没收敛：

1. Beads 必须变成多机器共享的单一 SoT。 现在本地 .beads/metadata.json 显示是 dolt_mode: "server"，.beads/config.yaml 没有 remote 配置。2026-06-10 的生产机实测记录还提到 EC2 上当时没有安装 bd / dolt。如果每台机器看的是自己的本地 Beads 数据库，Lark 控制台会天然失真。
2. Lark 入口必须有明确权限模型。 2026-06-10 的生产机实测记录显示现有 botmux/codex bot 是开放模式，并且 codex 以 --dangerously-bypass-approvals-and-sandbox 启动。这种配置可以用于小范围可信调试，但不能直接承载“改任务状态”或“派 agent 改代码”。
3. agent 的 push / PR / merge 规则要先分层。 不同 repo 和 agent runtime 对 push 的默认期待还没有收敛：callytics-infrastructure/AGENTS.md 有“work session 直到 git push 成功才算完成”的模板规则，而 docs repo 的 AGENTS.md 明确要求 push 前仍需用户确认。自动化前必须把这些约束收敛成组织级 lane policy：test-only lane 可以更自动，production lane 必须有人 gate。

所以推荐路线不是“禁止自动 PR”，而是先定义 lane：test-only lane 可以让 agent 自动 branch / push / open draft PR；production lane 默认保留人工批准。 这个顺序背后的原则是：先把任务状态、权限边界和验证信号收进 Lark，再扩大 agent loop 的自主权。

#2. 我们已经有的零件

这里不要把系统想成一个新平台。更准确地说，我们是在给已有零件补一层 control plane。

lark-dm-bot 负责出站通知。它把 GitHub、Sentry 等事件推到 Lark DM 或群里。它适合做“告诉人发生了什么”，不适合做人机命令入口。

botmux 负责入站命令。它把 Lark 消息接到命令行，再把结果回传成 Lark 卡片。现有 codex bot 已经证明了这条链路能跑：Lark 发消息，EC2 上执行 CLI，结果回到 Lark。

Beads (bd) 负责任务编排。它比普通 TODO 更适合 agent workflow，因为它有持久任务、依赖关系和 bd ready 这类“当前哪些任务可以做”的查询能力。但它必须接到共享后端，否则每台机器的任务状态会分叉。

Claude Code / Codex agent 负责执行。它可以读代码、调查问题、写代码、跑测试、准备 PR 草案。它不应该直接拥有发布权。

Lark 是人的控制台。人看任务、收通知、批准派发、审结果。Lark 不应该只是消息推送渠道，也不应该变成无权限边界的远程 shell。

这几个零件合在一起，边界应该是：

lark-dm-bot: 事件 -> Lark
botmux:      Lark -> CLI
Beads:       task graph / dependency / ready queue
agent:       investigation / code change / verification
human:       approve / review / publish

最容易混的是 botmux 和 lark-dm-bot。它们不是同一个东西：一个是入站命令桥，一个是出站通知桥。自动化控制台需要两者同时存在，但职责不能混。

#3. 目标架构

目标态不是“机器人替人做所有判断”，而是把重复、可观察、可回滚的流程自动化，把高风险判断和生产发布权留给人。

整体流向如下：

发现层
  GitHub issue / Sentry issue / pipeline monitor / eval regression
      |
      v
编排层
  Beads task graph
  - create / update task
  - dependency tracking
  - bd ready
      |
      v
控制层
  Lark + botmux
  - 看 ready tasks
  - claim / comment / close
  - 批准 agent dispatch
      |
      v
执行层
  agent worker
  - 调查
  - 修改代码
  - 跑测试
  - 准备 commit / PR 草案
      |
      v
验证层
  Measure
  - test / build / lint / type-check
  - prompt eval / golden dataset
  - health metrics / Sentry / trace
      |
      v
交付层
  Lark report / Beads task / draft PR / human review / production merge

这条链路里，机器可以自动做三类事：

• 把外部事件转成 Lark report 或任务，例如 eval 结果、Sentry 新 issue、GitHub issue、巡检异常。
• 根据 Beads 依赖图找出当前可做任务，例如 bd ready。
• 对低风险任务做只读分析，或在人工批准后让 agent 准备修复草案。
• 根据测试、eval、指标和 trace 判断这一轮是否通过，失败就回流成下一轮任务或反馈。

人必须保留三类动作：

• 批准 agent 开始改代码。
• review agent 的结果。
• 批准进入 production path 的 push、merge、deploy。

低风险 test lane 可以自动化到 draft PR 或 preview deployment。关键不是“agent 能不能 push”，而是 push 到哪里、触发什么环境、有没有可复现 Measure、失败能不能回滚。最终终点应该是 PR 交给人看，而不是自动进 production。

如果未来引入 Gastown 或其他 autonomous SWE 工厂，这套设计仍然有价值：Beads 可以继续做 task backend，Lark 继续做人机 control plane。区别只是执行层从单个 botmux/codex session 变成 worker pool 或更完整的 factory。

#4. 这个系统本质上是什么 Loop

这套系统本质上不是“聊天机器人接命令”，而是一个工程化的 agent loop：

Plan
  -> Execute
  -> Measure
  -> Reflect
  -> Plan

映射到本设计里：

• Plan: Beads 记录任务、依赖、优先级和当前 ready queue。
• Execute: agent 在受控环境里调查、改代码、跑命令。
• Measure: 外部系统给出验证信号，而不是 agent 自己说“我觉得好了”。
• Reflect: agent 基于失败证据提出下一步，或者把新问题回流成 task。
• Human gate: Lark 承接批准、review、merge、production deploy 这些高风险动作；agent 的最终产物是带证据的 PR。
• Output policy: eval / health / CI 这类只读任务发 Lark report，需要改代码的任务才进入 PR。
• Execution lane policy: test-only lane 允许更多自动动作，production lane 保留人工 gate。

这里最重要的是 Measure。AI 可以自我纠错，但纠错方向只有在外部反馈足够可靠时才可信。没有 Measure 的 loop 会把错误假设跑得更完整；有 Measure 的 loop 才会越跑越接近正确结果。

#Measure 应该是什么

Measure 必须尽量来自系统事实，而不是来自模型自评：

这张表应该成为后续 implementation plan 的入口：每加一个自动化任务，先写清楚它的 Measure，再决定 agent 能不能自动跑。如果写不出 Measure，这个任务就不适合直接自动化。

#Trace 是 Measure 的上下文

测试只能告诉我们“过了或没过”，trace 才能解释“agent 到底怎么走到这里”。因此每次 agent dispatch 至少要记录：

• task id、approval id、操作者、触发时间。
• agent 读了哪些输入，调用了哪些工具。
• 跑了哪些验证命令，结果是什么。
• 失败时 agent 基于什么证据提出下一步。
• 最终产物：Lark report、Beads task、本地 commit、diff summary、PR 草案或新 task。

没有 trace 的 loop 很难调试。失败时只看到“agent 没做好”，看不到是任务定义错、上下文错、工具错、权限错，还是 Measure 设计错。

#Output policy: 不是所有 Loop 都产 PR

这套控制台要先区分“产物是什么”，再决定 agent 要不要改代码。很多 loop 的最佳终点不是 PR，而是一张 Lark 卡片或一条 Beads task。

因此 eval 这种任务通常不应该开 PR。正常情况是跑完 eval，把分数、失败样本、baseline diff 发到 Lark；只有 eval 发现回归，并且修复需要改 prompt / code 时，才从 report-only 或 task-routing 转入 pr-producing。

#Execution lane policy: 自动化权限可以分层开放

如果我们愿意把代码、工具和 test 环境权限开放给 agent，就不需要等到很后面才允许它自动修复。更合理的设计是从第一天就分 lane：

所以“GitHub issue -> agent 自动修 -> 自动 push -> 自动 PR”不是原则上不能做。它可以作为 test-autofix execution lane 的目标能力。真正不应该直接放开的，是“自动修 -> 自动 merge 到 production path -> 自动 deploy prod”。凡是进入 pr-producing output lane 的工作，默认终点应该是 PR / draft PR + Measure evidence + trace summary，让人 review。

#5. 当前最大风险

#5.1 Beads 不是共享 SoT，闭环会失真

控制台最重要的前提是所有机器看到同一个任务图。现在这个前提还不成立。

本地仓库验证到的状态是：

• .beads/metadata.json 使用 Dolt backend，dolt_mode 是 server。
• .beads/config.yaml 没有 remote 配置。
• bd doctor 能跑通，但提示本地 Dolt 有 uncommitted change。

这说明 Beads 当前更像“每台机器的本地任务数据库”，而不是已经稳定接入共享 remote 的团队任务 SoT。生产机实测记录里还提到 EC2 上当时没有 bd / dolt，这会让 Lark 上的任务视图和开发机上的任务视图天然不同步。

自动化前必须先决定：Beads 的共享后端到底用 Dolt remote、Dolt sql-server remotesapi，还是换成别的任务后端。这个决策是地基，不是实现细节。

#5.2 现有 bot 更像可信远程 shell，不是受限控制台

2026-06-10 的生产机实测记录显示，现有 codex bot 的能力很强：能在 EC2 上执行 CLI、读文件、安装临时依赖、处理附件，并把结果回 Lark。这个能力证明 botmux 链路可用，但也说明它的风险边界很大。

如果 Lark 侧没有 allowedUsers / allowedChatGroups，而 agent 又以 --dangerously-bypass-approvals-and-sandbox 运行，那么任何能触发 bot 的人，本质上都可能触发一个无沙箱执行体。

这不适合作为任务控制台的默认形态。任务 bot 应该和通用 codex bot 分开：

• 用单独 Lark app。
• 配明确的用户或群白名单。
• 命令做 allowlist，而不是把 Lark 文本直接交给 shell。
• 对 mutating command 记录操作者、参数、结果和时间。
• 对 agent dispatch 记录 approval id。

OWASP 的 AI agent security guidance 也指向同一个原则：不要给 agent unrestricted shell，把高风险动作放到 human-in-the-loop 和 least-privilege 控制后面。

#5.3 Lark / webhook 本身也需要工程化处理

Lark 的事件和卡片能力足够支撑这个设计，但不能只当“聊天消息”处理。

实施时要考虑：

• Lark receive message 需要 bot ability 和 event subscription。
• Lark card callback 需要在 3 秒内响应，长任务应该先 ack，再异步更新卡片。
• Event subscription / callback request 应启用 verification token / encrypt key / signature verification。
• GitHub webhook 要校验 X-Hub-Signature-256，并用 X-GitHub-Delivery 做幂等。
• Sentry webhook 也要按 source event 做 dedup，避免重复报警重复建任务。

这些不是架构上最难的部分，但如果不提前写进边界，后面会变成“偶发重复建 task、按钮点击超时、错误请求也能触发命令”的运营问题。

#6. 推荐演进路线

#Phase 0: 先把地基补齐

这一步不做新自动化能力，只消除会让后续路线失真的前提问题。

需要完成：

• 选定 Beads 共享 SoT 方案，并让开发机、新 cloud machine、agent worker 都读写同一份任务库。
• 在新机器上安装并验证 bd / dolt / gh / agent CLI / lark-cli 等基础工具。
• 明确 Lark 操作者权限模型：按用户 open_id、邮箱、群，还是组合规则。
• 统一 agent 的 push / PR / merge 安全规则。建议写成 lane policy：test-autofix 可以自动 push bot branch / open draft PR；production merge 和 deploy 需要人明确批准。
• 设计 audit trail：谁在 Lark 点了什么、改了哪个 task、触发了哪个 agent、结果是什么。
• 定义第一批自动化任务的 Measure：每个任务必须写清楚验证命令、指标阈值、失败回流方式和人工 gate。

Phase 0 做完后，才值得把 Lark 接到 Beads。

#Phase 1: Lark 只读看任务

第一版只做 read-only。人在 Lark 里能看：

• bd ready
• task 详情
• 当前 in-progress / blocked / recently closed
• task 对应的 GitHub issue / PR link

这阶段不需要 agent dispatch，也不需要改 task。它的价值是先验证三个问题：

• Lark 卡片展示是否足够清楚。
• botmux 跑 bd 的工作目录、环境变量和权限是否稳定。
• Beads 共享 SoT 是否真的能被多机器一致读取。
• Lark 是否能清楚展示每个 task 的 Measure 和最近一次验证结果。

#Phase 2: Lark 可以改任务，但只能走受限命令

第二阶段加入 mutation，但命令必须收敛。

允许的命令可以从这些开始：

• bd update <id> --claim
• bd close <id>
• bd comment <id> ...
• bd dep add <id> <depends-on>

不应该允许：

• 任意 shell 命令。
• 任意 bd 子命令透传。
• 没有 task id / operator / audit log 的状态修改。
• 未授权群或用户操作。

按 2026-06-10 的 botmux source review 记录，botmux 当前不是简单加一个 cliId: "bd" 就能支持 Beads；需要加 bd CLI adapter。这个判断在 implementation plan 前要再次打开 botmux source 确认。正确方向不是把 Lark 文本拼进 shell，而是写一个很窄的 adapter：解析允许的动作，组装固定命令，返回结构化结果。

#Phase 3: Lark 批准 agent dispatch

第三阶段才让 agent 取任务。不是所有 output lane 都需要 dispatch：report-only 任务跑完发 Lark 就结束；只有需要进一步调查、修复或产出 PR 的任务，才进入 agent dispatch。

推荐流程：

1. 系统展示一个 ready task。
2. 人点击“批准调查”或“批准修复草案”。
3. 控制台写入 approval record。
4. agent 只拿到这个 task 的上下文和允许动作。
5. agent 执行后必须跑对应 Measure，并把证据回写到 task。
6. 在 test-autofix lane，agent 可以 push bot-owned branch 并 open draft PR。
7. 人 review PR，再决定是否 merge / deploy 到 production path。

调查类任务可以自动化程度更高；改代码类任务必须有批准。这里的 gate 应该按动作风险分类，而不是按“是不是 AI 做的”分类。

#Phase 4: worker pool / Gastown

如果未来要做多 worker 或 Gastown 式 autonomous factory，前面三阶段仍然是基础。

worker pool 的前提是 task state 不在机器上，而在共享 Beads SoT。机器可以随时替换，任务状态不能跟着机器丢。到这一步后，设计重点会从“Lark 怎么控制单个 agent”变成：

• worker 怎么 claim task。
• 并发 claim 怎么避免重复。
• 每个 worker 的权限和沙箱怎么隔离。
• PR 草案、测试结果、artifact 怎么回写 task。
• worker 异常退出怎么恢复。

Gastown 当前在本文里仍是未校准概念。需要团队确认它到底是已有系统、目标产品，还是泛指 autonomous factory。

#7. 第一批值得自动化的任务

第一批应该按 output lane 来选，而不是都往 PR 里塞。只读验证类先发 Lark；发现问题但还没决定修法时建 Beads task；只有需要改代码、prompt、配置或文档时才开 PR。

推荐顺序：

1. Prompt eval regression

   • 触发方式：prompt 改动后或 nightly schedule。
   • 自动动作：跑 eval，比较分数，结果发 Lark。
   • Output lane：默认 report-only；分数回落时转 task-routing；需要改 prompt / code 时转 pr-producing。
   • Measure：eval score、failed cases、baseline diff。
   • 人 gate：看 eval report；修复 PR 由人 review。

2. Pipeline health monitor

   • 触发方式：定时 Lambda。
   • 自动动作：检查 null rate、dedup、backlog、关键字段覆盖率。
   • Output lane：健康时 report-only 或静默；异常时 task-routing；修复代码/阈值/infra 时 pr-producing。
   • Measure：关键指标是否超过阈值，异常是否能定位到 pipeline 阶段。
   • 人 gate：异常 task 是否派 agent 修，由人批准；修复 PR 由人 review。

3. Sentry 新 issue 分诊

   • 触发方式：Sentry webhook。
   • 自动动作：拉上下文、初判严重度、去重、建 task 或发 Lark。
   • Output lane：默认 task-routing；明显噪声可以只发 report 或 suppress；需要修复时进入 pr-producing。
   • Measure：issue 是否去重、是否有 owner/severity、是否关联到 repo/path/log context。
   • 人 gate：是否派 agent 修，由人批准；修复 PR 由人 review。

4. CI / deployment watch

   • 触发方式：GitHub webhook 或 gh polling。
   • 自动动作：看 PR check、部署后异常窗口、把结果回 Lark。
   • Output lane：默认 report-only；失败时 task-routing；需要改代码时 pr-producing。
   • Measure：GitHub checks、deployment logs、post-deploy Sentry/error window。
   • 人 gate：CI 失败修复 PR 由人 review；merge / deploy 仍由人决定。

5. GitHub issue -> 修复草案

   • 触发方式：issue label 或人工批准。
   • 自动动作：建 Beads task，准备调查结果；在 test-autofix lane 可以自动开 bot branch 和 draft PR。
   • Output lane：pr-producing。
   • Measure：复现命令、targeted test、diff summary、剩余风险。
   • 人 gate：PR review、merge、production deploy。

这些任务的共同点是完成信号可观察，失败也容易回流成 task。一次性 design、价值判断、产品取舍，不应该直接放进 agent loop，因为它们通常缺少稳定 Measure；这类任务可以用 AI 辅助讨论，但不应该自动推进。

#8. 需要团队拍板的问题

1. Beads 共享 SoT 怎么做。 继续 Dolt remote / Dolt sql-server remotesapi，还是换后端？新 cloud machine 应该从第一天就接共享任务库。
2. Lark 权限模型。 谁能看任务，谁能改任务，谁能批准 agent dispatch？按用户、群、邮箱还是组合？
3. 现有 push / PR 规则怎么统一。 自动化系统必须同时定义 output policy 和 execution lane policy，不能笼统要求 agent “必须 push” 或 “不能自主 push”。
4. 第一批自动化任务选哪两个。 推荐从 eval regression 和 pipeline health 开始，因为它们主要是只读和告警，风险低、价值直接。
5. 每类任务的 Measure 谁定义。 工程类可以由 repo owner 定义，业务/产品类必须有人给判据，不能交给 agent 自评。
6. 哪些任务能进 pr-producing output lane。 eval / health / CI 这类任务默认只发 Lark report；只有需要修改代码、prompt、配置或文档时才开 PR。
7. 哪些任务能进 test-autofix execution lane。 例如 docs-only、prompt regression fix、pipeline monitor fix、targeted bugfix 是否都允许自动 branch / draft PR？
8. Gastown 的真实定位。 它是已有系统、未来目标，还是泛指完整 agent factory？它和 Beads / botmux 是上下层关系还是平行路线？
9. 多租户之后怎么隔离控制台。 如果未来 control plane 面向多个客户或多个 tenant，权限、任务 visibility、agent context 都要带 tenant boundary。

#9. 本文依据

本地验证：

• .beads/metadata.json 显示 backend 是 Dolt，dolt_mode 是 server，database 是 callytics_infrastructure。
• .beads/config.yaml 没有 remote 配置。
• bd doctor 在本机可运行，结果为 68 passed / 5 warnings / 0 errors，warning 包括 CLI 版本落后和本地 Dolt uncommitted change。
• 不同 repo / agent runtime 的 push 默认规则已经出现分叉：callytics-infrastructure/AGENTS.md 有必须 push 的 session completion 要求，docs repo 的 AGENTS.md 要求 push 前仍需用户确认。自动化前需要统一成组织级 lane policy。

2026-06-10 生产机实测记录：

• botmux/codex bot 已在 EC2 生产环境运行。
• codex 启动命令使用 --dangerously-bypass-approvals-and-sandbox。
• botmux 通过 Lark 消息触发 CLI，再用卡片返回结果。
• botmux 当前没有现成 bd adapter，后者需要源码改动。实施前应再次读 botmux source 确认。

外部资料核验：

• Lark receive message event: https://open.larksuite.com/document/server-docs/im-v1/message/events/receive
• Lark card callback 3 秒响应要求: https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication
• Lark event subscription / encrypt key: https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/configure-encrypt-key
• GitHub webhook headers and signature: https://docs.github.com/en/webhooks/webhook-events-and-payloads
• Sentry webhooks: https://docs.sentry.io/integrations/integration-platform/webhooks/
• AWS EventBridge Scheduler for recurring Lambda: https://docs.aws.amazon.com/lambda/latest/dg/with-eventbridge-scheduler.html
• Dolt sql-server remote endpoint: https://www.dolthub.com/docs/sql-reference/version-control/remotes/
• OWASP AI Agent Security Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html
• OpenAI Codex agent loop: https://openai.com/index/unrolling-the-codex-agent-loop/
• OpenAI iterative repair loop cookbook: https://developers.openai.com/cookbook/examples/codex/build_iterative_repair_loops_with_codex
• OpenAI agent improvement loop with traces and evals: https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop
• Claude Code best practices on verification evidence: https://code.claude.com/docs/en/best-practices
• LangChain trace-centered agent improvement loop: https://www.langchain.com/blog/traces-start-agent-improvement-loop