dsh-search-index（会话检索）
DSH 插件：会话标题 / 内容全文检索，自带独立 FTS5 索引；内容检索的语料与语义
来自 dsh-reference-session-collector（DRS）投影库，经 HTTP 或进程内只读 两条通道取数。
- 标题模式 —— 直接命中会话标题，输入即出结果；
- 内容模式 —— 按会话聚合展示标题 + 命中片段，支持类型（用户/回复/工具）、
检索域（全部/活跃/归档）、日期区间、排序（相关度/时间）与「命中展开」；
- 命中定位 —— 点结果打开会话并巡逻定位到目标行（诊断徽标 ⏳/✓/✗）；
冷数据（目标距会话最新回合 >40）在会话名后标 🧊，点击先弹确认，确认后按实测页宽
尽力回溯翻页（HUD 浮窗显示进度，落定停驻给「跳转/取消」；未命中可再追加两轮预算重试；
200 回合的过冷数据标 ❄️ 不自动回溯）；
- 索引生命周期 —— 增量同步（水位轮询）、非破坏性整理（影子库构建 + 原子切换 +
有界归档）、深度同步（DRS 慢扫自愈 + 整理）、JSON Lines 快照导出/导入。
DRS 是硬依赖，但通道可选：内容检索的语义（会话分组、类型加权、表面与归档日期过滤、
锚定节选）全部在 dsh-reference-session-collector 的投影库里完成。它作为本包的
正式依赖随包安装，包本身不需要用户单独下载；但注意「包装上 ≠ 插件激活」：
宿主激活 bundles 只扫 profile 顶层 dependencies，作为传递依赖它可能不被挂载，
此时投影库不会更新——设置卡会提示激活命令：
dsh plugin --profile <name> add dsh-reference-session-collector 后重启宿主。
两条检索通道任一生效即可用：
http（同源路由）与 in-process（只读直连 projection.db）。
DSH NEXT 桌面版必读：桌面宿主在 web 层对非渲染进程请求一律 403 Browser access is disabled，
所以 HTTP 通道在桌面版永远不可用——contentTransport 缺省 auto 会自动改走进程内只读臂，
用户无需任何操作。仅当两臂都不可用时，search-status 才返回 available:false 并给出具体档位码
（browser-access-denied / drs-http-unreachable / drs-http-error / drs-not-activated /
drs-missing / drs-empty / drs-schema-mismatch）；其中 drs-not-activated（路由 404）
会在 search-status.notActivated=true 中单独标记，即使进程内接穗可用也会提示执行上述激活命令。
进程内臂只读：不建目录、不跑 DDL、不写 meta；库 schema 与本包预期不符时只报错，绝不清库。
索引自愈：整理 vs 深度同步
面板页脚与设置卡各有两枚按钮，修的不是同一层：
| 按钮 | 做什么 | 修什么 |
|---|
整理索引（index-rebuild） | 读宿主 sessionQuery 全量重建本地 FTS 索引：影子库构建 → 原子切换 → 有界归档 | 本地索引脏 / 缺会话 / 标题陈旧 |
深度同步（drsc）（index-deep-sync） | ① POST {op:'sync'} 让 DRS 慢速重扫投影库，轮询 syncing=false 且 last_sync.deferred=0（上限 180s）；② 再自动跑一遍整理 | 命中定位不到（DRS 投影库滞后，seq/on_surface 与界面文本对不上） |
命中定位不走本地索引：拿命中行 seq 回查 DRS op=session，取该行 search_text /
surface_text 当 needle 到 GUI 里做文本匹配。所以「有些命中点进去不跳」只有深度同步对症，
整理索引重建多少次都不动 DRS 投影库。进度经 index-status.deepSync
（idle → drs-syncing → rebuilding → done | failed）暴露，两个按钮都在进行中拒绝并发；
整理正在跑时点深度同步会直接失败，等它跑完或只点深度同步。DRSC 侧触发契约为
POST ?op=sync（op 必须在 query，body 不作为判据），落定与否记在 drsSettled。
与 drsc 的版本耦合（0.7.15 起）：drsc 0.2.6 给单轮同步加了时间预算，
syncing=false 只说明「这一轮停了」，可能还剩 deferred 个会话没扫。所以本版的落定判据是
syncing === false && last_sync.deferred === 0。
- 本包 ≥0.7.15 + drsc 0.2.6：正确等扫完再整理（推荐组合）。
- 本包 <0.7.15 + drsc 0.2.6：会把「预算用完」误判为扫完，拿残缺语料重建本地索引——
这正是深度同步要防的事。升级时请先升本包、再升 drsc。
- 本包 ≥0.7.15 + 旧版 drsc：安全。旧版没有
deferred 字段，按 0 处理，行为与升级前逐行一致。
入口双形态（宿主代际）
| 宿主 | 形态 | 注册内容 / 交互 |
|---|
| ≥ 0.1.7 | 「插件页式」主栏整页 | sidebar.panellist 面板行（id dsh-search-index, order 5，落在「插件」0 之后、「会话管理」6 之前）+ main 整页（key 同名）；点行或 Ctrl/⌘+K → layout.selectPanel('dsh-search-index')；页内「关闭」回到会话 |
| < 0.1.7 | 侧栏弹窗（原样） | sidebar.footer.action 入口（order 5）+ SwitchPanel dialog（遮罩 / Esc / Ctrl/⌘+K）；不注册 panellist/main |
代际信号：sidebar.workspaces.session.menu.item 席位 + main 席位（0.1.5 线无前者、
0.1.7 线起有）。两形态互斥：席位就绪后一次性决定，席位后到时就地撤掉另一形态；
enabled=false 时整对注销。
支持 DSH 0.1.0-rc.2、0.1.0-rc.3、0.1.0-rc.6、0.1.0-rc.7、0.1.0-rc.8、0.1.1-rc.1、0.1.1-rc.2、0.1.2-rc.1、0.1.5-rc.1、0.1.5-rc.2、0.1.5-rc.3、0.1.7-rc.1、0.1.7-rc.2、0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.1、0.2.1-rc.2、0.2.1-rc.3、0.2.1-rc.4、0.2.1-rc.5（枚举 peer；其中 9 个 rc 有农场 cell 实测，矩阵见下节）。
兼容矩阵（0.7.7 实测）
农场 cell（_host-farm/cells/<rc>）逐个装入 0.7.7 后起 dsh web，探测宿主半身与设置面：
| 宿主 rc | /switch-search/api/index-status | settings-describe | 入口形态 |
|---|
| 0.1.0-rc.8 | 200 · available:true | 200 · writable:true（legacy 桥） | 底栏弹窗 |
| 0.1.1-rc.2 | 200 · available:true | 200 · writable:true | 底栏弹窗 |
| 0.1.2-rc.1 | 200 · available:true | 200 · writable:true | 底栏弹窗 |
| 0.1.5-rc.3 | 200 · available:true | 200 · writable:true | 底栏弹窗（UI 实测） |
| 0.1.7-rc.2 | 200 · available:true | 200 · writable:false（只读投影） | 主栏整页 |
| 0.2.0-rc.2 | 200 · available:true | 200 · writable:false | 主栏整页 |
| 0.2.1-rc.1 | 200 · available:true | 200 · writable:false | 主栏整页 |
| 0.2.1-rc.2 | 200 · available:true | 200 · writable:false | 主栏整页 |
| 0.2.1-rc.3 | 200 · available:true | 200 · writable:false | 主栏整页（UI 实测，桌面宿主） |
UI 侧（真浏览器）两端各验一格：0.1.5-rc.3 = 底栏「搜索 Ctrl K」+ 弹窗（Esc / Ctrl+K）；
0.2.1-rc.3 = sidebar.panellist 行 + 主栏整页（无遮罩）。
仍在枚举、暂无农场 cell 的 9 个 rc（0.1.0-rc.2/rc.3/rc.6/rc.7、0.1.1-rc.1、0.1.5-rc.1/rc.2、
0.1.7-rc.1、0.2.0-rc.1）是声明面放行，未逐格实测；若要收窄，删掉对应枚举即可。
安装
dsh plugin --profile web add dsh-search-index
# 或本地 tgz
dsh plugin --profile web add "file:E:/test/rewrite-agently/mine-dsh-plugins/dsh-search-index/dsh-search-index-0.7.7.tgz"
安装后必须重启宿主进程。DRS 未装时本插件的内容检索不可用（标题面可用）。
不能与合并包 dsh-session-steward（≤0.5.x，内含 search）同装：两者都注册
/switch-search/api 前缀，0.1.5 线宿主会直接启动失败（webserver: duplicate prefix route）。
升级路径：dsh plugin remove dsh-session-steward → 装 dsh-manage-session + 本插件。
0.1.5 线实测：底栏「搜索 Ctrl K」入口 → 弹窗（Esc 关闭），settings-describe 走 legacy 桥
writable:true；无 DRS 时 search-status 返回 available:false, reason:'drs-unavailable'。
路由契约
前缀 /switch-search/api，方法名：
| 方法 | 作用 |
|---|
list-sessions | 标题语料（会话 id + 标题 + cwd/updatedAt；索引优先、sessionQuery 兜底） |
content-search | 内容检索（DRS 分组检索直连；archived/types/sortBy/expand/from/to） |
search-status | 可用性由 DRS 探针裁决（available/reason），附索引水位与整理进度 |
index-status / index-rebuild | 索引生命周期面（设置卡行；index-status 附 deepSync 状态面） |
index-deep-sync | 深度同步：DRS 慢扫自愈 → 本地索引整理（后台执行，进度走 index-status） |
index-export / index-import | 快照导出（JSON Lines 原始体）/ 导入（原始体） |
settings-describe / settings-mutate | 设置面：0.1.7+ 只读投影；≤0.1.5 走 legacy settings 桥（可写） |
设置
命名空间：switch-search（存储键稳定承诺）。
0.7.0 起从合并包的 manage-sessions-search 回归本命名空间：旧键不再读取，升级后
enabled 等开关回到缺省（搜索默认开启），需要重新按需调整一次。
| 开关/字段 | 缺省 | 说明 |
|---|
enabled | true | 关闭后不注册任何方法，入口整体消失 |
defaultMode | title | 面板打开时默认标题还是内容模式 |
autoSync / syncIntervalMs | true / 30000 | 后台水位轮询增量同步 |
archiveKeep | 2 | 整理索引后保留的历史索引份数 |
indexDir | '' | 索引目录覆盖（缺省 ~/.dsh-switch-search，环境变量 DSH_SWITCH_SEARCH_DIR） |
corpusSource | drs | 同步语料源；drs=DRS 投影库；native=sessionQuery 兜底（仅标题面可用） |
drsBaseUrl | '' | DRS 基址；空=首个 trustedHosts 条目，再退 http://127.0.0.1:8080 |
contentTransport | auto | 内容检索通道：auto=HTTP 优先、失败降级进程内只读库；http=只走 HTTP；in-process=只走进程内只读库（桌面版） |
与 dsh-manage-session 的职责边界
- 归档集合只读：本插件只读官方归档集合（存储文件优先、registry 兜底），把归档标记
折进索引语料；写方只有
dsh-manage-session（归档 / 取消归档 / 清理）。
- 行内删除：搜索结果行的「删除」按钮可见性由跨插件探针决定 ——
POST /manage-session/api/session-health-status 的 switches.directDelete === true；
未装或探针失败即隐藏（破坏性入口 fail-soft）。删除动作走
POST /manage-session/api/session-history-purge（不复制 purge 实现，单一 owner）。
- 未装 manage-session 时，搜索结果打开会话仍正常（导航不依赖它）。
存储
| 路径 | 内容 |
|---|
~/.dsh-switch-search/ | 独立索引库（FTS5）、历史归档份数、墓碑台账 |
~/.dsh/storages/workspace.json | 只读：归档集合与工作区成员表 |
开发
pnpm install
pnpm run typecheck # tsc --noEmit
pnpm run build # tsc -p tsconfig.build.json && tsdown
pnpm test # 11 个客户端/宿主契约脚本 + DRS/归档契约（node:test，TS 走 tsx）
许可
MIT
