@birdie_moblie/plugin-marketplace-cli

v1.3.1

Published

2 months ago

维护 Agent Plugins 1.0、Claude Code、Codex 和 Cursor plugin marketplace 仓库的 CLI；支持 install-repo 注册 marketplace

0High
0Medium
0Low

@birdie_moblie/plugin-marketplace-cli

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

使用公网 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
npx @birdie_moblie/plugin-marketplace-cli install-repo <source> [--agent <agent>...] [--all]

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

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

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

install-repo 的 <source> 独立于 --root：它把已就绪的 marketplace 注册到所选 agent，不 build、不 validate、不安装插件。来源可以是本地目录、owner/repo、HTTPS Git URL 或 SSH Git URL。

# 非交互：显式选择 agent
npx @birdie_moblie/plugin-marketplace-cli install-repo owner/repo --agent claude --agent codex

# 选择全部五个目标（Cursor 仍需手工 Dashboard 导入）
npx @birdie_moblie/plugin-marketplace-cli install-repo ./my-marketplace --all

# TTY 下省略 --agent/--all 时会先探测并交互选择
npx @birdie_moblie/plugin-marketplace-cli install-repo https://github.com/org/plugins.git

目标固定顺序：claude → codex → copilot → vscode → cursor。退出码：全部完成 0、部分完成 2、无完成或预检失败 1、中断 130。如果已经本地或全局安装该 npm 包，也可以直接使用 plugin-marketplace bin 运行同一组命令。

插件仓库结构

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

每个插件的 Agent Plugins / Claude Code / Codex 平台信息以 plugin.yaml 为唯一来源。根 plugin.json 与可选根 mcp.json 遵循 Agent Plugins 1.0.0；CLI 离线内置 canonical schema，并校验 fixed Skill discovery 与 MCP 语义。插件也可以额外提供 openspec-source-adapters.yaml overlay，用于声明 OpenSpec source adapter metadata。

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

plugins/**/plugin.json
plugins/**/mcp.json
.claude-plugin/marketplace.json
.github/plugin/marketplace.json
.agents/plugins/marketplace.json
.cursor-plugin/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 暴露。

Hook 插件推荐使用声明式脚本字段：

components:
  hooks:
    - event: PreToolUse
      matcher: Bash
      type: command
      script: hooks/check.py
      interpreter: python3
      timeoutSeconds: 10
      statusMessage: "正在检查命令"

CLI 会生成带引号的 ${CLAUDE_PLUGIN_ROOT} 命令供 Claude Code 与 Codex lifecycle hook 消费。script 必须位于插件目录内且可执行；validate 会检查真实路径、生成物精确一致性和 stale hooks/hooks.json。旧 pattern / command / timeout 仍兼容，其中 legacy command 继续按插件内脚本路径处理并转换为带引号的插件根路径，legacy timeout 按毫秒读取并转换为生成文件中的秒。

Agent Plugins MCP 推荐显式声明 transport：

components:
  mcp:
    - name: local-server
      type: stdio
      command: node
      args: ["./mcp/server.mjs"]
      cwd: "${PLUGIN_ROOT}"
    - name: remote-server
      type: streamable-http
      url: https://example.com/mcp
      headers:
        X-Tenant: public

旧 MCP 条目省略 type 时继续按 stdio 读取。标准输出总会显式写 type。stdio 的 args / env / cwd 只允许 ${PLUGIN_ROOT} 与 ${PLUGIN_DATA} 两种可展开占位符；${TOKEN} 一类 ambient env 写法在标准客户端会保持字面量，CLI 会拒绝。Authorization、Cookie、API key 等凭据不能写入可见的 env/headers，由客户端认证与 secret 管理机制提供。

根 mcp.json 保留标准 ${PLUGIN_ROOT} / ${PLUGIN_DATA}。原生 .mcp.json 会自动转换为 ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA}，并把 ./ executable/cwd 锚定到插件根；不要手改任一派生文件。

Agent Plugins 1.0 不定义 Marketplace。CLI 生成 .claude-plugin / .github/plugin、.agents/plugins 与 .cursor-plugin 索引，是因为对应客户端明确支持这些入口；不会生成虚构的通用 Agent Plugins 市场文件。

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。

维护 CLI 源码

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

cd tools
npm install
npm run build
npm test
npm run mp -- --root .. build --all
npm run mp -- --root .. index
npm run mp -- --root .. validate --all
npm run mp -- --root .. install-repo . --agent cursor
npm pack --dry-run

本仓根目录 mp / ci:local 指向本地 tools/dist，用于验证未发布 CLI。远程用户与 init-repo 生成的新仓仍使用已发布 npx CLI，无需先 npm install。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@birdie_moblie/plugin-marketplace-cli

使用公网 CLI

常用命令

插件仓库结构

推荐脚本

维护 CLI 源码