Open CoDesign 实战：用 Calm Spaces 冥想 App 示例跑通「Prompt → 原型 → HTML 导出」全链路-育师

人工智能
AI 应用
桌面应用

【免费下载链接】open-codesign

Open-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.

项目地址：https://gitcode.com/gh_mirrors/op/open-codesign

点击查看免费下载

本文是 Open CoDesign（开源 Claude Design 替代方案，gh_mirrors/op/open-codesign）首个内置演示示例的端到端技术指南。它以仓库中的 examples/calm-spaces/README.md 为骨架，讲清楚如何从零启动应用、用一句话生成手机端冥想 App 原型、在沙箱 iframe 中渲染，并最终导出为独立 HTML 文件；同时结合packages/与apps/desktop的源码，说明 artifact 提取协议、Tailwind CDN 注入、CSS 变量设计令牌与「响亮失败」错误处理策略的实现原理。读完你将掌握 Open CoDesign 从提示词到可分发原型的最小可用闭环，以及 Phase 2 滑块调参所依赖的底层机制。

Calm Spaces 是什么

Calm Spaces 是 Open CoDesign 的头号演示（headline first demo），对应的是 Claude Design 官方主页上的招牌示例。它是一份自包含的 HTML artifact，在手机外框（phone-frame）中渲染一个冥想 App 的主屏 mockup，包含：

冥想课程列表；
播放按钮；
柔和绿 / 蓝配色；
通过:root上的 CSS 自定义属性（custom properties）暴露的可调设计令牌（design tokens）。

该示例在多语言模板库中也有对应条目，例如英文版 packages/templates/src/locales/en.ts 中id: 'meditation-app'的提示词为：

Design a mobile app prototype for a meditation app called Calm Spaces. Show a phone frame containing a home screen with a meditation list, play button, and progress tracker. Use serene typography, soft greens and blues, and lots of white space.

中文版见 packages/templates/src/locales/zh-CN.ts（"Calm Spaces 冥想 App"），另有西语es、葡语pt-BR变体。这些内置演示通过 packages/templates/src/index.ts 的getDemos(locale)/getDemo(id, locale)按语言环境取用。

运行环境准备

1. 提供开发期 API Key

Calm Spaces 演示默认走 Anthropic 接口，Anthropic 密钥开箱即用：

export VITE_OPEN_CODESIGN_DEV_KEY=sk-ant-...

该变量以VITE_前缀暴露给 Vite 渲染进程，是仓库为本地开发准备的密钥注入机制（README 中明确标注 "Provide a dev API key"）；在已打包应用中使用时，密钥通常改由设置面板 / onboarding 流程写入本地存储（参见 apps/desktop/src/main/auth-bridge.ts 对{ type: 'api_key', key }凭据的读写）。如果你在仓库源码中搜索不到该变量的其他定义，属正常现象——它只在 README 记录的开发路径中出现。

2. 安装依赖并启动桌面应用

在仓库根目录执行：

pnpm install pnpm --filter @open-codesign/desktop dev

项目使用 pnpm workspace 管理（见 pnpm-workspace.yaml），桌面端位于 apps/desktop，其 package.json 中的 dev 脚本由 apps/desktop/scripts/dev.cjs 驱动。

应用内操作步骤

启动后在桌面应用内按如下顺序操作：

在左侧边栏点击Calm Spaces meditation app起始模板（starter）。该 starter 即上文meditation-app模板，点击后提示词会被写入输入框（见 apps/desktop/src/renderer/src/components/Sidebar.tsx 的handlePickStarter）。
按Send（或直接回车）发送。
约 30 秒内，右侧 iframe 渲染出设计。
打开预览工具栏中的Export菜单 → 选择HTML→ 选择目标位置 →Save。
在浏览器中执行open <chosen-path>，即可看到脱离应用也能独立运行的同款设计。

生成管线原理：从提示词到沙箱 iframe

artifact 协议与提取

README 规定模型恰好输出一个<artifact identifier="design-1" type="html" …>块。这一约束在源码中有对应实现：packages/core/src/lib/artifact-collect.ts 的createDesignSourceArtifact会生成id: 'design-${index + 1}'、type: 'html'的 artifact 对象，并附带sourceFormat: 'jsx'、renderRuntime: 'react'、entryPath（默认DEFAULT_SOURCE_ENTRY）等元数据；stripEmptyFences还会清理流式解析过程中残留的空 ```html 围栏（fence）外壳。

沙箱 iframe 渲染

被提取的 artifact 交给 orchestrator 后，由 packages/runtime/src/index.ts 的buildPreviewDocument/buildStandaloneDocument包装成 iframesrcdoc文档：

buildPreviewDocument（packages/runtime/src/index.ts#L611-L640）会先剥离 CSP meta 标签，再对 HTML 源码注入 JSX 运行时、预览视口支持与 overlay，最后以wrapJsxAsSrcdoc包裹；
交互式预览使用INTERACTIVE_PREVIEW_SANDBOX = 'allow-scripts allow-forms'（packages/runtime/src/index.ts#L642），并通过 CSPform-action 'none'收紧表单提交；
渲染端的 iframe 错误会通过iframe-errors.ts的unhandledrejection监听转发给 UI，由CanvasErrorBar等组件呈现为可读信息。

提示词的底层模板

值得说明的是，README 引用的docs/research/01-claude-design-teardown.md在当前仓库快照中未随附；仓库 docs/research 目录现存11-custom-sliders.md与15-claude-design-prompts.md，后者从命名看即 Claude Design 提示词拆解资料，可作为了解该示例设计动机的补充阅读。

HTML 导出：单文件自包含产物如何生成

导出器架构

导出入口在 packages/exporters/src/index.ts：EXPORTER_FORMATS = ['html', 'pdf', 'pptx', 'zip', 'markdown']。每个格式是独立的子路径模块，通过动态import()懒加载（exportArtifact内部分支调用），使puppeteer-core、pptxgenjs、zip-lib等重依赖只在用户首次导出时才进入模块图，控制冷启动体积。

exportHtml 的完整处理链

exportHtml（packages/exporters/src/html.ts#L36-L46）按以下链路生成单文件：

buildInlineHtmlDocument：当配置了assetBasePath时，先通过inlineLocalAssetsInHtml把 workspace 内的src/href/url()本地引用内联为 data URI（inlineLocalAssets默认true）；
buildHtmlDocument（packages/exporters/src/html.ts#L61-L80）：用buildStandaloneDocument生成独立文档外壳（自动补<!doctype html>、<meta charset>、<meta name="viewport">），注入meta name="generator"与注释横幅，默认做两空格缩进美化；
默认文件名由 apps/desktop/src/main/exporter-ipc.ts 的buildDefaultExportPath生成：{设计名}-{源码文件名}-{UTC 时间戳}.{扩展名}，文件名片段经sanitizeFilenamePart做 NFKD 规范化清洗。

Tailwind CDN 的智能注入

README 指出 Tailwind 通过官方 CDN（https://cdn.tailwindcss.com）加载，且导出器会在模型忘记时自动补上。实现位于 packages/exporters/src/html.ts：

常量TAILWIND_CDN = 'https://cdn.tailwindcss.com'、TAILWIND_TAG = '<script src="…"></script>'（L12-L13）；
hasTailwindScript（L107-L122）用transformHtmlElementBlocks遍历所有<script>标签，解析其src的 hostname 是否为cdn.tailwindcss.com；
当opts.injectTailwind为真且检测不到时，injectIntoHead把 CDN 标签插入<head>之后（没有<head>则自动创建）。

导出 IPC 链路

桌面端的导出由registerExporterIpc注册的codesign:exporthandler（apps/desktop/src/main/exporter-ipc.ts#L229-L296）承载：先parseRequest校验格式与 source（非法格式抛EXPORTER_UNKNOWN），再resolveExportSource从 workspace 读取源码（含App.tsx等候选路径的自动回退），随后弹出系统保存对话框；用户取消时返回{ status: 'cancelled' }，保存成功则返回{ status: 'saved', path, bytes }供渲染端 toast。

设计令牌与 Phase 2 滑块：CSS 变量的作用

README 强调 Calm Spaces 的所有颜色、间距、字体大小都是 CSS 变量，这正是 Phase 2 滑块层（slider tier）要挂钩的对象。也就是说，生成结果不是写死的样式，而是把视觉参数收敛到:root的 CSS custom properties 上，后续的滑块调参只需改写变量值即可实时反馈到预览 iframe，无需重新生成。仓库 research 目录中的 docs/research/11-custom-sliders.md 从命名看即为该滑块方案的设计调研，可结合阅读。这也是该示例被选为「头号演示」的原因之一：它完整展示了「模型生成 + 令牌化 + 可调参数」的产品闭环。

失败模式：刻意响亮，不留静默回退

README 明确写道：这条路径上没有任何静默回退（"There are deliberately no silent fallbacks anywhere in this path"）。三类典型失败及其表现如下：

场景	表现
未设置密钥	assistant 消息提示你设置`VITE_OPEN_CODESIGN_DEV_KEY`
PDF / PPTX / ZIP 导出（README 记录的 Phase 1 行为）	抛出`CodesignError`，错误码`EXPORTER_NOT_READY`，toast 提示 "PDF export ships in Phase 2"
网络 / provider 错误	以`CodesignError`（错误码`PROVIDER_ERROR`）传播，呈现为以`Error:`开头的 assistant 回复

需要如实指出的是：EXPORTER_NOT_READY反映的是 README 撰写时（Phase 1 早期）的仓库快照。从当前源码看，packages/exporters/src已实现 pdf.ts、pptx.ts、zip.ts，exporter-ipc.ts的parseRequest也已接受这些格式，且当前错误码注册表中不存在EXPORTER_NOT_READY码（见下文），说明仓库已进入 Phase 2 实施阶段，该记录属于历史行为。

错误码注册表与多语言文案

CodesignError的错误码集中定义在 packages/shared/src/error-codes.ts，provider 相关码包括PROVIDER_AUTH_MISSING、PROVIDER_KEY_MISSING、PROVIDER_ERROR、PROVIDER_HTTP_4XX等；导出相关码为EXPORTER_UNKNOWN、EXPORTER_NO_CHROME、EXPORTER_PDF_FAILED、EXPORTER_PPTX_FAILED、EXPORTER_ZIP_UNSAFE_PATH、EXPORTER_ZIP_FAILED（L83-L88）。每个码都带用户可见文案与分类（ERROR_CODE_DESCRIPTIONS），并同步到 packages/i18n/src/locales/en.json 等四语言文件——例如PROVIDER_ERROR中文文案为 "provider 返回错误，请检查 API key 后重试。"（packages/i18n/src/locales/zh-CN.json）。渲染端对PROVIDER_ERROR的呈现路径可在 apps/desktop/src/renderer/src/store.test.ts 的测试中看到。

「响亮失败」原则（PRINCIPLES §10）意味着：宁可把错误明明白白抛给用户，也不要在背后吞掉异常换一个「看起来正常」的结果——这对一个以 AI 生成为核心的产品尤其重要，因为静默回退会让用户误判模型能力与产物可信度。

小结：一条可复制的端到端链路

Calm Spaces 演示浓缩了 Open CoDesign 的核心闭环：多语言模板提示词 → 模型输出单一 HTML artifact → orchestrator 按design-1协议提取 → 沙箱 iframe 渲染 → HTML 导出器补全文档外壳与 Tailwind CDN → 单文件分发。如果你要接入自己的首个生成场景，照此链路即可：在packages/templates/src/locales增加模板条目、确保模型遵守 artifact 协议、把视觉参数令牌化，并沿用「响亮失败」的错误处理策略。