本机整套系统搭建手册2026-09-17 搭建OpenPencil v0.8.4。目标需求 → 高保真原型.op→ 前端代码ReactTailwind→ 导出/回流全程 Agent 可驱动、人可随时接管。1. 系统总览┌────────────────────────────────────────────┐ 需求自然语言 │ 设计层OpenPencil │ ──────────────► │ ① DSH 对话: openpencil_new/render/edit │ │ ② Claude Code / 终端: op CLI129 个 MCP 工具│ │ ③ 人工: openpencil-desktop 桌面端 / op start --web │ └──────────────────┬─────────────────────────┘ ▼ design/name.op JSONgit 可 diff设计即代码 │ ┌──────────────────────────────────┼──────────────────────────┐ ▼ ▼ ▼ 出码 A: op codegen:plan → 出码 B: Agent 直接读 .op JSON 出码 C: op export-frames submit → assemble 按 DESIGN.md token 写生产代码 导出 PNG文档配图 (React/HTML/Vue/Flutter…) 并入现有工程项目 │ │ └──────────────┬───────────────────┘ ▼ web/feature/ 可独立运行的前端代码 │ ▼ 回流: op import:html index.html --out design/xxx.op → 回到设计层继续迭代四个入口各自负责什么入口擅长命令/工具DSH dsh-openpencil 插件对话式出稿聊天里直接看 PNG 预览、开画布、让 Agent 改选区openpencil_newopenpencil_renderopenpencil_createopenpencil_editopenpencil_selectionopCLI终端/Claude Code批量化、脚本化、CI分层设计skeleton→content→refine、模板、风格库、代码生成流水线、批量导出op designop codegen:*op export*op templatesop stylesOpenPencil 桌面端 / 浏览器端人工精修图层、属性、组件、交互原型、协同op start --file x.op桌面/op start --web浏览器DSH dsh-mcp-client可选增强把 129 个 MCP 工具全部接进 DSH模板/风格/codegen/导出/页面管理mcp__openpencil__*2. 本机已安装2026-09-17全部实测通过组件位置状态op.exeCLI166 个 MCP 工具客户端D:\app\openpencil\bin\✅ x64 可用openpencil-desktop.exe编辑器 无头 serve-web 精确渲染器D:\app\openpencil\app\✅ x64 可用op-host-web-server.exeD:\app\openpencil\bin\❌ARM64本机不可用官方只发了这一个架构已用 desktop 二进制顶替它共享--serve-webCLIDSH 插件zseven-w/dsh-openpencil0.1.0-rc.1C:\Users\BingerLiang\.dsh\profiles\web\✅ 5 个 openpencil_* 工具--managed守护模式已验证可启动用户环境变量HKCU\Environment✅DSH_OPENPENCIL_BINARY/DSH_OPENPENCIL_EDITOR_BINARY均指向 desktop 二进制/OPENPENCIL_DESKTOP_BIN/ PATH已验证的完整管线2026-09-17 实测产物见product/design/hello-world.opproduct/exports/hello-world.pngop start --web --port 4100→op design hello.dsl5 节点→op save_document.op 落盘 2150B→op stop→openpencil-desktop --render-shotsPNG 422×876下载走gh-proxy.com镜像本机直连 GitHub 不通全部文件按官方 SHA256 校验。升级脚本保留在D:\app\openpencil\download.mjs改版本号哈希重跑即可。⚠️ 本机 3100 端口被 Xshell 8 占用OpenPencil 服务固定用4100。3. 日常工作流推荐节奏3.1 出原型DSH 对话最快你: “读 product/DESIGN.md设计一个会员订阅页390×844 三个套餐卡片、月度/年度切换、底部安全区” Agent: openpencil_new → product/design/subscription-page.op → openpencil_rendereditableautoOpen→ 对话里出预览 右侧编辑器 你: “第二张卡片标‘推荐’主色用 DESIGN.md 里的 primary” Agent: openpencil_edit / openpencil_create活画布上改实时可见 你: 点编辑器 Save3.2 出原型终端 / Claude Code适合批量cdD:\ai\mywiki\mydocs\productopstart--web--port4100--filedesign/subscription-page.op# 无头服务4100 避开 Xshell 的 3100opuse-template模板id# 从 58 个模板起步可选opdesign batch.dsl# 或分阶段file 传参:opdesign:skeleton skeleton.jsonopdesign:content hero content.jsonopdesign:refine --root-ididopsave_documentfilePathdesign/subscription-page.op# 显式保存opstop3.3 出码快速原型独立页面opcodegen:plan plan.json# 1) 计划指定 framework: reactopcodegen:submitplanIdchunk1.json# 2) 分块提交opcodegen:assembleplanId--frameworkreact# 3) 组装 → web/feature/cdweb/featurenpmrun dev并入工程推荐质量更高你对 DSH 或 Claude Code: “把 design/subscription-page.op 实现成 ReactTailwind 页面放进 web/subscription-page/ 颜色字号用 DESIGN.md 的 token组件拆到 components/”.op就是 JSONAgent 直接读节点树/坐标/样式/设计变量即可。3.4 导出opexport-frames --output-dir exports/# 每帧一张 PNGopexport--selection--outputexports/xxx.png--scale2opexport-deck--outputexports/deck.pptx# 16:9 演示稿 → pptx/html/pdf3.5 回流代码改完想继续在设计里迭代opimport:html web/subscription-page/index.html--outdesign/subscription-page-v2.op4. Claude Code 侧接入与 DSH 并行驱动同一个 .op二选一或都用A. openpencil-skill官方一键教 Agent 用 op CLID:\app\openpencil\bin\op.exe install--target claude-code装完 Claude Code 会自动发现 OpenPencil 技能按技能指引驱动opCLI166 个 MCP 工具。B. MCP serverstdio经桌面二进制在~/.claude.json的mcpServers里加与现有 gitnexus 并列openpencil:{command:D:\\app\\openpencil\\app\\openpencil-desktop.exe,args:[--mcp,D:\\ai\\mywiki\\mydocs\\product\\design]}C. MCP serverHTTP常驻无头服务先op start --headless --file design/x.op再把 MCP client 指向http://127.0.0.1:3100/mcp。注意同一个.op同一时间只让一个 Agent/编辑器驱动文件型服务有锁与版本哈希避免两边同时写同一文件。5. DSH 侧本 GUI使用要点会话工作区是D:\ai\mywiki\mydocsopenpencil_new的.op就落在这里建议放product/design/。权限需要Workspace Write模式当前已满足。保存语义openpencil_new立即落盘create/edit的修改要在编辑器里点Save。未保存内容若 DSH 重载有最多 7 天的本地恢复草稿。渲染预览精确渲染走openpencil-desktop.exe已配置缺它时才会降级为低保真 jian 预览。6. 维护升级去 Releases 拿新版资产 → 改download.mjs里的版本号与 sha256 → 重跑 → 重启 dsh web 与 Claude Code。排错DSH 里openpencil_new报 “editor host binary is unavailable” → 环境变量没生效重启 dsh web。op报 “server must be running” → 先op start --headless --file xxx.op。预览报渲染器错误 → 确认DSH_OPENPENCIL_BINARY指向的 exe 存在且版本匹配。安全.op与代码都进 git 时仓库里不要放敏感内容设计稿可能含未发布产品。