@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slice-spec.md

@@ -0,0 +1,546 @@
+# TRTC 原子能力（Slice）定义规范
+
+> 本文档定义了 TRTC AI 知识库中 Slice 的拆分标准、编写规范和规划方法论。
+> 所有 slice 的创建和维护都应遵循本规范。
+
+---
+
+## 一、什么是 Slice
+
+Slice（原子能力）是 TRTC AI 知识库的最小知识单元。每个 slice 描述一个**独立的功能点**，包含：这个功能是什么、怎么用、常见的坑、出了问题怎么排查。
+
+**类比**：如果 TRTC SDK 是一台车，slice 就是驾驶手册里的一个章节——"怎么启动"、"怎么倒车"、"怎么用定速巡航"，每一章独立可读，合在一起就是完整手册。
+
+---
+
+## 二、Slice 拆分标准
+
+### 核心原则
+
+> **一个 slice = 用户遇到一个具体问题时，我们能一次性讲清楚的内容。**
+
+### 判断方法：三个问题
+
+#### 问题 1：「能不能一次讲清楚？」
+
+如果客户来问这个问题，技术支持能不能在**一次沟通**中完整解决？
+
+| 判断 | 举例 | 说明 |
+|------|------|------|
+| ✅ 合适 | "多端登录老是互踢怎么办？" | 讲清楚策略配置 + 回调处理 + 常见错误码就行 |
+| ✅ 合适 | "消息发不出去" | 讲清楚发送流程 + 权限检查 + 错误码就行 |
+| ❌ 太大了 | "消息功能怎么做？" | 发送、接收、历史记录、撤回、已读... 一次说不完 |
+| ❌ 太小了 | "怎么设置消息的优先级字段？" | 就一个参数，不值得单独做 |
+
+**简单判断**：想象客户发来一条微信问这个问题，你用**一段话或一个截图**能不能回答？能 → 合适的粒度。需要连续发好几屏 → 太大。回复一句话就搞定 → 太小，可以合并到相关功能里。
+
+#### 问题 2：「出问题时，排查方向一样吗？」
+
+如果两个功能出问题后，排查思路完全不同，就应该拆成两个 slice。
+
+| 场景 | 排查方向 | 结论 |
+|------|---------|------|
+| "消息发不出去" vs "收不到消息" | 发送查网络/权限/格式，接收查监听/登录状态/群设置 | → **拆成两个** |
+| "发文本消息" vs "发图片消息" | 都是查消息格式和网络 | → **合成一个**（发送消息） |
+| "主播无法开播" vs "连麦布局不对" | 开播查权限/配置，布局查模板参数 | → **拆成两个** |
+
+**简单判断**：客户报这两个问题的时候，你会不会分给同一个人处理？如果是，多半可以合并；如果你本能想找不同的人来看，就该拆开。
+
+#### 问题 3：「是独立的用户动作吗？」
+
+一个 slice 应该对应一个用户能感知到的**独立操作步骤**。
+
+| 场景 | 用户动作 | 结论 |
+|------|---------|------|
+| 配置准备页 → 点开播 → 进入直播间 | 这是一个连贯动作 | → **一个** slice（主播开播） |
+| 选择连麦布局模板 | 独立的配置决策 | → **单独一个** slice |
+| 隐藏某个按钮 + 改文案 + 换图标 | 都是"改 UI 外观"这一个动作 | → **合成一个** slice（UI 定制） |
+
+#### 问题 4：「能被多个场景复用吗？」
+
+一个 slice 应该能被 **2 个及以上** scenario（或其他 slice）引用。如果拆出来后只会被一个场景用到，通常说明它只是那个场景的一个步骤，而不是独立能力，应该合并回最相关的 slice。
+
+| 场景 | 复用性判断 | 结论 |
+|------|----------|------|
+| 「发送消息」 | 所有 Chat 相关 scenario 都会用 | → **独立 slice** |
+| 「进房」 | Live、Call、Room 所有场景共用 | → **独立 slice** |
+| 「主播开播前的网络探测提示」 | 只在「主播开播」这一个场景出现 | → **合并到 `live/anchor-lifecycle`** |
+| 「连麦申请时的倒计时 UI 定制」 | 只有「观众申请连麦」会用 | → **合并到 `live/coguest-apply`** |
+
+**唯一例外**：如果这个能力本身**极度独立、概念自洽、边界清晰**（即便当前只有一个引用方，未来很可能被复用），可以破例单拆。典型如「错误码速查」「日志诊断入口」这种跨能力的元能力。
+
+**简单判断**：先问自己「这个 slice 以后能被几个 scenario 引用？」——
+- 答得出 ≥2 个具体场景 → 独立 slice
+- 答不出、或只想得到一个 → 合并回去
+- 答不出但概念极独立、未来明显会被复用 → 可破例单拆，但要在 slice 开头写明「当前仅 X 场景使用，预留给 Y、Z 场景」
+
+### 粒度对比示例
+
+以「消息」为例：
+
+```
+❌ 太粗 → 一个"消息"slice 包含发送+接收+历史+撤回+转发+已读+推送
+   问题：客户说"消息收不到"，要在几千字里找相关部分
+
+❌ 太细 → 把发文本消息、发图片、发视频、发文件各做一个 slice
+   问题：它们的用法和排障方式几乎一样，重复内容太多
+
+✅ 合适 → 拆成：发送消息 / 接收消息 / 历史消息 / 消息撤回 / 离线推送
+   每个都能一次讲清，排查方向各不相同
+```
+
+---
+
+## 三、Slice 两层架构：主线 + 反馈
+
+| 层级 | 名称 | 来源 | 用途 |
+|------|------|------|------|
+| 🅰️ **主线 Slice** | 骨架 | 按 SDK 能力域系统规划（来自官方文档+研发经验） | 保证每个核心功能都有覆盖 |
+| 🅱️ **反馈 Slice** | 血肉 | 从产品/销售收集的用户高频问题中提炼 | 补充真实的坑和边缘场景 |
+
+### 两者的关系
+- **主线是骨架**：每个开发者都要走的路（初始化 → 登录 → 发消息 → ...）
+- **反馈是血肉**：开发者最容易摔跤的坑（互踢死循环、推送不到达、...）
+- 反馈 slice 可以是主线 slice 的深度补充，也可以是全新的边缘场景
+
+### 在 index.yaml 中的标记
+
+```yaml
+- id: chat/multi-instance
+  name: 多端登录与互踢
+  tags: [multi-instance, kick-offline, login]
+  platforms: [web, android, ios, flutter]
+  file: slices/chat/multi-instance.md
+  description: 多端登录策略配置、互踢回调处理、常见错误码
+  status: active          # active | planned
+```
+
+---
+
+## 四、Slice 文件结构规范
+
+每个 slice 文件是一个 Markdown 文件，包含 YAML frontmatter 和固定的内容结构。
+
+### 文件位置
+
+```
+knowledge-base/slices/{product}/{ability}.md          # 产品级概览（跨平台通用）
+knowledge-base/slices/{product}/{platform}/{ability}.md  # 平台实现细节
+```
+
+> **平台实现文件模板**：新建平台 slice 时，请复制 [`platform-slice-template.md`](platform-slice-template.md) 并按批注填写。填写范例见 `slices/live/ios/coguest-apply.md`。
+
+### Section 标签约定
+
+每个 section 标题后面统一标注三种标签之一，研发写的时候一眼知道要不要填：
+
+| 标签 | 含义 | 省略规则 |
+|------|------|---------|
+| `[必填]` | 必须写，否则 slice 不合格 | 不可省 |
+| `[可选]` | 视情况写，不影响合格 | 可整段删除 |
+| `[条件必填：<触发条件>]` | 满足条件时必须写，不满足时可省 | 不满足时可整段删除 |
+
+示例：
+```markdown
+## 功能说明 [必填]
+## 调用时序 [条件必填：异步回调嵌套 ≥3 层 或 涉及 3 个及以上角色]
+## 关联知识 [可选]
+```
+
+### Frontmatter 字段
+
+```yaml
+---
+id: chat/msg-send           # [必填] Slice ID，与 index.yaml 中的 id 一致
+name: 发送消息               # [必填] Slice 名称
+product: chat               # [必填] 所属产品
+tags: [message, send, ...]  # [必填] 搜索标签，至少 3 个
+platforms: [web, android, ios, flutter]  # [必填] 支持的平台
+related:                    # [可选] 关联的 slice，没有则省略此字段
+  - chat/msg-receive
+  - chat/msg-custom
+---
+```
+
+> **官方文档链接统一放在平台实现文件的 `api_docs` 字段**，产品级概览不放文档链接——因为教程/指南页通常按平台区分，放在跨平台的产品级文件里不合适。
+
+**平台实现文件的 frontmatter 字段**见「平台实现文件」小节。
+
+### 内容结构
+
+#### 产品级概览（`{product}/{ability}.md`）
+
+产品级概览是**跨平台通用**的，描述的是"做什么"和"为什么"，不涉及"怎么做"。
+
+**平台无关性规则**：
+
+| ✅ 可以出现 | ❌ 不可以出现 |
+|-------------|-------------|
+| 操作语义（"观众发起连麦申请"） | 具体 API 签名（`applyForSeat(seatIndex:timeout:)` 这种 Swift 命名参数风格） |
+| 通用概念名（"连麦管理器"、"事件流"） | 平台特有类名/机制（`PassthroughSubject`、`ViewController`、`cancellable`） |
+| 行为级最佳实践（"通过前不要开设备"） | 代码结构级约束（"`[weak self]` 避免循环引用"） |
+| 通用排障逻辑（"检查主播端是否订阅了事件"） | 平台特有排障（"检查 cancellable 是否被提前释放"） |
+| 跨平台统一的错误码 | 仅某平台出现的错误码或异常行为 |
+
+**核心概念表的写法**：用操作名 + 语义描述，不写某个平台的方法签名。如果各平台 API 完全一致（同名同参数），可以写通用签名；如果有差异，只写操作语义，具体签名放到平台文件。
+
+**自查方法**：把文件中所有 API 名、类名、术语逐一检查 — 如果一个 Android 开发者读到它会觉得困惑或不适用，那就是平台特有内容，应该下沉到平台文件。
+
+```markdown
+# {名称}（产品级概览）
+
+## 功能说明 [必填]
+[功能描述、典型场景、版本要求]
+
+## 核心概念 [必填]
+[操作语义 + 状态机 + 角色关系，不含平台特有 API 签名]
+
+## 最佳实践 [必填]
+### ✅ ALWAYS（必须做的）
+[行为级规则：描述"该做什么"，不指定"用哪个 API 做"]
+### ❌ NEVER（绝不要做的）
+[行为级规则：描述"不该做什么"，不指定平台实现细节]
+
+## 排障指南 [必填]
+### 常见错误码
+[跨平台统一的错误码表格]
+### 排障流程
+[通用排障逻辑树，平台特有分支标注 → 见平台文件]
+
+## 关联知识 [可选]
+[引用相关 slice；如果没有关联，删除整个 section]
+```
+
+**产品级概览中各 section 的必填理由**：
+- `功能说明` / `核心概念` — slice 的身份标识，缺失则无法理解这个 slice 是做什么的
+- `最佳实践` — slice 区别于官方文档的核心价值。如果仅抄 API 说明，无需做 slice
+- `排障指南` — slice 面向集成场景的交付标准。至少给出「常见错误码」和「排障流程」两个子项，否则客户报问题时无章可循
+- `关联知识` — 孤立能力可省。有 2+ 相关 slice 时必须写，防止知识孤岛
+
+> 提交前对照第五节「产品级概览 DoD」逐条打勾，合格后再提交。
+
+#### 平台实现文件（`{product}/{platform}/{ability}.md`）
+
+##### Frontmatter 字段
+
+```yaml
+---
+id: {product}/{ability}     # [必填] 与产品级 slice 的 id 一致
+platform: {platform}        # [必填] ios / android / web / flutter / electron
+api_docs:                   # [必填] 该平台 API 参考文档链接（至少 1 条）
+  - title: {API 类名/模块名}
+    url: https://...
+---
+```
+
+**`api_docs` 填写质量要求**：
+
+| 要求 | 说明 | 举例 |
+|------|------|------|
+| ✅ 精确到**类/模块**级 | 一条链接打开就能看到本 slice 涉及的具体类 API | `https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore/` |
+| ✅ 多个类的 slice 可多条 | 一个 slice 涉及多个 Store/Manager 时分别列出 | `CoGuestStore` + `DeviceStore` |
+| ❌ 不要填 SDK 首页 | 首页没有具体类签名，AI 拿不到校验所需信息 | `https://trtc.io/sdk` |
+| ❌ 不要填产品级教程页 | 教程/指南页不属于 API 参考 | `https://trtc.io/zh/document/74598` |
+
+**若该平台没有可用的 API 参考页**（如 Electron/Unity 某些模块）：
+- 优先考虑这个 slice 在该平台是否真的需要独立文件
+- 若确需保留，填入**头文件/类型声明文件**的 GitHub 永久链接（commit hash 固定版本），而不是空链接
+
+> 注：`name` / `tags` / `platforms` / `related` 在产品级概览中维护，平台文件不重复。
+
+##### 内容结构
+
+平台实现文件按以下结构编写，每个 section 标题后都必须带必填/可选标签：
+
+```markdown
+# {名称} — {平台} 实现
+
+## 前置条件 [必填]
+## 代码示例 [必填]
+## 调用时序 [条件必填：多角色异步交互 或 回调嵌套 ≥3 层]
+## 平台特有注意事项 [必填：至少 1 条]
+## 代码生成约束 [必填]
+## 验证矩阵 [必填]
+```
+
+各 section 详细要求见下方。
+
+##### 代码示例标准 [必填]
+
+平台 slice 的核心交付物。要求：
+
+| 维度 | 最低标准 |
+|------|---------|
+| **可编译** | 包含完整 import、完整类/函数闭包，不允许 `...` 省略任何逻辑分支 |
+| **可运行** | 补充业务参数后可直接跑通；业务参数用 `{TODO: 填入 xxx}` 占位，而不是随意编的字符串 |
+| **有日志锚点** | 关键路径（申请发送成功、主播同意、设备打开、失败分支）必须有 `print`/`console.log`/`Log.d`，供「验证矩阵」在运行时观察；日志统一带模块前缀如 `[CoGuest]` |
+| **有错误处理** | 每一个 `.failure` / `catch` / `error` 分支都必须有面向用户的处理（UI 可见的 `errorMessage` 或 `alert`），不允许只 `print` 就结束 |
+| **多角色分开写** | 主播端 / 观众端 这种异构角色，**必须**拆成独立示例代码块 |
+| **可组合性** | 对外暴露清晰输入/输出；不硬编码其他 slice 的调用（如登录初始化），依赖用注释标注 `// 前置：登录完成（→ live/login-auth）` |
+
+**禁止事项**：
+- ❌ 用伪代码或 `...` 跳过逻辑
+- ❌ 把多个 slice 的职责耦合在一个类里
+- ❌ 省略失败分支处理
+
+##### 代码生成约束 [必填]
+
+此 section 是给 AI 读的硬性规则。**只有 apply 能机械验证的规则才能进 MUST/MUST NOT**——具体什么样的规则算「能机械验证」，见下一节「MUST 规则的维度对齐原则」，必读。
+
+格式示例：
+
+```markdown
+### 编译必要条件 [必填]
+- 必须导入的模块/包（精确到包名）
+- 最低 SDK 版本（若高于 base）
+- 必须的权限声明或配置
+
+### 生成规则 [必填]
+
+#### MUST（生成时必须包含）
+
+1. **<动作> `符号`** — <违反后果>。
+   **Verify**: 检查是否存在 `符号`。
+
+2. **<动作> `符号 A`** — <违反后果>。
+   **Verify**: 检查是否存在 `符号 A`。
+
+#### MUST NOT（生成时绝不能出现）
+
+1. **不要 <动作> `符号`** — <违反后果>。
+   **Verify**: 检查 `符号` 出现 0 次。
+
+### 集成检查点 [必填]
+- 是否与项目已有 SDK 初始化冲突
+- 是否依赖其他 slice 的前置状态（引用具体 slice ID）
+- 对已有代码的侵入性（新增 vs 修改）
+```
+
+**关键约束**：
+
+- 每条 MUST/MUST NOT 的 `**Verify**:` 字段引用的 backtick 符号 = apply 唯一会 grep 的东西
+- 规则文字描述的所有判断、选择、等价、条件分支，apply **全部不验**——所以这些不要写进 MUST
+- 多 backtick 的规则可以接受，apply 解析为「全部都要出现」（all-of）
+
+##### MUST 规则的维度对齐原则 [必填阅读]
+
+###### 核心原则
+
+> **MUST 规则的语义 = 它的 backtick 符号能验的语义。**
+>
+> 如果你写的规则文字比 backtick 符号能表达的更多，规则就「维度溢出」了——AI 写对了你 grep 不到，AI 写错了你也 grep 不到，verifier 反而把 AI 推向凑字符串。
+
+###### 红旗词表：以下写法说明 MUST 写错了
+
+| 红旗词 | 例子 | 为什么是红旗 | 怎么改 |
+|---|---|---|---|
+| **「或 / 任一」** | "出现 `X` 或 `Y`" | grep 一个 ≠ 验了选择 | 拆两条 MUST 各管一个分支；或把「选哪个」移到「最佳实践」/「场景说明」 |
+| **「等价 / 或类似」** | "处理 `ERR_X` 或等价提示" | "等价" 无法机械化，AI 写等价代码 verify 还是 fail | 显式枚举所有可接受的 backtick 写法；或承认是软规则放到「最佳实践」 |
+| **「按业务 / 根据场景」** | "按业务目标选 `X` 或 `Y`" | 业务判断不是 grep 能做的事 | 完全移出 MUST。具体场景写到「代码示例」每个场景一段，让 AI 选示例 copy |
+| **「留给 / 负责」** | "把 X 留给 slice A，把 Y 留给 slice B" | 架构边界没有任何 grep pattern 能验 | 移到「集成检查点」section，作为 AI 读但 apply 不验的引导文字 |
+| **多 backtick 但 Verify 只提一个** | "调 `A()` 后再调 `B()`"，Verify 只检查 `A` | A 出现 ≠ 调用顺序对 | 拆两条 MUST 各管一个 API；调用顺序不能机械验，写到「调用时序」section |
+
+###### 自查三问（写完每条 MUST 之前问自己）
+
+1. backtick 里的符号是不是就是 verify 唯一会做的事？规则文字里的其他词能不能删？
+2. 如果 AI 写**等价但不同写法**的代码，verify 会不会误杀？误杀 = 规则太死，要么拆原子要么降级软规则。
+3. 如果 AI 写**只满足 backtick 字符串但语义错**的代码，verify 会不会放过？放过 = 规则太松，应该拆。
+
+###### 软规则 vs 硬约束
+
+| 类型 | 写在哪 | apply 行为 | AI 行为 |
+|---|---|---|---|
+| **硬约束**（MUST/MUST NOT） | 「代码生成约束」 | grep backtick，命中失败就 fail | 必须包含/避免符号 |
+| **软规则**（业务选择、架构建议、调用顺序、错误处理建议） | 「最佳实践」「集成检查点」「调用时序」「代码示例」 | 不验，仅作为 AI 上下文 | 阅读后自行判断 |
+
+> **重要 ≠ 能机械验证。**
+>
+> 把重要但验不了的规则放进 MUST，会**误杀正确代码 + 训练 AI 凑字符串**——这是 verifier 反向变成攻击面。
+>
+> 重要但不能机械验证的规则，**写到软规则区，靠 AI 阅读 + 反例代码**来引导。
+
+###### 完整改造示例：room-lifecycle 的失败规则
+
+❌ **改前**（现状写法，触发 AI 凑字符串）：
+
+```
+3. **按业务目标选择 `createAndJoinRoom()` 或 `joinRoom()`** — 房主快速创建并入会、
+   以及无法确认房间是否存在时，都更适合 `createAndJoinRoom()`；只有已知房间已存在
+   时才直接使用 `joinRoom()`。
+   **Verify**: 检查是否把"房主创建并入会""已知房间存在直接加入""存在性未知时尝试
+   进入"这三类路径明确区分。
+
+5. **为密码房和常见入会错误预留业务反馈** — 无 UI 接入时，密码输入、重试和错误
+   提示都需要页面自行承接。
+   **Verify**: 检查加入流程是否处理 `ERR_NEED_PASSWORD`、`ERR_WRONG_PASSWORD`
+   或等价失败提示。
+```
+
+红旗词诊断：「按业务」「或」「等价」全部命中。规则文字承诺的语义远超 backtick 能验的范围。
+
+✅ **改后**：
+
+「代码生成约束」→ MUST：
+```
+3. **必须调用房间进入 API（`createAndJoinRoom` 或 `joinRoom` 至少其一）** — 否则
+   无法进房。
+   **Verify**: 检查 `createAndJoinRoom` 与 `joinRoom` 至少其一出现 ≥1 次。
+```
+
+「代码示例」→ 增加场景一/二/三，每个场景写完整可 copy 的代码。
+
+「最佳实践」→ 新增软规则段（apply 不验，AI 阅读）：
+```
+- 房主快速创建会议 → 用 createAndJoinRoom（参考场景一）
+- 已知房间已存在 → 用 joinRoom（参考场景二）
+- 不确定房间是否存在 → 用 createAndJoinRoom（参考场景三）
+- 密码房 / 入会错误处理 → 见场景四与「常见错误与场景对照」表
+```
+
+效果：
+- apply 不再误杀「AI 用 catch 通用错误处理」的正确代码
+- AI 读到「最佳实践」能按业务选 API
+- 业务路径选择即使错了也不会因 verify fail 把 AI 推去凑字符串
+
+##### 验证矩阵 [必填]
+
+此 section 是平台 slice 末尾的**统一验证出口**，汇总该 slice 所有可 verify 的项，按 4 层分级。AI 生成代码后或人工 review 时，自上而下跑一遍即可完成验收。
+
+```markdown
+## 验证矩阵
+
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| **1. 编译级** | 模块导入齐全 | `xcodebuild build ...` / `./gradlew assembleDebug` / `tsc --noEmit` | exit code 0 |
+| **1. 编译级** | 最低版本达标 | 查项目 deployment target | ≥ {版本} |
+| **2. 静态规则级** | 所有 sink 都 `[weak self]` | `grep -E "sink\\s*\\{\\s*\\[weak self\\]"` | 匹配数 == sink 总数 |
+| **2. 静态规则级** | AnyCancellable 是实例属性 | `grep "var cancellables: Set<AnyCancellable>"` | 至少 1 处 |
+| **2. 静态规则级** | 每个 .failure 有 errorMessage | 代码审查 + grep | 无裸 print |
+| **3. 运行时级** | 申请发送成功 | 观众点申请 → 查日志 | `[CoGuest] 申请已发送...` |
+| **3. 运行时级** | 主播收到事件 | 主播端查日志 | `onGuestApplicationReceived` |
+| **3. 运行时级** | 超时 UI 反馈 | 主播不响应，等 30s | UI 展示"申请超时" |
+| **4. 业务行为级** | 通过前设备未开 | 点申请但未同意 | 摄像头指示灯不亮 |
+| **4. 业务行为级** | 断开后设备关闭 | 连麦中主动断开 | 摄像头指示灯熄灭 |
+```
+
+**4 个层级说明**：
+
+| 层级 | 含义 | 谁来跑 |
+|------|------|--------|
+| 1. **编译级** | 代码能编译通过、依赖齐全 | CI / AI 自动 |
+| 2. **静态规则级** | 不跑代码，纯静态扫描/ grep 就能查的规则 | CI / AI 自动 |
+| 3. **运行时级** | 跑起来后通过日志锚点可观察的行为 | AI 半自动 / 人工 |
+| 4. **业务行为级** | 需要人眼看 UI / 硬件状态的业务语义 | 人工 |
+
+> **与 MUST 规则的对应关系**：
+>
+> - 「层级 1 编译级」与「层级 2 静态规则级」是 apply 的**硬约束区域**——这两层的检查项基本对应「代码生成约束」里的 MUST / MUST NOT，apply 自动跑、命中失败会 fail。
+> - 「层级 3 运行时级」与「层级 4 业务行为级」是**软规则区域**——属于运行时观察 / 业务语义校验，apply 不验，需要 AI 半自动或人工跑。这些层级的内容对应「MUST 规则维度对齐原则」里的「软规则」（业务选择、调用顺序、架构边界等机械验证不了的项目）。
+
+**要求**：
+- 每条「代码生成约束」的 MUST/MUST NOT 都应在矩阵中有对应行（层级 1 或 2）
+- 至少 1 条层级 3 的检查，证明代码真的能跑起来
+- 至少 1 条层级 4 的检查，证明业务语义正确（通常是「ALWAYS/NEVER」的运行时体现）
+
+---
+
+## 五、完成自查清单（DoD）
+
+研发写完 slice 后，对照清单逐条打勾。任何一项未满足 = 未完成。
+
+### 产品级概览 DoD
+
+- [ ] Frontmatter 必填字段齐全（id / name / product / tags≥3 / platforms）
+- [ ] 每个 section 标题都带 `[必填]` / `[可选]` / `[条件必填]` 标签
+- [ ] `功能说明` 能让一个没接触过 TRTC 的开发者 30 秒内明白这个能力是什么
+- [ ] `核心概念` 无平台特有 API 签名（自查：逐个 API 名过一遍，iOS/Android 开发者读到都不应困惑）
+- [ ] `最佳实践` 的每条 ALWAYS/NEVER 都是**行为级**（"做什么"），不含代码结构细节（"怎么写"）
+- [ ] `排障指南` 至少包含 1 张错误码表 + 1 棵排障流程树
+- [ ] `关联知识` 的所有引用 slice ID 在 `index.yaml` 中存在（或标注 `status: planned`）
+- [ ] 全文不包含具体平台的类名/方法名/关键字（如 `ViewController`、`[weak self]`、`PassthroughSubject`）
+
+### 平台实现文件 DoD
+
+- [ ] Frontmatter 必填字段齐全（id / platform / api_docs≥1）
+- [ ] `api_docs` 链接精确到**类/模块**级，不是 SDK 首页或教程页
+- [ ] 每个 section 标题都带必填/可选标签
+- [ ] `前置条件` 没有重复 base-setup / login-auth 已覆盖的通用依赖
+- [ ] `代码示例` 满足**代码示例标准**的 6 条最低要求（见第四节表格）
+- [ ] 每个 `.failure` / `catch` / `error` 分支都有面向用户的可见处理，不允许只 `print`
+- [ ] 每段代码都有日志锚点，供「验证矩阵」层级 3 使用
+- [ ] `调用时序`：若涉及多角色异步交互或回调嵌套 ≥3 层，必须画；否则可省
+- [ ] `平台特有注意事项` 至少 1 条，且每条都是「该平台独有 + 不写出来研发会踩坑」
+- [ ] `代码生成约束` 的每条 MUST / MUST NOT 都使用 **prose + backtick** 格式：`**Verify**: 检查是否存在 \`symbol\``，每条规则的 backtick 符号是 apply 唯一 grep 的目标
+- [ ] 每条 MUST / MUST NOT 通过「自查三问」（见第四节「MUST 规则的维度对齐原则」）
+- [ ] 每条 MUST / MUST NOT 不含「红旗词」（或 / 任一 / 等价 / 按业务 / 根据场景 / 留给 / 负责）；含红旗词的规则要么拆成原子规则，要么下沉到软规则区
+- [ ] `代码生成约束` 的 MUST / MUST NOT 与产品级 ALWAYS / NEVER 不重复（前者管代码结构，后者管运行时行为）
+- [ ] `验证矩阵` 的 4 个层级都有至少 1 行
+- [ ] `验证矩阵` 覆盖了所有 MUST / MUST NOT 规则（每条规则都能在矩阵中找到对应行）
+
+### Slice 整体 DoD（提交合并前）
+
+- [ ] 通过第二节的 4 个拆分问题自查（特别是**问题 4：能被 ≥2 个场景复用**）
+- [ ] 在 `index.yaml` 中登记，`status` 标记为 `active` 或 `planned`
+- [ ] 如果是反馈 slice（🅱️），在描述中说明其对应的用户高频问题来源
+
+---
+
+## 六、引用规范与边界
+
+### 6.1 Slice 之间的引用规范
+
+目的：避免重复写、避免知识孤岛、让 AI 能沿着引用链找到完整上下文。
+
+#### 何时必须引用、不允许重复
+
+以下内容已由专门 slice 承载，其他 slice **必须引用、不允许重复**：
+
+| 内容 | 承载 slice |
+|------|-----------|
+| SDK 安装、主包依赖、基础权限声明 | `{product}/login-auth` 或 `{product}/base-setup` |
+| 登录认证流程 | `{product}/login-auth` |
+| 跨 slice 复用的错误码总表 | `{product}/error-codes` |
+| 设备开关（摄像头/麦克风） | `{product}/device-control` |
+
+引用写法统一：
+```markdown
+见 [login-auth 平台 slice](../login-auth.md)（SDK 安装、Info.plist 权限）
+→ 前置依赖：`LoginStore.shared.isLogin == true`（→ live/login-auth）
+```
+
+#### 何时允许适度重复
+
+仅以下两种情况允许少量重复：
+
+1. **单行关键代码** — 如果不复述一行代码会让阅读体验跳跃（比如 `import Combine`），可以保留这一行并备注"详见 xxx slice"
+2. **错误码的本地化提示文案** — 可以在各自 slice 中重复出现，因为每个 slice 的错误码含义上下文不同
+
+#### 引用格式统一
+
+| 场景 | 统一写法 |
+|------|---------|
+| 正文引用其他 slice | `[slice-id](相对路径.md)` 或 `（→ slice-id）` |
+| 代码注释中标注依赖 | `// 前置：xxx 完成（→ slice-id）` |
+| Frontmatter 中的 related | 只写 `slice-id`，不带路径 |
+| 指向官方文档 | 放在平台文件的 `api_docs` 中，正文不重复 URL |
+
+### 6.2 Slice 与 Scenario 的边界
+
+Slice 和 Scenario 经常会让人纠结某段内容该放哪，给一个简单判定：
+
+| 内容类型 | 归属 | 理由 |
+|---------|------|------|
+| 单一能力的完整实现（含所有角色、所有失败分支） | **Slice** | slice 是零件，必须自洽 |
+| 同一能力内部的多步骤先后顺序（如：申请→等待→开设备） | **Slice** | 属于该能力内部时序 |
+| 多个能力之间的组装顺序（如：登录→进房→推流→连麦） | **Scenario** | scenario 才知道全局顺序 |
+| 业务选型决策（如：选择 1v1 通话还是多人连麦） | **Scenario** | slice 不关心业务形态 |
+| 跨能力的状态共享（如：登录 Store 在哪个层级持有） | **Scenario** | slice 内部只声明依赖，不决定生命周期宿主 |
+| 某个能力特有的 UI 定制点 | **Slice** | UI 定制依附于能力 |
+| 场景级的 UI 布局/导航流程 | **Scenario** | 属于场景形态 |
+
+**反例自查**：
+- ❌ 一个 slice 的代码示例里写了「先调用登录、再调用本能力」 → 登录的组装应该交给 scenario，slice 只声明 `// 前置：登录完成（→ xxx）`
+- ❌ 一个 scenario 里大段贴某个能力的完整失败处理代码 → 应该是 scenario 引用 slice，而不是抄写 slice
+
+---
+