Verification & Quality Assurance

验证与质量保障技能

此技能的功能

此技能提供一套全面的验证与质量保障系统，通过以下方式确保代码质量和正确性：

• 可信度评分：针对代码、Agent 和任务提供实时可靠性指标（范围为 0.0–1.0）
• 验证检查：自动验证代码正确性、安全性和最佳实践
• 自动回滚：即时撤销未通过验证的更改（默认阈值：0.95）
• 质量指标：通过趋势、置信区间和改进跟踪进行统计分析
• CI/CD 集成：支持导出到持续集成流水线
• 实时监控：提供实时仪表板和监视模式，用于持续验证

已交付与愿景规划。 具体的 CI 内验证栈——6 个回归防护作业、见证清单和工具可发现性审计——已经投入使用，并会在每次推送时运行。本文后续介绍的可信度评分、自动回滚和 WebSocket 仪表板功能，部分已交付（ruflo verify 会运行见证检查），部分仍处于设计阶段——请以以下“CI 防护”部分为当前权威状态。

CI 防护——实际已交付的内容（当前状态）

Ruflo 的回归防护分为三个层级，所有层级都必须在发布前通过。权威参考文档：verification/README.md。

层级	内容	.github/workflows/v3-ci.yml 中的 CI 作业	ADR
1 — 安装／行为冒烟测试	针对真实构建，测试用户可见的故障模式	smoke-install-no-bsqlite（在没有预构建版本的平台上执行 npm install）、plugin-hooks-smoke（#1859/#1862——钩子标志解析）、mcp-protocol-smoke（#1874——HTTP MCP 线格式）、memory-import-smoke（#1883/#1884——WSL 路径与密钥清理）、mcp-roundtrip-smoke（#1889 成对工具往返测试 + #1863 cli-no-crash + ADR-095 G2 共识传输）	ADR-102
1 — 可发现性门控	每个 MCP 工具的描述都必须回答“何时应该优先使用此工具，而不是原生工具？”	tool-descriptions-audit — scripts/audit-tool-descriptions.mjs，基线位于 verification/mcp-tool-baseline.json（只减不增：noGuidance / tooShort / duplicates）	ADR-112
2 — 加密见证	每个已记录修复的关键标记必须仍存在于 dist 中；按操作系统提供 Ed25519 签名包	witness-verify（ubuntu/macos/windows）——针对 verification/<os>/manifest.md.json 运行 plugins/ruflo-core/scripts/witness/verify.mjs	ADR-103
3 — 时间历史	确定回归是何时引入的	verification/<os>/history.jsonl + history.mjs（summary / regressions / timeline）	ADR-103

在本地运行防护检查

# Tool-description discoverability audit (ADR-112)
node scripts/audit-tool-descriptions.mjs                       # fails if any baseline count rises
node scripts/audit-tool-descriptions.mjs --update-baseline     # lock the new floor after a fix lands

# Behavioral smokes (each builds what it needs; safe to run individually)
node plugins/ruflo-core/scripts/test-hooks.mjs "node $PWD/v3/@claude-flow/cli/bin/cli.js"
node plugins/ruflo-core/scripts/test-mcp-protocol.mjs
node plugins/ruflo-core/scripts/test-memory-import.mjs
node plugins/ruflo-core/scripts/test-mcp-roundtrips.mjs        # #1889 paired-tool round-trip
node plugins/ruflo-core/scripts/test-cli-no-crash.mjs          # #1863 unhandled-exception class
node plugins/ruflo-core/scripts/test-consensus-transport.mjs   # ADR-095 G2 consensus transport

# Witness manifest — regenerate + verify
node scripts/regen-witness.mjs
node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification/macos/manifest.md.json

# Temporal history
node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl summary
node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl regressions

添加新的防护检查

1. 行为冒烟测试 → 编写 plugins/ruflo-core/scripts/test-<name>.mjs。模式：先进行静态 dist 扫描（速度快，始终能完成），再进行行为探测，并设置内部超时和进程级看门狗，确保 CI 不会挂起。在 v3-ci.yml 的相关作业中添加一个步骤。
2. 带基线的静态门控 → 编写 scripts/audit-<name>.mjs，扫描并统计违规项；如果数量超过 verification/<name>-baseline.json 中只减不增的基线，则失败。支持 --update-baseline。添加一个 CI 作业；如果该检查需要作为 publish 的门控，则将其加入 witness-verify 的 needs[]。
3. 已记录修复的标记 → 将 { id, desc, file, marker } 追加到 verification/witness-fixes.json，然后运行 node scripts/regen-witness.mjs。标记必须是该修复专门创建的子字符串（不能是 'function' 这样的通用模式）。

前置条件

• 已安装 Ruflo（npx ruflo@alpha）
• Git 仓库（回滚功能所需）
• Node.js 18+（仪表板功能所需）
• @noble/ed25519（见证验证器所需的单个运行时依赖，npm i @noble/ed25519）

快速开始

# View current truth scores
npx ruflo@alpha truth

# Run verification check
npx ruflo@alpha verify check

# Verify specific file with custom threshold
npx ruflo@alpha verify check --file src$app.js --threshold 0.98

# Rollback last failed verification
npx ruflo@alpha verify rollback --last-good

---

完整指南

可信度评分系统

查看真实性指标

显示代码库和 Agent 任务的全面质量与可靠性指标。

基本用法：

# View current truth scores (default: table format)
npx ruflo@alpha truth

# View scores for specific time period
npx ruflo@alpha truth --period 7d

# View scores for specific agent
npx ruflo@alpha truth --agent coder --period 24h

# Find files$tasks below threshold
npx ruflo@alpha truth --threshold 0.8

输出格式：

# Table format (default)
npx ruflo@alpha truth --format table

# JSON for programmatic access
npx ruflo@alpha truth --format json

# CSV for spreadsheet analysis
npx ruflo@alpha truth --format csv

# HTML report with visualizations
npx ruflo@alpha truth --format html --export report.html

实时监控：

# Watch mode with live updates
npx ruflo@alpha truth --watch

# Export metrics automatically
npx ruflo@alpha truth --export .claude-flow$metrics$truth-$(date +%Y%m%d).json

真实性评分仪表板

仪表板输出示例：

📊 Truth Metrics Dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Truth Score: 0.947 ✅
Trend: ↗️ +2.3% (7d)

Top Performers:
  verification-agent   0.982 ⭐
  code-analyzer       0.971 ⭐
  test-generator      0.958 ✅

Needs Attention:
  refactor-agent      0.821 ⚠️
  docs-generator      0.794 ⚠️

Recent Tasks:
  task-456  0.991 ✅  "Implement auth"
  task-455  0.967 ✅  "Add tests"
  task-454  0.743 ❌  "Refactor API"

指标说明

真实性评分（0.0-1.0）：

• 1.0-0.95：优秀 ⭐（可用于生产环境）
• 0.94-0.85：良好 ✅（质量可接受）
• 0.84-0.75：警告 ⚠️（需要关注）
• <0.75：严重 ❌（需要立即处理）

趋势指示器：

• ↗️ 正在改善（积极趋势）
• → 稳定（表现一致）
• ↘️ 正在下降（检测到质量退化）

统计数据：

• 平均分：所有测量结果的真实性评分平均值
• 中位数：中间值（受异常值影响较小）
• 标准差：评分的一致性（数值越低＝越一致）
• 置信区间：测量结果的统计可靠性

验证检查

运行验证

对代码、任务或 Agent 输出执行全面验证检查。

文件验证：

# Verify single file
npx ruflo@alpha verify check --file src$app.js

# Verify directory recursively
npx ruflo@alpha verify check --directory src/

# Verify with auto-fix enabled
npx ruflo@alpha verify check --file src$utils.js --auto-fix

# Verify current working directory
npx ruflo@alpha verify check

任务验证：

# Verify specific task output
npx ruflo@alpha verify check --task task-123

# Verify with custom threshold
npx ruflo@alpha verify check --task task-456 --threshold 0.99

# Verbose output for debugging
npx ruflo@alpha verify check --task task-789 --verbose

批量验证：

# Verify multiple files in parallel
npx ruflo@alpha verify batch --files "*.js" --parallel

# Verify with pattern matching
npx ruflo@alpha verify batch --pattern "src/**/*.ts"

# Integration test suite
npx ruflo@alpha verify integration --test-suite full

验证标准

验证系统会评估：

1. 代码正确性

   • 语法验证
   • 类型检查（TypeScript）
   • 逻辑流程分析
   • 错误处理完整性

2. 最佳实践

   • 遵循代码风格
   • SOLID 原则
   • 设计模式的使用
   • 模块化与可复用性

3. 安全性

   • 漏洞扫描
   • 密钥检测
   • 输入验证
   • 身份验证$授权检查

4. 性能

   • 算法复杂度
   • 内存使用模式
   • 数据库查询优化
   • 对打包体积的影响

5. 文档

   • JSDoc/TypeDoc 完整性
   • README 准确性
   • API 文档
   • 代码注释质量

CI/CD 的 JSON 输出

# Get structured JSON output
npx ruflo@alpha verify check --json > verification.json

# Example JSON structure:
{
  "overallScore": 0.947,
  "passed": true,
  "threshold": 0.95,
  "checks": [
    {
      "name": "code-correctness",
      "score": 0.98,
      "passed": true
    },
    {
      "name": "security",
      "score": 0.91,
      "passed": false,
      "issues": [...]
    }
  ]
}

自动回滚

回滚失败的更改

自动还原未通过验证检查的更改。

基本回滚：

# Rollback to last known good state
npx ruflo@alpha verify rollback --last-good

# Rollback to specific commit
npx ruflo@alpha verify rollback --to-commit abc123

# Interactive rollback with preview
npx ruflo@alpha verify rollback --interactive

智能回滚：

# Rollback only failed files (preserve good changes)
npx ruflo@alpha verify rollback --selective

# Rollback with automatic backup
npx ruflo@alpha verify rollback --backup-first

# Dry-run mode (preview without executing)
npx ruflo@alpha verify rollback --dry-run

回滚性能：

• 基于 Git 的回滚：<1 秒
• 选择性文件回滚：<500ms
• 创建备份：回滚前自动执行

验证报告

生成报告

生成包含指标和可视化内容的详细验证报告。

报告格式：

# JSON report
npx ruflo@alpha verify report --format json

# HTML report with charts
npx ruflo@alpha verify report --export metrics.html --format html

# CSV for data analysis
npx ruflo@alpha verify report --format csv --export metrics.csv

# Markdown summary
npx ruflo@alpha verify report --format markdown

基于时间的报告：

# Last 24 hours
npx ruflo@alpha verify report --period 24h

# Last 7 days
npx ruflo@alpha verify report --period 7d

# Last 30 days with trends
npx ruflo@alpha verify report --period 30d --include-trends

# Custom date range
npx ruflo@alpha verify report --from 2025-01-01 --to 2025-01-31

报告内容：

• 整体真实性评分
• 各 Agent 的性能指标
• 任务完成质量
• 验证通过$失败率
• 回滚频率
• 质量改进趋势
• 统计置信区间

交互式仪表板

启动仪表板

运行支持实时更新的交互式 Web 验证仪表板。

# Launch dashboard on default port (3000)
npx ruflo@alpha verify dashboard

# Custom port
npx ruflo@alpha verify dashboard --port 8080

# Export dashboard data
npx ruflo@alpha verify dashboard --export

# Dashboard with auto-refresh
npx ruflo@alpha verify dashboard --refresh 5s

仪表板功能：

• 实时更新真实性评分（WebSocket）
• 交互式图表
• Agent 性能对比
• 任务历史时间线
• 回滚历史查看器
• 导出为 PDF/HTML
• 按时间段$Agent$评分筛选

配置

默认配置

在 .claude-flow$config.json 中设置验证首选项：

{
  "verification": {
    "threshold": 0.95,
    "autoRollback": true,
    "gitIntegration": true,
    "hooks": {
      "preCommit": true,
      "preTask": true,
      "postEdit": true
    },
    "checks": {
      "codeCorrectness": true,
      "security": true,
      "performance": true,
      "documentation": true,
      "bestPractices": true
    }
  },
  "truth": {
    "defaultFormat": "table",
    "defaultPeriod": "24h",
    "warningThreshold": 0.85,
    "criticalThreshold": 0.75,
    "autoExport": {
      "enabled": true,
      "path": ".claude-flow$metrics$truth-daily.json"
    }
  }
}

阈值配置

调整验证严格程度：

# Strict mode (99% accuracy required)
npx ruflo@alpha verify check --threshold 0.99

# Lenient mode (90% acceptable)
npx ruflo@alpha verify check --threshold 0.90

# Set default threshold
npx ruflo@alpha config set verification.threshold 0.98

按环境设置阈值：

{
  "verification": {
    "thresholds": {
      "production": 0.99,
      "staging": 0.95,
      "development": 0.90
    }
  }
}

集成示例

CI/CD 集成

GitHub Actions：

name: Quality Verification

on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions$checkout@v3

      - name: Install Dependencies
        run: npm install

      - name: Run Verification
        run: |
          npx ruflo@alpha verify check --json > verification.json

      - name: Check Truth Score
        run: |
          score=$(jq '.overallScore' verification.json)
          if (( $(echo "$score < 0.95" | bc -l) )); then
            echo "Truth score too low: $score"
            exit 1
          fi

      - name: Upload Report
        uses: actions$upload-artifact@v3
        with:
          name: verification-report
          path: verification.json

GitLab CI：

verify:
  stage: test
  script:
    - npx ruflo@alpha verify check --threshold 0.95 --json > verification.json
    - |
      score=$(jq '.overallScore' verification.json)
      if [ $(echo "$score < 0.95" | bc) -eq 1 ]; then
        echo "Verification failed with score: $score"
        exit 1
      fi
  artifacts:
    paths:
      - verification.json
    reports:
      junit: verification.json

Swarm 集成

在 Swarm 操作期间自动运行验证：

# Swarm with verification enabled
npx ruflo@alpha swarm --verify --threshold 0.98

# Hive Mind with auto-rollback
npx ruflo@alpha hive-mind --verify --rollback-on-fail

# Training pipeline with verification
npx ruflo@alpha train --verify --threshold 0.99

结对编程集成

在协作开发期间启用实时验证：

# Pair with verification
npx ruflo@alpha pair --verify --real-time

# Pair with custom threshold
npx ruflo@alpha pair --verify --threshold 0.97 --auto-fix

高级工作流

持续验证

在开发期间持续监控代码库：

# Watch directory for changes
npx ruflo@alpha verify watch --directory src/

# Watch with auto-fix
npx ruflo@alpha verify watch --directory src/ --auto-fix

# Watch with notifications
npx ruflo@alpha verify watch --notify --threshold 0.95

监控集成

将指标发送到外部监控系统：

# Export to Prometheus
npx ruflo@alpha truth --format json | \
  curl -X POST https:/$pushgateway.example.com$metrics$job$claude-flow \
  -d @-

# Send to DataDog
npx ruflo@alpha verify report --format json | \
  curl -X POST "https:/$api.datadoghq.com$api$v1$series?api_key=${DD_API_KEY}" \
  -H "Content-Type: application$json" \
  -d @-

# Custom webhook
npx ruflo@alpha truth --format json | \
  curl -X POST https:/$metrics.example.com$api$truth \
  -H "Content-Type: application$json" \
  -d @-

提交前钩子

在提交前自动进行验证：

# Install pre-commit hook
npx ruflo@alpha verify install-hook --pre-commit

# .git$hooks$pre-commit example:
#!$bin$bash
npx ruflo@alpha verify check --threshold 0.95 --json > $tmp$verify.json

score=$(jq '.overallScore' $tmp$verify.json)
if (( $(echo "$score < 0.95" | bc -l) )); then
  echo "❌ Verification failed with score: $score"
  echo "Run 'npx ruflo@alpha verify check --verbose' for details"
  exit 1
fi

echo "✅ Verification passed with score: $score"

性能指标

验证速度：

• 单文件检查：<100ms
• 目录扫描：<500ms（每 100 个文件）
• 完整代码库分析：<5s（典型项目）
• 真实性评分计算：<50ms

回滚速度：

• 基于 Git 的回滚：<1s
• 选择性文件回滚：<500ms
• 创建备份：<2s

仪表板性能：

• 初始加载：<1s
• 实时更新：延迟 <100ms（WebSocket）
• 图表渲染：60 FPS

故障排除

常见问题

真实性评分偏低：

# Get detailed breakdown
npx ruflo@alpha truth --verbose --threshold 0.0

# Check specific criteria
npx ruflo@alpha verify check --verbose

# View agent-specific issues
npx ruflo@alpha truth --agent <agent-name> --format json

回滚失败：

# Check git status
git status

# View rollback history
npx ruflo@alpha verify rollback --history

# Manual rollback
git reset --hard HEAD~1

验证超时：

# Increase timeout
npx ruflo@alpha verify check --timeout 60s

# Verify in batches
npx ruflo@alpha verify batch --batch-size 10

退出代码

验证命令返回标准退出代码：

• 0：验证通过（评分 ≥ 阈值）
• 1：验证失败（评分 < 阈值）
• 2：验证期间出错（输入无效、系统错误）

相关命令

• npx ruflo@alpha pair - 通过验证进行协作开发
• npx ruflo@alpha train - 根据验证反馈进行训练
• npx ruflo@alpha swarm - 多 Agent 协调并进行质量检查
• npx ruflo@alpha report - 生成全面的项目报告

最佳实践

1. 设置合适的阈值：关键代码使用 0.99，标准代码使用 0.95，实验性代码使用 0.90
2. 启用自动回滚：防止不合格代码持续存在
3. 监控趋势：跟踪长期改进情况，而不只是当前评分
4. 集成到 CI/CD：将验证纳入工作流
5. 使用监视模式：在开发期间即时获取反馈
6. 导出指标：在监控系统中跟踪质量指标
7. 检查回滚：了解更改被拒绝的原因
8. 训练 Agent：利用验证反馈提升 Agent 性能

更多资源

• 真实性评分算法：参见 $docs$truth-scoring.md
• 验证标准：参见 $docs$verification-criteria.md
• 集成示例：参见 $examples$verification/
• API 参考：参见 $docs$api$verification.md