feat(backend): 同步 ZZZ backend 演进（open_game + click/input/screen_area CRUD，7→11 tool）

.github/dev.md

@@ -1,28 +1,13 @@
 # 1.开发环境
 
-## 1.1.Python
-
-推荐使用 [3.11.9](https://www.python.org/downloads/release/python-3119/)
-
-## 1.2.虚拟环境
-
-普通运行
-
-```shell
-pip install -r requirements-dev.txt
-```
-
-开发额外
-
-```shell
-pip install -r requirements-dev-ext.txt
-```
-
-生成最终使用
-
-```shell
-pip-compile --annotation-style=line --index-url=https://pypi.tuna.tsinghua.edu.cn/simple --output-file=requirements-prod.txt requirements-dev.txt
-```
+开发环境与常用命令见根目录 [AGENTS.md](../AGENTS.md)。要点：
+
+- Python 3.11.9；包管理用 uv。
+- 安装依赖（含 ruff/pytest/pyright 等 dev 工具）：`uv sync --group dev`
+- 运行：`uv run python src/sr_od/gui/sr_full_app.py`（需 `PYTHONPATH=src`，详见 AGENTS.md）
+- Lint：`uv run ruff check src/<你修改的文件>.py`
+- 测试：`uv run pytest sr-od-test/`
+- 也可用 `debug.bat` 交互式调试。
 
 # 2.打包
 

.github/workflows/test-check.yml

@@ -0,0 +1,98 @@
+name: Test Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+jobs:
+  test-check:
+    runs-on: windows-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Install uv
+        shell: pwsh
+        run: |
+          Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 | Invoke-Expression
+
+      - name: Create and activate virtual environment
+        shell: pwsh
+        run: |
+          uv venv .venv --python=3.11.12
+
+      - name: Install dependencies
+        shell: pwsh
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          uv sync --group dev
+
+      - name: Checkout test repo
+        id: checkout-test-repo
+        uses: actions/checkout@v5
+        with:
+          repository: ${{ github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name && format('{0}/sr-od-test', github.event.pull_request.head.repo.owner.login) || 'OneDragon-Anything/sr-od-test') || 'OneDragon-Anything/sr-od-test' }}
+          path: sr-od-test
+          ref: ${{ github.event_name == 'pull_request' && github.head_ref || 'main' }}
+          fetch-depth: 1
+          persist-credentials: false
+        continue-on-error: true
+
+      - name: Checkout test repo (default branch)
+        id: checkout-test-repo-default
+        if: steps.checkout-test-repo.outcome == 'failure'
+        uses: actions/checkout@v5
+        with:
+          repository: OneDragon-Anything/sr-od-test
+          path: sr-od-test
+          ref: main
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Pre-download YOLO model (CI bypasses ghfast.top proxy; direct github)
+        shell: pwsh
+        run: |
+          # cal_pos/sim_uni 集成测试需 YOLO 模型；loader 默认走 ghfast.top 代理在 CI 会失败。
+          # CI 直连 github release 预下载到 loader 期望的目录，check_model_exists 通过 → 不触发下载。
+          $url = "https://github.com/OneDragon-Anything/OneDragon-YOLO/releases/download/sr_model/yolov8n-640-simuni-0601.zip"
+          $tmp = "$env:TEMP\yolo.zip"
+          Invoke-WebRequest -Uri $url -OutFile $tmp
+          foreach ($cat in @("world_patrol", "sim_uni")) {
+            $dst = "assets\models\$cat\yolov8n-640-simuni-0601"
+            New-Item -ItemType Directory -Force -Path $dst | Out-Null
+            Expand-Archive -Path $tmp -DestinationPath $dst -Force
+          }
+          Write-Host "YOLO model pre-downloaded to world_patrol + sim_uni"
+
+      - name: Run tests
+        shell: pwsh
+        run: |
+          chcp 65001
+          $OutputEncoding = [System.Text.Encoding]::UTF8
+          [Console]::InputEncoding = [System.Text.Encoding]::UTF8
+          [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+          .\.venv\Scripts\Activate.ps1
+
+          uv run pytest sr-od-test/ -v --tb=short --color=yes
+        env:
+          PYTHONIOENCODING: utf-8
+
+
+      - name: Test failure notification
+        if: failure()
+        run: |
+          $message = @"
+            ::notice::当前触发事件: ${{ github.event_name }}
+            ::error::测试失败！请检查上方的测试结果并修复问题。
+            ::notice::您可以fork测试仓库 https://github.com/OneDragon-Anything/sr-od-test 创建相同分支来修改测试代码
+            ::notice::您可以使用以下命令在本地运行测试: uv run pytest sr-od-test/ -v
+          "@
+          Write-Host $message
+        shell: pwsh

.gitignore

@@ -37,6 +37,7 @@ assets/ui/dynamic_background.webm
 
 # 执行文件
 *.exe
+*.exe.bak
 
 # 用户运行时产生的文件
 .temp
@@ -51,3 +52,13 @@ notice_cache/
 
 # 需自行下载的模型文件
 models/
+# AI 入口：.claude/ 整个不入库（CLAUDE.md 也是个人本地；团队共享走根 AGENTS.md）
+.claude/*
+CLAUDE.local.md
+
+# superpowers（规划文档/会话产物，不入库）
+docs/superpowers/
+.superpowers/
+
+# 装备图标采集调试标注(临时,不入库)
+assets/template/cw_equip/_debug/

AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS.md
+
+本文件是项目级 AI 编码协作入口，只保留会直接影响实现落点与提交流程的约束。
+详细规范与背景资料不要堆在这里，按需继续阅读：
+- AI 编码 harness 工程方法论：[docs/develop/harness/README.md](docs/develop/harness/README.md)
+- 上下文分层判据：[docs/develop/harness/context_layering.md](docs/develop/harness/context_layering.md)
+- 入口文件维护规范：[docs/develop/harness/entry_files.md](docs/develop/harness/entry_files.md)
+- AI 工具接入指引：[docs/develop/setup/ai_coding.md](docs/develop/setup/ai_coding.md)
+
+## 项目概述
+
+- 项目：星穹铁道一条龙（StarRail-OneDragon），面向 Windows 的崩坏星穹铁道自动化工具。
+- 语言与环境：Python 3.11、uv、PySide6。
+- 代码布局：`src-layout`，源码在 `src/`，运行时配置在 `config/`，资源在 `assets/`，开发文档在 `docs/develop/`。
+- 运行基准：1080p；配置以 YAML 为主。
+- 测试仓库独立维护：`sr-od-test/` 需要单独放在仓库根目录（已被 gitignore）。
+
+## 常用命令
+
+```shell
+uv sync --group dev
+uv run python src/sr_od/gui/sr_full_app.py
+uv run pytest sr-od-test/
+uv run ruff check src/你修改的文件.py
+uv run ruff check --fix src/你修改的文件.py
+```
+
+- 因 `pyproject.toml` 设 `[tool.uv] package = false`，运行前需确保 `PYTHONPATH=src`：PowerShell 执行 `$env:PYTHONPATH="src"`，或在项目根 `.env` 写入 `PYTHONPATH=src` 后改用 `uv run --env-file .env python src/sr_od/gui/sr_full_app.py`。
+- 也可以沿用 `debug.bat`（交互式调试入口，已设置好环境）。
+- 只对自己修改的文件运行 `ruff check`。
+- 不要对整个 `src/` 目录运行 ruff，现有仓库尚未全面适配。
+- 优先使用 Windows PowerShell 可直接执行的命令。
+
+## 架构落点
+
+### 1. 核心分层
+
+- `src/one_dragon/`：通用基础框架、配置、环境、工具、YOLO 能力。
+- `src/one_dragon_qt/`：通用 Qt GUI 框架与公共组件。
+- `src/onnxocr/`：OCR 引擎。
+- `src/sr_od/`：星穹铁道业务代码，包括 application、operation、context、gui 等。
+
+`one_dragon` / `one_dragon_qt` / `onnxocr` 是游戏无关的公共框架包（OneDragon 系列跨项目共享），星铁业务只在 `sr_od/`；公共框架的同步维护见 [common-package-sync.md](docs/develop/one_dragon/common-package-sync.md)。
+
+### 2. 功能开发优先路径
+
+- **涉及游戏流程的改动先理解再动手**：新功能 / debug / 修 bug 碰到自动化与游戏交互、游戏机制时，先读相关代码 + `screen_info` 弄清「bot 当前走到哪个画面、按什么玩法逻辑走」，知识缺失或过期按 `od-dev-screen-onboarding` 等 skill 补档，别凭猜改（凭猜 → 只覆盖一种情况、漏另一种 → 回归）。纯代码改动（重构 / 性能 / UI / 基建）不适用。
+- 新功能优先评估是否应做成 `SrApplication`，放在 `src/sr_od/application/`，并通过 `ApplicationFactory` 接入（参考现有 `world_patrol`、`sim_universe`、`trailblaze_power` 等 `XxxAppFactory`）。
+- 不要直接把新流程硬塞进主线逻辑；先复用现有 Application、Operation、配置体系与界面组件。
+- 新的设置界面优先沿用现有 setting card、`YamlConfigAdapter`、`AdapterInitMixin` 等模式。
+
+### 3. 关键运行机制
+
+- `SrContext`（继承 `OneDragonContext`）管理懒加载服务与配置；实例级配置变更要走 `reload_instance_config()`。
+- 操作链基于 `Operation` 编排；业务流程由 `SrApplication` 与各 `XxxAppFactory` 组装。
+- ONNX session 的异步调用必须通过 `one_dragon.utils.gpu_executor.submit`，不要并发直调多个 session。
+
+## 开发硬约束
+
+- 所有函数签名、类成员变量都要有类型注解；使用 `list[str]`、`X | Y`。
+- 注释与 docstring 用中文，保持现有项目风格。
+- 禁止相对导入；仅类型注解使用 `TYPE_CHECKING` 导入。
+- `__init__.py` 默认不要暴露模块，除非已有明确模式或收到明确要求。
+- 构造函数显式声明参数，不要用 `**kwargs`。
+- 路径操作使用 `pathlib`，字符串格式化使用 f-string。
+- GUI 优先复用 `pyside6-fluent-widgets` 与现有项目组件，保持 Fluent Design。
+- 配置改动优先落到 YAML 与对应 `YamlConfig` 子类，不要随意散落硬编码配置。
+- 1080p 坐标属于项目既有前提，可以按现有模式硬编码，不要额外做分辨率适配设计。
+- 模型文件（`.onnx` 等）走运行时资源下载，`.gitignore` 已忽略 `models/`，勿 `git add` 模型文件。
+
+## 文档与测试要求
+
+- 写文档 / skill / 注释 / 入口文件用直白表述，避免自造黑话或项目内部缩写（行业通用术语可用），首次出现的项目术语给定义 + 例子。
+- 修改代码后，同步更新对应的 `docs/develop/` 文档与 `sr-od-test/` 测试。
+- 提交前至少验证自己改动直接影响的部分（`ruff check` + 相关测试）；若无法本地完成，要明确说明缺失前提。
+- 复杂功能、架构调整或新自动化流程，先补设计/说明文档，再继续实现。
+
+## 提交流程与协作边界
+
+- 默认不要主动执行 `git commit`、`git push`、`git reset`、删分支等版本控制操作，除非用户明确要求。
+- 如果用户明确要求切换分支，先 `stash` 当前改动，再切换。
+- Review 关注逻辑错误、运行时崩溃、死循环、资源泄漏；不要为风格问题大改现有代码。
+- 提交 PR 后，review comment 需要逐条回复或修正。
+
+## 自维护指南
+
+修改 **AI 入口文件** `AGENTS.md`（团队共享 / 跨工具单一源，提交）时，必须先按 [entry_files.md](docs/develop/harness/entry_files.md) 的规范来：纯指令不掺杂元信息、只放 always-on 该留的（「删了会出错吗」逐条自检）、单一信息源（`AGENTS.md` 是源，工具入口 `@import` 引入）、共享文档改动先经用户确认。`.claude/CLAUDE.md` 是**个人本地**（`.claude/` 整个不入库，见 entry_files.md），个人随意改。
+
+## Skills
+
+本项目开发类 skill(`sr-od-dev-*`)用公共仓的 **`od-dev-writing-skills`** 指导编写(方法论:4 硬规范 / writing-craft / testing)。
+
+- **保存**:根 `skills/<name>/`(提交)。
+- **命名**:`sr-od-dev-` 前缀(星铁专属命名空间,防撞名);使用类 `sr-od-`。
+- **挂载**:junction `skills/<name>` → `.claude/skills/<name>`(本地,`.claude/` 不入库)。
+
+`od-dev-writing-skills` 本身从公共仓 `OneDragon-Skills` 挂载进本仓 `.claude/skills/`(可通用 skill 沉淀到公共仓,SR 独有业务留本仓)。详 [docs/develop/setup/ai_coding.md](docs/develop/setup/ai_coding.md)。
+
+## 深入阅读
+
+只在当前任务确实需要时继续看这些文档：
+- AI 编码 harness 工程：`docs/develop/harness/`
+- 打包说明：`.github/dev.md`
+- 业务模块架构：`docs/develop/one_dragon/`（按需补充）