@pzy560117/codex-harness 0.1.4 → 0.1.5

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

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## 作用范围
+
+- 本文件适用于 `docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/`。
+- 进入子目录后，继续读取该子目录自己的 `AGENTS.md`。
+
+## 目录作用
+
+- 这里是 `docs/codex-harness-engineering/*` 的 package-assets 文档镜像层。
+- 主要用于随安装包或镜像分发附带说明文档，不是默认第一 canonical。
+
+## 结构索引
+
+- 根目录 `*.md`：工程说明、使用文档、模式说明和方法论文档的镜像。
+- `examples/`：示例工程镜像。
+- `templates/`：模板文档镜像，不是模板源本体。
+
+## 修改规则
+
+- 默认先改上游 canonical：
+  - 方法论文档：`docs/codex-harness-engineering/*`
+  - 模板源：`docs/codex-harness-engineering/templates/*`
+- 只有在确认当前文件只存在镜像层，或本次任务就是修复 package-assets 分发面时，才先改这里。
+- 不要把这层镜像误当成安装模板源。

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

@@ -0,0 +1,198 @@
+# Codex Harness Engineering 最佳实践包
+
+**日期**: 2026-04-16  
+**适用环境**: Windows + PowerShell + Codex CLI + Git 仓库  
+**目标**: 把 Codex 从一次性对话工具升级为可复用、可审计、可验证的自动化工程执行系统。
+
+## 0. 从哪里开始
+
+如果这是你第一次进入这个目录，先读 `START-HERE.md`，再读 `mode-matrix.md` 理解当前唯一保留的 `full` driver-first 主链路。
+
+## 1. 当前范围
+
+这套文档和模板当前只保留单工作区、单 driver 的执行模型：
+
+```text
+task.json
+  -> tools/harness/codex-loop.ps1
+  -> codex exec
+  -> lint/build/test/eval
+  -> progress.txt + trace.json
+  -> task.json passes=true
+  -> git commit
+```
+
+额外 Git 执行工作区、外部 worker 编排、控制面状态机和相关模板已经从当前包中移除。
+
+## 2. 主要内容
+
+| 文件 | 用途 |
+| --- | --- |
+| `README.md` | 当前目录总览 |
+| `START-HERE.md` | 首次进入目录时的分流入口 |
+| `mode-matrix.md` | `user/project/vendor/full` 的职责边界、状态源、持续运行定位和验证入口 |
+| `best-practices.md` | 任务、上下文、权限、测试、阻塞、提交、回归沉淀的最佳实践 |
+| `implementation-flow.md` | 从 当前仓库包根结构出发说明安装、bootstrap、driver、验证、知识归档和同步的整体实现流程 |
+| `goal-harness-integration-guide.md` | 说明如何把 Codex `/goal` 与 Harness driver/stop hook 结合使用，包含推荐用法和提示词模板 |
+| `harness-analysis-and-practice.md` | GitHub 调研后的 Harness 工程分析、当前安装包工程评估和改进路线图 |
+| `harness-quality-model.md` | 定义好的、好用的、完整的 Harness 工程质量模型、成熟度和评分标准 |
+| `harness-improvement-plan.md` | 基于质量模型和源码审计的 Harness 改进计划，说明每项改哪里、怎么改、如何验收 |
+| `implementation-guide.md` | 在当前 Windows + Codex CLI 工程中落地的步骤 |
+| `global-rules-and-bootstrap.md` | 全局规则写法、新项目接入和新环境初始化教程 |
+| `codex-global-rules-example.md` | `~/.codex/AGENTS.md` 和 `~/.codex/config.toml` 的推荐配置示例与分层边界 |
+| `knowledge-surface-map.md` | 把 AGENTS、`.codex/*`、`docs/ai/*`、`docs/harness/*`、`docs/knowledge/*`、MCP 和个人知识库边界一次讲清 |
+| `agent-ecosystem-practices.md` | 分析大型项目 AI 编程生态实践，说明哪些内容应吸收到 当前仓库包根、模板、skills、hooks 和 MCP 配置 |
+| `spec-to-ui-to-code-workflow.md` | 从需求、设计、前端、契约到回归的前端先行闭环 |
+| `templates/docs/frontend-quality-rules.md` | 前端审美、动效、响应式、可访问性、性能和证据要求 |
+| `templates/docs/directory-structure-template.md` | 目录结构、文件放置、禁止目录名和业务域组织模板 |
+| `templates/docs/code-style-and-naming.md` | 业务词典、文件命名、函数命名和类型命名边界模板 |
+| `templates/docs/service-dependency-matrix.md` | 多服务、多仓库、契约和外部系统影响面的可选 truth source 维护口径 |
+| `templates/spec/10-data-model.md` | 数据模型、迁移、历史数据兼容和回滚模板 |
+| `templates/testing/test-report.md` | 需求对照、修改文件清单、测试结果和回滚方式的验收报告模板 |
+| `templates/design/frontend-architecture.md` | 前端页面、feature、组件、状态、API、响应式和测试边界模板 |
+| `examples/goal-templates.md` | `/goal` 启动模板库，强调它是外层控制壳而不是替代 `task.json` / spec 的目标定义 |
+| `templates/` | 可复制模板集中目录 |
+| `templates/docs/project-agents-template.md` | 根据不同项目事实生成项目根 `AGENTS.md` / 子目录 `AGENTS.md` / `CLAUDE.md` 组合的通用模板 |
+
+## 3. 快速使用方式
+
+1. 先读 `START-HERE.md`。
+2. 再读 `global-rules-and-bootstrap.md` 和 `codex-global-rules-example.md`。
+3. 读 `codex-host-runtime-and-autoload.md`，并对照 `../../harness-analysis/11-codex-autoload-governance-playbook.md` 确认自动加载面和治理 gate。
+4. 读 `knowledge-surface-map.md`，确认知识分层、导航层和外部知识边界。
+5. 读 `mode-matrix.md`，确认当前项目使用 full driver-first 主链路。
+6. 运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\codex-harness-engineering\templates\bootstrap-codex-harness.ps1 -ProjectRoot .
+```
+
+7. 如果这是一个刚初始化的全新仓库，先提交一次 bootstrap 基线，避免 driver 因未解释改动直接阻塞。
+8. 如果需要把根 `AGENTS.md` 调整为项目专属规则，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成，不要原样套模板。
+9. 先补齐 `docs/ai/repo-map.md`、`docs/ai/architecture-brief.md`、`docs/ai/CURRENT_TASK.md`；复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`。
+10. 如果某个目录有独立模块职责、技术栈、入口、测试命令或边界规则，优先新增或裁剪该目录下的 `AGENTS.md`，不要把目录级架构细节继续堆进根入口。
+11. 首次接入时，建议先用 `templates/runtime/smoke-task.json` 验证主链路；一旦 spec / plan 确认，就改用 `templates/runtime/project-task-template.json` 生成正式 `task.json` 并切回 driver。
+12. 正式任务队列落盘前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/ACCEPTANCE_EXAMPLES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/verify-matrix.md` 等测试左移真相源。
+13. 如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 `docs/testing/e2e-plan.md`，并先从 `docs/ai/repo-map.md` 进入代码结构后再做实现规划。
+14. 如果需要查外部文档、代码语义或本地知识库，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`。
+15. 运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1
+```
+
+## 3.1 内容门禁怎么用
+
+默认安装后的项目使用三档内容门禁：
+
+- `core`：默认档位，只阻塞最小闭环门禁：`spec / context / session / architecture / testing / impact`
+- `recommended`：在 `core` 基础上，再启用目录、命名、组件复用、业务规则、状态、UI、性能、文档和验收门禁
+- `full`：启用全部默认门禁；只建议对治理要求很高的项目使用
+
+高风险专项门禁通过任务级 `risk_tags` 启用，例如：
+
+- `security`
+- `backend`
+- `data`
+- `integration`
+- `mobile`
+- `config`
+- `observability`
+- `refactor`
+
+最常见的 3 种用法：
+
+1. 保持默认轻量：
+
+```json
+{
+  "runtime": {
+    "content_gates": {
+      "default_mode": "core"
+    }
+  }
+}
+```
+
+2. 整个项目默认更严格：
+
+```json
+{
+  "runtime": {
+    "content_gates": {
+      "default_mode": "recommended"
+    }
+  }
+}
+```
+
+3. 只给单个高风险任务加专项门禁：
+
+```json
+{
+  "id": "API-001",
+  "task_kind": "feature_impl",
+  "risk_tags": ["security", "integration"],
+  "content_gate_mode": "core"
+}
+```
+
+## 4. 推荐项目结构
+
+```text
+<project-root>/
+  AGENTS.md
+  task.json
+  progress.txt
+  tools/harness/codex-loop.ps1
+  .codex/
+    task-run-profile.json
+  .service-matrix/
+    dependencies.yaml
+  docs/
+    ai/
+      repo-map.md
+      architecture-brief.md
+      CURRENT_TASK.md
+      PROJECT_CONTEXT.md
+      DECISIONS.md
+      API_MAP.md
+      DB_SCHEMA.md
+      KNOWN_ISSUES.md
+      CHANGELOG_AI.md
+    harness/
+      architecture.md
+      code-semantics-and-navigation.md
+      frontend-quality-rules.md
+      code-style-and-naming.md
+      mcp-knowledge-governance.md
+      service-dependency-matrix.md
+      new-project-usage.md
+      regression-rules.md
+      sandbox-policy.md
+      task-session-strategy.md
+      trace-format.md
+    testing/
+      ACCEPTANCE_CRITERIA.md
+      ACCEPTANCE_EXAMPLES.md
+      TEST_STRATEGY.md
+      TRACEABILITY_MATRIX.md
+      RISK_BASED_TEST_PLAN.md
+      REGRESSION_PLAN.md
+      EVIDENCE_PROTOCOL.md
+      TEST_DATA_MATRIX.md
+      test-matrix.md
+      verify-matrix.md
+  traces/
+    <task-id>-<timestamp>.json
+```
+
+## 5. 参考资料
+
+- OpenAI Codex CLI: https://developers.openai.com/codex/cli
+- OpenAI Codex non-interactive mode: https://developers.openai.com/codex/noninteractive
+- OpenAI Codex AGENTS.md: https://developers.openai.com/codex/guides/agents-md
+- OpenAI Codex MCP: https://developers.openai.com/codex/mcp
+- OpenAI Codex hooks: https://developers.openai.com/codex/hooks
+- OpenAI Codex GitHub Action: https://developers.openai.com/codex/github-action
+- OpenAI Harness Engineering: https://openai.com/index/harness-engineering/

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/START-HERE.md

@@ -0,0 +1,66 @@
+# Codex Harness Engineering Start Here
+
+这份文档只做一件事：
+
+- 帮第一次进入 `codex-harness-engineering/` 的人快速判断应该先读什么、先做什么。
+
+## 路线 A：先理解方法论
+
+推荐阅读顺序：
+
+1. `README.md`
+2. `mode-matrix.md`
+3. `codex-host-runtime-and-autoload.md`
+4. `knowledge-surface-map.md`
+5. `global-rules-and-bootstrap.md`
+6. `implementation-guide.md`
+
+## 路线 B：把 Harness 接到一个新项目
+
+推荐阅读顺序：
+
+1. `README.md`
+2. `mode-matrix.md`
+3. `codex-host-runtime-and-autoload.md`
+4. `knowledge-surface-map.md`
+5. `global-rules-and-bootstrap.md`
+6. `implementation-guide.md`
+
+建议执行顺序：
+
+1. 确认目标目录本身是 Git 仓库。
+2. 运行 `templates/bootstrap-codex-harness.ps1`。
+3. 如果这是全新仓库，先提交一次 bootstrap 基线。
+4. 先裁剪 `docs/ai/repo-map.md` 和 `docs/ai/architecture-brief.md`，让 Agent 能准确导航目标项目。
+5. 再补 `docs/ai/CURRENT_TASK.md`；复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`。
+6. 如果项目已有明确业务词典、文件命名或类型后缀约束，补齐 `docs/harness/code-style-and-naming.md`，不要只靠口头约定。
+7. 需要项目专属 `AGENTS.md` 时，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成；根 `AGENTS.md` 只保留全局入口规则，目录独有的模块职责、边界和禁止事项优先写进子目录 `AGENTS.md`。
+8. 先使用 `templates/runtime/smoke-task.json` 做首次自检。
+9. 补齐 `docs/testing/ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md` 等实现前 testing truth source。
+10. 如果要接外部知识、MCP 或代码语义工具，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`。
+11. 通过后再替换为真实业务 `task.json`。
+
+## 路线 C：给现有项目补自动化
+
+推荐阅读顺序：
+
+1. `README.md`
+2. `mode-matrix.md`
+3. `codex-host-runtime-and-autoload.md`
+4. `knowledge-surface-map.md`
+5. `global-rules-and-bootstrap.md`
+6. `implementation-guide.md`
+
+## 最短路径
+
+1. 读 `README.md`
+2. 读 `mode-matrix.md`
+3. 读 `codex-host-runtime-and-autoload.md`
+4. 读 `knowledge-surface-map.md`
+5. 跑 `templates/bootstrap-codex-harness.ps1`
+6. 提交 bootstrap 基线
+7. 裁剪 `docs/ai/repo-map.md`
+8. 补 `docs/ai/CURRENT_TASK.md`
+9. 需要目录级架构规则时，优先给关键目录补子目录 `AGENTS.md`
+10. 用 `templates/runtime/smoke-task.json` 跑一次 smoke
+11. 补 testing truth source，再进入 `implementation-guide.md`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/agent-ecosystem-practices.md

@@ -0,0 +1,140 @@
+# Agent 生态实践吸收建议
+
+本文分析一组关于大型项目中使用 AI 编程工具的实践材料，并说明哪些内容适合吸收到 当前仓库包根，哪些应该保持为项目本地配置或后续扩展。
+
+核心判断：决定效果的不是单个模型，而是围绕模型建立的可导航、可验证、可分发、可复盘的工程环境。对本仓库来说，当前仓库包根就是这套环境的分发载体。
+
+## 可吸收内容总览
+
+| 来源思想 | 在 `agent/` 中的落点 | 吸收方式 |
+| --- | --- | --- |
+| 根入口规则保持短小 | `templates/runtime/AGENTS.md`、`templates/docs/project-agents-template.md` | 强化短入口、深文档索引、子目录规则分层 |
+| 子目录级规则按需加载 | `templates/docs/project-agents-template.md` | 只在目录规则明显不同的模块生成子目录 `AGENTS.md` |
+| 代码地图提升检索效率 | `templates/context/repo-map.md`、`update-codemaps` skill | 把 repo map / codemap 作为 AI 导航索引维护 |
+| 技能承载固定流程 | `skills/*`、`templates/package-assets/skills/*` | 将安全审查、文档同步、代码地图更新等流程沉淀为 skill |
+| Hooks 做自动化一致行为 | `templates/hooks/*` | 保持为增强层，用于 stop-gate、反馈门禁、会话复盘触发 |
+| 插件 / 包做团队分发 | `agent/` package assets | 通过 package mirrors 分发 rules、skills、prompts、hooks、docs |
+| MCP 连接外部系统 | `templates/config/mcp-config.toml`、接入文档 | 只放非敏感模板，真实服务和密钥留在项目配置或环境变量 |
+| LSP 提升代码导航 | `global-rules-and-bootstrap.md`、环境检查建议 | 作为环境建议，不把具体语言服务器写成所有项目硬约束 |
+| 定期规则治理 | `rule-governance.md`、`best-practices.md` | 3-6 个月或模型升级后清理过时规则 |
+
+## 1. 入口规则分层
+
+材料中强调不要把所有知识都塞进 `CLAUDE.md`。在 Codex / AGENTS 体系里，同样适用：
+
+- 全局 `~/.codex/AGENTS.md` 只放跨项目稳定习惯。
+- 项目根 `AGENTS.md` 只放每次会话必须知道的项目规则、真实入口和深文档索引。
+- 子目录 `AGENTS.md` 只在 monorepo、支付、权限、数据迁移等目录约束明显不同的地方添加。
+- 具体流程、长模板、复盘经验应下沉到 `docs/`、`.codex/rules/`、`.codex/prompts/` 或 skill。
+
+不建议吸收到根入口的内容：
+
+- 某个团队的口头偏好。
+- 已经能由 lint、schema、verify、hook 检查的长规则。
+- 只对单个模块成立的细节。
+
+## 2. 代码地图作为 AI 导航索引
+
+大型代码库中，AI 最大的浪费通常发生在“找错地方”和“全仓扫描”。因此 当前仓库包根应把 repo map / codemap 当成一等公民。
+
+推荐结构：
+
+```text
+AGENTS.md
+docs/ai/repo-map.md
+docs/ai/architecture-brief.md
+docs/architecture/constraints.md
+docs/harness/*
+docs/testing/*
+```
+
+根 `AGENTS.md` 应明确说明：需要理解代码结构时，先读 `docs/ai/repo-map.md` 或项目声明的同类文件，再进入具体模块；进入具有子目录 `AGENTS.md` 的模块后，必须同时遵守根规则和本地规则。
+
+代码地图应该记录：
+
+- 项目目标和主要业务域。
+- 关键目录职责。
+- 模块入口和真实 truth source。
+- 生成代码、外部系统、敏感目录和禁改区。
+- 常用验证命令。
+- 最近更新时间和维护责任。
+
+不应记录：
+
+- 大段源码解释。
+- 每个函数的实现细节。
+- 会频繁变化但没有维护机制的临时路径。
+
+## 3. 技能沉淀固定流程
+
+材料中“技能按需加载”的思想已符合当前 `docs/codex-harness-engineering/templates/package-assets/skills/*` 设计。适合继续吸收的方向：
+
+- 把重复的工作流沉淀成 skill，例如 code review、API contract、E2E planning、codemap 更新、文档同步。
+- skill 描述必须写清触发场景，避免每次会话都加载。
+- skill 内部要给确定性步骤、输入输出、验证方式和可复用脚本。
+- 专家知识优先放 skill，不放根 `AGENTS.md`。
+
+判断是否应创建 skill：
+
+| 条件 | 处理 |
+| --- | --- |
+| 多个项目复用同一流程 | 创建或更新 skill |
+| 只影响当前项目一次 | 放任务文档或 `docs/knowledge/` |
+| 可以脚本化 | skill 调用脚本，不重复写大段命令 |
+| 必须所有会话知道 | 才升级为 `AGENTS.md` 入口规则 |
+
+## 4. Hooks 的边界
+
+材料中提到 hooks 可用于格式化、检查和会话学习。对当前 Windows + PowerShell driver-first harness，边界应更保守：
+
+- hooks 可以作为增强层，例如 stop-gate、feedback-gate、格式检查提醒、复盘入口。
+- 不把 hooks 当主链路；任务选择、验证、trace、commit 仍由 `tools/harness/codex-loop.ps1` 负责。
+- 会话复盘不应每轮都写知识库，建议按轮次、失败类型或人工确认触发，避免低质量经验污染规则。
+- hook 产生的新知识先进入 `docs/knowledge/` 或 review queue，经治理后再升级为规则、prompt 或 skill。
+
+## 5. 包和插件分发
+
+材料中“插件像私有包一样分发能力”的思想，在本仓库对应 `agent/` package：
+
+- `.codex/rules/*` 分发角色和阶段规则。
+- `.codex/prompts/*` 分发 driver 注入提示。
+- `skills/*` 分发可复用流程。
+- `templates/hooks/*` 分发增强 hooks。
+- `docs/codex-harness-engineering/*` 分发人类可读方法论。
+
+新增或更新这些能力时，必须按同步矩阵刷新 package mirrors，避免只改活跃副本导致新项目安装不到。
+
+## 6. MCP 与外部系统
+
+MCP 适合连接工单、需求、设计、测试、知识库、监控等外部系统。`agent/` 里应吸收的是模板和边界，而不是真实配置：
+
+- 提供 `mcp-config.toml` 示例。
+- 文档说明 MCP 适合读取哪些外部 truth source。
+- 密钥、token、私有 URL、账号信息必须留在环境变量、用户配置或项目私有配置中。
+- 任务声明如果依赖外部系统，完成证据必须包含真实接入成功态和失败态，而不是 mock-only 结果。
+
+## 7. LSP 与导航工具
+
+LSP 对大型项目有明显价值，但具体语言服务器取决于项目技术栈。适合吸收为环境建议：
+
+- 新环境初始化时提示安装对应语言插件或 LSP。
+- 对 Java、TypeScript、Python、Go 等项目，在项目 `AGENTS.md` 或 README 中列出本项目推荐工具。
+- 不在全局规则里强制某个语言服务器。
+
+## 8. 定期治理
+
+模型能力、工具行为和团队工作流会变化。当前仓库包根应明确治理节奏：
+
+- 模型或 CLI 大版本升级后，检查 `AGENTS.md`、rules、prompts、skills 是否仍必要。
+- 每 3-6 个月清理一次重复、过时、已经自动化的文字规则。
+- 对失败复盘优先补测试、schema、verify 或 hook，再考虑写规则。
+- 入口规则越短，越容易长期保持有效。
+
+## 推荐落地优先级
+
+1. 先完善 `AGENTS.md` 分层、repo map 模板和 `update-codemaps` skill。
+2. 再把高频流程沉淀成 skill，避免继续增肥入口规则。
+3. 然后治理 hooks，让它们只做增强和复盘入口。
+4. 最后补 MCP、LSP、插件分发文档和环境检查。
+
+这套吸收方式可以把材料中的经验转成 当前仓库包根可分发的工程资产，同时避免把长篇知识直接塞进每次会话上下文。