test: 归一测试树(主仓 tests/ -> zzz-od-test/test/)+ entry 文档告知

.github/workflows/test-check.yml

@@ -68,7 +68,6 @@ jobs:
             uv run pytest zzz-od-test/ -v --tb=short --color=yes
           }
         env:
-          PYTHONPATH: src
           PYTHONIOENCODING: utf-8
           PUSH_SERVER_CHAN_PUSH_KEY: ${{ secrets.PUSH_SERVER_CHAN_PUSH_KEY }}
           PUSH_DD_BOT_SECRET: ${{ secrets.PUSH_DD_BOT_SECRET }}

AGENTS.md

@@ -14,7 +14,7 @@
 - 语言与环境：Python 3.11、uv、PySide6。
 - 代码布局：`src-layout`，源码在 `src/`，运行时配置在 `config/`，资源在 `assets/`，开发文档在 `docs/develop/`。
 - 运行基准：1080p；配置以 YAML 为主。
-- 测试仓库独立维护：`zzz-od-test/` 需要单独放在仓库根目录。
+- 所有测试统一在独立仓 `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)。
 
 ## 常用命令
 

docs/develop/setup/ai_coding.md

@@ -64,6 +64,10 @@ New-Item -ItemType HardLink -Path "CLAUDE.md" -Target "AGENTS.md"
 - **推荐**：[context7](https://github.com/upstash/context7) — 查询库文档；已在本项目 `.claude/settings.json` 启用（Claude Code 场景）。
 - **项目自有 MCP（感知/操作 tool 已实现）**：把游戏感知/操作（窗口状态 / 截图 / OCR / 进游戏 + 运行态查/停）经 MCP 暴露给 agent，辅助开发与调试。传输 streamable-http（端点 `/mcp`，默认端口 23001）。先起服务（`uv run --env-file .env python -m zzz_od.backend.entry.server`），再 `claude mcp add --transport http zzz_od http://127.0.0.1:23001/mcp`。**工具清单见 [zzz/backend/mcp.md](../zzz/backend/mcp.md)**（不在此列举，避免随实现演进过时）；整体设计见 [zzz/backend/](../zzz/backend/)，路线图见 [harness/README.md](../harness/README.md)。
 
+## 测试仓
+
+测试代码在独立仓 `zzz-od-test/`(`.gitignore`,clone 到项目根目录),不在主仓。Claude Code 的 Grep/Glob 默认尊重 `.gitignore`,**不会自动搜** `zzz-od-test/`——查/改测试须 `Read`/`grep` 显式指定 `zzz-od-test/` 路径。clone 指引见 [quickstart §②](quickstart.md#②-跑测试可选),规范见 [spec/agent_guidelines.md](../spec/agent_guidelines.md#测试代码规范)。
+
 ## LSP
 
 项目用 **uv 方式 pyright** 做 LSP(代码导航:定义 / 引用 / 符号)——不用 Claude Code 官方的全局 pyright(走系统 PATH,解析不到项目 `.venv` 依赖,跟 uv 环境冲突)。pyright 在 dev 组、`[tool.pyright]` 配置(团队共享);Claude Code 的插件安装见 [claude-code/pyright-lsp.md](claude-code/pyright-lsp.md)。

docs/develop/spec/agent_guidelines.md

@@ -95,8 +95,10 @@ uv run --env-file .env ruff format src/你修改的文件.py # 仅格式化自
 
 ## 测试代码规范
 
+- **所有测试统一放在 `zzz-od-test/test/`,主仓不保留测试**(`tests/` 已废弃)。新测试一律加到 `zzz-od-test/test/` 对应被测包路径下。
+
 - 测试文件路径约定: 测试文件的目录路径应该是被测文件的包路径+被测文件名的文件夹。
-  - 示例: 对于被测文件`one_dragon.base.operation.one_dragon_context.py`，应创建`zzz-od-test/tests/one_dragon/base/operation/one_dragon_context/`文件夹，里面存放多个测试用例文件。
+  - 示例: 对于被测文件`one_dragon.base.operation.one_dragon_context.py`，应创建`zzz-od-test/test/one_dragon/base/operation/one_dragon_context/`文件夹，里面存放多个测试用例文件。
 - 单方法测试文件: 每个Python测试文件应专门用于测试单个方法的各种场景。
   - 示例: 要测试`method_a`方法，创建一个名为`test_method_a.py`的文件。该文件应包含专门针对`method_a`方法的所有测试用例。
 - 测试类: 测试文件必须使用测试类(以`Test`为前缀)来组织相关测试方法。

pyproject.toml

@@ -105,3 +105,8 @@ extraPaths = ["src"]  # src-layout + package=false：让 pyright 去 src/ 解析
 # TODO(type-check): typeCheckingMode 暂 off——只用导航（定义/引用/符号），不刷类型诊断。
 #   现有代码尚未 type-clean，后续随改造逐步提升 → basic → standard。
 typeCheckingMode = "off"
+
+# Pytest 配置：src-layout + package=false，让 pytest 自动把 src/ 加入 sys.path
+# (取代 CI 的 PYTHONPATH=src env 和测试文件里手动的 sys.path.insert)
+[tool.pytest.ini_options]
+pythonpath = ["src"]