前言¶

在 DeepSeek Harness（DSH）里做界面或视觉稿，常见做法是让 Agent 直接改 HTML/CSS，或导出静态图片。这类路径能出结果，但和 pen.dev 的 .pen 文档模型、官方编辑器并不在同一套工作流里：画布状态难以跟会话绑定，Agent 改稿后也不一定能即时在可见编辑器里渲染并落盘。

dsh-with-pencil 由社区维护者 IWAIBAOLI 开发，把官方 @pen.dev/cli 无头引擎与兼容的官方浏览器编辑器接到 DSH Web 上。DeepSeek 仍是设计 Agent；插件负责让模型工具、当前会话与 Pencil 画布协同工作。它不是 Pencil 的重写版，也不是独立设计产品，且与 pen.dev、DeepSeek 无官方背书关系。

这是什么¶

一句话定位：面向 DSH Web 的会话感知型 Pencil 集成插件，提供按需画布、9 个核心模型工具，以及官方 MCP 设计能力。

维护者与仓库：

• 维护者：IWAIBAOLI
• GitHub：https://github.com/IWAIBAOLI/dsh-with-pencil
• 当前 npm 版本：0.5.4（MIT 许可证）
• 社区目录：https://www.skillhub.cn/plugins/IWAIBAOLI/dsh-with-pencil（分类：趣味换装）

核心功能¶

下面按 README 已写明的能力归纳，不展开未在资料中出现的行为。

按需画布与会话绑定工作区¶

Harness 启动时不会自动打开画布。每个会话绑定自己的工作区：切换会话时画布隐藏，切回时恢复原有编辑器会话。界面提供约 42% 的分屏视图，支持指针安全的拖拽调整，也可选用浮动布局。

Agent 实时改稿与落盘¶

Agent 可通过可见编辑器的 IPC 进行实时编辑，改动即时渲染，并以原子方式确认写入磁盘。浏览器画布关闭时，插件会序列化调用官方无头引擎作为后备路径。

选型上下文与截图附件¶

插件可向下一轮 Agent 注入当前选型上下文，并支持从 Pencil 截图生成真实图片附件。工作区内的文件打开、新建、另存为、PNG/PDF 导出、导入、生成图片、设计库、外部变更重载与冲突处理，均在工作区安全边界内完成。

九个核心模型工具¶

插件注册以下工具（README 列出的完整清单）：

• 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_mcp_export_html — 将节点导出为 HTML
• pencil_mcp_export_nodes — 将节点导出为图片文件（交付物）
• pencil_mcp_insert_image — 用 pen.dev 官方 image-fill 把图片放到画布上

另有五个旧版一次性 CLI 辅助工具（status、login、workspaces、design、export）默认隐藏。仅在兼容需要时设置 DSH_PEN_LEGACY_TOOLS=1 启用。

pencil_mcp_insert_image 与 Harness 原生 read_image 职责分离：前者把附件复制进 .pen 工作区并上画布；后者把像素载入支持图像的模型上下文。本插件不替换 read_image。

visionMode 配置¶

在 Settings → Plugins → dsh-with-pencil 中设置 visionMode（保存后立即生效，首次安装默认为 text）：

• text — 面向 DeepSeek 等非多模态模型；截图走高分辨率渲染以保证转写可靠。图像转写本身不由本插件提供，依赖部署中的图像能力包装（如 dsh-vision-proxy 或 dsh-vision-router 的 wrapper/stealth 路由）
• multimodal — 模型直接看到截图像素

安装与启用¶

环境要求：Node.js >= 22.15.0。

在已配置好的 DSH Web profile 下安装 npm 包：

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

先停止正在运行的 DSH 进程（Ctrl-C），再重启 Web：

npx @deepseek-ai/dsh web

npm 包会安装固定版本的官方 @pen.dev/cli（0.3.0）。首次打开画布时，插件从 pen.dev 官方发布源下载编辑器 0.1.94，校验固定 SHA-256 后缓存到 ~/.dsh/dsh-with-pencil/editor/0.1.94/。Harness 启动阶段不会下载或打开任何内容；后续打开画布使用已校验缓存。

浏览器编辑器不会随 npm 包分发。离线使用时，可预先下载同一官方包并解压，将 DSH_PEN_EDITOR_DIR 指向其 out 目录。

从源码本地开发时：

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

安装前请自行查阅仓库源码与 MIT 许可证；插件以当前 DSH 进程权限运行。

典型用法¶

创建 Pencil Designer 预设¶

在普通 Harness 会话中发送一次以下提示，让 Agent 创建并校验名为 Pencil Designer 的 Agent Preset（README 原文提示，可直接复用）：

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.

设计任务的一般顺序¶

1. 用 pencil_mcp_open 在工作区内创建或打开 .pen 文件
2. 用 pencil_mcp_execute 编辑节点
3. 用 pencil_mcp_get_screenshot 做视觉核对
4. 用 pencil_mcp_batch_get 核对文本与属性
5. 需要交付文件时用 pencil_mcp_export_nodes 或 pencil_mcp_export_html

适用场景与注意¶

适合在 DSH 里让 Agent 直接操作官方 Pencil 工作流的用户：会话内 UI 草图、组件布局迭代、需要 .pen 源文件与 PNG/PDF 交付的设计任务。若只需一次性静态图或纯代码前端，不一定需要本插件。

注意事项：

• 本插件依赖 DSH Web profile 与对应 peer 依赖（@deepseek-ai/dsh-tools 等）
• visionMode=text 时，纯文本路由会在插件运行前拒绝聊天图片输入，需配合部署中的图像能力包装
• 插件以 DSH 进程权限读写工作区与缓存目录；安装与启用前应检查源码与许可证
• SkillHub 为独立社区目录，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」思路，本包是社区插件而非官方应用商店条目

结尾¶

dsh-with-pencil 把官方 Pencil 无头引擎、浏览器编辑器与 DSH 会话模型工具对齐：按需画布、会话绑定工作区、Agent 实时改稿与九项 MCP 设计工具，适合在 Harness 内完成 .pen 设计闭环。

• 社区目录：https://www.skillhub.cn/plugins/IWAIBAOLI/dsh-with-pencil
• GitHub：https://github.com/IWAIBAOLI/dsh-with-pencil