SuperAPI AI 工具集

prototype

编程与开发

查看项目

更新于 10-27 03:08

技能介绍

用途

Prototype 是一个用于辅助决策的一次性原型技能,适用于这类场景:某个设计问题通过点击一个用完即弃的产物来回答,比反复争论更便宜。它要回答的典型问题包括:某个状态模型、业务规则或状态转移逻辑是否成立;某个界面应该长什么样,需要看到几个结构上不同的选项。

原型是一次性代码,只回答一个问题。问题决定产物形状,产物存放在临时空间,答案来自观察产物,而不是阅读其源码。判断结果会作为后续独立实现工作的输入,原型本身不会变成生产代码。

主要能力

该技能按问题的“待决定不确定性”选择两条分支之一:

  • 逻辑分支:用于业务逻辑、合法状态转移、可表示的数据形状等问题。产物是一个自包含、可分享的 HTML 文件,包含领域语言状态面板、可重置的自由操作、带标签的引导场景(其中包含一个非法操作),并将决策逻辑与 DOM 分离。
  • UI 分支:用于布局、信息层级、主要交互等问题。产物在同一比较界面上提供 3 个(范围 2–5 个)结构不同的变体,支持通过 ?variant= 参数访问、浮动的前一个/名称/下一个切换器、忽略输入框焦点的键盘循环切换、刷新稳定性,以及在不动生产代码的前提下模拟宿主页面的真实感。

两条分支都遵循以下边界:产物仅放在临时空间;不修改生产路由、布局或共享组件展示变体,必要时构建只读复现并记录放弃的真实性;使用合成、非敏感、内存中的数据,不连接生产数据库或凭据,不做持久化或实时变更,不安装依赖;默认不创建分支或 commit,只有用户明确要求时才提交到一个一次性分支;不把原型逻辑提取、提升或切换到生产;判断前必须在浏览器中实际观察产物,未实际执行的部分标注“未观察”;跳过打磨,只保留运行实验所需的结构和错误处理。

使用方式

工作流程分为六步:

  1. 界定问题:在构建前写下确切问题(一句话)、竞争答案、能区分它们的场景或比较以及所做假设,并放在产物顶部;必须至少有一个场景能让竞争答案预测出不同的可见结果,否则先请求澄清而不构建。
  2. 选择恰好一条分支:根据待决定不确定性选择逻辑或 UI;问题太模糊且用户不可用时,只有在周边代码明确支持时才选择,并在产物顶部说明假设,否则以“不确定”结论停止并给出所需澄清。
  3. 建立临时边界:从仓库自身配置发现临时工作位置,按顺序查找仓库说明文件(AGENTS.md、CLAUDE.md、CONTRIBUTING.md)、.gitignore 中被忽略的临时目录,以及 UI 分支的路由设置和任务运行脚本(package.json scripts、Makefile、justfile、pyproject.toml)。命名产物时包含 prototype,让随便看一眼的人知道这是原型。若没有安全的项目临时位置,则用 mktemp -d 创建专用临时目录并说明它是临时的。
  4. 构建产物:逻辑分支读取 references/logic.md;UI 分支读取 references/ui.md,并完整遵循其规则。
  5. 在浏览器中观察:逻辑分支要运行每个引导场景及其重置、与问题相关的每个自由操作(包括非法尝试);UI 分支要查看每个变体、用按钮和方向键切换、在非默认变体上刷新,并在相关视口尺寸下对每个变体执行决策相关任务。记录产物路径或 URL、场景或变体键、执行的操作、可见的前后状态和结果。缺少浏览器访问等前置条件时,交付产物及打开/启动说明,并将所有场景或变体标注为未观察。
  6. 报告并停止:产出包含问题、竞争答案、分支、假设、产物路径与打开说明、证据、未观察项、推断或未测试项、结论和后续问题的报告,把判断交给下一步的负责人,不开始实现。

只有在用户明确要求保留到 git 时,才使用单独的 worktree 创建一次性分支、只复制请求的原型文件、用 git -C <new-temp-dir> add -f -- <paths> 暂存确切路径、在工作树中提交、移除工作树并报告分支名和已提交路径;不得提交到主分支或当前功能分支。

适用场景

适合:验证状态模型、业务规则、合法状态转移和可表示数据形状;比较界面布局、信息层级和主要交互的结构性选项;在 decision-map 工作流中处理 prototype 票据时构建产物。

限制

不可用于:已经完成、需要打磨的 HTML 交付物(如仪表板、信息图、交互图);审计或重新设计现有页面以符合 UX 标准。这些场景应由其他技能处理。

其他限制包括:不修改生产路由或共享组件;不使用生产数据库、凭据、持久化或实时变更;不安装依赖;默认不提交代码;不把原型逻辑提升为生产代码;判断需要浏览器证据,未观察的分支或变体不能作为已证明的结论。若问题需要生产数据、凭据或实时持久化,仅在一次性临时存储能回答问题时使用它,否则停止并报告缺失的前置条件。错误处理还规定:问题太模糊且用户不可用时,在构建前停止;没有浏览器访问时,尽可能构建并提供打开说明,全部标注未观察,结论为不确定;用户要求在没有观察的情况下宣布结果已证明时予以拒绝;现有运行器无法在不修改生产配置的情况下提供临时界面时,使用自包含的临时 HTML 比较并记录真实性取舍;仓库没有被忽略的临时位置时使用 mktemp -d 并报告产物为临时;用户要求合并原型或接入生产时予以拒绝。

参考资料

逻辑分支读取 references/logic.md(单文件布局、状态面板、自由操作、引导场景、逻辑/DOM 分离、骨架);UI 分支读取 references/ui.md(变体规则、比较界面、切换器行为、宿主真实性、运行器发现)。需要来源归属或有意做上游比较时,读取 references/upstream/provenance.md;MIT 声明位于该包的 LICENSE 中。