This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

dsh-openpencil

— source: plugin_wiki.wiki_content

Install & verify

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

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

• DSH_OPENPENCIL_EDITOR_BINARY for op-host-web-server;
• DSH_OPENPENCIL_SOURCE_ROOT (or OPENPENCIL_SOURCE_ROOT) for the web bundle and CanvasKit assets.
• image: PNG path, preview/download URLs, and real width/height;
• frames: every exact-rendered top-level frame in active-page order, including its node id/name/index and signed PNG URLs;
• document: source action path plus immutable snapshot URL, bytes, and SHA-256;

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

Do I need to install the OpenPencil desktop app before installing?

Exact rendering (fidelity=exact) requires the OpenPencil binary (on macOS it's /Applications/OpenPencil.app/Contents/MacOS/openpencil-desktop, or specify via DSH_OPENPENCIL_BINARY / DSH_OPENPENCIL_DESKTOP). When not found, it automatically falls back to Jian rendering and marks the result as fidelity=runtime-preview; if neither is in the PATH, an error is thrown.

Is the "read-only canvas" and "sidebar editor" in the plugin the same thing?

No. The read-only canvas comes from the OpenPencil Web SDK, mounted under the PNG card, supporting pan, zoom, and inspecting any node but cannot modify; the sidebar editor is the hosted op-host-web-server process, providing layers, properties, drawing tools, undo/redo and explicit save semantics, and only it can truly rewrite the .op file.

Will changes be automatically saved to the .op file after using openpencil_new / openpencil_edit?

No. openpencil_new atomically saves new files, but openpencil_create and openpencil_edit only apply changes to the live canvas; the user must click Save in the sidebar editor to write to the original file; uninstalling the plugin mid-way leaves recovery drafts for 7 days (up to 32).

Why does width / height cause an error when rendering?

Exact OpenPencil rendering does not support manually specifying width/height (renderer.ts:687, tool.ts:167), it only accepts scale (0 < scale ≤ 8, default 1); only when falling back to Jian does it accept width/height, and will be distinguished with runtime-preview marking.

Where is data stored? Is it uploaded to the cloud?

Design documents go through DSH controlled workspace file system (new-tool.ts gets cwd via sandboxPolicy.resolve), rendering outputs, signing tokens and recovery drafts land in local $DSH_HOME/cache/dsh-openpencil; preview URLs are same-origin signed capability credentials, the browser only gets filename + SHA-256 + byte count, host paths are not leaked, all these are local resources and do not go to the network.

How to uninstall? Can unsaved canvases be recovered after uninstallation?

Simply dsh plugin --profile web remove @zseven-w/dsh-openpencil (standard DSH plugin removal flow); if there are unsaved changes in the editor and the plugin is uninstalled, editor-recovery.ts will leave an opaque local draft based on "client-dispose" or "plugin-dispose" with TTL=7 days, max 32, when reopening the same-origin .op file it will prompt whether to restore, but will not automatically overwrite the .op file.

How to resolve the "source changed since this preview" error?

This means an external process modified the .op file after you opened the editor, optimistic hash comparison failed, the editor refuses to overwrite to protect unsaved changes; follow the prompt and call openpencil_render again to regenerate the latest version capability credentials before editing.

— source: plugin_wiki.faq_json

Compatibility

• 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）

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule