接入 Claude Code / Codex / Cursor

袋袋专家可以作为 Skill 或 MCP Server 被主流 AI 编程工具调用，开发者在 IDE 中直接获取专家的专业能力。

支持的工具

工具	接入方式	状态
Claude Code	Skill / MCP Server	✅ 可用
Cursor	Skill	✅ 可用
Codex (OpenAI)	Skill	✅ 可用
Cline	Skill	✅ 可用
Gemini CLI	Skill	✅ 可用

前置条件

袋袋账号 + Developer 角色
API Key（在开发者控制台创建，格式 sk-pro-*）
专家需要开启 API 访问（apiAccess: "open"）

方式一：Skill 接入（推荐，零基础设施）

Skill 是一个 Markdown 文件，教 AI 编程工具如何调用袋袋 API。安装后，agent 会自动识别何时调用袋袋专家。

Claude Code

插件位于袋袋仓库的 agent-plugin/ 目录，安装脚本会自动探测你机器上装了哪些编程工具，并按各自格式写入：

cd agent-plugin && bash install.sh

# 只装指定工具
bash install.sh --only=cursor,codex,claude

它自带 4 个 skill——quick-start、distillation、publish-and-earn、evolution，外加一份指向远程 MCP Server 的 .mcp.json。配置 API Key：

export PROFY_API_KEY="sk-pro-your-key-here"

安装后在 Claude Code 中直接说：

“用袋袋的 react-architect 专家审查一下这段代码”

Claude Code 会自动按 Skill 指引调用 POST https://api.profy.cn/v1/agents/run，并在请求体里带上 expert_identifier: "react-architect"。

Cursor

同一个脚本会写入 .cursor/rules/ 规则和 .cursor/mcp.json：

bash install.sh --only=cursor

Codex / Gemini CLI / 其他

安装器原生覆盖 13 种工具——Claude Code、Copilot、Gemini CLI、OpenCode、Cursor、Codex、Aider、Windsurf、OpenClaw、Qwen Code、Kimi Code、Osaurus、Hermes，各按该工具自己的格式与安装位置落盘。其余任何支持 MCP 的客户端，直接指向 https://mcp.profy.cn/mcp 即可。确保运行这些工具的 shell 里已导出 PROFY_API_KEY。

方式二：MCP Server 接入

MCP (Model Context Protocol) 提供更强的集成能力，让 AI 工具以结构化工具调用的方式使用袋袋专家。

配置 `.mcp.json`

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "profy": {
      "type": "http",
      "url": "https://mcp.profy.cn/mcp",
      "headers": {
        "Authorization": "Bearer ${PROFY_API_KEY}"
      }
    }
  }
}

Claude Code 注册

claude mcp add --transport http profy https://mcp.profy.cn/mcp

可用 Tools

MCP Server 一共暴露 22 个 tool，按能力分组如下。注意它的重心：这套接口是给你创建并上架专家用的，而不只是调用专家。

分组	Tools
身份（2）	`get_creator_profile`、`apply_creator`
专家配置（4）	`create_expert`、`update_expert`、`get_expert_detail`、`list_my_experts`
技能（3）	`install_skill`、`list_expert_skills`、`list_marketplace_skills`
计费与发布（3）	`set_billing`、`publish_expert`、`get_submission_status`
蒸馏（2）	`start_distillation`、`continue_distillation`
测试（2）	`test_expert`、`open_expert_chat`
页面跳转（1）	`open_profy_page`
自进化（3）	`list_evolution_suggestions`、`accept_evolution`、`get_evolution_stats`
收益与发现（2）	`get_earnings`、`browse_marketplace`

这里没有 invoke_expert：真正跑一次专家要走 REST API（POST /v1/agents/run）。MCP 负责的是创作闭环——蒸馏、配置、测试、发布、看收益。

API 端点速查

所有请求均需 Authorization: Bearer $PROFY_API_KEY。 Base URL: https://api.profy.cn

方法	路径	说明
POST	`/v1/agents/run`	调用一次专家（SSE 流式）
POST	`/v1/chat/completions`	OpenAI 兼容 Chat Completions
GET	`/v1/models`	你可用的模型列表
GET	`/v1/meters`	计费计量项（公开，无需鉴权）
POST	`/v1/sessions`	创建会话，用于多轮任务
GET	`/v1/agents`	列出你自己的 agent

完整清单（含 sessions、files、environments）见端点参考。

调用专家示例

专家标识放在请求体里，不在路径上：

curl -N https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer $PROFY_API_KEY" \
  -H "X-End-User-Id: your-end-user-id" \
  -H "Content-Type: application/json" \
  -d '{
    "expert_identifier": "react-architect",
    "message": "Review this code for performance issues:\n\nfunction App() { ... }"
  }'

响应：SSE 流（text/event-stream）。

用 API Key 调用时 X-End-User-Id 是必填的，缺了直接返回 400。它的作用是把这次调用归属到你的某个终端用户，而不是归到你的 Key 本身。

多轮对话

带上 session_id 续接同一条会话：

curl -N https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer $PROFY_API_KEY" \
  -H "X-End-User-Id: your-end-user-id" \
  -H "Content-Type: application/json" \
  -d '{
    "expert_identifier": "react-architect",
    "message": "How about using virtualization?",
    "session_id": "SESSION_ID_FROM_FIRST_CALL"
  }'

OpenAI 兼容

curl -s https://api.profy.cn/v1/chat/completions \
  -H "Authorization: Bearer $PROFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

创作者：如何让你的专家被 AI 编程工具调用

每个专家的 API 访问默认关闭——api_access 列的库内默认值就是 off，并且和其他内容字段一样，会随发布版本与待审提交一起流转。

在 Studio 中编辑你的专家
设置 API 访问 为 开放（任何持有 API Key 的开发者可调用）
发布新版本——和所有内容改动一样，审核通过后才会到达公开面

设置后，你的专家就能被全球开发者在 Claude Code、Cursor、Codex 中直接调用。

常见问题

Skill 和 MCP 有什么区别？

Skill：纯文本指令，教 AI 如何 curl 你的 API。零基础设施，跨平台兼容。
MCP Server：结构化工具协议，AI 以 function call 方式调用，覆盖创作闭环（蒸馏/配置/发布/收益）。

两者不互斥：install.sh 同时装 skill 和 .mcp.json。跑专家用 REST，做专家用 MCP。

返回 403 怎么办？

专家的 api_access 字段为 off（默认值）。联系专家创作者开启 API 访问，或换一个 api_access: open 的专家。

SSE 流怎么解析？

响应为标准 Server-Sent Events 格式。每行以 data: 开头，最终以 data: [DONE] 结束。大多数 HTTP 客户端和 AI 工具原生支持 SSE 解析。

支持哪些模型？

通过 /v1/chat/completions 端点，支持平台已接入的所有模型（DeepSeek、Qwen 等）。具体可用模型取决于平台配置。

计费怎么算？

按 token 计费（METERED），从 API Key 所属用户的积分中扣除。可在开发者控制台查看用量。

关键数值

项	值
MCP 暴露的 tool 数	22
MCP 传输方式	Streamable HTTP，`https://mcp.profy.cn/mcp`
API Key 前缀	`sk-pro-`
新专家的 `api_access` 默认值	`off`
Key 调用时的 `X-End-User-Id`	必填，缺失返回 400
调用专家的端点	`POST /v1/agents/run`（标识放请求体）
响应格式	SSE，以 `data: [DONE]` 结束
计费	按 token 计量，从 API Key 所属用户扣除

失败与对策

现象	HTTP	原因	对策
`401 Unauthorized`	401	Key 缺失或格式不对	Key 必须以 `sk-pro-` 开头，走 `Authorization: Bearer`
报错提示缺终端用户	400	Key 调用没带 `X-End-User-Id`	传一个稳定的终端用户标识
`400 Missing required field: expert_identifier`	400	把标识写在了路径上	`/v1/agents/run` 从请求体读取标识
某个专家返回 `403`	403	该专家的 `api_access` 为 `off`	联系其创作者开启
请求 `/v1/experts/...` 返回 `404`	404	这个路由不存在	改用 `/v1/agents/run`，见端点参考
流读完却没有内容	—	把 SSE 当普通 JSON 响应解析了	按 `text/event-stream` 逐行读到 `data: [DONE]`
积分掉得比预期快	—	token 计量记在 Key 所属用户头上，不记在你的终端用户头上	在控制台看用量，并自行对每个终端用户设上限

下一步

端点参考

每个 /v1/* 路由的鉴权方式与用途

SSE 事件

一次调用里会解析到哪些事件类型

MCP Tools

22 个 tool 的完整参数说明

Python SDK

用带类型的客户端替代裸 curl

核实于 2026-08-12。来源：services/core/src/routes/platform-api/index.ts（/v1 端点面）、services/core/src/routes/mcp/tools/index.ts（22 个已注册 tool）、packages/db/src/schema/marketplace.ts（api_access 默认值）、agent-plugin/（安装器与 4 个 skill）。

开始使用

认证与密钥

API 能力指南

SDK

集成

Cookbook

参考

接入 Claude Code / Codex / Cursor

支持的工具

前置条件

方式一：Skill 接入（推荐，零基础设施）

Claude Code

Cursor

Codex / Gemini CLI / 其他

方式二：MCP Server 接入

配置 `.mcp.json`

Claude Code 注册

可用 Tools

API 端点速查

调用专家示例

多轮对话

OpenAI 兼容

创作者：如何让你的专家被 AI 编程工具调用

常见问题

关键数值

失败与对策

下一步

端点参考

SSE 事件

MCP Tools

Python SDK

​支持的工具

​前置条件

​方式一：Skill 接入（推荐，零基础设施）

​Claude Code

​Cursor

​Codex / Gemini CLI / 其他

​方式二：MCP Server 接入

​配置 .mcp.json

​Claude Code 注册

​可用 Tools

​API 端点速查

​调用专家示例

​多轮对话

​OpenAI 兼容

​创作者：如何让你的专家被 AI 编程工具调用

​常见问题

​关键数值

​失败与对策

​下一步

端点参考

SSE 事件

MCP Tools

Python SDK

支持的工具

前置条件

方式一：Skill 接入（推荐，零基础设施）

Claude Code

Cursor

Codex / Gemini CLI / 其他

方式二：MCP Server 接入

配置 `.mcp.json`

Claude Code 注册

可用 Tools

API 端点速查

调用专家示例

多轮对话

OpenAI 兼容

创作者：如何让你的专家被 AI 编程工具调用

常见问题

关键数值

失败与对策

下一步