193 lines
10 KiB
Markdown
193 lines
10 KiB
Markdown
# 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 |