dsh-commandcode-usage-monitor 项目设施与维护手册

August 30, 2026 · View on GitHub

本文档按 codebase-documenter 思路编写，面向“上游维护 / 快速拾取”场景。它把 README、现有 docs、源码与 DSH 基础编码流程整合成一份可执行的设施手册。

1. 项目元信息

项	值
包名	`dsh-commandcode-usage-monitor`
版本	`0.1.0`
类型	DSH（DeepSeek Harness）组合包 / 插件
定位	Host 侧抓取 Command Code `/alpha/*` 用量/额度接口，Browser 侧提供侧边栏挂件与设置页仪表盘
运行环境	Node.js `>=22`、ESM、TypeScript
许可证	MIT
发布入口	npm：`dsh-commandcode-usage-monitor`
安装命令	`dsh plugin --profile web add dsh-commandcode-usage-monitor`

核心亮点：

Host 侧保守抓取 /alpha/whoami、/alpha/usage/summary、/alpha/billing/credits、/alpha/billing/subscriptions。
Host 内存 UsageStore 保存最新快照与每轮消耗，浏览器只读同源 JSON，不接触明文 API Key。
浏览器端注册 sidebar.footer.action 小挂件与 settings.section 设置页，中英双语。

2. 完整技术栈

2.1 Host / 后端侧

领域	技术	说明
运行时	Node.js `>=22`	ESM，`"type": "module"`
语言	TypeScript `6.x`	`strict`，`moduleResolution: Bundler`，允许 `.ts` 后缀 import
插件框架	`@deepseek-ai/cordis` `^4.0.1`	Cordis 插件/Fiber 生命周期、依赖注入、`ctx.effect` 自动清理
配置	`@deepseek-ai/schemastery` `^3.18.1`	`Config` interface + 同名 Schema
命令	`@deepseek-ai/dsh-commands`	`/commandcode-usage` 斜杠命令
凭据	`@deepseek-ai/dsh-credentials`	`ctx.credentials` 可选服务；`credentialRef`
Web 路由	`@deepseek-ai/dsh-host-webserver`	`ctx.webServer.register(route)`，`WebRoute` 类型
启动环境	`@deepseek-ai/dsh-launch-environment`	`launchEnvironmentOf(ctx).get(envName)`
设置	`@deepseek-ai/dsh-settings`	`installSettingsSection` / `settingsNamespace`
构建	`tsc` + `tsdown`	`tsc` 产类型声明到 `lib/types`，`tsdown` 产 Host `/ Browser` bundle
测试	`node:test` + `tsx`	Node 内置 test runner 直接跑 TS

2.2 Browser / 前端侧

领域	技术	说明
UI	React `18`	函数组件 + hooks
客户端基座	`@deepseek-ai/dsh-client-store`	DSH `0.1.2-alpha.1` 平台模块表中的 store
客户端类型	`@deepseek-ai/cordis`	`ClientContext` 即 `Context` 的类型别名
连接	`@deepseek-ai/dsh-client-connection`	`ctx.connection`
设置 UI	`@deepseek-ai/dsh-client-ui-settings`	`settings.section` 槽位、`SettingsScope`/`SettingsScopeSpec`
侧边栏 UI	`@deepseek-ai/dsh-client-ui-sidebar`	`sidebar.footer.action` 槽位
槽位渲染器	`@deepseek-ai/dsh-client-ui-renderer`	提供 `ctx.slots`
槽位类型	`@deepseek-ai/dsh-client-ui-slots`	`PropsLocale`、`PropsRuntime`、`InjectFace`
多语言	`@deepseek-ai/dsh-client-locale`	`ctx.locale.register`

注：本分支 0.1.2-comp 面向 DSH 本地源码 0.1.2-alpha.1（dsh-client-runtime 已拆为 dsh-client-store / dsh-client-ui-renderer）。main 分支仍面向 npm 发布版 0.1.1-rc.2。

| 样式 | CSS Modules + lightningcss | 构建期编译 .module.css，注入 <style data-plugin> | | 构建产物 | lib/client.js | 闭包工厂 window.__ModuleLoader__.load({ id, factory }) |

2.3 外部依赖 / 上游接口

外部系统	接口	说明
Command Code API	`/alpha/whoami`	账户身份；可能带 `org.id`，影响订阅接口的 `orgId` 参数
Command Code API	`/alpha/usage/summary`	累计请求/花费/Token
Command Code API	`/alpha/billing/credits`	月额度/已购/赠送 + 5 小时/每周窗口
Command Code API	`/alpha/billing/subscriptions`	套餐信息；`planId` 可能来自 credits 兜底
官方 CLI 登录态	`~/.commandcode/auth.json`	最后一级 API Key 来源

注意：/alpha/* 不是公开 Provider API 合同，上游变化时需同步更新 src/client.ts 的解析逻辑与 src/plan.ts 套餐表。

3. 目录结构与入口

dsh-commandgo-usage/
├── package.json                 # bundle 声明（dsh.bundle.patch）、exports、peerDependencies
├── cordis.patch.yml             # 插件挂载层：insert 一行 commandcode-usage-monitor
├── tsconfig.json / tsconfig.build.json
├── tsdown.config.ts             # 入口：clientBundle('dsh-commandcode-usage-monitor', ...)
├── build/
│   ├── tsdown.client.ts         # 共享 client bundle 构建预设（来自 DSH monorepo 的单一事实源）
│   └── web-platform.ts          # 浏览器平台模块表（react、cordis、slot 等）
├── assets/readme/               # hero.svg / workflow.svg
├── docs/                        # 项目文档（本手册所在目录）
├── src/
│   ├── index.ts                 # Host 侧 apply 入口：装配 Poller/Routes/Watcher/Command/UI routes/Settings
│   ├── config.ts                # Config/UiConfig/AccountConfig + Schema + 默认值 + resolveConfig
│   ├── credentials.ts           # API Key 解析链 + auth.json 读取
│   ├── client.ts                # CommandCodeClient：/alpha/* 抓取、归一化、失败分类
│   ├── store.ts                 # UsageStore：内存快照、revision、turn cost、事件回调
│   ├── poller.ts                # UsagePoller：定时/退避/并发控制/防重叠
│   ├── routes.ts                # 只读 JSON 路由：status / turn-cost / health
│   ├── ui-routes.ts             # UI 路由：credential / credential-test / refresh / plans / plan-preference
│   ├── session-watcher.ts       # SessionWatcher：session/event 聚合每轮消耗
│   ├── commands.ts              # /commandcode-usage 命令渲染
│   ├── plan.ts                  # 官方套餐表 + 额度计算
│   ├── types.ts                 # 全链路共享数据契约
│   └── client/
│       ├── index.ts             # Browser apply：locale、settings.section、sidebar.footer.action
│       ├── MonitorMiniWidget.tsx
│       ├── MonitorSettingsPage.tsx
│       ├── use-monitor.ts       # 状态轮询 / turn-cost seq 对齐 / 工具函数
│       ├── api.ts               # 同源 fetch 封装
│       ├── locales.ts           # zh/en 字典
│       ├── monitor.module.css   # 自包含颜色变量 + 明/暗主题
│       └── css-modules.d.ts
├── tests/
│   ├── client.test.ts           # CommandCodeClient 解析/降级/分类
│   └── poller.test.ts           # UsagePoller 发布/防重叠
├── lib/                         # 构建产物（lib/index.js、lib/client.js、lib/types/...）
└── README.md / README.en.md / CHANGELOG.md / LICENSE

入口点：

Host 入口：src/index.ts 的 apply(ctx, rawConfig)。
Browser 入口：src/client/index.ts 的 apply(ctx)。
npm 导出：. → lib/index.js；./client → lib/client.js；./src/* 供源码引用。

4. DSH 基础编码流程 / 插件挂载机制

本项目遵循 DSH 插件标准：

插件形态：导出 name、inject、apply(ctx, config?)；注册全部走 ctx，卸载自动清理。
配置：src/config.ts 导出 interface Config 与同名 Config Schema，默认值写在 Schema / resolveConfig；不可硬编码可调参数。
依赖注入：
- 必需：export const inject = ['webServer']（Host）；浏览器 inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote']。
- 可选：ctx.get('credentials') 判空后使用。
副作用生命周期：ctx.effect 内部 poller.start()、注册路由/监听/命令；返回统一 disposer 停止清理。
可选服务：ctx.inject(['commands'], ...) 在子 Fiber 中注册命令，卸载自动注销。
设置页：Host 用 installSettingsSection(ctx, UI_SETTINGS_NAMESPACE, UiConfig, entry, hooks) 注册浏览器可改的 UI 偏好。
UI 槽位：Browser 用 ctx.slots.inject('settings.section', ...) 与 ctx.slots.inject('sidebar.footer.action', ...) 挂载页面/挂件。
多语言：ctx.locale.register(NS, { zh, en })，NS = 'commandcode-usage'。
打包：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml；安装后 profile 层按行替换。
浏览器隔离：浏览器只消费同源 Host JSON；任何跨插件 value import 由 build/tsdown.client.ts 的 purity gate 在构建期拒绝。

5. 核心组件与数据流

5.1 Host 侧核心类

组件	文件	职责
`CommandCodeClient`	`src/client.ts`	抓取 4 个 `/alpha/*` 端点；独立降级；全失败分类 `invalid-key` / `service-unavailable` / `network`；网络/5xx 重试 1 次；4xx/解析错误不重试
`UsageStore`	`src/store.ts`	持有最新 snapshot + turnCost + revision；对象替换式更新；可订阅事件
`UsagePoller`	`src/poller.ts`	按 `pollIntervalMs` 轮询；`errorBackoffMs` 退避；`accountConcurrency` 控制并发；防 in-flight 重叠
`SessionWatcher`	`src/session-watcher.ts`	监听 `session/event` 的 `assistant/message` usage；`turn/end` 结算；按 `(sessionId, turn)` 聚合；`session/disposed` 清理
`makeUsageRoutes` / `registerUsageRoutes`	`src/routes.ts`	只读 JSON：`status.json`、`turn-cost.json`、`health`
`makeUiRoutes` / `registerUiRoutes`	`src/ui-routes.ts`	UI 管理：credential / test / refresh / plans / plan-preference
`commandDefinition` / `applyCommands`	`src/commands.ts`	`/commandcode-usage` 命令文本仪表盘
`resolveApiKey` / `resolveAuthFileApiKey`	`src/credentials.ts`	按优先级解析 Key
`PLAN_*` / `planMonthlyCap` 等	`src/plan.ts`	官方套餐额度表与计算

5.2 Browser 侧核心模块

模块	文件	职责
`apply`	`src/client/index.ts`	注册 locale、设置页、侧边栏挂件
`MonitorMiniWidget`	`src/client/MonitorMiniWidget.tsx`	sidebar footer 紧凑用量条
`MonitorSettingsPage`	`src/client/MonitorSettingsPage.tsx`	设置页：API Key 配置、Plan 选择、仪表盘
`useMonitorStatus` / `useTurnWatch`	`src/client/use-monitor.ts`	状态轮询、turn-cost seq 对齐、刷新事件
`api.ts`	`src/client/api.ts`	同源 fetch 封装

5.3 主数据流

flowchart LR
    subgraph Host
        CC[Command Code /alpha/* API]
        PO[UsagePoller]
        CL[CommandCodeClient]
        ST[UsageStore]
        SW[SessionWatcher]
        RT[UsageStore routes<br/>status/turn-cost/health]
        UR[UI routes<br/>credential/refresh/plans/plan-preference]
        SE[DSH session/event]
        CM[/commandcode-usage/]
        CC -->|GET /alpha/*| CL
        PO -->|interval/backoff| CL
        CL -->|normalized report| ST
        SE -->|assistant/message usage| SW
        SW -->|turn-cost| ST
        ST --> RT
        ST --> CM
        UR -->|refresh| PO
        PO --> ST
    end
    subgraph Browser
        API[src/client/api.ts]
        HOOK[useMonitorStatus/useTurnWatch]
        WIDGET[MonitorMiniWidget]
        PAGE[MonitorSettingsPage]
    end
    RT -->|same-origin JSON| API
    UR -->|same-origin JSON| API
    API --> HOOK
    HOOK --> WIDGET
    HOOK --> PAGE

5.4 一次完整抓取流程

UsagePoller.start() 立即 runNow()，之后 setInterval(runIfDue)。
CommandCodeClient.fetchAccount(accountId, label) 先解析 Key：
- 无 Key → configured: false，空报告。
- 有 Key → getUsageReport(apiKey)。
getUsageReport 依序请求 4 个端点；单端点失败进 failures，成功字段仍写入报告。
全部失败时按状态码分类 blocked。
UsagePoller.doRun() 用 worker 池（默认串行）抓取所有账户，组装 CommandCodeUsageSnapshot 写入 UsageStore。
前端轮询 /commandcode-usage/status.json 或 /commandcode-usage/turn-cost.json 展示。
Browser 点击“测试/保存/刷新”时经 ui-routes.ts 触发 Host 动作。

5.5 每轮消耗流程

SessionWatcher.start() 订阅 session/event。
遇到 assistant/message 且 data.usage 存在时，按 (sessionId, turn) 聚合 input/cache/output/reasoning tokens。
遇到 turn/end 时 finalize，把 TurnCostSnapshot 写入 UsageStore（seq++）。
前端 useTurnWatch 以 seq 判断是否是新的一轮；amount 当前始终 null（未注入 costFor 价格表）。

6. 对外 API

6.1 只读状态路由（`src/routes.ts`）

路由	方法	说明
`/commandcode-usage/status.json`	GET	完整快照 + `revision` + `lastError`
`/commandcode-usage/turn-cost.json`	GET	最近一轮消耗 + `seq`
`/commandcode-usage/health`	GET	健康检查

6.2 UI 管理路由（`src/ui-routes.ts`）

路由	方法	说明
`/commandcode-usage/credential.json`	GET / POST / DELETE	查询/写入/清除凭据
`/commandcode-usage/credential-test.json`	POST	测试当前 Key 可用性
`/commandcode-usage/refresh.json`	POST	强制 Host 立即抓取一轮
`/commandcode-usage/plans.json`	GET	官方套餐下拉目录
`/commandcode-usage/plan-preference.json`	GET / POST / DELETE	读取/保存/清除 Plan 偏好

所有路由均 Cache-Control: no-store，Access-Control-Allow-Origin: *。

6.3 API Key 解析链（`src/credentials.ts`）

账户级字面量 accountApiKey
账户级 env / 顶层 env 名经 ctx.credentials 服务
DSH 启动环境 launchEnvironmentOf(ctx).get(envName)
顶层 config.apiKey（仅未指定账户级 env 时）
官方 CLI ~/.commandcode/auth.json（仅默认账户）

7. 配置项

Schemastery 定义在 src/config.ts，完整表见 docs/configuration.md；维护时以 src/config.ts 的 Config 与 resolveConfig 为准。

配置	默认值	说明
`apiKeyEnv`	`COMMANDCODE_API_KEY`	凭据引用名
`apiKey`	`''`	组合配置字面量 Key
`apiBase`	`https://api.commandcode.ai`	Command Code API 地址
`pollIntervalMs`	`60000`	轮询间隔
`errorBackoffMs`	`15000`	失败后退避
`requestTimeoutMs`	`15000`	单请求超时
`accountConcurrency`	`1`	多账户并发数
`accounts`	`[]`	额外账户
`activeAccount`	`''`	预留
`enableSessionCost`	`true`	是否启用每轮消耗
`enableRoutes`	`true`	是否注册只读状态路由
`storagePath`	`''`	预留
`ui.*`	见 `UiConfig`	浏览器 UI 偏好

8. 构建 / 测试 / 开发循环

npm install
npm run typecheck   # tsc --noEmit
npm test            # node --import tsx --test tests/**/*.test.ts
npm run build       # tsc -p tsconfig.build.json && tsdown

tsconfig.build.json 只 emit 声明到 lib/types。
tsdown.config.ts 通过 clientBundle 同时产出：
- lib/index.js（Host / Node）
- lib/client.js（Browser / web dsh.client）
浏览器 CSS Modules 由 build/tsdown.client.ts 用 lightningcss 编译并自动注入 <style>。

本地安装验证

dsh plugin --profile web add "link:$(pwd)"
export COMMANDCODE_API_KEY=user_xxx
dsh web --port 3099
curl http://127.0.0.1:3099/commandcode-usage/status.json
curl http://127.0.0.1:3099/commandcode-usage/turn-cost.json

已知缺口：README / docs 提到的 scripts/dev-loopback.sh 在当前仓库中不存在。若需要回环验证脚本，需补齐或从历史版本恢复。

9. 已知技术债 / 上游维护注意点

UsageStore.setError() 目前无调用方；status.json 的 lastError 实际几乎总是 null。若要让前端看到最近错误，应在 UsagePoller 失败分支调用 store.setError()。
UsageStore.hydrate() 已实现但未接入；storagePath 配置是预留项。
activeAccount 为预留配置，尚未参与运行时选择。
SessionWatcher 的 costFor 未注入，turn-cost.json 的 amount 为 null。
enableRoutes: false 只关闭只读状态路由；ui-routes.ts 仍会注册。若希望完全关闭 HTTP 面，需要调整 src/index.ts。
tests/ 只覆盖 CommandCodeClient 与 UsagePoller；SessionWatcher、routes、ui-routes、commands、store 尚无单测。
Command Code /alpha/* 非公开合同，字段变化需同步 src/client.ts 与 src/plan.ts。
Browser bundle 由 build/tsdown.client.ts 驱动；若 DSH 更新平台模块表，需同步 build/web-platform.ts。

10. 快速拾取 / MCP 工作流（推荐）

后续维护时建议优先使用以下本地索引 + 网络检索组合，形成“代码链 → 知识库 → 官方文档”闭环。

10.1 codegraph：查询目的组件 / 流程

当前项目索引位于本仓库 .codegraph/；DSH 框架源码索引位于：

当前项目：/home/xingpeng/项目/dsh-commandgo-usage
DSH 框架源码：/home/xingpeng/文档/RAG/documents/deepseek-harness

常用查询示例：

# 当前项目：完整插件装配链
index.ts config.ts credentials.ts poller.ts store.ts routes.ts session-watcher.ts commands.ts plan.ts

# DSH 框架：某个服务接口 / 槽位机制
webServer.register WebRoute
installSettingsSection settingsNamespace
slots.register settings.section sidebar.footer.action

10.2 txtai：自建知识库索引

用 txtai 把本项目 docs/、README、CHANGELOG 以及 DSH 官方文档/技能参考资料建成向量索引。
拿到相关文档路径后，再用 codegraph 展开对应源码，形成“文档段落 → 文件/符号 → 调用链”的完整链路。
适合“上游 /alpha/* 变更后，哪些解析代码受影响”这类语义检索。

10.3 firecrawl：专业网络搜索 / 抓取

当 DSH 上游接口或 Command Code 套餐/接口变化时，用 firecrawl 检索并抓取：
- DeepSeek Harness 官方文档站
- commandcode.ai / pricing / docs
- GitHub issues / PR（dsh-commandcode-provider、CLI 相关）
抓取结果落地到 docs/ 或知识库，再对照本地 codegraph 更新代码。

10.4 上游维护最小闭环

先看 CHANGELOG.md 与 git log，了解最近改动。
用 codegraph 对目标组件（如 CommandCodeClient、plan.ts、routes.ts）做 blast radius 查询。
对 /alpha/* 返回结构变化，先跑 tests/client.test.ts，再更新解析字段。
对 DSH 平台变化（peerDependencies / build 预设），对照 build/web-platform.ts 与 DSH 源码索引导航。
改完跑 npm run typecheck && npm test && npm run build。