@wwkit/harness 1.0.27 → 1.0.29

package/skills/jstest/references/test-standards.md

@@ -0,0 +1,288 @@
+# 测试用例创建规范
+
+> 本规范适用于 JS/TS Jest 测试框架，包含通用规范、JS/jest 特定规范、以及单元/集成测试专属规范。
+
+## 一、通用规范
+
+### AAA 模式（Arrange-Act-Assert）
+
+每个测试用例分为三段：
+
+```javascript
+describe('MyService', () => {
+  test('should create with valid data', () => {
+    // Arrange — 准备
+    const service = new MyService();
+    const data = { name: 'test', age: 18 };
+
+    // Act — 执行
+    const result = service.create(data);
+
+    // Assert — 断言
+    expect(result.id).toBeDefined();
+    expect(result.name).toBe('test');
+  });
+});
+```
+
+### FIRST 原则
+
+| 原则 | 说明 |
+|------|------|
+| Fast | 快速执行（单元测试秒级，集成测试分钟级） |
+| Isolated | 测试间相互独立，不依赖执行顺序 |
+| Repeatable | 可重复运行，结果稳定 |
+| Self-Validating | 自动断言，无需人工判断 |
+| Timely | 与开发同步编写 |
+
+### 命名规范
+
+| 元素 | 规则 | 示例 |
+|------|------|------|
+| 文件名 | `{ModuleName}.test.js` | `MyService.test.js` |
+| describe 名 | `'ModuleName'` | `describe('MyService', ...)` |
+| test/it 名 | `'should {action} {expected}'` | `test('should create with valid data', ...)` |
+
+用例命名要素：
+- **action**：被测方法名或核心行为（create, send, parse）
+- **expected**：输入条件或预期结果（with valid data, throw on timeout）
+
+### 一个用例一个行为
+
+每个 test/it 只验证一个行为，不混合多个断言逻辑。
+
+## 二、JS/jest 特定规范
+
+### describe/test/it 结构
+
+遵循 AGENTS.md 规则：
+- 2 空格缩进
+- describe/test/it 函数式（非类风格）
+- 一个文件内只定义一个顶层 describe
+- ESM 项目使用 `import`/`export`
+
+```javascript
+import { MyService } from '../../../src/mypackage/MyService.js';
+
+describe('MyService', () => {
+
+  test('should create with valid data', () => {
+    // Arrange
+    const service = new MyService();
+    // Act
+    const result = service.create({ name: 'test' });
+    // Assert
+    expect(result.id).toBeDefined();
+  });
+});
+```
+
+### setup/teardown 使用
+
+```javascript
+describe('MyService', () => {
+
+  beforeEach(() => {
+    // 每个测试前初始化
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    // 每个测试后清理
+    process.env.NODE_ENV = 'test';
+  });
+
+  beforeAll(() => {
+    // 所有测试前执行一次
+  });
+
+  afterAll(() => {
+    // 所有测试后执行一次
+  });
+
+  test('should create with valid data', () => {
+    const service = new MyService();
+    const result = service.create({ name: 'test' });
+    expect(result.id).toBeDefined();
+  });
+});
+```
+
+### Mock/Stub 使用
+
+```javascript
+import { MyService } from '../../../src/mypackage/MyService.js';
+
+jest.mock('../../../src/mypackage/MyService.js');
+
+describe('MyService', () => {
+
+  test('should process returns data from remote', () => {
+    // Stub — 预设返回值
+    const mockFetchRemote = jest.fn().mockResolvedValue({ key: 'value' });
+    const service = new MyService({ fetchRemote: mockFetchRemote });
+
+    // Act
+    return service.process().then(result => {
+      // Mock — 验证调用行为
+      expect(mockFetchRemote).toHaveBeenCalledTimes(1);
+      expect(result.key).toBe('value');
+    });
+  });
+});
+```
+
+### 参数化测试
+
+```javascript
+describe('MyValidator', () => {
+
+  test.each([
+    [18, true],
+    [30, true],
+    [60, true],
+    [17, false],
+    [61, false],
+    [-1, false],
+  ])('should validate age %i → %s', (age, expected) => {
+    expect(MyValidator.validateAge(age)).toBe(expected);
+  });
+});
+```
+
+### 异常断言
+
+```javascript
+describe('MyService', () => {
+
+  test('should throw on empty name', () => {
+    const service = new MyService();
+    expect(() => service.create({ name: '' })).toThrow('name不能为空');
+  });
+
+  test('should throw specific error type', () => {
+    const service = new MyService();
+    expect(() => service.create({ name: '' })).toThrow(TypeError);
+  });
+});
+```
+
+### jest test category
+
+```javascript
+// unit 测试 — 在 package.json jest 配置或 testNamePattern 中区分
+describe('MyService', () => {
+  // 单元测试
+});
+
+// integration 测试 — 按目录组织（tests/integration/）
+describe('LoginFlow', () => {
+  // 集成测试
+});
+```
+
+## 三、单元测试专属规范（unit）
+
+### Mock 策略：full — 全部 Mock 外部依赖
+
+| 依赖类型 | 处理策略 | 示例 |
+|---------|---------|------|
+| HTTP 请求 | Mock：mock 请求方法，预设返回值 | `jest.mock('axios')` / mock fetch |
+| 数据库操作 | Fake：内存数据库 或 mock 模块 | `jest.mock('db-module')` |
+| 文件系统 | Fake：使用 `os.tmpdir()` 或 mock | `jest.mock('fs')` |
+| 时间依赖 | Mock：fake timers | `jest.useFakeTimers()` |
+| 随机值 | Mock：spyOn random | `jest.spyOn(Math, 'random').mockReturnValue(0.5)` |
+| 外部服务 | Mock：mock 发送方法 | `jest.mock('email-module')` |
+| 环境变量 | Stub：直接设置 process.env | `process.env.KEY = 'val'` |
+
+### 用例覆盖要求
+
+| 源码特征 | 必须创建的用例 |
+|---------|---------------|
+| 每个公开函数 | 至少 1 个正向用例 |
+| 含 if/else 分支 | 边界值用例（每个分支至少 1 个） |
+| 含 throw/try-catch | 异常路径用例（expect().toThrow()） |
+| 多输入场景 | 参数化用例（test.each / it.each） |
+| 有返回值 | 断言返回值类型和内容 |
+
+### 禁止事项
+
+- 禁止真实网络调用
+- 禁止操作真实文件系统
+- 禁止依赖真实时间
+- 禁止依赖随机值
+- 禁止测试间依赖（共享状态）
+- 禁止硬编码路径
+
+## 四、集成测试专属规范（integration）
+
+### Mock 策略：minimal — 最少 Mock，优先真实调用
+
+| 依赖类型 | 处理策略 |
+|---------|---------|
+| 内部模块 | 真实调用，不 Mock |
+| 数据库 | 真实连接（测试库）或 Fake 内存数据库 |
+| 文件系统 | 真实文件操作（使用 `os.tmpdir()` 清理） |
+| 外部 API | 仅 Mock 不可控的生产 API，测试环境 API 真实调用 |
+| 时间/随机 | 可接受真实值，或 `jest.spyOn` 固定 |
+
+### 用例组织
+
+- 按 **业务场景** 组织用例，不按函数
+- 每个场景覆盖完整流程：输入 → 处理 → 输出
+- 验证端到端数据流完整性
+
+```javascript
+import { OrderService } from '../../../src/mypackage/OrderService.js';
+
+describe('OrderFlow', () => {
+
+  let db;
+  let service;
+
+  beforeAll(() => {
+    // 场景级 setup
+    db = Database(testUrl);
+    service = new OrderService({ db });
+  });
+
+  afterAll(() => {
+    // 场景级 teardown
+    db.close();
+  });
+
+  test('should create order and send notification', async () => {
+    // 场景：创建订单并发送通知
+    // Arrange — 数据已在 beforeAll 准备
+
+    // Act
+    const order = await service.createOrder({ userId: 1, item: 'book' });
+    const notification = await service.sendNotification(order.id);
+
+    // Assert — 验证完整数据流
+    expect(order.id).toBeDefined();
+    expect(order.status).toBe('created');
+    expect(notification.orderId).toBe(order.id);
+    expect(notification.sent).toBe(true);
+  });
+});
+```
+
+### setup/teardown 使用
+
+- 使用 `beforeAll`/`afterAll` 的场景级 setup/teardown
+- teardown 负责清理测试数据
+- 数据准备放在 setup 中，不硬编码在测试用例内
+
+## 五、稳定性保障规则
+
+| 规则 | 说明 |
+|------|------|
+| 禁止真实网络 | 单元测试所有 HTTP 必须 Mock |
+| 禁止真实文件 | 文件操作使用 `os.tmpdir()` 或 `jest.mock('fs')` |
+| 禁止真实时间 | 时间依赖必须 `jest.useFakeTimers()` |
+| 禁止真实随机 | 随机值必须 `jest.spyOn` 或固定 |
+| 禁止真实外部服务 | 邮件/消息队列等必须 Mock（单元测试） |
+| 禁止测试间依赖 | 每个测试独立，不依赖执行顺序 |
+| 禁止硬编码路径 | 使用 `os.tmpdir()` 或相对路径 |
+| Mock 清理 | `afterEach` 中 `jest.clearAllMocks()` 或 `jest.restoreAllMocks()` |

package/skills/pytest/SKILL.md

@@ -11,23 +11,26 @@ metadata:
   workflow: sequential
 ---
 
-# pytest 技能
+# pytest 技能（固定 Sprint 冲刺）
 
-## 核心约束（最高优先级）
+## 执行范式
 
-- **MUST**：收到任务消息后，先 todowrite 落单 7 步，再逐步执行。
-- **MUST**：每步完成立即 todowrite 勾单。
-- **MUST**：test_type 只能是 unit、integration 或 sample，其他值报错退出。
-- **禁止**：混合测试类型（unit 不混合 integration，反之亦然）。
-- **禁止**：修改 conftest.py（除非直接导致失败）。
-- **MUST**：子工作流通过 `read` 加载 `references/xxx.md` 并按其指令执行，**不再调用独立 skill**（原 pytest-* 子 skill 已合并入 references/）。
+每次调用 = 一个固定 Sprint，三个事件：
+
+1. **Sprint Planning**：解析入参 → 定义 Sprint Goal → todowrite 落固定 7 项 Sprint Backlog（每项带 DoD）
+2. **Sprint Execution**：7 步 + 双层 loop 逐项执行，每项 = 执行 → 验证 DoD → todowrite 勾单 Done
+3. **Sprint Review**：对照 Sprint Goal 验证 Increment（测试报告）及输出语义，沉淀 1 条回顾
 
-## 第一步硬指令（自检）
+**Sprint Goal** = `对 {{source}} 执行 {{test_type}} 测试，产出测试质量报告（unit 达标 score≥90，integration 达标 score≥70）`。
 
-解析入参前，强制自检：
-> 我是否已用 todowrite 落单 7 步？
-> - 未落单 → 立即 todowrite 创建清单。
-> - 已落单 → 继续。
+**铁律（最高优先级）：**
+
+- **没有 Sprint Backlog 不能开始执行**：收到任务消息后，先做 Sprint Planning（解析入参）再 todowrite 落固定 7 项 Sprint Backlog，然后才进入 Sprint Execution。
+- **每项执行周期** = 进度检查（Daily Scrum 映射）→ 执行 → 验证 DoD → 勾单 Done。
+- **子工作流通过 `read` 加载 `references/xxx.md` 并按其指令执行**，**不再调用独立 skill**（原 pytest-* 子 skill 已合并入 references/）。
+- **禁止**：混合测试类型（unit 不混合 integration，反之亦然）。
+- **禁止**：修改 conftest.py（除非直接导致失败）。
+- **禁止**：使用 WebFetch 或任何网络请求。
 
 ## 配置表（按 test_type 分支）
 
@@ -57,14 +60,7 @@ metadata:
 
 ## 输入参数（自包含）
 
-入参为调用方传入的**原始任务消息**，可能是以下任一形态：
-
-- **JSON 对象**：`{test_type, source, test_dir}`，直接取字段值。
-- **key=value**：`test_type=unit, source=src/mymodule`，按 `,` 和 `=` 拆分为字段。
-- **纯文本 prose**：含 "集成/integration" → integration；含 "单元/unit" → unit；默认 unit。`source` 从文本中出现的路径推断。
-- **命令风格**：`unit src/mymodule` 或 `integration src/mymodule tests/integration/mymodule`，第一段为 test_type，第二段为 source，第三段（可选）为 test_dir。
-
-字段清单：
+入参为调用方传入的**原始任务消息**，可为 JSON 对象、key=value、自然语言或命令风格等任意形态，agent 依据字段语义自主提取（详见 Step 1）。字段清单：
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
@@ -72,6 +68,8 @@ metadata:
 | source | string | 是 | 源码包目录或 .py 文件路径 |
 | test_dir | string | 否 | 测试目录；未指定时按 `tests/{test_type}/{归一化路径}/` 自动推导 |
 
+**提取原则**：从消息中自主识别三个字段——命令风格（`unit src/mymodule` 或 `integration src/mymodule tests/integration/mymodule`，第一段为 test_type，第二段为 source，第三段可选为 test_dir）、JSON 对象（`{test_type, source, test_dir}`）、key=value（`test_type=..., source=...`）、或自然语言（含 "集成/integration" → integration；含 "单元/unit" → unit；默认 unit；`source` 从出现的路径推断）。
+
 **必填校验**：若无法解析出 `test_type` 或 `source`，将错误信息输出到 stderr 并结束，**禁止**继续执行。
 
 **test_type 校验**：解析后若 `test_type` 不在 `{unit, integration, sample}` 中，输出 "test_type 只能是 unit、integration 或 sample，得到: {value}" 并结束。
@@ -84,17 +82,19 @@ metadata:
 
 ## 工作流程
 
-### 阶段 0：todowrite 落单
+### 阶段 0：todowrite 落单（Sprint Backlog）
 
-收到任务消息后，先用 `todowrite` 创建 7 步清单（status=pending）：
+收到任务消息后，先用 `todowrite` 创建固定 7 项 Sprint Backlog（status=pending），每项带 DoD：
 
-1. 入参校验与目录映射（test_type + source + test_dir）
-2. 模块适用性评估
-3. 环境检查（+ integration 补充检查）
-4. 覆盖率分析（外层 loop）
-5. 用例创建
-6. 测试执行
-7. 用例修复（内层 loop）
+| # | 任务 | 对应 Step | DoD |
+|---|------|----------|-----|
+| 1 | 入参校验与目录映射 | Step 1 | test_type/source/test_dir 已校验，target/test_dir/report_dir/flow_start_time 已确定，7 项清单已建 |
+| 2 | 模块适用性评估 | Step 2 | 得到 testable_classes（或为空已按原因退出） |
+| 3 | 环境检查 | Step 3 | 得到 config（或 env-ensure 失败已退出）；integration 补充检查已记录警告 |
+| 4 | 覆盖率分析（外层 loop） | Step 4 | 得到 score/uncovered_areas，按退出条件结束或进入下一轮 |
+| 5 | 用例创建 | Step 5 | 得到 new_cases_count（=0 已跳过 execute+fix 直接轮尾评分） |
+| 6 | 测试执行 | Step 6 | 得到通过/失败结果（有失败已进入 Step 7） |
+| 7 | 用例修复（内层 loop） | Step 7 | 得到修复结果，按内层退出条件回到 Step 6 或 Step 4 轮尾评分 |
 
 每步完成立即 todowrite 勾单（status=completed）。
 
@@ -502,6 +502,14 @@ integration:
 - 内容：上述完整报告（含源码 Bug 汇总）
 - 同时在 chat 中输出报告摘要
 
+## Sprint Review
+
+所有 Backlog Items 完成后：
+
+- **对照 Sprint Goal 验证**：是否对 `{{source}}` 完成 `{{test_type}}` 测试并产出测试质量报告？得分是否达标（unit≥90，integration≥70）？报告是否写入 `report_dir/test_report.md`？
+- **展示 Increment**：测试报告路径 + chat 摘要。
+- **简要回顾（Retrospective）**：沉淀 1 条改进项供下一轮采纳。
+
 ## 规则
 
 **共同规则**：

package/skills/query/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: query
 description: |
-  自包含内容生成 skill：每次调用 = 一个固定 Sprint——Sprint Planning（解析入参、定义 Sprint Goal、todowrite 落固定 Sprint Backlog）→ Sprint Execution（逐项执行并验证 DoD）→ Sprint Review（对照 Sprint Goal 校验交付 + 简要回顾）。
-  prompt 为任务要求（含输出格式说明），source 为可选素材，language 控制输出语言（默认中文）。
-  调用方直接传原始任务消息，skill 自解析自包含。内部用 todowrite 管理固定 3 项 Sprint Backlog（每项带 DoD）。禁止 WebFetch/网络请求。
-  适用：通用内容生成（摘要/改写/翻译/结构化提取等任意 prompt 驱动任务）。
+  自包含内容生成 skill（固定 Sprint 范式）：每次调用 = 一个固定 Sprint（Planning→Execution→Review），todowrite 落 3 项带 DoD 的 Sprint Backlog 并逐项验证，按输出语义交付生成内容。
+  prompt 为任务要求（含输出格式说明），source 为可选素材，language 控制输出语言（默认中文）。调用方直接传原始任务消息即可，无需预处理；禁止 WebFetch/网络请求。
 license: MIT
 metadata:
   workflow: sequential
@@ -18,13 +16,13 @@ metadata:
 
 1. **Sprint Planning**：解析入参 → 定义 Sprint Goal → todowrite 落固定 3 项 Sprint Backlog（每项带 DoD）
 2. **Sprint Execution**：逐项执行，每项 = 执行 → 验证 DoD → todowrite 勾单 Done
-3. **Sprint Review**：对照 Sprint Goal 验证 Increment（生成内容）及输出语义，沉淀 1 条回顾
+3. **Sprint Review**：对照 Sprint Goal 验证 Increment（生成内容）及输出语义
 
 **Sprint Goal** = `按 {{prompt}} 生成内容（语言 {{language}}），并按输出语义交付`。
 
 ## 输入参数
 
-入参为调用方传入的**原始任务消息**，可为 JSON 对象、key=value 或自然语言等任意形态，agent 依据字段语义自主提取（详见 Item 1）。字段清单（字段/类型/必填/默认值）以 `references/input.schema.json5` 为准：
+入参为调用方传入的**原始任务消息**，可为 JSON 对象、key=value 或自然语言等任意形态，agent 依据字段语义自主提取。字段清单（字段/类型/必填/默认值）：
 
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
@@ -33,71 +31,42 @@ metadata:
 | `language` | string | ❌ | 输出内容语言，默认 中文 |
 | `output` | string | ❌ | 输出文件路径（提供则写文件，否则 stdout） |
 
-本技能仅使用上表四个字段，忽略所有其他字段（如 `url`），不得读取、写入或据此推断任何行为。
+本技能仅使用上表四个字段，忽略所有其他字段（如 `url`）。
 
 ## 固定 Sprint Backlog（todowrite 落单，覆盖历史 todos）
 
-1. 解析入参（从任意形态任务消息自主提取 prompt/source/language/output） | DoD: 得到四个字段值（或 prompt 缺失时 stderr 报错结束）
-2. 内容生成（LLM 创作） | DoD: 按 prompt 生成内容，语言 language（默认中文），source 已按需解析为素材
-3. 输出（写 output 文件或 stdout） | DoD: 按输出语义交付（文件路径或 stdout），结果为空/失败时 stderr 报错
+1. 解析入参 | DoD: 四字段已提取（或 prompt 缺失时 stderr 报错结束）
+2. 内容生成 | DoD: 按 prompt 生成内容，语言 language（默认中文），source 已按需读取为素材
+3. 输出 | DoD: 按输出语义交付（文件路径或 stdout）
 
 ## Sprint Execution
 
-按固定 3 项逐项执行，每项周期 = 进度检查（刚完成什么/本项做什么/有无阻塞）→ 执行 → 验证 DoD → 勾单 Done。
+按固定 3 项逐项执行（勾单机制见执行范式）。
 
 ### Item 1：解析入参
 
-将第 1 项标记 in_progress，从原始任务消息中**自主提取**四个字段。入参可为 JSON 对象、key=value 或自然语言等任意形态，依据字段语义理解提取即可，无需固定解析规则。提取原则：
-
-- **自然语言推断**：从文本中推断提取参数（如"输出到xxx"→`output`、"素材xxx"→`source`、"用英文"→`language`），剩余内容作为 `prompt`；若无法提取，整段文本作为 `prompt`。
-
-解析后得到 `prompt`、`source`、`language`、`output` 四个字段（字段说明见上文输入参数表；`source`/`language`/`output` 缺省时留空由后续 Item 处理）。
-
-**必填校验**：若 `prompt` 为空、null 或仅含空白字符，将错误信息输出到 stderr 并结束，**禁止**继续执行。
-
-**验证 DoD**：四个字段值已得到（或 prompt 缺失已报错结束）。通过后标记 Done。
+从原始任务消息中自主提取 `prompt`/`source`/`language`/`output` 四个字段。`prompt` 为空、null 或仅含空白 → 将错误信息输出到 stderr 并结束，**禁止**继续执行。
 
 ### Item 2：内容生成
 
-将第 2 项标记 in_progress，先判断 `source` 是否提供：
-
-- `source` 非空时，若值为现有文件路径则用 `read` 读取文件内容作为素材；否则直接以值作为素材。
-- `source` 为空时，仅依据 `prompt` 生成内容。
-
-利用自身能力按 `prompt` 要求生成内容，输出语言使用 `language`（默认中文）。**禁止用 bash 解析 JSON**，直接依据内容理解处理。
-
-**验证 DoD**：已按 prompt 生成内容，语言 language（默认中文），source 已按需解析为素材。通过后标记 Done。
+`source` 为文件路径时用 `read` 读取其内容作为素材。按 `prompt` 要求生成内容，输出语言使用 `language`（缺省按参数表默认值）。
 
 ### Item 3：输出
 
-将第 3 项标记 in_progress：
-
-- 提供 `output` 参数：用 `write` 工具将生成内容写入 `output` 指定文件（**禁止创建其他文件**），stdout 输出该文件路径。
-- 未提供 `output` 参数：将生成内容直接输出到 stdout，**不写任何文件**。
-
-若结果为空或生成失败，将错误信息输出到 stderr 并结束，**不写任何文件**。
+- 提供 `output` → 用 `write` 将生成内容写入该文件（**禁止创建其他文件**），stdout 输出文件路径
+- 未提供 `output` → 将生成内容直接输出到 stdout，**不写任何文件**
 
-**验证 DoD**：按输出语义交付（文件路径或 stdout 数组），或结果为空/失败时 stderr 已报错。通过后标记 Done。
+结果为空或生成失败 → stderr 报错并结束，**不写任何文件**。
 
 ## Sprint Review
 
-所有 Backlog Items 完成后：
+本 skill 每次调用 = 无状态独立 Sprint，无跨轮次状态，故不进行 Retrospective。所有 Backlog Items 完成后：
 
 - **对照 Sprint Goal 验证**：生成内容是否符合 `{{prompt}}` 要求、语言 `{{language}}`？输出语义是否正确（写文件输出路径 / stdout 输出内容）？
 - **展示 Increment**：输出文件路径或 stdout 的生成内容。
-- **简要回顾（Retrospective）**：沉淀 1 条改进项供下一轮采纳。
 
 ## 约束
 
 - 只处理已声明字段（prompt/source/language/output），忽略所有其他传入参数（如 `url`），**禁止**以任何形式使用它们。
 - **禁止使用 WebFetch 或任何网络请求、禁止访问外部网络**；`source` 仅为素材透传，绝不自行获取内容。
-- 写文件一律用 `write` 工具；读文件用 `read` 工具；需要中间数据时写入临时文件，以 stdin 重定向传给 node。
-- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成。
-- 中间产物用临时文件，完成后清理，禁止写入 output 以外的任何持久文件。
-
-## references/ 目录结构
-
-```
-references/
-└── input.schema.json5              # 入参字段清单（纯文档）
-```
+- 写文件一律用 `write` 工具；读文件用 `read` 工具。