Files
lc-mcp/README.md
T
ywsandClaude Opus 5.5 030527f5de 审查修复: 任务配置恢复、执行器容错与续局状态、识别性能
正确性
- stop_task 强杀后 run_task 的临时次数会残留在 config.yaml (AALC 中途整份存盘);
  任务启动时先落盘原值, 强停/异常退出后由 TaskRunner 用 --restore 写回,
  写回失败时拒绝启动新任务并在 task_status 显示 pending_restore
- Jev 执行器: 工具失败不再抛异常导致整局退出 (Session raise_on_error=False),
  原有的"截图暂不可用"等降级分支终于生效; 刷新计数/开战标记只在动作成功后更新
- 一局完成后归档 jev_shop_context.json, 否则 claim_requested 让下一局一启动就判定完成
- 通用按钮直接点已核对的坐标, 不再 click_text 重新搜索 (可能点到背景同名按钮)
- 认证行按字节比较, 非 ASCII 输入不再让 compare_digest 抛 TypeError
- 单实例互斥改用 use_last_error 读取 ERROR_ALREADY_EXISTS

性能
- find_image 只在窗口尺寸变化时清模板缓存 (原来每次两次全量 gc); 模板列表只扫描一次
- 截图 PNG 压缩级别 1: 1080p 存图 0.66s -> 0.19s
- 执行器每帧截图只解码一次 (button_enabled 75ms -> 0.3ms); 地图模板与 ORB 描述子按比例缓存
- 箭头模板用 imdecode 读取, 支持中文路径 (输出与 imread 逐像素一致)

测试 73 -> 84, 修改前的识别输出与修改后逐项比对一致。

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

132 lines
7.2 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 画面比例临时缩放,匹配结束后恢复内存中的原配置。
## 工具
| 工具 | 说明 |
|------|------|
| `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`,并在写回成功前拒绝启动新任务。
## 环境变量
| 变量 | 默认 | 说明 |
|------|------|------|
| `AALC_DIR` | `vendor/aalc` | 使用其他位置的 AALC 源码 |
| `LCP_PORT` | 8765 | 服务/bridge 端口 |
| `LCP_KEEP_SHOTS` | 30 | 截图保留张数 |
## 开发 / 测试
```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 完整任务或另一个游戏执行器同时操作。
中途续跑沿用 `jev_shop_context.json`;一局领取完成后它会归档为 `jev_shop_context.<时间>.json`,下一局从干净状态开始。
工具调用失败(截图暂不可用、按钮已消失等)会记入日志并重新观察画面,同一画面上同一动作最多尝试两次,不会因单次失败整局退出。
本次修复、实际失败反馈、操作日志、截图清单、修改源码快照和速通 skill 见 [2026-10-02 实测记录](docs/feedback/2026-10-02/README.md);安装与测试说明见 [INSTALL_TEST_REPORT.md](INSTALL_TEST_REPORT.md)。这些是开发中的真实记录,包含失败和仍未验证的步骤。
## 许可证
AALC 使用 AGPL-3.0。本项目会导入并运行 AALC 的代码,分发时需遵守 AGPL-3.0。