akg-review

name	akg-review
description	提交前代码自审工具。检查 rebase 冲突、代码规范（ruff/bandit）、危险函数、SPEC.md 合规性。 生成审查报告写入 .tmp/review/。当用户输入 /akg-review 或要求代码审查、提交前检查时使用。
argument-hint	可选：TARGET_BRANCH（目标分支）。未指定时自动探测并请求确认。 示例：/akg-review /akg-review origin/br_agents /akg-review origin/master

AKG Review - 提交前代码自审

你是代码自审助手。使用现有工具（ruff、git）+ 自定义脚本， 在提交前检查 rebase 冲突、代码规范、危险函数、SPEC.md 合规性。

⛔ 核心规则

1. 所有产物写入 $AKG_AGENTS_DIR/.tmp/review/。
2. 优先使用现成工具：ruff（代码规范）、git（rebase 检查）。
3. 自定义检查仅覆盖项目特定规则（危险函数、包名、SPEC.md）。
4. 不执行任何修改，只检查和报告。

依赖检查（自动）：

• ruff - 如未安装，自动执行 pip install ruff
• git - 系统自带

---

流程

Step 0: 依赖检查（自动安装）

for tool in ruff bandit; do
  if ! command -v $tool &> /dev/null; then
    echo "$tool 未安装，正在安装..."
    pip install $tool -q
  fi
done

MYPY_AVAILABLE=$(command -v mypy &> /dev/null && echo "yes" || echo "no")
VULTURE_AVAILABLE=$(command -v vulture &> /dev/null && echo "yes" || echo "no")

REVIEW_TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/akg_review_XXXXXX")

Step 1: 确定目标分支（需用户确认）

缓存文件：$AKG_AGENTS_DIR/.tmp/review_last.txt，记录上次确认过的参数。

CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
TARGET_BRANCH=${ARGUMENTS:-}
REVIEW_CACHE="$AKG_AGENTS_DIR/.tmp/review_last.txt"

确定 TARGET_BRANCH 的优先级（依次尝试，取第一个有效值）：

1. 用户本次指定的参数（$ARGUMENTS）
2. 缓存文件中记录的上次值（$REVIEW_CACHE）
3. 自动探测远程分支

# 如果用户未指定，尝试读缓存
if [ -z "$TARGET_BRANCH" ] && [ -f "$REVIEW_CACHE" ]; then
  CACHED_TARGET=$(grep '^target_branch=' "$REVIEW_CACHE" | cut -d= -f2)
  if [ -n "$CACHED_TARGET" ] && git rev-parse --verify "$CACHED_TARGET" &>/dev/null; then
    TARGET_BRANCH="$CACHED_TARGET"
  fi
fi

# 如果仍为空，自动探测
if [ -z "$TARGET_BRANCH" ]; then
  for candidate in origin/br_agents $(git branch -r | grep '/br_agents$' | head -1 | tr -d ' '); do
    if git rev-parse --verify "$candidate" &>/dev/null; then
      TARGET_BRANCH="$candidate"
      break
    fi
  done
fi

必须向用户展示以下信息并等待确认后才能继续：

📋 审查参数确认

• 当前分支: $CURRENT_BRANCH
• 目标分支: $TARGET_BRANCH （来源：用户指定 / 上次缓存 / 自动探测）
• 变更文件数: git diff $TARGET_BRANCH...HEAD --name-only --relative | wc -l
• 变更 .py 文件数: git diff $TARGET_BRANCH...HEAD --name-only --diff-filter=ACMR --relative | grep '\.py$' | wc -l

确认以上信息正确？(y/n)，或指定其他目标分支。

⛔ 如果目标分支不存在或用户未确认，停止流程，不要猜测或 fallback。

确认后保存本次配置到缓存，并收集变更文件：

mkdir -p "$(dirname "$REVIEW_CACHE")"
cat > "$REVIEW_CACHE" <<EOF
target_branch=$TARGET_BRANCH
current_branch=$CURRENT_BRANCH
timestamp=$(date +%Y%m%d_%H%M%S)
EOF

CHANGED_FILES_LIST="$REVIEW_TMP_DIR/changed_files.txt"
git diff $TARGET_BRANCH...HEAD --name-only --diff-filter=ACMR --relative | grep '\.py$' > "$CHANGED_FILES_LIST" || true
FILE_COUNT=$(wc -l < "$CHANGED_FILES_LIST" | tr -d ' ')

⛔ 后续所有工具必须通过 xargs < "$CHANGED_FILES_LIST" 或 cat "$CHANGED_FILES_LIST" 传入文件，禁止用 shell 变量 $CHANGED_FILES 拼接命令（LLM 容易将其整体加引号导致路径错误）。

---

Step 2: Rebase 冲突检查

python $AKG_AGENTS_DIR/.opencode/skills/akg-review/scripts/check_rebase.py \
  --target-branch "$TARGET_BRANCH" \
  --current-branch "$CURRENT_BRANCH" \
  --repo-path "$AKG_AGENTS_DIR" \
  --output "$REVIEW_TMP_DIR/rebase_result.json"

---

Step 3: 代码规范检查（多工具组合）

3a. Ruff 检查（快速、全面）

if [ "$FILE_COUNT" -gt 0 ]; then
  xargs ruff check \
    --config pyproject.toml \
    --output-format=json \
    < "$CHANGED_FILES_LIST" \
    > "$REVIEW_TMP_DIR/ruff_result.json" 2>&1 || true
fi

检测：语法、导入、命名、复杂度（配置已 ignore=C901）

3b. Bandit 安全检查（危险函数、SQL 注入等）

if [ "$FILE_COUNT" -gt 0 ]; then
  xargs bandit \
    --format json \
    --output "$REVIEW_TMP_DIR/bandit_result.json" \
    < "$CHANGED_FILES_LIST" \
    2>&1 || true
fi

检测：exec/eval、hardcoded passwords、SQL injection、shell injection

3c. Mypy 类型检查（可选，如已安装）

if [ "$MYPY_AVAILABLE" = "yes" ] && [ "$FILE_COUNT" -gt 0 ]; then
  xargs mypy \
    --no-error-summary \
    --show-column-numbers \
    < "$CHANGED_FILES_LIST" \
    > "$REVIEW_TMP_DIR/mypy_result.txt" 2>&1 || true
fi

3d. Vulture 死代码检测（可选，如已安装）

if [ "$VULTURE_AVAILABLE" = "yes" ] && [ "$FILE_COUNT" -gt 0 ]; then
  xargs vulture \
    --min-confidence 80 \
    < "$CHANGED_FILES_LIST" \
    > "$REVIEW_TMP_DIR/vulture_result.txt" 2>&1 || true
fi

3e. 自定义规则检查（项目特定）

if [ "$FILE_COUNT" -gt 0 ]; then
  CHANGED_FILES_INLINE=$(paste -sd ' ' "$CHANGED_FILES_LIST")
  python $AKG_AGENTS_DIR/.opencode/skills/akg-review/scripts/check_code_style.py \
    --files "$CHANGED_FILES_INLINE" \
    --repo-path "$AKG_AGENTS_DIR" \
    --output "$REVIEW_TMP_DIR/custom_style_result.json"
fi

自定义检查（4 条项目特定规则）：

规则	说明	级别
CODE-001	License 头（Apache 2.0，只需存在即可）	error
CODE-002	从 core/ 导入（建议迁移到 core_v2/）	warning
CODE-004	参数值不规范（backend/dsl/arch，跳过 f-string 占位符）	error
CODE-013	错误包名（ai_kernel_generator）	error
CODE-010	TODO/FIXME 注释	info

---

Step 4: SPEC.md 合规性检查

if [ "$FILE_COUNT" -gt 0 ]; then
  CHANGED_FILES_INLINE=$(paste -sd ' ' "$CHANGED_FILES_LIST")
  python $AKG_AGENTS_DIR/.opencode/skills/akg-review/scripts/check_spec_compliance.py \
    --files "$CHANGED_FILES_INLINE" \
    --base-branch "$TARGET_BRANCH" \
    --repo-path "$AKG_AGENTS_DIR" \
    --output "$REVIEW_TMP_DIR/spec_result.json"
fi

检查规则（7 条架构约束）：

规则	说明	级别
SPEC-001	core_v2/ 中有业务逻辑	error
SPEC-002	op/ 中有框架代码	error
SPEC-003	core_v2/tests/ 中有新测试	error
SPEC-004	新目录缺 __init__.py	error
SPEC-005	新增模块未更新 SPEC.md	warning
SPEC-006	修改接口未更新 SPEC.md	warning
SPEC-007	测试缺 marker（op-st/bench）	warning

---

Step 5: 生成报告

mkdir -p $AKG_AGENTS_DIR/.tmp/review

python $AKG_AGENTS_DIR/.opencode/skills/akg-review/scripts/generate_report.py \
  --current-branch "$CURRENT_BRANCH" \
  --target-branch "$TARGET_BRANCH" \
  --rebase-result "$REVIEW_TMP_DIR/rebase_result.json" \
  --ruff-result "$REVIEW_TMP_DIR/ruff_result.json" \
  --bandit-result "$REVIEW_TMP_DIR/bandit_result.json" \
  --custom-style-result "$REVIEW_TMP_DIR/custom_style_result.json" \
  --spec-result "$REVIEW_TMP_DIR/spec_result.json" \
  --output-dir "$AKG_AGENTS_DIR/.tmp/review" \
  --repo-path "$AKG_AGENTS_DIR"

# 清理临时目录
rm -rf "$REVIEW_TMP_DIR"

报告格式：

# AKG Code Review Report

**分支**: <current> → <target>
**状态**: ✅ PASS / ⚠️ WARNING / ❌ FAIL

## 检查概览

| 检查项 | 状态 | 错误 | 警告 |
|--------|------|------|------|
| Rebase 冲突 | ✅/❌ | N | 0 |
| Ruff 检查 | ✅/❌ | N | N |
| 自定义规则 | ✅/❌ | N | 0 |
| SPEC.md 合规 | ✅/❌ | N | N |

## 主要问题

1. [CODE-012] 使用危险函数 exec(): ...
2. [SPEC-001] 在 core_v2/ 中写业务逻辑: ...
...

## 修复建议

...

---

Step 6: 展示结果

展示审查摘要 + PR Checklist（用于贴到 PR）：

代码审查完成

分支: <current> → <target> 状态: ✅ PASS / ⚠️ WARNING / ❌ FAIL

检查结果:

• Rebase: ✅ 无冲突 / ❌ N 个冲突
• Ruff: ✅ 通过 / ❌ N 个问题
• Bandit: ✅ 通过 / ❌ N 个安全问题
• 自定义: ✅ 通过 / ❌ N 个错误
• SPEC: ✅ 通过 / ❌ N 个错误

文件:

• 详细报告: .tmp/review/review_<branch>_<ts>.md
• PR Checklist: .tmp/review/checklist_<branch>_<ts>.md 👈 复制此文件内容到 PR 描述

<如果有错误，列出前 3 个>

PR Checklist 示例（.tmp/review/checklist_*.md）：

## Pre-submit Review Checklist

**Branch**: `feature/xxx` → `origin/br_agents`
**Review Time**: 2026-04-02 16:30
**Status**: ✅ PASS

### Checks Performed

- [x] Rebase conflict check
- [x] Code style check (ruff + bandit + custom)
- [x] SPEC.md compliance check

### Summary

- **Errors**: 0
- **Warnings**: 2
- **Files Changed**: 5

**Result**: ✅ All checks passed. Safe to merge.

---
*Generated by `/akg-review`*

使用方式：

1. 运行 /akg-review
2. 复制 .tmp/review/checklist_*.md 的内容
3. 粘贴到 PR 描述的末尾

---

工具分工

工具	检查内容	安装
ruff	语法、导入、命名、复杂度、行长度	自动
bandit	安全漏洞（exec/eval/SQL 注入/密码硬编码）	自动
mypy	类型检查	可选
vulture	死代码检测	可选
自定义脚本	License、包名、参数值、SPEC.md	内置
git worktree	Rebase 冲突（用 --detach 避免分支锁定）	系统自带

---

自定义规则详解

CODE-001: License 头

检测: Apache 2.0 License，只需存在即可（不检查年份）

---

CODE-002: 从 core/ 导入

检测: from akg_agents.core. → 建议改为 core_v2.（warning 级别，迁移期间不强求）

---

CODE-013: 错误包名

检测: ai_kernel_generator, kernel_generator, akg_agent（少 s）

示例:

# ❌ 错误
from ai_kernel_generator.core import Coder

# ✅ 正确
from akg_agents.core_v2.agents import AgentBase

---

SPEC-001/002: 代码放置位置

• core_v2/: 只放框架代码（Agent 基类、Workflow、LLM）
• op/: 只放算子场景代码（KernelGen、验证器）
• cli/: 只放命令行入口

检测: 关键词匹配（op_name, kernel code, verify kernel 等）

---

修复建议

遇到代码格式问题时，推荐修复方式：

问题类型	修复工具	说明
E501（行太长）、W291/W293（空白字符）	autopep8 --in-place --max-line-length=119	自动修复大部分格式问题
E402（import 顺序）、F841（未使用变量）等	LLM 或手动修复	需要理解代码逻辑
C901（函数复杂度）	建议暂时跳过	需要重构，建议后续处理

常用命令：

# 使用 autopep8 修复格式（推荐优先使用）
git diff origin/br_agents...HEAD --name-only --diff-filter=ACMR --relative | grep '\.py$' | xargs autopep8 --in-place --max-line-length=119

# 使用 ruff 检查（配置文件: pyproject.toml, max-line-length=119, ignore=C901）
git diff origin/br_agents...HEAD --name-only --diff-filter=ACMR --relative | grep '\.py$' | xargs ruff check --config pyproject.toml

---

注意事项

1. autopep8 优先: 大部分格式问题（E501/W291/W293）可用 autopep8 自动修复，效率高。
2. ruff 检查: 通用规范由 ruff 检查（配置 max-line-length=119, ignore=C901）。
3. 自定义精简: 只检查项目特定规则（License 头、包名、参数值、架构约束）。
4. Bandit 分级: HIGH/MEDIUM 算 error，LOW 算 warning。
5. 独立运行: 各阶段独立，一个失败不影响其他。
6. 只读操作: 不修改代码，只生成报告。