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
|