dsh-agora 0.2.5 → 0.2.7

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

@@ -1,159 +0,0 @@
----
-name: agora-cn-rtm
-description: |
-  China-mainland (国内/声网) delta for Agora Signaling (RTM, 云信令): CN area
-  code / region selection on Web (AgoraRTM.setArea) and native (RtmAreaCode.CN /
-  AgoraRtmAreaCode.CN), the CN data-center concept vs the CLI
-  `--rtm-data-center CN` control-plane flag, and the CN endpoint domain
-  (sd-rtn.com). Use for 国内 RTM / 云信令, RTM data center CN, RTM setArea
-  CHINA, RtmAreaCode.CN questions.
-license: MIT
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# 国内 RTM（云信令 / Signaling）差异：区域 / 数据中心
-
-> 本页只记录国内（大陆 / 声网 / CN 区域）与海外 RTM 的差异。
-> 基础机制（login / subscribe / publish / presence / storage / lock / stream channel）仍以
-> `agora` skill 的 `references/rtm/*` 为准。海外基线里**完全没有** region/area/domain 内容，本页补齐。
-
-验证基线：Web SDK `agora-rtm` 2.3.0（npm 包 `agora-rtm.d.ts` 实测，latest=2.3.0）；原生 SDK 2.x
-声网文档（`doc.shengwang.cn` api-ref + `docs.agora.io` signaling 文档）。
-
----
-
-## 已确认的国内 delta
-
-### 1. Web SDK（`agora-rtm` v2）选择 CN 区域
-
-**API 是顶层 `AgoraRTM.setArea`，值是大写字符串 `"CHINA"`，不是 `"CN"`。**（与 RTC 的
-`AgoraRTC.setArea({ areaCode: "CHINA" })` 形状不同：RTM 用的是**复数数组** `areaCodes`。）
-
-```js
-import AgoraRTM from "agora-rtm";
-
-// 只连国内服务器（中国大陆）
-AgoraRTM.setArea({ areaCodes: ["CHINA"] });
-
-// 或：全球里排除中国大陆（海外场景）
-AgoraRTM.setArea({ areaCodes: ["GLOBAL"], excludedArea: "CHINA" });
-
-// 之后才创建实例
-const rtm = new AgoraRTM.RTM(appId, userId, { logLevel: "info" });
-```
-
-- TS 签名（2.3.0）：`setArea(options: { areaCodes: AreaCode[]; excludedArea?: AreaCode }): void`。
-- 枚举 `AreaCode`（v2 字符串值）：`GLOBAL`（默认）/ `CHINA`（中国大陆）/ `INDIA` / `JAPAN` /
-  `ASIA`（除大陆外亚洲）/ `EUROPE` / `NORTH_AMERICA`。
-- ⚠️ **不是** `new RTM(appId, uid, { areaCode: ... })`：v2 的 `RTMConfig`（构造器第三参）里**没有**
-  `areaCode` 字段（只有 `encryptionMode/salt/cipherKey/presenceTimeout/logUpload/cloudProxy/
-  useStringUserId/logLevel/heartbeatInterval/privateConfig`）。
-- ⚠️ 包内还保留了 legacy v1 的 `LegacyAreaCode` 枚举（`CN = "CN"`, `GLOB = "GLOB"`, `NA`, `EU`,
-  `AS`, `JP`, `IN`, `OC`, `SA`, `AF`, `KR`, `US`, `OVS`）——那是 v1 兼容枚举，**v2 请用
-  `AreaCode.CHINA = "CHINA"`**，不要照搬 v1 的 `"CN"`。
-
-来源：
-- `https://registry.npmjs.org/agora-rtm`（latest=2.3.0；`agora-rtm.d.ts` 的 `AreaCode` / `LegacyAreaCode` / `setArea` / `RTMConfig`）
-- `https://docs.agora.io/en/signaling/get-started/client-configuration?platform=web`（"Geographical area configuration" 示例 `setArea({ areaCodes: ["GLOBAL"], excludedArea: "CHINA" })`）
-
-### 2. Android SDK（`io.agora:agora-rtm` v2）选择 CN 区域
-
-**字段是 `RtmConfig.Builder(...).areaCode(...)`，类型 `EnumSet<RtmAreaCode>`，CN 常量是 `RtmAreaCode.CN`。**
-
-```kotlin
-import io.agora.rtm.RtmConfig
-import io.agora.rtm.RtmConstants
-
-val rtmConfig = RtmConfig.Builder("your-app-id", "user-id")
-    .areaCode(EnumSet.of(RtmConstants.RtmAreaCode.CN))   // 中国大陆
-    .eventListener(rtmEventListener)
-    .build()
-val rtmClient = RtmClient.create(rtmConfig)
-```
-
-- 枚举 `RtmAreaCode`（位掩码）：`CN` = `0x00000001`（中国大陆）、`NA` = `0x00000002`、`EU` =
-  `0x00000004`、`AS` = `0x00000008`（除大陆外亚洲）、`JP` = `0x00000010`、`IN` = `0x00000020`、
-  `GLOB` = `0xFFFFFFFF`（默认，全球）。
-- 默认值 `GLOB`；不设 `areaCode` 即全球，不限定大陆。
-
-来源：
-- `https://docs.agora.io/en/signaling/get-started/client-configuration?platform=android`（`.areaCode(EnumSet.of(RtmConstants.RtmAreaCode.AS, RtmConstants.RtmAreaCode.CN))`）
-- `https://doc.shengwang.cn/api-ref/rtm2/android/enumv`（`RtmAreaCode.CN` = `0x00000001` 中国大陆）
-
-### 3. iOS SDK（`AgoraRtmKit` / `AgoraRtmClientKit` v2）选择 CN 区域
-
-**字段是 `AgoraRtmClientConfig.areaCode`，类型 `AgoraRtmAreaCode`（OptionSet），CN 是 `.CN`。**
-
-```swift
-import AgoraRtmKit
-
-let config = AgoraRtmClientConfig(appId: "yourAppId", userId: "yourUserId")
-config.areaCode = [.CN]        // 中国大陆（可组合多区域，如 [.CN, .NA]）
-let rtmClient = try AgoraRtmClientKit(config, delegate: nil)
-```
-
-- 枚举 `AgoraRtmAreaCode`（位掩码）：`CN` = `0x00000001`（中国大陆）、`NA` = `0x00000002`、`EU` =
-  `0x00000004`、`AS` = `0x00000008`、`JP` = `0x00000010`、`IN` = `0x00000020`、`GLOB` =
-  `0xFFFFFFFF`（默认，全球）。
-- Objective-C 写法：`rtm_config.areaCode = AgoraRtmAreaCodeCN;`（`@property (nonatomic, assign) AgoraRtmAreaCode areaCode;`，默认 `AgoraRtmAreaCodeGLOB`）。
-
-来源：
-- `https://doc.shengwang.cn/api-ref/rtm2/swift/toc-configuration/configuration`（`config.areaCode = [.CN, .NA]` 示例）
-- `https://doc.shengwang.cn/api-ref/rtm2/ios/enumv`（`AgoraRtmAreaCodeCN` = `0x00000001` 中国大陆）
-- `https://doc.shengwang.cn/api-ref/rtm2/ios/toc-configuration/configuration`（`areaCode` 属性声明）
-
-### 4. RTM 数据中心：控制面 vs 数据面（与 CLI `--rtm-data-center CN` 的关系）
-
-国内 RTM 涉及**两层独立配置**，二者互补、不可互相替代：
-
-| 层 | 入口 | 作用 | CN 取值 |
-|---|---|---|---|
-| **控制面**（项目/凭据落在哪个区域后端） | CLI `agora project create ... --rtm-data-center CN` / `agora init --rtm-data-center CN` | 决定项目在哪个区域后台开通、去哪个控制台拿 App ID | `CN`（另 `NA`/`EU`/`AP`，默认 `NA`） |
-| **数据面**（SDK 运行时连哪个 SDRTN 边缘区域） | 客户端 area code（§1–§3 的 `setArea` / `areaCode`） | 决定 SDK 连到哪个区域的 RTM 服务边缘节点 | Web `"CHINA"`；Android `RtmAreaCode.CN`；iOS `.CN` |
-
-- CLI 的 `--rtm-data-center CN` **不会**替客户端设置 area code，反之亦然：国内部署要**两者都设**
-  （CN 项目拿 App ID + 客户端 areaCode = CN）。
-- ⚠️ 取值集不对齐：CLI 是 `CN|NA|EU|AP`，SDK area code 是更细的位掩码
-  （`CN/NA/EU/AS/JP/IN/GLOB`），没有字面一一对应（CLI 的 `AP` 无同名 SDK 码）。这是"控制面 vs 数据面"
-  两个维度，不是同一枚举的两套别名。
-
-来源：CLI 行为以 `agora` CLI 实测为准（`agora init --rtm-data-center CN` / `project create`）；SDK
-area code 见 §1–§3 来源。
-
-### 5. CN 域名 / 端点（RTM Web 消息频道）
-
-- 国内主域名后缀 **`sd-rtn.com`**（海外 `agora.io`）。
-- Signaling SDK（Web）消息频道防火墙白名单里同时列了两套，其中 **国内（`sd-rtn.com`）部分**：
-  `.edge.sd-rtn.com`、`web-1.ap.sd-rtn.com` … `web-4.ap.sd-rtn.com`、`rtm.statscollector.sd-rtn.com`、
-  `rtm.logservice.sd-rtn.com`；**海外（`agora.io`）部分**：`.edge.agora.io`、`ap-web-1.agora.io` …
-  `ap-web-4.agora.io`、`webcollector-rtm.agora.io`、`logservice-rtm.agora.io`。
-- 端口（消息频道）：`443; 9591; 9593; 27387`（TCP）；v1.x 另加 `9601`。
-
-来源：
-- `https://docs.agora.io/en/signaling/reference/firewall`（"Signaling SDK (Web) → Message channel → Domains"）
-
----
-
-## 与海外一致（无 delta）
-
-- **凭据模型**：App ID + App Certificate + token 完全不变。国内只是去 `console.shengwang.cn`
-  建项目拿 App ID/证书，token 生成方式（App ID + App Certificate → token）与海外一致。
-- **RTM API 面**：`login` / `subscribe` / `publish` / presence（`getOnlineUsers`/事件）/ storage /
-  lock / stream channel（topic）全部同海外；RTM UID 仍是字符串、RTC↔RTM 命名空间隔离等规则不变。
-- **客户端形态**：RTM 仍是纯客户端 SDK（无服务端 SDK / 无 Electron/桌面版），CN 下不变。
-- **areaCode 是可选的**：不设默认 `GLOB`（全球），行为与海外完全一致；只有需要限定/合规时才设 CN。
-
----
-
-## 待验证 / 未知
-
-- **原生（Android/iOS）RTM 的精确 CN 接入点域名**：海外防火墙文档"Signaling SDK (Native)"小节只列了
-  `.agora.io`（未列出 `.sd-rtn.com` 原生宿主名）。已确认的是后缀 `sd-rtn.com` + Web 端列出的
-  `rtm.*.sd-rtn.com` 系列；原生设 `RtmAreaCode.CN` / `.CN` 后连接的确切信令 host 未在公开白名单页
-  单独枚举，落地如需精确域名按 `doc.shengwang.cn` 现查。
-- **`--rtm-data-center CN` 与 SDK area code 的字面等价**：官方文档没有一句"CLI CN == 客户端 areaCode CN"
-  的直接表述；本页按"控制面 vs 数据面"两层表述（§4），但若需要权威原文确认二者的绑定关系，属待验证。
-- **v1（legacy）SDK 的国内配置**：v2 包里保留的 `LegacyAreaCode.CN = "CN"` 是 v1 兼容枚举；独立 v1
-  包（`agora-rtm-sdk`）的国内 area code 具体 API/取值未在本任务核实。

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

@@ -1,77 +0,0 @@
----
-name: agora-cn-server
-description: |
-  China-mainland (国内/声网) server-side token/auth delta: token algorithm is
-  region-agnostic, CN REST domain (api.sd-rtn.com), CN console RESTful API
-  credential location, and the CN Docker token image. Use for 国内 token,
-  声网 token server, api.sd-rtn.com, RESTful API 凭证.
-license: MIT
-metadata:
-  author: agora
-  version: '0.1.0'
----
-
-# 国内 Server：token / 鉴权
-
-验证基线：官方文档（声网 `doc.shengwang.cn` 与海外 `docs.agora.io` 对照）。
-
-## 已确认的国内 delta
-
-### 1. 服务端 REST 域名（直接调服务端 API 时）
-
-CN 主域名 `sd-rtn.com`，但**不是所有服务端产品都换域名**：
-
-| 服务端产品 | CN 域名 | 海外域名 |
-|---|---|---|
-| 云端录制 REST | `https://api.sd-rtn.com` | `https://api.sd-rtn.com`（canonical 已统一；`api.agora.io` 仅残留于 quickstart 示例） |
-| RTC 服务端 RESTful（频道管理/踢人规则等） | `https://api.sd-rtn.com` | `https://api.agora.io` |
-
-> 云端录制 base URL 已在海外/国内两套文档里统一为 `api.sd-rtn.com`、且无 `/cn/` 前缀；
-> 其真正的国内差异是「控制台换成声网 + `clientRequest.region="CN"`」，详见 [cloud-recording.md](cloud-recording.md)。
-
-### 2. Basic Auth 的客户 ID / 密钥获取位置不同
-
-鉴权 Header 完全一致：`Authorization: Basic base64(customerID:customerSecret)`。
-但**菜单路径不同**：
-
-- **CN（声网）**：`console.shengwang.cn` → 设置 (Settings) → **RESTful API** → 添加密钥。
-- **海外**：`console.agora.io` → **Developer Toolkit** → RESTful API → Add a secret。
-
-（即：CN 走"设置 → RESTful API"，海外走"Developer Toolkit → RESTful API"。）
-
-### 3. CN 专属 token 服务器 Docker 镜像
-
-声网文档给的 Docker 部署镜像名是 `agoracn/token:0.1.2023053011`（`agoracn` 命名空间）。
-部署层面小贴士：可用 `goproxy.cn` 加速 `go get`。
-
-## 与海外一致（无 delta）
-
-### Token 算法 / 输入完全一致，无 region 参数（确认）
-
-- 同一开源仓库 `AgoraIO/Tools` 的 `DynamicKey/AgoraDynamicKey`，算法 HMAC-SHA256（AccessToken2）。
-- 同一函数签名、同样输入（App ID + App Certificate + channel + UID/account + role + 过期时间），**无 region 参数**：
-  - RTC：`BuildTokenWithUid(...)` / `RtcTokenBuilder.buildTokenWithUid(...)` / `buildTokenWithRtm(...)` / `buildTokenWithUserAccount(...)`
-  - RTM：`RtmTokenBuilder2.BuildToken(appId, appCertificate, userId, expire)`
-- **结论**：token builder 是 region-agnostic 的；region 内嵌于 App ID / App Certificate（CN 项目与海外项目是两套不同的 App ID + 证书）。因此**同一个 `agora-token` / `buildTokenWithRtm` 直接用于 CN 项目**，无需 CN 变体或额外参数。
-
-### 无 CN 版 token 库 / npm 包
-
-CN 文档指向的仍是同一个 `AgoraDynamicKey` 仓库；`agora-token`（npm）全球同一包，CN 直接复用。
-唯一的 CN 专属产物是上述 Docker 镜像 `agoracn/token`（部署层，非库/算法层）。
-
-### 其余一致
-
-- token 约束：24h 最长有效期、过期前 30s `token-privilege-will-expire`、UID 范围 1..(2³²-1)——CN 与海外相同。
-
-## 待验证 / 未知
-
-1. 云端录制 base URL 已在两套文档统一为 `api.sd-rtn.com`（已确认）；但 RTC 服务端 RESTful 是否也在向 `api.sd-rtn.com` 统一、迁移期 `api.agora.io` 是否仍可用——未钉死。
-2. `agoracn/token` 是否有海外等价镜像 `agoraio/token`（未在海外文档找到，未确认）。
-
-## 来源
-
-- 声网 token 生成：https://doc.shengwang.cn/doc/rtc/javascript/basic-features/token-authentication
-- 声网 RTM token：https://doc.shengwang.cn/doc/rtm2/javascript/user-guide/token/token-generation
-- 声网云录制 REST 快速开始：https://doc.shengwang.cn/doc/cloud-recording/restful/get-started/quick-start
-- 声网 RTC 服务端 REST：https://doc.shengwang.cn/doc/rtc/restful/get-started/call-api
-- 海外对照：https://docs-md.agora.io/en/video-calling/token-authentication/deploy-token-server.md