IWAIBAOLI/dsh-with-pencil

dsh-with-pencil

Awesome DSH Plugin

English · 简体中文

English

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

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

它提供什么

- 一个按需启动的 Pencil 画布，Harness 启动时不会打开。
- 与对话绑定的工作区：切换对话时画布隐藏，
切回时恢复其原始编辑器会话。
- 通过可见的编辑器 IPC 进行实时 Agent 编辑，具有即时渲染和
已确认的原子磁盘保存。
- 当浏览器画布关闭时，使用串行化的官方无头回退方案。
- 为下一轮 Agent 注入选择上下文，以及来自 Pencil 截图的真实图像
附件。
- 工作区安全的文件打开、创建、另存为、实时 PNG/PDF 导出、导入、
生成图像、设计库、外部更改重新加载和冲突
解决。
- 响应式 42% 分屏视图，支持指针安全的调整大小和可选的
浮动布局。

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

- 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 预设

在普通 Harness 对话中发送一次此提示：

创建并验证一个名为 Pencil Designer 的 Harness Agent Preset；不要
仅仅解释步骤。以标准编码预设为基础，并保留
固定的官方工具。

将以下 Pencil 设计工具分配给该预设，且不分配其他设计工具：
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 和 pencil_mcp_insert_image。同时绑定一个
可用的视觉工具，并将其
确切名称写入 persona；如果没有可用的，询问用户。

persona 必须告诉 Agent 仅使用分配给此预设的设计和视觉工具
直接完成 .pen 设计任务。在调用
工具之前，阅读 Agent 可用工具列表中该工具自身的描述和参数定义；
这些描述就是完整的使用参考——
不要在其他任何地方搜索、探测或验证用法。

persona 必须要求 Agent 在开始新设计时，首先使用
pencil_mcp_open 在工作区内创建一个 .pen 文件，然后编辑、截取
截图，并在保存前进行视觉验证。使用
pencil_mcp_get_screenshot 进行视觉验证（视觉保真度抽查：颜色、字体
渲染、对齐/间距、布局位置；大型节点会自动以高分辨率渲染）。使用
pencil_mcp_batch_get（节点读取）验证文本和属性内容。仅在生成交付文件时
使用 pencil_mcp_export_nodes。不要使用未指定的设计工具，也不要检查任何
源代码或仓库来寻找工具或研究其用法。编辑 .pen 时优先使用指定的设计
工具；不要将直接编辑 JSON 视为默认做法。

完成后，报告预设名称/路径、绑定的视觉工具，以及如何
选择该预设。不要修改任何其他预设。

五个旧版一次性 CLI 辅助工具默认隐藏，以避免功能重复
和无关的模型上下文。仅当兼容性需要 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_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（设置 → 插件 → dsh-with-pencil，默认 text）：

- text — 适用于 DeepSeek 和其他非多模态模型。截图会路由到
高分辨率渲染，以确保图像转录保持可靠。图像
转录本身并非由本插件提供：它依赖于部署中具备图像能力的包装器（例如 dsh-vision-proxy，或来自 dsh-vision-router 的包装器 / 隐蔽路由）。纯文本的 Harness 直连路由会在本插件运行之前就拒绝聊天图像输入，并且无法消费图像工具结果。
- multimodal —— 原生截图；模型自己看到像素。

设置卡片位于 Settings → Plugins → dsh-with-pencil，保存后立即生效。首次安装默认为 text。

有关实现细节，请参阅 docs/ARCHITECTURE.md。

安装

在拥有可用的 DeepSeek Harness Web 配置文件的情况下，安装 npm 包：

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

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

npx @deepseek-ai/dsh web

这就是完整的常规安装流程。该 npm 包会安装固定版本的官方 @pen.dev/cli。首次打开画布时，插件会直接从官方 pen.dev 发布源下载编辑器 0.1.94，校验其固定的 SHA-256 校验和，并以原子方式缓存到
~/.dsh/dsh-with-pencil/editor/0.1.94/。Harness 启动时不会下载或打开任何内容，后续打开画布时使用已验证的缓存。

浏览器编辑器不会被复制进本 npm 包，也不会通过本 npm 包再分发。如需离线使用，请提前下载并解压同一官方包，并将 DSH_PEN_EDITOR_DIR 指向其 out 目录。

从本检出目录进行本地开发：

npm run dev:install -- --profile web
npx @deepseek-ai/dsh 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，并读取旧位置以保持兼容 |

画布行为

- 首次打开时使用 42% 的右侧分屏。调整大小会以视口比例持久化；
画布也可以浮动。
- 画布外框和 Pencil 编辑器会自动跟随当前活动的 Harness/系统浅色或
深色主题；该插件不添加单独的主题控制。
- 工具栏包含工作区、.pen 文件、导出、布局和关闭
控件。这些插件自有的控件遵循当前活动的 Harness 语言；
官方 Pencil 编辑器保留其上游的英文界面。
- iframe 容器保持挂载在其对话中。切换 .pen
文件会保存前一个文档，并使用新的
文件 URI 重新加载官方编辑器；其内部资源基址在初始化时固定。这会重置
新打开文档的临时选择/撤销状态。
- 手动编辑每六秒自动保存一次；Agent 编辑在每次
成功操作后等待保存。
- 另存为会在工作区内写入一个新的 .pen，绝不覆盖现有
目标，将画布切换到副本，并保持源文件不变。官方
序列化器会为目的地重定资源 URL 的基址；资源仍保留
在原有位置。跨目录移动需要先在画布中打开源文件，
以便同一个序列化器能够保留其资源。
- 导出使用实时编辑器状态：它会将选中的节点，或在未选中任何内容时
将所有顶层节点，作为 2× PNG 文件或 PDF 写入
exports// 下。结果菜单可以直接打开该文件夹。
- 导入和生成的图像会持久化到相邻的 images/
目录。SVG 由官方编辑器转换为节点。
- 工作区中的 .lib.pen 文件和官方
CLI 附带的只读库会出现在编辑器库列表中。
- 外部冲突和保存失败会持续显示在工具栏中，并且绝不会
静默覆盖已修改的文档。
- 关闭时会先刷新已修改的画布，再释放其会话。
- 固定版本的编辑器仅在首次打开画布时下载；下载、
校验和、解压或兼容性失败会在打开空白
iframe 之前显示。
- 尚未到达编辑器的已取消请求会从其
队列中移除；已送达的请求在重试前需要检查画布状态。

该集成的 lib/session-file.js 负责管理对话当前的 .pen
路径、编码后的文件 URI、目录和切换修订版本。画布、资源
导入和无头回退都使用该身份；关闭渲染器
不会清除它。拖入的图像会经过官方编辑器的二进制
导入请求 → 宿主写入当前 .pen 的 images/ → 相对 URL
returned → 编辑器会基于同一个文件 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 导出、资源导入、
生成图片、设计库、外部修改重载和冲突处理。
- 默认 42% 的响应式右侧分屏，拖动过程中保持指针控制，也可切成浮动窗口。

插件默认注册 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_get_guidelines、
pencil_mcp_execute、pencil_mcp_get_screenshot、
pencil_mcp_export_html、pencil_mcp_export_nodes、
pencil_mcp_insert_image，不再指定其他设计工具。
同时绑定一个可用的视觉工具，并把准确工具名写入 Persona；没有视觉工具则询问用户。

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_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，默认 text）：

- text — 适用于 DeepSeek 等非多模态模型。截图自动走高清渲染，保证图片转译的可靠性。
本插件不提供图片转译模块：转译依赖声明图片能力的包装路由（如
dsh-vision-proxy 或 dsh-vision-router 的 wrapper/stealth 路由）。Harness 的直连
纯文本路由会在本插件运行前拒绝聊天图片，也无法消费工具返回的图片结果。
- multimodal — 使用原生截图，模型自己看像素。

配置卡片位于 设置 → 插件 → dsh-with-pencil，保存后立即生效；首次安装默认
text。

实现细节见 docs/ARCHITECTURE.md。

安装

在已有可用 DeepSeek Harness Web profile 的前提下，安装 npm Bundle：

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

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

npx @deepseek-ai/dsh 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 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，并兼容读取旧路径 |

画布行为

- 首次打开为 42% 右侧分屏；拖动后按视口比例保存，也可切成浮动窗口。
- 画布外框和 Pencil editor 自动跟随 Harness/系统的明暗主题；插件不增加单独的主题开关。
- 顶栏提供工作区、.pen 文件、导出、布局和关闭操作。这些插件自有控件跟随当前 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。