前言¶

在 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/」的麦麦插件开发闭环。

插件不联网、不读凭据、不执行被校验插件的代码；校验阶段如需 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 仓库。