liuhaocun/open-design-api-wrapper
0
Open Design API Wrapper PoC
把 Open Design daemon 封装成一个更适合 OpenClaw / 飞书 / 自动任务调用的受控 API。
为什么需要 Wrapper
Open Design 原生是 Web UI + daemon，内部有 /api/projects、/api/runs、/api/chat、/api/projects/:id/files 等接口，但它不是面向公网 SaaS 的稳定 API 产品。
这个 wrapper 负责：
- 鉴权：
WRAPPER_API_TOKEN - 标准化入口：
POST /design/generate - 自动创建 Open Design project
- 自动发起 run
- 轮询完成状态
- 汇总产物文件
- 提供 artifact / archive 代理下载地址
环境变量
PORT=8787
OD_BASE_URL=http://127.0.0.1:7456
PUBLIC_BASE_URL=https://your-wrapper.example.com
WRAPPER_API_TOKEN=change-me
# 默认已在 HF Dockerfile 中设为 pi；也可覆盖为 /api/agents 里可用的 agent id，例如 opencode/codex/gemini/pi
OD_AGENT_ID=pi
OD_MODEL=default
GENERATION_TIMEOUT_MS=600000
OD_POLL_MS=1500
# pi 需要至少一个 provider key；放 Hugging Face Space Settings → Secrets
ANTHROPIC_API_KEY=sk-ant-...
# 或 OPENAI_API_KEY=sk-...服务器部署建议使用 server-friendly CLI（如 opencode/codex/gemini/pi）+ API Key 环境变量；不建议在 HF 容器里维护 Claude Code / Cursor 这类桌面/本地登录态。Open Design 的 BYOK proxy 适合 UI/连接测试，自动写文件的生成链路仍要确认可用 agent。优先使用ANTHROPIC_API_KEY/OPENAI_API_KEY；HF Docker 启动脚本也兼容ANTHROPIC_APLKEY/OPENAI_APLKEY这类 typo alias。
启动
node src/server.mjs健康检查：
curl http://127.0.0.1:8787/health检查 Open Design daemon 可用能力：
curl http://127.0.0.1:8787/design/capabilities \
-H "Authorization: Bearer $WRAPPER_API_TOKEN"会聚合：
/api/health/api/agents/api/skills/api/design-systems
用于确认容器里到底有哪些 agent、skill、design system 可用，避免盲调。
生成设计稿
curl -X POST http://127.0.0.1:8787/design/generate \
-H "Authorization: Bearer $WRAPPER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "landing-page",
"prompt": "做一个 OpenClaw 官网落地页，Linear 风格，突出 Agent 自动化",
"format": ["html", "zip"],
"brand": "OpenClaw / Clawd / lobster energy",
"language": "zh-CN",
"agentId": "opencode"
}'返回示例：
{
"ok": true,
"projectId": "odwrap-...",
"conversationId": "...",
"runId": "...",
"status": "completed",
"skillId": "saas-landing",
"designSystemId": "vercel",
"entryFile": "index.html",
"entryUrl": "https://.../design/artifacts/<projectId>/index.html",
"archiveUrl": "https://.../design/archive/<projectId>",
"files": []
}类型映射
可在请求里显式传 skillId / designSystemId 覆盖。
HF / 服务器落地建议
- Open Design daemon 放私有 HF Space / VPS 内网。
- Wrapper 暴露给 OpenClaw / 飞书，不直接暴露 Open Design daemon。
- API Key 放平台 Secrets。
.od数据目录挂持久化存储：HF Storage Bucket 或 VPS volume。- PDF/截图由 wrapper 增加 headless Chrome/Playwright 导出，不依赖 Open Design 桌面 PDF 接口。
当前 PoC 边界
- 已完成 API 编排、鉴权、产物代理、测试。
- 尚未接真实 Open Design daemon 实跑，因为当前机器没有启动该服务，也没有确认容器内可用的 agent CLI。
- PDF/PNG 导出待下一步加 Chromium/Playwright；HF 免费容器可能需要自定义镜像安装 Chromium。
测试
npm test