@wwkit/harness 1.0.8 → 1.0.10

package/skills/new-skill/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: new-skill
+description: |
+  交互式引导创建符合最佳实践的 OpenCode Skill 定义文件，基于 blame-skill 评分规则逐项收集信息并生成高质量 SKILL.md。
+  提供：交互式引导流程、工作流模式参考、SKILL.md 模板、自动评分验证。
+  适用：新建 Skill 定义、Skill 脚手架生成、从零创建规范技能。
+  不适用：修改已有 Skill（使用 better-skill）、审查 Skill 质量（使用 blame-skill）、非 SKILL.md 文件创建。
+---
+
+# Skill 创建向导
+
+## 工作流模式
+
+本 Skill 采用 **上下文感知** 工作流：
+
+1. **收集**：通过交互式问答逐项收集 Skill 定义所需信息
+2. **决策**：根据收集的信息选择工作流模式和步骤设计
+3. **生成**：基于模板和收集的信息生成 SKILL.md 及 references/ 文件
+4. **验证**：调用 blame-skill 评分，确保达到 B 级（75分）以上
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| name | 是 | 字符串 | Skill 名称，须符合 `^[a-z0-9]+(-[a-z0-9]+)*$` 格式 |
+| 其他信息 | 否 | 交互收集 | 通过阶段一的问答逐步收集，用户也可一次性提供 |
+
+## 输出
+
+- `packages/agent/src/skills/<name>/SKILL.md` — Skill 定义文件
+- `packages/agent/src/skills/<name>/references/` — 参考文档目录（如需要）
+- 创建报告（含 blame-skill 评分结果）
+
+---
+
+## 阶段一：收集
+
+**输入**：用户提供的 name 参数（或全部信息）
+
+**操作**：通过交互式问答，逐项收集 Skill 定义的 6 类信息。如果用户在调用时已提供完整信息，则跳过对应问答。
+
+### 1.1 基本信息（对应 Frontmatter 规范 15 分）
+
+向用户收集：
+
+| # | 问题 | 对应字段 | 约束 |
+|---|------|---------|------|
+| 1 | Skill 名称？ | name | 必须符合 `^[a-z0-9]+(-[a-z0-9]+)*$`，与目录名一致 |
+| 2 | 一句话描述核心能力？ | description.具体能力 | 如"根据X规则对Y执行Z操作" |
+| 3 | 适用场景？ | description.适用 | 如"首次执行、定期扫描、问题修复" |
+| 4 | 不适用场景？ | description.不适用 | 如"功能逻辑Bug修复、性能优化" |
+| 5 | 提供的资源？ | description.提供 | 如"规则库、修复策略、迭代验证" |
+
+**description 拼接规则**：将 2-5 的回答拼接为完整 description，控制在 50-300 字符：
+```
+{{核心能力}}。提供：{{提供资源}}。适用：{{适用场景}}。不适用：{{不适用场景}}。
+```
+
+### 1.2 工作流模式（对应工作流匹配 20 分）
+
+向用户收集：
+
+| # | 问题 | 说明 |
+|---|------|------|
+| 6 | Skill 的核心执行逻辑是哪种？ | 展示 5 种工作流模式供选择 |
+
+**展示选项**（读取 `references/workflow-patterns.md` 中的摘要）：
+
+| 模式 | 特征 | 典型场景 |
+|------|------|---------|
+| 顺序工作流 | 步骤按固定顺序执行，无循环 | 提交流程、部署、迁移 |
+| 迭代优化 | 执行→检查→改进→再检查，循环直到达标 | 质量修复、评分达标 |
+| 多 MCP 协调 | 协调多个外部技能/工具 | 跨系统操作、多技能编排 |
+| 上下文感知 | 根据运行时条件动态选择路径 | 条件分支、多模式切换 |
+| 领域智能 | 基于知识库推理匹配 | 规则匹配、智能推荐 |
+
+用户选择后，告知该模式的必要定义项（如迭代优化需定义目标条件和最大迭代次数）。
+
+### 1.3 步骤设计（对应工作流完整性 5 分 + 指令可执行 3 分）
+
+向用户收集：
+
+| # | 问题 | 说明 |
+|---|------|------|
+| 7 | 列出 Skill 的主要执行步骤 | 每个步骤用一句话描述做什么 |
+| 8 | 每个步骤的输入和输出分别是什么？ | 如"输入：规则列表；输出：违规项清单" |
+| 9 | 哪些步骤之间有循环？ | 仅迭代优化模式需要，定义循环条件和终止策略 |
+
+**步骤设计原则**：
+- 每个步骤必须有明确的输入和输出
+- 步骤粒度适中：太粗（"处理文件"）→ 拆分；太细（"读取第1行"）→ 合并
+- 迭代类步骤必须定义：目标条件、最大迭代次数、终止策略
+- 协调类步骤必须定义：调用的技能/工具、数据传递方式
+
+### 1.4 输入输出规范（对应输入输出规范 5 分）
+
+向用户收集：
+
+| # | 问题 | 说明 |
+|---|------|------|
+| 10 | Skill 接受哪些参数？ | 参数名、是否必填、类型、说明 |
+| 11 | Skill 产生哪些输出？ | 输出文件、报告格式、副作用 |
+
+### 1.5 失败处理（对应失败处理 4 分）
+
+向用户收集：
+
+| # | 问题 | 说明 |
+|---|------|------|
+| 12 | 可能遇到哪些失败场景？ | 文件不存在、语法错误、外部调用失败等 |
+| 13 | 每种失败如何处理？ | 回滚、重试、降级、跳过、人工介入 |
+
+### 1.6 边界与资源（对应边界说明 5 分 + 渐进式加载 5 分）
+
+向用户收集：
+
+| # | 问题 | 说明 |
+|---|------|------|
+| 14 | 一定要做的事情？ | 列出 3-8 条核心约束 |
+| 15 | 一定不要做的事情？ | 列出 3-8 条禁止项 |
+| 16 | 是否有大量参考数据？ | 如规则库、模板、配置等，有则放入 references/ |
+
+**输出**：完整的 Skill 定义信息清单
+
+---
+
+## 阶段二：生成
+
+**输入**：阶段一收集的完整信息清单
+
+**操作**：基于 `references/template.md` 模板和收集的信息，生成 SKILL.md 文件
+
+**生成规则**：
+
+1. **Frontmatter**：按模板格式拼接 name 和 description
+2. **工作流声明**：在正文开头（一级标题后）添加工作流模式声明，列出步骤编号和名称
+3. **输入输出表**：生成参数表和输出说明
+4. **步骤正文**：每个步骤包含 `输入`/`操作`/`输出`/`失败`（如适用）四要素
+5. **失败处理表**：汇总所有失败场景和处理方式
+6. **一定要做/一定不要做**：列表格式
+7. **references/ 目录**：如果用户提供了大量参考数据（规则库、模板等），创建对应文件
+8. **行数控制**：主文件（SKILL.md）控制在 200 行以内，超出部分拆分到 references/
+
+**输出**：
+- `packages/agent/src/skills/<name>/SKILL.md`
+- `packages/agent/src/skills/<name>/references/` 目录及文件（如需要）
+
+---
+
+## 阶段三：验证
+
+**输入**：生成的 SKILL.md 文件路径
+
+**操作**：调用 blame-skill 对生成的 Skill 进行审计评分
+
+**输出**：评分结果
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 得分 >= 75（B 级） | 输出创建报告，流程结束 |
+| 得分 < 75 且迭代次数 < 3 | 调用 better-skill 自动优化，回到验证 |
+| 得分 < 75 且迭代次数 >= 3 | 输出创建报告（含未达标说明和改进建议），流程结束 |
+
+---
+
+## 阶段四：输出
+
+**输入**：生成的文件 + 评分结果
+
+**操作**：生成创建报告
+
+**输出**：
+
+```markdown
+## Skill 创建报告：[name]
+
+### 生成文件
+- SKILL.md：[行数] 行
+- references/：[文件列表]
+
+### 评分结果
+- 得分：XX / 100（等级：X）
+- 各项得分：[来自 blame-skill 的分项得分]
+
+### 后续建议
+- [如有未达标项，列出改进建议]
+- 可使用 better-skill 进一步优化至 A 级
+```
+
+---
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| name 不符合命名规范 | 提示格式要求，要求用户重新输入 |
+| 同名 Skill 已存在 | 提示用户确认是否覆盖，确认后继续 |
+| 用户信息不完整 | 根据已有信息推断缺失项，用默认值填充并提示用户确认 |
+| blame-skill 评分失败 | 跳过验证阶段，直接输出文件和手动验证建议 |
+| better-skill 优化失败 | 输出当前文件和改进建议，由用户手动修改 |
+
+## 一定要做
+
+1. 按阶段一的问题顺序逐项收集信息，确保 6 类信息完整
+2. 用户已提供的信息不重复询问
+3. description 拼接后控制在 50-300 字符，包含具体能力、适用场景、不适用场景、提供资源
+4. 工作流模式必须从 5 种标准模式中选择
+5. 每个步骤必须定义输入和输出
+6. 生成的 SKILL.md 必须包含工作流声明、输入输出表、失败处理、一定要做/一定不要做
+7. 主文件控制在 200 行以内，超出部分拆分到 references/
+8. 生成后必须调用 blame-skill 验证评分
+
+## 一定不要做
+
+1. 不要跳过交互收集直接生成（除非用户提供了完整信息）
+2. 不要使用 5 种标准工作流以外的自定义模式
+3. 不要生成没有输入输出定义的步骤
+4. 不要在 description 中省略适用场景或不适用场景
+5. 不要生成超过 200 行且无 references/ 拆分的 SKILL.md
+6. 不要修改 blame-skill 的评分规则或 better-skill 的优化逻辑
+
+## 参考资源
+
+- `references/template.md`：SKILL.md 生成模板
+- `references/workflow-patterns.md`：5 种工作流模式详细参考

package/skills/new-skill/references/template.md

@@ -0,0 +1,53 @@
+# Skill 模板
+
+本文件为 new-skill 技能使用的 SKILL.md 生成模板。`{{占位符}}` 由收集的信息填充。
+
+---
+
+```yaml
+---
+name: {{name}}
+description: |
+  {{description_capability}}。提供：{{description_resources}}。适用：{{description_applicable}}。不适用：{{description_not_applicable}}。
+---
+```
+
+```markdown
+# {{title}}
+
+## 工作流模式
+
+本 Skill 采用 **{{workflow_type}}** 工作流：
+
+{{workflow_steps}}
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+{{input_rows}}
+
+## 输出
+
+{{output_desc}}
+
+---
+
+{{stages}}
+
+---
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+{{failure_rows}}
+
+## 一定要做
+
+{{must_do_items}}
+
+## 一定不要做
+
+{{must_not_do_items}}
+```

package/skills/new-skill/references/workflow-patterns.md

@@ -0,0 +1,104 @@
+# 工作流模式参考
+
+创建 Skill 时，必须从以下 5 种工作流模式中选择一种。选择依据是 Skill 的核心执行逻辑。
+
+---
+
+## 1. 顺序工作流
+
+**特征**：步骤按固定顺序依次执行，前一步的输出是后一步的输入，无循环。
+
+**适用场景**：提交流程、部署流程、文件迁移、一次性转换。
+
+**声明格式**：
+```markdown
+本 Skill 采用 **顺序工作流**：
+1. **阶段A**：描述
+2. **阶段B**：描述
+3. **阶段C**：描述
+```
+
+**示例**：git-feat（分支→暂存→提交→推送→集成）
+
+---
+
+## 2. 迭代优化工作流
+
+**特征**：执行→检查→改进→再检查，循环直到达标或达到最大迭代次数。
+
+**适用场景**：代码质量修复、文档优化、评分达标、搜索精炼。
+
+**声明格式**：
+```markdown
+本 Skill 采用 **迭代优化** 工作流：
+1. **执行**：描述
+2. **检查**：描述
+3. **判断**：达标→输出 / 未达标→改进
+4. **改进**：描述
+5. **循环**：回到步骤2
+```
+
+**必须定义**：目标条件、最大迭代次数、终止策略。
+
+**示例**：pipeline-check（检查→修复→验证→迭代）、better-skill（评估→改进→重评→迭代）
+
+---
+
+## 3. 多 MCP 协调工作流
+
+**特征**：协调多个外部工具/技能/服务，主 Skill 负责调度和汇总。
+
+**适用场景**：跨系统操作、多技能编排、API 聚合。
+
+**声明格式**：
+```markdown
+本 Skill 采用 **多 MCP 协调** 工作流：
+1. **调度**：描述如何选择和调用外部技能/工具
+2. **协调**：描述数据在多个调用间如何传递
+3. **汇总**：描述如何合并多个结果
+```
+
+**必须定义**：协调的技能/工具列表、数据传递方式、部分失败处理。
+
+**示例**：pipeline-fix（读取bug→提取→生成→协调pipeline-check→输出）
+
+---
+
+## 4. 上下文感知工作流
+
+**特征**：根据运行时环境、用户输入或文件状态动态选择执行路径。
+
+**适用场景**：条件分支处理、环境适配、多模式切换。
+
+**声明格式**：
+```markdown
+本 Skill 采用 **上下文感知** 工作流：
+1. **感知**：描述如何检测上下文（环境变量、文件状态、用户输入）
+2. **决策**：描述根据上下文选择哪条执行路径
+3. **执行**：描述各条路径的处理逻辑
+```
+
+**必须定义**：上下文检测方式、分支条件、每条分支的完整流程。
+
+**示例**：pipeline-check（根据是否提供rules参数选择全量/定向模式）
+
+---
+
+## 5. 领域智能工作流
+
+**特征**：基于领域知识库进行推理、匹配和生成，核心是知识驱动而非流程驱动。
+
+**适用场景**：规则匹配、知识问答、智能推荐、模式识别。
+
+**声明格式**：
+```markdown
+本 Skill 采用 **领域智能** 工作流：
+1. **加载**：加载领域知识库（references/）
+2. **匹配**：将输入与知识库中的模式/规则进行匹配
+3. **推理**：基于匹配结果进行推理或生成
+4. **输出**：描述输出格式
+```
+
+**必须定义**：知识库位置和格式、匹配/推理逻辑。
+
+**示例**：blame-skill（加载评分规则→匹配Skill特征→评分推理→输出报告）