前言¶

在 DeepSeek Harness（dsh）里跑长任务时，成本往往不只在模型推理，还在上下文与往返次数：每一步机械操作（复制文件、检查存在、数行数）都要走一轮模型回合，整段对话和历次工具结果会反复进入上下文；工具原始输出（大段搜索命中、完整测试日志）又会把窗口撑满，而模型很多时候只需要状态、计数或差异摘要。

已有做法里，要么让模型逐步调用工具完成每件小事，要么在 Harness 开启 Code Mode / 程序化工具调用（PTC）时由运行时原生合并执行。本插件走另一条可落地的路径：把「计划 → 批量执行 → 收据」和反馈压缩、本地核验、重试治理写进一套 DSH 原生 Skill 与辅助脚本，在未开原生 PTC 时也能保持同样的执行纪律。

这是什么¶

deepseek-harness-batch-executor 是维护者 LastTrainKing 发布的 DSH 插件，社区目录分类为工作流。定位是：让模型只参与需要判断的步骤，把确定性工作合并为一次脚本化执行；汇报前在本地核验结果；把冗长反馈压成摘要，按需再深读；对无效重试及时止损。

辅助脚本为 Python 3.8+、纯标准库，不依赖 pip、不联网；插件通过 dsh.bundle（package.json + cordis.patch.yml）安装后自动注册 SKILL.md，scripts/ 随包解析。也可在非 DSH 的能跑 Python 的 Agent 环境中单独使用脚本。

针对的三类成本与对应机制¶

README 将长会话成本归纳为三类，插件用不同脚本与 Skill 层配合应对：

若 Harness 已启用原生 PTC，文档建议优先使用原生能力；未启用时，可用普通写文件 + 执行命令工具写出 plan/脚本、运行、只读摘要，Skill 中说明了两种路径及选用规则。

工作流概览¶

            ┌──────────────────────────── model (judgment) ───────────────────────────┐
            │ 1. CLASSIFY  拆分：可批量确定性 vs 需判断                              │
            │ 2. PLAN      写 plan JSON（或原生 PTC 下的一段程序）                    │
            └───────────────────────────────────┬───────────────────────────────────────┘
                                                │ 一次交接
            ┌──────────────────────────── executor (deterministic) ───────────────────┐
            │ 3. PRE-CHECK  源、目标、策略                                            │
            │ 4. EXECUTE    连续执行整段计划                                          │
            │ 5. VERIFY     计数、哈希、diff，本地、先便宜后昂贵                        │
            └───────────────────────────────────┬───────────────────────────────────────┘
                                                │ 收据 + 证据指针
            ┌──────────────────────────── model (judgment) ───────────────────────────┐
            │ 6. REPORT     只汇报紧凑收据；深读按日志路径懒加载                        │
            │ 7. GUARD      每次重试前 loop_guard check/record；遵守 STOP              │
            └─────────────────────────────────────────────────────────────────────────┘

安装与启用¶

推荐以 DSH 插件安装（仓库自带 dsh.bundle，Skill 自动注册，无需手抄文件）：

dsh plugin add github:LastTrainKing/deepseek-harness-batch-executor

插件通过 ctx.skills 注册捆绑的 SKILL.md；辅助脚本在包内 scripts/ 下，相对 Skill 目录解析。该插件也出现在 awesome-dsh-plugin 目录（分类 skill）。

package.json 标明插件版本 1.0.0、许可证 MIT，运行插件壳需要 Node >= 20，peer 依赖 @deepseek-ai/cordis 与 @deepseek-ai/dsh-skill。若不用插件通道，DSH 也会扫描项目级或用户级 skill 目录（如 ~/.dsh/skills/、<project>/.dsh/skills/ 等），完整路径与 skill-explorer.customSkillDirs 见仓库 README；Skill 支持热加载。

典型用法：批量执行与核验¶

下面以 batch_exec.py 为例，用 plan JSON 描述一串确定性操作，并在执行后做核验。

先准备 plan（结构可参考仓库 examples/sample-plan.json）：

{
  "plan_id": "copy-configs",
  "overwrite": "if-different",
  "operations": [
    {"id": "op-1", "op": "copy", "src": "templates/a.conf", "dst": "build/a.conf"},
    {"id": "op-2", "op": "mkdir", "path": "build/out"},
    {"id": "op-3", "op": "expect", "path": "build/a.conf", "expect": {"exists": true}},
    {"id": "op-4", "op": "remove", "path": "build/tmp", "requires_approval": true}
  ],
  "verify": [
    {"type": "count", "pattern": "build/*.conf", "expect": 8},
    {"type": "tree-hash", "src": "templates", "dst": "build"}
  ]
}

在项目根或脚本所在仓库目录执行：

python scripts/batch_exec.py --plan plan.json [--dry-run] [--approve] \
                             [--log-dir DIR] [--fail-fast] [--json]

--dry-run 用于先看将执行什么；含 requires_approval 的删除等操作需 --approve。执行成功后会打印紧凑 receipt（计划 id、状态、耗时、各 op 结果、verify 通过情况），完整日志写入 .dsh-batch-logs/ 下带时间戳的 JSON，模型侧只需读收据，需要时再按路径深读日志。plan 支持幂等语义（如 overwrite: if-different 会报告 already_satisfied）。

搜索与测试类冗长输出可分别走 search_summary.py、test_summary.py 做摘要；独立核验可用 verify_state.py；重试前用 loop_guard.py 做 check/record。

适用场景与注意¶

适合在 DSH 长任务里频繁做批量文件操作、需要本地证据（计数/哈希/diff）再向模型汇报、或希望压平搜索/测试日志的场景。也适合团队把同一套执行纪律带进 CI 或任意 Harness（仅脚本时 clone 后直接 python scripts/batch_exec.py 试跑示例 plan）。

安装与运行前请注意：插件与脚本以当前 dsh 进程的用户权限执行，plan 里的 copy/remove 等会真实改动磁盘；务必阅读源码与 MIT 许可证，对 requires_approval 与 --approve 的使用范围自行把关。社区目录 skillhub.cn 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。

结尾¶

deepseek-harness-batch-executor 把程序化工具调用纪律落到可安装的 DSH Skill：一次脚本跑完确定性步骤、收据式汇报、本地核验与重试治理，并用纯标准库脚本降低环境负担。进一步了解可查看 GitHub 仓库（含 README.zh-CN.md）与 SkillHub 目录页。