SuperAPI AI 工具集

harness-run

编程与开发

查看项目

更新于 10-19 01:11

技能介绍

用途

harness-run 用于长时间运行、且必须跨越全新上下文、后台重启或计划性交接继续推进的工作。技能说明明确不适用于一次性问答。典型触发场景包括:无人值守的改进—验证循环,过夜的调试、修复、审计或交付工作,从全新 Codex 会话依据持久状态恢复任务,应以全新 codex exec 会话重新拉起后台运行,以及范围受控的多智能体检查、验证或复核。

主要能力

该技能通过 scripts/harness_run_ctl.py 提供持久化运行控制,在 .harness-run/ 下保存持久状态;运行本地协作文档位于 .harness-run/docs/,每轮证据、生成知识和设计笔记分别位于 .harness-run/evidence/、.harness-run/generated/ 和 .harness-run/design/。它保证前台与后台行为对等,提供恢复、状态、停止和交接行为,并支持一次一轮的改进—验证循环。

每次运行都会在 .harness-run/docs/ 下初始化一份迷你协作记录,相当于运行本地的项目文档系统,包含架构快照、运行计划、约束、验证流水线、进度、决策、交接、完成和同步策略。如果目标仓库自带 docs/,仍以 .harness-run/docs/ 作为执行层,仅当 sync-policy.md 允许时同步简明摘要。

使用方式

用户入口有三项:run-task 以一句自然语言目标启动持久运行,--verify 为可选项;status 以人类可读形式查看当前运行;stop 干净地停止当前运行。普通用户无需操作内部命令或设计完整启动契约。技能触发时应只接受目标请求,从项目证据中推断计划、范围、指标和验证方式,自行运行辅助脚本,并报告持久状态路径与当前状态。仅在调试或全新 Codex 会话需手动重建运行时提示时才提及内部命令。

启动契约中只有 Goal 是用户必填项,需在启动前推断 Scope、Metric、Direction、Verify,可选字段包括 Guard、Iterations、Stop condition、Run mode、Execution policy。能安全推断则推断;范围不清时默认当前仓库或当前工作目录,读取证据后再收窄;验证不清时不阻塞启动,改用带具体证据的计划/清单完成判定。只有继续推进很可能产生与用户意图相反的工作时才询问。若用户明确要求遵循某目录、计划文件、路线图、问题列表或清单,则将其视为权威范围与顺序,除非它与安全、仓库指令或可执行证据冲突,否则不重新协商计划。

默认执行策略为 workspace_write;除非用户明确要求或接受更高后台风险,不使用 danger_full_access,该模式会向嵌套 codex exec 会话注入 Codex 的危险绕过参数。默认停止行为:direction=pass 时验证通过即停止;direction=complete 时记录指标达到完成即停止;提供 verify 但省略 metric 时,验证命令本身作为被跟踪指标标签;省略 verify 时使用 metric=planned work checklist、direction=complete、stop_condition=complete,并在推断或用户指定计划有证据满足后才记为完成;后台运行在无显式上限时默认迭代上限为 25。

快速开始(后台):先用 run-task 启动,用 status 查看运行时,用 stop 结束。若进程停在 needs_human,先阅读 .harness-run/runtime.log、.harness-run/state.json 和 .harness-run/rounds.tsv 再继续;恢复工作前阅读 .harness-run/docs/handoff.md、.harness-run/docs/run-plan.md 和 .harness-run/docs/constraints.md。

快速开始(前台):run-task --foreground 在当前 Codex 会话中准备持久运行;阅读仓库 AGENTS.md、当前源码、构建/测试配置和近期日志;测量基线;基线存在后初始化状态;执行一项聚焦变更,用命令或证据清单验证并记录结果;每轮更新 .harness-run/docs/handoff.md,仅在事实变化时更新进度、决策、约束和架构;从持久状态重复。

常用命令: python <skill-root>/scripts/harness_run_ctl.py run-task --goal "<goal>" python <skill-root>/scripts/harness_run_ctl.py run-task --foreground --goal "<goal>" python <skill-root>/scripts/harness_run_ctl.py run-task --goal "<goal>" --verify "<command>" python <skill-root>/scripts/harness_run_ctl.py run-task --foreground --goal "<goal>" --verify "<command>" python <skill-root>/scripts/harness_run_ctl.py status python <skill-root>/scripts/harness_run_ctl.py stop

持久状态

所有正常运行产物位于 <workspace_root>/.harness-run/,包括:launch.json(已确认启动清单)、state.json(主要恢复快照)、rounds.tsv(仅追加审计轨迹)、runtime.json(后台控制器 pid、状态与最近决策)、runtime.log(控制器与嵌套 Codex 输出)、context.json(活动运行的标准路径映射),以及 docs/、evidence/、generated/、design/ 四个目录。每个受管理的 git 仓库还可能获得本地指针,位置为 git rev-parse --git-path harness-run/pointer.json,指向工作区所属的 context.json。运行本地文档由 references/templates/ 中的模板初始化,不替代目标仓库文档,而是让全新 Codex 会话无需隐藏对话状态即可继续的持久执行记录。核心运行文档包括 project-architecture.md、product-context.md、run-plan.md、constraints.md、change-inventory.md、validation-pipeline.md、operability.md、security-boundary.md、sync-policy.md、progress.md、decisions.md、handoff.md、completion.md。

轮次规则

从源文件、日志、测试和持久状态重建上下文;编辑前阅读 constraints.md、run-plan.md、project-architecture.md、validation-pipeline.md 和 handoff.md;改动前建立或刷新基线;验证不清时先创建或推断执行清单与证据清单;每轮只做一项聚焦变更或一个可证伪诊断;有命令时机械验证,否则用文件清单、diff 审查、构建可行性、样例输出、截图、生成报告或清单完成等具体证据验证;记录保留、丢弃、阻塞或无操作等恰好一种结果;仅目标的部分轮次使用 refine、search 或 pivot 并标记 metric=incomplete,指标实际完成前不使用 keep;每轮更新 handoff.md,且每个记录轮次至少更新一个进度/证据产物;Markdown 文档中不保留原始日志和密钥,只总结脱敏事实;绝不让下一轮依赖隐藏对话状态。

内部控制平面

较重的运行时协议位于 references/runtime-loop.md 和辅助脚本中。run-task 是用户入口,创建或恢复持久运行并默认启动后台控制器;create-launch、launch、start、controller、init-state、record、resume-prompt 为内部或高级命令。控制器循环通过从 .harness-run/ 重新启动全新 codex exec 会话,跨越 Codex 上下文限制。needs_human 表示控制器因真实阻塞、状态不一致、缺失运行产物、控制器进程陈旧或停滞而停止,而非用户应继续等待。重复启动规则:以相同目标、范围和验证命令再次运行 run-task 会复用现有运行;以相同目标和范围再次运行纯目标模式会复用现有计划/清单运行;行为契约不同则停在 needs_human 而不混合状态,契约比较包括 goal、scope、verify、metric、direction、guard、iterations、stop condition、execution policy 和 codex args。高级全新启动可传 --force,它会在创建新运行前归档现有 .harness-run 文件;后台控制器仍活动时 --force 拒绝归档,需先停止。

多智能体模式

只委派相互独立的辅助工作:一个智能体做有界源码检查,一个做日志或测试验证,或一个做审查,前提是这些路径不重叠。不要用多个智能体重复同一调查。在下一轮前把有用发现合并进持久状态。

恢复纪律

从 .harness-run/state.json、.harness-run/rounds.tsv 和 .harness-run/launch.json 恢复,而非对话记忆;改动前重读状态文件、最新轮次、最新日志、docs/handoff.md、docs/run-plan.md、docs/constraints.md 和 docs/project-architecture.md;证据缺失时先收集;harness 状态不一致时以 needs_human 停止而非自行发明恢复路径。

适用场景与限制

harness-run 能让运行可恢复,并在 Python 控制器和机器存活期间持续重新拉起 Codex。它不会在重启、登出或进程终止后自动重启:重启后需手动启动全新 Codex 会话,阅读 .harness-run/state.json、.harness-run/rounds.tsv 和 .harness-run/launch.json,再用相同目标继续 run-task。它自身也不能证明任务在语义上完成;完成仍需 run-plan.md、completion.md、验证输出和证据产物支撑最终 complete 指标。其他参考资料包括 references/collaboration-protocol.md(运行本地协作纪律与更新节奏)、references/run-docs-protocol.md(.harness-run/docs/ 文件角色与同步边界)、references/recovery-runbook.md(needs_human、陈旧运行时与恢复规则)、references/persistence-and-redaction.md(仅本地文件、脱敏与仓库同步安全)。