前言¶
在 DeepSeek Harness（DSH）裏，模型常常需要跑一段 Python：算數、讀表、改 Office 文檔、把 stdout 當結果回傳。若只靠 Shell 拼命令，解釋器版本、依賴和編碼容易和宿主不一致；若每次讓用戶本機裝一套環境，又會拖慢會話啓動。
下面介紹社區插件 dsh-plugin-python（維護者 jcy0chenyuan0）：向 DSH 註冊名爲 python 的工具，用 Harness 自帶的 Python 運行時執行代碼，README 寫明「無需安裝任何東西」指的是模型側不必再單獨裝解釋器——首次部署插件目錄時仍需按文檔跑安裝腳本並 install_bundle。
這是什麼¶
dsh-plugin-python 是可安裝的 DSH profile bundle（package.json 中 dsh.bundle 聲明 patch 層）。Host 側入口爲 lib/python.js，在 Cordis 裏註冊模型面向的 python 工具。
分類在 SkillHub 目錄中爲「模型推理」；倉庫簡介爲：DSH plugin: a model-facing python tool using the Harness bundled Python runtime.
捆綁運行時（資料記載）：Python 3.12.14，並附帶 numpy 2.3.5、pandas 3.0.1、python-docx、python-pptx、openpyxl、Pillow、lxml、XlsxWriter 等，便於在會話裏直接做數據處理與文檔類任務。
核心功能¶
README 用表格歸納了工具行爲，下列能力均在資料中標註爲已實現：
| 能力 | 說明 |
|---|---|
| 執行代碼並返回 stdout | 正常結束帶 [exit code: 0] |
| 中文 / UTF-8 | 強制 PYTHONUTF8=1 與 PYTHONIOENCODING=utf-8（Windows 捆綁解釋器默認 locale 爲 gbk，不設環境變量時中文易亂碼） |
| 非零退出與 stderr | 失敗時 [exit code: 1] 並分離 traceback |
args / stdin |
對應 sys.argv[1:]、sys.stdin |
workdir |
相對路徑按會話工作區解析；越界 ../ 會被拒絕 |
files 多文件 |
可寫輔助模塊與數據，支持 import helpers、Path(__file__).parent |
timeoutMs |
超時終止，示例文案 [timed out after 1500 ms] |
| 臨時目錄 | 異常路徑也會清理，不泄漏 |
| 路徑攔截 | files / workdir 中的 ../ 越界會被拒絕 |
設計側要點（摘自 README）：插件模塊零宿主 npm 依賴（僅用 Node 內置模塊），直接向 ctx.tools.register 傳原始 JSON Schema 定義；每次調用走 ctx.sandboxPolicy.resolve，非 danger-full-access 時用沙箱 confine 再 spawn，無沙箱提供者時 fail closed。
離線測試腳本 .tooling/test-python-plugin.mjs 對打樁 ctx 與真實子進程共 9/9 項通過；線上驗證記錄中多文件調用曾返回 [exit code: 0] 及預期 stdout。
安裝與啓用¶
1、生成 patch 配置¶
首次在本插件目錄執行安裝腳本（按平臺二選一，腳本會根據當前目錄生成 cordis.patch.yml，已 .gitignore，不寫死盤符）：
powershell -ExecutionPolicy Bypass -File .\install.ps1
macOS / Linux：
node install.mjs
僅檢查環境、不自動安裝時（Windows）：
powershell -ExecutionPolicy Bypass -File .\install.ps1 -CheckOnly
安裝腳本默認靜默補全缺失環境；插件加載時還會在後臺跑 bootstrap.ps1 -AutoInstall -Quiet（6 小時內不重複），不阻塞 DSH 啓動——資料提示首次裝完若工具不可用，可重試一次。
Python 來源優先級（資料原文）：優先 DSH 捆綁運行時（dsh-runtimes\*\dependencies\python\python.exe）；沒有則 Windows 上可 winget install Python.Python.3.12 --scope user。也可設環境變量 DSH_PYTHON 或配置項 pythonPath 指向 Python 3.11+。關閉自動安裝：patch 的 config 裏 autoInstall: false，或 DSH_BOOTSTRAP=0。
2、作爲 bundle 裝入 profile¶
本包需在 GUI「設置 → 插件」中可見、可整體啓停，安裝命令爲：
plugin_manager install_bundle file:<本目錄的絕對路徑>
裝完後 profile 的 package.json 會出現 dsh.profile.bundles 與 dependencies 中的 dsh-plugin-python 條目。卸載：GUI 插件頁移除，或 plugin_manager remove_bundle dsh-plugin-python。
機制說明（README）：pnpm 會把包複製到 <profile>/node_modules/dsh-plugin-python，而 cordis.patch.yml 掛載的是工作區絕對路徑的 lib/python.js——改插件 JS 一般重啓 DSH 即可；若改了 patch 掛載參數，需重新 install_bundle。改代碼後 ESM 按 URL 緩存，運行中的 fiber 可能仍用舊實現；資料給出的熱替換做法是換新的 loader 條目 id 並停用舊 id（現用 id 爲 plugin-python-4）。
工具參數與配置¶
調用參數¶
| 參數 | 必填 | 說明 |
|---|---|---|
code |
是 | 要執行的 Python 源碼（寫入 main.py） |
description |
是 | 5–10 詞動作描述（UI 展示） |
files |
否 | [{ path, content }]，寫入運行目錄 |
workdir |
否 | 進程 cwd，默認會話工作區；相對路徑按工作區解析 |
args |
否 | 追加命令行參數 |
stdin |
否 | 管道輸入文本 |
timeoutMs |
否 | 超時毫秒數 |
注意：進程工作目錄是會話工作區，不是腳本所在臨時目錄；讀 files 裏的數據應用 Path(__file__).parent；要把產物留在工作區應直接寫工作區路徑。
插件 config 條目¶
| 鍵 | 默認 | 含義 |
|---|---|---|
pythonPath |
自動 | 解釋器路徑；默認按 runtime.json 找捆綁運行時 |
cwd |
會話工作區 | 默認工作目錄 |
timeoutMs |
120000 |
默認超時 |
graceMs |
3000 |
終止寬限期 |
maxOutputBytes |
200000 |
單流收集上限，超出落盤並給出 spillPath |
keepScript |
false |
爲 true 時保留臨時腳本並回報 scriptPath |
典型用法（模型視角）¶
模型通過已註冊的 python 工具提交 code 與 description；需要多文件時附帶 files，例如輔助模塊 helpers.py 與同目錄數據文件，在 main.py 裏 import helpers 並用 Path(__file__).parent 讀數據。需要 CLI 風格輸入時使用 args 或 stdin；長時間任務可調 timeoutMs（未傳則用 config 默認 120000 ms）。
README 未給出完整 JSON 調用示例，但線上驗證記錄提到：files 多文件場景下 stdout 曾出現 live after move: moved-to-python_hk / data: k,v | x,1 等形式，說明多文件 import 與數據讀取路徑在真機環境中可用。
適用場景與注意¶
適合：需要在 DSH 會話裏讓模型執行 Python、且希望儘量對齊 Harness 捆綁運行時與常見數據/Office 庫的場景；希望插件出現在 GUI 插件頁、以 bundle 方式統一啓停的團隊工作流。
注意：
- 工具以當前 DSH 進程權限在主機上 spawn Python；安裝前應閱讀 GitHub 倉庫 源碼與 MIT 許可證（
package.json），確認沙箱策略與danger-full-access是否符合你的安全要求。 - 社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係；DSH 生態強調「一切皆插件」，本文事實以倉庫 README 與
package.json爲準。 - 改動插件實現後若行爲未更新，按 README「三個實測坑」③ 處理：重啓 DSH，或新 loader id + 停用舊條目。
結尾¶
dsh-plugin-python 把「在 Harness 裏跑 Python」收成單一模型工具：捆綁運行時、UTF-8、超時、多文件、workdir 邊界與沙箱 fail closed 均在文檔中有對應說明。若要安裝或提 issue，可從目錄頁與倉庫入手：
- 目錄頁：https://www.skillhub.cn/plugins/jcy0chenyuan0/dsh-plugin-python
- GitHub：https://github.com/jcy0chenyuan0/dsh-plugin-python
