@wwkit/harness 1.0.26 → 1.0.28

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

package/skills/revise/SKILL.md

@@ -1,101 +1,92 @@
 ---
 name: revise
 description: |
-  自包含内容创作 skill：解析入参（JSON/key=value/prose）→ 按 format 加载 prompt 生成 → schema 校验 → 写 output 文件或 stdout。
+  自包含内容创作 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 步。禁止 WebFetch/网络请求。
+  调用方直接传原始任务消息，skill 自解析自包含。内部用 todowrite 管理固定 6 项 Sprint Backlog（每项带 DoD）。禁止 WebFetch/网络请求。
   适用：内容创作（question/status/gallery/article 等）。
 license: MIT
 metadata:
   workflow: sequential
 ---
 
-# revise 技能
+# revise 技能（固定 Sprint 冲刺）
 
-## 核心约束（最高优先级）
+## 执行范式
 
-- **MUST**：收到任务消息后，先 todowrite 落单 6 步，再逐步执行。
-- **MUST**：每步完成立即 todowrite 勾单。
-- **禁止**：使用 WebFetch 或任何网络请求获取内容。
-- **禁止**：写入 output 以外的任何文件；中间产物用临时文件，完成后清理。
-- **禁止**：以任何形式使用未声明字段（url 等不属于 revise 的字段）。
+每次调用 = 一个固定 Sprint，三个事件：
 
-## 第一步硬指令（自检）
+1. **Sprint Planning**：解析入参 → 定义 Sprint Goal → todowrite 落固定 6 项 Sprint Backlog（每项带 DoD）
+2. **Sprint Execution**：逐项执行，每项 = 执行 → 验证 DoD → todowrite 勾单 Done
+3. **Sprint Review**：对照 Sprint Goal 验证 Increment（JSON 数组）及输出语义，沉淀 1 条回顾
 
-解析入参前，强制自检：
-> 我是否已用 todowrite 落单 6 步？
-> - 未落单 → 立即 todowrite 创建清单。
-> - 已落单 → 继续。
+**Sprint Goal** = `产出 {{count}} 条符合 {{format}} 格式、{{language}} 语言的 JSON 数组，并通过 schema 校验`。
 
 ## 输入参数
 
-入参为调用方传入的**原始任务消息**，可能是以下任一形态：
-- **JSON 对象**：如 `{format, source, count, language, output}`，直接取字段值；
-- **key=value**：如 `format=question, source=xxx`，按 `,` 和 `=` 拆分为字段；
-- **纯文本 prose**：不做格式推断（同一 source 可有多种 format）。仅当文本命中 `references/format-aliases.json5` 中某 format 的 `terms`（如"问题/文章/图集/动态"）时才翻译为该 format 标准值，`source` 取文本本身。
+入参为调用方传入的**原始任务消息**，可为 JSON 对象、key=value 或自然语言等任意形态，agent 依据字段语义自主提取（详见 Item 1）。字段清单（字段/类型/必填/默认值）以 `references/input.schema.json5` 为准：
 
-字段清单（字段/类型/必填）见 `references/input.schema.json5`。本技能仅使用 `source`、`format`、`count`、`language`、`output` 五个字段，忽略所有其他字段（如 `url`），不得读取、写入或据此推断任何行为。
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `format` | string | ✅ | 创作格式，标准值 `question`/`status`/`gallery`/`article`，可由别名表翻译 |
+| `source` | string | ✅ | 原始素材：文本 / JSON 字符串 / 文件路径 |
+| `count` | integer | ❌ | 生成 item 数量，默认 1 |
+| `language` | string | ❌ | 输出内容语言，默认 中文 |
+| `output` | string | ❌ | 输出文件路径（提供则写文件，否则 stdout） |
 
-## 输出
+本技能仅使用上表五个字段，忽略所有其他字段（如 `url`），不得读取、写入或据此推断任何行为。
 
-- 提供 `output` 参数：将 JSON 数组用 `write` 工具写入该文件，stdout 输出文件路径。
-- 未提供 `output` 参数：将 JSON 数组直接输出到 stdout，**不写任何文件**。
-- 校验失败未能产出数组：不写文件、不输出数组，将错误信息输出到 stderr 并结束。
+## 固定 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 报错
 
-### 阶段 0：todowrite 落单
+## Sprint Execution
 
-收到任务消息后，**先**用 `todowrite` 创建 6 步清单（status=pending）：
+按固定 6 项逐项执行，每项周期 = 进度检查（刚完成什么/本项做什么/有无阻塞）→ 执行 → 验证 DoD → 勾单 Done。
 
-1. 解析入参（JSON/key=value/prose → format/source/count/language/output）
-2. 加载 references（format prompt 文件 + schema 文件）
-3. 内容生成（LLM 创作）
-4. Schema 校验
-5. 校验失败修复重试（≤3 次）
-6. 输出（写 output 文件或 stdout）
+### Item 1：解析入参
 
-每步完成立即 todowrite 勾单（status=completed）。
+将第 1 项标记 in_progress，从原始任务消息中**自主提取**五个字段。入参可为 JSON 对象、key=value 或自然语言等任意形态，依据字段语义理解提取即可，无需固定解析规则。提取原则：
 
-### 阶段 1：解析入参
+- **格式翻译**：若消息中以自然语言指定创作格式（如"问题/文章/图集/动态"），用 `read` 读取 `references/format-aliases.json5`，将命中的 `terms` 翻译为该 format 标准值；未命中则 `format` 取消息中明确给出的值。
+- **count/language**：缺省时留空，由 Item 3 统一按默认值处理。
 
-将第 1 步标记为 in_progress，解析原始任务消息：
+解析后得到 `format`、`source`、`count`、`language`、`output` 五个字段（字段说明见上文输入参数表）。
 
-- **JSON 对象**：直接取 `format`/`source`/`count`/`language`/`output` 字段值。
-- **key=value**：按 `,` 分割、按 `=` 拆分为键值对，取上述五字段。
-- **纯文本 prose**：用 `read` 读取 `references/format-aliases.json5`，仅当文本命中某 format 的 `terms` 时翻译为该 format 标准值，`source` 取文本本身；未命中则 `format` 视为未提供。
+**短路规则（按顺序执行，命中即结束）：**
 
-解析后得到：
-- `format`（必填，经别名表翻译为标准值）
-- `source`（必填，素材文本或文件路径，原样透传由后续阶段解析）
-- `count`（可选，数值，缺省透传空由阶段 3 按默认 1 处理）
-- `language`（可选，缺省透传空由阶段 3 按默认 中文 处理）
-- `output`（可选，输出文件路径）
+1. **空 source 短路**：若 `source` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+2. **format 缺失校验**：若 `format` 未提供或经别名表翻译后仍为空：将错误信息输出到 stderr 并结束，**禁止**继续执行。
 
-**必填校验**：若无法解析出 `format` 或 `source`，将错误信息输出到 stderr 并结束，**禁止**继续执行。
+**验证 DoD**：五个字段值已得到（或按短路规则结束）。通过后标记 Done。
 
-**空 source 短路**：若 `source` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+### Item 2：加载 Prompt 和 Schema
 
-完成后 todowrite 勾单第 1 步。
-
-### 阶段 2：加载 Prompt 和 Schema
-
-从技能目录的 `references/` 加载对应格式的文件：
+将第 2 项标记 in_progress，从技能目录的 `references/` 加载对应格式的文件：
 
 - Prompt 文件：`references/{{ format }}.md` — LLM 创作指令
 - Schema 文件：`references/{{ format }}.schema.json5` — 输出校验规则（JSON Schema）
 
-用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（阶段 4 校验时需要）。若 `format` 为空或对应 references 文件不存在：直接输出 `[]` 并结束。
+用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（Item 4 校验时需要）。若对应 references 文件不存在：直接输出 `[]` 并结束（`format` 缺失已在 Item 1 处理）。
 
-完成后 todowrite 勾单第 2 步。
+**验证 DoD**：两个文件已读取、schema 绝对路径已记录（或 references 文件不存在已短路）。通过后标记 Done。
 
-### 阶段 3：内容生成
+### Item 3：内容生成
 
-先判断 `source` 是否为现有文件路径：若是则读取文件内容作为素材；否则直接以值作为素材。再判断素材是否为 JSON 字符串：若是则解析为结构化对象作为素材；否则直接作为文本素材。**禁止用 bash 解析 JSON**，直接依据内容理解处理。
+将第 3 项标记 in_progress，将 `source` 解析为素材。判断顺序：
 
-将素材结合 Prompt 文件内容调用 LLM 生成符合格式的结果。**必须生成 `{{ count }}` 个 item，整体输出为 JSON 数组（即使 count=1）。** 内容语言使用 `{{ language }}`（默认中文）。
+1. **文件路径**：`source` 为现有文件路径 → 用 `read` 读取文件内容作为素材；
+2. **JSON 字符串**：素材以 `{` 或 `[` 开头且可整体解析为 JSON → 解析为结构化对象作为素材；
+3. **否则**：素材作为纯文本字符串。
 
-`count` 解析为整数，默认 1；为空、非整数或小于 1 时按 1 处理。`language` 为空或仅含空白时按 `中文` 处理。
+**禁止用 bash 解析 JSON**，JSON 判断与解析直接依据文本内容理解完成。素材确定后，将素材结合 Prompt 文件内容调用 LLM 生成符合格式的结果。**必须生成 `{{ count }}` 个 item，整体输出为 JSON 数组（即使 count=1）。** 内容语言使用 `{{ language }}`（默认中文）。
+
+`count` 缺省、非整数或小于 1 时按 1 处理；`language` 缺省或仅含空白时按 `中文` 处理。
 
 生成时向 LLM 传入：
 - 原始素材（完整 source，已解析为可读格式）
@@ -104,22 +95,22 @@ metadata:
 - `{{ language }}`（输出语言）
 - 输出格式说明和示例
 
-完成后 todowrite 勾单第 3 步。
+**验证 DoD**：已产出含 `{{count}}` 个 item、`{{language}}` 语言的 JSON 数组。通过后标记 Done。
 
-### 阶段 4：Schema 校验
+### Item 4：Schema 校验
 
-用 `write` 工具将待校验的 JSON 数组写入临时文件，再用 `write` 工具将 `{"data": <JSON 数组>, "schema_path": "<schema 绝对路径>"}` 写入 JSON 输入文件，stdin 重定向交给 Node.js 校验：
+将第 4 项标记 in_progress，用 `write` 工具将待校验的 JSON 数组写入临时文件，再用 `write` 工具将 `{"data": <JSON 数组>, "schema_path": "<schema 绝对路径>"}` 写入 JSON 输入文件，stdin 重定向交给 Node.js 校验：
 
 ```bash
 node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 ```
 
-- 若校验通过，todowrite 勾单第 4 步，跳过阶段 5，进入阶段 6
-- 若校验失败，todowrite 勾单第 4 步，进入阶段 5 进行修复重试（最多 3 次）
+- 若校验通过：**验证 DoD**（校验执行完成且返回通过），标记 Done，跳过 Item 5，进入 Item 6
+- 若校验失败：**验证 DoD**（校验执行完成且返回失败），标记 Done，进入 Item 5 进行修复重试（最多 3 次）
 
-### 阶段 5：校验失败时修复重试
+### Item 5：校验失败时修复重试
 
-当 Schema 校验失败时，将错误信息反馈给 LLM，要求其根据原始素材重新生成。
+将第 5 项标记 in_progress，将错误信息反馈给 LLM，要求其根据原始素材重新生成。
 
 传入内容：
 - 原始素材（完整 source）
@@ -127,33 +118,34 @@ node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 - 上一轮生成的不合格内容
 - Schema 校验错误详情
 
-重新生成后，再次执行阶段 4 校验。**最多重试 3 次**，超过则将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
+重新生成后，再次执行 Item 4 校验。**最多重试 3 次**。
 
-重试成功后 todowrite 勾单第 5 步，进入阶段 6。
+**验证 DoD**：重试后校验通过 → 标记 Done，进入 Item 6；重试 3 次耗尽 → stderr 输出错误并结束（**不进入 Item 6**）。
 
-### 阶段 6：输出
+### Item 6：输出
 
-**若校验未通过（重试耗尽）：** 将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束，**不写任何文件**。
+将第 6 项标记 in_progress。进入本项时校验必已通过（重试耗尽场景已在 Item 5 结束）：
 
-**若校验通过：**
 - 提供 `output` 参数：用 `write` 工具将最终 JSON 数组写入 `output` 指定文件（**禁止创建其他文件**），stdout 输出该文件路径。
 - 未提供 `output` 参数：将最终 JSON 数组直接输出到 stdout，**不写任何文件**。
 
-完成后 todowrite 勾单第 6 步。
+**验证 DoD**：按输出语义交付（文件路径或 stdout 数组）。通过后标记 Done。
 
-## 工具使用约束
+## Sprint Review
 
-- 写文件一律用 `write` 工具；读文件用 `read` 工具。
-- 需要中间数据时，用 `write` 工具写入临时文件，再以 stdin 重定向传给 node。
-- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成。
-- 除技能校验所需 node 外，禁止执行其他 shell。
+所有 Backlog Items 完成后：
+
+- **对照 Sprint Goal 验证**：产出的是否为 `{{count}}` 条符合 `{{format}}` 格式、`{{language}}` 语言的 JSON 数组且通过 schema 校验？输出语义是否正确（写文件输出路径 / stdout 输出数组）？
+- **展示 Increment**：输出文件路径或 stdout 的 JSON 数组。
+- **简要回顾（Retrospective）**：沉淀 1 条改进项供下一轮采纳。
 
 ## 约束
 
 - 只处理已声明字段（source/format/count/language/output），忽略所有其他传入参数（如 `url`），**禁止**以任何形式使用它们。
-- **禁止使用 WebFetch 或任何网络请求获取内容**；`source` 为空时必须输出 `[]`，绝不自行获取内容。
+- **禁止使用 WebFetch 或任何网络请求、禁止访问外部网络**；`source` 为空时必须输出 `[]`，绝不自行获取内容。
+- 写文件一律用 `write` 工具；读文件用 `read` 工具；需要中间数据时写入临时文件，以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成。
 - 内部重试步骤的中间产物用临时文件，完成后清理，禁止写入 output 以外的任何持久文件。
-- 禁止访问外部网络。
 
 ## references/ 目录结构
 
@@ -171,4 +163,4 @@ references/
 ├── article.md               # 社交媒体图文文章 prompt
 ├── article.schema.json5
 └── ...
-```
+```

package/skills/revise/references/article.md

@@ -1,29 +1,25 @@
-# 社交媒体图文文章创作 Prompt
+# 社交媒体图文文章（article）创作 Sprint
 
-## 任务
+## Sprint Goal
 
-根据原始素材提取并创作一篇**适合社交媒体传播的图文文章（article）**。
+产出 `{{count}}` 篇适合社交媒体传播的图文文章（抓人标题 + 图文混排正文），整体为 JSON 数组。
 
-## 输入
+## 创作原则
 
-- `source`：原始素材（文本或 JSON 字符串）
-- `count`：生成的文章数量（默认 1，输出为数组）
-- 创作格式要求见下方
+基于原始素材创作，聚焦 format 特有要点：
 
-## 输出格式
-
-输出为 JSON **数组**，每个元素的结构必须严格符合 schema `references/article.schema.json5`（阶段 2 已读取）——字段、类型、必填项、数组数量、title 长度、图片块数量均以 schema 为准。
+1. **标题要抓人**：有吸引力、有冲突点，读者靠标题决定是否点开
+2. **正文适合快速阅读**：图文混排，段落短、节奏快，文本块与图片块交替出现，建议文本为主、图片辅助，整体 1-20 行
+3. **图片按需提取**：从素材中提取图片地址作为 `{"type": "image"}` 块，最多 5 个图片块；素材无图片时全部用 `{"type": "text"}` 块
+4. **基于素材**：从素材中提炼核心信息，重组为流畅文章，不能凭空编造
 
-> 字数计算采用 **cn_length** 规则：中文字符算 1，非中文字符（英文/数字/符号）算 0.5，结果向上取整。
+## 输出契约
 
-## 创作要求
+每个 item 结构严格符合 schema `references/article.schema.json5`：`title`（10-30 cn_length）、`blocks`（array，1-20 个，每个含 `type`（text/image）+ `content`）。**整体输出为 JSON 数组，含 `{{count}}` 个 item。**
 
-1. **标题要抓人**：有吸引力、有冲突点，读者靠标题决定是否点开
-2. **正文适合快速阅读**：图文混排，段落短、节奏快，文本块与图片块交替出现，建议文本为主、图片辅助，整体 1-20 行
-3. **图片按需提取**：从原始素材中提取图片地址作为 `{"type": "image"}` 块，**最多 5 个图片块**；素材无图片时全部用 `{"type": "text"}` 块
-4. **基于素材创作**：从素材中提炼核心信息，重组为流畅文章，不能凭空编造
+> 字数计算采用 **cn_length** 规则：中文字符算 1，非中文字符（英文/数字/符号）算 0.5，结果向上取整。
 
-## 输出示例
+示例：
 
 ```json
 [
@@ -38,7 +34,7 @@
 ]
 ```
 
-## 注意事项
+## 铁律
 
 - 仅输出 JSON 数组，不要包含任何解释、思考过程或额外文本
-- 输出始终为数组，包含 count 个 item（默认 1），禁止输出单个对象
+- 输出始终为数组，包含 `{{count}}` 个 item（默认 1），禁止输出单个对象

package/skills/revise/references/gallery.md

@@ -1,29 +1,25 @@
-# 社交媒体图集创作 Prompt
+# 社交媒体图集（gallery）创作 Sprint
 
-## 任务
+## Sprint Goal
 
-根据原始素材提取并创作一个**适合社交媒体传播的图集（gallery）**。
+产出 `{{count}}` 个适合社交媒体传播的图集内容（吸睛标题 + 图片列表），整体为 JSON 数组。
 
-## 输入
+## 创作原则
 
-- `source`：原始素材（文本或 JSON 字符串）
-- `count`：生成的图集数量（默认 1，输出为数组）
-- 创作格式要求见下方
+基于原始素材创作，聚焦 format 特有要点：
 
-## 输出格式
-
-输出为 JSON **数组**，每个元素的结构必须严格符合 schema `references/gallery.schema.json5`（阶段 2 已读取）——字段、类型、必填项、数组数量、title 长度均以 schema 为准。
+1. **标题要吸引**：点明图集主题，有看点、让人想点开
+2. **每张图配说明**：`images[].title` 简要说明图片内容，有助于读者理解
+3. **图片从素材提取**：从原始素材中提取图片地址，素材中图片不足时可适当精选
+4. **基于素材**：从素材中提炼主题，不能凭空编造
 
-> 字数计算采用 **cn_length** 规则：中文字符算 1，非中文字符（英文/数字/符号）算 0.5，结果向上取整。
+## 输出契约
 
-## 创作要求
+每个 item 结构严格符合 schema `references/gallery.schema.json5`：`title`（10-30 cn_length）、`images`（array，1-50 个，每个含 `url` + `title`（10-30 cn_length））。**整体输出为 JSON 数组，含 `{{count}}` 个 item。**
 
-1. **标题要吸引**：点明图集主题，有看点、让人想点开
-2. **每张图配说明**：title 简要说明图片内容，有助于读者理解
-3. **图片从素材提取**：从原始素材中提取图片地址，素材中图片不足时可适当精选
-4. **基于素材创作**：从素材中提炼主题，不能凭空编造
+> 字数计算采用 **cn_length** 规则：中文字符算 1，非中文字符（英文/数字/符号）算 0.5，结果向上取整。
 
-## 输出示例
+示例：
 
 ```json
 [
@@ -31,13 +27,13 @@
     "title": "三星电子二季度财报亮点图集",
     "images": [
       {"url": "https://example.com/pic1.jpg", "title": "三星第二季度初步财报发布"},
-      {"url": "https://example.com/pic2.jpg", "title": "全球存储芯片市场供需"}
+      {"url": "https://example.com/pic2.jpg", "title": "全球存储芯片供需格局"}
     ]
   }
 ]
 ```
 
-## 注意事项
+## 铁律
 
 - 仅输出 JSON 数组，不要包含任何解释、思考过程或额外文本
-- 输出始终为数组，包含 count 个 item（默认 1），禁止输出单个对象
+- 输出始终为数组，包含 `{{count}}` 个 item（默认 1），禁止输出单个对象