一次性原型（Prototype）— 用可抛弃的代码回答一个设计问题

技能概述

一次性原型技能帮你写一段用完就扔的代码，专门用来回答一个设计问题：这个状态模型讲不讲得通，或者这个界面到底该长什么样。

适用场景

1. 状态模型或业务逻辑拿不准的时候。 复杂的状态流转在纸上、在脑子里推演很容易漏掉分支。原型会生成一个可以双击打开的单文件 HTML，把状态机推过那些最难想清楚的边界情况，而且非开发人员也能自己点着玩。
2. 界面还没想好长什么样的时候。 与其反复描述"我想要那种感觉"，不如在同一路由下直接生成几个差异明显的 UI 变体，通过 URL 参数和悬浮底栏来回切换，用眼睛选。
3. 需要让别人参与判断的时候。 需求评审、方案讨论、给非技术同事讲逻辑——一个能自己动手点的原型，比一段文字描述有效得多。

核心功能

1. 自动分支选型。 技能会先判断当前要回答的是哪类问题："逻辑/状态模型对不对"走逻辑分支，"界面该长什么样"走 UI 分支。两个分支的产物完全不同，所以技能会结合你的描述、周边代码来判断；如果问题确实含糊且联系不上你，就默认选与周边代码更匹配的那个，并把假设写在原型顶部。
2. 逻辑原型：单文件 + 自由操作 + 分步引导。 产物是一个可分享的 HTML 文件，既有可以随便点的自由操作按钮，也有分标签页的引导式演示（walkthrough），把人一步步带过关键路径。
3. UI 原型：一个路由，多个变体。 在同一路由下给出几个风格迥异的界面方案，用 URL 搜索参数切换，配一个悬浮底栏方便快速对比。

两个分支共同遵守的约束

• 从第一天就明确是一次性的。 原型代码放在它将来真正要落地的模块或页面旁边（上下文清楚），但命名上让随手翻到的人一眼看出"这是原型，不是生产代码"。UI 路由沿用项目已有的路由约定，不新造一套顶层结构。
• 启动成本必须为零。 UI 原型跑一条项目里已有的任务命令（pnpm <name>、python <path>、bun <path> 等）；逻辑原型就是一个双击打开的 HTML 文件。不需要任何思考就能跑起来。
• 默认不持久化。 状态全部放在内存里——持久化本身往往正是要验证的东西，不该成为原型的前提。如果问题确实跟数据库有关，就打到临时库或一个名字里明确写着"PROTOTYPE，随便删"的本地文件。
• 跳过所有打磨。 不写测试，不做超出"能跑起来"范围的错误处理，不抽抽象。唯一目的是尽快学到东西。
• 把状态亮出来。 每次操作后（逻辑分支）或每次切换变体时（UI 分支），把相关的完整状态打印或渲染出来，让用户看清到底变了什么。
• 收尾时归档。 验证过的结论折回正式代码，原型本身作为一手材料提交到一个用后即弃的分支上、不进主分支，并在实现 issue 上留一个指向该分支的上下文链接；同时把结论（答案以及它回答的那个问题）记进 issue 或提交信息。主分支上只保留那个被验证过的决定。

常见问题

一次性原型和正式代码有什么区别？

本质区别是目的：原型是拿来回答一个问题的，问题答完它的使命就结束了。所以它不写测试、不做真正的错误处理、不抽抽象、默认不持久化，也不进主分支。技能最后一步会要求把验证过的决定折回正式代码，原型本身则提交到一个用后即弃的分支上留档。不要直接把原型改造成生产代码。

什么时候该做逻辑原型，什么时候该做 UI 原型？

看你在问哪个问题。问的是"这套逻辑/状态模型感觉对不对"，走逻辑分支，产物是一个带自由操作按钮和分步引导的单文件 HTML；问的是"这东西该长什么样"，走 UI 分支，产物是同一路由下的多个界面变体加悬浮切换栏。这个判断做错了整个原型就白做了，所以技能会优先从你的描述和周边代码里找线索；如果两边都说得通、又联系不上你，就选与周边代码更匹配的那个（后端模块→逻辑，页面或组件→UI），并把假设写在原型顶部。

原型里怎么知道状态到底变成了什么？

技能把"暴露状态"列为硬性规则：逻辑原型在每次操作后、UI 原型在每次切换变体时，都会把相关的完整状态打印或渲染出来。这样你看到的不是一个"好像对了"的界面，而是每一步之后的真实状态。