Preface¶

In DeepSeek Harness (DSH), agents frequently need to make consecutive tool calls: executing commands, reading files, trying different APIs or approaches. After some attempts fail, the model may still repeat the same path within the same session or in subsequent sessions. Existing approaches may only warn about byte-level duplicates within a session, or rely on humans remembering that “this path doesn’t work.” The goal of @akslcw/dsh-negative-ledger is to persist such “falsified paths,” binding them with evidence and retry conditions.

Below, we introduce this plugin’s positioning, core mechanisms, installation, typical usage, and applicable boundaries. This article is based on verified plugin documentation and does not include unconfirmed data, star counts, or user feedback.

What This Is¶

• Name: @akslcw/dsh-negative-ledger
• Maintainer: akslcw
• License: MIT
• Positioning: Agent negative-knowledge ledger for DeepSeek Harness.
• Core Function: Records failure paths, including failed commands, missing files, rejected approaches, unavailable APIs; each record includes evidence and retry conditions; when evidence changes, the conclusion automatically becomes invalid; upon successful retry, the fact is marked as resolved.

It is explicitly not:

• Not memory: Does not save positive knowledge or perform semantic retrieval.
• Not a cache: Saves conclusions, not tool results.
• Not a bug regression tracker: Covers tool calls and file reads, not limited to fix attempts.

Core Mechanics¶

Below, we explain the process in four steps: “Recording, Matching, Interception, and Invalidation.”

1. Recording Failure Paths¶

The plugin only records falsified paths, not all tool calls. Recordable types include:

• failed commands
• missing files
• rejected approaches
• unavailable APIs

Each record includes evidence and retry conditions. Subsequent checks for duplicate attempts rely on fingerprints:

• Command-type attempts: Based on normalized command plus cwd
• File-type attempts: Based on file path

2. Matching Identical Attempts¶

When the same fingerprint appears again, the plugin determines whether the failure conclusion is still valid. If the evidence has not changed, it proceeds to the prompt or interception flow; if the evidence has changed, the conclusion is invalidated, allowing retries.

3. Warn and Block¶

The plugin provides three modes: off, warn, and block:

• warn: Default mode. Attaches additionalContexts at tools/post-execute, does not block calls, and does not rewrite tool results.
• block: Refuses calls at the tools/pre-execute stage, before dispatch.
• off: Completely disables recording and interception.

4. Automatic Invalidation After Evidence Changes¶

If the evidence on which a record depends changes, the plugin automatically invalidates the related conclusions and allows retries. If a retry succeeds, the fact is marked as resolved.

Backend and API¶

The plugin provides two store backends:

• SQLite backend: Supports WAL, revision-based optimistic concurrency, operation receipts, retry leases, and JSONL import.
• Legacy JSONL backend: Single-process, suitable for single-writer scenarios.

The Engine API exposes the following methods:

getFact
queryFacts
commitAttemptDecision
recordFact
transitionFacts
settleLease
summarize

The CLI provides the following commands, optionally selecting between SQLite or JSONL backends:

list
show <id>
stale
stats

Sharing and Security Boundaries¶

• The ledger is shared across multiple agents; subagents do not repeat attempts that parent agents have already failed.
• Claims do not embed raw command text; model-facing previews perform control character sanitization and length limits.
• Raw commands are retained in the ledger file for fingerprinting; files are written with 0600 permissions within 0700 directories.
• The ledger renders facts as quoted data, not executed as instructions.
• Single-writer JSONL is only for the legacy backend; the SQLite backend supports multi-process with WAL.

Installation and Enabling¶

DSH’s plugin mechanism allows installing and enabling extensions via profiles. The installation command for this plugin is:

dsh plugin --profile <name> add @akslcw/dsh-negative-ledger

This command installs the plugin and activates its bundle layer. The plugin package includes cordis.patch.yml, declared by the dsh.bundle manifest.

After installation, you can review the configuration before starting DSH:

dsh --profile <name> --dump-config
dsh --profile <name>

Removing the plugin:

dsh plugin --profile <name> remove @akslcw/dsh-negative-ledger

Runtime environment requirements:

Node ^22.19.0 || >=24.0.0

For compatibility, the plugin has been tested with @deepseek-ai/dsh-tools 0.1.1-rc.2 and declares an optional peer range:

@deepseek-ai/dsh-tools >=0.1.1-rc.2 <0.2.0

pnpm Considerations¶

pnpm >=11 may turn ignored build scripts into hard errors, causing add to fail:

ERR_PNPM_IGNORED_BUILDS: better-sqlite3

Documentation indicates that better-sqlite3 provides official prebuilds, so the ignored script itself does not trigger compilation. If this error occurs, run the following in the profile directory:

pnpm config set --location project strict-dep-builds false

Then re-run the install command:

dsh plugin --profile <name> add @akslcw/dsh-negative-ledger

If you instead choose to allow builds, better-sqlite3 will be compiled from source, requiring a C++ toolchain.

Typical Usage¶

CLI Querying the Ledger¶

Within the source repository, you can use the CLI directly:

node src/cli.ts --dir .ledger stats

The full form is:

node src/cli.ts [--dir <path>] [--backend sqlite|jsonl] <list | show <id> | stale | stats>

Where:

• list: Lists facts, including status, kind, id, and claim.
• show <id>: Views a single fact.
• stale: Views facts invalidated due to evidence changes.
• stats: Views interception-related counters, such as duplicate failures observed, warnings emitted, and calls denied.

Demo and Smoke Commands¶

Executable examples provided in the documentation include:

node demos/run-demos.ts
node smoke/real-mount.ts
powershell -File smoke/plugin-add-smoke.ps1

Among these, powershell -File smoke/plugin-add-smoke.ps1 is for clean-environment end-to-end smoke testing, covering add, layer, headless warn, SQLite ledger, and profile restart after removal.

Overriding Configuration Rows¶

The plugin provides the negative-ledger configuration row, supporting the following keys:

backend
mode
dir
commandRetryAfterMs
commandTools
readTools

Subsequent layers can override the negative-ledger row by id, re-declaring all modified configuration keys. For example, if you only want to change mode, do not just write a single isolated key in the patch; express the complete new config in the override row to avoid losing other keys when the row is entirely replaced.

Default behavior:

• warn is the default mode and does not block calls.
• block rejects calls at tools/pre-execute.
• off disables recording and interception.
• The default commandRetryAfterMs for auto-recorded command facts is 5 minutes.
• never and manual are reserved for facts recorded by explicit, trusted authors.

Applicable Scenarios and Cautions¶

Scenarios suitable for this plugin include:

• DSH agents repeatedly invoking the same failing command.
• Files do not exist or paths are unavailable, yet agents repeatedly attempt to read them.
• Certain APIs or approaches are unavailable in the current environment, and you want to bind “do not retry immediately” as an evidence-linked constraint.
• Multi-agent or subagent scenarios where you do not want subagents to repeat attempts that have already failed for parent agents.
• When you need queryable, countable negative facts that can be invalidated by evidence changes.

Boundaries to note:

• It is not a positive memory system and does not save knowledge about “what can be done.”
• It is not a cache and does not replace tool result storage.
• It is not a bug regression tracker and does not target test failures or fix regressions themselves.
• The plugin runs with current DSH process privileges; inspect the source code and MIT license before installation to confirm its behavior meets your local security requirements.
• The Known limitations and deferred work section in the documentation is truncated, so not all limitations can be confirmed; it is recommended to review the repository README before use.
• The DSH ecosystem typically extends harness capabilities through plugins; the plugin mentioned in this article belongs to the community/plugin-index ecosystem and should not be understood as an official DeepSeek or High-Flyer application store offering.

Conclusion¶

The value of @akslcw/dsh-negative-ledger lies in its ability to transform failed attempts into trackable, invalidatable, and shareable negative facts. It does not replace memory, caching, or regression tracking, but instead addresses the problem of “agents repeatedly trying the same falsified path” by providing an evidence-bound DSH plugin solution.

Relevant Links:

• GitHub: https://github.com/akslcw/dsh-negative-ledger
• Plugin Index Directory Page: https://www.skillhub.cn/plugins/akslcw/dsh-negative-ledger
  Note: This directory page link comes from the plugin index and was not present in the main body of the scraped documentation. Please verify it yourself before visiting.