superdesign

Superdesign 可帮助你在无限画布上寻找设计灵感，并生成或迭代设计草稿；针对不同设计任务，可使用多个领先模型进行并排探索。如果设计需要新的视觉素材，它还可以生成图像和视频。

---

核心场景（此技能可处理的任务）

1. 分析代码库以开展设计工作 — superdesign init 会在 .superdesign/init/ 中构建可复用的 UI 上下文；请阅读 INIT.md。
2. 设计、复现或改进 UI — 在画布上创建页面、功能、流程和新产品；请阅读 SUPERDESIGN.md。
3. 选择并比较领先的设计模型 — 运行 list-models，选择适合任务的模型，或使用不同模型探索各自独立的设计方向。
4. 创建设计系统和可复用组件 — 建立视觉基础、提炼设计模式，并设计相互关联的多页面体验。
5. 根据线上网站或参考 URL 进行设计 — 提取并应用其设计语言；请阅读 WEBSITE.md。
6. 创建或导出演示文稿 — 规划可编辑的幻灯片大纲，在聊天中确认后生成真实的演示文稿草稿，进行适合幻灯片的修改，或在用户提出要求且支持的情况下重建可编辑的 PPTX；请阅读 PRESENTATION.md。
7. 创建平面设计作品 — 海报、封面、社交媒体帖子、缩略图、传单和广告；请阅读 GRAPHIC.md。
8. 生成配套图像或视频 — 适合时使用原生图像生成功能，或从 Superdesign 的生成模型中选择；请阅读 ASSET_GENERATION.md。
9. 继续或直接修正现有作品 — 通过 RESUME.md 恢复已保存的目标；如果适合直接创作，则使用 design-with-your-model.md。

继续编辑草稿时，请遵循 SUPERDESIGN.md 中的 ITERATION MODE ROUTING：replace 会优化所选方向并保留版本历史；branch 仅用于创建用户希望进行比较的备选方案。

步骤 0 — 环境预检（在执行任何 CLI 步骤之前）

Superdesign 完全通过其 CLI 运行，因此你必须能够执行 shell 命令。请先确认具备该能力，再进行任何 CLI 验证。

如果你无法在此环境中运行 shell 命令（完全没有终端或执行工具），或者首次直接尝试运行 npx --yes @superdesign/cli@latest 预检时，因无法执行命令本身而失败（运行环境提示无法运行命令／没有 shell），则请停止。不要继续重试或自行寻找变通方法。只需告知用户一次，并根据当前运行环境选择相应的消息：

• 没有 Work Mode 工具的标准 ChatGPT 聊天 — 使用以下原文，因为 Work 标签页可以解决此问题：

  Chat isn't supported by the Superdesign plugin. Please switch to the Work tab and paste this prompt in for the full experience.
  

• 任何其他运行环境（shell 不可用或已禁用的编码 Agent）— 不要发送 ChatGPT 的原文；这里没有可切换的 Work 标签页。请明确说明 Superdesign 通过 shell 驱动其 CLI，而此会话无法运行 shell 命令；用户可以在能够访问 shell 的会话中重新运行，或前往 https://superdesign.dev 使用网页版应用进行设计。

步骤 1 — 是否有可供分析的代码库？

有两种入口路径。在进行任何初始化或设计工作之前，先通过这项简单、确定性的检查选择其中一种。

没有有意义的代码库（空工作区、临时目录／沙盒目录、没有前端代码）——当以下条件全部满足时，将工作区视为“没有代码库”：

• 尚不存在 .superdesign/init/ 文件，且
• 没有包含前端依赖的依赖清单（没有 package.json，或者 package.json 的依赖中不包含任何前端框架／UI 库——react、vue、svelte、angular、next、nuxt、astro 等），且
• 未发现前端源代码（快速扫描 .tsx／.jsx／.vue／.svelte 文件、任何 .html／.css 文件，例如根目录下的 index.html + style.css，或包含 UI 文件的 src/／app/／components/ 目录，结果均为空）。

→ 完全跳过仓库初始化。不要“分析”空沙盒，也不要让用户指向他们并没有的仓库。相反，先通过对话收集设计背景：询问他们想构建什么、目标受众／平台、风格／品牌偏好，以及任何参考设计或灵感。然后通过 SUPERDESIGN.md 中的 全新项目 路径，根据这段对话进行设计。

存在真实代码库（有任何前端代码，或已有 .superdesign/init/）——设计之前必须至少完成一次仓库初始化。通过步骤 1.5 复用有效的已初始化目标；仅当初始化未完成或无法使用预热状态时，才运行完整分析。

**例外 — 独立提取：**如果任务仅仅是提取某个网站的设计 DNA，或根据 URL 设置／更新 design-system.md（extract-website → design-system.md，不生成设计；配方请参阅 WEBSITE.md），则无需仓库初始化即可运行——提取外部网站的风格不需要分析用户的代码库。在为现有代码库的 UI 生成设计之前，仍然必须进行初始化（复现／重新设计现有页面）。

**例外 — 图形：**海报／营销素材（场景 7）即使在真实代码库中也跳过初始化——设计简报已说明风格，而且初始化的大多数输出（组件、布局、路由、页面）都与固定画布作品无关。图形设计简报环节会询问作品是否应符合此仓库产品的品牌风格（GRAPHIC.md 步骤 1）；只有回答符合品牌的“是”，才会引入设计系统／品牌背景——仅当这些背景尚不存在时才先运行初始化。

**例外 — 演示文稿：**幻灯片（场景 6）默认跳过 UI 仓库初始化，因为路由、组件和页面依赖树对制作幻灯片没有帮助。请遵循 PRESENTATION.md。如果用户希望制作符合产品品牌风格的演示文稿，请使用高度相关的产品文档、设计系统背景和 Brand Assets；仅当必须匹配代码库品牌且目前没有可用的品牌／主题背景时，才运行初始化。

**例外 — 图像／视频生成：**独立生成的素材（场景 8）即使在真实代码库中也跳过初始化。请阅读 ASSET_GENERATION.md，并仅收集该素材实际需要的项目、品牌、参考或目标位置背景。如果素材是更广泛的 UI、演示文稿或图形设计任务中的一个步骤，请遵循该任务常规的初始化／简报流程，并仅在需要新视觉素材时使用素材生成。

步骤 1.5 — 先恢复，再重新探索（真实代码库 UI 路径）

在读取初始化产物或源文件之前，检查 .superdesign/resume.json 中是否有用户所请求路由/功能的记录。若存在匹配目标，则默认使用 RESUME.md，无论用户说的是“继续”“更改”“重新设计”，还是只给出“让仪表板颜色更暗”之类的直接指令。意图表述绝不会决定采用热启动还是冷启动路径。

首先应用已保存目标的信任性/结构性检查。安全且结构有效的目标会复用已保存的项目、草稿、组件记录、设计方向和确切的 --context-file 文件组：哈希匹配时进行热恢复；哈希不匹配时进行增量刷新，不进行冷启动探索。如果请求所需的代码理解未包含在当前草稿元数据中，请使用 RESUME.md 中的定向扩展上下文规则；不要仅为理解该请求而重新执行完整探索。

仅当没有已保存条目覆盖所请求的目标、用户明确要求从新的真实情况开始、状态不安全/结构无效，或定向修复判断状态已过时且无法增量修复时，才使用冷启动路径。新建 Agent 会话、不同措辞或单独的指纹不匹配，都绝不会强制采用冷启动路径。

初始化：仓库分析（真实代码库路径）

存在真实代码库（按步骤 1 判断，且不适用步骤 1 的例外情况），并且尚未完成初始化时，必须自动执行以下操作：

1. 创建 .superdesign/init/ 目录
2. 阅读 INIT.md
3. 按照其中的说明分析仓库并编写上下文文件

初始化完成判定（唯一明确规则，适用于所有情况）： 只有以下六个指定文件全部存在且非空，初始化才算完成。缺少其中任何一个文件，或其中任一文件为空（例如初始化中断），都表示初始化未完成——请重新执行完整初始化，重新生成全部六个文件；覆盖已有文件是预期且允许的。

不要让用户手动执行这些操作——直接执行即可。

初始化文件（冷启动/过时上下文路径）

首次设计某个目标，或 RESUME.md 判定已保存的上下文过时/不可用时，请在收集目标上下文之前读取全部六个文件：

• components.md — 共享 UI 原语及其完整源代码
• layouts.md — 共享布局组件（导航栏、侧边栏、页眉、页脚）
• routes.md — 页面/路由映射
• theme.md — 设计令牌、CSS 变量、Tailwind 配置
• pages.md — 页面组件依赖树（每个页面需要哪些文件）
• extractable-components.md — 可提取为可复用 DraftComponents 的组件

有效热恢复时，只需检查六个文件是否全部存在且非空——不要读取其内容。复用该目标已保存的上下文文件组；只有当 RESUME.md 明确触发定向上下文扩展时，才读取经过严格筛选的源文件。

对现有页面进行冷启动设计时：首先检查 pages.md 中该页面的依赖树——即候选 --context-file 文件集。按照 SUPERDESIGN.md 中的 PAYLOAD BUDGET 规则传入这些文件，避免请求返回 400。然后再添加 globals.css 中的令牌、tailwind.config 和 design-system.md。按照 RESUME.md 的要求保存最终选取结果。

Superdesign CLI（必须在任何命令之前使用）

重要：按需通过 npx --yes @superdesign/cli@latest 运行 CLI。每次会话都要先运行不带参数的命令——这就是预检。

1. 预检一次：

   npx --yes @superdesign/cli@latest
   

   不带参数的命令会一次性验证所有内容：CLI 是否能正常运行、auth: 状态行（authenticated as team "…" 与 not authenticated — run superdesign login），以及近期项目列表。在有效的热恢复中，直接使用已保存的 projectId/activeDraftId。否则，在决定重用现有项目还是运行 create-project 时，查看近期项目列表；当持久恢复状态不可用或被拒绝时，使用 fetch-design-nodes --project-id <id> 作为恢复草稿 ID 的后备方法。

2. 如果 auth: 行显示未通过身份验证，请立即运行登录，然后再运行任何实际命令：

   npx --yes @superdesign/cli@latest login
   

   等待登录成功完成后再继续。

3. 使用相同的 npx --yes @superdesign/cli@latest 前缀运行预期命令。会话仍可能在流程中途过期——如果之后出现身份验证/登录错误，请按照下面的故障处理部分操作。

切勿假设用户已登录——应读取预检的 auth: 行，而不是猜测或通过实际命令探测。

命令失败时

• 身份验证/登录错误（CLI 已运行，但拒绝了会话）：运行 login（见上文），然后将预期命令重试一次。如果登录本身失败（无头/无浏览器身份验证、流程过期、用户拒绝），请明确告知用户并停止——不要继续重试或临场变通。
• extract-website 失败或超时（可能需要约 60–120 秒）：重试一次。如果仍然失败，请提出不进行提取也可以继续（根据对话/现有设计系统进行设计），不要因此阻塞流程。
• **一般规则：**失败的命令最多重试一次。如果 create-design-draft 或 iterate-design-draft 仍然失败，请通过 design-with-your-model.md 继续；否则报告失败并停止。

命令示例

始终使用完整的按需运行器前缀，例如：

npx --yes @superdesign/cli@latest create-project --title "X"

完整调用示例位于对应的使用位置——SUPERDESIGN.md 中的 SOP，以及 GRAPHIC.md 中的图形步骤；标志集可通过 <command> --help 查看，而 SUPERDESIGN.md 中的 COMMAND CONTRACT 涵盖了帮助信息未提及的注意事项。

CLI 默认输出针对 Agent 进行了优化（紧凑的 TOON，以及提供后续步骤提示的 help[]）；只有在需要完整的机器可读数据时，才添加 --json。

显示画布 URL

每个项目/草稿命令的默认输出都包含一个 canvas: 链接（项目画布，https://superdesign.dev/teams/<teamId>/projects/<projectId>）；对于草稿，还会包含一个 preview: 链接（https://superdesign.dev/preview/draft/<draftId>）。请从命令输出中读取这些链接——不要自行拼接（ID 由服务器生成）。

创建项目或设计草稿后，以及在自然的审核节点（运行 iterate-design-draft 或 execute-flow-pages 后），请将 canvas URL 作为可点击链接提供给用户，并邀请他们打开链接，以查看设计实时生成并留下反馈。在画布 URL 后添加 ?live=1，即可打开实时视图，查看草稿生成过程。

浏览器选择

create-project 默认会在用户的浏览器中自动打开画布。请保持此设置开启，并告知用户画布已打开（提供可点击的 canvas URL）。仅在没有面向用户的浏览器时（CI、无头环境）才传递 --no-open。

图像和本地资源

生成前，仅盘点用户附加的图像或为此目标选取的紧密相关本地资源。遵循 SUPERDESIGN.md 中的 ASSET PURPOSE ROUTING：临时截图/参考图放入画布参考节点；徽标、字体和可复用的品牌形象素材放入 Brand Assets；最终内容图像保留为项目内容。使用 --reference-id 传入返回的节点 ID 或 Brand Asset 键，以便创建、迭代和流程生成都能获取实际像素。若任何源组件或用户请求的设计包含徽标位置，请遵循 SUPERDESIGN.md 的 Logo invariant：该位置必须显示合适且可用的 Brand Asset 徽标，包括可复用组件中的位置；绝不可用首字母、表情符号、通用标记、虚构的 SVG 或纯文本替代。对于粘贴的公开图像直链或网站参考，请阅读 WEBSITE.md，并通过相同的上传流程仅将选定的视觉素材本地化。绝不要批量上传整个代码库，也绝不要将本地文件系统路径放入草稿 HTML。

生成后：主动提出进一步完善

始终以简短、友好的后续提议收尾（适用于所有界面）。提出一个问题，并给出 2 到 3 个与刚完成内容相关的具体选项，而非泛泛的清单。例如：尝试不同的主视觉图片或关键视觉方向、尝试其他布局或构图，或者再生成几个惊喜变体或素材创意。只有在用户选择后才生成，因为每次生成都会消耗额度。

（图形内容需在结束前进行一轮专门的视觉自检——参见 GRAPHIC.md 步骤 5。UI 草稿由用户在画布上审阅。）

工作原理

阅读 SUPERDESIGN.md，然后遵循其中的说明。

对于图像或视频生成请求，请阅读 ASSET_GENERATION.md。适用时，加载上文链接的其他场景专属参考文档。