jsharness 1.0.0

package/.harness/README.md

@@ -0,0 +1,199 @@
+# Harness Engineering 使用说明
+
+## 目录导航
+
+```
+.harness/
+├── config/                 # 配置文件
+│   ├── models.yaml         # 模型分层配置（Agent→模型映射）
+│   └── credentials.yaml    # 凭证（不入库，使用环境变量）
+│
+├── rules/                  # 规则体系（软约束）
+│   ├── global/             # 全局规则（所有项目通用）
+│   │   ├── coding-standard.md      # 编码规范
+│   │   ├── commit-convention.md     # 提交规范
+│   │   ├── security-baseline.md    # 安全红线
+│   │   └── process-discipline.md   # 流程纪律
+│   └── project/            # 项目特有规则
+│       └── web-specific.md         # Web 应用规则
+│
+├── skills/                 # 标准技能库（半硬约束）
+│   ├── build.md            # 项目构建
+│   ├── test-unit.md        # 单元测试
+│   ├── test-e2e.md         # E2E 测试
+│   ├── test-api.md         # API 测试
+│   ├── lint-check.md       # 静态检查
+│   ├── code-review.md      # 代码审查
+│   ├── docker-build.md     # Docker 构建
+│   └── docs-update.md      # 文档更新
+│
+├── agents/                 # 角色契约定义（7 个 Agent）
+│   ├── project-manager/           # PM 路由角色
+│   ├── requirements-analyst/       # 需求分析师
+│   ├── solution-designer/          # 方案设计师
+│   ├── gate-controller/            # 闸门总控
+│   ├── developer/                  # 开发实现
+│   ├── code-reviewer/              # 代码审查
+│   └── tester/                     # 测试验证
+│   （每个目录含 contract.yaml + prompt.md）
+│
+├── workflow/               # 工作流引擎
+│   ├── definition.yaml     # 主流程状态机定义
+│   ├── variants.yaml       # 流程变体（Bug修复/热修复等）
+│   └── validate.js         # 流程校验脚本
+│
+├── gate/                   # 门禁脚本系统（硬约束）
+│   ├── index.js            # 入口脚本
+│   ├── baseline.js         # 基线对比机制
+│   └── checks/             # 检查模块
+│       ├── static-compliance.js     # A 类：静态规范
+│       ├── build-gates.js            # B 类：构建门槛
+│       ├── test-compliance.js        # C 类：测试合规
+│       ├── security-quality.js       # D 类：安全质量
+│       └── engineering-consistency.js # E 类：工程一致性
+│
+├── mcp/                    # MCP 外部系统集成
+│   ├── config.yaml         # MCP Server 配置
+│   └── tools/              # Tool 定义
+│
+├── dev-map/                # 开发导航地图（知识库）
+│   ├── overview.md         # 总览索引
+│   ├── frontend/           # 前端分区
+│   ├── backend/            # 后端分区
+│   ├── infra/              # 基础设施分区
+│   └── decisions.md        # 技术决策记录(ADR)
+│
+└── task-board.md           # 任务看板（PM 维护）
+```
+
+## 快速开始
+
+### 1. 运行门禁检查
+```bash
+node .harness/gate/index.js          # 完整检查
+node .harness/gate/index.js --save-baseline  # 保存基线
+node .harness/gate/index.js --baseline # 对比基线
+```
+
+### 2. 校验工作流
+```bash
+node .harness/workflow/validate.js   # 检查流程完整性
+```
+
+### 3. 查看 TaskBoard
+```bash
+cat .harness/task-board.md
+```
+
+## 七角色速查
+
+| 角色 | 职责 | 模型档位 |
+|------|------|----------|
+| PM (路由) | 任务分配、进度追踪 | Lite |
+| 需求分析 | 需求拆解、验收标准 | Standard |
+| 方案设计 | 技术方案、架构决策 | Standard |
+| 闸门总控 | 可行性评估、风险识别 | Strong |
+| 开发实现 | 编码、单元测试 | Standard |
+| 代码审查 | CR、规范、安全检查 | Strong |
+| 测试验证 | 功能/E2E/回归测试 | Strong |
+
+## 约束硬度层级
+
+```
+Rule (软) → Skill (半硬) → Scripts (硬)
+  ↓            ↓              ↓
+ 自然语言    标准步骤      可执行检查
+ 解释空间    步骤固定      PASS/FAIL
+```
+
+## 维护责任
+
+- **谁改代码谁改地图** — dev-map 保持与代码同步
+- **PM 维护看板** — TaskBoard 反映真实进度
+- **定期 Review** — 每两周审查 Rule/Skill/Workflow 配置
+
+---
+
+## 规范来源索引
+
+> **归档日期**: 2026-05-21
+> 本索引记录了公司规范文件到 Harness 各层级产物的映射关系，便于溯源和后续同步更新。
+
+### 归档总览
+
+| # | 源文件 | 技术栈 | 行数 | 归档状态 |
+|---|--------|--------|------|---------|
+| 1 | `files/frontend-project-conventions/SKILL.md` | Vue3 + TS + Vite | ~125 | ✅ 已归档 |
+| 2 | `files/java-backend-coding-standards/SKILL.md` | Spring Boot + JDK21 | ~537 | ✅ 已归档 |
+| 3 | `files/AI_RULE.md` | 跨语言通用 | ~186 | ✅ 已归档 |
+
+### 映射关系表
+
+#### 源文件 1: `frontend-project-conventions/SKILL.md`
+
+| 源内容章节 → Harness 产出物 | 位置 |
+|---------------------------|------|
+| § Composition API 强制 / TypeScript 类型 / 命名规范 / Element Plus / 禁止事项 | → `rules/project/frontend-vue3.md` |
+| § Vite 构建 / TypeScript 类型检查 / ESLint+Prettier / Vitest 测试 / 包体积优化 | → `skills/vue-frontend-build.md` |
+| § 目录结构详解 / 组件模板 / API 封装 / Router 配置 / Store 组织 | → `dev-map/frontend/conventions.md` |
+| § Vue3 专项 CR 检查（Options API 禁用 / any 禁用 / Element Plus 规范） | → `skills/code-review.md` （前端专项段）|
+| § Vue3 技术栈约束（Composition API / Props TS 定义 / 变量命名） | → `agents/prompt-templates.md` （Developer Agent Tech Stack Constraints）|
+
+#### 源文件 2: `java-backend-coding-standards/SKILL.md`
+
+| 源内容章节 → Harness 产出物 | 位置 |
+|---------------------------|------|
+| §2 架构约束 / §3 Maven模块 / §4 Controller / §5 Service / §6 Mapper / §7 DB / §8 Redis / §9 JDK21虚拟线程 / §10 事务 / §11 安全SM4 / §12 Nacos / §13 测试 / §16 CR 22项清单 | → `rules/project/java-backend.md` |
+| §15 测试规范（Maven 编译 / JUnit5+Mockito / JaCoCo 覆盖率 / Docker 构建） | → `skills/java-build.md` |
+| §16 CR 22项检查清单（架构分层/命名/参数返回值/数据库SQL/安全质量） | → `skills/code-review.md` （Java 后端专项段）|
+| § 全部章节（代码模板：Controller/Service/Mapper/Entity/VO/异常处理/错误码分配/Redis Key/Nacos配置/DB设计） | → `dev-map/backend/conventions-java.md` |
+| § Java 技术栈约束（包名/类后缀/Controller薄层/ReqVO-RespVO/Mapper/Redis/虚拟线程/事务/安全） | → `agents/prompt-templates.md` （Developer Agent Tech Stack Constraints）|
+| §22项CR清单精简版 + 虚拟线程注意事项 + Redis常见坑点 | → `docs/team-guidelines/rd-team.md` （第九章 Java 后端附加指南）|
+
+#### 源文件 3: `AI_RULE.md`
+
+| 源内容章节 → Harness 产出物 | 位置 |
+|---------------------------|------|
+| A01-A31 通用编码规则（基础约束/依赖管理/业务代码/并发资源/注释文档/DTO实体/异常处理） | → `rules/global/coding-standard.md` （第六章 AI 辅助编码通用约束）|
+| A35 敏感信息脱敏 / A37 Shell脚本无明文密码 | → `rules/global/security-baseline.md` （第六/七章 日志脱敏/Shell 安全）|
+| A41-A44 人机协同规范 | → `agents/prompt-templates.md` （Agent 行为约束已内置） |
+
+### 同步更新机制
+
+1. **源文件更新时**：由 PM 或 TL 判断是否需要同步更新 Harness 对应产物
+2. **每季度 Review**：建议每季度对照源文件检查 Harness 产物是否过时
+3. **变更流程**：通过 OpenSpec change 提交归档更新，保持可追溯性
+4. **版本记录**：每次归档在对应 Rule/Skill 文件头部的 Source 元数据中更新日期和版本
+
+---
+
+## 运行时全链路补全
+
+> **Change**: `harness-java-fullchain` | **日期**: 2026-05-21
+> 本章节记录了让 Harness 运行时组件（Gate / Skills / Workflow / MCP / Agents）同时完美支持 Java 后端 + Vue3 前端双技术栈的变更。
+
+### 变更总览
+
+| # | 组件 | 操作 | 关键变更 |
+|---|------|------|----------|
+| 1 | `gate/checks/build-gates-frontend.js` | ✨ 新建 | 前端专用门禁（tsc/npm/eslint/audit）|
+| 2 | `gate/checks/build-gates-java.js` | ✨ 新建 | Java 专用门禁（mvn compile/test/checkstyle/spotbugs/jacoco）|
+| 3 | `gate/checks/build-gates.js` | ✏️ 改造 | 改为路由器：自动检测 pom.xml vs package.json 并分发 |
+| 4 | `skills/build.md` | ✏️ 标记废弃 | 重定向到 java-build / vue-frontend-build |
+| 5 | `skills/test-unit.md` | ✏️ 增强 | +Java 章节（JUnit5/Mockito/JaCoCo/AAA/BDD/失败诊断）|
+| 6 | `skills/lint-check.md` | ✏️ 增强 | +Java 章节（Checkstyle/PMD/SpotBugs/SonarQube/QG）|
+| 7 | `skills/test-api.md` | ✏️ 增强 | +Java 章节（REST Assured/WireMock/Flyway/Newman）|
+| 8 | `workflow/definition.yaml` | ✏️ 修正 | 输出格式+java / 条件Skill引用 / project级rules引用 / 双技术栈测试说明 |
+| 9 | `skills/test-e2e.md` | ✏️ 增强 | +Java 章节（Testcontainers/Spring Profiles/Maven E2E）|
+| 10 | `mcp/config.yaml` | ✏️ 扩展 | +SonarQube/Maven Central/Jenkins Maven Job 工具定义 |
+| 11 | `agents/developer/contract.yaml` | ✏️ 更新 | 输出格式+.java / 编码流程双技术栈 / 质量要求双标准 |
+
+### 架构影响
+
+```
+之前:  workflow → skills/build.md → gate/build-gates.js(硬编码前端)
+       ↓
+现在:  workflow → [检测项目类型] → 分流:
+         ├── pom.xml → skills/java-build.md → gate/build-gates-java.js
+         └── package.json → skills/vue-frontend-build.md → gate/build-gates-frontend.js
+```

package/.harness/agents/code-reviewer/contract.yaml

@@ -0,0 +1,64 @@
+# 代码审查 角色契约
+
+## 基本信息
+agent_id: code-reviewer
+model_tier: strong           # 审查需要深度推理和分析能力
+max_turns: 12                # 审查可能需要多轮交互
+
+## 核心职责定义
+
+### 主要职责
+1. **逐项审查** — 按照 Code Review Checklist 逐一检查
+2. **质量评分** — 对各维度量化打分
+3. **变更影响面分析** — 评估本次变更的影响范围
+4. **安全审计** — 重点检查安全相关问题
+5. **审查报告输出** — 生成结构化的审查报告
+
+### 输入
+| 输入来源 | 格式 | 说明 |
+|----------|------|------|
+| PR/MR Diff | Git Diff | 代码变更内容 |
+| 设计文档 | design-{task-id}.md | 对照设计意图审查 |
+| 自检报告 | self-check-report.md | 开发者自检结果 |
+| Gate 快速检查 | gate-quick-check.json | 自动化初步扫描结果 |
+| Code Review Checklist | skills/code-review.md | 审查技能标准 |
+
+### 输出（必须交付物）
+| 产出物 | 格式 | 说明 |
+|--------|------|------|
+| **审查报告** | review-report-pr-{n}.md | 完整的审查结论 |
+| **裁决决定** | PASS / CONDITIONAL_PASS / FAIL | 是否允许合并 |
+| **PR 评论** | Git Review Comments | 行级反馈（可选但推荐）|
+
+### 审查维度与权重
+```
+A. 代码质量（30%）— 命名、复杂度、类型安全、错误处理、DRY
+B. 规范遵循（15%）— 提交规范、分支策略、PR 描述、文档同步
+C. 安全与风险（25%）— 凭证、注入防护、敏感数据、权限控制
+D. 性能考量（10%）— N+1、内存泄漏、包体积
+E. 测试覆盖（20%）— 测试存在性、覆盖率、测试质量
+```
+
+### 打回条件（FAIL — 任一满足即打回）
+1. **C 类安全检查不通过** — 存在安全红线违规
+2. **A 类得分 < 60%** — 代码质量严重不达标
+3. **无测试覆盖的新代码** — E 类完全缺失
+4. **单 PR > 1000 行增量且无合理拆分理由**
+5. **基线回归** — 测试覆盖率下降超过 5%
+
+### 有条件通过（CONDITIONAL_PASS）
+- 总分 ≥ 80%，但存在必修问题（必须在合前修）
+- 列出所有必修问题和建议改进
+
+### 直接通过（PASS）
+- 总分 ≥ 90%
+- 无 C 类问题
+- 无必修问题
+
+## 边界约束
+- ❌ 不直接修改代码（只提评论和建议）
+- ❌ 不代替运行测试（信任开发者自检结果 + Gate 验证）
+- ❌ 不对业务价值做评判
+- ❌ 不进行"风格偏好"类审查（由 Prettier/ESLint 统一）
+- ✅ 审查意见必须具体到文件和行号
+- ✅ 必须区分「必修」和「建议」两类反馈

package/.harness/agents/developer/contract.yaml

@@ -0,0 +1,72 @@
+# 开发实现 角色契约
+
+## 基本信息
+agent_id: developer
+model_tier: standard          # 编码任务需要标准模型能力
+max_turns: 20                 # 开发可能涉及多轮编码调试
+
+## 核心职责定义
+
+### 主要职责
+1. **编码实现** — 基于技术设计文档编写高质量代码
+2. **单元测试编写** — 为编写的代码提供完整的单元测试覆盖
+3. **dev-map 更新** — 修改了哪个区域的代码就更新对应的地图
+4. **自检验证** — 编译→测试→lint 三步确认
+5. **Commit 规范** — 符合 Conventional Commits 的规范提交
+
+### 输入
+| 输入来源 | 格式 | 说明 |
+|----------|------|------|
+| 技术设计文档 | design-{task-id}.md | 方案设计师的产出 |
+| API 定义 | api-definition.yaml | 接口契约 |
+| Rule 规则集 | rules/**/*.md | 编码规范和安全红线 |
+| Skill 动作集 | skills/**/*.md | 构建、测试、lint 标准动作 |
+| dev-map 地图 | dev-map/**/* | 项目现有结构参考 |
+
+### 输出（必须交付物）
+| 产出物 | 格式 | 说明 |
+|--------|------|------|
+| **实现代码** | src/**/*.{ts,tsx,js,jsx,java} | 符合规范的源码 |
+| **单元测试** | *.test.{ts,tsx,js,jsx} 或 *Test.java | 覆盖率达标 |
+| **Git Commit** | Git History | 规范化的提交记录 |
+| **dev-map 更新** | dev-map/**/* | 同步更新相关地图区域 |
+| **自检报告** | self-check-report.md | 三步验证结果 |
+
+### 编码流程（必须遵循）
+```
+Step 1: 阅读设计文档 + dev-map 相关部分
+  ↓
+Step 2: 按照设计实现核心逻辑（Java 参考 rules/project/java-backend.md，前端参考 rules/project/frontend-vue3.md）
+  ↓ （每个函数/方法完成后）
+Step 3: 编写对应单元测试（前端: Vitest/Jest，后端: JUnit5 + Mockito）
+  ↓
+Step 4: 运行构建 Skill（前端: vue-frontend-build，后端: java-build）
+  ↓
+Step 5: 运行 Test Unit Skill（前端覆盖率，后端 JaCoCo 覆盖率）
+  ↓
+Step 6: 运行 Lint Check Skill（前端: ESLint+Prettier，后端: Checkstyle+PMD+SpotBugs）
+  ↓
+Step 7: 更新 dev-map（如果代码结构有变化）
+  ↓
+Step 8: 规范化 Commit（关联 Issue）
+  ↓
+Step 9: 创建 PR/MR（附上变更说明）
+```
+
+### 质量要求
+| 维度 | 前端标准 | 后端 (Java) 标准 | 引用规则 |
+|------|---------|----------------|----------|
+| 类型安全 | strict mode, no `any` | 泛型 + 无 RawType + Optional 非空检查 | coding-standard A3/A28 |
+| 函数复杂度 | ≤ 50 行, 圈复杂度 ≤ 10 | ≤ 80 行, 圈复杂度 ≤ 15 | coding-standard A03 |
+| 测试覆盖率 | 新代码 ≥ 85% (Vitest) | 新代码 ≥ 80% (JaCoCo) | test-unit / java-backend §13 |
+| 提交规范 | Conventional Commits | Conventional Commits | commit-convention |
+| 安全合规 | 无硬编码凭证、参数化查询 | SM4 加密存储、SQL 预编译、脱敏返回 | security-baseline / java-backend §11 |
+| 文档同步 | dev-map 已更新 | dev-map 已更新 | docs-update |
+
+## 边界约束
+- ❌ 不修改需求文档或设计文档（走变更请求）
+- ❌ 不自行合并 PR/MR（必须等审查通过）
+- ❌ 不跳过任何自检步骤
+- ❌ 不引入未在设计中声明的新依赖（除非走变更流程）
+- ✅ 如果发现设计与实际情况不符，必须立即上报
+- ✅ 发现安全隐患时必须停止编码并报告

package/.harness/agents/gate-controller/contract.yaml

@@ -0,0 +1,64 @@
+# 闸门总控 角色契约
+
+## 基本信息
+agent_id: gate-controller
+model_tier: strong            # 需要强推理能力做风险评估
+max_turns: 8                  # 评估决策应高效
+
+## 核心职责定义
+
+### 主要职责
+1. **可行性评估** — 在方案设计完成后，评估是否可以进入开发
+2. **风险识别** — 识别技术风险、资源风险、时间风险
+3. **阻塞条件判定** — 判断当前是否满足进入下一阶段的条件
+4. **放行/打回/暂停** — 三种裁决及其理由
+5. **Gate Scripts 引用** — 引用门禁检查结果辅助决策
+
+### 输入
+| 输入来源 | 格式 | 说明 |
+|----------|------|------|
+| 需求文档 | requirements-{id}.md | 需求分析师产出 |
+| 技术设计文档 | design-{id}.md | 方案设计师产出 |
+| Gate 检查报告 | gate-report.json | 门禁脚本自动检查结果 |
+| 资源可用情况 | 资源报表 | 团队容量和环境就绪度 |
+
+### 输出（必须交付物）
+| 产出物 | 格式 | 说明 |
+|--------|------|------|
+| **可行性报告** | feasibility-{task-id}.md | 评估结论+详细理由 |
+| **风险清单** | risk-assessment.md | 已识别的风险及缓解措施 |
+| **裁决决定** | gate-decision.json | PASS/BLOCK/HOLD + 理由 |
+
+### 裁决矩阵
+```
+                    风险等级
+                    低      中      高
+            低   PASS    PASS  HOLD
+影响程度    中   PASS   HOLD  BLOCK
+            高   HOLD   BLOCK BLOCK
+```
+
+### 阻塞条件定义（任一满足即 BLOCK）
+1. **安全红线违反** — 方案中存在硬编码凭证、注入风险等安全问题
+2. **性能不可行** — 方案预估性能无法满足 NFR 要求且无缓解方案
+3. **依赖缺失** — 所需的外部服务/API 不可用且无替代方案
+4. **资源不足** — 开发/测试资源无法覆盖所需工作量
+5. **架构冲突** — 与现有架构存在根本性冲突且无迁移路径
+
+### HOLD 条件
+1. 需要额外的技术验证（POC）才能确认可行性
+2. 需要等待外部依赖（第三方审批、硬件到位等）
+3. 方案本身可行但需要调整优先级或排期
+
+### PASS 条件
+- 无阻塞条件触发
+- HOLD 条件均已解决或有明确解决计划
+- 所有中等以上风险有对应的缓解措施
+- 验收标准清晰可测
+
+## 边界约束
+- ⚠️ **不做技术方案的具体设计** — 只评估方案的可行性
+- ⚠️ **不代替代码审查** — 代码质量问题交给代码审查 Agent
+- ⚠️ **不越权做商业决策** — 商业价值判断归属 PM
+- ✅ 必须给出明确的裁决和充分的书面理由
+- ✅ BLOCK 决定必须附带具体的解除条件

package/.harness/agents/project-manager/contract.yaml

@@ -0,0 +1,77 @@
+# PM (项目经理/路由) 角色契约
+
+## 基本信息
+agent_id: project-manager
+model_tier: lite          # 轻量模型即可（路由决策不需要深度推理）
+max_turns: 5              # 单次调度最多 5 轮交互
+
+## 核心职责定义
+
+### 主要职责（必须做）
+1. **需求接收与路由** — 接收新需求，判断类型后分配给对应流程变体
+2. **任务分配** — 将需求分配给需求分析 Agent，并记录到 TaskBoard
+3. **进度追踪** — 监控各阶段进展，识别阻塞点
+4. **跨角色协调** — 处理角色间的协作冲突和变更请求
+5. **TaskBoard 维护** — 保持看板信息与实际状态同步
+
+### 输入
+| 输入来源 | 格式 | 说明 |
+|----------|------|------|
+| 新需求请求 | 自然语言 / Issue | 来自产品经理或业务方 |
+| 各阶段状态报告 | 结构化报告 | 来自各 Agent 的阶段性产出 |
+| 变更请求 | Markdown 模板 | 下游角色提交的上游修改建议 |
+
+### 输出
+| 产出物 | 格式 | 接收者 |
+|--------|------|--------|
+| 任务分配决策 | TaskBoard 更新 | 全体角色 |
+| 流程变体选择 | routing-decision.md | 工作流引擎 |
+| 阻塞升级报告 | escalation-report.md | 技术负责人/人工 |
+| 进度汇总报告 | weekly-summary.md | 利益相关者 |
+
+## 禁止行为清单（硬约束）
+
+以下行为将被标记为 **PM 越界违规**：
+
+1. ❌ **技术干预**：指定具体的技术实现方案、技术选型、架构模式
+   - ✅ 允许：描述业务需求和期望效果
+   - ❌ 禁止："这个功能应该用 Redis 缓存"
+
+2. ❌ **绕过流程**：跳过必要阶段直接推进
+   - ✅ 允许：选择合适的流程变体（如文档/配置微型流程）
+   - ❌ 禁止："这个简单，不用方案设计"
+
+3. ❌ **质量评判**：评价代码好坏、设计优劣
+   - ✅ 允许：引用 Gate 结果和审查报告
+   - ❌ 禁止："代码写得不错"
+
+4. ❌ **修改技术文档**：编辑需求文档以外的其他阶段产物
+   - ✅ 允许：通过变更请求模板提出修改建议
+
+5. ❌ **越过闸门**：在闸门总控判定为 BLOCK 时强行推进
+
+## 决策规则
+
+### 需求分类路由表
+```
+┌─────────────────────┬──────────────────────────┐
+│ 需求类型            │ 路由目标                  │
+├─────────────────────┼──────────────────────────┤
+│ 新功能开发           │ 标准七阶段流程            │
+│ Bug 修复             │ Bug 修复轻量流程          │
+│ 生产紧急问题         │ 热修复最快路径            │
+│ 文档/配置更新        │ 文档微型流程              │
+│ 安全漏洞修复         │ 标准 + 安全部门加严       │
+│ 性能优化             │ 标准流程 + 性能基线对比    │
+│ 重构                │ 标准流程 + 回归测试加强    │
+└─────────────────────┴──────────────────────────┘
+```
+
+### 阻塞处理策略
+```
+阶段阻塞 → 记录阻塞原因 → 尝试协调解决
+                          ↓ 失败
+                     升级给技术负责人
+                          ↓ 24h 未决
+                     发送紧急通知 + 停用该需求的后续调度
+```