# XFE AMS 2.0

XFE AMS 是 Space Engineers 原版编程块采矿舰队系统：自主推进器与陀螺飞控、移动母舰靠泊、按实际库存循环卸货、按总储能计算电量、有限区域探索试钻、手动范围采掘，以及 LCD Sprite 仪表盘。一次构建同时生成简体中文和英文两套脚本，每套包含四个角色；编程块自带屏幕默认显示图形化配置与状态。

矿机分别可以在大气/重力环境和太空作业；单次任务不负责穿越大气层。远程控制可作为位置、速度和姿态测量方块，飞行不使用其自动驾驶航点。系统面向单一刚性网格矿机，设计上限为 16 台。

**验收状态：代码编译、MDK 分析、打包及逻辑测试与游戏内验收分开记录。** 本仓库不把编译成功解释为实际飞行或多人服务器验证完成。首次部署请按照 [游戏内验收清单](docs/VALIDATION.md) 在测试存档中完成空载、重载、靠泊和三趟循环测试。

## 部署结构

| 角色 | 放置位置 | 导出的可粘贴脚本 | 用途 |
| --- | --- | --- | --- |
| `fleet` | 母舰/基地，1 个编程块 | `dist/zh-CN/AutoMiningFleet/script.cs` | 调度、泊位、母舰运动遥测、卸货、大屏 |
| `miner` | 每台矿机，1 个编程块 | `dist/zh-CN/AutoMiningScript/script.cs` | 自主飞控、采矿、能源、小屏 |
| `marker` | 可选标点船/基地终端 | `dist/zh-CN/AutoMiningMarker/script.cs` | 摄像机/GPS 标点并提交给主控 |
| `watchdog` | 可选，每台矿机另一个编程块 | `dist/zh-CN/AutoMiningWatchdog/script.cs` | 业务脚本停止后解除控制覆盖 |

表中为中文版；英文版位于相同结构的 `dist/en-US/` 目录。选择对应角色的完整脚本粘贴即可，无需向游戏额外安装语言资源。每份脚本首行注明角色，中文主控首行为 `// XFE AMS | 舰队主控（母舰） | zh-CN`。`dist/manifest.json` 记录本次八份产物的路径、实际校验角色、语言、字符数和 SHA-256。旧构建留下的 `dist/<角色工程>/` 文件不属于本次双语产物，请以清单为准。

**脚本类型由所粘贴的文件固定决定，不再配置“角色”。** 新模板不生成 `角色` / `Role`，旧配置残留的字段会被忽略，即使值填写错误或中英文值冲突，也不会改变脚本类型或阻止初始化。配置屏显示编号、语言和实际运行参数。原自定义数据不会被整段重写，已有编号、舰队编号、主控编号及方块组继续使用原值。

游戏内仅粘贴各角色 `script.cs` 内容，不安装 DLL。工程中的 `XFEExtension.SpaceEngineers.ScriptingHelper 1.0.3` 仅用于开发机的游戏 API 引用；脚本不继承 `IProgramBase`，不依赖该包在游戏内运行。

世界设置需要允许编程块脚本，舰队之间需要可用的 IGC 无线通信。所有参与方保持相同的“舰队编号”，每个编程块使用不同的“编号”，矿机与标点端的“主控编号”等于主控的“编号”。只有同舰队且协议兼容的数据参与调度。

**中文版的自定义数据、运行参数和枚举值均支持中文，以下部署示例以中文版为准。** 新生成模板使用“采矿舰队”“主控”“采矿泊位”“基地货仓”等默认名称；旧英文配置和原英文命令继续兼容，已有 `CustomData` 不会被自动重写。参数及命令完整对照见 [中文参数手册](docs/PARAMETERS.zh-CN.md)。中英文混用时，必须手动统一舰队编号和主控编号；“采矿舰队”与 `mining`、“主控”与 `base` 是不同的真实身份，不会按含义自动合并。旧部署可以继续使用原来的英文 ID 和方块组名，不必为翻译而更名。

编程块加载有效配置后自动设置自身名称，重新编译时会同步更新。中文主控固定为 `XFEAMS系统`，英文主控固定为 `XFEAMS System`；矿机、标点终端及看门狗均使用 `XFEAMS-各自ID`，例如编号“深空工业3号”的矿机编程块叫 `XFEAMS-深空工业3号`。ID 使用配置原文，不翻译、不重复添加“矿机”等前缀。仅修改编程块名称，舰船名称、通信编号、任务和自定义数据保持原值；无需新增命名配置。

## 硬件与建造要求

每台矿机需要：

- 一个可测量速度、重力、质量的驾驶舱或远程控制。
- 能覆盖前后、左右、上下六个方向的推进器和至少一个陀螺。大气推进器有效推力会随环境变化，不能使用地面空载数据代替重载能力。
- 全部朝同一方向的钻头，钻出的孔道必须容纳完整船体与安全间隙。推进器、钻头、控制器和连接器都必须在编程块所在刚性网格上。
- 可共同覆盖运动方向、退出方向与钻孔入口的摄像机。系统按区域选择位置、朝向和充能合适的镜头，合并扫描结果；不要求某一台镜头独自覆盖整个船体。扫描需要充能。
- 至少一块电池、足够容量的货舱、连接器、完整的传送系统。使用氢推进时需要储氢罐；库存中的冰不被当作保证可用的氢燃料。
- 能覆盖作业范围的通信设备。建议添加单独安全看门狗编程块。

不支持子网格推进器、转子/活塞钻具或子网格连接器。不可用“同构造”扫描来代替矿机所属网格，因为连接器会把母舰与矿机临时连成同一构造。运输载荷仅统计本刚性网格的货仓、钻头和连接器；反应堆、制气机等功能方块的供料库存另行保留，全部库存质量仍计入矿机称重。母舰库存和质量不计入。

母舰需要一个船舶控制器、与“泊位方块组”配置一致的连接器组、与“基地货仓组”一致的接收货舱组。中文版新模板默认名称为“采矿泊位”“基地货仓”；旧部署可继续使用 `AMS Docks`、`AMS Cargo`。组内受管方块必须在主控的刚性网格上。每个泊位的外侧预留完整的直线进出港通道，避免装饰、太阳能板或其他停泊船侵入；母舰可以移动，但只能在运动窗口满足条件时进出港。

中文版兼容两套默认组名：配置中的“采矿泊位”组不存在时会查找 `AMS Docks`，“基地货仓”不存在时查找 `AMS Cargo`，反向同样适用。已经存在的精确名称优先；自定义组名仍须完全匹配。只接管选定组内的母舰本体方块，不自动加入其它用途的连接器，也不改写自定义数据。诊断会分别指出缺失的泊位组和货仓组；缺少泊位的原因也会发送给等待返航的矿机。

## 从零启动

1. 在开发机运行下方构建命令，把主控、矿机及可选角色对应脚本分别粘贴到编程块并检查编译。
2. 首次编译会在空 `CustomData` 中生成 INI 模板。修改标识和硬件配置后重新编译以加载配置。配置齐全、硬件自检通过的空中矿机会自动请求返航接港；现有自定义数据不会被模板覆盖。
3. 在母舰创建“采矿泊位”和“基地货仓”方块组，名称与主控自定义数据一致。在主控运行 `诊断`，确认驾驶舱、泊位和接收库存可用。
4. 默认 `[硬件] 自动标定=是`：矿机自动初始化，并使用连接器的实际安装位置与朝向完成首次接港；主控暂停派工时仍接受返航，无需先人工连接或逐台运行 `标定`。连接成功后才保存实际贴合间距和姿态，尚未连接时仍显示“标定=否”。连接器不必与控制器共线。显式暂停或交还控制的矿机需从主控执行 `继续 矿机编号`；设为 `自动标定=否` 时，未标定矿机需人工连接后执行 `标定 矿机编号`。`[飞行] 起飞质量=0` 在停靠后自动测量本机起飞质量；也可填写覆盖最大预计起飞总质量的正数（kg），用于停靠时检查起飞推力。
5. 校核下节的钻头覆盖和钻尖偏移。安装看门狗时完成其配置和握手。
6. 主控运行 `标点 ...` 创建手动任务，或 `探索` 创建有限探索区域；检查矿图和任务数量。
7. 主控运行 `启动`。日常启停、召回、诊断、重扫和可选手动标定均可从主控发出，无需逐台操作矿机编程块。矿机会等待载荷满足离港阈值、足够能源、有效任务、许可及母舰平稳窗口，满足后自行出港。默认运输库存占用率降到 5% 或以下后可进入离港检查。

控制器设置示例：

```ini
[系统]
编号=矿机01
舰队编号=采矿舰队
主控编号=主控

[硬件]
自动标定=是
; 留空扫描本刚性网格。填写后必须是准确组名/方块名。
方块组=
控制器=矿机驾驶舱
连接器=矿机连接器
; 从钻头中心到有效钻尖的前向距离，单位 m，必须实测。
钻尖偏移=0.5

[飞行]
; 0：停靠时自动测量本机质量。正数：手动指定最大预计起飞总质量（kg）。
起飞质量=0
巡航速度=15
退钻速度=1
安全间距=1
每帧扫描射线=2

[采矿]
; 常用建造矿、燃料与稀有矿：铁,钴,镍,硅,冰,镁,银,金,铂,铀,石头
; 目标留空则全部采集，包括石头；优先矿种决定已确认矿点的调度顺序
目标矿种=
优先矿种=铁,钴,镍,硅
钻头覆盖宽度=6
钻头覆盖高度=6
重叠比例=0.15
孔道半径=3
钻进速度=0.5
单趟进尺预算=15

[货物]
载荷返航阈值=0.95
; 货仓、钻头、连接器允许离港的最大占用率；0 要求待卸矿物清空。
起飞载荷上限=0.05

[能源]
电量返航阈值=0.25
低氢阈值=0.25
充电目标=0.90
补氢目标=0.90
能源安全系数=1.5
紧急能源余量=0.10
靠泊预留秒数=120

[显示]
方块组=采矿屏幕
屏幕标签=[采矿屏幕]
页面=矿机
内置屏幕=是
内置屏幕页面=配置
字体=默认
每帧绘制屏数=2
离线判定秒数=5
自动翻页=是
轮播间隔秒数=8
手动停留秒数=20
```

`起飞质量=0` 时，矿机保持连接，分帧统计**本刚性网格的全部方块质量（含装甲）与完整库存质量**，库存按世界库存倍率折算；不会为称重主动脱离母舰，也不会把母舰质量加进来。自带屏配置页显示“测量中”或自动测得的 kg 数。测量未完成、库存快照过期或质量无效时保持停靠，不能用 `0 kg` 绕过推力检查。卸货、补给和船体变化会触发质量更新；重新编译或重扫后重新测量。**增换方块、尤其是带库存的方块后，先停靠，再在主控运行 `重新扫描 矿机编号` 重建硬件列表**；周期称重不会自动发现新的库存方块。离港后飞控使用控制器实时报告的物理质量，手动填写的正数也不会冻结飞行中的质量。

库存扫描单次最多读取本机 128 个库存的质量，并统计运输库存中合计最多 512 个物品堆栈，以保留原子快照并限制执行成本。功能方块的供料只参与称重。超限或扫描异常时会自动清理临时扫描结果，保留上一份完整数据，撤销卸空、离港载荷、采样和起飞质量许可；能源更新与退钻返航仍继续执行。修复库存规模或硬件问题后，停靠后在主控运行 `重新扫描 矿机编号` 解除扫描故障，再完成两次满足当前离港载荷条件的完整扫描。不会自动删除或抛弃真实物品。

母舰最小配置：

```ini
[系统]
编号=主控
舰队编号=采矿舰队
主控编号=主控

[舰队]
控制器=母舰驾驶舱
泊位方块组=采矿泊位
基地货仓组=基地货仓
矿机数量上限=16

[采矿]
; 留空采集全部（含石头）；优先顺序单独设置
目标矿种=
优先矿种=铁,钴,镍,硅
钻头覆盖宽度=6
钻头覆盖高度=6
重叠比例=0.15
孔道半径=3

[探索]
采样间距=60
扩挖宽度=60
扩挖高度=60
最大深度=100
任务数量上限=2048

[显示]
页面=舰队
```

`钻头覆盖宽度`、`钻头覆盖高度` 表示实际连续有效开挖覆盖，不能只填钻头外观总尺寸。`孔道半径` 用于空间占用与安全互斥；必须覆盖矿机安全包络。各矿机与主控使用一致的钻孔尺寸，异形/不同尺寸矿机应分别建立舰队。先在低速浅孔中实测孔道尺寸、船体尾部和偏置钻尖，不能靠增大参数跳过硬件问题。

## 两种采矿模式

### 手动标点与完整范围采掘

主控可以直接标点；独立标点端粘贴标点终端脚本，设置正确 `主控编号` 后发送同样的标点请求。

```text
标点 20 15 30
标点 20 15 30 GPS:入口:100:200:300: GPS:向内:100:200:330:
```

前三个数依次是入口平面宽度、高度、向内深度，单位 m。摄像机方式使用命中位置为入口中心、视线为钻入方向、摄像机上方向为入口平面的上方。GPS 方式要求**入口点和向内方向点两个不同坐标**；坐标可以包含 0。入口中心与任务区域会冻结在世界坐标中。

摄像机标点只接受行星或小行星表面。可通过 `[标点] 摄像机=准确名称` 选择摄像机，`扫描距离=1000` 设置扫描距离。提示摄像机充能不足时，待扫描范围恢复后重发命令。

范围被分成有重叠的平行孔，采用固定蛇形顺序。手动任务会完成规定范围和深度，遇到无目标矿段也继续；安全故障仍会使任务中止或暂停。实际开挖可能略超出几何边界，取决于钻头实际作用体积，不能用于贴近重要设施的精密切削。

### 自动探索、试钻与指定矿种优先

```text
探索
探索 300
启动
```

`探索` 在主控当前位置冻结一个有限区域；标点端的同名命令也使用主控当前位置。默认大气半径 300 m、太空半径 2000 m，可用参数覆盖。大气按地表采样点搜索，太空按有限观察点及方向扫描小行星。

航行避障与探索扫描都利用已安装的前后、左右、上下各方向镜头。目标方向已有工作镜头覆盖时保留船体姿态；镜头正在充能时等待或使用同方向其他镜头，不因缺电转船。只有目标射线缺少有效视场时，才按实际镜头安装朝向转动探测，并检查该姿态的悬停与制动能力。扫描阶段以已接受的观察位置停驻，不再要求朝侧面挪回更精确的坐标。射线终点仍由冻结的探索任务决定，实际命中位置与方向回传主控。导航避障射线命中的行星或小行星表面也会交给探矿逻辑：若小行星挡在观察点前方，可直接报告实际命中并申请试钻，不必先穿过小行星到点。主控仍核对冻结区域边界并去重，摄像机列表仍仅在初始化或明确重扫时更新。

扫描新发现小行星后，收到发现报告与完成遥测即可优先安排下一次试钻派发；发现者资源不足时由其他可用矿机接手。其它矿机保留已有扫描任务，正在钻孔的矿机不会被抢占。

**自动探索不再每扫一条射线就返航。** 完成扫描或退出已完成的自动试钻孔后，矿机显示“等待本矿区续派”，主控优先分配同一搜索区的新试钻点，其次安排附近未完成的观察方向。相同观察点的不同扫描方向可以原地连续执行。其它矿机正在占用所需空间时等待，不能把暂时无可用任务算成整个区域完成。返航条件仍包括满载、低电/低氢、动力或通信问题、返航指令，以及本区域已无待执行任务；不自动转去另一个搜索区。手动范围采掘仍沿原流程完成规定孔道。

空中续派会重新核算当前位置到新任务、退钻和返回移动母舰的能源；不套用停靠时的5%离港载荷和90%充电锁存门槛。预算不足时保留新领取任务并返航补给。结果会重发并随存档保留，续派绑定上一任务编号；晚到任务不会撤销暂停、返航或人工接管。更新时同时替换主控和所有矿机脚本，恢复上线后在主控运行 `继续`，可保留已有探索任务，无需重新创建矿区或逐机标定。

摄像机能判断实体及表面命中，**不能透视矿种**。系统钻进时每 5 m 比较货仓、钻头和连接器中的矿物库存增量，记录全部检出矿物，同一采样可确认多种矿物。`目标矿种` 是自动矿点的采集范围，默认留空，表示全部采集（包括石头）；显式填写列表时只安排其中的已确认矿点。`优先矿种` 单独决定已确认矿点的调度顺序，默认 `铁,钴,镍,硅`，列表靠前者优先；其余允许采集的矿物作为普通矿点。优先列表不会扩大目标范围。已有自定义数据不会自动重写，旧部署若要启用全矿种采集，需要将原 `目标矿种` 的值清空。

库存内部转运不会被算成新发现。采样时受管制气/加工/抛货会停用；如果仍存在库存损失或无法隔离，会提示采样无效并将未证实的试钻标为受阻，不会推断“这里没有矿”。

默认试钻深度为大气 60 m、太空 40 m，`[探索] 试钻深度` 可显式设置。发现区的扩挖受 `扩挖宽度`、`扩挖高度`、`最大深度` 和原搜索边界共同限制。连续两圈相邻孔没有目标矿增量后停止扩张。搜索完成后返航等待，不无限增加范围或深度。

`[探索] 母舰安全间距=80` 将大气观察点沿反重力方向抬高 80 m；太空首个观察点也避开母舰中心，且保持在搜索球内。搜索区域仍以创建时的世界坐标固定。按母舰体积和附近地形增大净空；不把母舰内部当作可到达的观察位置。入孔前执行中心和四周共五点检查，`[采矿] 入口高差上限=5` 限制新孔入口的地表起伏；已有孔道发现其他船体占用时拒绝钻进。

请区分结果：`SurveyEmpty` 表示该次扫描没有表面命中；试钻未检出只表示已采样部分没有目标矿增量；“采样完成”不等于已经确定地下无矿；手动任务的“指定范围采掘完成”才表示其计划钻孔全部完成。受阻或无效采样的区域不能当作正常完成。

## 周转、能源与移动母舰

矿机正常流程为停靠自检、领取任务、离港、飞行、探索/采掘、沿孔轴退钻。自动任务完成后可在矿区续派；需要卸货或补能时再返航、排队、对接、服务后继续任务。满载默认 95%，钻头库存堵塞、低电/低氢、返航预算不足或承载能力不足也会提前返航。保存孔位和实际进尺，卸货后可以从已开挖的孔恢复。

**收到进港请求时，只要有可用连接器，主控立即分配并发送位姿。** 新矿机可用首次请求同时登记和申请，不必先完成另一轮遥测或等待定时调度。不同连接器可同时分配进港或离港；主控只分配连接器，不进行进出港整条航道、假想接近路线或停泊船球形包络的封锁判断。同一连接器仍只分配给一台矿机，紧急低能源返航请求优先。

离港矿机保持接港姿态，沿分配连接器的开口方向向外直线飞出，再转入任务航线。各连接器以固定的打乱顺序错开直飞距离，相邻序号相差10米；未来航段相交不会阻止不同连接器同时获准离港。飞行时仍处理真实障碍与实际接近风险。

飞行时，只有实际相对轨迹预计进入两机船体包络，且预计接触时间已进入包含反馈响应和遥测延迟的避险范围时，才随机选择一方让行。风险触发后，侧移或等待都会加强制动，实际制动力仍受矿机推力限制。同一次遭遇保持随机优先顺序，侧移按最多2米一小步、1.5m/s推进；恢复原方向已无接触风险时立即解除，不等待固定分离距离。近泊位侧移保持当前姿态，侧移和等待都跟随母舰对应点速度；侧移终点不能跨过按船体半径留出的连接器净空面。例如在接口前方27米时，可以安全向接口方向挪2米，已处于净空面内则不再向内深入。侧移仍用摄像机扫描包含母舰船体的实际障碍。正式 `DockApproach` 也可短暂停航或执行这项近距侧移，完成后继续对接原连接器；过期位置不能授权未经确认的侧移。

“三次靠泊失败”属于靠泊故障，不能据此判断相机没发现小行星；故障状态本身不会继续执行探索。现在保留最后一次失败的具体原因。确认故障矿机已停稳且遥测新鲜后，主控释放远处未进入的任务及可确认已离开的泊位分配；实际占用或状态未知的泊位仍保留，清理离线名单和重载也不会抹掉这份分配。排除原因后在主控运行 `继续 矿机编号`，保留的矿机端原指令也仍可使用。

开放空间返航与前往接口前方时，矿机会朝实际航段调整姿态，利用整组摄像机检测航路。近似直线的返航航迹点提前衔接，保留原扫描有效范围内的新鲜净空；转弯、真实障碍或扫描证据失效时仍减速。重力环境先检查目标姿态的悬停能力。孔内退钻保持原孔轴，出港保持实际接港时的姿态，直到离开母舰通道。

收到有效泊位分配后，矿机直接前往接口前方的引导点，再连续进入对接；已经位于接口前方的矿机就近接入轴线。等待点只在没有可用分配时使用，取得分配后无需先飞到远处等待点、停稳，再返回接口。主控将连接器按实体编号稳定打乱顺序，以 `[对接] 接近距离` 为基础（默认30米），逐个增加10米，得到各连接器不同的起始对接距离；顺序不随每帧变化，当前分配的距离会保存。矿机至少保留两倍自身半径的入口距离。前往引导点的途中仍扫描避障，沿轴线到达入口时连续转入正式对接；已在入口以内且没有近距冲突的矿机就近接入。近港重启返航会核对新分配后就近进港，不先飞回旧采矿航迹的远端。

主控按连接器是否可用、是否已有分配决定泊位，不再等母舰运动稳定窗口后才发送分配；主控暂停派工时也会处理返航请求。矿机收到位姿后自行检查遥测时效、母舰运动、姿态及动力，决定何时实际接近。重载后旧令牌失效；矿机重新请求进港、遥测新鲜且仍在对应入口范围以外返航或等候时，主控可以重新选择可用泊位。正在接近、贴合接口或位置未知的分配仍保留。等待原因会区分“泊位已分配给：矿机编号”“等待空闲且可用的泊位”和矿机端的运动或遥测限制；占用检查针对同一连接器，解除后自动重试。

“进港对接”按两个连接器的实际安装关系控制姿态，使开口相向、上方向一致；自动标定保留连接器中心的对接间距，修正人工停靠时的横向和角度偏差。**正常轴向贴合关闭摄像机扫描及扫描限速**，清除上一段的绕行目标与扫描等待；实际近距冲突仍可触发短暂停航或带扫描的侧移。侧移时回到对齐阶段，再恢复原泊位的正常贴合。尚未吸附时继续检查许可、遥测和动力；人工接管始终优先。直接对接的扫描诊断描述正常贴合，近距让行时另显示让行对象及当前扫描原因。

已标定的正常直线进港随剩余距离逐步减速，最后1米才采用 `最终接近速度`（默认0.5m/s，有效范围0.5～1m/s）；最后3米仍要求姿态与速度连续稳定2秒。旧配置0.2或0.3m/s会自动按0.5m/s执行。对准后正常闭合不再被位置控制器继续压成0.1m/s爬行；姿态尚未稳定、实际障碍、近距让行、遥测或运动条件无效时仍会减速或停航。首次尚未测得贴合间距时，在距连接器中心至少6米、且不小于两倍矿机半径的范围内先稳定低速，再沿接口轴线接近。返航、进港等候、对齐、贴合或接港退避时，游戏一旦报告连接器“可连接”，就立即清除推力与陀螺覆盖并尝试锁定；不再等待姿态误差、相对速度、稳定计时或进港遥测门槛，也不等待两个方块中心重合。连接状态由[官方连接器接口](https://keensoftwarehouse.github.io/SpaceEngineersModAPI/api/Sandbox.ModAPI.Ingame.IMyShipConnector.html)提供。

尚未进入可连接范围时，末段轴向接近需横向偏移小于0.15m、姿态误差小于1°、横向速度小于0.1m/s、角速度差小于0.1°/s，连续稳定2秒；可在接近途中累计。进入后采用较宽的退出门限（0.25m、2°、0.2m/s、0.2°/s），避免轻微波动反复重置2秒等待。超过退出门限时暂停轴向接近、修正姿态后重新取得稳定窗口；已可连接则直接锁定。真正连接成功后立即上报连接状态并核对实际泊位；有效库存与能源快照会分别显示“正在卸货”“正在充能”，两项都需要时同时显示，全部完成或无需求时显示“待命中”（故障仍保留故障状态）；连接尚未完成时显示“连接器已吸附，正在锁定连接”，保持停止飞控修正并重试。主动暂停、人工接管及正常离港不会触发这项自动锁定。未吸附的两段进港状态都以连续60秒无进展触发退避，持续接近不会因为整段超过旧版4分钟限制而退出。

真正连接后关闭本矿机全部推进器并清零覆盖，包括本机控制组以外的推进器；母舰推进器不受影响。离港准备时恢复推进器，再检验推力和脱开条件，失败则重新停车；意外脱开后恢复飞行动力。

遇到母舰等障碍时，矿机先扫描候选绕路，按到目的地的剩余路程、已观测障碍和近期走过的位置排序。前后、左右、上下及斜向均可成为候选，不再盲选侧移并强加朝障碍前进的分量；整段船体包络扫描通过后才移动，再逐段接近原目标。候选受阻、持续自遮挡或所需姿态推力不足时换下一条；未扫描区域不视为空路，暂无空路时继续探测。

已经命中的近处栏杆等障碍会短期保留，后续射线穿过缝隙不会立即清除该障碍。记录按实体区分，静止点最多保留30秒、移动点3秒；母舰移开后旧记录会失效，指定连接器的接触许可也会更新对应判断。

扫描以待检测区域为单位，按镜头安装位置、朝向、可用距离分配检测工作，把所有镜头的有效结果合并为一轮扫描。某个镜头扫到自身船体时，仅在当前检测点尝试其他镜头，不清空已有的新鲜净空，也不把这个镜头从其他检测点永久排除。例如前方三个镜头中间一个被挡住，左右镜头仍可共同完成扫描；中间镜头在能看见的其他区域仍会被使用。

钻孔入口确认和探索采样同样会在某个镜头命中本机时继续尝试其他镜头；所有镜头都被本机遮挡时保持等待，不报告入口被其他船占用，也不把尚未观察到的区域记为无表面。

近处航点不会把扫描平面强行压到船头旁边。需要时，近处边缘采样点会沿同一检测方向移动到候选镜头的可视深度，最远不超过本轮扫描距离；每个计入结果的点都必须得到游戏 API 允许并实际完成射线检测。扫描可以观察到本段航点之外，但本段可用净空只计算到航点及船体前缘；航点后方的障碍不会被误判为本段必经障碍。不会跳过未完成的检测点并把它计为已扫描。整组镜头都无法完成某个区域的检测、充能不足或实际发现障碍时，诊断才报告相应问题。

远端射线命中障碍时，矿机会继续汇总各区域的检测结果，以最近命中限制可用净空。整轮扫描完成后，可以沿已经确认空出的部分继续接近，并根据船体前缘、制动力与速度余量减速；不会因为远处一次命中就把前面十几米的空路全部清零。新出现的近障碍会立即缩短已有净空，真正挡住船体时仍停车。障碍名称、距船体距离及命中区域会持续显示，直到新的完整扫描确认解除；普通等待扫描显示 `N/18` 进度，避免下一轮扫描掩盖受阻原因。这个距离是沿当前航向计算的船体余量，不是屏幕标记到玩家的距离。

在主控运行 `诊断 矿机编号` 可查看“已识别 / 工作 / 当前射线可扫”、扫描方向，以及“联合扫描：已完成 N/18 个区域，M 个镜头参与”。无法形成可用视线时，提示的是整组镜头尚未覆盖的区域，具体镜头的角度或遮挡作为补充诊断。视角问题不会导致扫描距离不断缩短；仅充能不足才缩短，并保持扫描终点在船体前缘之外。

摄像机列表仅在矿机脚本初始化和明确执行硬件重扫时建立，正常飞行期间不定时刷新。增删摄像机后，在安全停靠或暂停状态从主控运行 `重新扫描 矿机编号`；也可定向执行 `初始化 矿机编号`，主控不带目标的 `初始化` 则会清空主控存档。硬件扫描仍遵守本机刚性网格及方块组限制。初始化、硬件重扫和离港准备会启用已受管的镜头及射线充能。摄像机角度、可用距离和射线开关的含义见 [官方相机接口](https://keensoftwarehouse.github.io/SpaceEngineersModAPI/api/Sandbox.ModAPI.Ingame.IMyCameraBlock.html)。

`[采矿] 单趟进尺预算=15` 是出发时能源预算中的新增进尺预留，不是孔深上限；续挖还要计入已钻深度的进出成本。作业途中仍按实时能源和载荷决定何时返航，不强制每 15 m 返回。若准备预算已经超过满电/满氢容量，缩短任务距离、分段深度或增大能源容量；不能靠降低安全储备掩盖无法返航的任务。

| 常见状态 | 含义 |
| --- | --- |
| `Docked` / `Servicing` / `Ready` | 已停靠、卸货补能或检查离港条件 |
| `Departing` / `Transit` | 沿泊位通道离港、飞往任务入口 |
| `Survey` / `Align` / `Drilling` | 表面扫描、入口对齐、钻进 |
| `Retreat` / `Returning` | 保持孔轴退钻、沿验证航路返航 |
| `Holding` / `DockAlign` / `DockApproach` / `DockRetreat` | 等待泊位、前往接口前方、连续进港并减速贴合、取消接近退避 |
| `Paused` / `Manual` / `Fault` | 任务暂停、已交还人工控制、故障；结合原因判断下一步 |

电量比例按 `Σ剩余储能 / Σ最大储能` 计算；储氢按储罐容量加权。脚本分别学习巡航、悬停、钻进、返航能耗，并加入退钻、母舰会合、排队与靠泊预算。低电兜底为 25%，预算不足时会更早返航。充电一旦触发会保持到至少 90% 且下一趟预算足够；不需充电时，满足离港载荷条件即可申请离港。小屏 `NET` 功率正数表示净放电，负数表示净充电；`BRAKE` 是最弱方向扣除重力后的可用净加速度，单位 m/s²。

`Cargo`、`OreAmount`、`Empty`、卸货状态及出发/返航载荷阈值都只统计矿机本体的**货仓、钻头和连接器库存**。其中石头、冰等全部矿物均可卸货，不抛石；非矿物补给保留，但占用运输库存的体积仍计入载荷。反应堆燃料、制气机的冰及其它功能库存不计为运输载荷或待卸矿物，主控不会主动抽走这些供料。全部库存质量仍用于起飞称重。

主控将运输库存中的矿物转移到配置的基地货仓；基地传送系统仍按其自身设置工作。`Empty` 表示连续两次完整扫描确认待卸矿物为 0。离港另按 `[货物] 起飞载荷上限` 判断，默认 `0.05`：连续两次完整、有效扫描确认运输库存占用率 ≤5%，即可继续出港检查；零载荷同样满足。

设置 `起飞载荷上限=0` 可恢复严格清矿模式：全部待卸矿物必须为 0，非矿物补给仍保留。正数阈值必须小于返航载荷 `载荷返航阈值`。停靠期间主控会继续卸货；达到默认 5% 后无需等剩余矿物全部卸净，也不再仅因这部分残余矿物产生“卸货无进展”告警。基地满仓或传送不通且载荷仍超离港阈值时继续停靠；能源不足、任务无效、泊位分配或母舰窗口不满足也不能起飞，**没有“对接若干秒后强制出发”逻辑**。修改参数后在停靠状态重新编译使其生效。

靠泊按连接器自身的位置与速度控制，并计算母舰转动导致的连接器线速度。矿机实际接近的默认运动窗口：连接器速度 ≤5 m/s，母舰角速度 ≤0.2°/s，连接器加速度 ≤0.1 m/s²，遥测年龄 ≤0.5 s。主控发送泊位分配不等待这些条件。已标定矿机最后1米的默认目标相对速度为0.5 m/s；此前按剩余距离与实时制动力逐步减速，最后3米保留姿态稳定检查。远处航行受扫描净空限制。参数位于 `[对接]`：

```ini
[对接]
母舰速度上限=5
母舰角速度上限=0.2
母舰加速度上限=0.1
遥测时效上限=0.5
平稳窗口秒数=2
接近距离=30
最终接近速度=0.5
等待点距离=80
等待点间距=20
```

没有泊位分配时，主控将固定的 `WaitingSlot` 对应到按连接器实体 ID 排序的实际泊位。首排等待点沿各自泊位开口 `Forward` 方向设置，以 `等待点距离` 为基础，并至少处于该连接器入口再向外一个 `等待点间距` 的位置；超过泊位数量后沿同一方向展开下一排，每排增加 `等待点间距`。默认基础距离80米、排间距20米；起始对接距离较长的泊位相应外移等待点。横排泊位的等待点保持横排，连接器绕自身开口轴旋转90°不会把队列变成竖排。清理离线名单或重载保留已有槽号；泊位组和配置不变时等待位置稳定。真实对接姿态仍匹配连接器自身的上方向。

母舰运动超限、许可失效或遥测过期时，矿机会退出接近并等待；已连接时失联不会主动脱离。默认三次靠泊失败后暂停。无法在剩余能源内追上母舰时需要母舰驾驶员减速或接应，主控不会接管母舰驾驶权。

## 图形屏幕与命令

编程块自身的第一个显示面（`Surface 0`）默认加入仪表盘，无需改名或加入方块组，优先显示“配置”参数页。页面包括系统名称、编号、界面语言、状态和当前已生效的配置；参数分页默认自动轮播，也可使用 `页面 +` / `页面 -` 手动查看更多参数。第二个及后续显示面仅在配置了 `[屏幕.1]` 等节时启用，避免默认在很小的键盘屏上绘制完整仪表盘。

参数页使用更大的字号和高对比度配色，按显示面的实际可见宽度排版：宽屏每页 5 项，名称和值分列；普通屏或竖屏每页 4 项，名称在上、值在下。过长的文本按当前字体实际宽度省略，保持字号，不再为塞入整段文字而缩小。完整参数仍可在编程块 `CustomData` 中查看。此调整针对“配置”页，其他仪表盘页面保留原布局；脚本不能提高游戏显示面本身的纹理分辨率，实际中文字形和可读性仍需游戏内确认。

在编程块 `CustomData` 的 `[显示]` 中设置 `内置屏幕页面=矿机` 可让自带屏默认显示单机状态，设置 `内置屏幕=否` 可关闭自带屏托管。编程块自身的 `[屏幕] 页面=...` 可覆盖默认页；`启用=否` 优先关闭该显示面。配置页只读，修改 `CustomData` 后在停靠状态重新编译，屏幕会显示新生效的值；主控不带目标的 `初始化` 会清空旧存档并加载配置；只更新硬件列表请用 `重新扫描`。

自动翻页默认开启：每个屏幕独立计时，每 8 秒循环切换当前页面类型的子页，包括参数分页、舰队列表、未绑定的矿机列表和不同矿区；不会自动从参数页切到舰队等其它页面类型。设置了 `绑定矿机=矿机01` 的单机屏始终显示该矿机，只有一页时保持当前内容。屏幕底部用进度条和圆点标示轮播进度与当前子页。

在 `[显示]` 中可设置 `自动翻页=否` 关闭轮播，`轮播间隔秒数=8` 调整停留秒数（2～120），`手动停留秒数=20` 调整手动操作后的暂停秒数（0～300）。每个 `[屏幕]` 或 `[屏幕.N]` 节可用同名字段覆盖全局值。手动切页后，默认暂停 20 秒，再开始完整的 8 秒停留计时，下一次自动翻页约在操作后 28 秒发生；`页面 停止` 可持续停住查看，`页面 播放` 从当前子页重新计时。这两个命令只改变本次运行状态，重新编译后按配置恢复；永久关闭使用 `自动翻页=否`。轮播沿用屏幕绘制调度，不改变飞控更新频率。

已有部署更新显示效果时，先确认矿机停靠，再用重新生成的同语言、同角色 `script.cs` 替换编程块脚本并编译。运行 `页面 配置` 查看大字参数页，`页面 +` / `页面 -` 翻页，`页面 自动` 恢复各屏自己的页面绑定、首个子页及配置中的轮播设置。现有 `CustomData` 无需添加新字段，缺省即启用轮播。

将 LCD/驾驶舱加入本机配置的屏幕组，或在方块名加入配置的屏幕标签。中文版新模板标签为 `[采矿屏幕]`，可使用“采矿屏幕”组；旧部署可继续使用 `AMS Screens` / `[AMS LCD]`。同一屏只能由一个脚本负责。屏幕 `CustomData` 示例：

```ini
[屏幕]
页面=舰队
; 单机页可绑定其它矿机；留空在矿机上默认显示自己。
绑定矿机=
; 可选：覆盖本编程块 [显示] 的轮播设置。
自动翻页=是
轮播间隔秒数=8
手动停留秒数=20

; 驾驶舱的第二个面；第三个面使用 屏幕.2，以此类推。
[屏幕.1]
页面=矿机
绑定矿机=矿机01
启用=是
```

| 页面 | 数据 |
| --- | --- |
| `fleet` | 在线/总数、停靠和等待数量、任务汇总、每台电量/氢量/载荷、状态和首条告警；每页 7 台 |
| `miner` | 单机状态、能源与载荷条、MWh、净功率、估计续航、速度、重力、母舰距离、推力余量、孔深、任务号、原因/矿种摘要 |
| `map` | 主控探索地图：搜索边界、实测射线轨迹、去重的小行星轮廓与估算面积、矿机 ID/位置/离线状态；手动矿区显示孔位与进度；不同矿区及小行星子页自动轮播 |
| `diagnostics` | 指令预算、运行耗时、角色自检、硬件/泊位信息和最近事件 |
| `config` | 编号、语言、运行状态、已生效配置；按脚本类型显示飞行/钻采/能源阈值、舰队/泊位、标点或看门狗参数 |

离线数据保留并标注“离线”/`OFFLINE`，舰队列表显示数据年龄，不把最后已知状态当成实时状态。参数页和矿区页适配屏幕可见宽度，其他页面按原有比例居中缩放。默认每 0.5 s 最多绘制 2 个屏幕，多个屏幕轮转以保留飞控预算；设置 `每帧绘制屏数` 可调整吞吐。矿图单帧最多绘制 400 个孔位，统计仍覆盖当前矿区全部任务。图形按钮不是触摸控件，使用快捷栏、按钮板或编程块参数操作。字体使用 `[显示] 字体=默认`；目标游戏版本的中文字体覆盖及小屏排版仍需要游戏内验收。

主控运行 **`页面 矿区`** 可查看探索地图。蓝格表示实际射线经过该投影位置，未执行、仅预约和无有效扫描数据的受阻任务不会填亮；命中后的射线不会延伸到目标后方。格内仍有未扫描空间，不能将格子或扫描完成比例当作整片空间已排除障碍。太空地图使用冻结搜索区的参考平面；大气探索使用地表采样平面，投影可能重叠不同深度的位置。

地图上方显示所有搜索区域的整体扫描进度、已处理射线数与总数。小行星以圆形范围显示，`A1` 等为本矿区的显示编号；半径取实测世界包围盒外接球半径，旁边和底部显示近似圆形面积及去重数量，单位自动使用 m2/km2。这不是实际表面积、矿藏面积或可采矿量。尺寸来自相机返回的实体世界包围盒，未测得尺寸时不推算整颗大小。

矿物经实际钻采确认后，小行星圆周按矿种着色；一颗小行星含多种矿物时使用多色圆弧，并在明细中显示同色矿种符号：Fe铁、Co钴、Ni镍、Si硅、Mg镁、Ag银、Au金、Pt铂、U铀、Ice冰、St石头。未确认矿种时保留灰色。每页显示8颗小行星明细，超过后自动轮播。矿机名称带深色背景，并用错开的标签和引线标出位置；红色表示离线或故障，名称前的 `*` 表示其位置在当前地图之外。

主控和所有矿机需同时更新才能收到完整的射线与尺寸数据。新数据随任务存档保留；旧任务中的已知表面点仍可显示，但缺少尺寸时标为 `?`/大小未知，后续实测再补全，不把未知面积算作已测面积。清空任务也会清空对应地图记录。矿机本地矿区页仍显示自己的任务，完整探索地图由主控绘制。

| 中文运行参数 | 主控上的行为 | 原英文命令 |
| --- | --- | --- |
| `初始化` | 立即清空主控全部旧存档和运行数据，保留自定义数据配置；取消旧任务并召回在线矿机，舰队保持暂停。不迁移旧存档，恢复失败或正在恢复时也可执行 | `init` |
| `重新扫描` / `初始化 矿机编号` | 重扫硬件；不带目标的重新扫描覆盖主控和在线矿机，带矿机编号时仅重扫该矿机。矿机仅在停靠或安全暂停/人工状态接受重扫 | `rescan` / `init ID` |
| `诊断` | 显示主控诊断 | `diagnose` |
| `诊断 矿机编号` / `诊断 全部` | 请求指定矿机/全部在线矿机详细诊断，在主控查看回报 | `diagnose ID` / `diagnose all` |
| `标定` / `标定 矿机编号` | 手动重新标定全部在线矿机/指定矿机，要求实际连接；正常部署默认自动完成 | `calibrate` / `calibrate ID` |
| `标点 ...` / `探索 半径` | 创建手动/探索任务；探索半径可省略 | `mark ...` / `survey [radius]` |
| `启动` / `继续` | 恢复舰队派工；取消旧任务尚未完成的矿机先返航接港确认 | `start` / `resume` |
| `暂停` | 保留任务，全部矿机安全停驻或沿孔轴退钻 | `pause` |
| `返航` / `全部返航` | 全部矿机结束本趟并返航，已连接矿机保持停靠 | `return` / `return-all` |
| `交还控制` | 全部在线矿机解除推力、陀螺覆盖，交还人工控制 | `release` |
| `启动 矿机编号` / `继续 矿机编号` | 仅恢复指定矿机；主控原本暂停时不会顺带启动其它已登记矿机 | `start ID` / `resume ID` |
| `暂停 矿机编号` / `返航 矿机编号` / `交还控制 矿机编号` | 只操作指定矿机；保留单机停止状态，直到显式启动/继续 | `pause ID` / `return ID` / `release ID` |
| `清空任务` | 清空采矿/探索任务与矿区，安全退钻返航，保留未知空间占用 | `clear-tasks` |
| `清理离线矿机` | 清除离线注册名单与缓存，保留任务及未知空间占用 | `clear-offline` |
| `页面 舰队` / `页面 矿机` / `页面 矿区` / `页面 诊断` / `页面 配置` | 切换主控管理的屏幕页面类型，也接受数字 0 至 4 | `page fleet/miner/map/diagnostics/config` |
| `页面 下一页` / `页面 上一页` | 切换页面类型 | `page next` / `page prev` |
| `页面 +` / `页面 -` | 切换列表、未绑定单机、矿区或参数子页 | `page +` / `page -` |
| `页面 停止` / `页面 播放` / `页面 自动` | 暂停轮播、启用轮播、恢复各屏自身配置 | `page stop` / `page play` / `page auto` |

表中的“矿机编号”要替换为该机配置的实际编号，例如在主控依次运行 `诊断 深空工业1号`、`返航 深空工业1号`。编号包含空格时，动词后的剩余文本作为完整编号，也可加双引号。上述单机操作均接受“全部”或 `all`/`*` 指定在线矿机；不向离线矿机排队发送一次性维护操作，离线安全占用继续保留。原矿机端英文命令仍然可用，中文版也可直接使用中文。

暂停和交还控制不会被自动初始化或标定撤销。返航指令停止采矿，但保留接港导航；返航或对接期间重新编译后，矿机会自动重新获取母舰位姿和许可再接港，无需重复下令。完成维修或人工接应后，在主控运行 `继续 矿机编号`；人工仍在驾驶时，脚本不会夺取驾驶权。`诊断 全部` 的详细回包可能依次更新主控输出；定位单台故障时使用定向诊断最清楚。

要清理改名后留下的旧矿机条目，等待主控初始化或当前格式存档恢复完成，并让需要保留的矿机重新显示在线，然后在**舰队主控编程块的运行参数**中输入 `清理离线矿机`，点击运行一次。它采用与屏幕相同的离线判断：超过 `[显示] 离线判定秒数` 未收到遥测，默认超过 5 秒；恰好 5 秒仍在线。命令只删除当时离线的注册名单和相关缓存，不修改在线矿机、当前任务或运行开关。恢复期间不会执行该命令。

普通失联矿机的任务归属、未知孔道占用或泊位分配会继续保留；清理不会挪动在线矿机的等待点，也不复用尚未确认腾空的等待槽位。已分配且尚未结束的任务总数仍限制为 16：保留的未知任务同样计入，达到上限时新矿机可以登记，但需要等待已有任务归属得到确认和释放后才能派工。原矿机后来恢复有效遥测时会重新登记；`清理离线矿机` 不是永久拉黑，也不执行 `清空任务`。

矿机更换编程块后，若仍使用原连接器，主控可确认同一矿机并更新通信地址。整个矿机重建后也可沿用原编号，但需原登记超过 `离线判定秒数` 未更新、原编号没有采矿任务或孔道占用，且新矿机没有任务、正在返航或等候。满足后主控把泊位分配发给新矿机，无需先清空整个舰队。仍有旧采矿任务或未知占用时保留保护，不会交给替换矿机继续钻采；原矿机仍在线时，同编号的第二台矿机继续被拒绝。

对于改名后的已停靠矿机，主控会核实：新旧 ID 来自同一个非零编程块地址、新 ID 当前在线、主控连接器实际连接这台矿机。三项都满足时，才释放旧 ID 的任务归属、孔道和泊位占用，避免改名后卡住调度；已有任务进度保留，后续可重新派发。先清旧名单、随后新 ID 才登记的情况也会在真实接港后处理。仅有相同名字、连接状态上报或过期遥测均不能触发这个处理，标定与身份存档仍不自动合并。

舰队身份由矿机配置的 `[系统] 编号`（旧键为 `[System] Id`）决定，修改编程块方块名称不会改变身份。需要修改编号时，应先停靠并确认原任务与通道已安全处理，再修改配置、重新编译，按新身份重新登记。原 ID 的存档不匹配时，不会自动迁移原来的标定或任务状态；系统也不会自动把新旧 ID 合并。解决身份存档问题并初始化成功后，真实接港会自动重新标定。新身份正常上线后，可在主控运行 `清理离线矿机` 清理已离线的旧条目。

如果旧名单已占满 16 个注册名额，新 ID 暂时无法上线，可先等旧 ID 显示离线，运行 `清理离线矿机` 腾出名额；新 ID 后续上报遥测时会再次尝试登记。旧身份仍有未知占用时，系统会保留原编程块地址，防止另一台矿机复用相同 ID 后冒领旧任务或释放旧通道。

要放弃当前矿区并重新规划，先等待初始化或当前格式存档恢复完成，再在**舰队主控编程块的运行参数**中输入 `清空任务`，点击运行一次。恢复期间不会执行此命令；需先读完原存档，才能保留未知矿机和泊位分配。它是一次性命令，不是需要写进配置的开机清空开关；正常重新编译或载入不会再次清除后来创建的任务。此操作删除当前任务、采样进度和矿区，不能通过 `继续` 恢复。

正在孔内的矿机保留退出所需的孔轴和位置，关闭钻头后原轴退钻、返航；进出港中的矿机继续按安全通道处理，停靠矿机继续卸货和补能。人工接管仍优先，清空命令不会夺取驾驶权。失联矿机及尚未离开的孔道、泊位通道仍保留占用，不能因为任务列表清空就将相同空间立即派给别的矿机；取消重试、晚到旧任务或重新编译也不能使被清除的任务复活。

清空后，在主控依次运行新的 `探索 半径` 或 `标点 ...`，然后运行 `启动`。取消按矿机逐台确认：必须收到该机的新鲜取消确认，并核实它已实际连接母舰，才允许它领取新任务。已经确认的矿机可在载荷、能源、泊位分配及母舰运动条件满足后先行出港，为其他返航矿机腾出泊位，不要求所有矿机同时停靠。失联矿机需重新联机并回港确认；它的未知占用继续保留，其他矿机只能领取不冲突的任务。返航期间重新编译会自动重新申请接港；主动暂停或人工接管的矿机，在主控运行 `继续 矿机编号` 恢复；不需要逐台进入矿机编程块。若只是暂时回港并打算续挖原任务，应使用 `全部返航`。

## 看门狗、异常与恢复

屏幕提示“所用指令超过 50000 个限值”表示**一次执行的计算量超限**，不是日志、任务数或脚本文本容量已满。运行时指令计数由游戏管理，脚本没有清零接口；正常结束当前帧后，下一次执行会获得新的预算。系统通过检查剩余预算、分批处理后台工作来提前让出执行；清理仅针对可重新生成的临时显示数据，不删除配置、采矿任务、进尺、占用许可或完整存档。

若已经出现截图中的“脚本执行终止”，当前业务脚本已无法继续执行自动清理。需要替换为修复后的对应角色脚本并**重新编译**；仅清空屏幕、运行 `初始化` 或反复点击运行不能恢复已终止的实例。这与 [Keen 官方公开的编程块终止处理](https://github.com/KeenSoftwareHouse/SpaceEngineers/blob/master/Sources/Sandbox.Game/Game/Entities/Blocks/MyProgrammableBlock.cs) 和 [只读运行时计数接口](https://github.com/KeenSoftwareHouse/SpaceEngineers/blob/master/Sources/Sandbox.Common/ModAPI/Ingame/IMyGridProgramRuntimeInfo.cs) 一致。两份链接是官方历史源码；当前游戏中的指令峰值仍需实测。

业务脚本因异常、用户停用或电源中断而完全停止后，无法继续执行自身清理代码。可在矿机同一刚性网格安装独立看门狗；它在心跳中断后关闭钻头、清除推进器/陀螺覆盖并恢复阻尼，故障锁定后需要明确握手。看门狗自己同样需要供电和运行机会，不能修复缺失推进器或抵消不足的推力。

粘贴安全看门狗脚本，在其 `[系统]` 中配置 `编号=矿机01看门狗`、相同“舰队编号”，并填写 `[看门狗] 业务编程块编号=矿机01`、`超时秒数=3`；矿机配置 `[看门狗] 启用=是`、`编号=矿机01看门狗`。业务脚本运行后，在独立看门狗执行 `布防`，再在主控执行 `继续 矿机01`。看门狗只接受同刚性网格业务编程块的心跳；无新鲜心跳不能布防。可用 `触发保护` 手动触发清理。业务脚本重启后必须重新布防，恢复存档不会自动重新布防。

采矿业务脚本在正常运行中检测人工接管、关键硬件损坏、无进展、能源不足及失联。孔内优先沿原轴倒退，不先转头横穿未开挖矿体。失联矿机占用保持为未知状态，主控不把其孔道直接分配给另一台矿机。

`Storage` 保存任务、孔深、标定、能耗学习和充电锁存等状态。重新编译/载入后重新确认硬件、实际连接、母舰信息和许可，才恢复动作。改变矿机“编号”或换成另一种脚本会使原存档不匹配；内部仍保留脚本类型以检查存档归属，这不是配置参数。不要在未确认实际飞船位置之前通过编辑存档清除占用。

主控按独立记录分帧生成任务检查点，完成后才替换 `Storage`；保存回调保留最近完整检查点。恢复同样分批读取记录，恢复完成前暂停调度和任务执行，避免一次解析整个大型 INI 导致再次超限。正在保存期间的任务结果和占用会补写，重载后所有矿机先视为遥测过期，已有连接器分配保留，但旧令牌失效。分配记录只保存连接器、矿机、进出港方向及起始距离等必要信息，兼容旧存档，不再保存整条航道的几何数据。独立标点请求还保留最近 128 个回执，避免重发导致重复创建矿区。

在**舰队主控编程块**运行不带目标的 `初始化`（英文 `init`），立即删除全部历史 `Storage` 和内存中的任务、进尺、矿区、扫描/发现记录、矿机名单、占用许可、等待队列、消息重试和事件缓存；保留 `CustomData` 配置并重新读取硬件。命令在存档恢复中、恢复失败或旧档过大时也优先生效，不解析、不迁移旧数据。清空后即写入新的空状态标记，立即保存或重新编译也不会恢复旧任务。初始化完成后保持暂停，重新创建 `探索` 或 `标点` 任务，再运行 `启动`。

本版已删除旧 INI 主控存档迁移。普通重新编译/载入只恢复当前记录格式；遇到旧格式或损坏存档会暂停并提示，直到在主控运行 `初始化` 清空。无需删除自定义数据，也无需修改编号。需要保留当前格式数据时，修复后重新编译；`初始化` 的含义是清空，不能用于无损重试。

主控和矿机脚本需一起更新，可选标点终端也使用本版。重置消息使在线矿机取消旧任务、关钻并重新申请返航许可；孔内保留退出所需的孔道数据直到安全退钻，人工接管保持优先，已连接矿机保持连接。每次重置使用新的任务批次，迟到的旧派工、扫描结果和许可不能恢复已清空的数据；离线矿机重连后会收到新批次并取消旧任务。在线矿机收到新遥测后重新进入名单属于正常登记，不是恢复旧存档。矿机侧的标定、能源学习和硬件配置保留。

三个清理命令的范围不同：`初始化` 清空主控全部旧数据；`清空任务` 保留矿机名单及尚未确认撤离的空间占用；`清理离线矿机` 只删除离线名单与缓存。普通硬件更新用 `重新扫描`。矿机侧原 `初始化` 和主控定向 `初始化 矿机编号` 仍用于硬件重扫。

| 现象 | 排查方向 |
| --- | --- |
| 初始化失败 | 检查 `CustomData` INI 语法、编号及数值是否合法；修正后重新编译。主控运行 `初始化` 会清空全部旧存档 |
| 主控目录中的旧脚本生成“矿机”配置，或要求修改角色 | 替换本次修复后的主控脚本，新版类型由文件固定决定，旧 `角色` / `Role` 字段直接忽略，无需修改。如果编号也曾被错误版本生成或手动改变，恢复原主控编号（须与矿机配置的“主控编号”一致）后重新编译；保留原舰队编号、方块组及存档 |
| 返航中一直等待泊位，主控显示0个泊位 | 核对“泊位方块组”；新版中文版兼容“采矿泊位”和 `AMS Docks`，货仓组同样兼容。自定义名称须精确匹配，连接器须属于母舰刚性网格。主控与矿机一起更新并重新编译后会自动重新请求接港；仅刷新组内方块用 `重新扫描`，不要用清空存档的 `初始化` |
| 指令超过 50000 后执行终止 | 更新修复后的同角色脚本并重新编译；无需删除任务或配置。若矿机在飞行中，独立看门狗可在心跳超时后释放覆盖，恢复作业前重新检查实际位置并握手 |
| 起飞质量显示测量中 | `起飞质量=0` 正在分帧称重；等待完整本机方块与库存扫描。长时间无法完成时查看诊断中的扫描/库存问题；也可核对实际质量后设置正数手动覆盖 |
| 旧主控存档过大，初始化停止 | 更新主控与矿机脚本，在主控运行 `初始化` 清空旧存档；配置保留，随后重新创建任务并启动 |
| 存档恢复失败 | 主控可直接运行 `初始化` 删除旧数据。若需保留当前格式存档，修复身份/数据错误后重新编译；旧格式不再迁移 |
| 满电仍不出发 | 任务超航程、载荷高于离港阈值、缺任务、许可/母舰窗口不满足、推力不足；严格清矿模式还需矿物卸净 |
| 一直等待载荷下降或卸货 | 检查主控接收组、基地容量和传送系统；待卸矿物与载荷只看矿机货仓、钻头、连接器。运输库存中的冰、石头及保留补给占用仍需计入，反应堆燃料、制气机供料不要求卸空；旧版行为需同时更新主控与矿机 |
| 充电不增长 | 基地没有余电、接口供电或电池模式异常；充电等待不会由超时绕过 |
| 航行停住 | 查看联合扫描是否有尚未覆盖的区域、镜头充能、实际障碍、制动余量或近距让行；进出港另核对泊位分配。单个镜头不可用不会直接否决整组镜头 |
| 探索后飞到几个方向就停住，仍显示“前往任务入口” | 更新矿机脚本，待主控看到矿机上线并重新确认任务后运行 `继续`，保留原探索任务。旧版在观察点前几米提前转向探测方向，使剩余路程变成摄像机看不到的侧向移动；新版先到点停稳再转向扫描。入口导航会显示距离、速度、姿态误差与实际扫描原因，不再只保留旧状态文字 |
| 探索完成一次就返航 | 同时更新主控和矿机。新版自动任务在同一矿区连续续派；查看是否触发载荷、能源、通信或区域结束条件 |
| 小行星就在前方，却显示“三次靠泊失败” | 这是此前靠泊故障，故障状态不会扫描。新版保留最后失败原因，允许其它不冲突矿机作业；处理原因后从主控 `继续 矿机编号`。正常探索导航中的表面命中会自动提交试钻 |
| 点击返航后，两台外出的矿机报“三次靠泊失败 / 对齐超时 / 扫描区域暂无可用视线” | 旧版沿接口轴线接近时提前使用最终对接姿态，单前向摄像机看不到返航方向。更新主控及所有矿机后，在主控执行 `全部返航`；新版先朝行进方向到入口，再同步接口姿态，正常轴向贴合免扫描，近距侧移需扫描。入口前超时会回到等候并申请释放许可，主控核实停稳及位置后放行，不累计为靠泊失败；旧故障重新返航会重置尝试计数，重复返航不重置正在执行的对接尝试 |
| 多个空泊位仍无人进港 | 同时更新主控和矿机，检查真实连接器占用与当前分配。空闲连接器收到请求即分配，不等待主控运动窗口；矿机端仍检查实际运动条件。不同连接器可同时进出港，实际近距让行会显示对象，不必等待全队回港 |
| 横排泊位的等待矿机却排成竖列 | 更新主控；等待点按实际泊位位置及开口方向生成，连接器自身滚转只影响对接姿态。核对“泊位方块组”是否包含全部实际泊位 |
| 飞行时反复摆头 | 先在主控运行 `交还控制 矿机编号`，在安全停靠后更新矿机业务脚本；旧版陀螺自身 X 轴输出符号与当前游戏 PB 接口不符，已修正，并覆盖不同安装朝向。在主控运行 `诊断 矿机编号` 查看姿态误差，检查是否还有其他编程块或控制系统同时操作陀螺；不建议通过扩大坐标容差掩盖方向错误 |
| 一直卡在离港 | 同时更新矿机与舰队主控脚本，查看姿态、扫描、推力及近距让行原因。不同连接器的未来航段相交不再阻止分配；确认摄像机能看见连接器向外的出港方向，后退离港时不能只装朝钻头方向的相机。主控保留连接器分配，待矿机完成离港并确认脱离后释放 |
| 进港等候，主控已显示本机对接 | 主控已分配连接器，矿机核对当前分配与遥测后直接前往接口前方。主控运行 `诊断 矿机编号` 查看独立“泊位分配”和实际飞控原因；未收到分配时继续使用等待点，不能把主控显示当成矿机已收到确认 |
| 重载后一直等候主控泊位分配 | 同时更新主控和矿机并重新编译，保留现有配置与存档。旧分配需新鲜请求重新确认；原泊位可用时可续发，远处等候且原泊位不可用时可改派。同一泊位的未知分配继续保留；主控暂停不妨碍进港，无需执行 `初始化` |
| 重建后同编号矿机停在“等待泊位与外部等候点” | 旧版登记可能仍指向已删除的编程块，分配发送到了旧地址。更新主控后，旧登记超出离线时限、没有旧采矿占用、替换矿机无任务且返航或等候时，会自动重新登记并接收泊位；仍在线的同编号矿机需要使用不同编号 |
| 泊位对齐或进港对接不动 | 主控运行 `诊断 矿机编号`，查看目标距离、相对速度、姿态误差、接口横向偏移、角速度差及近距让行对象。前往引导点和执行侧移时查看扫描原因；正常轴向贴合免扫描。持续60秒无进展会保留具体原因并退避 |
| 接口前十几米反复显示“等待船体包络扫描 / 沿预约通道轴线接近” | 更新矿机脚本，随后从主控运行 `返航 矿机编号`。正常轴向贴合免扫描；入口前导航或近距冲突触发的侧移仍需摄像机净空，结合当前状态和让行对象判断 |
| 到2.8米附近停住，姿态与偏移接近零 | 更新矿机脚本并从主控运行 `返航 矿机编号`。末端稳定窗口加入退出容差，避免角速度差轻微越过0.1°/s就反复刹停。诊断中的指令速度为0表示仍在调整或同步；指令速度非零而实际速度持续接近0时，应核对推进器实际输出、动力和船体接触情况 |
| 到接口附近又向外飞，或30多米就以0.1m/s挪动 | 更新矿机脚本并从主控运行 `返航 矿机编号`。有效分配下直接接近接口；若显示近距让行，完成避让后继续。已标定的 `最终接近速度` 只用于最后1米，最后3米仍确认姿态稳定；正常轴向贴合免扫描，无需重新手动标定 |
| 对接反复退出 | 母舰加速/旋转、遥测过期、泊位阻塞、连接器几何/钻尖标定错误 |
| 已被连接器吸住，仍显示进港对接 | 更新矿机脚本；新版在连接器报告可连接时直接锁定，成功后立即上报连接状态，随后按实际需求显示卸货、充能或待命，不再被姿态、速度或稳定计时拦住 |
| 自动探索未检出 | 可见表面扫描不代表地下矿床；检查试钻深度、采样有效性与目标矿种配置 |
| 旧矿机失联后任务不派出 | 保守保留未知占用；先找到失联矿机并安全回收，不能仅等待超时 |
| 改名后大屏保留旧矿机 | 身份取自 `[系统] 编号`；新身份上线、旧条目显示离线后，在主控运行 `清理离线矿机`。只清名单，旧任务和未知通道占用仍保留 |

旧版“等待许可”状态现称“进港等候”，包含前往等待点、等候泊位分配和姿态速度同步。主控的“泊位分配：某矿机 对接”表示连接器已分配给它，不证明它已收到并核对当前分配。矿机诊断分别显示“采矿任务确认”和“泊位分配”：`清空任务` 后，返航矿机的采矿任务确认可以为否，不阻止使用已分配连接器对接；取消确认会在真实接港后完成。

需要人工接应时，在主控运行 `交还控制 矿机编号`，人工连接到主控受管泊位，然后在主控运行 `继续 矿机编号`。这会明确结束人工接管并处理取消任务的接港确认；仅连接或自动标定不会擅自结束人工控制。若要全舰队恢复，在主控运行 `启动`。更新脚本或加装摄像机后的验证在安全停靠状态进行。

## 构建、测试与开发

需要 .NET SDK 9 或更新版本、.NET Framework 4.8 编译目标，以及可从 PATH 调用的 PowerShell 7（`pwsh`，用于语言资源校验与生成）。当前固定使用 MDK2 `PbAnalyzers 2.2.0`、`PbPackager 2.2.11`。NuGet 游戏 API 引用来自已有 ScriptingHelper 包，所以无需为本仓库填写本机游戏安装目录；这仍需要在目标游戏版本编译检查兼容性。[MDK2 官方安装文档](https://malforge.github.io/spaceengineers/mdk2/Manual-Installation.html)

```powershell
# 默认：校验资源、生成中英各四个角色、校验打包文本、分别运行两种语言的测试
./build.ps1

# 仅打包开发中的代码，最终验收不使用该参数跳过测试
./build.ps1 -SkipTests

# IDE/单工程默认生成中文；完整交付使用上面的 build.ps1 同时生成两套
dotnet build AutoMiningFleet/AutoMiningFleet.csproj -c Release
# 单独调试英文版
dotnet build AutoMiningFleet/AutoMiningFleet.csproj -c Release -p:ScriptLanguage=en-US
```

工程按角色选择源码并定义 `MINER/FLEET/MARKER/WATCHDOG` 符号；每个项目有独立的 `obj` 目录。共享模块包括核心数据、INI 配置、版本化 IGC 协议、存储和显示。矿机额外包含飞控、硬件、资源和状态机；主控额外包含规划、调度和标点。源码限制 C# 6，禁用隐式 using 和 Nullable，目标为 x64。

参数页只编译当前脚本角色需要的配置行，通用 INI 读写复用公共函数；英文提示采用适合屏幕阅读的简短表达，以控制新增舰队功能后的导出长度。

MDK2 将多个 `partial Program` 源文件压缩并分别导出到 `dist/zh-CN` 和 `dist/en-US`。`build.ps1` 会拒绝打包失败、缺失/过期产物、语言/品牌不符、超过编程块 100000 字符限制或残留外部 Helper/远控航点导航的产物；还会使用游戏默认命名空间对八份导出文本逐一再次编译，防止项目内有效的 `using` 被打包移除后造成粘贴失败。随后运行 `tools/Verify-PackedRole.cs`，从已压缩产物实际执行脚本类型选择、缺省配置、本地化模板和已有配置，确认模板不再生成角色字段、旧角色字段不能覆盖编译类型；实际类型与导出工程不符就终止构建，不发布成功清单。该检查器只在开发机运行，不写入游戏脚本。两种语言的逻辑与界面测试分别记录在 `TestResults/zh-CN.trx` 和 `TestResults/en-US.trx`。`dist` 是生成物，修改后重新构建，不手改压缩脚本。测试覆盖细项及实机通过记录见 [验收文档](docs/VALIDATION.md)。

完整探索绘图仅编入主控；共享 `Data` 包装重复的引擎类型调用，局部变量只在推断类型一致时使用 `var`，不含预处理条件分支的单返回成员可使用 C# 6 表达式语法，以控制导出长度。含 `#if` 的成员必须保留全部角色分支；这些共享改动同时接受完整双语回归与八份导出角色检查。

## 可复用语言资源

文本存放在 [`Localization/`](Localization/) 的 UTF-8 JSON 文件中，按 `common`、`miner`、`fleet`、`display` 等语义分组；每组均有 `.zh-CN.json` 和 `.en-US.json`。`parameters` 保存配置节、参数名、枚举、命令和新部署默认名称的可复用映射，`fleetoperations` 保存集中控制提示。相同语义使用同一资源键，带变量的文本使用 `{0}`、`{1}` 等占位符；字面大括号写作 `{{` / `}}`。修改翻译时同时保持两份资源的键和占位符一致。

[`tools/Generate-Localization.ps1`](tools/Generate-Localization.ps1) 在构建时校验缺项、重复键、非法格式和占位符不一致，再为当前角色/语言生成独立的 C# 常量。四个角色共享资源；MDK 只保留该脚本实际使用的常量。生成文件放在 `.generated/<工程>/<语言>/`，不会覆盖资源原文，也不会把两套字典同时装入同一个游戏脚本。游戏内没有文件读取或 `ResourceManager` 依赖。

系统名称统一为 **XFE AMS**，源码工程名保留以兼容已有构建。中文配置、矿种名称和运行参数在用户输入边界转换为统一内部标识；通信协议、任务 ID 和存档标识保持一致。中文版接受原英文别名，英文版继续提供英文模板。用户自行设置的编号、真实方块名称和组名保持原文，系统不会把“主控”与 `base` 等名字当成相同身份。

两种版本可以通信，但必须统一实际舰队编号/主控编号，远端自由文本告警保留发送端语言；希望界面语言完全一致时，同一舰队使用同一种语言的全套脚本。切换语言请停靠后替换对应角色脚本并核对配置；原英文配置在中文版仍有效，现有 `CustomData` 的正文和注释不会被自动翻译或覆盖。若将中文配置切换到英文版，按对照表恢复英文节名、参数名及枚举值，保留实际 ID 和方块名称。

旧版升级流程：替换主控与每台矿机脚本、核对配置与编号，在主控运行 `初始化` 清空历史主控数据，再创建新任务。1.x 的布尔状态、远控航点以及 XFE AMS 2.0 早期 INI 主控任务存档均不迁移；1.x 矿机升级仍需先人工停靠，再完成首次自动标定。