qiaoxinjiu/Fulfilled-Knowledge

Fork 0

Files

qiaoxinjiu 96982ce5cf docs: 更新知识库使用说明

2026-05-26 15:40:01 +08:00

16 KiB

Raw Permalink Blame History

type, tags, aliases, source, status, owner, updated

type

如愿知识库使用说明

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

1. 知识库定位

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

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

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

2. 推荐打开方式

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

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

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

3. 主目录说明

如愿知识库/
├─ 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 需求文档

放入：

05_需求文档/

适合存放：

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

推荐命名：

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

示例：

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

新增后应同步维护：

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

5.2 里程碑文档

放入：

06_里程碑/

适合存放：

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

推荐命名：

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

新增后应同步维护：

06_里程碑/里程碑索引

5.3 技术文档

放入：

07_技术文档/

适合存放：

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

推荐命名：

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

新增后应同步维护：

5.4 测试相关文档

放入：

08_测试相关/

适合存放：

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

推荐命名：

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

新增后应同步维护：

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

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

5.5 业务流程文档

放入：

01_业务流程/

适合存放：

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

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

5.6 模板文档

放入：

03_规范与模板/

适合存放：

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

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

5.7 归档文档

放入：

99_归档/

适合存放：

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

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

6. Agent 检索优先级

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

05_需求文档/：正式需求、业务规则、需求变更。
06_里程碑/：项目节点、阶段计划、阶段评审、上线节奏。
07_技术文档/：系统架构、数据模型、接口说明、实现方案、技术决策。
08_测试相关/：测试计划、测试用例、缺陷记录、验收记录、上线检查。
02_项目管理流程/：内部系统开发流程、阶段、角色、门禁、交付物、检查清单。
01_业务流程/：真实业务流程、业务对象、业务规则。
04_Agent检索/：关键词、同义词、来源索引、回答规则。
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. 新增文档标准流程

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

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

9. 推荐 Frontmatter

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

---
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 需求索引

新增需求文档后，维护：

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

至少登记：

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

11.2 里程碑索引

新增里程碑后，维护：

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

至少登记：

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

11.3 技术文档索引

新增技术文档后，维护：

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

至少登记：

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

11.4 测试用例索引

新增测试用例后，维护：

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

至少登记：

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

12. Obsidian 链接规则

推荐使用 Obsidian 双链：

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

也可以使用 Markdown 链接：

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

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

13. Obsidian 图谱说明

Obsidian 图谱会显示两类节点：

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

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

示例：

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

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

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

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

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

14. 知识地图维护规则

知识地图文件：

00_首页/知识地图.md

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

推荐主结构：

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

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

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

15. Agent 回答规则

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

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

推荐引用格式：

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

16. 测试用例管理要求

测试用例应单独存放在：

08_测试相关/

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

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

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

17. 文档关系建议

推荐建立以下关系：

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

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

示例：

## 关联文档

- 需求来源：[[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 回答错了怎么办？

优先检查：

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

必要时更新：

21. 维护原则

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

16 KiB Raw Permalink Blame History Unescape Escape

如愿知识库使用说明

1. 知识库定位

2. 推荐打开方式

3. 主目录说明

4. 日常使用入口

5. 文档应该放在哪里

5.1 需求文档

5.2 里程碑文档

5.3 技术文档

5.4 测试相关文档

5.5 业务流程文档

5.6 模板文档

5.7 归档文档

6. Agent 检索优先级

7. 不同问题应该查哪里

8. 新增文档标准流程

9. 推荐 Frontmatter

10. 文档状态说明

11. 索引维护规则

11.1 需求索引

11.2 里程碑索引

11.3 技术文档索引

11.4 测试用例索引

12. Obsidian 链接规则

13. Obsidian 图谱说明

14. 知识地图维护规则

15. Agent 回答规则

16. 测试用例管理要求

17. 文档关系建议

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

19. 提交前检查清单

20. 常见问题

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

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

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

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

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

20.6 Agent 回答错了怎么办？

21. 维护原则

16 KiB

Raw Permalink Blame History