qiaoxinjiu/Fulfilled-Knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新知识库使用说明

Browse Source
This commit is contained in:
qiaoxinjiu
2026-05-26 15:40:01 +08:00
parent 0e85cb0d10
commit 96982ce5cf
6 changed files with 676 additions and 370 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.obsidian/workspace.json vendored
View File

@@ -13,12 +13,12 @@
"state": {
"type": "markdown",
"state": {
"file": "05_需求文档/20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3.md",
"file": "02_项目管理流程/AI驱动内部系统开发流程_V3_总览.md",
"mode": "source",
"source": false
},
"icon": "lucide-file",
"title": "20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3"
"title": "AI驱动内部系统开发流程_V3_总览"
}
}
]
@@ -94,7 +94,7 @@
"state": {
"type": "backlink",
"state": {
"file": "05_需求文档/20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3.md",
"file": "02_项目管理流程/AI驱动内部系统开发流程_V3_总览.md",
"collapseAll": false,
"extraContext": false,
"sortOrder": "alphabetical",
@@ -104,7 +104,7 @@
"unlinkedCollapsed": true
},
"icon": "links-coming-in",
"title": "20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3 的反向链接列表"
"title": "AI驱动内部系统开发流程_V3_总览 的反向链接列表"
}
},
{
@@ -113,12 +113,12 @@
"state": {
"type": "outgoing-link",
"state": {
"file": "05_需求文档/20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3.md",
"file": "02_项目管理流程/AI驱动内部系统开发流程_V3_总览.md",
"linksCollapsed": false,
"unlinkedCollapsed": true
},
"icon": "links-going-out",
"title": "20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3 的出链列表"
"title": "AI驱动内部系统开发流程_V3_总览 的出链列表"
}
},
{
@@ -156,13 +156,13 @@
"state": {
"type": "outline",
"state": {
"file": "05_需求文档/20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3.md",
"file": "02_项目管理流程/AI驱动内部系统开发流程_V3_总览.md",
"followCursor": false,
"showSearch": false,
"searchQuery": ""
},
"icon": "lucide-list",
"title": "20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3 的大纲"
"title": "AI驱动内部系统开发流程_V3_总览 的大纲"
}
}
]
@@ -185,11 +185,11 @@
},
"active": "ff990f59633b7f33",
"lastOpenFiles": [
"Git使用说明.md",
"00_首页/知识地图.md",
"05_需求文档/20260517_USER评价业务闭环_第三步_数据流与中间对象设计_v3.md",
"Git使用说明.md",
"02_项目管理流程/AI驱动内部系统开发流程_V3_总览.md",
"20260517_USER评价业务闭环_共用能力图与渠道专属流程_v2.2.md",
"00_首页/知识地图.md",
"未命名.canvas",
"08_测试相关/上线检查模板.md",
"08_测试相关/验收记录模板.md",

5
00_首页/知识地图.md
View File

@@ -10,6 +10,11 @@ updated: 2026-05
# 知识地图
## 使用说明
- [[../知识库使用说明|知识库使用说明]]
- [[../Git使用说明|Git 使用说明]]
## 需求文档
- [[../05_需求文档/README|需求文档入口]]

1
00_首页/知识库首页.md
View File

@@ -14,6 +14,7 @@ updated: 2026-05
## 快速入口
- [[../知识库使用说明|知识库使用说明]]
- [[知识地图]]
- [[Agent问答入口]]
- [[../05_需求文档/README|需求文档]]

360
Git使用说明.md
View File

@@ -1,360 +0,0 @@
---
type: git_guide
tags: [Git, 版本管理, 知识库, 使用说明]
aliases: [Git说明, 仓库使用说明, 知识库提交说明]
source: manual
status: active
owner: 内部技术团队
updated: 2026-05
---
# Git 使用说明
本文档说明如愿知识库的 Git 仓库地址、目录结构、日常提交流程、多人协作规则和 Obsidian 图谱注意事项。
## 1. 仓库信息
远程仓库地址：
```bash
https://wdxz-gitea.best-envision.com/qiaoxinjiu/Fulfilled-Knowledge.git
```
本地知识库目录：
```text
D:\AIcoding\WishFulfilled\知识库\如愿知识库
```
推荐使用 Obsidian 打开该目录作为 Vault。
## 2. 知识库主目录说明
```text
如愿知识库/
├─ 00_首页/ # 知识库入口、知识地图、Agent 问答入口
├─ 01_业务流程/ # 业务流程、业务对象、业务规则、补充验证记录
├─ 02_项目管理流程/ # 项目阶段、角色职责、交付物、检查清单、FAQ
├─ 03_规范与模板/ # 需求、业务规则、会议、上线检查等模板
├─ 04_Agent检索/ # 检索说明、关键词、同义词、来源文件索引
├─ 05_需求文档/ # 正式需求文档、需求索引
├─ 06_里程碑/ # 里程碑计划、阶段计划、评审记录
├─ 07_技术文档/ # 技术方案、架构、接口、技术决策
├─ 08_测试相关/ # 测试用例、测试计划、缺陷、验收、上线检查
├─ 99_归档/ # 废弃或历史参考内容
├─ 欢迎.md # Obsidian 入口
└─ Git使用说明.md # 本文档
```
## 3. 推荐阅读入口
首次使用时建议按以下顺序阅读：
1. `欢迎.md`
2. `00_首页/知识库首页.md`
3. `00_首页/知识地图.md`
4. `00_首页/Agent问答入口.md`
5. `04_Agent检索/检索说明.md`
6. `04_Agent检索/来源文件索引.md`
## 4. Agent 检索优先级
Agent 回答问题时，建议按以下顺序检索：
1. `05_需求文档/`：正式需求、业务规则、需求变更。
2. `06_里程碑/`：阶段节点、项目计划、评审记录。
3. `07_技术文档/`：架构、接口、实现方案、技术决策。
4. `08_测试相关/`：测试用例、测试计划、缺陷、验收、上线检查。
5. `02_项目管理流程/`：项目阶段、角色、交付物、门禁、检查清单。
6. `01_业务流程/`：业务流程、业务对象、业务规则。
7. `04_Agent检索/`：关键词、同义词、来源索引、回答规则。
8. `03_规范与模板/`：需要产出模板或文档时使用。
回答业务问题时，必须注明来源文件。
## 5. 新增文档规则
### 5.1 新增需求文档
放入目录：
```text
05_需求文档/
```
推荐命名：
```text
业务域_需求或规则名称_YYYYMMDD.md
```
新增后同步维护：
- `05_需求文档/需求文档索引.md`
- `01_业务流程/业务规则索引.md`
- `01_业务流程/业务对象字典.md`
- `04_Agent检索/关键词索引.md`
- `04_Agent检索/同义词表.md`
- `04_Agent检索/来源文件索引.md`
### 5.2 新增里程碑文档
放入目录：
```text
06_里程碑/
```
推荐命名：
```text
项目名_里程碑计划_YYYYMMDD.md
项目名_阶段评审记录_YYYYMMDD.md
```
新增后同步维护：
- `06_里程碑/里程碑索引.md`
- `00_首页/知识地图.md`，如需新增主入口或二级入口。
### 5.3 新增技术文档
放入目录：
```text
07_技术文档/
```
推荐命名：
```text
系统或模块_技术方案_YYYYMMDD.md
系统或模块_接口说明_YYYYMMDD.md
系统或模块_数据模型_YYYYMMDD.md
```
新增后同步维护：
- `07_技术文档/技术文档索引.md`
- `04_Agent检索/关键词索引.md`
- `04_Agent检索/来源文件索引.md`
### 5.4 新增测试用例
放入目录：
```text
08_测试相关/
```
推荐命名：
```text
项目名_模块名_测试用例_YYYYMMDD.md
项目名_模块名_测试计划_YYYYMMDD.md
项目名_模块名_缺陷记录_YYYYMMDD.md
```
新增后同步维护：
- `08_测试相关/测试用例索引.md`
- `08_测试相关/测试计划模板.md`，如计划结构发生变化。
- `08_测试相关/缺陷记录模板.md`，如缺陷字段发生变化。
## 6. Obsidian 图谱说明
Obsidian 图谱会显示两类节点：
1. 已存在的 Markdown 文件。
2. 文档中链接到、但本地还不存在的 Markdown 文件。
例如文档中存在：
```markdown
[工作基线 v1.2](20260517_USER评价业务闭环主流程与后续工作基线_v1.2.md)
```
即使该文件还没有放入目录，Obsidian 图谱也可能显示这个节点。这是“未创建链接 / dangling link”，不是目录里真的多了文件。
如果只想显示真实存在的文件，可以在 Obsidian 图谱里开启：
```text
图谱视图 → 筛选 → 仅显示已有文件
```
如果希望知识链路完整，应把被引用的上游文档也补充到对应目录。
## 7. 首次拉取仓库
在目标目录执行：
```bash
git clone https://wdxz-gitea.best-envision.com/qiaoxinjiu/Fulfilled-Knowledge.git
```
然后用 Obsidian 打开克隆出的目录。
## 8. 日常更新流程
### 8.1 拉取最新内容
开始编辑前先拉取远程更新：
```bash
git pull origin master
```
如果主分支后续改名为 `main`，则使用：
```bash
git pull origin main
```
### 8.2 查看变更
```bash
git status
```
### 8.3 暂存变更
提交全部变更：
```bash
git add .
```
只提交指定文件：
```bash
git add 05_需求文档/需求文档索引.md
```
### 8.4 提交变更
提交信息建议包含动作和范围：
```bash
git commit -m "docs: 更新需求文档索引"
```
常用提交前缀：
| 前缀 | 用途 |
|---|---|
| `docs:` | 文档新增或修改 |
| `chore:` | 目录、配置、维护性调整 |
| `fix:` | 修正文档错误、链接错误 |
| `refactor:` | 调整结构但不改变内容含义 |
| `archive:` | 归档历史内容 |
### 8.5 推送到远程
```bash
git push origin master
```
如果主分支为 `main`，则使用：
```bash
git push origin main
```
## 9. 推荐的完整提交流程
```bash
git pull origin master
git status
git add .
git commit -m "docs: 更新如愿知识库"
git push origin master
```
## 10. 冲突处理原则
多人同时修改同一个文档时，可能出现冲突。
处理原则：
1. 不要直接覆盖别人内容。
2. 先阅读冲突区块。
3. 保留双方有效内容。
4. 删除 Git 冲突标记。
5. 再执行提交。
冲突标记示例：
```text
<<<<<<< HEAD
本地内容
=======
远程内容
>>>>>>> origin/master
```
处理完成后：
```bash
git add 冲突文件.md
git commit -m "fix: 解决知识库文档冲突"
git push origin master
```
## 11. 不建议提交的内容
一般不建议提交：
- 临时截图。
- 临时导出文件。
- 个人草稿。
- 含账号、密码、Token、密钥的文件。
- 含客户隐私或敏感原文的未脱敏文件。
如需沉淀敏感业务规则，应先脱敏，再放入知识库。
## 12. 提交前检查清单
提交前确认：
- [ ] 新文档放在正确目录。
- [ ] 文件名清晰，能表达业务域和用途。
- [ ] 重要文档已写 Frontmatter。
- [ ] 新增需求已维护 `05_需求文档/需求文档索引.md`。
- [ ] 新增测试用例已维护 `08_测试相关/测试用例索引.md`。
- [ ] 新增技术文档已维护 `07_技术文档/技术文档索引.md`。
- [ ] 需要 Agent 检索的关键词已同步到 `04_Agent检索/关键词索引.md`。
- [ ] 链接能正常跳转，或确认它是故意保留的上游虚链接。
- [ ] 不包含密码、Token、密钥和未脱敏敏感数据。
## 13. 常见问题
### 13.1 为什么我只放了一个文档，图谱里出现多个节点？
因为文档中引用了其他 Markdown 文件。Obsidian 会把被链接但尚未创建的文件也显示为节点。
解决方式：
- 图谱开启“仅显示已有文件”。
- 或补齐被引用的上游文档。
### 13.2 README.md 为什么也会出现在图谱里？
因为 README.md 也是 Markdown 文件，Obsidian 会把它作为普通节点显示。
### 13.3 删除文件后图谱还有节点怎么办？
检查是否仍有其他文档链接到该文件。只要有链接，图谱仍可能显示虚节点。
### 13.4 Agent 回答问题应该依赖哪个目录？
优先依赖 `05_需求文档/`，其次是 `06_里程碑/`、`07_技术文档/`、`08_测试相关/`，再查流程、业务和检索规则目录。
## 14. 维护原则
1. 知识库不是文件堆积，而是可检索、可追溯、可回答的知识网络。
2. 正式需求必须有索引。
3. 关键业务规则必须有来源。
4. 测试用例必须能追溯到需求。
5. 技术文档必须能追溯到需求或业务流程。
6. 里程碑必须能追溯到阶段目标和交付物。
7. Agent 回答必须说明来源文件。

1
欢迎.md
View File

@@ -14,6 +14,7 @@ updated: 2026-05
常用入口：
- [[知识库使用说明]]
- [[00_首页/知识地图]]
- [[00_首页/Agent问答入口]]
- [[05_需求文档/README|需求文档]]

659
知识库使用说明.md Normal file
View File

@@ -0,0 +1,659 @@
---
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. 知识库持续维护比一次性整理更重要。