用途
Using Ably 是一个面向 AI 编码助手的技能（Skill），当你要构建、修改或生成使用 Ably 实现实时消息、聊天、协作或 AI 流式输出的应用代码时使用它。Ably 是实时基础设施，负责跨不可靠网络的连接管理、消息顺序与投递保证、自动重连与状态恢复，以及弹性扩展到海量设备，支持 25+ SDK 和 WebSocket、MQTT、SSE、HTTP 等协议。
写代码前的三项检查
- 先获取最新文档：训练数据会过时，方法可能改名、参数可能变化、新产品可能上线。先抓取 https://ably.com/llms.txt?source=using-ably 获取文档 URL 索引，再抓取相关产品与平台文档页，核对方法名、参数、返回类型和包版本。文档中没有的功能大概率不存在，不要编造。不要猜测或拼凑文档 URL，只用 llms.txt 或搜索结果中的 URL；若 URL 404 就回到 llms.txt。llms.txt 不可达时可退回搜索或直接浏览 https://ably.com/docs?source=using-ably。
- 确认 SDK 可用性：并非所有产品在所有平台都有 SDK。若没有，应明确说明“[产品] 目前没有 [平台] 的 SDK”，不要编造 API，可提供替代方案：直接使用 REST API、改用有 SDK 的产品，或对受限设备使用 MQTT/SSE 协议适配。
- 生成后检查常见错误：客户端代码里是否出现 API key（必须用 authUrl/authCallback 配合 JWT 或 token 认证）；Chat SDK 是否在订阅前就 attach()（应先订阅以免消息静默丢失）；React 中是否在组件内创建 Ably 客户端且未清理（应在外部创建一次并通过 provider 传入，或用 useEffect 正确清理）；服务端是否在 REST 足够时用了 Realtime SDK（发布、生成 token、查询历史默认用 Ably.Rest）；卸载/退出时是否调用 realtime.close()；是否重复实现了内置行为（不要为输入指示器加自定义防抖、为光标加自定义节流、为 LiveObjects 加自定义冲突解决）；AI Transport 是否启用了频道规则（命名空间需要 mutableMessages，否则流式会以错误 93002 失败）。
产品与 SDK 选型
Ably 是多产品平台，选错产品或 SDK 是最常见的集成错误。
产品层：Pub/Sub 用于核心消息（实时仪表盘、通知、IoT、事件流），SDK 为 ably（Realtime 或 REST）；AI Transport 用于流式 LLM token、多智能体协调、可恢复 AI 会话，SDK 为 @ably/ai-transport；LiveObjects 用于共享可变状态（计数器、键值映射、协作数据），SDK 为 ably + LiveObjects 插件；LiveSync 用于数据库到前端同步（PostgreSQL 变更流），SDK 为 @ably-labs/models + ADBC 连接器；Chat 用于聊天室、输入指示器、反应、消息历史、审核，SDK 为 @ably/chat；Spaces 用于协作光标、头像堆叠、成员位置、组件锁定，SDK 为 @ably/spaces。
SDK 架构分两层。第一层核心 SDK：Ably.Realtime 用于客户端需要订阅消息、presence 或状态变化（持久 WebSocket）；Ably.Rest 用于服务端仅发布、生成 token、查询历史（无状态 HTTP）。LiveObjects 和 LiveSync 构建在核心 Realtime SDK 之上。第二层产品 SDK：@ably/chat、@ably/spaces、@ably/ai-transport 依赖核心 Realtime SDK，创建时传入 Ably.Realtime 实例，底层认证、频道、presence 知识仍然适用。
决策规则：服务端发布、生成 token、历史用 Ably.Rest；服务端流式 AI 智能体输出用 @ably/ai-transport 的 agent session；服务端需要持久连接（订阅）用 Ably.Realtime。客户端用 Ably.Realtime，然后按需选择：聊天用 @ably/chat，协作用 @ably/spaces，消费 AI 输出用 @ably/ai-transport 客户端 session，共享状态用 LiveObjects 插件，同步数据库用 @ably-labs/models 配合 ADBC 连接器，否则直接用 Ably.Realtime。服务端经验法则：默认用 Ably.Rest，只有确实需要持久连接时才在服务端用 Ably.Realtime。
现代 SDK 模式（v2.x）
JavaScript SDK v2.x 使用 async/await，不要生成 1.x 回调风格。订阅用 channel.subscribe('event', (message) => {...})，发布用 await channel.publish('event', {...})。导入保持简单：import Ably from 'ably'; const realtime = new Ably.Realtime({ key: 'your-key' }); Chat SDK 用 import { ChatClient } from '@ably/chat'。不要发明基于类型的初始化。若遇到 ESM/CommonJS 导入错误，检查 tsconfig.json 的 moduleResolution 是否为 bundler 或 node16，并从 'ably' 导入（不要用子路径），不要尝试多种导入策略，查看对应环境的 SDK README。
AI Transport 需要频道规则：每个用于 AI Transport 的命名空间都需要 Message annotations、updates、deletes、appends 规则（mutableMessages: true），因为流式会把 token 追加到同一条消息，没有该规则追加会被拒绝并报错 93002。这是 AI Transport 最常见的失败，且只在首次追加时暴露，症状是助手消息为空或只有第一个 token。可在仪表盘启用，或运行 ably apps rules create "conversations" --mutable-messages。
认证
API key 仅限服务端，绝不能暴露给客户端；API key 不过期，泄露后攻击者可长期访问直到你重新生成。推荐客户端使用 JWT 认证：无需往返 Ably 服务器，后端直接签发；可集成现有认证系统；能力按 token 定义；在无 Ably SDK 的环境（MQTT、嵌入式设备）也可用。JWT 声明包括 kid（header，你的 Ably API key 名称）、iat、exp、x-ably-capability（频道权限的 JSON 字符串）、x-ably-clientId（可选，presence 身份）。客户端用 authUrl 或 authCallback，不要嵌入 API key 或直接传静态 token（过期不会自动刷新）。需要 presence 时设置 clientId。用 capabilities 限制每个客户端可访问的频道和操作。当能力列表超出 JWT 大小限制（JWT 需放入 HTTP 头，约 8KB）或需要保密能力时，可改用 Ably Token Requests，但集成更复杂且不支持全部 JWT 功能。
频道设计
频道把消息分到不同主题，命名要尽早确定。用 : 作为层级分隔符，如 chat:room-123、orders:user-456；频道名区分大小写；不要每条消息建一个频道，频道是长期存在的主题；用仪表盘规则对频道组应用设置（持久化、推送通知等）。常见模式：chat:room-{roomId}、notifications:user-{userId}、cursors:doc-{docId}、events:{eventType}、conversations:{sessionId}。规则和能力按第一个冒号前的命名空间字面匹配，所以 conversation（单数）不匹配 conversations:*，频道名、频道规则和 token 能力要用同一种拼写。
连接管理
Realtime SDK 自动管理重连，不要手动重连。监听连接状态变化更新 UI：connected、disconnected、suspended。完成时调用 realtime.close()。断线期间发布的消息会在重连后收到（2 分钟恢复窗口内）。原始 Pub/Sub 可用 channel rewind 在 attach 时给返回客户端最近消息，如 params: { rewind: '2m' }。AI Transport 不要用 rewind，客户端 session 会先订阅再读历史并通过 view.loadOlder() 向前翻页，历史与实时流无缝衔接且无重复。
Presence
Presence 跟踪频道上的客户端，用于“谁在线”。认证时设置 clientId（presence 必需）。用 channel.presence.enter() 加入、update() 更新数据、leave() 离开；get() 获取当前成员，subscribe() 订阅变化。客户端非正常断开后约 15 秒被移除（非即时）。不要用 presence 传高频数据（光标位置、输入坐标），应改用频道；presence 用于低频状态（在线/离线、用户状态）。Chat 用 room.presence，Spaces 用 space.enter() / useMembers() 钩子，Spaces 有专门的光标 API。
Chat SDK 关键生命周期
使用 @ably/chat 时最常见的错误：始终先订阅再调用 attach()。未先订阅就 attach 会导致消息静默丢失，这是最糟糕的一类 bug。
适用场景与限制
适用于使用 Ably 构建实时消息、聊天、协作、presence 或 AI 流式输出的开发场景，尤其适合让 AI 编码助手生成符合 Ably 当前 API 的代码。限制：本技能本身不提供 Ably 服务，实际使用需 Ably 账号与 API key；具体 API、参数、包版本以官方文档为准；部分产品并非所有平台都有 SDK；AI Transport 依赖频道规则配置。