前言¶
DeepSeek Harness（DSH）的插件生態裏，每個 bundle 通常帶着英文 README 或 meta.detail 長文檔，插件列表行也往往是 meta.title、meta.description 的英文 fallback。讀文檔、對比功能時，如果依賴瀏覽器翻譯或每次手動複製，既慢，插件一更新又要從頭來。下面介紹社區插件 dsh-plugin-readme-zh（維護者 PinkyKan，GitHub：PinkyKan/dsh-plugin-readme-zh）：在 DSH 插件頁內把已安裝插件的長說明與列表一行簡介譯成簡體中文，結果寫入持久化分段緩存，只有文檔實際變更的部分才重新調用模型。
這是什麼¶
dsh-plugin-readme-zh 是一個 DSH bundle（package.json 版本 1.0.0，MIT 許可證，要求 dsh >=0.2.1-rc.3、node >=22）。它在社區目錄 skillhub.cn 的分類爲「記憶」；簡介爲：對已安裝插件文檔做簡體中文翻譯，並用持久化分段緩存避免重複勞動。
翻譯使用當前 profile 下選爲 agent 默認的模型（或在 profile patch 裏顯式配置的 provider / model）；緩存目錄爲 $DSH_HOME/plugin-data/dsh-plugin-readme-zh/（Markdown 分段與短字符串）。
核心功能¶
詳情頁「中文說明」¶
在每個已安裝插件的詳情頁頭部增加 中文說明 控件。點擊後彈出對話框，展示譯好的長文檔、實時進度與緩存統計。首次翻譯會走進度條；之後命中緩存可即時打開。對話框內提供 重新翻譯、複製中文（複製譯好的 Markdown），以及 翻譯全部已安裝插件（後臺翻譯所有已安裝插件的長文檔，並刷新列表一行簡介）。
若插件沒有可讀文檔、文件不可用，或文檔本身已是中文，該按鈕會隱藏。
插件列表一行中文（可選）¶
默認不會在別的 package 目錄裏寫文件。若在 bundle 配置裏開啓 metaSidecars: true，會把列表行的 meta.title / meta.description 譯成中文，寫入各已安裝 bundle 自己的 locale/zh.json（合併已有文件，作者自帶中文不會被覆蓋）；若包內原本沒有 locale/，還會補 locale/en.json 作爲英文種子；需要時會在 exports 裏追加 "./locale/*.json": "./locale/*.json"。這樣 Settings → Plugins 列表通過宿主正常的 locale 解析顯示中文，而不是在前端 DOM 上打補丁。
pnpm install 重新解壓包會清掉這些 sidecar 文件；下次啓動會從字符串緩存重新寫入。
分段緩存與增量翻譯¶
長文檔按 Markdown 結構切分後再譯：
- 圍欄代碼塊、HTML 註釋塊、獨立 HTML 標籤行原樣保留，不送模型。
- 先按標題（
#…######）切段，增刪或重排某一節隻影響該節的 hash。 - 節內正文按行邊界打包，單塊最多 3000 字符。
- 每塊以源文 SHA-256 爲鍵；緩存記錄文檔 hash、塊 hash 與譯文。
插件升級後：未改動的塊直接複用；僅源文變化的塊重新翻譯；文檔不變則版本 bump 也不消耗模型調用。翻譯中途重啓會保留已完成的塊，下次繼續而非重頭開始。
安裝與啓用¶
官方 README 給出多種分發方式，任選其一（將 <name>、<profile>、路徑替換爲你的環境）：
Git 倉庫（需能訪問 GitHub）：
dsh plugin --profile <name> add git+https://github.com/<owner>/<repo>
本地目錄（開發時用 link）：
dsh plugin --profile <name> add link:/abs/path/dsh-plugin-readme-zh
離線 tarball：
dsh plugin --profile <name> add file:/abs/path/<name>.tgz
npm registry（發佈後）：
dsh plugin --profile <name> add <package-name>
安裝後在 Plugins 頁面啓用該 bundle（或寫入 dsh.profile.bundles）。若需要列表一行也顯示中文，在 profile patch 裏爲該 bundle 設置 metaSidecars: true（默認 false，公開安裝默認不改動其他包目錄）。
典型用法¶
- 安裝並啓用 bundle；每次啓動會在後臺自動翻譯所有已安裝插件的列表一行簡介（已緩存字符串不再消耗模型）。
- 打開 Settings → Plugins，列表行在包名旁可見中文一行說明（在開啓
metaSidecars: true時）。 - 進入任意已安裝插件詳情頁，點 中文說明 查看長文檔譯文。
- 需要全量刷新時，使用 翻譯全部已安裝插件 或單文檔 重新翻譯。
配置項¶
在 profile patch 的 bundle 行上可改以下字段（默認值見下表）：
| Field | Default | Meaning |
|---|---|---|
engine |
auto |
auto 優先模型服務，失敗回退 translator；llm 必須用模型；translator 僅用 ctx.translator。 |
provider |
agent default | 翻譯用的模型 provider。 |
model |
agent default | 翻譯用的 model id。 |
reasoningEffort |
off when supported |
翻譯調用的 reasoning effort。 |
maxTokens |
8192 |
每塊輸出 token 上限。 |
translatorProvider |
bing |
translator 回退時的 provider。 |
metaSidecars |
false |
爲 true 時寫入各包的 locale/ sidecar，使列表原生顯示中文。 |
翻譯 prompt 要求保留 Markdown、代碼、URL、路徑、包名與標識符，且只返回譯文片段。
適用場景與注意¶
適合誰： 長期在 DSH 裏安裝、對比多個英文插件文檔的開發者；希望列表與詳情統一看簡體中文、又希望插件更新後儘量少重複翻譯 token 的用戶。
權限與安全： 插件以當前 DSH 進程權限運行；開啓 metaSidecars 時會向已安裝包目錄寫入 locale/*.json 等文件。安裝前應閱讀 源碼倉庫 與 MIT 許可證，確認符合你的環境策略。
侷限（摘自官方說明）：
- 長詳情與列表 meta 一行會譯；深層配置字段標籤、行標題、文檔內嵌字符串仍保持原語言。
- 長文檔首次翻譯按塊調用模型，約 30 KB README 通常需數次調用。
- 對話框使用精簡 Markdown 渲染器；原始 HTML 會降爲文本，外鏈圖以 alt 顯示，鏈接限於 HTTP(S)、
mailto:、頁內錨點。 - 緩存按 profile 的
$DSH_HOME隔離；換 profile 從空緩存開始。 - 不支持手改緩存文件後繼續使用。
社區目錄 skillhub.cn 與 DeepSeek / 幻方無官方從屬關係；DSH 生態遵循「一切皆插件」，本文僅介紹該 bundle 的已文檔化行爲。
結尾¶
dsh-plugin-readme-zh 把「讀英文插件文檔」收成插件頁內的 中文說明 與可選的列表 locale sidecar，並用按標題與 hash 分段的方式控制更新成本。需要進一步瞭解實現與分發細節時，可直接查閱 GitHub：https://github.com/PinkyKan/dsh-plugin-readme-zh；在目錄站瀏覽條目：https://www.skillhub.cn/plugins/PinkyKan/dsh-plugin-readme-zh。
