jsharness 1.0.0

package/.harness/docs/training-materials.md

@@ -0,0 +1,280 @@
+# Harness Engineering — 团队文档与培训材料
+
+> 本目录包含面向不同角色的使用指南和培训材料。
+
+---
+
+## 12.1 快速入门指南（面向开发者）
+
+### 《Harness 快速入门 — 5 分钟上手》
+
+#### 你是谁？
+你是开发者，你已经在写代码，现在团队引入了 Harness 来规范化 AI 辅助开发的流程。
+
+#### Harness 对你意味着什么？
+
+```
+之前：
+  需求 → 自己理解 → 直接写代码 → 提 PR → 等人 Review → 合入
+
+现在（有了 Harness）：
+  需求 → PM路由 → 需求分析师拆解 → 方案设计师出方案 → 闸门审批 → 
+  你写代码（遵循 Skill）→ 自检三步 → 提 PR → 审查Agent审 → 测试Agent验 → 合入
+```
+
+听起来步骤多了？但每一步都有明确的输入和产出，**不再模糊**。
+
+#### 你的日常工作流
+
+##### Step 1: 接任务
+
+收到闸门放行后的设计文档：
+- `design-TASK-xxx.md` — 技术方案
+- `api-definition.yaml` — 接口定义
+- `dev-map/frontend/conventions.md` — 编码规范
+
+##### Step 2: 写代码（按 Skill 操作）
+
+```bash
+# 1. 先读设计文档和 dev-map
+# （了解要做什么、怎么做、现有约定）
+
+# 2. 写核心代码
+# 3. 同时写/更新单测
+npm run test -- --watch  # 开发时保持测试通过
+
+# 4. 完成后，运行 Build Skill
+npm run build           # 编译必须通过
+
+# 5. 运行 Test Unit Skill
+npm run test            # 全部通过 + 覆盖率不降
+
+# 6. 运行 Lint Check Skill
+npx eslint . && npx prettier --check  # 零 warning
+
+# 7. 更新 dev-map（如果改了结构）
+# 8. 规范 Commit
+git commit -m "feat(user): add avatar upload (#123)"
+
+# 9. 创建 PR
+gh pr create --title "feat(user): add avatar upload (#123)" --body "..."
+```
+
+##### Step 3: 等 Review
+
+审查 Agent 会检查你的代码。可能的结果：
+
+| 结果 | 含义 | 你需要做的 |
+|------|------|-----------|
+| **PASS** | 可以合入 | 等测试通过即可 |
+| **CONDITIONAL_PASS** | 基本OK但有小问题 | 修掉必修问题即可 |
+| **FAIL** | 需要修改 | 按审查报告修复，重新提交 |
+
+##### 常见坑 & 避免
+
+| 坑 | 怎么避免 |
+|----|----------|
+| 忘记写单测 | 边写代码边写测试，TDD 思路 |
+| console.log 残留 | 提交前 `npx eslint .` 会抓到 |
+| 覆盖率降了 | Gate 会对比基线，新增代码必须有足够测试 |
+| 不知道怎么命名 | 看 `dev-map/frontend/conventions.md` |
+| 不确定某个 API 怎么调 | 看 `dev-map/frontend/api-integration.md` |
+
+#### 遇到问题？
+
+```
+1. 先看 dev-map — 大部分问题答案都在那里
+2. 再看 Skill 文件 — 标准操作步骤
+3. 最后问 PM 或 Tech Lead
+```
+
+---
+
+## 12.2 PM 操作手册
+
+### 《PM 操作指南 — 如何用好 TaskBoard 和路由》
+
+#### 你的核心职责
+
+你不是技术决策者，你是**交通指挥官**。
+
+#### 日常操作
+
+##### 1. 接收新需求
+
+```
+来源: 产品经理口头 / Jira Issue / 邮件 / 会议纪要
+
+操作:
+1. 在 TaskBoard「待分配池」中快速记录
+2. 判断类型:
+   ├── 新功能?     → 标记为 standard
+   ├── Bug?         → 判断严重度 → hotfix(紧急) / bugfix(一般)
+   ├── 文档/配置?   → micro
+   └── 安全问题?    → security-response
+3. 如果是重复需求 → 关联已有任务，不新建
+4. 分配 Task ID → 移入「待开始」→ 分配给需求分析师
+```
+
+##### 2. 监控进度（每天至少看一次 TaskBoard）
+
+```
+关注信号:
+⚠️ 任何任务在同一阶段停留超过 48 小时 → 询问原因
+⚠️ 打回次数超过 2 次 → 可能是需求不清或能力不足
+⚠️ 同一阶段堆积 >3 个任务 → 瓶颈预警，考虑加资源或排优先级
+✅ 任务正常流动 → 无需干预
+```
+
+##### 3. 处理冲突和阻塞
+
+```
+当下游提出变更请求时:
+1. 阅读变更请求内容
+2. 判断是否合理
+3. 合理 → 路由给对应上游角色处理
+4. 不合理（越界/不合理要求）→ 与下游沟通解释为什么
+5. 记录决策到 TaskBoard 备注
+```
+
+##### 4. 周报生成
+
+每周五下午，基于 TaskBoard 度量指标自动生成周报：
+- 本周完成多少个需求
+- 平均交付周期
+- 各阶段瓶颈在哪里
+- 下周重点
+
+#### 禁止事项清单
+
+```
+❌ "这个应该用 Redis"                    ← 技术判断，不是你的事
+❌ "跳过方案设计吧，直接做"              ← 流程绕过，不允许
+❌ "代码质量看起来还行"                  ← 质量评判交给审查 Agent
+❌ 未经讨论直接修改其他角色的文档          ← 违反下游不得改上游规则
+❌ 在闸门 BLOCK 时强行推进               ← 安全是红线
+```
+
+---
+
+## 12.3 QA 协作指南
+
+### 《QA 协作指南 — 如何在 Harness 中发挥最大价值》
+
+#### 你的角色变化
+
+```
+之前:
+  收到构建通知 → 手动测试 → 报告 Bug → 等修复 → 回归
+
+现在（Harness）:
+  测试验证 Agent 的核心执行者
+  自动化测试的设计者和维护者
+  Gate 结果的最终把关人
+```
+
+#### 你在流程中的位置
+
+```
+... → 开发 → 代码审查 → 【你在这里】 → 交付
+                          ↑
+                    你接收: 设计文档 + 验收标准 + 代码 + 审查报告
+                    你产出: 测试报告 + 缺陷列表 + 回归风险评估
+```
+
+#### 测试策略制定
+
+每次接到任务时：
+
+```yaml
+# 1. 读验收标准（来自需求文档）— 这是你的测试依据
+# 2. 读设计文档 — 了解技术实现，帮助定位缺陷
+# 3. 读审查报告 — 了解已经关注的风险点
+# 4. 制定测试计划:
+
+test_plan:
+  must_have:
+    - 单元测试覆盖率检查（开发者负责执行，你审核结果）
+    - API 契约测试（接口是否符合定义）
+    - E2E 关键路径测试（核心用户流程）
+    - 安全基础扫描（npm audit 等）
+    
+  should_have:
+    - 性能测试（如果有 NFR 要求）
+    - 边界值测试（字段长度限制、并发等）
+    - 兼容性测试（浏览器版本）
+    
+  focus_areas_based_on_review:
+    - 审查报告中标记的高风险区域
+    - 新增或修改的复杂函数
+    
+  regression_scope:
+    - 本次修改影响的功能模块
+    - 相关联的数据表和 API
+```
+
+#### 缺陷分级速查
+
+| 发现 | 级别 | 响应 |
+|------|------|------|
+| 数据库被删 / 支付金额错误 | P0 🔴 | 立即阻断，通知所有人 |
+| 登录不了 / 核心功能挂了 | P1 🟠 | 24h 内必须修 |
+| 显示偏差 / 非关键路径异常 | P2 🟡 | 本迭代修 |
+| UI 小瑕疵 / 文案错误 | P3 🔵 | 下版本 |
+
+#### 与开发者协作的最佳实践
+
+```markdown
+✅ 做:
+- 缺陷描述包含：复现步骤、期望行为、实际行为、截图/日志
+- 使用统一模板（defects-{task-id}.md）
+- 区分"必修"和"建议"
+
+❌ 不做:
+- 只说"有问题"不给复现步骤
+- 把风格偏好当作 Bug 提（那是 ESLint 的事）
+- 修改被测代码来"证明"Bug 存在
+```
+
+---
+
+## 12.4 培训会组织指南
+
+### 首次培训会议议程（建议 2 小时）
+
+```markdown
+# Harness Engineering 首次培训会
+
+## 时间安排（总计 ~120 分钟）
+
+### Part 1: 为什么需要 Harness？（15 分钟）
+- 当前 AI 辅助的问题（效果不稳定、不可控）
+- Harness 要解决什么
+- 预期收益
+
+### Part 2: 整体架构概览（20 分钟）
+- 七角色介绍（每人 1 分钟讲自己的职责）
+- 工作流演示（白板画一遍完整流程）
+- Rule / Skill / Gate 三层约束体系
+
+### Part 3: 分角色实操（45 分钟，分 3 组并行）
+- **开发组**: 创建一个简单的 Hello World 功能，走完开发→自检→提 PR 全流程
+- **PM组**: 模拟接收 3 个不同类型的需求，练习路由和 TaskBoard 操作
+- **QA组**: 基于一个已有的 PR，编写测试计划和执行测试
+
+### Part 4: Q&A（20 分钟）
+- 收集各组实操中遇到的问题
+- 解答疑问
+
+### Part 5: 下一步（20 分钟）
+- 选定试点需求
+- 确定试点时间表
+- 明确反馈收集方式
+```
+
+### 培训材料准备清单
+
+- [ ] PPT: Harness 架构图 + 角色职责 + 流程图
+- [ ] 每人一份打印版: Rule 摘要 + Skill 清单 + 快速参考卡
+- [ ] 试用环境：预配置好的分支和测试数据
+- [ ] 反馈表（纸质或在线表单）

package/.harness/gate/baseline.js

@@ -0,0 +1,220 @@
+/**
+ * Gate Baseline 对比机制 (baseline.js)
+ * 
+ * 功能：
+ * - 保存基线 (--save-baseline): 将当前 gate 结果保存为基线
+ * - 加载基线并与当前结果对比 (--baseline)
+ * - 标记 REGRESSION / IMPROVEMENT / STABLE
+ * - 生成对比报告
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BASELINE_FILE = path.join(process.cwd(), '.gate-baseline.json');
+
+/**
+ * 保存当前结果为基线
+ * @param {Object} currentResult - 当前 Gate Report JSON
+ */
+function saveBaseline(currentResult) {
+  const baseline = {
+    saved_at: new Date().toISOString(),
+    version: currentResult.tool || 'harness-gate v1.0.0',
+    overall_status: currentResult.overall_status,
+    categories: {},
+    metadata: {}
+  };
+
+  // 提取各类别的关键指标
+  for (const cat of currentResult.categories || []) {
+    baseline.categories[cat.category_id] = {
+      status: cat.status,
+      score: cat.score,
+      issues_count: cat.issues_count,
+      key_metrics: extractKeyMetrics(cat)
+    };
+  }
+
+  // 提取元数据指标
+  baseline.metadata = {
+    source_files_count: countSourceFiles(),
+    test_files_count: countTestFiles(),
+    package_version: getPackageVersion()
+  };
+
+  fs.writeFileSync(BASELINE_FILE, JSON.stringify(baseline, null, 2));
+  console.log(`💾 基线已保存到 ${BASELINE_FILE}`);
+  return baseline;
+}
+
+/**
+ * 对比当前结果与基线
+ * @param {Object} currentResult - 当前 Gate Report JSON
+ * @param {Object} baselineData - 历史基线数据
+ * @returns {Object} 对比结果
+ */
+function compare(currentResult, baselineData) {
+  const comparison = {
+    baseline_date: baselineData.saved_at,
+    regression: false,
+    improvement: false,
+    stable: true,
+    changes: [],
+    details: []
+  };
+
+  // 对比每个类别
+  for (const cat of currentResult.categories || []) {
+    const baselineCat = baselineData.categories?.[cat.category_id];
+    if (!baselineCat) continue;
+
+    const change = compareCategory(cat, baselineCat);
+    if (change) comparison.changes.push(change);
+
+    // 如果任何类别出现回归
+    if (change?.regression) {
+      comparison.regression = true;
+      comparison.stable = false;
+    }
+    if (change?.improvement) {
+      comparison.improvement = true;
+    }
+  }
+
+  // 元数据对比
+  if (baselineData.metadata) {
+    const currentTests = countTestFiles();
+    const baselineTests = baselineData.metadata.test_files_count || 0;
+    if (currentTests < baselineTests) {
+      comparison.changes.push({
+        type: 'metadata',
+        metric: 'test_file_count',
+        from: baselineTests,
+        to: currentTests,
+        trend: 'decrease',
+        regression: true
+      });
+      comparison.regression = true;
+      comparison.details.push(`⚠️ 测试文件数量下降: ${baselineTests} → ${currentTests} (-${baselineTests - currentTests})`);
+    } else if (currentTests > baselineTests) {
+      comparison.details.push(`✅ 测试文件数量增加: ${baselineTests} → ${currentTests} (+${currentTests - baselineTests})`);
+      comparison.improvement = true;
+    }
+  }
+
+  // 生成汇总
+  if (comparison.regression) {
+    comparison.details.unshift('🔴 检测到 REGRESSION：部分指标相比基线下降！');
+  } else if (comparison.improvement) {
+    comparison.details.unshift('📈 检测到 IMPROVEMENT：部分指标相比基线改善！');
+  } else {
+    comparison.details.unshift('✅ STABLE：所有指标与基线持平或改善');
+  }
+
+  return comparison;
+}
+
+/**
+ * 对比单个类别
+ */
+function compareCategory(current, baseline) {
+  const changes = [];
+  let hasRegression = false;
+  let hasImprovement = false;
+
+  // 状态退化
+  if (baseline.status === 'pass' && (current.status === 'fail' || current.status === 'warning')) {
+    hasRegression = true;
+    changes.push(`[${current.category}] 状态退化: ${baseline.status} → ${current.status}`);
+  }
+
+  // 状态改善
+  if ((baseline.status === 'fail' || baseline.status === 'warning') && current.status === 'pass') {
+    hasImprovement = true;
+    changes.push(`[${current.category}] 状态改善: ${baseline.status} → ${current.status}`);
+  }
+
+  // 问题数量增加（回归信号）
+  if (current.issues_count > (baseline.issues_count || 0) + 2) {
+    hasRegression = true;
+    changes.push(`[${current.category}] 问题数增加: ${(baseline.issues_count || 0)} → ${current.issues_count}`);
+  }
+  // 问题数量减少（改善信号）
+  if ((current.issues_count || 0) < (baseline.issues_count || 0) - 2) {
+    hasImprovement = true;
+    changes.push(`[${current.category}] 问题数减少: ${(baseline.issues_count || 0)} → ${current.issues_count}`);
+  }
+
+  if (changes.length === 0) return null;
+
+  return {
+    category: current.category_id,
+    regression: hasRegression,
+    improvement: hasImprovement,
+    changes
+  };
+}
+
+/**
+ * 从类别结果中提取关键指标
+ */
+function extractKeyMetrics(cat) {
+  const metrics = {};
+  
+  // 从 score 中提取百分比
+  if (cat.score && typeof cat.score === 'string') {
+    const pctMatch = cat.score.match(/(\d+)%/);
+    if (pctMatch) metrics.percentage = parseInt(pctMatch[1]);
+  }
+
+  // 从 details 中提取覆盖率等
+  if (cat.category_id === 'C' && cat.details?.unit?.coverage) {
+    metrics.coverage_avg = cat.details.unit.coverage;
+  }
+
+  return metrics;
+}
+
+// --- 辅助函数 ---
+
+function countSourceFiles() {
+  try {
+    const srcDir = path.join(process.cwd(), 'src');
+    if (!fs.existsSync(srcDir)) return 0;
+    let count = 0;
+    function walk(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) walk(path.join(dir, entry.name));
+        else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) count++;
+      }
+    }
+    walk(srcDir);
+    return count;
+  } catch { return 0; }
+}
+
+function countTestFiles() {
+  try {
+    const srcDir = path.join(process.cwd(), 'src');
+    if (!fs.existsSync(srcDir)) return 0;
+    let count = 0;
+    function walk(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) walk(path.join(dir, entry.name));
+        else if (/\.(test|spec)\.(ts|tsx|js|jsx)$/.test(entry.name)) count++;
+      }
+    }
+    walk(srcDir);
+    return count;
+  } catch { return 0; }
+}
+
+function getPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+    return pkg.version || 'unknown';
+  } catch { return 'unknown'; }
+}
+
+module.exports = { saveBaseline, compare, BASELINE_FILE };

package/.harness/gate/checks/build-gates-frontend.js

@@ -0,0 +1,152 @@
+/**
+ * Gate Check Category B (Frontend): 前端构建门槛
+ * 
+ * 从原 build-gates.js 提取的前端专用逻辑
+ * 适用于 package.json 存在的项目（Vue3/Vite 等）
+ *
+ * 检查项：
+ * - F-B1 TypeScript 类型检查（tsc --noEmit）
+ * - F-B2 依赖完整性检查（npm/pnpm ls）
+ * - F-B3 前端构建（npm run build）
+ * - F-B4 ESLint 快速检查
+ * - F-B5(可选) npm 安全审计
+ *
+ * > 来源: harness-java-fullchain change | 创建日期: 2026-05-21
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+async function run(options = {}) {
+  const issues = [];
+  const checks = [];
+
+  // 辅助函数：执行命令并记录结果
+  function runCheck(name, cmd, opts = {}) {
+    const start = Date.now();
+    try {
+      execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: opts.timeout || 120000,
+        stdio: 'pipe',
+        cwd: process.cwd(),
+        ...opts.env ? { env: { ...process.env, ...opts.env } } : {}
+      });
+      checks.push({ name, status: 'pass', duration_ms: Date.now() - start });
+      return true;
+    } catch (e) {
+      const output = (e.stderr?.toString() || e.stdout?.toString() || e.message).slice(0, 500);
+      checks.push({ name, status: 'fail', duration_ms: Date.now() - start, error: output });
+      issues.push({
+        code: `F-B${checks.length}`,
+        severity: opts.blocking ? 'error' : (opts.warningOnly ? 'warning' : 'error'),
+        message: `${name} 失败`,
+        details: output.split('\n').slice(0, 5),
+        suggestion: opts.suggestion
+      });
+      return false;
+    }
+  }
+
+  function getPackageJson() {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+    } catch { return null; }
+  }
+
+  const pkgJson = getPackageJson();
+  
+  if (!pkgJson) {
+    return {
+      status: 'warning',
+      score: 'N/A',
+      issues: [{ code: 'F-B0', severity: 'warning', message: '未找到 package.json，跳过前端构建门禁', suggestion: '此模块仅适用于前端项目' }],
+      summary: { checks: [], passed: 0, failed: 0 }
+    };
+  }
+
+  // === F-B1: TypeScript 类型检查 ===
+  // 检测是否有 tsconfig.json，有才运行 tsc
+  const hasTsConfig = fs.existsSync(path.join(process.cwd(), 'tsconfig.json'));
+  if (hasTsConfig) {
+    await runCheck(
+      'TypeScript 类型检查 (npx tsc --noEmit)',
+      'npx tsc --noEmit 2>&1',
+      { blocking: true, suggestion: '修复类型错误后再提交。运行 npx tsc --noEmit 查看具体错误' }
+    );
+  } else {
+    checks.push({ name: 'TypeScript 类型检查', status: 'skipped', duration_ms: 0, reason: '无 tsconfig.json' });
+  }
+
+  // === F-B2: 依赖完整性检查 ===
+  const pm = fs.existsSync(path.join(process.cwd(), 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
+  await runCheck(
+    `依赖完整性检查 (${pm} ls)`,
+    `${pm} ls --depth=0 2>&1 | head -20`,
+    { timeout: 30000, blocking: true, suggestion: `运行 ${pm} install 安装缺失依赖` }
+  );
+
+  // === F-B3: 前端生产构建 ===
+  if (pkgJson?.scripts?.build) {
+    await runCheck(
+      '前端生产构建 (npm/pnpm run build)',
+      `${pm} run build 2>&1`,
+      { timeout: 180000, blocking: true, suggestion: '检查构建日志定位错误原因。常见问题：类型错误/环境变量缺失/动态import路径' }
+    );
+  } else {
+    checks.push({ name: '前端生产构建', status: 'skipped', duration_ms: 0, reason: 'package.json 中无 build 脚本' });
+  }
+
+  // === F-B4: ESLint 快速检查 ===
+  const hasEslintConfig = 
+    fs.existsSync(path.join(process.cwd(), 'eslint.config.js')) ||
+    fs.existsSync(path.join(process.cwd(), '.eslintrc.js')) ||
+    fs.existsSync(path.join(process.cwd(), '.eslintrc.json')) ||
+    (pkgJson?.devDependencies && (
+      Object.keys(pkgJson.devDependencies).some(d => d.includes('eslint')) ||
+      Object.keys(pkgJson.dependencies || {}).some(d => d.includes('eslint'))
+    ));
+  
+  if (hasEslintConfig) {
+    await runCheck(
+      'ESLint 静态检查',
+      `npx eslint . --ext .ts,.tsx,.js,.jsx,.vue --max-warnings 0 --format compact 2>&1 | tail -10`,
+      { timeout: 60000, blocking: false, warningOnly: true, suggestion: '运行 npx eslint . --fix 自动修复可修复的问题' }
+    );
+  } else {
+    checks.push({ name: 'ESLint 静态检查', status: 'skipped', duration_ms: 0, reason: '未检测到 ESLint 配置' });
+  }
+
+  // === F-B5(可选): npm 安全审计 ===
+  if (pm === 'npm') {
+    await runCheck(
+      'npm 安全审计 (npm audit)',
+      'npm audit --audit-level=high 2>&1',
+      { timeout: 30000, blocking: false, warningOnly: true, suggestion: '运行 npm audit fix 修复可自动修复的漏洞；HIGH/CRITICAL 需要手动升级依赖版本' }
+    );
+  } else {
+    // pnpm 使用 pnpm audit
+    await runCheck(
+      'pnpm 安全审计 (pnpm audit)',
+      'pnpm audit --audit-level high 2>&1',
+      { timeout: 30000, blocking: false, warningOnly: true, suggestion: '运行 pnpm audit fix 修复漏洞' }
+    );
+  }
+
+  // 计算结果
+  const passed = checks.filter(c => c.status === 'pass').length;
+  const failed = checks.filter(c => c.status === 'fail').length;
+  const hasBlockingFailure = issues.some(i => i.severity === 'error');
+  
+  return {
+    project_type: 'frontend',
+    package_manager: pm,
+    status: hasBlockingFailure ? 'fail' : (failed > 0 ? 'warning' : 'pass'),
+    score: `${checks.length > 0 ? Math.round((passed / checks.filter(c => c.status !== 'skipped').length) * 100) : 100}% (${passed}/${checks.filter(c => c.status !== 'skipped').length})`,
+    issues,
+    summary: { checks, passed, failed, skipped: checks.filter(c => c.status === 'skipped').length }
+  };
+}
+
+module.exports = run;