继续完善测试模板

tests/README.md

@@ -6,6 +6,43 @@
 
 ---
 
+## 我该把测试写在哪里？
+
+人类开发者与 Cursor 等 AI 工具在加用例前，先对照下表决定**文件落点**与**是否默认执行**：
+
+| 场景 | 放在哪里 | 默认是否运行 | 说明 |
+|------|----------|--------------|------|
+| CLI / health / version / metadata / runtime 路径 | `tests/test_*.py` | 是 | 默认必跑，保持轻量、无外联 |
+| 纯函数 / 业务规则 | `tests/test_*.py` | 是 | 不依赖真实外部系统 |
+| service 层契约 | 从 `tests/samples/test_service_contract.py.sample` 复制到 `tests/test_service_contract.py` | 是，复制后 | 用 `FakeAdapter` / stub 注入外部依赖 |
+| golden fixture 回归 | 从 `tests/samples/test_golden_cases.py.sample` 复制到 `tests/test_golden_cases.py` | 是，复制后 | 输入样例 + 期望输出，适合解析、计算、校验类技能 |
+| 仿真 API | `tests/integration/test_simulator_api_contract.py.sample` | 否 | 复制并设置 `OPENCLAW_TEST_TARGET=simulator_api`（或兼容键名 `OPENCLOW_TEST_TARGET`）后按需运行 |
+| 仿真 RPA / 页面操作 | `tests/integration/test_simulator_rpa_contract.py.sample` | 否 | 用 localhost / 仿真页面，不碰真实系统 |
+| 真实 API | `tests/integration/test_real_api_contract.py.sample` | 否 | 必须 `OPENCLAW_TEST_TARGET=real_api` 且 `ALLOW_REAL_API=1` |
+| 真实 RPA | `tests/integration/test_real_rpa_contract.py.sample` | 否 | 最高风险，只能手动触发 |
+| 桌面宿主 E2E | `tests/desktop/test_desktop_smoke.py.sample` | 否 | 需要 pytest + `jiangchang_desktop_sdk` |
+
+说明：`python tests/run_tests.py` **只**收集 `tests/` **根目录**下的 `test_*.py`；子目录里的 `*.sample` 与 desktop 用例**不会**被默认发现。
+
+---
+
+## 新技能最小测试清单
+
+从本模板复制出新技能仓库后，建议至少逐项确认：
+
+- [ ] `python tests/run_tests.py -v` 能通过。
+- [ ] `python scripts/main.py health` 能通过。
+- [ ] `python scripts/main.py version` 输出 JSON，且 `skill` 与目录名 / `SKILL.md` / `constants.SKILL_SLUG` 一致。
+- [ ] 所有 DB / 文件写入都在 `IsolatedDataRoot`（或等价隔离）下测试，不写真实数据目录。
+- [ ] 外部系统默认使用 mock / `FakeAdapter`，不访问真实 API，不打开真实 RPA。
+- [ ] 至少有 1 个成功路径测试。
+- [ ] 至少有 1 个缺必填字段 / 非法输入测试。
+- [ ] 如果有 adapter，至少覆盖 timeout / unauthorized / invalid response（可用 fake 模拟）。
+- [ ] 如果有解析 / 计算 / 校验类业务，至少保留 1 组 golden fixture（脱敏）。
+- [ ] 真实 API / 真实 RPA 测试只放 `tests/integration/`，并且默认 `.sample`，不默认运行。
+
+---
+
 ## 1. 默认必跑（unittest）
 
 在**技能仓库根目录**执行：
@@ -113,6 +150,21 @@ python tests/run_tests.py test_cli_smoke
 
 ---
 
+## AI 编程工具注意事项（Cursor 等）
+
+以下约束适用于为本仓库或复制出的技能编写/修改测试时，**避免误伤业务与生产**：
+
+- **不要为了**让测试通过去改业务代码，除非用户明确要求修改实现。
+- **不要**把真实外部系统调用写进默认的 `tests/test_*.py`（默认套件须无外联、无真实浏览器）。
+- **不要**把 `*.sample` 改名为可执行测试或移入根目录并去掉 `.sample`，除非用户明确要求启用 integration / 真实联调。
+- **不要**硬编码真实凭证、token、cookie、生产 URL；占位请用明显虚构域名（如 `example.invalid`）或文档约定的 `credential_ref`。
+- 默认测试只能使用 **mock、stub、`FakeAdapter`、fixtures、隔离 SQLite** 等安全手段。
+- 业务逻辑应优先在 **service 层** 编写与测试，不要只断言 CLI 文案。
+- 异常路径应返回**结构化错误**（如统一错误码/字段），避免裸异常直接穿透到 CLI。
+- 有真实系统联调需求时，测试应写在 `tests/integration/`，并配合 `OPENCLAW_TEST_TARGET` / `ALLOW_REAL_*` / `ALLOW_WRITE_ACTIONS` 等**显式开关**；不得默认开启。
+
+---
+
 ## 6. 与 content-manager 的关系
 
 - **未**复制 article / media / prompt / NotebookLM 等业务测试。