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,166 @@
+# CI/CD 细则（团队开发版）
+
+> 本文档规定 NotesAgent 在 Gitea 上的持续集成、构建产物、发布和回滚要求。当前仓库尚未提交 Gitea Actions 工作流，因此本文首先作为落地流水线时的统一规范；流水线启用前，Pull Request 仍须人工执行同等检查。
+
+> 更新日期：2026-09-01。当前阶段的 CD 指“生成可验证的候选构建与发布产物”，不包含把后端自动部署到公网环境。
+
+## 1. 目标与原则
+
+CI/CD 用于尽早发现依赖锁文件失效、类型错误、测试回归、前后端契约不一致和生产构建失败。流水线应遵守以下原则：
+
+- 以 Gitea 为唯一远程和流水线入口；
+- `main` 始终保持可安装、可测试、可构建；
+- 安装依赖时使用锁文件，避免流水线与开发机解析出不同版本；
+- 未通过必需检查的提交不得合入 `main`；
+- 外部模型、真实 API Key 和用户本地数据不得成为基础 CI 的前置条件；
+- 缓存只用于加速，不得影响构建结果；删除缓存后流水线仍应成功；
+- 测试、构建和发布步骤使用最小权限，敏感信息不得写入日志或产物。
+
+## 2. 运行环境基线
+
+| 组件 | CI 要求 | 说明 |
+| --- | --- | --- |
+| Python | 3.12 | 项目最低支持 3.11，CI 使用团队推荐版本 |
+| uv | 当前稳定版，并在日志中输出版本 | 按 `backend/uv.lock` 安装后端依赖 |
+| Node.js | 22 LTS | 满足前端环境要求并保持 Runner 兼容性 |
+| pnpm | 10 | 按 `frontend/pnpm-lock.yaml` 安装前端依赖 |
+| 操作系统 | Linux Runner 为基础门禁 | 桌面端启用后再增加 Windows、macOS 构建矩阵 |
+
+Runner 镜像或 Action 的大版本必须固定。升级 Python、Node.js、uv、pnpm 或基础 Action 时，应使用独立的 `chore/` 分支，并完整运行前后端检查。
+
+## 3. 触发规则
+
+| 事件 | 必须执行 | 用途 |
+| --- | --- | --- |
+| Pull Request 指向 `main` | 文档检查、后端测试、前端测试、类型检查、生产构建 | 合并门禁 |
+| 推送到 `main` | 全量检查、集成冒烟、保存候选构建 | 验证合并结果 |
+| 推送功能分支 | 至少执行受影响模块的检查 | 尽早反馈；不得替代 PR 全量门禁 |
+| 推送 `v*` 标签 | 全量检查、构建、校验和、发布候选产物 | 正式发布入口 |
+| 手动触发 | 可选择全量回归或重新生成候选产物 | 发布前复核和故障恢复 |
+
+纯文档变更可以跳过前后端耗时任务，但必须执行文档链接检查和 `git diff --check`。只有可靠的路径检测结果才能判定为纯文档变更；锁文件、工作流、构建配置和接口契约变更一律按代码变更处理。
+
+## 4. Pull Request 必需检查
+
+建议将以下 Job 名称固定为 Gitea 分支保护所要求的状态检查：
+
+| Job | 必需命令或行为 | 通过标准 |
+| --- | --- | --- |
+| `docs-check` | `git diff --check`，检查仓库内 Markdown 相对链接 | 无空白错误、无失效本地链接 |
+| `backend-test` | `uv sync --frozen`、编译检查、`uv run pytest` | 依赖锁有效且测试全部通过 |
+| `frontend-test` | `pnpm install --frozen-lockfile`、`pnpm test` | 依赖锁有效且测试全部通过 |
+| `frontend-typecheck` | `pnpm type-check` | 无 TypeScript/Vue 类型错误 |
+| `frontend-build` | `pnpm build` | Vite 生产构建成功 |
+| `integration-smoke` | 启动 FastAPI，验证健康检查和关键本地链路 | 服务可启动，响应与契约符合预期 |
+
+后端 Job 的基准命令：
+
+```bash
+cd backend
+uv sync --frozen
+uv run python -m compileall -q app
+uv run pytest
+```
+
+前端 Job 的基准命令：
+
+```bash
+cd frontend
+pnpm install --frozen-lockfile
+pnpm test
+pnpm type-check
+pnpm build
+```
+
+`integration-smoke` 应使用 Mock Provider、临时数据库和临时附件目录，不访问 OpenAI、DeepSeek 或其他外部服务。测试结束后必须关闭服务并清理临时数据。
+
+## 5. 路径与模块检查规则
+
+- 修改 `backend/**`、`backend/uv.lock` 或后端配置时，必须运行 `backend-test` 和 `integration-smoke`。
+- 修改 `frontend/**`、`frontend/pnpm-lock.yaml` 或前端配置时，必须运行全部前端 Job。
+- 修改 `docs/contracts/**`、FastAPI 路由、DTO、SSE 事件或前端 Service 类型时，必须同时运行前后端全量检查。
+- 修改 `.gitea/**`、根目录工程配置或依赖版本时，必须运行所有 Job。
+- 修改 `docs/**` 以外且无法明确归类的文件时，默认运行所有 Job。
+
+路径过滤只用于减少无关重复任务，不得造成关键检查缺失。若无法可靠判断影响范围，应执行全量流水线。
+
+## 6. 凭据与敏感信息
+
+- 基础 CI 不配置真实模型 API Key，Provider 相关测试统一使用 Mock 或请求桩。
+- 确需发布签名或访问受保护服务时，凭据只保存在 Gitea Actions Secrets 中，不写入仓库、工作流参数、缓存或构建产物。
+- 来自外部分支或不受信任 Pull Request 的任务不得读取发布凭据。
+- Secret 名称表达用途和环境，例如 `RELEASE_SIGNING_KEY`；禁止使用含义模糊的 `KEY1`、`TOKEN2`。
+- 日志中禁止输出请求头、完整 Token、API Key、用户笔记内容和本地凭据存储内容。
+- 生产凭据与测试凭据分离，并遵循最小权限、定期轮换和可撤销原则。
+
+前端构建时注入的变量会进入静态资源，不能用于保存秘密。只有明确可公开的配置才允许使用 Vite 客户端环境变量。
+
+## 7. 缓存与产物
+
+可以缓存 uv 下载缓存和 pnpm Store，缓存键至少包含操作系统、运行时版本和对应锁文件哈希。不得缓存：
+
+- `backend/.venv/`；
+- `frontend/node_modules/`；
+- `backend/data/`、测试数据库和用户附件；
+- `.env`、API Key、本地凭据库或签名材料。
+
+普通 PR 不上传可执行发布包，只保留必要的测试报告和前端构建日志。`main` 或版本标签的候选产物应记录提交 SHA，生成 SHA-256 校验和，并设置明确的保留期限；非正式候选产物建议保留 14 天。
+
+## 8. 分支保护与合并门禁
+
+Gitea 中的 `main` 应启用以下保护：
+
+- 禁止普通成员直接推送和强制推送；
+- 要求 Pull Request 审阅通过；
+- 要求第 4 节列出的适用状态检查成功；
+- Head 更新后使旧审阅和旧检查失效，必须针对最新提交重新检查；
+- 对话和审阅意见处理完成后才允许合并；
+- 优先使用 squash 或 rebase 保持主线清晰，具体方式遵循 [Git 使用细则](Git使用细则-团队开发版.md)。
+
+临时绕过门禁只允许用于明确的仓库级故障。绕过者需要记录原因、影响、补验计划，并在恢复后立即补跑全部检查。
+
+## 9. 发布流程
+
+当前阶段按以下顺序生成发布候选：
+
+1. 从已通过全部检查的 `main` 提交确定发布 SHA；
+2. 更新版本号、变更说明和必要文档；
+3. 创建形如 `v0.2.0` 的语义化版本标签；
+4. 标签流水线重新执行全部测试和生产构建；
+5. 对产物执行本地启动或安装冒烟测试；
+6. 生成校验和，并把版本、提交 SHA、构建环境和已知限制写入发布说明；
+7. 人工确认后在 Gitea 发布页面公开产物。
+
+Tauri 桌面端接入后，发布流水线再增加 Windows、macOS 和 Linux 构建矩阵、平台签名及安装包验证。在签名、更新通道和回滚方案准备完成前，不启用面向用户的自动更新。
+
+## 10. 回滚与热修复
+
+- 尚未公开的候选产物直接标记为失败，不覆盖同一版本的已有产物；修复后递增预发布编号或版本号。
+- 已发布版本出现问题时，优先停止分发并回退到最近一个已验证版本。
+- 代码修复从 `main` 创建 `hotfix/<模块>-<问题>` 分支，通过完整门禁后合并并发布补丁版本。
+- 禁止重写已公开版本标签或用新文件替换旧版本同名产物。
+- 回滚或热修复完成后，在 `docs/retrospectives/` 记录原因、影响、处置过程和防复发措施。
+
+## 11. 流水线失败处理
+
+1. 先确认失败是否可在本地使用相同锁文件和命令复现；
+2. 判断是代码、测试、依赖、Runner 还是外部基础设施问题；
+3. 代码或测试问题由当前 PR 修复，不通过重跑掩盖不稳定测试；
+4. Runner 或 Gitea 故障应记录日志和时间，恢复后针对同一 Head 重新执行；
+5. 连续出现的偶发失败必须作为缺陷处理，明确负责人并增加稳定性修复；
+6. 修复流水线本身时，不得顺便降低测试范围或绕过既有门禁。
+
+## 12. 落地清单
+
+首次创建 `.gitea/workflows/` 时，应逐项确认：
+
+- [ ] 工作流只使用 Gitea Runner 支持且来源可信的 Action；
+- [ ] Python、Node.js、uv 和 pnpm 版本符合本规范；
+- [ ] 后端和前端依赖均以 frozen 模式安装；
+- [ ] 必需 Job 名称与 `main` 分支保护一致；
+- [ ] Mock 测试不依赖外部模型服务和真实凭据；
+- [ ] 缓存键包含锁文件哈希，缓存内容不含用户数据或秘密；
+- [ ] PR、`main`、版本标签和手动触发行为分别验证；
+- [ ] 失败任务能返回非零退出码，后续发布步骤不会继续；
+- [ ] 候选产物包含提交 SHA、校验和和保留期限；
+- [ ] 团队成员能够按本文档在本地复现全部门禁。
@@ -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) 中的状态检查与产物要求。
@@ -0,0 +1,43 @@
+# 代码注释与 TODO 约定
+
+本文用于统一团队在前后端代码中编写注释和待办项的方式。注释应解释设计意图、边界条件和不明显的取舍，不重复代码本身已经清楚表达的内容。
+
+## 注释原则
+
+- 模块或核心类说明其职责和边界，例如 Agent 编排器、工具执行边界、凭据存储边界。
+- 异步流程说明顺序、快照、去重、回滚和竞态处理原因。
+- 安全相关流程说明默认拒绝、权限收敛、输入净化和凭据优先级。
+- 简单赋值、显然的条件判断、类型定义和展示模板不添加翻译式注释。
+- 注释随实现一并维护；实现变化后已经失真的注释应在同一提交中修改或删除。
+
+## TODO 格式
+
+前端使用：
+
+```ts
+// TODO(editor): 描述尚未完成的能力、完成条件或替换目标。
+```
+
+后端使用：
+
+```python
+# TODO(agent): 描述尚未完成的能力、完成条件或替换目标。
+```
+
+领域标签使用小写英文，当前约定包括 `agent`、`ai-core`、`chat`、`desktop`、`editor`、`extension`、`performance`、`security` 和 `streaming`。一个 TODO 应对应真实存在的工程缺口；小型清理工作直接完成，不长期保留无负责人、无目标的占位待办。
+
+## 当前待办索引
+
+以下内容可通过 `rg "TODO\\(" backend/app frontend/src` 定位，代码中的注释是最新状态：
+
+| 领域 | 当前边界 |
+| --- | --- |
+| Agent / Streaming | 运行事件仍在进程内保存，后续需要持久化、`Last-Event-ID` 和断线重连 |
+| Security | 本地主密钥目前保存在数据目录，桌面端接入后迁移到系统凭据库 |
+| Extension | 扩展安装状态尚未持久化；MCP Host、进程隔离、签名与来源校验属于第二阶段 |
+| AI Core | 音频转写当前只读取文本或 Host 预生成旁路文本，后续接入本地 ASR 队列 |
+| Desktop | Web Workspace 已连接 FastAPI 单 Vault；后续由 Tauri IPC 增加原生目录选择、多 Vault 和文件监听 |
+| Editor / Chat | 待补文件冲突合并、受控链接对话框及会话持久化 |
+| Performance | Shiki 已复用单例，后续按首屏指标评估延迟加载或 Web Worker |
+
+TODO 完成后应删除对应代码注释并同步更新本索引；若工作超过一个提交，应建立 Issue，并在 Issue 中引用代码位置，而不是在源码中记录长篇设计讨论。
@@ -0,0 +1,378 @@
+# 第一阶段测试验证操作手册
+
+> 适用基线：2026-08-30 `main`  
+> 适用对象：开发、自测、代码审阅、合并验收和 Demo 前检查  
+> 验证范围：Vue Web 前端、FastAPI、Knowledge/Retrieval Core、AI/Agent Core、Extension Core、Provider 与开发阶段凭据链路
+
+## 1. 验证目标
+
+本手册用于确认第一阶段已经形成可运行的本地知识工作流：
+
+```text
+启动前后端
+→ 编辑 Markdown
+→ 建立或更新索引
+→ Search / RAG 返回 Citation
+→ Chat 或 Agent 调用统一 Provider
+→ Agent 展示 Trace、Tool 和 Permission
+→ Skill / Plugin 完成生命周期与 Tool 注册
+```
+
+当前不作为第一阶段通过条件的内容：Tauri/Rust Host、Stronghold、真实桌面文件系统、独立 MCP Plugin Host、真实音频模型和 Sync Server。
+
+## 2. 环境准备
+
+最低环境：
+
+| 工具 | 要求 |
+| --- | --- |
+| Git | 较新稳定版 |
+| Node.js | 22 或更高版本 |
+| pnpm | 10 或更高版本 |
+| Python | 3.11 或更高版本 |
+| uv | 较新稳定版 |
+
+在仓库根目录检查版本：
+
+```powershell
+git --version
+node --version
+pnpm --version
+python --version
+uv --version
+```
+
+同步依赖：
+
+```powershell
+cd backend
+uv sync --frozen
+
+cd ../frontend
+pnpm install --frozen-lockfile
+
+cd ..
+```
+
+`uv sync` 会自动创建和管理 `backend/.venv`，不需要手动创建或激活虚拟环境。
+
+## 3. 自动化验收
+
+### 3.1 后端测试
+
+```powershell
+cd backend
+uv run pytest -q -p no:cacheprovider
+```
+
+当前基线：
+
+```text
+80 passed
+```
+
+通过标准：退出码为 0、失败数为 0。用例数可以随功能增加，但不得低于当前基线。
+
+### 3.2 前端测试
+
+```powershell
+cd frontend
+pnpm test
+```
+
+当前基线：
+
+```text
+11 test files passed
+27 tests passed
+```
+
+通过标准：退出码为 0、失败数为 0。测试覆盖 Provider Store、主题偏好、Workspace、文件树、文件切换、可视化编辑器、智能体中文标签、轻量动效性能约束、Markdown 对比度 Token、scoped CSS 选择器约束和 Shiki GitHub 双主题输出。
+
+### 3.3 类型检查与生产构建
+
+```powershell
+cd frontend
+pnpm build
+```
+
+通过标准：`vue-tsc -b` 和 `vite build` 均成功，生成 `frontend/dist`。当前较大的编辑器与 Markdown Chunk 会产生体积警告，该警告不等于构建失败，但应记录在验收结果中。
+
+### 3.4 Git 与文档检查
+
+```powershell
+cd ..
+git diff --check
+git status --short
+```
+
+通过标准：`git diff --check` 没有错误。测试产生的 `.venv`、`node_modules`、`dist`、凭据和运行数据不得进入提交。
+
+## 4. 启动联调环境
+
+打开两个 PowerShell 终端。
+
+终端 A：
+
+```powershell
+cd backend
+uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+终端 B：
+
+```powershell
+cd frontend
+pnpm dev
+```
+
+访问：
+
+- 前端：<http://127.0.0.1:5173>
+- 健康检查：<http://127.0.0.1:8000/health>
+- 服务状态：<http://127.0.0.1:8000/api/status>
+- Swagger UI：<http://127.0.0.1:8000/docs>
+- OpenAPI：<http://127.0.0.1:8000/openapi.json>
+
+快速检查：
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8000/health
+Invoke-RestMethod http://127.0.0.1:8000/api/status
+```
+
+如果 `/docs` 返回 `RESOURCE_NOT_FOUND`，检查启动命令是否在 `backend` 目录执行、端口 8000 是否被其他程序占用，以及浏览器地址是否确实为 `http://127.0.0.1:8000/docs`。
+
+## 5. 后端主链路验证
+
+以下命令在第三个 PowerShell 终端执行，保持后端运行。
+
+### 5.1 Note 创建、读取与检索
+
+```powershell
+$apiBase = 'http://127.0.0.1:8000/api'
+$noteBody = @{
+  title = '第一阶段验收笔记'
+  markdown = "# 第一阶段验收`n`nNotes Agent 支持混合检索和可定位引用。"
+  folder = '验收'
+  tags = @('phase-1', 'verification')
+} | ConvertTo-Json
+
+$note = Invoke-RestMethod -Method Post -Uri "$apiBase/notes" -ContentType 'application/json' -Body $noteBody
+$noteId = $note.note_id
+Invoke-RestMethod -Uri "$apiBase/notes/$noteId"
+```
+
+执行搜索：
+
+```powershell
+$searchBody = @{
+  query = '混合检索'
+  mode = 'hybrid'
+  note_ids = @($noteId)
+  limit = 10
+  offset = 0
+  include_snippet = $true
+} | ConvertTo-Json
+
+$search = Invoke-RestMethod -Method Post -Uri "$apiBase/search" -ContentType 'application/json' -Body $searchBody
+$search.items | Format-Table title, file_path, snippet
+```
+
+通过标准：创建响应包含稳定 `note_id`；读取内容一致；搜索至少返回一项，并包含 `note_id`、`block_id`、文件路径、Snippet 和 Citation 定位信息。
+
+### 5.2 Index 状态与重建
+
+```powershell
+Invoke-RestMethod -Uri "$apiBase/index/status"
+
+$indexJob = Invoke-RestMethod -Method Post -Uri "$apiBase/index/rebuild" -ContentType 'application/json' -Body '{"scope":"all","force":false}'
+$indexJob
+Invoke-RestMethod -Uri "$apiBase/index/jobs/$($indexJob.job_id)"
+```
+
+通过标准：状态接口可访问；重建任务最终为 `completed`。重建失败时应返回统一错误并保留可恢复状态，不应留下半成品索引。
+
+### 5.3 Chat SSE
+
+使用内置 Mock Provider，不需要外部 API Key：
+
+```powershell
+curl.exe --no-buffer -X POST "http://127.0.0.1:8000/api/chat" -H "Content-Type: application/json" --data-raw '{"provider_id":"mock","model":"mock-1","messages":[{"role":"user","content":"请回复第一阶段 Chat 验收成功"}],"use_rag":false}'
+```
+
+通过标准：响应类型为 `text/event-stream`，能看到递增 `sequence` 的 `TextDelta`，并以 `Done` 终止；不得一次性伪装为流式结果。
+
+### 5.4 Agent Run 与 Trace
+
+```powershell
+$runBody = @{
+  input = '执行第一阶段 Agent 基础验证'
+  provider_id = 'mock'
+  model = 'mock-1'
+  allowed_tools = @('system.echo', 'math.add')
+  max_steps = 10
+  tool_timeout_seconds = 30
+  run_timeout_seconds = 300
+  max_concurrent_tools = 1
+  allow_network = $false
+} | ConvertTo-Json
+
+$run = Invoke-RestMethod -Method Post -Uri "$apiBase/agent/runs" -ContentType 'application/json' -Body $runBody
+Start-Sleep -Milliseconds 300
+$runResult = Invoke-RestMethod -Uri "$apiBase/agent/runs/$($run.run_id)"
+$runResult
+```
+
+订阅事件也可以使用：
+
+```powershell
+curl.exe --no-buffer "http://127.0.0.1:8000/api/agent/runs/$($run.run_id)/events"
+```
+
+通过标准：Run 最终为 `completed`，Trace 至少包含开始、文本或工具事件和完成事件；事件序号递增。需要权限的 Tool 应进入 `waiting_permission`，用户允许、会话允许或拒绝后能正确恢复或终止。
+
+### 5.5 Tool、Skill 与 Plugin
+
+```powershell
+Invoke-RestMethod -Uri "$apiBase/tools"
+Invoke-RestMethod -Uri "$apiBase/skills"
+Invoke-RestMethod -Uri "$apiBase/plugins"
+```
+
+通过标准：内置 Tool Definition 能被列出；内置知识助手 Skill 和示例 Plugin 状态可读取；未知权限、缺失依赖和畸形 Manifest 必须被拒绝，不能静默启用。
+
+### 5.6 Provider 与模型发现
+
+```powershell
+Invoke-RestMethod -Uri "$apiBase/providers"
+Invoke-RestMethod -Uri "$apiBase/providers/presets"
+Invoke-RestMethod -Uri "$apiBase/providers/mock/models"
+```
+
+通过标准：预设至少包含 OpenAI、DeepSeek 和 Ollama；Mock Provider 能返回模型列表。OpenAI/DeepSeek 属于选测项，需要测试人员自己的有效 API Key，真实密钥不得写入命令历史、文档、Issue、截图或提交。
+
+如需验证外部模型，优先在“设置 → 模型提供商”中选择预设并填写 API Key。页面不得回显明文；后端 `GET /api/credentials/{credential_id}` 只返回 `configured` 状态。测试完成后可在 Swagger 中调用对应 DELETE 接口删除测试凭据。
+
+## 6. 前端人工验收
+
+### 6.1 App Shell 与主题
+
+- 主导航、辅助侧栏、标题栏和状态栏正常显示；
+- `Ctrl+P` 能打开命令面板并跳转页面；
+- 亮色、暗色和护眼主题切换后文字、表格线、列表序号和浮动工具栏均清晰；
+- 导航使用统一图标，不出现无意义 Emoji；
+- 窄窗口下主要操作仍可访问。
+
+### 6.2 Workspace 与 Markdown
+
+- 启动 FastAPI 并配置 `APP_VAULT_PATH` 后，能打开后端真实 Vault；
+- 能在磁盘和 SQLite/FTS/向量索引之间一致地新建、读取、保存、重命名和删除文件及目录；
+- 后端不可用时明确报告连接错误，不展示或写入 Mock 文件；
+- 连续快速点击不同文件时，路径和正文始终一致；
+- 文件切换前的未保存内容不会被错误写入新文件；
+- 写作模式不展示 Markdown 源码，源码模式可以精确编辑；
+- H1–H6、正文、粗体、斜体、有序/无序列表、行内代码、代码块、行内/块公式、链接和字号输入均能修改 Markdown；
+- 选择文本后，顶部工具栏和浮动工具栏都对当前选区生效；
+- 正文不默认加粗，标题默认加粗；
+- 代码块默认展开编辑，不显示额外 Shiki 预览；
+- 主题页可在跟随主题、GitHub Light 和 GitHub Dark 间切换代码块样式，刷新后偏好仍保留；
+- Chat 等只读 Markdown 区域的代码高亮能跟随亮暗主题；
+- 表格、公式和 Markdown HTML 渲染正常，危险 HTML 被 DOMPurify 清理。
+
+### 6.3 Search、Chat 与 Citation
+
+- FTS、Vector 和 Hybrid 查询可切换；
+- 向量服务不可用时能降级到 FTS 并显示说明；
+- Chat 能展示 Streaming、Thinking、Tool Call、Usage、错误与 Citation；
+- 点击 Citation 后能打开对应笔记并定位内容；
+- 取消生成后页面状态恢复，不继续追加旧请求内容。
+
+### 6.4 智能体页面
+
+- 能新建、查看、切换和取消智能体运行；
+- Provider、模型、Skill、Tool 和运行限制可配置；
+- 运行状态、事件类型、工具说明、权限弹窗和常用详情字段显示中文；
+- `notes.search` 等技术 ID 保留显示，便于与日志对应；
+- Permission Request 不会跨 Run 残留；
+- Completed、Failed、Cancelled 和连接中断状态均有明确反馈。
+
+### 6.5 设置与扩展管理
+
+- Provider 预设可选择，保存后自动获取模型，也能手动刷新和选择默认模型；
+- 凭据缺失和 HTTP 401 会显示可理解的错误，不只显示笼统网络失败；
+- Skill、Plugin 的安装、启用、停用、权限和删除操作状态一致；
+- AI Core 诊断页能显示健康状态和开发 API 地址；
+- 前端不会在 Store、Local Storage 或页面中保存、回显 API Key 明文。
+
+## 7. 清理测试数据
+
+删除本手册创建的验收笔记：
+
+```powershell
+Invoke-RestMethod -Method Delete -Uri "$apiBase/notes/$noteId"
+```
+
+如果测试了外部 Provider，还应删除临时 Provider 和不再使用的测试凭据。不要直接递归删除整个 `backend/data`，其中可能包含其他成员的本地 Vault、索引和任务数据。
+
+## 8. 通过判定
+
+第一阶段可以标记为“验证通过”需要同时满足：
+
+- 后端测试零失败；
+- 前端测试零失败；
+- TypeScript 检查和生产构建成功；
+- 健康检查、OpenAPI 和主要接口可访问；
+- Note → Index/Search → Citation 主链路通过；
+- Mock Chat 和 Agent Trace 主链路通过；
+- Tool、Skill、Plugin 和 Provider 基础接口通过；
+- 前端人工验收没有 P0/P1 缺陷；
+- 没有真实密钥、生成目录或运行数据进入 Git；
+- 已记录测试环境、提交、结果、警告和遗留问题。
+
+外部 OpenAI/DeepSeek、Tauri、Stronghold、真实文件系统、真实音频模型与 Sync Server 失败或未测，不阻止当前第一阶段 Web 联调基线通过，但必须在验收记录中注明“未纳入本阶段”或“选测未执行”。
+
+## 9. 验收记录模板
+
+```markdown
+# 第一阶段验收记录
+
+- 日期：
+- 验收人：
+- 分支：main
+- 提交：
+- 操作系统：
+- Node / pnpm：
+- Python / uv：
+
+## 自动化结果
+
+- 后端 pytest：通过 / 失败，数量：
+- 前端 Vitest：通过 / 失败，数量：
+- 前端 build：通过 / 失败：
+- git diff --check：通过 / 失败：
+
+## 主链路
+
+- Health / OpenAPI：
+- Note / Search / Citation：
+- Chat SSE：
+- Agent Run / Trace / Permission：
+- Tool / Skill / Plugin：
+- Provider / Models：
+- 前端页面人工验收：
+
+## 选测项
+
+- OpenAI：未测 / 通过 / 失败
+- DeepSeek：未测 / 通过 / 失败
+- Ollama：未测 / 通过 / 失败
+
+## 警告与遗留问题
+
+-
+
+## 最终结论
+
+- 通过 / 有条件通过 / 不通过
+```