前言¶

在 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