企业官网建设流程全解析

• 桌面应用
• RPA
• 计算机视觉

导读：本文围绕开源仓库 ZenlessZoneZero-OneDragon 的 docs/game/screens/README.md（画面描述索引）展开。该索引按screen_name组织「1 篇文档 ↔ 1 个screen_info画面」的知识库，是自动化的"眼睛"：从登录页到大世界、从战斗画面到各种非战斗 App，每个可识别画面都有对应的描述文档与assets/game_data/screen_info/<name>.yml配置文件。读完本文，你将掌握：画面索引的组织方式与双向引用规范、36 个已登记画面的分类与建档状态、非战斗 App 的三种建档路线，以及如何用 MCP 工具（增改/删除画面区域、OCR 快照复核）为缺口画面补档的完整实操流程。

一、画面描述索引是什么：自动化的"视觉地图"

在绝区零一条龙（ZenlessZoneZero-OneDragon）这类全自动脚本项目中，AI 或脚本要能"看懂"游戏画面，才能决定下一步操作。这一能力建立在screen_info 画面模型之上：每个可识别画面对应一份 YAML 配置（assets/game_data/screen_info/ 目录下，如 menu.yml、大世界、战斗画面），而 docs/game/screens/README.md 就是这个模型的人类可读索引。

索引的定位规则只有一句话：按screen_name组织，每篇文档 ↔ 一个assets/game_data/screen_info/<name>.yml。这里的关键是screen_name（中文名，如「菜单」「大世界-普通」「打开游戏」），而不是底层的screen_id（英文标识，如menu、common_screen）。这个约定在 docs/game/README.md 的「记录规范」中被再次强调——关联键一律使用screen_info.screen_name（中文），非screen_id。之所以这样约定，是因为文档面向本地 AI 与开发者阅读，中文画面名更直观，且能与gameplay_name形成跨文档的双向引用。

1.1 双向引用规范：screens ↔ gameplay

docs/game/目录下有两类领域知识文档（docs/game/README.md）：

• screens/— 画面描述，1 篇 md ↔ 1 个画面，对齐assets/game_data/screen_info/<name>.yml；
• gameplay/— 玩法，描述跨画面的机制与系统。

两者通过 frontmatter 建立双向引用：

• screens/*.md的 frontmatter 带appears_in（本画面出现在哪些玩法，用gameplay_name）；
• gameplay/*.md的 frontmatter 带involves_screens（本玩法经过哪些画面，用screen_name）。

以 大世界.md 为例，其 frontmatter 为：

screen_name: 大世界 appears_in: [登录游戏] last_updated: 2026-07-06 source_image: screens/大世界/普通.webp

除了appears_in，frontmatter 还会记录last_updated（核对日期）和source_image（当前基线截图）。规范明确要求：正文绝不写死截图 ID，因为.debug/images/下的截图文件名是一次性捕获 ID、易失；变更复核走方法（重新截图 →analyze_screen→ 与 OCR 快照 diff → 更新last_updated/source_image），归档测试则使用可读名的 webp 版本（方法论见 docs/develop/zzz/screenshot_archive.md）。

1.2 识别快照：每篇画面文档的"体检报告"

每篇画面文档都要求保存一份analyze_screen快照，包含三部分：

1. 匹配画面：screen_name+is_precise（是否精准命中）；
2. 匹配 area 表：取自screens[].areas，包含 area_name、类型（text|template）、文本或template_id、conf（置信度）、位置（x,y,w×h，基于 1080p 游戏空间坐标pc_rect）；
3. 全量 OCR 文本（ocr_texts）。

大世界.md 的识别快照展示了这一格式：

- 匹配画面: 大世界-普通 (is_precise=True ✓) - 匹配 area: | area | 类型 | conf | 位置 (x,y,w×h) | |---|---|---|---| | 按钮-信息 | template | 0.991 | 1738,928,78×78 | | 预备编队 | template | 0.990 | 1321,51,90×44 | | 快捷手册 | template | 0.968 | 1531,60,48×43 |

一个值得注意的细节：MCP 的ocr_texts保持全量（area 维护的文字可能不全），所以文字 area 在「匹配 area 表」和「全量 OCR 文本」两边都出现属正常现象，并非重复维护。

二、36 个画面条目全景：screen_name / 文件 / 简介总表

索引正文是一张按screen_name排列的登记表。下表完整继承了原索引的全部 36 个条目（含末尾补充的「预备编队」），并补注了各自的建档状态（已建模 / 已建档 / screen_info 缺口 / 待补），便于读者快速定位哪些画面"能用"、哪些"待补"。

2.1 实战模拟室 vs 防卫战：战斗结束画面按玩法分流

索引中「实战模拟室」条目隐含了一个重要设计原则——战斗结束画面的归属按玩法分流：

• 战斗中画面统一归「战斗画面」；
• 防卫战结束后 → 「挑战结果」画面；
• 实战模拟室结束后 → 「获得奖励」弹窗。

因此每个玩法都有各自的screen，不能共用一个"战斗结束"通用画面。这与 式舆防卫战.md 中「选关主界面 + 弱点/编队/战斗/领奖多子态」的建模方式一致：一个玩法 = 一个 screen_name + 多个子态 area。

2.2 迷失之地的 OCR 修复案例（ppocrv5/v6）

索引中「迷失之地」条目记录了真实的排障案例，值得自动化开发者留意：

✅ 通用选择按钮-确定宽 rect（940px）曾致 ppocrv6 漏检 + ppocrv5 误判「以太稳定」卡死，已收紧 rect+提 lcs 修复（ppocrv6 恢复）。

这说明：OCR 引擎（ppocrv5 与 ppocrv6）对同一区域的行为可能截然不同——过宽的矩形区域会让新版引擎漏检、旧版引擎误检。修复手段是同时收紧pc_rect并提高 LCS（最长公共子序列，用于文本相似度匹配的lcs_percent）阈值。这也是在 menu.yml 中每个 area 都带有pc_rect+lcs_percent+template_match_threshold的原因。

三、screen_info 配置结构：一个 area 的完整字段

要理解索引文档，必须先能读懂它背后的 YAML。以 menu.yml（screen_id: menu，screen_name: 菜单）为例，一个典型的 area 字段如下：

- area_name: 返回 id_mark: false pc_rect: [82, 13, 150, 90] # 1080p 游戏空间坐标 (x, y, w, h) text: '' lcs_percent: 0.1 # 文本 LCS 相似度阈值 template_sub_dir: menu # 模板子目录（assets/template/ 下） template_id: back # 模板名 template_match_threshold: 0.7 # 模板匹配阈值 color_range: null goto_list: [] # 点击该 area 后的跳转目标 screen_name

area 的类型通过字段组合区分：

• 文字 area（text）：靠 OCR 识别text字段，如「邮件」「仓库」「确认」；
• 模板 area（template）：靠模板匹配template_sub_dir+template_id，如「返回」（menu/back）、「关闭」（menu/btn_close）；
• 跳转 area（goto）：goto_list非空，表示点击后进入的目标画面，如 menu.yml 中：

- area_name: 底部-更多 text: 更多 goto_list: - 菜单-更多功能 # 点击「更多」→ 进入「菜单-更多功能」画面 - area_name: 按钮-返回 id_mark: true # id_mark=true 的画面锚点 template_id: back template_match_threshold: 0.9 goto_list: - 大世界-普通 # 返回 → 大世界-普通

另外，screen_id: common_screen、screen_name: 画面-通用（common_screen.yml）是通用兜底画面，包含「左上角-区域」「返回」「关闭」等公共 area。这与 对话.md、加载画面.md 这类"无固定文字特征"的兜底画面（fallback screen）相呼应。

四、非战斗 App 的三种建档路线与跳过原则

索引后半部分「非战斗 app 建档进度」对无战斗玩法的 App 做了分类，是按「操作复杂度」划分的三条建档路线：

4.1 路线一：纯 UI，MCP 可复现

已建档：email（邮件）/redemption_code（兑换码）/drive_disc_dismantle（驱动盘拆解）/engagement_reward（快捷手册-日常）/city_fund（丽都城募）/ridu_weekly（丽都周纪；BINGO 积分领奖）。

这类 App 纯点按 UI 即可走通，对应的 screen_info 已可在 assets/game_data/screen_info/ 中直接查到（如 email.yml、city_fund.yml、ridu_weekly.yml）。

4.2 路线二：move / interact / drag 类

已建档：

• scratch_card（报刊亭；刮刮卡；嗷呜对话 / 确认弹窗待补）；
• trigrams_collection（卦象集录；滑动获取卦象 / 领奖确认待补）；
• random_play（影像店营业；Transport POINT_2 + interact 进经营；营业确认弹窗待补）；
• suibian_temple（随便观；入口 interact 狮耶 + 9 子画面实拍归档；3 画面无 screen_info 待补）。

这类 App 需要鼠标拖拽、交互进入等操作，建档时用key_tap+drag+run_operation Transport分解（具体见 onboarding skill 的「截图获取」章节）。

4.3 路线三：通用兜底画面（无固定文字特征）

已建档：对话（NPC 对话；有 NPC 名已建档，旁白待补）、加载画面（通用 lore 轮换）。

这类画面没有稳定的文字特征，只能靠兜底逻辑识别，详见 onboarding skill 的「兜底画面」章节。

4.4 ⚠️ 跳过与不建档

• 跳过（边界 app，不在建档范围）：
  • hou_hou_bakery（吼吼饼铺.md，骨架已建，信息源三层；⚠️Transport 卡 3.0 布亚斯特城区未探索，截图待补）；
  • life_on_line（危局：含战斗EnterHddMission+KeySimRunner，非「不含战斗」app）；
  • commission_assistant（委托助手.md，辅助循环器多态识别已建 doc；⚠️含可选 auto_battle，边界）；
  • coffee（咖啡店.md，已建档非战斗画面；⚠️边界 app，可选挑战副本含战斗）。
• 不建档（无游戏画面）：notify（只发推送通知，汇总 run_record，不截图/不点 UI）。

4.5 缺口画面的补档路径

索引明确给出结论：

跳过的 app 待 MCP 补足transport/move/drag/键盘注入能力后，或用框架run_standalone_app跑通后沿途截图补。

即：缺口画面的补档依赖两条通道——MCP 的交互能力扩展，或run_standalone_app独立跑通后沿途截图。

五、源码级验证：screen_info 的读写与 MCP 工具

画面索引不只是文档约定，它在后端源码中有完整的落点。以下路径均在 src/zzz_od/backend/ 下可验证。

5.1 screen_loader：get_screen / save_screen

画面模型的读取与回写由上下文对象screen_loader承担。从源码结构看，其核心接口包括：

• screen_loader.get_screen(screen_name)：按中文screen_name取画面，未找到时 raise；
• screen_loader.save_screen(screen_info)：把修改后的画面写回对应 YAML 并重载。

调用点示例（backend_context.py 的 area 增删逻辑，约 L587-L650）：

screen_info = self._ctx.screen_loader.get_screen(screen_name) # 未找到 raise action = screen_info.upsert_area(area) self._ctx.screen_loader.save_screen(screen_info)

以及删除路径：

if not screen_info.remove_area_by_name(area_name): ... # 未找到 area 报错 self._ctx.screen_loader.save_screen(screen_info)

区域更新语义为：area_name 已存在 → 整体更新；不存在 → 追加，随后写回 YAML 并重载，保证运行时热生效。

5.2 坐标体系：pc_rect 与 1080p 游戏空间

索引文档中的坐标（如大世界的1531,60、1738,928）都基于1080p 游戏空间坐标，与 screen_info 的pc_rect同源。这一点在 backend_context.py 的点击/拖拽工具注释中被反复强调：

• 点击：点击游戏窗口内指定坐标(1080p 游戏空间,同源 screen_info pc_rect)；
• 拖拽：鼠标按住拖拽((x1,y1)→(x2,y2),1080p 游戏坐标,同源 screen_info pc_rect)。

这也解释了 大世界.md 中「PC 端点击需pc_alt=true（Alt 解锁光标）+ 非零press_time（框架默认 0.1）」的原因：绝区零 PC 端锁光标，不按 Alt 直接点击会落空。

5.3 匹配结果语义：is_precise 与候选列表

screens匹配结果在 schemas.py 中的语义为：

画面匹配结果：精准命中 = [1 个 is_precise=True]；否则 top_n 个 is_precise=False 候选。决策优先看 screens；需看散落文本再看 ocr_texts。

而 backend_context.py 在识别回写逻辑中有条件判断if write_back and screens and screens[0].is_precise:，即只有精准命中时才考虑回写状态，避免把模糊候选当结论写入。索引文档中「大世界-普通（is_precise=True ✓）」这类标注，正对应此语义。

5.4 MCP 工具：建档/维护画面区域的实操入口

画面索引的建档工作通过 MCP（Model Context Protocol）服务完成，入口在 mcp/app.py。与本文主题直接相关的工具包括：

• 识别画面（决策入口）：analyze_screen相关工具，返回screens（精准命中 1 个is_precise=True；否则 top_n 候选）+ocr_texts；离线校验时从.debug/images/<名字>.png读图、不回写识别状态，用于校验/反哺 screen_info；
• 增改画面区域：按area_name在指定 screen 插入或更新一个 area（写 yml + reload，操作类）；
• 删除画面区域：按area_name删除（写 yml + reload，操作类 + 不可逆，需谨慎）。

配合索引正文与每篇画面文档的「识别快照」，即可完成"截图 → analyze_screen → 对照快照 diff → 增改 area → 更新文档 last_updated"的闭环维护流程。

六、实战：如何阅读与使用这份索引

6.1 快速定位一个画面是否可用

1. 在 README.md 索引表中按screen_name（中文）找到对应条目；
2. 查看「简介」列的建档状态词：已建模（screen_info 完整可用，如 menu.yml）、已建档（画面文档已建但 screen_info 可能不全）、screen_info 缺口（只有文档、无 YAML 配置）、待补（已知缺口）；
3. 若需在代码/配置中核实，到 assets/game_data/screen_info/ 找<name>.yml（name 为英文 screen_id），确认screen_name与area_list是否齐全。

6.2 从索引走向画面细节

每个条目链接的画面文档（如 大世界.md、战斗画面.md、式舆防卫战.md）会进一步给出：

• 何时出现（进入路径）；
• 识别特征（稳定锚点，模板/文字/位置）；
• 可交互元素（每个 area 的坐标与 goto 目标）；
• 条件弹窗（模态覆盖，非独立画面）；
• 识别快照（匹配画面 + area 表 + OCR 文本）。

6.3 为缺口画面补档（工作流）

针对标记为「screen_info 缺口 / 待补」的画面，按索引第 4.5 节给出的路径操作：

1. 优先选择 MCP 具备transport/move/drag/键盘注入能力后补档；
2. 或用框架run_standalone_app跑通对应 App，沿途截图；
3. 用 MCPanalyze_screen识别截图，对照 docs/game/README.md 的「识别快照」规范（匹配画面 + area 表 + 全量 OCR）记录快照；
4. 用「增改画面区域」工具写入 area（area_name已存在则整体更新、不存在则追加，写 yml + reload）；
5. 更新画面文档 frontmatter 的last_updated/source_image，保持双向引用（appears_in↔involves_screens）一致。

6.4 边界与陷阱

• 不要混淆 screen_name 与 screen_id：文档/索引用中文screen_name，YAML 文件名与代码中常用英文screen_id；
• 兜底画面（对话/加载画面）无固定文字特征，别期待其像大世界那样有精准模板锚点；
• 战斗结束画面按玩法分流，切勿用一个通用「结算」画面覆盖所有玩法；
• OCR 引擎差异（ppocrv5 vs ppocrv6）会导致同一 rect 表现不同，参考迷失之地案例，必要时收紧pc_rect并调整lcs_percent；
• 识别回写仅在 is_precise 时发生（见 5.3 节），模糊匹配不写入状态。

七、结语：从索引到模型的反哺闭环

这份画面索引属于 docs/game/README.md 定义的离线领域知识库——Part A 的analyze运行时并不读取它（运行时解耦），它服务于「自由积累 → 统一分析 → 反哺/重构 screen_info 模型」的演化路径（对应 CLAUDE.local.md 的「增量 → 合并回主 spec」）。因此，索引与其说是"运行文档"，不如说是画面模型的增量待办清单 + 验收台账：36 个条目中哪些已建模、哪些已建档、哪些待补，一目了然；每补一个画面，assets/game_data/screen_info/ 就多一份可被 src/zzz_od/backend/ 读取的 YAML，自动化的"眼睛"就更完整一分。对希望为该项目贡献画面建模能力的开发者而言，这份索引就是最佳起点。

• 桌面应用
• RPA
• 计算机视觉