@qomob/dsh-madrank

v0.5.3

Published

7 days ago

MADRank Usage — track your AI usage in DeepSeek Harness, see how you rank.

Downloads

472

0High
0Medium
0Low

jonkilin

dsh deepseek deepseek-harness madrank usage plugin tokens

MADRank for DSH（中文版）

统计你的 AI 使用量。看看你排在哪里。

English | 简体中文

MADRank 是一个运行在 DeepSeek Harness (DSH) 中的 AI Usage & Ranking 插件。它把你在 DSH 中产生的 AI 使用数据转化为三个层次：

你的 DSH 会话
      ↓
本地 Usage 数据
      ↓
Today / 7 Days / Models / Streak
      ↓
可选加入 MADRank
      ↓
7-Day Token Race

它的核心原则很简单：本地统计默认运行，全球排名明确 opt-in，上传只发生在已结束的 UTC 日，而且只上传聚合后的 usage 数据。

你可以先把它当成一个私人 AI 使用仪表盘，也可以选择加入全球排名，看看：

过去 7 个 UTC 日，你究竟用了多少 AI Token，以及你排在全球什么位置。

MADRank 的排名指标不是"模型有多强"，而是真实 AI 使用量。

为什么是 Token Ranking？

今天大家讨论 AI 排名，通常讨论的是 benchmark、模型能力、SWE-Bench、Arena 等。但还有一个非常直接的问题：

谁真的在使用 AI？用了多少？

MADRank 关注的是 Usage Rank：谁每天真的在使用 AI、谁持续使用 AI、谁在过去 7 天产生了最多的有效 Token 使用量。

AI Usage Layer，而不是 Model Benchmark Layer。

核心功能

1. 本地 AI Usage Dashboard（无需加入全球排名）

Today — 今日使用量
7-Day / 30-Day History — 近 7 天 / 30 天历史
Top Models — 使用最多的模型
Streak — 连续使用天数
vs 7-Day Average — 与过去 7 日平均值对比
RANK — 全球排名状态
Cached Tokens — 缓存 Token 单独统计

这些数据来自 DSH 的 session projection feed，而不是读取 DSH 内部数据库。

2. 7-Day Token Race（核心竞争指标）

7 日总量，即最近 7 个 UTC 日的 Primary Tokens 总量。

Primary Tokens = uncached input tokens + output tokens
Cached Tokens  = cache read + cache write

关于口径的一个诚实说明：竞速数字是上传的 input+output 全量（uncached input + cache write + output）；cache read（缓存命中）单独上报、绝不进入竞速。本地仪表盘上的「未缓存」指本地 primary（uncached input + output）——两个数字回答的是不同问题，卡片对此都已标注：本地数字标 本机 · 实时，竞速数字来自服务器并附带同步时间。这样既避免缓存命中差异扭曲跨模型比较，又不隐瞒实际计入的内容。

3. 全球排名是可选的

MADRank 默认不上传任何数据。只有你主动开启 参与全球排名 之后，插件才会进入同步流程：

默认关闭，用户主动 opt-in
不上传实时请求，不上传当天数据
只上传已经结束的 UTC 日的天级聚合数据
同步失败不影响本地统计

4. 一键分享你的 Token Race（Share Card）

Quick View 卡片上的分享按钮会把你的排名变成一个可传播的社交卡片：

专属分享链接 — https://madrank.ai/share/<shareToken>，任何设备、任何人都能打开查看
社交卡片图 — 分享时自动生成专属海报图（服务端动态渲染：7 天 Token 数、全球排名、品牌标识与跳转二维码），在微信 / X / 小红书等平台发布时自动作为卡片配图
一键复制的分享文案 — 中 / 英文双语，附排名与模型信息
数字以服务器权威数据为准 — 分享前自动向服务器刷新数据（/api/usage/me），不会出现本地缓存陈旧导致的数字不一致

分享不是上传新的隐私数据：shareToken 只是你匿名节点的公开寻址标识，榜面数据本就公开。

隐私设计

MADRank 从架构层面把"本地统计"和"全球同步"分开。

默认状态（离线可用）：
DSH → Local Projection → Local Usage Store → Local Dashboard

加入全球排名后：
Local Usage Store → Finished UTC Day → Aggregated Usage → MADRank Ingest

不会上传： Prompt、Response、Tool Arguments、单次请求内容、当天实时 usage。 上传的： 按日期、按模型聚合后的 usage。

数据删除

清除本地数据 — 只删除本机 MADRank usage 数据，不影响远端。
删除已同步数据 — 请求删除当前安装身份对应的远端 usage 数据。

本地删除和远端删除是两个独立操作。

数据为什么可信？

MADRank 不自己创造另一套 Token 统计逻辑。它使用 DSH 的 session projection 作为数据来源，并通过独立的 reference token-meter 对账。针对真实 DSH session 的回放验证：

input        745,120  =  745,120
output       186,324  =  186,324
cache read 26,352,384 = 26,352,384

MATCH ✓

覆盖 streaming replacement、waterfall tool traffic、跨午夜分桶、同 (turn, step) 替换语义。目标是：

和 DSH 的 Token Meter 保持一致。

安装

DSH 插件由 profile 挂载。下面两件事必须同时成立，否则插件会静默失效：
包已在该 profile 中声明并安装（package.json + node_modules，通过 dsh plugin … add）；
该 profile 挂载了它 —— cordis.patch.yml 里的 insert 条目。
发布包里 Host 半侧已编译为 JavaScript（dist/host/）、浏览器半侧已预构建（dist/client.js）——消费方无需任何构建步骤。（Node 拒绝对 node_modules 内的 TypeScript 做类型剥离，所以安装包的 main 不能指向 .ts 文件。）

方式一：桌面 app 内置插件管理器（app 内推荐）

打开侧栏 插件（Plugins） 页（插件管理器；设置 → 插件 为只读列表），从以下任一来源安装：

GitHub —— 仓库 qomob/dsh-madrank
npm —— 包 @qomob/dsh-madrank

然后完整退出并重开 app（profile 组合只在启动时加载，刷新页面不够）。若管理器未自动挂载，补上下面的挂载条目后再重启。

v0.5.2 适配 DSH 0.2.x（新版插件模型：Config + configForms + slot props 会话数据）。旧版 DSH 上浏览器半侧会等待激活 —— 请先升级 DSH。Host 半侧照常每日同步聚合数据，并把服务端返回的排名记录通过独立客户端可见投影（madrankRank）发布，因此实时排名卡与分享卡在新模型下照常可用。

方式二：命令行（适用于任意 profile：`desktop`、`web`…）

# GitHub（始终取 main 最新）
dsh plugin --profile desktop add github:qomob/dsh-madrank

# 或 npm 已发布版本
dsh plugin --profile desktop add @qomob/dsh-madrank

dsh plugin 会在 ~/.dsh/profiles/<profile>/ 内转发给 pnpm，从而正确声明依赖（未声明的包会在下次 pnpm install 时被剪掉）。

随后在 ~/.dsh/profiles/<profile>/cordis.patch.yml 加入挂载条目：

- insert:
    - id: madrank
      name: '@qomob/dsh-madrank'

重启 DSH。

方式三：本地开发（改动实时生效）

git clone https://github.com/qomob/dsh-madrank.git
cd dsh-madrank && npm install && npm run build
dsh plugin --profile desktop add 'link:/absolute/path/to/dsh-madrank'

注意使用 link: 而不是 file:（file: 会复制实体、不再随源码同步）。link: 方式下 profile 加载的是已构建的 dist/，源码修改后需 npm run build 再重启。之后同样补挂载条目并重启。

验证

侧栏出现 MADRank 入口；
日志出现 madrankUsage projection registered 与 settings ns registered: madrank-usage。

排障：装完却没有反应

| 现象 | 检查 | | --- | --- | | 无 MADRank 入口、无日志 | cordis.patch.yml 缺少挂载条目 | | 装了别的插件后本插件消失 | profile package.json 里未声明依赖（重跑 dsh plugin … add） | | 缺「settings ns registered」这行 | profile 没有完整重启，或只刷新了页面 | | UI/文案比本 README 旧 | 装到了 npm 上的旧版本 —— 改用 GitHub 源，或升级（dsh plugin --profile desktop add @qomob/dsh-madrank@latest） | | 已安装、已启用，但运行状态显示「未运行」（v0.3.6 及更早） | 该版本把 main 指向了 src/index.ts，而 Node 不能剥离 node_modules 下的 TS。升级到 v0.4.0+（Host 已编译为 dist/host/） |

使用方式

Sidebar → Quick View = VIEW（看数据）
Settings → MADRank   = CONFIGURE（改配置）

Quick View 查看使用情况、7 日趋势、模型分布与 Rank；点击卡片上的分享按钮即可生成专属分享卡片。Settings 负责参与排名开关、自动同步、隐私、本地/远端数据删除与插件状态。

💬 加入社群

扫码加入 DSH 插件社群——交流 dsh 用法、插件开发与最佳实践：

微信群二维码有时效；若扫码失效，请到 Issues 留言，我们会更新二维码。

Architecture

┌──────────────────────┐
│   DSH Session Logs   │
│    Source of Truth   │
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│  sessionProjections  │
│     madrankUsage     │
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│      UsageStore      │
│  local usage cache   │
└──────────┬───────────┘
      ┌────┴─────┐
      ▼          ▼
   Local UI    Daily Sync
                   │
                   ▼
            MADRank Ingest
                   │
                   ▼
           7-Day Token Race

Framework owns events — 不创建第二套 session/event subscription，插件只负责 Projection + Fold + Persistence + Sync
Session log is the source of truth — 本地 usage-store.json 只是可删除、可重建的 projection cache
No direct SQLite access — 数据采集只通过 sessionProjections
Sync is isolated — 同步失败 ≠ 本地统计失败

核心兼容原则：

Never fork DSH
Never read internal SQLite directly
Never duplicate token-meter semantics
Never subscribe to session events independently
Never upload same-day usage
Never upload prompts / responses / tool arguments
Never let global sync block local usage

对 DSH 的全部耦合集中在 src/compat.ts，可用 npm run verify:dsh 验证。

集成层遵循 DeepSeek Harness 官方仓库的现行推荐（cookbook docs/cookbook/adding-a-settings-card.md + dsh-session-projection / dsh-settings 包参考）：投影定义为官方 { key, stateSchema, init, apply, wire, stateVersion } 形状（zod ZodType 校验）；设置命名空间以官方 schemastery schema 注册（src/settings-schema.ts，取代旧 zod 可调用适配器 + 手写 toJSON 图）；同步 tick 与落盘去抖优先用官方 timer 服务；浏览器配置卡注册在 settings.plugin.item，键 = 命名空间，与宿主服务的命名空间自动配对。

项目结构

dsh-madrank/
├── src/
│   ├── index.ts              # Host 侧插件入口
│   ├── compat.ts             # DSH 唯一兼容层
│   ├── fold.ts               # Usage Projection / 状态折叠
│   ├── caliber.ts            # Token 数据口径
│   ├── stats.ts              # Dashboard 聚合
│   ├── store.ts              # 本地 Usage Store
│   ├── snapshot.ts           # Card Snapshot
│   ├── sync.ts               # 全球日级同步
│   ├── whoami.ts             # 节点自识别 / 分享令牌
│   ├── global-rank.ts        # Rank 数据处理
│   ├── global-rank-file.ts   # Rank 本地持久化
│   ├── settings-schema.ts    # Settings 契约
│   └── client/
│       ├── index.ts          # Browser / Client 入口
│       ├── panel.ts          # Quick View（含分享动作）
│       ├── settings-panel.ts # Settings
│       ├── card-data.ts      # 卡片数据 / wire 解码
│       ├── card-html.ts      # 卡片渲染 / 分享文案
│       ├── share-modal.ts    # 分享弹窗
│       ├── i18n.ts           # 双语词典
│       └── tick.ts           # 数据 tick / locale
├── tools/                    # token-meter 对账 / 兼容性验证 / client 构建
├── tests/                    # Vitest + golden fixtures
├── dist/                     # 构建产物（browser half）
├── docs/                     # README 截图
├── LICENSE
├── package.json
└── README.md

数据与存储

默认数据目录 ~/.madrank/usage/，可用 MADRANK_USAGE_DIR 覆盖。典型文件：installation-id、usage-store.json、card-snapshot.json、global-rank.json、deleted-epoch、cleared-epoch。匿名安装 ID 是本机生成的 UUID，换机器默认视为新身份。

开发

npm install
npm test                  # Vitest
npm run typecheck         # tsc --noEmit
npm run build:client      # 构建 browser half（dist/client.js）
npm run reconcile -- <events.jsonl>   # 真实事件流对账
npm run reconcile:fixture # fixture 对账
npm run verify:dsh        # DSH 兼容性验证
npm run preview           # 用本地真实数据渲染卡片预览页

技术栈：TypeScript、React、Zod、Vitest。

当前状态

本地 usage projection、7 日/30 日历史、Top Models、Streak、Quick View、Settings、本地清除、远端删除、日级聚合同步、golden cases 与真实流量对账、DSH 兼容性验证——均已完成。全球排名已接入线上 ingest（madrank.ai）；分享链路完整可用：专属分享链接、服务端动态社交卡片图、双语分享文案，分享前通过服务器权威接口（/api/usage/me）自动刷新数字。当前版本 v0.3.6。

声明

本站为社区驱动的非官方项目，与 DeepSeek AI 官方无隶属关系。"DeepSeek"、"dsh"、"DeepSeek Harness" 等名称与商标版权归原作者所有。

🌐 https://madrank.ai

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme