@chongyan/autospec 1.0.1 → 1.0.3

package/plugins/skills/benchmark-executor/SKILL.md

@@ -1,647 +0,0 @@
----
-name: benchmark-executor
-description: "Execute benchmarks evaluation for practical workflow stages, compare actual outputs against criteria, and generate evaluation reports to guide optimization"
----
-
-# Benchmark Executor — 阶段 Benchmarks 执行器
-
-## 定位
-
-在实战流程各阶段（requirement/design/implementation/testing）中执行 benchmarks 评测，对比实际产出与预期标准，生成评测报告指导优化迭代。
-
-## 触发时机
-
-1. **阶段完成时** - 阶段产出物生成后自动执行
-2. **改动检测触发** - 产出物变更时自动重新评测
-3. **手动触发** - `/benchmark --run --stage={stage}`
-4. **优化迭代时** - 根据评测建议修改后验证
-
-## 输入
-
-```yaml
-project_context:
-  project_root: string           # 实战项目根目录
-  stage: string                  # 当前阶段
-  artifacts:                     # 阶段产出物
-    - path: string
-      type: string
-      content: string
-  benchmarks_file: string        # benchmarks 文件路径
-  previous_results: object       # 上次评测结果（如有）
-```
-
-## 输出
-
-```yaml
-evaluation_report:
-  file: ".autospec/benchmarks/results/{stage}-{run-id}.json"
-  summary:
-    total: number
-    passed: number
-    failed: number
-    score: number
-    grade: string
-  results: []                    # 各 benchmark 详细结果
-  recommendations: []            # 改进建议
-  metrics: object                # 过程指标
-```
-
----
-
-## 执行步骤
-
-### Step 1: 加载 Benchmarks
-
-```
-1. 扫描 .autospec/benchmarks/auto-generated/{stage}-*.yaml
-2. 如无自动生成，扫描 .autospec/benchmarks/custom/{stage}-*.yaml
-3. 解析 YAML，加载所有 test_cases
-4. 验证 benchmarks 格式正确性
-5. 按优先级排序（P0 > P1 > P2）
-```
-
-### Step 2: 检测阶段产出物
-
-```
-1. 根据 stage 确定预期产出物清单
-2. 扫描 specs/{feature}/ 目录
-3. 验证各产出物是否存在
-4. 读取产出物内容
-5. 记录产出物状态（存在/缺失/变更）
-```
-
-各阶段预期产出物：
-
-| 阶段 | 预期产出物 |
-|------|-----------|
-| exploration | clarifications.md, requirement.md (draft) |
-| requirement | requirement.md, user-stories.md |
-| design | design.md, contracts/api.yaml, data-model.md |
-| implementation | src/**/*, tests/**/*, docs/api.md |
-| testing | test-reports/**/*, coverage-report.md |
-
-### Step 3: 执行 Layer 1 确定性验证
-
-```
-对每个 benchmark 中的 criteria：
-
-1. Schema 校验（如适用）
-   - 读取产出物的 schema 定义
-   - 验证字段完整性
-   - 验证数据类型
-
-2. 规则检查（如适用）
-   - 正则表达式匹配
-   - 关键字检查
-   - 数量统计（问题数、字段数等）
-
-3. 文件检查（如适用）
-   - 文件存在性
-   - 文件大小
-   - 最后修改时间
-
-4. 代码检查（implementation/testing 阶段）
-   - 编译检查
-   - Lint 检查
-   - 测试执行
-   - 覆盖率统计
-```
-
-### Step 4: 执行 Layer 2 AI 审查
-
-```yaml
-layer2_review:
-  trigger_condition: "Layer 1 通过或需要深度评估"
-
-  execution:
-    1. 创建独立 reviewer Agent
-    2. 传入：
-       - 产出物内容
-       - benchmark criteria
-       - 审查标准
-    3. Agent 执行审查：
-       - 逐项检查 criteria
-       - 评估质量等级
-       - 识别问题点
-       - 生成改进建议
-    4. 返回结构化审查结果
-```
-
-Layer 2 审查标准：
-
-```yaml
-review_criteria:
-  completeness:      # 完整性
-    weight: 0.25
-    checks:
-      - "所有必填字段已填充"
-      - "边界条件已定义"
-      - "异常处理已考虑"
-
-  accuracy:        # 准确性
-    weight: 0.25
-    checks:
-      - "技术方案符合需求"
-      - "设计可实现"
-      - "无逻辑矛盾"
-
-  consistency:     # 一致性
-    weight: 0.25
-    checks:
-      - "术语使用一致"
-      - "与上游产出一致"
-      - "内部无冲突"
-
-  quality:         # 质量
-    weight: 0.25
-    checks:
-      - "表达清晰"
-      - "结构合理"
-      - "符合最佳实践"
-```
-
-### Step 5: 计算评分与等级
-
-```
-评分计算：
-
-1. 单个 benchmark 得分
-   score = (criteria_passed / total_criteria) * 100
-
-2. 阶段综合得分
-   overall_score = Σ(benchmark_score * benchmark_weight) / Σ(weights)
-
-3. 等级划分
-   A+ (95-100): 优秀
-   A  (90-94):  良好
-   B+ (85-89):  较好
-   B  (80-84):  合格
-   C  (70-79):  待改进
-   D  (<70):    需重做
-
-4. 通过标准
-   - 所有 P0 benchmark 必须通过
-   - 综合得分 >= 80
-   - 无 critical 级别问题
-```
-
-### Step 6: 生成改进建议
-
-```yaml
-recommendation_generation:
-  for_each_failed_benchmark:
-    1. 分析问题根因
-    2. 关联具体产出物位置
-    3. 生成具体改进建议
-    4. 估算改进工作量
-    5. 标注优先级
-```
-
-建议格式：
-
-```yaml
-recommendation:
-  id: string
-  benchmark_id: string
-  priority: P0 | P1 | P2
-  category: schema | content | quality | consistency
-  target:
-    file: string
-    line: number          # 如适用
-    section: string      # 如适用
-  issue: string          # 问题描述
-  suggestion: string     # 改进建议
-  example: string        # 参考示例
-  estimated_effort: string  # 预计工作量
-  auto_fixable: boolean  # 是否可自动修复
-```
-
-### Step 7: 生成评测报告
-
-```yaml
-report_structure:
-  metadata:
-    run_id: string
-    stage: string
-    timestamp: ISO8601
-    trigger: auto | manual | change-detected
-    project_fingerprint: string
-
-  summary:
-    total_benchmarks: number
-    passed: number
-    failed: number
-    skipped: number
-    overall_score: number
-    grade: string
-    duration_ms: number
-
-  results:
-    - benchmark_id: string
-      name: string
-      status: passed | failed | skipped
-      score: number
-      layer1_result:
-        status: passed | failed
-        checks: []
-      layer2_result:
-        status: passed | failed
-        score: number
-        findings: []
-      issues: []
-
-  recommendations:
-    - id: string
-      priority: P0 | P1 | P2
-      description: string
-      suggestion: string
-      target_file: string
-
-  metrics:
-    layer1_duration_ms: number
-    layer2_duration_ms: number
-    total_duration_ms: number
-    retry_count: number
-```
-
-### Step 8: 反馈与迭代
-
-```
-1. 保存评测报告到 .autospec/benchmarks/results/
-2. 如评测未通过：
-   a. 向用户展示评测结果
-   b. 列出改进建议
-   c. 提供一键修复选项（如 auto_fixable）
-   d. 用户修改后触发重新评测
-3. 如评测通过：
-   a. 记录通过状态
-   b. 允许进入下一阶段
-4. 更新阶段状态文件
-```
-
----
-
-## 评测触发机制
-
-### 自动触发
-
-```yaml
-auto_triggers:
-  on_stage_complete:
-    description: "阶段完成时自动触发"
-    condition: "stage_state == 'completed'"
-    action: "execute_benchmarks"
-
-  on_file_change:
-    description: "产出物变更时触发"
-    watch_paths:
-      - "specs/**/requirement.md"
-      - "specs/**/design.md"
-      - "specs/**/contracts/*.yaml"
-      - "src/**/*"
-      - "tests/**/*"
-    debounce_ms: 5000  # 防抖5秒
-
-  on_git_commit:
-    description: "代码提交时触发"
-    trigger: "pre-commit"
-    scope: "changed_files_only"
-```
-
-### 手动触发
-
-```bash
-# 执行当前阶段 benchmarks
-/benchmark --run
-
-# 执行指定阶段
-/benchmark --run --stage=design
-
-# 执行指定 benchmark
-/benchmark --run --id=DES-001
-
-# 带修复建议执行
-/benchmark --run --suggest-fixes
-
-# 仅报告不保存
-/benchmark --run --dry-run
-```
-
----
-
-## 与阶段技能的集成
-
-### Requirement Stage 集成
-
-```yaml
-# 在 requirement-stage SKILL.md 中添加
-
-### Step 4: Benchmarks 评测（新增）
-
-1. 检测 requirement.md 是否生成
-2. 调用 benchmark-executor 执行评测
-3. 检查 benchmarks:
-   - REQ-001: 需求文档完整性
-   - REQ-002: 非功能需求覆盖
-   - REQ-003: 多系统需求一致性（如适用）
-4. 如未通过：
-   - 生成改进建议
-   - 返回 Step 2 完善需求
-   - 最多重试 3 次
-5. 如通过：
-   - 记录评测结果
-   - 允许进入 design stage
-```
-
-### Design Stage 集成
-
-```yaml
-# 在 design-stage SKILL.md 中添加
-
-### Step 4: 设计 Benchmarks 评测（新增）
-
-1. 检测设计产出物完整性
-   - design.md
-   - contracts/api.yaml
-   - data-model.md（如适用）
-2. 调用 benchmark-executor 执行评测
-3. 检查 benchmarks:
-   - DES-001: 架构设计完整性
-   - DES-002: API 设计规范性
-   - DES-003: 数据模型设计
-   - DES-004: 设计-需求一致性
-4. 如未通过：
-   - 生成改进建议
-   - 返回 Step 2 完善设计
-5. 如通过：
-   - 记录评测结果
-   - 允许进入 implementation stage
-```
-
-### Implementation Stage 集成
-
-```yaml
-# 在 implementation-stage SKILL.md 中添加
-
-### Step 5: 代码 Benchmarks 评测（新增）
-
-1. 执行 Layer 1 验证
-   - 编译检查
-   - Lint 检查
-   - 单元测试
-2. 调用 benchmark-executor 执行评测
-3. 检查 benchmarks:
-   - IMP-001: 代码-设计一致性
-   - IMP-002: 代码质量基准
-   - IMP-003: 功能完整性
-4. 如未通过：
-   - 生成改进建议
-   - 自动修复（如 auto_fixable）
-   - 返回 Step 3 修正代码
-5. 如通过：
-   - 记录评测结果
-   - 允许进入 testing stage
-```
-
-### Testing Stage 集成
-
-```yaml
-# 在 testing-stage SKILL.md 中添加
-
-### Step 3: 测试 Benchmarks 评测（新增）
-
-1. 执行测试套件
-2. 收集覆盖率报告
-3. 调用 benchmark-executor 执行评测
-4. 检查 benchmarks:
-   - TST-001: 测试覆盖率
-   - TST-002: 测试质量
-   - TST-003: 集成测试（多系统）
-5. 如未通过：
-   - 生成改进建议
-   - 返回 Step 2 补充测试
-6. 如通过：
-   - 记录评测结果
-   - 允许进入 delivery stage
-```
-
----
-
-## 评测结果处理
-
-### 通过标准
-
-```yaml
-pass_criteria:
-  must_meet:
-    - "所有 P0 benchmark 通过"
-    - "综合得分 >= 80"
-    - "无 critical 级别问题"
-
-  nice_to_have:
-    - "综合得分 >= 90"
-    - "所有 P1 benchmark 通过"
-    - "Layer 2 评分 >= 85"
-```
-
-### 未通过处理
-
-```yaml
-failure_handling:
-  level_1_auto_fix:
-    condition: "存在 auto_fixable 建议"
-    action: "执行自动修复"
-    examples:
-      - "格式问题 → 自动格式化"
-      - "缺失字段 → 补充模板"
-      - "路径错误 → 自动更正"
-
-  level_2_suggest:
-    condition: "无 auto_fixable 或修复失败"
-    action: "生成详细改进建议"
-    format: "文件 + 位置 + 问题 + 建议 + 示例"
-
-  level_3_retry:
-    condition: "用户修改后"
-    action: "重新执行评测"
-    max_retries: 3
-
-  level_4_escalate:
-    condition: "3次重试后仍未通过"
-    action: "升级人工审查"
-```
-
----
-
-## 存储结构
-
-```
-.autospec/benchmarks/
-├── auto-generated/           # 自动生成的 benchmarks
-│   ├── exploration-{timestamp}.yaml
-│   ├── requirement-{timestamp}.yaml
-│   ├── design-{timestamp}.yaml
-│   ├── implementation-{timestamp}.yaml
-│   └── testing-{timestamp}.yaml
-├── custom/                   # 用户自定义 benchmarks
-│   └── *.yaml
-├── results/                  # 评测结果
-│   ├── exploration-{run-id}.json
-│   ├── requirement-{run-id}.json
-│   ├── design-{run-id}.json
-│   ├── implementation-{run-id}.json
-│   └── testing-{run-id}.json
-└── history/                  # 历史趋势
-    └── trend-{stage}.json
-```
-
----
-
-## 反模式
-
-1. **评测与阶段脱节** - benchmarks 与阶段实际产出不匹配
-   - 缓解：benchmarks 必须基于阶段实际产出定义
-
-2. **过度评测** - 评测项过多导致流程缓慢
-   - 限制：每个阶段最多 12 个 benchmarks
-
-3. **阈值不合理** - 阈值过高或过低
-   - 缓解：基于项目复杂度和历史数据动态调整
-
-4. **忽略评测结果** - 评测失败仍允许进入下一阶段
-   - 缓解：强制执行准出标准
-
-5. **评测不反馈** - 只评测不生成改进建议
-   - 缓解：每个失败的 benchmark 必须生成具体建议
-
----
-
-## 使用示例
-
-### 场景1：需求阶段自动评测
-
-```
-用户完成需求编写
-    ↓
-自动触发 requirement benchmarks 评测
-    ↓
-评测结果：
-  - REQ-001: 通过 (95分)
-  - REQ-002: 失败 (60分) - 缺少性能指标
-    ↓
-生成改进建议：
-  "在 requirement.md 第 3 节补充性能指标：
-   - 响应时间: < 200ms (P95)
-   - 吞吐量: > 1000 QPS"
-    ↓
-用户补充后重新评测
-    ↓
-评测通过，进入 design stage
-```
-
-### 场景2：设计阶段变更触发
-
-```
-用户修改 design.md
-    ↓
-改动检测器触发
-    ↓
-重新执行 design benchmarks 评测
-    ↓
-评测结果：
-  - DES-004: 警告 - 设计与需求不一致
-    新增的设计项 '实时通知' 未在需求中定义
-    ↓
-用户确认：
-  - 选项1: 返回 requirement 补充需求
-  - 选项2: 移除设计中的额外功能
-    ↓
-用户选择后调整，重新评测通过
-```
-
-### 场景3：代码提交前评测
-
-```
-用户提交代码
-    ↓
-pre-commit 钩子触发 implementation benchmarks
-    ↓
-评测结果：
-  - IMP-002: 失败 - 测试覆盖率 65% < 80%
-    未覆盖的代码：
-      - src/utils/validator.js (45%)
-      - src/services/order.js (60%)
-    ↓
-阻止提交，生成测试补充建议
-    ↓
-用户补充测试后重新提交
-    ↓
-评测通过，允许提交
-```
-
----
-
-## 产出物
-
-### 评测报告示例
-
-```json
-{
-  "run_id": "20240326-001",
-  "stage": "design",
-  "timestamp": "2024-03-26T10:30:00Z",
-  "trigger": "auto",
-  "summary": {
-    "total": 4,
-    "passed": 3,
-    "failed": 1,
-    "score": 87.5,
-    "grade": "B+"
-  },
-  "results": [
-    {
-      "benchmark_id": "DES-001",
-      "name": "架构设计完整性",
-      "status": "passed",
-      "score": 95,
-      "layer1_result": { "status": "passed" },
-      "layer2_result": { "status": "passed", "score": 95 }
-    },
-    {
-      "benchmark_id": "DES-002",
-      "name": "API 设计规范性",
-      "status": "failed",
-      "score": 70,
-      "layer1_result": { "status": "passed" },
-      "layer2_result": {
-        "status": "failed",
-        "score": 70,
-        "findings": [
-          {
-            "type": "missing",
-            "item": "API 版本管理策略",
-            "severity": "medium"
-          }
-        ]
-      }
-    }
-  ],
-  "recommendations": [
-    {
-      "id": "rec-001",
-      "benchmark_id": "DES-002",
-      "priority": "P1",
-      "category": "content",
-      "target": {
-        "file": "contracts/api.yaml",
-        "section": "info"
-      },
-      "issue": "缺少 API 版本字段",
-      "suggestion": "添加 version 字段，格式为 'v1.0.0'",
-      "example": "version: '1.0.0'",
-      "estimated_effort": "5分钟",
-      "auto_fixable": true
-    }
-  ]
-}
-```