@birdie_moblie/plugin-marketplace-cli

这是用于维护 Claude Code / Codex plugin marketplace 仓库的 CLI。它负责创建插件骨架、验证 plugin.yaml、生成平台 manifest、更新 marketplace 索引，并打出本地发布包。OpenSpec source adapter metadata 通过插件内 overlay 生成 sidecar，作为兼容层存在，不改变 Claude Code / Codex 输出格式。

使用公网 CLI

npx @birdie_moblie/plugin-marketplace-cli --help

常用命令

npx @birdie_moblie/plugin-marketplace-cli init-repo [name] --organization "团队名" [--no-skill]
npx @birdie_moblie/plugin-marketplace-cli init <plugin-name> --type <skill|mcp|lsp|hook>
npx @birdie_moblie/plugin-marketplace-cli validate [plugin-name] --all
npx @birdie_moblie/plugin-marketplace-cli build [plugin-name] --all
npx @birdie_moblie/plugin-marketplace-cli index
npx @birdie_moblie/plugin-marketplace-cli release-local

从其他目录操作指定仓库时，使用 --root <dir>：

npx @birdie_moblie/plugin-marketplace-cli --root /path/to/repo validate --all

不传 --root 时，CLI 会从当前工作目录向上查找 marketplace.yaml。除 init-repo 外，找不到 marketplace.yaml 会直接报错并提示先初始化仓库。

如果已经本地或全局安装该 npm 包，也可以直接使用 plugin-marketplace bin 运行同一组命令。

插件仓库结构

.
├── marketplace.yaml
├── plugins/
│   └── my-plugin/
│       ├── plugin.yaml
│       └── skills/
├── .agents/skills/marketplace-maintainer/SKILL.md
├── .claude/skills/marketplace-maintainer/SKILL.md
├── .claude-plugin/marketplace.json
├── .agents/plugins/marketplace.json
└── marketplace.json

每个插件的 Claude Code / Codex 平台信息以 plugin.yaml 为唯一来源。插件也可以额外提供 openspec-source-adapters.yaml overlay，用于声明 OpenSpec source adapter metadata。

仓库本身要作为 marketplace 源使用时，以下生成物需要随源码一起提交：

• .claude-plugin/marketplace.json
• .agents/plugins/marketplace.json
• .openspec-plugin/source-adapters.json
• plugins/**/.claude-plugin/plugin.json
• plugins/**/.codex-plugin/plugin.json
• plugins/**/.openspec-plugin/plugin.json
• plugins/**/.mcp.json
• plugins/**/.lsp.json
• plugins/**/hooks/hooks.json
• marketplace.json
• plugins/CATALOG.md

LSP 插件在 plugin.yaml 的 components.lsp 声明 server metadata：

components:
  lsp:
    - name: dart
      command: dart
      args: ["language-server", "--protocol=lsp"]
      extensionToLanguage:
        ".dart": dart
      startupTimeout: 30000
      maxRestarts: 3
      diagnostics: true

CLI 会由 components.lsp 生成插件根目录 .lsp.json，并只在 Claude Code marketplace 写入 lspServers 字段。Codex 当前没有原生 LSP manifest；语义能力必须通过 MCP server 暴露。

OpenSpec sidecar 输出只来自 openspec-source-adapters.yaml overlay：

• plugins/<name>/.openspec-plugin/plugin.json
• .openspec-plugin/source-adapters.json

不要把 OpenSpec-only 字段加入 plugin.yaml、.claude-plugin/plugin.json、.codex-plugin/plugin.json、.claude-plugin/marketplace.json、.agents/plugins/marketplace.json 或根 marketplace.json。

推荐脚本

plugin-marketplace init-repo 会给新仓库写入一组 npm scripts，并默认注入 marketplace-maintainer SKILL 到 .agents/skills/ 和 .claude/skills/，方便维护者继续创建、验证和发布插件。如需只生成基础仓库结构，可传 --no-skill。这些 scripts 默认调用公网 npx，不要求先执行 npm install：

{
  "scripts": {
    "mp": "npx @birdie_moblie/plugin-marketplace-cli",
    "validate:plugins": "npx @birdie_moblie/plugin-marketplace-cli validate --all",
    "build:plugins": "npx @birdie_moblie/plugin-marketplace-cli build --all",
    "build:index": "npx @birdie_moblie/plugin-marketplace-cli index",
    "build:all": "npm run build:plugins && npm run build:index",
    "ci:local": "npm run validate:plugins && npm run build:all",
    "release:local": "npm run ci:local && npx @birdie_moblie/plugin-marketplace-cli release-local"
  }
}

如果某个仓库需要固定 CLI 版本，或希望离线维护插件目录，可以手动把 CLI 加为 devDependency：

npm install --save-dev @birdie_moblie/plugin-marketplace-cli

维护 CLI 源码

只有需要修改、测试或重新发布 @birdie_moblie/plugin-marketplace-cli 时才进入 tools/：

cd tools
npm install
npm run build
npm run mp -- --root .. validate --all
npm run mp -- --root .. build --all
npm run mp -- --root .. index
npm pack --dry-run

仓库根目录使用的是已发布 CLI 包。根目录 scripts 用于维护当前插件目录，不用于验证 tools/ 里尚未发布的源码改动。