diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 6827bd5..ebaced2 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -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", diff --git a/00_首页/知识地图.md b/00_首页/知识地图.md index 5a5ce10..f008c77 100644 --- a/00_首页/知识地图.md +++ b/00_首页/知识地图.md @@ -10,6 +10,11 @@ updated: 2026-05 # 知识地图 +## 使用说明 + +- [[../知识库使用说明|知识库使用说明]] +- [[../Git使用说明|Git 使用说明]] + ## 需求文档 - [[../05_需求文档/README|需求文档入口]] diff --git a/00_首页/知识库首页.md b/00_首页/知识库首页.md index 145e172..25d0e56 100644 --- a/00_首页/知识库首页.md +++ b/00_首页/知识库首页.md @@ -14,6 +14,7 @@ updated: 2026-05 ## 快速入口 +- [[../知识库使用说明|知识库使用说明]] - [[知识地图]] - [[Agent问答入口]] - [[../05_需求文档/README|需求文档]] diff --git a/Git使用说明.md b/Git使用说明.md deleted file mode 100644 index 5edd798..0000000 --- a/Git使用说明.md +++ /dev/null @@ -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 回答必须说明来源文件。 diff --git a/欢迎.md b/欢迎.md index 479fc72..36811e9 100644 --- a/欢迎.md +++ b/欢迎.md @@ -14,6 +14,7 @@ updated: 2026-05 常用入口： +- [[知识库使用说明]] - [[00_首页/知识地图]] - [[00_首页/Agent问答入口]] - [[05_需求文档/README|需求文档]] diff --git a/知识库使用说明.md b/知识库使用说明.md new file mode 100644 index 0000000..f8b4d6f --- /dev/null +++ b/知识库使用说明.md @@ -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. 知识库持续维护比一次性整理更重要。