dsh-agora 0.2.5 → 0.2.7

package/index.js

@@ -1,76 +1,49 @@
-// dsh-agora — bundled skill providers for DeepSeek Harness.
+// dsh-agora — bundled skill provider for DeepSeek Harness.
 //
-// Registers two skills on ctx.skills, mirroring the official
-// `@deepseek-ai/dsh-skill-badge` provider pattern:
-//   - `agora`    — the official Agora skill, synced verbatim from
-//                  AgoraIO/skills at a pinned release tag (zero rewrite).
-//                  The SKILL.md body and references/ live in assets/agora/.
-//   - `agora-cn` — a shell-maintained companion documenting only the
-//                  China-mainland (国内/声网) delta. It lives in
-//                  assets/agora-cn/, which scripts/sync-deps.sh never touches.
+// Registers a single `agora` skill on ctx.skills, mirroring the official
+// `@deepseek-ai/dsh-skill-badge` provider pattern: a Cordis plugin whose
+// apply() registers one immutable provider. The SKILL.md body and references/
+// live in assets/agora/.
+//
+// assets/agora/ is produced by scripts/sync-deps.sh at prepack time:
+//   1. rsync the official AgoraIO/skills content verbatim (zero rewrite), then
+//   2. append our China-mainland (国内/声网) deltas (assets/agora-cn/*.md)
+//      into the corresponding product READMEs.
+// So one `agora` skill covers both global and CN regions.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { BUNDLED_SKILL_RANK } from '@deepseek-ai/dsh-skill'
 
 const PROVIDER_NAME = 'agora'
-
-const AGORA_DIR_URL = new URL('./assets/agora/', import.meta.url)
-const AGORA_BODY_URL = new URL('./assets/agora/SKILL.md', import.meta.url)
-
-const CN_DIR_URL = new URL('./assets/agora-cn/', import.meta.url)
-const CN_BODY_URL = new URL('./assets/agora-cn/SKILL.md', import.meta.url)
+const SKILL_DIR_URL = new URL('./assets/agora/', import.meta.url)
+const SKILL_BODY_URL = new URL('./assets/agora/SKILL.md', import.meta.url)
+const RESOURCE_BASE = {
+  kind: 'directory',
+  path: fileURLToPath(SKILL_DIR_URL),
+}
 
 const CANDIDATE = {
   name: 'agora',
   description:
-    'Activate when the user wants to build voice AI agents, video or voice calls, live streaming, screen sharing, in-app messaging and presence, recording, token or auth flows, or use the `agora` CLI for login, quickstarts, env setup, diagnostics, introspection, skills, or MCP serving, especially when integrating Agora into an app. For China-mainland (国内/声网) deployment, load the `agora-cn` skill instead.',
-  invocation: {
-    modelInvocable: true,
-    userInvocable: true,
-  },
-  provider: PROVIDER_NAME,
-  source: 'bundled',
-  resourceBase: {
-    kind: 'directory',
-    path: fileURLToPath(AGORA_DIR_URL),
-  },
-  rank: BUNDLED_SKILL_RANK,
-  locator: AGORA_BODY_URL,
-}
-
-const CN_CANDIDATE = {
-  name: 'agora-cn',
-  description:
-    'Activate for China-mainland (国内/声网) Agora deployment: console.shengwang.cn control plane, CN endpoints on the sd-rtn.com domain, `agora login --region cn` + CN data center, ConvoAI (Area.CN → api-cn-*.sd-rtn.com/cn + CN vendor/BYOK), and CN region selection for RTC (setArea CHINA / AREA_CODE_CN), RTM (setArea areaCodes / RtmAreaCode.CN), and Cloud Recording (clientRequest.region). Use when the user wants domestic deployment, 声网, China region (CN), or mainland data residency. Supplements the `agora` skill.',
-  whenToUse:
-    'Use when the user wants China-mainland (国内/声网) or CN-region deployment. Load the `agora` skill alongside it for the baseline mechanics.',
+    'Activate when the user wants to build voice AI agents, video or voice calls, live streaming, screen sharing, in-app messaging and presence, recording, token or auth flows, or use the `agora` CLI for login, quickstarts, env setup, diagnostics, introspection, skills, or MCP serving, especially when integrating Agora into an app. Covers both global (console.agora.io) and China-mainland (国内/声网, console.shengwang.cn) deployments.',
   invocation: {
     modelInvocable: true,
     userInvocable: true,
   },
   provider: PROVIDER_NAME,
   source: 'bundled',
-  resourceBase: {
-    kind: 'directory',
-    path: fileURLToPath(CN_DIR_URL),
-  },
+  resourceBase: RESOURCE_BASE,
   rank: BUNDLED_SKILL_RANK,
-  locator: CN_BODY_URL,
-}
-
-const BODY_BY_NAME = {
-  agora: AGORA_BODY_URL,
-  'agora-cn': CN_BODY_URL,
+  locator: SKILL_BODY_URL,
 }
 
 const provider = {
   name: PROVIDER_NAME,
-  list: () => Promise.resolve([CANDIDATE, CN_CANDIDATE]),
-  async get(candidate) {
-    const bodyUrl = BODY_BY_NAME[candidate.name]
+  list: () => Promise.resolve([CANDIDATE]),
+  async get(_candidate) {
     return {
-      ...candidate,
-      content: bodyUrl ? await readFile(bodyUrl, 'utf8') : '',
+      ...CANDIDATE,
+      content: await readFile(SKILL_BODY_URL, 'utf8'),
     }
   },
 }
@@ -79,7 +52,7 @@ const provider = {
 export const name = 'agora-skills'
 /** Service required by the bundled provider. */
 export const inject = ['skills']
-/** Register the bundled `agora` providers on `ctx.skills`. */
+/** Register the bundled `agora` provider on `ctx.skills`. */
 export function apply(ctx) {
   ctx.skills.registerProvider(() => provider)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agora",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "DSH skill bundle: the Agora skill (RTC, RTM, ConvoAI, CLI, Cloud Recording, tokens) synced verbatim from AgoraIO/skills at a pinned release tag. Install to add the `agora` skill to DeepSeek Harness.",
   "type": "module",
   "main": "index.js",
@@ -12,8 +12,7 @@
   "files": [
     "index.js",
     "cordis.patch.yml",
-    "assets/agora",
-    "assets/agora-cn"
+    "assets/agora"
   ],
   "license": "MIT",
   "repository": {

package/assets/agora-cn/SKILL.md

@@ -1,58 +0,0 @@
----
-name: agora-cn
-description: >-
-  Activate for China-mainland (国内/声网) Agora deployment: console.shengwang.cn
-  control plane, CN endpoints on the sd-rtn.com domain, `agora login --region
-  cn` + CN data center, ConvoAI (Area.CN → api-cn-*.sd-rtn.com/cn + CN vendor/
-  BYOK), and CN region selection for RTC (setArea CHINA / AREA_CODE_CN), RTM
-  (setArea areaCodes / RtmAreaCode.CN), and Cloud Recording (clientRequest.
-  region). Use when the user wants domestic deployment, 声网, China region (CN),
-  or mainland data residency. Supplements the `agora` skill.
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# Agora 国内区域（声网 / CN Region）
-
-> 本 skill 是 `agora` 的**国内补充**：只覆盖"大陆 / 声网 / CN 区域"与海外版的差异。
-> 基础机制（quickstart、token flow、生命周期）仍以 `agora` skill 为准。
-> 验证基线：CLI `0.2.8`（本机 `introspect --json` 实测）+ 声网/海外官方文档对照（各产品 SDK 版本见各 reference）。
-
-## 何时用本 skill
-
-用户目标是**国内/大陆部署**、`声网`、`console.shengwang.cn`、`CN 区域`、或国内数据合规时使用。
-否则仍走 `agora`。
-
-## 国内 vs 海外：四件套差异
-
-1. **账号**：国内控制台是 `console.shengwang.cn`（声网），且需在控制台**开通对应服务**（海外没有这个独立步骤）。
-2. **CLI**：`agora login --region cn`；`agora init --rtm-data-center CN`。
-3. **端点**：各产品 CN 端点以 `sd-rtn.com` 为主域名（详见各产品 reference）。
-4. **vendor**：ConvoAI 需换 CN vendor 目录，并按 managed/BYOK 矩阵填 key（详见 `conversational-ai.md`）。
-
-## Routing（按产品，与 `agora` 同构）
-
-| 产品 | 国内 delta | 读这里 |
-|---|---|---|
-| **RTC** | area code / CN 域名 / 云代理 | [references/rtc.md](references/rtc.md) ✅ |
-| **RTM** | region / 数据中心 | [references/rtm.md](references/rtm.md) ✅ |
-| **Cloud Recording** | CN 端点 / `clientRequest.region` / 存储 | [references/cloud-recording.md](references/cloud-recording.md) ✅ |
-| **Server（token）** | token 不变 / CN 域名 / 菜单路径 | [references/server.md](references/server.md) ✅ |
-| **CLI** | 国内命令 / 版本要求 | [references/cli.md](references/cli.md) ✅ |
-| **ConvoAI** | 端点 + CN vendor + managed/BYOK | [references/conversational-ai.md](references/conversational-ai.md) 📋 现状已记录（端到端待验证） |
-
-## 状态标注（诚实边界）
-
-| 状态 | 内容 |
-|---|---|
-| ✅ 已确认（源码/文档级） | RTC/RTM/Cloud Recording/Server/CLI 国内 delta 已填实（各文件内仍有"待验证"小节） |
-| 📋 ConvoAI 现状 | 端点 + CN vendor + managed/BYOK 已源码确认；但**免-key 直接启动体验未端到端验证**，不承诺与海外一致 |
-| ⚠️ 待运行时验证 | 原生 RTC/RTM 精确信令 host、`clientRequest.region` 是否需显式传、迁移期 `api.agora.io` 可用性、ConvoAI 免-key 组合等（见各文件"待验证"） |
-
-## Guardrails
-
-1. **本 skill 只补差异**；quickstart 克隆 / 生命周期 / token / baseline-first 约束沿用 `agora` skill。
-2. **区域取值别混用**：Web SDK 用 `"CHINA"`、原生 SDK 用 `CN`（RTC/RTM 一致）；RTM Web 是复数 `areaCodes`、RTC Web 是单数 `areaCode`。
-3. **ConvoAI 别断言"改一行 `Area` 就国内跑通"**：`Area.CN` 只解决端点路由，vendor 仍需换 CN 类并处理 key；国内免-key 体验未验证。
-4. 未在本 skill 标注为"已确认"的能力，不要凭记忆承诺；必要时回落到声网官方文档（`doc.shengwang.cn`）现查。

package/assets/agora-cn/references/cli.md

@@ -1,41 +0,0 @@
----
-name: agora-cn-cli
-description: |
-  China-mainland Agora CLI commands: login/console region, CN RTM data center,
-  webhook delivery region, and the version requirement for CN flags. Use for
-  国内 CLI, agora login --region cn, or --rtm-data-center CN.
-license: MIT
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# 国内 CLI 命令与版本
-
-验证基线：CLI `0.2.8`（`agora introspect --json` 实测）。
-
-> 注意版本漂移：`agora` skill 内容基线是 CLI `0.2.1`，其中 `agora project create --region global|cn`
-> 在 `0.2.8` 已**不存在**——国内 flag 已经搬家到 login / data-center。
-
-## 国内命令面（0.2.8 实测）
-
-- 登录国内控制台：`agora login --region cn`（等价 `agora auth login --region cn`；默认 `global`）
-- RTM 数据中心：`agora project create ... --rtm-data-center CN`（可选 `CN|NA|EU|AP`，默认 `NA`）
-- 一键脚手架：`agora init <name> --template <t> --rtm-data-center CN`
-- Webhook 投递区域：`agora project webhook create ... --delivery-region cn`（可选 `cn|sea|na|eu`）
-
-## 版本要求
-
-- CN 入口（`login --region cn`、`--rtm-data-center CN`）比 `agora` skill 的验证基线 `0.2.1` 新。
-- **确切引入版本待钉**：本机 `0.2.8` 已实测具备这两个 flag；低于该版本的 CLI 没有它们。
-- 落地建议：国内路径要求 CLI 至少为实测具备 CN flag 的版本（当前以 `0.2.8` 为参照下界）。
-
-## 端点相关环境变量（`agora env-help --json` 实测）
-
-- `AGORA_CONSOLE_URL` — 覆盖 `agora open --target console` 的 URL
-- `AGORA_API_BASE_URL`（默认 `https://agora-cli.agora.io`）
-- `AGORA_OAUTH_BASE_URL`（默认 `https://sso2.agora.io`）
-
-## 待验证
-
-- `agora login --region cn` 的 OAuth 流程端到端（需声网账号实测）。

package/assets/agora-cn/references/cloud-recording.md

@@ -1,59 +0,0 @@
----
-name: agora-cn-cloud-recording
-description: |
-  China-mainland (国内/声网) Cloud Recording delta: 声网 console + enable-service,
-  the (now-unified) api.sd-rtn.com base URL, clientRequest.region="CN", and CN
-  storage regions. Use for 国内录制, cloud recording CN, clientRequest.region, 录制存储.
-license: MIT
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# 国内 Cloud Recording：控制台 / 端点 / 存储
-
-验证基线：声网 `doc.shengwang.cn` 与海外 `docs.agora.io` 对照。
-
-## 已确认的国内 delta
-
-### 1. 控制台 / 账号 / 开通
-
-- 国内控制台 `console.shengwang.cn`（声网）。App ID / App 证书 / 客户 ID·密钥 / 开通服务都在声网控制台完成。
-- 需先**开通云端录制服务**（项目类型选**通用项目**）。
-
-### 2. 端点：`api.sd-rtn.com`（关键修正：云端录制已基本统一，非 CN 独有）
-
-- 国内 quick-start 全程 `https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/...`（acquire/start/stop 一致）。
-- **海外 canonical 参考也写 base URL `https://api.sd-rtn.com`**——即云端录制当前 base URL 在两套文档里**已统一为 `api.sd-rtn.com`**。
-  `api.agora.io` 只残留在海外 quickstart/认证示例里，属陈旧内容。
-- 路径与海外**完全一致，且无 `/cn/` 前缀**。
-
-### 3. CN 区域绑定：`clientRequest.region = "CN"`
-
-- acquire 请求体有 `clientRequest.region`（string）：`"CN"`（中国大陆）/ `"AP"` / `"EU"` / `"NA"`。
-- 默认「使用发起请求所在服务器的区域」；一旦显式设置，服务不访问该区域之外。
-- **约束**：`start` 时第三方云存储的 `region` 必须与之匹配。
-
-## 与海外一致（无 delta）
-
-- **操作路径**：acquire / start / query / update / updateLayout / stop 六个操作 path 完全一致。
-- **存储 vendor 枚举**：`1`=Amazon S3、`2`=阿里云 OSS、`3`=腾讯云 COS、`5`=Azure、`6`=GCP、`7`=华为云 OBS、`8`=百度云 BOS、`11`=其他 S3（需 `extensionParams.endpoint`）；无 vendor 4。
-- **存储 region（大陆可用，两边都有）**：阿里云 `CN_*`（杭州/上海/北京/广州/成都…）、腾讯云 `AP_Beijing/AP_Shanghai/AP_Guangzhou/…`、AWS `CN_NORTH_1`/`CN_NORTHWEST_1`、华为云 `CN_*`、百度云（保定/苏州/广州）。
-- **鉴权机制**：HTTP Basic Auth `Authorization: Basic base64(CustomerID:CustomerSecret)` 完全一致；仅 Customer ID/Secret 的生成控制台不同（声网：设置 → RESTful API）。
-- **录制模式/特性**：`individual`/`mix`/`web`、`streamMode`、`transcodingConfig`、订阅黑白名单、NCS webhook、云端截图、格式转换——均一致。
-- **storageConfig 字段集**：bucket/accessKey/secretKey/fileNamePrefix + `stsToken`/`stsExpiration`（S3/Aliyun/Tencent）一致。
-
-## 待验证 / 未知
-
-1. `clientRequest.region` 字段在**声网（CN）文档**里是否逐字一致未直接取到（CN operation 页 doc-mcp 返回"获取文档内容失败"；字段已从海外 canonical acquire 参考确认，但 CN 侧逐字出处缺失）。
-2. 阿里云 region 编号 26/27 命名在 CN 与海外文档不一致（一方疑似笔误，未判定哪方正确）。
-3. 迁移期 `api.agora.io` 是否仍实际可用（海外 canonical 已统一为 `api.sd-rtn.com`）。
-4. 是否需要显式传 `clientRequest.region="CN"`（默认按发起服务器区域；声网账号默认是否已落 CN 未实测）。硬性大陆数据驻留时建议显式 `"CN"` 并匹配存储 region，但未经运行时验证。
-
-## 来源
-
-- 声网云端录制快速开始：https://doc.shengwang.cn/doc/cloud-recording/restful/get-started/quick-start
-- 声网开通服务：https://doc.shengwang.cn/doc/cloud-recording/restful/get-started/enable-service
-- 海外 canonical：https://docs.agora.io/en/realtime-media/cloud-recording/reference/restful-api.md
-- acquire `clientRequest.region`：https://docs.agora.io/en/api-reference/api-ref/cloud-recording/acquire.md
-- region/vendor 对照：https://docs.agora.io/en/realtime-media/cloud-recording/reference/region-vendor.md

package/assets/agora-cn/references/conversational-ai.md

@@ -1,110 +0,0 @@
----
-name: agora-cn-conversational-ai
-description: |
-  China-mainland (国内/声网) Conversational AI delta: console.shengwang.cn + service
-  enablement, CN REST endpoint routing (Area.CN), and the CN vendor catalog with its
-  managed-vs-BYOK credential matrix. Use for 国内 voice agent, 声网 ConvoAI, Area.CN,
-  or CN vendor/BYOK questions.
-license: MIT
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# 国内 ConvoAI：现状 + 端点 / vendor
-
-> **现状说明（先读）**：国内 ConvoAI 的**端点路由 + CN vendor 清单 + managed/BYOK 矩阵已从 SDK 源码确认**
-> （下面这些是可信事实）；但"像海外那样只填 App ID / App Certificate 就一键启动"的体验
-> **尚未端到端跑通**——国内 LLM/TTS 的免-key（托管）面更窄，且整条链路未经运行时验证。
-> 因此本文是**现状记录**，不是"照着就能跑通"的承诺；动手前按"待验证"清单实测。
-
-验证基线：SDK `agora-agents` 2.6.0（TypeScript 与 Python 一致）。
-
-## 账号与控制台
-
-- 国内控制台：`https://console.shengwang.cn`（声网）；ConvoAI 入口
-  `https://console.shengwang.cn/product/ConversationAI?tab=Playground`。
-- **开通服务（enable-service）**：国内需先在声网控制台开通 ConvoAI 服务（海外没有这个独立步骤）。
-- 海外控制台是 `console.agora.io`；两者账号/项目体系不同，国内用声网账号。
-
-## CN 端点（Area.CN）
-
-`Area` 枚举（`agora-agents` 2.6.0）：
-
-```text
-US = 1, EU = 2, AP = 3, CN = 4   # CN = "eastern and northern regions of Chinese mainland"
-```
-
-`Area.CN` 时 SDK 自动路由（DNS 解析选择）：
-
-- 区域前缀：`api-cn-east-1`、`api-cn-north-1`
-- 主域名：`sd-rtn.com`（回退 `agora.io`）
-- 路径：`/cn/api/conversational-ai-agent`（海外是 `/api/conversational-ai-agent`）
-
-即完整端点形如：
-
-```text
-https://api-cn-east-1.sd-rtn.com/cn/api/conversational-ai-agent/v2/projects/{appid}/join
-https://api-cn-north-1.sd-rtn.com/cn/api/conversational-ai-agent/v2/projects/{appid}/join
-```
-
-> 说明：声网文档示例里也出现过 `https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/...`
-> 这种写法（`api.agora.io` + `/cn/` 路径）。以 SDK 2.6.0 的实际运行时为准：设置 `Area.CN` 后
-> 走 `api-cn-*.sd-rtn.com` + `/cn/` 路径。
-
-## 区域绑定方式
-
-- 客户端：`AgoraClient({ area: Area.CN, ... })`（TS）/ `AsyncAgora(area=Area.CN, ...)`（Python）。
-- SDK 提供 CN 专属类：`CNAgora` / `CNAsyncAgora`（Python，预绑定 `Area.CN`）。
-- `Agent(client=...)` 在 `area_scope == "cn"` 时返回 `CNAgent`。
-
-## CN vendor 目录（`agentkit/vendors/cn.py`）
-
-`area_scope == "cn"` 时切换到 CN vendor 命名空间，可选厂商与海外不同：
-
-| 类别 | CN 可选厂商 |
-|---|---|
-| ASR | fengming, tencent, microsoft, xfyun, xfyun_bigmodel, xfyun_dialect |
-| TTS | minimax, tencent, bytedance, microsoft, cosyvoice, bytedance_duplex, stepfun, generic |
-| LLM | aliyun, bytedance, deepseek, tencent |
-| MLLM | qwen_omni |
-| Avatar | sensetime, spatius |
-
-## managed / BYOK 矩阵（源码级确认）
-
-概念：**managed（免 key）** = 不填 vendor key、Agora 托管（常见 vendor 的表达式是"省略 api_key"）；
-**BYOK** = 填 vendor 自己的 key（LLM 还需 base_url）。没有统一的顶层 `credential_mode` 开关——
-`credential_mode: "managed"|"byok"` 字面量**只存在于 `RimeTTS`** 单个 vendor。
-
-| 环节 | 免 key（managed） | 需 BYOK |
-|---|---|---|
-| ASR | `fengming`（风鸣，无 key 字段，纯托管） | `tencent`（key/app_id/secret 必填）、`microsoft`；`xfyun` 系列 api_key 等可选（BYOK 时填） |
-| LLM | 仅白名单 `gpt-4o-mini` / `gpt-4.1-mini` / `gpt-5-nano` / `gpt-5-mini`（托管） | `deepseek` / `aliyun` / `bytedance` / `tencent` 必须 api_key + base_url |
-| TTS | （见"待验证"） | CN `minimax` 通常要 key（官方说明 "not Agora-managed in the same way and typically includes key"）；`tencent` / `bytedance` / `cosyvoice` / `stepfun` |
-| MLLM | 无 | `qwen_omni`（api_key 必填） |
-| Avatar | 无 | `sensetime` / `spatius`（BYOK） |
-
-要点：
-
-- CN 原生 LLM（DeepSeek/阿里/字节/腾讯）**没有免 key 托管**——托管白名单仍是 OpenAI 的
-  `gpt-4o-mini` 等几个模型（`_OPENAI_MANAGED_MODELS`）。
-- SDK 默认 ASR：`area_scope == "cn"` 且未显式传 STT 时，默认 `fengming`（否则 `ares`）。
-
-## 已知组合（待验证，勿当作"可用配方"）
-
-以下组合基于上面的矩阵推导，**均未端到端跑通**：
-
-1. **免 key 最小组合（理论）**：ASR `fengming` + LLM `gpt-4o-mini`（托管白名单）+ TTS（⚠️ 是否有免 key 项未知）
-2. **国内原生组合（需 BYOK）**：ASR `fengming` + LLM `deepseek`（api_key + base_url）+ TTS `minimax`（key）
-
-## 不支持的边界
-
-- `properties.geofence.area` 可选值只有 `GLOBAL / NORTH_AMERICA / EUROPE / ASIA / INDIA / JAPAN`，
-  **没有 `CHINA`**。即无法用 `geofence` 强制 agent 引擎只在大陆运行（`ASIA` 是最近的一档，不等于大陆）。
-
-## 待验证 / 未知
-
-- 免 key 组合是否端到端跑通（尤其 TTS 环节）。
-- 国内是否存在一款完全托管的 TTS（源码里 CN MiniMax 的 `key` 为可选，但官方说明"通常要 key"）。
-- "只把 `Area.US` 改成 `Area.CN`、vendor 仍用海外类（Deepgram/OpenAI/MiniMax）"能否在 CN 端点跑通——未实测，不要默认可行。
-- ConvoAI 直接 REST 在 CN 的官方推荐 host：`api.agora.io/cn/...` 还是 `api-cn-*.sd-rtn.com/cn/...`（未实测）。

package/assets/agora-cn/references/rtc.md

@@ -1,180 +0,0 @@
----
-name: agora-cn-rtc
-description: |
-  China-mainland (国内/声网) delta for Agora RTC (video/voice calling, live
-  streaming, screen share, join/publish/subscribe): CN region selection
-  (Web setArea / native areaCode), CN signaling domain (sd-rtn.com), and the
-  cloud-proxy / firewall setup for mainland restricted networks. Use for 国内
-  RTC, 声网 RTC, AREA_CODE_CN, setArea CHINA, or 云代理 questions.
-license: MIT
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# 国内 RTC 差异（声网 / CN Region）
-
-> 本页只记录国内（大陆 / 声网 / CN 区域）与海外 RTC 的差异。
-> 基础机制（join / publish / subscribe / token / channel profile）仍以 `agora` skill 的
-> `references/rtc/*` 为准。海外基线里**完全没有** region/area/domain 内容，本页补齐。
-
-验证基线：Web SDK `agora-rtc-sdk-ng` 4.24.7（`rtc-sdk_en.d.ts` 实测）；原生 SDK 4.x 声网文档
-（`doc.shengwang.cn` + `docs-md.agora.io`）。
-
----
-
-## 已确认的国内 delta
-
-### 1. Web SDK（`agora-rtc-sdk-ng`）选择 CN 区域
-
-**正确 API 是 `AgoraRTC.setArea`，值是大写 `"CHINA"`，不是 `"CN"`。**
-
-```js
-// 只连国内服务器
-AgoraRTC.setArea({ areaCode: "CHINA" });
-
-// 或：全球里排除中国大陆
-AgoraRTC.setArea({ areaCode: "GLOBAL", excludedArea: "CHINA" });
-```
-
-- 枚举：`AREAS.CHINA = "CHINA"`（`ASIA / NORTH_AMERICA / EUROPE / JAPAN / INDIA / GLOBAL` 等并列）。
-- TS 签名（4.24.7）：`setArea(area: AREAS[] | { areaCode: AREAS[]; excludedArea?: AREAS })`，自 4.2.0 起。
-- ⚠️ **不是** `AgoraRTC.createClient({ areaCode: "CN" })`：4.x 的 `ClientConfig` 里没有 `areaCode` 字段
-  （`createClient` 只接受 `mode/codec/role/clientRoleOptions` 等）。
-- ⚠️ **没有**静态 `AgoraRTC.setCloudProxy`（这个猜测不存在于当前 Web SDK）。
-
-来源：
-- `https://cdn.jsdelivr.net/npm/agora-rtc-sdk-ng@4.24.7/rtc-sdk_en.d.ts`（`AREAS` 枚举 + `setArea` 签名 + `ClientConfig`）
-- `https://registry.npmjs.org/agora-rtc-sdk-ng`（latest = 4.24.7）
-- `https://doc.shengwang.cn/doc/rtc/javascript/advanced-features/region`
-
-### 2. Web SDK 云代理（受限网络）
-
-云代理是 **client 实例方法**，不是全局静态方法；需先向声网申请开通。
-
-```js
-const client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });
-
-client.startProxyServer(3);   // 3 = Force UDP 云代理；5 = Force TCP/TLS 443（v4.9.0+）
-await client.join(APP_ID, channel, token, null);
-// ...
-await client.leave();
-client.stopProxyServer();     // 离开频道后才能关闭
-```
-
-- `startProxyServer` 必须在 `join` **之前**调用；`stopProxyServer` 必须在 `leave` **之后**调用。
-- 开通前置：联系 `sales@shengwang.cn` 提供 App ID / 使用区域 / 并发规模 / 运营商（不是开箱即用）。
-- 判断媒体是否走代理：`client.on("is-using-cloud-proxy", (isUsingProxy) => ...)`。
-- 自建代理（私有化/混合部署，非云代理）：`client.setProxyServer(domain)`（ASCII 域名）+ `client.setTurnServer(config)`；
-  二者与 `startProxyServer` **不能混用**。
-
-来源：
-- `https://doc.shengwang.cn/doc/rtc/javascript/basic-features/firewall`
-- `https://cdn.jsdelivr.net/npm/agora-rtc-sdk-ng@4.24.7/rtc-sdk_en.d.ts`（`startProxyServer`/`stopProxyServer`/`setProxyServer`）
-
-### 3. 原生 SDK 区域码（Android / iOS / C++）
-
-**Android**（`RtcEngineConfig.mAreaCode`）：
-
-```java
-RtcEngineConfig config = new RtcEngineConfig();
-config.mAppId = appId;
-config.mContext = mContext;
-config.mAreaCode = AREA_CODE_CN;      // 中国大陆
-mRtcEngine = RtcEngine.create(config);
-```
-
-- 常量 `AREA_CODE_CN = 0x00000001`（`Constants.AreaCode`）。其余：`AREA_CODE_GLOB`（默认）/ `NA` / `EU` / `AS` / `JP` / `IN`。
-- 支持位运算：排除大陆用 `AREA_CODE_GLOB ^ AREA_CODE_CN`。
-
-**iOS**（`AgoraRtcEngineConfig.areaCode`）：
-
-```swift
-let config = AgoraRtcEngineConfig()
-config.appId = "YourAppId"
-config.areaCode = .CN            // AgoraAreaCodeTypeCN
-agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
-```
-
-- 枚举：`AgoraAreaCodeTypeGlobal`（默认）/ `AgoraAreaCodeTypeCN` / `...NA` / `...EUR` / `...AS` / `...JP` / `...IN`。
-
-**C++ / Windows**（`RtcEngineContext.areaCode`）：
-
-```cpp
-RtcEngineContext context;
-context.appId = appId;
-context.areaCode = AREA_CODE_CN;   // 中国大陆
-m_rtcEngine->initialize(context);
-```
-
-来源：
-- `https://doc.shengwang.cn/doc/rtc/android/advanced-features/region`
-- `https://doc.shengwang.cn/doc/rtc/ios/advanced-features/region`
-- `https://doc.shengwang.cn/doc/rtc/windows/advanced-features/region`
-- `https://doc.shengwang.cn/api-ref/rtc/android/API/class_areacode`（`AREA_CODE_CN = 0x00000001`）
-
-### 4. 原生 SDK 云代理（受限网络）
-
-原生在受限网络下**只支持云代理，不支持防火墙域名白名单**（见 §6 表格）。
-
-- Android/C++：`RtcEngine.setCloudProxy(proxyType)`
-  - `TRANSPORT_TYPE_NONE_PROXY`(0) 默认自动；`TRANSPORT_TYPE_UDP_PROXY`(1) Force UDP；`TRANSPORT_TYPE_TCP_PROXY`(2) Force TCP/TLS 443。
-- iOS：`setCloudProxy(_ proxyType: AgoraCloudProxyType)`
-  - `AgoraNoneProxy`(0) / `AgoraUdpProxy`(1) / `AgoraTcpProxy`(2)。
-- 需在频道外调用，`RtcEngine` 生命周期内有效；同样要先向 `sales@shengwang.cn` 申请开通并加白名单 IP。
-
-来源：
-- `https://doc.shengwang.cn/doc/rtc/android/basic-features/firewall`
-- `https://doc.shengwang.cn/api-ref/rtc/ios/API/enum_cloudproxytype`
-
-### 5. CN 域名后缀 / 信令域名
-
-- 国内主域名后缀 **`sd-rtn.com`**（海外 `agora.io`）。
-- Web SDK 防火墙白名单域名（国内部分）：
-  `*.sd-rtn.com`、`*.edge.sd-rtn.com`、`*.ap.sd-rtn.com`、`*.statscollector.sd-rtn.com`、`*.webrtc-cloud-proxy.sd-rtn.com`
-  （海外是 `*.agora.io` / `*.edge.agora.io`）。
-- REST API 主域名（服务端在大陆时）：`api.sd-rtn.com`（海外 `api.agora.io`）；CN 区域子域
-  `api-cn-east-1.sd-rtn.com` / `api-cn-north-1.sd-rtn.com`。
-
-来源：
-- `https://docs-md.agora.io/en/broadcast-streaming/reference/firewall_web.md`
-- `https://docs-md.agora.io/en/broadcast-streaming/channel-management-api/best-practices/ensure-service-reliability.md`
-
-### 6. 网络/防火墙策略差异（Web vs 原生）
-
-| 产品 | 防火墙域名白名单 | 声网云代理 |
-|---|---|---|
-| Video SDK（原生 / 三方框架） | ✘ 不支持 | ✔ |
-| Video SDK（Web） | ✔ | ✔ |
-
-- 即：**原生 RTC 在受限网络只能走云代理**（申请开通 + `setCloudProxy`）；只有 Web SDK 能走域名白名单。
-
-来源：
-- `https://docs-md.agora.io/en/broadcast-streaming/reference/firewall_android.md`
-
----
-
-## 与海外一致（无 delta）
-
-- **凭据模型**：App ID + App Certificate + token（`join` 传 token）这套完全不变；国内只是去
-  `console.shengwang.cn`（声网）建项目拿 App ID，拿到后 SDK 用法与海外一致。
-- **频道机制**：`joinChannel` / `createClient` / `publish` / `subscribe` / channel profile
-  (`rtc`/`live`) / client role (`host`/`audience`) 全部同海外。
-- **token 续期**：`token-privilege-will-expire`（Web）/ `onTokenPrivilegeWillExpire`（原生）+ `renewToken` 同海外。
-- **编解码/双流/屏幕共享**等能力面无 CN 差异；差异只在"连哪个区域/什么网络"。
-
----
-
-## 待验证 / 未知
-
-- **原生 RTC 信令的精确接入点域名**：设置 `AREA_CODE_CN` 后原生 SDK 连接的确切信令主机名
-  （是否字面就是 `api.sd-rtn.com`）没有公开的"白名单域名"页可查（原生不支持防火墙白名单，官方未列域名）。
-  已确认的是后缀 `sd-rtn.com` + REST 主域名 `api.sd-rtn.com`；原生媒体信令具体 host 记为待验证。
-- **私有媒体网关（本地接入点 / 混合部署）**：确认原生有 `AgoraLocalAccessPointConfiguration` +
-  `setLocalAccessPoint`、Web 有 `setProxyServer`，但这是单独的企业私有化/混合部署项目（需声网部署本地媒体网关），
-  未在本任务里核实其完整开通流程与字段，落地前需按 `doc.shengwang.cn` 现查。
-- **Web `setArea` 单字符串写法**：中文文档示例是 `AgoraRTC.setArea("ASIA")`（单字符串），
-  而 4.24.7 类型签名是 `AREAS[] | { areaCode, excludedArea }`；运行时是否仍兼容单字符串未实测，
-  建议统一用 `setArea({ areaCode: "CHINA" })`。
-- **云代理"国内测试 IP"清单会漂移**：中文防火墙文档列出的国内测试 IP（如 `150.138.153.78` 等）
-  仅供测试、正式上线要声网另发，且清单随版本更新，落地以申请后声网提供为准。