前言¶
DSH 的理念是「一切皆插件」，但真正難的是另一件事：下一個該寫的插件是什麼。寫市場調研的人看的是別人的插件，看不到你自己的卡點。dsh-needle 走的是另一條路徑：只讀本機 $DSH_HOME/sessions 下的會話日誌，把「反覆出現的工具失敗」「說了不止一遍的請求」「被明確糾正過的做法」挖出來，按跨會話穩定性排序，輸出可直接開工的產品簡報。
它由 Daphne999 維護，在社區目錄裏歸在「記憶」分類下。截至 2026-11-07 目錄頁顯示星標爲 0。值得先說明的是，它不判斷模型聰不聰明，也不替你猜用戶想要什麼，只做一件事：把可觀察的摩擦和重複擺到你面前。
它解決什麼問題¶
一個用了兩週的 DSH 用戶，會話日誌裏通常已經堆着答案：同一個 pwsh 失敗簽名出現十幾次，每次都重試兩三輪；同一件事在三個會話裏說了三遍，說明第一次沒做成；用戶明確糾正過「不要這樣，應該那樣」，下一個會話又犯了。
這些不是模型能力問題，而是產品缺口——缺一個工具、缺一條流程、缺一處配置。人會疲勞，模型只看得到當前會話，所以需要一個只讀、離線、可復跑的工具把這類信號系統地挖出來。
工作方式¶
插件掃描的是每個會話下的 session.v4.jsonl.zstd，處理鏈路如下：
$DSH_HOME/sessions/<workspace>/<session-id>/session.v4.jsonl.zstd
│
├─ 逐幀解碼（DSH 是多幀追加的 zstd 流）
├─ 事件配對（tool/call 提供工具名，tool/result 提供輸出）
├─ 失敗簽名歸一化（路徑、UUID、數字、耗時 → 佔位符）
├─ 三類候選：工具摩擦 / 重複請求 / 用戶糾正
├─ 穩定閾值過濾
└─ 排名 → 需求簡報（證據已脫敏）
幾個值得單說的處理步驟，因爲它們直接決定了結果可不可信。
逐幀解碼：DSH 的會話日誌是多個 zstd 幀拼接追加的。zstdDecompressSync 只解第一幀，看起來就像「這個會話沒有內容」。插件逐幀解碼，並在幀之間補換行，讓正在寫入的半截尾幀的殘片落在單獨一行，而不是污染前一條有效事件。
事件配對：tool/result 本身不帶工具名，必須回到對應的 tool/call 取。不配對就只能得到「某個工具失敗了」，無法歸因。
簽名歸一化：C:\work\a\file.txt 和 C:\work\b\file.txt 是同一個失敗，兩個 UUID 也是。歸一化之後，跨會話的同一失敗才能歸併成一條需求。
穩定閾值（避免把一次性不順當成需求）：
| 類型 | 達標條件 |
|---|---|
| 工具摩擦 | 同一失敗簽名出現在 ≥2 個會話，或在同一會話出現 ≥3 次 |
| 重複請求 | 同一請求（歸一化後）出現 ≥2 次 |
| 用戶糾正 | 同一糾正出現 ≥2 次，或出現在 ≥2 個會話 |
脫敏：所有證據片段在統計、落盤、渲染之前都過一遍 redact，GitHub / 模型 API / AWS / Slack / npm token、JWT、Bearer 頭、--token、password=、client_secret: 等一律替換爲 <redacted:…>。40 位十六進制不動——那通常是 git SHA，抹掉反而破壞普通輸出。
三個工具¶
裝完後會話裏多出 needle_* 三個工具，對應掃描、簡報、報告三個動作。
needle_scan 掃描時間窗口內的會話，返回達標需求。入參爲可選的 hours（1-720，默認取配置 24）和 maxSessions（1-200，默認 20）：
{
"hours": 24, // 可選，1-720，默認取配置（24）
"maxSessions": 20 // 可選，1-200，默認 20
}
返回 needs[]，每條含 id、kind、title、occurrences、sessions[]、evidence[]（已脫敏）、suggestion.form。同時把完整結果寫到 .dsh/needle/latest.json，報告寫到 .dsh/needle/report.md。
needle_brief 把一條需求渲染成 Markdown 產品簡報，包含問題、證據、爲什麼建議這個形態、下一步、驗收標準、非目標：
{ "needId": "need-1a2b3c4d5e" } // 省略則取排名第一的需求
needle_report 把最近一次掃描渲染成完整 Markdown 報告，含總覽表、逐條簡報、方法與邊界，可直接貼進 issue 或提交進倉庫：
{ "limit": 10 } // 可選，1-20
交付形態建議分四類：plugin（需要工具、攔截或確定性檢查）、skill（需要流程紀律）、config（環境、權限、網絡、編碼問題）、docs（寫進 AGENTS.md 就夠了）。README 明確說明這「只是起點，不是結論」。
安裝與啓用¶
README 給的是「從源碼鏈接」方式，本地開發用這條：
git clone https://github.com/Daphne999/dsh-needle.git
dsh plugin --profile <profile> add link:"$PWD/dsh-needle"
也可以打 tarball 後再裝：
npm pack # 生成 dsh-needle-0.1.0.tgz
dsh plugin --profile <profile> add ./dsh-needle-0.1.0.tgz
或者直接寫進 profile 的 ~/.dsh/profiles/<profile>/package.json：
"dependencies": { "dsh-needle": "link:/abs/path/to/dsh-needle" },
"dsh": { "profile": { "bundles": [ /* ... */ "dsh-needle" ] } }
裝完重啓宿主。插件列表裏會出現「Needle 隱含需求雷達」，會話裏多出 needle_* 三個工具。源碼裏沒有另外提供 dsh plugin add github:... 形式的安裝命令。
配置¶
配置項寫在 profile 的 patch 行裏（cordis.patch.yml）：
- id: dsh-needle
config:
sessionRoot: "C:\\Users\\me\\.dsh\\sessions" # 默認 $DSH_HOME/sessions
hours: 24 # 默認窗口
maxSessions: 20 # 默認上限
evidenceDir: ".dsh/needle" # 產物目錄（相對工作區）
默認讀 $DSH_HOME/sessions 下的全部工作區，需要收窄時用 sessionRoot。
它和已有插件的區別¶
社區裏已有一批「看會話」的插件，但它們回答的是不同的問題。agent-clinic 這類會話健康體檢診斷的是「這次會話哪裏不健康」（token 浪費、上下文膨脹、失敗循環），產出診斷項與處方；dsh-needle 不判斷健康與否，只按跨會話穩定性排序需求。dsh-soul 這類經驗演化插件會記錄重複糾正與工具錯誤，並把經驗編譯成運行組件的改動；dsh-needle 不改任何東西，產出的是給人看的簡報。dsh-daily 這類市場日報看的是插件市場的下載量與空白，產出「生態裏還缺什麼」；dsh-needle 看的是你自己會話，產出「你反覆被什麼卡住」。
dsh-needle 的落點是需求發現：從本機會話裏找出反覆發生、值得做成產品的那幾件事，給出含形態建議與驗收標準的簡報。它不替你做市場判斷，也不自動生成插件。
適用場景與注意¶
適合已經在 DSH 上穩定用了一陣子、積累了幾百條會話日誌、想做插件或 skill 但不知道先做哪一個的開發者，也適合想給某個反覆出現的痛點留一份證據的人。
需要注意的幾點，來自 README 的「邊界」一節：
- 插件以當前 DSH 進程權限運行，安裝前應先檢查源碼與許可證（MIT，見倉庫 LICENSE）。
- 只讀本地日誌，不寫、不改名、不刪除任何會話文件；唯一的寫入是工作區
.dsh/needle/下的掃描產物。 - 閾值會漏。低頻但重要的需求不會被排上來，這是刻意的設計取捨——寧可漏，不硬造。
- 失敗簽名是啓發式的，不同根因可能被歸併成一條，同一根因也可能被拆成兩條。證據片段是給人複覈的。
- 依賴 Node 的 zstd 支持（
node:zlib，Node ≥ 22.15，DSH 自帶運行時滿足）。 - 只解析文本事件，圖片、二進制附件、工具私有格式不參與統計。
- 建議形態由錯誤文本與工具名啓發式判斷，人仍需拍板。
另外，它明確不調用模型：沒有 LLM 打分，同一份日誌永遠得到同一份結果，可 diff；也不聯網，不上傳、不查市場、不訪問任何 API。證據片段只保留到 220 字符，且先脫敏再統計。README 提醒，如果日誌裏出現過密鑰，仍應把它當作已泄露處理——脫敏只能減少二次傳播，不能撤回已經存在的記錄。
自驗¶
倉庫自帶測試與端到端腳本：
node --test --test-isolation=none test/*.test.mjs # 單元/集成測試
node scripts/smoke.mjs # 端到端：造日誌 → 掃描 → 簡報 → 報告
測試覆蓋多幀 zstd 解碼、半截尾幀、mtime 過濾、事件配對、簽名歸一化、穩定閾值、脫敏（含落盤產物）、工具參數校驗、空會話目錄、配置項。README 解釋了爲什麼加 --test-isolation=none：部分 Windows 沙箱環境不允許 Node 測試運行器爲每個文件創建管道式子進程，不加這個參數測試會因 spawn EPERM 失敗，與插件代碼無關。
來源¶
插件目錄頁：https://www.skillhub.cn/plugins/Daphne999/dsh-needle
源碼與文檔：https://github.com/Daphne999/dsh-needle
