> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 插件（Plugins）
插件将规则、技能、Agents、命令、MCP 服务器和钩子打包成可分发的捆绑包。你可以使用插件来扩展 Qoder 的能力——从代码审查、自动部署到连接企业内部系统。
## 插件包含的内容
| 组件 | 说明 |
| --------------- | -------------------------------------------------- |
| **Skills** | AI 的原子执行单元，定义"具体怎么做一件事"。每个 Skill 是一个 `SKILL.md` 文件 |
| **Rules** | 注入 AI 上下文的指令，约束 AI 的行为和风格 |
| **Agents** | 子代理定义，可被主 Agent 调度执行特定任务 |
| **Commands** | 斜杠命令（`/command-name`），用户手动触发的快捷操作 |
| **MCP Servers** | 连接外部服务的 MCP 服务器配置 |
| **Hooks** | 事件钩子，在特定时机自动执行脚本 |
## 目录结构
```plaintext theme={null}
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/` 目录下，是插件的唯一必需文件。
| 字段 | 类型 | 必填 | 说明 |
| ----------- | --------- | -- | -------------------------------- |
| 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：
```json theme={null}
"skills": ["skills/提交需求", "skills/评估Backlog"]
```
若指向一个目录（如 `"./skills"`），则该目录下所有包含 `SKILL.md` 的子目录均被加载。
### 最小配置
```json theme={null}
{
"name": "my-plugin",
"version": "1.0.0",
"description": "A simple Qoder plugin"
}
```
### 完整示例
```json theme={null}
{
"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 正文：
```markdown theme={null}
---
description: 对当前项目执行代码规范检查并自动修复
name: lint-check
---
## 工作流程
1. 读取项目的 lint 配置
2. 运行检查，汇总问题
3. 经用户确认后自动修复
```
**关键字段说明：**
| 字段 | 说明 |
| ----------- | ---------------------------- |
| description | 最重要的字段——Qoder 根据它决定何时自动调用该技能 |
| name | 技能名称，默认取目录名 |
## MCP 服务器配置
MCP 配置文件为 `mcp.json`（或 `.mcp.json`），顶层使用 `mcpServers` 字段。
```json theme={null}
{
"mcpServers": {
"my-db": {
"command": "npx",
"args": ["-y", "@my-org/db-mcp-server"],
"env": { "DB_URL": "postgres://localhost:5432/mydb" }
}
}
}
```
当 MCP Server 需要用户个人凭证时，使用占位符 + `_setup` 引导配置：
```json theme={null}
{
"mcpServers": {
"dingtalk-log": {
"type": "streamable-http",
"url": "{{USER_CONFIG}}",
"_setup": {
"configUrl": "https://aihub.dingtalk.com/#/detail?mcpId=9639",
"guide": "请访问上方链接登录钉钉，获取您的个人 MCP Server URL",
"required": true
}
}
}
}
```
* `{{USER_CONFIG}}`：占位符，安装时需用户填入实际 URL
* `_setup.configUrl`：引导用户获取凭证的页面
* `_setup.guide`：配置引导文案
* `_setup.required`：是否必须配置才能使用该插件
**客户端行为（QoderWork）**：Skill 依赖的 Connector 未配置时，QoderWork 会友好提示"此功能需要先配置「XXX」连接器，请前往插件详情页完成配置"，而非直接抛出连接错误。
## 钩子（Hooks）
钩子配置文件为 `hooks/hooks.json`，在特定事件发生时自动执行命令。
```json theme={null}
{
"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 依赖哪些连接、操作哪些资源、如何配置。
示例：
```markdown theme={null}
# Connector 依赖
## 钉钉日志
- **用途**：skill「查询日志」依赖此连接器读取钉钉审计日志
- **资源**：钉钉开放平台审计日志 API
- **配置方式**：前往 https://aihub.dingtalk.com 获取个人 MCP Server URL
## 企业数据库
- **用途**：skill「生成报表」依赖此连接器查询业务数据
- **资源**：PostgreSQL 只读副本
- **配置方式**：联系 DBA 获取只读连接串
```
此文件帮助使用者在安装插件后快速了解需要配置哪些外部连接，以及各连接的权限和安全边界。
## Commands 对象格式
当 `commands` 为对象时，可以为每个命令定义详细配置：
| 字段 | 类型 | 说明 |
| -------------- | ------ | ---------------- |
| `source` | string | 命令 Markdown 文件路径 |
| `description` | string | 命令描述 |
| `argumentHint` | string | 参数提示，如 `"[env]"` |
## 打包与分发
### 打包格式
插件以 `.zip` 格式分发。要求：
不要额外嵌套一层目录。
`.qoder-plugin/plugin.json` 必须存在。
建议文件名：`{name}-{version}.zip`。
正确结构：
```plaintext theme={null}
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 Desktop | Qoder CLI | JetBrains Plugin | QoderWork |
| ------------------ | ------------------------------------- | ------------------------------------- | ------------------------------------- | ------------------------------------- |
| Skills (SKILL.md) | | | | |
| Rules (.md) | | | | |
| Agents (.md) | | | | |
| Commands (斜杠命令) | | | | |
| MCP Servers | | | | |
| Hooks (hooks.json) | | | | |
| 项目指令文件 (qoder.md) | | | | |