> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 接入 Claude Code / Codex / Cursor

> 将袋袋专家接入 AI 编程工具（Claude Code、Codex、Cursor、Cline、Gemini CLI），让开发者在编码过程中直接调用你的专家。

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

## 支持的工具

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

## 前置条件

* 袋袋账号 + Developer 角色
* API Key（在 [开发者控制台](https://app.profy.cn/developer) 创建，格式 `profy_sk_*`）
* 专家需要开启 API 访问（`apiAccess: "open"`）

***

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

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

### Claude Code

```bash theme={null}
# 下载 Skill 到项目
curl -o .claude/skills/profy-api.md \
  https://raw.githubusercontent.com/AresEkb/profy/main/knowledge/skills/profy-developer-api/SKILL.md

# 或手动创建
mkdir -p .claude/skills && cp profy-developer-api/SKILL.md .claude/skills/profy-api.md
```

配置 API Key：

```bash theme={null}
export PROFY_API_KEY="profy_sk_your_key_here"
```

安装后在 Claude Code 中直接说：

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

Claude Code 会自动按 Skill 指引调用 `POST https://api.profy.cn/v1/experts/react-architect/chat`。

### Cursor

```bash theme={null}
mkdir -p .cursor/skills/profy-api
cp SKILL.md .cursor/skills/profy-api/SKILL.md
```

### Codex / Cline / Gemini CLI

将 `SKILL.md` 放到项目根目录的 agent skills 目录（具体路径因工具而异），确保环境变量 `PROFY_API_KEY` 已设置。

***

## 方式二：MCP Server 接入

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

### 配置 `.mcp.json`

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

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

### Claude Code 注册

```bash theme={null}
claude mcp add --transport http profy https://mcp.profy.cn/mcp
```

### 可用 Tools（MCP Server 上线后）

| Tool                | 说明             |
| ------------------- | -------------- |
| `search_experts`    | 搜索专家市场         |
| `get_expert_detail` | 获取专家详情         |
| `invoke_expert`     | 调用专家（返回结构化结果）  |
| `chat_completion`   | OpenAI 兼容 Chat |

<Note>
  MCP Server 端点 `mcp.profy.cn` 正在开发中。当前请先使用 Skill 方式接入。
</Note>

***

## API 端点速查

所有请求均需 `Authorization: Bearer $PROFY_API_KEY`。

Base URL: `https://api.profy.cn`

| 方法   | 路径                              | 说明                          |
| ---- | ------------------------------- | --------------------------- |
| POST | `/v1/experts`                   | 搜索专家（keyword/category/page） |
| GET  | `/v1/experts/{identifier}`      | 专家详情                        |
| POST | `/v1/experts/{identifier}/chat` | 调用专家（SSE 流式）                |
| POST | `/v1/chat/completions`          | OpenAI 兼容 Chat Completions  |
| GET  | `/v1/experts/categories`        | 专家分类列表                      |

### 调用专家示例

```bash theme={null}
curl -N https://api.profy.cn/v1/experts/react-architect/chat \
  -H "Authorization: Bearer $PROFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review this code for performance issues:\n\nfunction App() { ... }"
  }'
```

**响应**：SSE 流（`text/event-stream`），Header 中 `X-Session-Id` 用于多轮对话。

### 多轮对话

```bash theme={null}
curl -N https://api.profy.cn/v1/experts/react-architect/chat \
  -H "Authorization: Bearer $PROFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How about using virtualization?",
    "session_id": "SESSION_ID_FROM_FIRST_CALL"
  }'
```

### OpenAI 兼容

```bash theme={null}
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 编程工具调用

1. 在 Studio 中编辑你的专家
2. 设置 **API 访问** 为 `开放`（任何持有 API Key 的开发者可调用）
3. 发布新版本

```bash theme={null}
# 或通过 API 设置
curl -X PUT https://api.profy.cn/v1/creator/experts/{identifier} \
  -H "Authorization: Bearer $PROFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiAccess": "open"}'
```

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

***

## 常见问题

<AccordionGroup>
  <Accordion title="Skill 和 MCP 有什么区别？">
    * **Skill**：纯文本指令，教 AI 如何 curl 你的 API。零基础设施，跨平台兼容。
    * **MCP Server**：结构化工具协议，AI 以 function call 方式调用。更强但需要服务端支持。

    推荐从 Skill 开始，MCP Server 上线后可无缝升级。
  </Accordion>

  <Accordion title="返回 403 怎么办？">
    专家的 `api_access` 字段为 `off`（默认值）。联系专家创作者开启 API 访问，或换一个 `api_access: open` 的专家。
  </Accordion>

  <Accordion title="SSE 流怎么解析？">
    响应为标准 Server-Sent Events 格式。每行以 `data: ` 开头，最终以 `data: [DONE]` 结束。大多数 HTTP 客户端和 AI 工具原生支持 SSE 解析。
  </Accordion>

  <Accordion title="支持哪些模型？">
    通过 `/v1/chat/completions` 端点，支持平台已接入的所有模型（DeepSeek、Qwen 等）。具体可用模型取决于平台配置。
  </Accordion>

  <Accordion title="计费怎么算？">
    按 token 计费（METERED），从 API Key 所属用户的积分中扣除。可在开发者控制台查看用量。
  </Accordion>
</AccordionGroup>

***

## 下一步

* [API 完整参考](/api/post-invoke) — 所有端点的详细参数说明
* [SDK 快速开始](/sdk/quickstart) — TypeScript/Python SDK 接入
* [创作者激励](/documentation/creator-incentive) — API 调用产生的收益分成