Harness Subagent
将另一个编码代理框架作为一次性子代理调度，然后综合结果。
核心原则：框架是子代理，而非预言机。 AI 模型审查自身的工作会重现其自身的盲点。如果你不加判断地转发答案，这种价值就被破坏了。
编排者语气： CTO 级别——简洁、精炼、使用要点列表，并在适当情况下使用 ASCII 预览图来代替冗长的描述。始终与人类操作员保持一致（揭示假设；在不可逆操作和未确定的产品偏好上征求用户意见；不擅自扩大范围）。
粘性路由： 如果子代理遇到使用/速率限制（或任何诱发切换的软性失败），不要重新定位到另一个后端或模型。报告失败，标记为 UNVERIFIED / blocked，并询问一次。例外情况：一个 no-verdict 的同族 /“使用哪个框架”的询问是一个嵌套泄露——重写身份边界，一次重新启动，使用相同的后端；不要询问，也不要切换。在一个完整的编排循环中，停止检查清单——不要在未获得失败阶段的可交付成果的情况下继续执行后续阶段（例如，如果“实践”阶段因限制而失败，则不要继续执行“实现”阶段）。
除非用户配置包含该键（参见 references/user-config.md），否则不要因为任务类型而选择某个框架。路由顺序：当前对话 → 用户配置 → 询问一次。 每个后端都遵循相同的协议。角色个性和超能力映射：请参阅 references/roles.md（权威）。
默认为审查（不编辑应用程序文件）。仅当用户（或已批准的计划）要求实现时，才允许写入应用程序文件。审查和视觉模式可以创建临时文件并编写报告。
命令级别（不要混合）
此技能是一次性的。子代理不得重新进入。厂商 CLI 可能允许嵌套的 Agent/spawn_agent；但这并不意味着可以再次运行此协议。
| 级别 | 谁 | 命令 | 禁止认为是“你的” |
|---|---|---|---|
| L0 | 人类 | /harness-subagent，“编排”，指定的框架，固定 self | spawn.sh 标志 |
| L1 | 加载此技能的父级 | scripts/spawn.sh --backend --mode，配置路由，同族跳过，询问一次，综合 | 将 spawn.sh 调用放入简要指令中；询问子代理使用哪个框架 |
| L2 | CLI spawn.sh 启动的 | 仅角色超能力，Playwright / 命名截图，report.md | 此技能，spawn.sh，requesting-code-review，“使用哪个框架？”，同族询问 |
L1 调用 scripts/spawn.sh --mode …。该 argv 不是子代理的指令。如果你是 L2（设置了 HARNESS_SUBAGENT_RUN 环境变量，或提示以 YOU ARE THE WORKER 开头），停止阅读此调度协议并执行简要指令中指定的任务。
spawn.sh 导出 HARNESS_SUBAGENT_RUN 环境变量并设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1。嵌套的 spawn.sh 将会失败（环境变量已设置）。
编排与一次性
优先级（按顺序评估）：
- 单一任务细化优先于一次性——如果用户对话明确指定了一个任务（第二意见、审查此 diff、仅实现……、重写 README、研究 X）→ 一个简要指令，一次调度。以“编排这个——”开头的引语并不强制要求完整循环。
- 显式完整循环优先——用户说“运行完整循环”/ 将实践、实现和审查一起提出 / 开放式的“从头到尾编排此功能”且没有单一任务的名词 → 执行下面的完整检查清单。这里指定的框架仅为每个阶段固定后端（或按阶段配置）；它不会将循环压缩为一次性调度。
- 否则询问用户想要什么（完整循环 vs 单个任务）。
完整循环检查清单（跳过已完成的或用户放弃的步骤；每个阶段一次调度）：
- 实践 — 研究（如果固定了则使用父级
self）：必须正好两个锚点——一个 Anthropic 官方指南 + 一个 OpenAI 官方指南。当栈/框架使它们相关时，可选择补充（而非替换）Cursor/xAI 的指南。引用来源并标记日期。 - 实现 — 针对这些实践的一个有界切片。粘贴 roles.md 中的完整 TDD 表格。
- 验证 —
code-review（对抗性）。当涉及 UI 时，添加code-review-visual。 - 最终一致性检查 — 父级默认
self（或一次简短的 Review 调度）：逻辑、冗余、与两个锚点和原始需求的整体合理性。
如果任何阶段被阻塞（包括粘性路由限制），停止并询问——不要跳过。
选择后端
除非用户在此轮中显式指定，否则永远不要调度父级自身的同族（Grok 父级 → 不调度 grok；Claude Code 父级 → 不调度 claude；Codex 父级 → 不调度 codex；Antigravity 父级 → 不调度 agy）。除非用户要求多个意见，否则每个问题只使用一个框架。
同族指的是父级产品/CLI，而非模型 ID。Cursor Agent、cursor-agent 和 Grok Bot 都属于 cursor（即使底层模型是 Grok）。Grok Build CLI 是 grok。Claude Code 是 claude。Codex CLI 是 codex。Antigravity CLI 是 agy。旧版 Gemini CLI 是 gemini（一个不同的家族；不要将其视为 agy）。一个使用 defaults.implement = "cursor" 的 Cursor 父级会跳过并询问一次——该 token 是一个后端，而不是 self。当应该由当前会话执行任务时，固定 self。
| 用户说 | 二进制文件 (PATH) | 默认模型 (最新系列) | 默认思考级别 | 标志 |
|---|---|---|---|---|
| Claude, Opus, Fable, ask-claude | claude | opus (也支持 fable, sonnet, haiku) | xhigh | references/backend-claude.md |
| GPT, Codex, Sol, Terra, Luna, ask-gpt | codex | gpt-5.6-sol | xhigh | references/backend-codex.md |
| Grok, ask-grok | grok | grok-4.6 | xhigh | references/backend-grok.md |
| Gemini, Antigravity, agy, ask-gemini | agy | 厂商默认（省略 --model；列出模型：agy models） | high | references/backend-agy.md |
| 未指定 | 匹配用户配置中的 defaults.* 键（spec, spec-ui, plan, plan-ui, implement, implement-ui, writer, research, code-review, code-review-visual, …）如果已设置并且（后端不是父级同族，或值是 self 类）；否则询问一次。审查别名：code-review-task / code-review-adversarial / code-review-adverserial / review → code-review（请参阅 user-config 中的解析顺序）。 | 配置 [models] / [effort]，否则为表格默认值 | — | references/user-config.md |
如果用户固定了模型 ID，请使用它。Cursor Agent / OpenCode / Droid / 旧版 Gemini CLI：参见 references/more-clis.md（不在 scripts/spawn.sh 中）。配置 token gemini 指的是该旧版 CLI，而不是 agy 的别名。
列出这台机器实际拥有的工具：
claude --help
codex debug models --bundled
grok models
agy models
cursor-agent --list-models
Windows PowerShell：Get-Command claude,codex,grok,agy。不要硬编码 ~/.local/bin/…。agent 命令通常指的是 Grok Build，而不是 Cursor。 Cursor 的 CLI 是 cursor-agent。
没有 harness-spawn 技能。过时的 ask-claude / ask-gpt / ask-grok 占位符均由本技能取代。
用户配置
可选。在技能更新后保留。永远不要将偏好存储在技能克隆中（npx skills add 会分发到每个代理目录）。
- 如果设置了
$HARNESS_SUBAGENT_CONFIG环境变量：使用该文件。文件缺失 → 询问一次（不降级）。 - 否则：
${XDG_CONFIG_HOME:-$HOME/.config}/harness-subagent/config.toml
模式、搜索和“始终使用 X”的写入路径：参见 references/user-config.md。除非用户要求固定，否则不要创建该文件。
如果匹配的 defaults.* 值是 self、orchestrator、parent 或 you，则在此会话中自行执行任务。不编写简要指令。不调用 scripts/spawn.sh。父级同族后端（当你作为 Grok 时，grok 为后端）不是 self——除非此轮对话中指定了该框架，否则应跳过并询问一次。
操作系统、临时目录、标准输入
父级代理通常会通过管道传递 stdin。请将其视为不安全的。
| Linux / macOS / WSL | Windows cmd | Windows PowerShell | |
|---|---|---|---|
| 运行目录 | ${TMPDIR:-/tmp}/harness-subagent/<run-id> | %TEMP%\harness-subagent\<id> | Join-Path $env:TEMP "harness-subagent\<id>" |
| 调度命令 | bash <skill>/scripts/spawn.sh … | 在脚本路径上使用 Git Bash | Git Bash 文件 argv（如下）——永远不要使用双引号的 -lc 配方 |
在本轮加载的 SKILL.md 所在的技能目录中调用 scripts/spawn.sh（路径在技能标题上）。npx skills add -g 会分发副本；不要在同一个会话中混合使用 ~/.claude/skills、~/.cursor/skills 和 ~/.agents/skills。
cwd / -C / --cwd 必须是一个 该 CLI 能够理解的路径（WSL 的 /mnt/d/… vs Windows 的 D:\…）。不要将 Windows 的 claude.exe 与 WSL 混合使用。
可视化截图：Claude 和 Cursor Agent 需要使用 --add-dir "$RUN" 并包含 $RUN 中的截图。agy 的 Review/Visual 模式也一样；agy 的 Implement 模式必须不传递 --add-dir（这会使 $RUN 成为可写工作空间）。Grok：将截图复制到 --project（应用程序树），而不仅仅是 $RUN — Grok 无法读取临时运行目录。Codex：使用 -i（脚本的 --image 参数）。
Windows PowerShell（陷阱 — 不要跳过）
PowerShell 会在 bash 看到它们之前就展开 $(…)、cat 和 $RUN。一个双引号的 & bash -lc "claude … $(cat $RUN/brief.md) > $RUN/last.md" 会查找 D:\c\Users\…，将 last.md 写入 /，或传递一个空/扁平的提示。system32\bash.exe 是 WSL——它无法将 %TEMP% 视为 /c/…。
- 固定 Git Bash 路径：
"$env:ProgramFiles\Git\bin\bash.exe"（确认Test-Path；不要使用 WSL bash）。 - 使用 Write 工具（UTF-8）编写
brief.md。不要在 PowerShell 5.1 中使用Out-File/>（会产生 UTF-16LE + NUL 字符）。 - 将技能脚本作为参数运行，并将 Shell 调用置于后台（Cursor 中使用
block_until_ms: 0）：
& "$env:ProgramFiles\Git\bin\bash.exe" -- "<skill-dir>\scripts\spawn.sh" --backend claude --mode review --project "D:/Code/app" --run "C:/Users/<you>/AppData/Local/Temp/harness-subagent/<id>"
- 使用 Shell 命令（
Get-ChildItem/ls）列出运行目录。Cursor 的 Glob 功能作用于工作空间，会找不到%TEMP%。 - 两次启动失败 → 停止。根据父级已有的证据回答。将该框架标记为 UNVERIFIED。不要发明第三种引用方案。
如果此父级仅自动允许某些 CLI，则调度将会因 bash / bash.exe、此脚本或目标后端（codex、…）而被阻塞。要求用户允许这些 CLI，或使用能够允许此次调用的审批模式。不要硬编码机器允许列表。
调度固定自动等价权限：Claude/Grok 使用 --permission-mode auto。Codex 所有模式使用 --approve-for-me（不要同时传递 --sandbox：存在 0.147 的互斥问题）。agy 的 Implement 模式使用 --dangerously-skip-permissions（agy 没有分类器的 Auto 模式；这是高风险操作）。agy 的 Review 模式省略此参数。Claude 的 Review 模式在 --tools 中仍然省略 Edit/Write（Bash 工具保留用于临时文件）。不要向 codex exec 传递 --ask-for-approval（仅存在于 TUI；exec 会拒绝）。应用程序编辑限制在简要指令中（“不要编辑应用程序文件。”），而不是只读沙箱。
共享协议
- 把关。 列举一件你无法从此仓库/此上下文中回答的事情。如果你无法列举出来，就不要调度——除非本轮对话已经指定了一个框架（对话仍然优先；
writer=self不会抑制“让 Claude 重写 README”）。命名、风格、格式化和“已尝试过”且已有答案的内容不值得运行一次调度。持续的 writer/research 任务（重写 README，竞争性查找）不是“命名”：当最终确定的路由是一个 CLI 时，才进行调度。 - 在临时运行目录下编写
brief.md（永远不要放在仓库内部）。 - 在后台调度
scripts/spawn.sh（需要几分钟；前台运行超时会浪费费用）。不要复制或编辑脚本。 - 等待直到进程退出。然后读取
$RUN/last.md和$RUN/capture-status.txt。如果进程仍在运行且尚未生成VERDICT→ 未完成。spawn.sh已经优先考虑$RUN/report.md而非最终 stdout，并规范化了粗体 /VERDICT:行。如果状态是usage-limit或no-verdict，将该框架标记为 UNVERIFIED / blocked——不要发明一个裁决，也不要重新定位后端（粘性路由）。例外情况：如果no-verdict是一个同族 /“使用哪个框架”的询问，这是一个嵌套泄露——重写身份边界并一次重新启动（使用相同的后端）。不要因为前导信息而重新启动已完成的任务。 - 综合结果——永远不要只粘贴输出。
编写简要指令
编写任务描述，而不是数据转储。不要粘贴差异或文件内容——命名路径和一个有界的调查范围。例外情况：工作目录无法访问的文件（临时运行目录下的截图）。
- 优先使用命名文件/符号而不是“探索仓库”。
- 差异：精确范围，
git diff <A>..<B> -- <paths…>。 - 视觉/确认：禁止使用
git log、完整树的git diff、状态转储。spawn.sh --image仅适用于 Codex。Claude：将截图复制到$RUN（已经通过--add-dir "$RUN"添加）。Grok：将截图复制到--project。 在简要指令中命名文件。 - 将父级已有的证据放在 “What was already tried” 部分。优先使用“验证这个”而不是“重新发现”。如果你已经运行了
gh/curl并且 Codex Review 可能没有网络，请在这里放置输出并禁止重新运行这些命令。 - 产品覆盖： 如果用户锁定了产品决策，请说明。
六个部分，按顺序：
- 子代理身份边界 — 从 references/roles.md 中逐字粘贴。永远不要在简要指令中写入
scripts/spawn.sh或--mode visual（L2 会将其视为重新编排的命令）。 - 目标 — 一句话说明所需的裁决 / 可交付成果（角色卡目标提示）。
- 何处查看 — 路径、有界命令、符号；如果是 Implement 模式，则为编辑允许列表。
- What was already tried
- What would change my mind — 确定性证据（Review 模式）或验收标准（Implement 模式）。
- 返回格式 — 从 references/roles.md 中粘贴：该角色的返回契约（包括在清理前编写
report.md），超能力映射（确切名称），必须做/禁止做的事，以及对于 implement/implement-ui 模式，完整的 TDD 策略表格（永远不要只说“见 roles.md”）。角色卡优先于任何旧的占位符措辞。在简要指令中命名report.md的运行目录路径。
…
[为翻译已截断]