Plate 仓库中的 Clawpatch 集成语义功能映射、自动化代码审查与 Agent Skill 落地实践【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文以 PlateRich-text editor with AI and shadcn/ui仓库中的规划文档 2026-05-20-clawpatch-skill.md 为主线完整还原该仓库如何把 Clawpatch 这套语义功能映射 自动化审查 显式问题修复工具链封装为一等 Agent Skill从.agents/rules/*.mdc规则源经 Skiller 生成SKILL.md、到pnpm install自动同步的机制再到map/review/fix/revalidate全命令面的实操细节与本地状态.clawpatch/的目录约定。读完本文你可以理解该 Skill 的同步机制与验证闭环并掌握在一套大型 monorepo 中驱动 Clawpatch 完成审查、分诊、修复与状态恢复的完整工作流。一、规划文档本体一次把工具链变成一等 Skill的落地记录2026-05-20-clawpatch-skill.md 是 Plate 仓库docs/plans/目录下的一份目标规划文档goal plan其结构遵循该仓库规划文档的通用骨架Goal目标、Source事实来源、Result产出、Verification验证、Notes备注。核心内容如下Goal为从当前文档与本地 Slate v2 状态操作 Clawpatch 创建一个一等 Plate 仓库 Skill。SourceClawpatch 官方文档站点以及本地活跃 Slate v2 状态目录.tmp/slate-v2/.clawpatch本地运行时状态不属于仓库提交内容。Result产出清单新增规则源文件 .agents/rules/clawpatch.mdc通过pnpm install同步生成 .agents/skills/clawpatch/SKILL.md在 .agents/AGENTS.md 中登记clawpatchSkill在根.gitignore中忽略.clawpatch/目录规范化.tmp/slate-v2/.gitignore以忽略.clawpatch/。Verification验证清单pnpm install通过并成功执行 Skillerpnpm lint:fix通过test -f .agents/skills/clawpatch/SKILL.md通过生成物存在rg -n Force Re-Review All Features|review --dry-run|requireCleanWorktreeForFix|\.tmp/slate-v2对规则源与生成 Skill 的交叉检索通过证明生成物镜像了源文件的关键指令;cd .tmp/slate-v2 clawpatch status --json确认迁移后的状态已初始化features: 92cd .tmp/slate-v2 clawpatch review --dry-run --json确认普通审查队列为空wouldReview: 0node tooling/scripts/completion-check.mjs通过注该脚本在后续迭代中已被替换见本文最后一节。Notes当时.tmp/slate-v2报告findings: 182、openFindings: 75、activeLocks: 1清理该队列被明确划出本任务边界属于独立的后续工作。这份文档的价值在于它给出了一个可复用的方法论当一个外部工具Clawpatch在团队内承担日常审查职能时应当以规则源 生成 Skill 注册 忽略策略 验证闭环五件套的形式沉淀进仓库的 Agent 工程体系而不是散落在聊天记录或口口相传的命令片段中。二、Skill 同步机制.mdc规则源、Skiller 与pnpm install钩子Plate 仓库的 Agent 工程采用单一事实源模式其约定在 .agents/AGENTS.md 中写明.agents/AGENTS.md与.agents/rules/*.mdc是事实源。编辑它们之后运行pnpm install进行同步永远不要直接编辑SKILL.md。具体到 Clawpatch规则源.agents/rules/clawpatch.mdc 携带 frontmatter 元数据声明了 Skill 的描述与参数提示--- description: Operate Clawpatch for semantic feature mapping, automated review, explicit finding fixes, revalidation, reports, and state recovery. argument-hint: [init | map | review | rereview-all | report | fix finding-id | revalidate finding-id | status] ---生成物.agents/skills/clawpatch/SKILL.md 的 frontmatter 明确标注了来源--- description: Operate Clawpatch for semantic feature mapping, automated review, ... argument-hint: [init | map | review | rereview-all | report | fix finding-id | revalidate finding-id | status] name: clawpatch metadata: skiller: source: .agents/rules/clawpatch.mdc ---这解释了规划文档 Verification 中那条rg交叉检索命令的意义通过对同一批特征字符串如Force Re-Review All Features、review --dry-run、requireCleanWorktreeForFix、.tmp/slate-v2在规则源与生成物上执行相同正则可以机械地验证生成 Skill 镜像了规则源避免人工比对遗漏。同步驱动器是 Skiller。仓库根的 .agents/skiller.toml 声明了默认应用目标default_agents [claude-code, codex]、Skill 开关[skills] enabled true、MCP 服务器配置等skiller-lock.json 则以computedHash source sourceType记录每个 Skill 的哈希与来源充当Skill 依赖锁与bun.lock/pnpm-lock.yaml承担同类职责。规划文档把pnpm install列为第一步验证正是因为安装钩子会触发 Skiller 的 apply 流程——生成/更新.agents/skills/**/SKILL.md并向各 Agent 目录分发规则。注册入口.agents/AGENTS.md 的 Skill 列表中登记了该条目说明何时应触发此 Skillclawpatchfor Clawpatch init/map/review/report/fix/revalidate workflows三、Clawpatch 能做什么语义功能映射与本地状态布局规则源.agents/rules/clawpatch.mdc 第 40–44 行对 Clawpatch 的定位是Clawpatch maps a repo into semantic feature records, reviews those bounded feature contexts with a provider, persists findings, applies explicit one-finding fixes, runs configured validation commands, and records audit state.即它把仓库映射为有界的语义功能记录再由 AI 提供方provider在受限上下文内逐个审查、持久化 findings、按一次一个 finding的粒度应用修复、执行配置好的验证命令并全程留存审计状态。其本地状态布局全部位于被忽略的.clawpatch/下路径内容.clawpatch/config.json设置、提供方、命令、审查上限、git 安全开关.clawpatch/project.json检测到的项目元数据如存在.clawpatch/features/*.json功能记录、状态、finding id、analysisHistory.clawpatch/findings/*.jsonfinding 记录与分诊状态.clawpatch/patches/*.json修复尝试与验证结果.clawpatch/runs/*.json命令运行记录、已认领功能、错误.clawpatch/reports/*.md生成的 Markdown 报告.clawpatch/locks/瞬态功能锁运行结束应自动清除一个关键的概念区分被明确写出feature 状态与 finding 状态是两套词汇。feature 可以是reviewed、needs-fix、fixedfinding 可以是open、fixed、wont-fix、false-positive、uncertain。混淆这两者会造成报告里一大片 finding但实际没有待办之类的误判——这也是后文report --status open --json与status --json被指定为活队列读法的原因。目标目录检查前置原则规则源要求在作出任何断言之前先检查实际目标目录pwd test -f .clawpatch/config.json clawpatch status --json find .clawpatch/features -maxdepth 1 -type f 2/dev/null | wc -l find .clawpatch/reports -maxdepth 1 -type f 2/dev/null | sort | tail -5若预期的 feature 数量或 config 缺失应当停下来报告错误的 checkout 或缺失状态而不是反射性地对一个缺失的项目执行clawpatch init。这也呼应了规划文档 Notes 中把状态队列清理与本 Skill 创建任务严格划界的做法。在 Plate 场景中活跃目标被约定为仓库根下的.tmp/slate-v2Slate v2 兄弟仓库的本地克隆属于本地运行时状态当前仓库提交内容中不包含该目录其.clawpatch/状态体积可以很大因此被排除在版本控制之外。也可以从其他工作目录通过全局标志操作clawpatch --root .tmp/slate-v2 status --json clawpatch --root .tmp/slate-v2 report --status open --json四、命令参考、安装与提供方Provider4.1 核心命令面规则源给出的命令参考覆盖了完整生命周期clawpatch init初始化.clawpatch/。clawpatch map构建语义功能记录。clawpatch ci一条 CI 友好命令串联初始化、映射、审查、写报告并向 GitHub Actions 追加 step summary。clawpatch status汇总项目状态。clawpatch review审查队列中或指定功能。clawpatch report渲染 finding 报告。clawpatch show --finding id检查单个 finding。clawpatch next选取下一个 finding默认open。clawpatch triage带备注地变更 finding 状态。clawpatch fix应用一次显式修复。clawpatch open-pr把一个已应用的 patch 尝试转成显式 GitHub PR。clawpatch revalidate变更之后重新校验 finding 有效性。clawpatch doctor检查本地环境。clawpatch clean-locks清除陈旧的功能锁。实用全局标志--root path从其他 cwd 操作目标仓库、--state-dir path非默认状态目录、--config path指定配置文件、--json机器可读输出、--debug额外诊断、--no-input避免交互提示。4.2 安装与环境自检基线要求引自 Clawpatch 官方文档Node.js 22、Git 2.x、默认提供方所需的本地 Codex CLI。安装与探针npm install -g clawpatch # 或 pnpm add -g clawpatch clawpatch --version codex --version clawpatch doctor4.3 提供方选择默认提供方是本地 Codex当前提供方面还包括codex默认本地 Codex CLI 提供方claudemap、review、fix、revalidate 均路由到本地 Claude Code CLI 的 print 模式pireview、fix、revalidate 与 agent map 路由到 pi.devcursor实验性的 Cursor Agent CLI 提供方规则源明确要求仅当用户显式要求或目标 config 已经选用时才使用。提供方相关控制clawpatch review --provider claude --json clawpatch review --reasoning-effort high --json CLAWPATCH_REASONING_EFFORThigh clawpatch review --json CLAWPATCH_CODEX_SANDBOXworkspace-write clawpatch review --json规则源的告诫很直白提供方标志只在相关时使用不要把一次普通的 Clawpatch 运行变成一次提供方实验。4.4 初始化与映射仅当目标仓库确实没有 Clawpatch 状态时才执行clawpatch init clawpatch map clawpatch status --jsonclawpatch init创建.clawpatch/config.json默认配置排除大型/生成目录与.clawpatch/**使用本地 Codex 提供方并设置git.requireCleanWorktreeForFix: true。另一条操作纪律当目标是.tmp/slate-v2时不要在plate-2根目录执行clawpatch init——命令必须从真实目标根运行。五、Review队列语义、控制参数与严格的输出契约基础用法clawpatch review --json # 普通审查 clawpatch review --limit 10 --json # 批量审查 clawpatch review --feature featureId --json # 指定功能 clawpatch review --dry-run --json # 干跑检查队列规则源把下面这条称作硬规则hard ruleclawpatch review --json审查的是合格队列而不是磁盘上的每一个功能记录。即使clawpatch status --json报告大量 feature 记录只要clawpatch review --dry-run --json给出wouldReview: 0reviewed: 0就是正确结果。这正是规划文档 Verification 第 6 条review --dry-run --json确认wouldReview: 0背后的判断逻辑证明队列语义正确而不是没跑东西。当前的审查控制参数及各自纪律clawpatch review --include-dirty --json clawpatch review --prompt-file review-guidance.md --json clawpatch review --prompt-file - --json clawpatch review --export-tribunal-ledger .clawpatch/runs/review-ledger.jsonl --json clawpatch review --jobs 4 --json clawpatch review --rate-limit-per-minute 20 --json CLAWPATCH_RPM20 clawpatch review --json CLAWPATCH_REVIEW_RETRIES2 clawpatch review --json clawpatch review --prompt-retries 2 --json--include-dirty只有当目的就是要审计未提交的本地改动时使用--prompt-file用文件承载额外审查准则而不是把大段指引粘进对话--export-tribunal-ledger仅当下游确实要消费该台账时导出--jobs除非本地资源或提供方配额有压力否则留空Clawpatch 默认取 CPU 感知值且上限为 10--rate-limit-per-minute/CLAWPATCH_RPM用于提供方配额压力不能替代收窄审查范围重试控制只针对提供方输出格式瞬时错误。认证、配额、不支持的提供方、拒绝、取消这类确定性失败不应被当作 flaky 重试。输出契约比早期版本更严格提供方产出的 finding 必须引用被包含的文件、合法的行区间与匹配的证据引文。一次运行可以整体完成同时把不合法的个体 finding 以schema-drop或validation-drop标记丢弃进run.errors——因此在宣称审查干净之前必须检查run.errors。此外prompt 溯源与预算核算包含/省略文件、prompt 字节数、近似 token 数也是审查输出的一部分当审查结果看起来异常偏小或偏噪时应先检查这些数字再怪模型。5.1 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注意clawpatch ci --since在过滤后 diff 为空时报告reviewed: 0是合法的空队列而非运行失败。5.2 强制全量重审rereview-all的脚本形态argument-hint中列出的rereview-all不是一个内置子命令而是规则源给出的一套 shell 流程。当需要重审所有已知功能时不要用普通clawpatch review而要逐个显式强制mkdir -p .clawpatch/runs/forced-rereview-$(date -u %Y%m%dT%H%M%SZ) jq -r .featureId .clawpatch/features/*.json | sort .clawpatch/runs/forced-rereview/features.txt while IFS read -r feature_id; do clawpatch review --feature $feature_id --json done .clawpatch/runs/forced-rereview/features.txt长运行必须把每条结果落 JSONL使中断可恢复run_dir.clawpatch/runs/forced-rereview-$(date -u %Y%m%dT%H%M%SZ) mkdir -p $run_dir jq -r .featureId .clawpatch/features/*.json | sort $run_dir/features.txt while IFS read -r feature_id; do printf %s\n $feature_id if output$(clawpatch review --feature $feature_id --json 21); then printf {featureId:%s,ok:true,output:%s}\n \ $(jq -Rn --arg v $feature_id $v) \ $(jq -Rn --arg v $output $v) $run_dir/review-results.jsonl else printf {featureId:%s,ok:false,output:%s}\n \ $(jq -Rn --arg v $feature_id $v) \ $(jq -Rn --arg v $output $v) $run_dir/review-results.jsonl fi done $run_dir/features.txt一个容易踩的坑也被写进了规则在 shell 循环中避免使用 zsh 的保留变量status改用ok、exit_code、feature_status之类的名字。六、Report 与 Triage活队列的正确读法clawpatch report --status open --json # 打开的 findings clawpatch status --json clawpatch next --json clawpatch report # Markdown 报告过滤式报告clawpatch report --severity high --json clawpatch report --feature featureId --json clawpatch report --category category --json clawpatch report --triage triage --json clawpatch report --output .clawpatch/reports/open.md两条防误读规则一份报告可能包含非 open 状态的陈旧 finding。不能把整份 Markdown 报告当作当前工作量活队列以report --status open --json加status --json为准。JSON 报告建议以total与items作为稳定形状results是别名而遗留的findings键是计数而不是 finding 数组。误报不应被静默忽略而要在 Clawpatch 中记录clawpatch triage --finding findingId --status false-positive --note evidencewont-fix只用于刻意的产品/架构决策证据不足时用uncertain。七、Fix显式、单 finding、带 git 安全闸门修复是显式的、一次一个 findingclawpatch fix --finding findingId --json默认安全配置阻止在脏工作区上修复{ git: { requireCleanWorktreeForFix: true, commit: false, openPr: false } }规则源给出的例外路径本地多 finding 批量修复时如果 Clawpatch 自己上一个 patch 弄脏了工作区可以临时把requireCleanWorktreeForFix设为false跑完批次后在交接前恢复为true并把这个动作记录进计划。同时有两条硬边界除非用户明确要求绝不允许 Clawpatch 在本仓库 commit、push 或开 PRclawpatch open-pr --patch patchId --json只在用户显式要求 Clawpatch 开 PR 时使用——它会创建 git 状态与远端副作用否则 patch 保留在本地只报告 finding/patch id。相关背景可参考仓库沉淀的解决方案笔记 2026-05-18-slate-v2-clawpatch-fix-batches-need-dirty-gate-and-provider-failure-fallbacks.md它解释了 Slate v2 批量修复为何需要脏工作区闸门与提供方失败回退另有 2026-05-18-clawpatch-valid-findings-fix.md 记录了更早一次围绕合法 finding的修复规划。八、Revalidate、锁恢复与映射能力备忘8.1 Revalidate手动修复、Clawpatch patch 或上游变更之后使用clawpatch revalidate --finding findingId --json更宽的范围clawpatch revalidate --all --status open --json clawpatch revalidate --feature featureId --json clawpatch revalidate --since HEAD~1 --json clawpatch revalidate --limit 10 --status open --json clawpatch revalidate --include-dirty --json规则源提示一个典型陷阱信任 revalidate 的范围。如果源码已修好但 finding 仍然 open可能是因为导出产物dist过期——先重建相关包再 revalidate。Slate v2 的实例bun --filter slate-react build clawpatch revalidate --finding findingId --json8.2 锁Locksclawpatch status --json会报告activeLocks与lockFiles。进程退出后锁若残留先检查再清理find .clawpatch/locks -maxdepth 1 -type f -print -exec sed -n 1,120p {} \; ps -p pid-from-lock -o pid,comm 2/dev/null || true确认进程已消失且没有 Clawpatch 运行在进行中再清理陈旧锁clawpatch clean-locks --json除非clean-locks不可用且已证明进程死亡否则不要手动删除锁文件。规划文档 Notes 中的activeLocks: 1正是这类状态的典型读数而它被明确留作后续独立任务。8.3 映射能力备忘当前 Clawpatch 的 mapper 覆盖面比早期本地习惯更广规则源逐条列出apps/*与packages/*下的 Node 应用根在存在正向源码/框架信号时即使缺少本地包文件也能被映射Bun 文本锁文件被识别为bun.lockNode 路由映射更可靠地保留 Express、Hono、Flask、Django include、FastAPI router、Laravel group、Fastify、Rails 的字面路由前缀Maven/Spring 项目有专属的根/嵌套/多模块映射大型平铺目录会按重复的文件名族切分为更连贯的审查切片。纪律是遇到奇怪的映射不要假设旧 mapper 的局限仍然成立先跑clawpatch map --json或检查功能记录本身。九、Slate v2 操作规则、验证收尾与后续演进9.1 目标态三态与重启式进度规则源的Slate V2 Operating Rules定义了多命令长运行的重启语义默认目标为plate-2根下的.tmp/slate-v2.clawpatch/保持被忽略状态又大又本地跨越多条命令的运行使用活跃 goal 一份docs/plans/**目标计划来承载可重启进度不创建 hook 后备状态。状态语义pending仍有自主工作未完成done活跃 Clawpatch 目标已达成blocked缺少恢复的状态、缺失工具链或需要用户决策目标无法继续。9.2 验证收尾Verification Closeout纯审查类工作的收尾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而对生成 Skill 的仓库自身编辑.agents/rules/*.mdc或.agents/AGENTS.md之后必须pnpm install然后验证生成物镜像源即规划文档 Verification 中的test -f与rg两步。这一整套改源 → 安装同步 → 检索比对的验证链与规划文档pnpm install/pnpm lint:fix/test -f/rg四条验证一一对应构成该任务完成的可执行判据。9.3 规划文档的后续演进收尾命令的替换值得注意的事实性更新规划文档2026-05-20写明的收尾命令是node tooling/scripts/completion-check.mjs而该脚本已不存在于当前仓库的 tooling/scripts/ 目录中。后续规划文档 2026-05-24-sync-clawpatch-goal-completion.md 记录了这次替换其目标正是同步 Clawpatch 工作流文档使规则源与生成 Skill 不再指示 Agent 使用active goal state或旧的tooling/scripts/completion-check.mjs收尾命令并改用语义化的活跃 goal 一份docs/plans目标计划加node .agents/rules/goal/scripts/check-complete.mjs plan的收尾方式同样要求pnpm install后验证生成 Skill 与源镜像、精确的旧引用rg检索无匹配。从这份文档的记录看该同步以pnpm installSkiller apply 成功、pnpm lint:fix3419 个文件无修复项与check-complete.mjs通过为验证证据完成。这一演进印证了前述机制的必要性Skill 指令本身也会被当作代码一样做回归同步否则 Agent 会继续执行已被废弃的命令。9.4 小结这个模式的可迁移要点从本次落地可以提炼出四条可迁移的实践工具链即 Skill外部工具的用法命令、参数、陷阱、边界条件以.mdc规则源沉淀经 Skiller 生成SKILL.md用install 钩子 哈希锁.agents/skiller.toml、skiller-lock.json保证分发一致用rg交叉检索保证镜像正确状态与代码分离.clawpatch/这类本地运行时状态保持被忽略且先检查目录再断言、不反射性 init的纪律写入规则防止 Agent 在错误 checkout 上制造状态验证即判据规划文档的 Verification 一节全部是可执行命令pnpm install、pnpm lint:fix、test -f、rg -n、clawpatch status/review --dry-run --json、check-complete脚本完成不依赖主观判断边界显式化Notes 中明确修复 75 个 open findings 是另一件事让 Skill 创建任务与状态清理任务互不侵占这也解释了为什么review --dry-run的wouldReview: 0反而是本任务的合格证据而非缺陷。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考