# Git 使用细则（团队开发版）

> 本文档用于 Notes Agent 团队日常开发。目标是让三名成员可以并行开发、稳定联调，并确保 `main` 始终处于可运行状态。

> 更新日期：2026-08-30。当前远程只使用 `gitea`，功能分支不添加个人或工具名称前缀；合并门槛为相关测试、前端生产构建、文档同步和 `git diff --check` 全部通过。

## 1. 仓库与远程

团队代码统一使用 Gitea：

```text
remote: gitea
url:    https://gitea.kronecker.cc/Kronecker/NotesAgentic.git
```

检查远程：

```powershell
git remote -v
```

正常情况下只应存在 `gitea`。不要自行增加名称相同、地址不同的远程，也不要将团队代码推送到个人公开仓库。

## 2. 分支约定

### 2.1 长期分支

| 分支 | 用途 | 规则 |
| --- | --- | --- |
| `main` | 团队集成与演示版本 | 必须可安装、可构建、可运行；禁止直接开发 |

当前阶段不额外维护 `develop`。三人团队通过短生命周期功能分支和 Gitea Pull Request 合入 `main`，减少长期分支之间的同步成本。

### 2.2 功能分支

命名格式：

```text
<类型>/<模块>-<简短描述>
```

类型：

```text
feat      新功能
fix       Bug 修复
refactor  不改变功能的重构
docs      文档
test      测试
chore     构建、依赖、工程配置
hotfix    main 上紧急修复
```

示例：

```text
feat/frontend-workspace
feat/agent-tool-registry
feat/retrieval-hybrid-search
fix/frontend-sse-reconnect
fix/agent-permission-timeout
docs/api-contract
chore/backend-dependencies
```

要求：

- 使用英文小写、数字和连字符；
- 分支名应表达模块和目标；
- 一个分支只处理一个主要问题；
- 不使用 `test1`、`new`、`final`、`xxx-dev` 等无法识别用途的名称；
- 功能合入后删除远程分支，避免长期堆积。
- 不在分支名前添加 `codex/`、成员姓名或设备名；归属由提交作者、Issue 和 PR Reviewer 表达。

## 3. 模块分工与改动边界

| 成员 | 主要目录或模块 | Review 要求 |
| --- | --- | --- |
| 吉海燕 | `frontend`、UI、Store、Service、Design Token | 跨 API Contract 时邀请范涵宇 |
| 范涵宇 | `backend` 中的 Agent、Provider、Skill、Plugin、公共 API 和工程集成 | 核心接口与跨模块变更负责 Review |
| 杨星萱 | Knowledge、Retrieval、SQLite/FTS5、Vector、RAG、Citation | 涉及前端定位时邀请吉海燕，涉及 Agent Tool 时邀请范涵宇 |

边界不是文件所有权锁。确实需要修改其他成员负责的模块时：

1. 先在群里或 Issue 中说明原因；
2. 将跨模块修改拆成容易 Review 的提交；
3. Pull Request 必须邀请对应负责人；
4. 同步更新 Contract、测试和文档。

禁止为了临时联调直接绕过其他模块的接口访问数据库、文件或 Store 内部状态。

## 4. 开始开发前

每项工作从最新的 `main` 创建分支：

```powershell
git switch main
git fetch gitea
git pull --ff-only gitea main
git switch -c feat/agent-example
```

说明：

- `git fetch` 获取远程状态，但不修改工作区；
- `git pull --ff-only` 只允许快进，避免在 `main` 上产生意外 Merge Commit；
- 创建分支前先确认 `git status` 干净；
- 不要在已有未提交修改时随意切换分支。

检查：

```powershell
git status
git branch --show-current
```

## 5. 开发中的提交

### 5.1 提交原则

- 小步提交，每个提交只表达一个完整意图；
- 功能代码、测试和必要文档一起提交；
- 不提交无法运行的临时状态到共享分支；
- 不用一次提交混合前端格式化、后端功能和无关文档修改；
- 提交前检查实际 diff，不使用不加检查的 `git add .` 作为固定习惯。

推荐流程：

```powershell
git status --short
git diff
git add backend/app/agent backend/tests/test_agent_core.py
git diff --cached
git commit -m "feat(agent): 增加 Tool Registry"
```

需要提交所有确认过的修改时可以使用：

```powershell
git add -A
git diff --cached
```

`git diff --cached` 无异常后再提交。

### 5.2 Commit Message

格式：

```text
<类型>(<模块>): <简短说明>
```

示例：

```text
feat(agent): 增加 Tool 参数校验
feat(provider): 接入 Ollama Adapter
feat(frontend): 完成 Citation 定位交互
fix(retrieval): 修复 RRF 排名重复项
test(agent): 补充 Step Limit 测试
docs(api): 更新 Provider 接口契约
chore(frontend): 更新 Vite 依赖
```

常用模块：

```text
frontend
workspace
editor
search
chat
agent
provider
skill
plugin
retrieval
knowledge
api
docs
build
```

要求：

- 第一行建议不超过 72 个字符；
- 使用动词说明这次提交完成了什么；
- 不使用“修改一下”“update”“最终版”“fix bug”等模糊描述；
- 一个提交包含多个需要解释的变化时，在空行后补充正文；
- 关联 Issue 时可在正文写 `Refs #编号`，确认修复后写 `Closes #编号`。

示例：

```text
feat(agent): 增加高风险 Tool 权限确认

支持 allow_once、allow_session 和 deny，并在等待期间
将 Agent Run 状态更新为 waiting_permission。

Closes #18
```

## 6. 提交前检查

### 6.1 通用检查

```powershell
git status --short
git diff --check
```

确认：

- 没有 API Key、Token、密码、真实用户笔记或个人路径；
- 没有调试输出、临时代码和无关格式化；
- 没有误删其他成员的改动；
- 新增接口同时更新了 Contract 和文档；
- 错误信息中不包含 Secret 或完整笔记正文。

### 6.2 后端检查

```powershell
cd backend
uv sync
uv run pytest
```

后端依赖变化时必须同时提交：

```text
backend/pyproject.toml
backend/uv.lock
```

### 6.3 前端检查

```powershell
cd frontend
pnpm install
pnpm build
```

前端依赖变化时必须同时提交：

```text
frontend/package.json
frontend/pnpm-lock.yaml
```

禁止同时生成或提交 npm、yarn 的锁文件。

## 7. 禁止提交的内容

以下内容不得进入仓库：

```text
backend/.venv/
backend/.uv-cache/
backend/.pytest_cache/
backend/**/__pycache__/
backend/*.egg-info/
backend/.env
frontend/node_modules/
frontend/dist/
.pnpm-store/
*.tsbuildinfo
.idea/
.vscode/
```

另外禁止提交：

- API Key、同步 Token、Cookie、私钥和 Stronghold 导出数据；
- 个人 Vault、真实笔记、音频、课堂资料和聊天记录；
- `.ainote/app.db`、本地索引、Embedding 和模型文件；
- 未经团队确认的大文件、二进制安装包和模型权重；
- 只在个人电脑有效的绝对路径；
- 临时日志和包含正文的调试数据。

发现 Secret 已经提交时，不要只删除文件后再次提交。立即通知团队，撤销或轮换凭证，并根据是否已推送决定是否清理历史。

## 8. 推送功能分支

第一次推送：

```powershell
git push -u gitea feat/agent-example
```

之后：

```powershell
git push
```

推送前确认：

```powershell
git status
git log --oneline -5
```

不要将个人功能分支强制推送到 `main`。

## 9. Gitea Pull Request

功能通过 Pull Request 合入 `main`。Pull Request 标题沿用 Commit Message 风格：

```text
feat(agent): 完成基础 Agent Loop
```

### 9.1 Pull Request 描述

建议使用以下结构：

```markdown
## 改动内容

- 

## 影响模块

- 

## 验证方式

- [ ] 后端 pytest 通过
- [ ] 前端 build 通过
- [ ] 手动联调通过

## 接口或数据变更

- 无 / 具体说明

## 风险与恢复

- 

## 关联 Issue

- Closes #
```

### 9.2 Pull Request 大小

- 优先保持在 Reviewer 可以一次理解的范围；
- 大功能按 Contract、核心实现、页面接入等阶段拆分；
- 纯机械格式化与功能修改分开；
- 如果必须提交较大 PR，在描述中提供阅读顺序。

### 9.3 Review 要求

- 至少一名其他成员 Review 后再合入；
- 公共 API、Agent、Provider、Skill、Plugin 或工程结构变更由范涵宇 Review；
- 前端交互和 Design Token 变更由吉海燕 Review；
- Knowledge、Retrieval、Citation 和索引变更由杨星萱 Review；
- 作者自己不能作为唯一批准人；
- Review 意见解决后，由提出者确认或作者说明处理方式。

Reviewer 检查：

```text
功能是否符合分工与需求
依赖方向是否正确
Contract 是否同步
是否包含测试
错误与恢复是否明确
是否泄露敏感信息
是否误改其他模块
是否影响现有 Demo 流程
```

## 10. 合并策略

功能 PR 默认使用 `Squash Merge` 合入 `main`：

- 一个 PR 在 `main` 中保留一个清晰提交；
- Squash Commit 标题使用规范的提交格式；
- 合并前确认 CI 或本地验证通过；
- 合并后删除功能分支。

不要在 Gitea 上选择会产生大量无意义 Merge Commit 的方式。确实需要保留多提交历史的较大集成工作，由团队讨论后使用普通 Merge。

`main` 建议在 Gitea 开启：

```text
禁止 Force Push
禁止删除分支
要求 Pull Request
要求至少 1 人批准
要求检查通过后合并
```

## 11. 同步 main

功能分支开发期间应定期同步：

```powershell
git fetch gitea
git rebase gitea/main
```

只在自己的功能分支上执行 rebase。Rebase 后如果该分支已经推送，需要：

```powershell
git push --force-with-lease
```

只能使用 `--force-with-lease`，禁止使用普通 `--force`。禁止重写其他成员正在使用的分支或 `main` 历史。

如果团队成员对 rebase 不熟悉，可以使用合并方式同步：

```powershell
git fetch gitea
git merge gitea/main
```

同一个 Pull Request 中不要反复混用 rebase 和 merge。

## 12. 冲突处理

### 12.1 Rebase 冲突

```powershell
git fetch gitea
git rebase gitea/main
git status
```

逐个打开冲突文件，理解双方修改后手工合并。处理完成：

```powershell
git add <冲突文件>
git rebase --continue
```

无法确认时终止操作：

```powershell
git rebase --abort
```

### 12.2 冲突原则

- 不使用“全部接受当前”或“全部接受传入”处理不理解的冲突；
- 涉及他人模块时联系对应负责人；
- `pyproject.toml`、`package.json` 冲突解决后重新生成并验证锁文件；
- API Contract 冲突需要同时检查前端 TypeScript 类型和接口文档；
- 文档冲突不能简单保留较新的文件，需要合并双方有效内容；
- 冲突解决后重新运行相关测试。

## 13. 修正提交

### 13.1 尚未推送

只修正最近一次提交：

```powershell
git add <文件>
git commit --amend
```

### 13.2 已经推送或进入 Review

优先新增修正提交：

```powershell
git commit -m "fix(agent): 修正权限超时状态"
git push
```

Reviewer 确认后由 Squash Merge 整理历史。不要为了“历史好看”随意重写其他成员已经拉取的提交。

## 14. 撤销与恢复

### 14.1 撤销已合入 main 的提交

使用 `git revert` 创建反向提交：

```powershell
git switch main
git pull --ff-only gitea main
git switch -c fix/revert-problem
git revert <commit-id>
git push -u gitea fix/revert-problem
```

随后创建 Pull Request。不要对共享 `main` 使用 `git reset --hard` 或重写历史。

### 14.2 放弃尚未提交的修改

先检查：

```powershell
git status
git diff
```

放弃修改会丢失本地内容，必须确认目标文件和影响范围。拿不准时先创建临时分支或使用 stash：

```powershell
git stash push -u -m "wip: 临时保存说明"
```

恢复：

```powershell
git stash list
git stash pop
```

Stash 只用于短期切换，不作为长期备份。

## 15. Hotfix

影响 `main` 启动、数据安全或 Demo 的紧急问题使用：

```powershell
git switch main
git pull --ff-only gitea main
git switch -c hotfix/<模块>-<问题>
```

Hotfix 仍需：

- 最小化修改范围；
- 添加回归测试；
- 至少一人快速 Review；
- 合入后通知全员同步 `main`；
- 后续补充问题原因和预防措施。

## 16. Issue 与里程碑

建议每项跨一天或跨模块的任务先建立 Gitea Issue，至少包含：

```text
目标
负责人
涉及模块
验收条件
依赖项
优先级
```

标签建议：

```text
frontend
backend
agent
provider
knowledge
retrieval
extension
bug
documentation
P0 / P1 / P2
```

Pull Request 关联 Issue，避免功能完成后无法对应需求和验收条件。

## 17. Release 与 Tag

比赛开发阶段使用语义化版本：

```text
v0.1.0  第一个可运行壳子
v0.2.0  第一条完整知识问答链路
v0.3.0  第一阶段 Demo 候选版本
v1.0.0  稳定交付版本
```

Tag 只从验证通过的 `main` 创建：

```powershell
git switch main
git pull --ff-only gitea main
git tag -a v0.2.0 -m "Notes Agent v0.2.0"
git push gitea v0.2.0
```

创建 Tag 前记录：

- 功能范围；
- 已知问题；
- 数据库或配置迁移；
- 测试结果；
- Demo 操作步骤。

## 18. 每日推荐流程

```text
同步 main
→ 创建或切换自己的功能分支
→ 开发并小步提交
→ 同步 main 并解决冲突
→ 运行相关测试
→ 检查 staged diff
→ 推送功能分支
→ 创建 Pull Request
→ Review 与修正
→ Squash Merge
→ 删除功能分支
→ 全员同步 main
```

常用命令汇总：

```powershell
git status --short
git fetch gitea
git switch main
git pull --ff-only gitea main
git switch -c feat/<模块>-<功能>
git diff
git add <文件>
git diff --cached
git commit -m "feat(<模块>): <说明>"
git push -u gitea <分支名>
git log --oneline --decorate -10
```

本细则的核心要求是：`main` 可运行、改动可 Review、问题可追踪、敏感信息不入库、跨模块变化同步 Contract 与文档。