前言¶
DeepSeek Harness (DSH) 是一个插件化平台，开发者通常通过本地命令行工具 arkcli 查看火山方舟的 Agent Plan 用量。本插件在 DSH 的 Web UI 左侧边栏底部添加了一张可视化卡片，直接从本机 arkcli 获取数据并展示用量情况，避免频繁切换终端。
插件概览¶
- 名称：
dsh-ark-plan-usage - 维护者：Barry-Liu-001
- 许可证：MIT
- 核心功能：在侧边栏实时展示 5h/周/月 用量，支持展开/收起（轨道模式），提供颜色编码和一键重登录。
前置条件¶
在安装前需满足以下条件：
- DSH 版本：0.1.1-rc.x（Web profile）。
- arkcli 状态：已安装
arkcli并登录（arkcli auth status返回logged_in: true）。 - 订阅权限：当前 DSH profile 持有 Agent Plan 订阅。
安装与启用¶
通过 DSH 的插件管理命令安装：
dsh plugin --profile web add github:Barry-Liu-001/dsh_ark_plan_usage
安装完成后，重启 DSH Web（dsh web），在左侧边栏底部即可看到用量卡片。
功能说明¶
- 实时展示：卡片显示 5 小时总量的进度条、百分比、已用/总量及重置时间，下方附带周/月用量小进度条。
- 轨道模式：
- 展开：显示完整信息（图标、进度条、数据）。
- 收起：仅显示六边形小图标和百分比，鼠标悬停显示完整信息。 - 颜色编码：
- 绿色：< 50%
- 黄色：50% - 80%
- 红色：≥ 80%
（主条、周/月条、图标统一阈值） - 数据缓存：服务端采用 5 分钟内存缓存，与
arkcli调用节奏一致。点击卡片可强制刷新。拉取失败时保留旧数据并标注stale。 - SSO 凭证处理：当 SSO 凭证过期时，卡片错误区会出现「重新登录」按钮。点击后 host 会自动执行
arkcli auth login volc-sso打开浏览器进行授权，授权完成后自动刷新数据。
工作原理¶
插件通过 cordis.patch.yml 向 Loader 树插入 Node 服务（arkPlanUsage Typert Remote），浏览器端通过 RPC 调用该服务。
数据获取流程如下：
- 浏览器侧边栏卡片调用
ctx.remote.arkPlanUsage.getUsage()。 - Node 端
ArkPlanUsageService检查缓存：
- 若缓存有效（< 5 分钟），直接返回。
- 若缓存过期，执行arkcli usage balance --type plan --format json（超时 20 秒）。 - 解析 JSON 并返回结果。
错误处理场景包括：未找到 arkcli、SSO 过期、调用超时等，均会在界面上给出相应提示或操作入口。
配置与开发¶
环境变量¶
若 arkcli 不在默认路径（/opt/homebrew/bin/arkcli、/usr/local/bin/arkcli、~/.local/bin/arkcli、/usr/bin/arkcli），可通过环境变量指定：
export ARK_PLAN_USAGE_ARKCLI=/path/to/arkcli
# 或
export ARKCLI_BIN=/path/to/arkcli
开发模式¶
插件零构建，依赖 DSH 宿主能力。
若使用本地源码安装（dsh plugin --profile web add /path/to/dsh-ark-plan-usage），需补软链以解决 Node 模块解析问题：
mkdir -p node_modules
ln -sfn ~/.dsh/profiles/node_modules/@deepseek-ai node_modules/@deepseek-ai
修改 client.js 后刷新浏览器即可；修改 index.js 或 cordis.patch.yml 需重启 dsh web。
卸载¶
dsh plugin --profile web remove dsh-ark-plan-usage
总结¶
该插件通过在 DSH 侧边栏嵌入可视化卡片，解决了开发者查看 Agent Plan 用量需频繁操作终端的问题。其具备零构建、零运行时依赖的特点，集成 SSO 凭证管理功能，适合需要在 Web 界面实时监控配额的开发者使用。
