OneDragon-Anything · DoctorReid · Jul 8, 2026 · Jul 7, 2026 · Jul 8, 2026 · Jul 8, 2026
diff --git a/.github/README.md b/.github/README.md
@@ -76,7 +76,7 @@ __ZenlessZoneZero-OneDragon__
 ![Contributors](https://contrib.rocks/image?repo=DoctorReid/ZenlessZoneZero-OneDragon&columns=12)
 
 是你们的参与共同构建了这个项目，让这个项目越来越好♡
-如果想要参与开发，可以参考 [一条龙官网](https://onedragon-anything.github.io/) 对应的开发指南，我们期待你的加入
+如果想要参与开发，欢迎查看 [贡献者招募](../docs/develop/RECRUITING.md)（技术栈 / 参与方式 / 成长故事），并按 [快速开始](../docs/develop/setup/quickstart.md) 把项目跑起来，期待你的加入 ✨
 
 </div>
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -14,7 +14,8 @@
 - 语言与环境：Python 3.11、uv、PySide6。
 - 代码布局：`src-layout`，源码在 `src/`，运行时配置在 `config/`，资源在 `assets/`，开发文档在 `docs/develop/`。
 - 运行基准：1080p；配置以 YAML 为主。
-- 所有测试统一在独立仓 `zzz-od-test/test/`(`.gitignore`,须 clone 到仓库根目录才能读/改;clone 见 [quickstart §②](docs/develop/setup/quickstart.md),测试规范见 [agent_guidelines](docs/develop/spec/agent_guidelines.md))。主仓不保留测试。AI 查测试用 `Read`/`grep` 显式指定 `zzz-od-test/`(默认搜索会跳过 .gitignore)。
+- 所有测试统一在独立仓 `zzz-od-test/test/`(`.gitignore`,须 clone 到仓库根目录才能读/改;clone 见 [quickstart §②](docs/develop/setup/quickstart.md),测试规范见 [testing/](docs/develop/testing/README.md))。主仓不保留测试。AI 查测试用 `Read`/`grep` 显式指定 `zzz-od-test/`(默认搜索会跳过 .gitignore)。
+- 相关仓库全貌(测试仓 / yolo 训练仓 / 数据集 / 官网 blog)见 [相关仓库](docs/develop/setup/repositories.md);外部贡献者需 fork 后开发。
 
 ## 常用命令
 
@@ -52,6 +53,16 @@ uv run --env-file .env ruff check --fix src/你修改的文件.py
 - 操作链基于 `ZOperation` / `Operation` 编排；状态流转沿用现有 round 系列接口与节点声明方式。
 - GPU/onnx session 的异步调用必须通过 `gpu_executor.submit`，不要并发直调多个 session。
 
+## 开发流程（端到端）
+
+游戏自动化功能的开发链路(bug 修复 / 性能 / UI 等其他类型后续补充,详细判据见 [development_workflow.md](docs/develop/development_workflow.md)):
+
+1. **画面建档**(涉及新画面时):按 `zzz-od-dev-screen-onboarding` skill 截图 / 分析 / 建模 / 留档。
+2. **开发**:做成 `Application`(`ApplicationFactory` 接入)+ `Operation`,复用现有配置 / 界面模式(架构细则见上方「功能开发优先路径」)。
+3. **测试**:用留档截图在测试仓补流程测试(见 [testing/](docs/develop/testing/))。
+4. **提 PR**:assign **DoctorReid / ShadowLemoon**,按 `zzz-od-dev-pr-finishing` skill 走 review / resolve。
+5. **配套(按需)**:模型 → [yolo/dataset 仓](docs/develop/setup/repositories.md);使用说明 → blog(**用户可见变化**才更新)。
+
 ## 开发硬约束
 
 - 所有函数签名、类成员变量都要有类型注解；使用 `list[str]`、`X | Y`。
@@ -67,6 +78,7 @@ uv run --env-file .env ruff check --fix src/你修改的文件.py
 ## 文档与测试要求
 
 - 修改代码后，同步更新对应的 `docs/develop/` 文档与 `zzz-od-test/` 测试。
+- 测试方法论（测试基建 / FixtureController 流程测试 / 画面截图存档）见 [docs/develop/testing/](docs/develop/testing/README.md)。
 - 若测试依赖截图或环境变量，按 [docs/develop/README.md](docs/develop/README.md) 中说明准备 `.env` 与测试仓。
 - 提交前至少验证自己改动直接影响的部分；若无法本地完成，要明确说明缺失前提。
 - 复杂功能、架构调整或新自动化流程，先补设计/说明文档，再继续实现。

diff --git a/docs/develop/README.md b/docs/develop/README.md
@@ -4,13 +4,15 @@
 
 ## 文档索引
 
-- **开发环境与工具**：[快速开始](setup/quickstart.md) · [AI 编码助手接入](setup/ai_coding.md)
+- **开发环境与工具**：[快速开始](setup/quickstart.md) · [相关仓库](setup/repositories.md) · [AI 编码助手接入](setup/ai_coding.md)
 - **编码规范**：[agent_guidelines.md](spec/agent_guidelines.md)
+- **开发流程**：[端到端开发流程](development_workflow.md)
 - **架构设计**：[一条龙整体架构](one_dragon/one_dragon_architecture.md) · [集成启动器 RuntimeLauncher](one_dragon/runtime_launcher.md) · [模块文档](one_dragon/modules/)
 - **开发指引**：[应用插件开发](guides/application_plugin_guide.md) · [应用设置界面](guides/application_setting_guide.md)
-- **游戏业务**：[自动战斗](zzz/auto_battle.md) · [进游戏](zzz/enter_game.md) · [转向与灵敏度](zzz/turn_sensitivity.md) · [功能模块](zzz/application/) · [迷失之地](zzz/application/lost_void/) · [后端服务层](zzz/backend/)
+- **游戏业务**：[自动战斗](zzz/auto_battle.md) · [进游戏](zzz/enter_game.md) · [转向与灵敏度](zzz/turn_sensitivity.md) · [功能模块](zzz/application/) · [迷失之地](zzz/application/lost_void/) · [后端服务层](zzz/backend/) · [截图存档](zzz/screenshot_archive.md)
 - **AI Harness 工程**：[总览与路线图](harness/README.md)
 - **设计文档**：[屏幕区域识别设计](screen_scope_design.md) · [屏幕区域推进](screen_scope_rollout.md)
+- **测试与画面**：[测试方法论](testing/) · [截图存档](zzz/screenshot_archive.md)
 
 ## 1.开发
 
@@ -46,6 +48,8 @@ Github Action 有完整的环境变量配置，会运行所有的测试用例。
 uv run --env-file .env pytest zzz-od-test/
 ```
 
+> 测试方法论(测试基建 / FixtureController 流程测试 / 画面截图存档)见 [testing/](testing/)。
+
 ### 常用业务文档
 
 - [转向与灵敏度配置](zzz/turn_sensitivity.md) - 说明 `turn_dx`、`gamepad_turn_speed`、前台/后台模式，以及锄大地、录像店营业、迷失之地、式舆防卫战各自的转向链路。

diff --git a/docs/develop/RECRUITING.md b/docs/develop/RECRUITING.md
@@ -59,11 +59,10 @@
 ## 快速开始
 
 1. **Fork 并 Clone** 本仓库
-2. 安装依赖：`uv sync --group dev`
+2. 按 [快速开始](setup/quickstart.md) 把项目在本机跑起来（环境搭建 / 依赖 / 跑通 GUI、测试、AI 工具，分三阶段按需推进）
 3. 阅读统一入口：[AGENTS.md](../../AGENTS.md)
-4. 阅读开发文档：[docs/develop/README.md](README.md)
-5. 按需深入编码规范：[docs/develop/spec/agent_guidelines.md](spec/agent_guidelines.md)
-6. 找一个感兴趣的 issue，开始你的第一个 PR
+4. 浏览开发文档索引：[docs/develop/README.md](README.md)（编码规范按需看 [agent_guidelines.md](spec/agent_guidelines.md)）
+5. 找一个感兴趣的 issue，开始你的第一个 PR
 
 遇到问题？在 GitHub Discussions 或社区频道提问，我们很乐意帮助。
 

diff --git a/docs/develop/development_workflow.md b/docs/develop/development_workflow.md
@@ -0,0 +1,62 @@
+# 开发流程
+
+> 一个功能从立项到交付的端到端链路。AGENTS.md 有 always-on 骨架;本页给详细判据、实例与配套更新规则。
+>
+> 当前只覆盖**游戏自动化功能**(已验证场景:OpenAndEnterGame)。bug 修复 / 性能 / UI / 模型等其他类型见文末「其他类型」,后续补。
+
+## 主干
+
+流程主干采用团队共识的 [superpowers](https://github.com/anthropics/superpowers)(brainstorming → writing-plans → TDD → review → finishing-a-branch);本页只讲**本项目在各阶段要插入的项目特定动作**。
+
+## 游戏自动化功能
+
+以 **OpenAndEnterGame(打开并登录游戏)** 为实例。
+
+### 1. 画面建档(涉及新画面 / 交互时)
+
+**触发**:新增或改变游戏画面、可交互元素时(纯逻辑 / 算法 / 配置改动不用)。按 `zzz-od-dev-screen-onboarding` skill:
+
+- 截图 → `analyze_screen` 客观识别(匹配画面 / area / 全量 OCR)。
+- 主观理解 → 建画面文档 `docs/game/screens/<screen>.md`(子态 / 特征 / 可交互元素 / 识别快照)。
+- 缺口分析 → 主动建模图形 / 图标按钮(模板 / CV),经 CRUD 工具入 screen_info。
+- 归档代表截图到测试仓 `screens/<screen>/<state>.webp`(测试 fixture + 文档溯源)。
+
+> OpenAndEnterGame 实例:登录各子态(ready / 登录服务器中 / 登录成功 / 加载画面 / 大世界)逐一建档 + 建模(含图形按钮如登录页 ◀ 后退)+ 归档 webp。
+
+### 2. 开发
+
+做成 `Application`(放 `src/zzz_od/application/`,经 `ApplicationFactory` 接入)+ `Operation` 节点编排 flow;复用现有配置体系(YAML / `YamlConfig`)与界面(setting card / `YamlConfigAdapter`)。架构细则见 AGENTS.md「功能开发优先路径」。
+
+> OpenAndEnterGame 实例:`OpenAndEnterGame` 是一个编排 `OpenGame` + `EnterGame` 的 **Operation**(被 app 调用进入游戏);`OpenGame` 负责启动游戏进程(及相关系统设置),`EnterGame` 负责屏幕驱动,详见 [zzz/enter_game.md](zzz/enter_game.md)。
+
+### 3. 测试
+
+用留档截图在测试仓补**流程测试**(多帧 / 轮询 / 重试 / 恢复分支)用 `FixtureController`(`MockController` 子类);单节点识别用简单 mock。规范见 [testing/](testing/README.md)。
+
+> OpenAndEnterGame 实例:`test_enter_game_flow.py` 用 `FixtureController` 跑 `EnterGame` 自动登录全流程(ready → 点进入 → 登录服务器中 → 登录成功 → 加载 → 大世界)。
+
+### 4. 提 PR
+
+跨仓 PR 顺序:**先建测试仓 PR,再建主仓 PR**:
+
+1. 测试仓改动先提交、推送、开 PR(`git -C zzz-od-test`),拿到测试仓 PR 链接。
+2. 主仓开 PR,**描述里带上测试仓 PR 链接**(reviewer 可跳转看测试改动);主仓与测试仓用**同分支名**(CI 按分支名 clone 测试仓)。
+3. assign **DoctorReid / ShadowLemoon**,按 `zzz-od-dev-pr-finishing` skill 走 review(逐条回复 / 修正、清 unresolved thread、处理 CodeRabbit);**关联 PR 一起收尾、合并顺序(测试仓先)见该 skill §6**。
+
+### 5. 配套产出(按需)
+
+| 产出 | 何时做 | 在哪 |
+|---|---|---|
+| 开发文档 | 代码 / 架构变化 → **总要** | `docs/develop/` |
+| 游戏知识库 | 画面 / 玩法变化 | `docs/game/`(画面建档时同步) |
+| 模型 | 涉及 YOLO 检测 | yolo 训练仓 + dataset(见 [相关仓库](setup/repositories.md)) |
+| **使用说明(blog)** | **用户可见的功能 / 操作变化**(新功能、改用法、GUI 变化) | blog 仓;纯内部重构 / 性能 / 无感 bug → 不用 |
+
+## 其他类型(后续补充)
+
+尚无足够实例,流程待补;不提前臆造。已知方向:
+
+- **bug 修复**:`systematic-debugging`(定位)→ `zzz-od-dev-deciding-a-fix`(定修法)→ 改 → 回归测试 → PR。
+- **性能优化**:定位瓶颈 → 改 → benchmark 验证 → PR。(待实例)
+- **UI / GUI**:复用 Fluent widgets / setting card → 视觉 / 交互验证 → PR。(待实例)
+- **模型 / 识别**:跨 yolo / dataset 仓训练 → release → 主仓消费。(待实例)
diff --git a/docs/develop/harness/README.md b/docs/develop/harness/README.md
@@ -44,7 +44,7 @@ harness 的根本目标是**人机知识对齐**：凡开发者（人）做本
 | `AGENTS.md` | 仓库根 | 统一 AI 编码入口（架构 / 硬约束 / 流程），所有工具的信息源 |
 | `.claude/CLAUDE.md` | 仓库根 | Claude Code 入口，`@../AGENTS.md` 引入 |
 | `.github/copilot-instructions.md` | 仓库根 | Copilot 入口 |
-| [`skills/`](../../../skills/) | 仓库根 | 7 个 skill:开发类 `zzz-od-dev-pr-finishing` / `zzz-od-dev-deciding-a-fix` / `zzz-od-dev-skill-guide`(superpowers 风格,经 junction 加载);历史遗留 `agent-auto-battle-config` / `agent-definition` / `new-config` / `zzz-one-dragon-player` |
+| [`skills/`](../../../skills/) | 仓库根 | 开发类 `zzz-od-dev-*`(superpowers 风格,经 junction 加载)+ 历史遗留 skill;清单见目录,不在此罗列以免随增减过时 |
 | [../setup/ai_coding.md](../setup/ai_coding.md) | docs/develop/setup | 各 AI 工具的接入指引（用户向："怎么用"） |
 
 > "怎么用"见 `setup/ai_coding.md`；本目录（harness/）记录"怎么建、为什么这么建"。

diff --git a/docs/develop/setup/ai_coding.md b/docs/develop/setup/ai_coding.md
@@ -86,11 +86,13 @@ Skill 是 Claude Code（及 Codex 等少数工具）的可调用能力。要点
 
 Skill 分两类，统一用 `zzz-od-` 项目前缀，开发类再加 `dev-`：
 
-| 类别 | 前缀 | 用途 | 现有 skill |
-|---|---|---|---|
-| **开发** | `zzz-od-dev-` | 指引 AI 在本项目开发/配置/构建 | `zzz-od-dev-pr-finishing`、`zzz-od-dev-deciding-a-fix`、`zzz-od-dev-skill-guide`（已迁移，superpowers 风格） |
-| **历史遗留** | 无前缀 | 早期 skill，暂保留原名 | `agent-auto-battle-config`、`agent-definition`、`new-config`、`zzz-one-dragon-player`（迁移价值待评估） |
+| 类别 | 前缀 | 用途 |
+|---|---|---|
+| **开发** | `zzz-od-dev-` | 指引 AI 在本项目开发/配置/构建（superpowers 风格） |
+| **历史遗留** | 无前缀 | 早期 skill，暂保留原名（迁移价值待评估） |
 
+> 现有 skill 清单见 [`skills/` 目录](../../../skills/)（每个 SKILL.md frontmatter 有触发描述），不在此罗列以免随增减过时。
+>
 > `zzz-od-` 兼作**项目命名空间**——避免和插件/个人 skill 撞名，`/` 列表里本项目 skill 聚一起。命名示例：`zzz-od-dev-character`（新增角色）、`zzz-od-dev-build`（构建配置）、`zzz-od-player`（安装使用）。将来若出现第 3 类（如调试），加对应中缀（`zzz-od-debug-*`）即可。
 
 ### Skill 开发：三级晋升
@@ -109,10 +111,7 @@ Skill 分两类，统一用 `zzz-od-` 项目前缀，开发类再加 `dev-`：
 
 ### 现状
 
-仓库根 `skills/` 现有 7 个 skill：
-
-- **开发类 3 个**（`zzz-od-dev-*`，superpowers 风格，已提交）：`zzz-od-dev-pr-finishing`、`zzz-od-dev-deciding-a-fix`、`zzz-od-dev-skill-guide`。经 junction（`.claude/skills/<name>` → 根 `skills/<name>`）被 Claude Code 自动加载。
-- **历史遗留 4 个**（无前缀，暂保留原名）：`agent-auto-battle-config`、`agent-definition`、`new-config`、`zzz-one-dragon-player`。是否按 `zzz-od-` 规范迁移待评估。
+仓库根 [`skills/`](../../../skills/) 是 skill 的单一源（③）；开发类（`zzz-od-dev-*`，superpowers 风格）经 junction（`.claude/skills/<name>` → 根 `skills/<name>`）被 Claude Code 自动加载。**现有 skill 清单见目录本身**（每个 SKILL.md frontmatter 有触发描述），不在此罗列以免随增减过时。
 
 新 skill 按上面的命名规范用 `zzz-od-` 前缀。
 

diff --git a/docs/develop/setup/quickstart.md b/docs/develop/setup/quickstart.md
@@ -13,12 +13,31 @@
 
 ## ① 跑起来（核心）
 
-### 1. clone 主仓
+### 1. 获取代码
 
-```powershell
-git clone https://github.com/OneDragon-Anything/ZenlessZoneZero-OneDragon.git
-cd ZenlessZoneZero-OneDragon
-```
+- **组织/项目成员**（有主仓 push 权）：直接 clone
+
+  ```powershell
+  git clone https://github.com/OneDragon-Anything/ZenlessZoneZero-OneDragon.git
+  cd ZenlessZoneZero-OneDragon
+  ```
+
+- **外部贡献者**（无 push 权）：先 Fork 再 clone 自己的 fork，提 PR 回主仓
+
+  1. 在 [仓库页面](https://github.com/OneDragon-Anything/ZenlessZoneZero-OneDragon) 右上角点 **Fork**，fork 到自己账号下。
+  2. clone **你 fork 的仓库**（`<你的账号>` 换成 GitHub 用户名）：
+
+     ```powershell
+     git clone https://github.com/<你的账号>/ZenlessZoneZero-OneDragon.git
+     cd ZenlessZoneZero-OneDragon
+     ```
+  3. （可选）配 upstream remote，方便后续同步主仓更新（clone 只会设 `origin`，upstream 需手动加）：
+
+     ```powershell
+     git remote add upstream https://github.com/OneDragon-Anything/ZenlessZoneZero-OneDragon.git
+     ```
+
+> 其余相关仓库（测试仓 / yolo 训练仓 / 数据集 / 官网 blog）见 [相关仓库](repositories.md)。
 
 ### 2. 安装 uv
 
@@ -67,11 +86,19 @@ $env:PYTHONPATH = "src"; uv run src/zzz_od/gui/app.py
 
 测试代码在独立仓 `zzz-od-test`，clone 到**本项目根目录**下：
 
-```powershell
-git clone https://github.com/OneDragon-Anything/zzz-od-test.git zzz-od-test
-```
+- **组织/项目成员**：
+
+  ```powershell
+  git clone https://github.com/OneDragon-Anything/zzz-od-test.git zzz-od-test
+  ```
 
-IDE 里把 `zzz-od-test/` 设为 `Test Sources Root`；运行方式（含所需环境变量）见 [开发指南 §1.3](../README.md)。
+- **外部贡献者**（先在 GitHub fork，再 clone 你的 fork，`<你的账号>` 替换为 GitHub 用户名）：
+
+  ```powershell
+  git clone https://github.com/<你的账号>/zzz-od-test.git zzz-od-test
+  ```
+
+IDE 里把 `zzz-od-test/` 设为 `Test Sources Root`；运行方式（含所需环境变量）见 [开发指南 §1.3](../README.md)。测试改动随主仓 PR 同分支名一起提（CI 按分支名匹配 clone 测试仓），详见 [相关仓库](repositories.md)。
 
 ## ③ 配 AI 工具（可选）
 
@@ -94,7 +121,9 @@ claude mcp add --transport http zzz_od http://127.0.0.1:23001/mcp
 
 ### Skills
 
-项目有 3 个开发类 skill（`zzz-od-dev-pr-finishing` / `zzz-od-dev-deciding-a-fix` / `zzz-od-dev-skill-guide`），Claude Code 经 `.claude/skills/` junction 自动加载。**团队采用 [superpowers](https://github.com/anthropics/superpowers) 作为开发流程方法论**（brainstorming → 计划 → TDD → review → 合并），本项目 dev skill 是叠加其上的项目特定补充，建议一并安装（`/plugin install superpowers`）。详见 [AI 编码助手接入 §Skills](ai_coding.md#skills)。
+项目有开发类 skill（`zzz-od-dev-*`），Claude Code 经 `.claude/skills/` junction 自动加载；叠加在团队采用的 [superpowers](https://github.com/anthropics/superpowers) 开发流程方法论之上（brainstorming → 计划 → TDD → review → 合并）。建议一并安装：`/plugin install superpowers`。
+
+- **现有 skill 见 [`skills/` 目录](../../../skills/)**（每个 SKILL.md 的 frontmatter 有触发描述）；分类与命名规范见 [AI 编码助手接入 §Skills](ai_coding.md#skills)。
 
 ### Plugin