@wwkit/harness 1.0.28 → 1.0.30

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/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` 工具。

package/skills/revise/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: revise
 description: |
-  自包含内容创作 skill：每次调用 = 一个固定 Sprint——Sprint Planning（解析入参、定义 Sprint Goal、todowrite 落固定 Sprint Backlog）→ Sprint Execution（逐项执行并验证 DoD）→ Sprint Review（对照 Sprint Goal 校验交付 + 简要回顾）。
-  format=question/status/gallery/article。count 控制条目数（默认1），language 控制输出语言（默认中文）。
-  调用方直接传原始任务消息，skill 自解析自包含。内部用 todowrite 管理固定 6 项 Sprint Backlog（每项带 DoD）。禁止 WebFetch/网络请求。
-  适用：内容创作（question/status/gallery/article 等）。
+  自包含内容创作 skill（固定 Sprint 范式）：每次调用 = 一个固定 Sprint（Planning→Execution→Review），todowrite 落 3 项带 DoD 的 Sprint Backlog 并逐项验证，产出通过 schema 校验的 JSON 数组。
+  format=question/status/gallery/article（支持中文别名指定），count 控制条目数（默认1），language 控制输出语言（默认中文）。调用方直接传原始任务消息即可，无需预处理；禁止 WebFetch/网络请求。
 license: MIT
 metadata:
   workflow: sequential
@@ -16,136 +14,95 @@ metadata:
 
 每次调用 = 一个固定 Sprint，三个事件：
 
-1. **Sprint Planning**：解析入参 → 定义 Sprint Goal → todowrite 落固定 6 项 Sprint Backlog（每项带 DoD）
+1. **Sprint Planning**：解析入参 → 定义 Sprint Goal → todowrite 落固定 3 项 Sprint Backlog（每项带 DoD）
 2. **Sprint Execution**：逐项执行，每项 = 执行 → 验证 DoD → todowrite 勾单 Done
-3. **Sprint Review**：对照 Sprint Goal 验证 Increment（JSON 数组）及输出语义，沉淀 1 条回顾
+3. **Sprint Review**：对照 Sprint Goal 验证 Increment（JSON 数组）及输出语义
 
 **Sprint Goal** = `产出 {{count}} 条符合 {{format}} 格式、{{language}} 语言的 JSON 数组，并通过 schema 校验`。
 
 ## 输入参数
 
-入参为调用方传入的**原始任务消息**，可为 JSON 对象、key=value 或自然语言等任意形态，agent 依据字段语义自主提取（详见 Item 1）。字段清单（字段/类型/必填/默认值）以 `references/input.schema.json5` 为准：
+入参为调用方传入的**原始任务消息**，可为 JSON 对象、key=value 或自然语言等任意形态，agent 依据字段语义自主提取。字段清单（字段/类型/必填/默认值）：
 
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `format` | string | ✅ | 创作格式，标准值 `question`/`status`/`gallery`/`article`，可由别名表翻译 |
+| `format` | string | ✅ | 创作格式，标准值 `question`/`status`/`gallery`/`article`，可用自然语言别名指定（见别名对照） |
 | `source` | string | ✅ | 原始素材：文本 / JSON 字符串 / 文件路径 |
-| `count` | integer | ❌ | 生成 item 数量，默认 1 |
-| `language` | string | ❌ | 输出内容语言，默认 中文 |
+| `count` | integer | ❌ | 生成 item 数量，默认 1（非整数或 <1 按 1） |
+| `language` | string | ❌ | 输出语言，默认 中文（空白按中文） |
+| `style` | string | ❌ | 创作风格描述（自由文本），缺省用 format 默认风格（`<format>.md` 的 Style 模块） |
 | `output` | string | ❌ | 输出文件路径（提供则写文件，否则 stdout） |
 
-本技能仅使用上表五个字段，忽略所有其他字段（如 `url`），不得读取、写入或据此推断任何行为。
+本技能仅使用上表六个字段，忽略所有其他字段（如 `url`）。
 
-## 固定 Sprint Backlog（todowrite 落单，覆盖历史 todos）
-
-1. 解析入参（从任意形态任务消息自主提取 format/source/count/language/output） | DoD: 得到五个字段值（或按短路规则输出 `[]`/错误并结束）
-2. 加载 references（format prompt 文件 + schema 文件） | DoD: `references/{{format}}.md` 与 `references/{{format}}.schema.json5` 已读取，schema 绝对路径已记录（或 format 无效时输出 `[]`）
-3. 内容生成（LLM 创作） | DoD: 产出含 `{{count}}` 个 item、`{{language}}` 语言的 JSON 数组
-4. Schema 校验 | DoD: `node validate-schema.js` 执行完成，返回通过/失败结果
-5. 校验失败修复重试（≤3 次） | DoD: 重试后校验通过，或重试 3 次耗尽后 stderr 输出错误
-6. 输出（写 output 文件或 stdout） | DoD: 按输出语义交付 JSON 数组（文件路径或 stdout），校验未通过时 stderr 报错
-
-## Sprint Execution
-
-按固定 6 项逐项执行，每项周期 = 进度检查（刚完成什么/本项做什么/有无阻塞）→ 执行 → 验证 DoD → 勾单 Done。
-
-### Item 1：解析入参
-
-将第 1 项标记 in_progress，从原始任务消息中**自主提取**五个字段。入参可为 JSON 对象、key=value 或自然语言等任意形态，依据字段语义理解提取即可，无需固定解析规则。提取原则：
-
-- **格式翻译**：若消息中以自然语言指定创作格式（如"问题/文章/图集/动态"），用 `read` 读取 `references/format-aliases.json5`，将命中的 `terms` 翻译为该 format 标准值；未命中则 `format` 取消息中明确给出的值。
-- **count/language**：缺省时留空，由 Item 3 统一按默认值处理。
-
-解析后得到 `format`、`source`、`count`、`language`、`output` 五个字段（字段说明见上文输入参数表）。
-
-**短路规则（按顺序执行，命中即结束）：**
+**format 别名对照**：
 
-1. **空 source 短路**：若 `source` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
-2. **format 缺失校验**：若 `format` 未提供或经别名表翻译后仍为空：将错误信息输出到 stderr 并结束，**禁止**继续执行。
+| format 标准值 | 别名 terms |
+|---|---|
+| `question` | 问题 / 提问 / 互动话题 / 话题 / question |
+| `status` | 动态 / 微博 / 朋友圈 / 状态 / 一句话 / status |
+| `gallery` | 图集 / 相册 / 多图 / 图片合集 / gallery |
+| `article` | 文章 / 图文 / 长文 / 推文 / article |
 
-**验证 DoD**：五个字段值已得到（或按短路规则结束）。通过后标记 Done。
-
-### Item 2：加载 Prompt 和 Schema
+## 固定 Sprint Backlog（todowrite 落单，覆盖历史 todos）
 
-将第 2 项标记 in_progress，从技能目录的 `references/` 加载对应格式的文件：
+1. 解析入参 + 准备素材 + 加载 references | DoD: 六字段已提取、素材已就绪（文件已读）、prompt 与 schema 已读且 schema 绝对路径已记录（或 stderr 报错结束）
+2. 内容生成 + Schema 校验（失败修复重试 ≤3 次） | DoD: 产出含 `{{count}}` 个 item、`{{language}}` 语言的裸 JSON 数组且 `node validate-schema.js` 校验通过（或重试耗尽 stderr 报错）
+3. 输出 | DoD: 按输出语义交付 JSON 数组（文件路径或 stdout）
 
-- Prompt 文件：`references/{{ format }}.md` — LLM 创作指令
-- Schema 文件：`references/{{ format }}.schema.json5` — 输出校验规则（JSON Schema）
+## Sprint Execution
 
-用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（Item 4 校验时需要）。若对应 references 文件不存在：直接输出 `[]` 并结束（`format` 缺失已在 Item 1 处理）。
+按固定 3 项逐项执行（勾单机制见执行范式）。
 
-**验证 DoD**：两个文件已读取、schema 绝对路径已记录（或 references 文件不存在已短路）。通过后标记 Done。
+### Item 1：解析入参 + 准备素材 + 加载 references
 
-### Item 3：内容生成
+从原始任务消息中自主提取 `format`/`source`/`count`/`language`/`style`/`output` 六个字段；自然语言格式按「format 别名对照」翻译。`source` 为文件路径时用 `read` 读取其内容作为素材。
 
-将第 3 项标记 in_progress，将 `source` 解析为素材。判断顺序：
+**短路规则（命中即结束，禁止继续执行）：**
 
-1. **文件路径**：`source` 为现有文件路径 → 用 `read` 读取文件内容作为素材；
-2. **JSON 字符串**：素材以 `{` 或 `[` 开头且可整体解析为 JSON → 解析为结构化对象作为素材；
-3. **否则**：素材作为纯文本字符串。
+1. `source` 为空、null 或仅含空白 → 将错误信息输出到 stderr 并结束
+2. `format` 未提供或经别名对照翻译后仍为空 → 将错误信息输出到 stderr 并结束
 
-**禁止用 bash 解析 JSON**，JSON 判断与解析直接依据文本内容理解完成。素材确定后，将素材结合 Prompt 文件内容调用 LLM 生成符合格式的结果。**必须生成 `{{ count }}` 个 item，整体输出为 JSON 数组（即使 count=1）。** 内容语言使用 `{{ language }}`（默认中文）。
+未短路时**并行读取** `references/{{format}}.md`（LLM 创作指令）与 `references/{{format}}.schema.json5`（输出校验规则），记录 schema 绝对路径（Item 2 校验用）；references 文件不存在 → 将错误信息输出到 stderr 并结束。
 
-`count` 缺省、非整数或小于 1 时按 1 处理；`language` 缺省或仅含空白时按 `中文` 处理。
+### Item 2：内容生成 + Schema 校验
 
-生成时向 LLM 传入：
-- 原始素材（完整 source，已解析为可读格式）
-- Prompt 文件内容（创作指令）
-- `{{ count }}`（生成 item 数量）
-- `{{ language }}`（输出语言）
-- 输出格式说明和示例
+将素材结合 Prompt 文件内容调用 LLM 生成：**必须生成 `{{count}}` 个 item，整体输出为 JSON 数组（即使 count=1）**，内容语言使用 `{{language}}`（缺省按参数表默认值）。生成时向 LLM 传入：原始素材、Prompt 文件内容、`{{count}}`、`{{language}}`、输出格式说明和示例。
 
-**验证 DoD**：已产出含 `{{count}}` 个 item、`{{language}}` 语言的 JSON 数组。通过后标记 Done。
+**style 覆盖**：若提供 `style`，以 `{{style}}` 取代 `<format>.md` 的 **Style 模块**（默认创作风格）；**Format 模块（输出契约）不可变**——结构、schema 字段、长度、图片数量上限、真实性约束均以 Format 模块与 schema 为准。
 
-### Item 4：Schema 校验
+**裸 JSON 硬约束**：输出必须为裸 JSON 数组——不使用 markdown 代码围栏（```json）、不输出任何解释、思考过程或额外文本、无尾注，直接以 `[` 开始、`]` 结束。
 
-将第 4 项标记 in_progress，用 `write` 工具将待校验的 JSON 数组写入临时文件，再用 `write` 工具将 `{"data": <JSON 数组>, "schema_path": "<schema 绝对路径>"}` 写入 JSON 输入文件，stdin 重定向交给 Node.js 校验：
+用 `write` 将 `{"data": <JSON 数组>, "schema_path": "<schema 绝对路径>"}` 写入**单个**临时 JSON 输入文件（数组内嵌于 `data`，无需单独写待校验数组文件），stdin 重定向交给 Node.js 校验：
 
 ```bash
 node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 ```
 
-- 若校验通过：**验证 DoD**（校验执行完成且返回通过），标记 Done，跳过 Item 5，进入 Item 6
-- 若校验失败：**验证 DoD**（校验执行完成且返回失败），标记 Done，进入 Item 5 进行修复重试（最多 3 次）
-
-### Item 5：校验失败时修复重试
-
-将第 5 项标记 in_progress，将错误信息反馈给 LLM，要求其根据原始素材重新生成。
+- 通过 → 进入 Item 3
+- 失败 → 将 Schema 校验错误反馈给 LLM（原始素材 + Prompt 文件内容 + 上一轮不合格内容 + 错误详情）重新生成后再次校验，**最多重试 3 次**；耗尽 → 将最后一次错误及「重试 3 次后 schema 校验仍然失败」输出到 stderr 并结束
 
-传入内容：
-- 原始素材（完整 source）
-- Prompt 文件内容
-- 上一轮生成的不合格内容
-- Schema 校验错误详情
+### Item 3：输出
 
-重新生成后，再次执行 Item 4 校验。**最多重试 3 次**。
+本项执行时校验必已通过：
 
-**验证 DoD**：重试后校验通过 → 标记 Done，进入 Item 6；重试 3 次耗尽 → stderr 输出错误并结束（**不进入 Item 6**）。
-
-### Item 6：输出
-
-将第 6 项标记 in_progress。进入本项时校验必已通过（重试耗尽场景已在 Item 5 结束）：
-
-- 提供 `output` 参数：用 `write` 工具将最终 JSON 数组写入 `output` 指定文件（**禁止创建其他文件**），stdout 输出该文件路径。
-- 未提供 `output` 参数：将最终 JSON 数组直接输出到 stdout，**不写任何文件**。
-
-**验证 DoD**：按输出语义交付（文件路径或 stdout 数组）。通过后标记 Done。
+- 提供 `output` → 用 `write` 将最终 JSON 数组写入该文件（**禁止创建其他文件**），stdout 输出文件路径
+- 未提供 `output` → 将最终 JSON 数组直接输出到 stdout，**不写任何文件**
 
 ## Sprint Review
 
-所有 Backlog Items 完成后：
+本 skill 每次调用 = 无状态独立 Sprint，无跨轮次状态，故不进行 Retrospective。所有 Backlog Items 完成后：
 
 - **对照 Sprint Goal 验证**：产出的是否为 `{{count}}` 条符合 `{{format}}` 格式、`{{language}}` 语言的 JSON 数组且通过 schema 校验？输出语义是否正确（写文件输出路径 / stdout 输出数组）？
 - **展示 Increment**：输出文件路径或 stdout 的 JSON 数组。
-- **简要回顾（Retrospective）**：沉淀 1 条改进项供下一轮采纳。
 
 ## 约束
 
 - 只处理已声明字段（source/format/count/language/output），忽略所有其他传入参数（如 `url`），**禁止**以任何形式使用它们。
-- **禁止使用 WebFetch 或任何网络请求、禁止访问外部网络**；`source` 为空时必须输出 `[]`，绝不自行获取内容。
-- 写文件一律用 `write` 工具；读文件用 `read` 工具；需要中间数据时写入临时文件，以 stdin 重定向传给 node。
-- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成。
-- 内部重试步骤的中间产物用临时文件，完成后清理，禁止写入 output 以外的任何持久文件。
+- **禁止使用 WebFetch 或任何网络请求、禁止访问外部网络**；`source`/`format` 不合法时向 stderr 输出错误信息，绝不自行获取内容。
+- 写文件一律用 `write` 工具；读文件用 `read` 工具；中间数据写入临时文件，以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时用 `node -e` 的 fs 模块完成。
+- 中间产物完成后清理，禁止写入 output 以外的任何持久文件。
 
 ## references/ 目录结构
 
@@ -153,14 +110,13 @@ node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 
 ```
 references/
-├── input.schema.json5              # 入参字段清单（纯文档）
-├── question.md              # 社交媒体问题 prompt
-├── question.schema.json5    # 输出 JSON Schema
-├── status.md                # 社交媒体动态 prompt
+├── question.md                     # 社交媒体问题 prompt
+├── question.schema.json5           # 输出 JSON Schema
+├── status.md                       # 社交媒体动态 prompt
 ├── status.schema.json5
-├── gallery.md               # 社交媒体图集 prompt
+├── gallery.md                      # 社交媒体图集 prompt
 ├── gallery.schema.json5
-├── article.md               # 社交媒体图文文章 prompt
+├── article.md                      # 社交媒体图文文章 prompt
 ├── article.schema.json5
-└── ...
-```
+└── validate-schema.js              # schema 校验脚本（stdin 输入）
+```