dsh-harness-zh-cn

Readme

# dsh-harness-zh-cn

[![npm version](https://img.shields.io/npm/v/dsh-harness-zh-cn.svg)](https://www.npmjs.com/package/dsh-harness-zh-cn)
[![npm downloads](https://img.shields.io/npm/dm/dsh-harness-zh-cn.svg)](https://www.npmjs.com/package/dsh-harness-zh-cn)
[![License](https://img.shields.io/npm/l/dsh-harness-zh-cn.svg)](LICENSE)

**DeepSeek Harness 中文汉化插件** —— 在运行时把 DSH 的全部系统提示词、工具描述、运行时上下文，以及**前端 UI 文本**翻译成中文。

这是一个**纯运行时**插件，分**宿主半**与**客户端半**两部分，均通过 DSH 的公开扩展点工作，**不修改任何 DSH 源码**；卸载插件即完全还原英文：

- **宿主半**：通过 `system-prompt/assemble` 瀑布钩子，在每次组装提示词后把模型可见的英文文本替换为中文；并 patch `commands.list`，汉化斜杠命令菜单的描述。
- **客户端半**：patch `ctx.locale.lookup`（`t()` 标签的底层实现）让所有命名空间的 `zh` 词典生效；拦截 `/api/market/list` 汉化插件市场描述；patch `ctx.remote.commands.list` 汉化命令菜单描述。

当前内置 **1814 条翻译**，覆盖系统提示 sections、运行时上下文、全部工具描述与参数描述、cordis 完整 API 目录（55 服务 + 56 事件），以及前端 UI 的 `t()` 标签与命令菜单描述。

## 特性

- ✅ **零源码修改**：不碰 `node_modules`，升级 DSH 后依然有效
- ✅ **覆盖面广**：系统提示 sections、运行时上下文 contexts、工具描述与参数描述、cordis API 目录、前端 UI 标签、命令菜单描述全部汉化
- ✅ **协议安全**：`[exit code: N]`、`[killed by signal: X]`、`[sandbox: ...]`、`[stderr]` 等被 DSH 或前端解析的机器协议标记**保留原样**，不破坏下游解析
- ✅ **可开关**：`sections / contexts / tools` 三类翻译可分别关闭
- ✅ **前端 UI 汉化**：patch `ctx.locale.lookup` 让所有命名空间的 `zh` 词典在 `t()` 标签上生效——包括 composer 的 `+` 按钮、斜杠菜单的分组标题与周边文案，无需改动 DSH 前端代码
- ✅ **命令菜单汉化**：host 半 patch `commands.list`、client 半 patch `ctx.remote.commands.list` 双保险，把 `+` 菜单里各命令的英文描述翻译成中文；命令**名称保持英文**（它是 `/goal` 解析、派发与模糊匹配依赖的标识符），且命令是否展示由 DSH 按"是否在行首 / 是否带参数"正常过滤，汉化不改变行为
- ✅ **插件市场描述翻译**：安装 [dsh-plugin-marketplace](https://github.com/AwesomeHou/dsh-plugin-marketplace) 后，插件市场里各插件的英文描述会自动翻译成中文——先即时显示（词表兜底，不卡加载），后台用 LLM 批量翻译后自动刷新一次显示流畅中文，结果缓存（同一描述只翻一次，不重复消耗 token）
- ✅ **即插即用**：作为普通 DSH 插件加载，卸载即还原

## 安装

### 方式一：npm 包（推荐）

```bash
npm install dsh-harness-zh-cn
# 或
pnpm add dsh-harness-zh-cn
```

### 方式二：从 GitHub 安装

```bash
npm install git+https://github.com/zjl1989-li/dsh-harness-zh-cn.git
```

### 方式三：本地开发（直接引用本仓库）

```bash
npm install <本仓库路径>
```

## 启用

### 方式一：UI 插件管理（推荐）

在 DSH Web GUI 的 **设置 → 插件管理** 中添加 `dsh-harness-zh-cn`，重启后生效。UI 会正确登记 bundle 并持久化配置。

### 方式二：profile bundle 列表

在 profile 的 `package.json` 的 `dsh.profile.bundles` 列表中加入（`cordis.yml` 是自动生成文件，请勿直接编辑）：

```json
{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-harness-zh-cn"
      ]
    }
  }
}
```

### 方式三：cordis.patch.yml

在 DSH profile 的 `cordis.patch.yml` 中追加插件条目：

```yaml
- $plugin: dsh-harness-zh-cn
  config:
    includeSections: true
    includeContexts: true
    includeTools: true
```

重启 DSH 后生效。**无需改动任何 DSH 源码。**

## 配置

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `includeSections` | boolean | `true` | 翻译系统提示词 sections（身份、工具指导等） |
| `includeContexts` | boolean | `true` | 翻译运行时上下文 contexts（沙箱策略、审批策略、委托声明等） |
| `includeTools` | boolean | `true` | 翻译工具描述与参数描述 |
| `verbose` | boolean | `false` | 调试日志 |

## 工作原理

DSH 在每次模型请求前通过 `ctx.systemPrompt.assemble()` 组装提示词，组装过程会触发 `system-prompt/assemble` 瀑布事件。本插件在该瀑布的 `next()` 之后：

1. 遍历 `assembly.sections`，将每个 section 的 `text` 经 `translate()` 汉化；
2. 遍历 `assembly.contexts`，汉化每个动态上下文文本；
3. 遍历 `assembly.tools`，汉化工具 `description` 并递归汉化 `parameters` 中的 `description` 字段。

`translate()` 使用 `dict/` 目录下的 JSON 字典，匹配顺序：

1. **精确匹配**：整句文本与字典 `en` 完全一致时直接替换；
2. **空白折叠匹配**：将连续空白折叠为单个空格后比较，容忍源码拼接处的空格差异（如 `base + background` 的边界）；
3. **模板正则**：对含路径、数字、模式名等动态部分的文本，用 `template: true` 条目做整体正则替换（`$1`、`$2` 引用捕获组）。

机器协议标记与代码标识符一律保留。

### 客户端 UI 汉化（额外能力）

本插件带一个 **client 半**（浏览器端），其 `apply(ctx)` 会收到真正的客户端根 Context，在**只读扩展点**上做三件事（卸载即还原，均不修改 DSH 前端源码）：

1. **`t()` 标签汉化**：patch `ctx.locale.lookup`（LocaleRuntime 实例方法，是每个 `t()` 标签的底层实现），让任何自带 `zh` 词典的命名空间的 `zh` 翻译**优先生效**——包括 composer 的 `+` 按钮、斜杠菜单的分组标题与周边文案，不动当前 locale 也不改 boot-once 的 locale 面孔。
2. **命令菜单描述汉化**：patch `ctx.remote.commands.list` 的 getter，把每个斜杠命令描述符里**仅用于展示的** `description` 翻译成中文；命令 `name` 保持不变（它是 `/goal` 式解析、派发与模糊匹配依赖的标识）。内置精确翻译表覆盖 `/compact` `/export` `/goal` `/feedback` `/permission` `/plan`，未命中表项则后台用 LLM 翻译并写入 `localStorage` 缓存、下次打开即中文（不阻塞首次渲染）；并通过 `commands/change` 失效已缓存列表，让菜单始终以中文重拉。
3. **插件市场描述翻译**：拦截 `window.fetch` 对 `/api/market/list` 的响应（详见下节）。

> 说明：命令菜单的 7/3 切换是 DSH 的正常交互——**输入框为空**（命令在行首）时显示全部命令，**输入框有内容**时只显示不带参数的命令、隐藏需要吃整行参数的命令（`/goal`、`/feedback`、`/permission`、`/plan`）。这与汉化无关，插件不改变该行为。

### 插件市场描述翻译（额外能力）

本插件还带一个 **client 半**（浏览器端），配合 [dsh-plugin-marketplace](https://github.com/AwesomeHou/dsh-plugin-marketplace) 使用：

1. **拦截** `window.fetch` 对 `/api/market/list` 的响应；
2. **即时显示**：英文描述先用内置词表就地翻译（不阻塞列表渲染）；
3. **LLM 批量翻译**：后台调用本插件注册的 `POST /api/harness-zh/translate` 端点（用部署默认模型，一次调用翻译一批），结果写入 `localStorage` 缓存并**自动刷新一次**显示流畅中文；
4. **缓存复用**：同一描述只翻译一次，之后打开直接命中缓存，不重复消耗 token。

> 该翻译端点为插件自注册（`/api/harness-zh/translate`），不修改 dsh-plugin-marketplace 源码；LLM 不可用时自动回退到词表翻译。

## 翻译字典

所有译文集中存放在 [`dict/`](./dict) 目录，当前 5 个字典共 **1814 条**：

| 字典 | 条目数 | 覆盖内容 |
| --- | --- | --- |
| `core.json` | 28 | 身份行、沙箱/审批策略、委托声明、工作区指令、GUI/检出说明 |
| `tools-fs-bash.json` | 39 | read/write/edit/bash 工具与参数 |
| `tools-fs-core.json` | 221 | pwsh/fs/cordis 工具、plan-mode、sandbox 等 |
| `tools-web-jobs-goal.json` | 285 | web/jobs/goal/ralph/workflow/subagent 等 |
| `cordis-api.json` | 1241 | cordis 完整 API 目录（55 服务 + 56 事件 + 方法/参数/返回值） |

字典格式：

```json
{
  "包名:键名": {
    "kind": "section | context | tool | param | render | command | const",
    "en": "英文原文（整句），或模板正则（当 template: true）",
    "zh": "中文译文，模板中可用 $1、$2 引用捕获组",
    "template": true
  }
}
```

### 收录规范

- **只收模型可见文本**：经工具输出、结果渲染、停止原因错误回传给模型的完整句子；纯内部校验/配置错误不收
- **动态纯数据字符串不收**：如 job_list 行格式、presentCall 直接显示的标题
- **术语统一**：agent→代理、job→任务、session→会话、provider→提供方、fiber→纤程
- **机器协议原样保留**：`[status: ...]`、`[exit code: N]`、`[sandbox: ...]`、`<system-reminder>` 等标记本身不动，仅译内部说明文字
- **代码标识符保留**：工具名、参数名、`${...}`、`{{...}}`、反引号代码片段不译

欢迎通过 PR 补充或修正译文。

## 发布

- **npm**: [dsh-harness-zh-cn](https://www.npmjs.com/package/dsh-harness-zh-cn)
- **GitHub**: [zjl1989-li/dsh-harness-zh-cn](https://github.com/zjl1989-li/dsh-harness-zh-cn)

## 版本发布策略

为避免频繁发布冗余版本，遵循以下约定：

- **功能/修复攒够一批**：同一主题的改动（如"市场描述翻译"的多个小修复）合并为**一个版本**发布，不逐个小改动发布
- **本地验证通过后再发**：发布前必须在运行中的 DSH 部署验证（插件加载、端点响应、翻译效果），确认无回归
- **语义化版本**：破坏性/大功能 → minor（0.x.0）；修复/小改进 → patch（0.x.y）；不因 README、元数据等非功能性改动单独发版
- **版本间隔**：两次发布之间至少间隔一个完整的验证周期；紧急修复除外
- **旧版本**：被替代的早期版本用 `npm deprecate` 标记（不删除，符合 npm 生态惯例）

> 历史教训：早期 0.1.0–0.2.2 在 2 小时内发布 6 个版本，多为逐个小改动发布，属冗余行为，已通过 deprecate 0.1.x 修正并在此固化策略。

## 社区收录

本插件已通过 GitHub [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic 加入 DSH 社区插件生态：

- **dsh-plugin-marketplace**（设置 → 插件 的市场标签页）：实时同步 `dsh-plugin` topic，仓库已自动收录，用户可直接搜索 `harness-zh` 一键安装
- **awesome-dsh-plugin**：符合收录要求（`dsh.bundle` manifest + `cordis.patch.yml`），可提交 PR 加入精选列表
- **awesome-deepseek-harness**、**dshfind** 等社区列表均可提交

## 许可证

MIT