快速上手

本页面向第一次接手项目或第一次启动中控的开发者，默认按“开发态”说明；如果你使用的是打包版，可直接运行 凡修助手.exe，其余配置关系保持一致。

1. 安装依赖

推荐在项目根目录准备 Python 依赖：

pip install -r requirements.txt
# 或者
uv sync

如果你要维护文档站，还需要进入 website/ 安装前端依赖：

cd website
npm install

2. 启动主程序

日常开发与调试统一从包装脚本启动：

python scripts/main.py

启动后主界面会展示中控表格、日志区、配置操作、表格操作与模拟器配置区域。

如果要专门排查截图、OCR、模板图或组合匹配问题，直接另开一个可视化调试器窗口：

python scripts/run_designer.py

这个调试器现在通过左上角“调试模式”下拉切换页面，默认选项是 OCR调试；如果要改看找图、多点找色、组合匹配或代码调试，再切到对应模式即可。

其中和今天配置模型最相关的入口是：

• “全自动配置”：维护多套定时配置、绑定启用状态、执行顺序和方案覆盖。

另外，顶部还有一个 展开 / 折叠 按钮，用于切换中控表格的显示宽度；它主要解决小屏幕环境下日志区不够宽的问题。

3. 配置模拟器路径

在主界面的“模拟器配置”区域完成以下操作：

1. 勾选要启用的模拟器类型，例如“雷电模拟器”或“MuMu模拟器”。
2. 为每种模拟器填写安装路径。
3. 如需测试更新服务，填写“更新服务”地址。
4. 如有需要，设置“开机自启动”和启动方式。

这些内容最终会保存到 settings.json，其中最关键的字段是：

• enabled_emulators
• paths.ldplayer
• paths.mumu
• update_server_url
• startup
• controller_table_collapsed

4. 维护中控绑定

主表格中的每一行不是“方案槽位”，而是一个中控绑定，语义为：

模拟器 + 渠道 + 默认方案

常见操作如下：

1. 在“渠道”列选择目标渠道。
2. 在“任务方案”列选择该绑定的默认方案。
3. 使用“管理渠道”列的 + / - 为同一模拟器新增或删除渠道行。
4. 使用“表格操作”区的“刷新”同步实例列表。
5. 如需在调试时把日志区放大，可点击顶部 折叠，把表格临时收成四列。

当前中控事实源是 settings.json > controller_bindings，而不是旧版 accounts 结构。

5. 创建或同步任务方案

任务方案的主入口是 profiles/*.json，不是 config/task_config.json。

推荐的维护方式：

1. 点击“任务配置管理”打开方案编辑器。
2. 在方案中勾选任务、填写参数并保存。
3. 如果需要批量生成方案，可使用“一键生成方案”。
4. 如果你已经选中了多条中控绑定，可在“表格操作”区选择一个方案后点击“同步方案”。

运行前系统会先清洗方案，再按 global_task_order.json 统一重排任务顺序。

6. 手动执行或开启全自动

手动执行：

1. 勾选需要执行的表格行。
2. 点击“开始选中窗口”。
3. 运行时系统会把当前行的渠道注入到任务上下文，再按当前方案执行。

全自动执行：

1. 点击“全自动配置”维护定时项。
2. 每套配置都可以单独设置 enabled、bindings、schedule、max_concurrent 和 power.close_emulator_after_finish。
3. bindings 列表里只有 enabled = true 的条目会进入执行队列，列表顺序就是执行顺序。
4. bindings[].profile 为空时沿用中控默认方案，非空时覆盖默认方案。
5. 定时轮询会自动读取这些配置并按规则触发；主界面的“开启全自动”用于立刻启动第一套已启用配置。

如果同一模拟器勾选了多个渠道，它们会串行执行，并在该模拟器最后一个已勾选渠道完成后再决定是否关闭模拟器。

全自动的绑定入口是 auto_config.json > configs[].bindings[].binding_id，方案可以按定时项覆盖默认方案。

7. 配置文件位置

开发态

目标	路径
中控主配置	config/settings.json
全自动配置	config/auto_config.json
全局任务顺序	config/global_task_order.json
任务方案	config/profiles/*.json
任务状态	config/task_states/*.json

打包态

目标	路径
中控主配置	%LOCALAPPDATA%/scriptFrame/config/settings.json
全自动配置	%LOCALAPPDATA%/scriptFrame/config/auto_config.json
全局任务顺序	%LOCALAPPDATA%/scriptFrame/config/global_task_order.json
任务方案	凡修助手.exe 同级 plan/*.json
任务状态	%LOCALAPPDATA%/scriptFrame/config/task_states/*.json

打包版首次启动时，系统会把随包附带的默认配置种到本地运行目录。

8. 常见问题

• 看不到模拟器实例：先检查模拟器路径是否正确，再确认对应模拟器是否已启用。
• 方案执行顺序和编辑顺序不一致：这是正常现象，最终顺序以 global_task_order.json 为准。
• 切换方案后状态看起来“沿用”了之前结果：当前任务状态按“模拟器 + 渠道”隔离，同一渠道下切换方案会共享完成态。
• 全自动里明明有绑定却不执行：优先检查 bindings[].enabled 是否为 true，再检查这套配置本身是否启用。
• OCR 或找图调试困难：优先使用 调试功能 中的可视化调试器和工具页；运行 python scripts/run_designer.py 后，先看默认的 OCR调试，需要找图时再通过左上角“调试模式”切换。