1. 先说结论：Agent开发者的Token焦虑，可以缓解
最近这一个月我基本都泡在DSH上打磨Agent。DSH可以理解为一套面向智能体开发的本地工作台，它的CLI做得相当顺手，插件生态也越来越丰富，dsh plugin命令配合插件市场用起来很灵活。真正让我头疼的是另一个问题：Token消耗太快，余额和配额却要打开网页端才能看，开发节奏一快，根本顾不上切页面。后来我把dsh-usage-stats插件装上，一条命令就能把当前Profile下所有Agent的Token消耗、账户余额和调用配额全部列出来，我终于不用再靠猜来估算成本。
这个插件解决的是Agent开发里非常实际的问题：模型调用会产生Token，Token会消耗余额，余额不足会影响测试，配额被打满会让Agent直接报错。如果你也经历过“改了一版Agent，跑一轮测试，额度就掉了一截，还不知道烧在哪个环节”的情况，那dsh-usage-stats就是给你准备的。
我建议所有用DSH做Agent开发的人，无论你是刚入门还是已经在写生产级Agent，都先把这个插件装起来。它适合三种场景：一是本地开发时快速查看当前账号的Token用量，不打断思路；二是多Agent、多Profile并存时做成本归因；三是配合定时任务或脚本做余额告警，防止测试测到一半因为欠费中断。
2. 为什么Agent开发里，Token和配额统计这么重要
2.1 从“Agent框架”看Token到底烧在哪
很多人第一次意识到Token问题，是在Agent框架上跑通了一个完整任务之后。Agent不是简单的一次Prompt一次回复，它是一个循环：模型推理、调用工具、拿到结果、再次推理、再调用下一个工具，直到任务完成。这个循环里，每一轮模型调用都会把之前的上下文重新计算一遍，Token量自然呈倍数增长。
举个我实际跑过的例子。让一个带网页搜索和代码执行工具的Agent完成“查一个开源库的最新Release并查看变更日志”这种任务，表面上是两步操作，但实际上可能会有8到12次模型调用。第一次调用生成调用搜索工具的参数，第二次调用根据搜索结果决定要不要打开Release页面，第三次调用读取页面内容并生成下一步动作，如果页面信息太多，还会拆成多轮。每一轮都要把前面的对话历史、工具返回结果、系统提示词全部重新发送给模型，于是你看到的Token用量就被快速放大。
不同的Agent框架，比如热词里常提到的hermes agent、pi agent，在Token消耗的细节上会有差异，但核心逻辑一致：Agent越复杂，工具越多，上下文越长，Token越不经用。我早期调试Agent时，常常觉得“我也没让模型写多少字，怎么Token就飙了”，后来把每次调用的usage字段拉出来一看，才发现大部分Token都消耗在重复发送的历史上下文和工具返回结果上。
2.2 官方控制台与CLI插件各自能解决什么问题
DSH本身是有Web端控制台的，里面能看到账号的用量曲线和账单信息。说实话，官方控制台做得不差，图表化和计费明细都有，但它和开发者的工作流是割裂的。你在终端里改Agent配置、跑测试、看日志，出了问题想要确认是不是额度导致，就得切到浏览器，登录、点击、刷新、查找，一通操作下来，思考节奏早就断了。
dsh-usage-stats这类插件解决的是“开发上下文里直接给答案”的问题。它在DSH的CLI环境下运行，让你不用离开终端就能看到Token、余额和配额的实时状态，还能输出JSON格式，方便写脚本做自动化处理。
我用一个表格简单对比一下官方控制台和这个插件的差异：
| 对比维度 | 官方控制台 | dsh-usage-stats |
|---|---|---|
| 查看位置 | 浏览器 | 终端 |
| 数据粒度 | 账单级、按天/按月 | 可按Profile、Agent、Model聚合 |
| 多环境切换 | 手动切换页面 | 命令行指定Profile |
| 自动化 | 需要写爬虫或对接API | 原生支持JSON输出、阈值告警 |
| 适用场景 | 月底对账、查看趋势 | 日常开发、CI、快速定位问题 |
官方控制台适合做财务对账，插件适合做开发过程中的快速判断。两者并不冲突，我现在的习惯是：日常靠dsh-usage-stats监控，月底去官方控制台核对账单。
2.3 免费Token与配额使用率的隐藏成本
很多DSH用户会先领平台的免费Token额度，用免费额度跑通原型。免费额度有个特点，它是“先用先扣、用超才扣余额”，也就是说当你的免费Token快用完时，系统不会立刻切换，而是会继续消耗直到超额才计费。这个切换点如果不监控，很容易出现“我明明还有免费额度，怎么突然开始扣费了”的情况。
dsh-usage-stats可以把免费额度和付费余额分开显示，避免这种误判。除此之外，配额使用率也是一个容易被忽略的指标。所谓配额，不是“剩余还能用多少Token”，而是“每分钟或每秒最多能调用多少次、多少个Token”。Agent开发中经常会遇到突发并发，多个Agent同时跑任务，配额瞬间被打满，API返回限流错误，任务中断。这个错误看起来像是代码问题，实际上是因为你在短时间内把配额全部吃完了。
3. dsh-usage-stats 功能拆解：一次看全Token、余额和配额
3.1 插件到底能看什么
dsh-usage-stats的名字很直白，就是usage和stats。它不是一个简单的Token计数器，而是把和用量相关的几个关键维度集中到了一起。我整理了一下它提供的核心能力：
- Token用量统计：按Profile、Agent、Model维度聚合输入Token、输出Token、缓存Token。
- 成本估算：根据Token用量和模型单价，估算当前周期内消耗的金额。
- 账户余额：显示当前账号的可用余额，并区分免费额度和付费余额。
- 配额使用率：展示TPM、RPM等配额的使用情况，方便在触限前提前调整。
- 多Profile切换：通过参数指定不同的Profile，查看不同环境或不同账号的用量。
- JSON输出：方便被脚本或其他工具消费，做告警和自动化处理。
- 阈值告警：设置余额或配额使用率的阈值，触发后给出提示。
这些功能单独看都不复杂，组合在一起就很实用。尤其是“按Agent维度聚合”，这是官方控制台默认不提供的视角。你可以直接看到哪个Agent是烧Token大户，然后针对性地优化它的提示词、上下文管理或工具调用逻辑。
3.2 插件的数据来源与工作原理
这里解释一下插件的数据大概从哪里来，方便你理解为什么它的数字偶尔和Web控制台有出入。基于公开实践，这类用量统计插件通常不会自己去解析网络请求日志，而是调用账号体系下对应的用量统计接口，把返回的数据按Profile和Agent维度做聚合。
DSH的用量接口会返回账号下所有Agent调用的计量数据，包括每次请求的Token输入、输出、缓存命中，以及时间戳和模型信息。dsh-usage-stats拿到这些原始数据后，会按你指定的条件进行汇总。比如按Agent聚合时，它会把同一个Agent名称下的所有请求Token加起来；按模型聚合时，则按模型名称分组统计。
知道了这个原理，你就能理解“数据实时性”的问题。用量统计接口本身存在延迟，通常不是精确到秒的实时数据，而是滞后15分钟到1小时。因此插件显示的是一个“近似的当前状态”，适合做趋势判断和预警，不适合做精确的计费对账。如果你看到插件显示余额和官方控制台差了几分钱，不用太紧张，这是统计口径和延迟共同造成的。
3.3 为什么它比“自己写脚本统计”更省心
我也想过自己写个Python脚本，定时调用用量接口，然后输出报表。后来发现没必要，因为要做的事情看起来简单，实际处理起来有不少边角：
- 多个Profile的认证信息管理
- 分页拉取所有Agent的用量数据
- Token成本和余额的计算逻辑，不同模型价格不同，还要考虑缓存Token的折扣
- 输出格式适配终端和JSON，方便阅读和自动化
- 告警逻辑的状态管理，避免每次重复触发
dsh-usage-stats把这些都封装好了。它作为DSH插件，天然能读取当前登录态的Profile配置，不需要我重复管理密钥。我只需要关心怎么使用它，不用关心数据怎么来。
4. 安装与配置：从dshmarket到第一条统计命令
4.1 前置条件：保证DSH登录态正常
dsh-usage-stats是DSH插件，前提是你的DSH已经安装并能正常登录。如果你还没有初始化DSH，或者登录态已经过期，插件拿不到数据，运行时会提示类似dsh web authentication required; reopen the url printed by dsh web.的信息。
DSH的登录方式是通过Web授权完成的。在终端执行dsh web，它会自动打开默认浏览器，跳转到授权页面，你完成登录授权后，CLI就能拿到Token了。如果你是在远程服务器或没有图形界面的机器上操作，可以加--no-open参数禁用自动打开浏览器，命令会打印一个授权URL，复制到本地浏览器打开即可。
我在第一次配置远程开发环境时就踩过这个坑。服务器上没有浏览器，直接执行dsh web会尝试调用系统默认浏览器，结果打不开。后来加上--no-open，把URL复制到本地完成授权，才顺利登录。之后CLI会把Token保存在本地的Profile配置里，下次打开终端直接可用。
4.2 添加插件市场并安装dsh-usage-stats
DSH的插件默认从官方插件市场安装。如果你还没配置过插件市场，可以先执行下面的命令，把dshmarket这个市场添加到当前Profile下：
dsh plugin --profile web add dshmarket这里的web是Profile名称。如果你本地有多个Profile，对应改成你自己的Profile名。添加成功后再搜索和安装插件：
dsh plugin search usage dsh plugin install dsh-usage-stats安装完成后，可以用dsh plugin list确认插件是否已经启用。正常情况下，dsh-usage-stats会出现在插件列表里，并提供一组新的CLI命令。
4.3 快速上手：运行第一条统计命令
安装好之后，不需要额外配置就能先跑一遍最基本的命令，看看效果：
dsh usage这个命令会列出当前Profile下所有Agent的用量摘要，默认输出类似下面的表格：
| Profile | Agent | Token(输入) | Token(输出) | 缓存Token | 成本估算 | 余额 | 配额使用率 |
|---|---|---|---|---|---|---|---|
| web | hermes-agent | 1,204,331 | 186,204 | 92,110 | $6.42 | $42.18 | 38% |
| web | pi-agent | 894,220 | 130,985 | 41,880 | $4.07 | $42.18 | 26% |
| web | doc-reader | 2,301,804 | 54,232 | 1,120,550 | $9.81 | $42.18 | 61% |
一眼就能看出哪个Agent消耗最多。我这边doc-reader是负责解析PDF文档的Agent，缓存Token很高，因为它每次都要读取一个较大的文档切片，上下文里重复内容多，好在缓存Token价格便宜，整体成本可控。
你还可以用参数查看更详细的信息：
dsh usage --detail dsh usage --format json dsh usage --by-agent dsh usage --by-model--format json输出的数据结构方便脚本消费。比如我想快速判断是否需要告警，可以配合jq命令筛选：
dsh usage --format json | jq '.agents[] | select(.balance < 10)'这条命令会把余额低于10的Agent整理出来，一目了然。
4.4 配置刷新间隔与告警阈值
dsh-usage-stats支持通过插件配置调整刷新间隔和告警阈值。执行：
dsh plugin config dsh-usage-stats进入交互式配置界面后，常见的配置项有这些：
refresh_interval：自动刷新间隔，默认可能是300秒。不建议设得太短，因为每次刷新都会请求一次用量接口，频率过高反而消耗资源和配额。low_balance_threshold：余额告警阈值，比如设置为10，表示余额低于10时给出提醒。quota_alert_percent：配额使用率告警阈值，比如80，表示配额使用率超过80%时提醒。display_free_credit：是否单独展示免费额度，建议开启，方便区分免费和付费余额。
我建议把余额告警阈值设成一个你“能接受的最小安全值”，不要设太高。比如你有100美元余额，设成100完全没有意义，每天都会报警；设成10到20比较合理，给自己留出处理时间。配额使用率的告警阈值则要看你的任务类型。如果Agent对实时性要求高，80%可能已经偏晚了，建议设成60%到70%，提前降并发。
5. 数据怎么读：Token、余额和配额的正确理解
5.1 Token构成：输入、输出、缓存
dsh-usage-stats会分别展示输入Token、输出Token和缓存Token，这三个数字对应不同的计费规则，理解它们才能真正看懂数据。
输入Token是每次请求发送给模型的内容，包括系统提示词、历史消息、工具定义、工具返回结果等。输出Token是模型生成的回复。缓存Token是命中了缓存的那部分上下文，价格通常只有正常输入Token的十分之一甚至更低。
我判断一个Agent的上下文策略是否合理，主要看缓存Token占总输入Token的比例。如果缓存Token占比很低，说明这个Agent每次调用都在重复发送大量未命中缓存的内容，要么是系统提示词改得太频繁，要么是上下文管理没有利用缓存机制。如果缓存Token占比很高，成本就会相对可控，因为大部分重复上下文都走了便宜通道。
5.2 余额与免费Token的区别
插件显示的余额字段要理解成“可用余额”，它可能由付费余额和剩余免费额度组成。不同平台对额度的扣减顺序不一样，有的是先扣免费额度，有的是按比例混合扣，如果插件支持单独展示免费额度，建议打开。
我在跑一个长期项目时发现，余额从10美元掉到8美元，但免费Token还显示有几千K，后来查了下文档才知道，那个平台的扣费规则是“免费额度优先，用完了才扣付费余额”。也就是说，只要免费额度还有剩余，付费余额不会变动，但这不代表你的免费额度充足。插件把两者分开后，我才能准确判断还能跑多久。
5.3 配额：TPM和RPM并不等于“剩余Token”
很多新手会把配额当做“还能用多少Token”，这是一个严重的误解。配额指的是速率限制，TPM（Tokens Per Minute）表示每分钟最多可以处理的Token数，RPM（Requests Per Minute）表示每分钟最多可以发起的请求数。
假设你的TPM配额是100万，但你某一次请求就发送了60万Token，那这一分钟你最多只能再发一个类似规模的请求，然后就会触限。Agent开发中，如果你并行跑多个Agent，每个Agent每轮都要发送大量Token，很容易在短时间内把TPM打满。
dsh-usage-stats展示配额使用率，目的就是让你在触限之前提前感知。我一般在配额使用率超过70%时就减少并发数，或者暂停一些非关键任务，等配额窗口刷新后再继续。
5.4 成本归因：找出烧Token最多的Agent
当你有多个Agent时，只看总量没有意义，必须知道每个Agent的用量分布。dsh usage --by-agent按Agent聚合，dsh usage --by-model按模型聚合，这两个视角配合使用，能快速定位成本来源。
我之前有一个很明显的案例：总成本突然翻倍，按Agent一查，发现是某个做网页内容抓取的Agent消耗了约70%的Token。原因是它的工具返回结果没有做截断，每次把整个网页正文塞进上下文，模型还要再次总结，Token自然暴涨。后来我在Agent的提示词和工具逻辑里加了内容摘要步骤，把返回的网页内容压缩后再交给模型，Token成本立刻降了下来。
dsh-usage-stats在这里扮演的角色，就是从数据层面给你一个定位问题的起点。没有这个数据，你很难知道优化应该从哪个Agent下手。
6. 常见问题与排查技巧实录
6.1 登录态失效：重新执行dsh web
如果你在运行插件时看到dsh web authentication required; reopen the url printed by dsh web.，说明本地缓存的登录凭证已经失效。解决办法很简单，重新执行：
dsh web --no-open然后把打印出来的URL复制到浏览器完成授权，再回来执行dsh usage就能正常拉取数据。这个问题在切换网络、Token过期时间较长后经常出现，不用慌张，属于常规流程。
在实际使用中，我还遇到过dsh web: opening the default browser; pass --no-open to disable的输出。这说明DSH默认尝试打开浏览器，如果你是在无图形界面的环境里，记得带上--no-open，否则命令会因为找不到默认浏览器而卡住或报错。
6.2 Token交换失败：403、refresh_token为空
在DSH Web认证流程中，最让人难受的一类报错是Token交换失败。常见的有：
sign-in could not be completed token exchange failed: error sending requesttoken exchange failed: token endpoint returned status 403 forbidden: country, region, or territory not supportedfailed to refresh token: 400 bad request: invalid 'refresh_token': empty string. expected a string with minimum length 1, but got an empty string instead.
第一类error sending request，通常是网络波动或者授权服务临时不可用导致的，可以等几秒重试。第二类403，是认证服务的地区或网络策略限制，和本地网络入口有一定关系，建议换一个网络环境或者确认Profile配置是否正确，再重新走一遍dsh web流程。第三类refresh_token为空，多半是Profile配置里的refresh_token字段丢了或没有正确写入，可以直接删除当前Profile重新登录。
我处理这类问题的心得是：不要试图手动编辑Token字段。DSH的认证信息是通过Web授权流程自动写入的，手动改很容易出错，一旦发现refresh_token异常，最稳妥的方式是重新执行Web授权，让系统重新生成并写入凭证。
6.3 插件显示的数据和官方控制台对不上
如果你发现dsh-usage-stats显示的Token或余额和官方控制台不一致，一般有三个原因。
- 统计延迟：用量接口存在15分钟到1小时不等的延迟，插件拉取的是接口返回的最新数据，官方控制台的图表可能已经做了额外修正。
- 统计口径：官方控制台可能把模型内部思考Token（reasoning token）也计入总量，而插件只解析模型返回的usage字段，两者会存在差异。
- 计费周期：余额字段可能包含未结算的估算值，不同页面的余额显示逻辑不同。
我的建议是：插件数据用于日常监控和趋势判断，最终对账以官方账单为准。如果你发现自己和官方数字差了几美元，先别急着觉得插件有问题，先确认数据延迟和统计口径。
6.4 多Profile和多账号如何管理
DSH支持多Profile，每个Profile对应一套登录态和配置。dsh-usage-stats默认读取当前激活的Profile，如果你想查看其他Profile的数据，可以这样：
dsh usage -p staging dsh usage -p production我自己的开发环境分了三个Profile：dev、staging、production。dev环境额度紧张，staging环境跑集成测试，production环境只跑正式任务。每次要确认某个环境是否还有余额，直接指定Profile即可，不用反复切换。
如果你想把所有Profile的用量汇总到一份报告里，可以循环执行命令，或者看插件是否提供--all-profiles参数。汇总后的数字虽然独立统计，但足以帮你从全局角度判断成本分布。
6.5 与其他DSH插件配合的小技巧
dsh-usage-stats不是银弹，它给出的是用量数据，真正控制成本还得靠Agent本身的优化。在DSH生态里，有几个插件可以和它配合使用：
- 记忆类插件：帮助Agent管理长期记忆，减少重复向模型发送的历史信息，降低Token消耗。通过
dsh-usage-stats观察缓存Token的变化，可以判断记忆插件的命中效果。 - 文档解析插件：读取PDF、Word等文档时，解析结果会进入上下文，一个长文档可能瞬间消耗大量Token。我会先用文档解析插件做一次切片，再用
dsh-usage-stats对比不同切片策略的成本差异。 - Agent评测插件（agent evals）：跑评测集时会进行大量推理，Token消耗特别快。跑评测之前先看一眼余额和配额，能防止评测跑到一半因为触限中断。
我目前的监控方案是写了一个简单的shell脚本，每小时执行一次dsh usage --format json，用jq提取关键字段，追加到一个CSV文件里。这样虽然插件本身不做长期存储，但我自己积累了一份按小时粒度的用量历史，方便事后分析趋势。
7. 我的实际使用心得
用了dsh-usage-stats将近三周，我最直观的感受是“心里有底了”。以前跑Agent测试，最怕突然收到一条欠费通知，说明某个任务已经跑了一部分，然后因为额度问题中断，既浪费时间又浪费Token。现在我会在跑大规模评测之前，先执行一次dsh usage，确认余额充足、配额有余量，再开始跑任务。
有一段时间我只把dsh-usage-stats当做一个“查看器”，想起来才看一眼。后来我把它变成定时任务，每天凌晨跑一次，把汇总数据写入日志，连续记录了一周之后，我明显看出某个Agent的Token消耗在逐渐上升。顺着这个趋势往前排查，发现最近更新的工具调用逻辑里，返回结果没有做长度限制，导致上下文越来越长。这个优化点如果靠感觉去猜，可能很久都不会发现，但有了数据趋势，定位问题快了很多。
最后再分享一个小技巧，适合规模化使用。每个DSH账号的免费额度有限，如果你负责多个账号或团队资源，可以用dsh-usage-stats的JSON输出做一个快速的健康检查：
dsh usage --format json | jq -r '.agents[] | [.profile, .agent_name, .balance, .quota_usage_percent] | @tsv'这条命令会输出一个清爽的表格列，方便你进一步用awk、grep处理，甚至接入到团队的消息机器人里做每日播报。先让数据流动起来，你才能谈得上成本治理。
