前言¶

在 DeepSeek Harness（DSH）裏做智能體開發，會話一多，「上次在某段思考裏寫過什麼」「某個工作區裏 agent 在某一小時說了哪些話」這類問題，往往只能逐條翻事件日誌。官方 @deepseek-ai/dsh-session-query-sqlite 把索引單元定在事件上：一條事件抽一段文本、一行文檔，命中結果通常是「哪個會話的第幾號事件」，粒度對不上消息內部的 text、reasoning、tool-call 等塊。

下面介紹社區插件 dsh-better-session-query（維護者 leolee9086，SkillHub 分類：記憶）。它在不替換官方 sessionQuery、不改 DSH 源碼的前提下，給會話歷史再掛一套塊級並行索引，讓塊成爲索引行，從而回答塊級檢索與元數據過濾問題。

這是什麼¶

一句話：DSH 插件，對會話歷史建立塊級 FTS5 索引，與官方事件級 session-query 並行存在。

• 倉庫：leolee9086/dsh-better-session-query
• 當前版本（package.json）：0.1.1，許可證 MIT
• 依賴：分塊邏輯來自 @leolee9086/dsh-session-blocks@0.1.0；存儲使用 Node 自帶的 node:sqlite（FTS5）
• 硬邊界（README 原文）：
• 不替換 provider，只消費運行時注入的 sessionQuery 讀會話
• 不 import 任何 @deepseek-ai/* 包
• 可與官方 session-query 同時啓用

v0.1.1 另導出 dsh-better-session-query/blocks 下的純函數（extractRawBlocks、walkContentBlocks、parseToolArguments），可不加載索引服務單獨使用。記憶同步、向量與混合召回仍在開發中，未包含在本版發行。

核心功能¶

與官方索引的差異¶

官方索引以事件爲行；本插件把粒度下沉到塊：一條消息裏的 text / reasoning / tool-call / tool-result 等各自成塊。塊身份爲 blockId = <sessionId>#<seq>#<path>，path 表示塊在事件內的位置（如頂層 "0"，tool-result 內層 "3.0"）。

能回答的問題（摘要）¶

長度按 Unicode 碼點計；時間用事件自帶的 Unix epoch 毫秒（SessionEvent.time）。

塊與倒排策略¶

默認進入全文倒排：text、tool-call、todo。reasoning、tool-result 外殼、image/file 等默認不進倒排，但元數據查詢與 read 仍可用（與官方「思考塊不入索引」語義一致）。思考內容若要被 search 命中，需打開 include.reasoning 並重建索引。

後臺索引¶

索引在後臺漸進更新（默認 reconcileOnSearch: "background"，且每 30s 一輪定時）；檢索不等待索引完成。首次冷啓動需對每個尚未索引的會話完整讀日誌建塊，會話量大時會持續一段時間。可通過 session_blocks_list 指定會話 id，或 session_blocks_status {reindex:true} 手動推進。

索引庫默認路徑：<DSH_HOME>/session-blocks.db。倒排與過濾分表存儲（block_fts、block_meta、block_text 等），與 session 持久化 JSONL 無關。

模型工具與服務¶

Agent 側主要工具（README「模型工具」節）：

session_blocks_search(query="併發模型", sessionId?, workspace?, excludeWorkspaces?, blockTypes?, surface?, limit?, offset?)
session_blocks_query(granularity="blocks"|"messages", workspace?, excludeWorkspaces?, blockTypes?, eventTypes?, surface?, lengthMin?, lengthMax?, timeFrom?, timeTo?, orderBy?, descending?, limit?, offset?, withText?)
session_blocks_list(sessionId, seq?, limit?, offset?)
session_blocks_workspaces(groupBy="workspace"|"session", workspace?, titleContains?, limit?, offset?)
session_blocks_read(blockId) | session_blocks_read(sessionId, seq, path?)
session_blocks_sql(sql, limit?)
session_blocks_status(sessionId?, reindex?, force?)

運行時還提供 ctx.sessionBlockQuery（刻意不復用 sessionQuery 名），含 searchBlocks、queryBlocks、queryMessages、reconcile、compact 等方法。

可選 Web 側欄「會話塊索引」監控（dsh.client.platform: "web"）；數據面僅本機 loopback。不需要界面時可設 monitor.enabled: false。

安裝與啓用¶

環境要求：Node.js 22.19.0 或更高（node:sqlite；Node 22.x 可能打印 ExperimentalWarning）。

README 說明：包位於 SAC_search 倉庫的 dsh-better-session-query/ 子目錄。開發時可把該目錄放進 $DSH_HOME/plugins/，或在 profile 裏 link：

dsh-better-session-query/  # 會話塊級並行索引

在該 profile 的 cordis.patch.yml 裏掛載（已有 insert 列表時只追加這一項）：

- insert:
    - id: dsh-better-session-query
      name: dsh-better-session-query
      config:
        # path 留空 = <DSH_HOME>/session-blocks.db;要關後臺索引更新就設 backgroundReconcileMs: 0
        {}

包內已帶 cordis.patch.yml，也可以直接作爲 bundle 掛載：

- name: dsh-better-session-query

重載插件或重啓 DSH 後生效。不需要修改官方 session-query-sqlite 配置；官方索引關閉時本插件仍可用。

常用配置項（節選，完整表見 README「配置」節）：

典型用法¶

下列示例來自 README，可在 Agent 工具調用中復現。

按類型與長度篩思考塊：

session_blocks_query(blockTypes=["reasoning"], lengthMin=2000, lengthMax=5000, orderBy="length")

按時間窗查 assistant 消息：

session_blocks_query(granularity="messages", eventTypes=["assistant/message"], timeFrom="2026-09-13 10:00", timeTo="2026-09-13 12:00")

工作區與會話清單、限定工作區全文檢索：

session_blocks_workspaces()

session_blocks_workspaces(groupBy="session", workspace="D:\\work")
session_blocks_search(query="併發模型", workspace="D:\\work")

讀取某事件的塊：

session_blocks_read(sessionId="session-xxxx", seq=42)

需要自定義統計時，可用 session_blocks_sql 對公開表結構執行單條只讀 SELECT/WITH（寫操作與多語句會被拒絕；連接層啓用 query_only）。

適用場景與注意¶

適合誰： 長期在 DSH 裏跑多會話、多工作區的開發者；需要按塊搜正文、按 reasoning 長度或時間窗篩 agent 輸出、按 cwd 隔離檢索範圍，或希望與官方事件索引並存而不改 Harness 源碼。

務必知曉：

• 插件在 當前 DSH 進程權限下運行，會讀取會話日誌並在本地 SQLite 中建索引。安裝前請閱讀 GitHub 源碼 與 MIT 許可證，自行評估是否納入 profile。
• 只有已被索引的會話可查；首次全量完成前未掃到的會話會缺失，可用 session_blocks_list 指定 id 先拉入。
• 中文 FTS 爲子串語義，單字查詢面較寬，建議用小 limit；升級涉及 STORE_SCHEMA_VERSION 變更時會自動重建派生表，索引體積可能增大（README 給出中英混排約 +14%、純中文約 +71% 的量級說明）。
• SkillHub（目錄頁）是社區插件目錄，與 DeepSeek / 幻方無官方從屬關係；DSH 生態本身是「一切皆插件」的擴展模型。

結尾¶

dsh-better-session-query 在官方 session-query 之外提供塊級 FTS5 索引：塊可搜、可濾、可讀，後臺漸進建庫，並與事件級索引並行。若你的痛點是「事件太粗、思考塊與工具塊拆不開」，可以按 README 把包裝進 profile，先用 session_blocks_status 看覆蓋率，再按工作區與塊類型組合查詢。

• SkillHub：https://www.skillhub.cn/plugins/leolee9086/dsh-better-session-query
• GitHub：https://github.com/leolee9086/dsh-better-session-query