本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-openpencil

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add @zseven-w/dsh-openpencil

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• DSH_OPENPENCIL_EDITOR_BINARY 用于 op-host-web-server；
• DSH_OPENPENCIL_SOURCE_ROOT（或 OPENPENCIL_SOURCE_ROOT）用于 Web 打包产物与 CanvasKit 资源。
• image：PNG 路径、预览/下载 URL 以及真实宽高；
• frames：按活动页面顺序排列的每个精确渲染的顶层帧，包括其节点 id/名称/索引以及签名的 PNG URL；
• document：源操作路径以及不可变快照 URL、字节数与 SHA-256；

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

安装前需要先装 OpenPencil 桌面 App 吗？

想要"精确"渲染（fidelity=exact）需要 OpenPencil 二进制（macOS 上是 /Applications/OpenPencil.app/Contents/MacOS/openpencil-desktop，或用 DSH_OPENPENCIL_BINARY / DSH_OPENPENCIL_DESKTOP 指定）。找不到时会自动降级到 Jian 渲染并在结果里标记 fidelity=runtime-preview；这两种都不在路径里则会报错。

插件里看到的"只读画布"和"侧边栏编辑器"是一回事吗？

不是。只读画布来自 OpenPencil Web SDK，挂在 PNG 卡片下方，支持平移、缩放、检查任意节点但不能改；侧边栏编辑器是托管的 op-host-web-server 进程，提供图层、属性、绘图工具、撤销/重做和显式保存语义，只有它能真正改写 .op 文件。

用 openpencil_new / openpencil_edit 之后改动会自动保存到 .op 文件吗？

不会。openpencil_new 会原子保存新文件，但 openpencil_create 和 openpencil_edit 只是把改动应用到实时画布，必须由用户在侧边栏编辑器里点 Save 才会写入原文件；中途卸载插件会留 7 天的恢复草稿（最多 32 个）。

渲染时为什么 width / height 报错？

精确 OpenPencil 渲染不支持手动指定宽高（renderer.ts:687、tool.ts:167），只接受 scale（0 < scale ≤ 8，默认 1）；只有降级到 Jian 才接受 width/height，并会以 runtime-preview 标记区分。

数据存在哪里？会上传到云端吗？

设计文档走 DSH 受控工作区文件系统（new-tool.ts 通过 sandboxPolicy.resolve 获取 cwd），渲染产物、签名令牌与恢复草稿落在本地 $DSH_HOME/cache/dsh-openpencil；预览 URL 是同源签名能力凭据，浏览器只拿文件名 + SHA-256 + 字节数，宿主路径不外泄，所有这些都是本机资源，不出网。

怎么卸载？卸载后能恢复未保存的画布吗？

直接 dsh plugin --profile web remove @zseven-w/dsh-openpencil（标准 DSH 插件移除流程）；如果在编辑器里有未保存改动且插件被卸载，editor-recovery.ts 会按"client-dispose"或"plugin-dispose"留下一个不透明的本地草稿，TTL=7 天、最多 32 个，重新打开同源 .op 时会提示是否恢复，但不会自动覆盖 .op 文件。

出现 "source changed since this preview" 报错怎么解决？

这表示外部进程在你打开编辑器后改了 .op 文件，乐观哈希比对失败，编辑器拒绝覆盖以保护未保存的改动；按提示再调用一次 openpencil_render，重新生成最新版本的能力凭据再编辑即可。

— 源: plugin_wiki.faq_json

兼容性

• DSH: >= 0.1.0-rc.6（peerDependencies 中所有 @deepseek-ai/dsh-* 包均为 ^0.1.0-rc.6，@deepseek-ai/cordis ^4.0.1）
• Node: >=24.11.0（package.json#engines.node）

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则