# 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`。
