feat: 添加 dev-workflow 和 pr-review-gate 技能

## dev-workflow - Spec-Driven 开发流程 - 从需求生成 spec.md - 创建功能分支 - 调用子代理开发 - 自动创建 Gitea PR ## pr-review-gate - 3 审查者并行审查（安全/质量/逻辑） - 自动合并逻辑 - 修复循环（最多3次） ## .planning - PROJECT.md: 项目定义 - REQUIREMENTS.md: 需求列表 - ROADMAP.md: 开发路线图 - STATE.md: 当前状态
2026-03-09 01:22:28 +08:00
parent 3850bc33dc
commit 33c8de02da
12 changed files with 1501 additions and 0 deletions
@@ -0,0 +1,36 @@
+# dev-workflow + pr-review-gate 技能开发
+
+## Core Value
+
+为 kb-skills 仓库提供完整的 Spec-Driven 开发流程，包括：
+- 功能分支开发
+- 自动创建 Gitea PR
+- 3 审查者并行审查
+- 自动测试 + 自动合并
+
+## Context
+
+### 现有基础设施
+- Gitea Runner 已配置 (`self-hosted`, `ubuntu-latest`)
+- CI/CD: `.gitea/workflows/deploy.yml` (部署), `.gitea/workflows/test.yml` (PR 测试)
+- 目标仓库: `ssh://gitea-nas/starmen1265/kb-skills.git`
+
+### 用户工作流
+```
+需求 → Spec → 开发 → PR → 3审查者审查 → 测试 → 合并 → 部署
+```
+
+## Constraints
+
+- 必须与现有 Gitea 环境兼容
+- 审查者使用子代理实现
+- 修复循环最多 3 次
+- 必须集成到 kb-skills 作为新技能
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| 使用 GSD Spec-Driven | 成熟的开发方法论 | 已安装 GSD |
+| 审查者为子代理 | 实现并行审查 | 待开发 |
+| Gitea API 自动 PR | 无 GitHub CLI | 待开发 |
@@ -0,0 +1,51 @@
+# Requirements - dev-workflow + pr-review-gate
+
+## v1 Requirements
+
+### dev-workflow 技能
+
+- [ ] **DEV-01**: 用户描述需求后，生成 spec.md 文件
+- [ ] **DEV-02**: 从 spec 创建 `feature/*` 功能分支
+- [ ] **DEV-03**: 调用子代理进行开发（基于 GSD 子代理编排）
+- [ ] **DEV-04**: 开发完成后自动提交到功能分支
+- [ ] **DEV-05**: 调用 Gitea API 创建 PR
+- [ ] **DEV-06**: 触发 CI 测试（通过现有 test.yml）
+
+### pr-review-gate 技能
+
+- [ ] **PRG-01**: PR 创建后自动启动 3 个审查子代理
+- [ ] **PRG-02**: 审查者1 - Security Reviewer（安全审查）
+- [ ] **PRG-03**: 审查者2 - Quality Reviewer（代码质量审查）
+- [ ] **PRG-04**: 审查者3 - Logic Reviewer（业务逻辑审查）
+- [ ] **PRG-05**: 收集 3 个审查结果
+- [ ] **PRG-06**: 全部 approve + CI 通过 → 调用 Gitea API 合并
+- [ ] **PRG-07**: 有 reject → 修复 → 重新审查（最多 3 次）
+- [ ] **PRG-08**: 3 次修复后仍有问题 → 汇报失败，等待人工介入
+
+### 集成要求
+
+- [ ] **INT-01**: 技能安装到 `kb-skills/dev-workflow/` 和 `kb-skills/pr-review-gate/`
+- [ ] **INT-02**: 每个技能包含 `SKILL.md` 和 Python 辅助脚本
+- [ ] **INT-03**: 修改 `.gitea/workflows/` 支持自动合并逻辑
+
+## v2 Requirements (Future)
+
+- 支持自定义审查者数量
+- 支持不同类型的审查模板
+- 支持 GitHub 兼容模式
+
+## Out of Scope
+
+- GitHub 原生支持（仅 Gitea）
+- 图形化界面
+- 实时协作审查
+
+## Traceability
+
+| Phase | Requirements |
+|-------|--------------|
+| Phase 1: dev-workflow 核心 | DEV-01, DEV-02, DEV-03, DEV-04 |
+| Phase 2: Gitea PR 集成 | DEV-05, DEV-06 |
+| Phase 3: pr-review-gate 核心 | PRG-01 ~ PRG-05 |
+| Phase 4: 自动合并逻辑 | PRG-06, PRG-07, PRG-08, INT-03 |
+| Phase 5: 集成测试 | INT-01, INT-02 |
@@ -0,0 +1,106 @@
+# Roadmap - dev-workflow + pr-review-gate
+
+## Overview
+
+**5 Phases** | **11 Requirements** | All v1 requirements covered ✓
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| 1 | dev-workflow 核心 | 实现基础开发流程技能 | DEV-01~04 | 用户可以说"添加XXX功能"，系统生成 spec 并在 feature 分支开发 |
+| 2 | Gitea PR 集成 | 自动创建 PR 和触发测试 | DEV-05~06 | 开发完成后自动创建 PR，CI 测试运行 |
+| 3 | pr-review-gate 核心 | 实现 3 审查者并行审查 | PRG-01~05 | PR 创建后自动启动 3 个审查子代理并收集结果 |
+| 4 | 自动合并逻辑 | 实现审查通过后自动合并 | PRG-06~08, INT-03 | 全部通过自动合并，失败自动修复循环 |
+| 5 | 集成测试 | 完整流程验证 | INT-01~02 | 端到端测试通过，技能可用 |
+
+---
+
+## Phase 1: dev-workflow 核心
+
+**Goal:** 实现基础开发流程技能
+
+**Requirements:** DEV-01, DEV-02, DEV-03, DEV-04
+
+**Deliverables:**
+- `kb-skills/dev-workflow/SKILL.md`
+- `kb-skills/dev-workflow/dev_workflow.py`
+- `kb-skills/dev-workflow/templates/spec-template.md`
+
+**Success Criteria:**
+1. 用户描述需求后，生成 `.planning/spec.md` 文件
+2. 从 spec 创建 `feature/*` 功能分支
+3. 子代理可以基于 spec 进行开发
+4. 开发完成后提交到功能分支
+
+---
+
+## Phase 2: Gitea PR 集成
+
+**Goal:** 自动创建 PR 和触发测试
+
+**Requirements:** DEV-05, DEV-06
+
+**Deliverables:**
+- `dev_workflow.py` 添加 Gitea API 调用
+- 获取 Gitea API Token 配置
+
+**Success Criteria:**
+1. 开发完成后调用 Gitea API 创建 PR
+2. PR 创建后自动触发 CI 测试
+3. 返回 PR 编号和链接
+
+---
+
+## Phase 3: pr-review-gate 核心
+
+**Goal:** 实现 3 审查者并行审查
+
+**Requirements:** PRG-01, PRG-02, PRG-03, PRG-04, PRG-05
+
+**Deliverables:**
+- `kb-skills/pr-review-gate/SKILL.md`
+- `kb-skills/pr-review-gate/pr_gate.py`
+- `kb-skills/pr-review-gate/reviewers/security.md`
+- `kb-skills/pr-review-gate/reviewers/quality.md`
+- `kb-skills/pr-review-gate/reviewers/logic.md`
+
+**Success Criteria:**
+1. PR 创建后自动启动 3 个审查子代理
+2. 每个审查者有明确的审查重点
+3. 收集 3 个审查结果（approve/reject + 评论）
+4. 审查结果可追溯
+
+---
+
+## Phase 4: 自动合并逻辑
+
+**Goal:** 实现审查通过后自动合并
+
+**Requirements:** PRG-06, PRG-07, PRG-08, INT-03
+
+**Deliverables:**
+- `pr_gate.py` 添加合并逻辑
+- `.gitea/workflows/auto-merge.yml`（可选）
+- 修复循环逻辑
+
+**Success Criteria:**
+1. 全部 approve + CI 通过 → 自动合并到 main
+2. 有 reject → 启动修复流程
+3. 修复后重新审查（最多 3 次）
+4. 3 次后仍有问题 → 汇报失败详情
+
+---
+
+## Phase 5: 集成测试
+
+**Goal:** 完整流程验证
+
+**Requirements:** INT-01, INT-02
+
+**Deliverables:**
+- 端到端测试文档
+- 使用示例
+
+**Success Criteria:**
+1. 完整流程可运行：需求 → Spec → 开发 → PR → 审查 → 合并
+2. 技能文档完整（SKILL.md）
+3. 用户可以按照文档使用
@@ -0,0 +1,30 @@
+# Project State
+
+## Current Phase
+
+**Phase 1: dev-workflow 核心**
+
+Status: `in_progress`
+
+## Progress
+
+| Phase | Status | Notes |
+|-------|--------|-------|
+| Phase 1: dev-workflow 核心 | 🔄 In Progress | 开始开发 |
+| Phase 2: Gitea PR 集成 | ⏳ Pending | - |
+| Phase 3: pr-review-gate 核心 | ⏳ Pending | - |
+| Phase 4: 自动合并逻辑 | ⏳ Pending | - |
+| Phase 5: 集成测试 | ⏳ Pending | - |
+
+## Active Context
+
+- 开发 dev-workflow 技能
+- 目标: DEV-01 ~ DEV-04
+- 产出: SKILL.md + dev_workflow.py + templates/
+
+## Session Log
+
+### 2026-03-09 01:18
+- 安装 GSD
+- 创建 PROJECT.md, REQUIREMENTS.md, ROADMAP.md
+- 开始 Phase 1 开发
@@ -0,0 +1,166 @@
+---
+name: dev-workflow
+description: "Spec-Driven 开发流程技能。当用户说'添加功能'、'开发XXX'时使用。"
+---
+
+# dev-workflow - Spec-Driven 开发流程
+
+## 什么时候使用
+
+当用户发送包含以下模式的消息时触发：
+
+| 触发词 | 行为 |
+|--------|------|
+| `添加功能` + 描述 | 开始 Spec-Driven 开发流程 |
+| `开发` + 描述 | 同上 |
+| `实现` + 描述 | 同上 |
+
+## 环境变量
+
+| 变量名 | 用途 | 必需 |
+|--------|------|------|
+| `GITEA_TOKEN` | Gitea API Token（创建 PR） | 是 |
+| `GITEA_URL` | Gitea 服务地址 | 否（默认 http://192.168.1.22:8418） |
+| `GITEA_REPO` | 仓库路径 | 否（默认 starmen1265/kb-skills） |
+
+## 工作流程
+
+```
+用户描述需求
+    ↓
+┌─────────────────────────────────────┐
+│  Phase 1: Spec 生成                  │
+│  - 澄清需求                          │
+│  - 生成 .planning/spec.md            │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│  Phase 2: 分支创建                   │
+│  - 创建 feature/* 分支               │
+│  - 切换到功能分支                    │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│  Phase 3: 子代理开发                 │
+│  - 基于 spec 启动开发子代理          │
+│  - 子代理执行开发任务                │
+│  - 提交代码到功能分支                │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│  Phase 4: 创建 PR                    │
+│  - 调用 Gitea API 创建 PR            │
+│  - 返回 PR 编号                      │
+└─────────────────────────────────────┘
+    ↓
+通知 pr-review-gate 开始审查
+```
+
+## 执行步骤
+
+### Step 1: 需求澄清
+
+使用 GSD 风格的深度提问：
+
+1. 理解用户要做什么
+2. 探索边界条件
+3. 确认技术约束
+4. 识别依赖关系
+
+**示例问题：**
+- "这个功能解决什么问题？"
+- "期望的输入/输出是什么？"
+- "有什么技术约束？"
+- "需要与现有哪些模块交互？"
+
+### Step 2: 生成 Spec
+
+创建 `.planning/spec.md` 文件：
+
+```bash
+python3 dev_workflow.py --create-spec --title "功能名称" --description "详细描述"
+```
+
+Spec 文件结构参考 `templates/spec-template.md`。
+
+### Step 3: 创建功能分支
+
+```bash
+python3 dev_workflow.py --create-branch --spec .planning/spec.md
+```
+
+分支命名规则：
+- `feature/<简短描述>` - 新功能
+- `fix/<简短描述>` - Bug 修复
+- `refactor/<简短描述>` - 重构
+
+### Step 4: 启动开发子代理
+
+使用 `sessions_spawn` 启动开发子代理：
+
+```
+sessions_spawn(
+  task="根据 spec 开发 <功能名称>",
+  cwd="~/work/kb-skills",
+  runtime="subagent"
+)
+```
+
+子代理会：
+1. 读取 spec 文件
+2. 执行开发任务
+3. 提交代码到功能分支
+
+### Step 5: 创建 PR
+
+开发完成后：
+
+```bash
+python3 dev_workflow.py --create-pr --branch feature/xxx --title "PR 标题"
+```
+
+调用 Gitea API 创建 PR，返回 PR 编号。
+
+### Step 6: 通知审查
+
+PR 创建后，告知用户：
+
+```
+✅ PR #xxx 已创建
+
+**分支:** feature/xxx
+**链接:** http://192.168.1.22:8418/starmen1265/kb-skills/pulls/xxx
+
+正在启动 pr-review-gate 审查流程...
+```
+
+## CLI 命令
+
+```bash
+# 创建 spec
+python3 dev_workflow.py --create-spec --title "标题" --description "描述"
+
+# 从 spec 创建分支
+python3 dev_workflow.py --create-branch --spec .planning/spec.md
+
+# 创建 PR
+python3 dev_workflow.py --create-pr --branch feature/xxx --title "PR标题"
+
+# 查看当前状态
+python3 dev_workflow.py --status
+```
+
+## 与其他技能的协作
+
+| 技能 | 协作方式 |
+|------|----------|
+| **pr-review-gate** | PR 创建后自动触发审查 |
+| **kb-workflow** | 可复用其目录结构 |
+| **GSD** | 采用其 Spec-Driven 方法论 |
+
+## 注意事项
+
+1. 确保 `GITEA_TOKEN` 已配置
+2. 功能分支命名遵循规范
+3. 提交信息遵循 Conventional Commits
+4. 开发前先 pull 最新代码
@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+dev_workflow.py - Spec-Driven 开发流程辅助工具
+
+用法:
+    python3 dev_workflow.py --create-spec --title "标题" --description "描述"
+    python3 dev_workflow.py --create-branch --spec .planning/spec.md
+    python3 dev_workflow.py --create-pr --branch feature/xxx --title "PR标题"
+    python3 dev_workflow.py --status
+"""
+
+import os
+import sys
+import json
+import argparse
+import subprocess
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+# 配置
+GITEA_URL = os.environ.get('GITEA_URL', 'http://192.168.1.22:8418')
+GITEA_TOKEN = os.environ.get('GITEA_TOKEN', '')
+GITEA_REPO = os.environ.get('GITEA_REPO', 'starmen1265/kb-skills')
+REPO_PATH = Path.home() / 'work' / 'kb-skills'
+PLANNING_DIR = REPO_PATH / '.planning'
+
+
+def run_cmd(cmd, cwd=None, capture=True):
+    """执行 shell 命令"""
+    result = subprocess.run(
+        cmd,
+        shell=True,
+        cwd=cwd or REPO_PATH,
+        capture_output=capture,
+        text=True
+    )
+    return result
+
+
+def create_spec(title: str, description: str) -> dict:
+    """创建 spec 文件"""
+    PLANNING_DIR.mkdir(parents=True, exist_ok=True)
+
+    # 生成分支名
+    branch_name = re.sub(r'[^a-z0-9]+', '-', title.lower()).strip('-')
+
+    # 读取模板
+    template_path = Path(__file__).parent / 'templates' / 'spec-template.md'
+    if template_path.exists():
+        content = template_path.read_text(encoding='utf-8')
+    else:
+        content = """# Spec: {{TITLE}}
+
+**创建时间:** {{DATE}}
+**状态:** draft
+**分支:** feature/{{BRANCH_NAME}}
+
+---
+
+## 概述
+
+{{DESCRIPTION}}
+
+## 需求
+
+### 功能需求
+
+- [ ] **REQ-01**: 待补充
+
+## 验收标准
+
+1. 待补充
+
+---
+
+## 变更日志
+
+| 日期 | 变更 |
+|------|------|
+| {{DATE}} | 初始创建 |
+"""
+
+    # 替换变量
+    now = datetime.now().strftime('%Y-%m-%d %H:%M')
+    content = content.replace('{{TITLE}}', title)
+    content = content.replace('{{DATE}}', now)
+    content = content.replace('{{BRANCH_NAME}}', branch_name)
+    content = content.replace('{{DESCRIPTION}}', description)
+
+    # 写入文件
+    spec_file = PLANNING_DIR / 'spec.md'
+    spec_file.write_text(content, encoding='utf-8')
+
+    return {
+        "success": True,
+        "spec_file": str(spec_file),
+        "branch_name": branch_name,
+        "title": title
+    }
+
+
+def create_branch(spec_file: str) -> dict:
+    """从 spec 创建功能分支"""
+    spec_path = Path(spec_file)
+    if not spec_path.exists():
+        return {"success": False, "error": f"Spec 文件不存在: {spec_file}"}
+
+    # 从 spec 提取分支名
+    content = spec_path.read_text(encoding='utf-8')
+    match = re.search(r'\*\*分支:\*\*\s*feature/([^\n]+)', content)
+    if match:
+        branch_suffix = match.group(1).strip()
+    else:
+        branch_suffix = f"feature-{datetime.now().strftime('%Y%m%d%H%M%S')}"
+
+    branch_name = f"feature/{branch_suffix}"
+
+    # 确保在 main 分支
+    run_cmd('git checkout main')
+    run_cmd('git pull origin main')
+
+    # 创建功能分支
+    result = run_cmd(f'git checkout -b {branch_name}')
+    if result.returncode != 0:
+        # 分支可能已存在，尝试切换
+        result = run_cmd(f'git checkout {branch_name}')
+        if result.returncode != 0:
+            return {"success": False, "error": f"无法创建分支: {result.stderr}"}
+
+    return {
+        "success": True,
+        "branch": branch_name,
+        "spec_file": spec_file
+    }
+
+
+def create_pr(branch: str, title: str, body: str = "") -> dict:
+    """调用 Gitea API 创建 PR"""
+    if not GITEA_TOKEN:
+        return {"success": False, "error": "GITEA_TOKEN 未配置"}
+
+    # 获取最新提交信息作为 body（如果未提供）
+    if not body:
+        result = run_cmd('git log -1 --pretty=%B')
+        body = result.stdout.strip() if result.returncode == 0 else ""
+
+    # 调用 Gitea API
+    import urllib.request
+    import urllib.parse
+    import json as json_module
+
+    url = f"{GITEA_URL}/api/v1/repos/{GITEA_REPO}/pulls"
+    data = {
+        "title": title,
+        "head": branch,
+        "base": "main",
+        "body": body
+    }
+
+    req = urllib.request.Request(
+        url,
+        data=json_module.dumps(data).encode('utf-8'),
+        headers={
+            'Authorization': f'token {GITEA_TOKEN}',
+            'Content-Type': 'application/json'
+        },
+        method='POST'
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            result = json_module.loads(response.read().decode('utf-8'))
+            return {
+                "success": True,
+                "pr_number": result.get("number"),
+                "pr_url": result.get("html_url"),
+                "branch": branch
+            }
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode('utf-8') if e.fp else str(e)
+        return {"success": False, "error": f"API 错误: {e.code} - {error_body}"}
+    except Exception as e:
+        return {"success": False, "error": f"请求失败: {str(e)}"}
+
+
+def get_status() -> dict:
+    """获取当前开发状态"""
+    result = {
+        "current_branch": None,
+        "spec_exists": False,
+        "planning_exists": False,
+        "uncommitted_changes": False
+    }
+
+    # 当前分支
+    branch_result = run_cmd('git branch --show-current')
+    if branch_result.returncode == 0:
+        result["current_branch"] = branch_result.stdout.strip()
+
+    # spec 文件
+    result["spec_exists"] = (PLANNING_DIR / 'spec.md').exists()
+
+    # planning 目录
+    result["planning_exists"] = PLANNING_DIR.exists()
+
+    # 未提交的更改
+    status_result = run_cmd('git status --porcelain')
+    result["uncommitted_changes"] = bool(status_result.stdout.strip())
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description='dev-workflow 辅助工具')
+    subparsers = parser.add_subparsers(dest='command', help='命令')
+
+    # create-spec
+    spec_parser = subparsers.add_parser('create-spec', help='创建 spec 文件')
+    spec_parser.add_argument('--title', required=True, help='功能标题')
+    spec_parser.add_argument('--description', default='', help='功能描述')
+
+    # create-branch
+    branch_parser = subparsers.add_parser('create-branch', help='创建功能分支')
+    branch_parser.add_argument('--spec', required=True, help='spec 文件路径')
+
+    # create-pr
+    pr_parser = subparsers.add_parser('create-pr', help='创建 PR')
+    pr_parser.add_argument('--branch', required=True, help='分支名')
+    pr_parser.add_argument('--title', required=True, help='PR 标题')
+    pr_parser.add_argument('--body', default='', help='PR 描述')
+
+    # status
+    subparsers.add_parser('status', help='查看状态')
+
+    args = parser.parse_args()
+
+    if args.command == 'create-spec':
+        result = create_spec(args.title, args.description)
+    elif args.command == 'create-branch':
+        result = create_branch(args.spec)
+    elif args.command == 'create-pr':
+        result = create_pr(args.branch, args.title, args.body)
+    elif args.command == 'status':
+        result = get_status()
+    else:
+        parser.print_help()
+        return
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == '__main__':
+    main()
@@ -0,0 +1,78 @@
+# Spec: {{TITLE}}
+
+**创建时间:** {{DATE}}
+**状态:** draft
+**分支:** feature/{{BRANCH_NAME}}
+
+---
+
+## 概述
+
+<!-- 简要描述这个功能做什么 -->
+
+## 背景
+
+<!-- 为什么需要这个功能？解决什么问题？ -->
+
+## 需求
+
+### 功能需求
+
+- [ ] **REQ-01**: <!-- 需求描述 -->
+- [ ] **REQ-02**: <!-- 需求描述 -->
+- [ ] **REQ-03**: <!-- 需求描述 -->
+
+### 非功能需求
+
+- <!-- 性能要求 -->
+- <!-- 安全要求 -->
+- <!-- 兼容性要求 -->
+
+## 技术设计
+
+### 实现方案
+
+<!-- 描述技术实现方案 -->
+
+### 文件结构
+
+```
+kb-skills/
+└── <技能目录>/
+    ├── SKILL.md
+    └── <其他文件>
+```
+
+### 依赖
+
+- <!-- 依赖的库或模块 -->
+
+## 测试计划
+
+### 单元测试
+
+- [ ] <!-- 测试用例 -->
+
+### 集成测试
+
+- [ ] <!-- 测试用例 -->
+
+## 验收标准
+
+1. <!-- 验收标准 1 -->
+2. <!-- 验收标准 2 -->
+3. <!-- 验收标准 3 -->
+
+## 风险与缓解
+
+| 风险 | 缓解措施 |
+|------|----------|
+| <!-- 风险 --> | <!-- 措施 --> |
+
+---
+
+## 变更日志
+
+| 日期 | 变更 |
+|------|------|
+| {{DATE}} | 初始创建 |
@@ -0,0 +1,274 @@
+---
+name: pr-review-gate
+description: "PR 审查门禁技能。当 PR 创建后自动触发，启动 3 个审查子代理并行审查。"
+---
+
+# pr-review-gate - PR 审查门禁
+
+## 什么时候使用
+
+- PR 创建后自动触发
+- 用户说"审查 PR #xxx"
+- 用户说"开始审查"
+
+## 环境变量
+
+| 变量名 | 用途 | 必需 |
+|--------|------|------|
+| `GITEA_TOKEN` | Gitea API Token | 是 |
+| `GITEA_URL` | Gitea 服务地址 | 否 |
+| `GITEA_REPO` | 仓库路径 | 否 |
+
+## 工作流程
+
+```
+PR 创建
+    ↓
+┌─────────────────────────────────────────────────────┐
+│  并行启动 3 个审查子代理                              │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
+│  │  Security   │ │   Quality   │ │    Logic    │    │
+│  │  Reviewer   │ │   Reviewer  │ │   Reviewer  │    │
+│  │  (安全)     │ │   (质量)    │ │   (逻辑)    │    │
+│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘    │
+│         │               │               │           │
+│         ▼               ▼               ▼           │
+│      approve?       approve?       approve?         │
+│         │               │               │           │
+└─────────┼───────────────┼───────────────┼───────────┘
+          │               │               │
+          └───────────────┼───────────────┘
+                          ▼
+              ┌───────────────────────┐
+              │  收集审查结果          │
+              └───────────┬───────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          │               │               │
+          ▼               ▼               ▼
+    全部 approve     有 reject       CI 失败
+          │               │               │
+          ▼               ▼               ▼
+    ┌───────────┐   ┌───────────┐   ┌───────────┐
+    │ 自动合并   │   │ 修复循环  │   │ 等待修复  │
+    │ 到 main    │   │ (最多3次) │   │           │
+    └───────────┘   └───────────┘   └───────────┘
+```
+
+## 审查者角色
+
+### 1. Security Reviewer (安全审查者)
+
+**关注点：**
+- 输入验证
+- SQL 注入 / XSS / CSRF
+- 敏感数据处理
+- 权限检查
+- 依赖安全
+
+**审查清单：**
+- [ ] 所有用户输入都经过验证和清理
+- [ ] 没有硬编码的密钥或凭据
+- [ ] 文件操作有路径检查
+- [ ] API 调用有适当的认证
+
+### 2. Quality Reviewer (代码质量审查者)
+
+**关注点：**
+- 代码可读性
+- 命名规范
+- 代码结构
+- 测试覆盖
+- 文档完整性
+
+**审查清单：**
+- [ ] 函数/变量命名清晰
+- [ ] 代码有适当的注释
+- [ ] 复杂逻辑有文档说明
+- [ ] 有单元测试覆盖
+- [ ] SKILL.md 已更新（如适用）
+
+### 3. Logic Reviewer (业务逻辑审查者)
+
+**关注点：**
+- 需求是否满足
+- 边界条件处理
+- 错误处理
+- 与现有功能的兼容性
+- 性能影响
+
+**审查清单：**
+- [ ] 实现符合 spec 描述
+- [ ] 边界条件已处理
+- [ ] 错误情况有适当的处理
+- [ ] 不会破坏现有功能
+- [ ] 性能可接受
+
+## 执行步骤
+
+### Step 1: 获取 PR 信息
+
+```bash
+python3 pr_gate.py --get-pr --number 123
+```
+
+获取 PR 的：
+- 标题和描述
+- 变更文件列表
+- diff 内容
+
+### Step 2: 启动审查子代理
+
+使用 `sessions_spawn` 并行启动 3 个审查子代理：
+
+```
+# Security Reviewer
+sessions_spawn(
+  task="审查 PR #xxx 的安全性",
+  label="security-reviewer",
+  runtime="subagent"
+)
+
+# Quality Reviewer
+sessions_spawn(
+  task="审查 PR #xxx 的代码质量",
+  label="quality-reviewer",
+  runtime="subagent"
+)
+
+# Logic Reviewer
+sessions_spawn(
+  task="审查 PR #xxx 的业务逻辑",
+  label="logic-reviewer",
+  runtime="subagent"
+)
+```
+
+### Step 3: 收集审查结果
+
+等待所有子代理完成，收集结果：
+
+```json
+{
+  "security": {
+    "reviewer": "security",
+    "result": "approve|reject",
+    "comments": ["..."],
+    "issues": []
+  },
+  "quality": {
+    "reviewer": "quality",
+    "result": "approve",
+    "comments": ["..."],
+    "issues": []
+  },
+  "logic": {
+    "reviewer": "logic",
+    "result": "approve",
+    "comments": ["..."],
+    "issues": []
+  }
+}
+```
+
+### Step 4: 决策
+
+**全部 approve + CI 通过：**
+```bash
+python3 pr_gate.py --merge-pr --number 123
+```
+
+**有 reject：**
+```bash
+python3 pr_gate.py --fix-loop --number 123 --attempt 1
+```
+
+### Step 5: 修复循环（最多 3 次）
+
+1. 汇总所有问题
+2. 启动修复子代理
+3. 修复后重新审查
+4. 3 次后仍有问题 → 汇报失败
+
+## CLI 命令
+
+```bash
+# 获取 PR 信息
+python3 pr_gate.py --get-pr --number 123
+
+# 启动审查
+python3 pr_gate.py --review --number 123
+
+# 检查审查结果
+python3 pr_gate.py --check-results --number 123
+
+# 合并 PR
+python3 pr_gate.py --merge-pr --number 123
+
+# 修复循环
+python3 pr_gate.py --fix-loop --number 123 --attempt 1
+
+# 完整流程
+python3 pr_gate.py --full-pipeline --number 123
+```
+
+## 输出格式
+
+### 审查通过
+
+```
+✅ PR #123 审查通过
+
+**审查结果：**
+| 审查者 | 结果 | 评论数 |
+|--------|------|--------|
+| Security | ✅ approve | 0 |
+| Quality | ✅ approve | 2 |
+| Logic | ✅ approve | 1 |
+
+**CI 状态:** ✅ 通过
+
+正在合并到 main...
+```
+
+### 需要修复
+
+```
+⚠️ PR #123 需要修复
+
+**问题汇总：**
+| 审查者 | 问题 |
+|--------|------|
+| Security | 输入验证缺失 (HIGH) |
+| Quality | 缺少单元测试 (MEDIUM) |
+
+启动修复流程 (尝试 1/3)...
+```
+
+### 最终失败
+
+```
+❌ PR #123 修复失败
+
+经过 3 次修复尝试，以下问题仍未解决：
+
+1. [Security] 输入验证缺失
+   - 位置: dev_workflow.py:45
+   - 描述: 用户输入未经过验证直接使用
+
+请人工介入处理。
+```
+
+## 与其他技能的协作
+
+| 技能 | 协作方式 |
+|------|----------|
+| **dev-workflow** | PR 创建后触发审查 |
+| **Gitea CI** | 等待 CI 通过后才合并 |
+
+## 注意事项
+
+1. 审查子代理必须独立运行，互不干扰
+2. 修复循环有明确的上限（3 次）
+3. 最终失败必须汇报详细问题
+4. 合并前必须确认 CI 通过
@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+pr_gate.py - PR 审查门禁辅助工具
+
+用法:
+    python3 pr_gate.py --get-pr --number 123
+    python3 pr_gate.py --review --number 123
+    python3 pr_gate.py --check-results --number 123
+    python3 pr_gate.py --merge-pr --number 123
+    python3 pr_gate.py --full-pipeline --number 123
+"""
+
+import os
+import sys
+import json
+import argparse
+import subprocess
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+
+
+# 配置
+GITEA_URL = os.environ.get('GITEA_URL', 'http://192.168.1.22:8418')
+GITEA_TOKEN = os.environ.get('GITEA_TOKEN', '')
+GITEA_REPO = os.environ.get('GITEA_REPO', 'starmen1265/kb-skills')
+REPO_PATH = Path.home() / 'work' / 'kb-skills'
+PLANNING_DIR = REPO_PATH / '.planning'
+MAX_FIX_ATTEMPTS = 3
+
+
+def run_cmd(cmd: str, cwd=None, capture=True) -> subprocess.CompletedProcess:
+    """执行 shell 命令"""
+    return subprocess.run(
+        cmd,
+        shell=True,
+        cwd=cwd or REPO_PATH,
+        capture_output=capture,
+        text=True
+    )
+
+
+def gitea_api(method: str, endpoint: str, data: dict = None) -> dict:
+    """调用 Gitea API"""
+    import urllib.request
+    import urllib.error
+
+    url = f"{GITEA_URL}/api/v1{endpoint}"
+    headers = {
+        'Authorization': f'token {GITEA_TOKEN}',
+        'Content-Type': 'application/json'
+    }
+
+    if data:
+        body = json.dumps(data).encode('utf-8')
+    else:
+        body = None
+
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            if response.status == 204:
+                return {"success": True}
+            return json.loads(response.read().decode('utf-8'))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode('utf-8') if e.fp else str(e)
+        return {"success": False, "error": f"HTTP {e.code}: {error_body}"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def get_pr(number: int) -> dict:
+    """获取 PR 信息"""
+    result = gitea_api('GET', f'/repos/{GITEA_REPO}/pulls/{number}')
+
+    if 'error' in result:
+        return {"success": False, "error": result['error']}
+
+    # 获取变更文件
+    files_result = gitea_api('GET', f'/repos/{GITEA_REPO}/pulls/{number}/files')
+
+    # 获取 CI 状态
+    commits_result = gitea_api('GET', f'/repos/{GITEA_REPO}/pulls/{number}/commits')
+
+    return {
+        "success": True,
+        "pr": {
+            "number": result.get("number"),
+            "title": result.get("title"),
+            "body": result.get("body"),
+            "state": result.get("state"),
+            "head": result.get("head", {}).get("ref"),
+            "base": result.get("base", {}).get("ref"),
+            "mergeable": result.get("mergeable"),
+            "user": result.get("user", {}).get("login"),
+            "created_at": result.get("created_at"),
+            "url": result.get("html_url")
+        },
+        "files": files_result if isinstance(files_result, list) else [],
+        "ci_status": _extract_ci_status(commits_result)
+    }
+
+
+def _extract_ci_status(commits: list) -> dict:
+    """从 commits 提取 CI 状态"""
+    # 简化实现，实际需要检查 commit status
+    return {
+        "status": "unknown",
+        "checks": []
+    }
+
+
+def start_review(number: int) -> dict:
+    """启动 3 个审查子代理"""
+    # 获取 PR 信息
+    pr_info = get_pr(number)
+    if not pr_info.get("success"):
+        return pr_info
+
+    # 这里应该使用 sessions_spawn 启动子代理
+    # 由于当前环境限制，返回模拟结果
+    return {
+        "success": True,
+        "message": f"已启动 3 个审查子代理审查 PR #{number}",
+        "reviewers": ["security", "quality", "logic"],
+        "pr": pr_info["pr"],
+        "note": "请在 OpenClaw 环境中使用 sessions_spawn 启动实际子代理"
+    }
+
+
+def check_results(number: int) -> dict:
+    """检查审查结果"""
+    results_file = PLANNING_DIR / f'review-pr-{number}.json'
+
+    if not results_file.exists():
+        return {
+            "success": True,
+            "status": "pending",
+            "message": "审查尚未完成"
+        }
+
+    results = json.loads(results_file.read_text(encoding='utf-8'))
+
+    # 统计结果
+    approve_count = sum(1 for r in results.get("reviews", []) if r.get("result") == "approve")
+    reject_count = sum(1 for r in results.get("reviews", []) if r.get("result") == "reject")
+
+    all_approved = approve_count == 3
+    any_rejected = reject_count > 0
+
+    return {
+        "success": True,
+        "status": "complete",
+        "all_approved": all_approved,
+        "any_rejected": any_rejected,
+        "results": results
+    }
+
+
+def merge_pr(number: int) -> dict:
+    """合并 PR"""
+    # 检查审查结果
+    review_status = check_results(number)
+    if not review_status.get("all_approved"):
+        return {
+            "success": False,
+            "error": "审查未全部通过",
+            "review_status": review_status
+        }
+
+    # 调用 Gitea API 合并
+    result = gitea_api('POST', f'/repos/{GITEA_REPO}/pulls/{number}/merge', {
+        "Do": "merge",
+        "merge_title": f"Merge PR #{number}",
+        "merge_message": ""
+    })
+
+    if result.get("success"):
+        return {
+            "success": True,
+            "message": f"PR #{number} 已合并到 main",
+            "pr_number": number
+        }
+    else:
+        return result
+
+
+def fix_loop(number: int, attempt: int = 1) -> dict:
+    """修复循环"""
+    if attempt > MAX_FIX_ATTEMPTS:
+        return {
+            "success": False,
+            "error": f"已达到最大修复次数 ({MAX_FIX_ATTEMPTS})",
+            "final_failure": True
+        }
+
+    # 获取需要修复的问题
+    review_status = check_results(number)
+
+    issues = []
+    for review in review_status.get("results", {}).get("reviews", []):
+        if review.get("result") == "reject":
+            issues.extend(review.get("issues", []))
+
+    if not issues:
+        return {
+            "success": True,
+            "message": "没有需要修复的问题"
+        }
+
+    return {
+        "success": True,
+        "attempt": attempt,
+        "max_attempts": MAX_FIX_ATTEMPTS,
+        "issues_to_fix": issues,
+        "message": f"修复尝试 {attempt}/{MAX_FIX_ATTEMPTS}",
+        "note": "请在 OpenClaw 环境中启动修复子代理"
+    }
+
+
+def full_pipeline(number: int) -> dict:
+    """完整审查流程"""
+    steps = []
+
+    # Step 1: 获取 PR
+    pr_info = get_pr(number)
+    steps.append({"step": "get_pr", "success": pr_info.get("success", False)})
+
+    if not pr_info.get("success"):
+        return {"success": False, "steps": steps, "error": pr_info.get("error")}
+
+    # Step 2: 启动审查
+    review_result = start_review(number)
+    steps.append({"step": "start_review", "success": review_result.get("success", False)})
+
+    # Step 3: 等待审查完成 (模拟)
+    # 实际应该轮询 check_results
+    steps.append({"step": "wait_review", "success": True, "note": "审查进行中..."})
+
+    # Step 4: 检查结果
+    results = check_results(number)
+    steps.append({"step": "check_results", "success": True, "data": results})
+
+    if results.get("all_approved"):
+        # Step 5a: 合并
+        merge_result = merge_pr(number)
+        steps.append({"step": "merge", "success": merge_result.get("success", False)})
+        return {"success": True, "steps": steps, "merged": merge_result.get("success", False)}
+    else:
+        # Step 5b: 修复循环
+        fix_result = fix_loop(number, attempt=1)
+        steps.append({"step": "fix_loop", "success": False, "data": fix_result})
+        return {"success": False, "steps": steps, "needs_fix": True}
+
+
+def save_review_results(number: int, reviews: List[dict]) -> dict:
+    """保存审查结果"""
+    PLANNING_DIR.mkdir(parents=True, exist_ok=True)
+    results_file = PLANNING_DIR / f'review-pr-{number}.json'
+
+    data = {
+        "pr_number": number,
+        "timestamp": datetime.now().isoformat(),
+        "reviews": reviews
+    }
+
+    results_file.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding='utf-8')
+
+    return {"success": True, "file": str(results_file)}
+
+
+def main():
+    parser = argparse.ArgumentParser(description='pr-review-gate 辅助工具')
+    subparsers = parser.add_subparsers(dest='command', help='命令')
+
+    # get-pr
+    get_parser = subparsers.add_parser('get-pr', help='获取 PR 信息')
+    get_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+
+    # review
+    review_parser = subparsers.add_parser('review', help='启动审查')
+    review_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+
+    # check-results
+    check_parser = subparsers.add_parser('check-results', help='检查审查结果')
+    check_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+
+    # merge-pr
+    merge_parser = subparsers.add_parser('merge-pr', help='合并 PR')
+    merge_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+
+    # fix-loop
+    fix_parser = subparsers.add_parser('fix-loop', help='修复循环')
+    fix_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+    fix_parser.add_argument('--attempt', type=int, default=1, help='尝试次数')
+
+    # full-pipeline
+    full_parser = subparsers.add_parser('full-pipeline', help='完整流程')
+    full_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+
+    # save-results
+    save_parser = subparsers.add_parser('save-results', help='保存审查结果')
+    save_parser.add_argument('--number', type=int, required=True, help='PR 编号')
+    save_parser.add_argument('--reviews', type=str, required=True, help='审查结果 JSON')
+
+    args = parser.parse_args()
+
+    if args.command == 'get-pr':
+        result = get_pr(args.number)
+    elif args.command == 'review':
+        result = start_review(args.number)
+    elif args.command == 'check-results':
+        result = check_results(args.number)
+    elif args.command == 'merge-pr':
+        result = merge_pr(args.number)
+    elif args.command == 'fix-loop':
+        result = fix_loop(args.number, args.attempt)
+    elif args.command == 'full-pipeline':
+        result = full_pipeline(args.number)
+    elif args.command == 'save-results':
+        result = save_review_results(args.number, json.loads(args.reviews))
+    else:
+        parser.print_help()
+        return
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == '__main__':
+    main()
@@ -0,0 +1,62 @@
+# Logic Reviewer 指南
+
+## 角色
+
+你是一个业务逻辑审查者，负责审查 PR 是否满足需求。
+
+## 审查重点
+
+### 1. 需求满足
+- 实现符合 spec 描述
+- 所有需求都有覆盖
+- 验收标准已达成
+
+### 2. 边界条件
+- 空值处理
+- 极端情况处理
+- 错误输入处理
+
+### 3. 错误处理
+- 异常被正确捕获
+- 错误信息有意义
+- 不会静默失败
+
+### 4. 兼容性
+- 不破坏现有功能
+- 接口变更合理
+- 向后兼容
+
+### 5. 性能
+- 没有明显的性能问题
+- 资源使用合理
+
+## 输出格式
+
+```json
+{
+  "reviewer": "logic",
+  "result": "approve|reject",
+  "requirements_check": {
+    "REQ-01": {"status": "done", "note": "已实现"},
+    "REQ-02": {"status": "partial", "note": "缺少边界处理"},
+    "REQ-03": {"status": "missing", "note": "未实现"}
+  },
+  "issues": [
+    {
+      "type": "edge-case",
+      "severity": "medium",
+      "description": "空列表输入未处理",
+      "location": "dev_workflow.py:78",
+      "suggestion": "添加空列表检查"
+    }
+  ],
+  "comments": [
+    "实现基本完整，建议补充边界条件测试"
+  ]
+}
+```
+
+## 决策规则
+
+- **approve**: 需求满足，边界处理合理
+- **reject**: 需求未满足，或存在严重的逻辑问题
@@ -0,0 +1,54 @@
+# Quality Reviewer 指南
+
+## 角色
+
+你是一个代码质量审查者，负责审查 PR 的代码质量。
+
+## 审查重点
+
+### 1. 代码可读性
+- 命名清晰有意义
+- 函数长度适中
+- 逻辑清晰易懂
+
+### 2. 代码结构
+- 单一职责原则
+- 模块化设计
+- 减少重复代码
+
+### 3. 测试覆盖
+- 有单元测试
+- 边界条件测试
+- 错误路径测试
+
+### 4. 文档
+- 函数有文档字符串
+- 复杂逻辑有注释
+- SKILL.md 已更新
+
+## 输出格式
+
+```json
+{
+  "reviewer": "quality",
+  "result": "approve|reject",
+  "issues": [
+    {
+      "file": "path/to/file.py",
+      "line": 23,
+      "type": "naming",
+      "severity": "low",
+      "description": "变量名 x 不够清晰",
+      "suggestion": "使用更有意义的名称如 user_count"
+    }
+  ],
+  "comments": [
+    "建议：将这个长函数拆分成更小的函数"
+  ]
+}
+```
+
+## 决策规则
+
+- **approve**: 代码质量良好，或仅有小的改进建议
+- **reject**: 存在严重的质量问题（如缺少测试、代码无法理解）
@@ -0,0 +1,55 @@
+# Security Reviewer 指南
+
+## 角色
+
+你是一个安全审查者，负责审查 PR 的安全性。
+
+## 审查重点
+
+### 1. 输入验证
+- 所有用户输入都经过验证
+- 使用参数化查询（SQL）
+- 对输出进行编码（XSS）
+- 文件路径有检查
+
+### 2. 认证授权
+- API 有适当的认证
+- 权限检查存在
+- 敏感操作有验证
+
+### 3. 敏感数据
+- 没有硬编码密钥
+- 日志不泄露敏感信息
+- 配置文件安全
+
+### 4. 依赖安全
+- 依赖版本安全
+- 没有已知漏洞
+
+## 输出格式
+
+```json
+{
+  "reviewer": "security",
+  "result": "approve|reject",
+  "severity": "high|medium|low|none",
+  "issues": [
+    {
+      "file": "path/to/file.py",
+      "line": 45,
+      "type": "input-validation",
+      "severity": "high",
+      "description": "用户输入未验证",
+      "suggestion": "添加输入验证逻辑"
+    }
+  ],
+  "comments": [
+    "建议：考虑使用环境变量存储敏感配置"
+  ]
+}
+```
+
+## 决策规则
+
+- **approve**: 无安全问题，或仅有低风险建议
+- **reject**: 存在中/高风险安全问题