---
type: AgentsSpec
title: 知识库内容规范
description: 知识文件与变更文档内容结构的唯一标准；叠加 OKF 参考布局、图谱关系字段与 wikilink。
timestamp: 2026-07-12T00:00:00Z
related:
  - 知识地图
  - index
depends_on: []
---

# 知识库内容规范

> 本文件是**知识文件与变更文档内容结构的唯一标准**。kb 流程（`/kb-*`）生成或维护业务域知识文件、变更目录内 `02-design.md` / `03-tasks.md` 时，内容结构以本文件为准。OKF 参考布局与 `type` 见插件 `references/kb-okf.md`；内部链接与 `related`/`depends_on` 见 `references/kb-graph.md`。可选时效字段 `status` / `supersedes` / `keywords` 与写时图谱演化见同目录规范所引用的 `kb-knowledge-evolve`（插件 `references/kb-knowledge-evolve.md`）。

## 一、业务域文件组织

每个业务域目录（`knowledge/业务域/<中文领域>/`）统一采用：

```
<领域>/
├── index.md         # 领域局部索引（OKF 保留名，无 frontmatter）
├── log.md           # 可选；结构性变更日志（OKF 保留名）
├── 01-概览.md       # 模块总图（结构见「四」）；须含 YAML type
├── 02-<子模块>.md   # 编号子模块文件（十段式，结构见「三」）
├── 03-<子模块>.md
└── 0N-<子模块>.md
```

- **按「子模块/能力」拆分，不按「角色」拆分**：不再使用 `客户端流程.md`、`后台流程.md`、`架构.md`、`接口.md`、`数据.md` 这类按角色分文件的写法；客户端流程、接口、数据等作为**段落**写进各子模块文件，跨子模块的聚合视图放进 `01-概览`。
- **编号前缀按阅读优先级**：`01` 概览必为第一篇，其后按推荐阅读顺序编号。
- **概览必须 wikilink 全部子模块**；`index.md` 维护文件清单与阅读路径（wikilink 列表）。
- **默认扁平，不建子目录**：同一业务域内所有编号子模块文件直接放在 `<领域>/` 根下。
- **子目录仅作例外**：仅当编号子模块已拆到仍超限或独立主题体量极大时，才允许中文子目录分组；子目录内文件**仍遵循编号 + 十段式**，并维护子目录 `index.md`。领域 `index.md` 只链子目录入口，**不得**展开子目录叶子清单。

## 二、工程平台分区组织

每个工程平台分区（`knowledge/工程平台/<中文平台分区>/`）与业务域采用**同一套编号与内容结构**：

```
<平台分区>/
├── index.md
├── log.md           # 可选
├── 01-概览.md
├── 02-<子模块>.md
└── 0N-<子模块>.md
```

- 分区示例：`Flutter客户端/`、`Rust服务端/`、`Quasar管理后台/`、`QuasarH5/`、`官方网站/`、`Proto协议/`。
- **禁止**在分区内使用无编号的 `README.md`、`00-README.md`、`概览.md` 等旧命名；`工程平台/index.md`（根入口）只列各分区 `index.md`，不展开叶子文件。
- 子模块按**该端工程的阅读优先级**编号。
- 纯前端分区（Flutter/Quasar/H5/官网）的十段式中：「三、服务端规则」无服务端实现时写「无」；构建、路由、工程约定写入「二、设计决策与取舍」或「四、客户端流程」。

## 三、子模块文件结构（十段式）

每个编号子模块文件统一十段式（一～九 +「十、相关」），**标题用中文「一、二、三…」**；某段在本子模块确无内容时写「无」，不为凑结构注水。文件顶部须含 YAML frontmatter：`type: DomainModule` 或 `PlatformModule`，以及**必填** `related`、`depends_on`（可为空数组，字段不可省略）。

| 段 | 标题 | 内容 |
|---|---|---|
| 一 | 能力范围 | 本子模块负责什么、不负责什么 |
| 二 | 设计决策与取舍 | 为什么这样设计、权衡了什么（**回代码核实**，见「八」） |
| 三 | 服务端规则 | 业务逻辑、规则、约束、状态流转 |
| 四 | 客户端流程 | 用户侧/后台侧流程；关键链路配 mermaid |
| 五 | 接口 | 方法 + 关键入参/出参/错误码 |
| 六 | 数据 | 表/字段；必要时配关系图 |
| 七 | 非功能与可观测 | 并发、容错、安全/权限、关键日志/埋点 |
| 八 | 推送 | 推送类型与触发；无则写「无」 |
| 九 | 已知限制与 TODO | 集中沉淀限制、未覆盖、待办 |
| 十 | 相关 | `[[wikilink]]` 列表；正文链接 ⊇ `related` ∪ `depends_on` |

段内互链**仅** `[[wikilink]]`；外部 URL 用 Markdown 链接。细则见 `references/kb-graph.md`。

## 四、概览文件结构（`01-概览.md`）

概览是模块总图，不套用十段式正文，但**段落顺序、中文编号、必填项固定**；frontmatter `type` 为 `DomainOverview` 或 `PlatformOverview`，且含 `related`、`depends_on`。

| 段 | 标题 | 必填 | 必配图 | 内容 |
|---|---|---|---|---|
| 一 | 模块定位与边界 | 是 | 否 | 模块职责，含对外部领域的引用边界 |
| 二 | 整体架构 | 是 | **是**（mermaid） | 分层/多链路总图 |
| 三 | 核心状态机/主流程 | 是 | **是**（mermaid） | 领域主状态机或主流程；确无则写「无」并说明原因 |
| 四 | 子模块清单 | 是 | 否 | 功能模块表，逐条 wikilink 各编号子模块 |
| 五 | 关键约束 | 是 | 否 | 全局性硬约束 |
| 六 | 术语表 | 是 | 否 | 领域专有名词集中定义 |
| 七 | 依赖关系 | 是 | **是**（mermaid） | 对其他领域的引用，配依赖图；`depends_on` 须与此一致 |
| 八 | 全局非功能与可观测 | 是 | 否 | 全局并发/容错/安全/权限/日志/埋点 |
| 九 | 全局已知限制 | 是 | 否 | 领域级限制与未覆盖项 |
| 十 | 文档入口 | 是 | 否 | 编号子模块清单（有序 wikilink），不与「四」合并 |
| 十一 | 相关 | 是 | 否 | `[[wikilink]]` 列表；正文链接 ⊇ `related` ∪ `depends_on` |

- 「二」「七」必须配 mermaid 图；「三」原则上配图。
- 「四」与「十」职责不同，**不得合并省略**。

## 五、概念 frontmatter 字段

非保留名概念文件（**不含** `index.md`、`log.md`）frontmatter 除 `type` 外：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `type` | string | 是 | 见 `kb-okf.md` §3 |
| `related` | string[] | 是（可 `[]`） | 语义关联；wikilink 目标，**无括号** |
| `depends_on` | string[] | 是（可 `[]`） | 硬依赖；wikilink 目标，**无括号** |
| `title` | string | 推荐 | 标题 |
| `description` | string | 推荐 | 摘要 |
| `timestamp` | string | 推荐 | ISO 8601 |

缺 `related` 或 `depends_on` 视为违规。JSON Schema：`schema/kb-concept-frontmatter.schema.json`。

## 六、变更设计文档结构（`02-design.md`）

`/kb-design` 产出；frontmatter `type: ChangeDesign`；**段落顺序、中文编号、必填项固定**：

| 段 | 标题 | 必填 | 必配图 | 内容 |
|---|---|---|---|---|
| 一 | 业务流程与改动范围 | 是 | **是**（业务流程 mermaid） | 含「业务流程图」「流程步骤与改动对照」表、「改动汇总」 |
| 二 | 整体思路 | 是 | 否 | 根因、方案要点、与 01 的追溯 |
| 三 | 分层设计 | 是 | 可选 | 端点/服务/数据层落点 |
| 四 | 接口设计 | 是 | 否 | 方法 + 关键入参/出参/错误码；无变更写「无」 |
| 五 | 数据结构 | 是 | 否 | 表/字段/模型扩展；无变更写「无」 |
| 六 | 实现步骤 | 是 | 否 | 有序步骤；每步可回溯「一」中步骤 ID |
| 七 | 参考实现 | 是 | 否 | CodeGraph 或源码命中的关键符号与路径 |
| 八 | 技术影响 | 是 | 否 | 涉及模块、proto/数据变更、风险；可含「工程补充验收项」 |
| 九 | 知识库影响 | 是 | 否 | 初评：哪些知识文件可能受影响 |
| 十 | 知识库更新计划 | 是 | 否 | 分「（一）必须更新 / （二）可能更新 / （三）不需要更新」 |

**编号规则（大段 + 段内小节）**：

| 层级 | Markdown 标题 | 示例 | 引用写法 |
|---|---|---|---|
| 大段 | `## 一、` … `## 十、` | `## 八、技术影响` | `八` 或 `§八` |
| 段内小节 | `### （一）` … `### （三）` | `### （二）工程补充验收项` | `八·（二）` |

- 含段内小节：一 →（一）业务流程图（二）流程步骤与改动对照（三）改动汇总；八 →（一）影响范围（二）工程补充验收项；十 →（一）必须更新（二）可能更新（三）不需要更新。

## 七、变更任务文档结构（`03-tasks.md`）

`/kb-plan` 产出；frontmatter `type: ChangeTasks`；文件级**仅两段**：

| 段 | 标题 | 内容 |
|---|---|---|
| 一 | 执行计划 | `### （一）依赖图`；`### （二）分组调度` |
| 二 | 任务清单 | 若干 `## T{n}: {名称}` 任务块 |

每条 `T{n}` **必须**含：背景、上下文文件、实现范围、接口契约、验收标准、依赖。

## 八、内容规则

1. **以代码为准**：结论必须回 `kb.project.json` 中 `codeRoots` 核实；查不到依据标「（待确认/推测）」，**严禁编造**。
2. **中文编写**：所有知识文件、变更文档使用简体中文。
3. **中文标题分级**：大标题用「一、二、三…」。
4. **关键链路可视化**：优先 mermaid（节点 ID 不带空格，特殊字符 label 用双引号，不用 `end` 等保留字做 ID，不写显式颜色）。
5. **每文件 ≤ 3000 字符**：超限拆分为多个编号子模块文件。
6. **不臆改业务语义**：重组/补全文档时保留既有事实，产品意图不清先问用户。
7. **OKF 参考布局**：非保留名 `.md` 必须有 YAML frontmatter 且含非空 `type`；入口为各目录 `index.md`（wikilink 列表）；结构性变更追加同目录 `log.md`，**禁止**在正文写「变更记录」段。
8. **图谱**：概念文件必有 `related`、`depends_on` 与「相关」段；内部仅 `[[wikilink]]`；见 `kb-graph.md`。
9. **变更文档 type**：`01`～`07` 分别为 `ChangeProposal` / `ChangeDesign` / `ChangeTasks` / `ChangeReview` / `ChangeSummary` / `ChangeTest` / `ChangeRevisions`。

## 相关

- [[知识地图]]
- [[index]]