@dsh-external/dsh-thinking-counter

Readme

# dsh-thinking-counter · 蓝色大肥鱼·智商鉴定中心

> 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web GUI 提供的 **Thinking 短语检测统计**插件。从开启时刻起，对**所有正在运行/新运行的会话（含子代理）**的 thinking（reasoning）内容做短语出现统计——「thinking 里 `let me` 出现了几次？有没有 `we should`、出现了几次？」。侧边栏「🐳 肥鱼智商」按钮点开小面板，一键放鱼/收鱼，检测词自由增删，并按**偷吃词/头脑大开词/吃瓜词**分组给出「肥鱼瞳孔检测」+「梁圣/梁子」参考判定。

![version](https://img.shields.io/badge/version-0.1.1-4f8ef7) ![license](https://img.shields.io/badge/license-MIT-9b59b6) ![platform](https://img.shields.io/badge/platform-DSH%20Web-00c2a8)

## ✨ 功能特性

| 功能 | 说明 |
|---|---|
| 🕐 **统计窗口** | 每次点「放鱼！」= 清零重开；开启前产生的消息一律不计；「收鱼！」冻结数字保留；「清空战绩，肥鱼失忆」手动清零（仅清统计，检测词保留） |
| 👥 **全会话覆盖** | host 全局监听 `session/event`，后台并行会话与子代理都被统计，按会话查看明细 |
| 🧮 **两类指标** | 思考块数（结构化 reasoning 块，跨流式 `assistant/chunk` 与最终 `assistant/message` 去重）+ 检测词命中次数（词表默认空、由用户自行添加） |
| 🔤 **大小写模式** | 每个词独立选择「区分大小写 Aa / 不区分 aa」，chip 徽标点击切换；跨 chunk 边界不丢，命中时记录上下文片段 |
| 🗂️ **检测词分组** | 每个词归属「吃瓜词（默认）/ 偷吃词 / 头脑大开词」三组，chip 直接拖动到别的鱼池调整；添加时可选择新词分组 |
| 🐳 **肥鱼瞳孔检测** | 独立醒目行（标题 + 进度条 + 判定）：**良% = 头脑大开词命中 ÷ 全部命中**；≥60% 梁圣附体 / 30–60% 肥鱼歪头 / <30% 梁子结下梁子（阈值在源码 `src/client/panel.ts` 中可自行调整；仅是关键词假设的参考信号，不代表真实智商） |
| 📊 **悬浮窗面板** | 点击页面其它区域不会消失；可按住标题栏移动、拖上/下边缘调整高度，▾ 可折叠成标题栏（位置/高度/折叠状态持久化）；肥鱼瞳孔检测按智商状态切换透明鲸鱼娘插画（低智商摸鱼 / 中等赶工 / 高智商庆祝）；含思考块 / 思考字符 / 总命中 / 会话数 + 三个鱼池的检测词命中 + 最近命中日志（定高滚动，词·会话·时间·片段）+ 会话鱼塘明细（含「正在思考」脉冲点）；分区可折叠，深浅主题自适应，带完整 hover/空状态反馈 |
| 💾 **配置持久化** | 浏览器 localStorage（`dsh.thinkingCounter.v1`）为快捷缓存；**权威存储 = DSH 插件专属数据空间 `~/.dsh/plugins/dsh-thinking-counter/config.json`**——host 重启/热重载从磁盘恢复，localStorage 丢失时浏览器自动从 host 回填，词表不丢 |
| 👁️ **可选可见文本** | 面板内「含可见文本」开关——默认只统计思考段内文本，开启后可见回复文本也纳入短语匹配 |

## 🐋 状态插画

「肥鱼瞳孔检测」会按当前智商判定展示一张透明鲸鱼娘插画。图片内置在 `assets/whale/`，运行中由 host 通过 `/thinking-counter/whale/*.webp` 同源静态路由提供，不依赖外网。

| 状态 | 判定 | 资源引用 | 预览 |
|---|---|---|---|
| 待机 / 无数据 | — | `assets/whale/idle.webp` | <img src="assets/whale/idle.webp" width="96" alt="待机"> |
| 低智商 / 摸鱼 | 良% < 30 | `assets/whale/slack.webp` | <img src="assets/whale/slack.webp" width="96" alt="摸鱼"> |
| 中等 / 赶工 | 30 ≤ 良% < 60 | `assets/whale/deadline.webp` | <img src="assets/whale/deadline.webp" width="96" alt="赶工"> |
| 高智商 / 庆祝 | 良% ≥ 60 | `assets/whale/celebrate.webp` | <img src="assets/whale/celebrate.webp" width="96" alt="庆祝"> |

素材来自 [Sutera-Diffusus/dsh-whale-musume](https://github.com/Sutera-Diffusus/dsh-whale-musume)（MIT），版权与许可见 [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)。

## 📐 架构

```
浏览器（client）                             host 半区（Node）
🐳 侧边栏按钮 → 可拖拽/调高悬浮窗            ctx.on('session/event') 全局监听
localStorage 快捷缓存 + host 磁盘权威存储     → 计数引擎（enabled 才记账）
轮询 snapshot(1.5s, 隐藏暂停) + SSE          → Map<sessionId, Counter>
POST config（放鱼/收鱼/检测词/清空）           → GET snapshot / SSE 信号
状态插画 <img>                                → GET /thinking-counter/whale/*.webp
```

- `src/counting.ts` — 纯函数计数引擎（滚动尾缓冲处理跨 chunk 匹配、`{turn}:{step}:{index}` 块去重、命中日志环形队列；事件按结构类型读取，避免 host 类型污染 client 类型图）
- `src/index.ts` + `src/routes.ts` — host 装配：全局监听、SSE 心跳、三条 API 路由 + 状态插画静态资源路由
- `src/client/` — 面板（纯 DOM，样式走 `--dsw-alias-*` 主题令牌 + 明暗兜底）

## 🚀 快速开始

### 前提

- 一个可运行的 **DeepSeek Harness (DSH)**（本插件是 DSH 插件，必须运行在 DSH 进程内），Windows / macOS / Linux 均可。
- **dsh 命令行**（一行安装时需要）：先 `npm install -g @deepseek-ai/dsh`，验证 `dsh --version`。
- 只想用现成功能 → 走**方式 A**，**不需要** Node / bash / DSH 源码检出；只有想改源码再构建的开发方式（方式 C）才需要那些。

### 安装

**方式 A：一行安装（推荐，Windows / macOS / Linux 通用，免构建）**

```bash
# 标准方式：从 npm 官方注册表安装
dsh plugin --profile web add @21hbguo/dsh-thinking-counter

# 不想用 npm 时，直接装 GitHub Release 包也一样
dsh plugin --profile web add https://github.com/21hbguo/dsh-thinking-counter/releases/latest/download/dsh-external-dsh-thinking-counter-0.1.1.tgz
```

然后**重启 dsh**（`dsh web` 或重启现有 dsh 进程），刷新浏览器即可。不用 git、不用 bash、不用 DSH 源码检出。

> Windows 用户：PowerShell / cmd 都支持上面的命令；若提示 `dsh: command not found`，先执行 `npm install -g @deepseek-ai/dsh`，然后**重开一个终端**再跑。

**方式 B：手动 bundle 装配（没有 dsh 命令行时）**

1. 从 [Releases](../../releases) 下载 `dsh-external-dsh-thinking-counter-0.1.1.tgz` 并解压（内含 `cordis.patch.yml`）。
2. 把解压目录放入 profile 的 node_modules：
   - Windows：`%USERPROFILE%\.dsh\profiles\web\node_modules\@dsh-external\dsh-thinking-counter\`
   - macOS / Linux：`~/.dsh/profiles/web/node_modules/@dsh-external/dsh-thinking-counter/`
   - 或将源码目录建 junction 指过去（Windows）：
     ```powershell
     New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\@dsh-external\dsh-thinking-counter" -Target "D:\path\to\dsh-thinking-counter"
     ```
3. 在 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 数组里加入 `"@dsh-external/dsh-thinking-counter"`。
4. 应用 `cordis.patch.yml`（插入插件行 id：`dsh-thinking-counter`），重启 DSH。

**方式 C：从源码构建（仅开发者 / 想改代码时需要）**

需要 **bash** 环境（Windows 用 Git Bash / WSL）+ 一份 DSH 源码检出：

```bash
git clone https://github.com/21hbguo/dsh-thinking-counter.git
cd dsh-thinking-counter
DSH_CHECKOUT=/path/to/dsh-source-checkout bash scripts/build.sh
```

构建产物按方式 B 装配，或把 `lib/` + `cordis.patch.yml` 一起打成 bundle tar 分发（即 Release 里的 tgz）。

### 验证

1. 安装并重启 DSH 后刷新 Web GUI。
2. 侧边栏底部出现 **🐳 肥鱼智商** 按钮（双行模式会显示聪明程度%与进度条）。
3. 点开面板 → 点击 **放鱼！**。
4. 添加想检测的词（如 `let me`、`we should`、`however`），偷吃/头脑大开词/吃瓜选一个鱼池。
5. 让任意会话运行一轮 thinking，回到面板即可看到思考块数、总命中、当场逮到摸鱼日志与「肥鱼瞳孔检测」判定；对应的鲸鱼娘状态插画会随判定自动切换。

### 排错表

| 现象 | 原因 | 解决 |
|---|---|---|
| `dsh: command not found`（Windows） | 未全局安装 dsh CLI | `npm install -g @deepseek-ai/dsh` 后重开终端再跑 |
| 侧边栏无 🐳 按钮 | 插件未装配，或未重启 DSH | 确认 bundle 行已装配；方式 A 后请**重启 dsh** 再刷新页面 |
| 面板启动后一直无命中 | 检测词为空，或没有产生 thinking 事件 | 手动添加检测词；确认 DSH 会话确实输出了 reasoning 内容 |
| 重启后统计数字归零 | 统计为运行期数据，host 重启清零 | 这是预期行为；配置（检测词/开关）会从磁盘恢复 |
| 面板配置丢失 | localStorage 被清或跨浏览器 | 浏览器会自动从 host 磁盘回填（`~/.dsh/plugins/dsh-thinking-counter/config.json`） |
| 多标签页数字互相覆盖 | 多 GUI 标签页共享 host 计数器，localStorage 后写覆盖 | 建议同时只保留一个控制面板标签页 |
| 方式 C 构建报 `cannot locate the dsh checkout` | 未设置 `DSH_CHECKOUT` 且常见路径无 DSH 检出 | `export DSH_CHECKOUT=/path/to/dsh-source-checkout` 后重跑；只装现成功能请直接走方式 A |

## 🗂️ API

| 端点 | 方法 | 说明 |
|---|---|---|
| `/api/thinking-counter/config` | POST | `{ enabled?, matchers?, matchVisible?, reset? }`，`matchers` 接受 `string`（=不区分、吃瓜）或 `{ pattern, caseSensitive?, group? }[]`（group: `neutral`/`negative`/`positive`，默认 `neutral`），返回最新快照 |
| `/api/thinking-counter/snapshot` | GET | 快照：totals / recentHits / sessions |
| `/api/thinking-counter/stream` | GET | SSE `data: changed`（500ms 节流 + 30s 心跳） |
| `/thinking-counter/whale/:file` | GET / HEAD | 状态插画静态资源（`idle.webp` / `slack.webp` / `deadline.webp` / `celebrate.webp`，`image/webp`） |

## ⚙️ 配置项

插件无独立设置页，运行时通过面板或 API 控制：

| 配置 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `enabled` | boolean | `false`（面板未启动） | 总开关；开启时才开始统计，再次开启会清零重开 |
| `matchers` | `(string \| MatcherObject)[]` | `[]`（词表默认空） | 检测词；`MatcherObject` = `{ pattern, caseSensitive?, group? }` |
| `matchVisible` | boolean | `false` | 是否把可见回复文本也纳入检测词匹配 |
| 聪明阈值 | number | `60` / `30` | ≥60% 梁圣附体、30–60% 肥鱼歪头、<30% 梁子；源码 `src/client/panel.ts` 中可改 |

持久化位置：

- 浏览器快捷缓存：`localStorage` 键 `dsh.thinkingCounter.v1`
- host 权威存储：`~/.dsh/plugins/dsh-thinking-counter/config.json`（旧版 `~/.dsh/dsh-thinking-counter.json` 会自动迁移）

## 🔐 安全说明

- **只统计本机 DSH 会话事件**：插件不读取文件内容、不接触 API key / token。
- **无遥测、无外联**：唯一的网络活动是浏览器向 DSH 同源端点拉取快照/SSE，不向任何第三方发送数据。
- **快照端点与 DSH Web 同源**：请勿把 DSH 直接暴露到公网。
- **匹配词仅存本机**：词表与统计配置保存在浏览器 localStorage 与 DSH 插件数据目录，不会上传。

## ❓ 常见问题

**Q：为什么放鱼后一直没有命中？**
三种常见原因：检测词是空的（默认空，需手动添加）；当前会话没有产生 thinking/reasoning 内容；放鱼之前产生的消息不计入（每次放鱼 = 清零重开）。

**Q：重启后统计数字会丢吗？**
数字会丢——统计是运行期数据，host 重启清零。但检测词、开关、含可见文本等配置会从插件数据空间恢复，浏览器会自动回填，所以不需要重新配词。

**Q：「肥鱼瞳孔检测 / 梁圣 / 梁子」是真的智商吗？**
不是。它只是「头脑大开词命中 ÷ 全部命中」的占比，是关键词假设的娱乐/参考信号；把它当乐子看就好，别当评测结论。

**Q：多开标签页会怎样？**
多标签页共享同一个 host 计数引擎，数字一致；但 localStorage 是后写覆盖，建议只保留一个面板标签页做控制，避免配置互相覆盖。

## 📄 License

[MIT](./LICENSE) © 2026 21hbguo