ci: add Agent Review workflow for core source PRs

.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

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 中首次触发后自动出现）

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