dsh-with-pencil

English · 简体中文

English

Use the official pen.dev Pencil editing capabilities inside DeepSeek Harness.
DeepSeek remains the design agent; this community DSH plugin makes its model
tools, the active conversation, and the Pencil canvas work together.

This is not a Pencil rewrite or a standalone design product. It integrates the
official @pen.dev/cli headless engine and a compatible official browser editor
with DSH. It is independent and is not endorsed by pen.dev or DeepSeek.

What it provides

• An on-demand Pencil canvas that does not open when Harness starts.
• Conversation-bound workspaces: the canvas hides when you switch conversations
  and returns with its original editor session when you switch back.
• Live Agent edits through the visible editor IPC, with immediate rendering and
  acknowledged, atomic disk saves.
• A serialized official headless fallback when the browser canvas is closed.
• Selection context injection for the next Agent turn, plus real image
  attachments from Pencil screenshots.
• Workspace-safe file opening, creation, Save As, live PNG/PDF export, imports,
  generated images, design libraries, external-change reloads, and conflict
  resolution.
• A native DSH right-Sidebar tab with the built-in split, resize, float, and
  session layout restoration controls.

The plugin registers nine core model tools:

• pencil_mcp_open
• pencil_mcp_get_app_state
• pencil_mcp_batch_get
• pencil_mcp_get_guidelines
• pencil_mcp_execute
• pencil_mcp_get_screenshot
• pencil_mcp_export_html
• pencil_mcp_export_nodes
• pencil_mcp_insert_image

Create a Pencil Agent preset

Send this prompt once in a normal Harness conversation:

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_batch_get,
pencil_mcp_get_guidelines, pencil_mcp_execute,
pencil_mcp_get_screenshot, pencil_mcp_export_html,
pencil_mcp_export_nodes, and pencil_mcp_insert_image. Bind Harness
read_image if available for local image files. With DeepSeek-V4.1-Flash,
the model can inspect screenshot attachments directly.

The persona must tell the Agent to complete .pen design tasks directly using
only the 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). 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 and how to
select the preset. Do not modify any other preset.

Five legacy one-shot CLI helpers are hidden by default to avoid duplicated
capabilities and irrelevant model context. Set DSH_PEN_LEGACY_TOOLS=1 only
when compatibility requires status, login, workspaces, design, and
export.

Model tools

• pencil_mcp_open — open/switch the conversation's .pen file; call FIRST
  for any design work.
• pencil_mcp_get_app_state — current document state; include_schema: true
  returns the .pen schema.
• pencil_mcp_batch_get — read node data (text content, properties) by ID or
  pattern — the authoritative way to verify text and attribute values.
• pencil_mcp_get_guidelines — design guides and styles.
• pencil_mcp_execute — edit the document with a JS snippet
  (Update/Insert/Copy/Delete/Move/Set/Replace).
• pencil_mcp_get_screenshot — visual-fidelity spot check (colors, fonts,
  alignment). The default native-vision path uses Pencil's native screenshot;
  the vision-translation mode uses high-resolution export for large nodes and
  whole documents when the canvas is open.
• pencil_mcp_export_html — export nodes to HTML.
• pencil_mcp_export_nodes — export nodes to image files (deliverables).
• pencil_mcp_insert_image — place an image onto the canvas using pen.dev's
  official image-fill: writes the image into images/ next to the .pen and
  inserts a frame whose fill is {type:"image", url, mode}. Accepts a chat
  image as latest, recent:N (recent:1 = latest), an exact attachment id,
  or a local image file path; optional parentId / width / height / x /
  y / mode (fit|fill|stretch). Width/height default to 400×300 when omitted
  (the engine cannot auto-size an image-fill node).

Harness's native read_image and this tool have separate jobs: read_image
loads pixels into an image-capable model's context, while
pencil_mcp_insert_image copies the original attachment into the .pen
workspace and places it on the canvas. This plugin does not replace or register
read_image.

Configuration

visionMode (Plugins → dsh-with-pencil → Configure, default multimodal):

• multimodal — native screenshots for an image-capable model. The default
  Harness deepseek-flash entry is DeepSeek-V4.1-Flash and declares image
  input. No separate image-transcription plugin is needed for this route.
• text — high-resolution screenshots and a visual-fidelity instruction for
  an image-capable vision-translation wrapper (for example,
  dsh-vision-proxy or a dsh-vision-router wrapper). This plugin does not
  translate images itself. A direct text-only Harness route cannot consume
  screenshot attachments, even with this setting.

The plugin checks the active session route's declared image input before each
screenshot. The setting takes effect immediately after saving. If a profile
already has an explicit text override, use Reset to default to select
native vision. The default deepseek-v4-pro entry is text-only, so it cannot
consume screenshots. Custom model catalog entries must declare image input
themselves.

Install

Version 0.6.0 targets Harness 0.1.7-rc.2 only. Configure visionMode
again in the new Plugins page after upgrading from an older Harness.

After 0.6.0 is published, install the npm bundle into a DeepSeek Harness
0.1.7-rc.2 Web profile:

npx @deepseek-ai/[email protected] plugin --profile web add [email protected]

Restart DSH Web after installation (Ctrl-C the running process first):

npx @deepseek-ai/[email protected] web

That is the complete normal installation. The npm bundle installs the pinned
official @pen.dev/cli. The first time you open a canvas, the plugin downloads
editor 0.1.94 directly from the official pen.dev release source, verifies its
pinned SHA-256 checksum, and atomically caches it under
~/.dsh/dsh-with-pencil/editor/0.1.94/. Harness startup does not download or
open anything, and subsequent canvas opens use the verified cache.

The browser editor is not copied into or redistributed through this npm
package. For offline use, download and extract the same official bundle ahead
of time and point DSH_PEN_EDITOR_DIR to its out directory.

For local development from this checkout:

npm run dev:install -- --profile web
npx @deepseek-ai/[email protected] web

dev:install runs the complete test suite, packs the exact publishable files
into .dev-builds/ with a content hash in the tarball name, installs that
unique snapshot, and verifies the installed files. This avoids pnpm reusing an
old same-version file: snapshot and avoids the duplicate native libraries a
source link: can load. Stop the running DSH process before installation and
restart it afterward. Use npm run dev:pack only when an install is not needed.

When migrating from an older development build, remove pen-dev-bridge-bundle
and pen-dev-bridge first so the same canvas routes are not registered twice.

The development-only profile fixture is available at
profiles/dsh-with-pencil-template/.

Environment variables

Variable	Purpose
DSH_PEN_EDITOR_DIR	Optional offline/development override for an official editor out directory
DSH_PEN_EDITOR_CACHE_DIR	Override the automatic editor cache root; defaults to ~/.dsh/dsh-with-pencil/editor
DSH_PEN_FILE	Initial workspace-relative .pen path; defaults to designs/design.pen
DSH_PEN_CLI_BIN / DSH_PEN_MCP_BIN	Override official CLI/MCP paths; normally unnecessary
DSH_PEN_MCP_APP	Explicitly connect an external Pencil app; no automatic probing
DSH_PEN_LEGACY_TOOLS	Set to 1 to register five legacy CLI helpers
PEN_CLI_KEY / PENCIL_CLI_KEY	pen.dev organization CLI key
DSH_PEN_STATE_FILE	Browser session file; defaults to ~/.dsh/dsh-with-pencil/state.json and reads the old location for compatibility

Canvas behavior

• The conversation button opens a pen.dev Canvas tab in DSH's right Sidebar.
  DSH owns tab placement, split, resize, float, and per-session layout recovery.
  Reopening the canvas focuses its existing tab.
• The canvas chrome and Pencil editor follow the active Harness/system light or
  dark theme automatically; the plugin adds no separate theme control.
• The toolbar contains workspace, .pen file, and export controls. DSH provides
  the tab and layout controls. Plugin-owned controls follow the active Harness
  language; the official Pencil editor keeps its upstream English interface.
• Closing the tab saves pending canvas edits before releasing the live editor.
  If saving fails, the tab stays open and shows the error for a retry.
• The iframe container stays mounted within its conversation. Switching .pen
  files saves the previous document and reloads the official editor with the new
  file URI; its internal resource base is fixed at initialization. This resets
  transient selection/undo state for the newly opened document.
• Manual edits autosave every six seconds; Agent edits await a save after every
  successful operation.
• Save As writes a new .pen inside the workspace, never overwrites an existing
  target, switches the canvas to the copy, and leaves the source unchanged. The
  official serializer rebases resource URLs for the destination; assets remain
  in their existing locations. Cross-directory moves require opening the source
  in the canvas first so the same serializer can preserve its resources.
• Export uses the live editor state: it writes the selected nodes, or every
  top-level node when nothing is selected, as 2× PNG files or a PDF under
  exports/<document-name>/. The result menu can open that folder directly.
• Imported and generated images are persisted to an adjacent images/
  directory. SVG is converted into nodes by the official editor.
• Workspace *.lib.pen files and read-only libraries shipped with the official
  CLI appear in the editor library list.
• External conflicts and save failures remain visible in the toolbar and never
  silently overwrite a dirty document.
• Shutdown flushes dirty canvases before releasing their sessions.
• The pinned editor downloads only on the first canvas open; download,
  checksum, extraction, or compatibility failures appear before an empty
  iframe opens.
• Cancelled requests that have not reached the editor are removed from its
  queue; delivered requests require a canvas-state check before retrying.

The integration's lib/session-file.js owns the conversation's current .pen
path, encoded file URI, directory, and switch revision. The canvas, resource
imports, and headless fallback all use that identity; closing a renderer does
not clear it. A dropped image travels through the official editor's binary
import request → host writes to the current .pen's images/ → relative URL
returned → editor resolves it against that same file URI → host reads bytes →
official image fill renders. Late messages from a previous document revision
are rejected. pencil_mcp_insert_image also refuses a mismatched filePath or a
document switch during asset preparation; call pencil_mcp_open first to select
a different file. No official editor source or bundle is patched.

This integration is MIT licensed; official pen.dev and DeepSeek components are
not. See THIRD_PARTY_NOTICES.md.

---

简体中文

让 DeepSeek Harness 使用官方 pen.dev（Pencil）的编辑能力。DeepSeek 仍然是设计 Agent；
这个社区 DSH 插件只负责让模型工具、当前会话和 Pencil 画布协同工作。

它不是 Pencil 的重写版，也不是独立设计产品。插件对接官方 @pen.dev/cli headless
引擎和兼容的官方浏览器编辑器，项目独立维护，未获得 pen.dev 或 DeepSeek 的背书。

提供的能力

• 按需打开 Pencil 画布，Harness 启动时不会自动显示。
• 画布绑定所属会话：切换到其他会话时隐藏，返回后恢复原来的 editor session。
• Agent 编辑直接进入可见 editor IPC，实时渲染，并等待确认后的原子磁盘保存。
• 画布关闭时使用串行化的官方 headless 引擎。
• 将画布选区注入下一轮 Agent 上下文，并把 Pencil 截图作为真正的图片附件返回。
• 在会话工作区边界内提供文件打开、新建、另存为、实时 PNG/PDF 导出、资源导入、
  生成图片、设计库、外部修改重载和冲突处理。
• 使用 DSH 原生右侧栏标签页，支持内置分屏、调整宽度、浮窗和按会话恢复布局。

插件默认注册 9 个核心模型工具：

• pencil_mcp_open
• pencil_mcp_get_app_state
• pencil_mcp_batch_get
• pencil_mcp_get_guidelines
• pencil_mcp_execute
• pencil_mcp_get_screenshot
• pencil_mcp_export_html
• pencil_mcp_export_nodes
• pencil_mcp_insert_image

创建 Pencil Agent Preset

在普通 Harness 会话中发送一次以下提示词：

请实际创建并验证一个名为「Pencil 设计」的 Harness Agent Preset，不要只说明步骤。
基于标准编码 Preset，保留官方固定工具。

为该 Preset 指定以下 Pencil 设计工具：pencil_mcp_open、
pencil_mcp_get_app_state、pencil_mcp_batch_get、pencil_mcp_get_guidelines、
pencil_mcp_execute、pencil_mcp_get_screenshot、
pencil_mcp_export_html、pencil_mcp_export_nodes、
pencil_mcp_insert_image，不再指定其他设计工具。
如有 Harness read_image，可绑定它读取本地图片。DeepSeek-V4.1-Flash 可直接查看
截图工具返回的图片附件。

Persona 应要求 Agent 直接完成 .pen 设计任务，只使用该 Preset 指定的工具。
调用前查看 Agent 可用工具列表中这些工具自带的说明和参数定义；这些说明即完整
用法，不得再去其他地方查找、试探测或验证用法。

Persona 应要求 Agent 在新建设计时，先用 pencil_mcp_open 创建工作区内的 .pen
文件，再使用指定工具编辑、截图并进行视觉验证，直至保存完成。视觉验证使用
pencil_mcp_get_screenshot 做视觉保真抽查（颜色、字体渲染、对齐/间距、布局
位置）。文字与属性内容用
pencil_mcp_batch_get 按节点读取验证。pencil_mcp_export_nodes 仅用于交付
文件产物。不得使用未指定的设计工具，不得通过翻查任何源码或仓库来寻找工具、研究
用法。编辑 .pen 时优先使用指定设计工具，不把直接修改 JSON 作为默认方式。

创建完成后，报告 Preset 名称或路径及选择方法；不要修改其他 Preset。

为避免重复能力和无关上下文，5 个旧的一次性 CLI 助手默认隐藏。仅在兼容需要时设置
DSH_PEN_LEGACY_TOOLS=1，恢复 status、login、workspaces、design 和
export。

模型工具

• pencil_mcp_open — 打开/切换会话的 .pen 文件；任何设计任务先调用它。
• pencil_mcp_get_app_state — 当前文档状态；include_schema: true 返回 .pen schema。
• pencil_mcp_batch_get — 按节点 ID/模式读取节点数据（文字内容、属性）——验证文字与
  属性值的权威方式。
• pencil_mcp_get_guidelines — 设计指南与样式。
• pencil_mcp_execute — 用 JS 片段编辑文档（Update/Insert/Copy/Delete/
  Move/Set/Replace）。
• pencil_mcp_get_screenshot — 视觉保真抽查（颜色、字体、对齐）。默认的原生视觉
  路径使用 Pencil 原生截图；图像转译模式在画布打开时对大节点和整文档使用高清导出。
• pencil_mcp_export_html — 导出节点为 HTML。
• pencil_mcp_export_nodes — 导出节点为图片文件（交付物）。
• pencil_mcp_insert_image — 用 pen.dev 官方 image-fill 把图片放进画布：把图片写入
  .pen 旁的 images/ 并插入一个 fill:{type:"image",url,mode} 的 frame。接受
  latest、recent:N（recent:1 即最新图片）、准确附件 id 或本地图片路径；可选
  parentId/width/height/x/y/mode（fit|fill|stretch）。未指定尺寸时默认
  400×300（引擎无法对 image-fill 节点自动算尺寸）。

Harness 原生 read_image 与本工具职责不同：read_image 把像素送入具备图片能力的
模型上下文，pencil_mcp_insert_image 则把原始附件复制到 .pen 工作区并放进画布。
本插件不会替换或注册 read_image。

配置

visionMode（插件 → dsh-with-pencil → 配置，默认 multimodal）：

• multimodal — 适用于支持图片输入的模型，使用原生截图。Harness 默认的
  deepseek-flash 条目对应 DeepSeek-V4.1-Flash，已声明图片输入；这条路由不需要
  额外的图片转译插件。
• text — 仅供支持图片输入的图像转译包装路由使用，提供高清截图及视觉保真
  提示；例如 dsh-vision-proxy 或 dsh-vision-router 的包装路由。本插件本身不做
  图片转译。Harness 直连纯文本路由即使选择此模式，也无法消费截图附件。

插件在每次截图前检查当前会话路由是否声明图片输入。配置保存后立即生效；如果
Profile 已显式保存 text，请点重置为默认切回原生视觉。自定义模型目录条目须
自行声明图片输入。默认的 deepseek-v4-pro 条目仅支持文字，因此不能消费截图。

安装

0.6.0 仅支持 Harness 0.1.7-rc.2。从旧版 Harness 升级后，请在新版插件页重新设置
visionMode。

0.6.0 发布后，在已有 DeepSeek Harness 0.1.7-rc.2 Web profile 中安装 npm Bundle：

npx @deepseek-ai/[email protected] plugin --profile web add [email protected]

安装完成后重启 DSH Web（先用 Ctrl-C 停止正在运行的进程）：

npx @deepseek-ai/[email protected] web

这就是正常情况下的完整安装步骤。npm Bundle 会安装固定版本的官方 @pen.dev/cli。
用户第一次打开画布时，插件才会从 pen.dev 官方发行源直接下载 editor 0.1.94，核对
固定的 SHA-256 校验值，并原子缓存到
~/.dsh/dsh-with-pencil/editor/0.1.94/。Harness 启动时不会下载或打开画布，之后再次
打开会直接使用已验证缓存。

npm 包本身不复制或再分发 browser editor。离线环境可以预先下载并解压相同的官方版本，
再用 DSH_PEN_EDITOR_DIR 指向它的 out 目录。

从本仓库进行本地开发安装：

npm run dev:install -- --profile web
npx @deepseek-ai/[email protected] web

dev:install 会先运行完整测试，再把实际可发布文件打成文件名带内容哈希的唯一 tarball，
安装该快照并核对安装文件。这样既不会命中 pnpm 的同版本 file: 旧快照，也不会像源码
link: 一样加载重复的原生库。安装前先停止 DSH，安装后重新启动。只需要构建、不安装时
使用 npm run dev:pack。从旧开发版迁移时，先移除 pen-dev-bridge-bundle 和
pen-dev-bridge，避免相同画布路由被注册两次。

开发用 profile 模板位于 profiles/dsh-with-pencil-template/。

环境变量

变量	说明
DSH_PEN_EDITOR_DIR	可选的离线/开发覆盖项，指向官方 editor 的 out 目录
DSH_PEN_EDITOR_CACHE_DIR	覆盖自动下载缓存根目录；默认 ~/.dsh/dsh-with-pencil/editor
DSH_PEN_FILE	会话首次打开的 .pen 相对路径，默认 designs/design.pen
DSH_PEN_CLI_BIN / DSH_PEN_MCP_BIN	覆盖官方 CLI/MCP 路径；通常无需设置
DSH_PEN_MCP_APP	显式连接外部 Pencil app；默认不自动探测
DSH_PEN_LEGACY_TOOLS	设为 1 时注册 5 个旧 CLI 助手
PEN_CLI_KEY / PENCIL_CLI_KEY	pen.dev 组织 CLI key
DSH_PEN_STATE_FILE	Browser 登录态文件，默认 ~/.dsh/dsh-with-pencil/state.json，并兼容读取旧路径

画布行为

• 会话按钮会在 DSH 右侧栏打开 pen.dev 画布 标签页。DSH 负责标签页位置、
  分屏、调整宽度、浮窗和按会话恢复布局；再次打开会定位到已有标签页。
• 画布外框和 Pencil editor 自动跟随 Harness/系统的明暗主题；插件不增加单独的主题开关。
• 画布顶栏提供工作区、.pen 文件和导出操作；标签页与布局操作由 DSH 提供。
  插件自有控件跟随当前 Harness 语言；官方 Pencil editor 保持其上游英文界面。
• 关闭标签页前会先保存待写入的画布修改，再释放在线编辑器；若保存失败，标签页会保留并显示错误，供重试。
• iframe 容器在当前会话中保持挂载。切换 .pen 时先保存旧文档，再以新文件 URI
  重新初始化官方 editor，因为它的资源基准路径在初始化时固定；新打开文档的选区和撤销历史会重置。
• 用户手工编辑每 6 秒触发保存；Agent 编辑逐次等待保存确认。
• “另存为”在工作区内创建新的 .pen，拒绝覆盖已有文件，自动切换到副本并保持原文件不变。
  由官方序列化接口按目标位置转换资源相对路径，素材保留在原位置；跨目录移动需先在画布打开源文件。
• 导出直接读取当前可见 editor：有选区时导出选区，否则导出全部顶层元素；可输出 2× PNG
  或 PDF 到 exports/<文档名>/，并从结果菜单直接打开该文件夹。
• 导入和生成的图片保存到设计旁的 images/；SVG 由官方 editor 转换成节点。
• 工作区 *.lib.pen 和官方 CLI 随附的只读库会出现在 editor 设计库列表中。
• 外部冲突和保存失败会一直显示在顶栏，不会静默覆盖脏文档。
• 插件退出时会在释放会话前冲洗仍有修改的画布。
• 固定版本 editor 只在首次打开画布时下载；下载、校验、解压或兼容性错误会在空白 iframe
  打开前明确显示。
• 尚未交付 editor 的取消请求会从队列删除；已交付的请求要求先检查画布状态再重试。

接入层的 lib/session-file.js 统一管理会话当前 .pen 的绝对路径、编码后的文件 URI、
所在目录及切换版本。画布、图片导入与无界面引擎都使用这份身份；关闭渲染器不会清空当前文件。
拖图链路为：官方 editor 发送图片字节 → 宿主存入当前 .pen 旁的 images/ → 返回相对路径
→ editor 基于同一个文件 URI 解析 → 宿主读取图片字节 → 官方图片填充渲染。
旧文档版本的迟到消息会被拒绝；pencil_mcp_insert_image 也会拒绝与当前文件不一致的
filePath 或准备图片期间的文件切换。要操作其他文件，请先调用 pencil_mcp_open。
整个过程不修改官方 editor 源码或打包文件。

本对接代码采用 MIT 许可；官方 pen.dev 与 DeepSeek 组件不属于该许可，详见
THIRD_PARTY_NOTICES.md。