toybox 贡献指南

August 14, 2026 · View on GitHub

本指南面向 toybox 协作者；纯用户安装请看 INSTALL.md。

环境

git clone https://github.com/omdsh-dev/toybox.git && cd toybox
pnpm install        # TypeScript + 官方 MCP 2.0 SDK/client + esbuild + vitest

前置：Node ≥ 22（MCP 服务器目标运行时）、pnpm。

新增一个 MCP 插件（推荐模板：抄一个现有的）

plugins/<id>/
├── src/<id>.mts              # TypeScript 源码（使用固定版本的官方 MCP Server SDK）
├── tsconfig.json             # { "extends": "../../tsconfig.base.json", "compilerOptions": { "outDir": ".dsh-plugin/server" }, "include": ["src/**/*.mts"] }
├── README.md                 # 简介/工具表/示例/诚实边界
├── tests/<id>.spec.ts        # vitest + 官方 MCP 2.0 Client
└── .dsh-plugin/
    ├── package.json          # dshWorkshop + mcpName；不允许 lifecycle script
    ├── server.json           # MCP Registry 2025-12-11 schema
    └── server/<id>.mjs       # ← 构建产物，pnpm build 生成，勿手改

MCP 协议固定为 2026-07-28。使用官方 SDK 注册工具，构建链会把 SDK 打入单文件；不要手写 JSON-RPC 协议。

新增一个 skill 插件

plugins/<id>/
├── README.md
└── .dsh-plugin/
    ├── package.json          # dshWorkshop direct Skill；不允许 lifecycle script
    └── skills/<id>/SKILL.md  # frontmatter 必须有 name(小写连字符) + description

SKILL.md frontmatter 必须包含小写连字符形式的 name 和清晰的 description。

本地验证（必须全绿再提交）

pnpm build:one <id>   # 编译 TS
pnpm test -- plugins/<id>   # 协议测试
pnpm verify           # 全量：精确包面 + MCP 2.0 隔离/失败/重启 + Skill 静态检查

所有叶子都必须声明 package.json#dshWorkshop。MCP 还必须提供当前官方 server.json，Skill 只做非执行式静态检查。源仓通过不等于 Workshop 准入。

提交与发布

  1. 改源码 → pnpm build → pnpm verify → pnpm test
  2. commit（插件代码与构建产物一起提交，.dsh-plugin/ 是交付物）
  3. TOYBOX_GITHUB_REPOSITORY=omdsh-dev/toybox pnpm release:prepare：把全部插件 pin 到新 HEAD，生成安装配置、ref 表和 catalog.json
  4. 提交 publish 产物（README.md + catalog.json）
  5. 用公开固定 commit 向 Workshop 提交；隔离重跑与人工审核通过后才可单独 admission

本仓库和所有插件包都保持 private: true。发布流程只生成 Git source 配置，不执行或承诺公共 npm 发布。

玩具箱纪律

  • 好玩是第一生产力，但验收标准不能少：每个插件必须能过仓库自有 packager，README 写清“什么时候用”
  • 不重复造轮子：toybox 只收有趣且边界清楚的插件，统一经 Workshop 收录
  • 诚实标注：判断类技能要带证据；数据来源、算法简化、娱乐性质如实声明
  • 格式边界：MCP 只使用官方 SDK/Registry 契约；Skill 不伪装成可执行插件
  • 自包含：MCP 产物必须固定打包依赖，运行时不读取仓库 node_modules