插件参考 - Qoder

插件是可安装的扩展包，为 Qoder CLI 添加命令、Agent、Skills、Hooks、输出风格、工作流和 MCP 服务器。本页是插件清单（manifest）、目录结构与市场（marketplace）schema 的完整参考。使用指南见插件。

插件 Manifest（plugin.json）

manifest 文件位于 .qoder-plugin/plugin.json，不放在插件根目录。该文件可以省略——未声明时 CLI 按约定目录加载组件，并以插件目录名作为插件名；建议声明以获得稳定的 name、version 等元信息。

必填字段

plugin.json 中仅 name 必填，其余字段均可省略。

字段	类型	说明
`name`	string	插件唯一标识（kebab-case，不含空格）。

可选元信息字段

字段	类型	说明
`version`	string	语义化版本号（如 `1.0.0`）。
`displayName`	string	UI 中显示的易读名称。
`description`	string	简短描述。
`author`	object	作者信息（`name`/`email`/`url`）。
`homepage`	string	文档或主页 URL。
`repository`	string	源代码仓库 URL。
`license`	string	SPDX 许可证标识（如 `MIT`、`Apache-2.0`）。
`keywords`	string[]	搜索与分类标签。
`dependencies`	array	依赖的其他插件（可指定 marketplace）。

组件声明字段

以下字段用于覆盖约定目录或内联声明组件（相对路径字符串、数组或对象映射）：

字段	说明
`commands`	命令定义。
`agents`	Agent 定义文件路径。
`skills`	技能目录路径。
`outputStyles`	输出风格定义。
`workflowsPath` / `workflowsPaths`	工作流文件路径。
`hooks`	Hook 配置（相对路径 JSON 文件或内联配置）。
`mcpServers`	MCP 服务器配置（相对路径 JSON 文件或内联配置）。
`userConfig`	用户可配置选项定义。
`settings`	插件启用时合并的配置。当前仅支持 `agent` 键，其余键会被忽略。

约定目录结构

若未在 manifest 中显式声明组件，插件按以下约定目录自动发现：

plugin-name/
├── .qoder-plugin/
│   └── plugin.json      # 推荐：manifest（可省略）
├── commands/            # 命令定义（.md）
│   └── subdir/          # 支持嵌套目录
├── agents/              # Agent 定义（.md）
├── skills/              # 技能目录
│   └── skill-name/
│       └── SKILL.md
├── hooks/
│   └── hooks.json       # Hook 配置
├── output-styles/       # 输出风格定义
├── workflows/           # 工作流定义
├── bin/                 # 可执行文件（加入 PATH）
└── .mcp.json            # MCP 服务器配置

兼容 mcp.json（无前导点）作为 .mcp.json 的回退。两者同时存在时 .mcp.json 优先，且不会合并。

Marketplace Manifest（marketplace.json）

插件市场通过 marketplace.json 描述一组可安装的插件。

必需字段

字段	类型	说明
`name`	string	市场名称。
`owner`	object	市场维护者信息（`name`/`email`/`url`）。
`plugins`	array	插件条目数组。

可选字段

字段	类型	说明
`forceRemoveDeletedPlugins`	boolean	市场中删除的插件自动卸载。
`metadata.pluginRoot`	string	相对插件源的基路径。
`metadata.version`	string	市场版本。
`metadata.description`	string	市场描述。
`allowCrossMarketplaceDependenciesOn`	string[]	允许跨市场依赖的市场名称。

插件条目字段

字段	类型	说明
`name`	string	插件名称（须与 `plugin.json` 中的 `name` 一致）。
`source`	string/object	插件来源（相对路径、npm、git、github、url 等）。
`category`	string	分类标签。
`tags`	string[]	搜索标签。
`strict`	boolean	是否要求插件文件夹中存在 manifest（默认 `true`）。

管理命令

交互式会话中使用 /plugins（别名 /plugin）；不带子命令时打开插件浏览器：

子命令	参数	说明
`install`（别名 `i`）	`<plugin>`	安装插件。
`uninstall`（别名 `remove`/`rm`）	`<plugin>`	卸载插件。
`enable`	`<plugin>`	启用插件。
`disable`	`<plugin>`	禁用插件。
`update`*	`<plugin>`	更新插件。
`validate`	`<path>`	校验插件目录或 `plugin.json`。
`marketplace`（别名 `market`）*	—	管理插件市场，含 `add <source>`、`list`、`remove <name>`、`update [name]`。
`reload`	—	重新加载全部插件。

命令行使用 qodercli plugins（别名 plugin）：

子命令	说明
`list`	列出已安装的插件。
`install`（别名 `i`）	从市场或本地目录安装插件。
`uninstall`（别名 `remove`/`rm`）	卸载插件。
`enable` / `disable`	启用 / 禁用插件。
`update`*	从来源市场更新插件到最新版本。
`validate`	校验本地目录中的插件。
`marketplace`（别名 `mp`）*	管理插件市场。

* 标记的命令受插件市场功能开关控制，未启用时不可用。启动参数：--plugin-dir <path> 附加插件搜索目录。

安全

这两项写在 settings.json 的 security 分组下（修改后需重启）：

{
  "security": {
    "blockGitExtensions": true,
    "allowedExtensions": ["^https://github\\.com/my-org/"]
  }
}

security.blockGitExtensions: true 可阻止从 Git 安装/加载插件。
security.allowedExtensions 提供插件来源的正则白名单，非空时仅允许匹配的来源（覆盖 blockGitExtensions）。

下一步

插件使用指南：插件。
Hooks 参考：Hooks 参考。
MCP 参考：MCP 参考。

​插件 Manifest（plugin.json）

​必填字段

​可选元信息字段

​组件声明字段

​约定目录结构

​Marketplace Manifest（marketplace.json）

​必需字段

​可选字段

​插件条目字段

​管理命令

​安全

​下一步