Files
lc-mcp/README.md
T
ywsandClaude Opus 5.5 d15f5a1bb2 复查修正: 饰品三选一被上游倒序、选队顶栏同名被覆盖
- 饰品(P1-3): 三张及以上时上游把认出体系图标的卡逐张 insert(0), 后看的排到最前,
  两张命中关键词的卡都带图标时补丁的顺序会被倒过来, 先拿命中少的。现在交给上游
  "没命中的(原顺序) + 命中的(倒着)", 上游查体系图标时对命中的卡答"有", 拼出来是
  命中多 -> 命中少 -> 只认出图标 -> 其余。测试的假界面加上体系图标, 先复现再修。
- 选队(P1-5): _team_ocr 经 _run_ocr_for_text 的 {文本: 坐标} 取结果, 选中某队后
  顶栏和列表同名, 顶栏那条会被覆盖; 旧测试用成对结果模拟重复, 真实 dict 做不到。
  改读 OCR 引擎逐行结果(同一引擎、同一截图), 引擎导入不了才退回 dict。
- 事件(P1-4): 同一张截图只判断一次, 单通模式再找 "???" 时不再整屏 OCR 第二遍。
- 文档: 修正 BACKLOG/README/交接文档对应描述, 去掉两处没核实的推断。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 09:04:37 +00:00

356 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# lc-mcp — 基于 AALC 的 Limbus Company MCP server
把 [AhabAssistantLimbusCompany (AALC)](https://github.com/KIYI671/AhabAssistantLimbusCompany)
的识别与操控能力包装成 MCP 工具,给 AI agent(codex / 任意 MCP 客户端)用。
- **低层**:截图、RapidOCR、AALC 模板图匹配(几百张按钮/图标模板)、后台点击/按键,全部直接调 AALC 的 `module.automation`
- **高层**:`run_task` 直接跑 AALC 现成的完整流程(日常经验本/纽本、领奖励、狂气换体力、镜牢),自带战斗处理、掉线重试、游戏重启
AALC 以 git submodule 引入(`vendor/aalc`,固定到某个 commit),不改它的代码,升级时只需更新 submodule 指针。
## 架构
```
MCP 客户端 ──ssh──> python lc_mcp/bridge.py (stdio, 只用标准库)
│ 127.0.0.1:8765, 首行 token 认证
▼
python -m lc_mcp.server ← 登录时由计划任务在「交互桌面会话」启动
├─ AalcEngine → AALC auto / ocr / screen (找窗口、后台截图、PostMessage 输入)
└─ TaskRunner → 子进程 python -m lc_mcp.aalc_task <task> (停止 = 杀进程树)
```
为什么要常驻服务 + bridge:SSH 登录的进程跑在 session 0,看不到游戏窗口,也发不了输入。
旧版靠"每次截图注册一个计划任务"绕过,慢且不能输入;现在整个服务常驻在桌面会话里。
## 部署(Windows,跑游戏的那台机器)
```powershell
git clone --recursive https://git.lingll.icu/yws/lc-mcp
cd lc-mcp\vendor\aalc
uv sync # 按 AALC 的 pyproject 装依赖 (Python >= 3.12),生成 .venv
# 先用 AALC 自己的界面 (uv run main.py) 配好队伍、镜牢设置等,lc-mcp 读同一个 config.yaml
cd ..\..
powershell -ExecutionPolicy Bypass -File scripts\install_logon_task.ps1
```
`install_logon_task.ps1` 会注册 `LcMCPServer` 计划任务(登录时启动、普通权限、失败自动重启)。
游戏以管理员身份运行时才需要加 `-Elevated`。卸载:`-Uninstall`。
## MCP 客户端配置
```jsonc
{
"mcpServers": {
"limbus": {
"type": "stdio",
"command": "ssh",
"args": ["win", "python", "C:/Users/<you>/lc-mcp/lc_mcp/bridge.py"]
}
}
}
```
bridge 读取 `~/lc_mcp/token` 认证(服务首次启动时生成),所以 SSH 用户必须和登录桌面的用户是同一个账号。
服务没起来时 bridge 仍会完成握手,并对每个调用返回“服务未运行”的原因。
本机直接用(客户端本身就在桌面会话里):`python -m lc_mcp.server --stdio`。
本机 Codex 也可以连接常驻后台服务(将路径替换为自己的仓库目录):
```powershell
codex mcp add limbus --env PYTHONUTF8=1 -- D:\lc-mcp\vendor\aalc\.venv\Scripts\python.exe -X utf8 D:\lc-mcp\lc_mcp\bridge.py
```
常驻服务使用 `pythonw.exe` 时,启动日志写入 `~/lc_mcp/server.log`。
直接 stdio 模式会在导入 AALC 前隔离日志,并统一使用 UTF-8,避免日志破坏 JSON-RPC 或中文乱码。
模板识别会根据当前客户区的 16:9 画面比例临时缩放,匹配结束后恢复内存中的原配置。
后台操作且需要保留系统鼠标位置时,在 AALC `config.yaml` 使用
`background_click: true` 和 `win_input_type: window_move`,然后重启常驻服务。
此模式临时移动透明游戏窗口以对齐 Unity 的指针位置,释放后恢复位置,
不调用系统鼠标移动或前台激活。`background` 模式仅发送客户区鼠标消息;
部分 Unity 界面仍读取系统指针位置,实测标题页按钮需使用 `window_move`。
战斗按键有按下/释放间隔;隐藏启动后可用 `show_game_background` 恢复渲染。
## 可选:任务流使用罗技驱动鼠标输入
驱动接入代码已随仓库提交:`lc_mcp/driver_input.py`、`lc_mcp/aalc_patches.py`、
`lc_mcp/aalc_task.py`,回归测试在 `tests/test_driver_input.py`。
**仓库不包含 `logitech.driver.dll`、罗技驱动安装包或 `logitech.test.py`。**
需要在 Windows 目标机安装配套驱动并提供 DLL;仅拉取本仓库不能启用这套输入。
在启动 MCP 服务的进程环境中设置(路径替换为本机实际位置):
```powershell
$env:LCP_DRIVER_INPUT = '1'
$env:LCP_LOGITECH_DLL = 'E:\罗技键鼠驱动\logitech.driver.dll'
# 可选,目录需已存在:
$env:LCP_DRIVER_TRACE = "$env:USERPROFILE\lc_mcp\driver-input.log"
```
`LCP_DRIVER_INPUT` 默认关闭,DLL 路径未设置时默认使用上面的 E 盘路径。
服务已经运行时,需要让服务以这些环境变量重新启动;只给 SSH bridge 设置无效。
任务子进程必须在物理 console 会话内,且关闭“提高指针精确度”。预检失败会记录原因,
继续使用原输入后端,不修改系统设置。驱动模式会移动真实系统光标并尝试激活游戏;
激活或坐标转换失败时拒绝本次点击。
接管范围是 `run_task` 的鼠标点击(含空白点击、`all` 和游戏重启后的点击)。
模拟器不接管;拖拽、滚动、键盘以及 MCP 的独立 `click` 工具仍使用原后端。
当前回归验证覆盖软件接线和异常处理,DLL、实际驱动及游戏响应需在 Windows 实机核验。
任务运行期间按 **End** 急停,可用 `LCP_KILL_KEY` 改成 `pause`、`scrolllock` 等键名。
不要用 F12(Steam 截图键);监听用 `GetAsyncKeyState` 轮询,因为 pynput 钩子在该机器的会话里收不到按键。
急停会终止任务子进程,保留游戏窗口;`task_status` 返回 `stopped`、退出码 `130`。
刷取循环检测到用户停止后结束本轮,不再导航、升级或重试。急停前会尝试释放驱动
按住的鼠标按钮,清理超过 250 毫秒仍强制退出;硬退出留下的临时配置恢复文件由
`stop_task` 或下一次 `run_task` 处理。热键监听依赖 AALC 的 `pynput`,安装失败会写日志;
也可从 MCP 调用 `stop_task`,或按 Ctrl+Alt+Del 打开任务管理器终止任务进程。
此热键只覆盖 `run_task` 子进程,不覆盖独立运行的合成、升级脚本。
## 工具
MCP 初始化说明与工具描述均指导 AI 优先使用 AALC:常规日常、领奖、普通镜牢按
`task_status` → `run_task` → 轮询 `task_status` 执行。只刷经验本时显式传 `thread: 0`,
只刷纽本时传 `exp: 0`,避免沿用另一项配置。主线、特殊速通路线或故障恢复使用逐步输入。
只看状态或截图不会启动任务;`all` 只用于明确要求全部任务,`enkephalin` 需要明确授权花狂气。
启动成功不等于完成,最终还要检查 `errors` 和 `pending_restore`,用户停止后不自动重跑。
更新后重启常驻服务并重连 MCP,客户端才能获取新的初始化说明和工具描述。
| 工具 | 说明 |
|------|------|
| `get_state` | 截图 + OCR,返回窗口内全部文字 `{text,x,y,w,h,score}` |
| `click_text(text, index)` | 按文字点击;忽略空格/大小写,完全匹配优先 |
| `wait_for_text` / `wait_for_text_gone` | 轮询 OCR 等文字出现/消失(上限 300s) |
| `find_image` / `click_image(name, threshold, model)` | AALC 模板图匹配,适合没有文字的按钮 |
| `list_images(prefix)` | 列出模板图,如 `battle/`、`mirror/` |
| `screenshot` | 窗口截图(`~/lc_mcp/shots`,只保留最近 30 张) |
| `show_game_background` | 显示/恢复游戏窗口,不激活前台;完整任务运行中拒绝此操作 |
| `click(x,y,times)` / `keypress` / `type_text` | 低层输入(窗口客户区坐标) |
| `drag(from_x,from_y,to_x,to_y,duration)` | 保持左键按下并缓慢拖动,适用于卡包;默认 1 秒,范围 0.1–10 秒;坐标以 `get_state` 的客户区截图为准 |
| `run_task(task, …)` | `all` / `daily(exp,thread)` / `reward` / `enkephalin(times)` / `mirror(count)` |
| `task_status(lines)` / `stop_task` | 任务状态、日志尾部(`~/lc_mcp/runs`)、强制停止 |
任务运行期间,点击/按键类工具会被拒绝(防止打乱 AALC 的流程),只读工具仍可用。
`run_task` 传入的次数只对本次运行生效,结束后恢复 `config.yaml` 原值。AALC 运行中会整份保存配置,
所以任务启动时先把原值写到 `~/lc_mcp/runs/*.restore.json`;`stop_task` 强停或任务进程异常退出后,
服务会据此写回。写回失败时 `task_status` 显示 `pending_restore`,并在写回成功前拒绝启动新任务。
`state` 只反映任务子进程的退出码。AALC 在单次战斗失败(例如日志里的
`超出最大尝试次数,未能进入战斗`)后仍会继续跑完并正常退出,所以 `task_status`
会扫描整份任务日志,把最后 3 条 `[ERROR]`/异常行放进 `errors` 字段:
**看到 `succeeded` 也要先看 `errors`。** 任务退出后的首次查询会缓存扫描结果,后续查询不再扫描日志。
任务运行中如果 `task_status` 带 `stall` 字段,说明 AALC 在原地空转(例如选中了空队伍,
编队人数检查一直刷屏)。它不会自己报错退出,应当 `stop_task` 后重跑。
镜牢任务的局内决策逐条写进与日志同名的 `~/lc_mcp/runs/task_*.decisions.jsonl`(每行一个 JSON:
`time`/`stage`/`choice`/`reason` 加细节)。`task_status` 的 `decisions.counts` 按阶段统计 `reason`:
| `stage` | `reason` |
|---|---|
| `team` | `current` 已是目标队 / `exact` / `prefix` 后缀队名 / `header_unchanged` / `not_found` |
| `road` | `lowest` 下一列最优 / `next_best` 更优方向进不去 / `fallback` 退回按 ↑ |
| `theme_pack` | `preferred` 达到优选阈值 / `highest_weight` 刷新后取最高权重 / `event_pack` 最左活动卡包 |
| `gift` | `keyword` 命中体系关键词 / `no_keyword`(记的是交给 AALC 的第一顺位,白棉花、已持有仍由 AALC 处理) |
| `event` | `text` 按表选 / `deferred` 认出了表里的事件但交给 AALC / `not_in_table`(带 `options`,可直接拿来补表) |
| `shop` | `name_match` 按中文名找到必买饰品(`choice` 是名字)/ `purchase_clicked` 点到了购买按钮(`choice` 是之前点的商品:`shop_by_name` 按名字、必买模板名、`level_IV_to_buy`、`by_position` 本体系饰品) |
### 任务进程里的保护
`run_task` 启动的任务子进程会做以下处理,都不改 `vendor/aalc` 源码:
- **配置预检**:发现下列问题就直接拒绝启动(退出码 3,原因写在 `errors` 里):
- 镜牢队伍的 `sinner_order` 全是 0:这会让 AALC 选出空队伍,然后无限重试编队;
- 镜牢队列为空,或队列里没有适用当前难度的队伍(按"固定用途"判断):AALC 会一局不打就以 0 退出;
- `set_lunacy_to_enkephalin` 不为 0:体力不足时会花狂气换体力。确需使用时设 `LCP_ALLOW_LUNACY=1`;
- 自动设置窗口时,目标尺寸放不进当前桌面:窗口会被压扁成非 16:9。
`free` 位置计入标题栏,自动定位的无边框窗口只计客户区;`set_windows: false` 跳过此项。
- **队伍名精确匹配**:AALC 按子串找队伍,`TEAMS #1` 会命中 `TEAMS #10`。补丁要求编号完全相同。
- **窗口比例守护**:每 15 秒检查一次客户区。RDP 重连后窗口被拉伸时,自动调回 `set_win_size` 对应的 16:9 尺寸。
- **HDR 提示**:`all` 任务检测到 HDR 时记录警告并继续,不等待 GUI 确认。
- **镜牢完成核对**:监听 AALC 的镜牢进度信号统计实际完成局数。少于应打局数时记一条 `[ERROR]`
并以退出码 4 结束,`task_status` 显示 `failed`;AALC 正常返回不再被当成打完。
- **指定次数**:`mirror` 传 `count` 时本次临时关闭 `infinite_dungeons`(开着时 AALC 会把次数改成 9999),
原值和次数一起写入恢复文件,结束或被强杀后都会写回。
- **商店按中文名购买**:必买项先整屏 OCR 商品格下面的饰品名,对上 `lc_mcp/data/shop_gifts.json`(零协汉化名字,
靠前的先买)就点那一格,购买/确认仍走 AALC 原循环;AALC 的 5 张图标模板在后面兜底。`LCP_SHOP_NAMES=0` 关闭。
(必买/必卖/公式合成清单为空的问题,上游 V1.6.1 已修,本地补丁已删。)
- **镜牢按体系名选队**:按 `team_system` 在编队列表里点同名队伍(流血/斩击/…),点完核对顶栏队名。
名字先归一(去空白、全角转半角、纠正 `震颐`/`沉论`/`编#` 等误读);精确匹配优先,
否则接受这一屏唯一的"名字+后缀"(`流血队`、`流血(X)`),多条就不点。没找到时日志列出每屏看到的名字。
- **键盘寻路按节点类型**:开着简单键盘寻路时不再只按 ↑。先识别巴士右侧下一列的节点类型,
按上游权重(事件 < 商店 < 战斗 < …)依次按方向键,进不去再退回 ↑;不拖地图。`LCP_TYPED_ROAD=0` 关闭。
- **饰品选择按体系关键词**:镜牢路上的饰品 N 选一,先整屏 OCR,按卡面上命中当前体系关键词的行数给卡排序,
再交给 AALC 原逻辑(跳过白棉花、已持有排后)。三张卡时命中关键词的卡按"认出体系图标"交给 AALC,
并抵消它把这类卡逐张插到最前造成的倒序。关键词表在 `lc_mcp/data/gift_keywords.json`。
- **事件选项表**:事件出现选项时整屏 OCR,按同一屏其它选项的原文(零协汉化)认出 `lc_mcp/data/event_choices.json`
里的事件,就点表里那一项;不靠事件名(汉化数据没有标题)。没收录的事件照旧交给 AALC,
日志会打印这一屏的选项文字,便于补表。表里的选择优先于 AALC 的"有 ??? 先点 ???",小指良单通模式也一样。
- **挂不上就报错**:事件表、饰品排序、商店按名字这三个补丁靠拦截 AALC 的某个调用挂进去,安装时先查上游源码;
上游改了写法时记 `[ERROR]` 并跳过该补丁,不会悄悄失效。
## 无人值守
有两套独立的自动化,按需要各自启用:
### 1. 刷取循环(打关卡)
`scripts/auto_cycle.py` 每次跑一轮,流程是:刷材料(daily)→ 镜牢(`--mirror N`)→ 把队内人格升级、同步到 `--target`。
AALC 卡死时,脚本会停掉任务并重跑一次。每轮在 `~/lc_mcp/cycles/` 写一份 `cycle_*.log` 和一份 `cycle_*.json` 报告。
```powershell
# 先手动跑一轮确认
vendor\aalc\.venv\Scripts\python.exe scripts\auto_cycle.py --mirror 1
# 再注册计划任务: 每 1 分钟的会话看门狗 + 每 N 小时一轮
powershell -ExecutionPolicy Bypass -File scripts\install_unattended.ps1 -EveryHours 2.5 -Mirror 1
```
### 2. 只需挂机攒模块(不打任何关卡)
`scripts/convert_modules.py` 到点自己启动游戏 → 把体力合成为模块 → 关掉游戏。
每 4 小时一轮,用 `scripts/install_convert_task.ps1` 注册。
```powershell
vendor\aalc\.venv\Scripts\python.exe scripts\convert_modules.py # 手动跑一次
powershell -ExecutionPolicy Bypass -File scripts\install_convert_task.ps1 -EveryHours 4
```
看历史:`python scripts/modules_status.py`
合成脚本与 `run_task` 子进程通过 `~/lc_mcp/game.lock` 互斥,锁一直保持到操作和关闭游戏结束。
已有任务占用时,后来启动的一方报告失败;合成脚本无法确认任务状态时也会退出,不接管游戏。
进程退出后锁由系统释放,文件保留,无需手动删除。
**⚠️ 挂机值守前先读 [`docs/WATCH.md`](docs/WATCH.md)** —— 那里记着环境事实、
界面坐标、狂气的三道防线、六种已知失败模式及处置,以及几条踩过的坑
(比如 OCR 会把 `LUNACY` 读成 `UNACY`,曾让整条狂气防线静默失效)。
`scripts/levelup.py` 和 `auto_cycle.py` 里的坐标都按 1600×900 客户区书写,运行时会按实际客户区大小缩放。
`levelup.py card`、`weakest` 和 `progress` 带 `--uptie` 时,同步失败会返回非零退出码。
## 环境变量
| 变量 | 默认 | 说明 |
|------|------|------|
| `AALC_DIR` | `vendor/aalc` | 使用其他位置的 AALC 源码 |
| `LCP_PORT` | 8765 | 服务/bridge 端口 |
| `LCP_KEEP_SHOTS` | 30 | 截图保留张数 |
| `LCP_ALLOW_LUNACY` | 未设置 | 设为 `1` 时允许预检放行 `set_lunacy_to_enkephalin` 不为 0 的配置 |
| `LCP_TYPED_ROAD` | 未设置 | 设为 `0` 时镜牢简单键盘寻路保持上游的"只按 ↑",不按节点类型选方向 |
| `LCP_EVENT_CHOICES` | 未设置 | 设为 `0` 时事件不查选项表;设为 JSON 文件路径时用它代替 `lc_mcp/data/event_choices.json` |
| `LCP_GIFT_KEYWORDS` | 未设置 | 设为 `0` 时饰品选择不按体系关键词排序;设为 JSON 文件路径时用它代替 `lc_mcp/data/gift_keywords.json` |
| `LCP_SHOP_NAMES` | 未设置 | 设为 `0` 时商店必买只用 AALC 图标模板;设为 JSON 文件路径时用它代替 `lc_mcp/data/shop_gifts.json` |
| `LCP_KILL_KEY` | `end` | 任务子进程的急停键,如 `pause` / `scrolllock`;认不出的键名会报错而不是换成默认键 |
| `LC_PY` | 当前解释器 | `levelup.py`/`auto_cycle.py` 调用 MCP 用的 Python |
## 开发 / 测试
### Jev 决策接口
`scripts/jev_mirror_agent.py` 使用 `scripts/jev_client.py` 读取本地配置中的
`model`、`baseUrl`、`sessionId`、`transport` 和 `timeoutSeconds`。
Jev 默认地址为 `https://opencode.ai/zen/v1/systemone`;`baseUrl` 填到 `/v1`,
客户端会追加 `/systemone`。Go 网关的模型列表与 Jev 原生接口不同,不能仅替换地址就假设支持相同模型。
从 `scripts/jev_config.example.json` 创建仓库外的私有配置,API key 使用
`OPENCODE_API_KEY` 环境变量或私有配置中的 `apiKey`。不要把凭据提交到仓库。
Windows 上若 Python HTTPS 遇到握手中断,可用 `"transport": "curl"`,
并把超时提高到 20 秒;认证头通过 stdin 交给 curl,保留证书验证。
通用客户端也支持主线等其他场景的候选决策,不会发送游戏输入:
```powershell
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_client.py <private-config.json> <observation.json>
```
`observation.json` 提供 `state`(当前画面观察文本)、`criteria`(候选名到描述的映射)
和 `instructions`(当前任务规则)。返回候选名和耗时,候选之外的响应会被拒绝。
镜牢执行器的场景规则只适用于镜牢,推进主线时应提供主线观察和规则。
```bash
python -m unittest discover -s tests -t tests # 不需要 Windows/AALC (FakeEngine)
python -m lc_mcp.server --stdio --fake # 假引擎手动调试协议
```
服务安装后,可通过真实 bridge 做 MCP 握手和工具调用:
```powershell
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\mcp_probe.py task_status
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\mcp_probe.py get_state
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\mcp_probe.py find_image '{"name":"mirror/road_in_mir/setting_assets.png"}'
```
该脚本只调用指定工具;输入类工具会实际操作游戏。完整 AALC 任务依赖已配置好的队伍与流程,基础连接测试不需要启动完整任务。
## Jev 镜牢执行器与真实反馈
`scripts/jev_mirror_agent.py` 的 `--workflow auto` 默认把普通镜牢交给 AALC。
没有配置、决策模型要求或未完成速通记录时,先查 `task_status`,空闲后调用
`run_task({"task":"mirror","count":1})`,随即返回 `delegated` 和后续监控调用。
调用方继续轮询 `task_status`;脚本退出不代表通关。已有镜牢任务时返回 `monitoring`,
其他任务占用、用户停止、报错或状态不明时不会自动抢占或重试。
```powershell
# 普通镜牢:默认转交 AALC,不需要 Jev 配置
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py
# 明确启动新任务;先前有用户停止或失败时也需明确提出新任务
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py --workflow aalc --new-run
# 查看已交给 AALC 的任务结果,不启动下一局
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py --workflow aalc --resume
```
AALC 交接结果写入运行目录的 `aalc_mirror_status.json`;停止已交接的任务使用 `stop_task` 或急停键(默认 End)。
`JEV_STOP` 会阻止新的交接,但交接后不再由此脚本监听。`--steps` / `--seconds` 仅限制逐步模式。
`--workflow speedrun` 使用原有的特殊速通流程。为兼容现有调用,提供 Jev 配置、
`--decision-engine`、执行模型回调、`LC_FIXED_FALLBACK=1` 或未完成速通记录时,`auto` 保留逐步模式。
`--resume` 沿用已保存的流程;已有未完成速通局时,切换 AALC 必须明确指定 `--new-run`。
逐步模式通过 MCP bridge 操作游戏,路线等分支交给 Jev 或执行模型;战斗采用 P → 回车宏,事件先 SKIP,回车失效时使用当前按钮。它保留用户已配好的队伍,商店无可替换出战角色时至多刷新 4 次,加载期间不读取旧库存继续操作。
安装 AALC 依赖并启动常驻服务后,把 `OPENCODE_API_KEY` 设为自己的凭据,再运行:
```powershell
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py scripts\jev_config.example.json --workflow speedrun --steps 250 --seconds 1800
```
运行数据默认写到 `~/lc_mcp/jev`,可用 `LC_JEV_HOME` 指定其他目录。逐步模式下创建该目录的 `JEV_STOP` 文件即可停止;续跑前移除它。不要与 AALC 完整任务或另一个游戏执行器同时操作。
工具调用失败(截图暂不可用、按钮已消失等)会记入日志并重新观察画面,同一画面上同一动作最多尝试两次,不会因单次失败整局退出。
逐步模式每局运行有独立标识。默认续跑尚未结束且上下文一致的当前局;已完成或没有运行记录时建立新局。重新开一局时使用 `--new-run`,明确要求续跑时使用 `--resume`。旧版本未完成记录会保留楼层和强化进度,但旧的领取及战斗标记不会作为本局完成证据;只有上下文而没有运行记录时会重置它。领取截图和返回大厅截图必须属于当前局,才能记录完成。
```powershell
# 新开一局:清除上一局的楼层、饰品与领取状态
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py scripts\jev_config.example.json --new-run --seconds 1800
# 续跑已保存的未完成局,保持原计时起点
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py scripts\jev_config.example.json --resume --seconds 1800
```
MCP 客户端默认每次请求等待 30 秒,文字等待工具按自身时长延长响应期限。等待回复期间也检查停止标记和本次运行的时间预算。超时或中断时关闭客户端连接,并记录结果可能未知;不会自动重发点击或按键。常驻服务已经接收的操作可能仍会完成,需核对当前画面后再续跑。`battle_batch.py` 与主执行器共用判定、奖励、死亡和地图等战斗退出条件,并在每个按键前检查停止标记。
设置 `LC_FIXED_FALLBACK=1` 可只使用固定候选,无需 Jev API 密钥;仍需运行 MCP 服务。完整 AALC 任务启动时,如有 MCP 工具正在执行,会立即返回忙碌错误,避免与当前输入交错;查询与停止任务不受影响。
`decisionEngine` 支持 `auto`(默认)、`jev`、`executor`、`fixed`,也可用 `--decision-engine` 覆盖。只有指定非空 `model` 并提供凭据时,`auto`/`jev` 才调用 Jev。未指定模型、缺少凭据或 Jev 请求失败时,转交执行模型;固定策略需显式选择。Python 实际使用配置中的模型,并在动作日志保留概率、confidence 和实际决策来源。
不用 Jev 时可以省略配置文件:
```powershell
vendor\aalc\.venv\Scripts\python.exe -X utf8 scripts\jev_mirror_agent.py --decision-engine executor --seconds 1800
```
独立脚本在需要模型判断时输出 `requires_decision`,将页面观测、合法候选、当前局标识和请求标识写入 `decision_request.json` 及状态文件,随后释放连接与执行器互斥句柄。调用它的执行模型读取该请求,重新核对当前页面后处理动作,再用 `--resume` 继续同一局。请求文件是交接通知,旧请求不能直接用于输入。脚本本身没有访问当前聊天模型的 API。
嵌入执行端时,`scripts/decision_router.py` 的 `DecisionRouter` 及主脚本 `main(executor_decider=...)` 接受 `executor_decider(request)` 回调;返回候选 ID,或带同一 `request_id` 及 `choice` 的对象。回调只获得观测和候选,输入仍由执行器完成。未列出的候选、错误请求标识和无效概率会被拒绝。执行端应为自己的模型调用设置等待期限。长期混合执行器由这一接口接入当前执行模型,避免每个分支都重新启动脚本。
Jev 与 AALC 配置复用方案、离线页面样例及实测耗时统计见 [2026-10-03 自动化研究](docs/jev_aalc_automation_research_20261003.md)。
本轮修复、验证范围与已知限制见 [2026-10-03 运行可靠性改进](docs/mcp_runtime_improvements_20261003.md)。
本次修复、实际失败反馈、操作日志、截图清单、修改源码快照和速通 skill 见 [2026-10-02 实测记录](docs/feedback/2026-10-02/README.md);安装与测试说明见 [INSTALL_TEST_REPORT.md](INSTALL_TEST_REPORT.md)。这些是开发中的真实记录,包含失败和仍未验证的步骤。
[2026-10-03 主线实测与耗时复盘](docs/feedback/2026-10-03/README.md)记录了 4-48 未通关、三次 Jev 抉择耗时、混合操作限制、输入修复的验证边界及 94 项回归结果。
## 许可证
AALC 使用 AGPL-3.0。本项目会导入并运行 AALC 的代码,分发时需遵守 AGPL-3.0。