前言¶

如果你的團隊用 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 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，而其它工具會說明需要設置什麼。

典型用法¶

啓動後直接讓智能體調用這些工具即可，例如：先看服務狀態，再列團隊、列項目、看某個項目下的文件：

1. penpot_status 確認 endpoint 已配置；
2. penpot_teams 拿到團隊列表；
3. penpot_projects 按團隊列出項目；
4. penpot_files（帶項目上下文）查看該項目下的文件；
5. penpot_file 查看單個文件的 id、名稱與頁面。

導出與往返編輯的流程：

1. penpot_export 把 .penpot 文件寫到磁盤；
2. 解壓得到 Penpot JSON，用常規文件工具讀取或修改；
3. 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-file change 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 。