# 外挂总知识库研究

本目录研究 Codex Harness 的外挂总知识库。它不是当前项目的 `docs/knowledge/` 替代品，也不是泛技术百科，而是跨项目复用的 AI 软件工程质量知识库项目。

## 目标

- 在新项目启动前提供稳定的质量管理、软件工程和 Agent 工作流知识。
- 把多个项目沉淀出来的 verified/proven 经验提升为团队资产。
- 避免把一次性经验直接写进 `AGENTS.md`、prompt 或项目模板。
- 在外部知识不可用时，本地 driver 仍能完成实现、验证和提交。
- 优先解决 AI 编程中的需求未收敛、任务边界不清、假验证、伪实现、review 缺口和知识无法复用等痛点。

## 目录

| 文件 | 用途 |
| --- | --- |
| `architecture.md` | `team-wiki` 完整项目架构、模块、数据模型、质量门禁和同步协议 |
| `initial-content.md` | 初始必须设定好的内容类型、目录和种子条目 |
| `integration-roadmap.md` | 从文档方案到配置、脚本、任务模板和后续 RAG 的落地路线 |
| `common/catalog.md` | 通用 AI Coding 生产控制知识入口 |
| `common/AI_Coding_Production_Control_Framework_AI写完的代码如何不失控.md` | AI 生成代码不失控的架构、模式、实现、Review 和 Release Gate 通用框架 |
| `app/catalog.md` | 移动端和全平台 App 生产可上线知识入口 |
| `app/Mobile_App_Production_Readiness_Framework_移动端全平台生产可上线规范.md` | 移动端全平台生产可上线规范与宠物商城行业案例 |

## 核心判断

外挂总知识库应该先做成独立 `team-wiki` Git 项目和 Markdown catalog 体系，而不是一开始上向量库。原因是：

- Git 能保留审计、review、回滚和冲突处理。
- Markdown frontmatter 足够表达 maturity、source、tags 和适用阶段。
- Catalog-first 查询能控制上下文，不会把大量知识塞进每轮 Codex。
- 后续需要语义检索时，可以从同一批 Markdown 条目构建向量索引。

## 领域扩展

当前已新增 `common/` 通用扩展和 `app/` 领域扩展。

`common/` 用于沉淀跨技术栈的 AI Coding 生产控制知识，例如架构边界、模式约束、任务拆分、Review Gate 和 Release Gate。使用时先读 `common/catalog.md`，只有任务命中 AI 生成代码治理、任务边界、架构/契约/安全风险或生产控制时才读取完整规范。

`app/` 用于沉淀移动端和全平台 App 的生产可上线规范。该领域服务于 App PRD、移动端开发、QA、安全、隐私合规、商店审核和 Release Gate，不替代项目自身 PRD、架构约束、测试矩阵或法务合规结论。

使用原则：

1. 先读对应领域的 catalog。
2. 只有任务明确命中 catalog 的触发条件时，才读取完整规范。
3. 完整规范是长文档，不进入默认上下文源。

## 与现有知识层关系

```text
外挂总知识库 team-wiki/            # 跨项目补充，非阻塞依赖
  -> 项目接入时按需读取
  -> 项目归档后接收候选贡献

项目知识 docs/knowledge/           # 当前项目事实和本项目经验
  -> 本地 driver 直接读取
  -> 项目事实优先于外挂知识
```

项目事实、架构约束、PRD、测试矩阵始终高于外挂知识。外挂知识只能补充判断，不能覆盖当前项目 truth source。
