docs: 重组文档目录并补充CI/CD细则

2026-09-01 09:55:40 +08:00
parent 49dbacb296
commit a5b709a46f
23 changed files with 263 additions and 37 deletions
@@ -0,0 +1,625 @@
+# 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) 中的状态检查与产物要求。