---
type: knowledge_base_guide
tags: [知识库, 使用说明, Obsidian, Agent检索]
aliases: [如愿知识库使用说明, 知识库操作说明, 知识库维护说明]
source: manual
status: active
owner: 内部技术团队
updated: 2026-05
---

# 如愿知识库使用说明

本文档说明如愿知识库的用途、目录结构、文档存放规则、索引维护规则、Obsidian 图谱使用方式，以及 Agent 如何基于知识库回答问题。

## 1. 知识库定位

如愿知识库用于沉淀内部系统建设过程中的：

- 业务需求
- 业务规则
- 业务流程
- 项目里程碑
- 技术方案
- 测试用例
- 缺陷与验收记录
- Agent 检索规则

知识库不是单纯存文件，而是要形成可检索、可追溯、可被 Agent 引用回答的知识网络。

## 2. 推荐打开方式

推荐使用 Obsidian 打开以下目录作为 Vault：

```text
D:\AIcoding\WishFulfilled\知识库\如愿知识库
```

打开后建议从以下入口开始：

1. [[欢迎]]
2. [[00_首页/知识库首页]]
3. [[00_首页/知识地图]]
4. [[00_首页/Agent问答入口]]
5. [[04_Agent检索/检索说明]]

## 3. 主目录说明

```text
如愿知识库/
├─ 00_首页/              # 首页、知识地图、Agent 问答入口
├─ 01_业务流程/          # 业务流程、业务对象、业务规则、补充验证记录
├─ 02_项目管理流程/      # 项目阶段、角色职责、交付物、检查清单、FAQ
├─ 03_规范与模板/        # 需求、业务规则、会议、上线检查等模板
├─ 04_Agent检索/         # 检索说明、关键词、同义词、来源文件索引
├─ 05_需求文档/          # 正式需求文档、需求索引
├─ 06_里程碑/            # 里程碑计划、阶段计划、评审记录
├─ 07_技术文档/          # 技术方案、系统架构、接口说明、技术决策
├─ 08_测试相关/          # 测试用例、测试计划、缺陷、验收、上线检查
├─ 99_归档/              # 历史文档、废弃文档、仅供参考内容
├─ 欢迎.md               # Obsidian 入口页
├─ 知识库使用说明.md     # 本文档
└─ Git使用说明.md        # Git 仓库协作说明
```

## 4. 日常使用入口

| 使用场景 | 优先入口 |
|---|---|
| 想了解知识库整体结构 | [[00_首页/知识地图]] |
| 想让 Agent 回答业务问题 | [[00_首页/Agent问答入口]] |
| 查看或新增需求 | [[05_需求文档/README]] |
| 查看或新增里程碑 | [[06_里程碑/README]] |
| 查看或新增技术方案 | [[07_技术文档/README]] |
| 查看或新增测试用例 | [[08_测试相关/README]] |
| 查看项目管理阶段 | [[02_项目管理流程/AI驱动内部系统开发流程_V3_总览]] |
| 查看 Agent 检索规则 | [[04_Agent检索/检索说明]] |
| 查看来源依据 | [[04_Agent检索/来源文件索引]] |

## 5. 文档应该放在哪里

### 5.1 需求文档

放入：

```text
05_需求文档/
```

适合存放：

- 正式需求说明
- 业务规则说明
- 需求变更说明
- 业务补充说明
- 产品口径说明

推荐命名：

```text
业务域_需求或规则名称_YYYYMMDD.md
```

示例：

```text
USER评价业务闭环_数据流与中间对象设计_20260517.md
采购_供应商准入规则_20260526.md
库存_出入库审批规则_20260526.md
```

新增后应同步维护：

- [[05_需求文档/需求文档索引]]
- [[01_业务流程/业务规则索引]]，如涉及业务规则
- [[01_业务流程/业务对象字典]]，如涉及新增业务对象
- [[04_Agent检索/关键词索引]]，如需要 Agent 检索命中
- [[04_Agent检索/来源文件索引]]，如是新的权威来源

### 5.2 里程碑文档

放入：

```text
06_里程碑/
```

适合存放：

- 项目里程碑计划
- 阶段计划
- 阶段评审记录
- 上线节奏
- 准入/准出记录

推荐命名：

```text
项目名_里程碑计划_YYYYMMDD.md
项目名_阶段评审记录_YYYYMMDD.md
```

新增后应同步维护：

- [[06_里程碑/里程碑索引]]

### 5.3 技术文档

放入：

```text
07_技术文档/
```

适合存放：

- 系统架构说明
- 数据模型说明
- 接口说明
- 模块设计
- 技术方案
- 部署说明
- 技术决策记录

推荐命名：

```text
系统或模块_技术方案_YYYYMMDD.md
系统或模块_接口说明_YYYYMMDD.md
系统或模块_数据模型_YYYYMMDD.md
```

新增后应同步维护：

- [[07_技术文档/技术文档索引]]
- [[04_Agent检索/关键词索引]]，如需要 Agent 检索
- [[04_Agent检索/来源文件索引]]，如是新的技术依据

### 5.4 测试相关文档

放入：

```text
08_测试相关/
```

适合存放：

- 测试计划
- 测试用例
- 缺陷记录
- 验收记录
- 上线检查
- 回归测试记录

推荐命名：

```text
项目名_模块名_测试计划_YYYYMMDD.md
项目名_模块名_测试用例_YYYYMMDD.md
项目名_模块名_缺陷记录_YYYYMMDD.md
项目名_模块名_验收记录_YYYYMMDD.md
```

新增后应同步维护：

- [[08_测试相关/测试用例索引]]
- 关联需求文档
- 关联里程碑或测试阶段

测试用例必须能追溯到需求来源。

### 5.5 业务流程文档

放入：

```text
01_业务流程/
```

适合存放：

- 已稳定的业务流程
- 业务对象定义
- 业务规则索引
- 业务补充验证记录

如果是新需求或尚未确认的业务规则，优先放入 `05_需求文档/`，确认稳定后再沉淀到 `01_业务流程/`。

### 5.6 模板文档

放入：

```text
03_规范与模板/
```

适合存放：

- 需求说明模板
- 业务规则补充模板
- 会议纪要模板
- 上线检查模板
- 通用文档模板

模板只用于复用格式，不应存放具体项目内容。

### 5.7 归档文档

放入：

```text
99_归档/
```

适合存放：

- 已废弃文档
- 历史版本
- 仅供参考内容
- 不再作为当前依据的旧规则

归档文档不应作为 Agent 当前回答依据，除非问题明确询问历史背景。

## 6. Agent 检索优先级

Agent 回答问题时，按以下顺序查找依据：

1. `05_需求文档/`：正式需求、业务规则、需求变更。
2. `06_里程碑/`：项目节点、阶段计划、阶段评审、上线节奏。
3. `07_技术文档/`：系统架构、数据模型、接口说明、实现方案、技术决策。
4. `08_测试相关/`：测试计划、测试用例、缺陷记录、验收记录、上线检查。
5. `02_项目管理流程/`：内部系统开发流程、阶段、角色、门禁、交付物、检查清单。
6. `01_业务流程/`：真实业务流程、业务对象、业务规则。
7. `04_Agent检索/`：关键词、同义词、来源索引、回答规则。
8. `03_规范与模板/`：需要产出模板或文档时使用。

Agent 回答必须注明来源文件。

## 7. 不同问题应该查哪里

| 问题类型 | 优先查找位置 |
|---|---|
| 某个需求是什么 | `05_需求文档/`、`05_需求文档/需求文档索引.md` |
| 某个业务规则是什么 | `05_需求文档/`、`01_业务流程/业务规则索引.md` |
| 某个业务对象怎么定义 | `01_业务流程/业务对象字典.md`、相关需求文档 |
| 项目当前到哪个阶段 | `06_里程碑/`、`06_里程碑/里程碑索引.md` |
| 某阶段要交付什么 | `02_项目管理流程/阶段交付物清单.md` |
| 技术怎么实现 | `07_技术文档/`、`07_技术文档/技术文档索引.md` |
| 接口怎么设计 | `07_技术文档/`、具体接口说明文档 |
| 数据模型怎么设计 | `07_技术文档/`、具体数据模型文档、需求文档 |
| 测试用例在哪里 | `08_测试相关/`、`08_测试相关/测试用例索引.md` |
| 缺陷如何记录 | `08_测试相关/缺陷记录模板.md` |
| 上线前检查什么 | `08_测试相关/上线检查模板.md`、`02_项目管理流程/项目检查清单.md` |
| Agent 为什么这样回答 | `04_Agent检索/检索说明.md`、`04_Agent检索/来源文件索引.md` |

## 8. 新增文档标准流程

新增文档建议按以下流程操作：

```text
确定文档类型
  ↓
放入对应目录
  ↓
按推荐命名规则命名
  ↓
补充 Frontmatter
  ↓
正文写清背景、规则、流程、验收口径
  ↓
补充 Agent 检索字段
  ↓
更新对应索引
  ↓
更新关键词/来源文件索引
  ↓
在 Obsidian 中检查链接和图谱
```

## 9. 推荐 Frontmatter

每个正式文档建议在顶部维护 Frontmatter：

```yaml
---
type: requirement
tags: [需求文档, USER评价业务闭环]
aliases: [数据流与中间对象设计]
source: manual
status: active
owner: 产品经理
updated: 2026-05-26
---
```

常用字段：

| 字段 | 说明 |
|---|---|
| `type` | 文档类型，如 requirement、technical_doc、test_case、milestone |
| `tags` | 标签，用于 Obsidian 和 Agent 检索 |
| `aliases` | 别名，便于搜索同义叫法 |
| `source` | 来源，如 manual、docx、meeting、requirement |
| `status` | 状态，如 draft、reviewing、active、deprecated |
| `owner` | 负责人 |
| `updated` | 最近更新时间 |

## 10. 文档状态说明

| 状态 | 含义 | Agent 使用规则 |
|---|---|---|
| `draft` | 草稿 | 只能作为参考，回答时需说明尚未确认 |
| `reviewing` | 评审中 | 可引用但需说明仍在评审 |
| `active` | 已确认 | 可作为正式回答依据 |
| `deprecated` | 已废弃 | 不作为当前规则依据，只能说明历史背景 |

## 11. 索引维护规则

### 11.1 需求索引

新增需求文档后，维护：

```text
05_需求文档/需求文档索引.md
```

至少登记：

- 编号
- 业务域
- 需求/规则名称
- 文件路径
- 状态
- 负责人
- 更新时间
- 验证状态

### 11.2 里程碑索引

新增里程碑后，维护：

```text
06_里程碑/里程碑索引.md
```

至少登记：

- 项目
- 里程碑名称
- 文件
- 阶段
- 负责人
- 计划时间
- 当前状态

### 11.3 技术文档索引

新增技术文档后，维护：

```text
07_技术文档/技术文档索引.md
```

至少登记：

- 模块/系统
- 文档类型
- 文件
- 关联需求
- 负责人
- 更新时间
- 状态

### 11.4 测试用例索引

新增测试用例后，维护：

```text
08_测试相关/测试用例索引.md
```

至少登记：

- 项目
- 模块
- 用例名称
- 文件
- 关联需求
- 测试类型
- 状态
- 负责人

## 12. Obsidian 链接规则

推荐使用 Obsidian 双链：

```markdown
[[05_需求文档/需求文档索引]]
[[07_技术文档/技术文档索引]]
[[08_测试相关/测试用例索引]]
```

也可以使用 Markdown 链接：

```markdown
[需求文档索引](05_需求文档/需求文档索引.md)
```

优先建议使用双链，方便图谱建立关系。

## 13. Obsidian 图谱说明

Obsidian 图谱会显示两类节点：

1. 已存在的 Markdown 文件。
2. 文档中链接到、但本地还不存在的 Markdown 文件。

如果你只放了一个文件，但图谱出现多个节点，通常是因为该文件引用了其他文档。

示例：

```markdown
[工作基线 v1.2](20260517_USER评价业务闭环主流程与后续工作基线_v1.2.md)
```

即使这个文件尚未放入目录，Obsidian 也可能在图谱中显示它。这是“未创建链接 / dangling link”，不是目录里真的多了文件。

如果只想显示真实存在的文件，可在图谱中开启：

```text
图谱视图 → 筛选 → 仅显示已有文件
```

如果希望知识链路完整，应把被引用的上游文档补充到对应目录。

## 14. 知识地图维护规则

知识地图文件：

```text
00_首页/知识地图.md
```

知识地图只维护主入口和关键二级入口，不需要把每个具体项目文档都放进去。

推荐主结构：

```text
知识地图
├─ 需求文档
├─ 里程碑
├─ 技术文档
├─ 测试相关
└─ Agent 检索
```

新增普通需求、测试用例、技术方案时，一般只维护对应索引，不需要直接改知识地图。

只有新增重要分类或核心入口时，才更新知识地图。

## 15. Agent 回答规则

Agent 基于知识库回答问题时，应遵守：

1. 先查知识库，再回答。
2. 优先引用 `active` 状态文档。
3. 先给结论，再展开依据。
4. 需求问题优先查需求文档。
5. 技术问题优先查技术文档。
6. 测试问题优先查测试相关。
7. 里程碑问题优先查里程碑。
8. 如果知识库没有明确记录，回答“知识库未明确记录”。
9. 不要根据经验补充未记录的事实。
10. 回答末尾必须说明来源文件。

推荐引用格式：

```text
来源：05_需求文档/xxx.md
```

## 16. 测试用例管理要求

测试用例应单独存放在：

```text
08_测试相关/
```

每个测试用例应尽量包含：

- 用例编号
- 关联需求
- 测试模块
- 前置条件
- 操作步骤
- 预期结果
- 实际结果
- 优先级
- 状态
- 负责人

测试用例必须关联需求文档或业务规则，避免出现无法追溯来源的测试项。

## 17. 文档关系建议

推荐建立以下关系：

```text
需求文档
  ↓
里程碑 / 阶段计划
  ↓
技术文档
  ↓
测试计划 / 测试用例
  ↓
缺陷记录 / 验收记录
  ↓
上线检查 / 复盘回流
```

每个下游文档应尽量写明上游来源。

示例：

```markdown
## 关联文档

- 需求来源：[[05_需求文档/xxx需求文档]]
- 技术方案：[[07_技术文档/xxx技术方案]]
- 测试用例：[[08_测试相关/xxx测试用例]]
```

## 18. 不建议放入知识库的内容

不建议直接放入：

- 密码
- Token
- API Key
- 未脱敏客户隐私
- 未脱敏订单号、电话、邮箱、地址
- 临时截图
- 个人草稿
- 与项目无关的资料

如果必须记录敏感业务规则，应先脱敏再写入知识库。

## 19. 提交前检查清单

新增或修改文档后，检查：

- [ ] 文件放在正确目录。
- [ ] 文件名能表达业务域和用途。
- [ ] 正式文档已写 Frontmatter。
- [ ] 文档状态正确。
- [ ] 关键业务规则有来源。
- [ ] 需求文档已更新需求文档索引。
- [ ] 技术文档已更新技术文档索引。
- [ ] 测试用例已更新测试用例索引。
- [ ] 重要关键词已补充到关键词索引。
- [ ] 需要追溯的来源已补充到来源文件索引。
- [ ] Obsidian 链接可以正常跳转，或确认是有意保留的上游虚链接。
- [ ] 不包含密码、Token、密钥和未脱敏敏感信息。

## 20. 常见问题

### 20.1 为什么只放一个文档，图谱显示多个节点？

因为文档中链接了其他 Markdown 文件。Obsidian 会把被链接但尚未创建的文件也显示成节点。

### 20.2 README.md 为什么会出现在图谱里？

因为 README.md 也是 Markdown 文件，Obsidian 会把它作为普通节点显示。

### 20.3 一个具体项目文档要不要加到知识地图？

通常不需要。具体项目文档登记到对应索引即可。知识地图只放主入口和关键二级入口。

### 20.4 需求文档和业务流程怎么区分？

- 尚在新增、变更、评审中的内容放 `05_需求文档/`。
- 已稳定、可复用的业务流程沉淀到 `01_业务流程/`。

### 20.5 测试用例应该跟需求还是技术文档关联？

优先关联需求文档；如果测试点来自技术实现细节，再补充关联技术文档。

### 20.6 Agent 回答错了怎么办？

优先检查：

1. 对应文档是否存在。
2. 文档是否放在正确目录。
3. 索引是否维护。
4. 关键词或同义词是否缺失。
5. 来源文件索引是否登记。
6. 文档状态是否为 `active`。

必要时更新：

- [[04_Agent检索/关键词索引]]
- [[04_Agent检索/同义词表]]
- [[04_Agent检索/来源文件索引]]
- [[04_Agent检索/知识库持续更新与验证流程]]

## 21. 维护原则

1. 文档要放对目录。
2. 正式内容要有来源。
3. 关键文档要有索引。
4. 测试用例要能追溯需求。
5. 技术文档要能追溯需求或业务流程。
6. 里程碑要能追溯阶段目标和交付物。
7. Agent 回答要能追溯来源文件。
8. 废弃内容要归档，不要混在当前依据中。
9. 敏感信息要脱敏。
10. 知识库持续维护比一次性整理更重要。