成本熔断器 openplancc/dsh-fuse

/dsh-fuse

面向 DeepSeek Harness 的多智能体成本策略：插件会计量每次智能体调用，在预算超支之前先熔断（本地熔断，<100ms，离线可用），再与 SaaS 面板同步——面板返回的 429 是第二道闸门。只有指标会上传：token、成本、模型——会话内容永远不离开本机。

中央面板：https://dsh.openplan.cc —— 按组织、项目、个人查看开销，插件在本地执行的预算，以及熔断历史。

安装

包内声明了 dsh.bundle，正是它让 dsh plugin add 激活这一层。没有这个声明，pnpm 只会装上一个不起作用的库。

npm — a forma canônica de instalação (publicado)
dsh plugin --profile <perfil> add @openplan/dsh-fuse

tarball (sem depender de registry)
pnpm pack # gera openplan-dsh-fuse-<versão>.tgz
dsh plugin --profile <perfil> add ./openplan-dsh-fuse-<versão>.tgz

direto do git (exige allowlist de build do pnpm >= 10 — veja a doc do harness)
dsh plugin --profile <perfil> add github:<org>/<repo>#<sha>

源码：https://github.com/openplancc/dsh-fuse（每次发版都会生成镜像——每个 v<版本> 标签对应本 monorepo 的一个 commit）。

插件用 @libsql/client 作为本地存储——无需原生构建，不用编译就能分发（Node ≥ 20）。

不用启动就能检查这一层：

dsh --profile <perfil> --dump-config # mostra '# == @openplan/dsh-fuse'

配置

bundle 自带安全的默认值（local-only 模式，store 锚定在 harness home，同步间隔 60s）。要覆盖，请编辑你自己 profile 的 cordis.patch.yml——这是用户层，在所有 bundle 层之后应用。覆盖方式是用同一个 id 直接写一行（不是再写一个 insert:，那会重复 id，让 loader 报 duplicate loader entry id 失败）：

~/.dsh/profiles/<perfil>/cordis.patch.yml
- id: fuse
name: '@openplan/dsh-fuse'
config:
project: meu-projeto
dev: eu@empresa.com
Caminho headless/CI (máquinas sem navegador). O padrão para humanos é
dsh plugin … exec dsh-fuse-connect (device flow) — ver acima. Segredo
nunca em texto puro no YAML — a tag !!js resolve no load. orgKey: !!js process.env.DSH_ORG_KEY baseUrl: https://dsh-api.openplan.cc Orçamento local (o fuse corta offline antes de gastar): budgets:
- limitUsd: 50
window: month
- limitUsd: 5
window: day
Políticas:
policies:
maxReasoningEffort é um id da PRÓPRIA rota (adapter-owned):
maxReasoningEffort: medium
allowedModels:
- deepseek/deepseek-v4-flash
denylistedProjects:
- projeto-cliente-confidencial
Preço (cents por 1M tokens) — OPCIONAL. Por padrão o plugin resolve o
preço de cada modelo automaticamente (registry models.dev; veja abaixo),
então esta tabela só existe para override explícito. As chaves podem ser
o id do adapter (com prefixo de provider), o id nu, ou qualquer alias:
pricingTable:
deepseek/deepseek-v4.1-flash:
inputCentsPerM: 15
outputCentsPerM: 60
cacheReadCentsPerM: 3
gpt-4o:
inputCentsPerM: 250
outputCentsPerM: 1000
Escape hatch quando o id do adapter não é adivinhável:
pricingAliases:
vendor/opaque-model-v9: gpt-4o
Uma taxa ÚNICA opcional (cents por 1M) para modelos que nenhuma fonte
precifica — um knob, não uma tabela. Sem ela, chamadas sem preço entram com custo zero mas marcadas como unpriced (nunca um zero silencioso). unpricedFallback: inputCentsPerM: 15 outputCentsPerM: 60

配置无效会让加载失败，并给出可操作的报错，而不是启动一个什么都不强制的插件：同步目标只写了一半（只有 baseUrl 或只有 orgKey），或者 cascade 与 policies.allowedModels 没有交集，都会在启动时被拒绝。价格不是必填项——插件会按下面的方式通用解析；没有价格的模型是一种可见状态（unpriced），而不是启动失败。

连接到面板（device flow——默认路径）

要把一台机器接入你的组织，对真人来说现代做法是 RFC 8628 device flow（和 gh auth login、wrangler login、Stripe 用的是同一套模式）：

dsh plugin --profile <perfil> exec dsh-fuse-connect

命令会打印一个 URL 加一个验证码，你在浏览器里批准（登录面板），token 就以 0600 权限保存到 $DSH_HOME/dsh-fuse/credentials.json——之后插件会直接和 SaaS 同步，不用粘贴任何密钥：

- token 绑定到批准它的用户（审计：是谁把这台机器接进来的），并且可以在面板里吊销（「已连接的会话」）——吊销会在下一次同步时生效（401 → 插件退回 local-only 并保留已有数据行）。
- 最小作用域（usage:write、policy:read）——批处理需要的就这些。
- 认证请求头：Authorization: Bearer <token>（x-org-key 仍然接受，用于机器/CI）。

如果你的流程是无头的（CI、容器、没有浏览器的机器），可用的路径是在配置里写 org key（见下）——API 两种都接受；device flow 是对真人的默认方式。

价格是怎么解析的

harness 上报模型时用的是 adapter 的 id（通常带 provider 前缀，比如 deepseek/deepseek-v4-flash），而价格目录是按路由（provider/model）作为键的。插件把两个来源合在一起，两者都会下载并缓存到 libsql 里，供离线使用：

- registry（pricingRegistryUrl，默认 https://models.dev/api.json）——按路由给出 USD 价格的目录，覆盖 200+ 个 provider。它能覆盖那些不公布价格的网关（比如 command-code），按 id 逐个解析模型。
- gateway（pricingGatewayUrl + pricingGatewayProvider）——当网关在自己的 /models 里公布价格时（OpenRouter、DeepInfra 等），这些数字对它自己的路由就是权威值。
adapter id 的解析按以下顺序查找：

1. pricingAliases[model]（显式指定，永远优先）
2. 本地表中的精确键
3. registry/gateway 中的 provider/model 路由
4. registry 中的裸 id（不带前缀的 adapter id）
5. id 的逐级后缀（例如 provider/anthropic/x → anthropic/x → x）

任何来源都未定价的模型会记为 unpriced: true（计入并在面板中显示）并写入日志——绝不静默记为零，因为价格为零会让 fuse 永不切断，服务器预算也永不触发。如果 org 设置了 unpricedFallback，这些模型就使用统一费率，预算仍会继续切断。

智能体能看到策略（面向模型的工具）

harness 文档规定了这一对组合：gate 说不（agent/pre-step 中的 fuse）——而一个独立的面向模型的工具让智能体自己读取策略状态。当组合装配 tools 服务（@deepseek-ai/dsh-tools）时，插件注册 dsh_budget_status：模型可以在会话中途查询各作用域（org/项目/dev）生效的预算、已花费总额与限额的对比，以及是否有远程 429 处于活动状态（以及持续到何时）。正是这一点让硬性拦截变得可容忍——智能体明白自己为什么被切断，可以做出调整（提问、停下、选择更便宜的路线），而不是盲目地撞死。

该工具只读，从不做决策：它读取 fuse 所执行的同一个 libsql（spentForWindow、remoteBlockFor、已发布的策略）并格式化出一个视图。它不做门控，也不重写任何东西。schema 会随每次请求传输，所以想要在 wire 上零存在感的人可以用 budgetStatusTool: false 关掉（默认 true）；如果 tools 服务没有装配，注册就直接跳过——插件不声明任何 inject，所以可选服务永远不会拖住加载。

仅本地模式

没有 baseUrl/orgKey 时，插件独自工作：不上传任何东西，fuse 离线执行预算。会话留在本地 libsql，默认位于 $DSH_HOME/dsh-fuse/local.db（未设置 DSH_HOME 时为 ~/.dsh/...）——锚定在 harness home，所以 ledger 不会随启动 harness 的目录而变化。storeUrl 可以换路径；相对路径只有在你显式设置时才有效。

上传到面板的内容（sync）

每 60s（syncIntervalMs）一个批次（POST /v1/usage/batch）：

- usage events —— 项目、dev、模型、provider、reasoning effort、tokens（输入、输出、缓存读取、缓存写入）、step 时长、成本和 timestamp。session id 在客户端哈希（SHA-256）后发出；内容永不外传。
- fuse cuts —— 每次 fuse 拦住一次调用（规则 + 项目），供面板显示「策略切断了多少次」。

只有 SaaS 确认（2xx 且带 ok）时，批次才会把这些行标记为已同步：500、代理返回的 502 或错误页面，永远不会让一行在未写入的情况下退役。

SaaS 返回的 429 BudgetExceeded { rule, reset_at } 会接上本地 fuse，直到重置窗口——被中心封禁的团队，在机器上同样被封禁。

面板作为控制平面

除了 429，插件在启动时以及每隔 policyRefreshMs 会拉取 GET /v1/policy（key 鉴权）：组织的预算和 hard 策略，用的是 fuse 的词汇表。正是这一步，让面板上编辑的规则能到达开发者的机器——没有这个拉取，本地 fuse 只能强制执行 deployment 的 YAML 里写的东西。结果缓存在 libsql 里，所以启动时的强制执行不依赖网络。

告警（50/80/95% + 偏离）

分级阈值由后端触发（不是插件）——在面板里配置渠道（告警 → 渠道）：Telegram（bot token + chat id）或 webhook（POST JSON {kind, payload, at}）。支出偏离会在最近一小时消耗 ≥ 过去 7 天均值的 5 倍且 ≥ US$ 1 时亮起。

Reasoning cap：为什么没有固定的取值列表

ReasoningEffortId 是 adapter-owned：harness 核心「brands identifiers but does not enumerate their values; each adapter owns the ordered set」。所以 cap 是按路由自身 efforts 列表里的下标比较的（ctx.llm.resolveModelInfo）。当路由没有公布这个列表时，cap 会被报告为不可强制执行（notEnforced，并在日志里告警），而不是靠猜——按名称或按字符编码做本地排序，会把某个 id 判成高于 high 的 none，结果恰恰卡住最便宜的那个请求。

GitHub Action

见 examples/agent-budget.yml。

验证

pnpm dsh:smoke（在 monorepo 根目录）会打包插件，用真实的 dsh plugin add 安装到一个一次性 profile，无头启动 harness，并要求 fuse 拒绝一个放不进 budget 的 step，且一次被允许的 run 记录下非零成本。

许可证

MIT。