626 lines
14 KiB
Markdown
626 lines
14 KiB
Markdown
# Git 使用细则（团队开发版）
|
||
|
||
> 本文档用于 Notes Agent 团队日常开发。目标是让三名成员可以并行开发、稳定联调，并确保 `main` 始终处于可运行状态。
|
||
|
||
> 更新日期：2026-09-01。当前远程只使用 `gitea`，功能分支不添加个人或工具名称前缀；合并门槛为相关测试、前端生产构建、文档同步和 `git diff --check` 全部通过。自动化门禁、产物和发布规则见 [CI/CD 细则](CI-CD细则-团队开发版.md)。
|
||
|
||
## 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 与文档。流水线启用后，合并和发布还必须满足 [CI/CD 细则](CI-CD细则-团队开发版.md) 中的状态检查与产物要求。
|