概览

dsh-agent-frugality

DSH 对抗多智能体三层失效的防御插件：读取台账去重度量(read-ledger)、免疫压缩规则区+完成机械门禁(immutable-core+completion-gate)、低成本审查lane(role-router)。零外部依赖，注入即用。

README / ZH

插件文档

dsh-agent-frugality

English | 中文

DeepSeek Harness（DSH）插件：对抗多智能体三层机制性失效的防御插件—— 读取台账去重 · 免疫压缩规则区 · 完成机械门禁 · 低成本审查 lane。零外部依赖，注入即用。

📐 规格事实源：docs/SPEC.md · 📋 任务清单：TICKETS.md · 📝 变更记录：CHANGELOG.md · 🛒 市场状态：docs/MARKETPLACE.md

它做什么

能力	效果
read-ledger 读取台账	所有读类工具调用按内容哈希记入 per-agent 台账；`frugality_ledger` 一眼看出"谁在重复读"——浪费从不可见变成可见
immutable-core 免疫规则区	恒久规则注册进每次组装都重渲染的提示词 section——上下文压缩无法移除
completion-gate 完成门禁	"完成"必须经过 `frugality_gate`：声明 + 验证 exit 0；空口完成被塞回重做（≤2 次防死循环）
review-lane 审查 lane	`frugality_review` 自动挑 CHEAP 便宜模型做独立审查——贵主模型不审查自己的活

适合谁：跑长时多智能体 DSH 会话的团队与个人、插件作者，以及任何觉得 token 在涨但说不清"为什么"的人。

为什么

多智能体系统存在三类被实测与独立证据支持的机制性失效：

失效	证据	本插件防御
子智能体重复读取（无共享记忆 → 内耗烧 token）	Claude Code #46968、#45660；Jack Maguire 实测子智能体占长任务大部分成本、修复可省 70–90%	`read-ledger` 内容哈希台账 + 已读清单注入
提示词失效（软规劝短期失效、压缩后丢失）	Anthropic《Building effective agents》：成本权衡来自架构而非提示语	`immutable-core` 规则区（免疫压缩）+ `completion-gate` 机械门禁
贵模型误区（贵模型产出低、当审查员反而更弱）	Anthropic《multi-agent research system》：收益来自 token 预算；RouteLLM/FrugalGPT 生态共识	`review-lane` 便宜模型独立审查

限制边界：本插件不禁止多智能体，而是把失效变成可度量 + 可物理阻断；先度量后干预（DEDUP 默认关）。

⚠️ 科研诚实声明：插件不背书流传的"$85K 多智能体实验"具体数字（54.7% / 243→311 / Opus 23.9% 等经核实无一手出处，属生成式摘要幻觉，核实报告见 research/01-primary-source.md）。本插件针对有独立证据的机制问题本身。

快速开始

# 1. 安装（v0.1.0 已发布）
dsh plugin add github:gongyijie85/dsh-agent-frugality   # GitHub 通道（主分发；市场收录基于 topic）
npm install dsh-agent-frugality                          # npm 通道

# 本地开发态（运行时注入，免重启）
dev_inject_plugin D:\plugins\dsh-agent-frugality
# dev_uninject_plugin dsh-agent-frugality

# 2. 先看基线——台账默认开，DEDUP 默认关
frugality_ledger

# 3. 基线说了算再干预（如 dupRate > 15% 持续一周 → DSH_FRUGALITY_DEDUP=1）

完成门禁默认开启（DSH_FRUGALITY_GATE=1）；只有跟你的工作流打架时才关。

机制（一图流）

工具调用 ──→ tools/result ──→ [read-ledger] SHA-1 台账 → JSONL 持久化
                      │                │
                      └─ 第≥2次同内容 ──→ [dedup-replace] 摘要替换（可选 DEDUP=1）
system-prompt/assemble ──→ [immutable-core] frugality-rules（免疫压缩）+ frugality-read-cache（已读清单）
agent/turn-stopping ──→ 完成性声明 且 无 gate 凭证 ──→ steer 塞回（≤2 次）
frugality_gate / frugality_review / frugality_ledger ──→ 三个工具

工具

工具	用途
`frugality_ledger`	读取台账（per-agent reads/dups/bytes、重复率、门禁状态、审查计数；含 JSONL 恢复）——先看基线，再决定开干预
`frugality_gate`	完成门禁：`claim` 必填；验证命令 exit 0 才通过（命令仅宿主配置）
`frugality_review`	低成本审查：便宜模型独立审查代码/diff/白名单文件（quick/deep），输出 verdict+findings

配置（环境变量全表，详见 docs/SPEC.md §6）

变量	默认	说明
`DSH_FRUGALITY_DEDUP`	`0`	`1`=同内容第 ≥2 次读取替换为摘要提示
`DSH_FRUGALITY_GATE`	`1`	`0`=禁用完成门禁
`DSH_FRUGALITY_GATE_MAX`	`2`	门禁 objection 轮数上限（防死循环）
`DSH_FRUGALITY_VERIFY`	空	默认验证命令（如 `npm test`；exit 0=通过）
`DSH_FRUGALITY_ALLOW_ARG_VERIFY`	`0`	`1`=允许工具参数 verify（默认忽略防模型 RCE，SPEC §7.1）
`DSH_FRUGALITY_REVIEW_MODEL`	auto	审查模型；auto=自动选 CHEAP 族
`DSH_FRUGALITY_RULES`	builtin	规则文件（≤8KB）
`DSH_FRUGALITY_LEDGER_CAP`	`30`	已读清单注入条数上限
`DSH_FRUGALITY_WORKDIR`	cwd	gate 验证命令工作目录
`DSH_FRUGALITY_READ_PATTERNS`	builtin	追加读类工具子串（逗号分隔）

FAQ / 排障

DEDUP 为什么默认关？ 先度量后干预：台账先告诉你真实重复率，再决定是否开干预；基线证明净收益为正才开。

验证命令会不会被用来执行任意代码？ 不会。frugality_gate 只运行宿主配置的 DSH_FRUGALITY_VERIFY；工具传入的 verify 参数默认忽略，除非 DSH_FRUGALITY_ALLOW_ARG_VERIFY=1（防 RCE，SPEC §7.1）。

会破坏子智能体吗？ 不会——read-ledger 只观察/可选去重读结果；immutable-core 只注入提示词 section；不拦截、不改写任何 agent 输出。

我的内容会被记日志吗？ 不记内容。台账只存内容哈希 + 目标；日志是 JSONL 事件（apply/read/gate/review），不含文件全文（SPEC §7）。

日志在哪？ $DSH_HOME/agent-frugality.log（JSONL 事件）与 $DSH_HOME/agent-frugality-ledger.jsonl（台账持久化）。

会不会和别的插件重复？ 只补缺口：共享记忆用 dsh-memory-vault、模型路由用 dsh-model-router、任务编排用 dsh-agent-teams；本插件只加读取去重度量、host 级完成门禁、低成本审查 lane。

目录结构

lib/index.js       宿主装配（hooks/工具注册/配置/持久化）
lib/core.js        纯函数与常量（18 用例全绿）
test/core.test.mjs node:test 零依赖测试
docs/SPEC.md       技术规格（FR/NFR/安全模型 §7/接口契约 §8/验收标准 §9）
docs/MARKETPLACE.md 市场收录材料与状态
TICKETS.md         产品化任务清单（Phase 1-5）
CHANGELOG.md       变更记录
LICENSE            MIT

测试与验证

node --test test/core.test.mjs   # 18/18（toJsonSchema/isReadTool/targetOf/applyRead/foldLedgerLine/...）
node --check lib/index.js && node --check lib/core.js

设计原则

先度量后干预：台账默认开、DEDUP 默认关；frugality_ledger 跑基线，净收益为正再开干预。
物理阻断 > 提示词：规则落到工具结果错误 / turn-stopping objection / deny；提示词仅回显（规则区本身免疫压缩）。
只补缺口：共享记忆用 dsh-memory-vault、路由降级用 dsh-model-router、任务门禁用 dsh-agent-teams；本插件只补读取台账、host 级完成门禁、低成本审查 lane。
零依赖：仅 node: 内置 + lib/core.js；JS 直出（dsh-mode-boost 同路径，无编译依赖）。

实验数据（日常即实验）

插件天生带度量：每个真实会话都在喂台账，周期性快照发布到仓库作为效果证据。

node scripts/experiment-report.mjs   # -> docs/experiments/YYYY-MM-DD-snapshot.{json,md}

首份快照（2026-08-29）：34 次读取 / 5.9% 重复率 / 93KB / 门禁 3 过 3 拦 / 审查 lane 1 次 9 findings / 0 插件错误
Exp-3 完成（2026-08-29）：cheap 臂（flash）81.8% recall @ $0.033、每美元命中 = 主模型 1.65×；strong 臂 100%/0 误报 @ $0.067 → 双 lane 策略验证通过（结果）
阈值与运营闭环：docs/EXPERIMENT.md（「运营模式」节）

路线图

每周台账快照 → README 实验数据段更新（T21）
阈值运营闭环：dupRate > 15% 持续一周 → DEDUP=1；每版记录「基线→改进→验证」（T22）
下一版候选：跨会话台账摘要；review-lane 反馈进入 DEDUP 启发式

发布与收录状态（v0.1.0，2026-09-02 更新）

GitHub：github.com/gongyijie85/dsh-agent-frugality（main + tag v0.1.0）
npm：dsh-agent-frugality@0.1.0
GitHub Release @ v0.1.0，含 dsh-agent-frugality-0.1.0.tgz 资产
仓库描述与 topics（dsh-plugin deepseek-harness multi-agent）已设——topic 同步市场自动收录
awesome-dsh-plugin curated 注册表 PR #4173——2026-09-02 已提交，待维护者合并（合并后 dsh-market 一键安装生效）
chnjames / 0326 目录——经 dsh-plugin topic 自动发现，下个同步周期自动出现（无手动提交入口）

Topics（2026-09-02 扩充为 12 个）：dsh-plugin deepseek-harness dsh cordis multi-agent ai-agents agent-cost cost-optimization token-efficiency context-management subagent completion-gate——在仓库 Settings → About → Topics 应用。

参与贡献

见 CONTRIBUTING.md。安全模型见 SPEC §7（verify 命令仅宿主配置；review 文件白名单；日志不记内容）。

License

MIT

dsh-agent-frugality