前言¶

在 DSH（DeepSeek Harness）裏做聯調或接口文檔維護時，Postman 往往仍是團隊存放 Collection 的主戰場。人工在 Postman 網頁端逐條增刪改，再和對話裏的 AI 來回覈對，成本高且容易漏改。常見做法是複製 JSON、手寫 curl，或讓 AI 只「建議」變更而不真正寫入雲端。

dsh-postman 是社區維護的 DSH 插件，通過 Postman 官方 API 把查詢、增刪改、導入導出接到模型可見工具上。插件不綁定任何語言或框架，只負責與 Postman 通信；從源碼整理接口清單再批量寫入，由模型和使用者完成。

這是什麼¶

• 名稱：dsh-postman（npm 包名同爲 dsh-postman）
• 維護者：LiuJiaCheng11
• 分類：聯網工具（SkillHub 目錄）
• 定位：DeepSeek Harness 插件，允許 AI 直接操作 Postman（網頁版）的 Collections
• 倉庫：https://github.com/LiuJiaCheng11/dsh-postman
• 許可：MIT（見倉庫 package.json）
• 版本：資料中 package.json 爲 0.5.0；安裝 GitHub 源時默認跟蹤 main 最新提交

注意倉庫歸屬：GitHub 上另有 zhousun55-byte/dsh-postman（文件上傳類插件），包名相同，裝錯會互相覆蓋。安裝請認準 LiuJiaCheng11/dsh-postman。

核心功能¶

插件向模型暴露 9 個工具，並註冊 /postman-skill 技能（用法類似 /browser-skill，可在輸入框 / 列表中選擇，將工具表與典型流程注入當前會話）。

設計要點（來自 README）：

• 只管 Postman，不管源碼：插件內無語言、框架或路由約定；批量加接口時由 AI 讀項目代碼整理清單，再交給 postman_add_many 一次寫入。
• 配置：推薦在 dsh 「設置 → Postman」 填寫 API Key；字段標了 role('secret')，明文不回傳瀏覽器。依賴僅 @deepseek-ai/schemastery，其餘使用 Node 內置模塊。
• 修改接口：應優先用 postman_edit 就地 patch；不要用「先 postman_rm 再 postman_add」，否則會靜默丟失 Pre-request / Tests 腳本、示例響應等字段。

運行環境（package.json）：Node >=22.5，dsh >=0.1.1-rc.1。

安裝與啓用¶

插件目錄本身是 dsh bundle，用 dsh 自帶命令從 GitHub 安裝：

dsh plugin --profile web add github:LiuJiaCheng11/dsh-postman

固定到某一提交：

dsh plugin --profile web add github:LiuJiaCheng11/dsh-postman#<commit-sha>

安裝後 dsh 會把 dsh-postman 寫入 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles。需要重啓 dsh（重新執行 dsh web）後插件才生效；刷新瀏覽器或新開標籤不足以熱重載插件代碼。

驗證是否裝配：

dsh --profile web --dump-config | grep -i postman

配置 Postman API Key¶

1. 在 Postman 賬號設置 → API Keys 生成 Key（PMAK- 開頭）。
2. 在 dsh 「設置 → Postman」 填入（推薦）。保存後若當前會話仍讀到舊 Key，可新開會話或重啓 dsh；也可用 postman_config 查看 status 與 Key 來源。
3. 0.2.x 提供上述設置分區；0.1.x 無 Web 客戶端該頁時，可用備用頁 http://127.0.0.1:<port>/dsh-postman，或直接編輯 profile 的 cordis.patch.yml。

Key 讀取回退順序（README 說明）：

1. 設置表單中的 apiKey（寫入 ~/.dsh/profiles/<profile>/cordis.patch.yml）
2. ~/.dsh/dsh-postman/config.json（備用頁寫入，權限 0600）
3. ~/.postman_api_key（歷史文件）
4. 環境變量 POSTMAN_API_KEY

備用頁每次取 Key 都會重讀文件，改完可立即生效，適合排查設置頁與會話緩存問題。

典型用法¶

安裝、配置 Key 並重啓 dsh 後，可直接用自然語言驅動工具；也可先輸入 /postman-skill 注入完整說明。

README 中的對話示例：

• 列出我的 Postman 集合
• 在 App 的「測試」目錄下加一個 GET 接口 http://localhost:8080/api/v1/models
• 把 App 集合裏「健康檢查」的地址改成 /healthz
• 把 Converter 集合導出到 D:/tmp/converter.json
• 掃一下 D:/src/MyApi，看哪些接口還沒進 Postman
• 把 D:/src/MyApi 裏沒同步的接口寫進 App 集合

大集合查看時，對 postman_tree 使用 path 縮小範圍，或調大 limit；截斷時輸出會帶明確提示與頂層目錄名。

批量新增前可用 postman_add_many 的 dryRun: true 預演將新增或跳過的項。

適用場景與注意¶

適合：已在用 DSH Web profile、Collection 託管在 Postman 雲端、希望對話內完成集合瀏覽與 CRUD、或從本地代碼/清單一次性同步多條接口的團隊或個人。

使用前請知悉：

• 插件以 當前 dsh 進程權限 運行，並持有你配置的 Postman API Key，可對雲端 Collection 做破壞性操作（刪除、整體 push 覆蓋等）。安裝前請閱讀倉庫源碼與 MIT 許可證，自行評估信任邊界。
• 聯網工具會訪問 Postman API；網絡與 Key 權限範圍由你的 Postman 賬號決定。
• 社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本文事實以 GitHub README 與倉庫文件爲準。

結尾¶

dsh-postman 把 Postman 雲端 Collections 的讀寫收成一組模型工具，並輔以 /postman-skill 與 Web 設置頁，減少在 Postman 網頁與 AI 對話之間手工搬運 JSON 的步驟。若你的聯調流程以 Postman 爲中心，可在 DSH 中按上文命令安裝、配置 Key 並重啓後試用。

• 目錄頁：https://www.skillhub.cn/plugins/LiuJiaCheng11/dsh-postman
• GitHub：https://github.com/LiuJiaCheng11/dsh-postman