From a5b709a46f29ebcb1d70c9a124a8f0496f6984b1 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Tue, 1 Sep 2026 09:55:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E7=BB=84=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=B9=B6=E8=A1=A5=E5=85=85CI/CD=E7=BB=86?= =?UTF-8?q?=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 39 ++-- backend/README.md | 8 +- docs/README.md | 69 ++++++++ .../AI笔记软件技术栈说明-团队版-v2.3.md | 2 +- docs/{ => architecture}/第一阶段分工表.md | 0 docs/{ => architecture}/第二阶段团队分工表.md | 0 .../前端页面需求说明-开发版.md | 2 +- docs/{ => contracts}/后端接口契约-开发版.md | 0 .../第二阶段接口契约-开发版.md | 2 +- .../AI-Core与Agent-Core开发说明.md | 0 .../Knowledge与Retrieval-Core开发说明.md | 2 +- .../前端写作体验优化开发说明.md | 0 .../前端壳子与接口层开发说明.md | 0 .../前端视觉与轻量动效优化开发说明.md | 0 .../模型提供商与模型发现开发说明.md | 2 +- docs/guides/CI-CD细则-团队开发版.md | 166 ++++++++++++++++++ docs/{ => guides}/Git使用细则-团队开发版.md | 4 +- docs/{ => guides}/代码注释与TODO约定.md | 0 docs/{ => guides}/第一阶段测试验证操作手册.md | 0 .../Agent-Core第二阶段问题与修复复盘.md | 0 ...Knowledge与Retrieval-Core问题与修复复盘.md | 2 +- .../前端合并审阅问题与修复复盘.md | 0 .../后端全面审阅问题与修复复盘.md | 2 +- 23 files changed, 263 insertions(+), 37 deletions(-) create mode 100644 docs/README.md rename docs/{ => architecture}/AI笔记软件技术栈说明-团队版-v2.3.md (99%) rename docs/{ => architecture}/第一阶段分工表.md (100%) rename docs/{ => architecture}/第二阶段团队分工表.md (100%) rename docs/{ => contracts}/前端页面需求说明-开发版.md (99%) rename docs/{ => contracts}/后端接口契约-开发版.md (100%) rename docs/{ => contracts}/第二阶段接口契约-开发版.md (99%) rename docs/{ => development}/AI-Core与Agent-Core开发说明.md (100%) rename docs/{ => development}/Knowledge与Retrieval-Core开发说明.md (98%) rename docs/{ => development}/前端写作体验优化开发说明.md (100%) rename docs/{ => development}/前端壳子与接口层开发说明.md (100%) rename docs/{ => development}/前端视觉与轻量动效优化开发说明.md (100%) rename docs/{ => development}/模型提供商与模型发现开发说明.md (93%) create mode 100644 docs/guides/CI-CD细则-团队开发版.md rename docs/{ => guides}/Git使用细则-团队开发版.md (97%) rename docs/{ => guides}/代码注释与TODO约定.md (100%) rename docs/{ => guides}/第一阶段测试验证操作手册.md (100%) rename docs/{ => retrospectives}/Agent-Core第二阶段问题与修复复盘.md (100%) rename docs/{ => retrospectives}/Knowledge与Retrieval-Core问题与修复复盘.md (99%) rename docs/{ => retrospectives}/前端合并审阅问题与修复复盘.md (100%) rename docs/{ => retrospectives}/后端全面审阅问题与修复复盘.md (98%) diff --git a/README.md b/README.md index fdbef14..547ec37 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ NotesAgent/ ├── frontend/ Vue 3 + TypeScript + Vite 前端 ├── backend/ FastAPI + Pydantic 后端 -├── docs/ 分工与技术栈说明 +├── docs/ 架构、契约、开发说明、协作规范与问题复盘 └── server sync/ 云同步服务预留目录，当前未实现 ``` @@ -36,7 +36,7 @@ python --version uv --version ``` -当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/AI笔记软件技术栈说明-团队版-v2.3.md` 安装 Rust Toolchain 与 Tauri CLI。 +当前 Web 联调不需要 Rust 和 Tauri。开始桌面端集成后，再按照 `docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md` 安装 Rust Toolchain 与 Tauri CLI。 ## 首次初始化 @@ -126,25 +126,15 @@ pnpm test | 文档 | 用途 | | --- | --- | -| [技术栈说明](docs/AI笔记软件技术栈说明-团队版-v2.3.md) | 目标架构、第二阶段技术边界与模块依赖 | -| [第一阶段分工表](docs/第一阶段分工表.md) | 成员职责、协作关系与当前交付状态 | -| [第二阶段分工表](docs/第二阶段团队分工表.md) | 第二阶段人员职责、任务顺序、协作关系与验收项 | -| [第一阶段测试验证操作手册](docs/第一阶段测试验证操作手册.md) | 自动化测试、接口主链路、前端人工验收与记录模板 | -| [后端接口契约](docs/后端接口契约-开发版.md) | HTTP/SSE 接口、错误和当前实现状态 | -| [第二阶段接口契约](docs/第二阶段接口契约-开发版.md) | 第二阶段公共 DTO、计划接口、SSE、错误码与联调顺序 | -| [AI Core 与 Agent Core](docs/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | -| [Knowledge 与 Retrieval Core](docs/Knowledge与Retrieval-Core开发说明.md) | Block、索引、混合检索和 Citation | -| [模型提供商与模型发现](docs/模型提供商与模型发现开发说明.md) | Provider 预设、模型发现和凭据边界 | -| [前端页面需求](docs/前端页面需求说明-开发版.md) | 页面、交互、状态与验收基线 | -| [前端实现说明](docs/前端壳子与接口层开发说明.md) | 当前前端目录、Service、SSE 和运行边界 | -| [前端写作体验](docs/前端写作体验优化开发说明.md) | Milkdown、CodeMirror、格式栏和 Shiki | -| [前端视觉与轻量动效](docs/前端视觉与轻量动效优化开发说明.md) | Design Token、页面美化、性能边界与主题注入约定 | -| [Git 使用细则](docs/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 | -| [代码注释与 TODO 约定](docs/代码注释与TODO约定.md) | 注释原则、TODO 格式、领域标签与当前待办索引 | -| [后端审阅复盘](docs/后端全面审阅问题与修复复盘.md) | 后端问题原因、后果与修复方案 | -| [Agent Trace 复盘](docs/Agent-Core第二阶段问题与修复复盘.md) | Agent 持久化、SSE 恢复、事件契约与脱敏问题复盘 | -| [Knowledge/Retrieval 复盘](docs/Knowledge与Retrieval-Core问题与修复复盘.md) | 检索与事务问题复盘 | -| [前端审阅复盘](docs/前端合并审阅问题与修复复盘.md) | 前端工程、契约和交互问题复盘 | +| [文档总索引](docs/README.md) | 文档分类、阅读顺序和维护规则 | +| [技术栈说明](docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md) | 目标架构、第二阶段技术边界与模块依赖 | +| [第二阶段分工表](docs/architecture/第二阶段团队分工表.md) | 第二阶段人员职责、任务顺序、协作关系与验收项 | +| [后端接口契约](docs/contracts/后端接口契约-开发版.md) | HTTP/SSE 接口、错误和当前实现状态 | +| [第二阶段接口契约](docs/contracts/第二阶段接口契约-开发版.md) | 第二阶段公共 DTO、计划接口、SSE、错误码与联调顺序 | +| [AI Core 与 Agent Core](docs/development/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | +| [Git 使用细则](docs/guides/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 | +| [CI/CD 细则](docs/guides/CI-CD细则-团队开发版.md) | Gitea 流水线、质量门禁、产物、发布与回滚规则 | +| [Agent Trace 复盘](docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md) | Agent 持久化、SSE 恢复、事件契约与脱敏问题复盘 | ## 日常开发注意事项 @@ -154,6 +144,7 @@ pnpm test - API 默认监听 `127.0.0.1:8000`，前端默认监听 `127.0.0.1:5173`。 - 后端附件目录默认是 `backend/data/attachments`，可通过 `APP_ATTACHMENTS_PATH` 覆盖；该目录由桌面 Host 管理。 - 跨模块接口发生变化时，需要同步更新前后端类型和 `docs` 中的接口说明。 -- 当前已实现接口见 `docs/后端接口契约-开发版.md`，第二阶段规划接口见 `docs/第二阶段接口契约-开发版.md`；已实现能力以 `/openapi.json` 为准。 -- 前端页面、交互、状态管理和第一阶段验收要求见 `docs/前端页面需求说明-开发版.md`。 -- 分支、提交、Pull Request、Review 和冲突处理规范见 `docs/Git使用细则-团队开发版.md`。 +- 当前已实现接口见 `docs/contracts/后端接口契约-开发版.md`，第二阶段规划接口见 `docs/contracts/第二阶段接口契约-开发版.md`；已实现能力以 `/openapi.json` 为准。 +- 前端页面、交互、状态管理和第一阶段验收要求见 `docs/contracts/前端页面需求说明-开发版.md`。 +- 分支、提交、Pull Request、Review 和冲突处理规范见 `docs/guides/Git使用细则-团队开发版.md`。 +- CI 检查、产物、发布和回滚规范见 `docs/guides/CI-CD细则-团队开发版.md`。 diff --git a/backend/README.md b/backend/README.md index dc18dfb..2025871 100644 --- a/backend/README.md +++ b/backend/README.md @@ -23,10 +23,10 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 71 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。 +当前基线为 80 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。 -团队接口清单见 `../docs/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 +团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 -AI Core 与 Agent Core 的模块边界、Mock Provider 和 Tool Calling 调试方式见 `../docs/AI-Core与Agent-Core开发说明.md`。 +AI Core 与 Agent Core 的模块边界、Mock Provider 和 Tool Calling 调试方式见 `../docs/development/AI-Core与Agent-Core开发说明.md`。 -Knowledge Core 与 Retrieval Core 的模块边界、数据模型、接口与检索流程见 `../docs/Knowledge与Retrieval-Core开发说明.md`。 +Knowledge Core 与 Retrieval Core 的模块边界、数据模型、接口与检索流程见 `../docs/development/Knowledge与Retrieval-Core开发说明.md`。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5857184 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,69 @@ +# NotesAgent 文档索引 + +本目录集中保存团队开发期间需要长期维护的架构、接口、实现、协作和问题复盘文档。文档按用途分类，避免设计约束、开发记录与故障复盘混放。 + +## 目录分类 + +| 目录 | 内容 | 适用场景 | +| --- | --- | --- | +| [`architecture/`](architecture/) | 技术栈、阶段目标与团队分工 | 确认整体边界、模块依赖和阶段范围 | +| [`contracts/`](contracts/) | 前后端接口契约与页面需求 | 开发前对齐 DTO、路由、事件和交互 | +| [`development/`](development/) | 各模块的实现说明 | 阅读现有代码、联调和扩展功能 | +| [`guides/`](guides/) | Git、测试、注释和 CI/CD 规范 | 日常开发、提交、审阅和发布 | +| [`retrospectives/`](retrospectives/) | 审阅发现的问题与修复复盘 | 排查同类问题、撰写总结或博客 | + +## architecture：架构与分工 + +- [AI 笔记软件技术栈说明](architecture/AI笔记软件技术栈说明-团队版-v2.3.md) +- [第一阶段分工表](architecture/第一阶段分工表.md) +- [第二阶段团队分工表](architecture/第二阶段团队分工表.md) + +## contracts：契约与需求 + +- [后端接口契约](contracts/后端接口契约-开发版.md) +- [第二阶段接口契约](contracts/第二阶段接口契约-开发版.md) +- [前端页面需求说明](contracts/前端页面需求说明-开发版.md) + +运行中的后端以 `/openapi.json` 为机器可读事实来源。接口契约用于描述设计意图、联调约束和实现状态；两者不一致时，应先确认代码行为，再在同一个 PR 中同步修正文档或实现。 + +## development：开发说明 + +- [AI Core 与 Agent Core 开发说明](development/AI-Core与Agent-Core开发说明.md) +- [Knowledge 与 Retrieval Core 开发说明](development/Knowledge与Retrieval-Core开发说明.md) +- [模型提供商与模型发现开发说明](development/模型提供商与模型发现开发说明.md) +- [前端壳子与接口层开发说明](development/前端壳子与接口层开发说明.md) +- [前端写作体验优化开发说明](development/前端写作体验优化开发说明.md) +- [前端视觉与轻量动效优化开发说明](development/前端视觉与轻量动效优化开发说明.md) + +## guides：团队协作规范 + +- [Git 使用细则](guides/Git使用细则-团队开发版.md) +- [CI/CD 细则](guides/CI-CD细则-团队开发版.md) +- [代码注释与 TODO 约定](guides/代码注释与TODO约定.md) +- [第一阶段测试验证操作手册](guides/第一阶段测试验证操作手册.md) + +## retrospectives：问题与修复复盘 + +- [后端全面审阅问题与修复复盘](retrospectives/后端全面审阅问题与修复复盘.md) +- [Agent Core 第二阶段问题与修复复盘](retrospectives/Agent-Core第二阶段问题与修复复盘.md) +- [Knowledge 与 Retrieval Core 问题与修复复盘](retrospectives/Knowledge与Retrieval-Core问题与修复复盘.md) +- [前端合并审阅问题与修复复盘](retrospectives/前端合并审阅问题与修复复盘.md) + +## 推荐阅读顺序 + +新成员或新阶段开始时，建议按以下顺序阅读： + +1. 技术栈说明和当前阶段分工表； +2. 所负责功能对应的接口契约； +3. 对应模块的开发说明； +4. Git、CI/CD、测试及注释规范； +5. 与当前任务相关的问题复盘。 + +## 维护规则 + +- 新文档先判断用途，再放入对应分类目录，不在 `docs/` 根目录继续堆放业务文档。 +- 移动或重命名文档时，同步修正仓库内全部链接，并执行本地链接检查。 +- 接口、数据结构或事件格式发生变化时，同一个 PR 内同步更新契约和相关开发说明。 +- 问题复盘至少写清原因、后果、解决思路、实际方案和验证结果。 +- `.local-plans/` 只保存个人或阶段性的本地计划，不属于正式团队文档，不应提交到远程仓库。 +- 文档中的“计划实现”和“已经实现”必须明确区分；实现状态以代码、测试和运行时契约为准。 diff --git a/docs/AI笔记软件技术栈说明-团队版-v2.3.md b/docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md similarity index 99% rename from docs/AI笔记软件技术栈说明-团队版-v2.3.md rename to docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md index 5cade4b..85922f9 100644 --- a/docs/AI笔记软件技术栈说明-团队版-v2.3.md +++ b/docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md @@ -1859,7 +1859,7 @@ POST /api/index/rebuild GET /health ``` -第一阶段已实现路径和第二阶段冻结草案分别见 `后端接口契约-开发版.md` 与 `第二阶段接口契约-开发版.md`。规划接口完成前不得在前端假定其可用；完成后以 OpenAPI、Pydantic Contract 和 TypeScript Wire DTO 的一致结果为准。 +第一阶段已实现路径和第二阶段冻结草案分别见 `../contracts/后端接口契约-开发版.md` 与 `../contracts/第二阶段接口契约-开发版.md`。规划接口完成前不得在前端假定其可用；完成后以 OpenAPI、Pydantic Contract 和 TypeScript Wire DTO 的一致结果为准。 HTTP 返回统一错误结构： diff --git a/docs/第一阶段分工表.md b/docs/architecture/第一阶段分工表.md similarity index 100% rename from docs/第一阶段分工表.md rename to docs/architecture/第一阶段分工表.md diff --git a/docs/第二阶段团队分工表.md b/docs/architecture/第二阶段团队分工表.md similarity index 100% rename from docs/第二阶段团队分工表.md rename to docs/architecture/第二阶段团队分工表.md diff --git a/docs/前端页面需求说明-开发版.md b/docs/contracts/前端页面需求说明-开发版.md similarity index 99% rename from docs/前端页面需求说明-开发版.md rename to docs/contracts/前端页面需求说明-开发版.md index 678fefd..2002220 100644 --- a/docs/前端页面需求说明-开发版.md +++ b/docs/contracts/前端页面需求说明-开发版.md @@ -2,7 +2,7 @@ > 文档用途：供团队在第一阶段进行页面设计、Vue 开发、前后端联调和验收。 > 文档性质：开发需求基线，不是最终视觉规范或产品宣传文档。 -> 依据：`第一阶段分工表.md`、`AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md`。 +> 依据：`../architecture/第一阶段分工表.md`、`../architecture/AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md`。 > 实现状态：更新至 2026-08-31。全部已注册业务路由均已有真实页面；Markdown 写作/源码模式、Search、Chat、智能体执行轨迹、扩展管理、设置、Provider 预设、模型发现和开发阶段加密凭据输入均已落地。Web Workspace 已连接 FastAPI 管理的真实单 Vault；Tauri 原生目录选择和多 Vault 尚未接入。 diff --git a/docs/后端接口契约-开发版.md b/docs/contracts/后端接口契约-开发版.md similarity index 100% rename from docs/后端接口契约-开发版.md rename to docs/contracts/后端接口契约-开发版.md diff --git a/docs/第二阶段接口契约-开发版.md b/docs/contracts/第二阶段接口契约-开发版.md similarity index 99% rename from docs/第二阶段接口契约-开发版.md rename to docs/contracts/第二阶段接口契约-开发版.md index 4da9867..58f3da2 100644 --- a/docs/第二阶段接口契约-开发版.md +++ b/docs/contracts/第二阶段接口契约-开发版.md @@ -4,7 +4,7 @@ > > 更新日期：2026-08-31 > -> 依据：`第二阶段团队分工表.md`、`AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md` +> 依据：`../architecture/第二阶段团队分工表.md`、`../architecture/AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md` 本文统一第二阶段新增能力的 HTTP、SSE、前端 Service、桌面 Host 和内部模块接口。文中标记为“计划新增”的路径尚未实现，不能据此判断当前服务已经支持；实现完成后以 FastAPI `/openapi.json`、TypeScript Wire DTO 和自动化测试共同作为最终依据。 diff --git a/docs/AI-Core与Agent-Core开发说明.md b/docs/development/AI-Core与Agent-Core开发说明.md similarity index 100% rename from docs/AI-Core与Agent-Core开发说明.md rename to docs/development/AI-Core与Agent-Core开发说明.md diff --git a/docs/Knowledge与Retrieval-Core开发说明.md b/docs/development/Knowledge与Retrieval-Core开发说明.md similarity index 98% rename from docs/Knowledge与Retrieval-Core开发说明.md rename to docs/development/Knowledge与Retrieval-Core开发说明.md index 45f6cee..13a6b42 100644 --- a/docs/Knowledge与Retrieval-Core开发说明.md +++ b/docs/development/Knowledge与Retrieval-Core开发说明.md @@ -3,7 +3,7 @@ > 本文档用于团队开发和模块联调，记录 Knowledge Core / Retrieval Core 已经落地的 > 模块边界、数据模型、接口与使用方式，对应分工表中的杨星萱。 -> 更新日期：2026-08-30。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 71 项测试通过。 +> 更新日期：2026-09-01。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 80 项测试通过。 ## 当前实现 diff --git a/docs/前端写作体验优化开发说明.md b/docs/development/前端写作体验优化开发说明.md similarity index 100% rename from docs/前端写作体验优化开发说明.md rename to docs/development/前端写作体验优化开发说明.md diff --git a/docs/前端壳子与接口层开发说明.md b/docs/development/前端壳子与接口层开发说明.md similarity index 100% rename from docs/前端壳子与接口层开发说明.md rename to docs/development/前端壳子与接口层开发说明.md diff --git a/docs/前端视觉与轻量动效优化开发说明.md b/docs/development/前端视觉与轻量动效优化开发说明.md similarity index 100% rename from docs/前端视觉与轻量动效优化开发说明.md rename to docs/development/前端视觉与轻量动效优化开发说明.md diff --git a/docs/模型提供商与模型发现开发说明.md b/docs/development/模型提供商与模型发现开发说明.md similarity index 93% rename from docs/模型提供商与模型发现开发说明.md rename to docs/development/模型提供商与模型发现开发说明.md index c5eb90f..f9f78e1 100644 --- a/docs/模型提供商与模型发现开发说明.md +++ b/docs/development/模型提供商与模型发现开发说明.md @@ -104,4 +104,4 @@ pnpm build 自动化验证覆盖 Provider 预设、OpenAI-Compatible `/models` 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。 -当前完整回归基线：后端 71 项测试、前端 14 项测试通过，前端生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。 +当前完整回归基线：后端 80 项测试、前端 27 项测试通过，前端类型检查和生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。 diff --git a/docs/guides/CI-CD细则-团队开发版.md b/docs/guides/CI-CD细则-团队开发版.md new file mode 100644 index 0000000..b36bd0f --- /dev/null +++ b/docs/guides/CI-CD细则-团队开发版.md @@ -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、校验和和保留期限； +- [ ] 团队成员能够按本文档在本地复现全部门禁。 diff --git a/docs/Git使用细则-团队开发版.md b/docs/guides/Git使用细则-团队开发版.md similarity index 97% rename from docs/Git使用细则-团队开发版.md rename to docs/guides/Git使用细则-团队开发版.md index 9c58767..fe03df0 100644 --- a/docs/Git使用细则-团队开发版.md +++ b/docs/guides/Git使用细则-团队开发版.md @@ -2,7 +2,7 @@ > 本文档用于 Notes Agent 团队日常开发。目标是让三名成员可以并行开发、稳定联调，并确保 `main` 始终处于可运行状态。 -> 更新日期：2026-08-30。当前远程只使用 `gitea`，功能分支不添加个人或工具名称前缀；合并门槛为相关测试、前端生产构建、文档同步和 `git diff --check` 全部通过。 +> 更新日期：2026-09-01。当前远程只使用 `gitea`，功能分支不添加个人或工具名称前缀；合并门槛为相关测试、前端生产构建、文档同步和 `git diff --check` 全部通过。自动化门禁、产物和发布规则见 [CI/CD 细则](CI-CD细则-团队开发版.md)。 ## 1. 仓库与远程 @@ -622,4 +622,4 @@ git push -u gitea <分支名> git log --oneline --decorate -10 ``` -本细则的核心要求是：`main` 可运行、改动可 Review、问题可追踪、敏感信息不入库、跨模块变化同步 Contract 与文档。 +本细则的核心要求是：`main` 可运行、改动可 Review、问题可追踪、敏感信息不入库、跨模块变化同步 Contract 与文档。流水线启用后，合并和发布还必须满足 [CI/CD 细则](CI-CD细则-团队开发版.md) 中的状态检查与产物要求。 diff --git a/docs/代码注释与TODO约定.md b/docs/guides/代码注释与TODO约定.md similarity index 100% rename from docs/代码注释与TODO约定.md rename to docs/guides/代码注释与TODO约定.md diff --git a/docs/第一阶段测试验证操作手册.md b/docs/guides/第一阶段测试验证操作手册.md similarity index 100% rename from docs/第一阶段测试验证操作手册.md rename to docs/guides/第一阶段测试验证操作手册.md diff --git a/docs/Agent-Core第二阶段问题与修复复盘.md b/docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md similarity index 100% rename from docs/Agent-Core第二阶段问题与修复复盘.md rename to docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md diff --git a/docs/Knowledge与Retrieval-Core问题与修复复盘.md b/docs/retrospectives/Knowledge与Retrieval-Core问题与修复复盘.md similarity index 99% rename from docs/Knowledge与Retrieval-Core问题与修复复盘.md rename to docs/retrospectives/Knowledge与Retrieval-Core问题与修复复盘.md index b7fd887..cf1b432 100644 --- a/docs/Knowledge与Retrieval-Core问题与修复复盘.md +++ b/docs/retrospectives/Knowledge与Retrieval-Core问题与修复复盘.md @@ -499,5 +499,5 @@ backend/app/retrieval/engine.py FTS/Vector/Hybrid 检索编排 backend/app/services/index_service.py 全量重建与失败恢复 backend/app/knowledge/parser.py Block ID 与 tags 解析语义 backend/tests/test_retrieval.py 审阅回归测试 -docs/Knowledge与Retrieval-Core开发说明.md 模块开发说明 +docs/development/Knowledge与Retrieval-Core开发说明.md 模块开发说明 ``` diff --git a/docs/前端合并审阅问题与修复复盘.md b/docs/retrospectives/前端合并审阅问题与修复复盘.md similarity index 100% rename from docs/前端合并审阅问题与修复复盘.md rename to docs/retrospectives/前端合并审阅问题与修复复盘.md diff --git a/docs/后端全面审阅问题与修复复盘.md b/docs/retrospectives/后端全面审阅问题与修复复盘.md similarity index 98% rename from docs/后端全面审阅问题与修复复盘.md rename to docs/retrospectives/后端全面审阅问题与修复复盘.md index 97482af..7322f02 100644 --- a/docs/后端全面审阅问题与修复复盘.md +++ b/docs/retrospectives/后端全面审阅问题与修复复盘.md @@ -4,7 +4,7 @@ > 审阅范围：FastAPI、Knowledge / Retrieval Core、Agent Core、Extension Core、Provider Adapter、公共接口和后端开发文档。 > 文档用途：记录问题形成原因、实际影响、修复判断和落地方案，供后续开发文档、比赛材料与技术博客使用。 -> 2026-08-30 状态补充：本文记录的缺陷均保持修复。此后又加入 Provider 预设、模型发现、DeepSeek/OpenAI 凭据解析和 Fernet 加密存储，当前完整后端回归基线为 71 项测试通过。 +> 2026-09-01 状态补充：本文记录的缺陷均保持修复。此后又加入 Provider 预设、模型发现、DeepSeek/OpenAI 凭据解析、Fernet 加密存储和 Agent Trace 持久化，当前完整后端回归基线为 80 项测试通过。 ## 1. 审阅结论