给编程智能体写插件：余额胶囊、任务面板与番茄钟实战指南

先说个真实场景。上个月我用 dsh——我日常主力用的 DeepSeek 编程智能体，社区里也有人把它简写成 DSH——跑一个中型后端重构任务。原以为一两个小时就能收工，结果凌晨三点它还在终端里刷日志：一会儿往项目里塞新文件，一会儿又把代码回退。我最难受的是，自己完全不知道它到底烧了多少 token、接下来要走哪几步、这个长任务会不会陷入空转循环。那晚之后，我下定决心要给这个编程智能体补齐三块能力，这就是后面三个插件的由来：余额胶囊、任务面板、番茄钟。

这三个插件不是啥惊天动地的黑科技。余额胶囊干的是成本核算和预算告警；任务面板让智能体自己在会话里维护一份可渲染的待办清单；番茄钟则像一个节拍器，定时打断超长会话，逼着智能体停下来总结、清理上下文、重新聚焦。整套东西我在本地跑了两周，现在基本每天都开着，中间踩了不少坑，也总结了一些设计经验，这篇就当一个实操记录写出来。适合谁参考？一是玩 AI 编程但老担心账单的人，二是被多步任务搞晕的人，三是对编程智能体插件机制感兴趣、想自己动手扩展的开发者。

1. 为什么给编程智能体写插件：三个让我动手的痛点

1.1 余额胶囊：对 token 消耗的失控感

先说账单。用编程智能体跑真实项目，本质上是在用 API 调用换时间。一次重构往往几十次循环，每次循环里 agent 要读文件、写代码、跑测试，每步都可能触发多次模型调用。默认的日志只会告诉你“调用成功与否”，消费统计要么打在 provider 后台，要么沉在一堆 JSON 输出里，根本没法实时感知。

我真正想要的其实就一句话：在每个关键节点告诉我，这轮对话花掉了多少钱、离我设定的预算还有多少。不是那种“总计 XX 元”的月结账单，而是边花边记、可拆到会话维度、能按工具调用逐条追溯的明细。余额胶囊就是干这件事的。它挂在每个 tool_call 的前后，解析 response 里的 usage 字段，按模型单价换算成本，再把结果渲染成终端里的一张小表。

你可能会说，这功能很多平台自带，为什么非要写插件？因为编程智能体是长会话，一个会话可能横跨几个小时。平台后台的指标是事后汇总，等看到账单时已经来不及调整策略了。本地插件能做的，是在一次调用刚结束时给出告警，比如“本次会话已用 82% 预算，建议切换到缓存模式或减少测试轮数”。这种实时反馈对成本控制是质变。

1.2 任务面板：多步任务里缺少外部记忆

编程智能体跑多步任务，最大的隐患不是单个步骤做错，而是做到一半忘了整体规划。比如我让它“重构订单模块，同时兼容旧的 REST 接口”，它可能在改了第五个文件之后就丢掉了“兼容旧接口”这个关键约束，开始埋头重写数据模型。

人脑记不住，模型也会忘。而智能体一旦进入长上下文，历史消息被截断或压缩，“当前目标”会越来越模糊。传统思路是把任务写在系统提示词里，但系统提示词是静态的，改一次就要重新起会话，不灵活。更麻烦的是，agent 内部可能有自己生成的待办列表，但那个列表藏在对话流里，人没法一目了然看到进度。

任务面板插件的思路，是给智能体提供一个“外部记忆”：会话期间维护一张结构化的任务表，agent 通过工具调用去增删改查，终端实时渲染成表格。任务状态机只有四个状态：todo、in_progress、done、blocked。任务之间允许声明依赖关系，比如“B 依赖 A 完成后才能开始”。这样即便上下文被清理，agent 只要查一次任务面板，就能恢复全局认知。

1.3 番茄钟：给长会话装一个节拍器

第三个插件听起来最不像技术产品——番茄钟不是给人用的吗？编程智能体要番茄钟干什么？我的初衷不是管理人的专注度，而是主动干预 agent 的疯狂循环。

长会话跑久了，agent 容易陷入“局部收敛”：反复改同一段代码，却不去看整体状态。因为没有外部时钟，它会在一棵树上吊死。番茄钟插件以 25 分钟为周期发信号，提醒 agent 三个事情：第一，把当前进度固化到任务面板；第二，清理会话里的临时噪音；第三，向用户输出一次简短小结，确认方向没跑偏。

本质上，这是一个节拍器，也是一个“强制反思点”。它把人从“不知道它在干嘛”的被动状态里拽出来，变成每隔一段时间就有一次主动汇报的协作模式。后面你还会看到，它配合任务面板使用，效果比单独跑好得多。

2. 插件机制与整体架构设计

2.1 编程智能体插件系统的基础约定

dsh 不是某个封闭平台，它的插件生态走的是轻量约定。要写插件，核心是理解三件事：生命周期钩子、工具注册、渲染扩展点。

生命周期钩子定义插件在什么时候执行。我写的这三个插件主要依赖这几个事件：on_session_start（会话开始时触发，常用来初始化状态）、before_tool_call（工具调用前触发，余额胶囊在这里记录当前余额快照）、after_tool_call（工具调用后触发，余额胶囊在这里做成本累计，任务面板在这里检查任务状态，番茄钟也在这里判断是否需要提醒）、on_agent_message（agent 输出消息时触发，可以往消息里附加插件渲染结果）。

工具注册解决的是“agent 怎么知道插件的存在”。dsh 支持把插件暴露成一组工具，agent 可以像调用外部函数一样调用它们。比如task.add、task.update、balance.query、pomodoro.status。这些工具不需要写进系统提示词的长文本里，而是通过工具的 schema 描述告诉 agent，在 agent 决策时按需选择。

渲染扩展点解决的是“人怎么看结果”。终端界面不能像网页那样随便画控件，所以我们约定：插件可以在 agent 的消息流里插入一种特殊的标记行，例如[[plugin:task_panel]]，渲染器扫描到这一行就把它替换成 Rich 表格或面板。这样插件逻辑和界面渲染就彻底解耦了，想在纯 CLI 看就在终端渲染，想接入 Web UI 也只要改一个渲染器。

2.2 三个插件的通用抽象：状态、事件、渲染

三个插件虽然功能不同，但共享一套抽象：状态仓库、事件总线、渲染组件。

状态仓库负责持久化。余额胶囊要存累计成本，任务面板要存任务列表，番茄钟要存时间段状态。我统一用一个 SQLite 文件，路径放在~/.dsh/plugins/<plugin_name>/state.db。为什么不用 JSON？因为编程智能体可能并发触发工具调用，比如 agent 同时发起一个文件读取和一次测试执行，如果都去写同一个 JSON，容易出现互相覆盖的情况。SQLite 自带事务，写冲突时能优雅处理，还能顺带做增量更新和查询。

事件总线是所有插件接收 agent 行为的通道。我们不希望每个插件都自己抓日志、解析终端输出，那太脆了。所以 dsh 在生命周期钩子的基础上，维护了一条事件队列。before_tool_call和after_tool_call会携带工具名、参数、返回结果，插件只需订阅自己关心的事件。事件总线还能处理“同一时刻多个插件都关心同一事件”的情况，避免插件之间互相干扰。

渲染组件则是一个纯函数式的存在：输入状态数据，输出终端可渲染的结构。余额胶囊的输出是一张成本表，任务面板的输出是 Markdown 风格的任务清单，番茄钟的输出是一个倒计时条。渲染组件不持有状态，所有数据通过查询接口从状态仓库拿。好处是状态可以被多个渲染器消费，比如我后续想把任务面板同步到本地网页，只需要加一个 HTTP 渲染端点，不需要改任务逻辑。

2.3 技术选型：为什么坚持轻量级

写插件时我一度想得很宏大：要不要上事件驱动架构、消息队列、WebSocket 推送？冷静下来之后全部砍掉了。原因很简单，插件跑在开发者本地，用户只关心三件事：装得上、跑得稳、看得懂。

最终技术栈是 Python plus 少量依赖。Python 是 dsh 生态的主要语言，插件市场里大部分插件也是 Python 写的，便于复用。第三方依赖只用两个：Pydantic 做配置和数据结构校验，Rich 做终端渲染。SQLite 用标准库，网络请求走标准库urllib或者已有的 HTTP client。加依赖越多，未来升级 dsh 主程序时插件越容易兼容性崩溃。

另一个设计决策是“少碰主进程”。插件只通过钩子和工具接口与主程序交互，不直接改 dsh 的内部数据结构。这样做有两个好处：一是插件写坏了不至于把智能体搞崩，二是可以把插件独立调试，单测时直接喂模拟事件即可。我在本地开发时，几乎都是开着一个小脚本模拟 tool_call 事件，验证输出格式，然后再上真机跑。

3. 三个插件的实现细节与实操要点

3.1 余额胶囊实现：成本核算公式与阈值告警

余额胶囊在计算成本前，需要先明确模型单价。以我当时用的模型报价为例，假设输入缓存命中每百万 token 是 0.014 美元，输入缓存未命中每百万 token 是 0.028 美元，输出每百万 token 是 0.042 美元。实际项目里价格会随时间和渠道变动，我把它做成配置文件，避免硬编码。

每次 tool_call 结束后，余额胶囊从 response.usage 字段里取三个数字：prompt_cache_hit_tokens、prompt_cache_miss_tokens、completion_tokens。成本计算的核心代码如下：

# cost.py price_in = {"cache_hit": 0.014, "cache_miss": 0.028} price_out = 0.042 def calc_cost(usage: dict) -> float: hit = usage.get("prompt_cache_hit_tokens", 0) miss = usage.get("prompt_cache_miss_tokens", 0) out = usage.get("completion_tokens", 0) return ( hit / 1_000_000 * price_in["cache_hit"] + miss / 1_000_000 * price_in["cache_miss"] + out / 1_000_000 * price_out )

这里有个容易踩的坑：不是所有兼容接口都会返回缓存命中拆分字段。有些接口只有prompt_tokens和completion_tokens。这种情况下不要硬拆，直接用prompt_tokens乘以一个偏保守的单价，宁可在数值上高估一点，也不要低估。我在插件里自动检测字段，如果缺失缓存字段，就退回到普通单价估算，并在日志里打一个“估算模式”的标记。

阈值告警我做成“三级预警”：用量达到预算的 40% 时提醒一次，70% 时再次提醒，90% 时给红色告警并建议 agent 暂停长任务。判断时机放在after_tool_call，因为这个时间点能拿到完整的 usage 数据。为了避免每次工具调用都往上下文塞成本数据，我让插件只把告警事件发给主进程，低于阈值的明细只更新本地 SQLite，不显示在对话记录里。

3.2 任务面板实现：任务状态机与证据绑定

任务面板的存储模型设计得比余额胶囊复杂一些。它需要支持任务的增、删、改、查，还要处理任务依赖。我建了一张表：

CREATE TABLE tasks ( id INTEGER PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'todo' CHECK(status IN ('todo', 'in_progress', 'done', 'blocked')), depends_on TEXT, evidence TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP, updated_at TEXT DEFAULT CURRENT_TIMESTAMP );

depends_on字段存的是任务 ID 或 ID 列表的 JSON 字符串。为什么用 JSON 字符串而不是关联表？因为 agent 在一条工具调用里通常只需要一次性传入全部依赖，JSON 字符串足够轻量，查询时也方便直接反序列化。等以后任务数量级上去了再拆关联表也不迟。

agent 通过工具命令操作面板，几个核心命令长这样：

• task.add(title, depends_on?)：新建任务，返回任务 ID。
• task.start(task_id)：把任务从 todo 切到 in_progress。
• task.block(task_id, reason)：标记阻塞，reason 会写进任务详情。
• task.done(task_id, evidence)：完成任务，evidence 必须传工具调用 ID 或者外部可验证的改动描述。

最后的task.done极其关键。如果不强制传证据，性格奔放的 agent 会把任务全部标成 done，但它实际上可能什么都没写。我在插件里约定：证据要么是能对应到after_tool_call里的工具调用 ID，要么是一段可核验的说明，比如“测试 test_payment.py 通过，输出请见日志抽取片段”。渲染任务表时，带有证据的任务会显示“已核”，没有证据的显示“待核”。这一条我后面在踩坑部分会展开讲。

任务面板的渲染风格是表格，每行是一个任务，状态用不同颜色标记。表中的“依赖”列会展示当前任务被哪些任务卡住，这样 agent 自己查看面板时，能快速判断下一步该解除哪个阻塞。

3.3 番茄钟实现：给 agent 一个不会骗人的节拍器

番茄钟的实现比前两个都要轻。它本质上是一个状态计数器和两个工具：pomodoro.start、pomodoro.status。

我在插件里维护一个(start_time, duration_minutes)状态。after_tool_call钩子里检查当前时间是否已经超过 start_time + duration。如果是，就把事件发给主进程，主进程会做三件事：追一条系统提示让 agent 输出中间小结、压缩最近几轮工具输出、提醒 agent 查一次任务面板。然后重置定时器，进入休息阶段。

休息阶段默认 5 分钟。这段时间 agent 不会被打断，但会收到“可以放慢节奏”的信号。休息结束后，自动开始下一轮工作计时。

有人会问，这个计时器会不会让 agent 在上下文里反复看到倒计时，导致 token 浪费？我一开始也担心这个，所以番茄钟不会每次都往对话里塞剩余时间。它的状态只存在插件侧，只有触发事件时才向主进程发一次信号。agent 主动调用pomodoro.status才返回剩余时间，不调用就完全不知道。这样把上下文噪音压到最低。

番茄钟还有一个隐藏作用：给“是否继续跑”提供了一个客观判据。如果连续三个番茄钟周期，agent 一直在同一个任务上打转，任务面板里该任务没有任何状态推进，插件就会给主进程发一条“疑似空转”的建议，让 agent 停下来汇报，或者让人介入。

4. 插件安装、配置与效果验收

4.1 插件市场与本地安装流程

dsh 的插件市场做得比较克制，只提供索引，不强制托管二进制。安装命令很简单：

dsh plugin install balance-capsule dsh plugin install task-panel dsh plugin install pomodoro

如果你在离线环境或公司内网，也可以直接把插件目录放到~/.dsh/plugins/下，然后执行dsh plugin scan让主进程重新扫描。这个机制对本地开发者很友好，调试插件时不用反复走打包、上传、安装的流程，改完代码直接重启会话就能生效。

每种插件装好后，会在~/.dsh/config.yaml里增加一块配置。我的完整配置长这样：

plugins: balance_capsule: budget_usd: 2.0 price_in_cache_hit: 0.014 price_in_cache_miss: 0.028 price_out: 0.042 warn_levels: [40, 70, 90] task_panel: storage: sqlite db_path: "~/.dsh/plugins/task_panel/state.db" pomodoro: work_minutes: 25 break_minutes: 5 enable_auto_checkin: true

注意balance_capsule.budget_usd只设了 2 美元，是因为日常调试任务通常 10 分钟就能跑完，设置太高反而失去告警意义。真正跑长任务时我会临时把预算调到 10 美元甚至更高。配置项支持热更新，改完不需要重启 dsh，下个工具调用会自动读取新值。

4.2 给智能体的系统提示词补充接入逻辑

插件装好了，智能体并不知道怎么用。如果系统提示词里没有插件相关说明，agent 大概率只会用默认的文件工具和代码执行工具，不会主动碰余额胶囊和任务面板。

我的做法是在系统提示词里增加一段“可用插件协议”：

你的环境里注册了三个特殊工具：balance（查询会话花费与剩余预算）、task（管理任务面板）、pomodoro（查询/启动工作计时）。在执行超过 5 步的任务前，必须先调用 task.add 创建任务清单；每个工具调用完成后，若任务有实质推进，必须调用 task.done 并附上证据；每隔一段时间主动调用一次 balance，确保花费不超过预算；若 pomodoro 状态为工作期结束，先输出一次中间小结再继续。

这段提示不需要很长，但要给 agent 明确的行动触发条件。我试过更短的版本：“你可以使用插件”，结果 agent 一次都没用过，因为模型不知道这些工具跟当前任务有什么关系。后来改成“超过 5 步先建任务清单”这种带场景的指令，使用率才上来。

4.3 实测效果：一次后端重构任务的完整表现

为了验收，我拿一个真实的爬虫任务管理器做重构试验：原来用 requests 同步抓页面，改成 httpx 异步并发抓取，同时保持旧接口兼容。整个任务我预估人工要做 1 到 2 小时，agent 独立跑的话，最怕它中途方向跑偏。

实际操作时，我在会话开始前给 agent 发了启动指令：“用任务面板规划这次重构，每完成一个阶段更新状态，别超过 1 美元预算。”agent 的行为让我意外地正常：

它先调task.add建了四个任务：梳理现有接口、写异步客户端、改造调用方、跑兼容性测试。紧接着调balance.query确认初始预算。重构过程中，每次完成一个文件修改，agent 都会调task.done并附上一个工具调用 ID。中途我特意打断它问“现在进度到哪了”，它直接调用task.list然后输出任务表格，清楚显示第三项任务进行中、第一项已完成。

番茄钟在这里也发挥了作用。第 25 分钟时插件触发中间小结，agent 输出了一段总结：“已完成接口梳理，异步客户端代码已生成但未接入调用方，下一步需要处理旧接口兼容。”我看了之后立刻发现它的方向偏了——它打算先重写调用方，但这可能破坏兼容性。我及时纠正，让它先补兼容层，避免了一次潜在返工。

跑完后我看余额面板，整个重构总共花了 0.87 美元，比人工成本低得多，更关键的是每个步骤都有据可查。没有这三个插件的时候，同样任务跑到一半很容易变成“黑盒操作”，现在至少成本和进度都透明了。

5. 踩坑记录与常见问题排查

5.1 余额统计偏差：缓存命中与并发请求

余额胶囊上线第一天，我就发现统计数字和平台后台差了 15% 左右。排查下来有两个原因。

第一个原因是接口没有返回完整的缓存拆分字段。平台侧统计口径可能是按缓存命中和未命中分开计费的，但模型返回的 usage 里只有prompt_tokens。我跟随的逻辑是：如果连prompt_cache_hit_tokens都没有，就不要强行区分，直接用prompt_tokens按缓存未命中单价算。这样会高估一点，但至少不会让用户误以为更便宜。

第二个原因是并发请求导致时序错乱。agent 有时会同时发多个工具调用，响应回来的顺序与发出顺序不一致，如果我按响应到达先后逐一累计，会把一次调用的成本记到另一次调用头上。解决办法是给每次 tool_call 生成一个自增 ID，HTTP 响应到达时带着这个 ID，余额插件按照 ID 顺序而不是到达顺序更新累计值。这个强制顺序其实不需要考虑机器性能，主要是为了避免统计错乱。

5.2 任务面板出现“僵尸任务”：状态机和 LLM 的幻觉

任务面板最大的坑，是 agent 会把任务标记成 done，但实际根本没做。我最早遇到这个现象时差点以为是插件 bug，后来才发现是模型在“自我安慰”。它可能觉得某个改动已经在某段代码里包含，于是任务就完成了，实际上那段代码根本没写。

解决办法就是我前面说的证据绑定。task.done现在强制要求evidence参数。我给 agent 的系统提示词加了一条硬性规则：“任务必须能回溯到具体工具调用；一次工具调用的整改，比如改了文件、跑了测试，才算是有效证据。”如果证据缺失，任务状态会自动打回 in_progress，而不是 done。

渲染任务表时，我也会把“无证据的完成”高亮出来。人在终端扫一眼就知道哪些任务需要复核。这条规则看起来很简单，但极大提升了任务的真实性——我甚至在另一组实验里对比过，没有证据绑定时 agent 的“假完成率”能到 30% 以上，加上之后基本降到了个位数。

5.3 番茄钟误伤长任务：定时刷新导致上下文膨胀

番茄钟一度让我很纠结。它确实能打断空转，但也会在几十行上下文里反复插入提醒，把本已紧张的长上下文塞得更满。

我最初的版本是在每次工作期结束时间点直接往对话流里加一句“你的 25 分钟工作期已结束，请输出小结”。听起来没问题，实际跑下来发现，agent 每次开启新一轮工作期都会把历史提示都纳入注意力，上下文越滚越大。一小时之后就明显感觉到后续对话变“迟钝”了。

优化方式是让插件不再往对话记录里写完整提醒，而是只推一个极小的系统事件：状态标记为“需要检查”，主进程看到标记后，先做一次轻量上下文压缩，再把“建议输出小结”的消息发出去。同时压缩的过程中保留任务面板的当前快照，避免 agent 丢失目标。这样番茄钟就不再是“在对话里刷屏”，而是一个安静的调度器。

5.4 插件常见问题速查表

这个表是我在实际使用中沉淀出来的，不一定覆盖所有环境，但它至少解决了 80% 的“看起来是插件问题，实际是用法问题”的案例。

最后再分享一点个人体会

三个插件跑通之后，我最大的感受是，给编程智能体做扩展，真正难的不是写代码，而是想清楚“agent 和人之间怎么分工”。余额胶囊、任务面板、番茄钟本质上都是一层“外部记忆”：一个记得花销，一个记得计划，一个记得时间。它们不负责替代模型的推理能力，只是把那些容易被遗忘、被忽略、被污染的边界信息，用结构化的方式保存下来。

这套插件后续还可以往几个方向扩展：比如把余额胶囊改成按项目维度做成本分摊，或者在任务面板里接入外部项目管理工具的双向同步，又或者让番茄钟在休息阶段自动触发一次代码格式化和静态检查。我在实际使用中发现，最值得投入的方向反而是“证据链”，让每一次任务完成都有可回溯的上下文，这样 agent 的产出才真正经得起推敲。

如果有读者也想给自己的编程智能体写插件，我的建议是从余额胶囊开始，因为它的逻辑最简单、收益最直观。把一次 tool_call 的 hook 跑通，后面再写任务面板和番茄钟都会有顺手的感觉。踩过几次坑之后，你会对这个智能体的行为边界有更清晰的认识——知道什么时候该放手让它跑，什么时候该把它按住，这比任何插件都重要。