Thanks to visit codestin.com
Credit goes to docs.qoder.cn

Skip to main content
扩展能力

插件（Plugins）

插件将规则、技能、Agents、命令、MCP 服务器和钩子打包成可分发的捆绑包。你可以使用插件来扩展 Qoder CN 的能力——从代码审查、自动部署到连接企业内部系统。

插件包含的内容

组件说明
SkillsAI 的原子执行单元，定义"具体怎么做一件事"。每个 Skill 是一个 SKILL.md 文件
Rules注入 AI 上下文的指令，约束 AI 的行为和风格
Agents子代理定义，可被主 Agent 调度执行特定任务
Commands斜杠命令（/command-name），用户手动触发的快捷操作
MCP Servers连接外部服务的 MCP 服务器配置
Hooks事件钩子，在特定时机自动执行脚本

目录结构

my-plugin/
├── .qoder-plugin/
│   └── plugin.json         # 插件清单（必需）
├── skills/                 # 技能
│   ├── skill-a/
│   │   └── SKILL.md
│   └── skill-b/
│       └── SKILL.md
├── rules/                  # 规则（.md 文件）
├── agents/                 # 子代理（.md 文件）
├── commands/               # 斜杠命令（.md 文件）
├── hooks/
│   └── hooks.json          # 钩子配置
├── mcp.json                # MCP 服务器配置
├── qoder.md                # 项目指令文件（可选）
├── CONNECTORS.md           # Connector 依赖说明（可选）
└── README.md               # 插件说明文档（可选）
除 .qoder-plugin/ 以外，所有目录均为可选，按需创建。plugin.json 中可显式声明路径覆盖默认约定。

插件清单（plugin.json）

plugin.json 位于 .qoder-plugin/ 目录下，是插件的唯一必需文件。
字段类型必填说明
namestring是插件标识符，必须 kebab-case（小写字母、数字、连字符）
versionstring是语义化版本号，如 1.0.0
descriptionstring否插件简介
displayNamestring否展示名称（支持中文），用于客户端 UI 和市场展示
authorobject否作者信息
keywordsstring 数组否搜索关键词
homepagestring否主页或文档 URL
repositorystring否源码仓库 URL
licensestring否SPDX 许可证标识

组件路径声明

字段类型说明
skillsstring 或 string 数组技能目录路径。客户端根据此字段加载对应的 Skill
rulesstring 或 string 数组规则目录路径
agentsstring 或 string 数组Agent 文件路径
commandsstring、string 数组或 object命令文件/目录路径，或命令对象映射
hooksstring钩子配置 JSON 文件路径
mcpServersstringMCP 服务器配置 JSON 文件路径
skills 字段支持精确声明包含哪些 Skill 路径，客户端仅加载声明的 Skill： 
"skills": ["skills/提交需求", "skills/评估Backlog"]
若指向一个目录（如 "./skills"），则该目录下所有包含 SKILL.md 的子目录均被加载。

最小配置

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A simple Qoder CN plugin"
}

完整示例

{
  "name": "requirement-pool",
  "version": "2.3.0",
  "description": "需求池管理工具集",
  "displayName": "需求池管理",
  "author": { "name": "Product Team" },
  "keywords": ["requirement", "backlog"],
  "skills": ["skills/提交需求", "skills/评估Backlog"],
  "rules": "./rules",
  "agents": ["./agents/requirement-reviewer.md"],
  "commands": {
    "submit-req": {
      "source": "./commands/submit.md",
      "description": "提交新需求到需求池",
      "argumentHint": "[title]"
    }
  },
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./mcp.json"
}

技能（SKILL.md）

每个技能是一个独立目录，包含一个 SKILL.md 文件。文件使用 YAML frontmatter + Markdown 正文： 
---
description: 对当前项目执行代码规范检查并自动修复
name: lint-check
---

## 工作流程
1. 读取项目的 lint 配置
2. 运行检查，汇总问题
3. 经用户确认后自动修复
关键字段说明：
字段说明
description最重要的字段——Qoder CN 根据它决定何时自动调用该技能
name技能名称，默认取目录名

MCP 服务器配置

MCP 配置文件为 mcp.json（或 .mcp.json），顶层使用 mcpServers 字段。
  • 本地进程模式
  • 远程服务模式（声明式 Connector）
{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": { "DB_URL": "postgres://localhost:5432/mydb" }
    }
  }
}
客户端行为（QoderWork）：Skill 依赖的 Connector 未配置时，QoderWork 会友好提示"此功能需要先配置「XXX」连接器，请前往插件详情页完成配置"，而非直接抛出连接错误。

钩子（Hooks）

钩子配置文件为 hooks/hooks.json，在特定事件发生时自动执行命令。 
{
  "description": "Simple Pre-Write Check",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${QODER_PLUGIN_ROOT}/check.js\""
          }
        ]
      }
    ]
  }
}
  • matcher：过滤触发的工具名
  • ${QODER_PLUGIN_ROOT}：当前插件安装目录的绝对路径。用于在命令中引用插件内部的资源文件（脚本、配置等），无论插件安装在何处，路径都能正确解析
支持的事件类型及详细配置，请参阅 Hooks 文档。

项目指令文件（qoder.md）

qoder.md 是插件级别的项目指令文件，定义 Agent 人设、工作流编排和护栏规则。当用户整体调起插件时，它作为核心 system prompt 注入，赋予 AI 统一的角色认知和任务编排能力。 文件名为 qoder.md。QoderWork 客户端同时识别 qoderwork.md。

Connector 依赖说明（CONNECTORS.md）

CONNECTORS.md 是面向插件使用者的 Connector 依赖说明文档。它标明每个 Skill 依赖哪些连接、操作哪些资源、如何配置。 示例： 
# Connector 依赖

## 钉钉日志
- **用途**：skill「查询日志」依赖此连接器读取钉钉审计日志
- **资源**：钉钉开放平台审计日志 API
- **配置方式**：前往 https://aihub.dingtalk.com 获取个人 MCP Server URL

## 企业数据库
- **用途**：skill「生成报表」依赖此连接器查询业务数据
- **资源**：PostgreSQL 只读副本
- **配置方式**：联系 DBA 获取只读连接串
此文件帮助使用者在安装插件后快速了解需要配置哪些外部连接，以及各连接的权限和安全边界。

Commands 对象格式

当 commands 为对象时，可以为每个命令定义详细配置：
字段类型说明
sourcestring命令 Markdown 文件路径
descriptionstring命令描述
argumentHintstring参数提示，如 "[env]"

打包与分发

打包格式

插件以 .zip 格式分发。要求：
1

zip 根目录即插件根目录

不要额外嵌套一层目录。
2

包含 plugin.json

.qoder-plugin/plugin.json 必须存在。
3

规范文件名

建议文件名：{name}-{version}.zip。
正确结构： 
deploy-helper-2.0.0.zip
├── .qoder-plugin/
│   └── plugin.json
├── skills/
├── hooks/
│   └── hooks.json
├── mcp.json
├── CONNECTORS.md
└── README.md

路径规则

  • 所有相对路径必须以 ./ 开头
  • 不允许包含 ..（禁止路径穿越）
  • JSON 路径必须以 .json 结尾
  • Markdown 路径必须以 .md 结尾

常见问题

插件和独立 Skill 有什么区别？

独立 Skill 适合单项目使用（直接放在项目的 .qoder/skills/ 下）。插件适合跨项目共享和企业分发——它将多个 Skill 及相关配置打包为一个整体。

plugin.json 放在哪里？

必须放在 .qoder-plugin/plugin.json。

MCP Server 需要个人凭证怎么办？

使用声明式 Connector 配置（{{USER_CONFIG}} 占位符 + _setup 引导），每个用户安装时填入自己的凭证，避免硬编码。

客户端支持情况

已支持　 即将支持　 不适用
组件Qoder CN CN DesktopQoder CN CN CLIJetBrains PluginQoderWork
Skills (SKILL.md)
Rules (.md)
Agents (.md)
Commands (斜杠命令)
MCP Servers
Hooks (hooks.json)
项目指令文件 (qoder.md)
产品概述
快速入门
用户指南
上下文
扩展能力
配置
服务支持