# dsh-token-attention — Token Check · 词元管理（DeepSeek Harness 插件）

[English README](README.md) | 中文

**Token Check（词元管理）** 是 [DeepSeek Harness](https://github.com/deepseek-ai/dsh)（DSH）的 token 注意力管理面板。它按 **任务 / 日 / 周 / 月** 记录每一次对话的 token 消耗（输入命中 / 未命中 / 输出 / 推理）与估算费用，识别任务类型，并结合 DeepSeek 峰谷计价与 DSH 上下文机制，告诉你**什么时候适合跑任务、该不该换对话、要不要写 hand-off 文件**。

它不是省钱工具：不会强制节流、不会自动砍请求——只**如实呈现 + 给出建议**，决定权在你。

## 功能特性

- **设置内五视图面板** — 总览 / 会话 / 任务 / 费用 / 设置
- **任务级台账** — token 消耗（输入命中 / 未命中 / 输出 / 推理）与估算费用，按日 / 周 / 月聚合
- **任务类型识别 + 建议引擎** — 执行时机、换对话、hand-off、上下文、费用、模型六类建议
- **注意力 KPI** — 注意力评分、命中率、上下文占用、压缩次数（按会话）
- **峰谷计价** — DeepSeek 空闲半价窗口（高峰 9:00–12:00 / 14:00–18:00），按桶拆解费用构成
- **多模型细分** — 按模型拆分费用与命中率（如 deepseek-v4-flash / pro / grok）
- **台账导出** — Markdown / CSV 下载，hand-off 模板一键生成
- **设置可编辑** — 单价表、峰谷时段、建议阈值，保存后新记录即时按新配置计价
- **零运行时依赖** — 本地 SQLite（`node:sqlite`），无任何网络调用

## 界面预览

**总览** — 今日消耗 / 费用 / 命中率 / 注意力评分 / 模型构成 / 建议卡 / 趋势

<img src="docs/screenshots/1-overview.png" alt="总览" width="760">

**会话卡** — 单会话模型拆解与注意力指标

<img src="docs/screenshots/2-session.png" alt="会话卡" width="760">

**任务视图** — 任务台账，支持 Markdown / CSV 导出

<img src="docs/screenshots/3-tasks.png" alt="任务" width="760">

**费用视图** — 峰谷拆解、费用杠杆拆解、模型对比

<img src="docs/screenshots/4-cost.png" alt="费用" width="760">

**设置视图** — 单价表、峰谷时段、建议阈值

<img src="docs/screenshots/5-settings.png" alt="设置" width="760">

## 安装

发布到 npm 后，一条命令安装：

```sh
dsh plugin --profile web add dsh-token-attention
```

重启 DSH 后，在 **设置 → 词元管理** 打开面板；数据落在 `DSH_HOME/token-attention/token_records.db`。

### 开发期（link 方式）安装

```sh
npm install && npm run build
```

然后在 web profile（`%APPDATA%\dsh-desktop\harness\profiles\web\package.json`）注册插件：

```json
{
  "dependencies": { "dsh-token-attention": "link:/path/to/dsh-token-attention" },
  "dsh": { "profile": { "bundles": ["...", "dsh-token-attention"] } }
}
```

在 `profiles\web` 目录执行 `pnpm install`，重启 DSH，验证：

```sh
curl http://127.0.0.1:<端口>/token-attention/api/health   # → {"ok":true,...}
```

## 工作原理

- **采集**：node 半区订阅 DSH 的 `session/event` 事件流（usage / goal / subagent / compaction / turn），归一化后写入 SQLite；启动时用 `last_seq` 游标增量回放既有会话（幂等）。
- **聚合**：每小时增量聚合到 `daily_agg`，每日全量重算校正。
- **官方投影适配（可选借用）**：base 层挂载 `session-projection` + `token-meter` + `session-stats` 时，会话卡的「上下文占用」优先读 `contextPressure.projectedTokens`（对压缩即时响应、容量取官方值），「轮次 / 步数 / LLM / 工具 / 解码」统计优先读 `sessionStats`（与 DSH 内置统计条同源）；未挂载时自动回退到自有计算，无任何额外依赖。
- **建议**：`src/shared/advice.ts` 依据上下文占用、轮次、命中率、费用与模型构成，对照你的阈值给出可执行建议。

## 配置项

面板中可编辑并保存到 SQLite：

| 配置 | 默认值 |
|---|---|
| 模型单价（元 / 百万 tokens · 空闲价） | flash：命中 0.05 / 未命中 1.5 / 输出 4.5 |
| 峰谷时段（24h，含 start 不含 end） | 9–12、14–18 |
| 上下文占用建议阈值 | 70% |
| 轮次建议阈值 | 40 |
| 命中率下限建议阈值 | 40% |

## 开发与验证

```sh
npm run typecheck   # tsc --noEmit
npm run check       # node --check src/client/index.js
npm run build       # tsc 编译 dist/
npm run selftest   # 采集层自测（幂等 / 峰谷计价 / 聚合校正断言）
npm pack            # 产出发布 tarball
```

## 卸载

在 DSH 设置 → 插件中卸载（或从 profile 的 `package.json` 移除依赖与 bundles 条目）。
数据目录 `DSH_HOME\token-attention\` 可手动删除；`dispose` 会自动清理定时器与 SQLite 连接。

## 许可

[MIT](LICENSE) © 2026 Young4ever33