@wwkit/harness 1.0.9 → 1.0.11

package/skills/lint-language-detect/references/detect-language.js

@@ -0,0 +1,65 @@
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+const JSTS_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.vue', '.mjs', '.cjs']);
+const PY_EXTENSIONS = new Set(['.py']);
+const MAX_SCAN_DEPTH = 10;
+const EXCLUDE_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.git', '__pycache__',
+  '.venv', 'venv', '.webwork', 'reports', 'coverage',
+  '.next', '.nuxt', '.output', 'eggs', '.eggs',
+]);
+
+export function detectLanguage(rootDir) {
+  if (existsSync(join(rootDir, 'package.json'))) {
+    return 'jsts';
+  }
+  if (existsSync(join(rootDir, 'pyproject.toml')) || existsSync(join(rootDir, 'setup.py'))) {
+    return 'python';
+  }
+
+  const counts = { jsts: 0, python: 0 };
+  _countFiles(rootDir, counts, 0);
+
+  if (counts.jsts === 0 && counts.python === 0) {
+    throw new Error(
+      'No lintable source files found: no package.json, pyproject.toml, or .js/.ts/.py files detected'
+    );
+  }
+
+  return counts.jsts >= counts.python ? 'jsts' : 'python';
+}
+
+function _countFiles(dir, counts, depth) {
+  if (depth > MAX_SCAN_DEPTH) return;
+
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      if (!EXCLUDE_DIRS.has(entry)) {
+        _countFiles(fullPath, counts, depth + 1);
+      }
+    } else {
+      const ext = extname(entry).toLowerCase();
+      if (JSTS_EXTENSIONS.has(ext)) {
+        counts.jsts++;
+      } else if (PY_EXTENSIONS.has(ext)) {
+        counts.python++;
+      }
+    }
+  }
+}

package/skills/lint-rules-analyze/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: lint-rules-analyze
+description: |
+  执行 linter 检查并解析 JSON 输出，产出违规清单。按主语言调用对应 linter（eslint/ruff），
+  解析输出为统一的 violations 结构。二元制评分：0 违规=100，1+违规=0。
+  适用：lint agent 的规则分析阶段，用于基线检查和轮尾独立验证。
+  不适用：修复违规（使用 lint-tool-fix / lint-ai-fix）、非 lint 场景的代码分析。
+---
+
+# Lint 规则分析
+
+## 工作流模式
+
+顺序执行，4 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target_dir | 是 | string | 检查目标目录路径 |
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+| config_file_path | 是 | string | lint 配置文件路径 |
+
+## 输出
+
+- `violation_count`：违规总数
+- `violations`：违规列表，每条含 `{ file, line, column, rule, severity, message, fixable }`
+- `score`：评分（100 或 0）
+
+## 阶段一：执行 linter
+
+按主语言执行 linter，输出 JSON 格式：
+
+| 主语言 | 命令 |
+|--------|------|
+| jsts | `cd {root_dir} && npx eslint {target_dir} --format json` |
+| python | `cd {root_dir} && ruff check {target_dir} --output-format json` |
+
+## 阶段二：解析 JSON 输出
+
+### ESLint JSON 解析
+
+ESLint 输出 JSON 数组，每元素含 `filePath` 和 `messages[]`：
+
+```
+对每条 message 提取：
+- file: filePath（转为相对 root_dir 的相对路径）
+- line: message.line
+- column: message.column
+- rule: message.ruleId
+- severity: message.severity === 2 ? 'error' : 'warning'
+- message: message.message
+- fixable: message.fix != null
+```
+
+### Ruff JSON 解析
+
+Ruff 输出 JSON 数组，每元素含 `code`、`filename`、`location`：
+
+```
+对每条 violation 提取：
+- file: filename（转为相对 root_dir 的相对路径）
+- line: location[0]
+- column: location[1]
+- rule: code
+- severity: code.startsWith('F') || code.startsWith('E') ? 'error' : 'warning'
+- message: message
+- fixable: fix != null
+```
+
+## 阶段三：评分计算
+
+| 条件 | score |
+|------|-------|
+| violation_count = 0 | 100 |
+| violation_count > 0 | 0 |
+
+## 阶段四：输出报告
+
+输出违规清单和评分。
+
+```
+## Lint 检查结果
+
+- 违规总数: X
+- 评分: 100|0
+- error 数: X
+- warning 数: X
+- 可修复数: X
+
+### 违规明细
+| # | 文件 | 行号 | 规则 | 严重级别 | 描述 | 可修复 |
+|---|------|------|------|---------|------|--------|
+| 1 | src/foo.js | 10 | no-unused-vars | error | 'x' is defined but never used | ✗ |
+```
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| violation_count = 0 | score=100，agent 判断达标 |
+| violation_count > 0 | score=0，agent 判断需修复 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| linter 未安装 | 报错"linter 不可用，请先运行环境检查" |
+| linter exit code 1（有违规） | 正常行为，解析 JSON 输出违规清单 |
+| linter exit code 2（配置错误） | 报错"linter 配置错误" |
+| linter 执行超时 | 报错"检查超时" |
+| JSON 解析失败 | 报错"linter 输出解析失败" |
+| target_dir 不存在 | 报错"检查目录不存在" |
+| 无违规（exit code 0） | 输出 violation_count=0, score=100 |
+
+## 一定要做
+
+1. 使用 JSON 格式输出，便于解析
+2. 将文件路径转为相对 root_dir 的相对路径
+3. 统一 violations 数据结构（file/line/column/rule/severity/message/fixable）
+4. 二元制评分：0 违规=100，1+违规=0
+
+## 一定不要做
+
+1. 不要修复任何违规（只检查）
+2. 不要修改源码文件
+3. 不要省略 warning 级别的违规
+4. 不要执行网络请求

package/skills/lint-suitability-check/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: lint-suitability-check
+description: |
+  扫描目标目录，筛选出可 lint 的源码文件列表。按主语言扩展名过滤，排除依赖/构建/缓存目录。
+  适用：lint agent 的适用性检查阶段，在环境检查前确定可检查的文件范围。
+  不适用：非 lint 场景的文件筛选、语言检测（使用 lint-language-detect）。
+---
+
+# 可 Lint 文件筛选
+
+## 工作流模式
+
+顺序执行，3 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+| target_dir | 是 | string | 检查目标目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+
+## 输出
+
+- `lintable_files`：可 lint 文件路径列表（相对 root_dir 的相对路径）
+- `file_count`：文件数量
+- `excluded_count`：被排除的文件数量
+
+## 阶段一：确定扩展名过滤集
+
+| 主语言 | 匹配扩展名 |
+|--------|-----------|
+| jsts | `.js`、`.jsx`、`.ts`、`.tsx`、`.vue`、`.mjs`、`.cjs` |
+| python | `.py` |
+
+## 阶段二：递归扫描
+
+递归扫描 `target_dir`，排除以下目录：
+
+| 排除目录 | 原因 |
+|---------|------|
+| `node_modules/` | 依赖目录 |
+| `dist/`、`build/`、`.output/` | 构建产物 |
+| `.git/` | 版本控制 |
+| `__pycache__/`、`.eggs/` | Python 缓存 |
+| `.venv/`、`venv/` | 虚拟环境 |
+| `.webwork/` | 工具输出目录 |
+| `reports/`、`coverage/` | 报告目录 |
+| `.next/`、`.nuxt/` | 框架缓存 |
+
+最大扫描深度 10 层。
+
+## 阶段三：输出文件清单
+
+将匹配的文件路径转为相对 `root_dir` 的相对路径，输出列表。
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| file_count > 0 | 输出文件清单，agent 继续 |
+| file_count = 0 | 输出空列表，agent 退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| target_dir 不存在 | 报错"检查目录不存在" |
+| target_dir 是文件 | 对该单文件检查 |
+| 扫描权限不足 | 跳过不可读目录 |
+
+## 一定要做
+
+1. 按主语言扩展名精确过滤
+2. 排除所有依赖/构建/缓存目录
+3. 输出相对路径而非绝对路径
+4. 统计 file_count 供 agent 判断
+
+## 一定不要做
+
+1. 不要扫描 node_modules 等排除目录
+2. 不要返回非目标语言的文件
+3. 不要修改任何文件
+4. 不要执行网络请求

package/skills/lint-tool-fix/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: lint-tool-fix
+description: |
+  执行 linter 的 --fix 自动修复，然后内部复跑 linter 获取剩余违规清单。
+  只处理 linter 可自动修复的规则，不可修复的规则交由 lint-ai-fix 处理。
+  适用：lint agent 的工具修复阶段，在 AI 修复前先自动修复可修复项。
+  不适用：AI 语义修复（使用 lint-ai-fix）、规则检查（使用 lint-rules-analyze）。
+---
+
+# Lint 工具自动修复
+
+## 工作流模式
+
+顺序执行，3 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target_dir | 是 | string | 检查目标目录路径 |
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+| config_file_path | 是 | string | lint 配置文件路径 |
+
+## 输出
+
+- `tool_fixed_count`：自动修复的违规数
+- `remaining_violations`：修复后剩余的违规列表（结构同 lint-rules-analyze 的 violations）
+
+## 阶段一：执行 --fix
+
+按主语言执行 linter 的自动修复命令：
+
+| 主语言 | 命令 |
+|--------|------|
+| jsts | `cd {root_dir} && npx eslint {target_dir} --fix` |
+| python | `cd {root_dir} && ruff check {target_dir} --fix` |
+
+`--fix` 会自动修复所有可自动修复的违规。不可自动修复的规则不受影响。
+
+## 阶段二：复跑 linter 获取剩余违规
+
+修复后重新执行 linter 检查（同 lint-rules-analyze 的命令），获取剩余违规：
+
+| 主语言 | 命令 |
+|--------|------|
+| jsts | `cd {root_dir} && npx eslint {target_dir} --format json` |
+| python | `cd {root_dir} && ruff check {target_dir} --output-format json` |
+
+解析 JSON 输出为 `remaining_violations`（结构与 lint-rules-analyze 一致）。
+
+## 阶段三：输出
+
+```
+## 工具修复结果
+
+- 自动修复数: X
+- 剩余违规数: X
+- 剩余可修复数: X（理论上应为 0，--fix 已尽力修复）
+- 剩余不可修复数: X（需 AI 修复）
+
+### 剩余违规明细
+| # | 文件 | 行号 | 规则 | 严重级别 | 描述 | 可修复 |
+|---|------|------|------|---------|------|--------|
+| 1 | src/foo.js | 10 | no-unused-vars | error | ... | ✗ |
+```
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| remaining_violations 为空 | agent 回到轮尾评分（final_count 应为 0 → 达标） |
+| remaining_violations 非空 | agent 进入 AI 修复（Step 8） |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| --fix 执行失败 | 报错，agent 跳过工具修复直接进入 AI 修复 |
+| 复跑 linter 失败 | 报错，remaining_violations 设为空列表，agent 将在轮尾独立验证中获取真实违规数 |
+| linter 未安装 | 报错退出 |
+
+## 一定要做
+
+1. --fix 后必须复跑 linter 获取剩余违规
+2. 输出 remaining_violations 的数据结构与 lint-rules-analyze 一致
+3. 统计 tool_fixed_count（修复前违规数 - 修复后违规数）
+
+## 一定不要做
+
+1. 不要执行 AI 语义修复（那是 lint-ai-fix 的职责）
+2. 不要修改 linter 配置文件
+3. 不要跳过复跑 linter 步骤
+4. 不要执行网络请求

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}}
+```