dsh-maa-cli

一个 DeepSeek Harness 插件：使用自然语言 "一键" 游玩《明日方舟》!

为什么选择 dsh-maa-cli？

[!TIP] MAA 负责稳定执行，dsh-maa-cli 让它能听懂目标、编译策略、记住偏好，并根据真实反馈继续推进。

• 边运行，边对话：MAA 执行期间仍可用自然语言追加受支持的运行时指令、改变停止条件和查询可验证的进度。
• 告诉 Agent 目标，而不是操作步骤：只需描述想完成的游戏目标，Agent 会基于真实 Box、仓库与资源约束规划任务并逐步推进。
• 把自然语言变成真正的游戏策略：招募、购物和战斗偏好会被编译为 MAA 实际读取的资源配置或 Copilot 作业，而不是只保存一段备注。
• 越用越懂你的偏好：不同肉鸽主题的完整参数和已验证的原子策略都能持久化复用，减少每次重复设置。
• 不只是执行，还能判断与纠错：插件会根据 MaaCore 回调、日志、检查点和 ADB 状态诊断异常、在可证明安全时恢复，并严格区分“任务已执行”与“目标已达成”。
• 日常操作零模型调用：只输入 /maa fight、/maa infrast、/maa rouge 等项目名即可打开参数面板；修改并确认后才执行，全程不进入模型上下文。
• 确认与执行分离：自然语言需求只消耗一次模型调用生成计划，执行由本地确认按钮触发，确认阶段不再调用模型。
• 不需要预装 MAA：插件自带私有运行时，首次真正执行任务时自动下载 maa-cli + MaaCore + 资源，与系统里已有的 MAA 完全隔离。
• 运行中可交互：任务在后台执行时仍可通过面板自然语言输入查询真实进度、立即停止，或设置“本局结束后 / 再打 N 局 / 下一处或指定层 Boss 前停止”；只控制本插件当前任务的 maa-cli 进程树，不动游戏、模拟器或其它 MAA 实例。
• 目标驱动工作流：可以提出“完成今日任务”“培养某干员”“检查仓库并规划材料”等目标；插件读取已验证的 Box / Depot 缓存，生成受预算约束的步骤，逐步执行并在证据不足时暂停。
• 故障诊断与安全恢复：记录 MaaCore 结构化回调、任务检查点和 ADB 状态，区分已确认与推测原因；自动重试只用于尚未产生完成检查点的只读 Box / Depot 扫描。
• 按需自动更新：开始新任务前至多每 24 小时调用一次 maa-cli 官方更新；培养榜只在用户请求建议时检查。

---

目录

• 快速开始
• 本地命令（零模型调用）
• 自然语言用法
• 工具一览
• 私有运行时
• 环境变量
• 兼容性
• 故障排查
• 安全边界
• 开发
• 常见问题
• 更新日志
• 许可与致谢

---

快速开始

dsh plugin --profile desktop add dsh-maa-cli

或

dsh plugin --profile web add dsh-maa-cli

安装完成后重启 DSH Desktop，然后任选一种方式：

/maa fight              # 打开理智作战参数面板，不会立即开打
/maa update             # 选择更新干员 Box / 仓库数据
/maa setup              # 想提前下载运行时的话

第一次真正执行游戏任务时会自动准备私有运行时（约 520–630 MB，视网络通常 1–3 分钟）。任务开始前请确保模拟器已经启动；没启动时插件会直接提示「请手动启动mumu模拟器！」，不会消耗理智，计划也不会失效。

本地命令（零模型调用）

命令走 DSH 的本地命令通道，完全不产生模型调用。任务命令只负责打开面板；不点击「确认并执行 MAA」就不会操作游戏。

命令	别名	作用
/maa help	帮助、?	显示命令帮助
/maa startup	启动游戏、打开明日方舟	打开开始唤醒面板
/maa fight	flight、刷、作战	打开理智作战面板
/maa infrast	基建、基建换班	打开基建换班面板
/maa recruit	公招、自动公招	打开自动公招面板
/maa mall	credit、信用收支	打开信用收支面板
/maa award	领取奖励、领奖	打开领取奖励面板
/maa rouge	rogue、roguelike、肉鸽	打开自动肉鸽面板
/maa reclamation	生息、生息演算	打开生息演算面板
/maa update	更新数据	选择更新干员 Box / 仓库数据
/maa closedown	关闭游戏、关闭明日方舟	打开关闭游戏确认面板
/maa box	operbox、扫描干员Box	打开只更新干员 Box 的数据面板
/maa stop [RUN-… / MAA-…]	停止、停止任务、终止任务	停止本会话的任务（或仍在启动中的确认）；等进程树真正退出后才返回，只终止记录的进程树
/maa status	状态、任务状态、执行状态	面板内部使用：读取执行中的任务与最近几次执行记录
/maa setup	安装运行时、初始化	下载并配置私有运行时
/maa confirm MAA-XXXXXX [参数]	—	面板内部确认命令；通常不需要手工输入

示例：

/maa fight              # 在面板里选关卡、次数、连战倍率与资源上限
/maa infrast            # 在面板里选设施、无人机用途、心情阈值等
/maa recruit            # 在面板里选择刷新、星级、次数与加急许可
/maa mall               # 在面板里选择访问好友、购物与名单
/maa rouge              # 在面板里选择主题、模式、分队与开局干员
/maa update             # 在面板里选择 Box、仓库或两者

约定：

• 所有面板参数来自同一套服务端白名单，确认前会再次校验；非法参数不会消耗确认码。
• 参数布局和字段类型遵循 MAA 官方任务协议；可发现的主题、模式、难度、分队、干员等选项及默认值以当前实际运行的 MAA 版本和资源为准。
• 兼容旧写法（如 /maa fight 1-7 10、/maa rouge 萨米 3），但旧参数只用于预填面板，仍不会直接执行。
• 执行期间确认条只提供一个自然语言输入框，不为各项运行时能力分别放置按钮。输入“现在停止”“再打两局就停”“这次 Boss 关前停止”“取消停止要求”或“现在打到哪里了”后，由 DSH 本地解析并明确反馈是否已经应用；无法可靠执行的要求会说明原因。
• 确认之后面板不会消失：点下「确认并执行 MAA」的同时它就切换成运行控制面板，并始终带一个独立的「停止任务」按钮（启动中、执行中、刷新状态、最小化再展开、刷新页面、切换会话回来都不会丢）。面板显示「执行中 / 已完成 / 失败 / 已停止」、耗时、可靠进度与退出码，并保留通用运行时指令输入框。计时在本地完成，不会反复调用命令；记录写在主机的 runs.json 里。
• 面板右上角：「−」只负责最小化，最小化后变成「+」，点一下完整展开——参数、备注、预览、按钮、运行状态和输入框都原样保留（面板主体只是隐藏，从不卸载）；最小化状态按确认码记住，刷新页面后依然有效。展开运行面板时会读一次主机状态，所以期间自然结束的任务会如实显示为已结束。
• 确认面板的「×」= 取消并删除计划：服务端删除待确认计划并为确认码写入失效记录，之后 /maa confirm <code>、模型确认、重启 DSH 后再确认都会被明确拒绝（「已被取消，已永久失效」）。取消与确认在同一个串行队列里执行，二者同时发生时只有一个成功；如果确认先赢了，面板会切到运行面板而不是假装取消成功。
• 运行面板的「×」= 停止任务：会先弹窗确认，然后终止本次任务的进程树，等进程真正退出、记录与临时资源结算完毕后才显示「已停止」。停止失败（例如 30 秒内进程没退出）时面板保持「执行中」，显示原因，停止按钮仍可用，可以重试。MaaCore 没有可靠的暂停/继续，所以这里只有「停止」，没有伪装的暂停。
• 每个运行记录都绑定发起它的 DSH 会话与插件进程。别的会话只能看到只读的「另一个 DSH 会话的 MAA 任务执行中」，不能停止它，也不能给它追加条件；另一个仍在运行的 DSH 进程持有的任务同样不会被碰。
• 确认后的 MAA 进程由插件在后台持有，/maa confirm 会立刻返回「已开始执行（RUN-…）」而不再占着一次命令调用：这样长任务不会被命令传输的 5 分钟超时打断。运行结果、资源覆盖恢复与 runs.json 都在进程真正退出时结算。
• 有任务正在执行时，插件拒绝一切新计划与确认（maa_prepare_* 工具与 /maa confirm 都会明确报错），避免抢占模拟器和覆盖临时资源；所有 DSH 会话共享这一限制。DSH 崩溃或重启后，插件启动时只按 runs.json 记录的进程号终止残留的进程树并把记录结算为「已停止」。

运行时指令

现在支持在运行时补充指令啦!想提前结束但又不想浪费这一把?刷到一半想自己打一把boss?没问题!新增运行时指令功能,只需在插件面板上输入你的要求即可(不过目前支持的指令并不多)

确认后的 MAA 子进程不会占住 DSH 命令通道，因此执行期间仍可在对话中追加运行时指令。插件把每条指令持久化在本次 runs.json 记录中，并严格区分 received（已接收）、applied（已挂载到当前监控器）、triggered（可靠条件已发生并开始终止）、completed（触发后的 MAA 进程已结束）、not_triggered（进程先结束、条件没有发生）、cancelled 和 unsupported。新的停止条件会取消旧的尚未触发条件；临时指令不进入长期策略记忆。

局数只根据 MaaCore 的 RoguelikeSettlement 回调累加，所以“再打 N 局就停”以收到指令时的已结算局数为基准，与最初计划的 starts_count（即使仍设为 9999）无关。黑流树海楼层只接受带 floor_from_ocr: true 的 BlackFlowMapSummary；指定层 Boss 只接受精确的 StageDreadfulFoe-<层数> 预进入回调，“这次 Boss 关前停止”则接受下一条精确的 StageDreadfulFoe 或 StageDreadfulFoe-<层数> 节点回调，但不接受已经进入战斗的 ...Enter 回调。日志没有可靠字段时，状态会显示“未知”并继续等待，不按耗时或文本猜测，也不会错误停止。

MaaCore 原生的 AsstSetTaskParams 需要调用方持有同一进程内的 Assistant 句柄和 task id；本插件当前通过独立 maa-cli run 子进程执行，maa-cli 没有把这些对象暴露给 DSH。因此“接下来优先招某干员”, “让开这把我来”会明确记录为 unsupported / 未应用，不会靠运行中改资源文件冒充已经生效；请把它放到下一次任务的备注中，经预览确认后执行。

统一零模型参数面板

截图中的 MAA 主任务已全部接入同一流程：开始唤醒、理智作战、基建换班、自动公招、信用收支、领取奖励、自动肉鸽、生息演算、更新数据。输入 /maa + 项目名 后，插件在输入框上方显示对应面板；参数改动、只读回读和确认全部走本地命令通道。

面板记忆只用于零模型的 /maa 面板。 通过自然语言让模型准备的计划，确认面板显示且执行的就是计划本身的参数，不会被上次手动确认的设置覆盖。

所有带参数的 /maa 面板都使用状态目录中的 panel-memory.json 记住上一次成功确认时的完整设置：开始唤醒、理智作战、基建换班、自动公招、信用收支、领取奖励、自动肉鸽、生息演算和更新数据各自独立，包括基础参数、高级开关、多选、列表和自定义数值。打开面板、修改后取消或确认失败都不会覆盖正式记忆；记忆只用于预填，不代表自动执行授权，源石、理智药和道具消耗仍须通过原有确认与资源预算检查。

预填优先级为：本次 /maa 命令显式参数 → 当前命令（肉鸽则为当前主题）的已确认记忆 → 当前 MAA 动态能力提供的合法默认值。MAA 资源更新后会逐字段重新校验：仍有效的值继续保留，只对已失效的选项回退，不会因一个字段失效而删掉整套配置。旧版肉鸽记忆会在下次确认时自动迁移到新格式。

/maa fight
/maa recruit
/maa mall
/maa rouge
/maa reclamation
/maa update

• 基础项直接显示，高级项放在「高级设置」中；布尔项使用复选框，枚举使用下拉框，多选项使用复选框组，数量使用受范围限制的数字框。
• MAA.exe 原本带提示的设置会在对应字段下显示说明；生息演算会根据当前模式显示启动位置、存档/编队要求、所需干员、预期流程和注意事项。
• 肉鸽保留专用面板和 MAA 推荐开局；其他项目使用统一表单渲染器。
• “更新数据”对应 MAA 的 UserDataUpdateTask：可分别选择 OperBox 与 Depot，不会被误解为下载软件更新。
• 面板里的参数来自待确认计划本身（/maa peek 只读回读），打开时看到的就是将要执行的值。
• 下拉框显示值和确认时提交值使用同一套规范化规则。MAA 能力缓存刷新、主题切换或上游删除选项后，失效值会自动换成当前合法默认值；没有可靠默认值的可选项显示为“未选择”。
• 未选择的可选文本、列表和下拉项不会以空字符串写入 MaaCore；如果用户把原有值改回“未选择”，对应参数会从最终任务中删除。必填项缺失则在消费确认码前报出具体字段，不会执行任务。
• 不点确认就什么都不会执行；计划 30 分钟有效、一次性，/maa confirm MAA-XXXXXX … 也能手动执行。
• /maa peek MAA-XXXXXX 是面板用的只读命令，手工用只会打印计划的 JSON，不会执行。

干员 Box 查询

/maa box 会先打开只包含 OperBox 的确认面板；确认后才识别已拥有干员并保存到 ~/.dsh/maa-cli/operator-box.json。缓存只包含干员 ID、名称、星级、精英化、等级、潜能和扫描时间，不包含账号凭据。

扫描一次后，可以直接用自然语言询问：

我有哪些六星干员？
哪些六星还没精二？
维什戴尔多少级、几潜？
给我一份培养建议

DSH 会先调用只读的 maa_operator_box 查询缓存，不连接模拟器。没有缓存，或用户明确要求刷新时，才会准备一份需要确认的 StartUp + OperBox 扫描计划。

每次扫描完成后，插件会主动询问是否需要培养建议。用户主动询问时，DSH 会先显示上次扫描时间，并让用户选择直接使用缓存还是重新扫描；重新扫描仍需单独确认。

培养建议使用以下可审计规则：

• 这是蒂蒂，她很可爱！！！
• 杯级来自明日方舟六星干员强度投票箱最新已发布主题，按该项目原有的九等分规则归为 超大上 > 超大中 > 超大下 > 大杯 > 中杯 > 其他。这是社区投票，不是官方强度结论。
• 职业与子职业读取当前 MAA 运行时自带的 battle_data.json，不维护另一份容易过期的名单；职业内排名由同一社区总榜按职业分组得到。
• “已有可用职业覆盖”定义为该职业至少有一名精一或精二干员。没有时会提高该职业候选人在同杯级内的顺序，并明确写出职业缺口原因。
• 只推荐尚未精二、或精二但低于 60 级的已拥有六星；榜单没有收录的干员标为“其他”，不会补造评级或排名。
• 每次生成建议前只检查最新已结束主题 ID；主题未变化时直接复用 ~/.dsh/maa-cli/training-ranking.json，不重复下载完整榜单。新主题下载成功后才原子替换；检查失败则继续使用旧缓存。

自然语言用法

复杂需求仍然可以直接说，例如「先启动游戏，领取基建奖励并轮换，再刷20次 1-7，最后领取每日奖励」。

1. 模型调用一次 maa_prepare_plan，把需求整理成有顺序的步骤，写入任务文件并进入缓存。
2. DSH 输入框附近出现确认条（思考区的工具卡里也有同样的按钮）。确认条右上角「−」最小化（变成「+」，点击展开，所有内容原样保留），「×」取消并删除计划——确认码随即在服务端永久失效。从工具卡确认的任务，工具卡和确认条上都会出现「停止任务」。
3. 若填写备注，离开备注栏时会自动解析（也可点击「解析并预览备注」）：插件优先用本地规则和已启用策略记忆编译；只有语义无法确定时，才把未识别部分交给模型重新准备策略——模型会先识别主语（干员/藏品/事件名，纠正错别字）和动词（抓、拿、捞、取、选、选择、招募都按「招募」理解），改写成规范化备注后调用 maa_prepare_note，再由本地规则重新解析和编译。参数或备注变化后旧预览自动失效。
4. 备注解析成功后，面板只提示「已收到并解析【备注】」（识别细节保留在命令结果里由模型说明）。点击「确认并执行 MAA」→ 本地执行 /maa confirm <code> → 临时应用策略并运行 maa-cli；未完成备注预览时不能确认。

自然语言策略编译

需要改变肉鸽策略或战斗作业时，DSH 会调用 maa_prepare_strategy（备注场景调用 maa_prepare_note），把自由表达和多意图组合编译成 MAA 原生资源或 Copilot 作业，再沿用同一套确认码执行。它不是只保存“意图 JSON”：确认后会把策略真正写入本次执行读取的资源/作业文件。

肉鸽战术直接写进 roguelike/<主题>/autopilot/<关卡>.json 的原生 deploy_plan（保留 replacement_home 等既有字段），并按文件内的 stage_name 查找关卡，因此和 MAA 自带的自动战斗共用同一套机制。备注里不写关卡名时，默认对该主题全部原生 autopilot 关卡生效：插件读取 Arknights-Tile-Pos 地图数据，按干员的 position（地面 / 高台）沿入口到蓝门的路径自动选点并计算朝向，所以不需要用户或模型手填坐标。显式点名关卡时才使用给出的坐标与朝向；点名了关卡却缺坐标、朝向，或主题没有该关卡 autopilot 配置时，会逐条列入“无法执行并给出原因”，没有地图数据的关卡也会列出名字，不会静默丢弃，也不会伪造资源条目。招募策略的覆盖文件是“内置分组 + 新增分组”的完整副本，因为 MAA 会整体替换该主题的招募表。

支持的原生能力：

• 按肉鸽主题调整指定干员的招募优先级、技能和精二优先级；招募表缺少该干员时，用 battle_data.json 校验干员真实存在后，新增最小合法分组（skill、is_key、is_start、recruit_priority、promote_priority），查不到干员则明确拒绝；
• 用主题已有的原生分组重设 team_complete_condition；
• 将指定藏品移到购买队列前部，或从购买队列移除；
• 按肉鸽模式选择对应事件策略文件，并修改已收录事件的优先选项；
• 切换主题后只修改该主题的 recruitment.json、shopping.json 和事件策略；
• 生成 Copilot 的有序部署、技能、撤退、技能用法等动作，支持 [x, y]、方向、费用、延迟和击杀数条件；
• 对“堵门”“守蓝门”，在肉鸽主题的 autopilot/<关卡>.json 里追加 deploy_plan 条目：不写关卡名时对该主题全部原生关卡自动选点（按 position 区分地面/高台、沿路线朝入口方向），点名关卡时使用给定坐标；Copilot 场景则从 Arknights-Tile-Pos 的可通行格估算入口到蓝门的最短路径，选择靠近目标的可部署格；
• 同一请求可以同时包含多名干员优先级、阵容条件、藏品、事件或多条战斗动作。

安全与回退：

• 肉鸽策略通过 maa-cli 官方 --user-resource 从配置目录覆盖加载，MAA 安装目录中的原始资源始终只读；覆盖文件执行前备份、结束后恢复或删除。若 DSH/MAA 异常中断，下次策略执行会先按恢复清单还原。
• 不新增不存在的肉鸽分组，不猜不存在的干员、藏品或事件；这些要求会从生效部分剔除，并在确认前列出原因。
• Copilot 地图不能唯一解析时，不会虚构“堵门/守蓝门”坐标；可以改用明确坐标和方向。
• MAA Copilot 是预编排动作，不是通用实时战术 AI。需要持续视觉推理、根据任意敌人状态动态改战术，或 MAA 协议没有字段承载的要求会明确回退。
• 生成策略仍需人工确认；插件不会因为本地解析或模型生成了作业就直接操作游戏。执行反馈会分别标明 MAA 日志已验证完成、明确失败，或仅确认进程结束但游戏结果仍未验证。

原子化策略记忆

通过校验的自然语言策略会按最小可执行单元保存到 ~/.dsh/maa-cli/strategy-memory.json（可随 DSH_MAA_CLI_STATE_DIR 改变位置）：

• 原始自然语言不会直接入库；记忆保存的是规范化后的 MAA step、肉鸽资源动作或 Copilot 动作。无法编译、资源中不存在或发生冲突的要求只进入安全回退说明，不写入记忆。依赖用户本地文件且无法稳定确认可用性的 Custom 任务也不持久化。
• 内置 combat、roguelike、reclamation 分类；其他 MAA step 会按任务类型自动形成分类。每类最多保留最近 20 条，重复语义会更新原记录和参数，不占新名额。
• 复用使用规范化动作、对象和适用场景组成的语义键，不比较用户原句，因此同义表达在模型映射到同一 MAA 动作后会命中同一条记忆，不需要额外的嵌入服务或第二次模型调用。
• 每次复用仍检查 maa-cli/MaaCore 版本、主题、地图和当前参数，并重新运行资源预览。堵门、守蓝门各只保存一条跨地图策略；记忆不保存生成坐标，每次都从当前地图重新计算。
• 同一请求中互相冲突的策略（例如同一藏品同时优先购买和禁买）都不会执行或入库。本次明确指令会覆盖相同语义的旧偏好；旧记忆按全局战术、肉鸽主题/模式、地图动作的适用范围合并。
• 记忆文件使用临时文件加原子重命名写入。版本查询或记忆写入失败时只停用本次记忆更新，不阻断原有 MAA 计划。
• 策略记忆管理面板不再显示在界面上：模型通过 /maa strategies、/maa strategy-enable、/maa strategy-disable、/maa strategy-delete 在后台查看和维护条目。禁用条目保留在文件中但不参与匹配；删除后不可恢复。

确认码规则：

• 只对同一个 DSH 会话有效；
• 一次性，用过即失效；
• 30 分钟后过期；
• DSH 重启后计划仍在磁盘上，可继续确认（默认 ~/.dsh/maa-cli/pending-plans.json，可用 DSH_MAA_CLI_STATE_DIR 改目录）。

自动肉鸽参数面板

计划里含 Roguelike 步骤时，确认条和工具卡会显示「自动肉鸽参数」。主题、模式、难度、分队、职业组和开局干员不再由浏览器维护固定清单，而是从当前实际运行的 maa-cli / MaaCore 版本及其 resource 目录发现；同一份能力描述同时供面板、确认参数校验和策略编译使用。黑流树海在 MaaCore 6.20.0 及以上会显示难度 0–16。

能力发现会读取肉鸽主题目录、主题任务图、recruitment.json、shopping.json、strategy.json、事件表和 stages.json。资源新增或删除主题、模式、干员、分组、藏品、事件或关卡后，能力签名随之变化；打开的确认面板每 15 秒只读刷新一次并自动换用新选项，不需要重启 DSH。切换主题时会立即载入该主题的已确认记忆；同一次未确认编辑中切回原主题时，还会恢复该主题的当前草稿，包括刷取次数和高级设置。

上游 Windows 包目前没有附带完整、机器可读的 MaaCore 任务参数 schema，因此以下内容仍集中在一个按版本约束的协议适配层：字段名和类型、模式中文名、推荐默认值、主题专属开关，以及 Core 内部实现但资源任务图没有节点的模式。适配层不会把未知值猜成可执行能力；资源发现结果始终优先。发现失败时沿用最近一次验证通过的 ~/.dsh/maa-cli/maa-capabilities.json，若从未成功发现才使用最小兼容适配数据并在响应中标记警告。

基础字段包括主题、模式、难度、刷取次数、分队、职业组、开局干员和助战设置。除刷取次数外均由当前能力描述生成选项；刷取次数默认 9999，可输入 1–99999。分队、职业组和开局干员是可选参数：当前主题没有可靠选项或用户选择“未选择”时，它们会从最终 MaaCore 任务中省略，不会提交 squad=、roles= 或 coreChar= 空值。

难度默认是「MAX（当前最高）」：确认时按当前主题可用的难度解析成最大值（例如黑流树海解析为 16、萨卡兹为 15），避免每局手动挑难度；明确选择某个数字时仍按数字执行。

确认成功后，插件会按主题把这次的肉鸽面板配置（模式、难度、刷取次数、分队、职业组、开局干员和高级开关）独立保存，并全局记住最后使用的主题。例如“界园 → 萨米 → 界园”会准确恢复界园自己的开局干员、刷取次数及所有高级设置，不会被萨米配置覆盖。

「高级功能（MAA 高级设置）」折叠区只显示当前主题 / 模式下 MAA 真正会用到的开关：切主题或换模式时，不适用的项直接不渲染、也不会随确认命令发送，避免出现「改了但 MAA 根本不理」的选项。

字段	说明	MaaCore 字段	出现条件
使用非好友助战	助战可以是路人	use_nonfriend_support	使用助战=是
打到最终 Boss 停	Boss房前停止	stop_at_final_boss	主题 ≠ 傀影
等级刷满停	肉鸽等级满后停止	stop_at_max_level	总是
投资源石锭	是否投资	investment_enabled	总是
投资次数	投资多少次（0–99999）	investments_count	投资源石锭=是
投资满停	投资到达上限即停	stop_when_investment_full	投资源石锭=是
投资后购物	投资后顺便购物	investment_with_more_score	模式 = 刷源石锭(1)
凹精二直升	凹开局时同时凹精二直升	start_with_elite_two	模式 = 凹开局(4)
只凹精二直升	只凹精二直升，忽略其他开局条件	only_start_with_elite_two	凹开局(4) 且 凹精二直升=是
月度小队自动切换	月度小队自动换	monthly_squad_auto_iterate	模式 = 刷月度小队(6)
深入调查自动切换	深入调查自动换	deep_exploration_auto_iterate	模式 = 刷深入调查(7)
常乐节点	目标 1 令 / 2 黍 / 3 年	find_playTime_target	模式 = 刷常乐节点(20001)
使用密文板	是否使用密文板	use_foldartal	主题 = 萨米
检测坍缩范式	检测本次拿到的坍缩范式	check_collapsal_paradigms	主题 = 萨米
骰子刷新商店	用骰子刷商店买特殊商品	refresh_trader_with_dice	主题 = 水月

• 主题、模式、难度、分队、职业组、开局干员、刷取次数和高级开关都遵循上述统一预填优先级；肉鸽各主题的记忆互不覆盖。刷取次数首次从 9999 起步，之后回填该主题上次确认的值。
• 改动后仍用同一个确认码执行：按钮实际发送 /maa confirm <code> theme=Sarkaz mode=0 difficulty=4 squad=蓝图测绘分队 ...。
• 参数在消费确认码之前按同一份动态能力描述校验（主题、模式、难度、分队、职业组、干员，以及固定协议字段的数值/布尔范围）。主题、模式、刷取次数等必填值缺失时会明确指出字段；校验失败时计划不会被消耗，可以改完再点。
• 确认按钮右侧「30 分钟内有效」旁边有一个备注栏：备注先被拆成可执行语义单元并经过策略记忆匹配与 MAA 资源校验。预览成功后才允许确认；面板只显示「已收到并解析【备注】」，无法执行的细节仍由模型在对话里说明，不会写进 MaaCore 或策略记忆。
• 只影响计划里的 Roguelike 步骤；计划中没有肉鸽步骤时面板不出现，附加参数会被拒。
• 高级开关只发送当前主题/模式下可用的项；开局干员只用于第 1 顺位招募（core_char，不支持三顺位 core_char_list）。
• 面板只提供下拉选项（开关是「是 / 否」）与刷取次数的手输数字；手工命令通道仍接受 key=value 文本（分队 / 职业组 / 干员长度 1–32），例如 /maa confirm MAA-1A2B3C theme=Sarkaz mode=0 difficulty=4 useSupport=false investmentsCount=999 note=%E6%89%93%E5%AE%8C%E5%B0%B1%E5%81%9C。

工具一览

模型侧可用的工具（本地命令不需要它们）：

工具	作用
maa_query	只读查询：version、help、list，以及各目录位置（cache_dir、hot_update_dir、config_dir、library_dir、resource_dir、data_dir、log_dir）
maa_runtime_instruction	对当前后台任务设置/取消条件停止、立即停止、查询可靠进度；无法实时应用的招募偏好明确返回未支持
maa_operator_box	只读查询上次 OperBox 缓存，可按星级、名称和精英化筛选；不会连接模拟器
maa_depot	只读查询上次 DepotInfo 仓库缓存；无缓存时明确要求先确认扫描，不把未知库存当成 0
maa_goal_manager	创建、重新规划、查看或取消日常、干员培养、材料和自定义目标；自动更新培养消耗与掉率缓存；生成一次性确认工作流
maa_workflow_manager	保存、编辑、删除、查看和复用工作流预设；MAA 能力签名变化后必须重新校验
maa_training_advice	基于 Box 缓存、MAA 职业数据和公开社区榜生成有序培养建议；首次请求会先询问使用缓存还是重扫
maa_doctor	环境体检，只读：maa-cli 版本、AppData 视图、缓存目录可原子写、热更新仓库、连接配置、ADB 文件、ADB 端口、MuMu 管理器，共 9 项
maa_prepare_plan	把自然语言步骤整理成计划并落盘，显示本地确认按钮
maa_prepare_strategy	把招募/精二/藏品/事件偏好或战斗战术编译成 MAA 原生策略与 Copilot 作业，验证后显示确认按钮
maa_prepare_note	备注无法被本地规则确定时，由模型先识别主语/动词并把备注规范化，再交给本地解析器编译成 MAA 原生策略，验证后显示确认按钮
maa_runtime	status / install / update：查看、安装、更新私有运行时；force 强制重装，keepCaches 保留安装包
maa_stage_schedule	只读：按服务器时间（04:00 为日界）列出今天开放 / 未开放的资源本与芯片本，只包含当前 MAA 认识的关卡
maa_prepare_infrast	把自然语言排班编译成 MAA 自定义排班（Infrast mode 10000），校验干员名后预览并生成确认码；支持保存、列出、删除、复用排班
maa_copilot	search 只读查询 MAA 作业站并按 Box 标注缺少的干员；prepare 下载指定作业并生成 Copilot / SSSCopilot 确认计划

目标、工作流与安全恢复

目标和工作流沿用原有确认码，不会因为用户提出了整体目标就自动获得源石、理智药、加急许可或商店消费授权。默认预算为不使用源石、不使用理智药；指定 maxSanity 后，已知关卡的预计理智消耗超过预算会在执行前阻断。

帮我完成今天的日常任务，不用源石和理智药。
我要培养结城理，先读取 Box 和仓库；缺什么列出来，不要直接刷。
源岩需要 20 个，库存不够时规划 1-7，但总理智不超过 120。
把“启动、基建、访问好友、领奖”保存成工作流，下次复用。

• Goal Manager 把目标、事实、材料缺口、预算和完成条件保存到 goals.json；Workflow Manager 把预设和执行游标保存到 workflows.json。长期目标、工作流预设、原子策略记忆和本次运行时指令分别存储，不会互相污染。
• 每个 MAA 步骤单独执行。只有日志明确报告该任务链完成，且 Box / Depot 等结构化结果成功落盘，才会进入下一步；进程退出码 0 但没有完成证据时状态为 needs_review。
• 工作流步骤全部结束后，目标进入“等待目标验证”，不会把“MAA 进程结束”或“任务链完成”冒充“游戏目标实际达成”。目标卡会显示事实、步骤数和完成条件。
• DepotInfo(done=true) 和 OperBoxInfo 仍是库存与干员当前状态的唯一自动数据源。培养消耗从 ArknightsGamedata 的区域游戏数据提取，关卡掉率从企鹅物流统计 Matrix API读取；数据只缓存在本机 planning-data.json，不会随 npm 包再分发。
• 培养/掉率缓存最多每 24 小时自动更新一次。下载成功后记录 URL、ETag、Last-Modified、SHA-256、服务器和取得时间；更新失败保留上次完整验证缓存并标为 stale。可通过 maa_goal_manager 的 data_status / refresh_data 查看或强制刷新。
• 自动培养规划默认目标为精二 1 级，可用 targetElite / targetLevel 明确修改。它根据干员当前精英化/等级计算升级经验、龙门币、晋升材料，并结合仓库库存计算缺口；作战记录按游戏内固定经验档位折算。
• 掉率是玩家上报样本的统计期望，不是必掉保证。插件只采用当前 MAA 仍认识、样本数至少 100 且 Matrix 标记仍有效的关卡，按期望理智排序；每次只执行一个刷取批次，随后强制重扫 Depot 并暂停重新规划，避免按期望值连续过量消耗理智。
• 故障记录写入 runs.json：diagnosis.confidence 区分 confirmed 与 inferred，恢复历史、重试次数和 TaskChain 检查点可在运行面板查看。自动重试上限为 2 次，退避 1 秒 / 3 秒，仅限未完成过任何步骤的 Depot / OperBox；作战、公招、商店、领奖和基建绝不盲目重放。
• DSH 在执行中退出时，下次启动会把正在运行的工作流标为 needs_review，当前步骤标为 uncertain，清理本插件的 dsh-generated 残留进程并尝试恢复策略覆盖。它不会自动续跑不确定步骤，避免重复消耗。

刷理智、公招、基建排班与抄作业

用两瓶药刷 1-7，不要碎石
刷 3 个固源岩组
今天开了哪个芯片本就刷哪个
公招 4 次，出 5 星以上告诉我
制造站全部放赤金，红云放贸易站
找一个 H8-4 低配作业打一下

• 作战次数与代理倍率：只需提供总次数。插件始终让 MaaCore 自动选择代理倍率分组（series: 0），理智不足一整组时自动减少，最后一组按剩余次数执行；面板不再提供倍率选项。
• 掉落目标：Fight 支持 MaaCore 的 drops（任一物品达到数量即停）。物品名按当前 MAA 的 item_index.json 换算成物品 ID，找不到的名字直接拒绝；/maa fight 面板新增「掉落目标」输入框（固源岩组=3；装置=2）。只给掉落目标时，次数默认以 100 为上限，理智药 / 源石仍默认 0。
• 剿灭：剿灭 / 剿灭作战 会写成 MaaCore 的 Annihilation。插件无法得知本周剿灭是否已打满，不会给出这类结论。
• 周常关卡开放日：开放日来自 ArknightsGamedata 的 zone_table.json（weeklyAdditionInfo），关卡所属分区来自同一套游戏数据的 stage_table.json（MAA 的 stages.json 不含分区；企鹅物流把所有芯片本归为同一分区，不能用来判断 PR-A～PR-D 各自的开放日），与培养数据一起每 24 小时更新。maa_stage_schedule 列出今天开放的关卡；准备计划时若关卡今天未开放，会在计划摘要里提示，但不阻止确认。限时活动的“资源全开放”不在统计内。
• 公招：MaaCore 只会对 confirm 中列出的星级真正开始招募，空列表等于“只识别不招募”。默认与 MAA 图形界面一致：招募 4 次、自动确认 3★/4★；5★/6★ 组合不确认、跳过该栏位留给你手动处理，只有明确要求时才会加入。计划摘要会写明会确认哪些星级。运行期间解析 MaaCore 的 RecruitTagsDetected / RecruitSpecialTag / RecruitResult 回调，把高星组合与稀有 Tag 写入 runs.json，在运行面板和执行结果中提示。正在运行的 maa-cli 无法改参数，所以这里是“事后提醒”，不是“暂停等待确认”。
• 基建自定义排班：maa_prepare_infrast 按 MAA「基建排班协议」生成 JSON，干员名用 MAA 的 battle_data.json 校验，查不到、重复安排或超出房间人数的干员会列入“未执行”并说明原因；有 Box 缓存时还会提示你尚未拥有的干员。未提到的设施保持 MAA 默认算法。MAA 不会切换制造站 / 贸易站的生产线：product 只告诉 MAA 房间当前生产什么，以便挑选对应技能的干员。排班可以用 saveAs 保存到 infrast-plans.json，之后用 useSaved 复用。
• 作业站：maa_copilot 通过 prts.maa.plus/copilot/query 按关卡搜索，结合 operator-box.json 标注缺少或练度不足的干员（2 技能需精一、3 技能需精二，以及作业写明的精英化 / 等级要求），干员齐全的排在前面；没有 Box 缓存时明确说“无法判断”。prepare 下载 copilot/get/{id} 的作业，确认面板显示标题、作者、所需干员和缺少的干员；保全派驻作业自动使用 SSSCopilot。默认不使用理智药。
• 生成的排班 / 作业文件只在确认后写到 maa-cli 配置目录的 dsh-strategies/ 下，计划里只保存占位标记，执行结束后删除；计划无法指向磁盘上的任意文件。面板记忆不会保存这些临时文件，也不会保存掉落目标；执行前若计划中残留找不到文件的占位标记，会直接拒绝启动并说明原因。

养成规划：技能、专精、模组与联合刷图

银灰和艾雅法拉都要二技能专三，帮我规划
我的仓库够不够把清流精二？

• maa_goal_manager 的干员培养支持精英化 / 等级、技能 1–7 级、专精 1–3、模组 1–3 级，并可通过 operators[] 一次规划多名干员，缺口按物品汇总后统一规划。
• OperBox 不含技能等级、专精和模组状态：这些当前值必须由用户提供，缺失时返回 needs_input 请求输入，绝不当作 0。
• expandSynthesis: true 时按加工站材料配方（building_data.json 的 F_EVOLVE）把紫色及以上材料展开到蓝色材料为止（品级取自 MAA item_index.json），展开前先扣除库存，并单独列出加工站龙门币。ArkPlanner 可用时不预先展开，因为它本身会规划合成。
• 模组目标会检查游戏数据中的解锁条件（如精二 60 级），目标等级不足时会说明需要先练到几级。
• 培养数据下载使用 ETag / Last-Modified 条件请求：文件没有变化时服务器返回 304，不重复下载（完整刷新约 59 MB）。
• 刷图规划优先调用企鹅物流 ArkPlanner（POST planner.penguin-stats.io/plan）做多材料联合优化；接口不可用时回退到原来的“单材料最低期望理智”选关，并明确标注“未联合优化”。仍然只执行一个批次，随后重扫仓库并暂停重新规划。
• action: "estimate" 是只读查询：计算需求并对比仓库缓存，回答“够不够 / 还缺什么”，不创建目标、不生成确认码。
• 培养数据缓存升级为 v2（新增技能 / 专精 / 模组消耗、加工站配方、周常开放日与关卡分区）；旧缓存会自动重新下载。新增数据源单独失败时只禁用对应功能，并沿用上次缓存。

私有运行时

插件不打包 maa-cli、MaaCore 或资源，而是给每位用户在自己的目录里准备一份：

• 默认位置：~/.dsh/maa-cli/runtime（DSH_MAA_CLI_RUNTIME_DIR 可改）。

• 结构：

  runtime/
  ├─ bin/                    maa-cli（Windows 下是 maa.exe）
  ├─ data/lib/               MaaCore 与依赖 DLL
  ├─ data/resource/          资源
  ├─ config/profiles/default.toml
  ├─ state/                  日志等
  ├─ cache/                  运行期缓存（安装包会被自动清理）
  └─ runtime.json            版本与安装信息
  

• 安装流程：下载 maa-cli 官方 release（约 3.6 MB）→ tar 解包 → maa-cli install --batch（由 maa-cli 自己下载匹配的 MaaCore 与资源）→ 探测 adb 并生成 default.toml → 清理几百 MB 的安装缓存。

• 自动更新：准备启动新任务时检查上次更新时间；距离上次检查满 24 小时才运行一次官方 maa-cli update --batch。maa-cli 自己判断远端版本，版本未变不会重复安装。更新过程全局互斥；已有任务运行时跳过，更新结束后任务才会启动。更新前用同盘硬链接保存旧 lib/resource 快照，成功后清理，失败或中断则原子恢复旧版本。

• 体积：装完约 520–630 MB（MaaCore 约 250 MB，资源约 267 MB）。

• 隔离：通过 MAA_DATA_DIR / MAA_STATE_DIR / MAA_CACHE_DIR / MAA_CONFIG_DIR 四个变量让 maa-cli 只认这个目录，不会读写用户全局的 MAA 配置与缓存。

• 生成任务时的目录：先执行 maa-cli dir config，把任务文件写到该进程实际使用的配置目录，避免私有运行时与全局配置不一致。

• 卸载：直接删除该目录即可，不影响系统里的 MAA。

• 不开 DSH 也能装：node scripts/install-runtime.mjs（会打印每一步的耗时）。

• adb 探测顺序：DSH_MAA_CLI_ADB_PATH → ANDROID_HOME / ANDROID_SDK_ROOT → %ProgramFiles% 与各固定盘的 Program Files / Program Files (x86) 下的 MuMu / 雷电 / 蓝叠 → PATH。探测不到时会写出不含 adb_path 的 default.toml，手动补一行即可（地址默认 127.0.0.1:16384）。

环境变量

变量	作用
DSH_MAA_CLI_RUNTIME_DIR	私有运行时根目录
DSH_MAA_CLI_PATH / MAA_CLI_PATH	指定别的 maa-cli（优先于私有运行时；指向不存在的文件会直接报错，不会偷偷下载）
DSH_MAA_CLI_ADB_PATH	指定 adb，安装时跳过探测
DSH_MAA_CLI_STATE_DIR	待确认计划的存放目录（默认 ~/.dsh/maa-cli）
DSH_MAA_CLI_ASSET_URL	覆盖 maa-cli 下载地址（内网镜像或离线 zip）

兼容性

• 系统：Windows 10/11 x64（运行时来自 maa-cli 官方发布，Linux/macOS 理论上同样适用，但未实测）。
• Node：>=22（只用 node --test、node:fs 等内置模块，无第三方依赖）。
• DSH：dshReleases: 0.2.1-rc.3 标记为兼容。
• 模拟器：任何能被 adb 连接的 Android 模拟器；MuMu 12 是主要测试环境（127.0.0.1:16384、MuMuEmulator12、MiniTouch）。
• 服务区：Official、Bilibili、Txwy、YoStarEN、YoStarJP、YoStarKR。

故障排查

先跑一次体检（模型侧 maa_doctor）：9 项里任何一项红了，基本都能直接定位问题。

现象	原因与处理
I/O error: 系统无法将文件移到不同的磁盘驱动器。 (os error 17)	目标目录被 EFS 加密，maa-cli 的「同目录临时文件 + rename」原子写在加密目录上必然失败。把该目录 cipher /d 解密，或用 junction 重定向到未加密盘（mklink /J）。
Resource directory ... not found, ignoring	maa-cli 回退到了内置资源，通常不影响功能；若行为异常，用 maa_doctor 看资源目录，再 maa_runtime update。
提示「请手动启动mumu模拟器！」	模拟器没启动或没开 ADB 调试。启动后重新点一次确认即可，计划不会失效。
adb 连不上 / 端口不通	adb devices 看设备；MuMu 需要在设置里开启 ADB，端口默认 16384；必要时 adb connect 127.0.0.1:16384。
目录一会儿存在一会儿不存在	从 Microsoft Store 打包的应用启动进程时，%APPDATA% / %LOCALAPPDATA% 会被重定向到 %LOCALAPPDATA%\Packages\<包名>\LocalCache\{Roaming,Local}，且「写后才物化」。插件用 paths.js 在两个视图里查找，maa_doctor 会显示实际路径。
运行时下载慢或失败	设置 DSH_MAA_CLI_ASSET_URL 指向镜像/离线 zip，或手动下载后放到 runtime/downloads/ 再重试 install。
提示「当前 DSH 会话已有一个 MAA 任务正在执行」	同一会话同时只能跑一个任务；先 /maa stop 或等它结束。
提示「MAA 任务正在执行中（…）」	有任务在跑时所有新计划都会被拒绝（跨会话共享）；在面板点「停止任务」或输入 /maa stop。
面板显示「最近一次 MAA 执行」	这是持久化的执行记录；点「×」隐藏（任务已经结束，不会再停止任何东西）。运行中的面板通过自然语言输入框查询进度或追加条件。
运行面板还显示「执行中」，但任务其实已经结束	为避免刷屏，面板不轮询；点「刷新状态」、展开面板或点「停止任务」都会读取一次真实状态。
点「停止任务」后提示「停止失败」	进程在 30 秒内没有退出（例如被安全软件拦截了 taskkill）。记录保持执行中、按钮仍可用，可直接重试；原因同时写入 runs.json 的 stopError。
提示「属于另一个 DSH 会话」	运行中的任务只能在发起它的会话里停止或追加条件；切回那个会话即可。
确认按钮点了没反应 / 提示确认码不匹配	确认码单会话、一次性、30 分钟过期；重新让模型准备一次计划即可。
任务跑到第 5 分钟就停 / 报 This operation was aborted	旧版把整次 MAA 执行放在一次命令调用里，被命令传输的 5 分钟超时打断。新版已改为后台执行：确认后立刻返回「已开始执行」，MAA 进程独立持有到退出；如果仍看到，说明 DSH 还在跑旧插件代码，重启 DSH Desktop 生效。

安全边界

• 只调用 maa-cli 的白名单子命令（查询类 version / help / list / dir，执行类 run），并对参数做字符校验；不会执行任意 shell。
• 只操作游戏：不涉及充值、不修改账号资料、不改动系统 MAA 的配置。
• 停止操作只对本插件当前运行记录对应的进程树执行 taskkill /T，并且只接受发起该任务的 DSH 会话的请求；DSH 重启后的兜底清理按 runs.json 记录的进程号定位进程树，并要求每个被终止的进程命令行都包含 dsh-generated（进程号被复用也不会误杀），另一个仍在运行的 DSH 进程持有的任务不会被碰。只有旧版本留下、没有进程号的记录才回退到按 dsh-generated 匹配。
• 确认码机制保证「模型提议」与「用户批准」是两次独立动作。
• 未知游戏状态、已有完成检查点、预算不足或可能重复消耗时，恢复与工作流都会停在人工确认点；“计划生成”“MAA 已启动”“进程正常退出”“MAA 任务链完成”“游戏目标达成”是五个不同状态。

开发

npm test          # node --test，无第三方依赖

目录按功能划分：

路径	职责
src/index.js	服务端入口：注册工具与 /maa 本地命令，串起确认与执行
src/client/	客户端 UI：计划卡片、备注预览、参数面板与自然语言运行控制输入框
src/capabilities/	MAA 版本/资源能力发现、签名缓存与协议版本适配
src/commands/	本地命令解析、MaaCore 任务规划与确认码管理
src/runtime/	maa-cli 调用、私有运行时、路径、状态、模拟器预检与环境诊断
src/operators/	干员 Box、仓库缓存与培养建议
src/agent/	Goal Manager、Workflow Manager、培养/掉率/开放日数据层、联网请求与故障诊断/安全恢复决策
src/strategy/	自然语言策略的严格校验、原子化记忆、肉鸽资源事务覆盖、Copilot 作业生成、基建自定义排班与 MAA 作业站客户端
test/	全部 Node 测试，包括统一零模型参数面板用例
config/	DSH/Cordis 插件挂载配置
scripts/	不启动 DSH 时可独立运行的维护脚本
docs/	开发与交接文档
artifacts/	本地历史打包文件；不随 npm 包发布

测试统一放在 test/，全部走 node --test test/*.test.mjs，无第三方依赖。

test/panel-lifecycle.test.mjs 是确认面板/运行面板的端到端测试：它在子进程里加载真实的 src/index.js 作为 DSH 主机，用 test/fixtures/fake-maa.mjs 充当 maa-cli（会产生真实的子进程树），再用 test/helpers/mini-react.mjs（一个遵循 React 挂载/卸载规则的极简 hooks 渲染器）渲染真实的 src/client/index.js 并点击按钮。它验证停止确实终止进程树、最小化不卸载面板、取消后确认码永久失效、跨会话与 DSH 重启（对主机进程 SIGKILL）后的恢复。它不连接模拟器、不操作游戏，不能替代实机验证。

发布流程：

# 1. 改 package.json 的 version
npm test
npm publish                       # 2. 发布到 npm
git tag -a v<version> -m "<说明>"  # 3. 打 tag
git push origin main --tags       # 4. 推送并创建 GitHub Release

常见问题

需要先装 MAA 吗？ 不需要。插件会自己准备运行时；系统里已有的 MAA 也不会被影响。

会覆盖我现有的 MAA 配置吗？ 不会。所有读写都限制在私有运行时目录内，通过四个 MAA_*_DIR 环境变量隔离。

装了插件以后原来的 MAA 还能用吗？ 能。两者互不干扰。

为什么不把 MAA 打包进 npm 包？ MaaCore 与资源有几百 MB，且 MAA 采用 AGPL-3.0，重新分发需要承担相应的源码义务。按需下载更轻，也更容易跟随上游更新。

支持哪些服？ Official、Bilibili、Txwy（台服）、YoStarEN/JP/KR。用自然语言指定即可，例如「日服刷 1-7 两次」。

能一次刷 100 次以上吗？ 单条命令上限 100；需要更多可以分多次执行。

任务跑到一半能暂停吗？ MaaCore 没有可靠的暂停/继续接口；可以立即停止，或让插件根据可靠回调在本局结算、再完成 N 局、下一处或指定层 Boss 前终止。停止后不会自动补完剩余局数。

日志在哪里？ 私有运行时下的 state/debug/；也可以用 maa_query 的 log_dir 查询实际路径。

更新日志

查看更新日志

---

许可与致谢

• 插件本身：MIT。
• 插件不附带 MaaCore。运行时会从官方渠道下载 MAA 与 maa-cli，它们遵循各自的许可（MAA 为 AGPL-3.0），下载后请遵守上游协议。
• 感谢 MaaAssistantArknights 团队维护 MAA 与 maa-cli，以及 DeepSeek Harness 提供插件机制。