前言¶
DSH 桌面端自身有代碼與純文本預覽，但定位是查看，不是編輯：沒有補全、摺疊、自動配對括號、保存衝突保護這些東西。想在 DSH 裏改代碼，要麼跳到外部編輯器，要麼忍受預覽面板。DSH CodeCraft 就是爲填這個缺口來的。
作者是 lllrunze，插件名 lllirunze/dsh-codecraft，npm 包名 dsh-codecraft，當前版本 0.2.2，許可證 MIT。它的做法不是另開一個窗口，而是在 DSH 原生的工作區瀏覽器和文件標籤頁裏掛一個 CodeMirror 6 編輯器，編輯和保存都走宿主的原生標籤頁流程。
下面按功能、安裝、用法、注意事項介紹。需要說明，該插件在 SkillHub 目錄的分類是「客戶端」，其 manifest 聲明的是 Web 客戶端側的注入與外部依賴，屬於客戶端型插件。
核心功能¶
編輯器基礎能力¶
- 語法高亮、行號、摺疊、搜索、行註釋、縮進、撤銷/重做、補全。
- 按回車時自動閉合常見括號和引號，包括選中後包裹、成對刪除，以及語言相關的反引號和 Python 三引號。
- 回車時按 Python 語法上下文決定縮進：塊、分支、多行表達式、閉合定界符。
- 縮進寬度可選兩個或四個空格，同一設置面板裏切換，改動隻影響打開的編輯器，不重寫已有文件內容。
Python 智能補全¶
- Python 文件在 macOS 和 Windows 上默認開啓語義補全（v0.2.2）。
- 使用插件自帶的 Pyright 服務，工作區範圍；優先選顯式解釋器或工作區的
.venv/venv，PATH 兜底時 macOS 用python3，Windows 用python。 - 補全覆蓋 import、跨文件符號、推斷出的成員、所選環境中的包。
- 在明確的調用上下文中接受方法、函數或構造函數補全時，會插入
()並把光標放在括號內；賦值右側、回調參數、容器、import、裝飾器、已有片段和已有括號保持不變。 - 狀態欄會顯示
Starting、Ready/Unavailable；服務不可用不影響正常編輯和保存。
Google Style Docstring 佔位¶
在 Python 函數、方法、異步函數或類的第一個語句位置輸入 """ 後回車，插件會生成 summary、Args、Returns / Yields 佔位內容。僅在語法上下文明確時生成；模塊作用域、賦值語句、嵌套塊、後續語句或帶前綴字符串中的三引號仍然是普通多行字符串。
保存與草稿¶
- 手動保存
Cmd+S（macOS）或Ctrl+S（Windows），也可點狀態欄的保存動作。保存路徑有衝突保護：能檢測外部改動並拒絕寫入過期內容。 - 自動保存默認關閉，可在
Settings → CodeCraft打開，間隔可選 10、30、60、120 秒。自動保存與手動保存共用同一條無衝突寫入路徑。 - 切標籤頁、關標籤頁或刷新頁面後恢復未保存草稿。
- 保留 LF / CRLF、UTF-8 BOM，並在支持的平臺保留 POSIX 文件權限位。
安全邊界¶
- 文件只本地編輯，沒有模型調用、遙測或文件上傳。
- 自動拒絕過大、二進制、非 UTF-8、行尾混合的文件。
- 限制在 2 MiB 以內的 UTF-8 源碼和文本文件。
安裝與啓用¶
環境要求¶
| 組件 | 要求 |
|---|---|
| 基礎編輯器 | macOS 或 Windows |
| Python Intelligence | v0.2.2 僅 macOS 或 Windows |
| DSH Desktop | 0.2.1-rc.5 |
| Node.js | 從源碼構建時需要 20 或更高 |
Linux 未做驗證，當前不支持。
從 npm 安裝¶
dsh plugin --profile desktop add dsh-codecraft@latest
裝完重啓 DSH Desktop。插件 manifest 會自動把 CodeCraft 加進所選 DSH profile，不需要手工改 profile。
從源碼安裝¶
git clone https://github.com/lllirunze/dsh-codecraft.git
cd dsh-codecraft
npm install
npm run check
dsh plugin --profile desktop add "$PWD"
npm run check 依次跑 typecheck、test、build、verify。裝完同樣需要重啓 DSH Desktop。
更新與卸載¶
dsh plugin --profile desktop update --latest dsh-codecraft
或者指定版本：
dsh plugin --profile desktop add dsh-codecraft@0.2.2
卸載：
dsh plugin --profile desktop remove dsh-codecraft
卸載後重啓 DSH Desktop，原生文件預覽會自動恢復。插件目前沒有應用內更新通知或後臺靜默更新，安裝與更新都由 DSH CLI 負責。
典型用法¶
- 在 DSH 工作區瀏覽器裏打開一個支持的源碼或文本文件。
- DSH 打開原生文件標籤頁，並選中 CodeCraft 渲染器。
- 直接編輯，按
Cmd+S或Ctrl+S，或點狀態欄保存動作。 - 需要看原始內容時，用標籤頁上方的 viewer 菜單切回 DSH 原生代碼或純文本預覽。
若要打開自動保存：進 Settings → CodeCraft，選擇 10 / 30 / 60 / 120 秒間隔。若要調整縮進寬度，在同一個設置區裏改；Python 文件額外享受語法感知的回車縮進。
快捷鍵（macOS 與 Windows 對照）：
| macOS | Windows | 作用 |
|---|---|---|
Cmd+S |
Ctrl+S |
保存當前文件 |
Cmd+F |
Ctrl+F |
文件內搜索 |
Cmd+/ |
Ctrl+/ |
切換行註釋 |
Cmd+Z / Cmd+Shift+Z |
Ctrl+Z / Ctrl+Y |
撤銷 / 重做 |
Tab / Shift+Tab |
Tab / Shift+Tab |
增加 / 減少縮進 |
| — | Ctrl+Space |
手動打開補全 |
macOS 未綁定 Option 組合鍵，因爲可能產生組合輸入字符。Ctrl+Space 在操作系統沒有佔用的環境下可用。
適用場景與注意¶
適合在 DSH 桌面端裏直接改 .py 或常見文本源碼、希望編輯動作保留在原生標籤頁和工作區流程裏的人。Mac 和 Windows 用戶可用 Python 語義補全；只做查看或純文本編輯的場景用原生預覽就夠了，不必裝。
按 DSH 的插件模型，插件以當前 DSH 進程權限運行，並可以通過 manifest 聲明注入客戶端模塊。本插件的 manifest 聲明瞭 inject 項（dsh-client-locale、dsh-client-ui-settings、dsh-client-ui-settings-plugins、dsh-client-ui-sidebar-right、dsh-client-ui-sidebar-documentpreview）和 external 依賴（dsh-client-ui-primitives、react、react/jsx-runtime）。安裝前建議檢查源碼與許可證（MIT），再決定是否裝入。
兩個已被文檔確認的兼容性注意點：
- 若同時裝了修改 DSH 側欄文件區的插件（例如
dsh-better-sidebar），它可能替換或攔截原生Files內容，導致 CodeCraft 拿不到正常的原生文件標籤頁流程。處理方式是進入該側欄插件的設置，關閉它對Files的作用，必要時重啓 DSH Desktop，再從原生Files側欄打開文件確認。 - 排查順序上的建議：先確認另一個插件替換或攔截了 DSH 的哪個原生界面，優先把那個插件配置成不干擾本插件需要的原生流程。
限制方面：符號鏈接只讀；Python 的 hover、簽名幫助、診斷、跨文件自動編輯、跳轉定義尚未提供；不支持 Linux；沒有跨窗口草稿同步。
結尾¶
DSH CodeCraft 把編輯能力放進 DSH 原生的文件標籤頁裏，靠原生工作區的權限和保存鏈路做衝突保護與草稿恢復，而不是另起一套編輯器界面。它的價值在於讓「在 DSH 裏改代碼」這件事不需要跳出宿主環境。目前維護在 0.2.2，Linux 和若干 Python 語義功能還缺位。
目錄頁：https://www.skillhub.cn/plugins/lllirunze/dsh-codecraft
GitHub：https://github.com/lllirunze/dsh-codecraft
文檔：https://github.com/lllirunze/dsh-codecraft/tree/master/docs
