@pzy560117/codex-harness 0.1.2 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/codex-global-rules-example.md

@@ -1,292 +0,0 @@
-# Codex 全局规则配置示例
-
-**定位**: 给 `~/.codex/AGENTS.md` 和 `~/.codex/config.toml` 一个可落地示例，说明哪些内容应该放全局，哪些必须留在项目规则或 Harness 文档中。
-
-本文件和 `global-rules-and-bootstrap.md` 的分工:
-
-- `global-rules-and-bootstrap.md`: 解释全局规则、新项目接入、新环境初始化的整体流程。
-- 本文件: 直接给出推荐配置样例和分层判断标准。
-
----
-
-## 1. 总原则
-
-Codex 全局规则要短、稳、跨项目成立。它应该管“行为边界”和“机器环境”，不应该管某个项目的业务流程。
-
-推荐分层:
-
-| 层级 | 文件 | 应放内容 | 不应放内容 |
-| --- | --- | --- | --- |
-| 全局行为规则 | `~/.codex/AGENTS.md` | 输出语言、工具查找、Git 安全、验证习惯、Windows 注意事项 | 具体项目的目录结构、业务规则、任务队列、多 Agent 阶段细节 |
-| 全局运行配置 | `~/.codex/config.toml` | 默认模型、sandbox、approval、shell environment、全局 features | token、项目专属 MCP、项目私有环境变量、普通项目规则 |
-| 项目入口规则 | `<repo>/AGENTS.md` | 本仓库任务规则、提交规则、目录边界、driver 规则 | 跨项目通用工具路径、个人偏好长文 |
-| 项目运行配置 | `<repo>/.codex/config.toml` | 项目专属 MCP、项目 profile、可信项目 sandbox 策略 | 个人全局习惯、其他项目路径、普通项目规则 |
-| 长文档 | `<repo>/docs/` | 19 阶段流程、测试矩阵、架构、trace、CI、回归策略 | 简短必须遵守的入口规则 |
-
-判断标准:
-
-- 换一个项目仍然成立，放全局。
-- 只对当前仓库成立，放项目 `AGENTS.md`。
-- 需要长篇解释或模板，放项目 `docs/`。
-- 会影响 Codex CLI 行为，放 `config.toml`。
-- `developer_instructions` 和 `model_instructions_file` 是上下文入口，不是普通配置注释区；默认不用它们承载项目规则。
-- 包含 token、cookie、密码、私钥，不放任何仓库文档。
-
----
-
-## 2. 推荐的 `~/.codex/AGENTS.md`
-
-下面是 Windows 环境的全局示例。它可以作为个人机器的默认规则使用。
-
-```markdown
-# Codex 全局规则（Windows）
-
-## 作用范围
-
-- 本文件只放跨项目稳定成立的规则。
-- 某个仓库专属的任务流、目录结构、提交规范和业务规则，不放这里。
-- 项目规则放项目根 `AGENTS.md`，长文档放项目 `docs/`。
-
-## 工具绝对路径速查
-
-| 工具 | 绝对路径 |
-| --- | --- |
-| git | `D:\Program Files\Git\cmd\git.exe` |
-| gh | `C:\Program Files\GitHub CLI\gh.exe` |
-| node | `C:\Program Files\nodejs\node.exe` |
-| python | `C:\Users\<user>\AppData\Local\Programs\Python\Python312\python.exe` |
-| pwsh | `C:\Program Files\PowerShell\7\pwsh.exe` |
-| rg | `C:\Users\<user>\AppData\Local\Microsoft\WinGet\Links\rg.exe` |
-| curl | `C:\Windows\System32\curl.exe` |
-
-## 工具规则
-
-1. 工具查找顺序：`Get-Command` -> 已知绝对路径 -> 明确报错停止。
-2. `npm`、`pnpm`、`yarn` 在 Windows 下优先通过 PowerShell 调用。
-3. 如果 PATH 已在 `~/.codex/config.toml` 中固化，命令仍找不到时优先使用绝对路径，不盲目重装。
-4. 搜索优先用 `rg` 或 `rg --files`。
-5. 非交互自动化优先使用 `codex exec`。
-
-## 验证规则
-
-- 没有 fresh verification evidence，不要声称任务已完成。
-- 提交、合并、交付前必须运行与结论直接对应的验证命令。
-- 文档改动至少运行 `git diff --check`。
-
-## Git 与安全规则
-
-- dirty workspace 默认视为阻塞，除非用户明确说明哪些改动属于当前任务。
-- 禁止在未确认时使用破坏性命令，如 `git reset --hard`、`git checkout --`、递归删除。
-- 不把 token、cookie、私钥、密码写入仓库、trace 或文档。
-- 不在不可信环境使用高权限 sandbox。
-
-## Windows 环境规则
-
-- Windows 主链路优先使用 PowerShell driver。
-- Codex hooks 可作为增强层启用；Windows 仍不把 hooks 当主链路。
-- 需要内联多步验证时，不要让前一个命令失败被后一个命令的退出码掩盖，应显式检查 `$LASTEXITCODE`。
-
-## 分层规则
-
-- 跨项目稳定习惯放 `~/.codex/AGENTS.md`。
-- 当前仓库规则放 `<repo>/AGENTS.md`。
-- 详细架构、回归规则、trace 格式、CI 策略放 `<repo>/docs/`。
-```
-
-### 不要放进全局 AGENTS 的内容
-
-- `task.json`、`progress.txt`、`tools/harness/codex-loop.ps1` 的具体 workflow。
-- 具体产品需求，例如“宠物商城”“订单系统”“后台管理”。
-- 某个仓库的目录所有权，例如 `apps/frontend/` 归 frontend worker。
-- 某个项目的 19 阶段产物路径。
-- 真实 token、cookie、私钥、密码。
-- 项目专属 MCP server、数据库 URL、API base URL。
-
----
-
-## 3. 推荐的 `~/.codex/config.toml`
-
-全局 `config.toml` 应保持保守，适合大多数项目默认启动。高权限、项目 MCP 和特殊 profile 留给项目 `.codex/config.toml` 或命令行显式指定。
-
-```toml
-model = "gpt-5.4"
-model_reasoning_effort = "medium"
-personality = "pragmatic"
-sandbox_mode = "workspace-write"
-
-[approvals]
-approval_policy = "on-request"
-
-[shell_environment_policy]
-inherit = "all"
-ignore_default_excludes = true
-
-[features]
-codex_hooks = true
-
-# 全局只放跨项目稳定设置。
-# 项目专属 MCP、env、trust、danger-full-access profile 放 `<repo>/.codex/config.toml`。
-```
-
-### 全局 config 的边界
-
-建议放全局:
-
-- 默认模型和默认思考深度。
-- 默认 sandbox 和 approval 策略。
-- shell environment 继承策略。
-- 是否启用 hooks 这类跨项目 feature。
-
-不建议放全局:
-
-- 项目私有 MCP server。
-- 真实 API key、数据库密码、cookie。
-- 某个项目专用的 `danger-full-access` 默认策略。
-- 某个仓库的绝对路径。
-- 只服务一个项目的 profile。
-- 普通项目规则、长流程或历史解释。
-- `model_instructions_file` 这类会覆盖基础指令层的高风险入口。
-
----
-
-## 4. 项目 `.codex/config.toml` 示例
-
-项目配置用于补充当前仓库的运行策略。对于 Harness 项目，建议从 `templates/config/codex-config.toml` 复制，再按项目删减。
-
-```toml
-model = "gpt-5.4"
-model_reasoning_effort = "medium"
-sandbox_mode = "workspace-write"
-project_doc_max_bytes = 65536
-
-# 默认项目模板会安装根 AGENTS.md，因此不设置 fallback。
-# 旧项目没有 AGENTS.md 且真实存在 TEAM_GUIDE.md / .agents.md 时，再按项目显式添加。
-
-[approvals]
-approval_policy = "on-request"
-
-[features]
-codex_hooks = true
-
-[agents]
-max_threads = 4
-max_depth = 2
-job_max_runtime_seconds = 1800
-
-[profiles.automation]
-model = "gpt-5.4"
-model_reasoning_effort = "medium"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[profiles.controller-5-5-medium]
-model = "gpt-5.5"
-model_reasoning_effort = "medium"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[profiles.product-analyst-5-5-high]
-model = "gpt-5.5"
-model_reasoning_effort = "high"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[profiles.frontend-worker-5-4-medium]
-model = "gpt-5.4"
-model_reasoning_effort = "medium"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[profiles.backend-worker-5-4-high]
-model = "gpt-5.4"
-model_reasoning_effort = "high"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[profiles.test-runner-5-4-mini-medium]
-model = "gpt-5.4-mini"
-model_reasoning_effort = "medium"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-
-[profiles.visual-reviewer-5-5-high]
-model = "gpt-5.5"
-model_reasoning_effort = "high"
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-```
-
-项目 profile 只提供 Codex CLI 的执行配置；真正的阶段到 agent 路由仍以这些文件为准:
-
-- `.codex/rules/agents.md`
-
-项目 `.codex/config.toml` 的边界:
-
-- 整个 TOML 不会作为项目规则正文进入模型上下文。
-- `developer_instructions` 会注入 session，默认不用；普通规则放 `AGENTS.md`。
-- `model_instructions_file` 会覆盖 built-in base instructions，默认禁用。
-- `.rules` 是命令执行策略，不是项目 instruction。
-- hooks 配置不是上下文；hook 输出 `additionalContext` 时才按动态上下文治理。
-
----
-
-## 5. 推荐初始化命令
-
-新机器或新环境上先创建全局配置目录:
-
-```powershell
-New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
-```
-
-复制模板:
-
-```powershell
-Copy-Item ".\docs\codex-harness-engineering\templates\config\global-AGENTS.md" "$HOME\.codex\AGENTS.md"
-Copy-Item ".\docs\codex-harness-engineering\templates\config\global-config.toml" "$HOME\.codex\config.toml"
-```
-
-如果已有全局文件，先备份:
-
-```powershell
-$Stamp = Get-Date -Format "yyyyMMdd-HHmmss"
-Copy-Item "$HOME\.codex\AGENTS.md" "$HOME\.codex\AGENTS.md.bak-$Stamp" -ErrorAction SilentlyContinue
-Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.bak-$Stamp" -ErrorAction SilentlyContinue
-```
-
-检查工具是否存在:
-
-```powershell
-Get-Command git, rg, node, python, pwsh -ErrorAction Continue
-```
-
----
-
-## 6. 检查清单
-
-修改全局规则后，至少检查:
-
-- [ ] `~/.codex/AGENTS.md` 没有项目业务规则。
-- [ ] `~/.codex/AGENTS.md` 没有 token、cookie、私钥、密码。
-- [ ] `~/.codex/config.toml` 没有真实密钥。
-- [ ] 默认 sandbox 不是无条件 `danger-full-access`。
-- [ ] hooks 在 Windows 环境中只作为增强层，不替代 PowerShell driver 主链路。
-- [ ] 项目根 `AGENTS.md` 仍负责项目专属规则。
-- [ ] 文档改动已运行 `git diff --check`。
-
----
-
-## 7. 和多 Agent Harness 的关系
-
-全局规则只告诉 Codex “应该怎么安全工作”。它不负责决定 19 个阶段用哪个 agent。
-
-多 Agent 阶段路由放在项目或 Harness 层:
-
-- Stage 02 需求分析: `product-analyst`，同时产出可执行验收示例和可测试需求边界
-- Stage 03 需求追溯: `requirements-trace-analyst`，把 Requirement IDs 固化到 `TRACEABILITY_MATRIX`
-- Stage 09 多 Agent 派发: `orchestrator`
-- Stage 10 前端实现: `frontend-worker`
-- Stage 13 后端实现: `backend-worker`
-- Stage 17 验证回归: `test-runner`，只运行 fresh evidence、affected tests 和 P0 回归，不在本阶段第一次补测试范围
-- Stage 19 合并提交: `release-manager`
-
-这样分层后，全局规则可以长期稳定，项目 Harness 可以按业务和阶段持续演进。

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

@@ -1,380 +0,0 @@
-# `/goal` 目标启动模板库
-
-## 1. 先说结论
-
-这里不是“自由目标文案库”，而是 **`/goal` 启动模板库**。
-
-原因很简单：
-
-- 真正定义“做什么”的，不是 `/goal`。
-- 真正定义“怎么拆任务”的，不是 `/goal`。
-- 真正定义“能不能完成”的，也不是 `/goal`。
-
-在当前 Harness 体系里，这三件事分别由下面几层承担：
-
-| 层 | 负责什么 |
-| --- | --- |
-| spec / PRD / design / testing truth source | 定义目标、范围、验收、风险、非目标 |
-| `task.json` | 定义可执行任务队列、依赖、owned paths、验证命令 |
-| `/goal` | 只负责外层长期目标保持、持续推进和人机 steering |
-
-所以这里的模板，更准确的名字应该理解成：
-
-- **goal launch profiles**
-- **goal wrappers**
-- **goal control prompts**
-
-而不是“随便写一个长期目标让它自己跑”。
-
-## 2. `/goal` 和 spec / task.json 的区别
-
-### 2.1 spec / truth source 解决什么问题
-
-spec、设计、测试真相源回答的是：
-
-- 为什么要做
-- 做到什么算完成
-- 不做什么
-- 哪些路径高风险
-- 哪些证据必须存在
-
-### 2.2 `task.json` 解决什么问题
-
-`task.json` 回答的是：
-
-- 先做哪个任务
-- 哪些任务有依赖
-- 哪个任务接管哪些路径
-- 每个任务要跑什么验证命令
-
-### 2.3 `/goal` 解决什么问题
-
-`/goal` 回答的是：
-
-- 在长时间运行里，系统持续朝哪个方向推进
-- 用户暂停、恢复、修改目标时，外层控制面怎么表达
-- 遇到 stop hook / failed trace / triage 结果时，是继续、保守、还是停下等人
-
-所以它本质上是：
-
-```text
-持续运行控制模板
-```
-
-不是：
-
-```text
-需求模板
-```
-
-也不是：
-
-```text
-任务模板
-```
-
-## 3. 使用前提
-
-任何 `/goal` 模板启用前，都要先确认下面这些已经存在：
-
-### 最小前提
-
-1. `task.json` 已经是真实任务队列，不是 smoke 占位。
-2. 已有 `docs/ai/repo-map.md` 或等价导航文件。
-3. 已有基本 testing truth source：
-   - `ACCEPTANCE_EXAMPLES.md`
-   - `TRACEABILITY_MATRIX.md`
-   - `TEST_DATA_MATRIX.md`
-   - `verify-matrix.md`
-
-### 高风险用户可见任务额外前提
-
-4. 已有 `docs/testing/e2e-plan.md`
-5. 已明确 `failure-triage.md`
-
-### 运行前检查
-
-6. `tools/harness/doctor.ps1` 通过
-7. `tools/harness/verify.ps1` 通过
-8. 工作区不是未解释的脏状态
-
-如果这些前提不成立，不要直接开 `/goal`。
-
-## 4. 模板字段说明
-
-下面每个模板都建议显式包含 6 类信息：
-
-### A. 目标对象
-
-- 当前 feature / release / recovery scope
-
-### B. 依赖的真实真相源
-
-- `AGENTS.md`
-- `docs/ai/repo-map.md`
-- `docs/testing/*`
-- `task.json`
-
-### C. 执行动作
-
-- 通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 推进
-
-### D. 停止条件
-
-- 没有 runnable task
-- stop hook block
-- failed trace
-- 人工 blocker
-
-### E. 禁止事项
-
-- 不绕过 `task.json`
-- 不绕过 `test_command`
-- 不绕过 review / trace / commit gate
-
-### F. 失败处理
-
-- 优先读取 `failure-triage` 结果
-
-## 5. 模板 01：标准持续推进
-
-### 适用场景
-
-- 已有明确 spec
-- 已有真实任务队列
-- 需要连续推进多个任务
-
-### 启动模板
-
-```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，不自行猜测。
-```
-
-### 适合的跟进消息
-
-```text
-继续按当前任务队列推进，不新增范围。优先完成已经 runnable 的任务。
-```
-
-## 6. 模板 02：夜间长跑
-
-### 适用场景
-
-- 白天人工确认过状态
-- 夜间希望继续推进
-- 更关注稳态而不是速度
-
-### 启动模板
-
-```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 结果、是否需要人工。
-```
-
-### 适合的跟进消息
-
-```text
-进入保守夜间模式：如果同一 blocker 连续出现，不要反复重试，直接停下并报告。
-```
-
-## 7. 模板 03：高风险用户可见功能
-
-### 适用场景
-
-- 路由
-- 表单
-- 权限
-- 状态流转
-- 关键 UI 主流程
-
-### 启动模板
-
-```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 冒充真实交付路径。
-```
-
-### 适合的跟进消息
-
-```text
-先确认 e2e-plan 和影响面，不要为了前进速度绕过用户可见路径的测试计划。
-```
-
-## 8. 模板 04：恢复性目标
-
-### 适用场景
-
-- 上一轮 stop hook 强制继续
-- 早上接手夜间运行
-- 测试刚失败，需要恢复执行链
-
-### 启动模板
-
-```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，输出需要人工处理的最小动作，不要空转。
-```
-
-### 适合的跟进消息
-
-```text
-先恢复上下文，不要直接重跑实现；先解释最近一次失败和当前是否真的可继续。
-```
-
-## 9. 模板 05：Release 收口
-
-### 适用场景
-
-- 多个故事已完成
-- 进入 P0/P1 回归
-- 需要收口而不是再发散实现
-
-### 启动模板
-
-```text
-持续推进当前 release 收口，但不新增新功能范围。目标是完成当前 task.json 中与 release 相关的 runnable task，并输出 fresh evidence。
-
-约束：
-1. 优先处理 P0/P1 回归、契约验证、e2e/视觉证据和 failure-triage。
-2. 不新增新的 feature 实现任务，除非任务队列本身已经声明。
-3. 如果发现问题，优先归因到现有 story 或 release blocker，不要模糊扩写需求。
-4. 没有 fresh evidence 就不要声称 release 完成。
-```
-
-### 适合的跟进消息
-
-```text
-收口优先，不再扩 scope。失败项先归因到现有 blocker，再决定是否需要 repair。
-```
-
-## 10. 模板 06：治理修复
-
-### 适用场景
-
-- stop hook 被 governance drift 卡住
-- rules / prompts / docs / mirrors 漂移
-- 需要先修 Harness 面再继续业务开发
-
-### 启动模板
-
-```text
-当前目标不是继续业务功能，而是先修复 Harness 治理面，使 driver 和 stop hook 能重新进入稳定运行状态。
-
-约束：
-1. 优先读取 AGENTS.md、docs/harness/governance-auto-repair.md、docs/harness/rule-governance.md、.codex/rules/agents.md。
-2. 只修与当前治理失败直接相关的 runtime/docs/template/package-assets 面。
-3. 业务实现不是当前目标，除非治理修复明确要求一起同步。
-4. 修复完成后重新运行 verify / doctor，再决定是否恢复原目标。
-```
-
-### 适合的跟进消息
-
-```text
-优先恢复治理面，不继续业务功能。只处理当前 stop hook / verify 报出的直接问题。
-```
-
-## 11. 模板 07：人工旁路保守模式
-
-### 适用场景
-
-- 人工希望介入更多
-- 不希望系统自由选择太多 repair 动作
-- 高风险上线前夕
-
-### 启动模板
-
-```text
-持续推进当前 Harness 项目，但进入人工旁路保守模式。
-
-规则：
-1. 只推进 task.json 中已经 runnable 的任务。
-2. 遇到同一 blocker 或 triage 分类不清时，立即停下请求人工确认。
-3. 不自行扩大范围，不自行改写目标，不自行新增 repair 分支。
-4. 每轮仅报告：当前任务、最近验证、failure-triage 分类、是否建议继续。
-```
-
-### 适合的跟进消息
-
-```text
-进入人工旁路模式：遇到需要策略判断的地方，不要自己选，直接停下问我。
-```
-
-## 12. 这些模板和 spec / task.json 的区别
-
-这是最容易混淆的一点：
-
-### spec / truth source 是“内容层”
-
-定义：
-
-- 业务目标
-- 验收
-- 约束
-- 风险
-
-### `task.json` 是“执行层”
-
-定义：
-
-- 任务顺序
-- 依赖
-- owned paths
-- test_command
-
-### `/goal` 模板是“控制层”
-
-定义：
-
-- 如何持续推进
-- 什么时候停
-- 什么时候保守
-- 遇到失败怎么先归因
-
-所以这里的模板库价值不在“重复写需求”，而在：
-
-- 减少使用 `/goal` 时的外层控制失误
-- 保证 `/goal` 不压过 Harness driver
-
-## 13. 推荐命名
-
-如果后续继续扩充，建议把这一类文案统一叫：
-
-- `goal launch profiles`
-- `goal control templates`
-
-不要叫：
-
-- feature goal specs
-- long-running task specs
-
-因为它们不是在定义业务目标本身。
-
-## 14. 推荐下一步
-
-如果后面还要继续完善，最值得补的不是“更多空泛模板”，而是：
-
-1. 基于真实 Harness 场景补更多 launch profiles。
-2. 补一个“如何从 stop hook / failed trace 自动挑选合适 goal 模板”的决策表。
-3. 如果未来 `user` 安装层正式支持 `/goal`，再把这套模板库明确挂到 user 模式文档里。