dsh-api-tools

为 DeepSeek Harness Web 提供 API 用量观测台和服务重启面板。四个插件包可分别安装，同一功能的 host 与 UI 应配套升级。

包	版本	用途
dsh-api-meter	0.2.0	用量记录、持久化、历史回算
dsh-ui-api-meter	0.2.0	用量图谱、模型分布、可搜索会话账本
dsh-refresh	0.3.0	重启准备、原参数重启、实例状态查询
dsh-ui-refresh	0.3.0	确认面板、阶段反馈、恢复后自动刷新

安装与升级

需要支持 Zstandard 的 Node.js（最低 22.15，建议使用 Node 24 LTS）及兼容的 dsh Web 宿主。

dsh plugin --profile web add ./dsh-api-meter
dsh plugin --profile web add ./dsh-ui-api-meter
dsh plugin --profile web add ./dsh-refresh
dsh plugin --profile web add ./dsh-ui-refresh

将 web 替换为实际 profile。更新本地文件后，按宿主的插件升级流程重新添加四个包，并完整重启一次 Web 服务、重新加载页面。不要混用新旧 host/UI；本次统一了独立插件包名与协议、前端模块标识。

安装操作不会由本仓库的构建或测试脚本自动执行。

用量观测台

从侧边栏底部的「API 用量」打开。

• 7 / 14 / 30 天和全部历史；时间筛选同时应用于总览、图表、模型和会话。
• 按 UTC 自然日统计，补齐没有调用的日期；长历史自动合并相邻日期以保持可读性。
• 未缓存输入、输出与推理、缓存命中、缓存写入分别呈现；写入不算缓存命中。
• 会话支持关键词搜索、每页 8 条和展开模型明细；图表可用键盘聚焦读取数值。
• 打开面板时每 5 秒刷新；页面隐藏时暂停请求，同一面板不会并发轮询。
• 适配宿主主题变量，提供浅色、暗色、窄屏和减少动画支持。

Token 字段沿用宿主的标准化口径：输入不含缓存，输出与推理分项。实时流中多个 usage 片段累加 Token，同一条流仅记一次调用；需要 provider 按宿主约定提供增量用量。

数据可靠性

默认文件：~/.dsh/storages/api-meter/usage.json。存在改动时定时保存，并在插件卸载、正常进程退出（包括本重启插件触发的退出）前同步保存最后一批数据。强制结束进程或断电仍可能损失尚未保存的调用。

保存使用同目录临时文件、刷盘和重命名，保留上一份有效快照 usage.json.bak。读取时校验数值及结构，主文件损坏时尝试备份。

历史回算按帧读取 Zstandard 会话日志，处理过程中让出事件循环。回算成功前保持现有统计；合并时保留已有历史和回算期间的新调用。失败不会标记完成，下次启动重试。升级会用版本标记重新核对一次旧快照，修复旧版错误标记成功的问题。

日志包含 request ID 时按 ID 关联用量；缺少 ID 的旧日志只能按最近的请求头归属，并发历史可能仍存在归属歧义。旧快照中没有每日明细的部分仅计入「全部」。

强制重建（先停止 dsh Web；完整成功后才替换文件，并生成带时间戳备份）：

node dsh-api-meter/scripts/backfill-sessions.mjs
# 可传入 usage.json 和 sessions 目录两个位置参数

重启面板

设置页的「重启服务」提供确认、阶段进度、失败原因和重试。

服务端先启动辅助进程，通过 IPC 确认参数、工作目录和日志可用，才安排原进程退出。重复请求共享同一重启流程。辅助进程等待原进程退出和端口释放，保留 Node 运行参数、原命令、工作目录及环境，启动新服务并执行 HTTP 健康检查。

端口仍被占用或原进程未退出时会停止流程，不会按端口终止任何进程。前端通过 Typert 查询新的服务实例 ID，确认恢复后再重载页面；网络断开本身不会被当作重启成功。

重启日志默认 <cwd>/data/refresh.log，超过 2 MiB 时在下次重启轮换为 .1。日志不记录原始启动参数，也不接收新进程的完整标准输出。需要启动详细日志时使用宿主自身的日志机制。

配置

在 profile 的插件配置中覆盖：

- id: api-meter
  config:
    persistIntervalMs: 30000
    # persistPath: 'C:\\data\\usage.json'
    # sessionsRoot: 'C:\\data\\sessions'

- id: refresh
  config:
    # port: 3080   # 默认解析原启动参数，再回退为 3080
    killDelayMs: 800
    timeoutMs: 30000
    # logPath: 'C:\\data\\refresh.log'

persistIntervalMs: 0 关闭定时保存，仍在卸载和正常退出时保存。不同 dsh 进程/profile 应配置不同 persistPath，避免多个写入者覆盖同一文件。当前保留全部历史，不会自动清除用户数据；RPC 仍传输完整快照，超大历史的服务端分页可作为后续扩展。

本地开发

源码在各包 src/；shared/ 包含共用弹窗和轮询逻辑。lib/ 是构建产物，请修改源码后重新生成。

npm ci --prefix .tooling --legacy-peer-deps
npm run build
npm test
npm run preview

工具依赖单独放在 .tooling/，不会改动项目根目录原有的宿主依赖链接。构建清理并重建四个包的 lib/，同步声明与协议，不再发布旧 source map 和增量编译缓存。

预览地址：http://127.0.0.1:4173。使用合成数据和模拟重启，不访问真实会话、不重启真实 dsh。

浏览器回归：

npm run test:browser

需要 Playwright，可通过 PLAYWRIGHT_MODULE_PATH 指定其模块目录，或安装到 .tooling/node_modules。默认使用系统 Edge，可用 BROWSER_CHANNEL=chrome 改为 Chrome。截图保存到忽略版本控制的 artifacts/。

测试覆盖退出保存、备份恢复、历史迁移、坏日志、并发请求归属、重启启动失败/互斥、真实测试服务重启、端口占用保护、Cordis 装卸、发布包接口及浏览器交互。

许可

MIT。每个发布包均包含许可证。详见 LICENSE。