前言¶
在 DeepSeek Harness（DSH）裏跑智能體，模型經常需要知道「環境裏有什麼」「倉庫現在什麼狀態」「改完能不能過檢查」。宿主自帶的工具未必覆蓋這些本地事實；市場上也有回合末自動門禁類插件，但不一定註冊模型可調用的檢查入口。下面介紹社區插件 dsh-local-devkit：用純 Node 內置模塊、無第三方依賴、不修改宿主文件，把環境探測、git 操作、寫入前快照和項目自檢串成一組工具。
這是什麼¶
dsh-local-devkit 由維護者 alice0721021-web 發佈在 GitHub（倉庫 alice0721021-web/dsh-local-devkit），當前 package 版本爲 0.1.0，MIT 許可證。定位是：爲 Harness 補齊「本地事實層」——探測執行環境、檢查功能是否還在產出、把 git 變成模型可直接調用的一等工具、在每次寫文件前自動留快照，並能跑項目自帶的檢查。
社區目錄頁：skillhub.cn/plugins/alice0721021-web/dsh-local-devkit（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。DSH 生態理念是「一切皆插件」；安裝前建議自行查看源碼與許可證，插件以當前 DSH 進程權限運行。
核心工具一覽¶
插件註冊的工具如下（寫操作列來自 README 工具表）：
| 工具 | 作用 | 寫操作 |
|---|---|---|
env_probe |
探測 bash / pwsh / node / pnpm / git / python 與 DSH profile 可寫性，給出修復建議 | 否 |
git_status |
分支、上游、ahead/behind、已暫存 / 未暫存 / 未跟蹤 / 衝突 | 否 |
git_diff |
工作區或暫存區 diff，支持路徑過濾、--stat、字節上限截斷 |
否 |
git_log |
提交歷史（短 hash、作者、日期、標題、引用） | 否 |
git_commit |
可選先 git add 再提交；dryRun 只預覽；不暴露 --amend / --force |
是 |
fs_checkpoints |
列出當前項目的寫入前快照，可按路徑過濾 | 否 |
fs_restore |
回滾：給 path 撤銷該文件上一次寫入；給 id 精確恢復；恢復前會再拍快照 |
是 |
project_check |
探測並運行項目檢查（Node scripts / Python pytest·ruff·mypy / Go test），結構化返回結果 | 部分是 |
health_probe |
檢查功能是否還在產出：recall 快照、工作區體積、profile bundles 等 | 否 |
非 git 目錄統一返回 NO_REPO 而不是拋異常；越界路徑返回 PATH_OUTSIDE_REPO。
設計約束上，子進程一律 execFile 且 shell: false，避免注入；默認超時 15s、輸出緩衝 1MB。git_commit 的路徑先 resolveRepo 再 assertInside 校驗。
寫入前快照¶
插件掛到宿主的 tools/execute waterfall：write / edit（以及 fs_write / fs_edit / multi_edit / apply_patch）在真正落盤之前，把目標文件的原始內容存到 <DSH_HOME>/devkit/checkpoints/<projectHash>/。
要點：
- 快照失敗只
console.warn，絕不阻斷工具執行； - 文件此前不存在時記錄
existed: false，恢復即刪除； - 單文件超過
checkpoint.maxFileBytes（默認 4 MB）只記元數據、標skipped: too-large； - 每個項目最多保留
checkpoint.maxEntries（默認 500）條，超出刪最舊； - 快照目錄自身不會被再次快照，避免遞歸。
在 profile 的 cordis.patch.yml 中可調整 checkpoint（示例來自 README）：
- id: devkit
name: dsh-local-devkit
config:
checkpoint:
maxEntries: 500
maxFileBytes: 4194304
按路徑連續回退時，被用掉的快照會標記 consumed: true；pre-restore 快照不參與路徑選擇，因此連續調用是逐版後退。典型用法：
fs_restore({ path: "src/app.ts" }) # 撤銷這個文件的上一次寫入
fs_restore({ path: "src/app.ts" }) # 再調一次 → 再退一版
fs_restore({ id: "1793376673288-..." }) # 知道 id 時精確回到某一版
想把某次回退本身也撤掉，用 fs_checkpoints 找到 pre-restore 記錄，按 id 恢復。
項目驗證 project_check¶
project_check 按項目形態自行探測，按 typecheck → lint → test → build 順序執行，第一個失敗就停。只運行項目自己聲明的檢查，不接受自定義命令；dryRun: true 只列出將執行的命令。
Node：從 package.json scripts 匹配 typecheck / lint / test / build 等常見名稱；包管理器按 packageManager 或 lock 文件推斷，不在 PATH 時回落 DSH 內置 pnpm。
Python：依據 mypy.ini、ruff.toml、pytest.ini 等標記決定是否跑 python -m mypy .、python -m ruff check .、python -m pytest；只有 pyproject.toml 而沒有對應聲明時不會臆造目標。解釋器優先項目內 .venv，其次 DSH 內置 python。
Go（存在 go.mod）：go test ./...；go 不在 PATH 時返回 MANAGER_MISSING。
每個目標默認 180s 超時（上限 600s），輸出截斷到 8 KB。README 說明：與 @jayyuen66/dsh-quality-gate（回合末門禁、不註冊模型工具）和 dsh-flakefinder（flaky 調查）相比，模型可主動調用的檢查入口仍是本插件要填的缺口之一。
健康檢查¶
env_probe 回答「二進制在不在、能不能跑」；health_probe 回答「功能還在不在產出」。後者檢查 recall 快照新鮮度（默認 stalenessHours 24h）、工作區可快照體積（默認上限 256 MB）、本插件 checkpoint 條數與時間、以及 dsh.profile.bundles 是否在 node_modules 中裝齊。工作區掃描有 scanBudgetMs（默認 1500 ms）預算，超時會標記 partial。
調用示例：
health_probe({ cwd, stalenessHours?, workspaceLimitBytes?, scanBudgetMs? })
安裝與啓用¶
官方方式是在插件目錄執行安裝腳本（冪等，寫前自動備份 package.json / cordis.patch.yml / pnpm-lock.yaml）。先做預覽，再正式寫入：
node scripts/install.mjs --dry-run # 先預覽改動
node scripts/install.mjs # 寫入 package.json / cordis.patch.yml 並 pnpm install
腳本會：在 profiles/<profile>/package.json 增加對插件的 link 依賴、把 dsh-local-devkit 追加到 dsh.profile.bundles、在 cordis.patch.yml 寫入 devkit 標記塊，並調用內置 pnpm 執行 install。README 中的 link 路徑示例爲本地開發路徑，實際以你 clone 或放置插件的位置爲準。
安裝完成後重啓 DSH，在會話裏調用 env_probe 驗證。卸載：
node scripts/install.mjs --uninstall
package.json 要求 Node ^22.19.0 || >=24.0.0，DSH >=0.2.1-rc.3 <0.3.0。
適用場景與注意¶
適合需要在會話內主動查環境、讀 git 狀態與 diff、在模型改文件前自動留檔、改完後跑項目聲明過的 typecheck/lint/test/build 的 DSH 用戶。不適合指望插件做結構化代碼檢索（README 明確宿主無 LSP/tree-sitter，與 ops_grep 重疊且投入產出比不成立）。
返回值須滿足宿主契約：lossless JSON；schema 裏聲明爲 string 的字段不能返回 null。改 schema 後可在插件目錄跑 node --test test/schema.test.mjs 本地復現校驗。
結尾¶
dsh-local-devkit 把本地開發裏常見的事實與護欄收成一組模型工具：環境與健康、git、寫入快照、項目檢查，實現上堅持無第三方依賴與不改宿主文件。進一步瞭解可打開 社區目錄頁 與 GitHub 倉庫。
