Preface

When creating interfaces or visual drafts in DeepSeek Harness (DSH), the common approach is to have the Agent directly modify HTML/CSS or export static images. While these paths can produce results, they do not align with pen.dev’s .pen document model and the official editor’s workflow: the canvas state is difficult to bind with the session, and after the Agent modifies the draft, it may not immediately render and save in the visible editor.

dsh-with-pencil, developed by community maintainer IWAIBAOLI, integrates the official @pen.dev/cli headless engine and the compatible official browser editor into DSH Web. DeepSeek remains the design Agent; the plugin facilitates collaboration between the model tools, current session, and the Pencil canvas. It is not a rewrite of Pencil, nor an independent design product, and has no official endorsement from pen.dev or DeepSeek.

What Is This

In one sentence: A session-aware Pencil integration plugin for DSH Web, providing on-demand canvas, nine core model tools, and official MCP design capabilities.

Maintainer and Repository:

  • Maintainer: IWAIBAOLI
  • GitHub: https://github.com/IWAIBAOLI/dsh-with-pencil
  • Current npm version: 0.5.4 (MIT License)
  • Community Directory: https://www.skillhub.cn/plugins/IWAIBAOLI/dsh-with-pencil (Category: Fun Dressing)

Core Features

The following summarizes the capabilities as outlined in the README, without expanding on behaviors not mentioned in the documentation.

On-Demand Canvas and Session-Bound Workspace

The canvas does not automatically open when Harness starts. Each session binds its own workspace: when switching sessions, the canvas hides, and when switching back, the original editor session is restored. The interface provides approximately a 42% split-screen view, supports pointer-safe drag-to-resize, and also offers a floating layout option.

Agent Real-Time Editing and Saving

The Agent can perform real-time editing through the visible editor’s IPC, with changes rendering immediately and being saved to disk atomically. When the browser canvas is closed, the plugin serializes calls to the official headless engine as a fallback path.

Selection Context and Screenshot Attachments

The plugin can inject the current selection context into the next Agent turn and support generating real image attachments from Pencil screenshots. Within the workspace, file operations such as opening, creating, saving as, exporting to PNG/PDF, importing, generating images, design library, reloading external changes, and conflict handling are all completed within the workspace security boundary.

Nine Core Model Tools

The plugin registers the following tools (complete list as per README):

  • pencil_mcp_open — Opens or switches the current session’s .pen file; should be called first for any design task.
  • pencil_mcp_get_app_state — Reads the current document state; returns the .pen schema when include_schema: true.
  • pencil_mcp_batch_get — Reads node data by ID or pattern, used for verifying text and attributes.
  • pencil_mcp_get_guidelines — Gets design guidelines and styles.
  • pencil_mcp_execute — Edits the document using JS snippets (Update/Insert/Copy/Delete/Move/Set/Replace).
  • pencil_mcp_get_screenshot — Visual spot-checks (color, font, alignment); large nodes and full pages are automatically rendered at high resolution.
  • pencil_mcp_export_html — Exports nodes to HTML.
  • pencil_mcp_export_nodes — Exports nodes to image files (deliverables).
  • pencil_mcp_insert_image — Places an image onto the canvas using pen.dev’s official image-fill.

Additionally, five legacy one-time CLI helper tools (status, login, workspaces, design, export) are hidden by default. They are enabled only when compatibility is required by setting DSH_PEN_LEGACY_TOOLS=1.

pencil_mcp_insert_image and the native read_image in Harness have separate responsibilities: the former copies attachments into the .pen workspace and places them on the canvas; the latter loads pixels into model contexts that support images. This plugin does not replace read_image.

visionMode Configuration

Set visionMode in Settings → Plugins → dsh-with-pencil (takes effect immediately after saving; default is text on first installation):

  • text — For non-multimodal models like DeepSeek; screenshots are rendered at high resolution to ensure reliable transcription. The image transcription itself is not provided by this plugin and relies on image capability wrappers in the deployment (e.g., wrapper/stealth routes from dsh-vision-proxy or dsh-vision-router).
  • multimodal — The model directly sees the screenshot pixels.

Installation and Enabling

Environment requirement: Node.js >= 22.15.0.

Install the npm package under a configured DSH Web profile:

npx @deepseek-ai/dsh plugin --profile web add dsh-with-pencil

Stop the running DSH process (Ctrl-C), then restart Web:

npx @deepseek-ai/dsh web

The npm package installs a fixed version of the official @pen.dev/cli (0.3.0). When the canvas is first opened, the plugin downloads the editor 0.1.94 from pen.dev’s official source, verifies a fixed SHA-256, and caches it to ~/.dsh/dsh-with-pencil/editor/0.1.94/. No downloads or openings occur during the Harness startup phase; subsequent canvas openings use the verified cache.

The browser editor is not distributed with the npm package. For offline use, you can pre-download the same official package, unzip it, and point DSH_PEN_EDITOR_DIR to its out directory.

For local development from source:

npm run dev:install -- --profile web
npx @deepseek-ai/dsh web

Before installation, please review the repository source and MIT license yourself; the plugin runs with the current DSH process permissions.

Typical Usage

Creating a Pencil Designer Preset

In a regular Harness session, send the following prompt once to have the Agent create and validate an Agent Preset named Pencil Designer (original prompt from README, can be reused directly):

Create and validate a Harness Agent Preset named Pencil Designer; do not merely explain the steps. Base it on the standard coding preset and retain the fixed official tools.

Assign these Pencil design tools to the preset, and no other design tools: pencil_mcp_open, pencil_mcp_get_app_state, pencil_mcp_get_guidelines, pencil_mcp_execute, pencil_mcp_get_screenshot, pencil_mcp_export_html, pencil_mcp_export_nodes, and pencil_mcp_insert_image. Also bind one available vision tool and put its exact name in the persona; if none is available, ask the user.

The persona must tell the Agent to complete .pen design tasks directly using only the design and vision tools assigned to this preset. Before calling a tool, read its own description and parameter definitions in the Agent’s available-tools list; those descriptions are the complete usage reference — do not search for, probe, or verify usage anywhere else.

The persona must require the Agent, when starting a new design, to first use pencil_mcp_open to create a .pen file inside the workspace, then edit, take screenshots, and visually verify it until it is saved. Verify visually with pencil_mcp_get_screenshot (a visual-fidelity spot check: colors, font rendering, alignment/spacing, layout positions; large nodes render at high resolution automatically). Verify text and property content with pencil_mcp_batch_get (node reads). Use pencil_mcp_export_nodes only for deliverable files. Do not use unspecified design tools or inspect any source code or repository to find tools or study their usage. Prefer the assigned design tools for .pen edits; do not treat direct JSON editing as the default.

When finished, report the preset name/path, the bound vision tool, and how to select the preset. Do not modify any other preset.

General Sequence for Design Tasks

  1. Use pencil_mcp_open to create or open a .pen file within the workspace.
  2. Use pencil_mcp_execute to edit nodes.
  3. Use pencil_mcp_get_screenshot for visual verification.
  4. Use pencil_mcp_batch_get to verify text and attributes.
  5. When deliverable files are needed, use pencil_mcp_export_nodes or pencil_mcp_export_html.

Use Cases and Considerations

Suitable for users who want the Agent in DSH to directly operate the official Pencil workflow: UI sketches within sessions, component layout iterations, and design tasks requiring .pen source files and PNG/PDF deliverables. If only one-time static images or pure code frontends are needed, this plugin may not be necessary.

Considerations:

  • This plugin depends on the DSH Web profile and corresponding peer dependencies (@deepseek-ai/dsh-tools, etc.).
  • When visionMode=text, the pure text route will reject chat image inputs before the plugin runs; it must be paired with image capability wrappers in the deployment.
  • The plugin reads and writes the workspace and cache directories with DSH process permissions; review the source and license before installation and enabling.
  • SkillHub is an independent community directory with no official affiliation to DeepSeek or High-Flyer; the DSH ecosystem follows an “everything is a plugin” philosophy, and this package is a community plugin, not an official app store entry.

Conclusion

dsh-with-pencil aligns the official Pencil headless engine, browser editor, and DSH session model tools: on-demand canvas, session-bound workspace, Agent real-time editing, and nine MCP design tools, making it suitable for completing the .pen design workflow within Harness.

  • Community Directory: https://www.skillhub.cn/plugins/IWAIBAOLI/dsh-with-pencil
  • GitHub: https://github.com/IWAIBAOLI/dsh-with-pencil