第二阶段收尾实现与验收

日期：2026-09-07。实现提交 89df10b，开发分支 feat/phase2-completion，基于最新拉取的 gitea/main / 95095197df8b607e55144748c9be0c7f6daf00df。本分支尚未合并、推送或发布。本记录覆盖所有成员的第二阶段工程范围，替代早期“不含杨侧验收”的当前状态口径；此前全量审计保留为修复前基线。

结论

原审计中可在现有环境推进的主要缺项已实现：标准 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。

配置	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

标准报告：现有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运行报告。修复了未打开工作区时无法从报告进入已有Trace的路由拦截；创建普通新Agent运行仍遵守原工作区入口约束。

集成报告：检索→读笔记→3个任务创建，以及MCP web_search，共2/2通过，工具6/6匹配，16070 Token。写入仅针对隔离数据库的3个任务，按这次运行的权限票据逐项批准。报告保留真实Agent Run ID，可在保留隔离数据库时恢复Trace；Benchmark报告本身是有界内存任务，应下载保存，重启不会恢复评测注册表。

上下文复测：不修改已保存Provider配置，在请求级测试配置中设8192窗口；detect在网络前返回CONTEXT_COMPRESSION_REQUIRED，compress调用真实模型生成摘要再回答，估算从2262降至516，原会话不变，最终答案保留Vault事实。首次256输出Token预算耗尽，见失败记录；改用1024上限后最终回答使用289输出Token并通过。四次受限调用包含两轮摘要及回答。该测试验证应用的预算与压缩路径，不证明厂商最大窗口。

验收库中18个该Provider请求上报缓存计数，13个有正命中、18个有正未命中；缺失字段保持未知，不记作0。缓存是否命中由服务商控制，不能强制保证。没有新增账号、密钥或服务，没有打印凭据或请求认证信息。

外部剩余项：当前未配置OpenAI Responses、Anthropic Messages、Ollama真实服务，协议单测通过仍不足以替代真实服务矩阵；厂商极限上下文需要单独预算与目标窗口。本轮没有发出超大输入探测。

性能与回归

后端全量与前端测试/构建结果以本报告末尾最终验证记录为准。
串行压力基线与修复后：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任务并看到已取消终态。页面结果、Mermaid矩阵。窄屏函数图保留640px坐标区域并可横向滚动，避免刻度被整体缩得过小。

PDF使用嵌入的可用CJK字体，已通过Poppler检查实际页面；未安装可用字体时保留CID回退并明确warning。可用APP_EXPORT_FONT指定兼容TTF/TTC。三格式包含未保存快照、函数图、中文Mermaid及公式；DOCX的OOXML、图片关系和媒体内容通过结构检查，参见产物清单。捆绑文档渲染器因缺少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绘图线程。

复现

uv sync --frozen 与 pnpm install --frozen-lockfile；把APP_DATA_DIR/APP_DB_PATH/APP_VAULT_PATH指向全新验收目录，不能指向用户知识库。
仅在用户授权下复用已有Provider凭据及模型配置；APP_MODEL_PYTHON指向已安装模型解释器。语料源为backend/data/benchmarks/corpus/phase2-v1.json；运行backend/scripts/phase2-quality.py --output <report.json>，生成独立Vault和Dataset、重建真实索引。--reuse-index会验证块ID一致，不能跳过缺失索引。
标准真实测试：backend/scripts/phase2-live.py --provider <已有ID> --output <report.json> --execute；上下文phase2-context.py同参数。写任务/MCP测试用phase2-integration.py --execute，先查脚本中隔离端口与现有工具ID；不能复制到生产Vault直接执行。
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矩阵。
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），大惰性分块警告仍保留。

12 KiB Raw Permalink Blame History Unescape Escape