前言¶
DSH 的官方客户端只把 6 个错误码本地化成中文，其余报错一律原样透传英文。日常开发里碰到的错误大多是英文，有些还会让会话直接断流、只剩一句没头没尾的字符串。要找这些错误的原因，只能靠自己搜日志、猜上下文，或者去比对官方错误码表。
dsh-error-gloss 就是解决这件事的客户端插件：它不改内核，不改报错原文，只在官方报错行下方加一行中文释义，并把原因分「确定 / 可能 / 未验证」三档来讲。下面介绍它的覆盖范围、设计原则、安装方式和适用边界。
这是什么¶
- 名称：dsh-error-gloss
- 维护者：chenmianmian19977-glitch（GitHub 显示作者名「一碗大灌面」）
- 版本：0.1.0（
package.json与索引index.json均为 0.1.0） - 仓库：https://github.com/chenmianmian19977-glitch/dsh-error-gloss
- 目录页：https://www.skillhub.cn/plugins/chenmianmian19977-glitch/dsh-error-gloss
- 星标：0（GitHub API 实时数据，仓库创建于 2026-11-05）
- 许可：代码 / 词典 / 构建脚本为 MIT；界面内的角色形象与首图为 CC BY-NC-SA 4.0
定位一句话：给 DeepSeek Harness 的每一条报错加一行中文释义，40 条词条覆盖全部官方错误码。
它只做客户端侧的事：通过官方公开扩展点往界面投影层注入注解。英文原文、原始 code 标签、官方原有报错行全部完整保留，不替换、不遮挡。带注解的报错显示效果如下，官方报错行原样在上，中文注解另起一行挂在下方：
本轮运行失败 pi-ai detected context overflow for model "trae-cn/deepseek-v4.1-flash" [CONTEXT_WINDOW_EXCEEDED]
【上下文窗口超限】本次请求携带的内容超过模型可用上下文，本轮已停止。 · 建议：新建会话，把长材料拆成几段 展开详情
展开「展开详情」之后有六段内容：原文、释义、原因（带可信度）、影响、建议、依据，仍是原文优先。
覆盖范围¶
词条共 40 条，分两层。
1、精确词条 29 条，每个码一条，含具体释义与建议，覆盖上下文溢出、6 条压缩失败分支、认证 / 额度 / 限流、密钥、图片、超时、中止、子任务续跑等。
2、码族词条 11 条，覆盖 TEAM_*、GOAL_*、ASK_*、SESSION_*、ATTACHMENT_*、WEB_*、SANDBOX_*、ACTIVATION_*，以及模型适配器、授权流程、工具调用。
官方码这一侧零未收录。唯一还会显示「原因未验证」的，是服务端自己写的自由文本（例如 INVALID_REQUEST 的详情），这类文本没有码、无法枚举，插件的做法是保留原文、只加中文释义，不猜原因。
三条设计原则¶
按 code 路由，不解析文案。 官方 HarnessError 的注释本身写得很直白：route on this, never by parsing message。适配器措辞随时会变，码相对稳定。匹配顺序是：精确码 → 码族 → 文案模板 → 兜底。
原因分三档，不确定就说不确定。 三档的组合方式如下。
| 档 | 界面表现 | 用在哪 |
|---|---|---|
| 确定 | 原因：因为 …（附依据） | 码的直接含义，如「压缩被取消」 |
| 可能 | 可能原因：…（需结合 token 用量判断） | 需要上下文才能判定的，如上下文溢出 |
| 未验证 | 原因未验证 —— 这条文案来自服务端 | 自由文本、码族（只知道属于哪个模块） |
码族词条一律是 forbidden。它只回答「这属于哪个功能模块、跟模型 / 网络有没有关系」，具体原因让你回到原文看。宁可说「不知道」，也不给一个假的归因。
任何异常都不许影响宿主。 客户端插件的 apply() 抛错会让整个 DSH 起不来。插件的每一步注册都单独兜异常，注册失败只记账、并在设置页用红框显示，绝不冒泡。
安装¶
这个包没有发布到 npm，当前方式是从 GitHub 装。仓库里已经带了构建好的 client/bundle.js，安装时不需要编译、不需要 npm install，也没有任何运行时依赖。
用插件管理器从 GitHub 装：
dsh plugin --profile desktop add https://github.com/chenmianmian19977-glitch/dsh-error-gloss
也可以直接给 tarball 地址，跳过 git clone，更快：
dsh plugin --profile desktop add https://github.com/chenmianmian19977-glitch/dsh-error-gloss/archive/refs/heads/main.tar.gz
卸载：
dsh plugin --profile desktop remove dsh-error-gloss
不用插件管理器的话，走手动安装脚本：
git clone https://github.com/chenmianmian19977-glitch/dsh-error-gloss
cd dsh-error-gloss
node tools/install-local.mjs # 拷进 profile + 追加 bundles + 装载预检
node tools/uninstall-local.mjs # 一键回退
两个脚本都幂等，装坏了可以退干净。
第三种是通过「发现」页安装。DSH 的插件市场不是中心化商店，而是一组索引源：每个源是一个 format: 1 的 JSON，Host 负责抓取与校验，「发现」页负责展示。仓库自带一份索引，校验器 @deepseek-ai/dsh-plugin-market-index 已验证通过。步骤是：插件 → 发现 → 添加索引源，粘贴下面这个地址：
https://raw.githubusercontent.com/chenmianmian19977-glitch/dsh-error-gloss/main/index.json
列表里出现「报错中文注解」，点安装即可。若「发现」标签页不存在，路径是：插件页 → 实验性插件 → 更多 → 启用「自定义插件市场」。索引源是你自己加的，装什么由你决定，界面上那句「索引由第三方提供」是真的。
装完确认¶
设置页路径是 设置 → 报错中文注解。这里能看到版本、已加载词条数、命中计数，还有一个「自测」按钮：点一下用内置样本渲染一条完整注解，零请求、零模型调用，用来确认装上了。
命中计数适合用来核对词条是否真的覆盖到了你遇到的码，而不是只是装上了。
自己改词条¶
词典是纯数据，放在 catalog/entries/*.json，一条一个文件。改完按下面三步重建：
node tools/build-client.mjs # 打包
node src/selftest.mjs # 引擎自检
node client/bundle-test.mjs # 客户端装载
用户级覆盖放在 ~/.dsh/error-gloss.user.json，按 id 做字段级合并。其中 causeAssertion 是单向锁定：你可以把「确定」降级成「可能」，不能反过来。这个设计等于强制留一个「不能悄悄把不确定写成确定」的口子。
隐私与兼容性¶
隐私方面声明为零遥测、零模型调用、零网络出口：注解全部来自本地词典，不会为了翻译报错再发一次请求；插件不发起任何网络请求；注解只进界面投影层，不改动 transcript。进入日志的内容会先过一遍脱敏，覆盖密钥、Bearer、UUID、request_id、绝对路径、手机号。
兼容性方面，插件面向 DeepSeek Harness 0.2.1-rc.2 实测，只用官方公开扩展点：dsh.client 清单、ctx.locale.register、ctx.slots.inject / ctx.slots.register，零内核改动、零 fork。词典条目各自带 dshVersionRange，跨版本的词条会被标 stale 并跳过，不会拿旧文案套新报错。
适用场景与注意¶
适合两类人。一类是日常用 DSH 客户端跑智能体、希望报错直接能看懂的开发者；另一类是维护 DSH 插件或二次开发、想统一团队报错解释口径的人，词典是纯 JSON，改起来成本低。
需要留意的地方：
1、这是客户端插件，注解依赖宿主客户端的界面投影层。如果用的是非客户端场景（纯 Host / 命令行），注解未必会被渲染出来。
2、插件以当前 DSH 进程的权限运行。安装前先翻一遍源码，确认注册逻辑和脱敏规则符合你的预期，再决定要不要装。
3、许可证分两层：代码、词典、构建脚本是 MIT；界面里的「大肥鱼」角色形象与首图（client/assets/、client/icon.png、assets/）是 CC BY-NC-SA 4.0，作者声明该形象不可以任何形式商业化。商业场景使用的话，删掉这两个资源后重新运行 node tools/build-client.mjs，插件会回落到原创的鲸尾徽章（纯 SVG），代码部分仍是 MIT。完整范围和 Takedown 流程见 PROVENANCE.md。
4、项目与 DeepSeek 官方无关，未包含也未修改任何官方代码，详见 NOTICE.md。社区目录页属于独立站点收录，不是官方应用商店。
小结¶
dsh-error-gloss 的价值不在于把报错重新写一遍，而在于在保留原文的前提下补上中文释义和可执行建议，并用三档原因处理「不确定」这件事。对主要在客户端开发 DSH 插件的人来说，它是一个可以照着改的本地报错词典。
目录页：https://www.skillhub.cn/plugins/chenmianmian19977-glitch/dsh-error-gloss
GitHub：https://github.com/chenmianmian19977-glitch/dsh-error-gloss
