用途
best-api 是 Plate 项目(udecode/plate)中的一项决策与品味技能,负责掌握公共调用点(call-site)的决策,而不是实现引擎。它挑选或评判一个公共调用形态,把落地执行交给 Plan playbook。产品与 API 方向记录在根目录 VISION.md 中,该技能要求读取并引用它,而不是复述。某个方向是否值得投入,由 verdict 负责。
模式
省略模式时自动推断,不为其他技能已负责的工作流阶段另造模式。
design:为新的或重新设计的表面选择最小且有实质理由的 API,返回一个调用形态决策。若工作继续进入 API 计划,则由 Plan playbook 在 api-plan 评审行下运行 pstack:architect。
review:评判一个当前或拟议的 API、diff 或计划,推荐更好的目标,并按架构参考的 P0 至 P3 尺度对发现排序(.agents/playbooks/references/architecture.md#priority),Babysit playbook 的 P0 与 P1 门槛会读取该排序。
repair:编辑唯一的 Vision 权威来源,然后修复仍教授被拒形态的每个示例、配方、检查与文档。
design 或 review 的结论写在计划页上(按 AGENTS.md 的 Plan pages),即当前活动计划或一次性计划的页面。
输入
只读取能改变决策的内容:根 VISION.md;先看先例(已有 Slate 原语、Plate 组件与参考编辑器);被命名表面的公共类型、导出、文档、代表性调用点及其实现;只在理想目标本身清楚之后,才看现有计划与兼容性约束。
两轮决策
第一轮是理想目标:完整应用 pstack:principle-redesign-from-first-principles 技能,按以下顺序为公共 API 排序:正确的归属与真实语义、一条明显的常用路径、可发现的推断、JSDoc 与示例、渐进披露、稳定的组合点、局部性,最后是生态契合。两种设计同样好时优先 Slate 与 Plate 惯例,另一形态明显更简洁或更可扩展时则偏离。在命名抽象之前先给出真实公共导入的具体调用点:常规路径、一条现实的自定义路径,以及仅在真实需要时才给的高级路径。如果常规路径在自然可读之前需要解释,API 就没完成。还要确定每个公共名词的归属与导入来源(根、功能入口、注册表或应用);调用点短但归属错误仍是坏 API。
硬删减门槛:把每个涉及的名词、命名空间、插件、抽象、归属、层与包都视为可删除候选。测试删除它并把现有职责路由到已有权威归属;测试在删除后只剩私有机制时合并或内联;向上看一层归属,问该能力是否只是已存在权威的输入适配器、视图、查询、策略或载荷。只有在硬性正确性、安全性、序列化数据、原生行为或运行时法则要求该边界,用户明确要求,或源码证明存在独立当前用户任务时才保留。选择保留这些法则与任务的最大删除锥,并指明唯一存活的权威与仍值得保留的私有适配器。调用次数、实现大小、测试、文档、兼容性、迁移成本与已接受计划都不能证明独立归属,只改变采纳顺序。如果评审建议重命名、移动或包装一个本可消失的表面,评审即不完整。
第二轮是现实核查:在理想目标仍可见的情况下检查当前归属、运行时真相、采纳、推断与破坏成本。优先分阶段硬删减而非永久混合。绝不因代码已有注册表、配置、生命周期、构建器、别名或已接受计划就悄悄下调目标。实现难度在 API 结论中没有投票权;当编译器限制、声明生成、兼容性或截止日期阻碍理想调用点时,保留其为建议,追踪阻碍到其归属的泛型、层或包契约,并在那里命名持久修复。拒绝只为规避该修复而存在的类型转换、注解、别名、包装、标记、载体或平行 API。若在其他归属修复期间必须保留现有约束,将其标为带删除证明的临时债务,它绝不是选定的 API 或完成证据。
若目标新增、保留或改变热运行时工作,在其通过 Benchmark 的预验收探测前保持暂定。只有活源码证明竞争形态共享同一运行时法则且结论不保留任何运行时机制时,才可无探测地确定调用语法。仅类型与零运行时工作可记录 N/A 并附源码证据。
有界穷举
当设计或评审问题涉及同置、内联、辅助函数存留、文件拓扑或“完整列表”时,先按架构参考构建完整有界归属的 Audit manifest(.agents/playbooks/references/architecture.md#audit)再建议清理。
评审问题
用户想说什么,调用点是否恰好表达了它?每个名词的真实导入路径是什么,该层是否是其诚实归属?归属名词能否离开作用域 API,嵌套能否变成扁平的领域动词,推断能否移除类型、转换、辅助函数或重复契约?自定义路径是否让每次基本调用都为高级情况付费(例如每个 demo 中同一占位 ID)?不变量、参数、可替换能力与应用策略是否在提议插件之前已分类?API 在三个合理的未来新增之后是否仍连贯?智能体能否从类型、JSDoc 与一个示例找到规范路径?最大合理删除锥是什么,哪个幸存者有硬性法则或独立当前任务证据?是否因为持久归属修复更难而选择了变通?守卫输入为新情况放宽时,现有守卫(含第三方)是否仍能正确决定该情况而不变?导出类型是否恰好承诺运行时接受的内容?不要因为提案更精细、更通用、更可观测或已有文档就保留较弱的方案。
输出
只给一条建议,不给菜单。严厉诚实的反馈以最大有实质理由的删减作为第一句。design 与 review 返回结论与删除锥;带确切公共导入路径的理想调用点;当前源码与调用方证据;为何目标是最简单真实模型;被拒方案与每个存活公共概念的保留证据;按层的归属与保留的运行时和安全法则;预验收尺度凭据或源码支持的零运行时 N/A;破坏与采纳影响;验证运行;以及确切的下一归属。review 为每个发现给出 P0 至 P3 优先级。
修复
当用户以可复用方式纠正 API 建议、已接受设计确立或拒绝可复用公共 API 原则、某变更删除/重命名/重新解释可复用公共 API 或其规范模式时运行 repair,它是 API 变更的自动收尾子任务。只读请求中报告确切修复而不写入。同一 API 错误第二次出现时,先运行 /pstack:correct 处理其类别,让类型、lint 或检查在学说文本变更前阻止它。根据活源码与当前 Vision 权威检查纠正;若其命名了源码缺失或与既定法则矛盾的 API,停止修复并对该纠正运行 verdict。编辑 VISION.md 中该规则的唯一权威。搜索所有教授该契约的制品(技能、示例、配方、检查、文档、生成镜像与生成参考输出)中拒绝使用的名称、示例与调用形态,运行 node tooling/scripts/teaching-sweep.mjs <API name> [...] 进行搜索,它按大小写变化拆分 ASCII 名称并在任意大小写中匹配(词间最多隔一个词),并列出英文文档命中项对应的中文孪生页面;命中分为 live、generated、release notes 与 history,history 无需改动,修复 live 命中、重新生成 generated 命中、修复未发布的 release notes;阅读每个孪生页面在其英文命中处的上下文及命中页全文正文。生成器在基座失败时,按 verify 的命令配方重新生成或把过期输出列为计划 Close 的开放工作。只更新教授或执行该变更契约的技能,移除矛盾,并链接 Vision 权威而非复制学说。按 pstack 块的 Agent files 规则重新生成技能及资源。在真实 API 上正向测试受影响操作,不预置预期答案。当任何归属或依赖技能仍教授被拒形态时,不得称 API 迁移完成。不把产品特定决策变成通用规则;所有长运行工作流都需要的规则应进 AGENTS.md 或块的共享源,绝不放在此处。
停止条件
当一个目标明显胜出且其未决问题属于实现/证明问题时停止 API 设计,将它们路由到 Plan playbook 或归属包。除非用户明确要求且已加载归属执行技能,否则不实现产品 API 变更。
限制与说明
该技能依赖 VISION.md、AGENTS.md、.agents/playbooks/references/architecture.md 等仓库内文件与 pstack 相关技能;其搜索脚本 teaching-sweep.mjs 的路径与用法按资料原文保留。资料未提供安装命令、价格、平台支持范围或效果数据。