diff --git a/.github/workflows/agent-review.yml b/.github/workflows/agent-review.yml new file mode 100644 index 00000000..c8cead28 --- /dev/null +++ b/.github/workflows/agent-review.yml @@ -0,0 +1,177 @@ +name: Agent Review + +on: + pull_request: + paths: + - 'libs/core/**' + - 'libs/loop/**' + - 'libs/app/**' + - 'libs/worldbuilding/**' + - 'libs/tools/**' + - 'libs/runtime/**' + - 'webui/**' + +jobs: + agent-review: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v4 + + - id: review + continue-on-error: true + uses: anthropics/claude-code-action@v1 + env: + ANTHROPIC_AUTH_TOKEN: ${{ secrets.ANTHROPIC_AUTH_TOKEN }} + ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic + ANTHROPIC_DEFAULT_HAIKU_MODEL: deepseek-v4-pro + ANTHROPIC_DEFAULT_OPUS_MODEL: deepseek-v4-pro + ANTHROPIC_DEFAULT_SONNET_MODEL: deepseek-v4-pro + ANTHROPIC_MODEL: deepseek-v4-pro + ANTHROPIC_REASONING_MODEL: deepseek-v4-pro + API_TIMEOUT_MS: "3000000" + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" + with: + prompt: | + You are a Senior Code Reviewer with expertise in modern C++ (C++17/20), + TypeScript, software architecture, and security best practices. + Review this pull request against its diff. + + ## Confidence-Based Filtering + + **Do not flood the review with noise.** Apply these filters: + - **Report** only if >80% confident it is a real issue + - **Skip** stylistic preferences unless they violate project conventions + - **Skip** issues in unchanged code unless CRITICAL security problems + - **Consolidate** similar issues into one finding + - **Prioritize** issues that could cause bugs, security vulnerabilities, or data loss + + ## Review Checklist + + ### CRITICAL — Memory Safety (C++) + - Raw `new`/`delete` — use `std::unique_ptr` or `std::shared_ptr` + - Buffer overflows — C-style arrays, `strcpy`, `sprintf` without bounds + - Use-after-free — dangling pointers, invalidated iterators + - Uninitialized variables — reading before assignment + - Memory leaks — missing RAII, resources not tied to object lifetime + - Null dereference — pointer access without null check + + ### CRITICAL — Security + - Hardcoded credentials — API keys, passwords, tokens, connection strings in source + - Command injection — unvalidated input in `execvp`, `system()`, `popen()` + - Format string attacks — user input in `printf` format string + - Integer overflow — unchecked arithmetic on untrusted input + - SQL injection — string concatenation in queries instead of parameterized queries + - Path traversal — user-controlled file paths without sanitization + - XSS vulnerabilities — unescaped user input in webui code + - Unsafe casts — `reinterpret_cast` without justification + + ### HIGH — Concurrency (C++) + - Data races — shared mutable state without synchronization + - Deadlocks — multiple mutexes locked in inconsistent order + - Missing lock guards — manual `lock()`/`unlock()` instead of `std::lock_guard` + - Detached threads — `std::thread` without `join()` or `detach()` + + ### HIGH — C++ Code Quality + - No RAII — manual resource management (`malloc`/`free`, raw handles) + - Rule of Five violations — incomplete special member functions (destructor without move) + - C-style code — `malloc`, C arrays, `typedef` instead of `using` + - Large functions > 50 lines, deep nesting > 4 levels + - Missing exception safety — no cleanup on error paths + - `const` correctness — missing `const` on methods, parameters, references + - Include hygiene — missing include guards, unnecessary includes, namespace pollution + + ### HIGH — Architecture + - Does the change follow existing project patterns? + - For C++ DI: PipelineManager::Dependencies, SubRunDeps + - Sound design decisions, clean separation of concerns + - Integrates cleanly with surrounding code + + ### MEDIUM — Performance (C++) + - Unnecessary copies — pass large objects by value instead of `const&` + - Missing move semantics — not using `std::move` for sink parameters + - String concatenation in loops — use `std::ostringstream` or `reserve()` + - Missing `reserve()` — known-size vector without pre-allocation + + ### MEDIUM — Production Readiness + - Edge cases handled? + - No hardcoded debug/test values? + - Migration-safe (no breaking DB schema without migration)? + - Error handling — unhandled promise rejections, empty catch blocks + + ## AI-Generated Code Review Addendum + + This project uses AI-generated code. Prioritize: + 1. Behavioral regressions and edge-case handling + 2. Security assumptions and trust boundaries + 3. Hidden coupling or accidental architecture drift + 4. Unnecessary model-cost-inducing complexity + + ## Common False Positives + + - Environment variables in `.env.example` (not actual secrets) + - Test credentials in test files (if clearly marked) + - Public API keys (if actually meant to be public) + **Always verify context before flagging.** + + ## Output Format + + ### Strengths + [What's well done? Be specific. Accurate praise helps the author trust the rest.] + + ### Issues + + #### Critical (Must Fix — Block Merge) + [Bugs, security vulnerabilities, data loss risks, memory corruption] + + #### High (Should Fix — Block Merge) + [Architecture problems, unsafe patterns, missing error handling, test gaps] + + #### Medium (Consider Fixing) + [Performance, code quality, production readiness] + + #### Low (Nice to Have) + [Code style, optimization opportunities, doc polish] + + For each issue: `file:line`, what's wrong, why it matters, how to fix (show code). + + ### Summary Table + + | Severity | Count | Status | + |----------|-------|--------| + | CRITICAL | N | pass/warn/fail | + | HIGH | N | pass/warn/fail | + | MEDIUM | N | info | + | LOW | N | note | + + **Verdict:** [Approve | Request Changes] + **Reasoning:** [1-2 sentence technical assessment] + + ## Approval Criteria + + - **Approve**: No CRITICAL or HIGH issues + - **Request Changes**: Any CRITICAL or HIGH issue found + + Post your review as a PR review. Use Chinese for the review body. + claude_args: "--max-turns 5" + + - name: Label ai-reviewed + if: steps.review.outcome == 'success' + run: gh pr edit --add-label "ai-reviewed" + env: + GH_TOKEN: ${{ github.token }} + + - name: Label needs-changes + if: steps.review.outcome == 'failure' + run: gh pr edit --add-label "needs-changes" + env: + GH_TOKEN: ${{ github.token }} + + - name: Block merge if needs changes + if: steps.review.outcome == 'failure' + run: | + echo "Agent review found issues — merge blocked" + exit 1 diff --git a/docs/superpowers/plans/2026-06-19-agent-review-ci-plan.md b/docs/superpowers/plans/2026-06-19-agent-review-ci-plan.md new file mode 100644 index 00000000..635acae1 --- /dev/null +++ b/docs/superpowers/plans/2026-06-19-agent-review-ci-plan.md @@ -0,0 +1,117 @@ +# Agent Review CI — 实现计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 新建一个 GitHub Actions workflow,在 PR 涉及核心源码时自动触发 Anthropic Claude Code 审查,以 PR Review 形式提交结果,自动打标签,status check 阻挡 merge。 + +**Architecture:** 单文件 `.github/workflows/agent-review.yml`,1 个 job 3 个 step:review、打标签、fail check。与现有 `ci.yml` 并行,互不影响。 + +**Tech Stack:** GitHub Actions, anthropics/claude-code-action@v1, gh CLI + +--- + +## 文件职责说明 + +| 文件 | 改动内容 | +|------|----------| +| `.github/workflows/agent-review.yml` | 新建 — 完整 workflow 文件 | + +--- + +### Task 1: 创建 agent-review.yml + +**Files:** +- Create: `.github/workflows/agent-review.yml` + +- [ ] **Step 1: 创建 workflow 文件** + +```yaml +name: Agent Review + +on: + pull_request: + paths: + - 'libs/core/**' + - 'libs/loop/**' + - 'libs/app/**' + - 'libs/worldbuilding/**' + - 'libs/tools/**' + - 'libs/runtime/**' + - 'webui/**' + +jobs: + agent-review: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v4 + + - id: review + continue-on-error: true + uses: anthropics/claude-code-action@v1 + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + with: + prompt: | + You are reviewing a pull request. Review the diff for: + - Memory safety (use-after-free, double-delete, dangling references) + - Concurrency safety (data races, lock ordering) + - Exception safety (RAII, resource cleanup) + - Architecture consistency (DI patterns, file boundaries) + - Security vulnerabilities (SSRF, command injection, XSS) + + Post your review as a PR review. If you find CRITICAL or IMPORTANT issues, + use "request changes". If only minor issues or none, "approve". + + Use Chinese for the review body (this is a Chinese project). + claude_args: "--max-turns 5" + + - name: Label ai-reviewed + if: steps.review.outcome == 'success' + run: gh pr edit --add-label "ai-reviewed" + env: + GH_TOKEN: ${{ github.token }} + + - name: Label needs-changes + if: steps.review.outcome == 'failure' + run: gh pr edit --add-label "needs-changes" + env: + GH_TOKEN: ${{ github.token }} + + - name: Block merge if needs changes + if: steps.review.outcome == 'failure' + run: | + echo "Agent review found issues — merge blocked" + exit 1 +``` + +- [ ] **Step 2: 验证 YAML 语法** + +```bash +cd /home/icepop/Merak && python3 -c "import yaml; yaml.safe_load(open('.github/workflows/agent-review.yml'))" && echo "YAML valid" +``` +Expected: `YAML valid` + +- [ ] **Step 3: 提交** + +```bash +cd /home/icepop/Merak && git add -f .github/workflows/agent-review.yml && git commit -m "ci: add Agent Review workflow for core source PRs + +Automatically triggers anthropics/claude-code-action on PRs touching +libs/{core,loop,app,worldbuilding,tools,runtime}/** or webui/**. +Posts PR review, adds ai-reviewed/needs-changes label, and blocks +merge via status check when issues are found." +``` + +--- + +## Post-Deploy + +PR merge 后需要仓库管理员做一次配置: + +1. 在 GitHub repo Settings → Secrets → Actions 中添加 `ANTHROPIC_API_KEY` +2. 在 Settings → Branches → Branch protection rules → `main` 中勾选 `Agent Review` 作为 required status check +3. 手动创建 `ai-reviewed` 和 `needs-changes` 两个标签(或在 PR 中首次触发后自动出现) diff --git a/docs/superpowers/specs/2026-06-19-agent-review-ci-design.md b/docs/superpowers/specs/2026-06-19-agent-review-ci-design.md new file mode 100644 index 00000000..7b027580 --- /dev/null +++ b/docs/superpowers/specs/2026-06-19-agent-review-ci-design.md @@ -0,0 +1,71 @@ +# PR Agent Review CI — 设计文档 + +> **For agentic workers:** 实现计划编写时需要将此 spec 转化为具体任务。 + +**Goal:** 在涉及核心源码改动的 PR 中,自动触发 Anthropic Claude 官方 Action 进行代码审查,以 PR Review 形式贴评论,同时创建 status check block merge,根据结果自动打标签。 + +**Architecture:** 新增一个独立 GitHub Actions workflow(`agent-review.yml`),与现有 `ci.yml` 并行运行。使用 `anthropics/claude-code-action` 官方 Action 进行审查,通过 `gh` CLI 操作 PR review 和标签。 + +**Tech Stack:** GitHub Actions, anthropics/claude-code-action, gh CLI + +--- + +## 触发条件 + +```yaml +on: + pull_request: + paths: + - 'libs/core/**' + - 'libs/loop/**' + - 'libs/app/**' + - 'libs/worldbuilding/**' + - 'libs/tools/**' + - 'libs/runtime/**' + - 'webui/**' +``` + +只在上述路径有文件改动时触发,避免 docs/config 等修改浪费审阅资源。 + +## Review 流程 + +``` +PR push → paths match → agent-review job 启动 + → anthropics/claude-code-action 审查 diff + → 通过 → gh pr review approve + → gh pr edit --add-label "ai-reviewed" + → 不通过 → gh pr review request-changes + → gh pr edit --add-label "needs-changes" +``` + +## Job 规格 + +- **Runs-on:** ubuntu-24.04(与现有 CI 一致) +- **Timeout:** 15 minutes(LLM 调用时间不可控,给足余量) +- **Permissions:** `pull-requests: write`(写 review)+ `contents: read`(读代码) + +## 标签 + +| 标签 | 含义 | +|------|------| +| `ai-reviewed` | Agent review 通过,无 Critical/Important 问题 | +| `needs-changes` | 存在 Critical 或 Important 级别问题,需修复后重新触发 | + +## Status Check + +Job 名称 `Agent Review`,失败时阻挡 merge。需要仓库开启 branch protection,勾选此 check 作为 required。 + +## 审查标准 + +Agent 审查时关注: +- 内存安全(use-after-free, double-delete, dangling ref) +- 并发安全(data race, lock ordering) +- 异常安全(RAII, resource cleanup) +- 架构一致(是否遵循现有 DI 模式、文件边界) +- 安全漏洞(SSRF, command injection, XSS) + +## 与现有 CI 的关系 + +- 不改动 `ci.yml` +- 与 `build-cpp` / `build-webui` 并行执行 +- 两者独立——build 失败不跳过 review,review 失败不跳过 build