@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/external-knowledge/architecture.md

@@ -1,358 +1,358 @@
-# AI 软件工程质量知识库项目架构
-
-本文把外挂总知识库定义为一个完整项目，而不是一组散落 Markdown。项目暂名 `team-wiki`，定位是面向 AI 编程的质量管理与软件工程知识系统。
-
-## 1. 项目定位
-
-`team-wiki` 不是泛技术百科，也不是简单文档站。它服务于 Codex、reviewer、test-runner、planner 和人类维护者，目标是解决 AI 编程中的质量痛点：
-
-- 需求没收敛就开始编码。
-- 任务拆分过大、owned paths 不清。
-- AI 编造完成状态或绕过验证。
-- 测试替身、demo、mock 冒充声明交付路径。
-- review 只看代码风格，不看需求、架构和证据。
-- release 阶段才第一次补测试范围。
-- 多 Agent 并行写冲突。
-- 经验无法复用，每个项目重复踩坑。
-- 规则、prompt、模板越写越重，缺少升级和衰减治理。
-
-第一版核心知识域必须围绕质量管理和软件工程，不优先建设 React、Django、Docker 这类技术栈百科。技术栈知识只有在它直接影响质量门禁、验证或工程治理时才进入第一版。
-
-允许按领域增加独立扩展包，但扩展包必须服务于生产准入、验证、合规、发布治理或行业风险控制。例如 `app/` 领域扩展用于移动端和全平台 App 的生产可上线检查，不作为泛移动开发教程。
-
-## 2. 产品边界
-
-### 用户角色
-
-| 角色 | 需求 |
-| --- | --- |
-| Codex 实现会话 | 在实现前读取少量高相关质量规则和历史坑 |
-| Planner / Architect | 拆任务、定义架构约束、设计验证闭环 |
-| Stage Reviewer | 根据成熟知识检查需求、架构、验证和风险 |
-| Test Runner | 选择 affected tests、识别假验证和环境坑 |
-| Maintainer | 审批知识晋级、冲突裁决、规则升级 |
-| 新项目接入者 | 快速获得 AI 编程质量基线和项目画像模板 |
-
-### 非目标
-
-- 不做完整技术百科。
-- 不复制 GitHub 项目的 Wiki、README 或代码。
-- 不替代当前项目 PRD、架构约束、测试矩阵。
-- 不让外部知识库成为 driver 的硬依赖。
-- 不让 Codex 静默把 `draft` 知识升级为 `proven`。
-
-## 3. 系统模块
-
-```text
-team-wiki/
-  content/             # 知识源文件，Git + Markdown
-  catalogs/            # 汇总索引和 Agent 查询入口
-  schemas/             # frontmatter 和配置 schema
-  scripts/             # lint、resolve、export、index
-  contributions/       # Codex 或项目导出的 pending/conflict 候选
-  reports/             # lint、sync、promotion、decay 报告
-  docs/                # 使用说明和治理协议
-```
-
-模块职责：
-
-| 模块 | 职责 |
-| --- | --- |
-| Content Store | 保存知识条目，是唯一事实源 |
-| Catalog Index | 给人和 Agent 提供低成本查询入口 |
-| Source Resolver | 读取项目 `.knowledge-sources.yml`，解析外挂知识路径 |
-| Lint Engine | 检查 frontmatter、catalog、重复、冲突、成熟度越权 |
-| Sync Engine | 从项目 `docs/knowledge/` 导出团队候选 |
-| Promotion Workflow | 维护 draft/verified/proven 晋级和衰减 |
-| Retrieval Adapter | 第一阶段用 catalog；后续可接 RAG，但 RAG 不做事实源 |
-
-## 4. 知识域架构
-
-第一版目录按 AI 编程质量问题组织：
-
-```text
-team-wiki/
-  README.md
-  knowledge-catalog.md
-  .knowledge-config.yaml
-  log.md
-  quality-management/
-    catalog.md
-    requirements-quality/
-    verification-engineering/
-    review-gates/
-    risk-management/
-  software-engineering/
-    catalog.md
-    task-decomposition/
-    architecture-constraints/
-    integration-quality/
-    change-management/
-  agent-engineering/
-    catalog.md
-    workflow-control/
-    prompt-and-rule-governance/
-    multi-agent-coordination/
-    knowledge-governance/
-  app/
-    catalog.md
-    production-readiness/
-  project-profiles/
-    catalog.md
-  contributions/
-    pending/
-    conflicts/
-  reports/
-  archive/
-  schemas/
-  scripts/
-```
-
-### 质量管理域
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `requirements-quality/` | 需求可测试性、验收标准、Requirement ID、追溯矩阵 |
-| `verification-engineering/` | affected tests、fresh evidence、失败态证据、假验证 |
-| `review-gates/` | Stage 1/2 分工、finding 格式、repair queue |
-| `risk-management/` | 外部依赖、安全、权限、数据、部署风险 |
-
-### 软件工程域
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `task-decomposition/` | task.json 拆分、owned paths、dependencies、单任务闭环 |
-| `architecture-constraints/` | 交付形态、公开入口、数据边界、异步边界、禁止伪实现 |
-| `integration-quality/` | contract first、真实依赖、mock 切真实接口、联调证据 |
-| `change-management/` | 变更范围、回归、兼容性、迁移和发布收口 |
-
-### Agent 工程域
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `workflow-control/` | driver-first、truth source、BLOCKED 协议、不伪造状态 |
-| `prompt-and-rule-governance/` | AGENTS/prompt/template 的写入边界和升级条件 |
-| `multi-agent-coordination/` | 并行任务、写路径隔离、handoff、review 复验 |
-| `knowledge-governance/` | draft/verified/proven、冲突、衰减、归档、团队同步 |
-
-### App 生产可上线域
-
-`app/` 是领域扩展包，不属于第一版核心三大域的替代项。它面向移动端和全平台 App 的生产发布质量，只有在任务涉及 App、H5 / WebView、Hybrid、小程序、商店审核、支付、隐私、安全、灰度、回滚、移动端 QA 或行业专项时才按需读取。
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `production-readiness/` | iOS、Android、H5 / WebView、小程序、后台、服务端、支付、隐私、安全、商店审核、灰度、回滚和 Release Gate |
-| `industry-cases/` | 电商、宠物商城等行业案例、P0 测试用例、高风险边界和行业专项 Release Gate |
-
-## 5. 数据模型
-
-### 知识条目
-
-```yaml
-id: GUIDELINE-VERIFY-001
-type: guideline
-domain: quality-management
-subdomain: verification-engineering
-maturity: draft
-tags: [verification, ai-coding, evidence]
-applicable_phases: [plan, implement, review, verify]
-source_references:
-  - project: codex-herness
-    ref: docs/harness/regression-rules.md
-validated_projects: []
-last_referenced:
-contradictions: []
-contributors:
-  - codex
-owner:
-not_applicable_when: []
-```
-
-正文必须包含：
-
-```markdown
-# 标题
-
-## Problem
-
-## Guidance
-
-## Not Applicable When
-
-## Evidence
-```
-
-### 项目画像
-
-```yaml
-project_slug:
-domains: []
-tech_stack: []
-delivery_shape:
-quality_profile:
-  critical_paths: []
-  required_gates: []
-  verification_baseline: []
-knowledge_sources:
-  project: docs/knowledge
-  team:
-validated_rules: []
-known_conflicts: []
-```
-
-项目画像用于过滤团队知识，避免把不相关技术栈或业务域注入到当前任务。
-
-### 贡献候选
-
-```yaml
-candidate_id:
-source_project:
-source_entry:
-target_domain:
-target_subdomain:
-suggested_action: add | merge | promote | conflict | decay
-evidence:
-review_required: true
-```
-
-候选只进入 `contributions/pending/` 或 `contributions/conflicts/`，不直接改主干条目。
-
-## 6. 来源策略
-
-`team-wiki` 不是复制别人的 Wiki，而是把可授权、可追溯、可验证的来源提炼成团队自己的短条目。
-
-| 来源 | 优先级 | 用法 | 初始成熟度 |
-| --- | --- | --- | --- |
-| 团队真实项目经验 | 最高 | 从 trace、review、失败记录、事故复盘和测试缺口提炼 | `draft`，复用验证后升级 |
-| 官方文档和标准 | 高 | 摘要规则、链接来源、写明版本或适用范围 | `draft` 或 `verified` |
-| 优秀开源项目实践 | 中 | 借鉴目录、流程、测试、CI、ADR 和治理模式，不复制原文 | `draft` |
-| 公开文章和案例 | 中低 | 作为启发和候选，不作为强约束 | `draft` |
-| 人工访谈和团队约定 | 高 | 记录来源人、日期、适用项目和验证计划 | `draft` |
-
-禁止事项：
-
-- 不直接复制 GitHub 项目的 README、Wiki、文档或代码作为知识条目。
-- 不复制许可证不清晰的大段文本。
-- 不把别人项目的具体路径、命令、部署和业务规则当成通用规则。
-- 不把博客观点直接写成 `proven`。
-- 不收录 token、cookie、私钥、客户数据、内部密钥或真实敏感配置。
-
-## 7. 成熟度和治理
-
-| 成熟度 | 定义 | 使用边界 |
-| --- | --- | --- |
-| `draft` | 单项目、单任务或人工导入候选 | 只能启发分析，不能作为阻塞性 review 依据 |
-| `verified` | 至少一个真实任务引用并通过验证 | 可作为 reviewer 辅助依据 |
-| `proven` | 至少两个不同任务或项目验证，或 maintainer 审批 | 可提升为规则、模板、prompt 或默认检查 |
-
-规则：
-
-- `draft -> verified` 需要真实任务引用和验证证据。
-- `verified -> proven` 需要两个不同任务或项目证据，或 maintainer 明确审批。
-- 冲突条目保留较低成熟度，并进入 `contributions/conflicts/`。
-- 长期未引用条目进入 decay candidate，不自动删除。
-- 只有 `proven` 或用户明确要求，才考虑升级到 `AGENTS.md`、prompt、模板或脚本。
-
-## 8. 查询和接入
-
-项目根目录使用 `.knowledge-sources.yml` 声明外挂知识：
-
-```yaml
-schema_version: 1
-sources:
-  project:
-    path: docs/knowledge
-    required: true
-  team:
-    path: ../team-wiki
-    required: false
-    catalogs:
-      - knowledge-catalog.md
-      - quality-management/catalog.md
-      - software-engineering/catalog.md
-      - agent-engineering/catalog.md
-      - app/catalog.md
-query:
-  max_catalogs: 4
-  max_entries: 8
-  prefer_maturity: [proven, verified, draft]
-```
-
-Codex 查询顺序：
-
-1. 当前项目 truth source：PRD、架构约束、测试矩阵、项目 `docs/knowledge/`。
-2. `.knowledge-sources.yml` 中可用的团队 catalog。
-3. 按 domain、subdomain、tags、phase、maturity 过滤。
-4. 读取少量相关条目。
-5. 最终报告列出 `knowledge_references`，包括 `source=project|team`。
-
-外挂知识不可用时只降级 warning，不能阻塞本地实现验证。
-
-长文档接入规则：
-
-- catalog 是默认入口，完整长文档不是默认上下文。
-- 长文档必须通过 catalog 暴露摘要、适用阶段、使用边界和路径。
-- 只有任务显式命中相关平台、行业、发布或验证风险时，才读取长文档相关章节。
-- 如果长文档中的 `draft` 建议与项目 truth source 冲突，以项目事实为准，并输出 conflict candidate。
-
-## 9. 脚本和接口
-
-第一版至少需要：
-
-```text
-scripts/
-  resolve-sources.ps1        # 解析 .knowledge-sources.yml
-  lint-knowledge.ps1         # 检查条目和 catalog
-  export-team-candidates.ps1 # 从项目知识导出 pending/conflict
-  build-agent-index.ps1      # 生成给 Agent 快速读取的摘要索引
-```
-
-脚本边界：
-
-- 不自动删除知识。
-- 不静默提升为 `proven`。
-- 不修改外部仓库主干，只写 pending/conflicts/report。
-- 外挂库不可用时 exit 0 + warning，除非用户显式要求强制同步。
-
-## 10. 质量门禁
-
-项目自身必须有质量门禁：
-
-| 门禁 | 命令或检查 |
-| --- | --- |
-| Markdown 格式 | `git diff --check` |
-| Frontmatter 完整 | `lint-knowledge.ps1` |
-| Catalog 一致 | `lint-knowledge.ps1` |
-| 敏感信息扫描 | 禁止 token、cookie、私钥、客户数据 |
-| 成熟度越权 | proven 必须有多项目证据或审批 |
-| 冲突检查 | 相反指导进入 conflicts |
-
-## 11. 与 RAG 的关系
-
-第一阶段不需要向量库。满足以下条件再接 RAG：
-
-- 条目超过 300 条。
-- catalog-first 检索已经不足。
-- frontmatter、chunk、权限和引用格式稳定。
-
-RAG 只做召回层。事实来源仍是 Git 中的 Markdown 条目，最终引用必须指向 Markdown 文件。
-
-## 12. MVP 范围
-
-第一版 MVP 只做：
-
-1. `team-wiki` 仓库骨架。
-2. 三大知识域：`quality-management`、`software-engineering`、`agent-engineering`。
-3. 10-20 条 `draft` 种子知识。
-4. `.knowledge-config.yaml` 和 `knowledge-catalog.md`。
-5. `lint-knowledge.ps1` 和 `resolve-sources.ps1`。
-6. 项目侧 `.knowledge-sources.yml` 示例。
-7. Codex prompt 查询协议更新。
-
-不做：
-
-- Web UI。
-- 向量库。
-- 自动写团队知识主干。
-- 技术栈百科。
-- 自动升级 `proven`。
+# AI 软件工程质量知识库项目架构
+
+本文把外挂总知识库定义为一个完整项目，而不是一组散落 Markdown。项目暂名 `team-wiki`，定位是面向 AI 编程的质量管理与软件工程知识系统。
+
+## 1. 项目定位
+
+`team-wiki` 不是泛技术百科，也不是简单文档站。它服务于 Codex、reviewer、test-runner、planner 和人类维护者，目标是解决 AI 编程中的质量痛点：
+
+- 需求没收敛就开始编码。
+- 任务拆分过大、owned paths 不清。
+- AI 编造完成状态或绕过验证。
+- 测试替身、demo、mock 冒充声明交付路径。
+- review 只看代码风格，不看需求、架构和证据。
+- release 阶段才第一次补测试范围。
+- 多 Agent 并行写冲突。
+- 经验无法复用，每个项目重复踩坑。
+- 规则、prompt、模板越写越重，缺少升级和衰减治理。
+
+第一版核心知识域必须围绕质量管理和软件工程，不优先建设 React、Django、Docker 这类技术栈百科。技术栈知识只有在它直接影响质量门禁、验证或工程治理时才进入第一版。
+
+允许按领域增加独立扩展包，但扩展包必须服务于生产准入、验证、合规、发布治理或行业风险控制。例如 `app/` 领域扩展用于移动端和全平台 App 的生产可上线检查，不作为泛移动开发教程。
+
+## 2. 产品边界
+
+### 用户角色
+
+| 角色 | 需求 |
+| --- | --- |
+| Codex 实现会话 | 在实现前读取少量高相关质量规则和历史坑 |
+| Planner / Architect | 拆任务、定义架构约束、设计验证闭环 |
+| Stage Reviewer | 根据成熟知识检查需求、架构、验证和风险 |
+| Test Runner | 选择 affected tests、识别假验证和环境坑 |
+| Maintainer | 审批知识晋级、冲突裁决、规则升级 |
+| 新项目接入者 | 快速获得 AI 编程质量基线和项目画像模板 |
+
+### 非目标
+
+- 不做完整技术百科。
+- 不复制 GitHub 项目的 Wiki、README 或代码。
+- 不替代当前项目 PRD、架构约束、测试矩阵。
+- 不让外部知识库成为 driver 的硬依赖。
+- 不让 Codex 静默把 `draft` 知识升级为 `proven`。
+
+## 3. 系统模块
+
+```text
+team-wiki/
+  content/             # 知识源文件，Git + Markdown
+  catalogs/            # 汇总索引和 Agent 查询入口
+  schemas/             # frontmatter 和配置 schema
+  scripts/             # lint、resolve、export、index
+  contributions/       # Codex 或项目导出的 pending/conflict 候选
+  reports/             # lint、sync、promotion、decay 报告
+  docs/                # 使用说明和治理协议
+```
+
+模块职责：
+
+| 模块 | 职责 |
+| --- | --- |
+| Content Store | 保存知识条目，是唯一事实源 |
+| Catalog Index | 给人和 Agent 提供低成本查询入口 |
+| Source Resolver | 读取项目 `.knowledge-sources.yml`，解析外挂知识路径 |
+| Lint Engine | 检查 frontmatter、catalog、重复、冲突、成熟度越权 |
+| Sync Engine | 从项目 `docs/knowledge/` 导出团队候选 |
+| Promotion Workflow | 维护 draft/verified/proven 晋级和衰减 |
+| Retrieval Adapter | 第一阶段用 catalog；后续可接 RAG，但 RAG 不做事实源 |
+
+## 4. 知识域架构
+
+第一版目录按 AI 编程质量问题组织：
+
+```text
+team-wiki/
+  README.md
+  knowledge-catalog.md
+  .knowledge-config.yaml
+  log.md
+  quality-management/
+    catalog.md
+    requirements-quality/
+    verification-engineering/
+    review-gates/
+    risk-management/
+  software-engineering/
+    catalog.md
+    task-decomposition/
+    architecture-constraints/
+    integration-quality/
+    change-management/
+  agent-engineering/
+    catalog.md
+    workflow-control/
+    prompt-and-rule-governance/
+    multi-agent-coordination/
+    knowledge-governance/
+  app/
+    catalog.md
+    production-readiness/
+  project-profiles/
+    catalog.md
+  contributions/
+    pending/
+    conflicts/
+  reports/
+  archive/
+  schemas/
+  scripts/
+```
+
+### 质量管理域
+
+| 子域 | 解决的问题 |
+| --- | --- |
+| `requirements-quality/` | 需求可测试性、验收标准、Requirement ID、追溯矩阵 |
+| `verification-engineering/` | affected tests、fresh evidence、失败态证据、假验证 |
+| `review-gates/` | Stage 1/2 分工、finding 格式、repair queue |
+| `risk-management/` | 外部依赖、安全、权限、数据、部署风险 |
+
+### 软件工程域
+
+| 子域 | 解决的问题 |
+| --- | --- |
+| `task-decomposition/` | task.json 拆分、owned paths、dependencies、单任务闭环 |
+| `architecture-constraints/` | 交付形态、公开入口、数据边界、异步边界、禁止伪实现 |
+| `integration-quality/` | contract first、真实依赖、mock 切真实接口、联调证据 |
+| `change-management/` | 变更范围、回归、兼容性、迁移和发布收口 |
+
+### Agent 工程域
+
+| 子域 | 解决的问题 |
+| --- | --- |
+| `workflow-control/` | driver-first、truth source、BLOCKED 协议、不伪造状态 |
+| `prompt-and-rule-governance/` | AGENTS/prompt/template 的写入边界和升级条件 |
+| `multi-agent-coordination/` | 并行任务、写路径隔离、handoff、review 复验 |
+| `knowledge-governance/` | draft/verified/proven、冲突、衰减、归档、团队同步 |
+
+### App 生产可上线域
+
+`app/` 是领域扩展包，不属于第一版核心三大域的替代项。它面向移动端和全平台 App 的生产发布质量，只有在任务涉及 App、H5 / WebView、Hybrid、小程序、商店审核、支付、隐私、安全、灰度、回滚、移动端 QA 或行业专项时才按需读取。
+
+| 子域 | 解决的问题 |
+| --- | --- |
+| `production-readiness/` | iOS、Android、H5 / WebView、小程序、后台、服务端、支付、隐私、安全、商店审核、灰度、回滚和 Release Gate |
+| `industry-cases/` | 电商、宠物商城等行业案例、P0 测试用例、高风险边界和行业专项 Release Gate |
+
+## 5. 数据模型
+
+### 知识条目
+
+```yaml
+id: GUIDELINE-VERIFY-001
+type: guideline
+domain: quality-management
+subdomain: verification-engineering
+maturity: draft
+tags: [verification, ai-coding, evidence]
+applicable_phases: [plan, implement, review, verify]
+source_references:
+  - project: codex-herness
+    ref: docs/harness/regression-rules.md
+validated_projects: []
+last_referenced:
+contradictions: []
+contributors:
+  - codex
+owner:
+not_applicable_when: []
+```
+
+正文必须包含：
+
+```markdown
+# 标题
+
+## Problem
+
+## Guidance
+
+## Not Applicable When
+
+## Evidence
+```
+
+### 项目画像
+
+```yaml
+project_slug:
+domains: []
+tech_stack: []
+delivery_shape:
+quality_profile:
+  critical_paths: []
+  required_gates: []
+  verification_baseline: []
+knowledge_sources:
+  project: docs/knowledge
+  team:
+validated_rules: []
+known_conflicts: []
+```
+
+项目画像用于过滤团队知识，避免把不相关技术栈或业务域注入到当前任务。
+
+### 贡献候选
+
+```yaml
+candidate_id:
+source_project:
+source_entry:
+target_domain:
+target_subdomain:
+suggested_action: add | merge | promote | conflict | decay
+evidence:
+review_required: true
+```
+
+候选只进入 `contributions/pending/` 或 `contributions/conflicts/`，不直接改主干条目。
+
+## 6. 来源策略
+
+`team-wiki` 不是复制别人的 Wiki，而是把可授权、可追溯、可验证的来源提炼成团队自己的短条目。
+
+| 来源 | 优先级 | 用法 | 初始成熟度 |
+| --- | --- | --- | --- |
+| 团队真实项目经验 | 最高 | 从 trace、review、失败记录、事故复盘和测试缺口提炼 | `draft`，复用验证后升级 |
+| 官方文档和标准 | 高 | 摘要规则、链接来源、写明版本或适用范围 | `draft` 或 `verified` |
+| 优秀开源项目实践 | 中 | 借鉴目录、流程、测试、CI、ADR 和治理模式，不复制原文 | `draft` |
+| 公开文章和案例 | 中低 | 作为启发和候选，不作为强约束 | `draft` |
+| 人工访谈和团队约定 | 高 | 记录来源人、日期、适用项目和验证计划 | `draft` |
+
+禁止事项：
+
+- 不直接复制 GitHub 项目的 README、Wiki、文档或代码作为知识条目。
+- 不复制许可证不清晰的大段文本。
+- 不把别人项目的具体路径、命令、部署和业务规则当成通用规则。
+- 不把博客观点直接写成 `proven`。
+- 不收录 token、cookie、私钥、客户数据、内部密钥或真实敏感配置。
+
+## 7. 成熟度和治理
+
+| 成熟度 | 定义 | 使用边界 |
+| --- | --- | --- |
+| `draft` | 单项目、单任务或人工导入候选 | 只能启发分析，不能作为阻塞性 review 依据 |
+| `verified` | 至少一个真实任务引用并通过验证 | 可作为 reviewer 辅助依据 |
+| `proven` | 至少两个不同任务或项目验证，或 maintainer 审批 | 可提升为规则、模板、prompt 或默认检查 |
+
+规则：
+
+- `draft -> verified` 需要真实任务引用和验证证据。
+- `verified -> proven` 需要两个不同任务或项目证据，或 maintainer 明确审批。
+- 冲突条目保留较低成熟度，并进入 `contributions/conflicts/`。
+- 长期未引用条目进入 decay candidate，不自动删除。
+- 只有 `proven` 或用户明确要求，才考虑升级到 `AGENTS.md`、prompt、模板或脚本。
+
+## 8. 查询和接入
+
+项目根目录使用 `.knowledge-sources.yml` 声明外挂知识：
+
+```yaml
+schema_version: 1
+sources:
+  project:
+    path: docs/knowledge
+    required: true
+  team:
+    path: ../team-wiki
+    required: false
+    catalogs:
+      - knowledge-catalog.md
+      - quality-management/catalog.md
+      - software-engineering/catalog.md
+      - agent-engineering/catalog.md
+      - app/catalog.md
+query:
+  max_catalogs: 4
+  max_entries: 8
+  prefer_maturity: [proven, verified, draft]
+```
+
+Codex 查询顺序：
+
+1. 当前项目 truth source：PRD、架构约束、测试矩阵、项目 `docs/knowledge/`。
+2. `.knowledge-sources.yml` 中可用的团队 catalog。
+3. 按 domain、subdomain、tags、phase、maturity 过滤。
+4. 读取少量相关条目。
+5. 最终报告列出 `knowledge_references`，包括 `source=project|team`。
+
+外挂知识不可用时只降级 warning，不能阻塞本地实现验证。
+
+长文档接入规则：
+
+- catalog 是默认入口，完整长文档不是默认上下文。
+- 长文档必须通过 catalog 暴露摘要、适用阶段、使用边界和路径。
+- 只有任务显式命中相关平台、行业、发布或验证风险时，才读取长文档相关章节。
+- 如果长文档中的 `draft` 建议与项目 truth source 冲突，以项目事实为准，并输出 conflict candidate。
+
+## 9. 脚本和接口
+
+第一版至少需要：
+
+```text
+scripts/
+  resolve-sources.ps1        # 解析 .knowledge-sources.yml
+  lint-knowledge.ps1         # 检查条目和 catalog
+  export-team-candidates.ps1 # 从项目知识导出 pending/conflict
+  build-agent-index.ps1      # 生成给 Agent 快速读取的摘要索引
+```
+
+脚本边界：
+
+- 不自动删除知识。
+- 不静默提升为 `proven`。
+- 不修改外部仓库主干，只写 pending/conflicts/report。
+- 外挂库不可用时 exit 0 + warning，除非用户显式要求强制同步。
+
+## 10. 质量门禁
+
+项目自身必须有质量门禁：
+
+| 门禁 | 命令或检查 |
+| --- | --- |
+| Markdown 格式 | `git diff --check` |
+| Frontmatter 完整 | `lint-knowledge.ps1` |
+| Catalog 一致 | `lint-knowledge.ps1` |
+| 敏感信息扫描 | 禁止 token、cookie、私钥、客户数据 |
+| 成熟度越权 | proven 必须有多项目证据或审批 |
+| 冲突检查 | 相反指导进入 conflicts |
+
+## 11. 与 RAG 的关系
+
+第一阶段不需要向量库。满足以下条件再接 RAG：
+
+- 条目超过 300 条。
+- catalog-first 检索已经不足。
+- frontmatter、chunk、权限和引用格式稳定。
+
+RAG 只做召回层。事实来源仍是 Git 中的 Markdown 条目，最终引用必须指向 Markdown 文件。
+
+## 12. MVP 范围
+
+第一版 MVP 只做：
+
+1. `team-wiki` 仓库骨架。
+2. 三大知识域：`quality-management`、`software-engineering`、`agent-engineering`。
+3. 10-20 条 `draft` 种子知识。
+4. `.knowledge-config.yaml` 和 `knowledge-catalog.md`。
+5. `lint-knowledge.ps1` 和 `resolve-sources.ps1`。
+6. 项目侧 `.knowledge-sources.yml` 示例。
+7. Codex prompt 查询协议更新。
+
+不做：
+
+- Web UI。
+- 向量库。
+- 自动写团队知识主干。
+- 技术栈百科。
+- 自动升级 `proven`。