@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/goal-harness-integration-guide.md

@@ -1,364 +1,364 @@
-# `/goal` + Harness 接入指南
-
-## 1. 目标
-
-本文说明如何把 Codex 官方 `/goal` 长期目标模式，与当前 Harness 的 driver-first 执行链结合使用。
-
-目标不是让 `/goal` 替代 Harness，而是让它承担：
-
-- 外层 7x24 持续目标保持
-- 人机协同 steering
-- 长任务 pause / resume / edit
-
-同时继续保留 Harness 的：
-
-- `task.json`
-- `tools/harness/codex-loop.ps1`
-- `test_command`
-- review gate
-- `progress.txt`
-- `traces/*.json`
-- stop hook continuation / block
-
-一句话：
-
-```text
-/goal 在外
-driver + stop hook 在内
-```
-
-## 2. 推荐分层
-
-推荐分层如下：
-
-```text
-Codex Goal Mode
-  -> 维持长期目标
-  -> 接受人工跟进消息修正方向
-  -> 持续要求“推进当前 Harness 任务”
-
-Harness Driver
-  -> 读取 task.json
-  -> 单任务实现
-  -> Stage 1 / test_command / Stage 2
-  -> trace / progress / commit
-
-Stop Hook
-  -> 停止前治理门
-  -> continuation / allow stop
-  -> dirty workspace / governance drift / failed trace gate
-```
-
-这三层的职责不要混：
-
-- `/goal` 不负责直接判断代码是否完成。
-- driver 不负责维护长期目标 UI 状态。
-- stop hook 不负责变更 goal 本身。
-
-## 3. 适用场景
-
-适合使用 `/goal + Harness` 的场景：
-
-- 长时间、跨多个任务推进的工程目标
-- 需要白天人工 occasional steering、夜间自动续跑
-- 希望持续推进，但又不能放弃严格的 review / test / trace / commit 约束
-
-不适合的场景：
-
-- 只跑一个短任务
-- 还没补齐 testing truth source、repo-map、task queue
-- 当前工作区不稳定、频繁 dirty、需求边界模糊
-
-## 4. 安装层建议
-
-### 4.1 `user` 层
-
-更适合放：
-
-- `/goal` 的使用习惯
-- 目标模板
-- 全局 steering 方式
-
-### 4.2 `project` / `full` 层
-
-更适合放：
-
-- `task.json`
-- `tools/harness/codex-loop.ps1`
-- stop hook
-- `docs/testing/*`
-- `docs/ai/repo-map.md`
-
-### 4.3 最终建议
-
-如果你要实际使用两者：
-
-- `/goal` 的“目标文案”放在用户工作流层
-- Harness runtime 和 repo truth source 仍放项目层
-
-## 5. 使用前提
-
-开始前至少满足：
-
-1. `features.goals = true` 已启用，或 `codex features enable goals` 已执行。
-2. 项目已完成 Harness bootstrap。
-3. 已有真实 `task.json`，不是 smoke 占位。
-4. 已有 `docs/ai/repo-map.md` 或等价导航文件。
-5. 已有最少 testing truth source：
-   - `ACCEPTANCE_EXAMPLES.md`
-   - `TRACEABILITY_MATRIX.md`
-   - `TEST_DATA_MATRIX.md`
-   - `verify-matrix.md`
-6. 若目标涉及用户可见高风险路径，已有 `docs/testing/e2e-plan.md`。
-
-如果这些前提不成立，不要直接开 `/goal` 长跑。
-
-## 6. 推荐操作顺序
-
-### Step 1：先收敛计划
-
-先用 `/plan` 或等价流程，把目标收敛成：
-
-- 当前要推进的 feature / release
-- 任务边界
-- 非目标
-- 阻塞条件
-
-### Step 2：确认 Harness 状态
-
-在目标项目里至少确认：
-
-```powershell
-git status --short
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/doctor.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
-```
-
-### Step 3：设置 `/goal`
-
-在 Codex app 中启动 `/goal`，让它以“持续推进 Harness 任务”为目标，而不是“自由发挥写功能”。
-
-### Step 4：目标运行时的固定动作
-
-推荐让 `/goal` 驱动以下固定策略：
-
-1. 优先读取 `AGENTS.md`、`docs/ai/repo-map.md`、`docs/testing/*`。
-2. 优先推进 `task.json` 中下一个 runnable task。
-3. 实际执行通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 完成。
-4. 遇到 stop hook continuation、failed trace、failure-triage 报告时，再决定：
-   - 继续
-   - 暂停
-   - 请求人工输入
-
-### Step 5：暂停 / 恢复 / 编辑
-
-`/goal` 适合做这些动作：
-
-- 暂停夜间运行
-- 修改长期目标的表述
-- 把“实现 feature”改成“先修 release blocker”
-- 清空不再需要的目标
-
-但这些不应直接修改 driver 协议本身。
-
-## 7. 推荐 `/goal` 文案模板
-
-下面这些模板的共同原则是：
-
-- 目标要约束到 Harness 执行方式
-- 不允许绕过 task/test/review/trace
-- 出现阻塞时要求明确输出
-
-### 模板 A：标准持续推进
-
-```text
-持续推进当前项目的 Harness 任务队列，直到 task.json 中没有 runnable task、出现真实人工阻塞，或 stop hook / review / test / trace 明确要求暂停。
-
-强制约束：
-1. 先遵守 AGENTS.md、docs/ai/repo-map.md、docs/harness/*、docs/testing/*。
-2. 通过 tools/harness/codex-loop.ps1 -RunUntilDone 推进任务，不绕过 task.json。
-3. 不跳过 test_command、Stage 1、Stage 2、trace 或 commit gate。
-4. 测试失败时先查看 failure-triage 结果，再决定下一步。
-5. 缺少 truth source、e2e-plan、权限或外部依赖时，明确报告 BLOCKED，不自行猜测。
-```
-
-适用：
-
-- 常规功能开发
-- 多任务串行推进
-
-### 模板 B：夜间长跑
-
-```text
-在无人值守时持续推进当前 Harness 项目，但只允许在 driver 和 stop hook 都认为可以继续时前进。
-
-运行原则：
-1. 优先执行 task.json 中下一个 runnable task。
-2. 任何 dirty workspace、governance drift、failed trace、truth source 缺失都视为暂停信号。
-3. 不要为追求连续运行而弱化测试、跳过 review 或绕过 stop hook。
-4. 每次停下时总结：当前任务、最近证据、failure-triage 结果、是否需要人工。
-```
-
-适用：
-
-- 夜间自动推进
-- 低频人工巡检
-
-### 模板 C：高风险用户可见功能
-
-```text
-持续推进当前高风险用户可见功能，但必须先确认 docs/testing/e2e-plan.md、验收示例、追溯矩阵和 repo-map 已齐备。
-
-额外约束：
-1. 没有 e2e-plan 时不进入实现，先补测试计划。
-2. 先从 docs/ai/repo-map.md 进入代码结构，再做局部文件修改。
-3. 测试失败时先按 TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY 分类。
-4. 不允许用 mock、fixture、local-only adapter 冒充真实交付路径。
-```
-
-适用：
-
-- 前端主流程
-- 权限、路由、状态流转
-- release 前关键路径
-
-### 模板 D：恢复性目标
-
-```text
-恢复并继续当前 Harness 执行链。先判断上次停止是正常 allow stop、stop hook continuation、review 失败、test_command 失败还是真实 BLOCKED。
-
-执行顺序：
-1. 读取最新 progress.txt、latest trace、failure-triage 报告。
-2. 确认当前 runnable task 和最近失败阶段。
-3. 如果 stop hook / driver 允许继续，则继续推进。
-4. 如果仍然 blocked，输出需要人工处理的最小动作，不要空转。
-```
-
-适用：
-
-- 中断恢复
-- 早上接手夜间运行结果
-
-## 8. 推荐跟进消息模板
-
-### 调整优先级
-
-```text
-把长期目标改成：优先清掉当前 release blocker，其次再继续 feature 实现。不要新增新范围。
-```
-
-### 强制保守
-
-```text
-接下来优先保守模式：不要扩展范围，只推进当前 runnable task，测试失败就停并给出 failure-triage 摘要。
-```
-
-### 切回人工确认
-
-```text
-如果下一轮还遇到相同 blocker，不要继续尝试，直接停下并输出需要人工决策的最小问题清单。
-```
-
-## 9. 和 stop hook 的协作规则
-
-推荐固定规则：
-
-1. stop hook 的 continuation / allow stop 结果优先于 `/goal` 的“想继续跑”。
-2. `/goal` 不应覆盖 dirty workspace gate。
-3. `/goal` 不应覆盖 failed trace / governance drift gate。
-4. stop hook 只决定：
-   - 允许继续
-   - 要求继续下一轮
-   - 必须阻塞
-5. `/goal` 只决定：
-   - 目标是否还有效
-   - 人类是否要继续让系统围绕这个目标工作
-
-## 10. 和 failure-triage 的协作规则
-
-当前 driver 已在测试失败时自动生成 `failure-triage` JSON。
-
-因此 `/goal` 运行时建议遵守：
-
-1. 测试失败后先读 triage 报告，不要直接盲修。
-2. 若一级分类是：
-   - `TEST_CODE_ISSUE`：可以优先修测试
-   - `PRODUCT_BUG`：优先修业务实现
-   - `REQUIREMENT_CHANGE`：先回规格/测试真相源
-   - `ENV_OR_DATA_ISSUE`：先修环境、seed、权限
-   - `FLAKY`：先修等待/隔离/时序，不要糊 timeout
-3. 若 triage parse 失败或报告缺失，应降级为人工检查 latest trace/log。
-
-## 11. 反模式
-
-不要这样用：
-
-### 反模式 1：把 `/goal` 当 driver 替代品
-
-错误：
-
-- 直接让 `/goal` 自由实现，不走 `task.json`
-
-问题：
-
-- 失去任务边界
-- 失去 trace / commit gate
-
-### 反模式 2：让 `/goal` 覆盖 stop hook
-
-错误：
-
-- stop hook 明确 blocked，但目标仍要求“继续往前冲”
-
-问题：
-
-- 容易导致脏工作区、无意义重试、证据漂移
-
-### 反模式 3：目标写得太宽
-
-错误：
-
-- “持续把这个项目做完”
-
-更好：
-
-- “持续推进当前 Harness 任务队列，严格遵守 task/review/test/trace/commit gate”
-
-## 12. 推荐最小试点方式
-
-不要一开始就在关键生产仓库全量依赖 `/goal`。
-
-建议试点顺序：
-
-1. 选一个已完成 bootstrap 的 Harness 项目。
-2. 任务规模控制在 2-5 个 runnable task。
-3. 先人工跑一轮 driver，确认链路干净。
-4. 再开 `/goal` 跑一个夜间周期。
-5. 第二天检查：
-   - `progress.txt`
-   - latest trace
-   - failure-triage 报告
-   - stop hook continuation 次数
-6. 只要出现空转或频繁重复 blocker，就先收紧目标文案，再继续试。
-
-## 13. 当前仓库的推荐结论
-
-当前仓库最适合的默认建议是：
-
-- `/goal`：可选、外层、用户级
-- stop hook：内层、治理门
-- driver：主执行链
-
-短期不建议：
-
-- 把 `/goal` 直接接进 driver 主逻辑
-- 让 stop hook 反向控制 goal 状态
-- 再造第二套长期运行状态文件
-
-## 14. 参考
-
-- OpenAI Codex app commands: `https://developers.openai.com/codex/app/commands`
-- OpenAI Codex use cases: `https://developers.openai.com/codex/use-cases`
-- 本仓库分析：`harness-analysis/13-goal-mode-vs-stop-hook-continuation.md`
-- 当前 driver：`tools/harness/codex-loop.ps1`
-- 当前 stop hook：`tools/harness/hook-stop-verify.ps1`
+# `/goal` + Harness 接入指南
+
+## 1. 目标
+
+本文说明如何把 Codex 官方 `/goal` 长期目标模式，与当前 Harness 的 driver-first 执行链结合使用。
+
+目标不是让 `/goal` 替代 Harness，而是让它承担：
+
+- 外层 7x24 持续目标保持
+- 人机协同 steering
+- 长任务 pause / resume / edit
+
+同时继续保留 Harness 的：
+
+- `task.json`
+- `tools/harness/codex-loop.ps1`
+- `test_command`
+- review gate
+- `progress.txt`
+- `traces/*.json`
+- stop hook continuation / block
+
+一句话：
+
+```text
+/goal 在外
+driver + stop hook 在内
+```
+
+## 2. 推荐分层
+
+推荐分层如下：
+
+```text
+Codex Goal Mode
+  -> 维持长期目标
+  -> 接受人工跟进消息修正方向
+  -> 持续要求“推进当前 Harness 任务”
+
+Harness Driver
+  -> 读取 task.json
+  -> 单任务实现
+  -> Stage 1 / test_command / Stage 2
+  -> trace / progress / commit
+
+Stop Hook
+  -> 停止前治理门
+  -> continuation / allow stop
+  -> dirty workspace / governance drift / failed trace gate
+```
+
+这三层的职责不要混：
+
+- `/goal` 不负责直接判断代码是否完成。
+- driver 不负责维护长期目标 UI 状态。
+- stop hook 不负责变更 goal 本身。
+
+## 3. 适用场景
+
+适合使用 `/goal + Harness` 的场景：
+
+- 长时间、跨多个任务推进的工程目标
+- 需要白天人工 occasional steering、夜间自动续跑
+- 希望持续推进，但又不能放弃严格的 review / test / trace / commit 约束
+
+不适合的场景：
+
+- 只跑一个短任务
+- 还没补齐 testing truth source、repo-map、task queue
+- 当前工作区不稳定、频繁 dirty、需求边界模糊
+
+## 4. 安装层建议
+
+### 4.1 `user` 层
+
+更适合放：
+
+- `/goal` 的使用习惯
+- 目标模板
+- 全局 steering 方式
+
+### 4.2 `project` / `full` 层
+
+更适合放：
+
+- `task.json`
+- `tools/harness/codex-loop.ps1`
+- stop hook
+- `docs/testing/*`
+- `docs/ai/repo-map.md`
+
+### 4.3 最终建议
+
+如果你要实际使用两者：
+
+- `/goal` 的“目标文案”放在用户工作流层
+- Harness runtime 和 repo truth source 仍放项目层
+
+## 5. 使用前提
+
+开始前至少满足：
+
+1. `features.goals = true` 已启用，或 `codex features enable goals` 已执行。
+2. 项目已完成 Harness bootstrap。
+3. 已有真实 `task.json`，不是 smoke 占位。
+4. 已有 `docs/ai/repo-map.md` 或等价导航文件。
+5. 已有最少 testing truth source：
+   - `ACCEPTANCE_EXAMPLES.md`
+   - `TRACEABILITY_MATRIX.md`
+   - `TEST_DATA_MATRIX.md`
+   - `verify-matrix.md`
+6. 若目标涉及用户可见高风险路径，已有 `docs/testing/e2e-plan.md`。
+
+如果这些前提不成立，不要直接开 `/goal` 长跑。
+
+## 6. 推荐操作顺序
+
+### Step 1：先收敛计划
+
+先用 `/plan` 或等价流程，把目标收敛成：
+
+- 当前要推进的 feature / release
+- 任务边界
+- 非目标
+- 阻塞条件
+
+### Step 2：确认 Harness 状态
+
+在目标项目里至少确认：
+
+```powershell
+git status --short
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/doctor.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+### Step 3：设置 `/goal`
+
+在 Codex app 中启动 `/goal`，让它以“持续推进 Harness 任务”为目标，而不是“自由发挥写功能”。
+
+### Step 4：目标运行时的固定动作
+
+推荐让 `/goal` 驱动以下固定策略：
+
+1. 优先读取 `AGENTS.md`、`docs/ai/repo-map.md`、`docs/testing/*`。
+2. 优先推进 `task.json` 中下一个 runnable task。
+3. 实际执行通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 完成。
+4. 遇到 stop hook continuation、failed trace、failure-triage 报告时，再决定：
+   - 继续
+   - 暂停
+   - 请求人工输入
+
+### Step 5：暂停 / 恢复 / 编辑
+
+`/goal` 适合做这些动作：
+
+- 暂停夜间运行
+- 修改长期目标的表述
+- 把“实现 feature”改成“先修 release blocker”
+- 清空不再需要的目标
+
+但这些不应直接修改 driver 协议本身。
+
+## 7. 推荐 `/goal` 文案模板
+
+下面这些模板的共同原则是：
+
+- 目标要约束到 Harness 执行方式
+- 不允许绕过 task/test/review/trace
+- 出现阻塞时要求明确输出
+
+### 模板 A：标准持续推进
+
+```text
+持续推进当前项目的 Harness 任务队列，直到 task.json 中没有 runnable task、出现真实人工阻塞，或 stop hook / review / test / trace 明确要求暂停。
+
+强制约束：
+1. 先遵守 AGENTS.md、docs/ai/repo-map.md、docs/harness/*、docs/testing/*。
+2. 通过 tools/harness/codex-loop.ps1 -RunUntilDone 推进任务，不绕过 task.json。
+3. 不跳过 test_command、Stage 1、Stage 2、trace 或 commit gate。
+4. 测试失败时先查看 failure-triage 结果，再决定下一步。
+5. 缺少 truth source、e2e-plan、权限或外部依赖时，明确报告 BLOCKED，不自行猜测。
+```
+
+适用：
+
+- 常规功能开发
+- 多任务串行推进
+
+### 模板 B：夜间长跑
+
+```text
+在无人值守时持续推进当前 Harness 项目，但只允许在 driver 和 stop hook 都认为可以继续时前进。
+
+运行原则：
+1. 优先执行 task.json 中下一个 runnable task。
+2. 任何 dirty workspace、governance drift、failed trace、truth source 缺失都视为暂停信号。
+3. 不要为追求连续运行而弱化测试、跳过 review 或绕过 stop hook。
+4. 每次停下时总结：当前任务、最近证据、failure-triage 结果、是否需要人工。
+```
+
+适用：
+
+- 夜间自动推进
+- 低频人工巡检
+
+### 模板 C：高风险用户可见功能
+
+```text
+持续推进当前高风险用户可见功能，但必须先确认 docs/testing/e2e-plan.md、验收示例、追溯矩阵和 repo-map 已齐备。
+
+额外约束：
+1. 没有 e2e-plan 时不进入实现，先补测试计划。
+2. 先从 docs/ai/repo-map.md 进入代码结构，再做局部文件修改。
+3. 测试失败时先按 TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY 分类。
+4. 不允许用 mock、fixture、local-only adapter 冒充真实交付路径。
+```
+
+适用：
+
+- 前端主流程
+- 权限、路由、状态流转
+- release 前关键路径
+
+### 模板 D：恢复性目标
+
+```text
+恢复并继续当前 Harness 执行链。先判断上次停止是正常 allow stop、stop hook continuation、review 失败、test_command 失败还是真实 BLOCKED。
+
+执行顺序：
+1. 读取最新 progress.txt、latest trace、failure-triage 报告。
+2. 确认当前 runnable task 和最近失败阶段。
+3. 如果 stop hook / driver 允许继续，则继续推进。
+4. 如果仍然 blocked，输出需要人工处理的最小动作，不要空转。
+```
+
+适用：
+
+- 中断恢复
+- 早上接手夜间运行结果
+
+## 8. 推荐跟进消息模板
+
+### 调整优先级
+
+```text
+把长期目标改成：优先清掉当前 release blocker，其次再继续 feature 实现。不要新增新范围。
+```
+
+### 强制保守
+
+```text
+接下来优先保守模式：不要扩展范围，只推进当前 runnable task，测试失败就停并给出 failure-triage 摘要。
+```
+
+### 切回人工确认
+
+```text
+如果下一轮还遇到相同 blocker，不要继续尝试，直接停下并输出需要人工决策的最小问题清单。
+```
+
+## 9. 和 stop hook 的协作规则
+
+推荐固定规则：
+
+1. stop hook 的 continuation / allow stop 结果优先于 `/goal` 的“想继续跑”。
+2. `/goal` 不应覆盖 dirty workspace gate。
+3. `/goal` 不应覆盖 failed trace / governance drift gate。
+4. stop hook 只决定：
+   - 允许继续
+   - 要求继续下一轮
+   - 必须阻塞
+5. `/goal` 只决定：
+   - 目标是否还有效
+   - 人类是否要继续让系统围绕这个目标工作
+
+## 10. 和 failure-triage 的协作规则
+
+当前 driver 已在测试失败时自动生成 `failure-triage` JSON。
+
+因此 `/goal` 运行时建议遵守：
+
+1. 测试失败后先读 triage 报告，不要直接盲修。
+2. 若一级分类是：
+   - `TEST_CODE_ISSUE`：可以优先修测试
+   - `PRODUCT_BUG`：优先修业务实现
+   - `REQUIREMENT_CHANGE`：先回规格/测试真相源
+   - `ENV_OR_DATA_ISSUE`：先修环境、seed、权限
+   - `FLAKY`：先修等待/隔离/时序，不要糊 timeout
+3. 若 triage parse 失败或报告缺失，应降级为人工检查 latest trace/log。
+
+## 11. 反模式
+
+不要这样用：
+
+### 反模式 1：把 `/goal` 当 driver 替代品
+
+错误：
+
+- 直接让 `/goal` 自由实现，不走 `task.json`
+
+问题：
+
+- 失去任务边界
+- 失去 trace / commit gate
+
+### 反模式 2：让 `/goal` 覆盖 stop hook
+
+错误：
+
+- stop hook 明确 blocked，但目标仍要求“继续往前冲”
+
+问题：
+
+- 容易导致脏工作区、无意义重试、证据漂移
+
+### 反模式 3：目标写得太宽
+
+错误：
+
+- “持续把这个项目做完”
+
+更好：
+
+- “持续推进当前 Harness 任务队列，严格遵守 task/review/test/trace/commit gate”
+
+## 12. 推荐最小试点方式
+
+不要一开始就在关键生产仓库全量依赖 `/goal`。
+
+建议试点顺序：
+
+1. 选一个已完成 bootstrap 的 Harness 项目。
+2. 任务规模控制在 2-5 个 runnable task。
+3. 先人工跑一轮 driver，确认链路干净。
+4. 再开 `/goal` 跑一个夜间周期。
+5. 第二天检查：
+   - `progress.txt`
+   - latest trace
+   - failure-triage 报告
+   - stop hook continuation 次数
+6. 只要出现空转或频繁重复 blocker，就先收紧目标文案，再继续试。
+
+## 13. 当前仓库的推荐结论
+
+当前仓库最适合的默认建议是：
+
+- `/goal`：可选、外层、用户级
+- stop hook：内层、治理门
+- driver：主执行链
+
+短期不建议：
+
+- 把 `/goal` 直接接进 driver 主逻辑
+- 让 stop hook 反向控制 goal 状态
+- 再造第二套长期运行状态文件
+
+## 14. 参考
+
+- OpenAI Codex app commands: `https://developers.openai.com/codex/app/commands`
+- OpenAI Codex use cases: `https://developers.openai.com/codex/use-cases`
+- 本仓库分析：`harness-analysis/13-goal-mode-vs-stop-hook-continuation.md`
+- 当前 driver：`tools/harness/codex-loop.ps1`
+- 当前 stop hook：`tools/harness/hook-stop-verify.ps1`