From 2c84a98474158db0c858e8715b4f163e1f964734 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Sun, 30 Aug 2026 15:20:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=AC=AC=E4=B8=80?= =?UTF-8?q?=E9=98=B6=E6=AE=B5=E6=B5=8B=E8=AF=95=E9=AA=8C=E8=AF=81=E6=89=8B?= =?UTF-8?q?=E5=86=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + docs/第一阶段测试验证操作手册.md | 376 +++++++++++++++++++++++++++++++ 2 files changed, 377 insertions(+) create mode 100644 docs/第一阶段测试验证操作手册.md diff --git a/README.md b/README.md index 6850459..b5c8405 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,7 @@ pnpm test | --- | --- | | [技术栈说明](docs/AI笔记软件技术栈说明-团队版-v2.2.md) | 目标架构、当前实施边界与模块依赖 | | [第一阶段分工表](docs/第一阶段分工表.md) | 成员职责、协作关系与当前交付状态 | +| [第一阶段测试验证操作手册](docs/第一阶段测试验证操作手册.md) | 自动化测试、接口主链路、前端人工验收与记录模板 | | [后端接口契约](docs/后端接口契约-开发版.md) | HTTP/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 | diff --git a/docs/第一阶段测试验证操作手册.md b/docs/第一阶段测试验证操作手册.md new file mode 100644 index 0000000..344add0 --- /dev/null +++ b/docs/第一阶段测试验证操作手册.md @@ -0,0 +1,376 @@ +# 第一阶段测试验证操作手册 + +> 适用基线：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 +71 passed +``` + +通过标准：退出码为 0、失败数为 0。用例数可以随功能增加，但不得低于当前基线。 + +### 3.2 前端测试 + +```powershell +cd frontend +pnpm test +``` + +当前基线： + +```text +6 test files passed +14 tests passed +``` + +通过标准：退出码为 0、失败数为 0。测试覆盖 Provider Store、Workspace、文件树、文件切换、可视化编辑器和智能体中文标签。 + +### 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 +``` + +访问： + +- 前端： +- 健康检查： +- 服务状态： +- Swagger UI： +- OpenAPI： + +快速检查： + +```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 + +- 能新建、打开、重命名和删除 Web Mock 文件； +- 连续快速点击不同文件时，路径和正文始终一致； +- 文件切换前的未保存内容不会被错误写入新文件； +- 写作模式不展示 Markdown 源码，源码模式可以精确编辑； +- H1–H6、正文、粗体、斜体、有序/无序列表、行内代码、代码块、行内/块公式、链接和字号输入均能修改 Markdown； +- 选择文本后，顶部工具栏和浮动工具栏都对当前选区生效； +- 正文不默认加粗，标题默认加粗； +- 代码块默认展开编辑，不显示额外 Shiki 预览； +- 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：未测 / 通过 / 失败 + +## 警告与遗留问题 + +- + +## 最终结论 + +- 通过 / 有条件通过 / 不通过 +``` +