@pzy560117/codex-harness 0.1.0 → 0.1.1

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

@@ -0,0 +1,33 @@
+# App Knowledge Catalog
+
+本目录保存移动端和全平台 App 生产可上线相关的外挂知识候选。Codex 会话应先读本 catalog，再判断是否需要读取完整规范文件；不要把完整长文档作为默认上下文。
+
+## 查询顺序
+
+1. 当前任务涉及移动端 App、H5 / WebView、Hybrid、小程序、上架审核、支付、隐私、安全、灰度、回滚、生产发布或移动端 QA 时，先读本文件。
+2. 需要完整 Release Gate、测试矩阵或行业案例时，再读取对应规范文件。
+3. 如果当前项目已有 PRD、架构约束、测试矩阵或合规规则，以项目事实为准；本目录只作为补充检查和 checklist 来源。
+
+## 条目索引
+
+| ID | Type | Maturity | Title | Tags | Path |
+| --- | --- | --- | --- | --- | --- |
+| FRAMEWORK-APP-READINESS-001 | framework | draft | Mobile App Production Readiness Framework：移动端全平台生产可上线规范与宠物商城行业案例 | mobile-app, release-gate, qa, privacy, security, app-store, ecommerce, pet-commerce | `docs/external-knowledge/app/Mobile_App_Production_Readiness_Framework_移动端全平台生产可上线规范.md` |
+
+## 适用阶段
+
+| 阶段 | 推荐用途 |
+| --- | --- |
+| analysis | 识别平台范围、隐私合规、商店审核、支付、行业高风险边界 |
+| design | 补齐 App 生命周期、权限、离线弱网、灰度回滚、可观测性和后台治理要求 |
+| plan | 拆分 iOS、Android、H5 / WebView、小程序、服务端、后台、QA、安全和合规任务 |
+| implement | 检查生产包、SDK、权限、WebView、Deep Link、支付、数据同步等实现边界 |
+| review | 作为 Stage Review 的移动端生产可上线 checklist，但 `draft` 内容不能单独作为阻塞依据 |
+| verify | 生成 Release Gate、真机矩阵、支付/退款、隐私、安全、灰度和回滚证据清单 |
+
+## 使用边界
+
+- 本目录内容初始为 `draft`，只能作为启发和检查清单，不能覆盖当前项目 truth source。
+- 涉及法律、医疗、兽药、活体交易、跨境数据、儿童、金融等高风险事项时，必须由项目法务或合规负责人确认。
+- 宠物商城内容是行业案例，不代表所有电商 App 的默认要求；非宠物行业只复用通用移动端框架部分。
+- 后续如果拆分为独立条目，应保留本 catalog 作为长文档入口，并把可验证规则提炼成短条目。

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

@@ -0,0 +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`。