三月七小助手（March7thAssistant）

三月七小助手是开源的《崩坏：星穹铁道》自动化工具：识别游戏画面并完成日常、清体力、各类周常玩法。 游戏操作全部由小助手完成；你的工作是查找 / 安装、运行任务、修改配置、读结果和排查问题。

这份说明只提供知识，不限制你使用任何工具。 这里没写到的，直接读文件、执行命令： m7a.exe --help、assets/config/config.example.yaml（每个配置项都有中文注释）、assets/docs/（教程、FAQ、任务表）。

1. 找到安装位置

1. 读 %LOCALAPPDATA%\March7thAssistant\installs.json：小助手每次启动都会登记安装路径与版本，最近使用的排在最前。
2. 用户给出的路径。
3. 少数常见位置（如 ~\Games\March7thAssistant、D:\March7thAssistant）。不要全盘搜索；找不到就问用户。

安装目录里有 March7th Launcher.exe（图形界面）、March7th Assistant.exe（命令行，需要管理员权限）、 m7a.exe（给脚本与 AI 用的命令行）、config.yaml、logs\。 源码目录（有 main.py、app.py）用 python main.py 代替 m7a.exe，参数完全相同。 还没安装：按 安装说明 操作。

2. 用 m7a.exe 操作

m7a.exe 不需要管理员权限：查询类命令直接返回；运行任务时会弹出一次 UAC，由用户点「是」， 任务在最小化的管理员窗口中执行，输出会实时转回你的终端，结束后返回任务的真实退出码。

命令（在安装目录执行）	作用
.\m7a.exe --status	版本、首次使用是否已确认、游戏路径是否有效、图形界面是否在运行、正在运行的任务、最近 5 次运行（JSON）
.\m7a.exe --list --json	全部任务 ID 与名称
.\m7a.exe <任务ID> --after-finish None	运行任务并等待结束
.\m7a.exe --workflow-name "流程名称"	运行用户在「流程编排」里建好的流程（--list-workflows 查看名称）
.\m7a.exe <任务ID> --after-finish None --detach	启动后立即返回运行编号，不等待（长任务用）
.\m7a.exe --follow latest	跟随最近一次运行的输出直到结束（也可写运行编号）
.\m7a.exe --control current pause	暂停 / 继续 / 停止正在运行的任务（pause / resume / stop），图形界面启动的任务也可以

• 运行类命令加 --json，最后一行输出完整运行记录；所有 JSON 输出只含 ASCII，中文以 \uXXXX 转义。
• PowerShell 读取中文输出前先执行 [Console]::OutputEncoding = [Text.Encoding]::UTF8，否则可能出现个别乱码字符。
• 安装目录里没有 m7a.exe 说明是旧版本：见 排查说明 的替代做法，并建议用户更新。

退出码	含义	该怎么做
0	成功	汇报结果
1	任务失败	看运行记录的 error 与日志，按 排查说明 处理
2	参数错误	看 --help 修正参数
3	首次使用尚未确认	打开 March7th Launcher.exe，请用户本人阅读并确认免责声明
4	已有任务在运行，本次未执行	等它结束（--follow current）或询问用户；确需同时运行才加 --force
5	没有获得管理员权限（UAC 被取消）	告诉用户需要在弹窗中点「是」
6	任务被停止指令中止	按用户意图决定是否重跑