dsh-searchflow — 搜索流程动效可视 + 快照加速

DSH 实时搜索加速插件，两件事：

1. 可视化 — 把 web_search → web_fetch → web_snapshot → browser_open/click → read 每一步实时呈现在工具调用行内：用动效 wb_* 图标（运行中蓝光呼吸 / 完成绿勾 / 失败红 X）替换默认的通用图标，黑盒等待变成可见的前进。同时用 ⚠ 挑战 / ⚠ 404 / ⚠ 噪声 徽标标记 Cloudflare 挑战页与 404 页等「假成功」结果。任务级另见下方「搜索流程卡片」——搜索中 → 阅读中 → 撰写中 阶段进度条 + 渐进结果流 + 完成摘要行。
2. 加速 — 在 tools/execute 瀑布中拦截（不改任何上游包）：
   • web_snapshot 命中缓存直接短路（90s 全量渲染 → 5ms）
   • browser_open 命中缓存立即返回已渲染内容，真实导航在后台预热（省 networkidle 8s + 全页截图）
   • 搜索结果 Top-3 自动预取预热内存缓存
   • URL 变体（www / 非 www / 尾斜杠 / 参数顺序）共享同一缓存键

架构

┌─ Host (lib/index.js) ─────────────────────────────────┐
│  ctx.on('tools/execute') ── 观察 web_*/browser_* 工具   │
│     → EventBus (start/completed/error, 含 cache/rule)   │
│  GET /searchflow/events (SSE) ── 回放 + 实时事件流       │
│  web_snapshot / browser_open 缓存拦截 + Top-N 预取      │
└────────────────────────────────────────────────────────┘
        │ EventSource
┌─ Client (lib/client.js) ──────────────────────────────┐
│  工具调用行内动态图标（搜索/抓取/快照/点击/阅读/导航）     │
│  running/done/error 实时切换 + 行级高亮 + 光晕           │
│  搜索流程面板：better-sidebar 在场 → 页签；缺席 → 浮动卡片 │
└────────────────────────────────────────────────────────┘

客户端采用 ModuleLoader 单文件自包含（图标内联，无相对路径依赖，无需构建步骤），与 dsh-icon-workbench / dsh-guardian 同型。

泳道映射

阶段	工具	图标
search	web_search / web_search_pro / web_platform_search / github_issue_list / browser_automation_search / wiki_recall / mcp_search	拉匣寻物
fetch	web_fetch / web_fetch_pro / web_exa_contents / browser_crawl / wiki_acquire	抓取
snapshot	web_snapshot / browser_screenshot	取景·定影
click	browser_open / browser_click / browser_type / browser_hover / browser_set_files / browser_recipe_run / browser_scroll / browser_automation_run	指尖按靶
read	browser_read / browser_evaluate / browser_status / browser_opencli_* / browser_script_* / wiki_* / mcp_call / web_rule / web_history / web_search_stats / github_issue_read 等	16宫格扫描
navigate	其它导航类	路径绘制

每个工具调用附带状态：缓存（fromCache 命中）与 规则（usedRule）徽标，加速效果可感可验证。

搜索流程卡片（Wave 1 观感升级）

工具行内图标之外，新增任务级「搜索流程」浮动卡片（右下角，搜索开始时出现，可收起/点击展开）：

• ⚡ 深度模式（默认关）：卡片头部金色闪电开关，开启后宿主在搜索前自动扩展查询——CJK 查询加英文学术关键词（overview survey），英文/拉丁查询加中文综述关键词（最佳实践 综述）。卡片实时显示「深度」徽章。通过 GET/POST /searchflow/deep 端点同步状态。
• 阶段进度条：搜索中 → 阅读中 → 撰写中 三段芯片，直接复用现有动效图标（进行中呼吸 / 完成绿勾绘制 / 空闲静置），配渐变连线与对齐标签行；「撰写中」由事件空闲 3.5s 推断（模型开始作答），完成后 9s 自动折叠成小胶囊。结果行带域名 hash 色徽章，双轮命中显示金色交叉验证勾。
• 渐进结果流：搜索完成事件携带 top-6 结果（标题 + 域名 + 摘要截断 ≤140 字符），客户端逐个浮现（70ms 错峰），可点击直达原文。
• 完成摘要 chips：进入「撰写中」后底部出现统计胶囊 —— 总耗时 · N 来源 · 去重 · 验证 高/中/低 · ≈tokens，速度/广度/可信度/省 token 一次可感知，不暴露任何引擎归属（引擎是内部实现细节）。进入撰写中时 doneAt 记时点，时间从「进行中 Xs」冻结为「总耗时 Xs」，不再继续累计。
• 数据来源：宿主 tool:completed 事件新增 durationMs / resultCount / distinctDomains / sourcesTop / charCount；token 估算 = 摘要字符数 / 3.5；交叉验证置信度 = 多次搜索重复域名占比（≥2 次搜索才显示）。纯观察层实现，零上游依赖。
• 无障碍：prefers-reduced-motion 下禁用全部动画；任务状态经 window.__SF_DEBUG__.task 透出便于诊断。

宿主形态：better-sidebar 页签 / 独立浮动卡片

搜索流程面板（阶段进度 + 结果流 + 摘要）有两种寄生形态，同一份实现（SearchFlowCard 的 variant），自动选择：

形态	触发条件	表现
页签	ctx.betterSidebar 在场	注册为侧栏页签（id searchflow:panel，single，order 96）：铺满容器、结果区占满剩余高度并自滚动、显示空态、不自带浮动外框与收起按钮
浮动卡片	better-sidebar 缺席	维持右下角卡片（fixed / 368px / 毛玻璃 / 可收起成胶囊）

• 软依赖：better-sidebar 是可选同伴，只按结构探测 ctx.get('betterSidebar')，不 import 它的类型（否则软集成会变成硬构建依赖）。注册后回读 getTab 校验；读不到就抛错并退回浮动卡片——宁可有卡片，不可没面板。
• 迟到接入：better-sidebar 比本插件晚挂载时，ctx.inject(['betterSidebar']) 一到就换成页签并撤掉浮动卡片，避免同一份数据在屏幕上有两个出处。
• 可见性：宿主给 visible=false（页签被切走）时停止 400ms 重绘定时器。
• 手动覆盖：localStorage['sf.host'] = 'dock' | 'tab' 强制形态（默认 auto）。
• 诊断：当前形态写在 document.body.dataset.sfHost（tab / tab-late / dock），面板根节点带 data-sf-variant。页签角标 = 进行中流程的结果数。
• 已知边界：宿主事件流不区分会话（tools/execute 是进程级观测），所以页签展示的是全局搜索流程，不随会话隔离；页签声明 single，只会有一个。

检索记录（悬挂，仅页签形态）

侧栏空间够，所以一次检索结束不等于它消失：新的搜索开始时，上一轮不会把面板就地覆盖，而是下移成「检索记录」里的一条挂在页签底部，可以随时翻回去。

• 一条记录 = 一行：查询词（tool:start 的 summary）· 时间（HH:MM）· N 次搜索 · M 个独立来源。点一下展开，看它自己的结果列表 + 摘要 chips（总耗时 / 来源 / 去重 / ≈tokens）。
• 顺序与上限：最新在前（进行中的那轮在上面，历史在它下面）；最多 SF_HISTORY_MAX = 20 条，展开单条最多列 SF_HISTORY_RESULTS = 30 条结果。
• 不记录空任务：只跑过 browser_open 之类、既没搜索也没结果的任务不占位置。
• 没有进行中的检索时，页签显示「当前没有进行中的检索」+ 记录列表，而不是一块空面板。
• 浮动卡片不显示记录：卡片就那么点地方，堆历史只会挤掉当前任务 —— 这条只在页签形态出现。
• 换会话不会清空：切换会话时，正在跑的那一轮会被归档成记录再放手（而不是像以前那样直接丢掉），记录本身跨会话保留 —— 宿主事件流不区分会话，记录也就是全局的。
• 生命周期：记录是页面会话级的（内存），刷新后由宿主 SSE 回放重建最近一轮；不做 localStorage 持久化。

什么算作一次「搜索」

只有宿主 TOOL_PHASE 里映射为 search 的 4 个工具才算一轮检索的开始：

工具	阶段
web_search / web_search_pro	search
web_platform_search	search
github_issue_list	search

其余网页工具都不算搜索：web_fetch / web_fetch_pro / web_exa_contents（fetch）、web_snapshot / browser_screenshot（snapshot）、browser_open / browser_click / browser_type / browser_recipe_run / browser_scroll（click）、browser_read / web_rule / web_history / web_search_stats / web_backend_status / web_deps / github_issue_read 等（read）。

三条规则：

1. 只有搜索能开一轮新任务。fetch / snapshot / click / read 只顺带推进已经在跑的那一轮；没有在跑的检索时它们什么都不开 —— 否则 agent 单纯打开一个网页，面板就会以「搜索流程」为标题冒出来显示「0 次搜索」。
2. 搜索次数按工具身份计，不按"有没有带回结果"计。一次真的搜索哪怕 0 结果（宿主没有 sources 可发、事件里就没有 sourcesTop），也记「1 次搜索 · 0 来源」—— 这和"根本没搜过"是两回事。
3. 既没搜索也没结果的任务不进记录（例如只有 browser_open 的一轮）。

知识库 / MCP 工具（dsh-learn-wiki / dsh-mcp-lens 集成）

知识库检索与 MCP 检索也会出现在泳道里（wiki_recall/mcp_search 用 search 图标、wiki_acquire 用 fetch 图标、其余 wiki_*/mcp_call 用 read 图标），但它们不算 Web 搜索：

• 开新一轮检索的判据 = 工具身份，不是 phase 字符串。只有 web_search / web_search_pro / web_platform_search / github_issue_list 四个工具能开一轮；wiki_recall / mcp_search 虽带 search 阶段（行内图标友好），但不会误开「搜索流程」面板、不会计为一次搜索（客户端 SEARCH_TOOLS 白名单守卫）。
• wiki_recall CRAG 判定徽标：宿主把 wiki_recall 的 bucket（hit/weak/miss）随完成事件发出，卡片/记录的「本次检索小结」会出现 知识库 命中/弱命中/未命中 芯片（绿/琥珀/红）——miss = 知识库没答上、这轮才去搜的外网，补料闭环（L3 自动补料该补什么）一眼可辨。
• L3 补料边界（实测）：learn-wiki 的自动补料走 ctx.web.search/fetch 服务（lib/acquire.js），不经 tools/execute 瀑布——searchflow 看不到、也不拦截不加速它。只有 agent 显式调用 wiki_acquire（映射为 fetch 阶段）时，补料过程才以单个工具调用形式出现在泳道里。
• 补料数据衔接：searchflow 每次 Web 搜索的 sourcesTop / charCount / curl 遥测本身是 wiki_learn 来源（sources=）的现成数据——检索到的好结果可顺手沉淀为知识页（两段式 staged → commit）。

加速细节

拦截点	行为	收益
web_snapshot	内存 LRU(200/1h) + web-search-pro store.db（只读）双层缓存，命中短路返回 {value}	90s → 5ms
browser_open	命中缓存立即返回已渲染内容；真实导航 fire-and-forget 后台预热（active page 保持就绪，后续 click/type 语义不破坏）	~13-18s → ~0ms 前台等待
搜索结果 Top-3	web_search* 完成后对结果 URL 串行预取渲染写入内存缓存	后续 open/snapshot 直接命中
URL 规范化	去 www / 尾斜杠 / 默认端口 / 参数排序，变体共享缓存键	变体重复渲染归零
噪声检测	Cloudflare 挑战 / 404 页 / 噪声查询 → ⚠ 徽标	假成功一目了然

可选性：browser 服务通过 ctx.get 软依赖（未安装 dsh-browser 时预取静默降级，不影响可视化与 snapshot/browser_open 缓存）。

安装

dsh plugin --profile web add dsh-searchflow          # 已发布/已收录后
dsh plugin --profile web add /path/to/dsh-searchflow # 或直接从源码目录/GitHub 地址装

重启 profile 后生效。卸载：dsh plugin --profile web remove dsh-searchflow。

发布为即插即用插件：本包是标准 DSH bundle（dsh.bundle.patch + dsh.client），pnpm pack / git 地址均可用 dsh plugin add <spec> 安装。

开发

• lib/index.js — host：tools/execute 观测 + 缓存拦截 + SSE（需 webServer、tools 注入；browser 为可选软依赖）
• lib/client.js — client：ModuleLoader 单文件自包含（内联图标，相对路径 require 不解析）
• lib/icons.js — 共享图标源（供抽取参考；实际 client 内联）
• preview.html — 独立泳道预览（vendor/ 本地 React UMD），含成功/错误双流程演示脚本
• test-realistic.mjs — 回归测试（node 直跑，无依赖）
• test-sidebar-tab.mjs — better-sidebar 集成回归（jsdom + 真实 React 18；jsdom/react 从 DSH 应用运行时解析，解析不到则 SKIP）

验证

node --check lib/index.js lib/client.js lib/icons.js
node test-realistic.mjs
node test-wave1.mjs
node test-sidebar-tab.mjs

覆盖：B#1 快照同 URL 短路、B#3 www/尾斜杠变体共享键、B#4 browser_open 缓存命中 + 后台 warm 刷新、B#5 无 browser 服务时预取静默降级。host 运行时以 node 模拟 cordis ctx 实测通过。

test-sidebar-tab.mjs（46 项）覆盖六组：A better-sidebar 在场（注册页签 / 不挂卡片 / 空态可渲染 / 事件驱动后阶段条与结果流出现 / 角标有数）、B 缺席（浮动卡片 / 登记迟到接入）、C sf.host=dock 手动钉住、D 浮动卡片回归（fixed 定位、368px、结果与摘要、收起胶囊）、E 检索记录悬挂（旧的一轮被归档而非覆盖、记录保留查询词与结果、记录区渲染、展开可见结果、20 条上限、空任务不占位）、F 浮动卡片不长出记录区。E 组用可推进的假时钟跨过 30s 任务间隔。

License

MIT