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/ 目錄，請確保該目錄有讀寫權限。