agent-orchestration

Agent 平台编排

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

---

1. 登记（team.toml）

渐进登记：每用一个外部 Agent，在 plugin/team.toml 追加一段。只记稳定事实（mode/launch/process/window_hint/dispatch_steps/note），禁止记 PID/窗口句柄/坐标（坐标走 ui-maps；PID/hwnd 每次启动必变，hwnd 编号还会被 OS 复用给无关窗口——任何把易变事实固化进配置或缓存当派发依据的做法都是错的，进程管理职责归 Leader 当次实况）。

[opencode]
mode = "embedded"        # background | embedded | standalone | web —— 决定交互协议（§2）
launch = "powershell -NoExit -Command opencode"   # Leader 手动启动命令（见 §2 启动 SOP）
window_hint = "OpenCode" # 窗口标题特征（windows_list 匹配用）
process = "opencode.exe" # 进程名特征（process_list 识别依赖此字段）

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

• 手改 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：唯一 id（字母数字-_；保存后不可改）
   • mode：background / embedded / standalone / web ——窗口分类依据（§2 交互方式由此决定）
   • display_name / icon：状态栏与人读标识
   • launch / args：启动命令与参数（Leader 手动启动时使用，§2 启动 SOP）
   • window_hint：窗口标题特征（windows_list 匹配；终端类运行时标题常被覆写，hint 应选稳定前缀）
   • process：进程名特征（process_list 识别依赖此字段）
   • cooldown_secs / await_timeout_secs / timeout_action / confirm_keywords：启动冷却/超时动作/确认词表（缺省有默认值）
   • description：职责一句话（路由提示；新 agent 自动同步为其 .nuphus/handoff/{key}/read.md 的职责段）
   • note：Leader 专属实测备忘（如某热键不生效、某交互必须换路径等一手观察），随配置读取并在派发结果中回显；UI 禁止编辑
2. 落盘核对：plugin/team.toml 出现该段且原有段未被破坏（写回是段级增量）；新 key 联动生成 handoff 工作目录。
3. 完整段示例（实测可用样本）：

[opencode]
mode = "embedded"        # background | embedded | standalone | web
display_name = "OpenCode"
icon = "terminal"
launch = "powershell -NoExit -Command opencode"
window_hint = "OpenCode"
cooldown_secs = 20
await_timeout_secs = 90
timeout_action = "screenshot_alive"
confirm_keywords = ["allow", "confirm", "proceed", "yes/no", "approve"]
# note = "实测备忘：…（Leader 专属，UI 不可编辑）

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

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

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

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