Files
lc-mcp/docs/feedback/2026-11-14/HANDOVER.md
T
Codex Agent 599282729c 镜牢入场前切队 + 选队页守卫;补回归结果与问题需求台账
实机回归发现: 镜牢入场时 AALC 直接点「进入」, 根本不走 select_battle_team,
用的是游戏记住的旧队伍; 「星之恩惠」页满屏星星又会让「选队星级」模板误命中。

- aalc_patches: 点「进入」前若在选队页且顶栏不是目标队, 先按体系名切队(充能优先,
  没有就震颤); 新增选队页守卫(只有出现「恩惠」字样才忽略星级模板); 选队扫描从每轮
  3 次拖动改为 1 次(3 次会整屏跳过, 实测漏掉「充能」)
- tests: 44→45 个用例, 覆盖偏好顺序、星之恩惠判定、守卫行为
- docs: REGRESSION-RESULTS.md(勾选结果), ISSUES.md(问题/需求台账),
  BACKLOG 状态表, HANDOVER 补「拉取后必须重启服务」

单测: 641 passed。实机: 2026-11-15 01:51 入场精确选中「充能」。
2026-11-15 02:03:27 +08:00

184 lines
8.5 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.
# 对接说明:镜牢选队(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)。
---
## 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` 一直不落盘。