jsharness 1.0.0

package/.harness/mcp/config.yaml

@@ -0,0 +1,435 @@
+# MCP 外部系统集成配置
+
+> **当前阶段**: 阶段一（只读集成）— 基础框架已搭建
+> **安全级别**: 高 — 涉及外部系统访问，需严格控制权限
+
+---
+
+## MCP Server 配置
+
+```yaml
+# .harness/mcp/config.yaml
+mcp_server:
+  name: "harness-mcp-bridge"
+  version: "1.0.0"
+  
+  # 连接的外部系统
+  systems:
+    gitlab:
+      type: "gitlab_api"
+      base_url: "${GITLAB_URL}"          # 环境变量注入
+      token_ref: "GITLAB_ACCESS_TOKEN"   # 不硬编码凭证
+      enabled: true
+      
+    jenkins:
+      type: "jenkins_api"
+      base_url: "${JENKINS_URL}"
+      credentials_ref: "JENKINS_API_TOKEN"
+      user_ref: "JENKINS_USER"
+      enabled: true
+      
+    docker_registry:
+      type: "docker_registry_api"
+      registry_url: "${DOCKER_REGISTRY_URL}"
+      credentials_ref: "DOCKER_REGISTRY_TOKEN"
+      enabled: false                    # 阶段二才启用
+
+  # 安全设置
+  security:
+    rate_limit:
+      requests_per_minute: 30
+      burst: 10
+    audit_logging: true                 # 记录所有 MCP 操作
+    allowed_operations:                # 阶段一限制为只读
+      - "git:*"                         # Git 操作（阶段二细分）
+      - "ci:status:read"               # CI 状态读取
+      - "issue:list"                   # Issue 列表读取
+```
+
+## 阶段一：只读集成 Tools 定义
+
+### Git 只读 Tools
+
+```typescript
+// mcp/tools/git-read.js
+
+/**
+ * Tool: git_status
+ * 获取仓库当前状态（分支、修改的文件等）
+ */
+{
+  name: "git_status",
+  description: "获取当前 Git 仓库的状态信息",
+  parameters: {
+    path: { type: "string", description: "仓库路径", default: "." }
+  },
+  readOnly: true,
+  handler: async ({ path }) => {
+    return {
+      branch: execSync(`git -C ${path} rev-parse --abbrev-ref HEAD`).toString().trim(),
+      changedFiles: JSON.parse(execSync(`git -C ${path} status --porcelain=json`).toString()),
+      lastCommit: execSync(`git -C ${path} log -1 --format="%H|%s|%an|%ai"`).toString().trim()
+    };
+  }
+}
+
+/**
+ * Tool: git_diff
+ * 获取指定范围或文件的 diff 内容
+ */
+{
+  name: "git_diff",
+  description: "查看代码变更的差异内容",
+  parameters: {
+    ref: { type: "string", description: "Git 引用 (commit/branch)" },
+    filePattern: { type: "string", description: "文件模式过滤", optional: true }
+  },
+  readOnly: true
+}
+
+/**
+ * Tool: git_pr_read
+ * 读取 PR/MR 的详细信息（不创建或修改）
+ */
+{
+  name: "git_pr_read",
+  description: "读取 Pull Request / Merge Request 的详细信息",
+  parameters: {
+    prNumber: { type: "number", description: "PR 编号" },
+    includeDiffs: { type: "boolean", description: "是否包含 diff", optional: true }
+  },
+  readOnly: true
+}
+```
+
+### CI 只读 Tools
+
+```javascript
+// mcp/tools/ci-read.js
+
+/**
+ * Tool: ci_build_status
+ * 查询 CI 构建状态
+ */
+{
+  name: "ci_build_status",
+  description: "查询 Jenkins/GitLab CI 的构建状态和结果",
+  parameters: {
+    jobName: { type: "string", description: "构建任务名称" },
+    buildNumber: { type: "number", description: "构建编号（可选，默认最新）" }
+  },
+  readOnly: true,
+  handler: async ({ jobName, buildNumber }) => {
+    const url = `${jenkinsUrl}/job/${jobName}/${buildNumber || 'lastBuild'}/api/json`;
+    // ... fetch 并返回构建状态、耗时、结果等
+  }
+}
+
+/**
+ * Tool: ci_build_logs
+ * 读取构建日志
+ */
+{
+  name: "ci_build_logs",
+  description: "读取 CI 构建日志（用于排查失败原因）",
+  parameters: {
+    jobName: { type: "string" },
+    buildNumber: { type: "number" },
+    maxLines: { type: "number", optional: true, default: 200 }
+  },
+  readOnly: true
+}
+```
+
+### Issue 只读 Tools
+
+```javascript
+// mcp/tools/issue-read.js
+
+/**
+ * Tool: issue_list
+ * 列出 Issues
+ */
+{
+  name: "issue_list",
+  description: "列出项目 Issues（支持按状态/标签/负责人筛选）",
+  parameters: {
+    state: { enum: ["opened", "closed", "all"], default: "opened" },
+    labels: { type: "array", optional: true },
+    assignee: { type: "string", optional: true },
+    perPage: { type: "number", default: 20 }
+  },
+  readOnly: true
+}
+
+/**
+ * Tool: issue_detail
+ * 获取 Issue 详情
+ */
+{
+  name: "issue_detail",
+  description: "获取单个 Issue 的完整详情（含评论）",
+  parameters: {
+    issueId: { type: "number/string" },
+    includeComments: { type: "boolean", default: true }
+  },
+  readOnly: true
+}
+```
+
+## 阶段二：写入集成（规划中）
+
+以下工具将在完成阶段一验证后逐步开放：
+
+| Tool | 操作 | 审批要求 | 风险等级 |
+|------|------|----------|----------|
+| `ci_trigger_build` | 触发 CI 构建 | 需人工审批 | 中 |
+| `pr_create_comment` | 在 PR 上评论 | Agent 自动 | 低 |
+| `pr_create` | 创建 PR/MR | 需人工审批 | 中 |
+| `docker_push` | 推送 Docker 镜像 | 需人工审批 | 高 |
+| `issue_create` | 创建 Issue | PM Agent 可用 | 低 |
+
+---
+
+# ════════════════════════════════════════════════════════
+#  Java 后端专属 Tools 定义
+# ════════════════════════════════════════════════════════
+
+> **适用技术栈**: Spring Boot / Maven / SonarQube
+> **触发条件**: 项目包含 pom.xml 时启用
+
+## Java 只读 Tools 定义
+
+### SonarQube 质量读取
+
+```javascript
+// mcp/tools/sonarqube-read.js
+
+/**
+ * Tool: sonarqube_project_metrics
+ * 读取项目的 SonarQube 质量指标
+ */
+{
+  name: "sonarqube_project_metrics",
+  description: "获取指定项目在 SonarQube 中的代码质量指标（覆盖率、Bug数、漏洞等）",
+  parameters: {
+    projectKey: { type: "string", description: "SonarQube 项目标识 (如 com.jieshun:backend)" },
+    metrics: { 
+      type: "array", 
+      description: "需要查询的指标列表",
+      optional: true,
+      default: ["coverage", "bugs", "vulnerabilities", "code_smells", "duplicated_lines_density"]
+    }
+  },
+  readOnly: true,
+  handler: async ({ projectKey, metrics }) => {
+    const url = `${sonarqubeUrl}/api/measures/component?component=${projectKey}&metricKeys=${metrics.join(',')}`;
+    // 返回各指标的当前值和趋势
+  }
+}
+
+/**
+ * Tool: sonarqube_quality_gate
+ * 查询项目的 Quality Gate 状态
+ */
+{
+  name: "sonarqube_quality_gate",
+  description: "查询 SonarQube Quality Gate 通过状态及失败原因",
+  parameters: {
+    projectKey: { type: "string" }
+  },
+  readOnly: true,
+  handler: async ({ projectKey }) => {
+    const url = `${sonarqubeUrl}/api/qualitygates/project_status?projectKey=${projectKey}`;
+    // 返回 PASS/FAIL + 失败的具体条件
+  }
+}
+```
+
+### Maven 构件查询
+
+```javascript
+// mcp/tools/maven-read.js
+
+/**
+ * Tool: maven_dependency_tree
+ * 查询项目的 Maven 依赖树（远程或本地）
+ */
+{
+  name: "maven_dependency_info",
+  description: "查询指定依赖的版本信息、是否存在安全漏洞",
+  parameters: {
+    groupId: { type: "string", description: "Maven groupId" },
+    artifactId: { type: "string", description: "Maven artifactId" },
+    version: { type: "string", optional: true, description: "版本号，不填则查最新" }
+  },
+  readOnly: true,
+  handler: async ({ groupId, artifactId, version }) => {
+    // 查询 Maven Central Repository API
+    // 返回：可用版本列表、最新稳定版、是否有已知 CVE
+  }
+}
+
+/**
+ * Tool: maven_central_search
+ * 在 Maven Central 中搜索构件
+ */
+{
+  name: "maven_central_search",
+  description: "在 Maven Central Repository 中搜索库/组件",
+  parameters: {
+    query: { type: "string", description: "搜索关键词" },
+    rows: { type: "number", optional: true, default: 10 }
+  },
+  readOnly: true
+}
+```
+
+### Jenkins Maven Job 工具
+
+```javascript
+// mcp/tools/jenkins-java.js
+
+/**
+ * Tool: jenkins_maven_job_status
+ * 查询 Maven 类型 Jenkins Job 的构建详情
+ */
+{
+  name: "jenkins_maven_job_status",
+  description: "查询 Maven 项目的 Jenkins 构建：编译结果、测试结果、JaCoCo覆盖率",
+  parameters: {
+    jobName: { type: "string", description: "Jenkins Job 名称 (如 backend-maven-build)" },
+    buildNumber: { type: "number", optional: true, default: "lastBuild" },
+    includeCoverage: { type: "boolean", optional: true, default: true }
+  },
+  readOnly: true,
+  handler: async ({ jobName, buildNumber, includeCoverage }) => {
+    // 查询 Jenkins API
+    // 返回：
+    //   - 编译状态 (SUCCESS/FAILURE)
+    //   - 测试通过率
+    //   - JaCoCo 覆盖率（如果 includeCoverage=true）
+    //   - Surefire 报告摘要
+  }
+}
+```
+
+## MCP Systems 配置 — Java 扩展
+
+### 新增系统连接
+
+```yaml
+# .harness/mcp/config.yaml → systems 下追加
+
+  # === Java 后端专用系统 ===
+  sonarqube:
+    type: "sonarqube_api"
+    base_url: "${SONARQUBE_URL}"           # 如 http://localhost:9000
+    token_ref: "SONARQUBE_TOKEN"
+    enabled: true                          # Java 项目必须启用
+    
+  maven_repo:
+    type: "maven_central_api"
+    base_url: "https://search.maven.org/solrsearch/select"  # 公开，无需凭证
+    enabled: true
+```
+
+### 权限矩阵扩展
+
+```yaml
+# permission_matrix 追加 Java 相关工具权限
+
+  developer:
+    allowed_tools:
+      # ... 已有 ...
+      - "sonarqube:*:read"               # 读取质量数据
+      - "maven:*:read"                   # 查询依赖信息
+      - "jenkins:maven-job:read"         # 查看 Maven Job 状态
+    blocked_tools:
+      - "sonarqube:*:write"              # 不能修改 Quality Gate
+      - "jenkins:maven-job:trigger"      # 触发需审批
+
+  tester:
+    allowed_tools:
+      # ... 已有 ...
+      - "sonarqube:*:read"
+      - "jenkins:maven-job:read"
+      
+  gate_controller:
+    allowed_tools:
+      # ... 已有 ...
+      - "sonarqube:quality_gate:read"     # 重点：检查 QG 状态
+      - "sonarqube:*:read"
+      - "security:scan:java"             # Java 安全扫描结果
+```
+
+## 阶段三：完整闭环（远期规划）
+
+- 制品上传 Tool
+- 部署触发/回滚 Tool（需多级审批）
+- 状态回写 Tool（GitLab → TaskBoard）
+- 通知发送 Tool（钉钉/企业微信/Slack）
+
+## 安全部署配置
+
+### 权限控制矩阵
+
+```yaml
+permission_matrix:
+  # 角色 → Tool 类别 映射
+  project_manager:
+    allowed_tools:
+      - "git:read:*"
+      - "issue:read:*"
+      - "issue:create"              # 阶段二
+      - "taskboard:*"
+    blocked_tools:
+      - "ci:write:*"
+      - "docker:*"
+      - "deploy:*"
+      
+  requirements_analyst:
+    allowed_tools:
+      - "git:read:*"
+      - "issue:read:*"
+      - "dev-map:read:*"
+    blocked_tools:
+      - "issue:write:*"
+      - "ci:*"
+      
+  developer:
+    allowed_tools:
+      - "git:read:*"
+      - "ci:status:read"
+      - "pr:create"                  # 阶段二
+      - "pr:read:*"
+    blocked_tools:
+      - "ci:trigger:*"               # 必须审批
+      - "deploy:*"
+      
+  gate_controller:
+    allowed_tools:
+      - "git:read:*"
+      - "ci:status:read"
+      - "security:scan:*"
+      
+  tester:
+    allowed_tools:
+      - "git:read:*"
+      - "ci:status:read"
+      - "ci:logs:read"
+```
+
+### 凭证注入方案
+
+```
+优先级：
+1. 环境变量（运行时注入）← 推荐
+2. 密钥管理服务（Vault / AWS Secrets Manager）← 生产环境
+3. .env 文件（仅本地开发，不入库）
+4. MCP 配置文件中的加密字段 ← 不推荐
+
+禁止：
+- ❌ 硬编码在任何代码或配置中
+- ❌ 提交到版本控制系统的任何形式的凭证
+```

package/.harness/rules/global/coding-standard.md

@@ -0,0 +1,232 @@
+# 通用编码规范规则 (coding-standard)
+
+> **级别**: 必须遵守 | **适用范围**: 全局（前端+后端）
+
+## 1. ESLint / Prettier 强制规则
+
+所有代码必须通过以下检查：
+
+| 规则类别 | 要求 |
+|----------|------|
+| **ESLint** | 零 error，零 warning（除已白名单的规则） |
+| **Prettier** | 格式化后无 diff 变更 |
+| **TypeScript** | `strict: true` 模式，禁止 `any` 类型（除非有明确注释说明原因） |
+
+### 前端特有
+
+```javascript
+// ✅ 正确：使用明确的类型
+const userId: string = user.id;
+
+// ❌ 错误：禁止裸 any
+const data = response.data;  // 隐式 any
+
+// ⚠️ 允许但有条件：必须注释 why
+const legacyData: any = parseLegacyFormat(raw); // Legacy API, 待重构
+```
+
+### 后端特有
+
+- 所有公开 API 入口必须有参数校验（使用 Joi/Zod/类装饰器）
+- 数据库操作必须使用 ORM/Query Builder，禁止拼接 SQL
+
+## 2. 命名约定
+
+| 类型 | 约定 | 示例 |
+|------|------|------|
+| **文件名** | kebab-case | `user-service.ts`, `login-form.vue` |
+| **组件名** | PascalCase | `UserProfile`, `DataTable` |
+| **变量/函数** | camelCase | `getUserById`, `isLoading` |
+| **常量** | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `API_BASE_URL` |
+| **类/接口/类型** | PascalCase | `UserService`, `IUserRepository` |
+| **CSS 类名** | BEM 规范 | `block__element--modifier` |
+| **环境变量** | UPPER_SNAKE_CASE 前缀 | `APP_PORT`, `DB_HOST` |
+
+### 组件文件命名规范
+
+```
+components/
+├── features/           # 功能组件（业务逻辑）
+│   └── user-profile/
+│       ├── UserProfile.vue       # 主组件
+│       ├── UserProfile.test.vue  # 测试
+│       ├── useUserProfile.ts     # Composable (Hook)
+│       └── index.ts             # 导出
+├── ui/                 # 通用 UI 组件
+│   └── button/
+│       └── Button.vue
+└── layouts/            # 布局组件
+    └── MainLayout.vue
+```
+
+## 3. 代码风格要求
+
+### 3.1 文件长度限制
+
+| 文件类型 | 最大行数 | 说明 |
+|----------|---------|------|
+| 单个组件文件 | 300 行 | 超出必须拆分 |
+| 单个工具函数文件 | 200 行 | 超出必须拆分 |
+| 测试文件 | 500 行 | 按场景分文件 |
+| 配置文件 | 100 行 | 复杂配置抽离 |
+
+### 3.2 函数复杂度
+
+- 单个函数不超过 50 行
+- 圈复杂度 ≤ 10
+- 嵌套层级 ≤ 4 层
+- 函数参数 ≤ 5 个（超出使用对象参数）
+
+### 3.3 导入顺序
+
+```typescript
+// 1. 外部库（按字母序）
+import { ref, computed, onMounted } from 'vue';
+
+// 2. 内部共享模块
+import { apiClient } from '@/lib/api';
+import { ElButton } from 'element-plus';
+
+// 3. 相邻模块
+import { UserProfile } from './UserProfile.vue';
+
+// 4. 类型导入（与对应库分组）
+import type { User } from '@/types';
+```
+
+### 3.4 禁止模式
+
+```typescript
+// ❌ 禁止：console.log 残留到生产代码
+console.log('debug:', data);
+
+// ❌ 禁止：debugger 语句
+debugger;
+
+// ❌ 禁止：硬编码魔法数字
+if (status === 37) { ... }
+
+// ✅ 正确：使用有命名的常量
+const ORDER_STATUS_SHIPPED = 37;
+if (status === ORDER_STATUS_SHIPPED) { ... }
+
+// ❌ 禁止：var 声明
+var x = 1;
+
+// ❌ 禁止：嵌套三元表达式
+const result = a ? (b ? c : d) : e;
+
+// ✅ 正确：使用早返回或提取函数
+```
+
+## 4. 错误处理规范
+
+```typescript
+// ✅ 正确：统一的错误处理模式
+try {
+  const result = await apiClient.fetchUser(id);
+  return result;
+} catch (error) {
+  // 区分可恢复和不可恢复错误
+  if (isRecoverableError(error)) {
+    logger.warn('Recoverable error', { error, id });
+    return fallbackValue;
+  }
+  // 不可恢复错误向上抛出
+  throw new UserFetchError('Failed to fetch user', { cause: error, id });
+}
+```
+
+## 5. 注释规范
+
+```typescript
+/**
+ * 根据用户 ID 获取用户信息
+ * 
+ * @param id - 用户唯一标识符（UUID v4 格式）
+ * @returns 用户基本信息，不存在时返回 null
+ * @throws {ValidationError} 当 ID 格式无效时抛出
+ * 
+ * @example
+ * const user = await getUserById('550e8400-e29b-41d4-a716-446655440000');
+ */
+async function getUserById(id: string): Promise<User | null>
+```
+
+**注释要求**：
+- 所有公开 API 必须有 JSDoc
+- 复杂逻辑必须有行内注释解释「为什么」而非「是什么」
+- TODO/FIXME 必须关联 Issue 编号：`TODO(#123): 说明`
+
+---
+
+## 6. AI 辅助编码通用约束
+
+> **来源**: `files/AI_RULE.md` (v1.0.0) | **归档日期**: 2026-05-21
+> 本章节为跨语言通用规则，适用于 AI 辅助代码生成场景。
+
+### 6.1 基础约束（A01-A06）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A01 | 匹配项目当前框架/语言版本，不得使用项目未引入的依赖版本 |
+| A02 | 沿用项目已有命名风格和模式，先阅读同目录下已有文件再生成 |
+| A03 | 单次代码长度 ≤ 80 行，超长逻辑必须拆分 |
+| A04 | 使用 4 空格缩进，遵循 .editorconfig 配置 |
+| A05 | 必须 包含 try-catch 或 throws 声明 |
+| A06 | 禁止空 catch 块（catch 中至少有日志记录），禁止顶层异常泄漏 |
+
+### 6.2 依赖与引入规范（A07-A10）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A07 | 复用优于新建：先检查项目中是否有相同功能的工具类或依赖，优先复用 |
+| A08 | import 按规范排序（第三方库 → 项目内部），禁止引入未使用的 import |
+| A09 | 禁止使用 @Deprecated 的 API，优先使用推荐替代方案 |
+| A10 | 新依赖版本与项目现有版本兼容，不得随意升级或降级 |
+
+### 6.3 业务代码规范（A11-A16）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A11 | Controller 只做路由转发和参数校验，业务逻辑下沉到 Service 层 |
+| A12 | Service 负责**业务编排**，协调多个 Mapper/外部服务完成流程 |
+| A13 | SQL 参数绑定必须使用预编译方式（`#{}` / `?` / named parameter），禁止字符串拼接 |
+| A14 | 操作集合前必须判空（null check 或 Optional），禁止对可能为 null 的集合直接调用方法 |
+| A15 | 循环内禁止执行数据库查询或 HTTP 请求（N+1 防范），大数据量循环考虑分批处理 |
+| A16 | 使用 Enum 枚举替代魔法数字/字符串 |
+
+### 6.4 并发与资源管理（A17-A20）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A17 | 多线程使用合理线程池配置（ThreadPoolExecutor），禁止 new Thread() 或 Executors 无界工厂 |
+| A18 | I/O 流、数据库连接、HTTP Client 等资源必须 try-with-resources 或 finally 释放，禁止资源泄漏 |
+| A19 | ThreadLocal 使用完毕后必须 remove() 清理，防止内存泄漏 |
+| A20 | 跨进程互斥必须使用分布式锁（如 Redisson），禁止 JVM 内置锁解决跨进程问题 |
+
+### 6.5 注释与文档规范（A21-A24）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A21 | public class/interface 必须包含完整的 JSDoc/JavaDoc 注释 |
+| A22 | 关键步骤处必须有行内注释解释"**为什么**"这样做，关注 why 而非 what |
+| A23 | TODO 必须附带具体场景说明，格式：`// TODO: [场景描述] - 待[具体动作]` |
+| A24 | 重构或修改时相关注释必须同步更新，禁止注释与代码不一致 |
+
+### 6.6 接口/DTO/实体规范（A25-A28）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A25 | DTO/Entity/VO 类属性必须为 private，通过 getter/setter 或 Lombok 访问，禁止 public 字段 |
+| A26 | API 返回结果必须使用统一 Result<T> 封装类，禁止返回原始对象 |
+| A27 | 分页查询返回包含标准分页结构（list + total + pages），请求参数包含 page/pageSize |
+| A28 | 时间字段使用 LocalDateTime / Instant 等现代时间 API，禁用 Date / Timestamp / SimpleDateFormat |
+
+### 6.7 异常处理规范（A29-A31）
+
+| 规则 ID | 要求 |
+|---------|------|
+| A29 | catch 块必须精确捕获具体异常类型，禁止笼统 `catch(Exception e)` 吞掉所有异常 |
+| A30 | 日志中必须包含足够上下文信息（参数、状态、关键变量），便于问题排查 |
+| A31 | 业务规则违反必须抛出项目自定义业务异常（如 BusinessException/JscicdBizException），携带错误码和错误信息 |