前言¶

在 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