rea-tool-design 技能实操：给逆向工具仓库立一套工具设计规范
给逆向工具设计工具：REA 仓库的第三枚技能
一个 AI 代理能调用的工具越多，越会出现一类新问题：这些工具本身该怎么设计？工具边界画在哪里、输入输出合同怎么定、权限归谁管——这不是使用问题，是工程问题。REA 仓库（morluto/rea，304,456 star，MIT 协议，2026-10-18 经 GitHub API 实查；npm 包名 rea-agents，最新版 6.5.0）给了个少见的答案：把「如何设计自家工具」本身做成一枚技能，挂在仓库的 .agents/skills/ 下，名字叫 rea-tool-design。
本站已上线过这个仓库的前两枚技能教程——reverse-engineer-anything（带证据地逆向闭源软件）和 rea-changelog-update（把 Git 历史写成 Release Notes）。这篇讲第三枚：它管的是 REA 自己的 CLI 与 MCP 工具面——当你想加一个新工具、改一份 MCP 合同、或调整 Evidence 语义时，代理加载这枚技能后按官方指南走完整的设计流程。素材全部来自 GitHub API 拉取的 SKILL.md、docs/tool-design.md 原文与本站 2026-10-18 的 CLI 实测。
.agents/skills/ 目录的五枚技能实测清单；右卡是 SKILL.md frontmatter 里写的触发条件——设计工具/改合同/调 Evidence 时自动加载
这枚技能做什么：SKILL.md 拆开看
技能本体只有 956 字节，是五枚里最短的。frontmatter 的 description 一句话概括：
Design or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.
（设计或变更 REA 的调查工具、CLI/MCP 合同、provider 能力与 Evidence 语义。）
正文三段，每段指向一份官方文档。第一段把设计依据指向 docs/tool-design.md（工具边界、合同语义、provider 归属、可发现性），并要求先勘察现状——原话值得引：
Inspect the current contract and nearest existing tool relevant to the analyst question; source, documentation, and live catalogs may describe different versions.
（勘察与分析者问题相关的当前合同与最近的既有工具；源码、文档和线上目录描述的可能是不同版本。）
第二段规定设计请求的返回物：拟议边界、输入/结果形状、Evidence 语义、最近的替代方案、验证方式五件套，实现时「保留用户的范围与既有授权」。第三段把实现与验证指向 docs/testing.md（受影响泳道的回归场景）和 CONTRIBUTING.md（生成文件归属），provider 与 workflow 指南按需再读。
SKILL.md 与 tool-design.md 规定的四站：勘察现状 → 决策扩展还是新增 → 产出五件套设计 → 按测试指南实现验证
它指向的核心文档：tool-design.md 讲什么
SKILL.md 只是个入口，真正的分量在 docs/tool-design.md（12,870 字符）。这份指南面向「给 REA 加工具的人」，但里面的判断标准对任何做 MCP 工具设计的人都有参考价值。
加工具前先过三问
指南开篇就是一盆冷水：设计围绕分析者的问题转，改工具面之前先看三样东西——当前权威合同、provider 能力、离问题最近的既有工具。意图与结果合同都吻合就扩展现有工具；只有明显不同的结果或实质不同的权限才值得加新工具。公共命名保持 provider 中立，精确覆盖按 provider 分别报告。还有一句对「工具目录」的忠告：保持目录完整，能力与会话可用性靠报告而不是靠截断 schema——「序列化的字节数本身不能证明代理能用」。
六种工具形状
指南最实用的一张表是把工具按任务形状分类。想清楚你要做的是哪种事，边界自然就出来了：
tool-design.md 的官方形状表：inspect 查事实、search 找候选、trace 追关系、compare 比对、workflow 组合、observe 看运行时
表后跟着两条命名纪律：形状「是任务类型，不是强制前缀」，命名要面向调用者推理的动作与对象；一个工具里不要混进不相关的发现/执行/变更模式。
优先做基元，工作流靠组合
指南反复强调基元（primitive）与工作流（workflow）的分界。基元报告「关于一个已识别对象或关系的可复用事实」——一个格式特定的解码器算基元，某个应用的业务解释就不该进通用合同。组合成工作流的前提是「重复使用已经证明了多源产出」，且不能隐藏调用者的选择与不确定性。指南甚至点名了几种过度设计：「自定义编排语言、重放引擎、独立的准备/执行计划，需要有基元无法满足的实测需求」——没有执行的计划不能证明任何运行时行为。
合同与生命周期细则
「Define the contract」一节要求严格输入、显式目标身份；返回里带工件与 provider 身份、源位置、Evidence 引用、覆盖与置信度；观测、推导、推断三类关系必须分开标；缺失覆盖记 unknown 而不是当作不存在。「Own the lifecycle」一节则细到进程句柄、描述符关闭顺序、取消信号传递——比如「进程退出不等于输出闭合」「监听器过期不能证明目标已关闭」这类反直觉断言，每条都是从真实事故里换来的。对普通读者来说这两节不必逐条啃，知道它们约束的是什么（资源所有权与观测真相）就够了。
两处容易被忽略的实现细则
指南末尾还有两条值得单独拎出来的内容。一条关于公开合同里的固定元组：Zod 的 tuple 投影会丢掉隐式长度边界和 Draft 2020-12 的 items 字段（一些客户端即便有 prefixItems 也要求它），所以 REA 为此专门维护了 src/domain/fixedTupleSchema.ts，带 rest schema 的元组还得显式写最小长度；空、短、超长、畸形四类值要在输入输出两个投影里都做解析器/schema 一致性检查。另一条关于可发现性：当工具的可发现性变了，要在目标宿主上跑「宽泛、直接、负面」三类代表性任务，记录宿主/模型/目录、被选中的工具、参数、错误、重试与任务结果——schema 合法与关键词命中都不能证明模型会正确选工具。这两条对做 MCP 的人都是能直接抄走的经验。
环境实测：Node 20 上这条 CLI 的真实表现
这枚技能服务的是给 REA 本身做贡献的场景，动手前先把 CLI 跑起来感受一下。本站在 2026-10-18 用 Node v20.16.0 实测了 rea-agents 6.5.0（npm registry 显示 engines 要求 node ^22.19.0 || ^24.11.0 || >=26.0.0，2026-10-14 发布）：
实测记录：--version 与 --help 在 Node 20 全通（子命令清单 167 项），doctor 与 capabilities 启动即崩——URL.parse 是 Node 22 才有的 API
结论分层看：npm 对 engines 不满足只警告不拦截，安装与静态子命令一切正常；但 doctor（环境自检）和 capabilities（能力清单）一跑就报 URL.parse is not a function——这两个子命令恰好是贡献者最常用的。要按这枚技能的流程干活，先装 Node 22.19+ 或 24.11+。--help 列出的子命令实测有 167 个，从 analyze、decompile 到 compare-wasm-interfaces、capture-browser-scenario，也侧面印证了「工具目录完整性」为什么被指南单独立规。另外 README 提醒 Linux 上部分分析功能需要 procps 兼容的 ps 在 PATH 上做进程归属检查，恢复步骤在 docs/installation.md。
上手路径
真要试这枚技能，路径是这样的。第一步装 REA：README 给的入口是 npx rea-agents setup，选你的代理（支持 Claude Code、Codex、Cursor、Gemini CLI 等），审阅提议的配置变更后批准——setup 会同时注册 MCP 服务器和配套的 workflow 指令（也就是这些技能），并对既有配置做备份。第二步确认技能已就位：检查代理配置目录下 .agents/skills/ 是否出现在仓库克隆里。第三步是试用：在已装 REA 的代理会话里提一个设计类请求，比如「我想给 REA 加一个对比两个 WASM 模块导出表的工具」，观察代理是否先去查既有合同与最近的既有工具（前面 compare-wasm-interfaces 在 CLI 清单里真实存在，可以直接当「最近的既有工具」案例看），再返回五件套设计。
适合谁读
说清楚这枚技能的受众，免得空欢喜。它不是给「想用 REA 逆向 App」的用户的——那是 reverse-engineer-anything 的地盘；它面向两类人：给 REA 仓库提 PR 的贡献者（工具与合同变更是最高频的贡献类型），以及在自家项目里做 MCP 工具面设计、想找一份经过实战打磨的参考规范的工程师。tool-design.md 里「何时该加工具」「六种形状」「基元优先」这三节，拿到任何 MCP 项目里都成立。局限也要说明：这份指南与 REA 的 Evidence 体系、provider 泳道深度绑定，生命周期那两节的细则（64 KiB 诊断保留、一秒排放窗口等）是 REA 自己的实现约定，照抄到别的项目前先对照自己的进程监督机制。
小结
rea-tool-design 展示了一种值得借鉴的做法：把「工具该怎么设计」的团队共识沉淀成机器可加载的技能，让 AI 贡献者与人类贡献者走同一条评审路径。对多数读者，这篇的收获是 tool-design.md 那份设计指南——六种形状表与「基元优先、工作流靠组合」的原则，可以直接搬进你自己的 MCP 项目。配合本站已上线的 reverse-engineer-anything 与 rea-changelog-update 两篇，REA 仓库五枚技能里最实用的三枚就齐了。
本文步骤、引文与表格依据 morluto/rea 仓库 .agents/skills/rea-tool-design/SKILL.md、docs/tool-design.md、README.md 整理（2026-10-18 经 GitHub API 拉取），CLI 实测于本站 Node v20.16.0 环境执行，版权归原作者所有。
