jsharness 1.6.0 → 1.8.0

package/.harness/commands/js/build-gates.md

@@ -0,0 +1,32 @@
+---
+name: build-gates
+description: 构建门槛检查 — 自动检测项目类型并分发到对应的门禁检查模块
+---
+
+# 构建门槛检查 (Build Gates)
+
+> **源文件**: `.harness/gate/checks/build-gates.js`
+> **类别**: B 类 — 构建门槛
+
+自动检测项目类型并分发到对应的门禁检查模块：
+- 检测到 `pom.xml` → 调用 build-gates-java.js (Maven/Java)
+- 检测到 `package.json` → 调用 build-gates-frontend.js (Node/前端)
+- 都没有 → 返回 warning
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| B1 | 项目类型检测 | 检测 pom.xml / package.json 确定项目类型 |
+| B2 | 前端构建 | TypeScript 类型检查 + 依赖完整性 + npm run build + ESLint |
+| B3 | Java 构建 | Maven 编译 + 单元测试 + Checkstyle + 依赖树分析 |
+
+## 通过条件
+
+- 项目类型检测成功（Java 或 Frontend）
+- 对应子模块的构建检查全部 PASS
+
+## 失败条件
+
+- 无法检测项目类型 → WARNING
+- 子模块构建失败 → FAIL

package/.harness/commands/js/engineering-consistency.md

@@ -0,0 +1,29 @@
+---
+name: engineering-consistency
+description: 工程一致性检查 — CHANGELOG 更新、dev-map 一致性、配置同步
+---
+
+# 工程一致性检查 (Engineering Consistency)
+
+> **源文件**: `.harness/gate/checks/engineering-consistency.js`
+> **类别**: E 类 — 工程一致性
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| E1 | CHANGELOG 更新检查 | 检查 Unreleased 区域是否有内容 |
+| E2 | dev-map 一致性检查 | 检查 dev-map 与实际代码是否一致 |
+| E3 | 配置同步检查 | 检查各配置文件是否同步 |
+
+## 通过条件
+
+- CHANGELOG Unreleased 区域有内容
+- dev-map 与代码一致
+- 配置文件同步
+
+## 失败条件
+
+- CHANGELOG 未更新 → WARNING
+- dev-map 不一致 → WARNING
+- 配置不同步 → WARNING

package/.harness/commands/js/security-quality.md

@@ -0,0 +1,27 @@
+---
+name: security-quality
+description: 安全与质量检查 — CVE 依赖审计、Code Review Approval 状态
+---
+
+# 安全与质量检查 (Security & Quality)
+
+> **源文件**: `.harness/gate/checks/security-quality.js`
+> **类别**: D 类 — 安全与质量
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| D1 | npm audit 安全审计 | 检测 CVE 漏洞（HIGH/CRITICAL 级别） |
+| D2 | Code Review Approval | 检查代码审查状态（通过 Git 信息判断） |
+
+## 通过条件
+
+- 安全评分 ≥ 80 分
+- 无 CRITICAL 级别 CVE 漏洞
+- HIGH 级别漏洞有修复计划
+
+## 失败条件
+
+- 存在 CRITICAL 级别漏洞 → FAIL
+- 安全评分 < 60 分 → FAIL

package/.harness/commands/js/static-compliance.md

@@ -0,0 +1,35 @@
+---
+name: static-compliance
+description: 静态合规检查 — ESLint、Prettier、console.log 残留、硬编码字符串、Secret 泄露检测
+---
+
+# 静态合规检查 (Static Compliance)
+
+> **源文件**: `.harness/gate/checks/static-compliance.js`
+> **类别**: A 类 — 静态合规
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| A1 | ESLint 检查 | 零 error，零 warning |
+| A2 | Prettier 格式化 | 格式化后无 diff 变更 |
+| A3 | console.log / debugger 残留 | 禁止残留到生产代码 |
+| A4 | 硬编码字符串检测 | 检测未国际化的中文字符串 |
+| A5 | TODO/FIXME 残留 | 检测遗留的 TODO/FIXME |
+| A6 | 命名规范检查 | 检查文件名/变量名是否符合规范 |
+| A7 | 文件长度限制 | 单文件不超过 300 行 |
+| A8 | Secret 泄露检测 | 检测硬编码的密钥/Token/密码 |
+
+## 通过条件
+
+- ESLint 零错误
+- Prettier 格式一致
+- 无 console.log / debugger 残留
+- 无 Secret 泄露
+
+## 失败条件
+
+- ESLint 存在 error → FAIL
+- Secret 泄露检测命中 → FAIL（安全红线）
+- console.log / debugger 残留 → FAIL

package/.harness/commands/js/task-board-maintenance.md

@@ -0,0 +1,68 @@
+---
+name: task-board-maintenance
+description: TaskBoard 维护命令 — 任务注册/状态流转/周报生成/看板同步
+alwaysApply: false
+enabled: true
+---
+
+# TaskBoard 维护 Command
+
+> **执行角色**: PM Agent / 工作流引擎
+> **触发时机**: 任务状态变更时、每日定时、周报生成前
+> **源文件**: `.harness/skills/task-board-maintenance/SKILL.md` (已迁移为 command)
+
+---
+
+## 操作清单
+
+### 1. 新任务注册
+
+当 PM 收到新需求时：
+
+- 分配 Task ID（格式：TASK-YYYYMMDD-NNN）
+- 判断流程变体类型：
+  - 新功能 → 标准七阶段流程
+  - Bug 修复 → Bug 修复轻量流程
+  - P0/P1 生产问题 → 热修最快路径
+  - 文档/配置变更 → 微型流程
+  - 安全漏洞 → 安全响应流程
+- 在「待开始任务」表添加一行
+- 检查是否与历史任务重复
+- 如有关联的 Issue/PR，填入对应编号
+- 更新「新增需求」计数器
+
+### 2. 状态推进
+
+当一个阶段完成，需要推入下一阶段：
+
+- 从当前区域移动目标任务到下一区域
+- 更新「当前阶段」字段
+- 更新「负责Agent」字段为下一个角色
+- 更新「上次更新」为当前时间
+- 在备注中记录简要原因
+- 如果是打回，在「备注」中注明打回原因和来源角色
+
+### 3. 交付归档
+
+测试 PASS 后：
+
+- 移动到「已完成」区域
+- 填写「交付结论」（PASS / CONDITIONAL_PASS）
+- 计算「实际周期」
+- 填写「归档日期」
+- 收集各阶段文档链接
+- 更新度量指标
+
+### 4. 定期维护
+
+**每日检查**（PM Agent 自动执行）：
+- 检查是否有超时未更新的任务（超过 48 小时）
+- 检查是否有阻塞超过 24 小时的任务
+- 更新「最后更新」时间戳
+
+**每周清理**（PM Agent 手动执行）：
+- 清理已取消或合并的重复条目
+- 确认已完成任务都已正确归档
+- 生成周度度量报告
+- 识别瓶颈阶段
+- 汇总流程违规情况并提出改进建议

package/.harness/commands/js/test-compliance.md

@@ -0,0 +1,30 @@
+---
+name: test-compliance
+description: 测试合规检查 — 单元测试执行与覆盖率、E2E 测试、API 集成测试
+---
+
+# 测试合规检查 (Test Compliance)
+
+> **源文件**: `.harness/gate/checks/test-compliance.js`
+> **类别**: C 类 — 测试合规
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| C1 | 单元测试 | `npm run test -- --coverage` |
+| C2 | E2E 关键路径测试 | 可选 |
+| C3 | API 集成测试 | 可选 |
+| C4 | 测试数量对比 | 基线模式，检测测试是否减少 |
+
+## 通过条件
+
+- 单元测试全部 PASS
+- 覆盖率不低于基线
+- 测试数量未减少
+
+## 失败条件
+
+- 单元测试失败 → FAIL
+- 覆盖率低于基线 → WARNING
+- 测试数量减少 → WARNING

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

@@ -1,11 +1,15 @@
 ---
 name: task-board-maintenance
-description: TaskBoard 维护技能 — 任务注册/状态流转/周报生成/看板同步，PM Agent 专属操作清单
+description: ⚠️ DEPRECATED — 已迁移为 command，请使用 .harness/commands/task-board-maintenance/COMMAND.md
 alwaysApply: false
-enabled: true
+enabled: false
 ---
 
-# TaskBoard 维护 Skill
+> **⚠️ DEPRECATED**: 此 Skill 已迁移为 Command。
+> 新位置: `.harness/commands/task-board-maintenance/COMMAND.md`
+> 迁移日期: 2026-05-21
+
+# TaskBoard 维护 Skill (已废弃)
 
 > **执行角色**: PM Agent / 工作流引擎
 > **触发时机**: 任务状态变更时、每日定时、周报生成前

package/bin/jsharness.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * jsharness CLI
@@ -8,7 +8,9 @@
  *   npx jsharness init --tool codebuddy       # 指定工具（跳过工具选择）
  *   npx jsharness init --stack vue3           # 指定技术栈（跳过技术栈选择）
  *   npx jsharness init --tool cursor --stack all  # 全部指定，无交互
- *   npx jsharness init --tool augment     # 指定 Augment Code
+ *   npx jsharness init --tool augment         # 指定 Augment Code
+ *   npx jsharness init --commands-only        # 只注入命令桶
+ *   npx jsharness init --subagents-only       # 只注入角色桶
  *   npx jsharness list-tools                  # 列出支持的工具
  *   npx jsharness status                      # 查看当前状态
  *   npx jsharness openspec list               # 列出 OpenSpec 变更
@@ -45,11 +47,13 @@ program
 
 program
   .command('init')
-  .description('初始化 Harness 到当前项目的 AI 工具中')
+  .description('初始化 Harness 到当前项目的 AI 工具中（四桶: Rules/Skills/Commands/Agents）')
   .option('-t, --tool <name>', '指定目标 AI 工具（跳过交互选择）')
   .option('-s, --stack <name>', '指定技术栈 vue3/java/all（跳过交互选择）')
-  .option('--rules-only', '只注入规则，不注入技能')
-  .option('--skills-only', '只注入技能，不注入规则')
+  .option('--rules-only', '只注入规则桶')
+  .option('--skills-only', '只注入技能桶')
+  .option('--commands-only', '只注入命令桶')
+  .option('--subagents-only', '只注入角色桶')
   .option('--force', '覆盖已有配置')
   .option('-v, --verbose', '显示详细输出')
   .action((opts) => runInit(process.cwd(), opts));

package/files/AI_RULE.md

@@ -0,0 +1,185 @@
+# AI 代码生成规范 (Rule)
+
+## 一、AI 生成基础约束
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A01** | AI 生成代码必须贴合项目 JDK 版本、SpringBoot/SpringCloud 指定版本，禁止自动引入高版本依赖 |
+| **Rule-A02** | AI 补全优先沿用项目现有变量名、方法名、命名风格，禁止擅自修改业务标识符 |
+| **Rule-A03** | AI 单次生成代码块长度控制在 80 行内，超长逻辑强制拆分方法 / 工具类 |
+| **Rule-A04** | 禁止 AI 自动生成 shturl.cc/、shturl.cc/anUsxIa 调试代码，统一使用项目日志框架 |
+| **Rule-A05** | AI 生成代码必须匹配项目缩进、空格、换行格式，统一 4 空格缩进，禁用 Tab |
+| **Rule-A06** | AI 禁止默认省略异常捕获、参数校验，业务接口强制生成入参非空与合法性校验 |
+
+---
+
+## 二、依赖与引入规范
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A07** | AI 引入第三方组件 / 工具类，优先使用项目已引入依赖，禁止随意新增陌生 Maven 依赖 |
+| **Rule-A08** | AI 生成工具方法优先复用项目 Common 工具类，禁止重复编写通用工具逻辑 |
+| **Rule-A09** | AI 导入包遵循项目包导入排序规则，禁止杂乱导入、全量通配导入 |
+| **Rule-A10** | AI 禁止自动引入废弃 API、过期类、已下线框架接口 |
+
+---
+
+## 三、业务代码生成
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A11** | AI 写 Controller 层只做参数接收、参数校验、结果封装，禁止编写业务逻辑 |
+| **Rule-A12** | AI 写 Service 层专注业务逻辑编排，DAO / 数据查询下沉至 Mapper/Repository |
+| **Rule-A13** | AI 生成数据库操作，强制使用 #{} 预编译，禁止直接拼接 SQL，杜绝注入风险 |
+| **Rule-A14** | AI 生成集合逻辑，默认指定集合初始化容量，优先使用 isEmpty 判空 |
+| **Rule-A15** | AI 循环逻辑禁止在循环内 new 对象、频繁创建连接，统一外部初始化 |
+| **Rule-A16** | AI 生成枚举类禁止使用 ordinal 取值，强制自定义 code 与 desc 字段 |
+
+---
+
+## 四、并发 & 线程 & 资源
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A17** | AI 创建线程一律使用线程池，禁止直接 new Thread、Executors 快捷创建线程池 |
+| **Rule-A18** | AI 涉及 IO 流、数据库连接、Redis 连接，强制生成 try-with-resources 自动关闭 |
+| **Rule-A19** | AI 使用 ThreadLocal 必须配套生成 remove 清理逻辑，规避内存泄漏 |
+| **Rule-A20** | AI 高并发逻辑禁止滥用 synchronized，优先推荐分布式锁 + JUC 并发工具 |
+
+---
+
+## 五、注释 & 文档
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A21** | AI 生成公共类、对外接口、核心业务方法自动补全标准 JavaDoc 注释 |
+| **Rule-A22** | AI 复杂逻辑仅写关键逻辑注释，禁止堆砌无意义冗余注释 |
+| **Rule-A23** | AI 生成 TODO 标记必须附带业务场景，禁止空 TODO 占位 |
+| **Rule-A24** | AI 重构代码时同步更新旧注释，保证注释与代码逻辑一致 |
+
+---
+
+## 六、接口 & DTO & 实体
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A25** | AI 生成 POJO/DTO 所有属性私有，自动生成标准 get/set，禁止手写冗余方法 |
+| **Rule-A26** | AI 生成接口返回值统一使用项目统一 Result 封装体，禁止直接返回原始数据 |
+| **Rule-A27** | AI 分页查询强制生成分页参数、分页返回结构体，禁止手写零散分页逻辑 |
+| **Rule-A28** | AI 时间字段统一使用 LocalDateTime/LocalDate，禁止默认使用 Date |
+
+---
+
+## 七、异常处理
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A29** | AI 捕获异常精准捕获业务异常，禁止一刀切捕获 Exception 顶级异常 |
+| **Rule-A30** | AI 异常处理必须打印上下文参数日志，禁止空 catch 空逻辑 |
+| **Rule-A31** | AI 抛异常优先使用项目自定义业务异常，禁止直接抛出原生 RuntimeException |
+
+---
+
+## 八、AI 重构 & 优化
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A32** | AI 代码重构不改动原有业务流程、接口出入参，只优化结构与性能 |
+| **Rule-A33** | AI 精简代码禁止删除原有业务分支、兜底逻辑，优先剔除冗余重复代码 |
+| **Rule-A34** | AI 性能优化优先优化循环、SQL 查询、频繁 IO，不擅自修改业务算法 |
+| **Rule-A35** | AI 代码脱敏自动屏蔽手机号、身份证、密钥等敏感字段输出 |
+
+---
+
+## 九、前端 / 脚本 / 通用
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A36** | AI 前端代码遵循项目 ESLint 规范，统一代码格式与变量命名 |
+| **Rule-A37** | AI Shell / 运维脚本禁止明文写入账号密码、服务器密钥 |
+| **Rule-A38** | AI 单元测试代码只写核心业务用例，覆盖正常 / 异常 / 边界场景 |
+| **Rule-A39** | AI 生成配置文件遵循项目 Nacos/yml/properties 统一格式规范 |
+| **Rule-A40** | AI 生成测试环境代码禁止携带线上硬编码地址、账号配置 |
+
+---
+
+## 十、AI 人机协同开发
+
+| 编号 | 规则描述 |
+|------|----------|
+| **Rule-A41** | AI 仅负责代码编写、补全、重构、查错，业务逻辑决策由开发人员确认 |
+| **Rule-A42** | AI 生成代码必须人工评审后提交，禁止直接一键提交 AI 产出代码 |
+| **Rule-A43** | 遇到 AI 错误逻辑、过时写法，统一录入规则库，统一纠正 AI 输出习惯 |
+| **Rule-A44** | 团队统一 AI 提示词模板，全员使用同款约束指令，保证 AI 输出风格统一 |
+
+---
+
+## 快速参考
+
+### 核心原则
+
+```
+1. 禁止擅自修改 - 沿用项目现有风格
+2. 控制代码长度 - 单次生成不超过 80 行
+3. 异常必须捕获 - 禁止空 catch 或顶层异常
+4. 复用优于新建 - 优先使用项目已有工具类
+5. 安全第一 - SQL 预编译、敏感信息脱敏
+6. 人工审核 - AI 代码必须评审后才能提交
+```
+
+### 常用代码模板
+
+#### Controller 层
+```java
+@RestController
+@RequiredArgsConstructor
+public class DemoController {
+
+    /**
+     * 示例接口
+     * @param request 请求参数
+     * @return 统一返回结果
+     */
+    @PostMapping("/demo")
+    public Result<DemoResponse> demo(@Valid @RequestBody DemoRequest request) {
+        // 仅参数校验和结果封装
+        return Result.success(demoService.process(request));
+    }
+}
+```
+
+#### Service 层
+```java
+@Service
+@RequiredArgsConstructor
+public class DemoService {
+
+    private final DemoMapper demoMapper;
+
+    /**
+     * 业务逻辑处理
+     */
+    public DemoResponse process(DemoRequest request) {
+        // 业务逻辑编排
+        // DAO 下沉至 Mapper
+    }
+}
+```
+
+#### 异常处理
+```java
+try {
+    // 业务逻辑
+} catch (BusinessException e) {
+    log.error("业务异常: userId={}, orderId={}", userId, orderId, e);
+    throw e;
+} catch (Exception e) {
+    log.error("系统异常: userId={}, orderId={}", userId, orderId, e);
+    throw new SystemException("系统错误");
+}
+```
+
+---
+
+*文档版本: v1.0*
+*最后更新: 2026-05-19*