NotesAgentic/docs/Git使用细则-团队开发版.md

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

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

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

1. 仓库与远程

团队代码统一使用 Gitea：

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

检查远程：

git remote -v

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

2. 分支约定

2.1 长期分支

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

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

2.2 功能分支

命名格式：

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

类型：

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

示例：

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 创建分支：

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 干净；
• 不要在已有未提交修改时随意切换分支。

检查：

git status
git branch --show-current

5. 开发中的提交

5.1 提交原则

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

推荐流程：

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"

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

git add -A
git diff --cached

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

5.2 Commit Message

格式：

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

示例：

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

常用模块：

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

要求：

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

示例：

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

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

Closes #18

6. 提交前检查

6.1 通用检查

git status --short
git diff --check

确认：

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

6.2 后端检查

cd backend
uv sync
uv run pytest

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

backend/pyproject.toml
backend/uv.lock

6.3 前端检查

cd frontend
pnpm install
pnpm build

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

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

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

7. 禁止提交的内容

以下内容不得进入仓库：

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. 推送功能分支

第一次推送：

git push -u gitea feat/agent-example

之后：

git push

推送前确认：

git status
git log --oneline -5

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

9. Gitea Pull Request

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

feat(agent): 完成基础 Agent Loop

9.1 Pull Request 描述

建议使用以下结构：

## 改动内容

- 

## 影响模块

- 

## 验证方式

- [ ] 后端 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 检查：

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

10. 合并策略

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

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

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

main 建议在 Gitea 开启：

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

11. 同步 main

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

git fetch gitea
git rebase gitea/main

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

git push --force-with-lease

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

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

git fetch gitea
git merge gitea/main

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

12. 冲突处理

12.1 Rebase 冲突

git fetch gitea
git rebase gitea/main
git status

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

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

无法确认时终止操作：

git rebase --abort

12.2 冲突原则

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

13. 修正提交

13.1 尚未推送

只修正最近一次提交：

git add <文件>
git commit --amend

13.2 已经推送或进入 Review

优先新增修正提交：

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

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

14. 撤销与恢复

14.1 撤销已合入 main 的提交

使用 git revert 创建反向提交：

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 放弃尚未提交的修改

先检查：

git status
git diff

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

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

恢复：

git stash list
git stash pop

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

15. Hotfix

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

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

Hotfix 仍需：

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

16. Issue 与里程碑

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

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

标签建议：

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

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

17. Release 与 Tag

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

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

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

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. 每日推荐流程

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

常用命令汇总：

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 与文档。