SuperAPI AI 工具集

clawpatch

编程与开发

查看项目

更新于 10-16 06:09

技能介绍

用途

Clawpatch 用于对代码仓库执行语义化功能映射(semantic feature mapping)与自动化代码审查。当用户提出 Clawpatch、.clawpatch、自动化代码审查、发现报告(finding reports)、clawpatch review、clawpatch fix、再验证(revalidation),或强制重审已有 Clawpatch 功能记录等需求时适用。

权威资料:官方文档 https://clawpatch.ai/ ,GitHub 文档 https://github.com/openclaw/clawpatch 。在相关仓库组合中,活动的 Slate v2 Clawpatch 项目通常位于 .tmp/slate-v2。

主要能力

Clawpatch 将一个仓库映射为语义功能记录,针对这些受边界约束的功能上下文调用提供方(provider)进行审查,持久化保存审查发现,应用针对单条发现的显式修复,运行已配置的校验命令并记录审计状态。

状态布局:

  • .clawpatch/config.json:设置、提供方、命令、审查限制、git 安全标志。
  • .clawpatch/project.json:检测到的项目元数据(存在时)。
  • .clawpatch/features/*.json:功能记录、状态、发现 id、analysisHistory。
  • .clawpatch/findings/*.json:发现记录与分诊状态。
  • .clawpatch/patches/*.json:修复尝试与校验结果。
  • .clawpatch/runs/*.json:命令运行、声明的功能、错误。
  • .clawpatch/reports/*.md:生成的 Markdown 报告。
  • .clawpatch/locks/:瞬时功能锁;运行后应清除。

功能状态与发现状态不同。功能可以是 reviewed、needs-fix 或 fixed;发现可以是 open、fixed、wont-fix、false-positive 或 uncertain。

使用方式

核心命令:clawpatch init(初始化 .clawpatch/)、map(构建语义功能记录)、ci(一条 CI 友好命令完成初始化、映射、审查、写报告并追加 GitHub Actions 步骤摘要)、status(汇总项目状态)、review(审查排队或选中的功能)、report(渲染发现报告)、show --finding <id>(查看单条发现)、next(挑选下一条发现,默认 open)、triage(带备注修改发现状态)、fix(应用一次显式修复尝试)、open-pr(将已应用的补丁尝试转为显式 GitHub 拉取请求)、revalidate(变更后重新检查发现有效性)、doctor(检查本地设置)、clean-locks(清除陈旧功能锁)。

常用全局标志:--root <path>、--state-dir <path>、--config <path>、--json、--debug、--no-input。

安装与检查:基础要求为 Node.js 22+、Git 2.x 以及默认提供方所需的本地 Codex CLI。安装命令:npm install -g clawpatch 或 pnpm add -g clawpatch。正式工作前探测:clawpatch --version、codex --version、clawpatch doctor。

提供方:默认提供方为本地 Codex。当前提供方还包括 codex(默认本地 Codex CLI 提供方)、claude(通过本地 Claude Code CLI print 模式路由 map、review、fix、revalidate)、pi(通过 pi.dev 路由 review、fix、revalidate 及 agent map),以及实验性的 cursor(Cursor Agent CLI 提供方,仅在选择加入时使用)。相关控制示例:clawpatch review --provider claude --json、clawpatch review --reasoning-effort high --json、CLAWPATCH_REASONING_EFFORT=high clawpatch review --json、CLAWPATCH_CODEX_SANDBOX=workspace-write clawpatch review --json。仅在相关时使用提供方专属标志,不要把普通 Clawpatch 流程变成提供方实验。

审查:plain 审查 clawpatch review --json;批量审查 clawpatch review --limit 10 --json;指定功能 clawpatch review --feature <featureId> --json;干跑队列检查 clawpatch review --dry-run --json。硬性规则:clawpatch review --json 审查的是合格队列,不一定审查磁盘上每一个功能记录。

审查控制项包括 --include-dirty(审计未提交的本地变更时使用)、--prompt-file(提供额外审查规则)、--export-tribunal-ledger(仅在下游摄取明确有用时使用)、--jobs(除非本地资源或提供方限制需要,保持未设置;默认按 CPU 感知取值且上限为 10)、--rate-limit-per-minute / CLAWPATCH_RPM(应对提供方配额压力)、重试控制(仅用于瞬时的提供方格式错误输出;不要对确定性的认证、配额、不支持提供方、拒绝或取消失败按不稳定发现来重试)。

CI 模式:clawpatch ci --json、clawpatch ci --since HEAD~1 --json、clawpatch ci --include-dirty --json、clawpatch ci --jobs 4 --rate-limit-per-minute 20 --json。--since 在空过滤 diff 上报告 reviewed: 0 属正常空队列,不算失败运行。

强制重审所有功能:需显式逐个功能重审,不能用普通 clawpatch review。使用 while 循环对每个 featureId 执行 clawpatch review --feature。长时可记录为 JSONL 以便中断可恢复。注意避免 zsh 保留的 status 变量,使用 ok、exit_code 或 feature_status 等名称。

报告与分诊:clawpatch report --status open --json、clawpatch status --json、clawpatch next --json;Markdown 报告 clawpatch report;可用 --severity、--feature、--category、--triage、--output 过滤。报告可能包含非 open 状态的旧发现,不要把整份 Markdown 当当前工作;使用 report --status open --json 与 status --json 获取实时队列。假阳性应记录在 Clawpatch 中而非静默忽略:clawpatch triage --finding <findingId> --status false-positive --note "<evidence>"。wont-fix 仅用于有意的产品/架构决策;证据不足时用 uncertain。

修复:一次一条显式发现,clawpatch fix --finding <findingId> --json。默认安全策略在脏工作树上阻止修复,config 中 git.requireCleanWorktreeForFix: true、commit: false、openPr: false。本地多发现批量修复时,可临时将 requireCleanWorktreeForFix 设为 false,运行批次后再恢复为 true 并在计划中记录。除非用户明确要求,绝不让 Clawpatch 提交、推送或打开 PR。补丁转 PR 需显式操作:clawpatch open-pr --patch <patchId> --json,仅在用户明确要求时使用。

再验证:clawpatch revalidate --finding <findingId> --json;更广范围包括 --all --status open、--feature <featureId>、--since HEAD~1、--limit 10 --status open、--include-dirty。信任再验证范围:若源码已修复但发现仍为 open 是因为导出产物陈旧,则重建相关包后再次再验证。

锁:clawpatch status --json 会报告 activeLocks 与 lockFiles。进程退出后若锁仍存在,应先检查再清理。若进程已消失且无活动 Clawpatch 运行,可用 clawpatch clean-locks --json;除非 clean-locks 不可用且已证明进程死亡,否则不要手动删除锁文件。

适用场景

适用于需要自动化代码审查、发现报告管理、对已有功能记录强制重审、批量修复与再验证、CI 流程集成,以及本地运行状态恢复的工程场景。Slate v2 操作规则:默认目标为 plate-2 根目录下的 .tmp/slate-v2;保持 .clawpatch/ 被忽略;使用 active goal 加一个 docs/plans/** goal plan 实现可重启进度;pending 表示仍有自主工作,done 表示目标达成,blocked 表示需恢复状态、缺失工具或用户决策。

验证收尾:仅审查类工作运行 clawpatch status --json、clawpatch report --status open --json、node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/<goal-plan>.md。修复类工作需运行已配置的 Clawpatch 校验加仓库相关检查(Slate v2 批次通常为 npm run typecheck、npm run lint:fix、npm run lint、npm run test、clawpatch status --json)。plate-2 中生成技能后,编辑 .agents/rules/*.mdc 或 .agents/AGENTS.md 后运行 pnpm install,然后验证生成的技能镜像与源一致。

限制

资料中未提供关于收费、价格、平台支持范围、审查效果保证或具体性能指标的信息。提供方中 cursor 为实验性、仅选择加入。状态目录可能很大,应保持其在 git 忽略之外(除非用户明确要求作为制品保留)。