SuperAPI AI 工具集

ship

编程与开发

查看项目

更新于 11-08 05:20

技能介绍

Ship 是一个用于自动化功能开发流程的技能。它接收一个 SPEC(规格说明)文件,然后依次执行准备(Prepare)、实现(Implement)、审查(Review)、验证(Verify)和创建草稿 PR(Open)五个阶段。每个阶段都在独立的上下文中运行,确保审查者没有参与代码编写,从而获得更客观的审查结果。整个过程无需人工实时干预,最终产出草稿 PR 和一份简明报告。

用途

Ship 的主要用途是将 SPEC 文档转化为可合并的代码变更。它特别适合需要遵循测试驱动开发(TDD)原则、进行多视角代码审查、并在真实应用中验证功能的场景。通过自动化这些步骤,Ship 旨在减少人工协调成本,同时保持审查质量。

主要能力

  • 自动化流程编排:从 SPEC 到草稿 PR 的完整链路,包括准备、实现、审查、验证和打开 PR。
  • 独立上下文代理:每个步骤由不同的代理在全新上下文中执行,避免代码作者自我审查的偏见,也避免审查观察者编写防御性描述。
  • 多视角审查:审查阶段模拟五个独立审查者,每个审查者关注不同的方面(如缺陷、兼容性、约定、领域、保真度),并由脚本自主派发。
  • 测试驱动实现:实现阶段遵循 TDD 流程,并交由 /commit 技能提交每一步变更,以便后续步骤进行差异对比。
  • 自动打开草稿 PR:使用 /pr --auto 技能创建草稿 PR,并包含行内注释而非总结评论。
  • 验证与截图:验证阶段尝试在真实应用中运行并截图,但截图不会自动上传至 PR。
  • 报告生成:返回结构化的报告,包含草稿 PR 链接、已构建的功能点、检查结果和待办事项。

使用方式

用户需要将工作流脚本 assets/workflow.js 交给 Workflow 工具执行,并通过 args 传递 SPEC 文件路径。示例代码:

Workflow({
  scriptPath: "<this skill's directory>/assets/workflow.js",
  args: { spec: "docs/specs/<the-slug>.md" }
})

如果 scriptPath 被拒绝,可以读取文件内容并通过 script 参数传递,但不要凭记忆重写。必须提供 SPEC 路径,否则脚本会抛出错误。

执行完成后,返回的报告包含四个部分:

  1. Draft PR:草稿 PR 的 URL。如果未打开,会说明原因(notOpenedReason)。
  2. Built:已构建的 SPEC 验收标准,未构建的会标记为“not built”。
  3. Checked:测试套件是否通过(suiteGreen),以及如何验证验收标准(包括测试之外的验证)。
  4. Needs you:需要用户处理的事项,如测试失败、未构建标准、审查遗留问题、未检查的视角、未驱动的应用、待附加的截图、未检查的描述等。

如果 PR 未打开,报告后还会提供标题、正文和注释(以代码块形式),以便用户手动粘贴。

此外,报告末尾可能包含最多三条审查者应在合并前了解的事项(开放问题、假设),并注明来源步骤。

适用场景

  • 根据 SPEC 文档自动实现功能并创建草稿 PR。
  • 需要多视角代码审查但希望避免人工审查偏见的场景。
  • 希望以测试驱动开发方式实现功能的团队。
  • 需要无人值守运行、事后检查草稿 PR 的工作流。

限制

  • 必须提供 SPEC 路径:没有 SPEC 文件时脚本无法运行。
  • 审查范围限制:如果差异超过 1500 行,审查会停止,避免产生不完整的审查结果。
  • 验证不完整:验证阶段会尝试截图,但截图不会自动上传到 PR,因为 gh 无法附加图片。用户需手动处理截图。
  • 部分审查发现不自动修复:只有“缺陷”和“兼容性”类别的问题会自动修复,其他类别(约定、领域、保真度)保留在报告中供用户判断。
  • 无法嵌套子代理:脚本需要自行派发审查代理,因为子代理没有工具生成子代理。
  • 流程中断处理:当在某个步骤中断时,会输出所有已生成的报告,并说明中断原因和用户需要做出的决策。
  • 不覆盖 SPEC 之前的工作:领域建模、切片、理解等步骤仍需人工完成。