Herdr 多智能体：并行编码智能体工作流

--- name: herdr-multiagent description: 在Herdr下并行运行多个编码代理：阶段分解、一个git worktree、隔离环境、每个代理的面板和文件简报、状态监控、审查、合并。子代理类型从`herdr pane current`（.result.pane.agent）读取，并与编排器（omp、opencode、claude、codex、kimi等）匹配。需要HERDR_ENV=1。 --- # 通过Herdr进行多代理工作 剧本：将项目任务分解为独立阶段，将每个阶段分配给一个单独的代理，该代理位于自己的git worktree和herdr面板中，提供文件简报，监控并接受结果。 技能与代理无关：子代理类型 = 编排器类型。从opencode启动技能 - 子代理将是opencode；从omp启动 - 将是omp；从claude启动 - 将是claude。切勿凭记忆替换编排器类型，也不要选择“流行”类型。 ## 0. 前置条件 ```bash test "${HERDR_ENV:-}" = 1 # 如果没有这个 - 停止，我们不在Herdr内部 ``` 如果检查失败 - 告诉用户会话不在Herdr下，并停止。不要从外部管理他人的Herdr。 面板/代理的基本命令 - 在标准Herdr技能中（`herdr --skill`）。已安装的二进制文件是语法权威；如有疑问，请阅读`herdr agent`、`herdr pane`、`herdr integration`，不要猜测。 ## 1. 确定自己的类型 - 在任何操作之前 ```bash herdr pane current --current ``` 字段`.result.pane.agent`就是编排器类型，也是子代理`--kind`的值： ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # 没有jq： KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` 为空或`unknown` - 询问用户以何种类型启动子代理。下文中的`$KIND`是获取到的值，不是字面量。 检查Herdr ↔ 该类型的集成（它提供`agent list/wait/prompt`）： ```bash herdr integration status | grep -i "$KIND" ``` - `current` - 正常。 - `not installed` - `herdr integration install "$KIND"`。集成仅由**新**会话拾取，因此必须在启动子代理之前安装；编排器本身对`agent list`不可见 - 这是正常的，不需要监控它。 - 类型不在`herdr integration install`列表中（例如`amp`、`cline`、`kiro`、`maki`）- 将没有结构化监控，我们按§7回退方案工作（`pane read` + git）。这不是阻塞问题。 记录并向用户声明：“子代理类型 = $KIND”。 ## 2. 分解 - 关键步骤，不要着急 - 阅读项目计划/规格和当前状态（`git log`、测试、`git worktree list`）。 - 将剩余工作分解为具有**不重叠文件区域**的阶段。两个代理处理同一个包 - 只能是有意识地且具有明确顺序（先后，不并行）。 - 对公共文件（config、lock）的增量修改是允许的 - 在简报中写入“仅增量，不更改签名”；合并冲突由编排器解决。 - 记录“阶段 → 可以/不可以触碰的文件”矩阵。 启动前：所有已完成的工作都已提交到main，工作树干净。 ## 3. 每个代理的Worktree + 隔离环境 ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Python项目的陷阱：共享venv会导入**他人**的代码（主仓库的editable install）。每个worktree都有自己的venv： ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` 多个venv通过一个后台命令顺序安装（pip缓存共享）。JS栈：每个worktree有自己的`node_modules`（`npm ci`）。 如果编排器有命令包装钩子（rtk等）：相对解释器路径（`../.venv/Scripts/python.exe`）在简报中通过此类钩子无法解析（“command not found”）。在简报和提示中 - 仅使用所需worktree的python/npm的**绝对**路径。 ## 4. 简报 - 用文件，不用命令行 `<repo>/.briefs/stage-<N>.md`（untracked）。简报结构： - **上下文**：先读什么（规格、契约、关键文件），已完成什么； - **任务**：具体需求，引用规格条款； - **边界**：可以/不可以触碰的文件，“不要离开worktree”，“不要push”； - **验收**：精确的测试/代码检查命令（使用worktree解释器的绝对路径），“旧测试保持绿色”，提交到自己的分支，最终报告。 简报不应假设特定的代理类型：不要写“运行omp/skill/...”，而是写目标、边界和验收命令。子代理将自行决定使用哪些工具。 给代理的提示要简短：“阅读文件<简报>并完整执行”。 ## 5. 面板：创建，立即命名 推荐布局 - main-left：编排器面板在左侧全高，所有子代理在右侧一列上下排列。如果用户安装了针对main-left的布局插件，任何其他方案都会破坏其视图。如果用户明确要求其他布局 - 按其要求执行。 第一个子代理 - `split --current --direction right`，其余 - `split --pane <前一个子代理> --direction down`在右列**内部**。不要拆分编排器面板，也不要向右拆分代理面板 - 只在右列中使用down链。 ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` 新面板ID - 来自JSON `.result.pane.pane_id`。不要触碰用户焦点（`--no-focus`）。子代理名称在第6步通过`agent start`给出，另外为了清晰起见，使用`herdr pane rename <pane_id> "s<N>-<name>"`。 ## 6. 启动自己类型的子代理 标准路径 - `agent start`，它还会验证面板中确实启动了预期的代理： ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <自主性标志> ``` 名称必须匹配`[a-z][a-z0-9_-]{0,31}`并且在活动代理中唯一。 ### 自主性标志 子代理在无人情况下工作，否则会卡在审批上。标志取决于CLI，而不是Herdr。已确认的： | 类型 | 启动 | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions`（或`--permission-mode bypassPermissions`） | | `opencode` | `-- --auto` | 对于任何其他类型（codex、gemini、kimi、cursor、copilot、droid、kilo、grok、hermes、qodercli、mastracode、pi等）- 不要编造标志。确定canonical可执行文件并阅读其帮助： ```bash herdr agent start --help # 在--kind描述中指定了canonical executable <executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` 未找到标志 → 检查CLI配置中是否有自主模式（例如`~/.omp/agent/config.yml: tools.approvalMode: yolo`、`~/.claude/settings.json: permissions`、`opencode.json: permission`），并警告用户子代理可能会卡在审批上 - 它们会显示为`blocked`状态（§7）。 ### 如果`agent start`因超时失败 Windows PowerShell面板中的已知错误：`agent start`发送损坏的`Start-Process` → 超时。解决方法 - 直接在面板中启动CLI： ```bash herdr pane run <pane_id> "<executable> <自主性标志>" sleep 3 && herdr pane read <pane_id> --lines 15 # 预期CLI提示 herdr agent rename <pane_id> s1-<name> # 如果herdr识别了代理 ``` 如果之后`herdr agent explain <pane_id>`没有给出已识别的代理 - 该面板的结构化监控不可用，我们按§7回退方案工作。 ### 发放简报 不要通过`pane run`：当TUI渲染粘贴时，Enter会被吞掉。分两步并暂停： ```bash herdr pane send-text <pane_id> "阅读文件<简报的绝对路径> - 这是你的简报。完整执行到底（代码、测试、代码检查、提交到自己的分支），然后给出最终报告。" sleep 5 && herdr pane send-keys <pane_id> Enter ``` 标准替代方案，当集成已安装且`agent start`成功时： ```bash herdr agent prompt s1-<name> "阅读文件<简报>并完整执行" --wait --timeout 300000 ``` 通过`pane read`检查简报已**发送**：输入为空，代理正在工作。 ## 7. 监控 - 通过集成，不是cron ```bash herdr agent list # 所有子代理的状态 herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<文本>" # 向工作中的代理补充指令 herdr agent read s1-<name> --lines 40 ``` 状态语义：`idle` - 准备好接收输入且其标签页已在UI中可见；`done` - 在不可见的后台工作后相同的idle（通过CLI读取不会将标签页标记为已见）；`blocked` - herdr识别到审批/问题UI，子代理在**等待**人类；`unknown` - 代理存在但没有分类，这不是完成标志。 编排器循环：`agent wait`逐个或按事件 → 验收（§8）。`blocked` → `agent read`，理解问题，通过`agent prompt`回答或询问用户。可疑的静默 → `pane read <pane_id>`。 `wait`超时保持适中（约30分钟），触发后重新设置：非常大的值会进入“timed out”。 当`$KIND`的集成不可用或`agent explain`未识别子代理时的回退方案：定期`herdr pane read <pane_id> --lines 60` + worktree中的`git log/status`。Cron - 仅作为最后手段，完成后必须删除。 子代理会话中断：worktree中的工作会保留。重新启动 - 使用相同的CLI及其继续标志（在`--help`中检查）：`omp --resume`、`claude --continue`、`opencode --continue`。然后提示：“会话已中断。检查git status，完成简报<文件>”。 ## 8. 验收和合并 - 每个分支：在其worktree中运行测试 + 代码检查，审查`git diff main...<branch> --stat`。 - 不要轻信子代理的最终报告 - 自己验证验收命令。 - 合并到main - 仅在用户确认后；手动解决增量冲突。 - 合并后：`git worktree remove`；分支 - 与用户协商。 - 释放子代理面板，不触碰编排器面板。