jsharness 1.0.0

package/.harness/skills/vue-frontend-build.md

@@ -0,0 +1,344 @@
+# Vue3 前端构建技能 (vue-frontend-build)
+
+> **执行角色**: 开发者 Agent / CI Pipeline
+> **适用项目**: Vue3 + TypeScript + Vite 前端项目
+> **来源**: `files/frontend-project-conventions/SKILL.md`
+> **归档日期**: 2026-05-21
+
+---
+
+## 1. 开发服务器启动
+
+### 1.1 Vite Dev Server
+
+```bash
+# 启动开发服务器（默认端口 5173）
+npm run dev
+
+# 指定端口
+npm run dev -- --port 3000
+
+# 指定主机（允许局域网访问）
+npm run dev -- --host
+
+# 使用 HTTPS（本地开发模拟生产）
+npm run dev -- --https
+```
+
+**通过标准**:
+- ✅ 开发服务器正常启动无报错
+- ✅ 页面可访问，组件正常渲染
+- ✅ HMR（热模块替换）正常工作
+
+### 1.2 开发代理配置
+
+```typescript
+// vite.config.ts — API 代理配置
+export default defineConfig({
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8080',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+    },
+  },
+});
+```
+
+---
+
+## 2. TypeScript 类型检查
+
+### 2.1 类型检查命令
+
+```bash
+# 类型检查（不生成输出文件）
+npx vue-tsc --noEmit
+
+# 仅检查指定文件
+npx vue-tsc --noEmit src/pages/user/*.vue
+
+# 监听模式（保存时自动检查）
+npx vue-tsc --noEmit --watch
+```
+
+**通过标准**:
+- ✅ 零 Type Error（error 级别）
+- ⚠️ warning 可以存在但建议修复
+
+### 2.2 tsconfig.json 关键配置
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "skipLibCheck": true,
+    "jsx": "preserve",
+    "moduleResolution": "bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}
+```
+
+---
+
+## 3. 生产构建
+
+### 3.1 构建命令
+
+```bash
+# 标准生产构建
+npm run build
+
+# 指定模式（使用 .env.production 配置）
+npm run build -- --mode production
+
+# 构建分析（查看包体积）
+npm run build -- --mode analyze
+
+# 清理缓存后构建
+rm -rf node_modules/.vite && npm run build
+```
+
+**通过标准**:
+- ✅ 零构建错误
+- ✅ 构建产物输出到 `dist/` 目录
+- ✅ 包体积在合理范围内（首次加载 < 1MB）
+
+### 3.2 Vite 构建优化配置
+
+```typescript
+// vite.config.ts — 生产优化
+export default defineConfig({
+  build: {
+    target: 'es2020',
+    cssCodeSplit: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          // 将第三方库分离为独立 chunk
+          'vue-vendor': ['vue', 'vue-router', 'pinia'],
+          'element-plus': ['element-plus'],
+        },
+      },
+    },
+    chunkSizeWarningLimit: 500, // KB
+    minify: 'terser',           // terser 比 esbuild 压缩更彻底
+    terserOptions: {
+      compress: {
+        drop_console: true,     // 生产移除 console
+        drop_debugger: true,    // 生产移除 debugger
+      },
+    },
+  },
+});
+```
+
+### 3.3 构建产物结构
+
+```
+dist/
+├── assets/
+│   ├── index-[hash].js       # 主 JS bundle
+│   ├── index-[hash].css      # 主 CSS 文件
+│   └── vendor-[hash].js      # 第三方库（如果配置了分包）
+├── favicon.ico               # 图标
+└── index.html                # 入口 HTML（自动注入资源链接）
+```
+
+---
+
+## 4. ESLint + Prettier 检查
+
+### 4.1 ESLint 检查
+
+```bash
+# 检查所有 .ts/.tsx/.vue 文件
+npx eslint src/ --ext .ts,.tsx,.vue
+
+# 只检查 error 级别问题
+npx eslint src/ --ext .ts,.tsx,.vue --max-warnings 0
+
+# 自动修复能修复的问题
+npx eslint src/ --ext .ts,.tsx,.vue --fix
+
+# 指定文件/目录检查
+npx eslint src/pages/user/UserProfile.vue
+```
+
+**ESLint 规则重点** (前端项目必须遵守):
+- ✅ 无 error
+- ✅ 禁止裸 any (`@typescript-eslint/no-explicit-any`)
+- ✅ 禁止 console.log 残留 (`no-console`)
+- ✅ Vue 组件使用 Composition API (`vue/no-deprecated-options-api`)
+
+### 4.2 Prettier 格式化
+
+```bash
+# 检查格式是否符合规范
+npx prettier --check "src/**/*.{ts,tsx,vue,json}"
+
+# 格式化所有文件
+npx prettier --write "src/**/*.{ts,tsx,vue,json}"
+
+# 格式化指定目录
+npx prettier --write "src/components/**/*.vue"
+```
+
+**Prettier 配置要点** (.prettierrc):
+```json
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "vueIndentScriptAndStyle": false,
+  "endOfLine": "lf"
+}
+```
+
+### 4.3 一键检查脚本
+
+```json
+// package.json scripts
+{
+  "lint": "eslint src/ --ext .ts,.tsx,.vue --max-warnings 0",
+  "lint:fix": "eslint src/ --ext .ts,.tsx,.vue --fix",
+  "format": "prettier --write \"src/**/*.{ts,tsx,vue,json}\"",
+  "format:check": "prettier --check \"src/**/*.{ts,tsx,vue,json}\""
+}
+```
+
+---
+
+## 5. 单元测试（Vitest）
+
+### 5.1 运行测试
+
+```bash
+# 运行全部测试
+npm run test
+
+# 监听模式
+npm run test:watch
+
+# 运行单个测试文件
+npx vitest run src/utils/formatDate.test.ts
+
+# 运行包含关键字的测试
+npx vitest run -t "UserProfile"
+
+# 生成覆盖率报告
+npx vitest run --coverage
+```
+
+### 5.2 Vitest 配置要点
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import vue from '@vitejs/plugin-vue';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    globals: true,
+    environment: 'jsdom',     // DOM API 支持（Vue Test Utils 需要）
+    setupFiles: ['./src/test/setup.ts'],
+    coverage: {
+      provider: 'v8',         // 使用 v8 覆盖率引擎
+      reporter: ['text', 'html', 'lcov'],
+      include: ['src/**/*.ts', 'src/**/*.tsx'],
+      exclude: ['src/types/**', 'src/test/**'],
+      thresholds: {
+        lines: 80,
+        functions: 75,
+        branches: 70,
+        statements: 80,
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+    },
+  },
+});
+```
+
+**覆盖率目标**:
+
+| 文件类型 | 行覆盖率 | 分支覆盖率 |
+|---------|---------|-----------|
+| 工具函数 (utils/) | ≥ 90% | ≥ 85% |
+| Composables | ≥ 80% | ≥ 75% |
+| Store (Pinia) | ≥ 75% | ≥ 70% |
+| 组件渲染逻辑 | ≥ 70% | ≥ 60% |
+
+### 5.3 Vue Test Utils 标准用法
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import UserProfile from './UserProfile.vue';
+
+describe('UserProfile', () => {
+  it('正确显示用户名称', () => {
+    const wrapper = mount(UserProfile, {
+      props: { name: '张三' },
+    });
+    expect(wrapper.text()).toContain('张三');
+  });
+
+  it('点击编辑按钮触发 emit', async () => {
+    const wrapper = mount(UserProfile);
+    await wrapper.find('[data-test="edit-btn"]').trigger('click');
+    expect(wrapper.emitted('update')).toBeTruthy();
+  });
+});
+```
+
+---
+
+## 6. 构建产物优化检查
+
+### 6.1 体积分析
+
+```bash
+# 使用 rollup-plugin-visualizer 分析包体积
+npm run build -- --mode analyze
+# → 自动打开浏览器可视化图表
+
+# 或者使用命令行工具
+npx vite-bundle-visualizer
+```
+
+### 6.2 优化目标清单
+
+| 指标 | 目标值 | 说明 |
+|------|--------|------|
+| 首次 JS 加载 | < 300KB (gzip) | 主要 chunk 大小 |
+| CSS 总大小 | < 50KB (gzip) | 全部样式合计 |
+| 静态资源 | 按需懒加载 | 图片、字体等 |
+| chunk 数量 | 合理拆分 | 避免过多请求也避免单一大文件 |
+| Lighthouse Performance | ≥ 90 分 | 生产部署后检测 |
+
+### 6.3 常见体积问题及解决方案
+
+| 问题 | 原因 | 方案 |
+|------|------|------|
+| Element Plus 全量引入 | 默认导入全部组件 | 改按需引入 (`unplugin-vue-components`) |
+| Moment.js 体积大 | 含大量语言包 | 替换为 dayjs（API 兼容）|
+| 图片未压缩 | 直接放入源码目录 | 使用 image-webpack-loader 或 CDN |
+| Lodash 全量引入 | import _ from 'lodash' | 改按需 import (`lodash-es`) |
+| 字体文件过大 | 引入中文字体全集 | 使用子集化字体或系统字体 |

package/.harness/specs/quality-feedback/implementation-guide.md

@@ -0,0 +1,350 @@
+# Quality Feedback 反馈闭环系统
+
+> **目的**: 让 AI 的产出从「做完」升级为「做对」
+> **核心机制**: 自动化验证 → 问题归因 → 智能打回 → 度量追踪 → 持续改进
+
+---
+
+## 1. 验证报告标准化输出格式
+
+所有 Gate 检查结果统一输出为标准化 JSON：
+
+```json
+{
+  "report_id": "gate-{timestamp}-{random}",
+  "timestamp": "2026-05-20T22:00:00Z",
+  "tool": "harness-gate v1.0.0",
+  "overall_status": "pass | warning | fail",
+  
+  "categories": [
+    {
+      "category_id": "A",
+      "category_name": "静态规范",
+      "status": "pass",
+      "score": "95% (19/20)",
+      "issues_count": 1,
+      "issues": [
+        {
+          "code": "A3",
+          "severity": "warning",
+          "file": "src/components/Header.tsx",
+          "line": 23,
+          "message": "console.log 残留",
+          "suggestion": "移除调试语句或在 Gate 白名单中登记"
+        }
+      ]
+    }
+  ],
+  
+  "baseline_comparison": null,
+  
+  "metadata": {
+    "source_branch": "feature/user-profile-123",
+    "target_branch": "develop",
+    "committer": "developer-agent",
+    "duration_ms": 4500
+  }
+}
+```
+
+## 2. 问题自动归因分析逻辑
+
+### 归因分类树
+
+```
+Gate 报告发现问题
+  │
+  ├── 类型判断 ──────────────────────────┐
+  │     ├── 代码质量问题 (A类)           │ → 归因: 开发者 Agent
+  │     │     ├── 命名不规范             │
+  │     │     ├── 复杂度过高             │
+  │     │     └── DRY 违反              │
+  │     │                               │
+  │     ├── 流程违规问题 (B类)           │ → 归因: 对应角色 + PM
+  │     │     ├── Commit 格式错误       │
+  │     │     └── 缺少文档更新           │
+  │     │                               │
+  │     ├── 安全红线问题 (C/D类)        │ → 归因: 开发者 + 升级安全审查
+  │     │     ├── 凭证泄露              │
+  │     │     ├── 注入漏洞              │
+  │     │     └── CVE 依赖              │
+  │     │                               │
+  │     ├── 测试不足问题 (E/C类)         │ → 归因: 开发者(单测) + Tester(E2E)
+  │     │     ├── 覆盖率下降            │
+  │     │     ├── 关键路径无测试         │
+  │     │     └── 测试质量低            │
+  │     │                               │
+  │     └── 一致性问题 (E类)            │ → 归因: 开发者 + dev-map 维护者
+  │           ├── CHANGELOG 未更新      │
+  │           └── dev-map 过期          │
+  │                                   │
+  └── 根因深度分析 ───────────────┐
+        ├── 是否首次出现？          │
+        │   ├── 是 → 新引入的问题    │
+        │   └── 否 → 回归问题        │
+        ├── 是否与基线对比？          │
+        │   └── REGRESSION 标记      │
+        └── 是否影响其他模块？        │
+            └── 影响面评估          │
+```
+
+### 自动归因引擎伪代码
+
+```javascript
+function analyzeIssues(gateReport) {
+  const attributions = [];
+  
+  for (const issue of gateReport.allIssues) {
+    const attribution = {
+      issue: issue,
+      rootCause: classifyRootCause(issue),
+      responsibleAgent: determineResponsibleAgent(issue),
+      severityLevel: assessImpact(issue),
+      suggestedAction: generateSuggestedAction(issue),
+      isRegression: checkAgainstBaseline(issue)
+    };
+    
+    attributions.push(attribution);
+  }
+  
+  // 生成汇总
+  return {
+    summary: groupByAgent(attributions),
+    regressionCount: attributions.filter(a => a.isRegression).length,
+    blockingIssues: attributions.filter(a => a.severityLevel === 'critical'),
+    recommendedActions: prioritizeActions(attributions)
+  };
+}
+```
+
+## 3. 自动打回规则引擎
+
+### 打回条件（任一满足即触发自动打回）
+
+```yaml
+auto_reject_rules:
+  # === 绝对打回（无条件执行）===
+  absolute_rejects:
+    - condition: "category == D AND severity == error"
+      reason: "🔴 安全红线违反 — 必须立即修复并重新提交"
+      target_agent: developer
+      escalation: true       # 同时通知技术负责人
+    
+    - condition: "baseline_comparison.regression == true AND affected_tests > 5"
+      reason: "🔴 测试覆盖率严重回归 — 修复后重新提交"
+      target_agent: developer
+    
+    - condition: "any issue with code == A7"  # Secret 泄露
+      reason: "🔴 发现可能的凭证泄露！立即处理！"
+      target_agent: developer
+      block_merge: true       # 阻止合并
+    
+  # === 有条件打回（可配置阈值）===
+  conditional_rejects:
+    - condition: "total_error_issues >= 3"
+      reason: "多个检查类别未通过，建议整体 review 后重新提交"
+      require_review_before_resubmit: true
+      
+    - condition: "coverage_drop_percentage > 10"
+      reason: "测试覆盖率下降超过 10%，需要补充测试"
+      target_agent: developer
+      
+    - condition: "new_security_findings_count > 0"
+      reason: "发现新的安全问题，需要安全审查后重提"
+      target_agent: developer
+      extra_reviewer: security-reviewer
+
+  # === 警告但不打回 ===
+  warnings_only:
+    - condition: "warnings_count <= 2"
+      action: "标记 WARNING，允许合并但需在下一迭代修复"
+      track_as_tech_debt: true
+```
+
+### 打回通知模板
+
+```markdown
+## 🔁 Harness 自动打回通知
+
+**PR**: #{number} — {title}
+**触发时间**: {timestamp}
+**打回原因**: {reject_reason}
+
+### 问题清单
+{issues_list_table}
+
+### 需要操作
+1. 查看 Gate 报告: `{report_link}`
+2. 按优先级修复上述问题
+3. 重新运行 `node .harness/gate/index.js`
+4. 确认全部 PASS 后重新提交 PR Review
+
+### 如有疑问
+- 打回规则参考: `.harness/rules/global/process-discipline.md`
+- 联系 PM 或闸门总控 Agent 申诉
+```
+
+## 4. 度量指标收集与存储
+
+### 过程指标（Process Metrics）
+
+```yaml
+process_metrics:
+  # 交付效率
+  cycle_time:
+    description: "需求接收到交付的总天数"
+    calculation: "(delivery_date - received_date) in days"
+    target: "<= 7 days"
+    alert_threshold: "> 14 days"
+    
+  lead_time:
+    description: "进入开发到合入主分支的天数"
+    target: "<= 5 days"
+    
+  # 质量指标
+  gate_pass_rate:
+    description: "Gate 首次通过率"
+    formula: "(first_attempt_passes / total_attempts) × 100"
+    target: "> 80%"
+    
+  rollback_rate:
+    description: "被打回重新处理的比率"
+    formula: "(rejected_tasks / total_completed_tasks) × 100"
+    target: "< 15%"
+    
+  rework_cycles:
+    description: "平均每个任务的返工次数"
+    target: "< 1.5"
+    
+  # 合规指标
+  process_compliance_rate:
+    description: "流程纪律遵守率"
+    formula: "(compliant_actions / total_actions) × 100"
+    target: "> 95%"
+    
+  security_incidents:
+    description: "安全相关问题的数量（应为 0）"
+    target: "= 0"
+
+# 质量指标
+quality_metrics:
+  test_coverage_avg:
+    description: "平均测试覆盖率"
+    collection_source: "gate category C"
+    
+  code_quality_score:
+    description: "代码审查加权平均分"
+    collection_source: "code review reports"
+    
+  defect_escape_rate:
+    description: "逃逸到生产环境的 Bug 数量 / 总交付数"
+    target: "< 5%"
+    
+  security_vulnerability_count:
+    description: "已知安全漏洞数量（按严重度分级）"
+    collection_source: "npm audit + gate category D"
+```
+
+### 度量数据存储
+
+```javascript
+// metrics/store.js — 度量数据存储模块
+
+class MetricsStore {
+  constructor() {
+    this.storage = '.harness/data/metrics.json';
+  }
+
+  /**
+   * 记录一次 Gate 结果
+   */
+  recordGateResult(report) {
+    const entry = {
+      timestamp: report.timestamp,
+      report_id: report.report_id,
+      overall_status: report.overall_status,
+      scores: this.extractScores(report),
+      issues_summary: {
+        total: report.totalIssues,
+        byCategory: this.groupByCategory(report),
+        bySeverity: this.groupBySeverity(report)
+      },
+      baseline_delta: report.baselineComparison?.regression ? 'REGRESSION' : 
+                       report.baselineComparison?.improvement ? 'IMPROVEMENT' : 'STABLE',
+      metadata: report.metadata
+    };
+    
+    this.appendToHistory(entry);
+  }
+
+  /**
+   * 生成周报数据
+   */
+  generateWeeklyReport(startDate, endDate) {
+    const data = this.queryRange(startDate, endDate);
+    return {
+      period: `${startDate} ~ ${endDate}`,
+      summary: {
+        total_gates: data.length,
+        pass_rate: this.calcPassRate(data),
+        avg_score: this.calcAvgScore(data),
+        top_failure_categories: this.topFailures(data, 5),
+        trend: this.calcTrend(data),
+        regression_events: data.filter(d => d.baseline_delta === 'REGRESSION').length,
+        process_violations: this.countViolations(data)
+      },
+      recommendations: this.generateRecommendations(data)
+    };
+  }
+}
+```
+
+## 5. 周报自动生成功能
+
+### 周报模板
+
+```markdown
+# 📊 Harness Engineering 周报
+
+**周期**: {week_range}
+**生成时间**: {generated_at}
+**自动生成**: ✅ 由 Quality Feedback 系统生成
+
+---
+
+## 📈 本周概览
+
+| 指标 | 本周数值 | 目标值 | 趋势 vs 上周 | 状态 |
+|------|---------|--------|-------------|------|
+| 完成交付数 | {delivered_count} | ≥3 | {delta} | {status} |
+| 平均交付周期 | {avg_cycle} 天 | ≤7 | {delta} | {status} |
+| Gate 通过率 | {pass_rate}% | ≥80% | {delta} | {status} |
+| 打回率 | {rollback_rate}% | <15% | {delta} | {status} |
+| 测试覆盖率 | {avg_coverage}% | ≥80% | {delta} | {status} |
+| 流程违规次数 | {violations} | =0 | {delta} | {status} |
+
+## 🔥 Top 5 失败类别
+
+1. **{cat_1_name}** — {count} 次 ({pct}%)
+   - 主要原因: {reason_1}
+   
+2. **{cat_2_name}** — {count} 次 ({pct}%)
+
+...
+
+## ⚠️ 需要关注
+
+- {alert_1}: {description}
+- {alert_2}: {description}
+
+## 💡 改进建议
+
+基于本周数据分析：
+1. {suggestion_1}
+2. {suggestion_2}
+3. {suggestion_3}
+
+## 📋 下周重点
+
+{next_week_focus_from_pm}
+```