plugins-management

插件管理器

跨编码 Agent 管理插件：创建、验证、发布、删除，并提交至官方目录或 npm。

支持的 Agent：

• Claude Code：基于 .claude-plugin/plugin.json 的插件，通过市场分发
• OpenCode：位于 .opencode/plugins/ 中的 TypeScript/JavaScript 插件，或在 opencode.json 中列出的 npm 包
• Devin CLI / Desktop：插件源（GitHub 仓库、git URL、git-subdir 或本地文件夹）中的 .devin-plugin/plugin.json 清单；将技能（<plugin>:<skill> 斜杠命令）、AGENTS.md/rules/、agents/ 子 Agent、hooks.json 和 .mcp.json 作为一个整体安装。通过 devin plugins 命令管理；插件也适用于 Devin 云端会话，但受各界面限制。此技能中的脚本针对 Claude/OpenCode 清单；对于 Devin，请按照 Devin 文档手动编写 .devin-plugin/plugin.json。

重要：执行任何删除、卸载或移除操作前，必须使用 AskUserQuestion 工具向用户确认。未经用户明确确认，绝不能删除/卸载插件或移除市场。

快速参考

任务	命令/脚本
创建插件	python scripts/init_plugin.py <name>
创建市场	python scripts/init_marketplace.py <name>
验证插件	python scripts/validate_plugin.py <path>
验证市场	claude plugin validate <path>
准备提交	python scripts/prepare_submission.py <path> --email X --company-url Y
安装插件	/plugin install <name>@<marketplace>
删除插件	/plugin uninstall <name>@<marketplace>
测试插件（开发）	claude --plugin-dir ./my-plugin
编辑后重新加载	/reload-plugins
创建发布标签	claude plugin tag --push
列出已安装插件	claude plugin list [--json] [--available]
更新插件	claude plugin update <name>@<marketplace>

工作流

1. 创建新插件

# Basic plugin with commands
python scripts/init_plugin.py my-plugin --path ./

# Full plugin with all components
python scripts/init_plugin.py my-plugin --path ./ --all

# Specific components
python scripts/init_plugin.py my-plugin --with-agents --with-skills

标志：

• --with-commands（默认）：包含 commands 目录
• --with-agents：包含 agents 目录
• --with-skills：包含 skills 目录
• --with-hooks：包含 hooks 配置
• --with-mcp：包含 MCP 服务配置
• --all：包含所有组件
• --author "Name"：设置作者姓名

创建后：

1. 编辑 .claude-plugin/plugin.json，填写插件详情
2. 在 commands/*.md 中添加带有 YAML frontmatter 的命令
3. 如有需要，在 agents/*.md 中添加 Agent
4. 更新 README.md 文档

2. 创建市场

# Empty marketplace
python scripts/init_marketplace.py my-marketplace --path ./

# With initial plugin
python scripts/init_marketplace.py my-marketplace --with-plugin my-plugin

创建后：

1. 编辑 .claude-plugin/marketplace.json
2. 将插件添加到 plugins/ 目录
3. 推送到 GitHub：git push origin main

用户通过以下命令安装：

/plugin marketplace add username/my-marketplace

市场引用：

• 必需文件：.claude-plugin/marketplace.json
• 插件条目的 name 必须与各插件 plugin.json 中的名称一致
• 在 source 中使用相对路径（例如 ./plugins/my-plugin），不要使用绝对路径
• 在市场插件引用的 hooks 和 MCP 配置中使用 ${CLAUDE_PLUGIN_ROOT}

3. 验证插件

python scripts/validate_plugin.py ./my-plugin

验证内容：

• plugin.json 必填字段（name、description、version、author）
• 语义化版本格式
• 命令/Agent frontmatter
• Hooks 和 MCP 配置
• README.md 和 LICENSE 是否存在

另请考虑：

• 使用 claude plugin validate <path> 验证市场 JSON

4. 发布插件

发布到 GitHub：

cd my-marketplace
git init
git add .
git commit -m "Initial release"
git remote add origin https://github.com/user/my-marketplace.git
git push -u origin main

# Tag release
git tag -a v1.0.0 -m "Version 1.0.0"
git push origin v1.0.0

分发方式：

• GitHub：/plugin marketplace add user/repo
• GitLab：/plugin marketplace add https://gitlab.com/user/repo.git
• URL：/plugin marketplace add https://example.com/marketplace.json

5. 删除／卸载插件

⚠️ 删除／卸载前务必先征得用户确认。 使用 AskUserQuestion 询问：“您确定要卸载‘[plugin-name]’吗？此操作无法撤销。”

# Uninstall from Claude Code
/plugin uninstall plugin-name@marketplace-name

# Remove marketplace (confirm with user first!)
/plugin marketplace remove marketplace-name

删除源文件： 先通过 AskUserQuestion 征得用户确认，然后从市场的 plugins/ 文件夹中移除插件目录，并更新 marketplace.json。

6. 提交至 Anthropic 官方目录

提交脚本会使用 gh CLI 和 git 自动收集所有必需的表单字段。

先决条件：

1. 插件已推送到 GitHub
2. 已安装并完成身份验证的 gh CLI
3. 所有验证检查均通过

准备提交：

# Basic - gathers repo URL and SHA automatically
python scripts/prepare_submission.py ./my-plugin

# With required contact info
python scripts/prepare_submission.py ./my-plugin \
  --email [email protected] \
  --company-url https://yourcompany.com

# Copy SHA to clipboard
python scripts/prepare_submission.py ./my-plugin --copy-sha

# Save to JSON file
python scripts/prepare_submission.py ./my-plugin --output submission.json

# Open form in browser
python scripts/prepare_submission.py ./my-plugin --open-form

自动收集的表单字段：

字段	来源
插件链接	gh repo view --json url
完整 SHA	git rev-parse HEAD
插件主页	plugin.json homepage 或仓库 URL
插件名称	plugin.json name
插件描述	plugin.json description（50-100 个单词）

需要你提供的字段：

• --email：主要联系人邮箱
• --company-url：公司／组织 URL

提交要求：

• 插件必须已推送到 GitHub
• 工作目录应保持干净（没有未提交的更改）
• 描述应为 50-100 个单词
• 必须包含 README.md 和 LICENSE 文件
• 代码中不得包含机密信息／API 密钥

插件结构参考

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Optional manifest (auto-discovered if absent)
├── skills/               # Agent skills (preferred over commands/)
│   └── */SKILL.md
├── commands/             # Skills as flat .md files
│   └── *.md
├── agents/               # AI subagents
│   └── *.md
├── output-styles/        # Output style definitions (2026)
├── themes/               # Color themes (2026)
├── monitors/             # Background monitors (2026, v2.1.105+)
│   └── monitors.json
├── hooks/
│   └── hooks.json        # Event handlers
├── bin/                  # Executables added to PATH (2026)
├── settings.json         # Default agent / subagentStatusLine (2026)
├── .mcp.json             # MCP servers
├── .lsp.json             # LSP server config (since v2.0.74)
├── package.json          # Auto-installed dependencies (2026)
├── README.md             # Documentation
├── CHANGELOG.md
└── LICENSE

详细参考： 请参阅 references/plugin-guide.md

OpenCode 插件

OpenCode（anomalyco/opencode v1.14.x）插件是 TypeScript/JavaScript 模块，与 Claude Code 插件有本质区别。

快速参考

任务	方式
创建本地插件	将 .ts 文件放入 .opencode/plugins/（项目级）或 ~/.config/opencode/plugins/（全局）
编写 npm 插件	执行 npm init，添加 keywords: ["opencode-plugin"]，并依赖 @opencode-ai/plugin
安装 npm 插件	将包名称添加到 opencode.json → "plugin": [...]；然后重启
分发	发布到 npm（没有中央市场）

最简插件

// .opencode/plugins/env-protection.ts
import type { Plugin } from "@opencode-ai/plugin"

export default (async () => ({
  tool: {
    execute: {
      before: async (input, output) => {
        if (output.args.filePath?.includes(".env")) {
          throw new Error("Reading .env is forbidden")
        }
      },
    },
  },
})) satisfies Plugin

注册 npm 插件

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "@my-org/custom-plugin"
  ]
}

OpenCode 会在启动时运行 bun install。缓存位置为 ~/.cache/opencode/node_modules/。

插件可以做什么

• 添加 AI 可调用的自定义工具（参数使用 Zod 验证）
• 拦截／阻止工具调用（抛出异常以阻止 tool.execute.before）
• 订阅约 25 个生命周期事件（session.idle、file.edited、permission.asked 等）
• 注册自定义斜杠命令和身份验证提供程序
• 在上下文压缩期间转换消息或系统提示词（实验性）

重要注意事项（v1.14.x）

• 对 MCP 工具调用不会触发 tool.execute.* 钩子——请使用 opencode.json 中的 permission 配置块
• 没有中央市场——通过 npm 和 awesome-opencode 等聚合平台分发
• 插件在进程内运行，并拥有完整的 SDK 访问权限——安装前请审查第三方代码

完整的 OpenCode 插件参考请参阅 references/opencode-plugins.md。

关键规则（避免静默失败）

• 将 skills/、commands/、agents/、hooks/、monitors/、themes/、output-styles/、bin/ 放在插件根目录（绝不要放在 .claude-plugin/ 内）。
• 不要将标准组件路径添加到 plugin.json。仅指定以 ./ 开头的非标准路径。
• 在 hooks 和 MCP/LSP/monitor 配置路径中使用 ${CLAUDE_PLUGIN_ROOT}（缓存路径，会随版本变化）和 ${CLAUDE_PLUGIN_DATA}（更新后仍保留）。相对路径在安装后会失效。
• 确保 hook 脚本具有可执行权限（chmod +x scripts/*）。
• Marketplace 的 plugins[].name 必须与插件 plugin.json 中的 name 一致。
• 路径遍历限制（2026）：插件不能引用其目录之外的文件；如有需要，请在插件内使用符号链接。
• 版本管理（2026）：省略 version 以使用 git SHA（每次提交都是新版本）。设置 version 并在发布稳定版本时递增。使用 claude plugin tag 创建发布标签。

常见模式

命令文件格式

---
description: What this command does
---

# Command Name

Instructions for Claude when command is invoked.

Agent 文件格式

---
description: Agent specialty and purpose
---

# Agent Name

Detailed instructions and expertise.

Hooks 配置

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  }
}

MCP 服务配置

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["./servers/server.js"]
    }
  }
}

技能文件格式

---
name: my-skill
description: What this skill does and when to use it
---

# Skill Title

Instructions for Claude when this skill is invoked.

Marketplace 条目示例

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "Short description",
  "version": "1.0.0",
  "author": { "name": "Author Name" },
  "category": "productivity",
  "keywords": ["tag1", "tag2"],
  "strict": true
}