From 0e773ec6e544818dcff8ecbb796036945f9d04d6 Mon Sep 17 00:00:00 2001 From: ULookup Date: Fri, 19 Jun 2026 18:28:15 +0000 Subject: [PATCH 1/6] docs: add Agent Review CI workflow design spec --- .../2026-06-19-agent-review-ci-design.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-19-agent-review-ci-design.md 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 From 809cfa38cd361fd6bc9d94e6e2842887bf134ee4 Mon Sep 17 00:00:00 2001 From: ULookup Date: Fri, 19 Jun 2026 18:30:05 +0000 Subject: [PATCH 2/6] docs: add Agent Review CI implementation plan --- .../plans/2026-06-19-agent-review-ci-plan.md | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-19-agent-review-ci-plan.md 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 中首次触发后自动出现） From 5edac8c280b1db7f00e1c6babd3659d0f4de71db Mon Sep 17 00:00:00 2001 From: ULookup Date: Fri, 19 Jun 2026 18:31:24 +0000 Subject: [PATCH 3/6] 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. --- .github/workflows/agent-review.yml | 60 ++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 .github/workflows/agent-review.yml diff --git a/.github/workflows/agent-review.yml b/.github/workflows/agent-review.yml new file mode 100644 index 00000000..9408df16 --- /dev/null +++ b/.github/workflows/agent-review.yml @@ -0,0 +1,60 @@ +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 From b7ece9df81ece6c5b22fc11ddd4231853ce88b6c Mon Sep 17 00:00:00 2001 From: ULookup Date: Fri, 19 Jun 2026 18:34:38 +0000 Subject: [PATCH 4/6] ci: configure Agent Review for DeepSeek API endpoint Update env vars for deepseek-v4-pro model via api.deepseek.com/anthropic --- .github/workflows/agent-review.yml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/workflows/agent-review.yml b/.github/workflows/agent-review.yml index 9408df16..63976816 100644 --- a/.github/workflows/agent-review.yml +++ b/.github/workflows/agent-review.yml @@ -25,7 +25,15 @@ jobs: continue-on-error: true uses: anthropics/claude-code-action@v1 env: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + 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 reviewing a pull request. Review the diff for: From 50c8fd3687f7526d2f0fd214a9f053c61b77efb5 Mon Sep 17 00:00:00 2001 From: ULookup Date: Fri, 19 Jun 2026 18:36:52 +0000 Subject: [PATCH 5/6] ci: align Agent Review prompt with superpowers code-reviewer template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Structured output: Strengths → Issues (Critical/Important/Minor) → Assessment with verdict. Added calibration guidance, project-specific architecture patterns, and C++/TS security checkpoints. --- .github/workflows/agent-review.yml | 71 ++++++++++++++++++++++++++---- 1 file changed, 63 insertions(+), 8 deletions(-) diff --git a/.github/workflows/agent-review.yml b/.github/workflows/agent-review.yml index 63976816..6ebeead3 100644 --- a/.github/workflows/agent-review.yml +++ b/.github/workflows/agent-review.yml @@ -36,17 +36,72 @@ jobs: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" with: prompt: | - You are reviewing a pull request. Review the diff for: + You are a Senior Code Reviewer with expertise in C++, TypeScript, + software architecture, and security best practices. Review this PR + against its diff. + + ## What to Check + + **Correctness:** - 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) + - Concurrency safety (data races, lock ordering, mutex hygiene) + - Exception safety (RAII, resource cleanup, no leaks on error paths) + - Logic errors (bounds checks, null/invalid deref, signed/unsigned) + + **Architecture:** + - Does the change follow existing project patterns? + - Sound design decisions, clean separation of concerns? + - For C++ DI patterns: PipelineManager::Dependencies, SubRunDeps + - Integrates cleanly with surrounding code? + + **Security:** + - Command injection (execvp, system, popen arguments) + - SSRF, path traversal, unsafe file operations + - XSS in webui code + + **Production readiness:** + - Edge cases handled? + - No hardcoded debug/test values? + - Migration-safe (no breaking DB schema without migration)? + + ## Calibration + + Categorize by ACTUAL severity. Not everything is Critical. + Acknowledge what was done well before listing issues — accurate + praise helps the author trust the rest of the feedback. + + ## Output Format + + ### Strengths + [What's well done? Be specific.] + + ### Issues + + #### Critical (Must Fix) + [Bugs, security vulnerabilities, data loss risks, broken builds] + + #### Important (Should Fix) + [Architecture problems, missing error handling, test gaps, unsafe patterns] + + #### Minor (Nice to Have) + [Code style, optimization opportunities, doc polish] + + For each issue: file:line, what's wrong, why it matters, how to fix. + + ### Assessment + + **Verdict:** [Approve | Request Changes] + **Reasoning:** [1-2 sentence technical assessment] + + ## Critical Rules + + DO: Be specific with file:line, explain WHY, acknowledge strengths, + give a clear verdict. - Post your review as a PR review. If you find CRITICAL or IMPORTANT issues, - use "request changes". If only minor issues or none, "approve". + DON'T: Say "looks good" without checking, mark nitpicks as Critical, + be vague, skip the verdict. - Use Chinese for the review body (this is a Chinese project). + Post your review as a PR review. Use Chinese for the review body. claude_args: "--max-turns 5" - name: Label ai-reviewed From 9142a5fc94bcdee2566c0b09e2d5b3cbc0be7dd3 Mon Sep 17 00:00:00 2001 From: ULookup Date: Fri, 19 Jun 2026 18:38:25 +0000 Subject: [PATCH 6/6] ci: merge everything-claude-code C++/security review patterns into Agent Review prompt Add cpp-reviewer checks (Rule of Five, RAII, const correctness, reserve, reinterpret_cast), security-reviewer false-positive awareness, confidence-based filtering (>80%), AI-generated code addendum, and summary table with per-severity counts. --- .github/workflows/agent-review.yml | 132 ++++++++++++++++++++--------- 1 file changed, 93 insertions(+), 39 deletions(-) diff --git a/.github/workflows/agent-review.yml b/.github/workflows/agent-review.yml index 6ebeead3..c8cead28 100644 --- a/.github/workflows/agent-review.yml +++ b/.github/workflows/agent-review.yml @@ -36,70 +36,124 @@ jobs: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" with: prompt: | - You are a Senior Code Reviewer with expertise in C++, TypeScript, - software architecture, and security best practices. Review this PR - against its diff. - - ## What to Check - - **Correctness:** - - Memory safety (use-after-free, double-delete, dangling references) - - Concurrency safety (data races, lock ordering, mutex hygiene) - - Exception safety (RAII, resource cleanup, no leaks on error paths) - - Logic errors (bounds checks, null/invalid deref, signed/unsigned) - - **Architecture:** + 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? - - Sound design decisions, clean separation of concerns? - - For C++ DI patterns: PipelineManager::Dependencies, SubRunDeps - - Integrates cleanly with surrounding code? + - For C++ DI: PipelineManager::Dependencies, SubRunDeps + - Sound design decisions, clean separation of concerns + - Integrates cleanly with surrounding code - **Security:** - - Command injection (execvp, system, popen arguments) - - SSRF, path traversal, unsafe file operations - - XSS in webui 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 - **Production readiness:** + ### 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 - ## Calibration + 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 - Categorize by ACTUAL severity. Not everything is Critical. - Acknowledge what was done well before listing issues — accurate - praise helps the author trust the rest of the feedback. + ## 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.] + [What's well done? Be specific. Accurate praise helps the author trust the rest.] ### Issues - #### Critical (Must Fix) - [Bugs, security vulnerabilities, data loss risks, broken builds] + #### 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] - #### Important (Should Fix) - [Architecture problems, missing error handling, test gaps, unsafe patterns] + #### Medium (Consider Fixing) + [Performance, code quality, production readiness] - #### Minor (Nice to Have) + #### Low (Nice to Have) [Code style, optimization opportunities, doc polish] - For each issue: file:line, what's wrong, why it matters, how to fix. + For each issue: `file:line`, what's wrong, why it matters, how to fix (show code). - ### Assessment + ### 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] - ## Critical Rules - - DO: Be specific with file:line, explain WHY, acknowledge strengths, - give a clear verdict. + ## Approval Criteria - DON'T: Say "looks good" without checking, mark nitpicks as Critical, - be vague, skip the verdict. + - **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"