sid-code

主题

预算 ​

这页写给用管理台的管理员：怎么在「成本」页给组织、团队、设备配远程预算，超限之后员工的 sid-code 会怎样。

远程预算是跨会话、跨设备的额度：用量由服务端从账本汇总，员工改本地 settings.json 放不宽它。员工本地的 costLimit（单会话、进程内）写在配额与成本控制，两者同时生效，先到先停，数字不合并。

看花了多少钱在成本页。这页只讲「额度和超限开关」。

只取一层，不合并

和策略一样，按 设备 > 团队 > 组织 取第一层有生效预算的，额度不叠加。

给团队 platform 配了 $50/月，组织 acme 的 $1000/月对这个团队的设备就完全不再生效：团队用完 $50 才触发，组织总额不再约束它们。

同一层里配了多个周期时，也只取一条，按固定顺序：单会话 > 自然日 > ISO 周 > 自然月。同层同时配了日预算和月预算，生效的是日预算，月预算被忽略。要同时约束日和月，目前做不到。

联动：配了之后员工那边会怎样 ​

你在管理台做了什么sid-code 什么时候知道拉取失败时员工看到什么
新建 / 修改 / 启用一份预算下次启动；本会话账本上报成功后刷新（两次至少间隔 30 秒）；执行 /login按没有远程预算处理，本地 costLimit 照常生效超限时见下表
停用 / 删除同上。服务端回 204 或命中上一层同上不再提示，或换成上一层的额度
切到「硬拦」同上同上超限后本轮结束

超限判定在客户端：估算用量 = 服务端返回的本周期 used_usd + 本会话尚未上报的部分，估算 ≥ 上限即超限。每次模型返回之后检查一次。

超限动作员工看到效果
告警放行（默认）远程预算 team:platform 2026-10 已超限（告警放行，不结束会话）（$51.2000 / $50.00，含辅助调用）继续工作。超限期间每次模型返回都会再提示一次
硬拦（结束会话）远程预算 team:platform 2026-10 已超限，自动停止（…）本轮立即结束，和本地 costLimit 超限同一种停法

几个细节：

  • 鉴权：GET /api/v1/ctl/budget，必须带设备凭据。没登录的员工拉不到远程预算。
  • 超时 5 秒，不重试；带 ETag，没变化时 304。
  • fail-open 的范围很宽：网络错误、超时、204、401、5xx、返回内容解析不了、没登录，一律当没配远程预算。
  • 硬拦是事后拦：检查发生在模型返回之后，最后一次调用的钱已经花了。不要把上限设在「一分都不能超」的位置。
  • 硬拦不锁设备：员工可以立刻开新会话，新会话里第一次模型返回之后又会被拦。

出处：packages/core/src/telemetry/remote-budget.ts、packages/core/src/query/loop.ts；agent-backend: backend/app/modules/cost/。

员工关了遥测时 ​

no-telemetry 的设备，预算会失真

员工把隐私级别调成 no-telemetry 或 essential-traffic 后，账本不再上报，但预算照常拉取。结果是：

  • 服务端的 used_usd 里没有这台设备的花费，团队层、组织层的用量偏低；
  • 这台设备自己只按「服务端 used + 本会话」估算，之前会话花的钱不计入。

要让预算可信，用托管配置锁定隐私级别，见企业 policy 与安全边界。

在管理台里操作 ​

页面在左侧菜单「成本」，下半部分的「预算（超限开关）」区块。

新建一份预算 ​

  1. 点「新建预算」。
  2. 「层」选 组织 / 团队 / 设备，填「组织 ID」；选团队或设备时，再填「团队 ID」或「设备 ID」。
  3. 选团队层或设备层时，如果上层已经有生效中的预算，弹窗顶部提示「此层生效后，上层 X 对这些设备不再生效」，下面每份上层预算一个「从…复制内容」按钮，复制周期、上限和超限动作。
  4. 「周期」：自然月（UTC）/ ISO 周 / 自然日（UTC）/ 单会话。
  5. 「上限（USD）」，最小 0.01。
  6. 「超限动作」：告警放行 / 硬拦（结束会话）。
  7. 「变更原因（进审计）」必填。
  8. 确定。选了硬拦时会再弹一次「切到硬拦？」确认。

建议先用「告警放行」跑一个周期，看清真实花费，再决定要不要切硬拦。

改、停用、启用、删除 ​

按钮作用要填什么
改改周期、上限、超限动作。层和对象不能改变更原因；保存硬拦时二次确认
停用不再下发，该层设备按没配远程预算处理原因
启用重新进入下发原因
审计这一份的变更记录——
删除真删。审计记录保留，账本不受影响原因

修改一份已经超限的预算并保存为硬拦时，确认框会写明「该层本周期已用 $X ≥ 上限 $Y，保存后将立即对正在跑的会话生效」，按钮是「确认，立即生效」。「立即」指的是客户端下一次拉取预算之后，不是瞬间。

表格「本周期 used / limit」显示的是服务端此刻按账本算出的已用额，used ≥ limit 时有红色「超限」标签。页面上方的「超限的层」卡片统计这类预算有几层，其中几层是硬拦。

预览某台设备会命中哪一份 ​

预算表上方输入设备 ID，点「预览命中」：

  • 「将命中 team platform · monthly（2026-10） · $1.25 / $50.00 · 告警放行」：这台设备现在按这一份算；
  • 「三层都没有生效预算（客户端按没配远程预算处理）」；
  • 黄色框「被遮蔽的上层预算（对这台设备整份不生效，不叠加）」：列出被下层遮住的上层预算。

字段说明 ​

字段取值校验规则员工端效果
层组织 / 团队 / 设备建好后不能改决定哪些设备受约束
组织 ID / 团队 ID / 设备 ID已存在的对象不存在 404；组织层的对象 ID 必须等于组织 ID——
周期见下同层、同对象、同周期只能有一份生效中的，否则 409决定 used_usd 的统计窗口
上限（USD）> 0只支持美元超过即触发超限动作
超限动作告警放行 / 硬拦默认告警放行。没有「降级模型」选项见联动
变更原因文本必填，空或纯空白 422只进审计

周期怎么算 ​

全部按 UTC 划分。北京时间每天 08:00 才是「新的一天」，每月 1 日 08:00 才是「新的一月」。

周期周期键统计什么
自然日（UTC）2026-10-16这一层所有设备当天的账本合计
ISO 周2026-W42当周合计，周一开始
自然月（UTC）2026-10当月合计
单会话session见下方警告
  • 用量含辅助调用：标题生成、子代理、分类器的花费都算在内。
  • 一个会话算在它最后一次上报的那一天：跨过 UTC 零点的会话，全部计入后一天（或后一周、后一月）。
  • 按上报时的归属统计：设备从团队 A 调到团队 B 之后，它之前在 A 花的钱仍算在 A。

「单会话」周期名不副实

服务端看不出会话是否还在进行。团队层、组织层的「单会话」预算，取的是这一层所有设备里最新上报的那一个会话，可能是别人的。单会话的硬停请让员工用本地 costLimit，见配额与成本控制。弹窗里这一项的说明也写了这一点。

写入规则 ​

情况结果
同层、同对象、同周期已有生效中的预算409「同层同周期已有生效预算」。改内容请更新那一条，或先停用再新建
修改或启用后会和另一份冲突409
组织 / 团队 / 设备不存在404
上限 ≤ 0、周期或超限动作取值不对、出现未知字段422
原因为空422

设备层预算的组织 ID 会被自动改成设备当前所在的组织。

能力边界（如实说） ​

1. 同一层只能约束一个周期。 日、周、月同层只取最严格顺序上的那一条，不能同时限「每天 $10 且每月 $100」。

2. 硬拦是事后的，也不锁设备。 超限后本轮结束，但开新会话还能再跑一轮模型调用。要彻底停掉一台设备，吊销设备。

3. 用量来自员工端上报，不是厂商账单。 成本是客户端按价格估算的；员工关了遥测、没登录、离线时这部分花费不进账本，见员工关了遥测时。

4. 不管 sid-code 之外的花费。 员工用同一把 API Key 在别处调用，不计入。

5. 生效有延迟。 员工端在启动、/login、账本上报成功后才刷新预算。长时间没有新上报的会话（例如一直在等用户输入）不会刷新。

常见问题 ​

配了预算，员工那边没有任何提示 ​

按顺序排查：

  1. 「预览命中」看这台设备命中的是不是你配的那一份，有没有被下层遮蔽；
  2. 「本周期 used / limit」是否真的超了。没超当然不提示；
  3. 让员工跑 sid-code auth status --verify，看「预算」通道是否 ✓；
  4. 员工是不是 no-telemetry：「成本」页「按设备看用量」里这台设备没有新的上报，就是这个原因。

团队超了，组织还没超，为什么团队的人被拦了 ​

这正是「只取一层」：团队层有预算时，团队的设备只看团队预算。想让团队只受组织总额约束，停用团队层那份。

用量什么时候清零 ​

周期键变化时自然清零：UTC 零点（日）、周一 UTC 零点（周）、每月 1 日 UTC 零点（月）。不能手动清零。

想临时给某个人放宽 ​

给他的设备加一份设备层预算（先「从…复制内容」再改上限），用完停用即可。设备层会遮蔽团队层和组织层。

相关 ​