前言¶

在 DSH 裏讓模型操作 Penpot，常見做法是掛上 Penpot 官方 MCP 服務器。MCP 裏的 execute_code 必須在已打開的設計稿標籤頁裏跑插件代碼，因此自動化、批量改稿、無人值守場景都會卡在這一條硬約束上。

dsh-plugin-penpot（維護者 sdf123098）在 DSH 側同時接好控制面（三種 Penpot MCP 連接目標）和設計面（基於 Penpot REST 的讀寫）。REST 通道只要 Authorization: Token <值>，不需要瀏覽器標籤頁，就能建文件、改圖層、增刪頁面等常規操作。兩條通道狀態在插件面板裏分開顯示，互不替代。

這是什麼¶

插件屬於 DSH 社區目錄中的聯網工具類擴展，當前倉庫版本爲 0.6.0（MIT）。它把 Penpot 暴露爲 DSH 模型側工具：一條 MCP 通道保留官方能力（含在設計稿裏執行任意 Plugin API）；一條 REST 通道覆蓋文檔中列出的文件/圖層級寫操作，適合腳本與智能體流水線。

插件加載後默認不做拉進程、開瀏覽器、發業務請求；後臺會用 REST 的 get-teams 做一次只讀自檢，然後等待你的下一步操作。

安裝與啓用¶

運行環境需要 Node 22+（驅動瀏覽器路徑依賴全局 WebSocket；若只用 REST 通道，README 說明 Node 20 也可）。

下面三條安裝方式均來自項目 README，任選其一：

# npm 全局
npm install -g dsh-plugin-penpot

# 由 DSH 安裝
dsh plugin install dsh-plugin-penpot

# 從 GitHub 安裝
dsh plugin install github:sdf123098/dsh-plugin-penpot

裝好後在 設置 → 插件 中啓用；配置卡片在插件頁內完成。用戶覆蓋配置寫入 ~/.dsh/data/dsh-plugin-penpot/config.json。

連接目標與憑據¶

Penpot 鑑權與常見 OAuth 服務不同，使用插件前建議先弄清三點（均見 README）：

1. 沒有 OAuth。MCP 官方託管地址形如 https://design.penpot.app/mcp/stream?userToken=<key>，key 在 Penpot「賬戶 → Integrations → MCP Server」生成；MCP 通道會忽略 Authorization 頭。
2. MCP 服務端不單獨校驗 key 對錯：initialize、tools/list 在無會話時也可能返回 200；是否真能跑 execute_code 取決於是否已有對應標籤頁會話。
3. REST 能離線驗憑據：使用 Authorization: Token <值>；Bearer 會 401。Integrations 裏的 MCP key 本身可作爲有效 PAT，同一字符串可兼用（面板項 pat.reuseMcpKey 默認 true）。

連接檔位有四檔，默認自動識別：首次加載會掃描本機已有 penpot MCP 配置（DSH profile、Codex、Claude Code、Claude Desktop、Cursor、Gemini、項目級 .mcp.json 等），找不到則回落本地檔。另有官方託管、本地自構建（packages/server/dist/index.js 或 npx @penpot/mcp）、自部署三種明確模式。

啓動方式默認 lazy（首次調用才啓動，之後常駐）；也可選 auto（加載即建連）。本地檔進程 detached，停止時會覈對 pid 命令行後再結束，避免誤殺佔用端口的其他進程。

面板與模型側工具¶

插件頁分爲概覽、連接、自動化、遷移、高級五個標籤；僅連接、自動化、高級有可編輯表單項。概覽頁用兩格分別表示 MCP 與 REST 通道狀態（綠/黃/紅），不是一個總開關——標籤頁未開時 MCP 可能變黃，REST 仍可能爲綠並繼續工作。

向模型暴露 9 個工具，出問題可先調 penpot_status：

默認 requireApproval: true 時，penpot_execute_code、penpot_import_image、penpot_write 會走審批閘門；penpot_read 僅允許白名單讀操作。

「遷移」標籤可掃描並導入其他 MCP 客戶端中的 penpot 配置，寫入前自動備份；遷移邏輯約定不把 key 寫成 Bearer、不按 OAuth 篩選、不改動 *.bak 文件。

典型用法：無瀏覽器的 REST 自動化¶

下面示例摘自 README，表示模型側調用 penpot_write 時的常見 op（參數名與結構以工具/schema 爲準）：

# 建文件
penpot_write  op=createFile  projectId=<項目id>  name=我的稿子

# 加畫板與文本圖層
penpot_write  op=addShapes  fileId=<文件id>
  shapes=[{"type":"frame","name":"Board","width":1440,"height":900,"fill":"#ffffff"}]

penpot_write  op=addShapes  fileId=<文件id>
  shapes=[{"type":"text","name":"標題","x":40,"y":40,"width":400,"height":40,
           "text":"你好","fontSize":32,"fontWeight":"700","parentId":"<boardId>"}]

# 改屬性、刪圖層、頁面與文件管理
penpot_write  op=modifyShape   fileId=…  pageId=…  shapeId=…  set={"x":500,"name":"新名字"}
penpot_write  op=deleteShapes  fileId=…  pageId=…  shapeIds=a,b
penpot_write  op=addPage       fileId=…  name=第二頁
penpot_write  op=renameFile    fileId=…  name=新名字

寫路徑有兩類容易踩坑的約束（README 已說明）：create-file / update-file 需要合法的 features 數組，否則 400 feature-not-supported；add-obj 字段需符合 malli schema，且 fills 多給 fill-image 或 fill-color-gradient（含 null）也會 400。插件內置了保守 features 集合與 makeShape 處理邏輯。

只讀可走 penpot_read，不經過寫審批白名單之外的命令無法改稿。

需要瀏覽器時的兜底¶

必須走 MCP、又沒人手開網頁時，可在配置裏啓用瀏覽器自動化（默認 browser.autoLaunch: false），通過 penpot_control 操作：

penpot_control  op=openDesign     fileId=<設計稿id>
penpot_control  op=browserStatus
penpot_control  op=closeBrowser

插件使用獨立 Chromium profile（~/.dsh/data/dsh-plugin-penpot/browser/profile），不佔用系統默認瀏覽器配置。Zen / Firefox 無 CDP，無法被插件腳本驅動；在 Zen 裏手動從 URL 加載 Penpot 插件仍可使用 MCP 交互，但無人值守驅動需 Chromium 系。

配置摘要¶

面板保存的 YAML 結構在 README 中給出，核心字段包括：

mode: auto              # auto | official | local | selfhost
startup: lazy           # lazy | auto
requireApproval: true
toolCallTimeoutMs: 180000
connectTimeoutMs: 60000
idleStopMinutes: 0

pat:
  token: ''
  reuseMcpKey: true

browser:
  autoLaunch: false

憑據在 API/面板中只回報是否已配置，不回顯明文；令牌輸入框留空表示不修改。數據目錄爲 ~/.dsh/data/dsh-plugin-penpot/（含 config.json、detected.json、local-run.json、logs/ 等）。

適用場景與注意¶

適合：希望在 DSH 對話或自動化流程中讀寫 Penpot 文件、批量建稿改稿的團隊；已在使用 Penpot MCP、需要從 Cursor/Claude Desktop 等遷移配置的用戶；需要「雲端 REST 寫 + 本地 MCP 跑代碼」組合的場景（本地檔無 REST 時，REST 會按配置回落遠端端點）。

務必知曉：

• 插件隨當前 DSH 進程權限運行，安裝前應自行審閱 源碼與 MIT 許可證，勿將生產 PAT 交給不可信環境。
• 官方託管上 get-profile 可能被 Cloudflare 攔截，自檢改用 get-teams；rename-file / delete-file 的 204 無正文屬正常。
• REST 讀回 camelCase、寫入 kebab-case，同一語義兩種鍵名工具側會識別。
• DSH 生態理念是「一切皆插件」；SkillHub 目錄頁爲社區站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-plugin-penpot 用雙通道把 Penpot 接進 DSH：MCP 保留標籤頁內的完整 Plugin API；REST 在無瀏覽器條件下完成多數文件與圖層讀寫。若你的痛點是自動化改稿而不是點選改色，優先摸清 REST 憑據與 penpot_write 白名單即可上手。

• 目錄頁：https://www.skillhub.cn/plugins/sdf123098/dsh-plugin-penpot
• 倉庫：https://github.com/sdf123098/dsh-plugin-penpot