Fulfilled-Knowledge/Git使用说明.md

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

type	tags	aliases	source	status	owner	updated
git_guide	Git 版本管理 知识库 使用说明	Git说明 仓库使用说明 知识库提交说明	manual	active	内部技术团队	2026-05

Git 使用说明

本文档说明如愿知识库的 Git 仓库地址、目录结构、日常提交流程、多人协作规则和 Obsidian 图谱注意事项。

1. 仓库信息

远程仓库地址：

https://wdxz-gitea.best-envision.com/qiaoxinjiu/Fulfilled-Knowledge.git

本地知识库目录：

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

推荐使用 Obsidian 打开该目录作为 Vault。

2. 知识库主目录说明

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

放入目录：

05_需求文档/

推荐命名：

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

新增后同步维护：

• 05_需求文档/需求文档索引.md
• 01_业务流程/业务规则索引.md
• 01_业务流程/业务对象字典.md
• 04_Agent检索/关键词索引.md
• 04_Agent检索/同义词表.md
• 04_Agent检索/来源文件索引.md

5.2 新增里程碑文档

放入目录：

06_里程碑/

推荐命名：

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

新增后同步维护：

• 06_里程碑/里程碑索引.md
• 00_首页/知识地图.md，如需新增主入口或二级入口。

5.3 新增技术文档

放入目录：

07_技术文档/

推荐命名：

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

新增后同步维护：

• 07_技术文档/技术文档索引.md
• 04_Agent检索/关键词索引.md
• 04_Agent检索/来源文件索引.md

5.4 新增测试用例

放入目录：

08_测试相关/

推荐命名：

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

新增后同步维护：

• 08_测试相关/测试用例索引.md
• 08_测试相关/测试计划模板.md，如计划结构发生变化。
• 08_测试相关/缺陷记录模板.md，如缺陷字段发生变化。

6. Obsidian 图谱说明

Obsidian 图谱会显示两类节点：

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

例如文档中存在：

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

即使该文件还没有放入目录，Obsidian 图谱也可能显示这个节点。这是“未创建链接 / dangling link”，不是目录里真的多了文件。

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

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

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

7. 首次拉取仓库

在目标目录执行：

git clone https://wdxz-gitea.best-envision.com/qiaoxinjiu/Fulfilled-Knowledge.git

然后用 Obsidian 打开克隆出的目录。

8. 日常更新流程

8.1 拉取最新内容

开始编辑前先拉取远程更新：

git pull origin master

如果主分支后续改名为 main，则使用：

git pull origin main

8.2 查看变更

git status

8.3 暂存变更

提交全部变更：

git add .

只提交指定文件：

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

8.4 提交变更

提交信息建议包含动作和范围：

git commit -m "docs: 更新需求文档索引"

常用提交前缀：

前缀	用途
docs:	文档新增或修改
chore:	目录、配置、维护性调整
fix:	修正文档错误、链接错误
refactor:	调整结构但不改变内容含义
archive:	归档历史内容

8.5 推送到远程

git push origin master

如果主分支为 main，则使用：

git push origin main

9. 推荐的完整提交流程

git pull origin master
git status
git add .
git commit -m "docs: 更新如愿知识库"
git push origin master

10. 冲突处理原则

多人同时修改同一个文档时，可能出现冲突。

处理原则：

1. 不要直接覆盖别人内容。
2. 先阅读冲突区块。
3. 保留双方有效内容。
4. 删除 Git 冲突标记。
5. 再执行提交。

冲突标记示例：

<<<<<<< HEAD
本地内容
=======
远程内容
>>>>>>> origin/master

处理完成后：

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 回答必须说明来源文件。