dsh-ark-plan-usage

Readme

# 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 支持的来源都可以装。任选一种：

```sh
# 方式 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 }
```

错误降级：

| 场景 | 表现 |
|------|------|
| 未安装 / 找不到 arkcli | 卡片红色提示「未找到 arkcli，请先安装并登录」 |
| SSO 凭证过期（refresh_token 失效） | 提示登录已过期并显示「重新登录」按钮（host 解析 arkcli stderr 里的结构化 JSON 错误并分类为 `arkcli-auth`）；点按钮即一键重登录 |
| 一键重登录中 / 失败 | 浏览器授权期间显示「正在打开浏览器…」spinner；5 分钟超时或失败时给出提示，可重试或回退终端 `arkcli auth login volc-sso` |
| 其他 arkcli 失败（未订阅 / 后端错误） | 展示 arkcli 返回的原始错误信息（单行裁剪） |
| 调用超时 | 旧数据显示 `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 目录树下的插件生效）。本地开发时补一个软链即可：

```sh
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`。

## 卸载

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

## 发布与分发（维护者）

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

```sh
# 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 资产里

## 文件说明

| 文件 | 作用 |
|------|------|
| `index.js` | Node 端 Typert Remote 服务：arkcli 用量调用、5 分钟缓存、错误分类降级、一键重登录（spawn `auth login volc-sso`） |
| `client.js` | 浏览器端 bundle：注册 `sidebar.footer.action` 插槽 UI（用量卡片 + 「重新登录」按钮）与 RPC 调用 |
| `cordis.patch.yml` | 向 Loader 树插入本插件的 Node 条目 |
| `package.json` | 插件清单（`dsh.bundle.patch` + `dsh.client`） |