docs: 初始化如愿知识库

2026-05-26 15:08:20 +08:00
commit 0e85cb0d10
59 changed files with 4371 additions and 0 deletions
--- a/Git使用说明.md
+++ b/Git使用说明.md
@@ -0,0 +1,360 @@
+---
+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 回答必须说明来源文件。