379 lines
12 KiB
Markdown
379 lines
12 KiB
Markdown
# 第一阶段测试验证操作手册
|
||
|
||
> 适用基线：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
|
||
81 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：未测 / 通过 / 失败
|
||
|
||
## 警告与遗留问题
|
||
|
||
-
|
||
|
||
## 最终结论
|
||
|
||
- 通过 / 有条件通过 / 不通过
|
||
```
|