@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/docs/knowledge-import.md

@@ -1,108 +1,108 @@
-# Knowledge Import
-
-本文定义历史项目或既有项目接入 Harness 时的知识冷启动流程。目标是把散落在代码、文档、issue、review 和口头经验里的隐性知识转成 `docs/knowledge/` 的 draft 条目。
-
-## 原则
-
-- 不追求一次导入完美；冷启动条目默认 `maturity: draft`。
-- 优先提取会影响后续实现决策的知识，而不是搬运完整文档。
-- 每条知识都必须有 `source_references`，可以追溯到代码路径、文档、issue、review 或人工访谈记录。
-- 单次导入建议控制在 5-13 条高价值条目，避免知识库第一天就膨胀。
-- 导入阶段只建立候选知识，不把规则直接升级到 `AGENTS.md`。
-
-## 输入来源
-
-| 来源 | 可提取内容 |
-| --- | --- |
-| README / docs | 项目边界、运行方式、架构说明、业务流程 |
-| 代码结构 | 模块边界、核心实体、数据流、依赖关系 |
-| 测试与 CI | 验证入口、风险路径、质量门禁 |
-| issue / PR / review | 反复出现的 pitfall、约束和决策原因 |
-| trace / failure triage | 已验证失败模式和排查路径 |
-| 团队访谈 | AI 无法从代码推断的私域经验 |
-
-## 三段式导入
-
-1. `doc-collector`：收集已有文档、README、测试说明、CI、issue 或人工访谈摘要。
-2. `codebase-profiler`：扫描代码结构、技术栈、模块边界、入口命令和关键依赖。
-3. `knowledge-builder`：按 `model / decision / guideline / pitfall / process` 标准化条目，写入 `docs/knowledge/` 并更新索引。
-
-## 输出要求
-
-- `docs/knowledge/catalog.md` 增加一行摘要。
-- 新条目写入对应目录，初始 `maturity: draft`。
-- 每条条目包含 `source_references` 和 `contributors`。
-- 导入报告说明未处理来源、低置信条目和后续验证建议。
-
-## 断点恢复
-
-冷启动导入可能跨多轮扫描。导入任务应在 `docs/knowledge/import-state.json` 或导入报告中记录可恢复状态，避免中断后重复处理同一批来源。
-
-推荐最小结构：
-
-```json
-{
-  "schema_version": "1",
-  "started_at": "2026-05-12T00:00:00+08:00",
-  "updated_at": "2026-05-12T00:00:00+08:00",
-  "sources": {
-    "processed": [],
-    "pending": [],
-    "skipped": [],
-    "low_confidence": []
-  },
-  "resume_cursor": {
-    "source": "",
-    "path": "",
-    "position": ""
-  },
-  "generated_entries": [],
-  "follow_up_verification": []
-}
-```
-
-`import-state.json` 只描述导入进度，不替代知识条目的 `source_references`。如果项目不希望长期保留该文件，可在导入完成后把同等信息写入导入报告，但必须保留未处理来源和低置信候选。
-
-## 任务模板片段
-
-需要加入 `task.json` 时，可复制并按项目裁剪：
-
-```json
-{
-  "id": "KNOWLEDGE-IMPORT-001",
-  "description": "从既有代码、文档和历史记录冷启动 docs/knowledge 项目知识库",
-  "task_kind": "archive",
-  "phase": "archive",
-  "gate_profile": "lightweight",
-  "required_truth_sources": ["repo_context"],
-  "priority": 5,
-  "dependencies": ["INIT-001"],
-  "passes": false,
-  "context_files": [
-    "AGENTS.md",
-    "README.md",
-    "docs/harness/knowledge-architecture.md",
-    "docs/harness/knowledge-import.md"
-  ],
-  "owned_paths": ["docs/knowledge/"],
-  "execution": { "mode": "single" },
-  "knowledge_query_budget": {
-    "catalogs": 2,
-    "entries": 5
-  },
-  "steps": [
-    "扫描 README、docs、测试入口、CI 和核心代码结构",
-    "维护 import-state.json 或导入报告，记录 processed/pending/skipped/low_confidence 来源和 resume_cursor",
-    "提取 5-13 条高价值 draft 知识，按 model/decision/guideline/pitfall/process 分类",
-    "更新 knowledge-catalog.md 和 catalog.md",
-    "输出导入报告，列出低置信来源和后续验证建议"
-  ],
-  "test_command": "git diff --check",
-  "acceptance": [
-    "新增条目均为 draft 且带 source_references",
-    "catalog 与新增条目一致",
-    "导入状态或报告能支持断点恢复，未处理来源没有丢失",
-    "没有把冷启动条目直接升级为 AGENTS.md 规则"
-  ]
-}
-```
+# Knowledge Import
+
+本文定义历史项目或既有项目接入 Harness 时的知识冷启动流程。目标是把散落在代码、文档、issue、review 和口头经验里的隐性知识转成 `docs/knowledge/` 的 draft 条目。
+
+## 原则
+
+- 不追求一次导入完美；冷启动条目默认 `maturity: draft`。
+- 优先提取会影响后续实现决策的知识，而不是搬运完整文档。
+- 每条知识都必须有 `source_references`，可以追溯到代码路径、文档、issue、review 或人工访谈记录。
+- 单次导入建议控制在 5-13 条高价值条目，避免知识库第一天就膨胀。
+- 导入阶段只建立候选知识，不把规则直接升级到 `AGENTS.md`。
+
+## 输入来源
+
+| 来源 | 可提取内容 |
+| --- | --- |
+| README / docs | 项目边界、运行方式、架构说明、业务流程 |
+| 代码结构 | 模块边界、核心实体、数据流、依赖关系 |
+| 测试与 CI | 验证入口、风险路径、质量门禁 |
+| issue / PR / review | 反复出现的 pitfall、约束和决策原因 |
+| trace / failure triage | 已验证失败模式和排查路径 |
+| 团队访谈 | AI 无法从代码推断的私域经验 |
+
+## 三段式导入
+
+1. `doc-collector`：收集已有文档、README、测试说明、CI、issue 或人工访谈摘要。
+2. `codebase-profiler`：扫描代码结构、技术栈、模块边界、入口命令和关键依赖。
+3. `knowledge-builder`：按 `model / decision / guideline / pitfall / process` 标准化条目，写入 `docs/knowledge/` 并更新索引。
+
+## 输出要求
+
+- `docs/knowledge/catalog.md` 增加一行摘要。
+- 新条目写入对应目录，初始 `maturity: draft`。
+- 每条条目包含 `source_references` 和 `contributors`。
+- 导入报告说明未处理来源、低置信条目和后续验证建议。
+
+## 断点恢复
+
+冷启动导入可能跨多轮扫描。导入任务应在 `docs/knowledge/import-state.json` 或导入报告中记录可恢复状态，避免中断后重复处理同一批来源。
+
+推荐最小结构：
+
+```json
+{
+  "schema_version": "1",
+  "started_at": "2026-05-12T00:00:00+08:00",
+  "updated_at": "2026-05-12T00:00:00+08:00",
+  "sources": {
+    "processed": [],
+    "pending": [],
+    "skipped": [],
+    "low_confidence": []
+  },
+  "resume_cursor": {
+    "source": "",
+    "path": "",
+    "position": ""
+  },
+  "generated_entries": [],
+  "follow_up_verification": []
+}
+```
+
+`import-state.json` 只描述导入进度，不替代知识条目的 `source_references`。如果项目不希望长期保留该文件，可在导入完成后把同等信息写入导入报告，但必须保留未处理来源和低置信候选。
+
+## 任务模板片段
+
+需要加入 `task.json` 时，可复制并按项目裁剪：
+
+```json
+{
+  "id": "KNOWLEDGE-IMPORT-001",
+  "description": "从既有代码、文档和历史记录冷启动 docs/knowledge 项目知识库",
+  "task_kind": "archive",
+  "phase": "archive",
+  "gate_profile": "lightweight",
+  "required_truth_sources": ["repo_context"],
+  "priority": 5,
+  "dependencies": ["INIT-001"],
+  "passes": false,
+  "context_files": [
+    "AGENTS.md",
+    "README.md",
+    "docs/harness/knowledge-architecture.md",
+    "docs/harness/knowledge-import.md"
+  ],
+  "owned_paths": ["docs/knowledge/"],
+  "execution": { "mode": "single" },
+  "knowledge_query_budget": {
+    "catalogs": 2,
+    "entries": 5
+  },
+  "steps": [
+    "扫描 README、docs、测试入口、CI 和核心代码结构",
+    "维护 import-state.json 或导入报告，记录 processed/pending/skipped/low_confidence 来源和 resume_cursor",
+    "提取 5-13 条高价值 draft 知识，按 model/decision/guideline/pitfall/process 分类",
+    "更新 knowledge-catalog.md 和 catalog.md",
+    "输出导入报告，列出低置信来源和后续验证建议"
+  ],
+  "test_command": "git diff --check",
+  "acceptance": [
+    "新增条目均为 draft 且带 source_references",
+    "catalog 与新增条目一致",
+    "导入状态或报告能支持断点恢复，未处理来源没有丢失",
+    "没有把冷启动条目直接升级为 AGENTS.md 规则"
+  ]
+}
+```

package/package-source/docs/codex-harness-engineering/templates/docs/knowledge-lint.md

@@ -1,98 +1,98 @@
-# Knowledge Lint
-
-本文定义 `docs/knowledge/` 的健康检查规则。目标是让知识库保持可检索、可追踪、不过期，而不是只进不出。
-
-## 触发时机
-
-- 每完成 10 个 driver 任务后建议运行一次。
-- 连续 30 天未运行 knowledge lint 时，下次 `ARCHIVE-*` 或项目维护任务应提醒补跑。
-- 每次较大 harness、规则、prompt 或模板改造后运行一次。
-- `ARCHIVE-*` 发现重复、矛盾、长期未引用条目时运行一次。
-- 手动维护知识库前后运行一次。
-
-## 检查项
-
-| 检查 | 规则 | 处理 |
-| --- | --- | --- |
-| 索引一致 | `knowledge-catalog.md`、`catalog.md` 必须覆盖实际条目 | 修复索引 |
-| 孤儿条目 | 条目不在任何 catalog 中出现 | 加入索引或移入 archive |
-| 路径失效 | catalog 指向不存在文件 | 修复路径或删除索引行 |
-| 重复条目 | 标题、tags、source_references 高度重叠 | 标记 merge candidate |
-| 矛盾条目 | 同主题出现相反指导 | 标记 conflict candidate |
-| 长期未引用 | `last_referenced` 为空或超过衰减窗口 | 标记 decay candidate |
-| 成熟度越权 | 单次来源直接为 `proven` | 降级并补 evidence |
-| 团队同步候选 | verified/proven 条目具备跨项目价值 | 输出 team sync candidate |
-| 团队冲突候选 | 项目事实与团队知识相反 | 输出 team conflict candidate |
-| frontmatter 缺失 | 缺少 `id/type/maturity/tags/applicable_phases/source_references` | 补齐元数据 |
-
-## 最小执行流程
-
-1. 读取 `docs/harness/knowledge-architecture.md`。
-2. 枚举 `docs/knowledge/` 下除 `archive/` 外的条目。
-3. 对照 `docs/knowledge/catalog.md` 检查索引完整性。
-4. 检查每条 frontmatter、路径、成熟度和引用信息。
-5. 输出 lint report，列出 `fix_now`、`promotion_candidates`、`decay_candidates`、`conflict_candidates`、`merge_candidates`、`team_sync_candidates`。
-6. 只自动修复索引、路径和明显元数据缺口；成熟度提升、冲突裁决、团队知识合并和删除归档必须保留人工确认或独立任务证据。
-
-## 报告格式
-
-```markdown
-# Knowledge Lint Report
-
-## Summary
-- Entries scanned:
-- Catalog mismatches:
-- Fixes applied:
-- Candidates:
-
-## Fix Now
-- ...
-
-## Promotion Candidates
-- ...
-
-## Decay Candidates
-- ...
-
-## Conflict Candidates
-- ...
-
-## Merge Candidates
-- ...
-
-## Team Sync Candidates
-- ...
-```
-
-## 任务模板片段
-
-需要加入 `task.json` 时，可复制并按项目裁剪：
-
-```json
-{
-  "id": "KNOWLEDGE-LINT-001",
-  "description": "检查 docs/knowledge 索引、重复、冲突、成熟度和长期未引用条目",
-  "task_kind": "archive",
-  "phase": "archive",
-  "gate_profile": "lightweight",
-  "required_truth_sources": ["knowledge"],
-  "priority": 95,
-  "dependencies": ["ARCHIVE-001"],
-  "passes": false,
-  "context_files": [
-    "docs/harness/knowledge-architecture.md",
-    "docs/harness/knowledge-lint.md",
-    "docs/harness/team-knowledge-sync.md",
-    "docs/knowledge/knowledge-catalog.md",
-    "docs/knowledge/catalog.md"
-  ],
-  "owned_paths": ["docs/knowledge/"],
-  "execution": { "mode": "single" },
-  "test_command": "git diff --check",
-  "acceptance": [
-    "输出 knowledge lint report",
-    "catalog 与实际条目一致",
-    "成熟度、冲突、团队同步和衰减只产出候选，不静默越权处理"
-  ]
-}
-```
+# Knowledge Lint
+
+本文定义 `docs/knowledge/` 的健康检查规则。目标是让知识库保持可检索、可追踪、不过期，而不是只进不出。
+
+## 触发时机
+
+- 每完成 10 个 driver 任务后建议运行一次。
+- 连续 30 天未运行 knowledge lint 时，下次 `ARCHIVE-*` 或项目维护任务应提醒补跑。
+- 每次较大 harness、规则、prompt 或模板改造后运行一次。
+- `ARCHIVE-*` 发现重复、矛盾、长期未引用条目时运行一次。
+- 手动维护知识库前后运行一次。
+
+## 检查项
+
+| 检查 | 规则 | 处理 |
+| --- | --- | --- |
+| 索引一致 | `knowledge-catalog.md`、`catalog.md` 必须覆盖实际条目 | 修复索引 |
+| 孤儿条目 | 条目不在任何 catalog 中出现 | 加入索引或移入 archive |
+| 路径失效 | catalog 指向不存在文件 | 修复路径或删除索引行 |
+| 重复条目 | 标题、tags、source_references 高度重叠 | 标记 merge candidate |
+| 矛盾条目 | 同主题出现相反指导 | 标记 conflict candidate |
+| 长期未引用 | `last_referenced` 为空或超过衰减窗口 | 标记 decay candidate |
+| 成熟度越权 | 单次来源直接为 `proven` | 降级并补 evidence |
+| 团队同步候选 | verified/proven 条目具备跨项目价值 | 输出 team sync candidate |
+| 团队冲突候选 | 项目事实与团队知识相反 | 输出 team conflict candidate |
+| frontmatter 缺失 | 缺少 `id/type/maturity/tags/applicable_phases/source_references` | 补齐元数据 |
+
+## 最小执行流程
+
+1. 读取 `docs/harness/knowledge-architecture.md`。
+2. 枚举 `docs/knowledge/` 下除 `archive/` 外的条目。
+3. 对照 `docs/knowledge/catalog.md` 检查索引完整性。
+4. 检查每条 frontmatter、路径、成熟度和引用信息。
+5. 输出 lint report，列出 `fix_now`、`promotion_candidates`、`decay_candidates`、`conflict_candidates`、`merge_candidates`、`team_sync_candidates`。
+6. 只自动修复索引、路径和明显元数据缺口；成熟度提升、冲突裁决、团队知识合并和删除归档必须保留人工确认或独立任务证据。
+
+## 报告格式
+
+```markdown
+# Knowledge Lint Report
+
+## Summary
+- Entries scanned:
+- Catalog mismatches:
+- Fixes applied:
+- Candidates:
+
+## Fix Now
+- ...
+
+## Promotion Candidates
+- ...
+
+## Decay Candidates
+- ...
+
+## Conflict Candidates
+- ...
+
+## Merge Candidates
+- ...
+
+## Team Sync Candidates
+- ...
+```
+
+## 任务模板片段
+
+需要加入 `task.json` 时，可复制并按项目裁剪：
+
+```json
+{
+  "id": "KNOWLEDGE-LINT-001",
+  "description": "检查 docs/knowledge 索引、重复、冲突、成熟度和长期未引用条目",
+  "task_kind": "archive",
+  "phase": "archive",
+  "gate_profile": "lightweight",
+  "required_truth_sources": ["knowledge"],
+  "priority": 95,
+  "dependencies": ["ARCHIVE-001"],
+  "passes": false,
+  "context_files": [
+    "docs/harness/knowledge-architecture.md",
+    "docs/harness/knowledge-lint.md",
+    "docs/harness/team-knowledge-sync.md",
+    "docs/knowledge/knowledge-catalog.md",
+    "docs/knowledge/catalog.md"
+  ],
+  "owned_paths": ["docs/knowledge/"],
+  "execution": { "mode": "single" },
+  "test_command": "git diff --check",
+  "acceptance": [
+    "输出 knowledge lint report",
+    "catalog 与实际条目一致",
+    "成熟度、冲突、团队同步和衰减只产出候选，不静默越权处理"
+  ]
+}
+```

package/package-source/docs/codex-harness-engineering/templates/docs/mcp-knowledge-governance.md

@@ -0,0 +1,24 @@
+# MCP 与外部知识治理
+
+本文定义项目里如何使用 MCP、搜索和外部知识源，避免把“查到的资料”误当成“已经进入项目治理的真相源”。
+
+## 目标
+
+- 先用项目内真相源回答项目内问题
+- 只在需要 freshness 或外部资料时再查 MCP
+- 把外部结论和项目沉淀分开
+
+## 默认顺序
+
+1. `AGENTS.md`
+2. `docs/ai/*`
+3. `docs/harness/*`
+4. `docs/testing/*`
+5. `docs/knowledge/*`
+6. MCP / 外部知识
+
+## 沉淀规则
+
+- 临时查询结果默认不进入规则层
+- 可复用结论先写 `docs/ai/*` 或 `docs/knowledge/*`
+- 稳定治理再升级到 `docs/harness/*`、prompt 或 rules

package/package-source/docs/codex-harness-engineering/templates/docs/new-project-checklist.md

@@ -1,7 +1,7 @@
-# 新项目接入检查清单
-
-- [ ] 已执行 `tools/install/bootstrap-codex-harness.ps1`
-- [ ] 已生成真实 `task.json`
-- [ ] 已确认 `.codex/task-run-profile.json`
-- [ ] 已提交 bootstrap 基线
-- [ ] 已验证 `tools/harness/codex-loop.ps1` 与 `tools/harness/verify.ps1`
+# 新项目接入检查清单
+
+- [ ] 已执行 `tools/install/bootstrap-codex-harness.ps1`
+- [ ] 已生成真实 `task.json`
+- [ ] 已确认 `.codex/task-run-profile.json`
+- [ ] 已提交 bootstrap 基线
+- [ ] 已验证 `tools/harness/codex-loop.ps1` 与 `tools/harness/verify.ps1`