# 第一阶段测试验证操作手册 > 适用基线：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 9 test files passed 22 tests passed ``` 通过标准：退出码为 0、失败数为 0。测试覆盖 Provider Store、主题偏好、Workspace、文件树、文件切换、可视化编辑器、智能体中文标签、轻量动效性能约束、Markdown 对比度 Token 和 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 ``` 访问： - 前端： - 健康检查： - 服务状态： - 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 预览； - 主题页可在跟随主题、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：未测 / 通过 / 失败 ## 警告与遗留问题 - ## 最终结论 - 通过 / 有条件通过 / 不通过 ```