jsharness 1.0.0

package/.harness/skills/lint-check.md

@@ -0,0 +1,482 @@
+# 静态检查技能 (lint-check)
+
+> **执行角色**: 开发实现 Agent / 代码审查 Agent / Gate Scripts
+> **触发时机**: 每次 commit 前、PR 提交时、Gate 门禁检查时
+
+---
+
+## ESLint / Prettier 执行
+
+### 基础命令
+
+```bash
+# ESLint 全量检查
+npx eslint . --ext .ts,.tsx,.js,.jsx --max-warnings 0
+
+# 只检查变更文件（推荐用于 Git Hooks）
+npx eslint $(git diff --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$')
+
+# Prettier 格式化检查
+npx prettier --check "src/**/*.{ts,tsx,js,jsx,css,json,md}"
+
+# 自动修复
+npx eslint . --fix && npx prettier --write "src/**/*.{ts,tsx,js,jsx}"
+```
+
+### ESLint 配置基准（flat config 示例）
+
+```javascript
+// eslint.config.js
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import vuePlugin from 'eslint-plugin-vue';
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...vuePlugin.configs['flat/recommended'],
+  {
+    plugins: {
+      'vue': vuePlugin,
+    },
+    rules: {
+      // === 错误级别 ===
+      'no-console': 'error',
+      'no-debugger': 'error',
+      'no-unused-vars': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+
+      // === Vue3 核心规则 ===
+      'vue/multi-word-component-names': 'off',
+      'vue/require-default-prop': 'off',
+      'vue/no-unused-vars': 'error',
+      'vue/no-mutating-props': 'error',
+      'vue/require-v-for-key': 'error',
+
+      // === 风格一致性 ===
+      'eqeqeq': ['error', 'always'],
+      'curly': ['error', 'all'],
+      'prefer-const': 'error',
+      'no-var': 'error',
+    },
+    ignores: [
+      'dist/**',
+      'node_modules/**',
+      'coverage/**',
+      '*.config.js',
+      '*.config.ts',
+    ],
+  }
+);
+```
+
+---
+
+## 安全扫描（npm audit / SAST）
+
+### npm Audit
+
+```bash
+# 扫描依赖漏洞
+npm audit
+
+# JSON 格式输出（供 Gate 脚本解析）
+npm audit --json
+
+# 按级别过滤
+# 门禁标准：HIGH 和 CRITICAL 必须 = 0
+```
+
+### 漏洞分级处理
+
+| 严重程度 | 数量限制 | 处理方式 |
+|----------|---------|----------|
+| CRITICAL | **= 0** | 门禁 FAIL，立即修复 |
+| HIGH | **= 0** | 门禁 FAIL，24 小时内修复 |
+| MODERATE | ≤ 5 | 记录警告，下次迭代修复 |
+| LOW | 不限 | 记录，低优先级跟踪 |
+
+### Secret 扫描（Git History 检测）
+
+```bash
+# 检测 git 历史中的密钥泄露
+npx detect-secrets scan [--baseline .secrets.baseline]
+
+# 或者使用 Gitleaks
+gitleaks detect --source . -v
+```
+
+**检测目标**:
+- AWS Access Key / Secret Key
+- GitHub Personal Access Token
+- JWT Secret
+- Database Connection Strings
+- Private Keys (.pem, .key)
+- API Keys (Google, Stripe, etc.)
+- Passwords in URLs
+
+---
+
+## 结果汇总与分级
+
+### 输出格式
+
+```yaml
+lint_result:
+  timestamp: "2026-05-20T22:00:00Z"
+  tool: "eslint + prettier + npm-audit + gitleaks"
+  overall_status: pass | warning | fail
+  
+  categories:
+    eslint:
+      status: pass
+      errors: 0
+      warnings: 0
+      files_scanned: 142
+      
+    prettier:
+      status: pass
+      unformatted_files: 0
+      
+    security:
+      npm_audit:
+        critical: 0
+        high: 0
+        moderate: 2
+        low: 8
+      secret_scan:
+        findings: 0
+        secrets_found: []
+        
+  details:
+    issues: []  # 空 = 通过
+    # issues:
+    #   - file: "src/utils/helper.ts"
+    #     line: 23
+    #     rule: "no-console"
+    #     severity: "error"
+    #     message: "Unexpected console.log"
+```
+
+### 状态判定规则
+
+```javascript
+function determineStatus(result) {
+  // FAIL 条件（任一满足即 FAIL）
+  if (result.eslint.errors > 0) return 'fail';
+  if (result.security.npm_audit.critical > 0) return 'fail';
+  if (result.security.npm_audit.high > 0) return 'fail';
+  if (result.security.secret_scan.findings > 0) return 'fail';
+  
+  // WARNING 条件
+  if (result.eslint.warnings > 0) return 'warning';
+  if (result.prettier.unformatted_files > 0) return 'warning';
+  if (result.security.npm_audit.moderate > 5) return 'warning';
+  
+  // PASS
+  return 'pass';
+}
+```
+
+### 白名单机制
+
+某些情况允许例外（需在 `.harness/config/lint-whitelist.yaml` 中登记）：
+
+```yaml
+whitelist:
+  rules:
+    - rule: "no-console"
+      reason: "CLI 工具入口文件需要 console 输出"
+      files: ["src/cli/index.ts"]
+      expires: "2026-06-30"  # 白名单必须有到期日
+      
+  paths:
+    - path: "src/legacy/"
+      reason: "遗留代码重构中，计划 Q3 完成"
+      expires: "2026-09-30"
+```
+
+---
+
+# ════════════════════════════════════════════════════════
+#  Java 后端静态检查（Checkstyle + PMD + SpotBugs）
+# ════════════════════════════════════════════════════════
+
+> **适用技术栈**: Spring Boot / JDK21
+> **参考规则**: `rules/project/java-backend.md` §命名规范
+
+---
+
+## Checkstyle — 代码风格检查
+
+### Maven 执行
+
+```bash
+# 运行 Checkstyle 检查
+mvn checkstyle:check
+
+# 查看详细报告（不阻塞）
+mvn checkstyle:checkstyle
+
+# 报告位置
+# target/site/checkstyle.html        # HTML 可视化报告
+# target/site/checkstyle-result.xml   # XML 格式原始数据
+```
+
+### 推荐规则集配置
+
+| 规则集 | 适用场景 | 严格度 |
+|--------|---------|--------|
+| `google_checks.xml` | 通用 Java 项目 | 中等 |
+| `sun_checks.xml` | Sun/Oracle 风格 | 较松 |
+| **自定义** (推荐) | 公司内部标准 | **按规范** |
+
+### pom.xml 插件配置（推荐）
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-checkstyle-plugin</artifactId>
+    <version>3.3.1</version>
+    <configuration>
+        <configLocation>checkstyle/custom-checks.xml</configLocation>
+        <encoding>UTF-8</encoding>
+        <consoleOutput>true</consoleOutput>
+        <failsOnError>true</failsOnError>
+        <!-- 排除自动生成的代码 -->
+        <excludes>**/entity/**,**/dto/**,**/vo/**</excludes>
+    </configuration>
+    <executions>
+        <execution>
+            <id>validate</id>
+            <phase>validate</phase>
+            <goals><goal>check</goal></goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+### 常见违规及修复
+
+| 违规 ID | 说明 | 修复方式 |
+|---------|------|----------|
+| `FileLength` | 单文件过长 (>1000 行) | 拆分职责到多个类 |
+| `MethodLength` | 方法过长 (>50 行) | 提取子方法 |
+| `LineLength` | 行超长 (>120 字符) | 换行或提取变量 |
+| `JavadocMethod` | 缺少 Javadoc 注释 | 补充方法注释 |
+| `MissingOverride` | 缺少 @Override | 添加注解 |
+
+---
+
+## PMD — 代码质量分析
+
+### Maven 执行
+
+```bash
+# 运行 PMD 分析
+mvn pmd:pmd          # 生成报告
+mvn pmd:check        # 门禁检查（失败则 build 失败）
+
+# 报告位置
+# target/site/pmd.html               # HTML 报告
+# target/pmd.xml                     # XML 原始数据
+```
+
+### 常见问题模式分类
+
+| 类别 | 示例 | 严重度 |
+|------|------|--------|
+| **代码复杂度** | CyclomaticComplexity > 10 | 🔴 高 |
+| **空指针风险** | NullAssignment / ReturnNullFromCollection | 🔴 高 |
+| **性能问题** | AvoidInstantiatingObjectsInLoops | 🟡 中 |
+| **代码风格** | LongVariable / ShortVariable | ⚠️ 低 |
+| **最佳实践** | UseArrayListInsteadOfVector | 🟡 中 |
+
+### pom.xml 配置示例
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-pmd-plugin</artifactId>
+    <version>3.21.2</version>
+    <configuration>
+        <rulesets>
+            <ruleset>pmd/rules/java-best-practices.xml</ruleset>
+            <ruleset>pmd/rules/java-codesize.xml</ruleset>
+        </rulesets>
+        <failOnViolation>true</failOnViolation>
+        <excludeFromFailureFile>pmd-exclude.properties</excludeFromFailureFile>
+    </configuration>
+</plugin>
+```
+
+---
+
+## SpotBugs — Bug 模式检测
+
+### Maven 执行
+
+```bash
+# 运行 SpotBugs 扫描
+mvn spotbugs:spotbugs     # 生成报告
+mvn spotbugs:check        # 门禁检查
+
+# 报告位置
+# target/spotbugsXml.xml              # XML 报告
+# target/spotbugsHtml.html           # HTML 可视化报告（可选）
+```
+
+### 必须修复的高优先级 Bug 模式
+
+| Bug 模式 | 说明 | 风险 |
+|----------|------|------|
+| **NP_NULL_ON_SOME_PATH** | 可能的空指针解引用 | NPE 导致服务崩溃 |
+| **OS_OPEN_STREAM** | 流未关闭 | 资源泄漏 |
+| **SQL_NONCONSTANT_STRING_PASSED_TO_EXECUTE** | SQL 注入风险 | 安全漏洞！ |
+| **EI_EXPOSE_REP** | 内部状态可被外部修改 | 数据不一致 |
+| **DM_CONVERTED_MAP** | HashMap 的 key 类型可能不一致 | ClassCastException |
+
+### pom.xml 配置示例
+
+```xml
+<plugin>
+    <groupId>com.github.spotbugs</groupId>
+    <artifactId>spotbugs-maven-plugin</artifactId>
+    <version>4.8.3.1</version>
+    <configuration>
+        <effort>Max</effort>
+        <threshold>Low</threshold>
+        <failOnError>true</failOnError>
+        <excludeFilterFile>spotbugs-exclude.xml</excludeFilterFile>
+        <plugins>
+            <plugin>
+                <groupId>com.mebigfatguy.sbcontrib</groupId>
+                <artifactId>sbcontrib</artifactId>
+                <version>7.6.0</version>
+            </plugin>
+        </plugins>
+    </configuration>
+    <executions>
+        <execution>
+            <phase>verify</phase>
+            <goals><goal>check</goal></goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+---
+
+## SonarQube — 代码质量平台
+
+### 本地启动 SonarQube（开发环境）
+
+```bash
+# Docker 启动本地 SonarQube（快速验证用）
+docker run -d --name sonarqube \
+  -p 9000:9000 \
+  -e SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true \
+  sonarqube:community
+
+# 访问 http://localhost:9000 (默认 admin/admin)
+```
+
+### 项目扫描命令
+
+```bash
+# Maven 方式扫描（推荐）
+mvn sonar:sonar \
+  -Dsonar.host.url=http://localhost:9000 \
+  -Dsonar.login=YOUR_TOKEN \
+  -Dsonar.projectKey=com.jieshun:backend \
+  -Dsonar.sources=src/main/java \
+  -Dsonar.tests=src/test/java \
+  -Dsonar.java.binaries=target/classes \
+  -Dsonar.junit.reportPaths=target/surefire-reports \
+  -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
+
+# CI 环境变量注入（避免硬编码 token）
+# SONAR_TOKEN=xxx mvn sonar:sonar -Dsonar.host.url=$SONAR_URL
+```
+
+### Quality Gate 标准
+
+| 维度 | 门禁值 | 说明 |
+|------|--------|------|
+| 覆盖率 (Coverage on New Code) | ≥ 80% | 新增代码必须达标 |
+| Duplicated Lines (%) | ≤ 3% | 新增重复代码限制 |
+| Maintainability Rating | A | 新增代码可维护性评级 |
+| Reliability Rating | A/B | 新增代码可靠性 |
+| Security Hotspots Reviewed | 100% | 安全热点必须审查 |
+| Security Rating | A/B | 安全等级 |
+| Blocker Issues | = 0 | 阻断级问题为零 |
+| Critical Issues | = 0 | 严重问题为零 |
+
+---
+
+## Java Lint 结果汇总模板
+
+```yaml
+lint_result_java:
+  timestamp: "2026-05-20T22:00:00Z"
+  tools: "Checkstyle + PMD + SpotBugs (+ SonarQube)"
+  project_type: "java"
+  overall_status: pass | warning | fail
+  
+  categories:
+    checkstyle:
+      status: pass
+      errors: 0
+      warnings: 3       # 不阻断但需记录
+      files_scanned: 142
+      
+    pmd:
+      violations_by_priority:
+        blocker: 0
+        high: 1
+        medium: 5
+        low: 12
+        
+    spotbugs:
+      bug_categories:
+        correctness: 2    # NP_NULL 等
+        bad_practice: 1
+        performance: 0
+        security: 0       # 必须为 0!
+        
+    sonarqube:
+      quality_gate: PASS
+      new_code_coverage_pct: 84.2
+      new_violations: 2
+      new_security_hotspots: 0
+      
+  details:
+    issues: []  # 空 = 通过
+    # issues:
+    #   - file: "src/main/java/com/jieshun/service/UserService.java"
+    #     line: 45
+    #     tool: "SpotBugs"
+    #     pattern: "NP_NULL_ON_SOME_PATH"
+    #     severity: "high"
+```
+
+### 状态判定规则（Java）
+
+```javascript
+function determineJavaStatus(result) {
+  // FAIL 条件
+  if (result.checkstyle.errors > 0) return 'fail';
+  if (result.pmd.violations.blocker > 0) return 'fail';
+  if (result.spotbugs.bug_categories.security > 0) return 'fail';  // 安全红线
+  if (result.sonarqube.quality_gate === 'FAIL') return 'fail';
+
+  // WARNING 条件  
+  if (result.pmd.violations.high > 0) return 'warning';
+  if (result.spotbugs.bug_categories.correctness > 3) return 'warning';
+  if (result.checkstyle.warnings > 10) return 'warning';
+  
+  // PASS
+  return 'pass';
+}
+```

package/.harness/skills/task-board-maintenance.md

@@ -0,0 +1,105 @@
+# TaskBoard 维护 Skill
+
+> **执行角色**: PM Agent / 工作流引擎
+> **触发时机**: 任务状态变更时、每日定时、周报生成前
+
+---
+
+## 操作清单
+
+### 1. 新任务注册
+
+当 PM 收到新需求时：
+
+```markdown
+- [ ] 1. 分配 Task ID（格式：TASK-YYYYMMDD-NNN）
+- [ ] 2. 判断流程变体类型
+  - [ ] 新功能 → 标准七阶段流程
+  - [ ] Bug 修复 → Bug 修复轻量流程
+  - [ ] P0/P1 生产问题 → 热修最快路径
+  - [ ] 文档/配置变更 → 微型流程
+  - [ ] 安全漏洞 → 安全响应流程
+- [ ] 3. 在「待开始任务」表添加一行
+- [ ] 4. 检查是否与历史任务重复（搜索 TaskBoard 和已关闭的 Issue）
+- [ ] 5. 如有关联的 Issue/PR，填入对应编号
+- [ ] 6. 更新「新增需求」计数器
+```
+
+### 2. 状态推进
+
+当一个阶段完成，需要推入下一阶段：
+
+```markdown
+- [ ] 1. 从当前区域移动目标任务到下一区域
+- [ ] 2. 更新「当前阶段」字段
+- [ ] 3. 更新「负责Agent」字段为下一个角色
+- [ ] 4. 更新「上次更新」为当前时间
+- [ ] 5. 在备注中记录简要原因（可选）
+- [ ] 6. 如果是打回，在「备注」中注明打回原因和来源角色
+```
+
+### 3. 交付归档
+
+测试 PASS 后：
+
+```markdown
+- [ ] 1. 移动到「已完成」区域
+- [ ] 2. 填写「交付结论」
+  - [ ] PASS: 全部检查通过，无遗留问题
+  - [ ] CONDITIONAL_PASS: 通过但有必修项需跟踪
+- [ ] 3. 计算「实际周期」（从进入开发到完成的自然日天数）
+- [ ] 4. 填写「归档日期」
+- [ ] 5. 收集并填写各阶段的文档链接
+- [ ] 6. 更新度量指标
+```
+
+### 4. 度量数据计算
+
+```yaml
+metrics:
+  # 每次操作后自动更新
+  new_requirements_count:
+    calculation: "统计本周新增的任务数量"
+  
+  completed_delivery_count:
+    calculation: "统计本周归档到已完成区的任务数量"
+  
+  avg_cycle_time_days:
+    calculation: "已完成任务的 actual_cycle_time 平均值"
+    
+  rollback_rate:
+    formula: "(总打回次数 / 总完成任务数) × 100"
+    target: "< 15%"
+    
+  blocked_tasks_count:
+    calculation: "当前处于 HOLD 或 BLOCK 状态的任务数"
+    
+  process_violation_count:
+    calculation: "本周期内 process-discipline 违规次数"
+    
+  stage_load_balance:
+    check: "任一阶段的进行中任务数 > 3 时发出警告"
+
+# 周报数据点
+weekly_report_data_points:
+  - velocity: "每周完成的需求总数"
+  - lead_time: "从需求接收到交付的平均天数"
+  - quality_score: "Gate 通过率平均值"
+  - team_utilization: "各 Agent 的任务分布均匀度"
+```
+
+### 5. 定期维护
+
+```markdown
+## 每日检查（PM Agent 自动执行）
+- [ ] 检查是否有超时未更新的任务（超过 48 小时的进行中任务）
+- [ ] 检查是否有阻塞超过 24 小时的任务
+- [ ] 更新「最后更新」时间戳
+
+## 每周清理（PM Agent 手动执行）
+- [ ] 清理已取消或合并的重复条目
+- [ ] 确认已完成任务都已正确归档
+- [ ] 生成周度度量报告
+- [ ] 识别瓶颈阶段（哪个阶段积压最多）
+- [ ] 汇总流程违规情况并提出改进建议
+```