Files
lc-mcp/README.md
ywsandClaude Opus 5.5 dd4259d41b 实验: 编队列表滑动补丁重写 (默认关闭, LCP_TEAM_SCROLL_PATCH=1 启用)
替代 66418dc 中的版本, 只验证"Windows 缺少队伍拖拽规避"这一假设:
- 几何/行程沿用 AALC build_windows_scroll_swipe_plan, 不改变 Windows 翻页标定
  (原版两端各加 60px escape);
- 参照 MuMu 在脱离段后保持 0.1s、松手前停稳 0.5s;
- 显式等待驱动分段移动: 原版后台每段 duration<0.01s, AALC _mouse_move_to
  步数为 0, 一个移动事件都不发; 前台关闭 pyautogui 默认 0.1s 停顿
  (原版单次滑动约 4.4s);
- 默认不安装, 需实机在编队界面验证后再决定是否默认开启。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 03:58:35 +00:00

197 lines
13 KiB
Markdown
Raw Permalink 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 画面比例临时缩放,匹配结束后恢复内存中的原配置。
## 工具
| 工具 | 说明 |
|------|------|
| `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 张) |
| `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`
会把日志尾部的 `[ERROR]`/异常行放进 `errors` 字段:**看到 `succeeded` 也要先看 `errors`。**
### 实验:编队列表滑动补丁(默认关闭)
AALC 基类允许适配器覆盖 `mouse_swipe_for_team_scroll`“以规避队伍拖拽判定”,上游只有 MuMu 实现了。
`lc_mcp/aalc_input_patch.py` 在 Windows 前台/后台适配器上补了一个最小版本:几何与行程沿用 AALC 的
`build_windows_scroll_swipe_plan`(不改变 Windows 翻页标定),脱离段后保持 0.1 秒、松手前停稳 0.5 秒。
是否真有队伍被拖乱的问题尚无实机证据,所以默认不启用。验证方法:给常驻服务设置环境变量
`LCP_TEAM_SCROLL_PATCH=1` 后重启服务,跑一次需要选队的日常任务,核对选中的队伍、编队人数以及 `task_status` 的 `errors`。
## 环境变量
| 变量 | 默认 | 说明 |
|------|------|------|
| `AALC_DIR` | `vendor/aalc` | 使用其他位置的 AALC 源码 |
| `LCP_PORT` | 8765 | 服务/bridge 端口 |
| `LCP_KEEP_SHOTS` | 30 | 截图保留张数 |
| `LCP_TEAM_SCROLL_PATCH` | 未设置 | 设为 `1` 启用实验性的编队列表滑动补丁 |
## 开发 / 测试
### 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 # 不需要 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` 通过 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 --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。