dsh-mc-agent —— 让 DSH 里的 AI 真的去玩 Minecraft

在 DeepSeek Harness（DSH）里给 AI 一副能动手的身体：
34 个 mc_* 工具，覆盖进服/寻路/挖矿/合成/熔炼/存取箱子/看第一人称画面/记账。
本仓库是 whale-craft（作者 yzi1b）的魔改版，
改名 dsh-mc-agent；CHANGELOG.md 里的旧名字（whale-craft）保持原样。

因为是 junction，改完源码不用拷贝，重启 DSH 就生效；本目录里的 node_modules\ 是 103 个
指回 profile 的 junction，用来让编辑器/node 找得到依赖。

装到自己的 DSH

pnpm add github:blueziii/dsh-mc-agent
pnpm add mineflayer-pathfinder mineflayer-collectblock mineflayer-tool mineflayer-pvp mineflayer-auto-eat

然后在 DSH 的 profile 配置里把 dsh.profile.bundles 加上 "dsh-mc-agent"，重启。

• 没装 mineflayer-pathfinder 时 mc_move 会直接拒绝（返回 via:"pathfinder-unavailable"），
  只剩"在水里游"和"原地跳"能用 —— 寻路能力完全依赖它。
• 改代码调试时用软链而不是装包："dsh-mc-agent": "link:C:/你的路径/dsh-mc-agent"。
• 依赖树体检：node tools\check-mc-deps.mjs（9 项）。
• 不想连服务器也能跑的自检：node tools\check-all.mjs。

那五个生态插件装在 <profile>\vendor\mc-deps\（独立依赖树，不跟插件自己的 node_modules 混），
src/plugins.mjs 的 loadMcDep 有四路候选，还会往 $DSH_HOME\profiles\*\vendor\mc-deps\ 兜底。

跑自检

node tools\check-all.mjs            # 42 项：41 个套件 + selfcheck（几分钟）
node tools\check-all.mjs --fast     # 跳过 selfcheck（快）
node tools\check-all.mjs --only check-core-dig   # 只跑一个

任何 ❌ 都会让整体 exit 1。套件自己收拾现场（--keep 保留现场供排查）。
各套件的期望值：

🔴 静态断言（"读源码文本 → 正则匹配"那一类）在拆分模块时最容易悄悄失效 ——
代码搬到别的文件、this. 改成 self.，断言还在原地找，于是一直红着没人看。
搬完模块先跑 node tools\scan-moved-assertions.mjs（顾问型），再核对上表数字。

配置速查

会话级配置用 mc_config 读写；下面的键写在 DSH 的 MC 设置里或 config.json。

单独文件（都在 <memoryDir>\）：

• auto.json —— 自主层开关；view.json —— 看图门禁（{"gate":true,"maxActions":8,"maxAgeMs":120000}，默认不强制）。
• RULES.md —— 行事准则（2026-10-08 起内置默认与记忆里那份是同一份文本）。
• 版本提示.md —— 2026-10-08 起只投一行指针。

环境变量：DSH_MC_AGENT_PATHFINDER（off 或路径）· DSH_MC_AGENT_MC_DEPS · DSH_MC_AGENT_MEMORY_DIR ·
DSH_MC_AGENT_AUTO · DSH_MC_AGENT_VIEW_GATE / _VIEW_GATED / _VIEW_MAX_ACTIONS / _VIEW_MAX_AGE_MS ·
DSH_MC_AGENT_SKIN_TIMEOUT_MS · MC_LOG_LEVEL(quiet|info|debug) · MC_LOG_MAX_BYTES · MC_LOG_KEEP ·
MC_HOST / MC_PORT · DSH_MC_AGENT_SCHEDULER（observe-only(默认) / enforce = 撞车时排队等、够高就叫停低的）·
DSH_MC_AGENT_PERF（off 关掉性能监测，默认开）· DSH_MC_AGENT_PERF_RESOLUTION（事件循环延迟直方图分辨率 ms，默认 100，最小 10）·
DSH_MC_AGENT_PERF_KEEP（每个动作留多少条样本，默认 20）·
DSH_MC_AGENT_WORKERS（Worker 线程池：不给 = 关；数字 = 池子上限（≤4）；on = 自动取）。
默认关是量过才这么定的 —— 唯一够格搬走的是 mc_map {format:"image", radius:96, scale:16} 的像素循环（943 万像素、28ms），
其余候选都在 16ms 以内，而且大头是搬不动的 bot.blockAt()。

工具速查（34 个）

三层命名空间：mc_* 游戏内动作、mc_kit_* 宿主能力、mc_admin_* 管理。
mc_connect / mc_disconnect / mc_map / mc_kit_image 不受 11 秒闸门（一次调用要把握手或算图做完）。

连接与账户

感知

动作

长活儿与自主

合成 / 熔炼 / 箱子

宿主工具

架构速览

三个宿主文件 + 53 个 src\ 模块 + 7 个扩展。**依赖方向**：index.js → extensions\ → src\；
src\ 内部单向，新模块不许反向 import 回 core.mjs（靠 setXxx() 注入或收 ctx）。

宿主侧

src\ 模块

extensions\（改完重启 DSH 即生效）

5 个现成依赖（不自己写这些能力）

#movements() 造的那份 Movements 同时给 pathfinder / collectBlock / pvp 用 —— 免得"我自己走不乱跳、
插件走就乱跳"。缺哪个只是少那项能力，其它照旧。

目录

index.js / selfcheck.mjs / client.js   宿主侧
src\                                   61 个模块（见上表）
extensions\                            7 个扩展 + mc_util.mjs
tools\check-*.mjs                      41 个离线自检套件
tools\check-all.mjs                    一条命令全跑完 + ✓/✗ 汇总表
tools\scan-moved-assertions.mjs        顾问型：搬模块后的断言扫描
实机验证\                               真服脚本（跑的时候要服务器开着）
 合成\ 熔炼\ 存取\ 搭方块\ 搭路\ 采集收尾\ 走路\ 用物品\ 溺水\ 皮肤\ 自主\ 打怪\ 攻击\ 地图\ 背包\ 挖方块\ 复原包\ 挖矿速度\ 感知\ 视角\
备份\                                  回滚用
presets\ locale\                       权限补丁 / 中英文案
README.md / 插件说明.md / 踩坑档案.md / PATHFINDER.md / CHANGELOG.md

实机验证\ 每个脚本都是"真服真跑 + 期望条数"（如 live-place.mjs 13/0、live-restore.mjs 11/0、
live-digtime.mjs 8/0、live-percept.mjs 26/0），部分支持把账号名当参数传
（node live-dig.mjs wcdig_run5 —— 位置存在服务端，旧账号可能卡在坑里，换个新名字就回出生点开阔地）。

备份\ 里：core.mjs.原版、watchdog.mjs.orig、selfcheck.mjs.orig、
dsh-mc-agent-index.js.orig、dsh-mc-agent-index.js.before-session-memory、
RULES-自定义备份.md、readable-stream-补丁备份\（7 个原文件）、pathfinder-补丁备份\（两处补丁成品，可直接还原）。

相对上游改了什么

上游 whale-craft 是一个能连服的 mineflayer 壳；这个版本把它做成了"能长期自己玩"的 agent。
按能力分类（每条的具体来龙去脉在 踩坑档案.md）：

安全与诚实

• "报成功必须有证据"：break/place/dig 的判据一律回读服务端状态；服务端发回原方块包
  （拒绝破坏）绝不算成功（server-break.mjs 三态判决）。
• 不许骗人：place 没出现方块、use 没开窗口、attack 没打死，都如实说；
  mc_connect {force:true} 的说明写明"玩家会看到你退游戏几秒"。
• 受保护文件（RULES.md / AGENTS.md / config.json）在 MC 模式下不许改。

不卡死

• 单次调用 ≤11 秒：mc_move/mc_dig/mc_build/mc_sequence 到点带结果收手，
  返回 remaining + hint 让模型接着叫 —— 挂住的时候用户看不到任何消息。
• 超时闸门走 abort signal + 本地 deadline；用户点"停止"能立刻真停（interruptMove 推号 + 停采集 + 松控制位）。
• 挖矿速度修正：上游 material 写错导致铁矿石要 4.5 秒，现在石镐挖铜矿 4550ms → 1302ms。
• pathfinder 接进来 + 两处补丁 + walkPlaceCost 调高（上游默认 1 会让机器人往空气上搭）。

能自己玩

• 看门狗：进服自动挂载，聊天/受击/死亡/传送/断线都在同一个对话里叫醒 AI。
• 自主层 mc_auto：反射层不花 token 地环顾/吃/捡/躲/跟随，被怪打或憋气时叫醒 AI 定策略；
  空闲决策层带"玩家在干什么 + 长期目标 + 没做完的任务"叫醒它，不许反问 Master。
• 任务台账 + 步骤表 + 执行器：挖 4 个以上自动开工，tasks.json 掉线重连都还在；
  mc_task {action:"run"} 一次推进一步，四道闸门防跑飞。
• 记忆：四分类（world/lessons/tasks/RULES）带来源·成功失败次数·适用版本；按服务器建子文件夹，可每会话独立。
• 统一动作调度器：资源冲突（interaction/movement）记账；enforce 模式下撞车先排队等（waitMs，默认 3 秒），
  够高就叫停低的（同级不抢、preemptible:false 不抢、取消边界在 cleanup/unknown 不抢）；
  父子动作复用 actionId，而且子步骤忘了说自己是谁也不会把自己锁死（AsyncLocalStorage 兜底）。

看得见

• 第一人称视角 mc_observe：从眼睛渲染截图 + 三段式感知（我看到 / 程序检测到 / 不确定），
  两套眼睛对不上时点名，以程序射线为准；门禁默认关，AI 自己决定何时看。
• 地形图：地表图 + 地下自动切洞穴层；format:"image" 出俯视图。

生活技能

• 合成/熔炼/存取箱子三个扩展走真服务端界面（不是作弊给物）：自动补齐中间产物、
  写产物名反查原料、自己挑燃料、附近没工作台/熔炉/箱子就自己放一个。
• 装备栏、附魔台、铁砧、锻造台。
• 图像工具链（mc_kit_image / mc_kit_express / mc_kit_memory）与 mc_admin_config。

工程

• src\core.mjs 从 4896 行拆到 1037 行，53 个模块单向依赖（拆的规矩见下一节）。
• 日志：本地时间、级别、去重、轮转（上游是 UTC + 从不轮转 + 59.7% 启动噪声）。
• tools\check-all.mjs 35 项离线自检 + 顾问型断言扫描器。

拆分模块的规矩

src\core.mjs 是分 43 刀拆出来的（4896 → 1037 行）。以后继续拆照这 46 条来 ——
每条都是踩出来的，括号里的"第 N 刀"是它第一次被踩到的位置（对应提交见 CHANGELOG.md）。

1. core.mjs 里保留同名导出：export { lossless, redactPath } from './format.mjs' —— 外部一行都不用改。
2. 一次只搬一个模块，搬完立刻 node --check + 真的 import 一遍，确认导出还在、行为没变。
3. 移动和挖掘最后再拆：#walkPathfinder() / dig() 共享 _moveGen、_ctrlLease、11 秒预算和一堆事件监听。
4. 静态断言也要跟着搬：套件里有"core.mjs 里有没有 const SOFT_ROOF = "这种按文件找代码的断言，代码一搬它就红。
5. 先 grep 谁在 import 这个名字：被别的模块 import 就必须 re-export，否则报的是加载期的
   does not provide an export named '…'（整个扩展起不来），不是运行期。
6. grep 要 grep 整个仓库（tools\ 与 *.md 都算），不只看 import —— 有一批断言是"按名字找代码"的。
7. 搬家脚本别手写"要加 export 的白名单"：node --check 只查语法不查导出，漏一个要等真 import 才报。
8. 新模块不许反向 import 回 core.mjs（循环导入）⇒ 改成 core 注入 setXxx()。
9. "模块加载时读一次"的环境变量搬进单例模块后必须改成现读：core.mjs 每个连接会重新 import 一份，
   src\log.mjs 整个进程只加载一次 ⇒ MC_LOG_MAX_BYTES/MC_LOG_KEEP 要写成 logLimits() 现读。
   搬之前先问一句"这个模块会被加载几次"。
10. 搬"私有方法"比搬"纯函数"多两件事：签名要多一个 b（this.#heldText(b) → heldText(b)，所有调用点都得改）；
    公开方法要在 core 留薄包装。"逐字等价"验证法失效（签名变了），改用行为对照。
11. "grep 整个仓库"里必须有 selfcheck.mjs：它有"读源码文本 → 打 ✅/❌"的检查，
    不打 fail、不影响退出码，会安静留 ❌ 在满屏绿字里。
12. 能并进已有模块就别新开（依赖方向要天然是顺的）。
13. 搬常量/工具函数时先分清"哪部分是纯的、哪部分绑在实例上"：纯的进模块，读 this.xxx 的留类里。
    判据："公开面不变"= "以前 export 过"，不是"有没有人用"。
14. 一个名字在两个模块里表示两件事时顺手改名（#reachOf → blockReachOf，与 mc_craft.mjs 那个"材料够不够做"的 reachOf 区分）；
    改名时用脚本统计命中数，命中 0 处就抛错。
15. 搬"公开方法"要给类留同名薄包装（不是 re-export）：heightmap (opts = {}) { return heightmapOf(this.requireBot(), opts) }。
    验证用 A/B 对照（把 git HEAD 的 core.mjs 临时拷回 src\，跑完即删）。
16. 薄包装的参数形状要跟原来一模一样：scan ({…} = {}) 收对象、entities (radius = 24, {…} = {}) 是位置参数 + 可选对象 ——
    调用方是照签名调的，签名一改就是静默改行为。
17. 实例状态不属于 bot：多给模块一个 ctx 参数（statusOf(b, ctx)）。
    判据：凡是被搬走的代码里出现 this.xxx，就问这个 xxx 是 bot 的还是插件的。
18. A/B 的假数据必须复刻真实数据的形状，否则"等价"可能只是"两边都走了同一条死路"
    （dig-speed.mjs 第一版冒烟 82/0 全绿，但假 registry 把工具表写成了 {900:2, 901:2}，真实数据只有木工具）。
19. 搬"实例状态 + 收尾动作"混在一起的方法：模块只做动作，状态全走 ctx
    （cancelCollect(b, ctx)，ctx = { force, budgetMs, bumpGen, stopPathing, releaseControls, log }）。
    薄包装里保留字面 this._moveGen++（check-call-budget.mjs 按字面数"抢占时把代号往前推 ≥2 处"）；
    收尾类动作一律 try { … } catch {} 包住每一步。
20. 有可变实例状态的层，第一参数直接收 self（不是 ctx）。判据："要读"进 ctx，"要改"就直接收 self。
21. 每搬一个模块都要跑 node tools\scan-moved-assertions.mjs（顾问型，不判红）。
    它做两遍：① 按导出名找"提到这些名字且正则带实现细节"的断言；② 把断言的正则拿去它断言的文件里试，
    在 core 里找不到、却能在别的 src/*.mjs 找到的就报。
22. 一个 ok() 里塞两条正则时，扫描器可能只看到第一条：要抠掉整行所有 .test(<ident>) 再判，
    并把 = 、.方法(、??、|| 也算实现细节。教训：两条正则都要单独看一眼。
23. lines.splice(n, …) 是 0-based，锚点自检用的是 1-based；split('\n') 后每行带 \r，比对要 .replace(/\r$/, '')。
    node --check 不会报这类错（多一行孤立 /** 语法完全合法）。
24. 搬"要发包的动作"时模块只做动作，实例/库相关的全走 ctx（giveItem/clearInventory/tossItem
    要 ctx = { t, makeItem }，模块不 import 任何游戏库）。
25. 搬"服务端不回执的动作"：把 await 留在模块里，别把 promise 交回实例
    （容器看 currentWindow、门看 getProperties() 翻没翻）。
26. 混合行尾的文件不能按行号切（既有 CRLF 又有孤立 LF ⇒ 从第一个孤立 LF 起整体错开）。
    自检：(raw.match(/\r\n/g)||[]).length 与 raw.split('\n').length - 1 对不上就是混合行尾。
    手术脚本要么按内容定位（raw.indexOf(锚点) + 括号配平），要么先统一了再切、搬完换回去。
27. 要回调一堆实例方法的层，第一参数收 self。判据："只读几项"用 ctx，"要改"或"要回调"用 self。
28. 模块够不着私有方法，就把它塞进 ctx：cancelCollect: (bb, o) => this.#cancelCollect(bb, o)
    （私有名在模块外面不能用字符串取）。
29. 搬方法时 JSDoc 也要一起搬（脚本删到哪儿，就把那儿的 JSDoc 写进新模块，或在 core 原位留一行指针）；
    分节注释（/* ─── 世界观察器 ─── */）同样跟着走。丢了注释不影响任何自动检查。
30. 薄包装和 import 撞名时 import 取别名：import { startObserver as startObserverImpl, … }
    （类方法名不进词法作用域，能跑但读的人会以为是递归）。
31. 搬进"已经存在的模块"时，那个模块头注释里的"N 件事"也要改 —— 头注释是这个项目"这个模块负责什么"的索引。
32. 搬进已有模块时把新成员要用的兄弟依赖补进 import，补之前先确认不会成环。
33. 新写的头注释里不许出现 */：写 $DSH_HOME/profiles/*/vendor 这种 glob 会提前关掉块注释，
    node --check 报的行号在注释中间很迷惑。用 <profile> 占位或反斜杠。
34. A/B 两边抛同一个错也算"通过" ⇒ 每条 A/B 都要配"真的走通了吗"的断言（输出非 null、!ea && !eb）。
35. 手术脚本的"不许残留 this."自检要先把注释剥掉：
    const bare = s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '')
    —— 注释里的 this. 是踩坑说明，代码里的才是残留。
36. 改调用点的正则要连"尾参"一起改（await this.connect({...}) → await connect(self, {...}, ctx)）；
    自检里加一条"新调用点的参数个数对得上"。
37. A/B 两边不能共用一份"状态会变"的假件（假 bot 的 entity.isInWater 是时变的）；
    假件里带时间 / 次数 / 状态的字段，A/B 就不能共享 —— 新旧各造一份，B 要在 A 跑完之后再造。
38. 按签名找函数体时 indexOf('{') 会先撞上参数里的解构 {
    （async #walkPathfinder (target, { arrive = 1.6, … } = {}) {）⇒ 先取第一个换行、再 lastIndexOf('{', nl)。
39. 手术脚本要"先全查、后写盘"：所有锚点（要删的、要插的、import 的）先验完，最后才写文件。
    import 锚点别按"单行 import"去猜（movement 的 import 是多行的，锚点只取 } from './movement.mjs'）。
40. A/B 全绿不等于那条路走到了：写完用例回头问一句"这条分支的前置条件是什么"，照着摆世界。
41. A/B 全绿 + 调用序列一致，也可能是同一份用例把两边带到同一条错路上
    （dig 的 40 条断言全绿，四条出口全走的是"够不着"那条）⇒ 每条用例配一条"这条路真的走到了"的断言，
    并把输出打出来看一眼。
42. 带定时器的状态层：状态字段留在实例，读写逻辑搬进模块（holdControl/#releaseControls 只搬读写，
    租约表 _ctrlLease 留 core.mjs）。
43. "抠旧实现"要连它依赖的模块级 import 一起搬：判据是"方法体 + 它引用的所有模块级标识符
    （函数、常量、类）"，不只是 import 名。
44. 模块里出现 mineflayer / prismarine 字样（哪怕只是 import）就该停下来看看。
45. 自写冒烟的 t 兜底写成 ctx.t ?? ((p) => p)，不必每次造一个真的闸门。
46. 拆分收尾用 check-module-load.mjs 体检（30/0：拆出去的模块全都 import 得进来）。

文档索引