Pencil 画布 IWAIBAOLI/dsh-with-pencil

dsh-with-pencil

Awesome DSH Plugin

English · 简体中文

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

这不是 Pencil 的重写版，也不是独立设计产品。它把官方 @pen.dev/cli 无头引擎和兼容的官方浏览器编辑器接入 DSH。它独立开发，未获 pen.dev 或 DeepSeek 认可。

提供什么

- 按需打开的 Pencil 画布，Harness 启动时不会自动打开。
- 会话绑定的工作区：切换会话时画布隐藏，切回来时恢复原来的编辑器会话。
- 智能体实时编辑，走可见的编辑器 IPC，立即渲染，并确认后原子写入磁盘。
- 浏览器画布关闭时，回退到串行化的官方无头引擎。
- 为下一轮智能体注入选中内容上下文，并支持 Pencil 截图生成的真实图片附件。
- 工作区安全的文件打开、创建、另存为、实时 PNG/PDF 导出、导入、生成图片、设计库、外部变更重载和冲突解决。
- 原生 DSH 右侧栏标签页，自带分栏、调整大小、浮动和会话布局恢复控件。

插件注册九个核心模型工具：

- 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 智能体预设

在普通 Harness 会话里发送一次这段提示词：

创建并验证一个名为 Pencil Designer 的 Harness 智能体预设；不要只是解释步骤。基于标准编码预设，保留固定的官方工具。

把下面这些 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 时，模型可以直接查看截图附件。

人设必须告诉智能体：只用分配给该预设的工具，直接完成 .pen 设计任务。调用工具前，先读智能体可用工具列表里该工具自己的描述和参数定义；这些描述就是完整的使用参考——不要到别处搜索、探测或验证用法。

人设必须要求智能体在开始新设计时，先使用用 pencil_mcp_open 在工作区里创建 .pen 文件，然后编辑、截图、目视验证，直到保存完成。用 pencil_mcp_get_screenshot 做目视验证（视觉保真度抽查：颜色、字体渲染、对齐与间距、布局位置）。用 pencil_mcp_batch_get 验证文本和属性内容（读取节点）。pencil_mcp_export_nodes 只用于交付文件。不要使用未指定的设计工具，也不要查看任何源码或仓库来找工具或研究其用法。编辑 .pen 时优先使用指定的设计工具；不要把直接改 JSON 当作默认做法。

完成后，报告预设名称/路径，以及如何选择该预设。不要修改其他任何预设。

五个旧版一次性命令行辅助工具默认隐藏，避免能力重复、也避免无关的模型上下文。只有在兼容性需要 status、login、workspaces、design 和 export 时，才设置 DSH_PEN_LEGACY_TOOLS=1。

模型工具

- 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 官方图片填充把图片放到画布上：把图片写入 .pen 旁边的 images/，并插入一个 frame，其 fill 为 {type:"image", url, mode}。接受聊天图片作为 latest、recent:N（recent:1 = 最新）、精确的附件 id，或本地图片文件路径；可选 parentId / width / height / x / y / mode（fit|fill|stretch）。省略时宽度/高度默认为 400×300（引擎无法自动确定图片填充节点的尺寸）。

Harness 原生的 read_image 和这个工具各司其职：read_image 把像素加载进支持图片的模型上下文，而 pencil_mcp_insert_image 把原始附件复制进 .pen 工作区并放到画布上。这个插件不会替换或注册 read_image。

配置

visionMode（Plugins → dsh-with-pencil → Configure，默认 multimodal）：

- multimodal — 为支持图片的模型使用原生截图。默认 Harness 的 deepseek-flash 条目是 DeepSeek-V4.1-Flash，声明支持图片输入。这条路由不需要单独的图片转写插件。
- text —— 高分辨率截图，外加一条视觉保真指令，交给支持图片的视觉翻译包装器（例如 dsh-vision-proxy 或 dsh-vision-router 包装器）。本插件自己不翻译图片。纯文本的 Harness 直连路由无法消费截图附件，即使开了这个设置也不行。

每次截图前，插件都会检查当前会话路由声明的图片输入能力。保存后设置立即生效。如果某个配置档已经有显式的 text 覆盖，用 Reset to default 选回原生视觉。默认的 deepseek-v4-pro 条目是纯文本的，所以无法消费截图。自定义模型目录条目必须自己声明图片输入。

安装

版本 0.7.0 只面向 Harness 0.2.0-rc.2。已有的 0.6.0 visionMode 设置继续可用。从 0.5.x 或更早版本迁移时，要在 Plugins 页面重新配置 visionMode。

把 npm 包安装进 DeepSeek Harness 0.2.0-rc.2 Web 配置档：

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-with-pencil@0.7.0

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

npx @deepseek-ai/dsh@0.2.0-rc.2 web

以上就是完整的常规安装流程。npm 包会安装固定版本的官方 @pen.dev/cli。第一次打开画布时，插件直接从 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@0.2.0-rc.2 web

dev:install 会跑完整测试套件，把真正要发布的文件打包进 .dev-builds/，tarball 名字里带内容哈希，然后安装这份唯一快照并校验安装后的文件。这样可以避免 pnpm 复用旧的同版本 file: 快照，也避免源码 link: 可能加载的重复原生库。安装前先停掉正在运行的 DSH 进程，安装后再重启。只有在不需要安装时才用 npm run dev:pack。

从旧的开发构建迁移时，先删掉 pen-dev-bridge-bundle 和 pen-dev-bridge，免得同一批画布路由被注册两次。

仅供开发用的配置档模板在 profiles/dsh-with-pencil-template/。

环境变量

| 变量 | 用途 |
| DSH_PEN_EDITOR_DIR | 官方编辑器 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 应用；不自动探测 |
| DSH_PEN_LEGACY_TOOLS | 设为 1 可注册五个旧版 CLI 辅助工具 |
| PEN_CLI_KEY / PENCIL_CLI_KEY | pen.dev 组织 CLI 密钥 |
| DSH_PEN_STATE_FILE | 浏览器会话文件；默认为 ~/.dsh/dsh-with-pencil/state.json，并读取旧位置以兼容 |

画布行为

- 对话按钮会在 DSH 右侧边栏打开 pen.dev Canvas 标签页。
DSH 负责标签页的放置、拆分、调整大小、浮动，以及按会话恢复布局。
重新打开画布会聚焦已有的标签页。
- 画布外壳和 Pencil 编辑器会自动跟随当前 Harness/系统的浅色或深色主题；插件不额外提供主题控制。
- 工具栏包含工作区、.pen 文件和导出控制。DSH 提供标签页和布局控制。
插件自有的控制项跟随当前 Harness 语言；官方 Pencil 编辑器保留其上游英文界面。
- 关闭标签页时，会先保存画布中待处理的编辑，再释放实时编辑器。
如果保存失败，标签页保持打开并显示错误，供你重试。
- iframe 容器始终挂载在所属对话中。切换 .pen 文件时，会保存上一个文档，并用新的文件 URI 重新加载官方编辑器；其内部资源基址在初始化时固定。
这会重置新打开文档的临时选择/撤销状态。
- 手动编辑每六秒自动保存一次；智能体编辑在每次成功操作后等待保存。
- 另存为会在工作区内写入新的 .pen，绝不覆盖已有目标，将画布切换到副本，并保持源文件不变。官方序列化器会为目的地重定资源 URL 的基址；资源仍留在原位置。
跨目录移动需要先在画布中打开源文件，这样同一个序列化器才能保留其资源。
- 导出使用实时编辑器状态：将选中的节点，或在未选中任何节点时将所有顶层节点，以 2× PNG 文件或 PDF 形式写入 exports/<document-name>/ 下。
结果菜单可直接打开该文件夹。
- 导入和生成的图片会持久化到相邻的 images/ 目录。SVG 由官方编辑器转换为节点。
- 工作区中的 .lib.pen 文件和官方 CLI 附带的只读库会出现在编辑器库列表中。
- 外部冲突和保存失败会一直显示在工具栏中，绝不静默覆盖有未保存改动的文档。
- 关闭时会先刷写脏画布，再释放对应会话。
- 固定版本的编辑器只在首次打开画布时下载；下载、校验和、解压或兼容性失败都会在空 iframe 打开之前报错。
- 尚未送达编辑器的已取消请求会从队列中移除；已送达的请求需要先检查画布状态，再决定是否重试。

集成的 lib/session-file.js 持有会话当前的 .pen 路径、编码后的文件 URI、目录和切换修订号。画布、资源导入和无头回退都使用这套身份标识；关闭渲染器不会清除它。拖入的图片走官方编辑器的二进制导入请求 → 宿主写入当前 .pen 的 images/ → 返回相对 URL → 编辑器基于同一个文件 URI 解析它 → 宿主读取字节 → 官方图片填充渲染。来自上一文档修订号的迟到消息会被拒绝。pencil_mcp_insert_image 也会拒绝不匹配的 filePath，或资源准备期间发生的文档切换；要选择其他文件，请先调用 pencil_mcp_open。没有对官方编辑器源码或 bundle 打任何补丁。

本集成采用 MIT 协议；官方 pen.dev 与 DeepSeek 组件不适用该协议。见 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.7.0 仅支持 Harness 0.2.0-rc.2。已有的 0.6.0 visionMode 配置继续有效。
从 0.5.x 或更早的插件版本升级时，请在插件页重新设置 visionMode。

在已有 DeepSeek Harness 0.2.0-rc.2 Web profile 中安装 npm Bundle：

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-with-pencil@0.7.0

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

npx @deepseek-ai/dsh@0.2.0-rc.2 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/dsh@0.2.0-rc.2 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。