clawpatch: OpenClaw 生态的代码审查自动修复利器

一句话定位

将代码仓库映射为语义特征切片，用 LLM 逐片审查并持久化发现的问题，再通过显式命令驱动修复。

快速概览

• 仓库: openclaw/clawpatch
• 版本: v0.3.0（2026-05-15 创建，仅 7 天）
• 技术栈: TypeScript (strict, ESM, Node.js)，仅有 zod 一个运行时依赖
• 代码量: ~49K LOC（含 31K 测试）
• 协议: MIT
• npm 包: pnpm add -g clawpatch

OpenClaw 生态中的位置

clawpatch 不是孤立项目——它是 openclaw GitHub 组织下的一个垂直工具。该组织的旗舰产品 OpenClaw（373K stars）是一个自托管的个人 AI 助手，管理你的邮件、日历、消息和文件。openclaw 团队围绕"个人 AI agent"构建了完整工具链，全部使用 TypeScript strict + zod schema 的统一工程标准：

技术依赖关系：clawpatch 的 acpx provider 直接使用 openclaw/acpx（2.7K stars）——一个基于 Agent Client Protocol 的无头 CLI，可以让 clawpatch 通过标准协议调用 Codex、Claude、Gemini 等任意编程 agent。

核心架构

clawpatch 的工作流分 6 个阶段，每个阶段都是显式命令而非自动化黑箱：

阶段 1：init — 项目检测

零 LLM 调用。自动识别：Git 信息、语言（20+ 种）、框架（Next/Nest/Django/Rails/Phoenix/ASP.NET 等）、包管理器（npm/pnpm/gradle/maven/pip/poetry/mix 等）、项目命令（typecheck/lint/test/format）。

阶段 2：map — 语义特征切片

这是 clawpatch 最核心的设计。不是按文件列表逐行审查，而是将代码库分解为语义特征单元：

• 17 个启发式 mapper：Node、Next.js、React、Go、Python、Ruby、Elixir、Rust、.NET、Swift、Gradle、Maven、Laravel、C/C++、Apple、路由、配置
• 每个特征记录：入口文件、主文件(ownedFiles)、上下文文件(contextFiles)、关联测试、信任边界
• 双层映射决策引擎：先跑启发式 mapper → 评估覆盖率 → 若 coverage < 25% 或 meaningful features ≤ 2，自动切换 agent mapper（LLM 辅助）

阶段 3：review — LLM 审查

组装特征的 owned + context + test 文件为 bounded prompt context（可配 maxOwnedFiles=12, maxContextFiles=24，单文件 24K 字符截断）。通过 strict JSON schema 约束 LLM 输出 10 类发现：bug、security、performance、concurrency、api-contract、data-loss、test-gap、docs-gap、build-release、maintainability。

支持并发审查（默认 10 jobs），provider 支持：Codex、OpenCode、ACpx、Grok、Pi、mock。

阶段 4-6：fix → revalidate → open-pr

修复是显式且安全的：

• clawpatch fix --finding <id> — 仅修复指定 finding
• 拒绝 dirty worktree（除非 --force）
• 不 commit、不 push、不开 PR — 需显式 open-pr --patch <id>
• 修复后必须 revalidate 验证才能标记 fixed

深入 map：语义特征切片引擎

map 是 clawpatch 架构中最具设计深度的子系统。17 个语言/框架专用 mapper 并行运行，输出统一的种子结构，经过去重、ID 生成、测试发现、变更检测后落盘为持久化 FeatureRecord。当启发式覆盖不足时，agent-mapper 决策引擎自动唤醒 LLM 补位。

完整数据流

第一层：FeatureMapper 统一接口

每个 mapper 实现相同的契约，共享 MapperContext（含 Node 项目发现 + Turborepo task graph）：

type FeatureMapper = {
  name: string;
  map(root: string, context: MapperContext): Promise<FeatureSeed[]>
}

输出统一的 FeatureSeed 结构——这是 map 子系统的"内部通货"：

• entryPath：入口文件（如 src/main.rs）
• identityKey：去重键——同 source 下的稳定标识
• kind：11 种特征类型（cli-command、route、service、library 等）
• trustBoundaries：信任边界标记（user-input、network、database、secrets 等）
• ownedFiles / contextFiles / tests：三环审查文件体系

Python mapper 解剖（1902 行）

这是最复杂的 mapper，将一个 Python 项目分解为 6 类 feature seed：

1. 项目元数据（source: "python-project"）：解析 pyproject.toml/setup.py/setup.cfg，ownedFiles 为元数据文件集合
2. CLI 入口（source: "python-console-script"）：解析 [project.scripts] / [tool.poetry.scripts]，逆向解析 module:function → 实际 .py 文件路径
3. Flask 路由（source: "python-flask-route"）：正则扫描 @app.route("/path") 装饰器
4. FastAPI 路由（source: "python-fastapi-route"）：正则匹配 @router.get/post/put/delete，处理 include_router() 嵌套
5. Django 路由（source: "python-django-route"）：解析 urls.py 的 urlpatterns 列表，检测 from django.urls import 导入
6. Source Groups（source: "python-source-group"）：通过 partitionFileGroups() 将 src/ 文件分组成 ≤12 个文件的审查单元

测试命令推断同样精细——顺序检测 uv.lock → poetry.lock → pdm.lock → hatch.toml，分别返回 "uv run pytest" / "poetry run pytest" / "pdm run pytest" / "hatch run pytest"。

Rust mapper 对比（358 行）

Rust 的 mapper 结构更简洁，体现了"约定优于配置"的语言特点：

1. 检测 Cargo.toml → 解析 [workspace] members（含 glob 展开 crates/*）
2. src/main.rs → "Rust command"（source: "rust-command"）
3. src/lib.rs → "Rust library"（source: "rust-library"）
4. src/bin/*.rs → 每个 bin 独立 feature
5. tests/*.rs → 集成测试 feature
6. 对 workspace 每个 member 递归上述流程

Python 1902 行 vs Rust 358 行反映了 mapper 深度的现实差异——Python 需要处理 3 个 Web 框架 + 4 个包管理器的组合爆炸，而 Rust 的 Cargo 约定使得工作区发现更统一。这也意味着 Python 项目的审查切片质量优于 Rust。

第二层：Seed → FeatureRecord 的桥接

mapFeatureSeeds() 完成了 4 项关键转换：

① 稳定 ID 生成

featureId = stableId("feat", [
  seed.kind,       // "route"
  seed.source,     // "python-django-route"
  seed.entryPath,  // "config/urls.py"
  seed.identityKey ?? seed.command ?? seed.route ?? seed.symbol ?? ""
])

同一 feature 在不同运行中产生相同 ID——这是后续 review → fix → revalidate 链路的锚点。

② 自动测试发现

如果 seed 未设 skipNearbyTests: true，nearbyTests() 自动扫描入口文件所在目录 + test/tests/__tests__/src/，按文件名匹配（stem.test.ts、tests/stem.rs），上限 5 个。覆盖 JS/Rust/Swift/C/C++ 的测试命名约定。

③ 变更检测

const featureChanged =
  JSON.stringify(stripVolatile(previous)) !== JSON.stringify(stripVolatile(feature))

// 如果 ownedFiles 变了，且之前是 "reviewed"/"revalidated"/"fixed"
// → 自动重置为 "pending"

④ FileGroup 智能分区

当 mapper 遇到大量源文件（如 Python src/ 下 45 个 .py），partitionFileGroups() 使用层级分区算法：

• 深度 0：按第一层子目录拆分（src/auth/、src/models/、src/api/）
• 超过 maxFiles 的分组进入深度 1：按文件名"家族"前缀分组（user.ts、user.service.ts、user.test.ts → family "user"）
• 排除无意义的家族名：index、main、shared、helper、util、type、test、spec
• 仍然超限的用 chunkFiles() 切片，标签追加 #1、#2 后缀

最终每个审查单元 ≤12 个 owned 文件，保持 prompt context 可控。

第三层：Agent Mapper 决策引擎

这是 clawpatch 最务实的设计——启发式优先，仅在覆盖不足时用 LLM 补位。

weakMap() 实现三条判定规则：

repoInventory() 先收集整个仓库的文件清单——首选 git ls-files -z，回退目录遍历——过滤掉 node_modules、dist、.git、vendor 后统计 sourceCoverage（已被 owned 的源文件占比）。

当判定 weak 时，将仓库清单（manifests、topLevelDirs、sourceFileSamples 前 500、testFileSamples 前 200）发给 LLM，要求返回 strict JSON 的 AgentMapOutput。LLM 返回的特征经 Zod 验证后与 heuristic 结果 merge——同 featureId 的 agent 特征优先覆盖。

如果 agent mapper 返回 0 条有效特征且 source="agent"（用户显式要求），抛出错误；如果 source="auto"，保留 heuristic 结果。

安全遍历保障

整个 map 子系统共享安全文件遍历基元：

• 符号链接拒绝：walk() 和 isSafeFile() 检测并跳过所有 symlink
• 路径逃逸防护：realpath() 解析后与仓库 root 比较，拒绝越界路径
• 自动跳过清单：node_modules、dist、build、coverage、.git、.clawpatch、.venv、__pycache__、target、Pods、Carthage 等 18 个常见生成/依赖目录
• null byte 检测：拒绝含 的路径（防截断攻击）

map 子系统的设计评价

亮点：

• 启发式优先的务实策略——大多数项目无需 LLM 即可完成特征切片，成本可控
• 稳定 ID 体系——跨运行不变，使 review→fix→revalidate 链路可追溯
• 自动测试发现是跨语言的高质量实现
• FileGroup 分区算法的"文件家族"概念减少了审查单元的碎片化
• Agent mapper 只在 coverage < 25% 时激活，避免不必要的 LLM 成本

局限：

• 所有解析基于正则/字符串匹配（无 AST），对非标准代码写法容易漏掉
• Mapper 深度不均——Python 1902 行 vs Rust 358 行，审查切片质量存在系统性差异
• Agent mapper 完全信任 LLM 输出（仅 Zod 验证格式，不验证语义合理性）

关键技术创新

1. 分区审查解析（Partitioned Review Parsing）

provider.ts 的 parseReviewOutput() 是一个精巧的容错机制：

• 快速路径：整个输出通过 Zod schema → 成功直接返回
• 回退路径：先验证容器形状(findings 数组 + inspected 对象)，再逐个解析 finding
• 单个 finding schema 失败 → 放入 droppedFindings（记录 layer: schema/validation），其余 finding 继续有效
• 只有容器形状根本错误时才整体失败

这意味着 LLM 输出 10 条 finding 中 2 条格式不对，8 条仍然可用——而非整体丢弃。

2. Deslopify 模式

--mode deslopify 专门检测 AI 生成代码的质量问题：

• 语义重复：跨文件的相同行为
• 影子模块：thin pass-through wrapper
• 死代码路径：靠测试存活的废弃逻辑
• 防御性过度编码：不匹配真实信任边界的 try/catch
• 同义反复测试：镜像实现内部结构的测试
• 类型静默 hack：any 强转、sleep、fake success returns

这是目前开源生态中少有的"AI slop 清理"专用工具。

3. 多层安全防御

4. 状态持久化设计

零数据库依赖，全部 JSON 文件：

.clawpatch/
  project.json        — 项目元数据
  config.json         — 配置
  features/*.json     — 特征记录（持久工作单元）
  findings/*.json     — 发现记录（含签名去重）
  patches/*.json      — 修复尝试
  runs/*.json         — 运行记录（可审计）
  reports/*.md        — Markdown 报告
  locks/              — 并发锁

Finding 去重通过 signature 字段（hash of category + evidence + title）实现。所有 run 可审计。

5. Tribunal Ledger 导出

--export-tribunal-ledger 将 finding 转为 JSONL 格式，供下游 Tribunal 系统签名和消费：

{"kind":"clawpatch-review","finding_id":"...","claim_hash":"...","severity":"high","category":"bug","agent_label":"clawpatch-codex"}

这是一个 agent-to-agent 审计链的设计思路——允许多个审查 agent 交叉验证彼此发现。

Provider 矩阵

全部实现统一接口：check → map → review → fix → revalidate。review 和 revalidate 为 read-only，fix 使用 workspace-write。

评价

亮点

• 架构极简：仅 zod 一个运行时依赖，TypeScript strict mode，无数据库——这在 2026 年的 agent 工具中极为罕见
• 容错设计成熟：分区解析、多层验证、弱映射回退——不像一个 7 天前创建的项目
• 安全第一：从命令层到文件系统到 Git 操作的多层防御
• 覆盖面广：16+ 语言/框架的启发式 mapper，Deslopify 模式填补了 AI slop 检测空白
• 审计友好：每步持久化 JSON 记录，Tribunal ledger 导出支持多 agent 交叉验证

关注点

• 极早期项目：v0.3.0，patching "still requires manual review"——生产使用时机尚未成熟
• Mapper 质量不均：Python mapper 1902 行，Rust 仅 358 行；部分 mapper 深度有限
• 无数据库：JSON 文件在大仓库（数千 features）中可能成为瓶颈
• 签名去重依赖 hash：finding signature 的微小措辞变化可能产生重复
• provider 差异：codex 是主要开发路径，其他 provider 测试覆盖未知

与同类工具对比

总结

clawpatch 是 OpenClaw 生态中专门面向代码审查自动化的垂直工具。它的设计哲学是"保守执行、透明记录"：每一步都是显式命令，每次运行都可审计，修复必须人类确认路径。在 auto-fix 满天飞的 2026 年，这种"审查优先、修复显式"的设计反而显得务实——它承认 LLM 会犯错，因此把模型输出视为"建议"而非"指令"，并通过两层验证（schema + evidence）过滤不可靠内容。

适合关注的人群：需要 CI/CD 中集成自动化代码审查的团队、希望系统性检测 AI slop 的维护者、对 agent-to-agent 审计链感兴趣的研究者。

引用：分析基于 clawpatch v0.3.0 源码和 spec.md。代码仓库：github.com/openclaw/clawpatch，官方文档：clawpatch.ai。OpenClaw 生态：openclaw.ai。