看我在 Minecraft 里的状态：在线 / 坐标 / 朝向 / 血量 / 饱食度 / 手持物 / 模式（active 或 standby）/ 看门狗是否在守 / 最近 3 条聊天。 要完整明细（连接信息、看门狗全部开关、最近 5 条聊天原文）传 verbose:true。

探测局域网里的 Minecraft 服务器（只读：不连接、不进服）。只听原版"对局域网开放"那条多播公告（224.0.2.60:4445，[MOTD]…[/MOTD][AD]端口[/AD]，1.5 秒一次），听到就拿到地址+端口+MOTD。 🔴 不扫端口、不发探测包，所以恒定在 seconds 秒内返回（默认 3，上限 15）；拿到后用 mc_connect 进服。 没听到时：确认对方真开了"对局域网开放"（或 enable-lan-visibility）；部分 WiFi / VPN / 容器会挡多播，那种直接问对方地址。

【单地址探测】已知地址时先问一句"你是谁、通不通"——发一次 Minecraft STATUS ping，拿 通不通 / 版本 / 协议号 / MOTD / 人数 / 延迟。 🔴 不登录、不用账户、不进服，拿到就断；超时自己兜，不会挂住。连不上时把原因说成人话（ECONNREFUSED=端口没人听 / ENOTFOUND=域名拼错 / 超时=防火墙或 enable-status=false）。 分工：先用 mc_ping 确认地址与版本（推荐）再 mc_connect 进服；不知道地址时用 mc_lan 听局域网公告。

连接到 MC 服务器。这里没有账号密码——用哪个账户由mc_accounts 维护的账户决定： 先用 mc_accounts 看有哪些账户（action:"use" 选定，或用 account 参数指名 innerID）。 服务器地址/端口/子服由你传（host 不传就看环境变量 MC_HOST，两个都没有会直接报错）；连接成功后会等区块加载完成。 登录失败时会明确说"需要用户处理"——那就告诉用户去终端跑 mcp-mc-agent accounts login <innerID>（正版）或 accounts refresh <innerID>（皮肤站）。

【账户】列出 / 搜索 / 刷新 / 选定 MC 账户。永远拿不到密码或 token。 action： · list（默认）列出所有账户：innerID / 游戏名 / UUID / 类型（离线或皮肤站）/ 服务器名与地址 / 是否已存凭据 · search 按关键词搜（名字、UUID、服务器名、登录账号）：给 query · use 选定本会话要用的账户：给 innerID（之后 mc_connect 用它） · refresh 刷新登录状态（皮肤站去认证服换新令牌）：innerID 不传用当前选定/默认的 ⚠️ 失败时带 needUserAction —— 明确告诉用户在终端跑 mcp-mc-agent accounts refresh <innerID>（皮肤站）或 accounts login <innerID>（正版）；密码只有用户能填。

停止本会话的 Minecraft：先尝试优雅退出游戏，再清空本会话全部后台任务（看门狗在里面）。 ⚠️ 它不会中断你自己当前这一轮（你正跑在这轮里，自我 abort 会表现为 "tool call aborted"）。所以它适合"我不想玩了，下线"——想停掉自己正在跑的动作，直接别再调工具就行。 ⚠️ MCP 下没有"强制停止"按钮（旧 Web GUI 入口已无），且 server 管不到客户端那一轮（stoppedLLM 恒为 false 就是这个意思）——这个工具就是唯一的停止路径。

从 MC 下线（当前会话的机器人退出游戏）。不影响其他会话的机器人。看门狗会自动关闭并提醒你。

在 MC 公屏说话（游戏里所有玩家能看到）。

看门狗控制。进服自动挂载、退服自动卸载，整局持续运行：记录事件，命中唤醒条件就写一条进事件队列（用 mc_events 取走），并发一条 MCP 日志通知（只是提示，内容以 mc_events 为准）。 ⚠️ MCP 是"你问它答"：没人能把消息塞进你的上下文——叫醒不会自己蹦到你面前，得主动 mc_events 去收。 action="status"（默认）看状态与配置；"arm" 手动挂载；"disarm" 关闭；"log" 看最近事件留档（含被传送/捡物这类不进队列的）。默认叫醒：有人喊我 / 身边有人说话 / 任何玩家说话（wakeOn.anyChat，默认开）/ 受击 / 死亡 / 被传送 / 断线。唤醒条件/近距半径/心跳/观察窗口等用 mc_config 调（有默认值）。

读写本会话的 MC 配置（看门狗唤醒条件、近距半径、心跳间隔、观察窗口、叫法等）。不传参数 = 看当前配置 + 默认值。改配置传 patch；嵌套项用点号键，如 {"wakeOn.itemPickup":true,"nearRadius":24,"mentionPatterns":["ds","用户"]}。嫌"任何玩家说话都叫醒"太吵就把 "wakeOn.anyChat" 设成 false。叫法是配置不是硬编码——学到玩家的新称呼就加进 mentionPatterns。

【边界信息】这个插件能做什么、边界在哪：支持的 MC 版本范围（testedVersions）、底层 mineflayer 版本、支持的登录方式、工具命名空间、各种上限（序列步数/记忆大小/事件队列）以及当前配置要点。 进服前不确定版本能不能连时先看它；确实不支持就如实告诉 Master，别硬试。

列出当前所有活跃的 MC 会话实例（诊断用：确认各会话的 bot 状态、连接信息）。

读取/消费当前会话的 MC 事件队列（看门狗记下来的：聊天、系统消息、受伤、上线/死亡/重连/断线）。默认消费掉；peek=true 只看不清（都是最早的先出）。返回一行一条（时间 + 类型 + 内容），省 token。 ⚠️ 被传送 / 捡物 / 其他玩家上下线不在这里（那些只在看门狗的留档里，用 mc_watch {action:"log"} 看）。 ⚠️ waitSec 是兜底，别用它长时间空等：有人叫你（mention）/ 受击 / 死亡 / 断线时，看门狗会打断这个等待（返回里 interrupted:true 就是在告诉你"有人找你了"，唤醒内容同时已经记进事件队列——就在上面那几行里）。真需要盯着某一类事件时才给 waitSec（上限 10 秒）。

扫描我周围方块：给 name 就找这种方块的位置；不给就返回方块统计。

看周围地形。默认给"脚下方块那一层"（地板层图：这一层哪里是实心地面、哪里是坑/岩浆/未加载）：· 能站 # 墙 v 会掉下去 ~ 水 ≈ 岩浆 ? 未加载。mode="floor"（默认）/ "auto"（地下自动切洞穴层：# 墙 · 能站 ↓ 低一格 v 会掉 * 矿石）/ "surface"（地表：@ 我 · . 沙 · " 草木 · T 木构 · : 石/建筑 · _ 土/农田）/ "cave"/ "column"（竖列：只看你脚下这一格，往下几格实心、哪里开始是空的）；slab = 洞穴层上下各看几格（默认 2）。format="image" 出俯视图像（有视觉的模型能直接看，并落盘）。字符图省 token 且坐标精确；形状/外观问题用图像。

看背包、装备栏和手持物品。

移动。mode="walk" 走过去（自动避障；在水里会自动改成"直接游"，实测 2 格/秒）；mode="fly" 创造模式直飞（最稳，创造模式默认用它）；mode="jump" 原地跳一下（爬台阶/脱困，不需要坐标）；mode="swim" 在水里游到 x/y/z（不给坐标就只上浮换气）。 🔴 一次只走 10 秒（用户要求：单次调用别超过 11 秒）。没走到会返回 arrived:false + remaining（还差几格）+ hint——直接再叫一次 mc_move 往同一个目标走就行，会从当前位置接着走；走远路就是连着叫几次，比一次挂 90 秒好（挂住的时候用户看不到消息）。 🔴 在水里（mc_status 里 在水里）寻路基本不动（A* 不把水当节点，实机"4 秒只挪 1 格"）：mc_move 会自动直接游（按住 forward+jump 浮在水面，实测 2 格/秒），上了岸再交回寻路。快淹死了就 mode:"swim" 不给坐标（只上浮换气）：水挖不掉，别去 mc_dig 水。 🔴 路上自己垫方块上去（pillared）会报 pillaredWith/held——手上会变成垫脚那种方块，别以为还攥着镐（要挖就 mc_act{mode:"break"}，它会自己换）。

与游戏世界互动（优先用它，别用服务器指令）。mode： · look 看向坐标(x,y,z)或玩家(who)："看向我" = look + who · toward 看向并走近某个玩家(who) · place 放方块到 (x,y,z)；悬空先垫脚（=搭高） · bridge 搭路：朝 (x,y,z) 一格格铺（铺在脚下一层），每块等服务端确认了才走；有坠落/岩浆风险就停 · break 破坏 (x,y,z)：先自动换对的工具；换不上就拒绝 · use 使用方块或实体(who)：开门、按钮、拉杆、喂动物；都不给=用手上的东西 · useitem 用手上的东西：扔眼睛/雪球、拉弓、喝药水 · attack 打实体：who 按名字找（中英文都认，24 格内会追）；不给就打 4.5 格内最近的（怪优先）。约 10 秒 · equip 装备(name)：护甲自动穿到对应格（盾→副手），其余拿到手上；to 指定格子 · enchant 附魔台：自动开窗放料；option:0-2 真附魔，不给只报选项 · anvil 铁砧：action:combine(默认) / rename；item + name · smithing 锻造台：item 底座、name 附加、template 模板 · toss 丢弃物品(name, count)

创造模式直接获取物品（协议级改槽位，非 OP 也能用）。给英文物品 id，如 oak_planks / diamond_sword / white_concrete。clearAll=true 清空背包。

按顺序执行一串世界交互（替代"写脚本"）：适合"走到这里放几个方块，再走到那里放几个"这类连串动作。 steps 是数组，每项 op 可为：wait(sec) / move(x,y,z,mode) / look(x,y,z 或 who) / toward(who) / place(x,y,z,name) / break(x,y,z) / dig(name 或 x,y,z,count) / use(x,y,z 或 who) / useitem(hold) / attack(who) / equip(name) / give(name,count) / toss(name,count) / say(text) / jump / swim(x,y,z 或 hold)。 逐步执行，默认遇错即停。 🔴 整串只跑 10 秒（用户要求：单次调用别超过 11 秒）。没跑完会返回 stoppedAt（停在第几步，从 0 数）+ remaining + hint——再叫一次 mc_sequence，steps 从停下的那一步往后发就行，前面已经做完了。所以宁可拆成"一串 3~4 步"叫几次，也别写一大串（一大串跑到 10 秒就断了）。

批量搭方块：把 (x1,y1,z1)–(x2,y2,z2) 这个实心长方体用 name 方块搭出来（会自己走近/垫脚，上限 max 个）。适合"搭一面墙/一根柱子/一个平台"，比一个个 mc_act{place} 省事。结果带 used/held。 🔴 一次只放 10 秒的量（用户要求：单次调用别超过 11 秒）。没放完会返回 remaining + hint——再叫一次 mc_build、范围原样重发就行，已经放对的格子会自动跳过（不会报"这格已经有方块"）。

挖方块：给 name 挖最近的，或给 pos 挖指定坐标；count 可连续挖多个（会自己换成对的工具；结果带 held）。 🔴 一次只挖 10 秒的量（用户要求：单次调用别超过 11 秒）。没挖完会返回"这一轮的 11 秒用完了"——再叫一次 mc_dig 接着挖就行（挖到的方块留在背包里，不会白挖）。

长活儿进度台账（挖 4 个以上自动开），存记忆根 tasks.json，掉线重连都还在。 run 一轮推进一步；resume 复核；plan/step 记账。

以玩家身份执行服务器指令。白名单可配置（默认 tp/give/time/weather/say/gamemode/effect/setblock/fill/clone/summon/title/clear/xp）。要放行别的指令，在普通会话里用 mc_admin_config 改 commandWhitelist（MC 模式会话改不了）。 ⚠️ 这是最后手段：正经动作优先 mc_act / mc_build / mc_move（那些不需要 OP）。

图像能力。SVG 是编辑语言：布局/画框/加文字（含中文）/拼网格都直接写 SVG 文本，再用这个工具光栅化成 PNG。 action： · info 看图的尺寸/格式（也能确认文件是不是能用的图） · embed 把图片变成 data URI + 现成 <image> 标签 —— 往 SVG 里引图必须这么做 · render SVG → PNG（可给 width/height/scale；svg 文本或 svgPath 二选一） · grid 把多张图按网格拼成可继续编辑的 SVG 文本（省掉重复写 N 个 和算坐标） · save 把 SVG 文本或 PNG 字节落盘 输出默认落 .mcp-mc-agent/.out/。图会直接内联给你；要留一份给别人看就写发布区 .mcp-mc-agent/.express/<子目录>/x.png，再用 mc_kit_express 取。

把发布区（.mcp-mc-agent/.express/）里的文件给用户。 · 入参 path：发布区下的文件（相对或绝对；必须在 .mcp-mc-agent/.express/ 下）； · 返回一行，内容取决于 mc_admin_config 里 expressBase 有没有配： · 没配（默认）：只回一句"文件分享已关闭…"——那就把文件的绝对路径告诉用户，让用户自己打开； · 开启：回完整 URL——图片 ![图片名](url)、其它文件 [文件名](url) 嵌进回复里； · 链接原样使用，不要再补 http://… 或域名。 ⚠️ 只有发布区（.mcp-mc-agent/.express/）下的文件可分享。

长期记忆（跨会话、重启后还在），放在 .mcp-mc-agent/ 里，按服务器建子文件夹（_global/ 放通用的）。 索引由你自己维护：README.md（server 把它的内容 + 目录树放进 instructions，忘了更新也不失真，但改了记忆就顺手更新它）。 action： · index（默认）看总览：有哪些文件夹/文件、各多少条、README 现状 · kinds 四类记忆的说明 + 各类各有几个文件 · record 记一条带元数据的记忆（推荐；同 key 累加成功/失败，不堆重复） · read 读文件（path 或 topic+server）；读图片会直接给你看 · append 追加一条（同 key 覆盖）—— 只对文本文件 · write 整文件覆盖（重组内容/小标题/表格） · put 把工作区里的任意文件（图片最常用）复制进记忆 · delete 删文件（path 指向目录则整目录删） · search 跨文本文件搜关键词，返回命中行 路径写法：path:"mc.example.com/maps/town.png" 或 topic:"landmarks"（server 默认当前服，不传进 _global/）。 ⚠️ 只读写文件，不执行任何东西（没有 shell）。

【管理】读写 mcp-mc-agent 的全局配置（指令白名单、记忆目录…）。 ⚠️ MCP 下没有 preset 分档：注册的工具全都能调，mcModePresets/mcPlusPresets/mcMode.* 是 DSH 遗留键，改了没效果（真限制只有 commandWhitelist）。 action： · get（默认）看生效配置（给 path 看单项） · set 改一项（path + value）· unset 删一项（回默认）· reset 全恢复默认 · list 默认值 + 生效值 可用键：commandWhitelist（数组；"tp" 精确、"/^gi./" 正则、"" 全放行）· mcModePresets/mcPlusPresets/mcMode.allowOtherTools/mcMode.hideAdminTools（DSH 遗留，见上）· memoryDir（记忆根目录）· memoryPerSession（true = 每会话一份独立记忆 <memoryDir>/sessions/<短会话 id>/，看不到别的会话；默认 false = 共用一份）。 ⚠️ expressEnabled/expressBase（文件分享）是 DSH 遗留键：MCP 没有内置文件服务托管发布区，mc_kit_express 会直接回"请把绝对路径告诉用户"。 改完立即生效，落在状态目录的 config.json（默认 ~/.mcp-mc-agent/config.json）。

诊断：当前会话的机器人内部状态（物理/控制位/收包/事件队列/合成窗口与合成格）——排查"走不动/收不到消息/合成说缺料"用。同时报提示词状态（promptInjection：RULES.md / 版本提示.md 的文件位置、存在与否、字数、有没有进 instructions——MCP 没有"会话中注入"，提示词是握手时一次性给的），以及性能监测（perf：每个动作的墙钟 / CPU / 期间事件循环延迟 —— 判断"要不要把某个动作搬进 Worker 线程"就看它）。

🤖 自主行为层（"让它像正常玩家一样"）：不传参数 = 看状态。 两层：① 反射层（不花 token、常开）：AI 没调工具时我自己环顾、饿了吃、捡掉落物、躲岩浆火仙人掌、跟随玩家。被怪打 / 有怪贴上来 → 立刻叫醒 AI 定策略（还手/撤/垒方块由 AI 决定）；我自己不跑、不还手，只把手里那件活停下（dangerStopWork 可关；叫醒文案带怪名/坐标/距离/血量）。远程怪（骷髅/掠夺者/女巫…）22 格内且看得见我才算威胁；挨打却看不到怪会报上次看到它在哪。水里憋气（头在水下）也会叫醒 AI 上浮：掉血或超 10 秒；真要憋死了我只按住 jump 抬一下，不横向跑。附近有玩家时我一直看着他（不动位置、不碰东西）；任何工具调用后静默 6s；走路类只在 AI 这一轮跑完时才动。 ② 空闲决策层（花 token）：AI 停下来（默认 5 秒没事干）且这一轮结束时，我用插件提示叫醒它，文案带"玩家在干什么"（距离/在动/手持/面向/最近聊天）+ 长期目标 + 没做完的任务，让它按长期目标自己开工（看图不强制；默认目标"像正常玩家一样发展、最后打末影龙"，路线木头/石具→铁→钻石→下界→末地；旁边有人一起干）。不许反问 Master"要我做什么"（不回话 = 让它自己决定）；只有要动 Master 的箱子/建筑时才 mc_say 问一句、问完不等。叫醒 45s 后还没动手，我会再补一条"别问，直接做"的催促（每次叫醒最多一条，也占额度）。 每小时最多 120 次；叫醒后 AI 没做任何事就自动翻倍拉长间隔（封顶 30 分钟），做了事就复位。 用法：action:"status"（默认）｜"off" 关反射层（🔴 不是"全停"：空闲叫醒还开着，要 set {"idleWake":false} 才全静音；自保 avoid 独立，要一起关得 set {"avoid":false}）｜"on" 全开｜"stay" 站定（停跟随）｜"follow" + who:"玩家名" 跟着谁走｜"wake" 立刻叫醒一次（不等间隔）｜"set" + patch:{"standing":"先盖个小屋再挖矿","idleWakeSec":600} 改参数（落 .mcp-mc-agent/auto.json）。 Master 在对话里改了主意 → 立刻用 set 把 standing 写成他那句新的；他没发话就别自己改。 🔴 默认只做无害动作：不会自己拆别人建筑、动别人箱子、乱丢东西、跑太远。

📦 存取箱子（真·仓库，走服务端的箱子/木桶，不是作弊给物）。背包只有 36 格，攒家当就靠它。 · action:"list"（默认）：看背包里有什么、附近有哪些箱子；给 x/y/z 就打开那个箱子列内容。 · action:"put"：把背包里的东西放进箱子（name:"iron_ingot", count:16，或 all:true 全放）。 · action:"take"：从箱子里拿出来（name:"coal", count:8，或 all:true 全拿）。 · 附近没有箱子、但背包里有，就自己放到脚边再用（placeChest:false 可关）；都没有会告诉你去 mc_craft {name:"chest"} 做一个（8 个木板）。 · all:true 是真的全搬（工具也会被放进去！想留东西就写 name，或者用 keep:"wooden_pickaxe,stone_sword" 留一手）。 · 背包满 / 箱子满 / 开不开都会如实说；搬完会重新读一遍箱子，告诉你现在里面有什么。 🔴 会动世界里的箱子，所以受 mc_observe 门禁限制（强制模式下要先看一眼）。

🧱 合成物品（真合成，走服务端的合成台，不是作弊给物）。生存模式下"原木→木板→工作台→木镐"就靠它。 · 会自动补齐中间产物：给它 name:"wooden_pickaxe"，它自己排"木板→木棍→木镐"的顺序一起做，不用你一步步算。 · 需要工作台时：附近有就直接用；附近没有但背包里有，就自己放到脚边再用（placeTable:false 可关）。 · 原料不够会告诉你缺什么、缺几个、现在有几个，并给出下一步该调哪个工具（比如先 mc_dig 砍原木）。 · name 可以写简称：planks 会自动选背包里那种原木对应的木板（选了哪个会写在结果里）。 · list:true 看配方/看当前能做什么；dryRun:true 只出计划不动手（拿不准就先 dryRun）。 · count 是"背包里一共要到几个"（默认 1）：已经够了就一个都不做，结果会如实说"一个都没做"。要"再做 4 个"就写 {count:4, more:true}。 · 🔴 连着两三次都"超时"就先 mc_scan 复核现场（我每次动手前都会先把合成格里的材料点回背包）。 🔴 合成只动背包、不动世界，所以不受 mc_observe 门禁限制。

🔥 熔炼（真熔炼，走服务端的熔炉，不是作弊给物）。生存模式下"粗铁 → 铁锭 → 铁镐"就靠它。 · 能烧：矿石/粗矿（铁、铜、金、远古残骸…）、沙 → 玻璃、圆石 → 石头、原木 → 木炭、生肉/马铃薯 → 熟的、黏土球 → 砖、海带 → 干海带、仙人掌 → 绿色染料 等等。 · 写产物名也行：name:"iron_ingot" 会自动找背包里的粗铁/铁矿石去烧。 · 附近没有熔炉、但背包里有，就自己放到脚边再用（placeFurnace:false 可关）；都没有会告诉你去 mc_craft {name:"furnace"} 做一个（8 个圆石）。 · 自己挑燃料：按要烧的数量算，一次放够 —— 有煤炭/木炭就先烧煤（木棍、原木、木板是合成料，只有没有正经燃料时才拿来烧）；要烧 1 个放 1 块煤（够烧 8 个），要烧 9 个放 2 块。可以 fuel:"coal" 指定；list:true 看背包里有哪些燃料。 · 🔴 装好料就返回，不用盯着：炉子在服务端自己烧。默认不盯（maxWaitSec 默认 0，最多给 10 秒）；过一会儿再叫一次 mc_furnace 就能收成品（不用重新装料）。要烧很多就少量多次（一次最多装 8 个）。 · takeOnly:true = 只把熔炉里已经烧好的拿走（不新塞东西）；dryRun:true 只出计划。 🔴 熔炼会动世界里的熔炉，所以受 mc_observe 门禁限制（强制模式要先看）。

👁 第一人称视角：从我眼睛（眼高 1.62）朝我正在看的方向渲染截图，直接内联给你看，并附三段式感知：① 我看到（图里数出来的：像素占比、谁在哪一侧、准星压着什么、手里拿什么）；② 程序检测到（游戏数据：坐标/朝向/独立射线打到的方块/半径内实体带坐标·距离·血量/脚下）；③ 不确定（客户端预测的方块世界、没加载的区块、读不到的血量 —— 别把推测当事实）。两套眼睛对不上时点名（以程序射线为准）。 图里：玩家（人形，正版皮肤就贴真的）· 怪物（敌对红/被动黄）· 掉落物（黑描边）、右下角手上的东西；暗紫色块=区块没加载。 👁 什么时候看，你自己定：只读查询（mc_status / mc_inventory / mc_scan…）不用看；动手前先看一眼最划算 —— 挖/放/拆/建、走路、找路找东西、确认玩家或怪在哪、看不清、被卡住；一张图够做一段动作；环境变了（走远/天黑/挨打）就再看一眼。 （想变回强制模式：.mcp-mc-agent/view.json 写 {"gate":true}。） 🔴 图已直接内联给你；想另存一份给别人看就把 out:"\.mcp-mc-agent/.express/<子目录>/view.png" 写进发布区，再用 mc_kit_express 取（默认落 .mcp-mc-agent/.out/）。