XFE AMS 2.0
XFE AMS 是 Space Engineers 原版编程块采矿舰队系统：自主推进器与陀螺飞控、移动母舰靠泊、按实际库存循环卸货、按总储能计算电量、有限区域探索试钻、手动范围采掘，以及 LCD Sprite 仪表盘。一次构建同时生成简体中文和英文两套脚本，每套包含四个角色；编程块自带屏幕默认显示图形化配置与状态。
矿机分别可以在大气/重力环境和太空作业；单次任务不负责穿越大气层。远程控制可作为位置、速度和姿态测量方块，飞行不使用其自动驾驶航点。系统面向单一刚性网格矿机，设计上限为 16 台。
验收状态：代码编译、MDK 分析、打包及逻辑测试与游戏内验收分开记录。 本仓库不把编译成功解释为实际飞行或多人服务器验证完成。首次部署请按照 游戏内验收清单 在测试存档中完成空载、重载、靠泊和三趟循环测试。
部署结构
| 角色 | 放置位置 | 导出的可粘贴脚本 | 用途 |
|---|---|---|---|
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/ 目录。选择对应角色的完整脚本粘贴即可，无需向游戏额外安装语言资源。dist/manifest.json 记录本次八份产物的路径、语言、字符数和 SHA-256。旧构建留下的 dist/<角色工程>/ 文件不属于本次双语产物，请以清单为准。
游戏内仅粘贴各角色 script.cs 内容，不安装 DLL。工程中的 XFEExtension.SpaceEngineers.ScriptingHelper 1.0.3 仅用于开发机的游戏 API 引用；脚本不继承 IProgramBase，不依赖该包在游戏内运行。
世界设置需要允许编程块脚本，舰队之间需要可用的 IGC 无线通信。所有参与方保持相同 FleetId，每个编程块使用不同 Id，矿机与标点端的 BaseId 等于主控的 Id。只有同舰队且协议兼容的数据参与调度。
硬件与建造要求
每台矿机需要：
- 一个可测量速度、重力、质量的驾驶舱或远程控制。
- 能覆盖前后、左右、上下六个方向的推进器和至少一个陀螺。大气推进器有效推力会随环境变化，不能使用地面空载数据代替重载能力。
- 全部朝同一方向的钻头，钻出的孔道必须容纳完整船体与安全间隙。推进器、钻头、控制器和连接器都必须在编程块所在刚性网格上。
- 可对运动方向、退出方向与钻孔入口进行扫描的摄像机。扫描需要充能；没有净空证据时矿机减速或停驻。摄像机朝向和数量会直接限制航路可用性。
- 至少一块电池、足够容量的货舱、连接器、完整的传送系统。使用氢推进时需要储氢罐；库存中的冰不被当作保证可用的氢燃料。
- 能覆盖作业范围的通信设备。建议添加单独安全看门狗编程块。
不支持子网格推进器、转子/活塞钻具或子网格连接器。不可用“同构造”扫描来代替矿机所属网格，因为连接器会把母舰与矿机临时连成同一构造。矿机库存统计始终仅覆盖本刚性网格，母舰不会被算入载荷。
母舰需要一个船舶控制器、AMS Docks 连接器组、AMS Cargo 接收货舱组。组内受管方块必须在主控的刚性网格上。每个泊位的外侧预留完整的直线进出港通道，避免装饰、太阳能板或其他停泊船侵入；母舰可以移动，但只能在运动窗口满足条件时进出港。
从零启动
- 在开发机运行下方构建命令，把主控、矿机及可选角色对应脚本分别粘贴到编程块并检查编译。
- 首次编译会在空
CustomData中生成 INI 模板。修改标识和硬件配置后，在已连接状态重新编译以加载配置。现有自定义数据不会被模板覆盖。 - 在母舰创建
AMS Docks和AMS Cargo方块组。检查主控diagnose输出，确认驾驶舱、泊位和接收库存可用。 - 将矿机人工连接到目标泊位；
[Flight] DepartureMass=0（默认）会自动测量本机起飞质量，等待测量完成后运行diagnose、calibrate。也可填写正数，作为停靠时检查起飞推力的手动质量（kg），应覆盖最大预计起飞总质量。标定保存连接器与控制参考的相对位置和姿态，因此不要求连接器与控制器共线。 - 校核下节的钻头覆盖和钻尖偏移。安装看门狗时完成其配置和握手。
- 主控运行
mark ...创建手动任务，或survey创建有限探索区域；检查矿图和任务数量。 - 主控运行
start，需要时在矿机运行start/resume。矿机会等待卸空、足够能源、有效任务、许可及母舰平稳窗口，满足后自行出港。
控制器设置示例：
[System]
Role=miner
Id=miner-01
FleetId=mining
BaseId=base
[Hardware]
; 留空扫描本刚性网格。填写后必须是准确组名/方块名。
Group=
Controller=Miner Cockpit
Connector=Miner Connector
; 从钻头中心到有效钻尖的前向距离，单位 m，必须实测。
DrillTipOffset=0.5
[Flight]
; 0：停靠时自动测量本机质量。正数：手动指定最大预计起飞总质量（kg）。
DepartureMass=0
CruiseSpeed=15
RetreatSpeed=1
Clearance=1
RaysPerTick=2
[Mining]
TargetOres=Iron,Nickel,Cobalt
FootprintWidth=6
FootprintHeight=6
Overlap=0.15
HoleRadius=3
DrillSpeed=0.5
SortieDepthBudget=15
[Cargo]
ReturnFill=0.95
[Energy]
ReturnBattery=0.25
LowHydrogen=0.25
ChargeTarget=0.90
HydrogenTarget=0.90
ReserveFactor=1.5
EmergencyReserve=0.10
DockReserveSeconds=120
[Display]
Group=AMS Screens
Tag=[AMS LCD]
Page=miner
BuiltIn=true
BuiltInPage=config
Font=Debug
ScreensPerTick=2
OfflineSeconds=5
AutoPage=true
PageInterval=8
ManualHoldSeconds=20
DepartureMass=0 时，矿机保持连接，分帧统计本刚性网格的全部方块质量（含装甲）与完整库存质量，库存按世界库存倍率折算；不会为称重主动脱离母舰，也不会把母舰质量加进来。自带屏配置页显示“测量中”或自动测得的 kg 数。测量未完成、库存快照过期或质量无效时保持停靠，不能用 0 kg 绕过推力检查。卸货、补给和船体变化会触发质量更新；重新编译或重扫后重新测量。增换方块、尤其是带库存的方块后，先停靠并运行 rescan 重建硬件列表；周期称重不会自动发现新的库存方块。离港后飞控使用控制器实时报告的物理质量，手动填写的正数也不会冻结飞行中的质量。
整船库存扫描单次限制为 128 个库存、合计 512 个物品堆栈，以保留原子快照并限制执行成本。超限或扫描异常时会自动清理临时扫描结果，保留上一份完整数据，撤销卸空、采样和起飞质量许可；能源更新与退钻返航仍继续执行。修复库存规模或硬件问题后，停靠运行 rescan 解除扫描故障，再完成两次完整空库存确认。不会自动删除或抛弃真实物品。
母舰最小配置：
[System]
Role=fleet
Id=base
FleetId=mining
BaseId=base
[Fleet]
Controller=Base Cockpit
DockGroup=AMS Docks
CargoGroup=AMS Cargo
MaxMiners=16
[Mining]
TargetOres=Iron,Nickel,Cobalt
FootprintWidth=6
FootprintHeight=6
Overlap=0.15
HoleRadius=3
[Survey]
Spacing=60
ExpansionWidth=60
ExpansionHeight=60
MaxDepth=100
MaxJobs=2048
[Display]
Page=fleet
FootprintWidth、FootprintHeight 表示实际连续有效开挖覆盖，不能只填钻头外观总尺寸。HoleRadius 用于空间占用与安全互斥；必须覆盖矿机安全包络。各矿机与主控使用一致的钻孔尺寸，异形/不同尺寸矿机应分别建立舰队。先在低速浅孔中实测孔道尺寸、船体尾部和偏置钻尖，不能靠增大参数跳过硬件问题。
两种采矿模式
手动标点与完整范围采掘
主控可以直接标点；独立标点端设置 Role=marker 和正确 BaseId 后发送同样的标点请求。
mark 20 15 30
mark 20 15 30 GPS:入口:100:200:300: GPS:向内:100:200:330:
前三个数依次是入口平面宽度、高度、向内深度，单位 m。摄像机方式使用命中位置为入口中心、视线为钻入方向、摄像机上方向为入口平面的上方。GPS 方式要求入口点和向内方向点两个不同坐标；坐标可以包含 0。入口中心与任务区域会冻结在世界坐标中。
摄像机标点只接受行星或小行星表面。可通过 [Marker] Camera=准确名称 选择摄像机，ScanDistance=1000 设置扫描距离。提示摄像机充能不足时，待扫描范围恢复后重发命令。
范围被分成有重叠的平行孔，采用固定蛇形顺序。手动任务会完成规定范围和深度，遇到无目标矿段也继续；安全故障仍会使任务中止或暂停。实际开挖可能略超出几何边界，取决于钻头实际作用体积，不能用于贴近重要设施的精密切削。
自动探索、试钻与指定矿种优先
survey
survey 300
start
survey 在主控当前位置冻结一个有限区域；标点端的同名命令也使用主控当前位置。默认大气半径 300 m、太空半径 2000 m，可用参数覆盖。大气按地表采样点搜索，太空按有限观察点及方向扫描小行星。
摄像机能判断实体及表面命中，不能透视矿种。系统钻进时每 5 m 比较整船矿物库存增量，识别 TargetOres 指定的矿种，并按列表先后顺序安排已确认矿点。库存内部转运不会被算成新发现。采样时受管制气/加工/抛货会停用；如果仍存在库存损失或无法隔离，会提示采样无效并将未证实的试钻标为受阻，不会推断“这里没有矿”。
默认试钻深度为大气 60 m、太空 40 m，Survey.ProbeDepth 可显式设置。发现区的扩挖受 ExpansionWidth、ExpansionHeight、MaxDepth 和原搜索边界共同限制。连续两圈相邻孔没有目标矿增量后停止扩张。搜索完成后返航等待，不无限增加范围或深度。
Survey.BaseClearance=80 将大气观察点沿反重力方向抬高 80 m；太空首个观察点也避开母舰中心，且保持在搜索球内。搜索区域仍以创建时的世界坐标固定。按母舰体积和附近地形增大净空；不把母舰内部当作可到达的观察位置。入孔前执行中心和四周共五点检查，Mining.MaxEntryRelief=5 限制新孔入口的地表起伏；已有孔道发现其他船体占用时拒绝钻进。
请区分结果：SurveyEmpty 表示该次扫描没有表面命中；试钻未检出只表示已采样部分没有目标矿增量；“采样完成”不等于已经确定地下无矿；手动任务的“指定范围采掘完成”才表示其计划钻孔全部完成。受阻或无效采样的区域不能当作正常完成。
周转、能源与移动母舰
矿机正常流程为停靠自检、领取任务、离港、飞行、探索/采掘、沿孔轴退钻、返航、排队、对接、卸货与补能、继续任务。满载默认 95%，钻头库存堵塞、低电/低氢、返航预算不足或承载能力不足也会提前返航。保存孔位和实际进尺，卸货后可以从已开挖的孔恢复。
Mining.SortieDepthBudget=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²。
卸货包含所有受管矿物，包括石头和冰；不抛石，非矿物补给不作为待卸矿物。主控主动转移到 AMS Cargo，也允许基地传送系统抽取。矿机连续两次完整库存扫描确认待卸矿物为 0 后才完成卸货。满仓、传送不通、补能无进展时保持停靠并报告原因，没有“对接若干秒后强制出发”逻辑。
靠泊按连接器自身的位置与速度控制，并计算母舰转动导致的连接器线速度。默认许可窗口：连接器速度 ≤5 m/s，母舰角速度 ≤0.2°/s，连接器加速度 ≤0.1 m/s²；最终接近速度 ≤0.2 m/s，遥测年龄 ≤0.5 s。参数位于 [Dock]：
[Dock]
MaxBaseSpeed=5
MaxBaseAngularDeg=0.2
MaxBaseAcceleration=0.1
MaxTelemetryAge=0.5
StableSeconds=2
ApproachDistance=30
FinalSpeed=0.2
WaitingDistance=80
WaitingSpacing=20
母舰运动超限、许可失效或遥测过期时，矿机会退出接近并等待；已连接时失联不会主动脱离。默认三次靠泊失败后暂停。无法在剩余能源内追上母舰时需要母舰驾驶员减速或接应，主控不会接管母舰驾驶权。
图形屏幕与命令
编程块自身的第一个显示面（Surface 0）默认加入仪表盘，无需改名或加入方块组，优先显示 config 参数页。页面包括系统名称、角色、界面语言、状态和当前已生效的角色配置；参数分页默认自动轮播，也可使用 page + / page - 手动查看更多参数。第二个及后续显示面仅在配置了 [AMS.Screen.1] 等节时启用，避免默认在很小的键盘屏上绘制完整仪表盘。
参数页使用更大的字号和高对比度配色，按显示面的实际可见宽度排版：宽屏每页 5 项，名称和值分列；普通屏或竖屏每页 4 项，名称在上、值在下。过长的文本按当前字体实际宽度省略，保持字号，不再为塞入整段文字而缩小。完整参数仍可在编程块 CustomData 中查看。此调整针对 config 页，其他仪表盘页面保留原布局；脚本不能提高游戏显示面本身的纹理分辨率，实际中文字形和可读性仍需游戏内确认。
在编程块 CustomData 的 [Display] 中设置 BuiltInPage=miner 可让自带屏默认显示单机状态，设置 BuiltIn=false 可关闭自带屏托管。编程块自身的 [AMS.Screen] Page=... 可覆盖默认页；Enabled=false 优先关闭该显示面。配置页只读，修改 CustomData 后在停靠状态重新编译，屏幕会显示新生效的值；init 仍只负责初始化失败后的重试或运行中的重扫。
自动翻页默认开启：每个屏幕独立计时，每 8 秒循环切换当前页面类型的子页，包括参数分页、舰队列表、未绑定的矿机列表和不同矿区；不会自动从参数页切到舰队等其它页面类型。设置了 Miner=miner-01 的单机屏始终显示该矿机，只有一页时保持当前内容。屏幕底部用进度条和圆点标示轮播进度与当前子页。
在 [Display] 中可设置 AutoPage=false 关闭轮播，PageInterval=8 调整停留秒数（2～120），ManualHoldSeconds=20 调整手动操作后的暂停秒数（0～300）。每个 [AMS.Screen] 或 [AMS.Screen.N] 节可用同名字段覆盖全局值。手动切页后，默认暂停 20 秒，再开始完整的 8 秒停留计时，下一次自动翻页约在操作后 28 秒发生；page stop 可持续停住查看，page play 从当前子页重新计时。这两个命令只改变本次运行状态，重新编译后按配置恢复；永久关闭使用 AutoPage=false。轮播沿用屏幕绘制调度，不改变飞控更新频率。
已有部署更新显示效果时，先确认矿机停靠，再用重新生成的同语言、同角色 script.cs 替换编程块脚本并编译。运行 page config 查看大字参数页，page + / page - 翻页，page auto 恢复各屏自己的页面绑定、首个子页及配置中的轮播设置。现有 CustomData 无需添加新字段，缺省即启用轮播。
将 LCD/驾驶舱加入本机 AMS Screens 组，或在方块名加入 [AMS LCD]。同一屏只能由一个脚本负责。屏幕 CustomData 示例：
[AMS.Screen]
Page=fleet
; 单机页可绑定其它矿机；留空在矿机上默认显示自己。
Miner=
; 可选：覆盖本编程块 [Display] 的轮播设置。
AutoPage=true
PageInterval=8
ManualHoldSeconds=20
; 驾驶舱的第二个面；第三个面使用 AMS.Screen.2，以此类推。
[AMS.Screen.1]
Page=miner
Miner=miner-01
Enabled=true
| 页面 | 数据 |
|---|---|
fleet |
在线/总数、停靠和等待数量、任务汇总、每台电量/氢量/载荷、状态和首条告警；每页 7 台 |
miner |
单机状态、能源与载荷条、MWh、净功率、估计续航、速度、重力、母舰距离、推力余量、孔深、任务号、原因/矿种摘要 |
map |
按矿区入口平面投影的孔位与矿机位置、范围尺度、进度和采样状态；不同矿区分别切换 |
diagnostics |
指令预算、运行耗时、角色自检、硬件/泊位信息和最近事件 |
config |
角色、语言、运行状态、已生效配置；按角色显示飞行/钻采/能源阈值、舰队/泊位、标点或看门狗参数 |
离线数据保留并标注“离线”/OFFLINE 和数据年龄，不把最后已知状态当成实时状态。参数页适配屏幕可见宽度，其他页面按原有比例居中缩放。默认每 0.5 s 最多绘制 2 个屏幕，多个屏幕轮转以保留飞控预算；设置 ScreensPerTick 可调整吞吐。矿图单帧最多绘制 400 个孔位，统计仍覆盖当前矿区全部任务。图形按钮不是触摸控件，使用快捷栏、按钮板或编程块参数操作。字体使用 [Display] Font=Debug；目标游戏版本的中文字体覆盖及小屏排版仍需要游戏内验收。
| 命令 | 使用位置与行为 |
|---|---|
init |
初始化失败后重新初始化；运行中只重扫方块，配置修改需停靠后重新编译 |
diagnose / rescan |
输出诊断 / 重新发现受管硬件 |
calibrate |
矿机人工连接后进行几何标定 |
mark ... / survey [radius] |
主控或标点端创建手动/探索任务 |
start / resume |
主控恢复派工；矿机从安全核验开始恢复 |
pause |
保留任务并安全停驻或退钻 |
return |
单台矿机结束本趟并返航 |
return-all |
主控召回全部登记矿机 |
release |
单台矿机释放推进器和陀螺覆盖，交还人工控制 |
page fleet/miner/map/diagnostics/config |
强制本编程块所有受管屏幕显示指定页面（也可用数字 0 至 4） |
page next / page prev |
切换页面类型 |
page + / page - |
切换舰队列表页、未绑定的单机、矿区或参数分页；保留固定矿机绑定 |
page stop |
暂停所有受管屏幕的轮播，停留在当前内容 |
page play |
启用所有受管屏幕的轮播，从当前子页重新开始停留计时；不修改 INI |
page auto |
恢复各屏幕自身 INI 页面绑定、首个子页及配置中的轮播设置 |
看门狗、异常与恢复
屏幕提示“所用指令超过 50000 个限值”表示一次执行的计算量超限，不是日志、任务数或脚本文本容量已满。运行时指令计数由游戏管理，脚本没有清零接口；正常结束当前帧后，下一次执行会获得新的预算。系统通过检查剩余预算、分批处理后台工作来提前让出执行；清理仅针对可重新生成的临时显示数据，不删除配置、采矿任务、进尺、占用许可或完整存档。
若已经出现截图中的“脚本执行终止”，当前业务脚本已无法继续执行自动清理。需要替换为修复后的对应角色脚本并重新编译；仅清空屏幕、运行 init 或反复点击运行不能恢复已终止的实例。这与 Keen 官方公开的编程块终止处理 和 只读运行时计数接口 一致。两份链接是官方历史源码；当前游戏中的指令峰值仍需实测。
业务脚本因异常、用户停用或电源中断而完全停止后，无法继续执行自身清理代码。可在矿机同一刚性网格安装独立看门狗；它在心跳中断后关闭钻头、清除推进器/陀螺覆盖并恢复阻尼，故障锁定后需要明确握手。看门狗自己同样需要供电和运行机会，不能修复缺失推进器或抵消不足的推力。
看门狗的 System.Role=watchdog、Id=miner-01-watchdog、相同 FleetId，并填写 [Watchdog] BusinessId=miner-01、Timeout=3；矿机配置 [Watchdog] Enabled=true、Id=miner-01-watchdog。业务脚本运行后，在看门狗执行 arm，再在矿机执行 resume。看门狗只接受同刚性网格业务编程块的心跳；无新鲜心跳不能布防。可用 trip 手动触发清理。业务脚本重启后必须重新 arm，恢复存档不会自动重新布防。
采矿业务脚本在正常运行中检测人工接管、关键硬件损坏、无进展、能源不足及失联。孔内优先沿原轴倒退，不先转头横穿未开挖矿体。失联矿机占用保持为未知状态，主控不把其孔道直接分配给另一台矿机。
Storage 保存任务、孔深、标定、能耗学习和充电锁存等状态。重新编译/载入后重新确认硬件、实际连接、母舰信息和许可，才恢复动作。改变矿机 Id 或角色会使原存档不匹配。不要在未确认实际飞船位置之前通过编辑存档清除占用。
主控按独立记录分帧生成任务检查点，完成后才替换 Storage；保存回调保留最近完整检查点。恢复同样分批读取记录，恢复完成前暂停调度和任务执行，避免一次解析整个大型 INI 导致再次超限。正在保存期间的任务结果和占用会补写，重载后所有矿机先视为遥测过期，已有航道占用保留，但旧许可令牌失效。独立标点请求还保留最近 128 个回执，避免重发导致重复创建矿区。
XFE AMS 2.0 早期主控使用单份 INI 保存任务。更新主控脚本并重新编译后，系统会自动分帧迁移旧 INI 存档，包含超过 32768 字符的大型旧档；迁移期间暂停调度，屏幕显示恢复状态。旧任务、实际进尺、矿区、发现记录和未知占用保留，只有新版完整检查点生成成功后才替换原 Storage。迁移完成后主控保持暂停，请核对矿机实际位置和在线状态，再在主控执行 start；不必重新运行 survey 或创建重复任务。
若仍看到旧版本的“旧格式存档过大”提示，请替换舰队主控脚本并重新编译。这个问题属于编程块内部的 Storage，不是 CustomData 配置错误；清空自定义数据不能解决。若迁移过程中发现存档损坏或角色/ID 不匹配，系统会保留原文并给出存档错误，不自动删档。重新编译或运行 init 可以在原因修复后重试；不要通过改变 ID 绕过已有任务的占用。建议升级前备份世界存档。
| 现象 | 排查方向 |
|---|---|
| 初始化失败 | CustomData INI 语法、Role 是否与粘贴脚本匹配、数值是否合法；按错误字段修正后运行 init |
| 指令超过 50000 后执行终止 | 更新修复后的同角色脚本并重新编译；无需删除任务或配置。若矿机在飞行中，独立看门狗可在心跳超时后释放覆盖，恢复作业前重新检查实际位置并握手 |
| 起飞质量显示测量中 | DepartureMass=0 正在分帧称重；等待完整本机方块与库存扫描。长时间无法完成时查看诊断中的扫描/库存问题；也可核对实际质量后设置正数手动覆盖 |
| 旧主控存档过大，初始化停止 | 替换新版舰队主控脚本并重新编译，等待自动分帧迁移；无需清空 CustomData 或任务。迁移完成后确认矿机状态，再执行 start |
| 存档恢复失败 | 按具体存档错误核对角色、ID 和数据完整性；原 Storage 保留。不要用清空配置、改 ID 或删除占用来绕过错误 |
| 满电仍不出发 | 任务超航程、未卸净、缺任务、许可/母舰窗口不满足、推力不足；查看单机原因 |
| 一直等待卸货 | 主控接收组是否正确、基地是否满仓、传送系统/连接器是否可输送；检查钻头和连接器残留的冰或石头 |
| 充电不增长 | 基地没有余电、接口供电或电池模式异常；充电等待不会由超时绕过 |
| 航行停住 | 摄像机扫描距离/角度不足、障碍、制动余量不足或未知通道；查看诊断后改善硬件/航路 |
| 对接反复退出 | 母舰加速/旋转、遥测过期、泊位阻塞、连接器几何/钻尖标定错误 |
| 自动探索未检出 | 可见表面扫描不代表地下矿床；检查试钻深度、采样有效性与目标矿种配置 |
| 旧矿机失联后任务不派出 | 保守保留未知占用；先找到失联矿机并安全回收，不能仅等待超时 |
构建、测试与开发
需要 .NET SDK 9 或更新版本、.NET Framework 4.8 编译目标，以及可从 PATH 调用的 PowerShell 7（pwsh，用于语言资源校验与生成）。当前固定使用 MDK2 PbAnalyzers 2.2.0、PbPackager 2.2.11。NuGet 游戏 API 引用来自已有 ScriptingHelper 包，所以无需为本仓库填写本机游戏安装目录；这仍需要在目标游戏版本编译检查兼容性。MDK2 官方安装文档
# 默认：校验资源、生成中英各四个角色、校验打包文本、分别运行两种语言的测试
./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。
MDK2 将多个 partial Program 源文件压缩并分别导出到 dist/zh-CN 和 dist/en-US。build.ps1 会拒绝打包失败、缺失/过期产物、语言/品牌不符、超过编程块 100000 字符限制或残留外部 Helper/远控航点导航的产物；还会使用游戏默认命名空间对八份导出文本逐一再次编译，防止项目内有效的 using 被打包移除后造成粘贴失败。两种语言的逻辑与界面测试分别记录在 TestResults/zh-CN.trx 和 TestResults/en-US.trx。dist 是生成物，修改后重新构建，不手改压缩脚本。测试覆盖细项及实机通过记录见 验收文档。
可复用语言资源
文本存放在 Localization/ 的 UTF-8 JSON 文件中，按 common、miner、fleet、display 分组；每组均有 .zh-CN.json 和 .en-US.json。相同语义使用同一资源键，带变量的文本使用 {0}、{1} 等占位符；字面大括号写作 {{ / }}。修改翻译时同时保持两份资源的键和占位符一致。
tools/Generate-Localization.ps1 在构建时校验缺项、重复键、非法格式和占位符不一致，再为当前角色/语言生成独立的 C# 常量。四个角色共享资源；MDK 只保留该脚本实际使用的常量。生成文件放在 .generated/<工程>/<语言>/，不会覆盖资源原文，也不会把两套字典同时装入同一个游戏脚本。游戏内没有文件读取或 ResourceManager 依赖。
系统名称统一为 XFE AMS，源码工程名保留以兼容已有构建。命令、INI 键、方块组名、矿种配置 ID（如 Iron）、任务结果标识及通信协议不随语言改变；中文只改变呈现文本。两种版本可通信，但远端发送的自由文本告警保留发送端语言；希望界面语言完全一致时，同一舰队使用同一种语言的全套脚本。切换语言请停靠后替换对应角色脚本；现有 CustomData 的注释不会被自动翻译或覆盖。
1.x 旧版升级流程：召回全部矿机、人工确认停靠、保存测试存档、替换主控与每台矿机脚本、更新配置与 ID、重新标定、重新创建任务。1.x 的布尔状态及远控航点不直接迁移为空中恢复点；XFE AMS 2.0 早期 INI 任务存档使用上文的自动迁移流程，保留原任务。