# 对接说明:镜牢选队(2026-11-14) 给**云端开发**看的交接文件。目标:云端改代码 → 我这边 `git pull` → 实机回归 → 回传结果。 所以这里写清楚「改哪、别动哪、怎么验、验到什么程度算过」。 --- ## 1. 仓库与运行环境 | 项 | 值 | |---|---| | 仓库 | `https://git.lingll.icu/yws/lc-mcp` | | 当前分支 | `codex/feedback-unattended-setup-20261004` | | 本机路径 | `D:\lc-mcp`(AALC 在 `vendor/aalc`,**submodule,不要改**) | | Python | `vendor\aalc\.venv\Scripts\python.exe`(3.13) | | 游戏 | `D:\SteamLibrary\steamapps\common\Limbus Company`(Steam build 26593955) | | 汉化 | `LLC_zh-CN` 2026111301(自定义语言,游戏基础语言 = 韩语,OCR 语言识别为 `zh_cn`) | | 分辨率 | 客户区 1280×720,`set_win_size: 720` | | 常驻服务 | 计划任务 `LcMCPServer`,`127.0.0.1:8765`,日志 `~/lc_mcp/server.log` | **测试入口**(本机验证统一用这个,不要直接跑 `main.py`): ```powershell D:\lc-mcp\vendor\aalc\.venv\Scripts\python.exe -X utf8 -c "from lc_mcp import ..." # 单测 # 实机:通过 MCP 工具 run_task mirror,或 D:\lc-mcp\vendor\aalc\.venv\Scripts\python.exe -X utf8 -m lc_mcp.aalc_task mirror "{\"count\": 1}" ``` --- ## 2. 本次改动(两个文件,均为增量,不改 vendor) ### `lc_mcp/aalc_patches.py` 新增一段(文件末尾,`install_default_battle_team` 之后): ```python SYSTEM_TEAM_NAMES = {...} # 体系(system 字符串) → 游戏内编队名元组 TEAM_LIST_X_MAX / TEAM_LIST_Y_MIN / TEAM_LIST_Y_MAX # 左侧列表命中范围(客户区像素) TEAM_HEADER = (170, 520, 90, 150) # 顶栏队名位置,用来确认选中 _team_ocr(auto) -> [(text, x, y), ...] # 整屏 OCR 逐行结果(同名保留)清洗,不排序 _in_list(x, y) / _in_header(x, y) # 区域判定 _scroll_team_list(auto, direction, times, distance) # +1=回顶部, -1=往下翻 _header_is(auto, names) / _wait_header(auto, names) # 顶栏确认(3 次 × 1.2s,归一后精确匹配) _select_team_by_name(auto, names, log, rounds=4) # 主流程,返回 bool install_system_team_selection(log=print) # 安装补丁,返回原始 select_battle_team ``` ### `lc_mcp/aalc_task.py` - import 里加 `install_system_team_selection` - `run()` 里、`install_default_battle_team` 之后: ```python if task in ('mirror', 'all'): install_system_team_selection(log=log) ``` ### 挂载点为什么是 `tasks.mirror.mirror` `tasks/mirror/mirror.py` 在模块顶部 `from tasks.teams.team_formation import ... select_battle_team`, 之后 `select_mirror_team()` 用的是**模块全局名**。所以补丁必须替换 `tasks.mirror.mirror.select_battle_team`;改 `tasks.teams.team_formation.select_battle_team` 对镜牢无效 (日常本那条补丁 patch 的是 `scheme` 命名空间,两者互不影响)。 --- ## 3. 接口契约(改的时候必须保住) 1. **`select_battle_team(num) -> bool`**:True = 已选中并确认在编队界面;False = 没选上,调用方会重试(最多 6 次)后抛 `unableToFindTeamError`。 2. **不能有副作用**:补丁只点击,不写配置文件;`Mirror.__init__` 的包装只读 `team_setting`。 3. **坐标空间**:一律按**客户区像素**(当前 1280×720)。缩放用 `cfg.set_win_size / 1440`,跟 AALC 其它地方一致。 4. **`auto._run_ocr_for_text(my_crop=None)` 返回 `{text: [cx, cy]}`**:`cx/cy` 是 box 中心;同名文本会互相覆盖。只把它转成列表并不能找回被覆盖的那条——2026-11-14 复查起 `_team_ocr` 直接读 OCR 引擎的逐行结果(`module.ocr.ocr.run(auto.screenshot)`,同一引擎、同样取框中心),引擎导入不了才退回 dict。 5. **不要用 `my_crop` 做界面裁剪**:实测裁剪坐标语义不可靠(裁 `(0,0,190,584)` 会读到右侧面板),统一「整屏 OCR + 坐标过滤」。 6. **点完必须验顶栏**:只点不验会出现「日志说成功,其实没换队」。 --- ## 4. 体系队名表(本机账号实际状态,2026-11-14 截图核对) 左侧编队列表,从上到下: | 顺序 | 列表显示 | 说明 | `team_system` | |---|---|---|---| | 1 | 剧情关卡 | 剧情用预设 | — | | 2 | 斩击 | 打击体系队 | 7 | | 3 | 突刺 | 突刺体系队 | 8 | | 4 | 打击 | 打击体系队 | 9 | | 5 | 烧伤 | 烧伤体系队 | 0 | | 6 | 流血 | 流血体系队(**当前镜牢在用**) | 1 | | 7 | 震颤 | 震颤体系队 | 2 | | 8 | 破裂 | 破裂体系队 | 3 | | 9 | 沉沦 | 沉沦体系队 | 5 | | 10 | 呼吸法 | 呼吸体系队(代码里另有别名「呼吸」) | 4 | | 11 | 充能 | 充能体系队 | 6 | | 12+ | 编队#13 … 编队#40 | 默认名残留,未使用 | — | > `#1`~`#12` 已不存在。任何按 `编队#N` 找队的逻辑在这个号上都会失败,这是本次问题的根。 > > 队名改动后最好同步 `SYSTEM_TEAM_NAMES`。2026-11-14 起(BACKLOG P1-5)名字先归一(空白/全半角/`震颐`→`震颤` 等误读), > 精确匹配优先;没有精确匹配时接受这一屏**唯一**的「名字+后缀」(`流血队`),不做任意子串。顶栏确认仍只认精确。 --- ## 5. 验证方法 > 下面 5.2/5.3 是最初选队补丁的回归。2026-11-14 云端交付的整轮(寻路、选队容错、饰品、事件、商店、审计、AALC V1.6.1) > 回归清单见 [REGRESSION.md](REGRESSION.md)。 ### 5.1 单测(不需要游戏) ```powershell cd D:\lc-mcp vendor\aalc\.venv\Scripts\python.exe -m unittest discover -s tests -t tests -v ``` 本次新增 `tests/test_system_team_selection.py`,覆盖:映射表完整性、区域判定边界、 `install_system_team_selection` 的挂载/回退行为(用假模块,不依赖 AALC/Windows)。 ### 5.2 实机回归(需要游戏在运行) ```powershell # 1) 确认补丁挂上 # 日志里应有:[lc_mcp] patch: 镜牢按体系名选队 # 2) 起一局 run_task(task="mirror", count=1) # 3) 看这几行 # [lc_mcp] 镜牢体系 bleed -> 目标编队 流血 # [lc_mcp] patch: 已按体系名选中编队 流血 (或「当前已经是编队 流血, 无需切换」) # [INFO] 楼层识别结果:当前为第1层 ``` ### 5.3 验收清单 - [ ] `select_battle_team` 返回 True 后,顶栏队名 = 目标队名(截图为准,不看日志) - [ ] 连续两局:第二局走「已经是目标队,无需切换」分支 - [ ] 把 `team_system` 改成 7(斩击)能选到「斩击」;改回 1 能选回「流血」 - [ ] 目标名不存在时(例如临时改成 `编队#999`)能 4 轮内返回 False,不卡死、不乱点 - [ ] 列表滚动后不会把队伍页留在错误位置(后续 `罪人编队` 步骤仍能正常执行) --- ## 6. 云端开发注意事项 - **不要改 `vendor/aalc`**:submodule 固定 commit,改了本地能跑、更新就丢。所有行为差异走 `lc_mcp/aalc_patches.py`。 - **不要引入本机绝对路径**(`D:\...`、`C:\Users\YWS-HHH\...`);已有代码里 `LC_*` / `LCP_*` 环境变量是既有限制。 - **失败要显式**:选队失败返回 False 让上层重试,不要静默 fallback 到 `编队#N`(这号没有 `#N`,会选中错的队)。 - **日志格式**:沿用 `[lc_mcp] ...` 前缀,`task_status` 的 `errors` 扫描依赖 `[ERROR]`。 - 新增依赖请加到 `pyproject.toml`,并确认 `uv sync` 后 `vendor/aalc/.venv` 能跑。 --- ## 7. 拉取与回传 ```powershell cd D:\lc-mcp git fetch origin git checkout <云端分支> git pull git submodule update --init --recursive vendor\aalc\.venv\Scripts\python.exe -m unittest discover -s tests -t tests # 实机回归 → 结果写回 docs/feedback/<日期>/ ``` 我这边回归后会补:跑团日志、截图路径、验收清单勾选结果,以及新发现的问题。 本轮要勾的清单在 [REGRESSION.md](REGRESSION.md),勾选结果在 [REGRESSION-RESULTS.md](REGRESSION-RESULTS.md), 问题与需求台账在 [`docs/ISSUES.md`](../../ISSUES.md)。 2026-11-15 云端按台账交付的下一轮清单在 [`../2026-11-15/REGRESSION.md`](../2026-11-15/REGRESSION.md)。 --- ## 8. 部署:拉取后必须重启常驻服务 `TaskRunner` 在**常驻服务进程**里给任务子进程设 `LCP_DECISIONS` 等环境变量。 只 `git pull` 不重启,子进程拿到的还是旧环境 → `decisions.jsonl` 不生成、`task_status.decisions` 为空。 ```powershell Stop-ScheduledTask -TaskName LcMCPServer Start-ScheduledTask -TaskName LcMCPServer # 验证:Get-NetTCPConnection -LocalPort 8765 -State Listen ``` 2026-11-14 第一局就踩了这个:代码是新的、服务是旧的,`decisions.jsonl` 一直不落盘。