前言¶
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
