前言¶
如果你的团队用 Penpot 做设计，又希望智能体（DSH agent）能帮忙翻看设计稿、导出文件、把改好的文件传回去，就会遇到一个具体问题：Penpot 本身只提供一个本地 HTTP RPC 接口，智能体没有内置的调用方式，要么自己写脚本拼 HTTP 请求，要么在系统外绕一圈。dsh-penpot-plugin 解决的就是这件事——它是 DeepSeek Harness（DSH）的一个插件，由 vladtsvirko 维护，在 DSH 进程内封装了 Penpot 的本地 HTTP RPC API，智能体可以用一组 penpot_* 工具直接列团队、查项目、搜文件、导出和导入 .penpot 文件。下面介绍它的能力、安装方式和实际用法。
这是什么¶
一句话定位：Penpot for DeepSeek Harness——read, export and import design files from a DSH agent over Penpot’s local HTTP RPC API。
它不依赖任何 MCP 后端。插件直接通过 POST /api/rpc/command/* 与一个本地（或局域网内）Penpot 实例通信，鉴权用 access token。所以前置条件只有两样：一个可访问的 Penpot 实例，以及一个访问令牌。许可证是 MIT，源码仓库在 GitHub。
能做什么¶
插件目前是「读 + 导出」为主，并提供导入。0.2 起不再提供只读的另一条传输路径，因为那条路不能导出，已移除。
工具清单如下：
| 工具 | 作用 |
|---|---|
penpot_status |
API 是否已配置，以及配置的 endpoint |
penpot_teams |
当前账号可见的团队 |
penpot_projects |
项目列表，可选按团队过滤 |
penpot_files |
某项目下的文件 |
penpot_search |
按名称或关键词搜索文件 |
penpot_file |
单个文件：id、名称、页面 |
penpot_export |
把文件写出为 .penpot 到磁盘 |
penpot_import |
上传 .penpot 作为新文件或替换已有文件 |
导出结果是一份 Penpot JSON 的 zip。解压后可以用常规文件工具读取甚至编辑，改完再用 penpot_import 传回去——不需要额外的 CLI，也不需要第二条工具链。新建文件需要 projectId，替换已有文件需要 fileId。
安装与启用¶
方式一：DSH setup 内安装（推荐）¶
setup 的可选 design 组件会同时装好 Penpot、penpot CLI 和这个插件，插件引用在 components.json 里锁定：
./install.sh --design penpot # 或后续启用：/system components -> Enable
这条路径是自包含的：会把 PENPOT_API_URL 和 PENPOT_ACCESS_TOKEN 写入运行时环境，装好锁定的插件，并挂载一个由托管的 dsh-penpot row。走这条路就不需要下面的内容了。
方式二：独立安装（任意 DSH runtime）¶
插件是一个普通的 DSH bundle，在任意 profile 里都能用，有没有 setup 都行。它发布在 npm 上的是精确版本：
dsh plugin --profile web add dsh-penpot-plugin@0.3.0
npm 上的 registry tarball 里已经包含构建好的 lib/，所以没有 prepare 构建、也不需要 allowBuilds 条目。加完之后重启 runtime。
如果你要从源码仓库安装，则需要先放开构建并锁住 tag：
allowBuilds:
dsh-penpot-plugin@https://github.com/vladtsvirko/dsh-penpot-plugin.git: true
dsh plugin --profile web add github:vladtsvirko/dsh-penpot-plugin#v0.3.0
配置凭据¶
dsh-penpot row 读取的是 runtime 进程本身的环境变量——你之后在 shell 里 export 的东西不会进到一个正在运行的 runtime：
export PENPOT_API_URL='http://192.168.2.50:8090' # 不需要 /api/rpc 后缀
export PENPOT_ACCESS_TOKEN='...' # 在 Penpot: Settings -> Access tokens 生成
在 DSH setup 里，意味着把这两项加进 .env 并重启 dsh.service；design 组件会自动做好这件事。配完后让智能体跑一次 penpot_status 验证：它会报出 endpoint，缺哪个变量也会按名字说明。
对应的配置形如：
- id: dsh-penpot
config:
apiUrl: http://192.168.2.50:8090
token: !!js process.env.PENPOT_ACCESS_TOKEN ?? ''
如果 apiUrl 或 token 为空，插件仍然可以加载，penpot_status 会返回 none，而其它工具会说明需要设置什么。
典型用法¶
启动后直接让智能体调用这些工具即可，例如：先看服务状态，再列团队、列项目、看某个项目下的文件：
penpot_status确认 endpoint 已配置；penpot_teams拿到团队列表；penpot_projects按团队列出项目；penpot_files（带项目上下文）查看该项目下的文件；penpot_file查看单个文件的 id、名称与页面。
导出与往返编辑的流程：
penpot_export把.penpot文件写到磁盘；- 解压得到 Penpot JSON，用常规文件工具读取或修改；
penpot_import把文件传回——新建传projectId，替换原文件传fileId。
底层接口¶
只有一个后端：Penpot 的 HTTP RPC。请求形如 POST /api/rpc/command/<name>，带 Authorization: Token …，payload 是 kebab-case 命名（get-teams、get-all-projects、get-files、search-files、get-file-summary、export-binfile、import-binfile）。插件负责把这些细节都封装掉，工具层只暴露上面的命令。
更新¶
插件版本独立于 DSH 和 setup 发行版。
- 在 setup 里：在 bot 中执行
/system update penpot（或/system update plugin dsh-penpot-plugin），它会解析最新版本、开启回滚试用，并通过主机的插件管理器替换 bundle。 - 独立安装时：先
dsh plugin --profile <name> remove dsh-penpot-plugin，再add新 tag。插件管理器无法覆盖已装好的 git 包，所以必须两步；当它提示restart-required时重启 runtime。
dsh-penpot row 的配置在更新中会被保留，只有包本身变动。兼容性信息见仓库的 COMPATIBILITY.md：每个发行版会写明所测的 DSH 范围和 Penpot 版本。
适用场景与注意¶
适合这类人：已经用本地或局域网 Penpot 做设计、想把「看设计稿 / 取文件 / 回传文件」交给 DSH 智能体的开发者或团队。它面向的是「通过 HTTP RPC 访问既有 Penpot 实例」的场景，不提供本地设计编辑器能力。
几点需要注意：
- 插件运行在当前 DSH runtime 进程内，使用该进程的网络与环境权限。安装前建议自行检查源码与许可证（MIT）。
- 凭据从 runtime 进程环境读取，改
.env后必须重启dsh.service才生效。 - 当前版本是「读 + 导出 + 导入」。若要做程序化改写设计稿内容，还需要 Penpot 的
update-filechange format，相关设计讨论在仓库的docs/DESIGN.md。 - 站点为第三方社区目录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-penpot-plugin 的价值在于把 Penpot 的本地 RPC 变成一组智能体可直接调用的工具，导出、编辑、导入形成一个不依赖额外 CLI 的闭环。目录页在 https://www.skillhub.cn/plugins/vladtsvirko/dsh-penpot-plugin ，源码与文档在 https://github.com/vladtsvirko/dsh-penpot-plugin 。
