dsh-ark-plan-usage

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

• 侧边栏展开：一张用量卡片 —— ⬡ 六边形状态图标、5h 进度条、百分比、已用/总量、窗口重置时间，下方附带 weekly / monthly 小进度条
• 侧边栏收起（轨道模式）：六边形小图标 + 百分比，hover 显示完整信息
• 🟢 <50% 绿色 / 🟡 50–80% 黄色 / 🔴 ≥80% 红色（5h 主条、weekly/monthly 小条、六边形图标统一阈值）
• 服务端 5 分钟内存缓存（和 arkcli 调用节奏一致），点击卡片立即强制刷新；拉取失败时保留旧数据并标注 stale
• SSO 过期一键重登录：卡片错误区出现「重新登录」按钮，点击后 host 拉起 arkcli auth login volc-sso（自动打开浏览器），授权完成自动刷新数据；5 分钟超时、单飞防重复，无需开终端（OAuth 授权本身仍需在浏览器点同意，无法完全静默）
• 零构建：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）

安装

dsh plugin 会转发给 pnpm 并自动把插件写入 profile 的 bundles 列表，所以 pnpm 支持的来源都可以装。任选一种：

# 方式 A：直接从 GitHub 安装（无需发布，推荐）
dsh plugin --profile web add github:Barry-Liu-001/dsh_ark_plan_usage

# 方式 B：从 npm 安装（发布后可用，见下文「发布与分发」）
dsh plugin --profile web add dsh-ark-plan-usage

# 方式 C：本地 tgz 安装（离线 / 审计后安装）
dsh plugin --profile web add ./dsh-ark-plan-usage-0.1.0.tgz

# 方式 D：本地源码目录（插件开发，workspace link）
dsh plugin --profile web add /path/to/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 插槽。

方式 A/B/C 都会把包解包进 profile 的 node_modules，依赖可正常向上解析，无需任何额外操作；只有方式 D（源码 link）需要按文末「开发说明」补一个 @deepseek-ai 软链。

工作原理

浏览器侧边栏卡片
   │  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 }

错误降级：

配置

• 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

发布与分发（维护者）

插件零构建、零运行时 dependencies（DSH 宿主能力全部走 optional peerDependencies），所以三种分发方式都不需要编译步骤：

# 1) 打 tgz（产物 dsh-ark-plan-usage-<version>.tgz，只含 package.json files 白名单里的 6 个文件）
npm pack
#   → 附到 GitHub Release，用户用「方式 C」安装；也可直接发给同事

# 2) 发布到 npm（公共 registry，所有人可装）
npm login --registry https://registry.npmjs.org
npm publish --registry https://registry.npmjs.org
#   → 用户用「方式 B」：dsh plugin --profile web add dsh-ark-plan-usage

# 3) 什么都不用发：代码推到 GitHub 后，用户直接用「方式 A」从 git 安装
#   （本插件无 prepare 构建脚本，git 安装不会触发 pnpm 的 allowBuilds 拦截）

发布前检查清单：

• [ ] package.json 的 version 已按 semver bump（npm 不允许覆盖已发布版本）
• [ ] npm pack --dry-run 确认 tarball 内容（应只有 LICENSE / README.md / client.js / cordis.patch.yml / index.js / package.json，不含 node_modules）
• [ ] 改动已合入 main 并推送到 GitHub（方式 A 始终装默认分支最新代码）
• [ ] 发布后在 GitHub 建同名 tag / Release（如 v0.1.0），tgz 可挂在 Release 资产里

文件说明