Agent Orchestrator演进方案

一、结论先行

对比 C:/GitHub/agent-orchestrator（下称 AO）与当前 chong，可以得出一个很清楚的判断：

• chong 当前更强的是“代理内核”与“可扩展执行底座”，包括 SessionAgent、subagent、skills、hooks、permission v2、scheduler、A2A、Lua-first 路线。
• AO 当前更强的是“多代理并行交付的编排控制面”，也就是围绕 issue、分支、PR、CI、review、merge、恢复、通知这一整条闭环的产品化能力。
• 若 chong 要在“并行 coding agents 编排”上追平并超越 AO，不应重写现有代理内核，而应在其上新增一层 Orchestrator 控制面。

一句话总结：AO 的领先点，不在“单个 agent 更聪明”，而在“把多 agent 并行交付流程做成了可运营、可恢复、可自治的系统”。

二、AO 相对 chong 的先进之处

2.1 核心先进点总表

2.2 AO 真正值得借鉴的不是 UI，而是这五个控制面能力

一、Canonical Lifecycle

AO 将“会话在干什么”拆成了多个正交面：

• session state
• PR state
• runtime state
• activity state
• reason / evidence

这带来两个直接收益：

• 任何自动化决策都基于标准状态，而不是散落在工具输出、日志文本、UI 按钮里的隐式判断。
• “CI fail 但 agent 仍存活”“review pending 但 session idle”“runtime 丢失但 PR 还开着”这类复杂情况可以被准确描述，而不是硬塞进单个状态字段。

当前 chong 的 internal/agent/subagent 已有良好的执行态状态机，但它只回答“任务有没有跑完”，不能回答“PR 是否需要处理、CI 是否失败、当前 worker 是否卡住、是否需要人类介入”。

二、Reaction Engine

AO 的 reaction 不是一般意义上的 hooks，而是面向编排结果的规则执行层：

• 触发源是编排事件，而不是任意工具事件
• 动作是编排动作，如 send-to-agent、notify、auto-merge
• 带有 retry、escalateAfter、priority、persistent tracking
• 可以对 oscillating condition 做去抖与预算累积，例如反复抖动的 CI failed

这比单纯“收到事件就执行一个 hook”高级，因为它把自动化的语义边界、重试语义、升级语义都建模了。

三、Workspace / Runtime 管理是一等对象

AO 不是简单“开个 worktree 就算隔离”，而是把以下问题一次性解决：

• 每个 worker 的 workspace 路径规则
• 每个项目的 runtime 目录与 session 元数据目录
• 多个 orchestrator checkout 共存时如何避免命名冲突
• session 终止后如何 restore/adopt
• workspace 归档和清理策略

当前 chong 的 worktree 能力更像执行器能力，而非编排平台能力。这个差别非常关键。

四、SCM / Tracker / Runtime / Agent 插槽明确

AO 的抽象边界非常清晰：

• Tracker 负责 issue/task 语义
• SCM 负责 PR/CI/review/mergeability 语义
• Workspace 负责代码隔离
• Agent 负责具体 coding runtime
• Notifier 负责通知

当前 chong 虽然已经有更通用的 plugin/hook/skill 系统，但编排领域还没有这层“窄而硬”的接口。没有这一层，未来接 GitHub、GitLab、Linear、外部 agent runtime 都会变成散点集成。

五、Operator Console 面向“注意力调度”

AO 的 Dashboard 重点不是漂亮，而是一个很对的产品视角：

• 操作者只看需要关注的 agent
• “谁在工作、谁卡住了、谁等 review、谁可 merge、谁要人工决策”一眼分层
• 编排系统的价值来自减少人类轮询成本

chong 当前有很强的 TUI 能力，但主视角仍然是“正在与一个 agent 交互”，不是“我在运营一群 agent”。

三、chong 当前的可复用基础

chong 并不是从零开始。相反，它已经具备大量 AO 没有或不如它的基础设施，这意味着演进重点应该是“加控制面”，不是“推倒重来”。

3.1 已有基础能力

• internal/agent/subagent：已有 worker pool、异步执行、任务状态机、中间件链、worktree 管理、真实 SessionAgent 适配。
• internal/agent/task/service.go：已有结构化任务 CRUD、状态流转、事件发布、存储接口。
• internal/hooks：已有 pre/post tool、session、permission、file change、subagent task 等多类事件。
• internal/plugin：已有多源插件加载与注册机制。
• internal/scheduler：已有持久化调度器，可承担 poller / cleanup / periodic reconciliation。
• internal/permission/v2：已有规则化权限引擎，可作为自治编排行为的安全边界。
• internal/session + goal/todo 注入：已有长任务目标保持机制，可作为 worker objective 同步基础。
• internal/a2a：具备向外暴露 agent skill / orchestrator 能力的潜力。
• Lua-first 路线：允许后续把编排规则与工作流表达为 Lua table / Lua skill，而非再次堆 YAML 方言。

3.2 当前边界

当前这些能力更像“很强的执行底座”，而不是“完整 orchestrator”。主要边界包括：

• subagent 的状态机还是执行态，不是交付态。
• task service 还是 agent/task 视角，不是 project/work-item/PR 视角。
• hooks 很强，但缺少编排语义和统一 reaction 预算管理。
• worktree 目前主要服务局部执行隔离，没有全局 runtime namespace、adopt、restore、archive 设计。
• UI 目前没有 operator-first 的多 worker 总览。
• SCM/Tracker 数据仍然是“工具或命令能力”，不是“被 orchestrator 周期性消费的数据面”。

四、演进目标

本次 AO 演进的目标，不是把 chong 变成 AO 的 Go 翻版，而是让 chong 具备更强的并行编排控制面，并保留其原有差异化优势。

4.1 产品目标

• 让用户可以从“单会话 coding”进入“项目级 orchestrator 模式”。
• 让一个 orchestrator 能稳定管理 10 到 30 个并行 worker。
• 让 CI 失败、review 评论、merge conflict、agent idle、agent needs input 等反馈自动回流给正确 worker。
• 让操作者只在需要人工判断时被打断。

4.2 技术目标

• 在现有 agent/subagent/task/scheduler 之上新增编排控制面，而不是重写底层。
• 统一 project、work item、worker session、PR、runtime、attention event 的持久化模型。
• 引入 canonical lifecycle 和 reaction engine。
• 构建 GitHub-first 的 Tracker/SCM/Workspace/Notifier provider 层。
• 提供 TUI-first 的 operator console，并为后续 Web/RPC 预留数据面。

4.3 差异化目标

• 配置与规则表达优先使用 Lua table，不照搬 AO 的 YAML 中心化风格。
• 利用 chong 现有 hooks、permissions、skills、A2A，把 orchestrator 变成“可自治又可编程”的系统。
• 把“goal/todo/session memory”与 orchestrator work item 串起来，降低长任务漂移。

五、目标架构

5.1 分层原则

第一层：Execution Layer，保持现有实现

保留现有：

• SessionAgent
• subagent executor
• task service
• hooks
• permission v2
• scheduler

这一层负责“怎么执行”。

第二层：Orchestration Layer，新增控制面

新增：

• planner
• lifecycle manager
• reaction engine
• workspace lease manager
• tracker/scm adapter
• attention queue
• restore/reconcile service

这一层负责“为什么执行、何时重试、何时升级、何时恢复、何时通知人类”。

第三层：Operator Surface

新增：

• /orch 命令组
• TUI board / queue / detail pane
• 通知与告警摘要
• 未来可选的 Web/RPC dashboard

这一层负责“人如何监督系统”。

六、核心设计方案

6.1 引入编排域模型，而不是复用 task 直接硬撑

建议新增以下一等模型：

• OrchestratorProject
• WorkItem
• WorkerSession
• CanonicalLifecycle
• PRSnapshot
• ReactionPolicy
• AttentionEvent
• WorkspaceLease
• AutomationAttempt

关键原则：

• internal/agent/task 继续做 agent/task 级内部任务，不直接充当 orchestrator 的主真相源。
• orchestrator 维护自己的 project/work-item/worker-session 视图，再选择性映射到 task service。
• subagent 状态机继续是执行细节，编排状态机在其上做归约与提升。

6.2 设计 Canonical Lifecycle

建议新增编排态结构：

type CanonicalLifecycle struct {
    Session  SessionStateRecord
    PR       PRStateRecord
    Runtime  RuntimeStateRecord
    Activity ActivityStateRecord
}

建议编排主状态至少覆盖：

• queued
• spawning
• working
• needs_input
• stuck
• ci_failed
• review_pending
• changes_requested
• merge_conflicts
• mergeable
• merged
• done
• terminated

每个状态必须附带：

• reason
• last_observed_at
• evidence
• source

关键约束：

• 不要把 PR 状态和 runtime 状态塞进一个 status 字段。
• 不要让 UI 直接依赖工具文本判断状态。
• 所有自动化动作必须基于 canonical lifecycle 决策。

6.3 建立 Reaction Engine

反应引擎不是 hooks 替代品，而是建立在 hooks、scheduler、SCM polling、webhook 之上的决策层。

事件源

• tracker backlog 变化
• PR 创建 / 关闭 / 合并
• CI fail / pass
• review comment / changes requested
• merge conflict
• agent idle
• agent needs input
• runtime lost
• goal complete / all complete

动作集合

• send_to_worker
• notify_operator
• pause_worker
• resume_worker
• request_permission
• open_followup_item
• attempt_merge
• archive_session

必备机制

• retry budget
• escalateAfter
• fingerprint 去重
• oscillation 去抖
• persistent reaction key
• audit log

特别建议直接吸收 AO 的两个经验：

• ci-failed 这类可抖动事件，reaction 预算不应在每次短暂恢复后立即清零。
• needs_input、stuck、runtime_lost 这类信号必须区分“短暂探测失败”和“需要人工介入”。

6.4 重构 Worktree 模型为编排级 Workspace Manager

当前 .chong/worktrees 适合局部 subagent 隔离，但不适合编排平台。建议新增 orchestrator 专用 runtime root：

~/.chong/orchestrator/{hash}-{project}/
  sessions/
  workspaces/
  archive/
  metadata/

设计原则：

• 项目级命名空间，而不是 repo 内局部目录。
• 支持同一项目被多个 checkout / 多个 orchestrator 实例管理时的 hash 隔离。
• 支持 restore、adopt-existing-workspace、archive、gc。
• 保留当前 subagent worktree 逻辑作为执行层实现，但由 orchestrator workspace manager 统一调度。

6.5 补齐 Provider 层，而不是把编排逻辑散落在命令里

建议在现有 plugin system 之上新增编排域 provider 接口：

• TrackerProvider
• SCMProvider
• WorkspaceProvider
• ExecutionProvider
• NotifierProvider
• OperatorSurfaceProvider（可选，后续）

GitHub-first MVP 先实现：

• github-tracker
• github-scm
• git-worktree-workspace
• internal-agent-executor
• desktop-notifier
• tui-surface

注意：

• 不必一开始就复制 AO 的全部 slot 数量与命名。
• 但接口边界必须先立起来，否则 GitHub 逻辑会迅速侵入 orchestrator 核心。

6.6 规划器要成为一等组件

AO 的“spawn agent”已经是产品动作。chong 若要继续演进，不能只做到“手动开多个 subagent”，而要做到“从 backlog 自动生成可执行 work item”。

建议 Planner 支持：

• 从 issue / PR / 用户目标生成 WorkItem
• 基于依赖关系构造 DAG
• 根据并发预算与风险等级决定 spawn 时机
• 根据任务类型选择 subagent type / tool budget / permission mode
• 将 worker goal/todo 与 work item objective 双向同步

第一期不追求复杂 AI 规划，可先做：

• 一 issue 一 worker
• 人工确认后 spawn
• 支持简单优先级与依赖阻塞

6.7 Operator Console 采用 TUI-first，Web-second

AO 当前用 Web Dashboard；chong 当前已经深耕 TUI，因此建议：

• 第一阶段先做 TUI 编排控制台
• 第二阶段暴露 RPC / API
• 第三阶段视需要补 Web 面板

TUI board 建议按注意力排序，而非按纯流程排序。建议初始列：

• Needs Action
• Working
• Review Pending
• CI Failed
• Mergeable
• Done

每个 worker 卡片至少展示：

• issue / 标题
• branch / PR
• lifecycle state + reason
• 最近 reaction
• 最近活动时间
• 是否需要人工介入

6.8 原生结构化活动日志，优于终端文本猜测

AO 使用 activity JSONL 兜底。chong 的优势是它本身掌控 SessionAgent 与工具执行，因此建议更进一步：

• SessionAgent、subagent、task service、scheduler 统一写入结构化 activity/event stream
• 只有对外部 runtime 才退回到 terminal parsing / JSONL fallback
• UI 与 reaction engine 一律消费结构化事件，而不是消费日志字符串

这会让 chong 在可靠性上有机会反超 AO。

七、建议的目录与模块落点

建议新增：

internal/orchestrator/
  service.go
  config.go
  types.go
  planner/
  lifecycle/
  reactions/
  workspace/
  tracker/
  scm/
  notifier/
  attention/
  restore/
  observability/
  api/

并与现有模块建立如下关系：

• internal/agent/subagent：继续负责执行
• internal/agent/task：继续负责 agent 级 task 记录
• internal/scheduler：负责 poll / reconcile / cleanup
• internal/plugin：承载 provider 加载与装配
• internal/permission/v2：作为自治动作安全门
• internal/ui：新增 orchestrator board / detail view
• internal/a2a：后续对外暴露 orchestrator 技能与状态查询

八、配置方案

8.1 配置原则

• 全局启停与默认值放在 crush.json
• 项目级 orchestrator 规则放在 .chong/orchestrator.lua
• 尽量用 Lua table，不再创造一套新的 YAML DSL

8.2 建议配置形态

crush.json 负责：

• 是否启用 orchestrator
• 默认 provider
• 默认并发预算
• runtime root
• 通知与权限默认策略

.chong/orchestrator.lua 负责：

• 项目列表
• tracker / scm / workspace 绑定
• reaction policies
• spawn policy
• cleanup policy
• merge policy

示意：

return {
  projects = {
    main = {
      path = ".",
      tracker = { kind = "github" },
      scm = { kind = "github" },
      workspace = { kind = "worktree" },
      max_parallel = 6,
    },
  },
  reactions = {
    ["ci-failed"] = {
      auto = true,
      action = "send_to_worker",
      retries = 2,
      escalate_after = "30m",
    },
    ["changes-requested"] = {
      auto = true,
      action = "send_to_worker",
      escalate_after = "30m",
    },
    ["approved-and-green"] = {
      auto = false,
      action = "notify_operator",
    },
  },
}

九、数据库与持久化设计

建议新增表：

• orchestrator_projects
• orchestrator_work_items
• orchestrator_worker_sessions
• orchestrator_lifecycle_snapshots
• orchestrator_reaction_attempts
• orchestrator_attention_events
• orchestrator_workspace_leases

建议保留的设计原则：

• 生命周期快照可追溯，不能只存当前状态。
• reaction 尝试与结果必须审计化。
• workspace lease 必须显式记录 owner、branch、path、created_at、archived_at。
• 所有“自动动作”都必须能从数据库回放出因果链。

十、实施路线图

Phase 0：设计冻结与最小垂直切片

目标：明确边界，不让 orchestrator 逻辑污染现有 agent 核心。

交付：

• internal/orchestrator/types.go
• 生命周期与 reaction 的设计文档
• SQLite migration 草案
• /orch 命令组骨架

验收：

• 能创建 orchestrator 项目定义
• 能创建一个空的 worker session 记录
• 不改动现有单会话主路径行为

Phase 1：GitHub-first Orchestrator MVP

目标：从 issue 手工 spawn 一个 worker，并能跟踪其基础状态。

交付：

• TrackerProvider / SCMProvider / WorkspaceProvider / ExecutionProvider 最小接口
• GitHub provider MVP
• orchestrator service
• worker session 与 worktree 创建
• TUI 简单列表视图

验收：

• 能从 GitHub issue 创建 worker
• 能在独立 workspace 中运行
• 能看到 queued / spawning / working / done 状态

Phase 2：Lifecycle + Reaction 闭环

目标：让 CI fail、review changes、needs input 自动回流。

交付：

• canonical lifecycle manager
• reaction engine
• poller + webhook 混合输入
• send_to_worker / notify_operator 动作
• retry / escalation / fingerprint

验收：

• CI fail 能在阈值内回流到对应 worker
• review changes 能自动回流
• needs_input / stuck 能升级到 operator
• reaction 行为可审计可重放

Phase 3：恢复、归档、清理

目标：把 orchestrator 变成长生命周期系统，而非一次性演示。

交付：

• runtime root 与 hash namespace
• restore worker session
• adopt existing workspace
• archive / cleanup / gc
• reconcile job

验收：

• 重启后能恢复活动 worker
• 失联 runtime 可被正确识别
• 旧 workspace 能归档并按策略清理

Phase 4：Operator Console

目标：让用户真正运营 10 到 30 个 worker，而不是手动轮询。

交付：

• TUI 看板
• 详情面板
• attention queue
• 快捷动作：pause / resume / retry / restore / merge / archive

验收：

• 20 个 worker 下仍可快速识别 attention hotspot
• 任一 worker 的最近状态、PR、CI、review、reaction 均可一屏查看

Phase 5：Planner 与高级自动化

目标：从“手工编排”演进到“半自动并行交付”。

交付：

• backlog ingest
• work item DAG
• 并发预算与优先级调度
• merge policy
• auto-merge / auto-close / follow-up issue creation

验收：

• 支持一项目多 issue 并行
• 支持按依赖和预算自动决定 spawn 顺序
• 支持受控 auto-merge

十一、测试策略

11.1 单元测试

• lifecycle state transition
• reaction retry / escalation
• fingerprint / dedupe
• workspace lease 管理
• provider contract tests

11.2 集成测试

• 本地 git 仓库 + worktree 生命周期
• 模拟 GitHub PR/CI/review 事件
• restore / adopt / archive / gc

11.3 端到端测试

至少覆盖一条完整链路：

1. 从 issue 生成 worker
2. worker 提交变更并开 PR
3. CI fail
4. reaction 回流给 worker
5. worker 修复并 push
6. reviewer 提出 changes requested
7. reaction 再次回流
8. CI green 且 review approved
9. operator merge 或策略 auto-merge

十二、风险与应对

12.1 状态分叉

风险：subagent/task/session/orchestrator 各有状态，易出现真相源冲突。

应对：

• orchestrator 引入自己的 canonical lifecycle
• 其他状态只做输入，不做最终真相源

12.2 自动化越权

风险：agent 自动处理 review、merge、rebase 时可能越界。

应对：

• 所有危险动作走 permission v2
• reaction policy 支持 per-project/per-action 安全等级
• auto-merge 默认关闭

12.3 API 成本与速率限制

风险：多 worker 并发轮询 GitHub，容易触发 rate limit。

应对：

• batch enrichment
• webhook 优先，polling 兜底
• cache 与 backoff

12.4 Workspace 膨胀

风险：大量 worktree 与 archive 占盘并拖慢 git 操作。

应对：

• lease + archive + gc
• 按项目/状态/年龄分层清理

12.5 UI 先行导致空心化

风险：先做看板，底层状态与 reaction 不稳定，最终只能演示不能运行。

应对：

• 坚持 lifecycle / reaction / restore 先于复杂 UI
• 先做列表视图，再做丰富看板

十三、建议的决策顺序

建议严格按以下顺序推进：

1. 先定编排域模型与 canonical lifecycle。
2. 再定 provider 接口与 GitHub-first MVP。
3. 再做 reaction engine。
4. 再做 restore / runtime namespace / gc。
5. 最后做 operator console 的丰富交互。

不要反过来。

十四、最终建议

对 chong 而言，最正确的 AO 对标路线不是“照抄一个 Web Dashboard”，而是：

• 保留现有 agent/subagent/task/hooks/permissions/Lua 能力作为底座。
• 新增一层面向项目交付的 orchestrator control plane。
• 以 GitHub-first、TUI-first、Lua-first 的方式切入。
• 先做 lifecycle、reaction、workspace restore 三件套，再做大而全的 UI。

如果这条线做对，chong 最终不只是补齐 AO 的长处，还会因为以下几点形成反超：

• 更强的原生 agent 内核控制权
• 更强的 hooks / permissions / memory 可编程性
• 更自然的 Lua 工作流表达
• 更好的 A2A / MCP / skill 生态融合能力

这才是适合 chong 的 AO 演进路线。