前言¶
在 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 仓库。
