# Agora AI编程助手技能库

`Agora` `实时通信` `AI编程助手` `RTC` `RTM` `对话式AI` `SDK`

# Agora Skills

为 [Agora](https://www.agora.io)（agora.io）实时 AI 与通信 SDK 提供的结构化参考知识库，专为 AI 编程助手设计。涵盖对话式 AI（语音 AI 智能体）、RTC（视频/语音）、RTM（信令/消息）以及服务端 Token 生成。

## 安装

### Skills CLI（推荐）

```bash
npx skills add github:AgoraIO/skills
```

当你的智能体检测到相关任务时（例如"构建语音智能体"、"集成 Agora RTC"、"生成 Token"），技能将自动激活。

### Claude Code 插件（使用 Claude 时推荐）

将 Agora skills 和 Agora Docs MCP 服务器作为 Claude Code 插件安装。在 Claude Code 中运行以下两条斜杠命令：

```
/plugin marketplace add AgoraIO/skills
/plugin install agora@agora-skills
```

Agora MCP 服务器（`mcp.agora.io`）会自动捆绑安装，无需单独配置 MCP。

### Git 克隆

克隆仓库后，将工具指向 `skills/agora/`：

```bash
git clone https://github.com/AgoraIO/skills.git ~/agora-skills
```

### 配置你的智能体或 IDE（可选）

**Claude Code — 符号链接（用户级）：**

使用 Skills CLI 安装技能后，可以将技能符号链接到主目录，使其对所有智能体可用。

```bash
ln -s ~/agora-skills/skills/agora ~/.claude/skills/agora
```

**Claude Code — 复制（项目级，与团队共享）：**

使用 Claude Code 插件安装技能后，可以将技能复制到项目目录，使其对该项目的所有智能体可用。

```bash
mkdir -p .claude/skills
cp -r ~/agora-skills/skills/agora .claude/skills/agora
```

**Cursor：** 复制或符号链接到 `.cursor/rules/`。参见 [Cursor skills 文档](https://cursor.com/docs/skills#skill-directories)。

**Windsurf：** 将 `skills/agora/` 添加到 Cascade 上下文。参见 [Windsurf skills 文档](https://docs.windsurf.com/windsurf/cascade/skills)。

**GitHub Copilot：** 通过 `@workspace` 引用，或添加到 `.github/copilot-instructions.md`。参见 [Copilot CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills) 和 [Copilot Agents skills](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills)。

**其他工具：** 技能文件均为纯 Markdown 格式。将工具指向 `skills/agora/`，或直接加载单个文件。以 `SKILL.md` 作为入口——它链接到所有其他内容。

---

## 这是什么

本仓库包含 Markdown 技能文件，为 AI 编程助手提供对 Agora 平台的深度知识。当开发者寻求 Agora 相关帮助时，助手会加载相应的参考资料——从高层产品概览到特定平台的代码示例和 API 详情。

**涵盖产品：**

- **RTC（视频/语音 SDK）** — Web、React、Next.js、iOS（Swift）、Android（Kotlin/Java）、React Native、Flutter
- **RTM（信令）** — Web（JS/TS）、iOS（Swift）、Android（Kotlin）——均为 v2；消息、在线状态、元数据、流频道
- **对话式 AI** — REST API、智能体配置、Gemini Live + OpenAI Realtime MLLM、iOS/Android 工具包，6 个示例仓库（agent-samples、agent-toolkit、agent-client-toolkit-react、agent-ui-kit、server-custom-llm、server-mcp）
- **云端录制** — REST API 的 acquire/start/query/stop 生命周期
- **服务器网关** — 服务端 RTC 的 Linux SDK（C++）
- **服务端** — Node.js、Python、Go 的 Token 生成
- **多产品集成** — RTC + RTM + ConvoAI 的初始化顺序、UID 策略、编解码器选择、Token 矩阵
- **测试指南** — 所有平台的 Mock 模式（Web、React、iOS、Android、React Native、Flutter、RTM）

## 设计——四层渐进式信息披露

LLM 的上下文窗口是有限的。加载所需的最少内容，仅在必要时深入加载。

| 层级 | 内容 | 大小 | 加载时机 |
| --- | --- | --- | --- |
| **第 1 层 — 描述** | `SKILL.md` frontmatter 中的触发关键词 | ~100 词 | 始终加载（技能索引） |
| **第 2 层 — SKILL.md 主体** | 核心概念、产品索引、框架说明 | ~72 行 | 激活时加载 |
| **第 3 层 — 产品 README** | 概览、关键规则、主题链接 | 20–100 行 | 按产品加载 |
| **第 4 层 — 主题文件** | 实现细节、代码示例、API 参考或目录+链接 | 34–500 行 | 按主题加载 |

导航路径：`SKILL.md` → 产品 `README.md` → 主题文件（如 `web.md`、`agent-samples.md`）。

### 链接优先 vs 内联

并非所有内容都适合内联。该技能根据上游内容的变更频率和文档完善程度采用两种策略：

| 产品 | 策略 | 原因 |
| --- | --- | --- |
| **对话式 AI** | 目录 + 链接到仓库 README 和 AGENT.md | 迭代快，5 个上游仓库文档完善 |
| **RTC / RTM** | 内联代码示例 | API 稳定，官方文档缺乏优质示例 |
| **服务端 / Token** | 目录 + 链接到官方文档 | docs.agora.io 文档完善 |

ConvoAI 文件与 [AgoraIO-Conversational-AI](https://github.com/orgs/AgoraIO-Conversational-AI/repositories) 中的仓库一一对应。每个文件映射一个仓库，并链接到其 README 和 AGENT.md 作为权威来源。LLM 经常出错的注意事项和怪异行为仍以内联方式保留在 ConvoAI README 中。

## 文件结构

```
skills/
└── agora/                          技能根目录
    ├── SKILL.md                    入口文件，产品索引（v1.2.0）
    ├── intake/
    │   └── SKILL.md                多产品需求分析路由器
    └── references/
        ├── doc-fetching.md         两级查找流程（面向智能体）
        ├── mcp-tools.md            MCP 工具参考与优雅降级
        ├── integration-patterns.md RTC+RTM+ConvoAI：初始化顺序、UID 策略、编解码器、Token
        ├── rtc/                    RTC（视频/语音 SDK）
        │   ├── README.md           关键规则、编码器配置、跨平台说明
        │   ├── web.md              agora-rtc-sdk-ng：客户端、音轨、事件、屏幕共享
        │   ├── react.md            agora-rtc-react：hooks、编解码器互操作、自定义模式
        │   ├── nextjs.md           Next.js / SSR 动态导入模式
        │   ├── ios.md              AgoraRtcEngineKit（Swift）：设置、委托
        │   ├── android.md          RtcEngine（Kotlin/Java）：设置、回调
        │   ├── react-native.md     react-native-agora：引擎初始化、事件、视频视图
        │   ├── flutter.md          agora_rtc_engine（Dart）：引擎初始化、AgoraVideoView
        │   └── cross-platform-coordination.md  UID 策略、编解码器互操作、屏幕共享
        ├── rtm/                    RTM 信令 SDK v2
        │   ├── README.md           核心概念、注意事项、平台链接
        │   ├── web.md              agora-rtm v2：消息、在线状态、流频道
        │   ├── ios.md              AgoraRtmClientKit（Swift）：初始化、登录、订阅、发布
        │   └── android.md          RtmClient（Kotlin）：初始化、登录、订阅、发布
        ├── conversational-ai/      对话式 AI（语音 AI 智能体）
        │   ├── README.md           架构、接口端点、认证、生命周期、注意事项
        │   ├── agent-samples.md    后端、React 客户端、配置文件、MLLM、部署
        │   ├── agent-toolkit.md    @agora/conversational-ai SDK：API、辅助工具、hooks
        │   ├── agent-client-toolkit-react.md   React hooks：provider、转录、状态
        │   ├── agent-ui-kit.md     @agora/agent-ui-kit React 组件
        │   ├── agent-toolkit-ios.md    iOS ConversationalAIAPIImpl Swift 工具包
        │   ├── agent-toolkit-android.md  Android ConversationalAIAPIImpl Kotlin 工具包
        │   ├── server-custom-llm.md  自定义 LLM 代理：RAG、工具、记忆
        │   ├── server-mcp.md       MCP 记忆服务器：持久化每用户记忆
        │   ├── auth-flow.md        直接 REST API 实现者的三 Token 流程
        │   ├── python-sdk.md       agora-agent Python SDK 模式
        │   ├── go-sdk.md           agora-agent-server-sdk-go 模式
        │   └── server-sdks.md      TypeScript/Node.js 服务端 SDK 模式
        ├── cloud-recording/        云端录制（REST API）
        │   └── README.md           acquire/start/query/stop 生命周期、存储配置
        ├── server-gateway/         服务器网关（Linux SDK）
        │   ├── README.md           概览、使用场景、关键说明
        │   └── linux-cpp.md        C++ SDK：设置、回调、媒体管线
        ├── server/                 服务端（Token）
        │   ├── README.md           Token 类型、使用场景
        │   └── tokens.md           Token 生成目录 + 官方文档链接
        └── testing-guidance/       测试模式
            └── SKILL.md            Mock 模式：Web、React、iOS、Android、RN、Flutter、RTM
```

## 维护与扩展

### 添加新产品

1. 创建 `references/{product}/README.md`（第 3 层）
2. 在 `SKILL.md` 的**产品**部分添加条目
3. 按需创建主题文件（第 4 层）

### 添加新平台

1. 创建 `references/{product}/{platform}.md`（第 4 层）
2. 在产品的 `README.md` 中添加链接

### 更新内容

- 编辑具体的第 4 层文件。
- **内联文件**（RTC、RTM、TEN）：保持代码示例最新，在底部保留**官方文档** URL。
- **链接优先文件**（ConvoAI、服务端）：当上游仓库重构时更新目录链接。仅将 LLM 容易出错且上游文档未明确说明的注意事项/怪异行为保留为内联内容。
- 不要重复上游仓库 README 或 AGENT.md 中已有的内容——改为链接。

### 验证 URL

```bash
grep -roh 'https://[^ )]*' skills/ | sort -u | while read url; do
  code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 10 "$url")
  echo "$code $url"
done
```

### Agora 发布说明

- 对话式 AI：https://docs.agora.io/en/conversational-ai/overview/release-notes
- Video SDK：https://docs.agora.io/en/video-calling/overview/release-notes
- 信令（RTM）：https://docs.agora.io/en/signaling/overview/release-notes