---
name: ballbattle-aiplay-yashu
description: 球球大作战无尽模式 AI 代打项目（AutoJS 手机端自闭环 + JEV 慢循环决策）。当用户要求「让 AI 自动玩球球大作战」「写/改代打脚本」「标定截图与摇杆参数」「设计或调优 JEV 决策判断」「定位代打脚本跑不起来的原因」，或需要迭代本技能自身时使用。
version: 4.0.0
agent_created: true
---

# 球球大作战 AI 代打（AutoJS + JEV）

**最终成品**：一个 AutoJS 工程。在手机**已进入球球大作战「无尽模式」之后**启动它 → 自己截图、自己识别、自己决策（**全本地**：aim.js 基线几何 + 逃命反射；JEV 已下线）、自己触控 → **目标（2026-09-25 二次改口径）：主动吃球长大是本局的意义，不被吃掉是前提——光活着不吃球没有意义**（逃命靠硬护栏⑥分身反射兜底：场上全是机器人、追不上弹射后的球，见 00 M15）。**签名确认死亡 ⇒ 脚本自己停**（老板 2026-09-25 改判；他再手动重开一局、重新启动脚本）。不做开局导航，不做结算页自动化，不点「免费复活」。

## 第 0 步（阻塞，不得跳过）

按当前要做的事，**先 Read 对应手册再动手**。这些手册是活文档，自进化会不断更新，**不要凭记忆，每次读最新的**：

| 你要干的事 | 先读 |
|---|---|
| **查游戏机制**、确认某条规则是否成立、给阈值找依据、写/改决策规则 | `references/00-游戏机制契约.md` |
| 首次真机跑 / 换手机 / 改分辨率 / 标定摇杆与色域 | `references/01-环境勘察与标定.md` |
| 改识别算法、改 state 输出、球认错或认漏 | `references/02-感知规范.md` |
| 改摇杆控制、**改按键点击（`press` / 吐孢速率红线）**、球不走或点不生效 | `references/03-快循环控制.md` |
| **改追吃/闪避/边界合成、加决策层日志、分析"为什么不吃旁边的小球"** | `references/03-快循环控制.md` **§三 + §3.6** |
| 接 JEV、改判断、调阈值、JEV 超时或答得离谱 | `references/04-JEV慢循环接入.md` |
| 脚本崩了 / 跑不出结果 / 要定位失败原因 | `references/05-实测与失败定位.md` |
| **问「脚本还活着吗 / 停掉了没有」「这局跑了多久」** | `node verify/pc/bb-alive.js`（一键判读，判据=中继任务单 + 手机 10s 心跳；`--selftest` 离线自检 10/10） |
| **改顶部悬浮条（HUD）文案 / 问「HUD 显示什么」/ 老板说显示看不懂或误导** | `references/05` **§3.7**；改完必跑 `node verify/pc/qiu-hud-smoke.js`（口径在纯模块 `lib/hud-text.js`） |
| 下发脚本到手机、拉截图、手机↔PC 通信、**标定/读取三个圆形按键坐标** | 走 `autojs-mobile-automation-yashu` 技能（按键：`qiu-btn-measure` / `qiu-btn-read`） |
| **查 AutoJS 图色 API**（截图/降采样/取像素/掩膜/找色/模板匹配）或**触摸手势 API**（`press`/`swipe`/`gesture`/`gestures(Async)`/`setScreenMetrics`） | 本项目实测要点与坑 → 本技能 `references/02-感知规范.md` **§七**；官方全文（6.8.0）→ `autojs-mobile-automation-yashu` 的 `references/autojs6_images_doc.md` 与 `references/autojs6_automator_doc.md`（**先 Grep 再局部读**） |
| 设计或改 JEV 判断本身（原语选择、state 组织、阈值标定方法论） | 走 `typesafe-jev-decision-yashu` 技能 |

## 红线（8 条，不可违背）

1. **决策全本地、快循环零网络请求（2026-09-25 老板两度改判，最终：JEV 整体下线）**：100ms 层纯本地执行；方向由 `aim.js` 本地基线决定，逃命由硬护栏⑥反射（`escapeReflex`，分身+吐孢两键齐发）接管。JEV 慢循环 2026-09-25 经老板拍板**下线**（"效果并不好，不要了"；工程 0.8.0 起 `ENABLE_JEV=false`，慢循环线程不启动、零 HTTP）。代码留档不删，判断表/成本实测见 `references/04`（顶部有下线公告）。
2. **任何模型都不吃画面**。决策只接受结构化 state（JSON）。永远不要把截图、像素、图像描述塞给决策层——识别必须在本地做完。（原"JEV 不吃画面"红线在 JEV 下线后同样适用于将来任何重启/替代模型。）
3. **先基线后 AI**。本地启发式基线没跑通之前不许接 JEV。否则失败了你分不清是 AI 弱、还是链路本来就弱。
4. **一次一个 UI 任务**。UI 操作串行下发，严禁并发。
5. **语法门禁不过不下发**。中继自带门禁，退出码 6 = 语法不过，改完再发。
6. **⛔ 永不把客户端引擎当停止目标**。清场只按任务单精确强杀，禁止全量 stop（细则见 `autojs-mobile-automation-yashu` 硬约束 7）。
7. **凭证不落盘**。`TYPESAFE_API_KEY` 只从环境变量或手机端本地配置读，**不得**写进任何脚本、日志、文档、汇报。
8. **自进化**——见下节。它是本技能的第一优先级，优先级高于"先把活干完"。

---

## 自进化（常驻，最高优先级）

**核心承诺：发现该改就当场改，不等用户提醒。** 改文档、改代码、改参数，都由本技能的 AI 自行判断并执行。

### 一、必须触发回写的场合（不给判定空间）

| 干完了这件事 | 必须回写什么 | 写去哪 |
|---|---|---|
| 真机跑通一次 | 标定出的**算法参数数值**（色域阈值、死区、边距、按压时长等）→ `01` 表 **且** `config.js` 常量，双写 | `01-环境勘察与标定.md` + `config.js` |
| 三个圆形按键（摇杆/吐孢子/分身）重新标定 | **什么都不用回写**——坐标是易变数据，只存手机端 `storages qiu-btn`，本技能只记**取法**（`01` §三）；确认 `qiu-btn-read` 返回 `ready:1` 即可 | 只在必要时更新 `01` §三 的取法说明 |
| 脚本崩了、定位到根因 | 现象 → 原因 → 修法，一条一条记 | `05-实测与失败定位.md` |
| 发现文档写的与实测不符 | **删掉错的**，写对的 | 对应文档 |
| JEV 实测延迟 / 成本 / 行为与预期不符 | 更新预算表与判断表 | `04-JEV慢循环接入.md` |
| 改了 `config.js` 里任何常量 | **同步**改对应文档的阈值表 | `04` 或 `01` |
| 改了识别算法 | 同步改 state schema 与算法说明 | `02-感知规范.md` |
| 官方文档（TypeSafe / AutoJS）有更新 | 按它订正对应部分 | 对应文档 |
| 阶段目标达成 | 更新下方「阶段与当前进度」 | 本文件 |

**节奏**：遇到才改，**不做全库主动审计**。改动在本轮任务内**当轮落盘**，不留"待办事项"。

### 二、双写一致性（最容易被破坏的一条）

代码常量与文档阈值表**必须始终一致**。只改一边 = 改动未完成。改任一边时，**同一轮内**改另一边。

### 三、授权分级

| 级别 | 判定 | 授权 |
|---|---|---|
| **直接改，不问** | 事实订正 / 删已证伪的句子 / 补实测结论 / 标定参数 / 修 bug / 调阈值 / 改识别算法 / 新增踩坑记录 | 直接执行 |
| **先报备，等确认** | 改下列任一红线 / 改架构结论（如改成 PC 主控）/ 删整节 / 改阶段目标 | 停下来说明理由，等用户点头 |

**红线不可自改**：快循环不过大模型 / JEV 不吃画面 / 先基线后 AI / **停机规则**（**签名确认判死 ⇒ 脚本自停**；⛔ 禁止用「self 丢 N 帧」等**不可靠判据**停机；⛔ 不点「免费复活」、不做结算页自动化、不自动续局）/ 手机端自闭环。这五条被自进化掉，整个项目就没人守了。

### 四、版本号（frontmatter `version`，每次改动必须递增）

| 位次 | 判定 | 推送 |
|---|---|---|
| patch（0.1.**x**） | 订正错误、补实测数值、改参数 | 落盘 + commit，**不推送** |
| minor（0.**x**.0） | 新增知识、新增文档、新增代码模块 | 落盘 + commit + 推送（有远程时） |
| major（**x**.0.0） | 结构性重写、红线变更、阶段目标变更 | 落盘 + commit + 推送（有远程时） |

**不递增版本号 = 改动未完成。** 不记变更历史（不写 CHANGELOG），历史交给 git。

### 五、活文档与删错门槛

- **只留正确的知识**。被硬证据证伪的内容**当场删干净**——不并存、不标注、不归档。
- **删错门槛**：只有硬证据（真机实测 / 官方文档原文 / 可复现反例）才动手删。仅"我觉得可疑"不动手——误删一条对的知识比留着错知识更难发现。
- **改完必做**：在同一轮汇报里列出改动清单（改了哪些文件、各改了什么、版本号从哪到哪）。

---

## 依赖的两个技能

| 技能 | 什么时候用 | 它负责什么 |
|---|---|---|
| `autojs-mobile-automation-yashu` | 下发脚本、拉截图、手机↔PC 通信、看真机画面、**标定/读取三个圆形按键坐标** | 执行中继（PC → 手机）；按键坐标的标定与读取也归它（`qiu-btn-measure` / `qiu-btn-read`） |
| `typesafe-jev-decision-yashu` | 设计 JEV 判断、选原语、组织 state、标定阈值、排查 JEV 失效 | TypeSafe 集成方法论（它自己会再加载 `typesafe-ai`） |

**引用方式**：进入 JEV 相关工作时，用 Skill 工具加载 `typesafe-jev-decision-yashu`，按它的执行顺序走，不要自己另起一套。它产出的判断主表与阈值契约表，**回填到本技能的 `04-JEV慢循环接入.md`**。

---

## 阶段与当前进度

| 阶段 | 内容 | 状态 |
|---|---|---|
| **1** | 链路跑通：截图 → 识别自己球与其他球 → 摇杆持续控制 → 60 秒不崩 | **完成**（2026-09-24 v0.5.0 实机验收通过：393s 连续运行 1884 帧、guard 零违规、stick=标定值 457/964/231、圆盘原位、方向正确、不崩；require 实例分裂根因已定罪并修复，见 05 §3.4） |
| **2** | 本地启发式基线（先活命后吃球：闪避威胁 > 追吃最近可食球），采数 | **进行中**（baseline 策略已随 v0.5.0 实机跑通；感知层「碎片聚合+几何筛选+self 组识别」随 v1.1.0、低饱和盲区修复 + UI 簇级软判据随 v1.2.0（8 图真机回归）完成；**决策层可观测性**随 v1.3.0；**贴身遮挡补偿 +「尺寸不可信」护栏**随 v1.4.0 落地，真机验证局腿② 触发 22 次、全部贴脸、零假阳性（腿① `occl_boost`/`occl_unreliable` 仍是死字段、待补出口，见 03 §3.6.1）；**局边界判死**随 **v1.4.2** 重做——原 `ROUND_T_DEATH_FRAMES=40`（实测 3.33 fps ⇒ **12.0 s**）比复活页寿命（10 s）还长，于是"真死必现的复活页"被稳定漏判、两次 `round_end` 全落在其后的绿色结算页；改为 **12 帧** + 复核 **2 帧**，新增**签名 C「左绿右金」按钮几何**（主判据），并把签名 B（`dark≥.65` 在真机对局帧 15 张里有 11 张过线）**降级为旁证**；算法抽成 `lib/settle-sign.js` 纯模块 + `verify/pc/qiu-settle-smoke.js` 离线回归（复活页 3/3 命中、绿页 4/4 排除、**真机对局帧 15/15 零误报**），见 05 §3.6）。**新判死真机验证通过**（2026-09-25 01:30，`ballbattle-1790271041228.jsonl` / 620 行 / 1 局 / 存活 87.2 s）：self 于 f287 起丢（复活页窗口 33 帧 = 9.9 s），`dying_trigger` 在 **f299 / 3.9 s**（旧参数需 12.0 s ⇒ 必看其后的绿色页），`settle_check` **一枪命中 `sg=C` / `why=respawn_struct`**，抓到时距窗口结束**还剩 6.3 s 余量**；判据实测 `green .01 / dark .74 / midY .10` 与标定复活页一致；判死后仍零输入（红线未变），见 05 §4.3）。**判死即自停已落地**（**v1.4.4**，老板 2026-09-25 指令：球死 → 脚本自己停 → 他手动重开一局再启动；判据**只能是签名确认的判死**，离线回归 `verify/pc/qiu-round-smoke.js` **17/17 通过** + 全量真机帧「**死亡页 7/7 停机、对局帧 15/15 不停机**」；同时按 05 §3.5 教训**删净**旧 `STATE_DEAD` 等重生逻辑与 `BIRTH_CONFIRM_FRAMES`，不留"不会踩中的代码"）。**⚠️ 目标口径已二次变更（2026-09-25，见顶部）：吃球是意义、活命是前提（原「主指标=存活时长；不关心吃球」口径作废）。** **判死即自停真机验收通过**（2026-09-25 01:54–02:00，task `t0925_015445_b8d0` / 354 帧 / 存活 **115.5 s**）：`dying_trigger` f266 → `settle_check` **一枪命中 `sg=C`** → `round_end` → `end.stop_reason="death:respawn_struct"` → **脚本自己退出、任务转 success**，触发到判定仅 **182 ms**（远快于复活页 10 s 寿命）；同局 `guard` 零违规、self 盲帧 **6.5%**（上轮 39.1%），见 05 §4.4。**P0-1/P0-2 全部关闭 ⇒「活着」链路地基完成。** **P0-b HUD 观感修正已关闭（工程 0.6.6）**：self 丢失期第一段改显 `丢N帧`、丢失期**绝不再说"活"**（旧口径下 self 连丢 13 帧仍显示 `自:0 ｜ 游戏界面 ｜ 活`，老板反馈"有误导性"）、判死确认后悬浮条多停 `HUD_DEATH_HOLD_MS`=1500ms 再关窗；文案抽纯模块 `lib/hud-text.js` + 离线回归 `verify/pc/qiu-hud-smoke.js` **16/16**。**真机核对（2026-09-25 02:11 局）**：`start.version=0.6.6`、截屏目视 `自:1 ｜ 游戏界面 ｜ 活` 渲染无裁字、`guard` 零违规、self 丢失 **0.7%**、1003 帧 / 293s / 3.42 fps，见 05 §4.5（丢失态文案 `丢N帧…活?` 该局未出现，仍待下次真机目视）。**下一步：把「活着」做长 —— 死因归因闭环（P1-1）、腿① 日志出口（P1-2）、self 盲区压缩（P1-3）**；待：0.93/1.02 阈值重估（**方向改为保守**：宁可不吃）、`MAX_BALLS` 截断策略、Hough 半径双向偏差、追吃选择规则调优、活命权重调优） |
| 3 | JEV 慢循环接入，与基线对照 | **⛔ 已下线（2026-09-25 老板拍板："JEV 大模型效果并不好，删了吧，我们不要了"）** —— 工程 **0.8.0** 起 `ENABLE_JEV=false`、慢循环线程不启动、**零网络**；决策回到本地（阶段 2 基线 + 护栏⑥逃命反射，反射分身+吐孢两键齐发）。留档：判断表/护栏/成本实测见 `references/04`（顶部下线公告）；drive 真机战绩：存活 8m32s 新高、判死自停链路走通、模型按键 253/253 全零（05 §4.6–4.8）。**下一步：回到阶段 2 打磨本地基线（追吃/闪避权重、活命能力），用"存活时长 + 吃球成长"衡量** |
| 4 | 调参迭代 | 未开始 |

**进度更新规则**：阶段状态有变，直接改本表——这是自进化的一部分，不用问。

---

## 真机跑一局的固定动作

1. 用户先手动打开球球大作战并**进入无尽模式**（技能不负责这一步）。
2. 通过 `autojs-mobile-automation-yashu` 的部署与运行入口，把 `scripts/autojs-project/ballbattle-aiplay/` 下发到手机并启动。
3. 全程观察：PC 侧跑 `node verify/pc/bb-alive.js`（或 `--watch 5` 常驻）看**脚本是否在跑 / 已存活多久**；手机侧看**悬浮窗 HUD** 与**球是否在动**。HUD 口径见 `05 §3.7`：**self 丢失期第一段显 `丢N帧`、生死段不再写"活"**（`丢1帧 ｜ 游戏界面 ｜ 活?`），判死那一帧显 `丢N帧 ｜ 判死确认 ｜ 死·停` 并停留 1.5 s。
4. 局末**判死即自停**（v1.4.4 起）：签名确认死亡 ⇒ 脚本自己收尾退出，日志 `end.stop_reason = "death:<why>"`，任务单转终态——老板只需手动重开一局、重新启动脚本。异常退出按 `05-实测与失败定位.md` 定位后回写。

> 具体命令、模板名、路径约定一律以 `autojs-mobile-automation-yashu` 的当前文档为准，**本技能不复述它的用法**。
