Skill · 技能市场 API

索引：backend/real-agent-web/src/main/java/com/ai/agent/real/web/controller/skill/SkillMarketController.java

Skill Market 是 VOLO AI 的能力扩展生态——浏览、安装、卸载、组合 Skill，让 AI 在不同领域获得专业能力。

---

端点总览

Method	Path	用途
GET	/api/skills	分页列出全部 Skill
GET	/api/skills/{id}	获取 Skill 详情
GET	/api/skills/{id}/content	获取 Skill markdown 内容
GET	/api/skills/by-name/{name}	按名称获取
GET	/api/skills/author/{authorId}	按作者列出
GET	/api/skills/my	我已安装的 Skill
POST	/api/skills/{id}/install	安装
DELETE	/api/skills/{id}/install	卸载
GET	/api/skills/{id}/children	获取 Skill Package 的子技能
POST	/api/skills/{id}/toggle-child	切换 Package 内子技能
POST	/api/skills/seed	批量导入种子（管理员）

---

1 · 列出 Skill

GET /api/skills?page=0&pageSize=20&category=design&keyword=critique

参数	类型	说明
page	int	页码（默认 0）
pageSize	int	每页条数（默认 20，max 200）
category	string?	分类过滤（如 design, frontend, pm）
keyword	string?	关键词搜索（名称 + 描述）

响应

{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "uuid-...",
        "name": "h-frontend-design",
        "displayName": "前端设计大师",
        "description": "创建独特的、生产级的前端界面",
        "category": "frontend",
        "version": "1.0.0",
        "authorId": "uuid-...",
        "authorName": "VOLO Team",
        "iconUrl": "https://cdn.volo.ai/skills/h-frontend-design.png",
        "tags": ["frontend", "design", "vue"],
        "installCount": 1024,
        "installed": false,
        "isPackage": false,
        "createdAt": "2026-04-01T10:00:00+08:00"
      }
    ],
    "total": 67,
    "page": 0,
    "pageSize": 20,
    "hasMore": true
  }
}

[TODO: SkillVO 完整字段需对照 backend/real-agent-contract/.../SkillVO.java]

---

2 · 获取 Skill 详情

GET /api/skills/{id}

返回单个 SkillVO。

---

3 · 获取 Skill 内容（Markdown）

GET /api/skills/{id}/content

返回 Skill 的 markdown 全文（即 SKILL.md）：

{
  "code": 200,
  "data": "# h-frontend-design\n\n> 创建独特的..."
}

---

4 · 按名称获取

GET /api/skills/by-name/{name}

例：

curl -X GET "https://api.volo.ai/api/skills/by-name/h-critique" \
  -H "Authorization: Bearer $VOLO_API_KEY"

---

5 · 我已安装的 Skill

GET /api/skills/my?page=0&pageSize=20

返回当前用户已安装的 Skill 分页列表。

---

6 · 安装 Skill

POST /api/skills/{id}/install

返回 true 即安装成功。免费 Skill 立即可用，付费 Skill 触发计费流程（参考 SubscriptionController）。

---

7 · 卸载 Skill

DELETE /api/skills/{id}/install

卸载后该 Skill 在对话中不再被路由。已使用的历史消息不受影响。

---

8 · Skill Package（套装）

Package 是多个 Skill 的组合。用户可整体安装，并在 Package 内单独开关子技能：

获取 Package 子技能

GET /api/skills/{packageId}/children

返回 List<ChildSkillVO>：

{
  "code": 200,
  "data": [
    {
      "id": "uuid-...",
      "name": "h-typeset",
      "displayName": "排版大师",
      "enabled": true
    },
    {
      "id": "uuid-...",
      "name": "h-colorize",
      "displayName": "色彩大师",
      "enabled": false
    }
  ]
}

切换子技能

POST /api/skills/{packageId}/toggle-child?childSkillId={childSkillId}&enabled=true

---

9 · 触发 Skill

在对话中用 / 触发：

/h-critique 帮我评价这个登录页设计

后端 ChatCommandRouterChain 识别 / 触发符，路由到 SkillCommandSpec，发送 COMMAND_START SSE 事件，Skill 执行完发 COMMAND_END。

详见 Quickstart · 第一个 Skill。

---

Skill 命名约定

前缀	用途
h-*	Human-augmenting（设计/产品/UX 专家系列）
pm-*	Product Manager 工具集
gen-*	AI 生成类（图片、文档、代码）
opencli-*	OpenCLI 适配器系列

---

相关

• Quickstart · 第一个 Skill
• Chat API · COMMAND 事件家族