快速上手

本页面向第一次接手当前仓库的开发者，默认按开发态说明。如果你使用的是打包版，可直接运行 凡修助手.exe；用户配置在 %LOCALAPPDATA%\scriptController\config。

1. 安装依赖

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

uv sync

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

cd website
npm install

2. 启动主程序

日常开发与调试统一从仓库根目录启动：

uv run python main.py dev-gui

无参数运行 uv run python main.py 也会进入 GUI。开发态默认读取仓库里的 config/。

启动后主界面是完整中控表格，不再使用旧项目的左侧表格 + 右侧常驻参数工作台。顶部工具条提供日志、配置、全自动、调试和更新入口。

如果要专门排查截图、OCR、模板图或组合匹配问题，直接点主界面 开启调试。调试结果使用表格展示，命中项排在顶部。

其中和当前配置模型最相关的入口是：

• 配置 -> 任务配置：只勾选任务开关。
• 配置 -> 参数配置：维护当前绑定的任务参数。
• 配置 -> 全自动配置：维护定时队列、绑定启用状态、执行顺序和可选方案覆盖。

3. 配置模拟器路径

在主界面打开 配置，进入“模拟器配置”完成以下操作：

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

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

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

4. 维护中控绑定

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

模拟器 + 渠道 + 任务方案

常见操作如下：

1. 在“渠道”列选择已知渠道。未选择渠道时允许保存，但不允许执行。
2. 在“任务方案”列选择该绑定的默认方案。
3. 使用“管理渠道”为同一模拟器新增或删除渠道行。
4. 在“参数配置”里给这个 binding_id 填写任务参数。

当前中控事实源是 settings.json > controller_bindings。渠道选项以 controller_core.config.KNOWN_CHANNELS 为唯一来源，不再提供自动识别。

5. 创建方案并填写 binding params

任务方案的主入口是 config/profiles/*.json。方案文件只保存任务开关。

任务参数的主入口是 config/binding_task_params.json。运行时按 binding_id + task_id 读取。

推荐的维护方式：

1. 打开“任务配置”，勾选任务并保存方案。
2. 打开“参数配置”，按绑定填写参数。
3. 如果你已经选中了多条中控绑定，可在配置中心选择一个方案后点击“同步方案”。同步方案不会写 binding params。

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

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

手动执行：

1. 勾选需要执行的表格行。
2. 在配置中心点击“开始选中窗口”。
3. 运行时系统会读取当前绑定的渠道和 binding params，再按当前方案执行。

全自动执行：

1. 打开“全自动配置”维护定时项。
2. 每套配置都可以单独设置 enabled、bindings、schedule、max_concurrent 和 power.close_emulator_after_finish。
3. bindings 列表里只有 enabled = true 的条目会进入执行队列，列表顺序就是执行顺序。
4. bindings[].profile 为空时沿用中控默认方案，非空时覆盖默认方案。
5. 全自动不再提供任务参数覆盖层。运行参数始终来自当前 binding 的 binding params。

如果同一模拟器勾选了多个渠道，它们会串行执行。

7. 配置文件位置

开发态

目标	路径
中控主配置	config/settings.json
任务方案	config/profiles/*.json
绑定任务参数	config/binding_task_params.json
全自动配置	config/auto_config.json
全局任务顺序	config/global_task_order.json
定时参数计划	config/timed_param_schedule.json

打包态

目标	路径
用户配置目录	%LOCALAPPDATA%\scriptController\config
中控主配置	%LOCALAPPDATA%\scriptController\config\settings.json
任务方案	%LOCALAPPDATA%\scriptController\config\profiles\*.json
绑定任务参数	%LOCALAPPDATA%\scriptController\config\binding_task_params.json
全自动配置	%LOCALAPPDATA%\scriptController\config\auto_config.json

打包版首次启动时，系统会把随包附带的默认配置种到本地运行目录，已有文件不会被覆盖。

8. 常见问题

• 看不到模拟器实例：先检查模拟器路径是否正确，再确认对应模拟器是否已启用。
• 方案执行顺序和编辑顺序不一致：这是正常现象，最终顺序以 global_task_order.json 为准。
• 切换方案后参数看起来“沿用”了之前结果：参数按 binding_id 保存，不跟方案走。
• 全自动里明明有绑定却不执行：优先检查 bindings[].enabled、渠道是否为已知渠道，以及这套配置本身是否启用。
• OCR 或找图调试：优先使用主窗口 开启调试，不要再找旧项目的 scripts/run_designer.py。