chore: minor doc polish after refactor review

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-05-10 11:56:05 +08:00
parent 5c18d308bb
commit d347e36fea
4 changed files with 9 additions and 7 deletions

View File

@@ -461,7 +461,7 @@ python scripts/main.py <your-command>
新 skill 不应该等所有业务做完才补测试。建议在每个开发阶段都先把对应测试跑一遍: 新 skill 不应该等所有业务做完才补测试。建议在每个开发阶段都先把对应测试跑一遍:
1. **目录搭建后**:跑 `python tests/run_tests.py -v`,确认 6 个默认测试套件全部通过。 1. **目录搭建后**:跑 `python tests/run_tests.py -v`,确认全部默认测试套件通过。
- 此时 `test_skill_metadata.py` 会校验 `SKILL.md` slug 与 `constants.SKILL_SLUG` 一致;如果你只改了一边,会立刻发现。 - 此时 `test_skill_metadata.py` 会校验 `SKILL.md` slug 与 `constants.SKILL_SLUG` 一致;如果你只改了一边,会立刻发现。
2. **改完 constants 后**:再跑一次必跑套件,确认未引入回归。 2. **改完 constants 后**:再跑一次必跑套件,确认未引入回归。
3. **写完 service 业务后**:从 `tests/samples/test_service_contract.py.sample` 复制一份做契约测试。 3. **写完 service 业务后**:从 `tests/samples/test_service_contract.py.sample` 复制一份做契约测试。

View File

@@ -217,6 +217,8 @@
- skill 可以正常安装 - skill 可以正常安装
- 安装后可在“新建任务”中调用 - 安装后可在“新建任务”中调用
**测试与日志相关验收(所有新 skill 必须满足)**
- `python tests/run_tests.py -v` 必跑测试全部通过 - `python tests/run_tests.py -v` 必跑测试全部通过
- 任务日志task_logs写入和查询符合预期 - 任务日志task_logs写入和查询符合预期
- 真实联调(如有)已在 tests/integration/ 中验证,且默认套件不包含真实外联 - 真实联调(如有)已在 tests/integration/ 中验证,且默认套件不包含真实外联

View File

@@ -101,7 +101,7 @@ def test_whatever():
**何时用它**service 层出现『调用第三方 HTTP / RPA stub』但又不能把真实系统纳入 CI。**契约测试**(复制 [`tests/samples/test_service_contract.py.sample`](../tests/samples/test_service_contract.py.sample))应优先组合 FakeAdapter而不是直接把 CLI when-json 断言堆上天。 **何时用它**service 层出现『调用第三方 HTTP / RPA stub』但又不能把真实系统纳入 CI。**契约测试**(复制 [`tests/samples/test_service_contract.py.sample`](../tests/samples/test_service_contract.py.sample))应优先组合 FakeAdapter而不是直接把 CLI when-json 断言堆上天。
把它看成:**你把不确定性折叠进可控表格**,而不是在生产日志里才第一次看到错位字段。 把它看成:**你把不确定性收敛到可控的测试矩阵里**,而不是在生产日志里才第一次看到错位字段。
--- ---
@@ -124,12 +124,12 @@ Golden fixture 流程同理([`tests/samples/test_golden_cases.py.sample`](../t
任何 touching **真实租户数据** 的路径: 任何 touching **真实租户数据** 的路径:
1. **禁止**硬编码 token / cookie / 内部域名落入仓库; 1. **禁止**硬编码 token / cookie / 内部域名落入仓库;
2. **禁止**默认套件 silent import integration 2. **禁止**默认套件隐式导入 integration
3. **真实 RPA** 只能标记为手动触发(双人复核 / 本地 `.env` 不入库)。 3. **真实 RPA** 只能标记为手动触发(双人复核 / 本地 `.env` 不入库)。
范式阅读 [`tests/integration/README.md`](../tests/integration/README.md):那里有针对凭证来源、目录 artifact 忽略策略的补充。 范式阅读 [`tests/integration/README.md`](../tests/integration/README.md):那里有针对凭证来源、目录 artifact 忽略策略的补充。
记住:**测试代码也是一种部署面**,别把 staging 凭证烘焙进来 记住:**测试代码也是一种部署面**,别把 staging 凭证写死进仓库
--- ---
@@ -156,9 +156,9 @@ Golden fixture 流程同理([`tests/samples/test_golden_cases.py.sample`](../t
| 红线 | 解释 | | 红线 | 解释 |
|------|------| |------|------|
| 不改业务凑测试 | 除非需求变更已确认,否则别让 CI 绿通过阉割业务分支达成 | | 不改业务凑测试 | 除非需求变更已确认,否则**不要为了让 CI 变绿而砍掉业务分支** |
| **默认套件零外联** | 不把真实 HTTP / 浏览器写进 `tests/test_*.py` | | **默认套件零外联** | 不把真实 HTTP / 浏览器写进 `tests/test_*.py` |
| `.sample` 尊重 | 集成范式改名前先读完 README别让 `.sample` silent 变成根测试 | | `.sample` 尊重 | 集成范式改名前先读完 README别让 `.sample` 悄悄变成根测试 |
| **零硬编码凭证** | token / cookie / 生产 URL → 用虚构域名或 vault ref | | **零硬编码凭证** | token / cookie / 生产 URL → 用虚构域名或 vault ref |
| mock 优先 | 逻辑应在 service + FakeAdapter而不是巨胖 CLI 断言 | | mock 优先 | 逻辑应在 service + FakeAdapter而不是巨胖 CLI 断言 |
| 结构化错误 | 断言错误码字段,而不是 substring of stderr 漂移集合 | | 结构化错误 | 断言错误码字段,而不是 substring of stderr 漂移集合 |

View File

@@ -70,7 +70,7 @@ python tests/run_tests.py test_cli_smoke
| **subprocess 真实入口** ``python scripts/main.py`` | ``test_entrypoint_subprocess.py`` | | **subprocess 真实入口** ``python scripts/main.py`` | ``test_entrypoint_subprocess.py`` |
| 运行路径与 **CLAW_*/JIANGCHANG_*** 隔离 | ``test_runtime_paths.py`` | | 运行路径与 **CLAW_*/JIANGCHANG_*** 隔离 | ``test_runtime_paths.py`` |
| ``SKILL.md`` slug 与 ``constants.SKILL_SLUG`` | ``test_skill_metadata.py`` | | ``SKILL.md`` slug 与 ``constants.SKILL_SLUG`` | ``test_skill_metadata.py`` |
| DB / ``publish_logs`` 骨架冒烟 | ``test_db_smoke.py`` | | DB / ``task_logs`` 骨架冒烟 | ``test_db_smoke.py`` |
| **adapter profile / 外呼授权策略** | ``test_adapter_profile_policy.py`` + ``adapter_test_utils.py``(非 ``test_`` 前缀,不自动当用例收集) | | **adapter profile / 外呼授权策略** | ``test_adapter_profile_policy.py`` + ``adapter_test_utils.py``(非 ``test_`` 前缀,不自动当用例收集) |
### 1.3 数据隔离(``_support.IsolatedDataRoot`` ### 1.3 数据隔离(``_support.IsolatedDataRoot``