dsh-ark-plan-usage

DeepSeek Harness (DSH) 侧边栏插件：在 Web UI 左侧边栏底部实时展示 火山方舟 Agent Plan 用量（5h / weekly / monthly），数据来自本机 arkcli，与 ark-5h-prompt 终端提示符挂件 同源。

• 侧边栏展开：一张用量卡片 —— ⬡ 六边形状态图标、5h 进度条、百分比、已用/总量、窗口重置时间，下方附带 weekly / monthly 小进度条
• 侧边栏收起（轨道模式）：六边形小图标 + 百分比，hover 显示完整信息
• 🟢 <30% 绿色 / 🟡 30–70% 黄色 / 🔴 ≥70% 红色（与终端挂件阈值一致）
• 服务端 5 分钟内存缓存（和 arkcli 调用节奏一致），点击卡片立即强制刷新；拉取失败时保留旧数据并标注 stale
• 零构建：Node 端是普通 ESM，浏览器端是手写的 client factory 经典脚本（React 由 DSH shell 注入）

前置条件

• 已安装 arkcli 并登录（arkcli auth status 为 logged_in: true），且当前 profile 持有 Agent Plan 订阅
• DSH 0.1.1-rc.x（Web profile）

安装

在仓库目录下把插件加入 web profile（dsh plugin 会转发给 pnpm，并自动写入 profile 的 bundles 列表）：

dsh plugin --profile web add /Users/bytedance/workspace/ark-5h-prompt/dsh-ark-plan-usage

然后重启 DSH Web（dsh web 或重新打开 DeepSeek Harness.app 会话），侧边栏底部即出现用量卡片。

插件通过 cordis.patch.yml 向 Loader 树插入 Node 服务（arkPlanUsage Typert Remote），浏览器 bundle 由 package.json 的 dsh.client + exports["./client"] 自动发现并挂到 sidebar.footer.action 插槽。

工作原理

浏览器侧边栏卡片
   │  ctx.remote.arkPlanUsage.getUsage()   (Typert RPC, /api/arkPlanUsage/getUsage)
   ▼
Node 端 ArkPlanUsageService（dsh-ark-plan-usage/index.js）
   │  缓存有效（<5 分钟）→ 直接返回
   │  缓存过期 → spawn `arkcli usage balance --type plan --format json`（20s 超时）
   ▼
解析 JSON → 裁剪为 viewer + item(periods) → 返回 { ok, viewer, item, fetchedAt, stale }

错误降级：

场景	表现
未安装 / 找不到 arkcli	卡片红色提示「未找到 arkcli，请先安装并登录」
arkcli 未登录 / 无订阅	「arkcli 查询失败（未登录或未订阅 Agent Plan）」
调用超时	旧数据显示 stale；无旧数据时提示超时
刷新失败	保留屏幕上的旧数据

配置

• ARK_PLAN_USAGE_ARKCLI（或 ARKCLI_BIN）环境变量：自定义 arkcli 可执行文件路径。默认依次探测 /opt/homebrew/bin/arkcli、/usr/local/bin/arkcli、~/.local/bin/arkcli、/usr/bin/arkcli，最后回退到 PATH 中的 arkcli。

开发说明（workspace link 方式）

以本地目录 dsh plugin add /path/to/dsh-ark-plan-usage 安装时，pnpm 用软链指向源码目录，Node 从源码目录向上解析不到 DSH 的依赖闭包（DSH 在 ~/.dsh/profiles/node_modules 维护的符号链接兜底只对 profile 目录树下的插件生效）。本地开发时补一个软链即可：

mkdir -p node_modules
ln -sfn ~/.dsh/profiles/node_modules/@deepseek-ai node_modules/@deepseek-ai

以 tgz 形式安装（dsh plugin add ./dsh-ark-plan-usage-0.1.0.tgz，文件会解包到 profile 的 node_modules 里）则无需任何额外操作。

改 client.js 后刷新浏览器即可（bundle 以 no-cache 提供）；改 index.js / cordis.patch.yml 后需要重启 dsh web。

卸载

dsh plugin --profile web remove dsh-ark-plan-usage

文件说明

文件	作用
index.js	Node 端 Typert Remote 服务：arkcli 调用、缓存、错误降级
client.js	浏览器端 bundle：注册 sidebar.footer.action 插槽 UI + RPC 调用
cordis.patch.yml	向 Loader 树插入本插件的 Node 条目
package.json	插件清单（dsh.bundle.patch + dsh.client）