插件将规则、技能、Agents、命令、MCP 服务器和钩子打包成可分发的捆绑包。你可以使用插件来扩展 Qoder CN 的能力——从代码审查、自动部署到连接企业内部系统。
除
若指向一个目录(如
每个技能是一个独立目录,包含一个
关键字段说明:
MCP 配置文件为
钩子配置文件为
此文件帮助使用者在安装插件后快速了解需要配置哪些外部连接,以及各连接的权限和安全边界。
当
插件以
正确结构:
独立 Skill 适合单项目使用(直接放在项目的
必须放在
使用声明式 Connector 配置(
已支持 即将支持 不适用
插件包含的内容
| 组件 | 说明 |
|---|---|
| Skills | AI 的原子执行单元,定义"具体怎么做一件事"。每个 Skill 是一个 SKILL.md 文件 |
| Rules | 注入 AI 上下文的指令,约束 AI 的行为和风格 |
| Agents | 子代理定义,可被主 Agent 调度执行特定任务 |
| Commands | 斜杠命令(/command-name),用户手动触发的快捷操作 |
| MCP Servers | 连接外部服务的 MCP 服务器配置 |
| Hooks | 事件钩子,在特定时机自动执行脚本 |
目录结构
.qoder-plugin/ 以外,所有目录均为可选,按需创建。plugin.json 中可显式声明路径覆盖默认约定。
插件清单(plugin.json)
plugin.json 位于 .qoder-plugin/ 目录下,是插件的唯一必需文件。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 插件标识符,必须 kebab-case(小写字母、数字、连字符) |
| version | string | 是 | 语义化版本号,如 1.0.0 |
| description | string | 否 | 插件简介 |
| displayName | string | 否 | 展示名称(支持中文),用于客户端 UI 和市场展示 |
| author | object | 否 | 作者信息 |
| keywords | string 数组 | 否 | 搜索关键词 |
| homepage | string | 否 | 主页或文档 URL |
| repository | string | 否 | 源码仓库 URL |
| license | string | 否 | SPDX 许可证标识 |
组件路径声明
| 字段 | 类型 | 说明 |
|---|---|---|
skills | string 或 string 数组 | 技能目录路径。客户端根据此字段加载对应的 Skill |
rules | string 或 string 数组 | 规则目录路径 |
agents | string 或 string 数组 | Agent 文件路径 |
commands | string、string 数组或 object | 命令文件/目录路径,或命令对象映射 |
hooks | string | 钩子配置 JSON 文件路径 |
mcpServers | string | MCP 服务器配置 JSON 文件路径 |
skills 字段支持精确声明包含哪些 Skill 路径,客户端仅加载声明的 Skill:
"./skills"),则该目录下所有包含 SKILL.md 的子目录均被加载。
最小配置
完整示例
技能(SKILL.md)
每个技能是一个独立目录,包含一个 SKILL.md 文件。文件使用 YAML frontmatter + Markdown 正文:
| 字段 | 说明 |
|---|---|
| description | 最重要的字段——Qoder CN 根据它决定何时自动调用该技能 |
| name | 技能名称,默认取目录名 |
MCP 服务器配置
MCP 配置文件为 mcp.json(或 .mcp.json),顶层使用 mcpServers 字段。
- 本地进程模式
- 远程服务模式(声明式 Connector)
钩子(Hooks)
钩子配置文件为 hooks/hooks.json,在特定事件发生时自动执行命令。
matcher:过滤触发的工具名${QODER_PLUGIN_ROOT}:当前插件安装目录的绝对路径。用于在命令中引用插件内部的资源文件(脚本、配置等),无论插件安装在何处,路径都能正确解析
项目指令文件(qoder.md)
qoder.md 是插件级别的项目指令文件,定义 Agent 人设、工作流编排和护栏规则。当用户整体调起插件时,它作为核心 system prompt 注入,赋予 AI 统一的角色认知和任务编排能力。
文件名为 qoder.md。
Connector 依赖说明(CONNECTORS.md)
CONNECTORS.md 是面向插件使用者的 Connector 依赖说明文档。它标明每个 Skill 依赖哪些连接、操作哪些资源、如何配置。
示例:
Commands 对象格式
当 commands 为对象时,可以为每个命令定义详细配置:
| 字段 | 类型 | 说明 |
|---|---|---|
source | string | 命令 Markdown 文件路径 |
description | string | 命令描述 |
argumentHint | string | 参数提示,如 "[env]" |
打包与分发
打包格式
插件以 .zip 格式分发。要求:
1
zip 根目录即插件根目录
不要额外嵌套一层目录。
2
包含 plugin.json
.qoder-plugin/plugin.json 必须存在。3
规范文件名
建议文件名:
{name}-{version}.zip。路径规则
- 所有相对路径必须以
./开头 - 不允许包含
..(禁止路径穿越) - JSON 路径必须以
.json结尾 - Markdown 路径必须以
.md结尾
常见问题
插件和独立 Skill 有什么区别?
独立 Skill 适合单项目使用(直接放在项目的 .qoder/skills/ 下)。插件适合跨项目共享和企业分发——它将多个 Skill 及相关配置打包为一个整体。
plugin.json 放在哪里?
必须放在 .qoder-plugin/plugin.json。
MCP Server 需要个人凭证怎么办?
使用声明式 Connector 配置({{USER_CONFIG}} 占位符 + _setup 引导),每个用户安装时填入自己的凭证,避免硬编码。
客户端支持情况
已支持 即将支持 不适用
| 组件 | Qoder CN CN Desktop | Qoder CN CN CLI | JetBrains Plugin |
|---|---|---|---|
| Skills (SKILL.md) | |||
| Rules (.md) | |||
| Agents (.md) | |||
| Commands (斜杠命令) | |||
| MCP Servers | |||
| Hooks (hooks.json) | |||
| 项目指令文件 (qoder.md) |