# 架构与开发 通用MCP路径:`MCP客户端 → src/mcp-server.mjs → ClientActions → 本机认证RPC → Fabric真实玩家`。标准MCP不要求DeepSeek或直播平台。 DSH基础入口在`dsh`,通过宿主webServer挂载模式栏按钮和启动路由,打开浏览器控制台。插件安装器已安装的SDK/yaml/zod在工作区通过目录链接复用,首次启动创建日志目录;失效链接或不完整依赖可修复。默认托管工作区升级先备份源码,保留data/runtime;外部指定项目不自动覆盖。退出只清理拥有的进程。 ## 环境准备 - `versions.json`固定12个游戏版本的官方客户端/服务端元数据及模组校验值。 - `src/versions.mjs`检查默认或指定目录内原版JAR的SHA1,识别第三方启动器版本文件夹;不同版本分开世界、数据库和模型记忆,保留旧1.21.4位置。 - `src/game-setup.mjs`负责检查、便携Java21、运行库与资源、预构建模组及版本启动配置。最终用户无需Git、Python、JDK或Gradle。 - `src/downloads.mjs`流式下载、校验、重试、取消和有界子进程。资源别名按目标路径去重,避免并发争用临时文件。 - `src/setup-state.mjs`记录实际阶段/进度/可恢复错误;控制台使用同一状态展示。Java、游戏、网络、占用端口、连接等失败有具体提示。 - `src/runtime.mjs`在真实玩家连接、状态读取和保存冻结后才进入ready;准备可取消,窗口关闭会使ready失效。 运行组件写在工作区;不改系统PATH、证书校验、代理、安全设置、自启或系统服务。游戏资源从官方源获取,客户端本体由使用者已有安装提供。下载只复用通过校验的完整文件。 ## 游戏与显示 Store.goal既是控制台阶段目标,也是overlayState.goal和每轮决策明确读回的目标。原生FishHud在左上角独立绘制自动换行目标板,气泡留出其下方空间;备用网页读同一字段。目标只经原有set_goal/目标工具更新并保存,动作say不改它;未改变历史上限、观察信息或上下文保留策略。 dig_tunnel的up坡度每步升高一级,先清起步列额外头顶,再清前方身体空间;核对支撑后用普通跳跃与前进,不挖掉脚下支撑。保留level/down及既有危险/取消检查。scripts/smoke_stairs.mjs用独立可回收1.21.4世界验证真实上/下阶梯、常驻目标、长句换行和直播关闭;输出原生截图,不调用模型。 `client-actions/spatial/tunnel/mining`提供有界动作和反馈;`FishSpatialScan`及其他客户端类负责真实观测。上游固定版本JS运行时随包提供,来源与许可证保存在bundled/mcpfabric。 可选`packages/dsh-minecraft-stream`只切换基础控制台的直播显示模式。默认普通界面不显示鲸鱼/气泡;直播模式通过游戏内HUD绘制,浏览器绿幕保留作备用。没有弹幕接收或自动推流。`FISH_OVERLAY_URL`可为开发测试指定独立的挂件数据地址,默认仍为本机控制台。 ## 连续近战与停滞恢复 背包主区装备到快捷栏第8格(索引7),避开Baritone自动整理镐的第1格;连续近战选武器使用同一目标格。`equip_item`读取装备前后的真实背包,等待150毫秒后核对手持物品ID和耐久,结果返回实际手持格子/物品/数量;未拿到目标物品时明确失败,不以原生接口的selected回执冒充完成。2026-11-05在1.21.4实际世界中,主区木板与工作台往返切换并保持700毫秒通过。 `combat.mjs`接收单个已观察UUID和真实背包武器,最多60秒内轮询目标、更新寻路和执行原生冷却攻击。它不选择新目标;目标消失不等于击杀,只有原生死亡证据才确认。低血、低氧、岩浆、近处苦力怕、耐久或无进展时提前返回,取消始终释放寻路。弓箭、爆炸目标和复杂群战未自动化。 自主循环限制连续被动等待,并在无进展时要求实际动作;需要时先诊断截图,未读图片不会被自动移动或新截图覆盖。`recovery.mjs`仅在稳定安全位置检查48个近邻方块,找到有支撑、两格身体空间且无已知危险的短路才移动,不挖掘、不假造目标进展。无可验证出口时明确交回模型重新规划。手动暂停、余额、时长和真正运行错误仍可停止。 开发烟测 `node scripts/smoke_combat.mjs` 创建独立可回收测试世界,验证牛、两只骷髅、取消及局部脱困,默认不调用模型;`--model`额外执行一次有余额保护的真实决策。2026-11-02在1.21.4普通难度、既有辅助效果、石剑无护甲下两次单骷髅均4次挥击约4.4秒击杀;这不等于所有地形、群战或其他版本的战斗验收。 ## 容器窗口观察 `FishContainerState`只读当前真实玩家菜单,保留原生格子编号、背包格映射、空格、光标物品、槽位取放条件、窗口同步属性及交易报价。`container-state.mjs`按已知原版布局标记用途,相同取放条件按格子组压缩;未知布局保持unknown,不伪装为箱子。工作台、酿造台、铁砧、锻造/切石/织布/制图、交易和存储类窗口复用同一层。原生允许放入某物品不等于存在配方。 默认烹饪配方索引由`cooking_index.py`从对应版本官方客户端生成,解析标签并校验摘要;不要求用户编译或执行Python。熔炉输出与当前配方产物不兼容、输出满或原生禁止取出时明确报告。燃烧/烹饪、酿造、铁砧费用来自实际菜单同步属性;未知状态不推测。自定义数据包覆盖默认配方的情形未专项验证,索引来源会标明。 打开/传输后的工具结果附带新的结构化容器状态;关闭后验证实际界面,已关闭的重复请求返回SCREEN_ALREADY_CLOSED并进入原有重规划保护。这是观察和反馈能力,不代表所有特殊窗口按钮的自动操作都已实现。 ## 移动镜头与环境发现 寻路开始时关闭Baritone的freeLook和remainWithExistingLookDirection,启用smoothLook,由实际路径控制镜头;不固定盯住终点坐标,不影响停下后的普通观察/交互瞄准。控制台继续使用原生玩家第一视角。 空间扫描附带当前位置客户端群系注册表ID。`discovery.mjs`只从射线可见体素归纳矿井、遗迹、紫晶、洞穴植被等组合线索,结构统一标possible;不查种子、服务器结构坐标或隔墙特征。当前位置群系是实测事实,结构名称是推断,二者不混用。重复看到同一地点不会每轮作为新发现。 连续矿道在每次挖开/推进后检查新线索;移动/探索/采集任务每约2秒检查,重要新发现时取消本人机械任务并返回interrupted/new_environment及真实部分进展。模型自行决定探索、避险或记位置后继续主线,不由程序预设探索路线。新事件可在动作同次请求附带reaction,已交付的事件不会下一轮反复标新;危急状态仍优先脱险。控制台空间详情展示群系、线索及新事件。 ## 上下文记忆 `src/memory.mjs`统一设置500000输入token触发、100000token近期保留目标、16000字符摘要上限。借鉴本机DSH compaction-basic的“旧记录摘要+近期完整消息”方式,没有引入其会话存储/token-meter/LLM运行时或修改DSH配置。游戏仍直接调用官方API。 API只在请求后报告准确用量:下一请求压力用上次实报加UTF-8字节增长保守估量,图片按1024token预留,不将base64当文字。无有效计量时文本字节作为保守上界,因此可能提前整理;不是精确卡住500000token。整理后首轮用已测token/字节密度加20%余量重新估量,避免旧计量或字节回退导致立即重复整理;收到下一次API实报后恢复正常校准。保留目标用实报密度加余量估算,始终以完整工具调用/响应组为单位,不拆散同轮记录。固定提示/工具说明和最新状态也计入触发压力。 Agent在下一轮决策前发一次禁用工具的摘要请求,合并旧自动摘要、手动notes和真实历史;游戏当前状态优先于旧笔记。摘要、近期记录、手动笔记及计量按世界原子保存,重开继续。成功才替换旧历史;空摘要、截断、工具调用、请求/写盘失败保留原记录并暂停,不自动重试扣费。摘要请求复用原模型、余额保留线、取消/超时和用量统计;截图留待游戏决策,不重复发给摘要请求。 Runtime使用现有玩家/服务端冻结功能,整理期间不计游戏时长;开启直播扩展时原生与网页气泡持续显示“正在压缩上下文”。仅成功且人工暂停/断线/世界生命周期未变化才解冻。无需新增模型工具、依赖或后台任务。独立MCP客户端的上下文仍由其宿主管理。 实施清单见[上下文整理计划](superpowers/plans/2026-11-05-context-memory.md)。 ## 辅助通关 `locate_resource`只在调用时查询:`target`可选`lava_lake/nether_fortress/village/ruined_portal/stronghold/piglin/blaze/enderman`。岩浆/生物`radius`16–256格,结构`structureChunks`1–64区块;结构使用服务端定位,岩浆仅逐批扫描已加载地形中的暴露源簇,不为查询生成新区块,返回候选而不冒称全局最近或安全入口。生物只查当前加载范围,最多返回5个成年/目标实体,不向模型倾倒整张地图。查询有时限,未找到与未完成范围分开说明。 `barter_piglins`参数为`item`(如`ender_pearl`,也接受minecraft前缀)、新增`count`、`goldBudget`(1–64枚)、可选`seconds`(15–180,默认120)和`uuid`。只在地狱使用:留两空槽、至少两块普通建筑块与金锭,选择会主动靠近的成年近战猪灵,搭台时提供5秒临时抗击退(不减伤、不持久保存),正常跳跃放置两格高台、手持金锭按Q式定向逐枚投掷,核对花费、等待交换、正常走下高台拾取。返回`goldOffers/goldSpent/observedDrops/receivedItems/gained`;目击或金锭消失不能证明获得珍珠。危险、取消、预算耗尽、未确认交换或无可验证落地处时停止,可能留在高台上;建筑块和金锭正常消耗,不凭空补资源。 托管服务器中普通持弩猪灵不把DeepSeekFish选为攻击目标;普通近战猪灵、猪灵蛮兵及其他怪物保持原行为。该规则随服务器启动参数启用,不给其他玩家全局无敌。客户端桥仅暴露同机每世界请求目录;请求经临时JSON文件交给现有服务端tick处理,不增加监听端口、系统服务或独立机器人。位置提示、交易观察只在调用时返回,不自动加入每轮上下文;模型工具仅新增上述两个。既有observe默认扫描从6区块降为1、上限2;未传notes的目标更新保留旧记忆,提供notes时才替换。复用代码及许可见THIRD_PARTY.md。 本轮验证与未验证范围维护在[兼容表](compatibility.md),不以编译通过替代实际交易、复杂自然地形或通关验收。关闭游戏即停止这些辅助;源码回退并重新构建/准备会恢复旧规则,原存档保留。 本轮实施步骤见[辅助通关计划](superpowers/plans/2026-11-05-assisted-progression.md)。 ## 构建与验证 源码开发需要Node22.16+、Python、Git和JDK21;这些是维护者工具,不是最终用户的安装要求。 ```powershell npm ci --ignore-scripts git clone --depth 1 --branch v0.8.0 https://github.com/denfry/mcpfabric.git vendor/mcpfabric # 确认上游revision与vendor-lock.json一致。 python -X utf8 scripts/build_helpers.py npm test node scripts/check_package.mjs npm pack --pack-destination outputs ``` `scripts/build_helpers.py`按版本生成兼容源并编译,Java构建产物位于artifacts/helpers,受Git忽略、由发布包携带。`scripts/bundle_runtime.mjs`从固定上游已编译dist生成随包JS副本;更新该副本前在上游mcp-server中使用仓库锁文件完成npm ci/build,保留MIT声明。 Fabric启动清单和Maven SHA1锁定在fabric-lock.json,按完整游戏/加载器版本校验,与发布包一起提供;更新versions.json的加载器或版本集合时运行 `node scripts/update_fabric_lock.mjs` 从官方接口重新生成,check_package会检查全部12版本。准备优先读取内置清单,再读runtime/versions/<版本>/fabric-metadata-<加载器>.json缓存,最后才联网补取;补取单次15秒、最多3次、可取消,全部校验值取得后才原子写缓存。二进制仍由downloadVerified逐一校验,不因使用内置清单而跳过完整性检查。 ```powershell node scripts/smoke_game.mjs --version 1.21.4 --minecraft-home D:/Games/.minecraft/versions/1.21.4/1.21.4.jar ``` 省略路径时,该开发脚本从本机Gradle构建缓存复用官方客户端。它使用独立smoke-v3测试世界,真实启动/连接/挖木/截图/辅助效果/冻结/关闭,且不调用模型。输出证据在outputs/smoke;`record_validation.mjs`根据真实报告更新兼容表。可以只在本次子进程设置`FISH_PORTABLE_JAVA_ONLY=1`验证缺少系统Java时的自动下载分支。 2026-11-01安装验收使用独立DSH profile安装两个tarball,创建空工作区,强制只用便携Java。实测缺游戏提示、选择已有游戏目录、下载Java、取消/重试、准备并冻结、关闭游戏后的失效提示、缓存重开及原生气泡。它复用了本机已有DSH和游戏安装/资源,不等于全新Windows电脑或所有网络环境的验收;原生文件夹选择对话框仍需人工点选。 GitHub Actions按12版本编译,合并产物后运行测试、包内完整性及排除规则检查;版本标签通过构建后自动生成两个Release安装包。CI编译和本机实机验收分别记录,不互相替代。发布前应以新profile安装tarball验证,不在同一profile直接把仍指向开发源码的link安装替换为tarball。 世界、凭据、日志、下载、游戏JAR和测试数据不进入公开提交或发布包。敏感凭据始终留在DSH原位置或受控子进程环境;公开挂件接口不包含控制错误或密钥。 ## 第三方仓库检查 2026-11-05已在GitHub安装M8ven Verify,仅选择`tianyingAquila/minecraft-native-mcp`。GitHub安装设置实测确认仓库权限为只读源码、元数据和Dependabot告警;安装时还授权读取账号邮箱地址。该集成用于通知M8ven代码更新并安排复检,属于仓库维护服务,无需游戏使用者安装或提供DeepSeek密钥。 本次已确认GitHub安装存在、仅选中此仓库,M8ven回调返回已连接1个仓库。公开收录页暂仍显示`Live Monitored: not connected`及旧提交`447d84a`,因此发布者认领、Live显示及推送后自动重扫尚未验收;以[收录页](https://m8ven.ai/mcp/tianyingaquila/minecraft-native-mcp)的实际扫描提交和日期核对,不能由已安装推断检查已通过。 暂停或撤销:GitHub个人设置 → Applications → [Installed GitHub Apps](https://github.com/settings/installations) → M8ven Verify → Configure,使用Suspend暂停或Uninstall卸载。需要撤销账号邮箱授权时,同时在Authorized GitHub Apps中找到M8ven Verify并撤销。恢复时从[M8ven连接页](https://m8ven.ai/connect)重新安装并仅选择此仓库。集成权限不会修改源码;README徽章可单独移除。