agent-orchestration

Agent 平台编排

外部 Agent（独立终端 TUI / 桌面 App / Web 等平台）协作指南。系统提示词已覆盖的（工具描述/annotation/Constitution）不重复，本技能只写外部 Agent 特有流程。

铁律：非显式指定不派发外部 Agent。

---

1. 登记（team.toml）

渐进登记：每用一个外部 Agent，在 plugin/team.toml 追加一段。只记稳定事实（mode/launch/process/window_hint/dispatch_steps/note）；PID/hwnd 每次启动必变、hwnd 会被 OS 复用给无关窗口——一律按当次实况重新解析，禁止写死。

本段只示格式（键名与注释）；字段值一律占位，不代表任何已登记 agent 的实况。 任何具体 agent 的字段值，一律以 plugin/team.toml 当次读取为准。 完整段示例（含 dispatch_steps）见本节末尾第 3 条，此处不重复。

双登记路径（实测均有效）：

• 手改 team.toml：直接编辑保存即可被运行中系统即时读取（无需重启），适合快速实验与本轮临时接入；
• 配置中心录入：桌面 设置 → 外部 Agent → 新增（走 upsert_external_agent），适合正式归档——会联动生成 handoff 工作目录（read.md/memory.md/status.json），手改路径不生成这些文件（须后续补 agent_init 或由首次 dispatch 补建空骨架）。

调用决策：Read team.toml → process_list 看谁活着（活着优先）→ 按平台能力匹配。不维护历史评分。

跑通即归档（强制，当轮完成）

新外部 Agent 首次跑通验证后，必须当轮登记归档，禁止「以后再用再配」——不归档则下次会话无从知晓其存在与用法，跑通经验直接丢失。

1. 配置中心录入：桌面 设置 → 外部 Agent → 新增（走 upsert_external_agent）：
   • 派发必需：key（唯一、保存后不可改）/ mode（窗口分类依据，§2 交互方式由此决定）/ launch+args（§2 启动 SOP 手动启动用）/ window_hint（终端类标题常被覆写，选稳定前缀）/ process（process_list 识别依赖此字段）/ dispatch_steps（§1.1——配错一步指令就打不进去，第一责任区）
   • 人读与备忘：display_name/icon/description（description 会同步为该 agent read.md 的职责段）；note = Leader 专属实测备忘（随配置读取、派发结果回显、UI 禁编辑）——opencode 的「window_hint 扫描无效、走 pid 路径」结论就记在这里

   已废弃不生效：cooldown_secs / await_timeout_secs / timeout_action / timeout_script / auto_approve / auto_approve_script / confirm_keywords——早期设想均未落地，配了等同没配，不要依赖（后端仅为旧配置兼容解析，UI 不再提供录入）。字段全集以代码为准：AgentFields（src-tauri/src/commands/config/team.rs）。

2. 落盘核对：plugin/team.toml 出现该段且原有段未被破坏（写回是段级增量）；新 key 联动生成 handoff 工作目录。
3. 完整段示例（全量字段的格式示例；值一律占位，实况以 plugin/team.toml 为准）：

[{key}]
mode = "embedded"        # background | embedded | standalone | web
display_name = "<显示名>"
icon = "terminal"
launch = "<启动命令>"
window_hint = "<窗口特征>"
process = "<进程名>"
note = "<Leader 实测备忘>（Leader 专属，UI 不可编辑）"

[[{key}.dispatch_steps]]
tool = "desktop_window_activate"
with = { hwnd = "{hwnd}" }

[[{key}.dispatch_steps]]
tool = "__sleep"
with = { ms = 500 }

[[{key}.dispatch_steps]]
tool = "desktop_input"
with = { hwnd = "{hwnd}", mode = "type", text = "{message}", send = "none" }

[[{key}.dispatch_steps]]
tool = "desktop_input"
with = { hwnd = "{hwnd}", mode = "hotkey", keys = ["enter"] }