插件

快速开始

下面创建一个仅包含一个 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. 安装

qoderclicn 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 声明

约定目录的行为说明：

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

manifest 字段

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

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

安装作用域

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

命令

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

安装：plugins install

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

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

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

卸载：plugins uninstall

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

别名：remove / rm。

启用 / 禁用：plugins enable / plugins disable

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

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

列出：plugins list

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

校验：plugins validate

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

qoderclicn 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 在执行时会额外得到两个环境变量：

更多 Hook 编写细节见钩子。