jsharness 1.0.0

package/.harness/skills/build.md

@@ -0,0 +1,192 @@
+# 项目构建技能 (build)
+
+> ⚠️ **已废弃 (DEPRECATED)** — `harness-java-fullchain` change | 2026-05-21
+> 
+> 本文件已被技术栈专属构建技能替代。**请根据项目类型使用对应的 Skill：**
+> 
+> | 项目类型 | 推荐使用 Skill | 说明 |
+> |---------|---------------|------|
+> | **Vue3 + Vite 前端** | `skills/vue-frontend-build.md` | 完整的 Vite/TS/ESLint/Vitest/构建优化 |
+> | **Spring Boot (JDK21) 后端** | `skills/java-build.md` | 完整的 Maven/测试/JaCoCo/Docker/CI 流程 |
+> 
+> ---
+> 以下内容保留作为**通用参考/历史存档**，workflow 已切换为按技术栈条件引用上述专属 Skill。
+
+---
+
+> **执行角色**: 开发实现 Agent / CI Pipeline
+> **触发时机**: 代码修改完成后、提交 PR 前、CI 构建时
+
+---
+
+## 前端构建流程
+
+### Step 1: 依赖安装
+```bash
+# 使用 pnpm（推荐）或 npm
+pnpm install
+
+# 检查依赖安全
+npm audit --audit-level=moderate
+```
+
+**通过标准**: 安装无 error，无 HIGH/CRITICAL 安全漏洞
+
+### Step 2: 类型检查
+```bash
+# TypeScript 严格模式类型检查
+npx tsc --noEmit
+
+# 或使用项目配置的命令
+npm run type-check
+```
+
+**通过标准**: 零 type error
+
+### Step 3: 代码格式化检查
+```bash
+# ESLint 检查
+npx eslint . --ext .ts,.vue,.js --max-warnings 0
+
+# Prettier 格式化验证
+npx prettier --check "src/**/*.{ts,vue,js,css,md}"
+```
+
+**通过标准**: 零 warning（白名单规则除外）
+
+### Step 4: 生产构建
+```bash
+# Vue3 + Vite（推荐）
+npm run build
+
+# 或具体命令
+vite build         # Vite
+```
+
+### Step 5: 构建产物分析（可选但推荐）
+```bash
+# 分析打包体积
+npx @next/analyze   # Next.js
+npx rollup-plugin-visualizer  # Vite/Webpack
+
+# 通过标准：
+# - 首屏 JS ≤ 200KB (gzip)
+# - 单 chunk ≤ 100KB (gzip)
+```
+
+**通过标准**: 构建成功，退出码 0，产物体积在限制内
+
+---
+
+## 后端编译流程
+
+### Step 1: 编译检查
+```bash
+# TypeScript 后端（如 NestJS）
+npx tsc --noEmit
+
+# Java (Maven)
+mvn compile
+
+# Go
+go build ./...
+```
+
+**通过标准**: 编译零错误
+
+### Step 2: Lint 检查
+```bash
+# NestJS / Node.js
+npx eslint . --ext .ts
+
+# Java
+mvn checkstyle:check
+
+# Go
+golangci-lint run ./...
+```
+
+**通过标准**: 零 warning（可配置的白名单）
+
+---
+
+## TypeScript 类型检查专项
+
+### 配置要求
+
+```jsonc
+// tsconfig.json 必须启用
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+### any 类型使用规范
+
+| 场景 | 是否允许 | 要求 |
+|------|---------|------|
+| 新增代码 | 禁止 | 必须定义明确类型 |
+| 遗留系统重构 | 有条件允许 | 必须注释 `// TODO(#issue): replace with proper type` |
+| 第三方类型缺失 | 允许 | 封装一层并定义接口 |
+| JSON.parse 结果 | 禁止 | 使用泛型或 Zod 校验 |
+
+---
+
+## 构建失败处理策略
+
+```
+构建失败
+  │
+  ├── 依赖安装失败 → 检查 lockfile 一致性 / 清缓存重试 / 检查网络
+  │
+  ├── 类型错误 → 定位错误位置 → 修复类型 → 重新运行
+  │               └── 如果是第三方库类型问题 → 添加 type declaration
+  │
+  ├── Lint 错误 → 运行 `--fix` 自动修复 → 手动修复剩余项
+  │
+  ├── 生产构建失败 → 检查 build log → 定位问题 → 修复
+  │                   └── 常见原因：动态 import 路径错误 / 环境变量缺失
+  │
+  └── 体积超限 → 分析 bundle → 排查大依赖 → 懒加载 / tree-shaking
+```
+
+## 构建结果输出模板
+
+```yaml
+build_result:
+  timestamp: "2026-05-20T22:00:00Z"
+  status: pass | fail
+  duration_seconds: 45
+  
+  frontend:
+    typecheck:
+      errors: 0
+      warnings: 0
+    lint:
+      errors: 0
+      warnings: 0
+    build:
+      success: true
+      output_size_kb:
+        total: 180
+        gzip: 62
+        
+  backend:
+    compile:
+      success: true
+    lint:
+      errors: 0
+      warnings: 2
+      
+  security_audit:
+    critical: 0
+    high: 0
+    moderate: 3
+    low: 5
+```

package/.harness/skills/code-review.md

@@ -0,0 +1,251 @@
+# 代码审查技能 (code-review)
+
+> **执行角色**: 代码审查 Agent
+> **触发时机**: 开发者提交 PR/MR 后、合并前
+
+---
+
+## 审查逐项检查清单
+
+### A 类：代码质量（必须全部通过）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| A1 | **命名规范** | 符合 coding-standard.md 中的命名约定 | ⭐⭐⭐ |
+| A2 | **函数复杂度** | 单函数 ≤ 50 行，圈复杂度 ≤ 10 | ⭐⭐⭐ |
+| A3 | **类型安全** | 无裸 `any`，TypeScript strict 模式通过 | ⭐⭐⭐ |
+| A4 | **错误处理** | try-catch 完善，有明确的错误传播链 | ⭐⭐⭐ |
+| A5 | **代码重复** | 无明显的复制粘贴（DRY 原则） | ⭐⭐ |
+| A6 | **死代码** | 无未使用的导入、变量、函数 | ⭐⭐ |
+
+### B 类：规范遵循（必须全部通过）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| B1 | **提交规范** | Commit Message 符合 Conventional Commits | ⭐⭐ |
+| B2 | **分支策略** | 分支名称符合 feature/description-issue 格式 | ⭐ |
+| B3 | **PR 描述完整** | 含变更说明+测试方案+影响范围 | ⭐⭐⭐ |
+| B4 | **文档同步** | dev-map 相关部分已更新 | ⭐⭐ |
+| B5 | **CHANGELOG** | 用户可见的功能已更新 CHANGELOG | ⭐ |
+
+### C 类：安全与风险（一票否决）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| C1 | **无硬编码凭证** | 无密钥/token/密码出现在代码中 | 🔴 |
+| C2 | **注入防护** | SQL 参数化、XSS 转义、输入校验到位 | 🔴 |
+| C3 | **敏感数据处理** | 日志脱敏、传输加密 | 🔴 |
+| C4 | **依赖安全** | 无新的 HIGH/CRITICAL 漏洞引入 | 🔴 |
+| C5 | **权限控制** | 新增 API 有适当的认证/授权 | 🔴 |
+
+### D 类：性能考量（建议性）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| D1 | **N+1 查询** | 无明显的 N+1 问题（循环中查询数据库）| ⭐⭐ |
+| D2 | **内存泄漏** | 事件监听器/定时器正确清理 | ⭐⭐ |
+| D3 | **大数据处理** | 列表使用虚拟滚动/分页 | ⭐ |
+| D4 | **包体积** | 新增依赖评估对 bundle size 的影响 | ⭐ |
+
+### E 类：测试覆盖（必须通过）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| E1 | **单元测试** | 新增/修改代码有对应单测 | ⭐⭐⭐ |
+| E2 | **覆盖率** | 新代码覆盖率 ≥ 85% | ⭐⭐⭐ |
+| E3 | **测试质量** | 测试有意义（非假断言）| ⭐⭐ |
+
+---
+
+## 变更影响面分析
+
+### 影响范围评估矩阵
+
+```yaml
+change_impact_analysis:
+  pr_number: "#123"
+  changed_files_count: 12
+  insertions: 450
+  deletions: 120
+  
+  affected_modules:
+    - name: "用户模块"
+      files: ["src/features/user/*.ts"]
+      risk_level: high
+      impact_reason: "认证逻辑变更，可能影响所有登录流程"
+      
+    - name: "API 层"
+      files: ["src/api/user.ts", "src/api/auth.ts"]
+      risk_level: medium
+      impact_reason: "新增了两个接口端点"
+      
+  cross_module_dependencies:
+    - from: "订单模块"
+      to: "用户模块"
+      coupling_type: "API 调用"
+      needs_verification: true
+      note: "订单创建时会调用用户服务"
+      
+  regression_risk_score: 7  # 1-10 分制
+  recommended_reviewers: 
+    - "backend-team-lead"
+    - "security-reviewer"
+```
+
+---
+
+## 审查报告输出格式
+
+```markdown
+# Code Review Report — PR #123: feat(auth): JWT 双 Token 刷新机制
+
+## 总评: **CONDITIONAL PASS** ✅🟡
+
+| 维度 | 得分 | 状态 |
+|------|------|------|
+| 代码质量 (A) | 18/20 | PASS |
+| 规范遵循 (B) | 13/15 | PASS |
+| 安全风险 (C) | 5/5 | PASS |
+| 性能考量 (D) | 4/5 | PASS |
+| 测试覆盖 (E) | 7/10 | WARNING |
+
+**综合评分: 47/55 (85%)**
+
+---
+
+## 必修问题（合并前必须解决）
+
+### 🔴 C5: 新增刷新接口缺少权限中间件
+- **文件**: `src/api/auth/refresh.ts:15`
+- **现状**: `/api/v1/auth/refresh` 未添加 `@UseGuards(JwtAuthGuard)`
+- **风险**: 攻击者可能利用 refresh token 进行越权操作
+- **要求**: 添加 RefreshTokenGuard，限制调用频率
+
+### ⚠️ E2: `refreshToken()` 函数缺少错误路径测试
+- **文件**: `src/services/auth.test.ts`
+- **现状**: 只覆盖了正常刷新路径
+- **要求**: 补充 token 过期、token 被撤销、并发刷新等异常场景
+
+---
+
+## 建议改进（本次可不改，记录到技术债）
+
+### 💡 D1: 可考虑将 token 存储迁移至 HttpOnly Cookie
+- 当前方案 localStorage 在 XSS 场景下有风险
+- 可作为独立优化任务跟进
+
+---
+
+## 结论
+
+**审查结论**: CONDITIONAL_PASS — 解决 2 个必修问题后可通过
+
+**审查人**: code-reviewer-agent
+**审查耗时**: 12 分钟
+**下次审查时间**: 修正后自动触发
+```
+
+---
+
+## 打回条件
+
+以下任一条件满足时，**直接打回（FAIL）**：
+
+1. **C 类任何一项不通过**（安全红线）
+2. **A 类得分 < 60%**
+3. **PR 描述缺失或不完整**（B3 不通过且拒绝补充）
+4. **无测试覆盖的新功能代码**（E1 不通过）
+5. **影响面过大未拆分**（单 PR 超过 1000 行增量且无合理理由）
+6. **基线对比出现 REGRESSION**（测试覆盖率下降超过 5%）
+
+---
+
+## 前后端技术栈专项检查
+
+> **来源**: `files/java-backend-coding-standards/SKILL.md` + `files/frontend-project-conventions/SKILL.md`
+> **归档日期**: 2026-05-21
+
+### Java 后端专项检查（22 项）
+
+#### JB-A: 架构与分层检查（4 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| JB-A1 | Controller 薄层 | Controller 只做路由和校验，无业务逻辑 | 🔴 |
+| JB-A2 | Service 编排 | Service 做业务编排（非 CRUD 直通 Mapper） | ⭐⭐⭐ |
+| JB-A3 | Mapper 纯接口 | Mapper 不继承 BaseMapper，复杂 SQL 在 XML 中 | ⭐⭐ |
+| JB-A4 | 依赖方向正确 | 无循环/反向/跨层跳跃依赖 | 🔴 |
+
+#### JB-B: 命名与规范检查（5 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| JB-B1 | 包名规范 | 必须为 `com.jieshun`（禁止 `com.jscicd`） | ⭐ |
+| JB-B2 | 类后缀标准 | 符合 9 种标准后缀（Entity/DTO/VO/ReqVO/RespVO/Enum/Service/ServiceImpl/Controller/Mapper）| ⭐⭐ |
+| JB-B3 | Javadoc 注释 | public 类有完整 Javadoc | ⭐ |
+| JB-B4 | 方法命名清晰 | 动词开头，语义明确表达意图 | ⭐⭐ |
+| JB-B5 | 常量风格 | 使用 UPPER_SNAKE_CASE | ⭐ |
+
+#### JB-C: 参数与返回值检查（4 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| JB-C1 | JSR303 校验 | Controller 参数有 `@Valid` / `@Validated` 注解 | ⭐⭐⭐ |
+| JB-C2 | ReqVO/RespVO | 使用 ReqVO 入参、RespVO 出参分层传递 | ⭐⭐⭐ |
+| JB-C3 | 禁 Map/Entity | 禁止 Map 和 Entity 直接暴露 | 🔴 |
+| JB-C4 | Result 封装 | 返回值用统一 Result/CommonResult 封装 | ⭐⭐ |
+
+#### JB-D: 数据库与 SQL 检查（3 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| JB-D1 | SQL 预编译 | 使用 `#{}` 预编译参数绑定（防注入）| 🔴 |
+| JB-D2 | 分页拦截器 | 分页使用拦截器自动 LIMIT，非手动写 | ⭐⭐ |
+| JB-D3 | ALTER 脚本 | 表结构变更必须有 ALTER 脚本（禁删重建）| ⭐ |
+
+#### JB-E: 安全与质量检查（6 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| JB-E1 | SM4 加密存储 | 敏感数据（手机号/身份证等）SM4 加密 | 🔴 |
+| JB-E2 | RespVO 脱敏 | 手机号/邮箱/身份证按格式脱敏 | 🔴 |
+| JB-E3 | Redis TTL | Redis key 必须设置过期时间 | ⭐⭐ |
+| JB-E4 | 参数化日志 | 日志使用 `{}` 占位符，禁字符串拼接 | ⭐⭐ |
+| JB-E5 | 事务最小化 | @Transactional 范围最小化，外部调用放事务外 | ⭐⭐⭐ |
+| JB-E6 | 虚拟线程无 synchronized | JDK21 虚拟线程中无 synchronized（改 ReentrantLock）| 🔴 |
+
+### Vue3 前端专项检查
+
+#### FV-A: Composition API 与 TypeScript（4 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| FV-A1 | Composition API 强制 | 只允许 `<script setup lang="ts">`，禁止 Options API | 🔴 |
+| FV-A2 | 类型安全 | Props 用 TS interface 定义，禁止裸 any | ⭐⭐⭐ |
+| FV-A3 | Pinia 类型完整 | Store state/getters/actions 有明确类型标注 | ⭐⭐ |
+| FV-A4 | 导出类型规范 | 组件导出类型与文件命名一致 | ⭐ |
+
+#### FV-B: Element Plus 规范（3 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| FV-B1 | 消息提示 | 使用 ElMessage/ElMessageBox，不自行实现 toast | ⭐⭐ |
+| FV-B2 | 加载状态 | 使用 v-loading 指令，非手动控制变量 | ⭐ |
+| FV-B3 | 图标包裹 | 图标组件包裹在容器标签中 | ⭐ |
+
+#### FV-C: 命名与组织（3 项）
+
+| # | 检查项 | 标准 | 权重 |
+|---|--------|------|------|
+| FV-C1 | 文件命名 | PascalCase 组件文件，kebab-case 目录 | ⭐⭐ |
+| FV-C2 | 变量命名 | camelCase 变量/函数，UPPER_SNAKE_CASE 常量 | ⭐⭐ |
+| FV-C3 | 布尔/事件命名 | is前缀布尔/handle前缀事件 | ⭐ |
+
+### 技术栈专项裁决补充
+
+| 违规类型 | 默认处理 | 说明 |
+|---------|---------|------|
+| Java 架构分层违反（JB-A1/A4） | **C 类 FAIL** | 直接打回修复 |
+| Java 安全违规（JB-D1, JB-E1/E2/E6） | **C 类 FAIL** | 安全红线 |
+| Vue3 Options API（FV-A1） | **A 类扣分** | 每处 -10 分 |
+| Vue3 裸 any 无注释（FV-A2） | **A 类扣分** | 每处 -5 分 |

package/.harness/skills/docker-build.md

@@ -0,0 +1,227 @@
+# Docker 构建技能 (docker-build)
+
+> **执行角色**: 开发实现 Agent / CI Pipeline
+> **触发时机**: PR 合并到 develop/main 时、发布镜像时
+
+---
+
+## Dockerfile 构建执行
+
+### 构建命令
+
+```bash
+# 构建镜像
+docker build -t myapp:latest .
+
+# 多阶段构建（生产环境推荐）
+docker build -f Dockerfile.prod -t myapp:prod .
+
+# 带构建参数
+docker build \
+  --build-arg NODE_ENV=production \
+  --build-arg APP_VERSION=v1.2.3 \
+  -t myapp:v1.2.3 .
+
+# 构建并验证容器可启动
+docker build -t myapp:test . && \
+docker run --rm -d -p 3000:3000 myapp:test && \
+sleep 5 && \
+curl -f http://localhost:3000/api/health && \
+echo "Build OK" || echo "Build FAILED"
+```
+
+### Dockerfile 最佳实践模板（Node.js 多阶段构建）
+
+```dockerfile
+# ============================================
+# Stage 1: 构建阶段
+# ============================================
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# 先复制依赖定义文件，利用 Docker 缓存层
+COPY package.json package-lock.json* ./
+
+RUN npm ci --only=production=false
+
+# 复制源码并构建
+COPY . .
+RUN npm run build
+
+# ============================================
+# Stage 2: 运行阶段（精简生产镜像）
+# ============================================
+FROM node:20-alpine AS runner
+
+WORKDIR /app
+
+# 创建非 root 用户
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+# 从构建阶段复制必要产物
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nodejs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nodejs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node healthcheck.js || exit 1
+
+CMD ["node", "server.js"]
+```
+
+---
+
+## 镜像标签规范
+
+### 标签策略
+
+```
+格式: {image-name}:{version}-{git-sha}
+
+示例:
+  myapp:v1.2.3-a1b2c3d     # 正式版本
+  myapp:latest              # 最新稳定版（指向 main 分支最新构建）
+  myapp:develop-abc1234     # 开发版
+  myapp:pr-123-def456       # PR 预览版
+  myapp:v1.2.3-rc.1-xyz789 # 候选发布版
+```
+
+### 强制元数据标签
+
+```bash
+# 为镜像添加标准化元数据
+docker build \
+  --label "org.opencontainers.image.title=MyApp" \
+  --label "org.opencontainers.image.version=v1.2.3" \
+  --label "org.opencontainers.image.created=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --label "org.opencontainers.image.revision=$(git rev-parse HEAD)" \
+  --label "org.opencontainers.image.source=https://github.com/org/myapp" \
+  -t myapp:v1.2.3 .
+```
+
+---
+
+## 镜像大小优化检查
+
+### 限制标准
+
+| 镜像类型 | 最大大小 | 目标大小 |
+|----------|---------|---------|
+| 前端应用镜像 | 200 MB | < 150 MB |
+| 后端 API 镜像 | 300 MB | < 200 MB |
+| 全栈应用镜像 | 500 MB | < 350 MB |
+
+### 优化检查清单
+
+```bash
+# 1. 检查镜像大小
+docker images myapp:v1.2.3 --format "{{.Size}}"
+
+# 2. 检查镜像层数
+docker history myapp:v1.2.3 | wc -l
+# 目标：< 15 层
+
+# 3. 分析镜像内容（dive 工具）
+dive myapp:v1.2.3
+
+# 4. 检查安全漏洞
+docker scan myapp:v1.2.3
+# 或使用 Trivy
+trivy image --severity HIGH,CRITICAL myapp:v1.2.3
+```
+
+### 优化技巧速查
+
+| 技巧 | 效果 | 适用场景 |
+|------|------|---------|
+| **多阶段构建** | 减少 ~80% 体积 | 所有生产镜像 |
+| **Alpine 基础镜像** | 减少 ~50% 体积 | 无 glibc 依赖的应用 |
+| **.dockerignore** | 加速构建、减少上下文 | 所有项目 |
+| **npm ci --omit=dev** | 不拷贝 devDependencies | 生产镜像 |
+| **合并 RUN 指令** | 减少层数 | 多个 apt-get/install 步骤 |
+| **清理缓存** | 减少 ~100MB+ | npm/pip/apt 后清理 cache |
+
+### .dockerignore 模板
+
+```
+# Dependencies
+node_modules
+npm-debug.log
+yarn-error.log
+
+# Build output
+.next
+dist
+build
+coverage
+
+# Development
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# VCS
+.git
+.gitignore
+
+# Docs
+README.md
+LICENSE
+
+# Harness（不需要进入镜像）
+.harness/
+openspec/
+*.gate-report.json
+```
+
+---
+
+## Docker Build 结果输出模板
+
+```yaml
+docker_build_result:
+  timestamp: "2026-05-20T22:00:00Z"
+  status: pass | fail
+  
+  image:
+    name: "myapp"
+    tag: "v1.2.3-a1b2c3d"
+    size_mb: 145.3
+    layers: 11
+    base_image: "node:20-alpine"
+    
+  optimization:
+    multi_stage: true
+    distroless: false
+    non_root_user: true
+    
+  security_scan:
+    tool: "trivy"
+    critical: 0
+    high: 0
+    medium: 3
+    low: 8
+    
+  verification:
+    container_start: true
+    health_check_pass: true
+    endpoint_response: 200
+    
+  baseline_comparison:
+    size_delta_mb: -2.1    # 负数表示变小（好）
+    vulnerability_change: 0  # 不应增加
+```