# AI 玩家阶段路线

本文档按能力模块重新整理 AI 玩家当前阶段路线。项目目标是：玩家用自然语言下达任务后，AI 通过 DeepSeek 理解意图、拆解目标，再由本地代码按照 Minecraft 生存模式允许的方式执行，包括观察、采集、合成、熔炼、挖矿、复盘和失败恢复。

状态说明：

- `[x] 已完成`：代码、文档和基础验证已完成。
- `[ ] 未开始`：后续新增阶段使用。
- `[~] 开发中`：阶段正在实现但尚未完成验证。

已完成阶段保持 `[x] 已完成`，新增阶段按实际进度维护。后续新增阶段必须追加到对应编号下，避免再插入到无关章节中。

## 1. 基础架构与生存边界

### 1.1 项目原则

状态：`[x] 已完成`

目标：确定 AI 玩家必须是普通生存玩家，而不是创造模式工具。

要求：

1. DeepSeek 只负责理解意图、高层计划和失败复盘。
2. 配方、材料数量、背包、箱子、工具等级、方块存在性和路径可达性由本地代码判断。
3. 不允许飞行、瞬移完成任务、凭空生成物品、创造模式放置或绕过材料消耗。
4. 所有世界交互必须在服务端线程内执行。
5. DeepSeek 请求必须异步，不能阻塞 server thread。

完成记录：项目已按生存玩家规则推进，DeepSeek 输出会经过动作白名单、配方系统和执行器校验。

验证：`./gradlew build` 通过。

### 1.2 Observe 观察层

状态：`[x] 已完成`

目标：把 AI 当前能知道的世界事实整理成稳定结构，供 DeepSeek 和本地验证器使用。

能力：

1. 导出 AI 背包、主手工具、装备、血量、位置和当前状态。
2. 扫描附近箱子、关键方块、洞穴入口、实体和敌对生物。
3. 记录维度、生物群系、昼夜、危险数量和玩家命令。
4. 支持 `/ai snapshot` 和 AI 面板输入 `snapshot` 查看观察 JSON。

完成记录：`WorldSnapshot` 已成为规划、配方、失败复盘和挖矿策略的统一输入。

验证：`./gradlew build` 通过。

### 1.3 RecipeResolver 配方递归层

状态：`[x] 已完成`

目标：用 Minecraft 原版配方和基础资源来源表递归计算目标物品的材料链。

能力：

1. 查询合成、熔炉、高炉、烟熏炉、营火、切石机和锻造台配方。
2. 根据当前 AI 背包和附近箱子扣减已有材料。
3. 递归追溯木头、圆石、煤、铁、金、钻石、红石、青金石等基础来源。
4. 对无配方、创造专属或环境条件不足的目标给出明确失败原因。
5. 避免让 DeepSeek 编造物品 ID、配方或材料数量。

完成记录：制作链已升级为“原版 RecipeManager 配方递归 + 基础资源来源表”，覆盖常规生存制作链。

验证：`./gradlew build` 通过。

### 1.4 DeepSeek Planner 规划层

状态：`[x] 已完成`

目标：让 DeepSeek 基于观察结果和本地配方事实生成高层计划。

能力：

1. 普通自然语言命令由 DeepSeek 理解。
2. 明确制作、采集、挖矿、烧炼、打水等目标优先走本地 `make_item` 生存链。
3. DeepSeek 只能输出声明过的高层动作。
4. 非法动作、错误物品 ID、错误数量和作弊能力会被本地拒绝或修正。
5. DeepSeek 不可用时，常见制作和采集任务仍有本地兜底。

完成记录：`TaskPlanner`、`PromptBuilder`、`PlanValidator` 和本地意图识别已协同工作。

验证：`./gradlew build` 通过。

### 1.5 Execute And Replan 执行复盘层

状态：`[x] 已完成`

目标：AI 不一次性执行完整大计划，而是小步执行并持续复盘。

执行循环：

```text
观察当前状态
解析玩家目标
查询配方链
生成高层计划
本地验证计划
执行一个 step
重新观察
判断目标是否完成
继续执行或复盘
```

触发复盘的情况：

1. step 完成。
2. 背包、箱子或工作站状态变化。
3. 找不到目标资源。
4. 路径长时间没有进展。
5. 工具缺失或耐久不足。
6. 附近危险过高。
7. 长任务达到策略心跳间隔。

完成记录：`MakeItemAction`、`TaskSession`、`StepExecutor`、`ReplanPolicy` 已形成观察、执行、复盘闭环。

验证：`./gradlew build` 通过。

## 2. Agent 规划、记忆与 DeepSeek 协作

### 2.1 意图理解与任务类型归一

状态：`[x] 已完成`

目标：把玩家的中文自然语言命令归一成稳定意图。

能力：

1. 识别制作、采集、烧炼、装水、停止、召回、背包、状态、定位和闲聊。
2. “给我 / 我要 / 做 / 弄 / 挖 / 找 / 采集”等说法归一到目标物品或资源。
3. “挖金锭”会理解为取得 `minecraft:gold_ingot`，不是寻找不存在的金锭方块。
4. 老的 `mine` 或 `craft` 风格任务会改写到更稳定的 `make_item`。

完成记录：`AgentIntentParser` 和 `TaskPlanner` 已覆盖常见中文任务。

验证：`./gradlew test --tests com.aiplayer.agent.AgentIntentParserTest` 通过。

### 2.2 DeepSeek 输入上下文标准化

状态：`[x] 已完成`

目标：让 DeepSeek 每次收到的上下文稳定、可控、不泄露 API key。

上下文包含：

1. 当前目标和当前 step。
2. AI 背包、附近箱子、附近方块、附近实体和洞穴摘要。
3. 当前坐标、Y 高度、维度、主手工具和危险信息。
4. 最近失败和最近 step 事件。
5. 允许动作清单。
6. 已知经验摘要。

完成记录：`AgentContext`、`PromptBuilder`、`MiningStrategyAdvisor` 已统一上下文结构。

验证：`./gradlew test --tests com.aiplayer.agent.AgentContextTest` 通过。

### 2.3 动作白名单与能力清单

状态：`[x] 已完成`

目标：DeepSeek 只能请求本地声明过的生存动作。

能力：

1. `ActionManifest` 声明允许动作和参数要求。
2. `make_item`、`gather_tree`、`gather_stone`、`craft_inventory`、`craft_station`、`fill_water`、`withdraw_chest`、`deposit_chest`、`return_to_owner` 等动作可被验证。
3. `teleport`、`give`、`setblock`、`summon`、`creative` 等能力被拒绝。
4. 动作参数缺失、类型错误或非法物品 ID 会生成 `PlanViolation`。

完成记录：动作白名单和计划守卫已覆盖 DeepSeek 规划、失败复盘和挖矿策略。

验证：`./gradlew test --tests com.aiplayer.agent.ActionManifestTest` 通过。

### 2.4 高层计划协议

状态：`[x] 已完成`

目标：把高层计划表达为结构化对象，便于验证、执行和复盘。

能力：

1. `AgentPlan` 记录目标、数量、step 列表、所需事实和失败策略。
2. `AgentPlanStep` 记录单个高层步骤。
3. `AgentPlanProtocol` 支持 JSON 解析、输出和协议校验。
4. 本地配方计划可以转换为 Agent 计划结构。

完成记录：Agent 计划协议已覆盖制作链和 DeepSeek 输出校验。

验证：`./gradlew test --tests com.aiplayer.agent.AgentPlanProtocolTest` 通过。

### 2.5 计划验证、修复与本地事实仲裁

状态：`[x] 已完成`

目标：DeepSeek 计划必须经过本地事实仲裁后才能执行。

能力：

1. 检查动作是否在白名单中。
2. 检查目标物品是否存在。
3. 检查数量和材料是否符合本地配方链。
4. 检查是否包含作弊动作。
5. 对可修复计划给出修复建议；不可修复时回退到本地配方计划或失败说明。

完成记录：`AgentPlanGuard` 和 `PlanValidator` 已用于计划校验。

验证：`./gradlew test --tests com.aiplayer.agent.AgentPlanGuardTest` 通过。

### 2.6 Step 执行事件

状态：`[x] 已完成`

目标：每个 step 都产生可追踪事件，用于日志、复盘和经验沉淀。

事件包含：

1. taskId。
2. stepId 和 step 序号。
3. 状态、消息和进度。
4. 开始 tick、结束 tick 和耗时。
5. 背包变化。
6. AI 执行位置。

完成记录：`StepExecutionEvent` 已接入 `MakeItemAction`，并写入 `make_item.log`。

验证：`./gradlew test --tests com.aiplayer.agent.StepExecutionEventTest` 通过。

### 2.7 循环调度器

状态：`[x] 已完成`

目标：统一判断何时继续、何时观察、何时复盘。

触发条件：

1. step 成功。
2. step 卡住。
3. 连续失败。
4. 背包或箱子变化。
5. 时间片结束。
6. 附近危险变化。

完成记录：`AgentLoopScheduler` 已定义这些调度条件。

验证：`./gradlew test --tests com.aiplayer.agent.AgentLoopSchedulerTest` 通过。

### 2.8 失败诊断与恢复策略

状态：`[x] 已完成`

目标：失败时不要只返回“失败”，而要分类并给出可执行恢复方向。

失败分类：

1. 材料不足。
2. 工具缺失。
3. 配方缺失。
4. 路径卡住。
5. 目标不可达。
6. 资源未找到。
7. 挖矿路线失败。
8. 环境危险。
9. 背包满。
10. 工作站缺失。
11. DeepSeek 输出非法。

完成记录：`FailureRecoveryAdvisor` 会基于失败文本和上下文给出本地兜底策略，DeepSeek 建议也必须通过白名单。

验证：`./gradlew test --tests com.aiplayer.agent.FailureRecoveryAdvisorTest --tests com.aiplayer.agent.FailureRecoveryTest` 通过。

### 2.9 会话记忆与玩家偏好

状态：`[x] 已完成`

目标：AI 能记住当前任务、近期失败、已拒绝目标、已知箱子、工作站和偏好。

能力：

1. `AgentSession` 保存当前 taskId、goal 和 target。
2. 保存最近命令和最近失败。
3. 保存已拒绝目标，避免短时间重复撞同一个点。
4. 保存已知箱子、工作站和矿洞信息。
5. 生成可发给 DeepSeek 的摘要。

完成记录：会话记忆已用于失败复盘和挖矿上下文。

验证：`./gradlew test --tests com.aiplayer.agent.AgentSessionTest` 通过。

### 2.10 技能记忆与本地 Critic

状态：`[x] 已完成`

目标：把成功任务沉淀为经验，并用本地事实判断任务是否真正完成。

能力：

1. `AgentSkillRecord` 记录成功目标、step、事件证据和失败规避信息。
2. `AgentSkillLibrary` 支持保存、检索、容量控制和 JSON 恢复。
3. `AiPlayerMemory` 持久化技能库。
4. `MakeItemAction` 成功后自动写入技能记录。
5. `AgentCritic` 用 `GoalChecker` 和真实背包判断目标是否完成。
6. 技能记忆只作为经验提示，不绕过本地配方、背包、箱子和世界校验。

完成记录：普通 DeepSeek 规划、失败复盘和挖矿策略上下文都能收到相关技能摘要；最终完成判定仍由本地 Critic 执行。

验证：`./gradlew test --tests com.aiplayer.agent.AgentSkillLibraryTest --tests com.aiplayer.agent.AgentContextTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 2.11 Agent 评测矩阵

状态：`[x] 已完成`

目标：建立固定回归用例，防止 AI 退化成只会聊天或只会硬编码。

覆盖场景：

1. 铁工具。
2. 金锭。
3. 黑曜石。
4. 熟牛肉。
5. 水桶。
6. 木门。
7. 砍树。
8. 停止、召回、背包、状态。
9. 闲聊。
10. 非法动作拒绝。

完成记录：`AgentEvaluationMatrix` 和相关测试已覆盖核心 Agent 能力。

验证：`./gradlew test --tests com.aiplayer.agent.AgentEvaluationMatrixTest` 通过。

## 3. 生存执行与玩家交互

### 3.1 制作链顺序优化

状态：`[x] 已完成`

目标：从空背包开始按普通玩家顺序完成木、石、铁、钻石等工具链。

典型链路：

```text
砍树 -> 木板 -> 木棍 -> 工作台 -> 木镐 -> 圆石 -> 石镐 -> 铁矿/煤 -> 熔炉 -> 铁锭 -> 铁工具
```

完成记录：配方计划会优先补齐采集工具，再处理矿物和熔炉。铁制工具会先做石镐，钻石工具会先做铁镐。

验证：`./gradlew test --tests com.aiplayer.recipe.SurvivalRecipePlanningTest` 通过。

### 3.2 持续资源会话

状态：`[x] 已完成`

目标：同一任务内连续采集资源时复用上下文，避免每个 step 都从零开始。

能力：

1. 记录已拒绝目标。
2. 记录矿洞入口、最近站位和洞穴入口。
3. 连续补圆石时复用刚挖出的矿洞。
4. 后续矿物 step 可复用已有矿井上下文。

完成记录：`ResourceGatherSession` 已持有跨 step 的资源和矿井状态。

验证：`./gradlew build` 通过。

### 3.3 路径、可达性与卡住恢复

状态：`[x] 已完成`

目标：AI 不能一直追逐不可达目标；普通资源可换目标，挖矿卡住要记录原因并结束任务。

能力：

1. 直接可触及方块优先。
2. 可寻路目标其次。
3. 普通资源目标移动无进展会加入拒绝集合。
4. 挖矿下探站位无进展会记录 debug 原因并终止任务。
5. 分支矿道站位也会使用移动进展检测。

完成记录：`StepExecutor` 已处理 `movement_stuck`、目标拒绝和下探站位超时。

验证：`./gradlew build` 通过。

### 3.4 工具、耐久与动作拟真

状态：`[x] 已完成`

目标：AI 做事时看起来像玩家，并真实消耗工具耐久。

能力：

1. 按方块类型选择镐、斧、铲、武器或空手。
2. 挖掘、砍树、放置和攻击时面向目标。
3. 工作时右手挥动。
4. 工具耐久不足时提前处理。
5. 工具损坏后从背包移除。

完成记录：`AiPlayerEntity`、`SurvivalUtils` 和各 action 已接入工具选择、挥手和耐久消耗。

验证：`./gradlew test --tests com.aiplayer.util.SurvivalToolRulesTest` 通过。

### 3.5 工作站生命周期

状态：`[x] 已完成`

目标：需要工作台、熔炉等工作站时，AI 必须找到或制作并放置工作站。

能力：

1. 检查附近已有工作站。
2. 没有工作站时递归制作。
3. 放置工作站时消耗 AI 背包物品。
4. 熔炼任务消耗原料和燃料后产出结果。
5. 支持工作台、熔炉、高炉、烟熏炉、营火、切石机和锻造台。

完成记录：`StepExecutor` 已处理工作站制作、放置和使用。

验证：`./gradlew build` 通过。

### 3.6 AI 背包与玩家交互

状态：`[x] 已完成`

目标：玩家能查看、转移和管理 AI 物品，并控制 AI 状态。

能力：

1. AI 拥有 36 格真实背包。
2. AI 面板最多显示 20 个 AI 背包格。
3. 打开 AI 背包时同时显示玩家背包和 AI 背包。
4. 支持玩家背包和 AI 背包之间直接转移物品。
5. 支持 `/ai backpack take`、`/ai backpack put` 等命令。
6. AI 面板提供“背包 / 状态 / 定位 / 召回”按钮。
7. `/ai recall` 立即停止任务并把 AI 移到玩家身边。
8. `/ai status` 和 `/ai location` 显示当前阶段、位置和背包摘要。
9. 任务队列完成后，AI 清空当前目标并按普通导航回到拥有者玩家身边。

完成记录：客户端面板、服务端命令和任务完成后的空闲回身均已实现。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 3.7 分类日志与回归文档

状态：`[x] 已完成`

目标：每类执行事实都能按分类日志追踪，并支持长期排查。

日志分类：

1. `planning`
2. `snapshot`
3. `recipe`
4. `action`
5. `make_item`
6. `mining`
7. `mining_strategy`
8. `llm`
9. `player`

完成记录：日志按 `run/log/<category>/` 写入，每个分类最多 3 个文件，单文件最大 100MB，采用 rotate 机制。

验证：`./gradlew build` 通过。

### 3.8 树木搜索与外扩探索

状态：`[x] 已完成`

目标：当 AI 从空背包制作工具链时，不再因为出生点附近 32 格没有树就立刻失败。

能力：

1. `make_item` 的 `gather_tree` step 先扫描近处树木，再分 tick 扫描更大的已加载区域。
2. 大范围扫描每 tick 有方块预算，只保留少量最近原木候选做路径检查。
3. 候选路径检查按 tick 限流，避免在 server thread 一次性创建大量路径。
4. 仍找不到树时，AI 会选择可达探索点向外移动，并到点后重新扫描。
5. 直接 `gather tree/wood` 动作也会按探索点移动，避免立即失败。
6. 彻底找不到树时，失败信息会带扫描半径、候选数量、可达数量和建议玩家移动或提供木材。

完成记录：`StepExecutor` 增加树木分批扫描、候选路径限流和探索点重扫；`GatherResourceAction` 增加树木探索兜底与扫描节流。

验证：`./gradlew build` 通过。

### 3.9 树木任务卡住诊断基线

状态：`[x] 已完成`

目标：把“任务长时间卡在第一步 `gather_tree minecraft:oak_log x1`”的问题固定为可复现、可诊断的回归场景。

背景问题：

1. 空背包制作金锭、铁工具、石工具等目标时，第一步通常是获取原木。
2. 日志显示附近存在原木候选，但 `reachable=0`，AI 长时间停留在第一步。
3. 探索点可能存在明显高度差，例如目标点在 Y=71，AI 停在 Y=64，导航无法真正到达。
4. `gather_tree` 被标记为 stateful step，周期性重规划会跳过它，因此卡住后不会快速退出。

开发内容：

1. 增加树木任务专项日志摘要，记录 `taskId`、当前位置、目标 step、近扫/远扫半径、候选数、可达数、路径检查数和探索点。
2. 记录每个不可达候选树的首要原因，例如无站位、路径为空、高差过大、区块未加载或目标已消失。
3. 记录探索点失败原因，例如移动无进展、导航完成但距离仍过远、站位失效或高度差过大。
4. 在 `make_item.log` 中输出树木任务累计耗时、扫描轮数、探索次数和最近失败原因。
5. 在回归文档中记录“空背包挖金锭卡在砍树”的复现步骤。

验证方式：

1. 运行 `runClient`，在无木头背包状态输入 `/ai say 帮我挖两块金锭`。
2. 确认 `make_item.log` 能解释为什么第一棵树不可达。
3. 确认日志不只显示 `reachable=0`，还要显示具体拒绝原因。

完成记录：`make_item.log` 的树木扫描日志已增加可砍站位、拒绝原因、连续不可达次数和探索失败次数；树木硬超时会输出扫描摘要并终止当前 step。

验证：`./gradlew build` 通过。

### 3.10 树干周围工作站位生成

状态：`[x] 已完成`

目标：树木搜索不能只判断树干方块本身，而要为每个树干生成普通玩家能站立并挥手砍树的工作站位。

开发内容：

1. 为每个候选原木扫描四个水平相邻方块、下方方块和可接受的近距离站位。
2. 站位必须满足脚部空气、头部空气、脚下有支撑、不是水、岩浆、基岩或危险坠落边缘。
3. 站位到原木距离必须在普通交互范围内。
4. 如果树干在高处，优先找树根附近可砍到的低位原木，而不是直接追逐树冠原木。
5. 为每个候选树保存 `logPos`、`standPos`、`distance`、`verticalDelta`、`reason`。

验证方式：

1. 单元测试覆盖平地树、斜坡树、雪地树、树干旁有水、树干悬空和树叶遮挡场景。
2. 实机确认 AI 会移动到树旁可站位，而不是树干方块坐标。

完成记录：`StepExecutor` 和 `GatherResourceAction` 现在会为原木目标解析可站立工作位；移动时优先走向站位，交互时仍面向原木方块。

验证：`./gradlew build` 通过。

### 3.11 树木候选评分与排序

状态：`[x] 已完成`

目标：在多个树木候选中优先选择最容易成功的一棵，而不是最近但不可达或站位差的树。

评分因素：

1. 可达站位存在优先于只有树干候选。
2. 路径距离短优先。
3. Y 高差小优先。
4. 树根低位原木优先于树冠高位原木。
5. 周围有多个同树原木优先，减少砍一块后重新找树。
6. 水边、悬崖边、复杂障碍物附近降低分数。

开发内容：

1. 新增树木候选评分结构。
2. 大范围扫描只保留评分最高的有限候选。
3. 路径检查按评分顺序执行。
4. 日志输出最终选择原因和前几个被拒绝候选的原因。

验证方式：

1. 构造多个树候选，确认 AI 选择可达近地树。
2. 日志能解释为什么没有选择最近但不可达的树。

完成记录：树木候选按可达工作位距离和高度差惩罚评分，优先选择可站位更近、Y 高差更小的原木。

验证：`./gradlew build` 通过。

### 3.12 探索点生成与黑名单

状态：`[x] 已完成`

目标：探索点必须真正能帮助接近树木区域，并且失败后不能反复选择同一片无效高低差区域。

开发内容：

1. 探索点必须由“候选树附近的可站位”或“朝向候选树的可达中继点”生成。
2. 探索点选择前先进行路径检查。
3. 探索点失败后加入黑名单，记录失败 tick、位置和原因。
4. 黑名单在同一 `gather_tree` step 内生效，避免重复选择同一点或相邻很近的点。
5. 探索点达到后必须立即重新扫描树木，而不是继续沿旧方向漫游。

验证方式：

1. 复现 Y 高差探索点，确认失败后不会继续选择同一高度差点。
2. 日志出现 `explore_rejected`、`explore_blacklisted` 或等价字段。

完成记录：制作链树木探索点连续不可达时会加入黑名单，同一 step 内跳过相邻无效探索点，并记录失败次数。

验证：`./gradlew build` 通过。

### 3.13 树木路径失败快速退出

状态：`[x] 已完成`

目标：当连续多轮扫描都发现树但没有可达树时，AI 要快速给出明确失败或请求玩家协助，而不是持续数分钟停在第一步。

开发内容：

1. 对 `gather_tree` 增加连续失败计数。
2. 区分“没有候选树”和“有候选树但不可达”。
3. 如果连续 N 轮 `candidates > 0 && reachable == 0`，进入失败恢复。
4. 如果探索点连续 M 次失败，进入失败恢复。
5. 失败消息包含建议：移动到树林附近、放入任意原木、清理障碍或把 AI 放到可达地面。

验证方式：

1. 人为站在无法到达树的高低差区域，确认 AI 在限定时间内失败并说明原因。
2. 不允许再出现 3 分钟以上仍只显示 `step 1/21 gather_tree` 而没有诊断结论。

完成记录：制作链树木扫描连续多轮 `candidates > 0 && reachable == 0` 或探索点连续失败时会终止 step，并提示移动到树林平坦地面附近或提供木材。

验证：`./gradlew build` 通过。

### 3.14 直接采集与制作链采集统一

状态：`[~] 开发中`

目标：`/ai say 去砍一棵树` 和 `make_item` 内部的 `gather_tree` 使用同一套树木搜索、评分、站位和失败恢复逻辑。

开发内容：

1. 抽出共享的 `TreeTargetResolver` 或等价工具类。
2. `StepExecutor` 和 `GatherResourceAction` 不再各自维护不同的树木扫描逻辑。
3. 统一候选扫描、站位生成、路径检查、探索点生成和日志字段。
4. 保留直接采集动作的简单接口，但底层复用同一 resolver。
5. 避免后续只修制作链、不修直接砍树，或反过来。

验证方式：

1. `/ai say 去砍一棵树` 和 `/ai say 帮我做木镐` 在同一地点选择一致的可达树目标。
2. 两条路径的失败日志字段一致。

完成记录：直接采集动作已补上可站位解析和站位移动；尚未抽出共享 `TreeTargetResolver`，两条路径仍各自维护扫描状态。

验证：`./gradlew build` 通过。

### 3.15 任意原木与已有材料优先

状态：`[~] 开发中`

目标：从零制作链需要木材时，优先使用 AI 背包、附近箱子或任何可替代原木，不要过度执着于 `minecraft:oak_log` 表面目标。

开发内容：

1. 计划展示仍可用 `minecraft:oak_log` 表示通用原木，但执行层必须明确显示“任意原木”。
2. 背包已有任意原木或任意木板时，优先跳过砍树或减少砍树数量。
3. 附近箱子有任意原木/木板时，优先取用可达箱子。
4. 树木搜索覆盖所有原版原木，并在日志中显示实际选中的木种。
5. 合成木板、木棍、工作台和木制工具时正确接受各种木板。

验证方式：

1. 给 AI 放入云杉原木，制作金锭链路不应再先找橡木。
2. AI 砍到白桦/金合欢等原木后，后续木板和木棍链路继续推进。

完成记录：制作链和直接采集已支持所有原版原木作为通用木材，已有任意原木/木板计数能力已存在；附近箱子优先取用木材仍需后续补齐。

验证：`./gradlew build` 通过。

### 3.16 树木状态机超时与重规划策略

状态：`[x] 已完成`

目标：保留 `gather_tree` 的状态上下文，但不能因为 stateful step 永远跳过重规划。

开发内容：

1. 为 `gather_tree` 增加软超时和硬超时。
2. 软超时触发局部重新扫描和清理旧探索点。
3. 硬超时触发失败恢复或向 DeepSeek 上报“前置木材不可达”。
4. 周期性重规划可以保留树木状态，但必须检查失败计数和最近进展。
5. 如果背包材料、玩家位置或 AI 位置发生明显变化，允许重建树木 step。

验证方式：

1. 日志出现 `skipped periodic rebuild during stateful step` 时，也要能看到状态超时判断。
2. 长时间无进展时，任务会退出或重建，而不是无限保持 `gather_tree`。

完成记录：`gather_tree` 增加硬超时、连续不可达扫描计数和探索失败计数；stateful step 不再无限保持无进展状态。

验证：`./gradlew build` 通过。

### 3.17 树木任务玩家反馈与 AI 面板状态

状态：`[ ] 未开始`

目标：玩家在 AI 面板或 `/ai status` 中能看懂 AI 为什么还在第一步找树。

开发内容：

1. 状态显示当前目标：制作金锭，需要先获取木材。
2. 显示树木扫描摘要：候选树数量、可达树数量、当前探索点、失败次数。
3. 如果有树但不可达，状态显示“发现树但找不到可站立砍树位置”。
4. 如果探索点失败，状态显示最近失败点和原因。
5. 失败时给出玩家可执行建议。

验证方式：

1. `/ai status` 能显示树木阶段和最近失败原因。
2. AI 面板“状态”按钮能显示同样摘要。

### 3.18 树木前置链路回归验收

状态：`[ ] 未开始`

目标：用固定用例验收从空背包开始的第一步木材获取是否稳定。

验收用例：

1. 平原附近有树：空背包制作木镐。
2. 雪地/海滩附近树较远：空背包制作石镐。
3. 有树但高差较大：AI 应失败并说明不可达，不能长时间卡住。
4. 背包已有云杉原木：制作木镐应跳过砍树。
5. 背包已有木板：制作工作台应跳过砍树和木板合成。
6. 附近箱子有原木：AI 先取箱子材料。
7. 直接命令 `/ai say 去砍一棵树`。
8. 制作链命令 `/ai say 帮我挖两块金锭`，至少通过前置木材阶段。
9. 探索点连续失败后能在限定时间内退出。
10. 日志中能明确区分无树、树不可达、探索点不可达和成功砍树。

验证方式：

1. 每个用例记录 `taskId`、最终状态、背包变化和关键日志。
2. 自动化能覆盖纯逻辑部分，实机 `runClient` 覆盖路径和导航部分。
3. 验收结果同步到 README 或回归文档。

## 4. 挖矿能力

### 4.1 矿物资料与目标归一

状态：`[x] 已完成`

目标：所有常见矿物都用统一资料表推演目标方块、产物、工具等级、维度和高度策略。

覆盖资源：

1. 煤。
2. 铜。
3. 铁。
4. 金。
5. 钻石。
6. 红石。
7. 青金石。
8. 绿宝石。
9. 下界石英。
10. 下界金矿。
11. 黑曜石。
12. 远古残骸。

完成记录：`MiningResource`、`AutoMiningTarget` 和 `SurvivalRecipeBook` 已处理矿物目标、工具要求和特殊环境。

验证：`./gradlew test --tests com.aiplayer.recipe.MiningResourceTest` 通过。

### 4.2 圆石采集与阶梯下挖

状态：`[x] 已完成`

目标：AI 找不到可接近石头时，像玩家一样挖横向阶梯，而不是垂直挖脚下或追不可达目标。

能力：

1. 优先挖可直接工作的石头。
2. 找不到可达石头时进入阶梯下挖。
3. 先清理前方站位空间，再挖前方下一格。
4. 跳过水、岩浆、基岩、砂砾、沙子和红沙。
5. 下方站位不可达时改为就地挖阶梯。
6. 长时间没有新增圆石时给出明确失败摘要。
7. 判断可达石头时必须存在相邻可站立工作位，不能把低处石头方块本身当成移动目标。
8. 只有缺少镐时才进入准备工具状态，避免 `准备工具` 和 `前往矿区` 每 tick 抖动。

完成记录：`gather_stone` 已修正可达性、下探顺序、低处目标误判和状态日志抖动，避免卡在 `descent_move_target`。

验证：`./gradlew build` 通过。

### 4.2.1 森林地表圆石下探修复

状态：`[x] 已完成`

目标：AI 在森林、树冠或树叶附近完成木镐后，采集圆石不能只清理几块树叶就提前失败，必须先找到适合起挖的开阔地面，或持续按横挖一格、下挖一格、移动一阶的方式下探到石头层。

触发样本：

1. `/ai say 帮我挖两块金锭`
2. 失败 step：`gather_stone minecraft:cobblestone x3`
3. 失败摘要：起点在森林地表，`访问Y=69..70`、`扫描=0`、`候选=0`、`已挖方块=3`，下探目标包含 `minecraft:oak_leaves`。

修复内容：

1. `gather_stone` 进入下探前，如果当前位置或前方阶梯区域被树叶、原木或树冠包围，先选择附近开阔、脚下有稳定实体方块、头顶空间足够的起挖点。
2. 圆石下探不能在只访问 1-2 个 Y 层时因为 `no_downward_target` 直接终止；应继续换方向、换起挖点或保持阶梯式下探，直到达到明确下探预算或安全约束。
3. 阶梯方向选择失败时，日志必须记录被拒绝方向、站位、水平目标、垂直目标和拒绝原因。
4. 清理树叶、草、泥土等覆盖层只能算“下探进展”，不能算采集圆石成功。
5. 普通生存掉落模拟需要修正树叶：没有剪刀或精准采集时，破坏树叶不应直接获得 `minecraft:*_leaves`。
6. 回归文档记录本次失败样本、修复点和复测重点。

验证方式：

1. `./gradlew build`
2. agent2 审查 `gather_stone` 在森林地表、普通地表和已有露天石头三种场景下的逻辑路径。
3. 实机复测时执行 `/ai say 帮我挖两块金锭`，确认圆石 step 不再只访问 `Y=69..70` 后提前失败。

完成记录：`gather_stone` 已新增开阔起挖点选择、起挖点拒绝与重选、严格阶梯移动到达判断、失败方向完整摘要日志；普通破坏树叶不再掉落树叶方块。

验证：`./gradlew build` 通过；agent2 两轮复查通过，确认 4.2.1 可以标记完成。后续仍需通过 `runClient` 实机复测验证导航稳定性。

### 4.3 矿井入口和路线规划

状态：`[x] 已完成`

目标：深层矿物不能在地表随机扫描，必须下探到合理高度。

能力：

1. 生成 `MiningRoutePlan`。
2. 记录入口、目标 Y、高度策略、主方向、分支长度和路线提示。
3. 高于推荐高度时先阶梯下探。
4. 到达目标高度附近后再进入分支矿道。
5. 同一任务可复用矿井入口和 waypoint。

完成记录：`MiningRoutePlan` 和共享矿井状态已接入 `StepExecutor`。

验证：`./gradlew build` 通过。

### 4.4 分支矿道与层级搜索

状态：`[x] 已完成`

目标：深层矿物使用可持续分支矿道搜索，而不是无目标乱挖。

能力：

1. 到达目标高度后开 2 格高水平分支矿道。
2. 每段达到上限后记录原因并结束任务。
3. 分支受阻时记录 debug 原因并结束任务。
4. 分支进度写入 `MiningRun`。
5. 分支失败会给出路线摘要。

完成记录：金、钻石、红石等深层矿物已使用分支矿道策略；遇到上限、受阻或破坏失败时不再静默换方向，会结束任务并回到玩家身边。

验证：`./gradlew build` 通过。

### 4.5 洞穴优先与矿脉追踪

状态：`[x] 已完成`

目标：附近有安全洞穴时优先探索洞穴；发现矿脉后尽量连续采集。

能力：

1. `WorldSnapshot` 扫描附近洞穴入口。
2. 记录洞穴可达性、连通空气、暴露石壁和可见矿物数量。
3. 安全洞穴优先进入扫描。
4. 挖到矿后追踪相邻同类矿石。
5. 危险洞穴会被跳过或请求玩家协助。

完成记录：洞穴入口扫描和自然矿脉追踪已接入探矿流程。

验证：`./gradlew build` 通过。

### 4.6 危险处理与生存安全

状态：`[x] 已完成`

目标：AI 挖矿必须处理岩浆、坠落、低血量、背包和工具耐久；敌对生物攻击对 AI 不造成伤害。

能力：

1. 挖掘前检查目标周围岩浆。
2. 避免垂直挖脚下。
3. 避免下方空气导致坠落。
4. 忽略敌对生物数量，敌对生物攻击不造成伤害。
5. 血量过低时停止挖矿。
6. 背包满或工具耐久不足时进入等待或恢复。

完成记录：环境危险和路径卡住会写入 `MiningRun`，失败摘要中包含具体原因；任务会结束并由空闲跟随回到玩家身边。

验证：`./gradlew build` 通过。

### 4.7 挖矿进度评分与动态换策略

状态：`[x] 已完成`

目标：AI 不等到统一超时才失败，而是持续评估当前路线是否有价值。

评分因素：

1. 已挖方块数。
2. 扫描次数。
3. 可达候选数。
4. 洞穴发现。
5. 拒绝目标数。
6. 破坏失败数。
7. 危险次数。

完成记录：`MiningRun` 会记录 `mining progress decision`，并在无收益时换分支、换层或重新规划。

验证：`./gradlew test --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.8 DeepSeek 挖矿策略心跳

状态：`[x] 已完成`

目标：长挖矿任务每隔一段时间向 DeepSeek 上报状态，让 DeepSeek 给策略建议。

能力：

1. `gather_stone`、铁矿、金矿、钻石等长 step 每 600 tick 最多上报一次。
2. 上报目标、当前 step、背包、箱子、位置、附近方块、洞穴、近期失败和近期事件。
3. DeepSeek 只能返回继续、阶梯下挖、重建计划、重新观察或请求玩家协助。
4. 本地代码仲裁建议后才执行。
5. 无 API key 或请求失败时，本地执行继续推进。

完成记录：`MiningStrategyAdvisor` 已接入异步 DeepSeek 策略心跳。

验证：`./gradlew test --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.9 自动挖矿命令和玩家状态反馈

状态：`[x] 已完成`

目标：玩家不用翻日志也能知道 AI 正在做什么。

命令：

```mcfunction
/ai mining start iron 3
/ai mining status
/ai mining stop
/ai mining return
/ai status
/ai location
```

能力：

1. 启动自动挖矿目标。
2. 查看 taskId、目标、当前动作、位置、Y 高度、主手和背包摘要。
3. 停止挖矿或回到玩家身边。
4. AI 面板提供状态和定位按钮。
5. 失败消息给出可操作建议。

完成记录：命令和面板已同步 README。

验证：`./gradlew build` 通过。

### 4.10 挖矿回归基准

状态：`[x] 已完成`

目标：建立固定挖矿测试矩阵，避免每次只修一个单独样例。

回归文档：

- `docs/mining-regression.md`

覆盖目标：

1. 煤。
2. 铁。
3. 铜。
4. 金。
5. 钻石。
6. 红石。
7. 青金石。
8. 绿宝石。
9. 黑曜石。
10. 远古残骸。

记录字段：

1. 命令。
2. taskId。
3. 起始材料。
4. 维度、起始 Y 和地形。
5. 是否有洞穴。
6. 耗时。
7. 最终结果。
8. 关键日志。
9. 下一步建议。

完成记录：挖矿实机回归矩阵和圆石下探卡住样例已记录。

验证：`./gradlew build` 通过。

### 4.11 服务端探矿目标模型

状态：`[x] 已完成`

目标：把“想要获得某种材料”统一转换为服务端可扫描、可验证、可执行的矿物目标。

开发内容：

1. 建立 `OreProspectTarget`，统一记录目标 ID、中文名、矿石方块、方块标签、掉落物、维度、推荐高度和最低工具等级。
2. 覆盖煤、铁、铜、金、钻石、红石、青金石、绿宝石、黑曜石、远古残骸等生存挖矿目标。
3. 区分“矿石方块”和“最终材料”，例如金锭需要金矿或深层金矿加熔炼，不应直接寻找金锭方块。
4. 把 `MiningResource`、基础资源来源表和配方递归结果对齐到同一个目标模型。
5. 对不可挖、不可合成、维度不匹配或工具等级不足的目标给出明确失败原因。

完成记录：新增 `OreProspectTarget`，从矿物资料表生成探矿目标，保留目标物品、矿石方块、维度、推荐高度和最低工具要求。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.12 服务端探矿扫描器

状态：`[x] 已完成`

目标：把探矿扫描改造成服务端能力，让 AI 能在任务执行中获得最近矿点坐标。

开发内容：

1. 新增 `OreProspector`，在 server thread 内扫描 AI 周围已加载区块。
2. 支持按方块标签和具体方块匹配目标矿物。
3. 扫描范围使用配置值和任务策略控制，默认不超过 100 格。
4. 按玩家当前位置、AI 位置、Y 高度和目标矿物计算最近候选。
5. 返回 `OreProspectResult`，包含目标类型、方块坐标、水平距离、垂直差、所在区块、匹配来源和扫描统计。
6. 未找到矿物时返回结构化原因，而不是只写“找不到”。

完成记录：新增 `OreProspector` 和 `OreProspectResult`，在 server thread 的挖矿 step 中扫描附近已加载区块，返回真实矿点坐标、候选数量、扫描预算和拒绝原因。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.13 探矿性能预算与缓存

状态：`[x] 已完成`

目标：避免探矿扫描造成卡顿，同时让长任务能持续获得新结果。

开发内容：

1. 每 tick 限制扫描区块数、section 数和方块数。
2. 支持分批扫描，未完成时继续沿用上一次扫描游标。
3. 缓存最近一次有效结果，记录 TTL、任务 ID、目标类型和 AI 所在区块。
4. AI 移动距离过大、目标变化、矿点被挖掉或超时后刷新缓存。
5. 分类日志记录扫描耗时、候选数量、缓存命中、缓存失效和扫描中断原因。

完成记录：探矿扫描新增半径上限、方块扫描预算、扫描间隔、最近结果记录和阶段路线复用，避免每 tick 全量扫描。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过；交互式 TPS 仍需后续实机观察。

### 4.14 探矿候选筛选与终止原因

状态：`[x] 已完成`

目标：探矿结果不能只看最近，还要判断是否值得挖、能否安全接近。

开发内容：

1. 为候选矿点计算评分，包含距离、Y 差、目标价值、工具要求、危险方块和路线复杂度。
2. 初筛岩浆、基岩、虚空、下方空气和不可破坏方块；敌对生物不参与挖矿危险判定。
3. 对路径卡住、环境危险、挖掘失败、目标被挖掉或目标位于当前层上方的情况写出 debug 原因。
4. 终止原因记录坐标、目标类型、失败原因和当前背包。
5. 当前候选无法继续挖掘时结束整个任务，并让 AI 回到玩家身边。

完成记录：探矿目标会过滤错误维度和未加载区块；执行中遇到不可挖原因时不再记录坐标后反复换点，而是记录 debug 原因、终止任务并回到玩家身边。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.15 工具与材料闭环准备

状态：`[x] 已完成`

目标：AI 前往矿点前先确认自己具备挖取条件，缺什么就递归获取什么。

开发内容：

1. 根据目标矿物查询最低工具等级、推荐工具和消耗链。
2. 背包没有合适工具时，调用 `RecipeResolver` 生成制作链。
3. 制作链缺少木头、圆石、铁、煤等材料时，继续拆成可执行的采集、挖掘或熔炼子任务。
4. 工具耐久不足时优先制作替代工具或请求玩家补给。
5. 每次子任务完成后重新观察背包和附近箱子，避免使用过期材料状态。
6. 工具准备完成后再恢复原始挖矿目标。

完成记录：探矿前沿用 `RecipeResolver`、工具等级检查、镐耐久检查和背包空间检查；缺工具或材料时继续走 `make_item` 递归链。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过；空背包金锭链路需后续实机复测。

### 4.16 阶段式挖矿路线生成

状态：`[x] 已完成`

目标：把探矿坐标转换为普通生存玩家可执行的分阶段路线。

开发内容：

1. 新增 `StageMiningPlan`，按准备、探矿、接近、下探、横挖、暴露矿物、挖取、收集、校验、复探分段。
2. 目标在同层附近时优先使用可达路径接近。
3. 目标低于 AI 时使用阶梯式向下挖，保持可站立空间和返回路径。
4. 目标高于 AI 时使用安全上行台阶或绕路，不垂直向上硬挖。
5. 接近矿点时根据探矿方向逐段调整矿道方向。
6. 每段路线都写入可读状态，用于 `/ai status` 和 AI 面板展示。

完成记录：新增 `StageMiningPlan`，把探矿坐标转换为接近、下探、横挖、暴露和采集阶段，并写入 `mining.log`。当前路线强制先按阶梯式下挖到探矿目标所在高度，再在同层平行开路接近矿物；如果 AI 低于目标超过 1 格，会记录原因并结束任务，避免向上硬挖。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.17 探矿引导执行器

状态：`[x] 已完成`

目标：让 AI 按阶段路线真实移动、挖掘和调整方向，而不是站在原地等待。

开发内容：

1. 新增 `ProspectMiningAction` 或等价执行器，逐 tick 执行 `StageMiningPlan`。
2. 每次挖掘前先转头看向目标方块，并触发右手挥动。
3. 按普通玩家距离限制破坏方块，够不到就继续移动。
4. 挖通道时先清理头部和脚部空间，再推进站位。
5. 阶段超时、移动卡住或目标方块变化时触发局部重算。
6. 执行器必须能被 `/ai stop`、召回、低血量和危险策略打断。

完成记录：`StepExecutor` 已接入探矿引导执行，按阶段移动、下挖、横挖、看向目标方块并挥动主手；环境危险、卡住和召回仍可打断。阶梯下挖严格按“横向挖前方头部空间 -> 向下挖前方低一格脚下空间 -> 移动到下一阶”循环执行；同一探矿路线每挖 30 个方块、移动 30 格或完成 30 次挖掘/移动动作会重新调用探矿模块，使用最新位置修正后续路线。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过；动作观感需后续 `runClient` 观察。

### 4.18 矿脉采集与数量闭环

状态：`[x] 已完成`

目标：AI 找到矿后要按需求数量持续采集，而不是挖一块就结束。

开发内容：

1. 暴露目标矿物后扫描相邻同类矿石，生成矿脉队列。
2. 按安全顺序挖取矿脉，避免先挖掉脚下支撑或打开岩浆面。
3. 每挖一块都重新统计背包获得物。
4. 掉落物未进入背包时移动到掉落物附近拾取。
5. 数量不足时按重探规则重新探矿；如果重探发现不可挖原因则终止任务。
6. 数量满足时结束任务，并向玩家反馈获得数量、耗时和剩余工具耐久。

完成记录：探矿目标挖开后复用相邻矿脉追踪，采集结果按真实背包数量校验；数量不足会按重探规则继续，遇到不可挖原因会终止任务。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过；多目标数量闭环需后续实机复测。

### 4.19 DeepSeek 探矿复盘协同

状态：`[x] 已完成`

目标：DeepSeek 参与策略判断，但不编造配方、矿点或物品事实。

开发内容：

1. 上报目标、当前阶段、探矿结果、背包、箱子、工具、环境危险、终止原因和最近日志摘要。
2. DeepSeek 只输出高层建议，例如继续当前矿点、重新探矿、补工具、回到玩家身边或请求协助。
3. 本地代码验证 DeepSeek 建议是否符合任务白名单和生存规则。
4. 每 30 秒或阶段失败后触发一次复盘，普通推进不频繁请求接口。
5. DeepSeek 不可用时，本地探矿路线仍能继续执行。

完成记录：`MiningStrategyAdvisor` 上下文新增探矿规则说明，明确矿点坐标、配方、工具和材料事实由本地代码负责，DeepSeek 只建议继续、重扫、重建计划或请求协助。

验证：`./gradlew test --tests com.aiplayer.mining.OreProspectTargetTest --tests com.aiplayer.recipe.MiningResourceTest --tests com.aiplayer.agent.MiningStrategyAdvisorTest` 通过。

### 4.20 探矿挖矿回归验收

状态：`[~] 开发中`

目标：用固定用例验收探矿引导式挖矿是否真正闭环。

验收用例：

1. 空背包制作石镐并挖煤。
2. 空背包制作石镐并挖铁矿。
3. 空背包制作铁镐并挖金矿，最终获得金锭。
4. 空背包制作铁镐并挖钻石。
5. 空背包制作铁镐并挖红石和青金石。
6. 山地环境寻找绿宝石。
7. 有水桶和钻石镐时采集黑曜石。
8. 下界环境寻找远古残骸。
9. 候选矿点存在环境危险时记录原因并结束任务。
10. 候选矿点被挖掉后记录原因并结束任务。

完成记录：`docs/mining-regression.md` 已补充探矿引导专项检查、关键日志字段和复测命令；自动化测试已通过，交互式实机记录尚未补齐。

验证方式：后续运行 `runClient` 后，把每个用例的 `taskId`、探矿结果、路线阶段、最终背包和关键日志补入 `docs/mining-regression.md`。

## 5. 文档、验证与维护规则

### 5.1 README 同步

状态：`[x] 已完成`

目标：用户可见行为变化必须同步 README。

已同步内容：

1. DeepSeek 配置。
2. `/ai` 命令。
3. AI 面板。
4. AI 背包转移。
5. 自动挖矿命令。
6. 技能记忆和本地 Critic。
7. 分类日志。
8. 生存制作、打水、烧炼和挖矿说明。

验证：`./gradlew build` 通过。

### 5.2 阶段文档整理

状态：`[x] 已完成`

目标：阶段路线按编号维护，避免无序插入。

维护规则：

1. 大类使用一级编号，例如 `1. 基础架构与生存边界`。
2. 小类使用二级编号，例如 `1.2 Observe 观察层`。
3. 新阶段必须追加到对应大类末尾。
4. 不再使用无序的字母分段插入方式。
5. 每个阶段必须包含状态、目标、能力或开发内容、完成记录和验证方式。

完成记录：本文档已按 1 到 5 的顺序重新编排。

验证：Markdown-only 调整，本阶段不需要运行构建。

## 6. 长期鲁棒交互框架

### 6.1 统一交互目标模型

状态：`[x] 已完成`

目标：所有需要接触世界的动作都先生成统一交互目标，而不是各动作各自维护目标方块、站位和距离判断。

开发内容：

1. 新增 `InteractionTarget`，统一描述目标方块、工作站位、触达距离、工具类型、动作类型和选择原因。
2. 新增交互动作类型枚举，覆盖破坏方块、放置方块、使用方块、打开容器等基础动作。
3. 砍树扫描阶段先输出 `InteractionTarget`，保留原有树木搜索能力，但不再只传递裸 `targetPos` 和 `standPos`。
4. 日志输出交互目标摘要，包含目标、站位、距离、工具和选择原因。
5. 暂不迁移全部动作，先让模型稳定服务 `gather_tree`。

验证方式：`./gradlew build`；agent2 复查模型是否能支撑后续 `MoveThenInteract`。

完成记录：新增 `InteractionTarget` 和 `InteractionActionType`；砍树扫描会生成并保存交互目标，选中树木时输出目标、站位、触达距离、工具、动作类型和选择原因。

验证：`./gradlew build` 通过；agent2 复查通过，确认 6.1 可以标记完成。当前砍树站位误判问题归入 6.2 处理。

### 6.2 统一移动到工作站位

状态：`[x] 已完成`

目标：有工作站位的动作必须真正到达工作站位，不能用模糊距离把相邻格误判为到达。

开发内容：

1. 新增 `MoveThenInteract` 的移动阶段辅助逻辑。
2. `InteractionTarget` 存在 `standPos` 时，移动完成条件必须是 AI 当前方块坐标等于工作站位。
3. 如果站位不可达或长期没有进展，返回明确 `stand_unreachable`。
4. 砍树动作优先接入该移动逻辑，解决相邻格误判导致的长时间无进展。
5. 保留没有工作站位时的直接触达逻辑。

验证方式：`./gradlew build`；agent2 复查砍树不会再因为 `1.5D` 范围误判站位完成。

完成记录：砍树动作已接入 `moveToInteractionTarget`；有 `standPos` 时必须实际站到该方块才允许继续交互，站位失效或移动超时会记录 `stand_no_longer_valid` / `stand_unreachable` 并拒绝当前交互目标。

验证：`./gradlew build` 通过；agent2 复查通过，确认 `task-917b613a` 中相邻格误判站位的问题已由 6.2 覆盖。

### 6.3 交互前最终校验

状态：`[x] 已完成`

目标：破坏、放置或使用前统一校验目标仍有效、当前位置能触达、工具满足且环境安全。

开发内容：

1. 校验目标方块是否仍存在且类型匹配。
2. 校验 AI 当前站位是否仍是目标的有效工作站位。
3. 校验距离是否在 `reachRange` 内。
4. 校验工具类型和危险方块。
5. 失败时输出结构化原因，而不是静默重新扫描。

验证方式：`./gradlew build`；agent2 复查失败原因是否足够定位。

完成记录：砍树交互前已校验目标区块、目标方块类型、实际工作站位、触达距离和工具规则；失败时记录 `target_chunk_unloaded`、`target_changed`、`stand_not_reached`、`out_of_reach` 或 `tool_mismatch` 等结构化原因。

验证：`./gradlew build` 通过；agent2 复查通过，确认 6.3 可以标记完成。

### 6.4 结构化失败黑名单

状态：`[x] 已完成`

目标：失败黑名单记录目标、站位、动作类型和原因，避免同一失败组合被重复选择。

开发内容：

1. 新增 `InteractionFailureKey`。
2. 黑名单字段包含 `targetBlock`、`standPos`、`actionType`、`reason` 和过期 tick。
3. 砍树扫描跳过未过期的失败组合。
4. 失败原因进入日志和 step event。
5. 黑名单过期后允许重新尝试，避免永久误伤可恢复目标。

验证方式：`./gradlew build`；agent2 复查重复失败目标不会立即被重选。

完成记录：新增 `InteractionFailureKey` 和 `InteractionFailureMemory`，交互失败按 `targetBlock + standPos + actionType + reason` 记录并带过期 tick；砍树扫描会跳过未过期的失败交互组合，交互失败不再污染旧的方块级黑名单。

验证：`./gradlew build` 通过；agent2 第二轮复查通过，确认 6.4 可以标记完成。

### 6.5 砍树完整迁移

状态：`[x] 已完成`

目标：砍树从目标选择、移动、交互、校验到失败恢复都走统一交互框架。

开发内容：

1. 优先选择可工作站位能触达的最低原木。
2. 同一棵树底部砍掉后重新识别剩余树干。
3. 站位失效时拉黑目标和站位组合，再换站位或换树。
4. 长时间无进展时报告最后一次交互目标、当前位置、距离和失败原因。
5. 砍树成功后用真实背包 delta 判定完成。

验证方式：`./gradlew build`；实机复测 `/ai say 给我两金锭` 的前三个木材 step。

完成记录：`gather_tree` 已完整走统一交互框架；直接 `/ai say 去砍一棵树` 的 `gather resource=tree` 也会路由到 `GatherTreeAction`，再包装 `StepExecutor` 的 `gather_tree minecraft:oak_log` step。砍树会优先选择最低可达原木，破坏一块后重新扫描剩余树干；站位失效、不可达、目标变化、超距和工具变化都会记录交互失败组合；硬超时会输出扫描摘要、最后交互目标、最后交互失败、当前位置、距离和失败原因；完成判定使用真实背包 delta。

验证：`./gradlew build` 通过；agent2 第三轮复查通过，确认直接砍树和制作链木材 step 已共用统一交互框架。

### 6.6 挖矿、箱子和工作站迁移

状态：`[ ] 进行中`

目标：把圆石、矿物、工作台、熔炉和箱子交互逐步迁移到同一套模型，彻底减少“修完一个动作另一个动作复发”的问题。

#### 6.6.1 圆石采集迁移

状态：`[x] 已完成`

目标：`gather_stone` 使用统一交互目标，而不是只保存裸 `targetPos` 并靠距离移动。

开发内容：

1. 圆石目标选择输出 `InteractionTarget`，包含石头方块、工作站位、触达距离、工具类型和原因。
2. 直接可触达的石头使用无站位直接交互；不可直接触达时必须移动到可站立工作位。
3. 挖掘前校验目标仍是石头、旁边有空气、实际站位正确、距离可触达、工具规则未变化。
4. `stand_no_longer_valid`、`stand_unreachable`、`target_changed`、`out_of_reach`、`tool_mismatch` 等失败进入结构化交互失败记忆。
5. 圆石长时间无进展时输出最后交互目标、最后交互失败、当前位置、距离和失败原因。

验证方式：`./gradlew build`；agent2 复查圆石 step 不再绕过统一交互框架。

完成记录：圆石采集已生成 `stone_direct` / `stone_reachable_stand` 交互目标，移动、校验、失败记忆和超时诊断均接入统一交互框架。

验证：`./gradlew build` 通过；agent2 复查通过，确认圆石 step 已接入统一交互框架。

#### 6.6.2 矿物采集迁移

状态：`[x] 已完成`

目标：可见矿物、探矿目标和阶段式挖矿最终破坏矿石时使用统一交互目标。

开发内容：

1. 可见矿物目标输出 `InteractionTarget`。
2. 探矿目标进入最终采集前转换为 `InteractionTarget`。
3. 失败原因进入结构化失败记忆和 mining 日志。
4. 工具等级、危险方块和目标变化在最终交互前统一校验。
5. 长时间无进展时报告最后交互目标和失败组合。

验证方式：`./gradlew build`；agent2 复查可见矿物、探矿最终采集、阶段式挖矿最终破坏矿石、相邻矿脉追踪都不绕过统一交互框架。

完成记录：可见矿物扫描会返回 `InteractionTarget`；探矿最终采集和阶段式路线挖到矿石时会进入 `mineProspectOreTarget`，再统一移动、校验和破坏；隐藏矿石必须先暴露空气面才会进入最终采集；相邻矿脉追踪保存 `vein_follow` / `prospect_vein_follow` 交互目标；交互拒绝会写入 `InteractionFailureMemory`、`MiningRun` 和 `mining` 分类日志。

验证：`./gradlew build` 通过；agent2 第四轮复查通过，确认 6.6.2 可以标记完成。

#### 6.6.3 工作台和熔炉使用迁移

状态：`[x] 已完成`

目标：工作台、熔炉等工作站使用必须先移动到可触达站位，再执行使用和合成。

开发内容：

1. 查找已有工作站时输出 `USE_BLOCK` 交互目标。
2. 放置新工作站时输出 `PLACE_BLOCK` 交互目标。
3. 合成或熔炼前校验站位、距离、方块类型和背包材料。
4. 失败时区分工作站丢失、站位不可达、材料变化和距离超限。
5. 工作站使用日志写入最后交互目标。

完成记录：`craft_station` 不再直接假设工作站可用；已有工作台、熔炉和高炉会先生成 `USE_BLOCK` 交互目标，必要时先生成 `PLACE_BLOCK` 放置目标。合成前会校验工作站方块类型、站位、触达距离和材料变化；缺少 `station` 的 `craft_station` 计划会被 `PlanValidator` 拒绝，避免绕过工作站交互。

验证：`./gradlew build` 通过；agent2 复查通过，确认工作站查找、放置、使用和计划校验均接入统一交互框架。

#### 6.6.4 箱子取放迁移

状态：`[x] 已完成`

目标：附近箱子检查、取出和放入都走 `OPEN_CONTAINER` 交互目标。

开发内容：

1. 扫描附近箱子时生成可站立打开位置。
2. 打开前校验箱子仍存在、站位正确、距离可触达。
3. 取放物品记录真实数量 delta。
4. 失败时记录箱子位置、站位、操作类型和原因。
5. 玩家和 AI 背包面板的转移逻辑保持不变。

完成记录：`withdraw_chest` 和 `deposit_chest` 会先生成 `OPEN_CONTAINER` 交互目标，移动到可打开距离后校验容器仍存在、站位有效和真实可转移数量。取出和放入都按实际移动的物品 delta 判定进度，失败组合会进入结构化交互失败记忆。

验证：`./gradlew build` 通过；agent2 复查通过，确认箱子取放没有绕过统一交互 contract。

#### 6.6.5 方块放置迁移

状态：`[x] 已完成`

目标：建筑和工作站放置统一走 `PLACE_BLOCK` 交互目标。

开发内容：

1. 放置前生成目标位置和工作站位。
2. 放置前校验背包材料、支撑方块、替换方块、站位和距离。
3. 失败时记录结构化失败组合。
4. 成功后用真实背包和世界方块变化确认。
5. 建造动作复用同一套交互日志。

完成记录：直接放置动作和生存建造动作都会生成 `PLACE_BLOCK` 交互目标，先移动到可触达距离，再校验目标可替换、背包材料、相邻支撑、交互距离和最终世界方块变化。不可替换方块、材料缺失、距离超限、无支撑、移动卡住和放置失败都会进入结构化交互失败记忆，不再静默跳过导致缺块却报告建造完成。

验证：`./gradlew build` 通过；agent2 第一轮指出建造遇到不可替换非目标方块时仍会跳过，已修复；agent2 第二轮复查通过，确认直接放置和建造放置满足统一 `PLACE_BLOCK` contract。

## 7. 探矿路线鲁棒化

状态：`[ ] 未开始`

背景：最近一次 `task-c8fae94e` 在“给我挖两块金锭”任务中失败。任务并未进入金矿阶段，而是在前置 `gather minecraft:raw_iron x3` 阶段终止。日志显示探矿找到了远处隐藏铁矿 `-1, 58, -515`，AI 在接近过程中下探到 `63, 56, -496`，随后因为“探矿目标位于当前层上方”触发 terminal failure。核心问题是探矿结果分级、路线目标选择、阶段式路线失效恢复和即时重探策略还不够鲁棒。

目标：把“扫描到矿物坐标”升级为“选择可执行采矿路线”。AI 不应因为一个远处隐藏矿点或高度偏差直接终止整条制作链，而应能重新探矿、换目标、调整路线、继续当前层推进或给出明确可操作失败原因。

### 7.1 探矿结果分级模型

状态：`[x] 已完成`

目标：把探矿结果从单一 `orePos` 拆成不同执行等级，避免隐藏矿点直接变成硬目标。

开发内容：

1. 新增探矿目标等级，例如 `DIRECT_MINEABLE`、`APPROACHABLE_EXPOSED`、`EMBEDDED_HINT`、`REJECTED`。
2. `DIRECT_MINEABLE` 表示矿物已有空气邻面且 AI 当前可触达。
3. `APPROACHABLE_EXPOSED` 表示矿物已有空气邻面，但需要移动到工作站位。
4. `EMBEDDED_HINT` 表示矿物真实存在但完全埋在实体方块内部，只能作为方向提示，不能直接进入最终挖取阶段。
5. `REJECTED` 记录岩浆、基岩、未加载、工具不足、维度错误、已挖掉等不可执行原因。

验收标准：

1. 探矿日志能显示每类候选数量。
2. `EMBEDDED_HINT` 不会直接创建 `MINE` 阶段。
3. 原有可见矿物采集不退化。

验证方式：`./gradlew build`；agent2 复查探矿结果分级不会让隐藏矿直接绕过路线生成。

完成记录：新增 `OreProspectClassification`，探矿结果区分 `DIRECT_MINEABLE`、`APPROACHABLE_EXPOSED`、`EMBEDDED_HINT`、`REJECTED` 和 `NOT_FOUND`。`OreProspectResult` 日志输出选中目标分类和分类计数；`OreProspector` 会先选择可执行候选，再考虑隐藏提示；暴露但无可达站位的矿点会记录为 `REJECTED / exposed_unreachable`，不会被误当作隐藏提示；`MiningRun` 只把可执行探矿结果计入 reachable。

验证：`./gradlew build` 通过；agent2 第一轮指出“暴露但不可达矿点被误归为 EMBEDDED_HINT”，已修复；agent2 第二轮复查通过，确认 7.1 可以标记完成。

### 7.2 探矿目标评分与近距离优先

状态：`[x] 已完成`

目标：避免 AI 锁定远处隐藏矿点，尤其是铁矿、煤矿这类前置基础资源。

开发内容：

1. 建立 `OreTargetScore`，评分维度包含水平距离、垂直差、是否暴露、是否可触达、是否同层、工具匹配、危险邻近和路线预算。
2. 基础矿物优先选择近距离目标，例如煤、铁、铜优先当前 32 格内可执行候选。
3. 远距离隐藏矿只能作为方向提示，必须低于近距离可执行目标。
4. 同层或低一层目标优先，高于当前层的目标降权。
5. 日志输出被选目标分数和被拒目标主要原因。

验收标准：

1. `task-c8fae94e` 中类似 `-1, 58, -515` 的远距离隐藏铁矿不会优先于附近提示矿或近距离路线。
2. 没有可执行目标时，日志明确说明是“仅有隐藏提示”还是“完全没有矿物”。

验证方式：`./gradlew build`；agent2 复查评分规则；实机复测铁矿前置链。

完成记录：新增 `OreTargetScore`，探矿候选选择从“分类 + 距离”升级为路线质量评分。评分包含分类、水平距离、垂直差、是否基础资源、是否近场、是否同层/低层；基础铁矿、煤、铜、圆石和基础方块有近场加权；隐藏矿 `EMBEDDED_HINT` 有额外惩罚；高于当前层的目标会被降权；`OreProspectResult` 日志输出 `selectedScore`，可追踪为什么选中该矿点。

验证：`./gradlew build` 通过；agent2 复查通过，确认 7.2 可以标记完成。工具匹配、危险邻近和路线预算评分留给后续 phase 继续扩展。

### 7.3 暴露面目标生成

状态：`[x] 已完成`

目标：阶段式路线不再直接朝矿物本体硬挖，而是先计算矿物相邻的可站立或可挖通道点。

开发内容：

1. 为每个矿点生成 `ExposureTarget`，包含矿物坐标、目标邻面、预计站位和需要挖开的通道方块。
2. 已有空气邻面时，直接使用邻面作为最终工作目标。
3. 完全隐藏矿只生成“暴露面候选”，不能直接执行 `break ore`。
4. 暴露路线必须保证最终能从邻面触达矿物，而不是站在矿物方块内部。
5. 如果所有邻面都被岩浆、基岩、虚空或不可挖方块阻挡，则拒绝该矿点。

验收标准：

1. `StageMiningPlan` 的最终目标从 `orePos` 扩展为 `orePos + exposurePos`。
2. 只有矿物暴露后才进入 `MINE`。
3. 失败日志能说明哪个邻面不可用。

验证方式：`./gradlew build`；agent2 复查路线目标不会把矿物本体当作行走点。

完成记录：新增 `ExposureTarget`，`StageMiningPlan` 保存 `orePos + exposureTarget`，日志和状态输出暴露点与 `routeTarget`。隐藏矿会先选择相邻暴露点作为路线目标，已暴露矿仍可进入 `MINE` / `APPROACH`。无有效暴露面会拒绝该矿点并输出 `no_valid_exposure_target`。执行层只允许 `routeTarget` 在当前隧道前沿 `nextStand` 或 `nextStand.above()` 时被破坏，避免隔墙远程破坏暴露邻面；暴露点可用性与 `breakableTunnelBlock` 的砂砾、沙子、红沙过滤保持一致。

验证：`./gradlew build` 通过；agent2 前两轮指出远程破坏暴露点和暴露点过滤不一致问题，均已修复；agent2 第三轮复查通过，确认 7.3 可以标记完成。

### 7.4 高度偏差恢复策略

状态：`[x] 已完成`

目标：把 `prospect_target_above_current_layer` 从终止任务改为路线失效恢复。

开发内容：

1. 当目标位于当前层上方超过允许阈值时，不直接 terminal failure。
2. 优先触发重新探矿，尝试选择同层或下方目标。
3. 如果旧目标仍是最佳目标，则切换为“当前层水平推进到暴露面附近”，而不是向上硬挖。
4. 只有连续多次重探仍只剩上方不可达目标时，才请求玩家协助或结束当前 step。
5. 失败复盘记录“目标高于当前层”的次数、旧目标、重探结果和新决策。

验收标准：

1. AI 低于目标 2 格时不会立刻清空整条任务。
2. 日志出现 `route_invalid_reprospect` 或等价状态，而不是直接 `terminal_failure`。
3. 若最终失败，消息说明已经重探多少次以及为什么没有替代目标。

验证方式：`./gradlew build`；agent2 复查终止条件；实机复测 `gather raw_iron`。

完成记录：`prospect_target_above_current_layer` 和 `tunnel_target_above_current_layer` 不再直接终止任务，而是记录上方目标恢复态、拒绝当前矿点、清空旧 stage plan 并触发重新探矿。恢复态会保留上次矿点、路线目标、原因、当前位置和重探次数；扫描暂时找不到替代目标时不会落入普通 `prospect_not_found`，而是按上限继续等待下一轮探矿，达到上限后再输出带完整上下文的失败消息。普通 `prospect_timeout` 和 `prospect_no_progress` 也接入恢复态，避免绕过恢复上限提前终止。

验证：`./gradlew build` 通过；agent2 第一轮指出恢复态下 `prospect_not_found` 仍可能提前终止，已修复；agent2 第二轮指出普通超时和无进展仍可能绕过恢复上限，已修复；agent2 第三轮复查通过，确认 7.4 可以标记完成。

### 7.5 路线预算与阶段失效重探

状态：`[ ] 未开始`

目标：每挖 30 块、移动 30 格或行动 30 次后强制重探，且路线质量恶化时即时重探。

开发内容：

1. 统一统计 `blocksSinceProspect`、`distanceSinceProspect`、`actionsSinceProspect`。
2. 达到 30 阈值后强制清空旧 stage plan 并重新探矿。
3. 如果当前路线水平距离增加、垂直差变差、目标变成上方、路径卡住或候选被拒，立即重探，不等待 30 秒 DeepSeek 心跳。
4. 重探时保留最近失败目标和拒绝原因，避免马上选回同一个坏目标。
5. 重探日志包含旧计划、旧分数、新候选、新分数和是否切换目标。

验收标准：

1. 长路线不会持续追逐同一个远处矿点。
2. `mining.log` 能看出每次重探是由距离、挖掘次数、动作次数还是路线失效触发。

验证方式：`./gradlew build`；agent2 复查重探触发条件；实机复测远距离矿点。

### 7.6 近场探索优先策略

状态：`[ ] 未开始`

目标：基础资源阶段优先把当前位置附近挖透，而不是长距离追一个扫描到的矿点。

开发内容：

1. 对铁、煤、铜这类前置资源新增近场探索窗口。
2. 如果当前位置附近存在大量石头且矿物不可见，优先执行短分支、阶梯下探或横向探槽。
3. 近场探索每轮只推进有限步数，之后重探。
4. 若附近出现可见矿物或暴露邻面，立即切换到采集。
5. 若近场探索多轮无发现，再扩大半径或请求玩家移动到矿洞/低处。

验收标准：

1. AI 不会在刚做出石镐后马上锁定几十格外的隐藏铁矿。
2. 前置铁矿失败时，日志能显示已经完成多少轮近场探索。

验证方式：`./gradlew build`；agent2 复查近场优先不会无限挖空。

### 7.7 探矿黑名单与过期机制

状态：`[ ] 未开始`

目标：对失败矿点记录结构化原因，避免反复选择同一个不可执行目标，同时允许世界变化后重新尝试。

开发内容：

1. 新增 `ProspectFailureKey`，至少包含矿物坐标、目标类型、失败阶段、失败原因和维度。
2. 黑名单原因区分 `no_air_neighbor`、`above_current_layer`、`route_budget_exceeded`、`danger`、`target_changed`、`tool_mismatch`。
3. 每个失败项带过期 tick，避免永久误伤。
4. 重探时优先排除未过期失败矿点。
5. 失败摘要写入 `MiningRun` 和 `mining.log`。

验收标准：

1. 同一远处隐藏矿不会在失败后立刻被重新选中。
2. 黑名单过期后仍可重新评估。
3. 失败原因可用于 DeepSeek 复盘上下文。

验证方式：`./gradlew build`；agent2 复查黑名单粒度不会误伤整个矿种。

### 7.8 路线执行本地复盘

状态：`[ ] 未开始`

目标：路线失败不再直接依赖 30 秒 DeepSeek 心跳，而是先由本地策略立即恢复。

开发内容：

1. 新增本地 `MiningRouteRecoveryPolicy`。
2. 输入当前 stage、探矿结果、失败原因、背包、工具、位置和最近黑名单。
3. 输出动作：继续当前路线、重探、切换近场探索、换目标、补工具、请求玩家协助或终止。
4. DeepSeek 只在本地策略无法判定或多次失败后介入。
5. 复盘结果写入 `planning.log` 和 `mining.log`，便于追踪。

验收标准：

1. 类似 `prospect_target_above_current_layer` 的失败会先走本地恢复。
2. DeepSeek 不可用时，AI 仍能执行重探或换目标。

验证方式：`./gradlew build`；agent2 复查本地恢复不会绕过生存执行。

### 7.9 挖矿回归用例自动化

状态：`[ ] 未开始`

目标：把这类失败固化为回归测试和日志验收模板，避免以后只修当前样例。

开发内容：

1. 增加阶段式路线单元测试，覆盖目标同层、低于目标、高于目标、远距离隐藏矿、近距离暴露矿。
2. 增加评分测试，确认近距离可执行目标优先于远距离隐藏目标。
3. 增加黑名单测试，确认失败目标不会立即重选。
4. 更新 `docs/mining-regression.md`，新增“两块金锭前置铁矿失败”样例。
5. 记录实机测试字段：`taskId`、初始坐标、选中矿点、分数、重探次数、最终背包。

验收标准：

1. 自动化测试覆盖本次失败模式。
2. 后续改动如果重新把远处隐藏矿作为硬目标，测试会失败。

验证方式：`./gradlew build`；agent2 复查测试是否覆盖当前失败链。

### 7.10 金锭完整链路实机验收

状态：`[ ] 未开始`

目标：验证“从零开始取得两块金锭”不再卡在铁矿前置链。

开发内容：

1. 实机执行 `/ai say 给我挖两块金锭`。
2. 记录木材、圆石、铁矿、煤、熔炉、铁镐、金矿、熔炼金锭每个阶段的结果。
3. 对失败情况区分可接受失败和代码失败：例如玩家不在已加载区域、附近无矿洞、工具耐久不足是可解释失败；远处隐藏矿导致直接终止是代码失败。
4. 若失败，必须能从日志看出重探次数、候选评分、最终请求协助原因。
5. README 增加当前金锭链路能力边界。

验收标准：

1. 普通森林/地表起点至少能稳定完成前置工具和铁矿搜索恢复，不会在第一次路线失效时清空任务。
2. 如果没有足够环境条件，失败消息必须说明玩家该怎么协助。
3. agent2 完成最终逻辑复查。

验证方式：`./gradlew build`；`runClient` 实机复测；agent2 复查日志和代码路径。