@240xu/dsh-session-search
DSH web 插件：跨会话全文搜索。对 ~/.dsh/sessions 下全部会话日志（多帧
zstd，v3 格式）建立消息级全文索引，一条关键词查回所有历史会话的命中位置
（sessionId + seq ±60 字符窗口摘录）。
- 零 npm 依赖（node:zlib zstd + 纯 JS）；
- 对
~/.dsh/sessions 零写入：索引缓存是唯一写点，存
$DSH_HOME/cache/session-search/index.json（原子写 tmp+rename）；
- 侧边栏零触碰：无任何 sidebar 注册面，UI 是独立面板页
/api/session-search/panel（devkit 装了可由 Ctrl+K 命令指向该 URL）；
- 信任围栏硬门槛：全部路由先过
isTrustedApiRequest（回环 Host 挡
DNS rebinding + sec-fetch-site: cross-site 拒绝 + Origin 同源校验），
与 dsh-message-ops 0.2.1 同款（arch-review L4/L5 教训）。
端点
| 方法 | 路径 | 说明 |
|---|
| GET | /api/session-search?q=&limit=20&project=<slug 可选> | 跨会话搜索；大小写不敏感子串（indexOf，防 ReDoS）；命中按会话 mtime 新→旧 |
| GET | /api/session-search/panel | 独立 HTML 面板页（搜索框 + 结果列表 + 「复制定位」） |
| POST | /api/session-search/refresh | 手动触发增量刷新（Content-Type 必须 application/json） |
Agent 工具
session_search（peer @deepseek-ai/dsh-tools，容错注册——tools 服务缺失或
包不可解析时只跳过工具，HTTP 面不受影响）：参数 q（必填）、limit（1-100）、
project（slug 过滤）。输出每行 [slug] title/id seq N (type): snippet，定位符
在前、摘录在后（见「权威依据」节）。
安装
# 方式一：独立安装（推荐先这样试）
dsh plugin --profile web add @240xu/dsh-session-search
# 方式二：随聚合包安装（会带入本插件及另外三个插件 + 官方 Inspector）
dsh plugin --profile web add @240xu/dsh-plugin-hub
装完重启 dsh web。独立安装与聚合包安装可以共存，浏览器 UI 只显示一份；
宿主侧可能出现一行 already registered 警告，工具只保留一份，属已知噪音。
索引与性能取舍
- 索引条目 = 每条 user/assistant/system message 的
{seq, type, text(截 500 字符)}；
tool/call 与空文本不入索引（工具调用文本噪声大且无对话语义）。
- 增量判定：会话日志
mtimeMs + size 与缓存一致 → 跳过；变更/新增重扫该会话；
消失的会话从缓存移除。
- 检索：大小写不敏感
indexOf 线性扫描内存数组（按 mtime 新→旧的会话序遍历，
满 limit 即停）。本地规模（数千会话 × 数百条消息）亚秒级，未做倒排/分词。
- 首次全量构建：逐帧解压每 8 帧
setImmediate 让出事件循环（大会话不冻结 GUI）。
权威依据与取舍（读了什么 → 采纳/拒绝）
- node:sqlite vs JSON 索引 — Node 22.5+ 内建
node:sqlite（DatabaseSync，
Node v26 SQLite 文档）。拒绝迁移：
本插件索引是单进程、单对象（≤几 MB）的轻量投影，tmp+rename 原子写已满足
一致性；而检索核心是 CJK 子串匹配，SQLite FTS 默认分词器不处理 CJK 子串
（trigram tokenizer 需要额外配置且索引体积 ×3），换 schema 反而偏离「零依赖、
可整包删缓存」的目标。采纳路径：若未来语料涨到十万级消息或需要相关性
排序，再迁 node:sqlite（FTS5 + trigram），接口 SessionIndex.search() 不变。
- worker_threads — Node Worker threads 文档
建议 CPU 密集 JS 出主线程。暂缓：索引构建的耗时大头是 zstd 同步解压 +
JSON.parse，已用帧间
setImmediate 让出（每 8 帧一次）把 GUI 卡顿压到帧级；
worker 化的收益（彻底零阻塞）要付出每会话一次结构化克隆的序列化成本与
worker 生命周期管理，在「首次构建 < 数秒」的本地规模下不成比例。采纳阈值：
真实语料首次全量构建 > 5s 时再出 worker（readSessionFileAsync 的让出粒度
参数已预留调优空间）。
- snippet 策略 — Tavily Search Best Practices：
面向查询的短片段（chunks）优于整页摘要；
max_results 过高反而稀释质量
（→ 本插件 limit 钳制 1-100、默认 20）。采纳：±60 字符窗口 + 首尾 … 的
query-aligned 摘录。Anthropic long-context prompting /
Contextual Retrieval：
相关内容置于上下文前部、给出来源引用。采纳：工具输出与面板条目都是
「定位符（slug/session id/seq）在前、摘录在后」，让模型/用户先拿到 citation
再读内容；agent 多轮检索的 dedupe 思路（Tavily [...] 分隔符合并唯一内容）
留作工具输出的后续优化。
已知重复（待 suite 聚合层收口）
与生态其它插件存在有意复制（保持插件自包含、不跨包 import），待
@240xu/dsh-plugin-hub 聚合层提供共享工具后收口（agg-researcher L3 建议）：
src/fence.js 的 isTrustedApiRequest ≡ dsh-message-ops ops-core.js 同款
（arch-review 要求的上线硬门槛，复制是安全侧的选择）；src/session-file.js 的多帧 zstd 帧扫描/读取 ≡ dsh-message-ops session-file.js、
dsh-session-lazy-view frames.js（同源实现，帧魔数扫描的取舍三处一致）；messageText（message 事件 → 首个非空 text 块）与 dsh-message-ops 重复。
开发
npm test # 33 个零依赖测试（node --test，含围栏 403/415 与增量跳过）
node --check src/*.js
License
MIT
v0.1.4
- 命中项新增「在 Timeline 打开」按钮：直达 lazy-view 时间线深链
/lazyview?session=<id>&seq=<seq>（lazy-view ≥0.3.0）。
- 主搜索按钮触控目标提升至 ≥44×44px（.acts 辅助钮 36px 下限）。
- 搜索请求飞行中按钮 disabled（含失败恢复），防重复点击。
0.1.5 · Bug 猎场修复（P1 毒化 + P2）
- [P1] refresh 被 rejected promise 永久毒化：async IIFE 首个 await 前同步抛出
（如缓存目录被占位 → saveCache mkdirSync 抛）时，内层 finally 的
scanning=null
先于赋值执行，随后 rejected promise 永久挂上 → 索引/搜索 500 到进程重启，且坏缓存
无法自愈。改为先赋值再外挂 finally；loadCache 校验收紧（typeof null==='object'
陷阱：{"sessions":null} 现在走重建）。两条回归测试在原代码上实证全红。
- [P2] 零变更不重写 index.json：脏标记（scanned/removed>0 才落盘）——原实现每次
搜索（GET 先 refresh）都同步 stringify 全缓存 + 写盘。
0.1.6 · 未来代际前视（P2）
- 文件名泛扫
session.vN.jsonl.zstd（取 N 最大）——固定 v4/v3 字面量会让 dsh 发布
v5 后新会话文件永远发现不了（静默断索引）；与 lazy-view artifact.js 同款做法。
- header 版本 ≥5 正整数：warn + best-effort 索引（原 throw → per-session 静默 skip）；
1/2/负数/非整数（损坏头）保持 fail loud。测试改语义 + 新增未来代际接受用例。
