> ## 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.

# 拓展发布指南

> 面向希望将自己的能力沉淀至 QoderWork 公开市场的作者，介绍拓展生态及四类拓展（Skill / Plugin / Connector / 工作台）各自的上架要求与规范。

本指南面向希望将自己的能力沉淀至 QoderWork 公开市场的作者，介绍 QoderWork 的拓展生态及四类拓展各自的上架要求。

## QoderWork 拓展生态

QoderWork 通过四类拓展，让用户能够按需为 AI 装配能力、角色与外部连接，从"通用助手"演化为契合自身业务的"专属智能体"。四类拓展彼此独立、又可相互组合：Skill 提供原子能力，Plugin 将能力打包为专家角色，Connector 打通外部系统，工作台则承载垂直场景的完整界面。

### Skill — 原子能力

Skill 是 QoderWork 中最基础的能力单元，一份 Skill 即一项可被 AI 复用的"做事方法"。当用户提出与之匹配的任务时，AI 会自动调用对应 Skill，按其内置的步骤、规范与示例完成工作，从而显著提升单一场景下的表现质量。

**典型场景**：生成 PDF 报告、撰写专业合同、解读用户反馈数据、整理周报等。

**特点**：粒度小、即装即用、可被多个专家套件共同复用，是构建上层能力的基石。

### Plugin（专家套件）— 虚拟岗位专家

Plugin 是围绕一个真实岗位或专业角色组织的能力集合，由多个 Skill、若干 Connector 依赖与岗位指令文档共同构成。安装后即可在 QoderWork 中获得一位"虚拟同事"，可独立承担该岗位的完整工作链路。

**典型场景**：超级 HR（招聘全案）、超级法务（合同审查）、超级财务（对账与异常分析）、超级产品经理（需求规划）等。

**特点**：以岗位为中心、能力相互联动、具备完整的工作流，适合需要"一人成军"的复合任务场景。

### Connector — 外部系统连接器

Connector 是 QoderWork 与第三方系统之间的标准化连接通道，本质是一台支持 OAuth 授权的 MCP Server。安装并授权后，AI 即可在用户许可的权限范围内读写对应系统的数据，将外部业务系统纳入工作流之中。

**典型场景**：连接钉钉、Notion、Slack、Jira、企业 CRM 或自建业务系统等。

**特点**：以服务为单位、用户授权可控、可被任意 Skill 或专家套件调用，是 AI 触达真实业务数据的关键入口。

### 工作台 — 垂直场景的独立工作界面

工作台是 QoderWork 中一类形态较重的拓展，为特定专业场景提供独立的工作界面与状态管理，将相关的 Skill、Connector 与自定义 UI 编排在同一画布之内。相较于通用对话界面，工作台更适合高频、重状态、多任务并行的专业作业场景。

**典型场景**：估值复核工作台、合同审阅工作台、销售线索看板等。

**特点**：拥有独立界面与状态、面向单一垂直场景、可深度定制交互流程，是面向专业岗位的"专属工厂"。

## 上架要求

四类拓展共享同一条自助上架通道：在 QoderWork 内提交 → 通过审核 → 上架至公开市场。通过审核后即对外可见，并可在"我的发布"中持续管理。以下仅列出各类拓展最关键的差异化要求。

### Skill 上架要求

Skill 的核心价值在于"被 AI 准确理解并稳定复用"，因此审核重点在内容质量本身：

* **内容清晰**：描述须以第三人称说明 Skill 的职责与触发场景，并包含用户在自然语言中可能使用的关键词，便于 AI 在合适的时机调用；
* **结构合理**：正文应包含明确的使用步骤、注意事项与验证方式，避免出现占位符（如 `TODO`、`<your-token>`）或无法直接执行的伪代码；
* **安全无害**：不得包含恶意脚本、可疑的外部请求或越权指令，亦不得在示例中泄漏真实凭证。

Skill 采用机审为主、人工抽检为辅的审核机制，通常数分钟内即可获得结果。

### Plugin（专家套件）上架要求

Plugin 体现的是"一位专家"的完整能力，因此审核更关注套件作为整体的合理性与专业度：

* **符合套件结构**：须按规范组织目录，提供完整的元数据（`plugin.json`）、内嵌的 Skill 与必要的角色指令文档，且每个内嵌 Skill 自身均须合规；
* **围绕岗位组织**：套件名称建议直接采用真实存在的岗位名称（2–6 字），所含 Skill 与 Connector 之间应存在明确的协作关系，避免将无关能力简单堆砌；
* **依赖可解析**：套件中引用的 Connector 必须为市场中已上架的有效条目。

Plugin 在提交前由客户端进行结构预检，预检通过后进入与 Skill 类似的机审流程。

### Connector 上架要求

Connector 涉及外部数据访问与用户授权，是审核要求最高的拓展类型。原则上，每家公司均可为自家服务提交一个官方 Connector：

* **支持 OAuth 的 MCP Server**：必须为公开可达的 HTTPS MCP Server，并实现完整的 OAuth 授权流程，确保用户的访问权限可控、可撤销；
* **公司身份核验**：上架者须为对应服务的公司可信人员，提交时须配合官方完成实名或企业认证，官方将通过电话方式确认上传人身份；
* **法务与隐私合规**：须提供公开可访问的隐私政策、服务条款，并明确说明采集的数据范围与使用目的；
* **自测报告完整**：须提交涵盖连通性、典型工具调用、权限范围、异常处理与服务可用性的自测说明。

Connector 在机审通过后，将统一进入人工终审环节，不会被自动放行。

### 工作台上架要求

工作台属于较为复杂的一类拓展，承载完整的界面与业务流程，因此对工程化交付有更高的要求：

* **遵循 SDK 规范**：须基于 QoderWork 官方提供的工作台 SDK 进行开发，包含合规的清单文件、UI 资源与 MCP Server 实现；
* **垂直场景明确**：每一个工作台应聚焦一个清晰的专业场景，具备完整的输入、处理与输出链路；
* **资源边界清晰**：工作台所依赖的 Skill、Connector 须在套件内明确声明，并通过 SDK 提供的接口完成集成与权限确认。

由于工作台对界面与状态有深度定制，建议在提交前完成端到端走查，确保在 QoderWork 中可稳定加载与运行。

## 拓展规范

本章为各类拓展提供结构与格式层面的具体要求。满足上述上架要求的同时，须符合本章所列的规范方可通过审核。

### Skill 规范

每个 Skill 以一个独立文件夹为单位，核心为 `SKILL.md`，其余为可选的参考资料。

**目录结构**

```plaintext theme={null}
<skill-name>/
├── SKILL.md          # 技能定义文件（必需）
└── references/       # 参考文件目录（可选，存放模板、示例、数据等辅助材料）
    ├── template.md
    └── example.json
```

**SKILL.md 格式**

文件顶部为 YAML Frontmatter，正文为 Markdown：

```yaml theme={null}
---
name: contract-review           # 技能标识（必需）
description: 审查合同条款并标注风险点。适用于用户上传合同文件并要求审查时。  # 功能描述（必需）
version: 1.0.0                  # 版本号（可选）
---
```

**命名规则**

* 仅允许小写字母、数字与连字符（`-`），不得以连字符开头或结尾
* 最长 64 个字符
* 名称即为技能的唯一标识，发布后不可修改

**版本号**

采用语义化版本（Semantic Versioning），格式为 `主版本.次版本.修订号`，如 `1.2.0`。每次发布新版本时须递增。

**参考文件**

`references/` 目录用于存放 Skill 执行过程中可能引用的辅助材料，如文档模板、格式示例、字典数据等。该目录中的文件将在 AI 调用 Skill 时作为上下文提供，无需额外配置即可生效。

### Plugin（专家套件）规范

Plugin 以文件夹为单位，将多个 Skill、角色指令与 MCP 依赖组织为一个完整的岗位专家。

**目录结构**

```plaintext theme={null}
<plugin-name>/
├── .qoder-plugin/           # 插件元数据目录（必需）
│   └── plugin.json          # 元数据清单（必需）
├── skills/                  # 技能目录（核心）
│   ├── 技能A/SKILL.md
│   └── 技能B/SKILL.md
├── agents/                  # subagent 角色配置（可选）
│   ├── agentA.md
│   └── agentB.md
├── .mcp.json                # MCP Connector 声明（可选）
├── qoder.md                 # 项目指令文件（可选，兼容 cursor.md / claude.md）
├── CONNECTORS.md            # Connector 依赖说明（可选）
└── README.md                # 插件说明文档（可选）
```

**plugin.json 要点**

`plugin.json` 声明了套件的名称、版本、所含技能清单及角色信息。命名建议为真实岗位名称，2–6 个汉字。

**声明式 MCP Connector 配置（可选）**

若套件内的 Skill 需要调用外部系统，可通过 `.mcp.json` 文件声明所需的 MCP Server 连接。用户安装套件时，QoderWork 将引导其完成对应的授权配置。

```json theme={null}
{
  "mcpServers": {
    "钉钉日志": {
      "type": "streamable-http",
      "url": "{{USER_CONFIG}}",
      "_setup": {
        "configUrl": "https://aihub.dingtalk.com/#/detail?mcpId=9639",
        "guide": "请访问上方链接登录钉钉，获取您的个人 MCP Server URL",
        "required": true
      }
    }
  }
}
```

各字段说明：

* `type`：传输协议，支持 `streamable-http` 与 `stdio`
* `url`：填写 `{{USER_CONFIG}}` 作为占位符，用户安装时由实际地址替换
* `_setup.configUrl`：引导用户获取凭证或地址的页面链接
* `_setup.guide`：向用户展示的配置说明文字
* `_setup.required`：是否为必填项；设为 `true` 时，用户未完成配置则无法使用该连接

该文件为可选项。若套件不依赖任何外部系统，可不提供。

### Connector 规范与指南

Connector 本质为一台面向公网的 MCP Server，须满足以下技术与合规要求方可上架。

**技术要求**

* 服务地址须为 HTTPS，且为公开可达的稳定域名（不接受内网 IP 或临时隧道）
* 须实现完整的 OAuth 2.0 授权流程，确保用户授权可控且可撤销
* 工具（Tool）定义须具备清晰的名称与描述，参数应使用 JSON Schema 声明类型与约束
* 建议提供健康检查端点，以便平台监测服务可用性

## 发布之后

上架成功后，作者可在"设置 → 我的发布"中集中管理已发布的拓展，包括查看安装量、修改公开信息、发布新版本、临时下架与重新上架等操作。其中"修改公开信息"仅触发轻量机审，不影响已安装用户；"发布新版本"将重新走完整审核流程，已安装用户会收到更新提示，可自主选择是否升级。

若拓展被驳回，可在"我的发布"中查阅具体原因并按要求重新提交，必要时亦可发起申诉。作者主动下架或官方强制下架均不会强制清除已安装用户的本地副本，但市场中将不再展示，亦不再向新用户分发。

<Note>
  如对发布流程或上架规范存在疑问，可通过 QoderWork 官方反馈通道与审核团队联系。
</Note>