OneDragon-Anything · DoctorReid · Jul 19, 2026 · Jul 19, 2026 · Jul 19, 2026 · Jul 19, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -100,6 +100,12 @@ uv run --env-file .env ruff check --fix src/你修改的文件.py
 - **共享先确认**：入口文件团队共享，改前问用户，不静默重写。
 - **写得清晰易懂**：改入口文件 / 方法论文档时，用直白表述（首次出现的术语给定义 + 给例子），让首次接触的 AI 也读得懂；术语定义指向 [context_layering](docs/develop/harness/context_layering.md) / [entry_files](docs/develop/harness/entry_files.md)。
 
+## 改/建 skill
+
+**创建 / 修改任何 skill 前，先触发 `zzz-od-dev-skill-guide`**（即使你正在另一个 skill 的流程里，如改 `zzz-od-dev-screen-onboarding` 时 —— 改 skill = 触发 skill-guide，不论当前在哪个流程）。它的 4 条硬规范里两条最易漏、现普遍未遵循：
+- **同步该 skill 的 `design.md`（若有）**：改重要决策时，在该 skill 的 `design.md` 记「为什么这么定」（不只改 SKILL.md），避免后续不知道原意改坏。**这是项目 `zzz-od-dev-*` skill 的约定**（`zzz-od-dev-skill-guide` 规范 1），第三方 / `superpowers:*` skill 无此约定 → **先看 skill 目录有没有 design.md，有就更新**。⚠️ skill **本体在根 `skills/<name>/`**（项目源、稳定）；各 AI 工具用各自方式加载（可能映射 / 链接到别处，那是工具特定的加载路径）→ **查 / 改 skill 文件到本体（根 `skills/`），别查工具的加载映射路径**（映射不一定是真文件，搜索会漏）。
+- **SKILL.md 写方法论，不写跟外部代码强相关的具体内容**（函数名 / 测试 API / 具体路径 / 行号）—— 易变，外部代码改了 skill 没跟上会误导；具体例子 / 踩坑进 design.md。
+
 ## 产出前先判断：信息放哪、写什么
 
 写 doc / skill 前（以及信息重复、边界不清时），先判断放哪层、写什么，别盲目堆：

diff --git a/docs/develop/zzz/backend/design-principles.md b/docs/develop/zzz/backend/design-principles.md
@@ -101,6 +101,11 @@ tool 按服务 / 资源分组前缀(如 `game_*` / `run_*`),帮智能体在多 s
 观察类 tool(如 `analyze_screen`)默认只在内存处理观测(截图 → OCR / 匹配),**不落盘**。但调用方若想对**同一帧**做二次分析(典型:喂给 vision double-check),重新取观测 = 第二次截图、且画面可能已变。故观察类 tool 可**可选地**把已取的观测样本顺手持久化并回传路径(例 `analyze_screen(save_image=True)` → `screenshot_path`),供调用方复用 —— **默认关闭、opt-in**,避免无谓落盘。
 (与 P6「返回智能体友好」协同:路径锚点让智能体关联观测样本;与 P3「操作 vs 观察分离」协同:持久化是观察的可选副作用,docstring 标注,不改变观察语义。)
 
+### P14. 观察类工具可返回能力边界提示
+观察类 tool(如 `analyze_screen`)的输出是**部分识别**(OCR 文字 + 已建模模板命中项),不保证覆盖画面全部视觉信息。智能体易把它当「画面全貌」下判断 → 状态 / 布局判断不完整。故观察类 tool 可在返回里**主动带能力边界提示**(如 `vision_hint`),引导智能体在需要全面理解时补一步视觉工具 / 多模态。
+
+与 P1「capability over compensation」的边界:这不是**新增 tool 补偿模型弱点**(那是债),而是**陈述该 tool 的客观固有能力边界**(它本就只做部分识别,边界永远成立)—— 即使模型变强到总自觉用 vision,字段描述的事实仍真实。承载引导的事实独立成立,故非临时补丁。与 P6(返回智能体友好)/ P13(可选持久化复用同帧)协同:路径给复用入口、提示给「为什么该复用」,形成完整 nudge 链路。
+
 ## 4. 能力分配总表
 
 | 需求 | 智能体自己 | MCP | skill |

diff --git a/docs/develop/zzz/backend/mcp.md b/docs/develop/zzz/backend/mcp.md
@@ -10,7 +10,7 @@
 |---|---|---|
 | `check_game_window` | `backend.check_window()` | `WindowStatus`（结构化 JSON；backend 抛错时返 `{'error': ...}`） |
 | `capture_game_screen` | `backend.capture()` | 截图绝对路径（落盘 `.debug/zzz_od_mcp/screenshot/`） |
-| `analyze_screen(screenshot=None, save_image=False)` | `backend.analyze()` | `AnalyzeScreenResult`（结构化 JSON；实时 + `save_image=True` 多回传 `screenshot_path`） |
+| `analyze_screen(screenshot=None, save_image=False)` | `backend.analyze()` | `AnalyzeScreenResult`（结构化 JSON；实时 + `save_image=True` 多回传 `screenshot_path`；success 时带 `vision_hint` 能力边界提示） |
 | `upsert_screen_area(screen_name, area_name, pc_rect, ...)` | `backend.upsert_screen_area()` | `{success, action(inserted/updated), area_count, error}`（写 yml + reload） |
 | `delete_screen_area(screen_name, area_name)` | `backend.delete_screen_area()` | `{success, action(deleted), area_count, error}`（写 yml + reload） |
 | `open_game(enter=True, block=True)` | `backend.start_run('mcp', op_factory)`（`enter=False`→`OpenGame`，`enter=True`→`OpenAndEnterGame`） | `block=True`：结果文本；`block=False`：已启动 JSON；并发拒绝时返错误 JSON |
@@ -36,6 +36,7 @@
 - backend 实例通过闭包注入 tool，不使用全局单例，也不让 FastMCP lifespan 管 backend 生命周期。
 - `capture_game_screen` 落盘返回路径；`analyze_screen` 返回结构化 dataclass，由 FastMCP 序列化。
 - `analyze_screen(save_image=True)`（实时模式）把已截的内存图顺手存盘 + 回传 `screenshot_path`，供调用方喂 vision double-check；默认 `false` 不落盘，离线模式忽略。
+- `analyze_screen` 成功时返回 `vision_hint`：提醒本结果仅含 OCR + 模板匹配的部分识别，不等同完整视觉理解，需要全面判断画面时配合视觉工具 / 多模态再看（能力边界提示，[design-principles.md](design-principles.md) P14；防智能体把部分识别当画面全貌）。失败时为 `null`。
 - 所有运行（`open_game` / 一条龙 / 独立应用 / 自定义 op）经**同一个 `RunSlot`** 派发：op 路径（`open_game` / `run_operation`）槽自管 `start_running/execute/stop_running`，app 路径（`run_one_dragon` / `run_standalone_app`）委托 `run_application`（复用 GUI/CLI 共享入口）。`block=True` 用 `asyncio.wrap_future(future)` 阻塞 await 取结果，`block=False` 立刻返回已启动状态，后续用 `get_run_status` 查进度。
 - `run_operation` 是**通用 operation 运行入口**（不框死为调试）：`op_id` 格式 `<dotted module path>.<ClassName>`（可从 `list_operations` 获取）；`args` 传构造参数，以 `cls(ctx, **args)` 烤进闭包——仅限 JSON 可序列化标量/列表/字典，复杂数据类参数（`ChargePlanItem` 等）拒绝并提示走 application；先用 `describe_operation` 看参数 schema。
 - 配置刷新：app 路径在 `run_application` 前（槽线程内、`_start` 已赢锁后）刷新当前进程的 YAML 配置缓存，对齐 GUI 已保存设置；`list_applications` 与 `list_operations` 是只读路径，不刷新。

diff --git a/docs/game/gameplay/式舆防卫战.md b/docs/game/gameplay/式舆防卫战.md
@@ -0,0 +1,102 @@
+---
+gameplay_name: 式舆防卫战
+involves_screens: [式舆防卫战, 式舆防卫战-三间选择, 快捷手册, 战斗画面]
+---
+
+# 式舆防卫战(玩法)
+
+绝区零**终局战斗玩法**(endgame combat),限期击败所有敌人领奖。画面见 [式舆防卫战.md](../screens/式舆防卫战.md)。
+
+## 这是什么
+
+式舆防卫战是绝区零的终局战斗挑战,定位类似其他游戏的「深渊」——考验配队练度 + 属性克制,通关给菲林(抽卡货币)等周期奖励。
+
+**解锁**:绳网等级(Inter-Knot Level)20,完成绳网声誉升阶任务后开放(Game8)。**剧变节点**需**先通关稳定节点全部 10 关**才解锁(Fandom wiki)。
+
+**入口**:快捷手册 → 作战 tab → 式舆防卫战「前往」→ 传送(见 [快捷手册](../screens/快捷手册.md))。
+
+## 三大节点类型(玩法核心区分)
+
+式舆防卫战含**三种节点**,玩家视角含义不同(来源:Fandom wiki + Game8):
+
+| 节点 | 中文 | 防线数 | 刷新 | 时限 | 评分依据 |
+|---|---|---|---|---|---|
+| Stable Node | 稳定节点 | 10 | **永久**(一次性) | 有(10 分钟) | 消灭敌人 + 剩余时间 |
+| Disputed Node | 纷争节点 | 8 | **永久**(一次性) | **无** | 角色存活(不被击倒) |
+| Critical Node | **剧变节点** | 5(2.5 改版) | **每 14 天重置**(双周五 04:00) | 有(10 分钟) | 消灭敌人 + 剩余时间 |
+
+- **稳定 / 纷争节点**:永久常驻,一次性通关即可(练度够了打一次永远不用再打)。
+- **剧变节点**:**周期刷新**,每期重置进度可重新领奖 → **这是脚本能反复跑的价值所在**(app `shiyu_defense` 只自动化剧变节点,代码 `TransportByCompendium('作战', '式舆防卫战', '剧变节点')`)。
+
+## 玩法目标
+
+打满当期**剧变节点 5 个防线**,达成挑战目标拿**最高评级(S)**,领满周期奖励。
+
+里程碑:防线 1 → 5 逐个攻克;每防线 2 个挑战目标(如「剩余时间≥X」「消灭所有敌人」),全达成 = S 评级 = 满奖励。
+
+## 核心机制
+
+### 弱点 + 抗性(配队依据)
+每防线分 **2 个半场(1st Half / 2nd Half)**,各自显示:
+- **推荐属性(弱点)**:用这些属性的代理人伤害更高。
+- **敌人抗性**:这些属性的代理人伤害被削,避免用。
+
+据此为每个半场配克制队 —— 这是「配队策略」核心。脚本 `calc_teams` 就是按弱点匹配预备编队(见附录)。
+
+### 防线效果(Frontier Effect)
+每期剧变节点有**整期共享的特殊增益**(如「冰属性伤害+10%、异常精通+40」),利用效果配队更易通关。2.5 改版后所有防线共享同一效果(来源:Game8)。
+
+### 快速扫荡(Quick Sweep)—— 周期跳关机制
+- 上季**防线 5 评 S** → 下季**防线 1-3 自动 S**(跳过)。
+- 上季**防线 4 评 S** → 下季**跳过防线 1-2,从防线 3 开始**。
+
+⚠️ **这是 issue #2506 的玩法根因**:新一期可能从**中间防线**开始(上季成绩决定跳关),脚本要 OCR「剧变节点进度 X/Y」判断从哪个防线继续,不能无脑从防线 1 开始(见 [画面 doc](../screens/式舆防卫战.md)「剧变节点进度」)。
+
+### 防线 5 = 多间模式(2.5 改版新增)
+防线 5 拆成 **3 个独立房间(Room)**:
+- 每房间**独立配队**,代理人/音擎/驱动盘**锁定不共享**(A 房用了的装备 B 房不能用)。
+- 每房间累积战斗得分:击败 Normal/Elite/Boss = **100/500/8000 DMG Score** + 击败 Normal/Elite 一次性 **100/500 Elimination Score**(基础满分 10000);时间倍率 60/70/80/90/105/120/135/150s 内 = **4/3.2/2.5/2.0/1.5/1.0/0.6/0.3x**(应用后满分 50000)。来源:Fandom wiki。
+- 画面见 [式舆防卫战-三间选择](../screens/式舆防卫战.md)(screen_info `shiyu_defense_select_3.yml`)。
+
+## 核心资源(奖励)
+
+剧变节点**全防线 S 评级**总奖励(来源:Fandom wiki):
+
+| 资源 | 数量 | 作用 |
+|---|---|---|
+| 菲林(Polychrome) | 780 | 抽卡货币(核心价值) |
+| 调查绩点(Investigation Merits) | 1080 | 调查商店货币 |
+| 高保真母带(Hi-Fi Master Copy) | 5 | 角色升级材料 |
+| 音擎晶片(W-Engine Chip) | 3 | 音擎强化材料 |
+| 丁尼(Denny) | 350,000 | 金币 |
+
+> 稳定节点全通 = 3000 菲林(一次性);纷争节点全通 = 1600 菲林(一次性)。这两类打一次永久领完,脚本能反复跑的只有剧变节点(每期 780 菲林)。
+
+## 周期
+
+- **剧变节点**:每 **14 天**(双周五 04:00)重置,进度清零,可重新领奖。
+- **稳定 / 纷争节点**:永久常驻,无需周期关注。
+
+日常节奏:剧变节点刷新那周跑一次脚本即可(周限倒计时显示在选关主界面,如实测「距本次作战终止还有 04 天 13 时」)。
+
+## 入口
+
+大世界 → 快捷手册(右上角)→ 作战 tab → 式舆防卫战「前往」→ 传送确认 → 剧变节点选关主界面。
+
+## 附录:自动化实现(app `shiyu_defense`)
+
+⚠️ **只自动化剧变节点**(稳定/纷争是永久一次性,玩家手动通一次即可,不值得写脚本)。
+
+**普通防线(1-4)节点链**:
+传送(TransportByCompendium 作战/式舆防卫战/剧变节点)→ 等加载(关"前次行动最佳记录"弹窗 + 等"前哨档案")→ 选择节点(OCR 剧变节点进度 X/Y 首尾数字法判断从哪开始,#2510)→ 识别弱点算配队(`calc_teams`,2 半场弱点+抗性 → DFS 选预备编队,避代理人冲突)→ 选配队(`ChoosePredefinedTeam` 点编队名+200px)→ 出战(Deploy)→ 自动战斗(`ShiyuDefenseBattle`,每半场一次,op 内部移动+战斗+阶段切换)→ 下一节点(战斗结束-下一防线/退出)→ 所有节点完成 → 领奖(奖励入口→全部领取)→ 关闭奖励 → 返回大世界。
+
+**防线 5(多间模式)**:选节点-05 → 三间选择(`calc_teams_for_multi_room` 3 房配队)→ 循环{前往第N间 → 实战模拟室预备编队 → 出战 → `ShiyuDefenseBattle` → 战斗结束-退出}→ 返回主界面 → 领奖。
+
+**关键 op(`ShiyuDefenseBattle`)内部**:等战斗画面 → 检测防卫战倒计时(pipeline)→ 有倒计时=战斗中跑 auto_battle / 无倒计时按距离移动(move_w)→ 一层敌人清完(连续5秒无倒计时)→ `move_after_battle`:检测距离/传送点(防卫战空洞传送点 pipeline)/按键-交互 → 自移动 + F 交互进下一层 → 直到该半场胜利。**op 完整封装移动+战斗+阶段切换,不需外部干预**(详见 [画面 doc](../screens/式舆防卫战.md)「选配队与触发战斗」)。
+
+## 信息来源与置信度
+
+- **玩法机制(节点类型/弱点抗性/快速扫荡/多间规则/奖励数字)**:Fandom wiki(Shiyu Defense/Critical Node)+ Game8(Shiyu Defense Guide and Reset),2026-07-19 查证。
+- **实拍确认**(2026-07-19):选关主界面(前哨档案+节点01-05+剧变节点进度 3/5→OCR 连写 315)/ 弱点编队界面(2 阶段弱点抗性)/ 预备编队管理+选队 / 战斗画面(移动触发)/ 一层结束(距离+入口)/ 入口前可交互(按键-交互+F)。
+- **代码反推**:`shiyu_defense_app.py`(节点链)/ `shiyu_defense_battle.py`(ShiyuDefenseBattle op 内部)/ `shiyu_defense_team_utils.py`(calc_teams)/ screen_info `shiyu_defense.yml` + `shiyu_defense_select_3.yml`。
+- **待确认**:2.5 改版后防线数(代码节点-01..05 = 5,与 wiki 一致);多间模式 3 房间规则(代码 ROOM_NAMES = 3,与 wiki 一致)。奖励数字以 wiki 为准(脚本不读奖励,仅通关领奖)。
diff --git a/docs/game/screens/3D地图.md b/docs/game/screens/3D地图.md
@@ -2,7 +2,7 @@
 screen_name: 3D地图
 appears_in: [大世界, 传送]
 last_updated: 2026-07-18
-source_image: map_3d_default
+source_image: screens/3D地图/默认.webp
 status: 默认态(立体俯视)已建;子区域/筛选/图标/前往流程待补截图
 ---
 

diff --git a/docs/game/screens/README.md b/docs/game/screens/README.md
@@ -12,6 +12,8 @@
 | 加载画面 | [加载画面.md](加载画面.md) | 通用加载画面(lore 轮换);screen_info 缺口 |
 | 大世界 | [大世界.md](大世界.md) | Overworld 主画面(活动入口/任务/快捷键);已建模(is_precise) |
 | 战斗画面 | [战斗画面.md](战斗画面.md) | 战斗实动作界面;战斗态稳定锚点=攻击按钮模板(id_mark 无,框架走 is_normal_attack_btn_available);子态:默认/精英(BOSS血条)/限时(倒计时)/战斗结果 |
+| 式舆防卫战 | [式舆防卫战.md](式舆防卫战.md) | 周期战斗玩法(快捷手册-作战入口);选关主界面(前哨档案+节点01-05+剧变节点进度)+弱点/编队/战斗/领奖多子态;剧变节点进度 OCR 连写(3/5→315,#2510) |
+| 快捷手册 | [快捷手册.md](快捷手册.md) | 玩法总入口(大世界右上);5 TAB(目标/日常/训练/作战/战术),各玩法卡片「前往」传送;TransportByCompendium 经此 |
 | 邮件 | [邮件.md](邮件.md) | 每日领取邮件附件(菜单→邮件);列表态 + 确认弹窗子态已建档 |
 | 菜单-更多功能 | [菜单-更多功能.md](菜单-更多功能.md) | 菜单点「更多」;功能入口枢纽(预备编队/兑换码/登出);已建模 |
 | 兑换码输入 | [兑换码输入.md](兑换码输入.md) | 兑换码输入框(菜单-更多功能→兑换码);screen_info 缺口;结果弹窗待补 |

diff --git a/docs/game/screens/丽都周纪.md b/docs/game/screens/丽都周纪.md
@@ -2,7 +2,7 @@
 screen_name: 丽都周纪
 appears_in: [快捷手册-日常]
 last_updated: 2026-07-12
-source_image: BINGO主画面
+source_image: screens/丽都周纪/BINGO主画面.webp
 ---
 
 # 丽都周纪(周常积分奖励)
@@ -26,11 +26,11 @@ source_image: BINGO主画面
 - **积分行**:`积分行-1/2/3`(`120,410~1055,925`,3 行)—— app `claim_score` 在此 OCR "100"(白色 `250~255` `lcs=1.0`)点击领积分。
 - **领取奖励**:`领取奖励`(`1558,314` 点坐标)—— app `confirm_schedule` 点击。
 
-source_image: BINGO主画面
+source_image: screens/丽都周纪/BINGO主画面.webp
 
 ## 识别快照
 
-### 1. BINGO 主画面(source_image: BINGO主画面)
+### 1. BINGO 主画面(source_image: screens/丽都周纪/BINGO主画面.webp)
 
 - 匹配画面:**无精准命中**(本 screen area 全 `id_mark=false`,analyze 不匹配)。
 - 匹配 area(误匹配,均非本 screen):

diff --git a/docs/game/screens/丽都城募.md b/docs/game/screens/丽都城募.md
@@ -2,7 +2,7 @@
 screen_name: 丽都城募
 appears_in: [菜单]
 last_updated: 2026-07-11
-source_image: city_fund_default
+source_image: screens/丽都城募/默认.webp
 ---
 
 # 丽都城募

diff --git a/docs/game/screens/仓库-驱动仓库.md b/docs/game/screens/仓库-驱动仓库.md
@@ -2,7 +2,7 @@
 screen_name: 仓库-驱动仓库
 appears_in: [仓库-音擎仓库]
 last_updated: 2026-07-11
-source_image: storage_drive_disc_default
+source_image: screens/仓库-驱动仓库/默认.webp
 ---
 
 # 仓库-驱动仓库

diff --git a/docs/game/screens/兑换码输入.md b/docs/game/screens/兑换码输入.md
@@ -2,7 +2,7 @@
 screen_name: 兑换码输入
 appears_in: [菜单-更多功能]
 last_updated: 2026-07-11
-source_image: redemption_code_input
+source_image: screens/兑换码输入/默认.webp
 status: 独立画面;screen_info 缺口(无独立 screen,area 借 menu.yml);兑换结果弹窗未覆盖
 ---
 

diff --git a/docs/game/screens/加载画面.md b/docs/game/screens/加载画面.md
@@ -2,7 +2,7 @@
 screen_name: 加载画面
 appears_in: [登录游戏]
 last_updated: 2026-07-06
-source_image: _1783247956712
+source_image: screens/加载画面/港口工厂旧址.webp
 ---
 
 # 加载画面(lore 加载过渡)

diff --git a/docs/game/screens/卦象集录.md b/docs/game/screens/卦象集录.md
@@ -2,7 +2,7 @@
 screen_name: 卦象集录
 appears_in: [trigrams_collection]
 last_updated: 2026-07-12
-source_image: 主界面.webp
+source_image: screens/卦象集录/主界面.webp
 ---
 
 # 卦象集录
@@ -36,14 +36,14 @@ source_image: 主界面.webp
 
 ## 识别快照
 
-### 1. 主界面(source_image: 主界面.webp)
+### 1. 主界面(source_image: screens/卦象集录/主界面.webp)
 
 - 匹配画面:`卦象集录` screen **未精准命中**(analyze `is_precise=false`,命中通用「返回」area);靠 OCR「卦象集录」+ vision「開」字图标判定。
 - 匹配 area:通用「返回」(左上角,template,conf 0.99);screen_info「卦象集录」screen 的「区域-获取卦象」为**纯坐标 area 不参与 analyze 匹配**。
 - 全量 OCR:卦象集錄 / 卦象集录(底部)。
 - vision:阿朔 NPC(左)+「開」字圆形主图标(右,区域-获取卦象)+ 龟形雕塑 / 竹签筒(场景道具)+ 半透明遮罩弹窗。
 
-### 2. 今日已领取终点(source_image: 今日已领取.webp)
+### 2. 今日已领取终点(source_image: screens/卦象集录/今日已领取.webp)
 
 - 匹配画面:无精准命中;靠 OCR「今日已经完成过一次相同类型的奖励领取」+「确认」判定。
 - 匹配 area:「确认」文字 area 命中多个 screen(丽都城募 / 咖啡店 / 零号空洞 等 `is_precise=false`,均匹配「确认」`950,609` conf 0.998)—— 通用确认按钮,非卦象集录专属。

diff --git a/docs/game/screens/咖啡店.md b/docs/game/screens/咖啡店.md
@@ -2,7 +2,7 @@
 screen_name: 咖啡店
 appears_in: [coffee]
 last_updated: 2026-07-12
-source_image: 对话点单-已喝过.webp
+source_image: screens/咖啡店/对话点单-已喝过.webp
 ---
 
 # 咖啡店(每日咖啡增益)
@@ -28,11 +28,11 @@ screen_info `咖啡店`(`coffee_shop.yml`,10 area):
 - **点单后**:`点单后跳过`(`1684,64-1850,200`,需先 drag 显鼠标)/ `电量确认`(`875,640-1200,754`)/ `不可贪杯确认`(`882,606-1084,690`,已喝过)。
 - **挑战分支**:`对话框前往`(`728,600-928,692` 前往副本)/ `对话框确认`(`1040,600-1228,688` 不挑战)。
 
-source_image: 对话点单-已喝过.webp
+source_image: screens/咖啡店/对话点单-已喝过.webp
 
 ## 识别快照
 
-### 1. 对话点单-已喝过态(POINT_2 汀曼咖啡)(source_image: 对话点单-已喝过.webp)
+### 1. 对话点单-已喝过态(POINT_2 汀曼咖啡)(source_image: screens/咖啡店/对话点单-已喝过.webp)
 
 - 匹配画面:`咖啡店`(is_precise=false)。
 - 匹配 area: