# skill_monitor

**Repository Path**: yxc2/skill_monitor

## Basic Information

- **Project Name**: skill_monitor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 质量行为追踪系统 — 三轨采集 + MR 合规门禁

> 量化 · 留痕 · 闭环 · 跨平台

## 架构概览

```
┌─ Track 1: AOP 自动埋点 ──────────────┐
│  BaseAgent.run()                      │
│  BaseSkill.execute()                  │──→ quality_activity 表
│  BaseTestPlanSkill.execute()          │
│  LocalAgentRuntime.execute()          │
└───────────────────────────────────────┘

┌─ Track 2: REST API 上报 ─────────────┐
│  CI/CD (curl POST)                    │
│  Claude Code Hook (quality-hook.js)   │──→ quality_activity 表
│  Skill脚本 (quality-tracker.sh)       │
│  本地缓冲同步 (sync-buffer.sh/bat)    │
└───────────────────────────────────────┘

┌─ Track 3: MCP 代理 ─────────────────┐
│  QualityMcpProxy.java                │
│  透明拦截所有 MCP tools/call          │──→ quality_activity 表
│  支持 SonarQube/Semgrep/Snyk 等      │
└───────────────────────────────────────┘

┌─ MR 合规门禁 ────────────────────────┐
│  ComplianceGateService                │
│  mandatory_behavior 配置驱动          │──→ MR comment (✅/❌)
│  enforcement: monitor → warn → block  │
└───────────────────────────────────────┘
```

## 目录结构

```
jiankong/
├── backend/                                   # Java 后端模块（唯一一份）
│   ├── aop/
│   │   └── QualityTrackingAspect.java         # Track 1: AOP 自动埋点
│   ├── controller/
│   │   └── QualityTrackerController.java      # REST API (活动+问题+合规+门禁)
│   ├── model/
│   │   ├── QualityActivity.java               # 活动记录模型
│   │   ├── QualityIssue.java                  # 问题记录模型
│   │   ├── MandatoryBehavior.java             # 强制行为配置
│   │   └── DeveloperCompliance.java           # 合规评分
│   ├── repository/
│   │   ├── QualityActivityRepository.java
│   │   ├── QualityIssueRepository.java
│   │   ├── MandatoryBehaviorRepository.java
│   │   └── DeveloperComplianceRepository.java
│   └── service/
│       ├── QualityTrackerService.java         # 上报 + 问题提取 + 指纹闭环
│       ├── ComplianceService.java             # 合规评分计算 (定时 @Scheduled)
│       └── ComplianceGateService.java         # MR 合规门禁
├── mcp-proxy/
│   └── QualityMcpProxy.java                   # Track 3: MCP 代理 (独立Java程序)
├── hook/
│   ├── quality-hook.js                        # Claude Code PostToolUse Hook
│   ├── claude-code-hook.json                  # Hook 配置片段
│   ├── sync-buffer.sh                         # Linux/Mac 缓冲同步
│   ├── sync-buffer.bat                        # Windows 缓冲同步
│   └── README-SETUP.md                        # Hook 配置指南
├── skill/                                     # Claude Code Skill 定义（主版本）
│   ├── SKILL.md
│   ├── scripts/
│   │   └── quality-tracker.sh                 # CLI 瑞士军刀脚本
│   ├── prompts/
│   │   ├── system.md
│   │   └── user.md
│   └── assets/
│       └── output_template.json
├── openclaw/                                  # OpenClaw 平台部署包
│   ├── agents/
│   │   ├── openclaw.json                      # Agent 团队配置
│   │   └── quality-tracker/SOUL.md            # Agent 人设
│   ├── skills/quality-tracker/                # Skill 副本（部署用）
│   ├── deploy.sh / deploy.bat                 # 一键部署脚本
│   └── install.sh
├── schema/
│   ├── schema-sqlserver.sql                   # SQL Server DDL (4表+索引+样本数据)
│   └── schema-h2.sql                          # H2 DDL (测试环境)
├── test/
│   └── test-all-tracks.sh                     # 全链路测试脚本
├── plan-final.md                              # 设计文档（权威规格说明）
└── README.md
```

## 集成步骤

### 1. 建表

```sql
-- SQL Server 生产环境:
-- 执行 schema/schema-sqlserver.sql

-- H2 测试环境:
-- 将 schema/schema-h2.sql 内容追加到主项目 backend/src/main/resources/schema-h2.sql
```

### 2. 复制 Java 文件到主项目

```bash
# 目标路径: 主项目 backend/src/main/java/com/quality/platform/module/qualitytracker/
TARGET="<主项目>/backend/src/main/java/com/quality/platform/module/qualitytracker"

# 复制各子目录
for DIR in model repository service aop controller; do
  mkdir -p "$TARGET/$DIR"
  cp backend/$DIR/*.java "$TARGET/$DIR/"
done
```

### 3. 确保 pom.xml 有 AOP 依赖

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>
```

### 4. 编译验证

```bash
cd backend && mvn compile
```

### 5. 启动后端 + 运行测试

```bash
# 启动
cd backend && mvn spring-boot:run

# 运行全链路测试
bash test/test-all-tracks.sh
```

### 6. 配置 Claude Code Hook

```json
// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "command": "node hook/quality-hook.js"
    }]
  }
}
```

### 7. 配置 MCP 代理（可选）

```bash
# 编译 MCP 代理
javac mcp-proxy/QualityMcpProxy.java

# 在 MCP 配置中使用:
{
  "mcpServers": {
    "sonarqube": {
      "command": "java",
      "args": [
        "-cp", "mcp-proxy",
        "QualityMcpProxy",
        "--target=npx -y @anthropic/sonarqube-mcp",
        "--report-to=http://localhost:18080/api/quality-tracker/activities",
        "--tool-name=sonarqube"
      ]
    }
  }
}
```

### 8. 配置定时同步（可选）

```bash
# Linux crontab:
0 1 * * * bash /path/to/hook/sync-buffer.sh

# Windows 计划任务:
schtasks /create /tn "QualitySync" /tr "E:\jiankong\hook\sync-buffer.bat" /sc daily /st 01:00
```

## API 速查

| 方法 | 路径 | 用途 |
|------|------|------|
| POST | `/api/quality-tracker/activities` | 上报单条活动 |
| POST | `/api/quality-tracker/activities/batch` | 批量同步（缓冲上传） |
| GET | `/api/quality-tracker/activities` | 查询活动记录 |
| GET | `/api/quality-tracker/activities/stats` | 活动统计（按工具分组） |
| POST | `/api/quality-tracker/issues` | 上报问题 |
| POST | `/api/quality-tracker/issues/batch` | 批量上报问题 |
| PUT | `/api/quality-tracker/issues/{id}/status` | 更新问题状态（闭环） |
| GET | `/api/quality-tracker/issues` | 查询问题列表 |
| POST | `/api/quality-tracker/check-mr` | **MR合规门禁检查** |
| GET | `/api/quality-tracker/compliance/{dev}` | 合规评分查询 |
| GET | `/api/quality-tracker/compliance/ranking` | 合规排行榜 |
| POST | `/api/quality-tracker/compliance/calculate` | 手动触发合规计算 |
| GET | `/api/quality-tracker/behaviors` | 强制行为列表 |
| POST | `/api/quality-tracker/behaviors` | 新增强制行为 |
| PUT | `/api/quality-tracker/behaviors/{id}` | 更新强制行为 |
| DELETE | `/api/quality-tracker/behaviors/{id}` | 删除强制行为 |

## Skill 一站式命令（瑞士军刀）

```bash
# 环境初始化
bash scripts/quality-tracker.sh setup

# 上报活动
bash scripts/quality-tracker.sh scan --tool sonarqube --action scan --issues 3

# 查询问题
bash scripts/quality-tracker.sh issues --status open

# 上报问题
bash scripts/quality-tracker.sh issues --report --tool sonarqube --file PaymentService.java --severity critical --message "空指针风险"

# 合规评分
bash scripts/quality-tracker.sh compliance

# 合规排行
bash scripts/quality-tracker.sh compliance --ranking

# MR门禁检查
bash scripts/quality-tracker.sh check --branch feature/payment

# 同步缓冲区
bash scripts/quality-tracker.sh sync

# 查看强制行为
bash scripts/quality-tracker.sh behaviors

# 活动统计
bash scripts/quality-tracker.sh stats --start 2026-03-01
```

## 核心设计原则

1. **三轨采集让记录变容易** — AOP零改动、REST灵活上报、MCP透明拦截
2. **MR门禁让绕过没意义** — mandatory_behavior 配置驱动，新增一行配置 = 新增一个强制要求
3. **本地缓冲保证零网络依赖** — 编码时全离线，凌晨自动同步
4. **指纹去重确保问题闭环** — MD5(tool_name + rule_id + file_path)，排除行号变动干扰
5. **一个Skill管全部** — 瑞士军刀模式，8个子命令覆盖所有操作