┌─────────────────────────────────────────────────┐
│  Schema 层(规则)                                │
│  - 知识分类体系、命名约定、ADR 模板               │
│  - LLM 行为规则:什么时候更新、什么时候叫人         │
│  - 治理:谁有权改、谁负责质量                      │
└─────────────────────────────────────────────────┘
                    ↓ 指导
┌─────────────────────────────────────────────────┐
│  Wiki 层(LLM 维护的"理解")                      │
│  - 架构图、依赖图、API 文档、ADR 索引              │
│  - 概念词典:领域名词 ↔ 代码位置                   │
│  - 决策记录:为什么 A 不选 B                       │
│  - 失败案例:踩过的坑、撤销的决策                   │
└─────────────────────────────────────────────────┘
                    ↑ 编译自
┌─────────────────────────────────────────────────┐
│  Raw Sources 层(只读的事实)                      │
│  - 代码仓库(git)、PR/CI/CD 日志                   │
│  - Issue/工单/Slack/会议纪要                      │
│  - 外部依赖文档、SDK、RFC                         │
│  - 监控告警、用户反馈                             │
└─────────────────────────────────────────────────┘

二、知识分类:研发团队该存什么

不是所有"知识"都值得存。用一个问题过滤:这条知识三个月后还会被谁、用在什么场景下消费?

按价值密度排序,优先建这五类:

类型	内容	价值	更新频率
ADR(架构决策记录)	选型理由、Trade-off、被否决的方案	极高(防重复争论)	低但关键
API / 服务契约	接口、字段、依赖、变更历史	极高(人和 Agent 都要消费)	中
领域词典	业务名词 ↔ 代码模块 ↔ 负责人	高(新人入职第一周)	低
失败 / 事故档案	怎么挂的、根因、修复、复盘	高(防重复踩坑)	事件驱动
运行手册(Runbook)	告警处理、回滚、扩容	高(值班用)	中

不优先建:新人onboarding手册(从 ADR + 领域词典 + Runbook 自动生成)、技术博客(发到外部,内部只存索引)、会议纪要全文(只存"决策"和"行动项")。

2.1 输入层:Raw Sources(原始事实)

这一层只读不写,是知识库的"水源"。软件开发团队的输入源,按价值密度排:

来源	抓什么	怎么接
Git 仓库	commit、branch、merge、blame	git hook + 定期 dump
PR + Review	diff、讨论、批准记录	GitHub / GitLab API
Issue/工单	创建、关闭、根因	Jira / Linear API
监控告警/事故	触发、响应、复盘	Datadog / PagerDuty + 复盘文档
会议纪要	决策、行动项、悬而未决	飞书/腾讯会议 + 飞书妙记
Slack / IM	决策讨论、答疑	飞书/Lark API
外部依赖	SDK、API、RFC 版本变更	定期抓 + LLM 摘要
客户/用户反馈	投诉、需求、NPS 原文	客服系统 + 调研工具
设计/PRD	决策点、被否决方案	Figma/语雀

输入层的设计原则:所有源必须有"摄取路径"——没路径的源不接,接了也跑不通。优先接 4 个最有价值的:Git、PR、工单、会议纪要,这四个覆盖率到 80%。

2.2 沉淀层:Wiki(可消费的"理解")

这一层LLM 写 + 人读 + Lint 校。按"价值密度 + 更新频率"双维度排：

高价值 · 低更新   │  ADR  决策记录
                  │  领域词典
                  │  知识地图(谁负责什么)
──────────────────┼────────────────────
高价值 · 高更新   │  API 契约 / 服务依赖图
                  │  Runbook / 故障处理
                  │  事故档案
──────────────────┼────────────────────
中价值 · 中更新   │  技术债清单
                  │  性能基线
                  │  容量规划
──────────────────┼────────────────────
低价值 · 任意     │  Onboarding 手册(从上面自动生成)
                  │  会议纪要原文(只存索引)
                  │  培训材料(从 ADR 生成)

关键判断:Onboarding 手册不要单独维护，它该是 ADR + 领域词典 + Runbook 的"渲染产物"。单独维护的 onboarding 文档 100% 会过时。

2.3 规则层:Schema(约束一切)

这一层人写,所有自动化读。一个研发团队的 schema 必须包含:

知识分类体系:五种知识类型的定义、模板、命名
LLM 行为规则:什么时候更新、什么时候叫人、改动怎么走 PR
质量标准:什么样的 wiki 算合格,什么样算"过时"
治理规则:谁能改 schema、谁能批准新分类、矛盾谁仲裁

Schema 写得越具体,LLM 跑得越准。一份"vague"的 schema 等于没有 schema。

三、LLM 自动化流水线

这是研发知识库跟一般 wiki 拉开差距的地方。LLM 应该是 7×24 跑的"维护工",不是被叫来才动。包含四个自动化触发器：

PR merged → 自动总结：LLM 读 PR diff + commit message + review 评论,生成 1-2 段"这个 PR 改变了什么,为什么",写入对应模块的 wiki 页面。
定期 lint(每天/每周)：LLM 跑全量检查:
- 哪些 wiki 页面引用的代码路径已经不存在了
- 哪些 ADR 被新的 PR 推翻但没标记"superseded"
- 哪些概念在 wiki 里有定义但代码里没对应
- 哪些"决策"和"代码现状"矛盾(代码做了 X 但 ADR 说要做 Y) 生成 lint 报告,人 review 后批量更新。
Issue/工单关闭 → 归档：LLM把"非平凡"的工单(关掉后还有信息价值的)压缩成 1 段"问题/根因/解法",归档到对应模块的"事故档案"或"常见问题"。
代码重大变更 → 触发 ADR 草稿：当 LLM 检测到某个模块连续 N 个 PR 都集中在同一方向,自动草拟一份 ADR 草稿,提醒架构组 review 是否值得记一笔。

Schema 里要明确定义：LLM 写的内容必须带 [🤖 LLM-generated, last reviewed: <date>] 标记；超过 30 天没被 review 的页面，自动降权(搜索排后)。

3.1 机制 1:自动化(机器跑的部分)

让 LLM 7×24 跑四条流水线:

流水线	触发	动作
PR-ingest	PR merged	读 diff + review,写 1-2 段摘要到对应模块页
Daily-lint	每天 0 点	跑 5 类检查,出报告
Issue-archive	工单关闭	非平凡工单 → 事故档案/常见问题
ADR-trigger	模块 N 个 PR 集中同方向	草拟 ADR,提醒架构组 review

Lint 的 5 类检查是命脉:

代码引用一致性:wiki 提到的代码路径是不是还存在
ADR 现状一致性:代码是否已偏离 ADR
孤儿页:有页面但没人引用
内部矛盾:两页说相反的话
覆盖度:哪些代码模块在 wiki 里完全没出现

LLM 写的内容必须带机器标记:[🤖 auto, last reviewed: <date>]。30 天没 review 的自动降权,这是 Schema 写死的。

3.2 机制 2:流程(人参与的"卡点")

流程	卡点
PR review	review 模板必填"是否需要更新 wiki"
重大架构变更	合并前必须有 ADR,否则不准合
事故复盘	24h 内出初稿,72h 内归档到事故档案
Onboarding	新人首周"必读 wiki 清单"自动生成,完成度有记录
季度 wiki 健康度	报告覆盖率、过时率、矛盾数、孤儿数

这些流程看起来是"流程税",但没有它,知识库 3 个月内必崩。

3.3 机制 3:角色(谁负责)

必须明确的三个角色,缺一就烂:

角色	数量	职责	通常谁来当
Schema Owner	1-2 人	维护规则、批准新分类、仲裁矛盾	架构师 / 首席工程师
Wiki Gardener	1-2 人(可兼职)	Review LLM 提议、处理 Lint 告警、清理孤儿	资深开发 / 模块 Owner
Module Owner	每个核心模块 1 人	本模块知识第一责任人,处理模块级 Lint	Tech Lead

关键原则：

LLM 没有写权限,只有"提议 + 写草稿"权限。所有 wiki 变更走 PR,人 review 后合并。
Lint 报告的"问题"是任务,不是建议。schema 规定:30 天内没人处理的 lint 告警,自动升级到模块 owner。
代码改 ≠ wiki 改。代码改动 wiki 不会自动跟着变——必须显式触发 LLM 维护流程(避免 LLM 把"理解"写得跟代码不同步)。
Schema 变更最难,门槛最高。改 schema = 改知识分类体系 = 几乎等于知识库重建,要走架构组 review。

最常被忽略的:Module Owner。没有模块级的"知识 owner",lint 告警就没人处理,wikipedia 就慢慢烂掉。

3.4 机制 4:考核(怎么让人愿意做)

指标	谁负责	怎么算
ADR 数量	Tech Lead	每个架构决策都有 ADR,无 ADR 不算决策
模块 Lint 告警处理率	Module Owner	30 天内处理 90%
新人 Onboarding 体验评分	Schema Owner	季度调研
事故复盘归档及时率	SRE/值班长	72h 内归档 100%
Wiki 覆盖率	全员	关键模块 100% 覆盖