dsh-toolkit：DSH Web 端 Bundle（图片生成与 Token 用量面板）

前言¶

DeepSeek Harness (DSH) 采用了插件化架构。在 Web 端开发智能体时，往往需要直接生成图片或追踪多轮对话的成本。dsh-toolkit 是一个 DSH Web Bundle，把图片生成面板与 Token 用量统计面板整合在一起，通过插件 Manager 安装后即可在侧边栏使用。

组件概览¶

该 Bundle 包含两个独立组件：

• image-gen（侧边栏面板 order 49）：提供图片生成工具与面板，支持文生图、图生图、编辑，调用 OpenAI 兼容接口，并管理图库与提示词。
• token-usage（侧边栏面板 order 50）：统计全部会话（含 subagent）的 Token 消耗与成本，包含近一年活跃度热力图。

两个组件可单独启用，面板 Key 不同，路由前缀也不同。

安装与启用¶

前置要求¶

• DSH 版本 0.1.7 及以上。
• 运行环境为 DSH Web（client.platform: web）。

安装方式¶

在 profile 的 package.json 中声明依赖，然后使用 plugin_manager 加载：

1. 在 profile 的 package.json 中声明依赖：

    // ~/.dsh/profiles/<profile>/package.json
    {
      "dependencies": {
        "dsh-toolkit": "^0.2.0"
      }
    }

2. 执行安装命令：

    plugin_manager install_bundle dsh-toolkit

或者重启 DSH 使其自动加载。

本地开发调试¶

如需本地调试，可在 package.json 中使用本地 link：

"dependencies": {
  "dsh-toolkit": "link:/absolute/path/to/dsh-toolkit"
}

注意：remove_bundle 会从 profile 的 package.json 中一并删除声明，重新安装前需手动加回。

核心功能¶

图片生成¶

1. 工具调用¶

在 Agent 代码中调用 generate_image 工具。

函数签名：

generate_image(prompt, size, count, image)

参数说明：

返回：
返回 ok、model、count、size、imageUrls（约 24 小时有效）、imageUrl（首张）、files（本地落盘路径）。部分失败时附 partial。

2. 侧边栏面板操作¶

1. 打开侧边栏 「图片生成」→「设置」。
2. 点 「+ 添加模型」，填写 API 地址、模型 ID（可点击「获取可用模型」探测）和 API 密钥。
3. 点 「加入目录」，在 「默认模型」 下拉中选中它。
4. 在 「文生图」 或 「图生图」 区域输入提示词或上传参考图，点击生成。

Token 用量与成本¶

该组件统计 DSH 全部会话（含 subagent）的 Token 消耗与成本，数据来自会话事件流，不额外埋点。

面板功能¶

• 数据概览：顶部显示真实消耗 Tokens 总量、总请求数、总成本。时间范围可切 今天、7 天、30 天、90 天、全部 或自定义。成本货币可切 $ 美元 / ¥ 人民币。主数据 15 秒轮询，支持手动刷新。
• 指标卡：显示新增输入、输出、缓存创建、缓存命中、推理、缓存命中率（带进度条）。
• 活跃度：近一年按天的热力图，按当日请求数着色。
• 模型分布：展示模型 / 请求 / 输入 / 输出 / 缓存读 / 缓存写 / 总量 / 成本 / 占比。
• 使用趋势：双 Y 轴折线图，左 Token、右成本，各指标独立画线。
• 请求查看：按会话聚合，支持按 全部来源 / 主会话 / 子会话 过滤，按标题 / ID / 路径搜索。点行可展开到单次请求明细。
• 计价明细：可增改删价目、同步 models.dev、设置汇率。

配置与环境变量¶

插件运行时数据默认收在 $DSH_HOME/dsh-toolkit/ 下（本机默认即 ~/.dsh/dsh-toolkit/）。

主要环境变量：

数据落地¶

插件运行时数据默认收在 $DSH_HOME/dsh-toolkit/ 下：

• $DSH_HOME/dsh-toolkit/images/：生成图统一目录。
• $DSH_HOME/dsh-toolkit/favorites/：收藏图（与 images/ 同级）。
• $DSH_HOME/dsh-toolkit/config.json：模型目录配置。
• $DSH_HOME/dsh-toolkit/library.json：提示词库。
• $DSH_HOME/dsh-toolkit/usage.jsonl：图片生成计费记录。
• $DSH_HOME/dsh-toolkit/token-usage/pricing.json：用户价目 + models.dev 同步结果。

注意事项¶

• 插件不绑定任何服务商，模型目录需自行添加。
• 插件许可证为 MIT。
• 数据落地在 $DSH_HOME/dsh-toolkit/ 目录，请确保该目录有读写权限。