kagura-ai/kagura-code-reviewer

# kagura-code-reviewer [](https://pypi.org/project/kagura-code-reviewer/) [](https://pypi.org/project/kagura-code-reviewer/) [](LICENSE) [](https://github.com/kagura-ai/kagura-code-reviewer/actions/workflows/ci.yml) [](https://codecov.io/gh/kagura-ai/kagura-code-reviewer) **在您的 git diff 上进行专业级代码审查，无需消耗任何 Anthropic 费用。** 本地（或云端）的 Ollama 模型会并行启动多角度 finder，通过对抗式多数投票验证每一个发现，去重后返回带有 `green`（绿）/ `yellow`（黄）/ `red`（红）结论的排名 Markdown/JSON 报告，您可以用它来作为 CI 的门控。 专为 Claude Code 提供的免费、基于 Ollama 的代码审查工具。审查的“大脑”运行在 Ollama 模型（云端或本地）上，因此审查过程**完全不消耗 Anthropic 费用**。配套的 slash command（`/kagura-code-reviewer`）集成了 Kagura Memory：外部 Claude 会话会检索过往的规范和发现，将其作为上下文传递给 CLI，然后在审查完成后将持久化的知识写回。该 CLI 本身是一个独立工具——它不会直接调用 Kagura Memory。 ## 工作原理 ``` Claude Code (outer session) │ /kagura-code-reviewer slash command │ 1. Recalls past findings from Kagura Memory (trust_tier: trusted filter) │ 2. Writes assembled context to /tmp/kcr-ctx.md │ 3. Invokes CLI ──────────────────────────────────────────────────────┐ │ │ └── Presents report to user ←── 5. Writes durable knowledge back │ ▼ kagura-code-reviewer CLI │ git diff (base...HEAD) │ sandboxed repo tools │ read_file / grep / git ▼ Ollama (local or cloud) │ agentic review loop ▼ Markdown / JSON report exit 0 = clean exit 1 = blocking issues ``` ## 安装 ``` pip install kagura-code-reviewer ``` ### 系统前置条件 pip **不会**安装这些内容——您必须单独进行设置： - 正在运行的 **Ollama daemon**，且至少拉取了一个模型。 默认的云端别名使用 `qwen3-coder:480b-cloud`；默认的本地别名使用 `qwen2.5-coder:7b`。 拉取命令：`ollama pull qwen2.5-coder:7b` - **`claude` CLI** —— 仅在 `/kagura-code-reviewer` slash command 工作流中需要。 安装命令：`npm install -g @anthropic-ai/claude-code` ## 快速开始 ``` # 审查当前分支与 main 的对比（Markdown 输出到 stdout） kagura-code-reviewer --base main # 将报告以 JSON 格式写入文件 kagura-code-reviewer --base main --format json --out report.json # 使用本地模型别名（更快、更小） kagura-code-reviewer --local # 将审查限制在特定路径 kagura-code-reviewer --base main --paths src/foo.py --paths tests/test_foo.py # 通过 URL 审查 GitHub PR（开放或已关闭/已合并）——在 PR 仓库的 clone 中运行 kagura-code-reviewer --pr https://github.com/owner/repo/pull/123 # 将审查进度流式传输到 stderr（这样缓慢的本地运行就不会看起来像是卡住了） kagura-code-reviewer --base main -v ``` **进度 (`-v`/`--verbose`)：** 将阶段进度（finder → 去重 → 针对每个候选者的验证 `i/N` → 最终计数）流式传输到 **stderr**，这样即使本地模型运行缓慢，也不会看起来像是卡住了。stdout / `--out`（md/json 报告）保持干净且管道安全，因此 `--format json --out` 不会受到影响。 **审查 GitHub PR (`--pr`)：** 传入一个 PR URL，该工具会将该 PR 不可变的 head ref（`refs/pull//head`）拉取到一个隔离的 git worktree 中，像本地 diff 一样对其进行审查，并在之后进行清理（传入 `--keep` 可保留 worktree 以供调试）。它适用于**已打开和已关闭/已合并**的 PR——即使源分支被删除了——也同样适用于 fork 仓库的 PR。要求：**在该 PR 仓库的本地克隆中**运行（ref 是从其 `origin` 获取的——如果您的规范远程仓库使用了不同的名称，例如 `upstream`，请使用 `--pr-remote `），并且需要安装 `gh` 并完成认证（用于 PR 元数据和私有仓库认证）。`--pr` 不能与 `--base`/`--head`/`--repo` 组合使用；但可以与 `--cloud`、`--provider` 等参数搭配使用。（从无关的检出目录中审查任意 PR 是计划中的后续功能。） **退出代码：** - `0` —— 没有阻塞性问题（仅包含 INFO / LOW / MEDIUM 严重级别） - `1` —— 一个或多个 HIGH 或 CRITICAL 发现 - `2` —— git 错误（错误的 ref、不是 git 仓库等） ### 输出示例 ``` # Code Review ## [CRITICAL] 当 orders 为空时出现 IndexError（正确性） - **Where:** `orders.py:14` - **Why:** latest_order accesses ordered[-1] without verifying the list is non-empty, causing IndexError when orders is empty. - **Fix:** Guard the empty case before indexing. - **Seen by:** correctness-linescan, cross-file, removed-behavior ×5; votes: CONFIRMED 2; conf 1.00 ``` 每个发现都包含来源（`Seen by:` —— 表示哪些 finder 视角发现了它）、对抗式验证的 `votes` 以及 `conf` 分数，因此您可以使用 `--min-confidence` 过滤干扰信息。 ### 机器可读输出契约 `--format json` 会为下游自动化提供一个稳定且带版本的封装（无需抓取 Markdown）。为了向后兼容，`findings` 键保持在顶层；`schema_version` / `verdict` / `summary` 则是附加内容。 ``` { "schema_version": 1, "verdict": "green", // green = clean, yellow = non-blocking only, red = blocking finding "summary": { "total": 0, "blocking": 0, // findings with severity >= HIGH "by_severity": {}, // {"HIGH": 2, "LOW": 1, ...} "incomplete": false // true if the review did not finish (a "meta" finding is present) }, "findings": [ /* per-finding: dimension, severity, file, line, title, rationale, suggestion, angles, votes, merge_count, confidence */ ] } ``` **结论 ↔ 退出代码不变式：** `verdict == "red"` **当且仅当**退出代码为 `1`。 `green` 和 `yellow` 都会以 `0` 退出（使用 `verdict` 来区分完全无问题和警告性建议）。`summary.incomplete` 让执行器能够区分“审查未能运行”和“存在真正的阻塞性发现”。 ## Slash command / Kagura Memory 工作流 有两种方法可以将 `/kagura-code-reviewer` slash command 引入 Claude Code。 ### 选项 A —— 作为 Claude Code 插件安装（推荐） 在 Claude Code 内部添加 Kagura marketplace 并安装该插件： ``` /plugin marketplace add kagura-ai/kagura-code-reviewer /plugin install kagura-code-reviewer@kagura-code-reviewer ``` `/kagura-code-reviewer` 随后将出现在所有项目的技能列表中——无需在每个仓库中进行拷贝。（您仍然需要将 `kagura-code-reviewer` CLI 放在您的 `PATH` 中；可以使用 `pip install kagura-code-reviewer` 进行安装。） ### 选项 B —— 将内置命令拷贝到单个项目中 如果您安装了 PyPI 包，并且只想在单个仓库中使用该命令，请将内置命令拷贝到该项目的 `.claude/commands/` 目录中： ``` # 将内置的 slash command 复制到您的项目中，以便 Claude Code 可以运行 /kagura-code-reviewer mkdir -p .claude/commands cp "$(python -c "import kagura_code_reviewer, pathlib; print(pathlib.Path(kagura_code_reviewer.__file__).parent / 'commands' / 'kagura-code-reviewer.md')")" .claude/commands/ ``` 然后在 Claude Code 内部，运行： ``` /kagura-code-reviewer ``` 该命令将： 1. 从 Kagura Memory 检索此仓库锁定的审查策略和过往发现（过滤条件为 `trust_tier: trusted`，以防 prompt 注入）。 2. 通过 `--context-file` 将组合好的上下文传递给 CLI。 3. 展示报告。 4. 将新的持久化规范和常见模式写回 memory。 ### Memory 安全契约 Memory 是基础依据，而非权威。CLI 仅通过 `--context-file` 接收字符串，并且**无法重新验证其来源**，因此调用者需负责提供以下保证（纵深防御）： 1. **使用 `trust_tier: "trusted"` 进行检索** —— 必需。它会排除外部/connector 导入的 memory（Slack/Discord 等），这些 memory 可能携带注入的指令（OWASP LLM01/LLM03）。CLI 假设调用者已经进行了过滤；它本身不会（也无法）进行检查。 2. **注入的 memory 是不受信任的、仅作参考的数据。** CLI 会将其包含在 `BEGIN/END UNTRUSTED MEMORY CONTEXT` 标记中，并且系统提示词严禁服从其中的任何内容。 3. **Memory 没有压制发现的权力。** 结论是根据通过 `submit_findings` 工具和对抗式验证阶段产生的发现计算出来的——绝不会根据描述性文本或 memory 得出。上下文可以为发现的理由提供依据，但不能移除发现或更改结论。 4. 对于自动化使用场景，仅允许 **owner 锁定**的 memory 影响门控决策；不要将 agent 编写的 `on_recall` memory 视为安全相关门控的可信来源（以避免自我中毒的反馈循环）。 ## 配置 模型别名和默认值在内置的 `config.toml` 中定义： ``` default_alias = "review-cloud" [models.review-cloud] ollama_model = "qwen3-coder:480b-cloud" base_url = "http://localhost:11434/v1" num_ctx = 32768 [models.review-local] ollama_model = "qwen2.5-coder:7b" base_url = "http://localhost:11434/v1" num_ctx = 16384 ``` **用户覆盖：** 创建 `~/.config/kagura-code-reviewer/config.toml`（或将 `KAGURA_CODE_REVIEW_CONFIG` 设置为其他路径）。只有您设置的键会覆盖默认值；其余一切均继承默认设置。 要添加自定义别名： ``` default_alias = "my-model" [models.my-model] ollama_model = "deepseek-r1:70b" base_url = "http://localhost:11434/v1" num_ctx = 65536 ``` ## 状态 / 范围 v0.1 是**同步的**：CLI 会阻塞直到 Ollama 审查循环完成（每次调用最多 `--timeout` 秒，最多 `--max-iters` 次 agent 迭代）。 以下功能**尚未实现**，且上文也未作此声明： - `--background` 模式（即发即忘的异步审查，带有一个状态轮询命令） - 与 `kagura-engineer` 或其他 kagura-* 工具共享 Memory 模式 - MCP server 模式 设计规范：[`docs/superpowers/specs/2026-06-06-kagura-code-review-design.md`](docs/superpowers/specs/2026-06-06-kagura-code-review-design.md) ## 贡献 欢迎提交 Issue 和 PR。有关开发设置和工作流，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，以及 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。要报告安全问题，请遵循 [SECURITY.md](SECURITY.md)（请不要为漏洞公开创建 issue）。 ## 许可证 Apache-2.0 —— 见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。

标签：AI, AI风险缓解, Claude Code, LLM评估, Ollama, SOC Prime, 代码审查, 开发工具, 自动化代码审查, 逆向工具