dsh-cot-en2cn

Readme

# dsh-cot-en2cn

DeepSeek Harness（DSH）的 Web 插件。模型用英文“思考”时，展开那个「思考」块，中文译文直接出现在原文下方；原文一个字节都不改。

```text
+-- 思考 -----------------------------------------------------------------
|  Let me check whether the settings service is mounted before calling
|  register on it, otherwise the row would throw.
|
|  | 中文译文 · deepseek/deepseek-chat            [重新翻译] [复制] [收起]
|  | 我先确认 settings 服务是否真的挂载了，否则注册这一行会抛错。
+------------------------------------------------------------------------
```

## 为什么需要它

在使用 DeepSeek、GLM、Gemini 等推理模型时，模型经常输出大段英文思维链（Chain of Thought）。对于中文母语用户，逐字阅读长篇英文思考过程非常耗费精力。

`dsh-cot-en2cn` 专为解决这个问题设计：
- **不修改任何会话数据**：原文保持原样，只在浏览器界面渲染一层译文面板。
- **不浪费 Token**：折叠的思考块不翻译；原文本来是中文直接跳过；已翻译内容双端缓存。
- **零运行时依赖**：不引入任何第三方 npm 包，仅使用 Node.js 内置模块。

## 系统要求

- DSH `>=0.1.0-rc.5`
- Node.js `>=20`

## 安装与生效

### 从 GitHub 安装（推荐）

```bash
dsh plugin --profile web add github:Eyeing0721/dsh-cot-en2cn
```

国内网络如果卡在下载那一步，先给当前终端设好代理再执行：

```powershell
$env:HTTPS_PROXY = 'http://127.0.0.1:7897'
```

### 从本地目录安装（开发 / 自用）

```bash
dsh plugin --profile web add /path/to/deepseek-cot-en2cn
```

> 注意：使用本地目录（link 方式）安装时，源目录不可删除或移动，否则插件会失效。

安装完成后，**重启 `dsh web`**，刷新浏览器页面即可生效。

### 卸载

```bash
dsh plugin --profile web remove dsh-cot-en2cn
```

卸载后，配置文件仍会保存在 storages 目录下，不会丢失。

## 实际行为与使用方式

1. **界面交互**：展开任意「思考」块，中文译文直接渲染在思考原文正下方。译文左侧带有一条竖线，顶部小字清晰展示所用模型、是否命中缓存以及耗时。右上角提供三个操作按钮：`重新翻译`、`复制`、`收起`。
2. **触发机制**：
   - 处于折叠状态的思考块**绝不翻译**，不产生模型调用。
   - 展开思考块时，若模型仍在流式输出，默认等待其思考结束后再翻译，期间显示“模型还在思考，结束后自动翻译…”。
   - 原文为中文时**直接跳过**，不发起请求。
3. **分块与缓存**：长文本会自动按段落、换行或句子边界分块（默认 3000 字符/块）并逐块缓存。服务端默认缓存 600 条，浏览器端同步缓存。二次展开或刷新页面均不会重复调用模型。
4. **控制面板**：进入 **设置 → 插件 → 「CoT 英文转中文」** 即可打开配置面板。面板内包含运行状态卡片（当前模型路由、缓存命中数、调用次数、最近一次调用耗时、最近一次错误、配置文件路径）、基础开关、模型选择（提供“拉取模型列表”与“用默认模型”按钮）、高级参数调整、清空缓存、恢复默认，以及一个可以直接贴英文进行效果测试的“试译”文本框。

## 设置项

配置文件路径：`$DSH_HOME/storages/cot-en2cn/config.json`（不放在 `settings.yaml` 中，不依赖 schema 库）。手动修改该文件是安全的，所有配置项在载入时都会经过校验并夹紧至合法范围。

| 界面上的名字 | 默认值 | 含义 |
|---|---|---|
| 启用 CoT 中文翻译 | 开 | 总开关。关掉后所有译文面板立即消失，原文不受影响。 |
| 展开时自动翻译 | 开 | 关掉后每块思考需要手动点「翻译这段思考」。 |
| 思考过程中也翻译 | 关 | 模型还在流式输出时就翻译（会重复调用模型，更费 token）。 |
| Provider / 模型 | 空 | 留空 = 跟随 DSH 默认模型。两者要么都填、要么都留空。翻译是纯体力活，建议选便宜快的小模型。 |
| 关闭思考（推荐） | 开 | 把翻译请求走 DSH 的辅助请求通道（`purpose: session-title`），让这次调用不产生思考 token。注意：**只有 DeepSeek 官方适配器认这个映射**；用 pi-ai 之类 OpenAI 兼容中转时这一项等于空操作。 |
| 目标语言 | 简体中文 | 还可选 繁體中文 / English / 日本語。 |
| 单块字符数 | 3000 | 超过就分块翻译，逐块缓存。调小更稳（不容易被 max-tokens 截断），但请求数变多。 |
| 并发请求数 | 2 | 同时进行的模型请求数。 |
| 单次超时 | 120 秒 | 单次模型请求的截止时间。 |
| 服务端缓存条数 | 600 | 按"块"缓存译文。 |
| 跳过已是中文的思考 | 开 | 原文本来就是中文时直接跳过，不调用模型。 |
| 译文文字大小 | 13px | 只影响译文面板。 |

## 原理与安全性保证

插件采用双端架构：
- **宿主端（lib/index.js）**：注册六条本地同源路由：
  - `GET /dsh-cot-en2cn/state`
  - `PUT /dsh-cot-en2cn/config`
  - `POST /dsh-cot-en2cn/translate`
  - `GET /dsh-cot-en2cn/providers`
  - `GET /dsh-cot-en2cn/models`
  - `POST /dsh-cot-en2cn/cache/clear`
  翻译请求通过 DSH 的 `ctx.llm.stream()` 发起，复用用户在 DSH 中既有的模型渠道与凭据。翻译接口与配置接口严格限制仅接收本机（`127.0.0.1`）且同源的请求。
- **浏览器端（lib/client.js）**：利用 `MutationObserver` 监听对话视图，寻找带有 `data-variant="think"` 属性的思考节点（带类名兜底），在思考正文下方动态插入独立的译文 DOM。

为什么不做成官方插槽：DSH 的 slot 系统未提供针对“单块思考”的细粒度位置，若替换 `conversation.chat.node` 会强行覆写整个 assistant 渲染器，改动过重，因此采用只做 DOM 增强的实现方式。

由此提供三项确定性保证：
1. **绝不污染会话数据**：插件不写会话日志，会话记录、轨迹（Trajectory）视图、KV cache、上下文压缩完全不受影响。
2. **零副作用**：随时停用插件，界面恢复原生状态，不留痕迹。
3. **优雅降级**：若未来 DSH 调整了思考块的 DOM 结构，插件仅安静地不显示译文，绝不会破坏宿主页面的正常渲染。

## 隐私与调用开销

- **不触碰 API Key**：插件不包含、不索取、不存储任何 API Key，所有调用完全基于宿主已配置的通道。
- **按需消耗**：折叠不翻、中文跳过、切块复用。并发请求控制在阈值内（默认 2），单次超时受控（默认 120 秒）。
- **完全本地**：无外部数据上报，所有逻辑均在本地 Node.js 进程与浏览器之间完成。

## 常见问题 (FAQ)

**Q: 展开思考块后没有出现译文？**
A: 请按顺序排查：
1. 设置面板中的「启用 CoT 中文翻译」总开关是否处于开启状态；
2. 该思考块是否仍处于流式生成中（默认策略会等待思考完成后自动触发）；
3. 思考原文是否本来就是中文（插件会自动跳过中文内容）；
4. 查看译文位置是否有报错提示信息，如网络超时等。

**Q: 界面提示“没有可用的模型路由”？**
A: DSH 尚未配置默认模型，或者插件设置里的 Provider 与 模型 名称仅填写了其中一项。两者必须同时填写或同时留空。

**Q: 提示输出被 max-tokens 截断？**
A: 思考文本较长时，可以在设置中将「单块字符数」调小（例如调整为 1500）。

**Q: 译文会记录在轨迹（Trajectory）视图里吗？**
A: 不会。插件仅在 Web 对话视图的思考块后插入临时渲染节点，不进入轨迹记录。

**Q: 会与其它 Web 插件冲突吗？**
A: 不会。插件不占用任何 slot 插槽，不替换既有渲染器。译文面板内按钮的点击事件均在捕获阶段拦截，不会误触发宿主思考块的展开或折叠。

## 质量保证

项目内置 83 项自动化测试，无第三方测试框架依赖，执行命令即可运行：

```bash
npm test
```

测试覆盖清单：
- `tools/smoke.mjs` (33 项)：验证长文本分块可逆性（分块重组后与原文逐字节一致）、中文检测启发式、缓存读写、并发控制、重复请求去重、失败类型归因、配置夹紧边界及包清单契约。
- `tools/host-integration.mjs` (14 项)：通过模拟 cordis 运行时挂载真实路由，验证状态获取、翻译处理、配置持久化及越权请求拦截。
- `tools/parity-check.mjs` (5 项)：比对插件内部封装的消息体与 DSH 原生 `createUserMessage`，确保参数逐字段对齐。
- `tools/browser-check.mjs` (31 项)：在 Headless Chrome 中加载真实的 `lib/client.js`，验证折叠不译、流式等待、中文跳过、单次请求去重、DOM 点击事件冒泡阻断、总开关关闭即时隐藏以及配置面板渲染逻辑。

## 目录结构

```text
dsh-cot-en2cn/
├── lib/
│   ├── index.js              # 宿主端：配置读写 + 六条同源路由
│   ├── engine.js             # 翻译引擎：分块缓存、并发闸门、超时、失败归类
│   ├── text.js               # 分块与中文检测（纯函数）
│   ├── config.js             # 默认值与校验夹紧
│   ├── store.js              # $DSH_HOME/storages/cot-en2cn/config.json 原子读写
│   ├── languages.js          # 目标语言表
│   └── client.js             # 浏览器端：DOM 监听、译文面板、设置面板
├── tools/
│   ├── browser-check.mjs     # 浏览器端无头集成测试
│   ├── host-integration.mjs  # 宿主路由与上下文集成测试
│   ├── parity-check.mjs      # 消息契约比对测试
│   └── smoke.mjs             # 单元与冒烟测试
├── cordis.patch.yml
├── package.json
├── README.md
├── README.en.md
└── LICENSE
```

## 许可证

[MIT](LICENSE)