@wwkit/harness 1.0.9 → 1.0.11

package/skills/pytest-env-ensure/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: pytest-env-ensure
+description: |
+  检查 Python uv 项目环境并加载测试代理配置。验证 uv 项目结构、检查并安装依赖插件、读取配置清单。
+  适用：测试代理启动前的环境准备，任何需要验证 pytest 运行环境的场景。
+  不适用：非 uv 管理的 Python 项目、非测试相关的环境检查。
+---
+
+# 环境检查与配置加载
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **uv 项目检查**：验证是否为 uv 管理的 Python 项目
+2. **依赖检查与安装**：检查依赖插件，未安装则自动安装
+3. **安装验证**：重新验证所有依赖是否可用
+4. **配置加载**：读取配置清单，输出给调用方
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| 无 | - | - | 自动检测当前工程 |
+
+## 输出
+
+- 配置对象（包含 dependencies、loops、metrics、naming、types 等字段）
+- 环境检查报告
+
+---
+
+## 阶段一：uv 项目检查
+
+**操作**：
+
+1. 检查 `pyproject.toml` 是否存在且包含 `[project]` 段
+2. 检查 `.venv/` 目录是否存在
+3. 运行 `uv run python --version` 验证 uv 可用
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| pyproject.toml 存在且 .venv 存在 | 进入阶段二 |
+| pyproject.toml 不存在 | **直接退出**，提示"当前 agent 仅支持 uv 项目，未找到 pyproject.toml" |
+| .venv 不存在 | **直接退出**，提示"当前 agent 仅支持 uv 项目，未找到 .venv 目录，请先运行 uv sync" |
+
+---
+
+## 阶段二：依赖检查与安装
+
+**输入**：读取 `references/config.md` 的 dependencies 清单
+
+**操作**：
+
+1. 逐个执行 `check` 命令验证是否已安装
+2. 对未安装的依赖，执行 `install` 命令
+3. 安装失败 → 重试（最多 3 次，由 config 的 `env.install_retry` 控制）
+4. `install` 为 null 的依赖（如 uv）→ 跳过安装，仅检查
+
+**重试逻辑**：
+
+```
+for each dependency:
+  if check passes:
+    mark as installed
+  else if install is null:
+    mark as missing (system-level, cannot auto-install)
+  else:
+    retry_count = 0
+    while retry_count < install_retry:
+      run install command
+      if check passes:
+        mark as installed
+        break
+      retry_count += 1
+    if still not installed:
+      mark as failed
+```
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部已安装 | 进入阶段三 |
+| 有 required 依赖安装失败 | **直接退出**，列出失败的依赖 |
+| 有非 required 依赖安装失败 | 记录警告，继续 |
+
+---
+
+## 阶段三：安装验证
+
+**操作**：对所有依赖重新执行 `check` 命令
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部通过 | 进入阶段四 |
+| 有 required 依赖未通过 | **直接退出**，列出未通过的依赖 |
+| 有非 required 依赖未通过 | 记录警告，继续 |
+
+---
+
+## 阶段四：pytest marker 注册检查
+
+**操作**：
+
+1. 读取 `pyproject.toml`
+2. 检查 `[tool.pytest.ini_options]` 段是否存在
+3. 检查 `markers` 列表是否包含 `unit` 和 `integration`
+
+**需要注册的 marker**：
+
+```toml
+[tool.pytest.ini_options]
+markers = [
+  "unit: 单元测试",
+  "integration: 集成测试",
+]
+```
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| marker 已注册 | 进入阶段五 |
+| marker 未注册 | 在 pyproject.toml 中添加上述 marker 配置 |
+| pyproject.toml 无 `[tool.pytest.ini_options]` 段 | 添加该段及 marker 配置 |
+| 无法写入 pyproject.toml | 记录警告，提示用户手动添加 |
+
+---
+
+## 阶段五：配置加载
+
+**操作**：
+
+1. 读取 `references/config.md`
+2. 解析配置项：dependencies、env、loops、metrics（unit + integration）、naming、types
+3. 输出配置对象给调用方（agent）
+
+**输出格式**：
+
+```
+## 环境检查报告
+
+### 项目检查
+- pyproject.toml: ✓
+- .venv: ✓
+- uv: ✓
+
+### 依赖检查
+| 依赖 | 状态 | 备注 |
+|------|------|------|
+| uv | ✓ 已安装 | 系统级 |
+| pytest | ✓ 已安装 | - |
+| pytest-cov | ✓ 已安装 | - |
+
+### Marker 检查
+- unit: ✓ 已注册
+- integration: ✓ 已注册
+
+### 配置已加载
+- coverage_threshold: 90 (unit) / 70 (integration)
+- outer_max: 3
+- inner_max: 3
+- test_root: tests
+```
+
+---
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 非 uv 项目 | 直接退出，提示仅支持 uv 项目 |
+| required 依赖安装失败（重试 3 次） | 退出，列出失败依赖 |
+| required 依赖验证不通过 | 退出，列出未通过依赖 |
+| config.md 不存在或格式错误 | 退出，提示配置文件缺失 |
+| 非项目特定错误 | 记录警告，不阻断流程 |
+
+## 一定要做
+
+1. 必须先检查 uv 项目结构，不满足直接退出
+2. 依赖检查必须读取 config.md 的 dependencies 清单
+3. 安装失败必须重试，重试次数由 config 控制
+4. 安装后必须重新验证
+5. 必须检查 pytest marker 注册，未注册时自动添加
+6. 最终输出完整的配置对象给调用方
+
+## 一定不要做
+
+1. 不要跳过 uv 项目检查
+2. 不要安装 install 为 null 的依赖（系统级工具）
+3. 不要忽略 required 依赖的失败
+4. 不要修改 config.md 文件内容
+5. 不要预设任何项目特定的依赖或配置

package/skills/pytest-env-ensure/references/config.md

@@ -0,0 +1,145 @@
+# pytest 测试代理配置清单
+
+> 本文件是测试代理的全局配置，agent 启动时首先读取，后续所有 skill 共享。
+
+## 依赖工具
+
+| name | check | required | install |
+|------|-------|----------|---------|
+| uv | `uv --version` | true | null（系统级工具，需手动安装） |
+| pytest | `uv run pytest --version` | true | `uv add --dev pytest` |
+| pytest-cov | `uv run pytest --cov --help` | true | `uv add --dev pytest-cov` |
+| pytest-timeout | `uv run pytest --timeout=1 --help` | true | `uv add --dev pytest-timeout` |
+| pytest-html | `uv run pytest --html --help` | false | `uv add --dev pytest-html` |
+
+## 环境检查
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| uv_project_check | true | 必须是 uv 项目（pyproject.toml + .venv/） |
+| install_retry | 3 | 插件安装失败重试次数 |
+
+## 超时配置
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| test_timeout_unit | 60 | 单元测试单用例超时（秒） |
+| test_timeout_integration | 300 | 集成测试单用例超时（秒） |
+
+## Loop 控制
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| outer_max | 3 | 外层 loop（coverage→create→execute）最大轮次 |
+| inner_max | 3 | 内层 loop（fix→execute）最大轮次 |
+
+## 测试指标 — 单元测试（unit）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| coverage_threshold | 90 | 覆盖率达标线 |
+| line_coverage_weight | 30 | 行覆盖率权重 |
+| branch_coverage_weight | 30 | 分支覆盖率权重 |
+| function_coverage_weight | 20 | 函数覆盖率权重 |
+| test_quality_weight | 20 | 用例质量权重 |
+
+## 测试指标 — 集成测试（integration）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| coverage_threshold | 70 | 覆盖率达标线 |
+| line_coverage_weight | 20 | 行覆盖率权重 |
+| branch_coverage_weight | 20 | 分支覆盖率权重 |
+| function_coverage_weight | 10 | 函数覆盖率权重 |
+| test_quality_weight | 50 | 用例质量权重（更重场景质量） |
+
+## 命名规则
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| test_root | tests | 测试根目录 |
+| dir_mapping_pattern | `tests/{type}/{package_module}` | 归一化仅去除 src/ 前缀，保留包名 |
+| report_dir_pattern | `{test_dir}/reports/{YYYYMMDD_HHMMSS}/` | 报告输出目录 |
+| report.test_report | `test_report.md` | 最终测试报告文件名 |
+| report.bug_list | `bug_list.md` | 源码 Bug 清单文件名 |
+| file.pattern | `test_{ModuleName}.py` | 测试文件命名 |
+| class.pattern | `test_{ModuleName}` | 测试类命名（与文件名一致） |
+| method.pattern | `test_{action}_{expected}` | 测试方法命名 |
+| fixture_file.name | conftest.py | 共享 fixture 文件名 |
+| fixture_file.data_dir | fixtures | 测试数据目录名 |
+
+### 目录映射算法（pyut/pyit agent Step 1 唯一权威定义）
+
+> pyut/pyit agent 的 Step 1 直接引用本算法，不另行重复定义。
+
+当用户未显式指定测试目录时，agent 按以下步骤自动推导 `test_dir`：
+
+**输入**: `source_path`（源码路径），`test_type`（unit 或 integration）
+
+**Step 1: 归一化源码路径**
+
+按顺序执行：
+
+1. 文件 → 取父目录
+2. 绝对路径 → 转为相对路径（相对于项目根目录）
+3. 含 `..` → 先 resolve 为标准路径再继续
+4. 为 `.` 或空 → 报错"请提供子目录路径，如 src/mypackage"
+5. 去除开头的 `./`
+6. 去除开头的 `src/`（仅去除一次）
+7. 归一化后为空 → 报错"归一化后路径为空，请提供 src/ 下的子目录"
+
+**归一化规则**：仅去除 `src/` 前缀，**保留包名及子模块路径**。无 `src/` 前缀的路径（flat layout）保持原样。
+
+**Step 2: 映射**
+
+```
+test_dir = tests/{test_type}/{归一化路径}/
+```
+
+**Step 3: 验证与创建**
+
+- `tests/` 不存在 → 自动创建 `tests/{test_type}/` 目录结构
+- 映射目录不存在 → 自动创建，标记为全新模式（无已有测试）
+
+### 映射示例
+
+| 源码路径 | test_type | 归一化 | 自动推导 test_dir |
+|---------|-----------|--------|------------------|
+| `src/pytest-sample` | unit | `pytest-sample` | `tests/unit/pytest-sample/` |
+| `src/mypackage/sub` | unit | `mypackage/sub` | `tests/unit/mypackage/sub/` |
+| `src/mypackage/MyService.py` | unit | `mypackage` | `tests/unit/mypackage/` |
+| `src/pytest-sample` | integration | `pytest-sample` | `tests/integration/pytest-sample/` |
+| `blues_lib/util` | integration | `blues_lib/util` | `tests/integration/blues_lib/util/` |
+| `mypackage/sub`（flat layout） | unit | `mypackage/sub` | `tests/unit/mypackage/sub/` |
+
+### 命名示例
+
+```
+源码路径:   src/mypackage/myservice
+模块名:     MyService
+测试目录:   tests/unit/mypackage/
+测试文件:   tests/unit/mypackage/test_MyService.py
+测试类:     test_MyService
+```
+
+## 测试类型
+
+### unit（单元测试）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| dir | tests/unit | 测试目录 |
+| marker | unit | pytest marker |
+| mock_strategy | full | 全部 Mock 外部依赖 |
+| coverage_focus | line, branch, function | 覆盖率关注点 |
+| timeout | 60 | 单用例超时（秒） |
+
+### integration（集成测试）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| dir | tests/integration | 测试目录 |
+| marker | integration | pytest marker |
+| mock_strategy | minimal | 最少 Mock，真实调用 |
+| coverage_focus | scenario, flow | 覆盖率关注点 |
+| timeout | 300 | 单用例超时（秒） |

package/skills/pytest-execute/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: pytest-execute
+description: |
+  执行 pytest 测试用例并输出测试报告。根据 test_type 选择对应测试目录，运行用例并解析结果。
+  适用：测试代理的测试执行阶段，运行已创建的用例并收集结果。
+  不适用：创建测试用例（使用 pytest-case-create）、修复失败用例（使用 pytest-case-fix）。
+---
+
+# 测试执行
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **选择目录**：根据 test_type 选择测试目录
+2. **执行测试**：运行 pytest
+3. **解析结果**：提取通过/失败/跳过统计
+4. **提取失败详情**：对每个失败用例提取详细信息
+5. **输出报告**：测试报告 + 失败详情
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target | 是 | string | 被测模块路径 |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 pytest-env-ensure 的配置对象 |
+| test_files | 否 | list | 指定测试文件（不指定则运行 test_dir 下全部） |
+
+## 输出
+
+- 测试报告（通过数/失败数/跳过数）
+- 失败详情列表（文件路径、用例名、错误类型、错误信息、堆栈）
+- 决策结论（全部通过 → 回到 coverage-analyze；有失败 → 交给 case-fix）
+
+---
+
+## 阶段一：选择目录
+
+**操作**：使用传入的 `test_dir` 作为测试目录
+
+如果指定了 test_files，则只运行指定的文件。
+
+---
+
+## 阶段二：执行测试
+
+**操作**：
+
+```
+# 运行 test_dir 下的测试（unit 超时 60s，integration 超时 300s）
+uv run pytest "{test_dir}" -v --tb=short --log-level=INFO --timeout={timeout} -m {test_type}
+
+# 如果指定了 test_files
+uv run pytest {test_files} -v --tb=short --log-level=INFO --timeout={timeout} -m {test_type}
+```
+
+**参数说明**：
+- `-v`：详细输出每个用例结果
+- `--tb=short`：失败时输出简短堆栈
+- `--log-level=INFO`：显示 INFO 级别日志
+- `-m {type}`：只运行对应 marker 的测试
+- `--timeout`：单用例超时秒数（unit=60, integration=300），来自 config
+
+---
+
+## 阶段三：解析结果
+
+**操作**：从 pytest 输出中提取：
+
+1. 统计数据：
+   - 通过数（passed）
+   - 失败数（failed）
+   - 跳过数（skipped）
+   - 错误数（error）
+   - 总数
+
+2. 对每个失败/错误用例提取：
+   - 文件路径
+   - 类名
+   - 方法名
+   - 错误类型（AssertionError, TypeError, ImportError 等）
+   - 错误信息（第一行错误描述）
+   - 堆栈信息（--tb=short 格式）
+
+---
+
+## 阶段四：输出报告
+
+**输出格式**：
+
+```
+## 测试执行报告
+
+### 统计
+- 总数：XX
+- 通过：XX
+- 失败：XX
+- 跳过：XX
+- 错误：XX
+- 通过率：XX%
+
+### 失败详情（如有）
+| # | 文件 | 类名 | 方法名 | 错误类型 | 错误信息 |
+|---|------|------|--------|---------|---------|
+| 1 | tests/unit/xxx/test_MyService.py | test_MyService | test_create_with_valid_data | AssertionError | assert result.id is not None |
+| 2 | tests/unit/xxx/test_MyService.py | test_MyService | test_parse_raises_on_empty | TypeError | argument cannot be None |
+
+### 失败堆栈（如有）
+#### 1. test_create_with_valid_data
+```
+E   assert result.id is not None
+E   assert None is not None
+tests/unit/xxx/test_MyService.py:15
+```
+
+### 结论
+- [全部通过] → 建议回到覆盖率分析阶段
+- [有失败] → 建议进入用例修复阶段，共 X 个失败需修复
+```
+
+---
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 全部通过（failed=0, error=0） | 输出"全部通过"，回到 coverage-analyze |
+| 有失败（failed>0 或 error>0） | 输出失败详情，交给 pytest-case-fix |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 测试目录不存在 | 输出"测试目录不存在"，提示需要先创建用例 |
+| pytest 执行错误（非测试失败） | 退出，输出错误信息 |
+| 无测试文件 | 输出"无测试文件"，通过率 0% |
+| pytest 超时 | 退出，提示测试执行超时，建议检查 hang 住的用例或增加 timeout |
+
+## 一定要做
+
+1. 必须使用传入的 test_dir 运行测试，并根据 test_type 选择 marker
+2. 必须使用 -v 输出详细结果
+3. 必须提取每个失败用例的详细信息
+4. 必须输出通过率
+5. 如果指定了 test_files，只运行指定文件
+
+## 一定不要做
+
+1. 不要修改测试文件或源码
+2. 不要跳过失败的用例
+3. 不要混合 unit 和 integration 的测试
+4. 不要忽略 pytest 执行错误
+5. 不要使用 --tb=long（堆栈过长影响分析）

package/skills/pytest-sample/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: pytest-sample
+description: |
+  在当前工程 src/ 下创建 pytest-sample 目录，注入一批 demo 类代码。
+  覆盖纯函数、HTTP Mock、DB Mock、文件系统、时间依赖、随机值、环境变量、状态机等多种测试场景。
+  demo 代码中故意注入了 15 个 bug（分 3 个难度梯度），用于触发测试代理的 create→test→fix 循环。
+  适用：首次使用 pyut/pyit agent 前的演示验证、测试 agent 流程的端到端测试。
+  不适用：生产代码、非测试目的的代码生成。
+---
+
+# Demo 样例代码注入
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **创建目录**：在 src/ 下创建 pytest-sample 包目录
+2. **写入文件**：从 references/src/pytest-sample/ 读取模板，写入到 src/pytest-sample/
+3. **验证**：检查所有文件语法正确
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| 无 | - | - | 自动在当前工程 src/ 下创建 |
+
+## 输出
+
+- src/pytest-sample/ 目录及 7 个文件
+- 各文件覆盖的测试场景清单
+- 故意 bug 清单及难度分级
+
+---
+
+## 阶段一：创建目录
+
+**操作**：创建 `src/pytest-sample/` 目录
+
+---
+
+## 阶段二：写入文件
+
+从 `references/src/pytest-sample/` 目录读取以下模板文件，写入到 `src/pytest-sample/`：
+
+| 文件 | 覆盖场景 |
+|------|---------|
+| __init__.py | 包初始化 |
+| Calculator.py | 纯函数、分支(if/elif)、异常(raise)、边界值、参数化 |
+| UserService.py | HTTP 请求(Mock)、数据库(Mock)、时间依赖(patch datetime)、验证逻辑 |
+| FileProcessor.py | 文件系统(tmp_path)、JSON 解析、文件不存在异常、目录操作 |
+| TokenGenerator.py | 随机值(patch random)、时间(patch time)、哈希、批量生成、边界检查 |
+| ConfigManager.py | 环境变量(monkeypatch)、单例模式、类型转换、默认值 |
+| OrderService.py | 复杂业务逻辑、状态机、多依赖、折扣计算(分支)、外部服务(Mock) |
+
+---
+
+## 阶段三：验证
+
+**操作**：
+
+```
+uv run python -m py_compile src/pytest-sample/*.py
+```
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部语法正确 | 输出创建报告 |
+| 有语法错误 | 修复后重新验证 |
+
+---
+
+## 故意 Bug 设计
+
+demo 代码中故意注入了 15 个 bug，分为 3 个难度梯度，用于尽可能触发测试代理的循环迭代。
+
+### Easy 难度（基础测试即可发现）
+
+| # | 文件 | 方法 | Bug 描述 | 触发方式 |
+|---|------|------|---------|---------|
+| 1 | Calculator.py | clamp | min/max 返回值互换 | 断言 clamp(0,1,10)==1 |
+| 2 | FileProcessor.py | write_file | 返回 len(content) 而非文件大小 | 写入多字节字符后断言 |
+| 3 | UserService.py | validate_email | TLD 正则 {2,}→{2} 拒绝 .com | 断言 validate_email("a@b.com")==True |
+
+### Medium 难度（需边界值/序列测试）
+
+| # | 文件 | 方法 | Bug 描述 | 触发方式 |
+|---|------|------|---------|---------|
+| 4 | Calculator.py | is_prime | sqrt+1→sqrt 漏检平方数 | 断言 is_prime(9)==False |
+| 5 | Calculator.py | fibonacci | range off-by-one | 断言 fibonacci(3)==2 |
+| 6 | FileProcessor.py | count_lines | 缺少 strip() 计入空白行 | 带首尾空行的文件断言 |
+| 7 | OrderService.py | _get_discount | >= → > 边界 | 断言 1000 元折扣为 10% |
+| 8 | OrderService.py | _get_tax | >= → > 边界 | 断言 500 元税率为 8% |
+| 9 | TokenGenerator.py | generate_uuid_like | 末段 12→11 字符 | UUID 格式正则验证 |
+
+### Hard 难度（需深入理解/非标准输入测试）
+
+| # | 文件 | 方法 | Bug 描述 | 触发方式 |
+|---|------|------|---------|---------|
+| 10 | ConfigManager.py | get_bool | 反转 truthy 逻辑，非标准字符串返回 True | 断言 get_bool(key, "unknown")==False |
+| 11 | ConfigManager.py | reset | 单例 _instance 未重置 | reset 后断言新实例 id 不同 |
+| 12 | OrderService.py | TRANSITIONS | created→delivered 非法跳转 | 断言该转换抛出 ValueError |
+| 13 | UserService.py | search_users | 返回完整 JSON 而非 results 字段 | 断言返回值为 list |
+| 14 | OrderService.py | create_order | 缺少 user_id 类型校验 | 传入字符串 user_id 断言 ValueError |
+| 15 | TokenGenerator.py | generate_token_with_timestamp | 时间戳含小数点 | 正则验证 token 格式 |
+
+---
+
+## 输出格式
+
+```
+## Demo 样例代码创建报告
+
+### 创建文件
+| 文件路径 | 类名 | 覆盖场景 |
+|---------|------|---------|
+| src/pytest-sample/__init__.py | - | 包初始化 |
+| src/pytest-sample/Calculator.py | Calculator | 纯函数、分支、异常、边界值 |
+| src/pytest-sample/UserService.py | UserService | HTTP Mock、DB Mock、时间 patch |
+| src/pytest-sample/FileProcessor.py | FileProcessor | 文件系统、JSON、异常 |
+| src/pytest-sample/TokenGenerator.py | TokenGenerator | 随机 Mock、时间 Mock、哈希 |
+| src/pytest-sample/ConfigManager.py | ConfigManager | 环境变量、单例、类型转换 |
+| src/pytest-sample/OrderService.py | OrderService | 状态机、多依赖、折扣计算 |
+
+### 故意 Bug 统计
+- Easy: 3 个（基础测试可发现）
+- Medium: 6 个（需边界值/序列测试）
+- Hard: 6 个（需深入理解/非标准输入）
+- 总计: 15 个
+
+### 使用方式
+1. 单元测试: /pyut src/pytest-sample
+2. 集成测试: /pyit src/pytest-sample
+
+### 场景覆盖说明
+- 纯函数测试: Calculator.add, Calculator.is_prime
+- 分支覆盖: Calculator.clamp, OrderService._get_discount
+- 异常路径: Calculator.divide(0), UserService.create_user(无email)
+- 边界值: Calculator.factorial(0), TokenGenerator.generate_token(1)
+- HTTP Mock: UserService.create_user
+- DB Mock: UserService.get_user, OrderService.create_order
+- 文件系统: FileProcessor.read_file, FileProcessor.write_file
+- 时间 Mock: UserService.update_last_login, OrderService.create_order
+- 随机 Mock: TokenGenerator.generate_token
+- 环境变量: ConfigManager.get_database_url
+- 状态机: OrderService.update_status
+- 参数化: Calculator.is_prime, Calculator.factorial
+```
+
+## 一定要做
+
+1. 必须在 src/pytest-sample/ 目录下创建文件
+2. 必须从 references/src/pytest-sample/ 读取模板内容写入
+3. 创建后必须验证语法正确
+4. 必须输出场景覆盖说明
+5. 必须保留 demo 中的故意 bug，不要修复
+
+## 一定不要做
+
+1. 不要修改 src/ 下已有的其他文件
+2. 不要在 demo 代码中导入项目特定的三方库
+3. 不要跳过语法验证
+4. 不要修复 demo 中的故意 bug（它们是设计意图）