dsh-deadend
面向编码代理的反驳记录：记住哪些方案未奏效，并在其所依赖的代码发生变化时自动使记录失效。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:liyixuan201211/dsh-deadend#7f32e3b5e6e67e8d36f389b058234f8ebb4fa6afDeadend 以 dsh-deadend 发布，当前版本为 1.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Remember what did not work — and expire it automatically when the code it depended on changes.
A refutation ledger for coding agents, as a DeepSeek Harness plugin.
dsh plugin --profile web add github:liyixuan201211/dsh-deadend
No install needed to try it:
npx --yes github:liyixuan201211/dsh-deadend --help
中文：一个失败账本。agent 每一轮新会话都会用同样的乐观重试同样的失败，代价重复支付。本插件把"试过且走不通"的方案记在仓库里，并在下一次尝试前先查一遍。关键在于：每条记录都带锚点（决定其真伪的文件的哈希）——锚点没变就拦截，锚点一变就自动降级为"待复测"，因为当初那个世界已经不在了。
Every memory system for agents stores what worked: facts, preferences, summaries, embeddings. Almost nothing stores what failed. So the failure loop repeats — the same broken install, the same two-hour detour, once per session, forever.
The obvious fix is a list of things that did not work. The obvious fix is also wrong, and worse than nothing:
A note from six months ago saying "X does not work", written against code that has since changed, will confidently block a fix that now works.
A stale block is not a harmless annoyance. It is the tool lying to you, and a tool that lies gets switched off. The hard part of negative knowledge is not recording it — it is invalidating it.
Every entry carries anchors: the files whose content would have to change for the failure to stop being true.
| Anchors | Meaning | check exit |
|---|---|---|
| all unchanged | authoritative — it still fails | 3 |
| any changed / deleted | suspect — re-test it | 4 |
| nothing known | clear | 0 |
| entry refused (no anchors) | record declined | 5 |
Validity is judged by content, not by a clock. No MAX_AGE_DAYS, no
calibration — and it is self-maintaining, because nobody has to remember to
expire anything.
record refuses to create an entry with no anchors. That is enforced, not
advised:
$ deadend record --title "go build fails on cgo" --cmd "go build ./..."
Refusing to record: no anchors.
A dead end with nothing to watch can never expire, and a claim that can
never expire is indistinguishable from a bug. Name the files whose content
would have to change for this failure to stop being true.
Suggested anchors (they exist here):
--anchor package.json
Or pass --unanchored if this genuinely has no local artifact — it will
block forever, and `deadend status` will keep saying so.
The undecayable case exists (an upstream API limit, a vendored dependency) and
--unanchored allows it — loudly, and counted in deadend status, so you always
know which of your claims are unfalsifiable.
Before re-running something expensive, ask:
deadend check --cmd "npm install sharp" --log /tmp/last-install.log
⛔ BLOCKED — 1 recorded dead end matches, and its anchors are unchanged.
────────────────────────────────────────────────────────────────────────
dd_50e127c7d9c5 npm install sharp fails: no prebuilt binary for darwin-arm64
matched identical command
recorded 2026-09-13 (today)
attempt npm install sharp → exit 1
symptom Error: Cannot find module sharp-darwin-arm64.node
why sharp ships prebuilt binaries and none exists for this platform/arch
instead npm rebuild sharp --build-from-source
anchors 2 of 2 unchanged — still authoritative
✓ package.json
✓ package-lock.json
evidence install.log
────────────────────────────────────────────────────────────────────────
This is not a prohibition — it is a claim that was true, with its evidence.
If you think the world moved, re-test it and re-confirm:
deadend verify dd_50e127c7d9c5 --still-fails --log <new-output>
Now change one line of package-lock.json and ask again:
⚠ SUSPECT — 1 recorded dead end matches, but the world it described has changed.
anchors 1 of 2 changed — no longer authoritative
✓ package.json
✗ package-lock.json f25e7d29 → 55eaf97b
Re-test it: it may now work.
still fails? deadend verify dd_50e127c7d9c5 --still-fails
works now? deadend verify dd_50e127c7d9c5 --now-works
That transition — authoritatively blocked, then honestly downgraded the moment its evidence moved — is the whole plugin.
deadend record \
--title "npm install sharp fails: no prebuilt binary for darwin-arm64" \
--cmd "npm install sharp" --exit 1 --log /tmp/last-install.log \
--why "sharp ships prebuilt binaries and publishes none for this platform/arch" \
--retry "npm rebuild sharp --build-from-source (needs libvips)" \
--anchor package.json --anchor package-lock.json \
--evidence /tmp/last-install.log --tag native
--log is worth the trouble. The failure is hashed in a normalised form —
line and column numbers, absolute paths, temp directories, digests, UUIDs,
timestamps, durations and ANSI colour removed — so the same breakage is
recognised across sessions, machines, and differently-worded commands:
# Recorded as: python app.py + ModuleNotFoundError: No module named numpy
# Still caught: python3 app.py --verbose, same failure, different command
deadend check --cmd "python3 app.py --verbose" --log ./run.log # -> exit 3
deadend check [--cmd C] [--log F|-] [--symptom T] [--title T] [-q] [--json]
deadend record -t TITLE [--cmd C] [--exit N] [--log F|-] [--why W] [--retry R]
[--anchor PATH]... [--unanchored] [--evidence E]... [--tag T]...
deadend verify <id> (--still-fails | --now-works) [--log F] [--note N]
deadend list [--status active|suspect|retired] [--all] [--json]
deadend show <id> [--json]
deadend status [--json] counts, plus the entries that need attention
deadend merge <ledger.jsonl...> (use - for stdin)
deadend gc [--dry-run] [--drop-retired] [--drop-undecayable]
deadend init
Exit codes are the interface, so check composes with any shell or CI gate:
deadend check --cmd "npm install sharp" -q || echo "already ruled out; not retrying"
| Strength | Match | Decisive? |
|---|---|---|
| 3 | identical failure signature | yes |
| 2 | identical normalised command | yes |
| 1 | same command family, or similar title | no — shown as related |
Strength-1 matches never change the verdict. npm install sharp failing says
nothing about npm install left-pad, so installing something else is never
blocked — it is mentioned, with the earlier note attached. A gate that blocks
too much gets disabled, which protects nobody.
Command normalisation strips whitespace and leading wrappers (sudo, time,
env) and nothing else. Flags are part of the command.
<repo>/.deadend/ledger.jsonl # append-only event log, one JSON object per line
Not in ~/.cache, not per-machine. That is the design decision with the most
consequences:
+ {"v":1,"event":"record",…} —
a claim you can argue with.verify appends an observation
rather than overwriting, and gc folds history into the entry so compaction
never loses one.Identity is content-derived (dd_ + sha256(title | command | signature | anchor paths)), so two clones that record the same refutation produce the same id and
merging ledgers is a set union, not a de-duplication problem.
Full format: skills/deadend/reference/schema.md.
Identity is content-derived, so the same refutation recorded twice — by two teammates, or by you on two machines — has the same id, and merging is a set union rather than a de-duplication problem. That is what makes committing the ledger to a shared repository workable in the first place.
deadend merge ../other-clone/.deadend/ledger.jsonl # or - for stdin
# added 3
# updated 1
# unchanged 7
# total 11
When both sides know an id, the more recently updated observation wins on status and anchors, and histories and notes are unioned so neither side loses one.
check reports through its exit code, so the ledger becomes a gate in one line:
- name: Do not re-run a known dead end
run: |
npx --yes github:liyixuan201211/dsh-deadend check --cmd "npm install sharp" -q
# exit 3 = still authoritative: fail
# exit 4 = anchors changed: re-test, do not fail
# exit 0 = clear
And because an unfalsifiable entry is the failure mode this tool exists to prevent, it is worth failing the build when the ledger itself drifts:
- name: Keep the ledger falsifiable
run: |
npx --yes github:liyixuan201211/dsh-deadend status --json > ledger.json
node -e '
const j = require("./ledger.json");
if (j.attention.length > 0) {
console.error("ledger needs attention:");
for (const a of j.attention) console.error(" " + a.id + " " + a.why);
process.exit(1);
}'
Recording failures is not a new idea, and this plugin does not claim it is. The closest prior art is a Claude Code plugin, dead-end-registry, which mines transcripts for reverted approaches; there is also academic work on failure-aware shared memory (Negative Knowledge, ICML 2026 AI4Research workshop) and "dead end registries" as a coordination mechanism in automated-research templates.
| Prior art | dsh-deadend | |
|---|---|---|
| Captured | reverted approaches mined from transcripts | refutations you state, with evidence |
| Lives in | ~/.claude/…, per machine | .deadend/ledger.jsonl, in the repo |
| Match | keyword match on the prompt | normalised failure signature + command identity |
| Extraction | heuristics (+ optional model pass) | deterministic, offline, no model |
| Expiry | wall-clock age (e.g. 60 days) | content hash of the falsifiers |
| Undecayable claims | not distinguished | refused by default; loud when allowed |
| Interface | editor hooks | exit codes, composable with any shell or CI |
Time-based expiry is wrong in both directions: too slow (a dependency bump that
invalidates a dead end this morning does not clear it for 60 days) and too fast
(a dead end about a frozen dependency vanishes on day 61 for no reason). The last
three rows are the contribution. Reasoning in full:
reference/decay.md.
No boot-time code. cordis.patch.yml is an empty patch, deliberately. A
plugin whose subject is "do not repeat mistakes" has no business inserting code
into the DSH process for every profile. The payload is a skill plus a CLI that the
skill runs through the visible shell tool.
An event log, not a mutable document. Append-only means no read-modify-write races, clean diffs, and a preserved reason for every status change.
suspect is never stored. It is recomputed from anchors on every read. A
stored staleness flag would itself go stale — the exact bug being avoided.
Refusal over a silent bad entry. record rejects anchors that do not exist,
duplicate entries, and entries without anchors, rather than writing something
that will quietly mislead later.
dsh plugin --profile web add github:liyixuan201211/dsh-deadend
This installs the skill (skills/deadend/), which teaches the agent to check
before it retries and record after it fails. The bundle patch adds nothing to the
boot graph; review cordis.patch.yml, package.json (no lifecycle scripts) and
src/ if you want to verify that.
Requires Node >= 20. The sources are plain ESM JavaScript with JSDoc types, so
there is no build step and no install-time script — and the published bin
actually runs when installed. (They cannot be TypeScript: Node refuses to strip
types for files inside node_modules, which is precisely where the package lands
when it is installed or run through npx. The installable CI job guards that.)
npm test # 74 tests
npm run typecheck # tsc --noEmit over the JSDoc types
npm run check # both
src/
cli.js exit-code contract and argument parsing
engine.js record / check / verify / gc, and the verdict rules
anchors.js hashing paths, detecting decay, suggesting anchors
fingerprint.js normalising failure output into a stable signature
model.js data model and event-log replay
ledger.js locating and reading/writing .deadend/ledger.jsonl
report.js human-readable rendering
index.js programmatic API
MIT.