feat: 固定本地检索进度总量，优化 AI 执行过程展示

design-qa.md

@@ -1,3 +1,110 @@
+# 本地检索固定总量验收 · 2026-09-15
+
+- final result: passed
+- 本节为最新验收；下方记录保留历史方案，原「预计总量、完成校准」已由固定本轮清单取代。
+- source visual truth path: `output/local-search-progress/total-desktop.png`（上一版面板）。
+- implementation screenshot path: `output/local-search-progress/fixed-total.png`、`fixed-counting.png`、`fixed-narrow-dark.png`（均在同目录）。
+- viewport: 1280×720 CSS px；比较截图均为 1280×720 像素，未额外缩放。宽容器 1000px，窄容器 480px。
+- state: 整理中、统计中；浅色宽屏、深色窄屏；正式组件使用明确标注的虚构数据。
+- full-view comparison evidence: 在同一输入中查看上一版总量面板、新固定总量面板和统计阶段截图；保留阶段、进度条、四项数字与处理详情的层级。
+- focused region comparison evidence: 完整截图中统计区域清晰可读，无需裁切；窄屏另行检查两列数字、分母和提示文字，无截断。
+
+## 五项核验
+
+- 字体：主数字和次要分母维持原有字号、字重；「本轮总量」取代「预计总量」。
+- 间距：宽屏四列、窄屏两列；保存进度与固定分母同组，长提示自然换行。
+- 颜色：沿用绿色保存进度和蓝色累计索引，深色数字清晰。
+- 图像：无新增位图，沿用现有状态图标和原生进度条。
+- 文案：统计时明确说明统计完成后开始整理；不显示中途增长的统计值或虚假百分比。整理时说明本轮固定、新消息下一轮。
+
+## 行为与验证
+
+- 先分页准备完整消息清单、去重并确定总量，然后开始模型整理；进度条按已保存消息 / 固定总量计算。
+- 暂停、重启沿用同一清单；源消息删除、新增或补入旧消息不会改变已冻结的总量。未完成任务不因后台发现新会话而扩大范围。
+- 清单暂存在本地 SQLite，完成后清理；首次统计增加等待时间和临时磁盘占用。清单丢失时明确报错，保留已有索引，不静默重算分母。
+- 83 项后端测试、54 项前端测试通过；覆盖完整准备先于编码、固定总量、源数据变动、暂停续接、统计失败重试、零值及旧任务兼容。
+- 浏览器 console error 为空；机械扫描无发现；目标文件 diff 检查通过。最终无 P0/P1/P2 视觉问题。
+- 当前桌面后端尚未重启，新后端逻辑需重启项目后加载。验收使用测试与隔离预览，未对真实聊天触发额外整理。
+
+final result: passed
+
+---
+
+# 本地检索消息总量补充验收 · 2026-09-15
+
+- final result: passed
+- source visual truth path: `output/local-search-progress/desktop.png`（已接受的面板），本轮要求在已读取消息旁增加总量。
+- implementation screenshot path: `output/local-search-progress/total-desktop.png`、`output/local-search-progress/total-narrow.png`。
+- viewport: 1280×720 CSS px；源与实现截图均为 1280×720 像素，工具已归一为 CSS 像素，未额外缩放。
+- state: 浅色、整理中、虚构数据；宽容器 1000px，窄容器 480px。
+- full-view comparison evidence: 同一输入并列查看原面板、新宽屏、新窄屏三张截图。所有主体布局保留，首项增加小字号分母 58,735，显示为 26,286 / 58,735。
+- focused region comparison evidence: 数字、标签与分母在完整截图中均可读，未额外裁切。
+
+## 五项核验
+
+- 字体：现有 24px 主数字保留；分母 14px、普通字重，清晰区分当前数与总量。
+- 间距：分母同行基线对齐，宽度不足可换行；窄窗口各统计项 clientWidth / scrollWidth 均为 182px，无溢出。
+- 颜色：分母使用现有次要文字令牌，继承深色主题；绿色与蓝色统计保持原样。
+- 图像：未新增图片或替换图标。
+- 文案：标明「预计总量」，本轮范围与去重校准规则放在处理详情；未知值不伪造分母。
+
+## 证据与边界
+
+- 浏览器无 console error；宽窄截图无 P0/P1/P2 问题，无需视觉修正。
+- 52 项前端测试通过；77 项后端测试通过。覆盖当前任务绑定、零值、未知/失效总量、范围合并、取消、失败降级、完成校准和禁止正文回退扫描。
+- 机械扫描无发现，修改文件 diff 检查通过。
+- 后端统计为新代码；现有运行服务需重启后加载。本轮未重启正在运行的桌面服务，也未对真实聊天触发额外索引。
+
+final result: passed
+
+---
+
+# 本地语义检索进度面板验收 · 2026-09-15
+
+- final result: passed
+- source visual truth path: `C:/Users/123/AppData/Local/Temp/codex-clipboard-6525eb58-700d-4983-a2a4-2eb62d433f8a.png`
+- 改造对象参考：`C:/Users/123/AppData/Local/Temp/codex-clipboard-271309b8-7457-4ccd-8051-81f66f0c1b58.png`
+- implementation screenshot path: `output/local-search-progress/desktop.png`
+- 补充截图：`output/local-search-progress/narrow-dark.png`、`initial.png`、`error.png`（均在同目录）。
+- 本地预览：`http://127.0.0.1:4173/tests/fixtures/local-search.html?progress=running`
+- 预览挂载正式 LocalSearchSettings 组件，数据为明确标注的虚构快照；未操作真实索引。
+
+## 对比依据与范围
+
+图一是语音任务的样式参考，图二是语义检索的改造对象，并非要求复制语音转换页面。参考图一 1800×1200、图二 1474×1104；最终浏览器截图 1280×720（工具输出按 CSS 像素归一）。浏览器视口 1280×720 CSS px；宽容器约 1000px，窄窗口容器 480px，状态卡约 417px。未拉伸图像，未把原图系统缩放或不同内容产生的尺寸差认定为视觉缺陷。
+
+已在同一图像比较输入中打开图一和 desktop.png，重点对比进度区的结构：阶段与状态标签、通栏绿色进度条、数字优先的四列统计、下方辅助说明。两张完整截图中的进度区均能直接读清，不需要额外裁切。语义检索继续使用自己的消息/片段/索引统计，未引入语音任务的失败数或成功数。
+
+## 五项视觉核验
+
+- 字体：保留现有系统中文字体；阶段 14px，主要数字最高 24px、600 字重，启用等宽数字。标签与说明降低层级，数字不再混在整句中。
+- 布局：白色面板、12px 圆角、20px 内边距；四列统计平铺，累计索引有细分隔线。容器小于 520px 改为两列，DOM 检查各项 scrollWidth 等于 clientWidth，无横向溢出。
+- 颜色：沿用产品绿色。绿色表示已保存，蓝色区分累计索引，错误用明确图标与文字表达。深色数字使用 #64d49c 和 #9aafd7。
+- 图标与图像：使用项目已有 Font Awesome 图标，无新增位图或占位图。参考中的纯 UI 元素用原生 progress 和组件样式实现。
+- 内容：百分比按任务已完成会话时间段计算，未知总数为不定进度。实时生成与事务保存数量分开；运行中可见暂停入口；批量、复用、索引模式移至处理详情，错误和警告保持展开。
+
+## 检查历史
+
+1. 首轮宽屏对比通过；窄窗口深色截图发现 [P2] 统计绿色/蓝色过暗，scoped CSS 的全局主题选择器未命中状态卡。
+2. 修正完整全局选择器；再次截图 `narrow-dark.png`，确认绿色变量为 #64d49c，绿色/蓝色数字清晰；两列无截断。无其他 P0/P1/P2 问题。
+
+## 交互与验证
+
+- 浏览器检查详情展开/收起、暂停、首次零进度、错误提示、深浅色、窄窗口。
+- 暂停后实际显示已保存片段 4,180，替换生成中片段 4,260；保留 43% 进度并提供继续整理入口。
+- 浏览器 console error 列表为空。
+- `vitest run tests/local-search.test.js --root frontend`：46 项通过，覆盖进度口径、未知/空范围、零值到完成、错误外显和原有事件/暂停语义。
+- Impeccable 机械扫描无发现；目标文件 `git diff --check` 通过。
+- 验证边界：组件与虚构任务状态验证；未重新运行真实模型或索引流程，后端未修改。
+
+## 结论
+
+final result: passed
+
+---
+
+以下保留此前任务的验收记录：
+
 # AI 助手改版验收
 
 - 日期：2026-09-08
@@ -471,3 +578,33 @@ final result: passed
 - 浏览器已检查强度和列表两态，回到强度态保留预览。10 项既有组件回归通过，git diff --check 通过。前端热更新已生效，无后端改动。
 
 final result: passed
+
+## 2026-09-15 读取小节点详情面板
+
+- 范围：AgentToolCall 的逐次读取节点；保留独立运行详情入口和已有执行过程结构。
+- 视觉来源：C:/Users/123/AppData/Local/Temp/codex-clipboard-1a0a8fe1-af94-4454-999b-6998fb7bc653.png（979×270），C:/Users/123/AppData/Local/Temp/codex-clipboard-54baee6a-21f0-4a21-888f-5a96545bed0a.png（735×1048）。前者定义展开面板，后者定义挂载位置。
+- 实现截图：tmp/agent-node-details-20260915/light-expanded.png、dark-expanded.png。
+- 预览：http://127.0.0.1:3057/tests/fixtures/agent-progress.html?nodes=1；仅合成数据。
+- 视口：1280×720 CSS px，浏览器 DPR 1.75，截图工具输出 1265×712 px。参考图未提供缩放比例；按节点与面板内容区域比较结构与效果，不以原图字号像素推断应用字号。
+- 状态：10 次读取，首节点展开，其余折叠；另测第二节点键盘展开、运行态、浅色和深色主题。
+- 对比证据：命令详情参考与实现截图在同批图像输入中展示，随后将节点列表参考与同张实现截图同批展示；聚焦首节点、浅灰面板、输入参数、结果和右下角状态，宽面板及窄侧栏均清晰可读。
+
+### Findings
+
+无待处理 P0/P1/P2。一次视觉比较通过；修复过一项旧测试对保存节点提示文字的断言，保留其原有提示。没有据截图追加视觉调整。
+
+- 字体：沿用现有系统字体、12px 详情与 11px 状态；参数使用现有等宽字体回退。保持应用密度，不复制参考截图的放大比例。
+- 间距：每个小节点独立箭头，展开区域紧随该节点；6px 圆角、10px/12px 内边距，竖线随面板高度延伸。窄面板约 231 CSS px，无横向溢出，日期自动换行。
+- 颜色：复用 ag-soft、ag-muted 等明暗主题变量；浅灰背景，完成状态右对齐；失败状态保留文字和图标，运行态使用既有 shimmer。
+- 图片与图标：无新增位图需求，全部使用现有 Font Awesome 图标，未将参考中的命令内容或批注复制为图片。
+- 文案与数据：本次会话、查询条件、分页位置、返回数量和状态来自已有节点数据；显示零分页位置，不伪造 Shell 命令。运行详情结构保持不变。
+
+### Implementation Checklist
+
+- 鼠标和 Enter 均可展开单个节点；节点互不干扰。
+- 进度更新保留展开选择；组件测试覆盖外部保存状态与本地状态，以及重新挂载。
+- 81 项相关测试已通过（22 项工具详情、26 项时间线、33 项聊天面板）。
+- 浏览器错误日志为空；改动文件 diff --check 通过。
+- 限制：浏览器使用合成数据，未调用真实模型。沿用现有全部结果文案与错误分支，未更改后端。
+
+final result: passed

docs/local-semantic-search.md

@@ -90,6 +90,10 @@ GPU 进程故障、超时、缺库或显存不足时销毁故障进程，在独
 - 默认自动批量（`read_batch_size=0`）。总内存不超过 4 GiB 或可用内存不足 1 GiB 时最多 100 条；总内存不超过 8 GiB 或可用内存不足 3 GiB 时最多 500 条；其余情况自动使用 1,000 条。高级设置可选 100／500／1,000／2,000 条，手动选择仍受内存保护，每批重新检查。不依赖 NVIDIA 显卡是否存在。
 - 单批累计文本达到 128,000 字符时提前处理，避免少量长文本积累过多片段；保留完整单条消息，因此此阈值不是进程内存的硬上限。推理仍按最多 8 个片段执行，不随读取批量扩大显存需求。低内存策略通过模拟测试，其他硬件、系统和磁盘速度仍需实机验证。
 - 读取数量约每 250 ms（有新消息时）上报一次，页尾立即上报；SSE 每秒传递事件，1.5 秒轮询兜底。界面直接更新读取数、片段数、实际批量和已保存进度，较旧事件或轮询响应不得让进度倒退。设备状态不变时不重复写入相同事件。
+- 整理采用固定轮次：先显示「正在统计消息总量」，按任务开始时的聊天目录、截止时间和本轮范围准备完整清单并去重，再显示「已读取 / 本轮总量」。统计中的临时数量不会作为分母展示；统计失败则保留断点并等待重试，不提前进入推理。
+- 本轮总量发布后不再增长、隐藏或在完成时校准，进度条按「已保存消息数 / 本轮总量」计算。后台发现的新会话不会打断未完成轮次；统计完成后收到或补入的消息留到下一轮。
+- 为避免统计与实际读取之间的数据变化，准备清单时会分页暂存本轮消息，之后直接从本地暂存数据整理，不再第二次读取微信正文。内存按分页条数和字符数限制；首次整理需等待全部统计完成，并临时占用额外磁盘空间。暂存文件位于本地检索数据目录的 `plans/` 下，按账号与任务隔离。
+- 暂停或重启保留统计断点及已固定的消息清单；旧任务迁移时将已保存数量纳入本轮总量。完成后自动清理临时清单，调整配置、清理索引或删除账号时也会清理。已固定清单丢失时提示从头整理，不静默重新统计成另一个总量。
 - 最小化继续处理；退出停止。重启恢复此前运行任务，主动暂停保持暂停。数据和断点仍在同一事务提交，读取中的数量不用于恢复；失败或暂停只保留已提交批次，大批写入期间每 100 条检查取消。恢复时会重读尚未保存的一批。
 - `members(source,chunk)` 索引保证按原消息查找关联片段时不扫描整张关联表，适用于新建及已有索引。批量去重和关联查询在后台线程执行。
 - 关键词及向量分别最多召回 200 条，按来源去重、RRF（常数 60）融合。查询票据固定账号、权限版本、范围及候选顺序，有效十分钟，最多缓存 32 次查询。检索文本返回前再次按原消息权限和过滤条件约束，不返回片段内越权相邻原文。