# deepseek-harness-desktop

> Shows real-time input/output token estimation and generation throughput (TPS) in the DSH Web chat status line, automatically replacing with actual provider usage when available.

## Metadata

- Author: [@ningbainb](https://github.com/ningbainb)
- Repo: <https://github.com/ningbainb/deepseek-harness-desktop.git>
- GitHub: [ningbainb/deepseek-harness-desktop](https://github.com/ningbainb/deepseek-harness-desktop)
- Stars: 156
- Language: TypeScript
- License: [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)
- Homepage: <https://ningbainb.github.io/deepseek-harness-desktop/>
- Topics: `ai-agent`, `ai-coding-assistant`, `codex`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `electron-app`, `gui`, `open-source`, `plugin-system`, `plugins`, `remote-access`, `skills`, `ssh-client`, `windows`, `windows-desktop`
- Forks: 5
- Open Issues: 6
- Last push: 2026-08-20T05:29:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-live-stats
```

## Wiki

## 一句话定位
DSH Web 聊天状态行里实时显示本次会话的输入/输出 token 估算与生成吞吐（TPS），等 provider 真实用量回来后自动替换掉估算值。

## 核心能力
- 实时估算输入 token：综合会话表面消息与 header/工具框架的字符数，按字符密度参数折算
- 实时估算输出 token：随着流式 chunk 逐块累计，文本、reasoning、tool-call 各自走不同的计费规则
- 实时生成吞吐：渲染 `TPS 31.4 tok/s` 之类的指标，挂在步骤计数之后、计费组之前
- 自动替换为真实用量：provider 返回 `usage` chunk 或最终消息落地时，估算值被真实数据覆盖
- TPS 常驻显示：测得一次速率后便持续显示，新步骤暂未产出或遇到无速率步骤时回退到最近一次测量值，避免状态行闪烁
- 暴露设置卡：DSH Web 插件设置里多出一张 `live-stats` 卡，可调字符密度参数和总开关

## 技术实现
- **语言**: TypeScript + React（客户端）
- **关键依赖**: `@deepseek-ai/dsh-session`（消费事件流）、`@deepseek-ai/dsh-session-projection`（注册可重放投影）、`@deepseek-ai/dsh-token-meter`（消费投影结果）、`schemastery` + `zod`（配置/数据结构校验）
- **架构模式**: 经典 host/client 双半区——host 侧用 cordis 插件形态注册 `liveTokenUsage` 会话投影（`liveTokenUsage` 走纯函数 fold，重放可知），client 侧把一张设置卡挂到 `web-ui.plugin.item` 槽位、把 TPS 行挂到 `conversation.composer.dock` 槽位
- **入口文件**: `src/index.ts`（host 半区）、`src/client/index.ts`（browser 半区）

## 适用场景
- 在 DSH Web 里跑长对话时，想实时看到生成速度（TPS）和累计 token 走势，不再等结束时再揭晓
- 想要在 provider 真实用量尚未到位时心里有数，比如判断是否需要尽早停止生成的场景
- 想统一调整 token 估算密度（例如中文工作流把 `charsPerToken` 调到 1.5-2），让状态行数字更接近真实计费

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7+ | 全部 SDK 依赖固定 `^0.1.0-rc.7`；同时声明了对 `rc.6` 的兼容回退（`ctx.webUiSettings` 缺失时回退到 `ctx.settingsScope`） |
| Node | >=22.19.0 | 仓库根 `package.json` 的 `engines` 字段：`^22.19.0 || >=24.0.0` |
| 运行平台 | Web | `dsh.client.platform: "web"`，仅在 Web 半区注册槽位，TUI/CLI 无等价物 |
| 原生模块 | 无 | 仅依赖 Runtime SDK，无 `node-gyp` 编译模块 |

## 安装方式
```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-live-stats
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `enabled` | 布尔 | 总开关，关闭后 host 侧投影折叠不会注册，TPS 行不再出现 | `true` |
| `charsPerToken` | 数字 | 一个 token 大致对应的文本字符数，调小会让估算 token 变大 | `4` |
| `blockOverhead` | 整数 | 每个内容块（文本/工具调用/工具结果等）分配的固定框架 token | `4` |
| `roleOverhead` | 整数 | 每条消息或助手响应分配的固定框架 token | `4` |

## 常见问题

**Q: 这个插件会增加每次请求的 token 消耗吗？**

A: 不会。插件只消费持久化事件流与投影数据，不注入提示段落、不注册工具、也不发送任何 session 事件，每个请求的 token 影响为零，对 KV 缓存也无影响。

**Q: 用 `charsPerToken=4` 估算中文是不是偏低？**

A: 是的。默认 4 字符/token 会低估中文（中文实际更密集），同时高估纯 ASCII 文本。可以在设置面板或 overlay 配置中调整 `charsPerToken`，中文密集场景建议调到 1.5-2 之间。

**Q: TPS 数字是怎么算出来的？为什么有时候不显示？**

A: TPS 由某个活跃步骤的输出 token 除以墙钟耗时得出，且遵循"常驻"策略：只要某个步骤测得过速率，状态行就会持续显示，在新步骤尚未产出或遇到无速率步骤时回退到最近测得值，避免闪烁。只有刚开始从未测得时才会不显示。

**Q: 估算值 `~` 什么时候会被替换成真实数据？**

A: `~` 表示启发式估算。当 provider 返回 `usage` chunk 或最终响应消息落地时，估算值会被真实用量替换；精确的缓存统计始终来自 DSH 自带的持久化 token 用量投影，不依赖本插件。

**Q: 它是 Web 限定还是所有客户端都支持？**

A: 目前是 Web 限定。TPS 状态行渲染在 DSH Web 的会话统计行内，暂无 TUI/CLI 等价物。安装时 `dsh.client.platform` 字段也固定为 `web`。

**Q: 怎么调整字符密度参数？配置文件在哪里？**

A: 推荐在 DSH Web 的插件设置面板里直接修改（一个 staging 表单绑到 `live-stats` 命名空间）。也可以在 `~/.dsh/config.yaml` 的 overlay 里加 `charsPerToken / blockOverhead / roleOverhead` 三个字段，保存即热加载。

**Q: 关闭插件后再开启需要重启吗？**

A: 不需要。设置面板的 enabled 开关或 overlay 配置变化时，宿主侧会销毁旧投影并按新参数重新注册投影折叠，下一次会话日志重放即生效，无需重启 `dsh web`。

## 上手难度
入门 — 安装即生效，零配置就能看到 TPS 与估算结果；进阶用户可在设置面板调密度参数。

## 已知问题与限制
- 估算为启发式：输入/输出总量在 provider 用量到达前为字符数估算（带 `~` 标记），精确缓存统计始终来自 DSH 自带的持久化 token 用量投影
- 仅 Web 端：TPS 行渲染在 DSH Web 的会话统计行内，暂无 TUI 等价物
- 单活跃步骤：投影每个会话只跟踪一个活跃步骤，并发会话各自拥有独立投影
- 字符密度假设：`charsPerToken=4` 会低估中文、高估纯 ASCII；估算偏差明显时需要按部署调整
- 没有平台原生模块：插件是纯 JS/TS，不引入 `node-gyp` 编译产物，但同时也只能依赖 DSH Web 这一种运行形态

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-harness-desktop](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-live-stats)
Wiki generated by AI (model: `MiniMax-M3`)