插件

插件（Plugin）是 Qoder CLI 中将命令、子 Agent、Skill、Hook、MCP server 等扩展能力打包成一个目录，便于安装、启用与共享的机制。一个插件目录可以包含一个或多个扩展资源，安装后这些资源会被 CLI 自动发现并加载。

​

快速开始

下面创建一个仅包含一个 Skill 的最小插件，并以本地目录形式安装。

​

1. 创建插件目录

mkdir -p ~/my-plugin/.qoder-plugin
mkdir -p ~/my-plugin/skills/hello

​

2. 编写 manifest

推荐每个插件都声明 plugin.json，至少包含 name 字段，以获得稳定的元信息（详见后文 manifest 字段）：

~/my-plugin/.qoder-plugin/plugin.json：

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "我的第一个插件"
}

​

3. 添加一个 Skill

~/my-plugin/skills/hello/SKILL.md：

---
name: hello
description: 打个招呼。当用户说"打招呼"时使用。
---

# Hello Skill

向用户友好地打个招呼。

​

4. 安装

qodercli plugins install ~/my-plugin

输出 Plugin "my-plugin@local" installed successfully. Run /plugins reload to apply. 后，重启 CLI 或在 TUI 中执行 /plugins reload，即可使用插件提供的 Skill。

​

插件目录结构

.qoder-plugin/plugin.json 是 Qoder 推荐的 manifest 位置；如未声明，CLI 会按约定加载并把目录名作为插件名。约定目录有则加载，无则忽略。

my-plugin/
├── .qoder-plugin/
│   └── plugin.json        # 推荐：manifest（声明 name/version 等元信息）
├── commands/              # 自定义命令（.md 文件或子目录）
├── agents/                # 自定义子 Agent
├── skills/                # 自定义 Skill
├── hooks/
│   └── hooks.json         # Hook 配置
├── output-styles/         # 输出样式
├── bin/                   # 插件可执行文件
└── .mcp.json              # 插件附带的 MCP server 声明

约定目录的行为说明：

目录 / 文件	用途
commands/	注册自定义斜杠命令，结构与 ~/.qoder/commands/ 一致
agents/	注册自定义子 Agent
skills/	注册 Skill，结构与 ~/.qoder/skills/ 一致
hooks/hooks.json	提供 Hook 配置；使用 { "hooks": ... } 包裹格式，其中 hooks 字段的值与 settings.json 的 hooks 字段一致
output-styles/	提供自定义输出样式
bin/	插件提供的可执行文件
.mcp.json	插件附带的 MCP server 声明

插件里的 agents/ 也可以声明 isolation: worktree，适合发布需要隔离执行的实现类 Subagent。

​

manifest 字段

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

字段	必填	说明
name	是	插件唯一标识；不能包含空格，建议使用 kebab-case（如 my-plugin）
version	否	语义化版本号（如 1.0.0）
description	否	简短描述
author	否	作者信息
homepage	否	文档或主页 URL
repository	否	源码仓库 URL
license	否	SPDX license 标识（如 MIT）
keywords	否	用于发现和分类的标签数组

进阶：manifest 还支持显式声明 commands / agents / skills / hooks / outputStyles 等字段，用于覆盖默认的目录约定或使用内联内容（注意 manifest 字段使用驼峰命名 outputStyles，对应的约定目录仍是 output-styles/）。如不显式声明，CLI 会按上一节的目录约定自动发现。

​

安装作用域

插件可以安装到三个作用域：

作用域	说明	适用场景
user	全局可用，对当前用户的所有项目生效（默认）	个人常用插件
project	仅在当前项目生效，配置写入项目级 settings.json，可提交 git 与团队共享	团队共享的项目专属插件
local	仅在当前项目生效，配置写入项目级 settings.local.json，建议加到 .gitignore	本地实验性插件

​

命令

插件相关命令位于 qodercli plugins 子命令组下，别名为 plugin。

​

安装：plugins install

从本地目录路径安装插件：

qodercli plugins install ~/my-plugin
qodercli plugins install ./relative/path/to/plugin
qodercli plugins install /abs/path/to/plugin --scope project

参数 / 选项	说明
<plugin>	本地插件目录路径（绝对路径、相对路径或 ~/... 均可）
-s, --scope <scope>	安装作用域：user（默认）、project、local

安装后建议重启 CLI 或在 TUI 中执行 /plugins reload 让变更生效。

​

卸载：plugins uninstall

qodercli plugins uninstall my-plugin
qodercli plugins uninstall my-plugin --scope project --keep-data

别名：remove / rm。

参数 / 选项	说明
<plugin>	已安装插件名
-s, --scope <scope>	卸载来源的作用域：user（默认）、project、local
--keep-data	保留插件的数据目录

​

启用 / 禁用：plugins enable / plugins disable

qodercli plugins enable my-plugin
qodercli plugins disable my-plugin
qodercli plugins enable my-plugin --scope project
qodercli plugins disable --all

参数 / 选项	说明
<plugin>	已安装插件名
-s, --scope <scope>	写入哪个作用域；不填则自动选择
-a, --all	（仅 disable）一键禁用作用域内所有已启用的插件

启用 / 禁用通过修改对应作用域 settings.json 中的 enabledPlugins 字段实现。被禁用的插件不会在新会话中加载。

​

列出：plugins list

qodercli plugins list
qodercli plugins list --json
qodercli plugins list --plugin-dir ./local-plugins ./more-plugins

选项	说明
--json	以 JSON 输出
-o, --output-format <format>	text 或 json（与 --json 等价）
--plugin-dir <dirs...>	额外扫描这些目录中的插件并合并到列表中（不会自动安装）

​

校验：plugins validate

校验本地插件目录的结构是否符合约定，常用于开发期：

qodercli plugins validate ~/my-plugin

校验会列出发现的命令、Skill、Hook 等组件，并在目录下完全没有任何约定子目录时打印一条提示。注意：validate 本身不会因此失败，但 plugins install 安装本地插件时要求至少包含一个可识别的组件或资源（约定目录或 manifest 中显式声明的资源均可）。

建议：始终在 .qoder-plugin/plugin.json 中声明 name、version 等元信息。这是 Qoder 推荐的插件组织方式——否则插件在 plugins list、enabledPlugins 配置等位置只能用目录名作为标识，不利于跨环境识别和共享。

​

配置 enabledPlugins

启用 / 禁用状态保存在 settings.json 的 enabledPlugins 字段中：

{
  "enabledPlugins": {
    "my-plugin@local": true,
    "another-plugin@local": false
  }
}

• 值为 true：启用该插件
• 值为 false：显式禁用该插件

配置 key 必须与已安装的插件 ID 完全匹配（本地安装的插件 ID 形如 name@local）。可通过 plugins list 查看每个插件的标识。

通过 plugins enable / plugins disable 修改该字段比手工编辑更可靠，因为命令会处理作用域选择、依赖关系等细节。

​

编写插件 Hook

插件可以在 hooks/hooks.json 中声明自身的 Hook。文件使用包裹格式：顶层是一个对象，其中 hooks 字段的值与 settings.json 的 hooks 字段一致：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"${QODER_PLUGIN_ROOT}\"/scripts/check.sh"
          }
        ]
      }
    ]
  }
}

这一点与 settings.json 不同：settings.json 直接写 hooks 字段；插件的 hooks/hooks.json 需要外层多一层 { "hooks": ... } 包裹。

插件提供的 Hook 在执行时会额外得到两个环境变量：

环境变量	说明
QODER_PLUGIN_ROOT	当前插件的安装根目录
QODER_PLUGIN_DATA	当前插件的数据目录（独立于安装目录，便于跨升级保留状态）

更多 Hook 编写细节见钩子。

​

插件市场（Marketplace）

插件市场是插件的集中分发源。通过添加市场源，你可以浏览和安装市场中发布的插件，无需手动管理本地目录。

​

添加市场

支持多种来源格式：

# Git 仓库（HTTPS / SSH）
qodercli plugins marketplace add https://git.example.com/org/my-marketplace.git
qodercli plugins marketplace add [e-mail]:org/my-marketplace.git

# Owner/repo 简写（适用于受支持的 git 托管平台）
qodercli plugins marketplace add org/my-marketplace

# 本地目录
qodercli plugins marketplace add /path/to/marketplace

# URL 指向 marketplace.json
qodercli plugins marketplace add https://example.com/marketplace.json

​

查看已配置的市场

qodercli plugins marketplace list
qodercli plugins marketplace list --json

​

更新市场

从源刷新市场的插件列表：

# 更新指定市场
qodercli plugins marketplace update my-marketplace

# 更新所有市场
qodercli plugins marketplace update

​

移除市场

qodercli plugins marketplace remove my-marketplace

移除市场时，从该市场安装的插件也会被一并卸载。

​

从市场安装插件

添加市场后，可以直接用插件名安装：

qodercli plugins install hello-world

CLI 会自动在已配置的市场中查找插件并安装。安装后的插件 ID 形如 name@marketplace-name。

​

查看可安装的插件

qodercli plugins list --available --json

返回已配置市场中所有可安装但尚未安装的插件列表。

​

更新已安装的市场插件

qodercli plugins update hello-world