Files

T

admin 0e8d4b7b9f fix(agent): 保留持久化Run完整内容

2026-09-01 10:05:58 +08:00

12 KiB

Raw Blame History

第一阶段测试验证操作手册

适用基线：2026-08-30 main
适用对象：开发、自测、代码审阅、合并验收和 Demo 前检查
验证范围：Vue Web 前端、FastAPI、Knowledge/Retrieval Core、AI/Agent Core、Extension Core、Provider 与开发阶段凭据链路

1. 验证目标

本手册用于确认第一阶段已经形成可运行的本地知识工作流：

启动前后端
→ 编辑 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	较新稳定版

在仓库根目录检查版本：

git --version
node --version
pnpm --version
python --version
uv --version

同步依赖：

cd backend
uv sync --frozen

cd ../frontend
pnpm install --frozen-lockfile

cd ..

uv sync 会自动创建和管理 backend/.venv，不需要手动创建或激活虚拟环境。

3. 自动化验收

3.1 后端测试

cd backend
uv run pytest -q -p no:cacheprovider

当前基线：

81 passed

通过标准：退出码为 0、失败数为 0。用例数可以随功能增加，但不得低于当前基线。

3.2 前端测试

cd frontend
pnpm test

当前基线：

11 test files passed
27 tests passed

通过标准：退出码为 0、失败数为 0。测试覆盖 Provider Store、主题偏好、Workspace、文件树、文件切换、可视化编辑器、智能体中文标签、轻量动效性能约束、Markdown 对比度 Token、scoped CSS 选择器约束和 Shiki GitHub 双主题输出。

3.3 类型检查与生产构建

cd frontend
pnpm build

通过标准：vue-tsc -b 和 vite build 均成功，生成 frontend/dist。当前较大的编辑器与 Markdown Chunk 会产生体积警告，该警告不等于构建失败，但应记录在验收结果中。

3.4 Git 与文档检查

cd ..
git diff --check
git status --short

通过标准：git diff --check 没有错误。测试产生的 .venv、node_modules、dist、凭据和运行数据不得进入提交。

4. 启动联调环境

打开两个 PowerShell 终端。

终端 A：

cd backend
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

终端 B：

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

快速检查：

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 创建、读取与检索

$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"

执行搜索：

$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 状态与重建

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：

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

$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

订阅事件也可以使用：

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

Invoke-RestMethod -Uri "$apiBase/tools"
Invoke-RestMethod -Uri "$apiBase/skills"
Invoke-RestMethod -Uri "$apiBase/plugins"

通过标准：内置 Tool Definition 能被列出；内置知识助手 Skill 和示例 Plugin 状态可读取；未知权限、缺失依赖和畸形 Manifest 必须被拒绝，不能静默启用。

5.6 Provider 与模型发现

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. 清理测试数据

删除本手册创建的验收笔记：

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. 验收记录模板

# 第一阶段验收记录

- 日期：
- 验收人：
- 分支：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：未测 / 通过 / 失败

## 警告与遗留问题

-

## 最终结论

- 通过 / 有条件通过 / 不通过

12 KiB Raw Blame History Unescape Escape