Open CoDesign 上手指南:用一句话提示词在本地生成 HTML 原型、幻灯片与营销素材

原创2026-09-27 12:17:122,462 阅读
文章标签:AI 应用人工智能桌面应用前端CLI多模态

Open CoDesign 上手指南:用一句话提示词在本地生成 HTML 原型、幻灯片与营销素材

Open CoDesign(开源 Claude Design 替代方案)是一款 MIT 许可、Local-first 的桌面 AI 设计工具:把一句自然语言提示词变成完成度很高的 HTML 原型、幻灯片或营销素材,支持自带任意模型 API Key、ChatGPT 订阅登录与多模型切换。读完本文,你将掌握从安装、接入 Claude Code / Codex 配置、添加 Provider 到第一条提示词出图的完整流程,并了解其内置设计技能、Agent 工作区与导出链路的底层实现。

Open CoDesign 主界面:左边是提示词,右边是实时生成的设计结果

它是什么:更开放、更本地化的 AI 设计工具

Open CoDesign 的核心主张写在官方标语里:“你的提示词,你的模型,你的电脑。” 与常见的订阅制云端设计工具不同,它把整条生成链路放到你的桌面上:

  • 直接跑在你的电脑上,不依赖云端工作区,应用状态默认保留在本地;
  • 直接用你自己的模型,支持 Claude、GPT、Gemini、Ollama、OpenRouter 等 20+ 提供商;
  • 导出的是真文件(HTML、PDF、PPTX、ZIP、Markdown),不是只能截图或看预览;
  • 生成过程看得见:Agent 在做什么、调了什么工具、什么时候可以打断,都实时展示。

它适合这样的用户:想要 AI 设计工具的速度,但不想被订阅制绑住,不想把工作流全部放到云端,也不想被锁死在单一模型上。

最近更新一览(截至 v0.2.0)

官方 CHANGELOG.md 记录了完整的发版历史,当前值得关注的能力演进包括:

  • feat/decompose-to-ui-kit 分支:把生成的图 / HTML 拆成 ui_kits/<slug>/ 目录交给下游 coding agent 接手,视觉判定走 12 项 boolean check(而非浮点分数),自检后自动迭代修补,每次 decompose 的成本以 toast 实时显示(详见 BENCHMARKS.md);
  • v0.2.0(2026-05-09)—— Agentic Design:带真实工作区的设计会话、带权限的本地工具、Files 面板升级、provider 诊断、安全加固、DESIGN.md 设计系统;
  • v0.1.4(2026-04-23):AI 图像生成、ChatGPT Plus / Codex 订阅登录、CLIProxyAPI 一键导入、API 配置稳定性优化;
  • v0.1.3(2026-04-21):修复 Gemini models/ 前缀 key、OpenAI 兼容中转 "instructions required" 报错、新增第三方中转 SSE 截断提示;
  • v0.1.2(2026-04-21):发版流程与 Homebrew / winget / Scoop 打包清单。

快速开始:3 分钟出第一个结果

官方给出的首次生成时间约 3 分钟,你只需要三样东西之一:一个 API Key、ChatGPT 订阅登录,或本地 Ollama。支持平台为 macOS、Windows、Linux。

1. 安装

推荐使用包管理器:

# macOS
brew install --cask opencoworkai/tap/open-codesign

# Windows — Scoop
scoop bucket add opencoworkai https://github.com/OpenCoworkAI/scoop-bucket
scoop install opencoworkai/open-codesign

也可以从 GitHub Release 直接下载安装包,各平台对应文件如下:

平台 文件
macOS(Apple Silicon) open-codesign-*-arm64.dmg
macOS(Intel) open-codesign-*-x64.dmg
Windows(x64) open-codesign-*-x64-setup.exe
Windows(ARM64) open-codesign-*-arm64-setup.exe
Linux(x64,AppImage) open-codesign-*-x64.AppImage
Linux(x64,Debian/Ubuntu) open-codesign-*-x64.deb
Linux(x64,Fedora/RHEL) open-codesign-*-x64.rpm

每个 release 都会附带 SHA256SUMS.txt 和 CycloneDX SBOM(*-sbom.cdx.json),方便校验下载内容。

其他包管理器的可用状态(以仓库 packaging/ 目录为准):Homebrew Cask 与 Scoop 可用;winget 的 winget install OpenCoworkAI.OpenCoDesign 首次提交仍在 Microsoft review 中;Flathub 的 flatpak install flathub ai.opencowork.codesign 因需要签名构建与 AppStream 元数据而延后;Snap 以 release 附带 .snap 文件为主,尚未接入 Snap Store。仓库的 packaging/homebrew、packaging/scoop、packaging/winget 目录分别维护各渠道的清单与说明。

未签名安装包提示(重要):当前安装包尚未经过 Apple notarization 和 Windows Authenticode 签名。macOS Sequoia 15+ 起,右键 → 打开 已不能绕过 Gatekeeper,即使在「系统设置 → 隐私与安全性」里点“仍要打开”也经常失败。最可靠的一行命令:

xattr -cr "/Applications/Open CoDesign.app"

执行后直接双击打开即可(0.1.x 旧版本安装路径为 /Applications/open-codesign.app)。Windows 侧则是 SmartScreen → More info → Run anyway。想要可验证构建,可以按 CONTRIBUTING.md 从源码自行编译。

2. 添加 Provider(模型入口)

首次启动时应用会直接打开设置页,按你已有的模型入口选择即可:

  • ChatGPT 订阅登录:直接登录 ChatGPT,使用 Codex 模型,无需粘贴 API Key;
  • API Key:粘贴 Anthropic(sk-ant-...)、OpenAI(sk-...)、Atlas Cloud、Google Gemini、OpenRouter、SiliconFlow、DeepSeek 或其他支持的 provider key;
  • 本地 / Keyless:使用 Ollama,或使用 IP 白名单的 OpenAI 兼容网关。

凭证默认保存在 ~/.config/open-codesign/config.toml,ChatGPT OAuth token 保存在应用配置目录下的 token store 中。除非你选择的模型入口本身需要联网,请求内容不会额外离开你的机器。

这一点有源码直接印证:桌面端的配置读写集中在 apps/desktop/src/main/config.ts,默认配置目录为 ~/.config/open-codesign(支持 XDG_CONFIG_HOME 覆盖),writeConfig 在写盘前会用 ConfigV3Schema.parse 做一次 schema 校验,防止格式漂移写坏配置文件导致下次启动失败——这正是 v0.1 时代“删除全部 provider 后应用无法重开”的教训修复。

3. 输入第一条提示词

你可以直接选 十五个内置 demo 之一——landing page、dashboard、pitch slide、pricing、mobile app、chat UI、event calendar、blog article、receipt/invoice、portfolio、settings panel 等——也可以直接写自己的需求。几秒内,你就能看到一个沙箱中的可交互原型(HTML 或 JSX/React 组件,渲染在隔离的 sandbox iframe 中,本地内置 vendored React 18 + Babel)。

直接接你现有的开发环境

如果你已经在用 Claude Code 或 Codex,API key 形式的 provider、model 和 key 都可以一键导入;如果你用的是 Codex 的 ChatGPT 订阅登录,可以直接在设置里登录 ChatGPT。

一键导入的底层逻辑在 apps/desktop/src/main/imports/claude-code-config.ts:它会扫描 ~/.claude/settings.json 和 shell 环境变量,把用户归类为 has-api-key(有真实 ANTHROPIC_* key 可直接使用)、oauth-only(仅有 OAuth 证据,无法直接复用——Anthropic 把 token 绑定在 Claude Code 客户端上)、local-proxy(baseUrl 指向 localhost,典型 Claude Code Proxy / LiteLLM 场景)、remote-gateway、parse-error、no-config 等类型,并据此决定设置页展示哪一种导入提示。同目录下还有 codex-config.ts 处理 Codex 配置的对应导入。

内置设计能力:十二个设计技能模块

通用 AI 工具很容易产出“差不多就那样”的设计。Open CoDesign 内置了 十二个设计技能模块——幻灯片、仪表盘、落地页、SVG 图表、玻璃拟态、编辑风排版、Hero 区块、价格页、页脚、聊天界面、数据表格和日历——外加一层内置设计约束,帮助模型更稳定地做出更讲究的排版、留白和配色。

在源码层面,这十二个技能对应 packages/core/src/design-skills/index.ts 中声明的 DESIGN_SKILL_FILES 数组(slide-deck.jsx、dashboard.jsx、landing-page.jsx、chart-svg.jsx、glassmorphism.jsx、editorial-typography.jsx、heroes.jsx、pricing.jsx、footers.jsx、chat-ui.jsx、data-table.jsx、calendar.jsx),文件以 <script type="text/babel"> 形式存放在用户数据目录的 templates/design-skills/ 下(首次启动从应用包内 seed,之后用户可自行编辑),每个文件头部带有 // when_to_use: 提示注释,供 Agent 在打开文件前判断该技能是否适用于当前需求。

每次生成时,这些能力都会自动参与:在模型真正开始写 CSS 之前,它会先判断当前需求适合哪些技能,并围绕布局意图、设计系统一致性和对比度做推理。如果你想把自己的风格教给模型,只需要在项目里加一个 SKILL.md。

你能得到什么:功能全景

模型与提供商

  • 统一的 provider 抽象:支持 Anthropic、OpenAI、Atlas Cloud、Gemini、DeepSeek、OpenRouter、SiliconFlow、本地 Ollama,以及任意 OpenAI-compatible relay;同时支持无 key 的 IP 白名单代理。
  • 一键导入和登录:Claude Code / Codex 的 API key provider 配置可以直接带进来,也可以用 ChatGPT 订阅登录使用 Codex 模型。
  • 动态模型选择器:每个 provider 都会展示真实模型列表,而不是一小撮写死的选项。

Provider 层实现在 packages/providers/src/index.ts:它是 @mariozechner/pi-ai 之上的统一封装,应用代码必须经过该包访问 provider,绝不直接 import provider SDK。其中值得注意的实现细节包括:

  • wire 覆盖参数:当自定义端点(DeepSeek、Ollama、LiteLLM、Azure 等)不在 pi-ai 的 provider 注册表里时,会构造一个合成 PiModel,让它走正确的 pi-ai adapter 路由;
  • reasoning 参数:映射到各家的思考开关——Anthropic Claude 4.x 上启用 extended thinking,OpenAI/Gemini 上映射到各自 reasoning effort,旧模型自动忽略;
  • allowKeyless:允许 OpenAI 兼容的无 key 网关(上游 SDK 要求非空 apiKey 字符串,因此本地用占位符,鉴权交给 httpHeaders 或网关本身);
  • CompletionLengthError:长度截断不算成功完成,只保留 usage、不保留半截内容,让调用方可以重试且不漏计 token 成本。

生成与编辑

  • 提示词 → HTML 或 JSX/React 组件原型,渲染在隔离的 sandbox iframe 中(本地 vendored React 18 + Babel);
  • 十五个内置 demo + 十二个设计技能模块:给常见设计需求准备好的起点;
  • 实时 Agent 面板:模型编辑文件时,工具调用实时流式展示(todo、工具调用、进度一目了然,随时可打断);
  • AI 图像生成:可选启用,通过 OpenAI、OpenRouter 或已登录的 ChatGPT 订阅为 hero、产品图、背景和插画生成位图素材;
  • AI 自动生成调节参数:模型主动暴露值得调的颜色、间距、字体等参数,直接拖动细调,不用重新来一轮;
  • Comment mode:点击预览中的任意元素留下批注,模型只重写对应局部,无需重写整段提示词;
  • 拆解为 UI Kit:聊天侧边栏一键把当前 artifact 拆成 ui_kits/<slug>/ 目录(index.html + components/*.tsx + tokens.css + manifest.json + README.md),形态对齐 coding agent 接入。内置确定性 + 视觉双 verifier 用 12 项 boolean check 自检(parityScore = passCount / totalChecks,不是 LLM 自己打的浮点分),不达标自动迭代,每次成本以 toast 实时显示;
  • 支持中途取消生成:停止后不丢失之前的上下文和结果。

Agent 使用的设计工具按需加载,见 packages/core/src/tools 目录:ask(结构化问卷)、scaffold(脚手架)、skill(技能加载)、preview(预览与交互自检)、gen_image(图像生成)、tweaks(可调参数)、todos、done。以 ask 为例,packages/core/src/tools/ask.ts 定义了五种问题类型——text-options(单选/多选文本选项)、svg-options(带预览的 SVG 选项)、slider(滑杆数值)、file(文件上传)、freeform(自由文本)——每次最多 25 个问题,由渲染层 <AskModal /> 呈现,主进程 IPC 把用户答案回填到 Agent 的待决工具调用。

实时 Agent 面板:Todo、工具调用与实时进度,随时可以打断

AI 自动生成可调参数:颜色、间距、字体等参数直接拖动细调

预览与工作流

  • 源码绑定微调(Source-backed tweaks):微调面板读取当前预览源文件,而非独立 starter 或之前工具返回的声明。/*EDITMODE-BEGIN*/ 与 /*EDITMODE-END*/ 之间的扁平 JSON 定义可调值,可选 TWEAK_SCHEMA 指定控件类型;值必须绑定到实际设计(如 CSS 中的 --ocd-tweak-card-radius),tweaks() 只发现声明、不创建绑定;缺失、空声明和无效声明分别说明。保存仅合并改变的键,遇到源码冲突时拒绝覆盖;
  • 全屏预览:在当前应用窗口内展开可运行的 JSX/HTML,无需手动缩小侧栏;支持预览页、App.jsx 等独立文件标签及文件列表内的预览,点击退出或按 Escape 恢复原布局,不重载作品中的表单或页面状态;
  • 清晰可用的预览控件:评论模式、缩放和导出保留可见标签,空间不足时换行到文件标签下方;缩放和导出菜单限制在窗口内,可用方向键、Home / End 导航,Enter 选择,Escape 关闭;
  • 手机 / 平板 / 桌面预览:一键切换真实响应式视图;
  • Files 面板:导出前先检查多文件产物(HTML、CSS、JS);
  • 即时设计切换:最近五个设计保持 iframe 存活,Hub 和 Workspace 之间切换几乎零延迟;
  • 连接诊断面板:一键检测任意 provider 的连接状态,给出可操作的报错信息(对应 v0.1.3 修复的 timeout、SSE 截断、缺少 /models、Messages API 不兼容等中转问题);
  • 每次生成的 token 计数:侧边栏直接看到这一轮花了多少 token;
  • 四个设置页签:Models、Appearance、Storage、Advanced;
  • 浅色 / 深色主题,以及 英文 / 简体中文 UI 的实时切换。

导出与发布

  • 五种导出格式:HTML(内联 CSS)、PDF(本地 Chrome)、PPTX、ZIP、Markdown。导出器入口见 packages/exporters/src/index.ts,EXPORTER_FORMATS = ['html', 'pdf', 'pptx', 'zip', 'markdown'],四种重格式(HTML/PDF/PPTX/ZIP)均为懒加载,重型运行时依赖(puppeteer-core、pptxgenjs、zip-lib)只在用户真正导出时才进入模块图,保证冷启动包体精简;
  • GitHub Release 发布链路:当前提供未签名的 DMG(macOS)、EXE(Windows)和 AppImage(Linux);代码签名(Apple ID + Authenticode)与可选自动更新计划在 v0.5 落地。

v0.2 架构:从一次性生成器到本地设计 Agent

当前版本 v0.2.0 的主题是 Agentic Design,它把 Open CoDesign 从一次性生成器升级成一个带真实工作区的本地设计 Agent:

  • Design as session:每个 design 都是一个 pi session,历史写入 JSONL,产物落在磁盘工作区;
  • 带权限的 agent loop:复用 pi 的 read、write、edit、bash、grep、find、ls 能力,由 Open CoDesign 的权限 UI 统一拦截;
  • 按需调用设计工具:ask、scaffold、skill、preview、gen_image、tweaks、todos、done;
  • DESIGN.md 作为设计系统源文件:品牌 token 和设计决策写成可编辑文件,而不是存在模型记忆里;
  • v0.1 迁移路径:旧 SQLite 设计会迁移到真实工作区和 session history。

提示词系统的组织方式在 packages/core/src/prompts/compose-full.ts 中清晰可见:完整的系统提示由一组可插拔 section 组合而成——IDENTITY(身份)、WORKFLOW(工作流)、OUTPUT_RULES(输出规则)、DESIGN_METHODOLOGY(设计方法论)、PRE_FLIGHT(预检)、EDITMODE_PROTOCOL(编辑模式协议)、ANTI_SLOP_DIGEST(防敷衍摘要)、BRAND_ACQUISITION(品牌获取)、MULTI_SCREEN_BATON(多屏接力)与 SAFETY(安全),tweak 模式下额外追加 TWEAKS_PROTOCOL。这些 section 各自以 .md 文件形式存放在 packages/core/src/prompts/sections 目录(loader.ts 在模块加载时一次性读取并暴露为冻结字符串常量),让 PR diff 和 git blame 保持干净可读。组合器还支持按用户偏好路由(feature routing)动态决定 tweaks、位图素材、可复用设计系统这些能力在本轮是启用、禁用还是自动。

Roadmap 与后续方向

官方 Roadmap 中已明确的方向包括:

  • 继续打磨新版 ask、preview、tweaks 和进程管理界面;
  • 成本透明化:生成前估算 + 每周预算控制(每轮 token 计数已上线);
  • 版本快照 + 并排 diff;
  • 三种风格并行探索;
  • 从代码库提取设计系统 token;
  • 代码签名(Apple ID + Authenticode)+ 可选自动更新——v0.5;
  • Figma 图层导出——1.0 之后。

技术栈与工程实践

项目构建在以下技术之上(见仓库根目录与 apps/desktop/package.json):

  • Electron + React 19 + Vite 6 + Tailwind v4;
  • @mariozechner/pi-ai 与 pi-coding-agent:模型 / provider 与 agent loop 的基础能力;
  • electron-builder:跨平台打包(macOS DMG、Windows EXE、Linux AppImage/deb/rpm,配 electron-builder.yml)。

仓库为 monorepo 结构(pnpm workspace),核心包包括 packages/core(Agent 会话、提示词组合、工具与设计技能)、packages/providers(provider 统一封装与兼容层)、packages/exporters(五种导出格式)、packages/runtime(编辑模式、iframe 错误处理、tweaks 桥接)、packages/shared(跨端共享类型与协议)、packages/ui(基础组件与设计 token)、packages/i18n(en / es / pt-BR / zh-CN 四语言)与 packages/templates(demo 包与示例)。桌面端源码位于 apps/desktop/src/main(主进程)与 apps/desktop/src/renderer(渲染层)。

许可证与引用

项目采用 MIT 许可证(见 LICENSE),可 fork、发布、商用;第三方依赖相关声明保留在 NOTICE。安全相关事项见 SECURITY.md。如果要在论文、文章或产品对比中引用本项目,可以使用仓库根目录下机器可读的 CITATION.cff,或使用 README 中给出的 BibTeX 格式。

总体而言,Open CoDesign 提供了一条“自带模型、本地优先、可导出真文件、生成过程透明”的 AI 设计路径:从 README.zh-CN.md 描述的 3 分钟快速开始出发,配合 CHANGELOG.md 追踪能力演进、BENCHMARKS.md 查看 decompose 视觉判定基准,再深入到 packages/ 各源码包理解 provider、提示词与导出链路,你就能完整掌握这个开源桌面设计 Agent 的安装、使用与扩展方式。

登录后查看全文
open-codesign