前言¶
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
