Fulfilled-Knowledge/Git使用说明.md

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