zjl1989-li/dsh-harness-zh-cn

dsh-harness-zh-cn

npm version
npm downloads
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 后，插件市场里各插件的英文描述会自动翻译成中文——先即时显示（词表兜底，不卡加载），后台用 LLM 批量翻译后自动刷新一次显示流畅中文，结果缓存（同一描述只翻一次，不重复消耗 token）
- ✅ 即插即用：作为普通 DSH 插件加载，卸载即还原

安装

方式一：npm 包（推荐）

npm install dsh-harness-zh-cn
或
pnpm add dsh-harness-zh-cn

方式二：从 GitHub 安装

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

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

npm install

启用

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

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

方式二：profile bundle 列表

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

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

方式三：cordis.patch.yml

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

- $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 使用：

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/ 目录，当前 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 事件 + 方法/参数/返回值） |

字典格式：

{
"包名:键名": {
"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: ...]、 等标记本身不动，仅译内部说明文字
- 代码标识符保留：工具名、参数名、${...}、{{...}}、反引号代码片段不译

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

发布

- npm: dsh-harness-zh-cn
- GitHub：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 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