dsh-agent-frugality
English | 中文
A DeepSeek Harness (DSH) plugin that defends multi-agent systems against three mechanism-level failure modes:
read-ledger dedup · compaction-immune rules · mechanical completion gate · cheap-review lane.
Zero external dependencies — inject and go.
📐 Spec: docs/SPEC.md · 📋 Tickets: TICKETS.md · 📝 Changelog: CHANGELOG.md · 🛒 Market status: docs/MARKETPLACE.md
What it does
| Capability | Outcome |
|---|
| read-ledger | Every read-type tool call is content-hashed into a per-agent ledger. frugality_ledger shows who re-reads what — waste becomes visible instead of invisible. |
| immutable-core | Frugality rules live in a compaction-immune prompt section (re-rendered on every assembly) — context compression cannot erase them. |
| completion-gate | "Done" must pass frugality_gate with a claim + exit-0 verification. Unsupported completion claims are steered back (≤2 objections, anti-loop). |
| review-lane | frugality_review runs independent review on the CHEAP model family — the main (expensive) model never reviews its own work. |
Who it is for: teams and solo builders running long multi-agent DSH sessions, agent plugin authors, and anyone whose token spend grows with no accounting for why.
Why
Three failure modes are real and independently evidenced:
| Failure | Evidence | This plugin's defense |
|---|
| Subagent duplicate reads (no shared memory → token waste) | Claude Code #46968, #45660; Jack Maguire: subagents account for most token cost in long runs, 70–90% recoverable | read-ledger content-hash ledger + "already read" sheet injection |
| Prompt decay (soft rules fade, compaction erases them) | Anthropic Building effective agents: cost tradeoffs come from architecture, not wording | immutable-core rules in a compaction-immune prompt section + completion-gate mechanical gate |
| Expensive-model fallacy (costly models are worse reviewers) | Anthropic multi-agent research system: gains come from token budget; RouteLLM/FrugalGPT consensus | review-lane cheap-model independent review |
This plugin does not forbid multi-agents — it makes the waste visible and the behavior mechanically bounded; measure first, intervene second (DEDUP off by default).
⚠️ Research-integrity note: this plugin does not endorse the headline numbers of the "$85K multi-agent experiment" (54.7% duplicate reads / 243→311 commits / Opus 23.9% — verified to have no primary source; they are a generated-summary hallucination; verification report: research/01-primary-source.md). It targets the mechanism problems themselves, which do have independent evidence.
Quick start
# 1. Install (published v0.1.0)
dsh plugin add github:gongyijie85/dsh-agent-frugality # GitHub channel (primary)
npm install dsh-agent-frugality # npm channel
# Local dev (runtime injection, no restart)
dev_inject_plugin D:\plugins\dsh-agent-frugality
# dev_uninject_plugin dsh-agent-frugality
# 2. Measure your baseline — the ledger is ON by default, DEDUP is OFF
frugality_ledger
# 3. Intervene only when the baseline says so
# (e.g. dupRate > 15% for a week → set DSH_FRUGALITY_DEDUP=1)
The completion gate is ON by default (DSH_FRUGALITY_GATE=1). Disable only if it fights your workflow.
How it works
tool calls ──→ tools/result ──→ [read-ledger] SHA-1 ledger → JSONL persistence
│ │
└─ 2nd+ same content ──→ [dedup-replace] summary swap (DEDUP=1)
system-prompt/assemble ──→ [immutable-core] frugality-rules (compaction-immune) + frugality-read-cache
agent/turn-stopping ──→ completion claim without gate proof ──→ steer back (≤2)
frugality_gate / frugality_review / frugality_ledger ──→ three tools
Tools
| Tool | Purpose |
|---|
frugality_ledger | Read ledger (per-agent reads/dups/bytes, dup rate, gate & review counters; JSONL-restored) — baseline first, then decide on intervention |
frugality_gate | Completion gate: claim required; verify command must exit 0 (host-configured only) |
frugality_review | Cheap-review lane: independent review on a CHEAP-class model (quick/deep), verdict + findings |
Configuration (env vars — full table in docs/SPEC.md §6)
| Variable | Default | Meaning |
|---|
DSH_FRUGALITY_DEDUP | 0 | 1 = replace 2nd+ identical read with a summary |
DSH_FRUGALITY_GATE | 1 | 0 = disable completion gate |
DSH_FRUGALITY_GATE_MAX | 2 | max gate objections (anti-loop) |
DSH_FRUGALITY_VERIFY | empty | default verify command (npm test; exit 0 = pass) |
DSH_FRUGALITY_ALLOW_ARG_VERIFY | 0 | 1 = accept tool-arg verify (default ignored — anti-RCE, SPEC §7.1) |
DSH_FRUGALITY_REVIEW_MODEL | auto | review model id; auto = CHEAP family |
DSH_FRUGALITY_RULES | builtin | rules file (≤8KB) |
DSH_FRUGALITY_LEDGER_CAP | 30 | read-cache sheet max entries |
DSH_FRUGALITY_WORKDIR | cwd | gate verify command cwd |
DSH_FRUGALITY_READ_PATTERNS | builtin | extra read-tool substrings (comma-separated) |
FAQ & troubleshooting
Why is DEDUP off by default? Measure-first philosophy: the ledger shows your real duplicate rate before any intervention. Enable it only when the baseline shows net gain.
Can the verify command run arbitrary code? No. frugality_gate only runs the host-configured DSH_FRUGALITY_VERIFY; tool-provided verify args are ignored unless DSH_FRUGALITY_ALLOW_ARG_VERIFY=1 (anti-RCE, SPEC §7.1).
Does it break subagents? No — read-ledger only observes and dedupes read results (opt-in); immutable-core only injects a prompt section; nothing blocks or rewrites agent output.
Is my content logged? No content is stored: the ledger records content-hashes + targets only; logs are JSONL events (apply/read/gate/review) without file contents (SPEC §7).
Where are the logs? $DSH_HOME/agent-frugality.log (JSONL events) and $DSH_HOME/agent-frugality-ledger.jsonl (ledger persistence).
Does it duplicate other plugins? It intentionally fills only the gaps: shared memory → dsh-memory-vault; model routing → dsh-model-router; task orchestration → dsh-agent-teams. This plugin adds read dedup metrics, the host completion gate, and the cheap-review lane — nothing else.
Layout
lib/index.js host assembly (hooks / tool registration / config / persistence)
lib/core.js pure functions & constants (18 unit tests green)
test/core.test.mjs node:test, zero-dependency
docs/SPEC.md spec (FR / NFR / security model §7 / API contract §8 / acceptance §9)
docs/MARKETPLACE.md marketplace ingestion kit & status
TICKETS.md productization checklist (phase 1-5)
CHANGELOG.md release notes
LICENSE MIT
Test & verify
node --test test/core.test.mjs # 18/18
node --check lib/index.js && node --check lib/core.js
Design principles
- Measure first, intervene second — ledger on, DEDUP off until your baseline shows net gain.
- Mechanical bounds > prompts — rules land in tool-result errors / turn-stopping objections; prompts only echo (the rules section itself is compaction-immune).
- Only fill real gaps — shared memory via
dsh-memory-vault, routing via dsh-model-router, task gates via dsh-agent-teams; this plugin adds read-ledger, host completion gate, cheap-review lane.
- Zero deps — node built-ins +
lib/core.js; JS-direct like dsh-mode-boost.
Experiment data (daily-use-as-experiment)
The plugin is instrumented by design: every real session feeds the ledger, and periodic snapshots are published to the repo as evidence.
node scripts/experiment-report.mjs # -> docs/experiments/YYYY-MM-DD-snapshot.{json,md}
- First snapshot (2026-08-29): 34 reads, 5.9% duplicate rate, 93KB, gate 3 pass / 3 objections, review lane 1×9 findings, 0 plugin errors
- Exp-3 done (2026-08-29): cheap lane (flash) 81.8% recall @ $0.033 with 1.65× per-dollar hits vs strong; strong (v4) 100%/0 FPs @ $0.067 → dual-lane policy validated (results)
- Thresholds & ops loop:
docs/EXPERIMENT.md ("运营模式" section)
Roadmap
Release & ingestion status (v0.1.0, updated 2026-09-02)
Topics (2026-09-02 expanded, 12): dsh-plugin deepseek-harness dsh cordis multi-agent ai-agents agent-cost cost-optimization token-efficiency context-management subagent completion-gate — apply in repo → Settings → About → Topics.
Contributing
See CONTRIBUTING.md. Security review: SPEC §7 model (verify command is host-config only; review file whitelist; no content in logs).
License
MIT
