jsharness 1.0.0

package/.harness/skills/docs-update.md

@@ -0,0 +1,164 @@
+# 文档更新技能 (docs-update)
+
+> **执行角色**: 开发实现 Agent / 需求分析 Agent / 方案设计 Agent
+> **触发时机**: 每次代码变更后、阶段交付前
+
+---
+
+## CHANGELOG 更新检查
+
+### 格式规范（Keep a Changelog）
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New: 用户头像上传与裁剪功能 (`feat(user)` #123)
+- New: JWT 双 Token 刷新机制 (`feat(auth)` #124)
+
+### Changed
+- Update: 升级 Vue3 到 3.5 / Vite 到 6.x (`chore(deps)` #125)
+- Update: 用户列表 API 默认分页从 10 改为 20 (`fix(api)` #126)
+
+### Fixed
+- Fix: Safari 下记住登录状态失效的问题 (`fix(auth)` #127)
+- Fix: 用户查询分页边界越界 (`fix(api)` #128)
+
+### Security
+- Fix: 修复 X-XSS-Protection 头未设置的问题 (`security` #129)
+
+## [1.2.0] - 2026-05-15
+
+### Added
+- ...
+```
+
+### 检查规则
+
+| 规则 | 说明 |
+|------|------|
+| **用户可见功能** | 必须记录到 Changelog（Added / Changed / Fixed）|
+| **纯内部重构** | 可选记录到 Changed |
+| **依赖升级** | 必须记录（含安全补丁）|
+| **破坏性变更** | 必须标记 BREAKING CHANGE |
+| **Issue 关联** | 每条记录必须关联 Issue/PR 编号 |
+| **时间戳** | 每个正式版本必须有发布日期 |
+
+### Gate 检查脚本引用
+
+```yaml
+# gate/checks/engineering-consistency.js 会检查：
+# 1. 当前 PR 的改动是否需要在 CHANGELOG.md 中体现
+# 2. Unreleased 区域是否有对应条目
+# 3. 条目格式是否符合规范
+```
+
+---
+
+## dev-map 同步检查
+
+### 同步原则：**谁改代码谁更新地图**
+
+当发生以下变更时，必须同步更新 dev-map：
+
+| 代码变更 | 需要更新的 dev-map 文件 |
+|----------|------------------------|
+| 新增目录/文件 | `dev-map/frontend/structure.md` 或 `dev-map/backend/structure.md` |
+| 新增组件/复用模式 | `dev-map/frontend/components.md` 或 `dev-map/backend/structure.md` |
+| 修改状态管理方式 | `dev-map/frontend/state-management.md` |
+| 新增/修改 API | `dev-map/backend/api-definition.md` 或 `dev-map/frontend/api-integration.md` |
+| 数据模型变更 | `dev-map/backend/database.md` |
+| CI/CD 流水线调整 | `dev-map/infra/ci-cd.md` |
+| Docker/部署变更 | `dev-map/infra/docker.md` |
+| 重要技术决策 | `dev-map/decisions.md` |
+
+### 同步检查脚本
+
+```bash
+# 检查 dev-map 是否与代码一致
+node .harness/gate/checks/engineering-consistency.js --check-devmap
+```
+
+**不一致的情况**：
+- 代码中存在 dev-map 未记录的新模块 → WARNING
+- dev-map 引用了已删除的代码 → FAIL（地图过期）
+
+---
+
+## README / API 文档同步
+
+### README.md 检查项
+
+| 变更类型 | 需要更新的 README 部分 |
+|----------|-----------------------|
+| 新的环境变量 | Configuration / Environment Variables |
+| 新的 npm scripts | Getting Started / Commands |
+| 新的技术栈依赖 | Tech Stack |
+| 修改启动方式 | Quick Start |
+| 新的部署要求 | Deployment |
+
+### API 文档同步
+
+如果项目使用 OpenAPI/Swagger：
+
+```bash
+# 检查 API 文档与代码的一致性
+# 方法 1: 类型驱动（如 tsoa/nestjs/swagger）
+npm run generate:openapi   # 从代码生成文档
+diff docs/openapi.yaml generated-openapi.yaml  # 对比差异
+
+# 方法 2: 契约测试（Pact）
+npm run test:pact          # 验证文档与实现的契约一致性
+```
+
+### 文档更新检查清单
+
+```
+□ CHANGELOG.md 已更新（如有用户可见变更）
+□ dev-map 相关分区已同步
+□ README.md 环境变量/启动命令已更新
+□ API 文档（如有）与新接口一致
+□ 新增的配置项已在 .env.example 中标注
+□ 删除的功能/配置已从文档中移除
+```
+
+---
+
+## 文档更新结果输出模板
+
+```yaml
+docs_update_result:
+  timestamp: "2026-05-20T22:00:00Z"
+  status: pass | fail | warning
+  
+  changelog:
+    required: true          # 本次变更是否需要更新 CHANGELOG
+    updated: true           # 是否已完成更新
+    entry_format_valid: true
+    
+  dev_map_sync:
+    checked_files: 3
+    consistent: true
+    stale_entries: []
+    
+  readme_sync:
+    requires_update: false
+    updated: true
+    
+  api_docs_sync:
+    enabled: true
+    consistent: true
+    
+  issues:
+    - severity: "warning"
+      file: "dev-map/backend/api-definition.md"
+      issue: "缺少新增端点 PATCH /api/v1/users/:id/preferences 的文档"
+      suggestion: "请更新 API 定义文档"
+```

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

@@ -0,0 +1,261 @@
+# Java 后端构建技能 (java-build)
+
+> **执行角色**: 开发者 Agent / CI Pipeline
+> **适用项目**: Spring Boot + Maven Java 后端项目
+> **来源**: `files/java-backend-coding-standards/SKILL.md` §15 测试规范
+> **归档日期**: 2026-05-21
+
+---
+
+## 1. 编译构建
+
+### 1.1 Maven 编译
+
+```bash
+# 完整清理编译（清除 target 目录后重新编译）
+mvn clean compile
+
+# 跳过测试编译
+mvn clean compile -DskipTests
+
+# 指定 profile 编译
+mvn clean compile -P prod
+
+# 多模块编译（从根目录）
+mvn clean compile -pl domain -am
+```
+
+**通过标准**:
+- ✅ 零编译错误
+- ✅ 零 deprecated 警告（理想状态）
+- ⚠️ 允许 minor warning 但需说明理由
+
+### 1.2 常见编译问题处理
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+| 找不到符号 | 缺少依赖或 import 错误 | 检查 pom.xml 和 import |
+| 循环依赖 | 模块间相互引用 | 重构消除循环或使用事件解耦 |
+| JDK 版本不匹配 | 项目要求 JDK21，环境为低版本 | 设置 JAVA_HOME 或 maven.compiler |
+| Lombok 注解未生效 | 注解处理器未配置 | 确认 pom.xml 中 lombok 依赖和 annotationProcessorPaths |
+
+---
+
+## 2. 单元测试执行
+
+### 2.1 运行测试
+
+```bash
+# 运行全部单元测试
+mvn test
+
+# 运行指定测试类
+mvn test -Dtest=UserServiceTest
+
+# 运行指定测试方法
+mvn test -Dtest=UserServiceTest#testCreateUser
+
+# 跳过测试（仅打包时使用）
+mvn test -DskipTests
+
+# 并行执行测试（加速）
+mvn test -T 4  # 4 个线程并行
+
+# 失败重跑（CI 环境推荐）
+mvn test -Dsurefire.rerunFailingTestsCount=2
+```
+
+### 2.2 覆盖率收集（JaCoCo）
+
+```bash
+# 执行测试并收集覆盖率
+mvn test jacoco:report
+
+# 查看覆盖率报告
+# 报告位置: {module}/target/site/jacoco/index.html
+
+# 覆盖率阈值检查（不达标则构建失败）
+mvn verify -Djacoco.check.skip=false
+```
+
+**覆盖率目标**:
+
+| 代码类型 | 行覆盖率目标 | 分支覆盖率目标 |
+|---------|------------|--------------|
+| 核心业务逻辑 | ≥ **90%** | ≥ **80%** |
+| 工具函数 | ≥ **85%** | ≥ **75%** |
+| Controller 层 | ≥ **70%** | ≥ **60%** |
+| 配置/常量 | ≥ **50%** | - |
+
+**JaCoCo pom.xml 配置**:
+```xml
+<plugin>
+    <groupId>org.jacoco</groupId>
+    <artifactId>jacoco-maven-plugin</artifactId>
+    <version>0.8.11</version>
+    <executions>
+        <execution>
+            <goals><goal>prepare-agent</goal></goals>
+        </execution>
+        <execution>
+            <id>report</id>
+            <phase>test</phase>
+            <goals><goal>report</goal></goals>
+        </execution>
+        <execution>
+            <id>check</id>
+            <phase>verify</phase>
+            <goals><goal>check</goal></goals>
+            <configuration>
+                <rules>
+                    <rule>
+                        <element>BUNDLE</element>
+                        <limits>
+                            <limit>
+                                <counter>LINE</counter>
+                                <value>COVEREDRATIO</value>
+                                <minimum>0.80</minimum>
+                            </limit>
+                        </limits>
+                    </rule>
+                </rules>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+```
+
+### 2.3 测试框架标准配置
+
+```xml
+<!-- JUnit 5 + Mockito -->
+<dependency>
+    <groupId>org.junit.jupiter</groupId>
+    <artifactId>junit-jupiter</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.mockito</groupId>
+    <artifactId>mockito-core</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-test</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+---
+
+## 3. 打包与部署
+
+### 3.1 Maven 打包
+
+```bash
+# 标准打包（跳过测试）
+mvn package -DskipTests
+
+# 完整打包（含测试）
+mvn package
+
+# 打包并安装到本地仓库
+mvn install -DskipTests
+
+# 排除文档生成加速打包
+mvn package -DskipTests -Dmaven.javadoc.skip=true
+```
+
+### 3.2 Docker 镜像构建
+
+```dockerfile
+# 标准 Dockerfile（多阶段构建）
+# === 阶段 1: 构建 ===
+FROM maven:3.9-eclipse-temurin-21 AS builder
+WORKDIR /app
+COPY pom.xml .
+COPY src ./src
+RUN mvn clean package -DskipTests -o
+
+# === 阶段 2: 运行 ===
+FROM eclipse-temurin:21-jre-alpine
+WORKDIR /app
+COPY --from=builder /app/target/*.jar app.jar
+EXPOSE 8080
+ENV JAVA_OPTS="-Xms256m -Xmx512m"
+ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]
+```
+
+```bash
+# 构建镜像
+docker build -t jscicd-app:latest .
+
+# 推送镜像
+docker push registry.example.com/jscicd-app:latest
+```
+
+---
+
+## 4. 构建失败处理策略
+
+### 4.1 分类处理
+
+| 失败类型 | 原因分析 | 解决步骤 |
+|---------|---------|----------|
+| 编译错误 | 语法错误、类型错误、缺少依赖 | 修复代码 → 重新 `mvn compile` |
+| 测试失败 | 测试用例未通过 | 分析失败原因 → 修复代码或更新测试 → 重新 `mvn test` |
+| 覆盖率不足 | 新代码缺少测试 | 补充测试用例 → 重新验证覆盖率 |
+| Checkstyle/PMD 违规 | 代码风格不符合规范 | 按 IDE 提示修复 → 重新检查 |
+| 依赖解析失败 | 私有库不可用、版本冲突 | 检查网络/仓库配置 → 更新 pom.xml |
+
+### 4.2 快速诊断命令
+
+```bash
+# 查看详细错误信息
+mvn clean compile -e          # 显示完整堆栈
+mvn clean compile -X         # 调试模式（最详细）
+
+# 查看依赖树（排查冲突）
+mvn dependency:tree -Dverbose
+
+# 查找特定依赖来源
+mvn dependency:tree -Dincludes=com.baomidou:mybatis-plus
+
+# 检查过时依赖
+mvn versions:display-dependency-updates
+```
+
+---
+
+## 5. CI/CD 集成示例
+
+```yaml
+# .gitlab-ci.yml 或 GitHub Actions 示例
+stages:
+  - build
+  - test
+  - package
+  - deploy
+
+build-job:
+  stage: build
+  script:
+    - mvn clean compile
+  artifacts:
+    paths:
+      - target/
+
+test-job:
+  stage: test
+  script:
+    - mvn test jacoco:report
+  coverage: '/Total.*?([0-9]{1,3})%/'
+
+package-job:
+  stage: package
+  script:
+    - mvn package -DskipTests
+    - docker build -t $IMAGE_TAG .
+  only:
+    - main
+```