前言¶
在 DeepSeek Harness（DSH）裏做智能體或工作流時，常見需求是：把 JSON、日誌、堆棧、路徑這類輸入交給模型處理，並希望得到穩定、可複用的結構化結果。模型往往可以臨時寫腳本完成單次任務，但輸出格式、邊界行爲（超大數據、截斷、覆蓋率）每次不一定一致，token 與步驟數也會波動。
dsh-zidev-toolbox 是維護者 ax2 發佈的工作流類插件合裝包：用一條安裝命令，在 DSH 中註冊四個獨立插件、共 46 個工具，覆蓋格式處理與 JVM、Python、Windows 側的生產診斷。工具純本地運行，無網絡、無安裝期腳本、無二進制依賴；實現帶 214 個通過的測試，許可證爲 MIT。
這是什麼¶
dsh-zidev-toolbox（npm 包名 dsh-zidev-toolbox，當前資料中版本 0.1.0）本身不是 46 個工具的實現體，而是四個 DSH 插件的合裝層：安裝時通過 cordis.patch.yml 一次插入四行 bundle，四個插件仍各自獨立版本。四個子插件分別對應 ax2 的 zi-devtools 工具箱在 DSH 上的 TypeScript 實現，契約包括統一回執信封、預算門禁與邊界行爲。
合裝後不要與單獨安裝的那四個 npm 插件混用，否則會重複註冊同名工具。
核心功能：四個插件與 46 個工具¶
下面按 README 中的劃分說明各包職責（工具數量與測試數以資料爲準）。
dsh-deterministic-tools（29 個工具，35 個測試）¶
面向 JSON/YAML/CSV/文本/編碼/正則等「格式活」，例如：JSON 校驗（精確行列偏移）、受限 JSONPath、結構化 diff、CSV↔JSON、YAML↔JSON、文本統計、正則捕獲、base64/hex/URL 編解碼、哈希，以及 Unicode、進制、顏色、CIDR、JWT、時間戳檢查等。
dsh-jvm-doctor（5 個工具，47 個測試）¶
面向 JVM 診斷：thread dump（含 Java 級死鎖環）、GC 日誌、Maven/Gradle 依賴衝突、異常鏈（... N more 還原）、Spring 配置 diff（載荷前脫敏）。
dsh-py-doctor（6 個工具，75 個測試）¶
面向 Python 診斷：traceback 根因、pytest 摘要、Django migrations/N+1/checks、celery 報告；解析結果帶覆蓋率信息。
dsh-win-native（6 個工具，57 個測試）¶
面向 Windows 環境：編碼檢測與轉換（GBK/Big5/Shift-JIS 置信度）、Windows 路徑合法性、netstat 解讀、只讀磁盤巡檢與重複文件查找。
設計要點（相對「讓模型現場算」）¶
資料中強調的價值不在「模型算不出來」，而在於：固定實現提高一次做對的概率；同樣輸入同樣輸出；超預算拒絕（INPUT_TOO_LARGE），文本截斷按 code point 並標註 truncated，解析覆蓋率與未識別行明確上報；部分工具聲明能力邊界（例如 jwt_inspect 不驗籤、netstat_parse 不編造文本中不存在的進程名與 UDP 狀態）；回執爲 { result, meta } 結構，便於後續步驟消費。
46 個工具裏僅 dir_usage、file_duplicates 會只讀訪問磁盤（有文件數/字節預算，軟鏈接與 junction 跳過並上報，不跟隨符號鏈接）；其餘均爲純文本/純字節分析，不提供數據則不會自行讀取。不髮網絡請求、不裝二進制、不寫安裝期腳本。
安裝與啓用¶
Node 引擎要求爲 >=20.10（來自 package.json）。
Web 配置檔安裝：
dsh plugin --profile web add dsh-zidev-toolbox
裝完後重啓應用（bundle 列表在啓動時讀取）。桌面版將 web 換成 desktop：
dsh plugin --profile desktop add dsh-zidev-toolbox
離線或固定版本時，可使用 Release 預構建 tarball（資料中的示例爲 latest）：
dsh plugin --profile web add https://github.com/ax2/dsh-zidev-toolbox/releases/latest/download/dsh-zidev-toolbox.tgz
四個子插件也可各自從 GitHub releases/latest/download/<repo>.tgz 單獨安裝；與合裝包二選一，避免重複註冊。
Token 與工具裁剪¶
工具 schema 隨每次請求發送，安裝後即使不用也會佔用 input token。README 實測：乾淨 headless base 約 75 個工具名、首次約 11,931 inputTokens；加上這四個插件後約 121 個工具名、首次約 19,608 inputTokens（+7,677）。一次性小任務可能總 token 反而高於模型自寫腳本；更適合輸入大、輸出小、或需要穩定解析與邊界語義的場景。
若只需常用子集，可在 profile 中按插件 id 覆蓋，例如只保留 deterministic-tools 中 5 個工具（資料示例）：
# profiles/<name>/cordis.patch.yml
- id: deterministic-tools
config:
only: [json_format, json_validate, json_query, text_diff, csv_to_json]
toolPrefix: zi
典型用法¶
安裝並重啓後，在對話中粘貼問題或日誌片段，由模型選擇合適的工具調用。README 給出若干可對照的預期行爲。
Python traceback¶
輸入示例：
Traceback (most recent call last):
File "svc.py", line 42, in handle
KeyError: 'user_id'
模型可調用 python_traceback，得到結構化字段（資料實測輸出包括 exception_type、exception_message、deepest_frame、cause_hints、coverage 等）。
其他常見說法與工具對應¶
| 你說 | 它調用 | 你拿到 |
|---|---|---|
校驗 {"a":1,}，要精確行列 |
json_validate |
line/column/position + 錯誤文案 |
C:\temp\CON.txt 這個路徑能用嗎 |
path_inspect |
如 reserved_name（error）及位置信息 |
| 貼上 jstack，有沒有死鎖 | java_thread_dump |
死鎖環、鎖競爭隊列、狀態直方圖等 |
| 這是 GC 日誌，p99 停頓多少 | java_gc_log |
停頓分位數、Young/Full 拆分等 |
netstat -ano 裏誰在監聽 8080 |
netstat_parse |
監聽項與 PID/進程名（文本中沒有的不編造） |
| D 盤哪個目錄最佔空間 | dir_usage |
總字節、最大文件、擴展名直方圖（只讀） |
適用場景與注意¶
適合：需要在 DSH 工作流中穩定處理 JSON/YAML/CSV/編碼/正則；解析 JVM thread dump、GC 日誌、構建依賴衝突；Python traceback、pytest、Django、celery 報告；Windows 路徑、netstat、編碼與磁盤只讀巡檢；且希望結果可復現、邊界明確。
注意：
- 插件在當前 dsh 進程權限下運行；安裝前請自行查看 GitHub 源碼與 MIT 許可證，確認符合你的安全與合規要求。
- 合裝包與四個子插件不要混裝。
- 社區目錄站點（SkillHub）與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本文安裝命令以倉庫 README 爲準。
- 子插件 npm 包：
dsh-deterministic-tools、dsh-jvm-doctor、dsh-py-doctor、dsh-win-native，均有獨立倉庫與 Release tarball。
鏈接¶
- 社區目錄頁：https://www.skillhub.cn/plugins/ax2/dsh-zidev-toolbox
- GitHub 倉庫：https://github.com/ax2/dsh-zidev-toolbox
- npm：https://www.npmjs.com/package/dsh-zidev-toolbox
