Introduction¶

DSH’s philosophy is “everything is a plugin,” but the real challenge lies elsewhere: deciding what plugin to write next. Market researchers look at others’ plugins but cannot see their own bottlenecks. dsh-needle takes a different path: it only reads session logs under $DSH_HOME/sessions on the local machine. It extracts “frequently occurring tool failures,” “requests made more than once,” and “practices explicitly corrected,” sorts them by cross-session stability, and outputs a product brief ready for immediate work.

It is maintained by Daphne999 and is categorized under “Memory” in the community directory. As of 2026-11-07, the directory page shows 0 stars. It is worth noting first that it does not judge whether the model is intelligent, nor does it guess what the user wants; it does only one thing: puts observable friction and repetition before you.

What Problems It Solves¶

A DSH user who has been using it for two weeks will typically have piles of answers in their session logs: the same pwsh failed signature appearing dozens of times, retried two or three times each; the same thing mentioned three times across three sessions, indicating the first attempt failed; the user explicitly corrected “Don’t do it this way, do that instead,” and then made the mistake again in the next session.

These are not model capability issues, but product gaps—missing a tool, missing a process, missing a configuration. Humans get tired, and models only see the current session, so a read-only, offline, reproducible tool is needed to systematically mine these signals.

How It Works¶

The plugin scans session.v4.jsonl.zstd under each session. The processing chain is as follows:

$DSH_HOME/sessions/<workspace>/<session-id>/session.v4.jsonl.zstd
        │
        ├─ 逐帧解码（DSH 是多帧追加的 zstd 流）
        ├─ 事件配对（tool/call 提供工具名，tool/result 提供输出）
        ├─ 失败签名归一化（路径、UUID、数字、耗时 → 占位符）
        ├─ 三类候选：工具摩擦 / 重复请求 / 用户纠正
        ├─ 稳定阈值过滤
        └─ 排名 → 需求简报（证据已脱敏）

A few processing steps worth mentioning individually because they directly determine whether the result is credible.

Frame-by-Frame Decoding: DSH session logs are multiple zstd frames concatenated. zstdDecompressSync only decompresses the first frame, making it look like “this session has no content.” The plugin decodes frame-by-frame and inserts newlines between frames, ensuring that fragments of a trailing half-frame land on a separate line rather than polluting the previous valid event.

Event Pairing: tool/result itself does not carry the tool name and must be retrieved from the corresponding tool/call. Without pairing, you can only get “some tool failed” without attribution.

Signature Normalization: C:\work\a\file.txt and C:\work\b\file.txt are the same failure, as are two UUIDs. After normalization, the same failure across sessions can be merged into a single requirement.

Stability Thresholds: (Avoid treating one-offs as requirements):

Redaction: All evidence snippets pass through redact before statistics, disk writing, and rendering. GitHub / Model API / AWS / Slack / npm tokens, JWT, Bearer headers, --token, password=, client_secret:, etc., are all replaced with <redacted:...>. 40-digit hexadecimal numbers are left untouched—usually git SHA, and erasing them would destroy normal output.

Three Tools¶

After installation, three tools needle_* appear in the session, corresponding to scan, brief, and report actions.

needle_scan scans sessions within a time window and returns qualifying needs. Parameters are optional hours (1-720, default is 24 from config) and maxSessions (1-200, default 20):

{
  "hours": 24,        // 可选，1-720，默认取配置（24）
  "maxSessions": 20   // 可选，1-200，默认 20
}

Returns needs[], each containing id, kind, title, occurrences, sessions[], evidence[] (redacted), and suggestion.form. It also writes the full result to .dsh/needle/latest.json and the report to .dsh/needle/report.md.

needle_brief renders a single need into a Markdown product brief, including problem, evidence, why this form is suggested, next steps, acceptance criteria, and non-goals:

{ "needId": "need-1a2b3c4d5e" }  // 省略则取排名第一的需求

needle_report renders the most recent scan into a complete Markdown report, including an overview table, per-item briefs, methodology and boundaries, ready to be pasted into an issue or committed to a repository:

{ "limit": 10 }  // 可选，1-20

Delivery form suggestions are divided into four categories: plugin (needs tool, interception, or deterministic checks), skill (needs process discipline), config (environment, permissions, network, encoding issues), and docs (just write it in AGENTS.md). The README clearly states this is “just a starting point, not a conclusion.”

Installation and Activation¶

The README provides a “link from source” method, which is used for local development:

git clone https://github.com/Daphne999/dsh-needle.git
dsh plugin --profile <profile> add link:"$PWD/dsh-needle"

You can also install after creating a tarball:

npm pack                # 生成 dsh-needle-0.1.0.tgz
dsh plugin --profile <profile> add ./dsh-needle-0.1.0.tgz

Or write it directly into the profile’s ~/.dsh/profiles/<profile>/package.json:

"dependencies": { "dsh-needle": "link:/abs/path/to/dsh-needle" },
"dsh": { "profile": { "bundles": [ /* ... */ "dsh-needle" ] } }

Restart the host after installation. The “Needle Implicit Needs Radar” will appear in the plugin list, and the three needle_* tools will appear in the session. The source code does not provide an install command in the form dsh plugin add github:....

Configuration¶

Configuration items are written in the profile’s patch line (cordis.patch.yml):

- id: dsh-needle
  config:
    sessionRoot: "C:\\Users\\me\\.dsh\\sessions"  # 默认 $DSH_HOME/sessions
    hours: 24                                     # 默认窗口
    maxSessions: 20                               # 默认上限
    evidenceDir: ".dsh/needle"                    # 产物目录（相对工作区）

It reads all workspaces under $DSH_HOME/sessions by default; use sessionRoot to narrow the scope if needed.

How It Differs from Existing Plugins¶

There are already a batch of “session viewers” in the community, but they answer different questions. Plugins like agent-clinic perform a health check on the session, diagnosing “where this session is unhealthy” (token waste, context bloat, failure loops), and producing diagnostic items and prescriptions; dsh-needle does not judge health, only sorts requirements by cross-session stability. Plugins like dsh-soul record repeated corrections and tool errors and compile experience into changes for runtime components; dsh-needle does not change anything, producing a brief for humans to read. Plugins like dsh-daily look at plugin market download volumes and gaps, producing “what is missing from the ecosystem”; dsh-needle looks at your own sessions, producing “what you are repeatedly stuck on.”

The focus of dsh-needle is need discovery: finding events that repeatedly happen in local sessions and are worth making into products, providing a brief including form suggestions and acceptance criteria. It does not make market judgments for you, nor does it automatically generate plugins.

Use Cases and Notes¶

It is suitable for developers who have been using DSH stably for a while, have accumulated hundreds of session logs, and want to create plugins or skills but don’t know which to start with. It is also suitable for anyone wanting to leave evidence for a recurring pain point.

A few points to note, taken from the “Boundaries” section of the README:

• The plugin runs with the current DSH process permissions. You should check the source code and license (MIT, see repository LICENSE) before installing.
• It reads local logs only; it does not write, rename, or delete any session files; the only write is the scan artifacts under .dsh/needle/ in the workspace.
• Thresholds will miss things. Low-frequency but important needs will not be surfaced; this is a deliberate design trade-off—prefer to miss rather than force things.
• Failure signatures are heuristic; different root causes may be merged into one, and the same root cause may be split into two. Evidence snippets are for human review.
• Relies on Node’s zstd support (node:zlib, Node ≥ 22.15, DSH runtime satisfies this).
• Only parses text events; images, binary attachments, and tool private formats do not participate in statistics.
• Suggested forms are determined heuristically by error text and tool names; humans still need to make the final call.

Additionally, it explicitly does not call models: there is no LLM scoring, and the same log will always yield the same result, making it diffable. It is also offline, does not upload, check the market, or access any API. Evidence snippets are kept to 220 characters and are redacted before statistics. The README warns that if keys have appeared in the logs, you should still treat them as leaked—redaction can only reduce secondary spread, it cannot retract existing records.

Self-Verification¶

The repository comes with tests and end-to-end scripts:

node --test --test-isolation=none test/*.test.mjs   # 单元/集成测试
node scripts/smoke.mjs                              # 端到端：造日志 → 扫描 → 简报 → 报告

Tests cover multi-frame zstd decoding, trailing half-frames, mtime filtering, event pairing, signature normalization, stability thresholds, redaction (including disk artifacts), tool parameter validation, empty session directories, and configuration items. The README explains why --test-isolation=none was added: some Windows sandbox environments do not allow the Node test runner to create pipe subprocesses for each file; without this parameter, tests fail with spawn EPERM, which is unrelated to the plugin code.

Source¶

Plugin Directory Page: https://www.skillhub.cn/plugins/Daphne999/dsh-needle

Source Code and Documentation: https://github.com/Daphne999/dsh-needle