前言¶
在 DeepSeek Harness（DSH）裏給麥麥（MaiBot）寫插件，難點往往不在「能不能寫出 Python」，而在契約是否對齊當前宿主：_manifest.json 字段嚴格、能力白名單與代碼調用要一致、SDK 方法名會隨版本變化。憑模型記憶寫，常見結果是 manifest 校驗失敗、運行時「未獲授權能力」，或 EventHandler 消息字段取錯。
dsh-maibot-plugin-writer 是社區維護的 DSH 工作流類插件（cordis bundle），向 agent 註冊 5 個 maibot_* 工具，並隨包投放 skill maibot-plugin-writer。能力白名單與 ctx.* 方法表從本機運行中的 MaiBot 源碼和已安裝的 maibot_sdk 讀取，而不是聯網拉文檔或靠記憶猜 API。維護者爲 Lgv-H；倉庫 GitHub，社區目錄頁 SkillHub。許可證 MIT，當前 package 版本 0.1.0。
這是什麼¶
一句話：讓 DSH 自己完成「查契約 → 生成三件套 → 靜態校驗到 0 error → 安裝到 plugins/」的麥麥插件開發閉環。
| 層 | 內容 |
|---|---|
| 工具 | maibot_plugin_catalog、maibot_sdk_reference、maibot_plugin_scaffold、maibot_plugin_validate、maibot_plugin_install |
| Skill | maibot-plugin-writer（加載時投放到 <dshHome>/skills，熱加載生效） |
| 事實源 | 能力白名單與 SDK 方法表實時取自本機 MaiBot |
插件不聯網、不讀憑據、不執行被校驗插件的代碼；校驗階段如需 AST 深檢，會用本地 Python 子進程解析文件（見倉庫 SECURITY.md）。
爲什麼需要它¶
README 中歸納的宿主約束與「憑記憶寫」的常見後果包括：
_manifest.json爲強類型模型：多字段、版本號格式、author.url非 http(s) 等會導致 manifest 校驗失敗。capabilities爲授權白名單：代碼用了未聲明的能力會報錯；聲明瞭宿主未註冊的名字則 manifest 非法。- SDK 接口隨版本變化，部分方法在當前 SDK 中可能不存在。
@EventHandler默認不攔截消息；ON_MESSAGE 應使用message["session_id"]、message["processed_plain_text"]等字段，而非錯誤的鍵名。- 僅
[plugin].enabled = true的插件會被激活；缺[plugin]段時行爲與預期可能相反。
maibot_plugin_validate 對上述規則做靜態檢查；在能找到 Python 時還會做 AST 層面的語法、導入與結構檢查。
核心功能¶
maibot_plugin_catalog¶
列出 plugins/ 下已有插件（ID、名稱、版本、目錄、啓停、組件、能力聲明、行數）以及宿主當前註冊的能力名，用於查 ID 衝突和參考現有寫法。
maibot_sdk_reference¶
按主題返回當前宿主的開發契約，可選：overview、capabilities、methods、components、messages、config、pitfalls、all。
maibot_plugin_scaffold¶
生成可通過宿主校驗的三件套：_manifest.json、plugin.py、config.toml；默認 enabled = false。可指定目錄，在正式安裝前於插件目錄外寫草稿。
maibot_plugin_validate¶
對插件目錄做靜態校驗，返回 error / warning / info，涵蓋 manifest、config.toml、plugin.py、能力聲明與代碼調用交叉覈對、組件裝飾器契約、重複插件 ID 等。
maibot_plugin_install¶
先校驗，存在 error 則拒絕安裝；通過後複製到 <maibotRoot>/plugins/<dirName>，並按參數設置 [plugin].enabled（默認保持禁用）。
Skill：maibot-plugin-writer¶
定義完整工作流（查契約 → 看現狀 → 生成骨架 → 寫實現 → 校驗到乾淨 → 交付）與硬性契約清單。DSH 在處理「給麥麥寫插件 / 改插件 / 排查加載失敗」類請求時會加載該 skill。
安裝與啓用¶
本插件僅通過 GitHub 分發（npm 上無此包）。官方 README 給出三種方式，任選其一：
# 1) 檢出並鏈接進 profile
git clone https://github.com/Lgv-H/dsh-maibot-plugin-writer.git
dsh plugin --profile web add link:/path/to/dsh-maibot-plugin-writer
# 2) 無網絡/無 registry 環境（等價於 1) 的鏈接安裝，不依賴 pnpm 聯網）
cd dsh-maibot-plugin-writer
node scripts/deploy-local.mjs --profile web
# 3) 經插件市場安裝：倉庫公開並帶上 dsh-plugin 主題後，市場的 GitHub 來源可檢索到（以市場實際收錄爲準）
安裝或更新後需要重啓一次該 profile 的服務。隨包 skill 由文件監視器熱加載，新會話無需重啓即可看到。
卸載：
dsh plugin --profile web remove dsh-maibot-plugin-writer
配置¶
在 profile 的 cordis.patch.yml 中可覆蓋（profile 層優先於插件 bundle）：
- id: dsh-maibot-plugin-writer
name: dsh-maibot-plugin-writer
config:
maibotRoot: 'C:\...\modules\MaiBot' # MaiBot 源碼根（含 src/plugin_runtime 與 plugins/）
pythonPath: '' # 可選：AST 深檢用解釋器
dshHome: '' # 可選：默認 $DSH_HOME 或 ~/.dsh
syncSkill: true # 是否把隨包 skill 投放到 <dshHome>/skills
maibotRoot 解析順序爲：工具參數 → 插件配置 → 環境變量 DSH_MAIBOT_ROOT / MAIBOT_ROOT → 從當前工作目錄向上探測 → 常見安裝路徑自動發現；顯式配置錯誤會直接報錯，不會靜默換目錄。
典型用法¶
裝好並重啓 profile 服務後，在 DSH 中用自然語言描述需求即可。README 示例：
給麥麥寫一個插件：每天早上 8 點在指定羣裏發一句早安，文案可以在配置裏改。
agent 按 skill 大致會執行：
maibot_plugin_catalog → 確認沒有 ID 衝突、看看有沒有可參考的插件
maibot_sdk_reference → 取 components / messages / config / capabilities 契約
maibot_plugin_scaffold → 生成 author.morning-greeting 三件套
（用文件工具補全 plugin.py 的業務邏輯與 config.toml 字段）
maibot_plugin_validate → 反覆校驗到 0 error
maibot_plugin_install → 複製進 plugins/，保持 enabled = false
最後由使用者根據說明決定是否將 [plugin].enabled 設爲 true 並驗證行爲。
適用場景與注意¶
適合誰： 已在本地部署 MaiBot 1.x（_manifest.json v2 + plugin_runtime）與 DSH web profile，希望由 agent 按本機真實契約生成、校驗並安裝插件的開發者。README 實測環境包括 DSH 0.1.7-rc.2 桌面客戶端 + web profile、@deepseek-ai/dsh-tools 0.1.2-rc.1、Node ≥ 20、MaiBot Plugin SDK 2.x（示例 2.8.2）；Windows 已實測，macOS / Linux 路徑探測有覆蓋但未在 README 中標註爲已實測。
侷限（倉庫原文）： 只做靜態校驗，不啓動 MaiBot、不保證業務邏輯正確；找不到 Python 時 AST 深檢會降級並在結果中說明；寫入 plugins/ 可能觸發宿主文件監視器重載插件運行時；不聯網，一切以本機宿主爲準。
安裝前建議： DSH 插件以當前 DSH 進程權限運行，會讀取 MaiBot 源碼與 plugins/、寫入 scaffold/install 目標及 skill 目錄。安裝前應自行閱讀 倉庫源碼 與 MIT 許可證，確認 maibotRoot 與路徑披露符合你的環境。社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
維護者在 README 開頭也指向 MaiBot 官方的 vibe-coding 文檔，若你更傾向官方文檔驅動的開發方式，可一併參考。
結尾¶
dsh-maibot-plugin-writer 把麥麥插件開發裏易錯的契約細節交給本機事實源和靜態校驗，把「寫對能加載、能力聲明一致」的部分自動化，交付仍由你決定是否啓用插件。進一步瞭解見 SkillHub 目錄頁 與 GitHub 倉庫。
