Files
lc-mcp/README.md
T

156 lines
8.7 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 | 截图保留张数 |
## 开发 / 测试
### 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 完整任务或另一个游戏执行器同时操作。
中途续跑沿用 `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)。这些是开发中的真实记录,包含失败和仍未验证的步骤。
[2026-10-03 主线实测与耗时复盘](docs/feedback/2026-10-03/README.md)记录了 4-48 未通关、三次 Jev 抉择耗时、混合操作限制、输入修复的验证边界及 94 项回归结果。
## 许可证
AALC 使用 AGPL-3.0。本项目会导入并运行 AALC 的代码,分发时需遵守 AGPL-3.0。