88 lines
12 KiB
Markdown
88 lines
12 KiB
Markdown
# 第二阶段收尾实现与验收
|
||
|
||
日期：2026-09-07。实现提交 `89df10b`，开发分支 `feat/phase2-completion`，基于最新拉取的 `gitea/main` / `95095197df8b607e55144748c9be0c7f6daf00df`。本分支尚未合并、推送或发布。本记录覆盖所有成员的第二阶段工程范围，替代早期“不含杨侧验收”的当前状态口径；[此前全量审计](第二阶段全量验收报告-2026-09-07.md)保留为修复前基线。
|
||
|
||
## 结论
|
||
|
||
原审计中可在现有环境推进的主要缺项已实现：标准 Agent Benchmark 与报告页、函数图像编辑器和共用 Markdown 预览、三格式未保存快照导出、Mermaid 静态图片、DOCX 图像与受支持公式、真实 RAG 质量对照，以及现有 Provider/MCP 的受限集成验证。
|
||
|
||
不将本次结果写成“所有厂商、所有文档及音频质量全部通过”。未配置的 Responses/Anthropic/Ollama 真实服务、厂商最大上下文边界、DOCX Office/LibreOffice 整页视觉复核仍列为验收边界；音频质量按本轮范围排除。Tauri/Rust、联网社区、Sync Server、操作系统沙箱仍属第三阶段。
|
||
|
||
## DoD 矩阵
|
||
|
||
| 项目 | 本轮状态 | 实现与证据 |
|
||
| --- | --- | --- |
|
||
| Agent Benchmark | 已实现、真实运行通过 | 标准版本化 Case、正式 Runtime、真实 Trace、逐例检查及成功/选择/参数/无效调用/步骤/耗时/Token 指标；4/4 标准案例与2/2集成案例通过 |
|
||
| RAG Benchmark 与报告页 | 已实现、真实本地模型对照完成 | 12篇自建中文工程笔记，关键词/语义改写各12题；6配置×24题×2轮，288个样本，零运行失败；冻结语料与逐例 provenance |
|
||
| 函数图像 | 已实现、页面复核通过 | 写作/源码切换、编辑刷新、诊断、只读/AI共用组件、缩放/重置/大图、六主题宽窄屏；共享后端白名单语法与几何 |
|
||
| 导出 UI | 已实现、浏览器下载通过 | HTML/PDF/DOCX，点击时快照、标题/纸张选项、后台状态、取消、下载和 warning；包含未保存 PHASE2-SNAPSHOT |
|
||
| 静态内容导出 | 已实现、产物检查通过 | Mermaid 浏览器净化后栅格化，按源码摘要绑定PNG；HTML/PDF/DOCX真实嵌图；DOCX函数图、MathText公式及Vault内PNG/JPEG/WebP；无法表示的资源显式warning |
|
||
| 主题与 Mermaid | 已复核 | light/dark/sepia/paper-moments/ocean-blue/midnight-purple；36组Mermaid用隔离iframe检查，无全局主题串扰 |
|
||
| Provider | 已配置协议通过 | DeepSeek OpenAI Compatible：发现、普通、流式、推理事件、Tool往返、Usage、取消与错误映射；额外上下文压缩及缓存字段观测 |
|
||
| MCP | 现有服务通过 | MiniMax Coding Plan stdio注册与Agent真实web_search调用，工具权限仍由Runtime约束 |
|
||
| Plugin/Skill、Trace、Task、工作区 | 回归通过 | 全量回归；隔离压力测试、权限等待/取消、恢复与分页；本地持久安装已实现 |
|
||
| 音频 | 本轮排除质量专项 | 当前Qwen3-ASR + ERes2NetV2；没有将faster-whisper/pyannote写成已交付，也未声称CER/WER/DER达标 |
|
||
|
||
## RAG 结果与调优决策
|
||
|
||
冻结模型 `hotchpotch/bekko-embedding-v1-a8m@c721113d59a1d91b447450324f51c4b3332c924a`，384维，真实已安装本地模型；LexicalReranker `lexical-v1/1`。Top K=5、RRF K=60、候选20，参数变体K=20。向量来源逐例为local，无HashEmbedding测试注入或远端失败回退。完整记录见[rag-quality.json](evidence/phase2-20260907/rag-quality.json)。
|
||
|
||
| 配置 | Hit@1 | Hit@5 / Recall@5 | MRR | Citation Hit Rate | P50 / P95 ms |
|
||
| --- | ---: | ---: | ---: | ---: | ---: |
|
||
| FTS | .9583 | 1 / 1 | .9667 | .7500 | 9.64 / 12.20 |
|
||
| Vector（冷暖混合） | 1 | 1 / 1 | 1 | .5833 | 4571.74 / 10284.19 |
|
||
| Hybrid 加权50/50 | .9583 | 1 / 1 | .9688 | .6667 | 15.44 / 19.69 |
|
||
| Hybrid RRF | .9167 | 1 / 1 | .9583 | .6667 | 15.44 / 20.28 |
|
||
| RRF + Lexical rerank | .9167 | 1 / 1 | .9583 | .8750 | 15.70 / 22.26 |
|
||
| RRF K=20 | .9167 | 1 / 1 | .9583 | .6667 | 15.68 / 27.67 |
|
||
|
||
Citation Hit Rate判断首条返回块是否命中预期引用块，不是“任意返回块命中”。因此高笔记命中率不等于准确引用。数据属于开发集，不是生产分布或留出测试集；没有事后补造质量阈值来宣布生产达标。
|
||
|
||
RRF K=20没有收益，保留默认60；加权融合提供可选对照，不改变默认策略。Lexical rerank改善本集引用命中，却未提高笔记Top1，不能宣布通用质量提升。
|
||
|
||
瓶颈是重复查询反复启动本地Embedding推理。新增128条/10分钟进程内缓存，仅存真实本地单文本向量，键包含模型目录/revision、冻结运行配置与查询摘要；返回副本，未安装模型不走缓存，不缓存远端响应。Vector的24个miss P50=9474.32ms，24个hit P50=15.11ms。后续Hybrid配置大多复用暖缓存，其时延不能与冷Vector直接比较。改前无缓存Vector P50约9368.46ms；冷推理没有提速。保留本地进程长期驻留优化作为后续独立设计，不扩大本轮范围。
|
||
|
||
## 真实 Provider、Agent、MCP
|
||
|
||
[标准报告](evidence/phase2-20260907/live.json)：现有DeepSeek `deepseek-v4-flash`，4/4任务成功，工具选择/参数准确率均1，无效调用率0，平均1.75步、5682.33ms，5888 Token。发现3个模型；流包含TextDelta/ThinkingDelta/Usage/Done；无效模型映射PROVIDER_INVALID_REQUEST。取消关闭客户端流约12.16ms，不等于能观测到服务商停止计费。
|
||
|
||
另通过实际Benchmark页面启动、下载与Trace跳转复测，4/4成功、5939 Token、平均4646.52ms，见[UI运行报告](evidence/phase2-20260907/agent-ui-report.json)。修复了未打开工作区时无法从报告进入已有Trace的路由拦截；创建普通新Agent运行仍遵守原工作区入口约束。
|
||
|
||
[集成报告](evidence/phase2-20260907/integration.json)：检索→读笔记→3个任务创建，以及MCP web_search，共2/2通过，工具6/6匹配，16070 Token。写入仅针对隔离数据库的3个任务，按这次运行的权限票据逐项批准。报告保留真实Agent Run ID，可在保留隔离数据库时恢复Trace；Benchmark报告本身是有界内存任务，应下载保存，重启不会恢复评测注册表。
|
||
|
||
[上下文复测](evidence/phase2-20260907/context.json)：不修改已保存Provider配置，在请求级测试配置中设8192窗口；detect在网络前返回CONTEXT_COMPRESSION_REQUIRED，compress调用真实模型生成摘要再回答，估算从2262降至516，原会话不变，最终答案保留Vault事实。首次256输出Token预算耗尽，见[失败记录](evidence/phase2-20260907/context-budget256.json)；改用1024上限后最终回答使用289输出Token并通过。四次受限调用包含两轮摘要及回答。该测试验证应用的预算与压缩路径，不证明厂商最大窗口。
|
||
|
||
验收库中18个该Provider请求上报缓存计数，13个有正命中、18个有正未命中；缺失字段保持未知，不记作0。缓存是否命中由服务商控制，不能强制保证。没有新增账号、密钥或服务，没有打印凭据或请求认证信息。
|
||
|
||
外部剩余项：当前未配置OpenAI Responses、Anthropic Messages、Ollama真实服务，协议单测通过仍不足以替代真实服务矩阵；厂商极限上下文需要单独预算与目标窗口。本轮没有发出超大输入探测。
|
||
|
||
## 性能与回归
|
||
|
||
- 后端全量与前端测试/构建结果以本报告末尾最终验证记录为准。
|
||
- [串行压力基线](evidence/phase2-20260907/agent-task-before.json)与[修复后](evidence/phase2-20260907/agent-task-after.json)：200并发均完成，事件顺序、回放和终态恢复正确。恢复读取约313ms移出事件循环；该场景loop lag max从326.14降到12.19ms。运行P95从1007.22到1155.52ms，没有声称模型或总吞吐提速。
|
||
- 200活跃运行容量拒绝与取消通过，取消P95=5.85ms；权限等待10批准/10取消、订阅释放，故障隔离后无残余工具执行器。
|
||
- Task API 100/1000条、20并发CRUD及50条分页完整；1000条创建/更新/删除P95约121.67/146.20/145.87ms。此脚本显式mock，不能代替真实Agent Benchmark。
|
||
- KaTeX通过Vite dedupe合为一个运行时chunk；Mermaid/语法等大惰性资源仍有构建提示，未调高阈值隐藏问题。
|
||
|
||
## 产物与视觉复核边界
|
||
|
||
浏览器真实加载项目组件与API，六主题各保存宽屏、390px窄屏和大图截图，检查缩放、源码切换、实时编辑、主题切换、无效表达式及打印warning。使用受限复杂图文档实际从UI取消后台PDF任务并看到已取消终态。[页面结果](evidence/phase2-20260907/browser-results.json)、[Mermaid矩阵](evidence/phase2-20260907/browser-mermaid-matrix.json)。窄屏函数图保留640px坐标区域并可横向滚动，避免刻度被整体缩得过小。
|
||
|
||
PDF使用嵌入的可用CJK字体，已通过Poppler检查实际页面；未安装可用字体时保留CID回退并明确warning。可用APP_EXPORT_FONT指定兼容TTF/TTC。三格式包含未保存快照、函数图、中文Mermaid及公式；DOCX的OOXML、图片关系和媒体内容通过结构检查，参见[产物清单](evidence/phase2-20260907/artifacts.json)。捆绑文档渲染器因缺少LibreOffice `soffice.exe` 无法完成DOCX整页渲染，不能声称Word分页已视觉通过。没有改用用户安装的Office/LibreOffice绕过工具约束。
|
||
|
||
MathText是受限TeX子集，不等同于KaTeX全语法；不支持的公式、远端/越界图片明确保留源码或替代文字及warning。服务器不执行客户端SVG/XML、任意TeX命令或外部资源下载。PNG每图4百万像素、总16百万像素/8MiB、最多64附件；重复引用及本地自动补全资源也受文档级累计预算约束；前端最多准备16幅Mermaid。函数图每块16表达式、预览总8000节点，导出每文档16图/8000节点，预览并发2。取消在线程渲染边界生效，不能强杀正在运行的Python绘图线程。
|
||
|
||
## 复现
|
||
|
||
1. `uv sync --frozen` 与 `pnpm install --frozen-lockfile`；把APP_DATA_DIR/APP_DB_PATH/APP_VAULT_PATH指向全新验收目录，不能指向用户知识库。
|
||
2. 仅在用户授权下复用已有Provider凭据及模型配置；APP_MODEL_PYTHON指向已安装模型解释器。语料源为`backend/data/benchmarks/corpus/phase2-v1.json`；运行`backend/scripts/phase2-quality.py --output <report.json>`，生成独立Vault和Dataset、重建真实索引。`--reuse-index`会验证块ID一致，不能跳过缺失索引。
|
||
3. 标准真实测试：`backend/scripts/phase2-live.py --provider <已有ID> --output <report.json> --execute`；上下文`phase2-context.py`同参数。写任务/MCP测试用`phase2-integration.py --execute`，先查脚本中隔离端口与现有工具ID；不能复制到生产Vault直接执行。
|
||
4. API监听8017，前端以NOTES_API_TARGET=http://127.0.0.1:8017在5187启动。设置NODE_PATH到含Playwright的运行库后执行`node frontend/scripts/phase2-browser-check.cjs <输出目录>`，访问`/tests/visual/phase2.html`及隔离Mermaid矩阵。
|
||
5. `backend/.venv/Scripts/python -m pytest backend/tests -q -p no:cacheprovider`；前端目录`pnpm test -- --reporter=dot`、`pnpm build`。压力脚本`backend/scripts/agent-task-stress.py --output <report.json>`自建隔离数据。
|
||
|
||
浏览器产物及完整测试日志保留于本机`.local-plans/phase2-completion/`；可复查的配置、指标与逐例证据已提交文档目录，不依赖该忽略目录才能读到结果。主工作区两份原有未提交笔记未修改。
|
||
|
||
## 最终验证记录
|
||
|
||
后端861测试通过（Python 3.13.9，48.32s），含HTTP/OpenAPI、预览累计复杂度、重复资源预算、导出、评分、取消与缓存回归；仅1条既有Starlette/httpx弃用提示。前端80文件437测试通过，vue-tsc及Vite生产构建通过；KaTeX仅一个261.18kB运行时chunk（gzip77.76kB），大惰性分块警告仍保留。
|