@tencent-rtc/trtc-agent-skills 0.1.1 → 0.1.4

package/knowledge-base/slice-spec.md

@@ -1,486 +1,2526 @@
-# TRTC 原子能力（Slice）定义规范
+# TRTC 原子能力(Slice)定义规范
+# TRTC 原子能力(Slice)定义规范
 
 > 本文档定义了 TRTC AI 知识库中 Slice 的拆分标准、编写规范和规划方法论。
 > 所有 slice 的创建和维护都应遵循本规范。
 
 ---
 
+## 0. 给新人:你只需要做三件事
+
+如果你是第一次写 slice,只要:
+
+1. **复制模板**:找到对应 section 的「写作模板」,把 `{占位符}` 全部填掉。
+2. **对照正反例**:每个 section 都有 ✅ 正例 + ❌ 反例,写完后逐条对照自查。
+3. **跑验证手段**:每个 `[必填]` 都附了「验证手段」,跑命令通过才算合格。
+
+**只要这三步通过,你的 slice 就自动符合团队的 AI 文档质量标准。**
+
+> ⚠️ 这份 spec 里你看到的所有"强势语言"("绝不要""必须""不可合并")**不是夸张表达**——都对应过真实事故。
+
+---
+
+## 0. 给新人:你只需要做三件事
+
+如果你是第一次写 slice,只要:
+
+1. **复制模板**:找到对应 section 的「写作模板」,把 `{占位符}` 全部填掉。
+2. **对照正反例**:每个 section 都有 ✅ 正例 + ❌ 反例,写完后逐条对照自查。
+3. **跑验证手段**:每个 `[必填]` 都附了「验证手段」,跑命令通过才算合格。
+
+**只要这三步通过,你的 slice 就自动符合团队的 AI 文档质量标准。**
+
+> ⚠️ 这份 spec 里你看到的所有"强势语言"("绝不要""必须""不可合并")**不是夸张表达**——都对应过真实事故。
+
+---
+
 ## 一、什么是 Slice
 
-Slice（原子能力）是 TRTC AI 知识库的最小知识单元。每个 slice 描述一个**独立的功能点**，包含：这个功能是什么、怎么用、常见的坑、出了问题怎么排查。
+Slice(原子能力)是 TRTC AI 知识库的最小知识单元。每个 slice 描述一个**独立的功能点**,包含:这个功能是什么、怎么用、常见的坑、出了问题怎么排查。
+Slice(原子能力)是 TRTC AI 知识库的最小知识单元。每个 slice 描述一个**独立的功能点**,包含:这个功能是什么、怎么用、常见的坑、出了问题怎么排查。
+
+**类比**:如果 TRTC SDK 是一台车,slice 就是驾驶手册里的一个章节——"怎么启动"、"怎么倒车"、"怎么用定速巡航",每一章独立可读,合在一起就是完整手册。
+
+**最终读者是 AI**:slice 文档会被 AI 直接读取并用于生成代码。这意味着:
+- 任何模糊词("应该""大概""一般来说")都会被 AI 解释为"可选" → 跳过
+- 任何遗漏的反例,AI 都会用训练数据里的错误模式去补
+- 任何不可机械验证的规则,AI 都可能"凑字符串"通过
+
+→ 所以本 spec 用极端强势的语言,是为了让产出的 slice 也具有同样的硬约束力。
+**类比**:如果 TRTC SDK 是一台车,slice 就是驾驶手册里的一个章节——"怎么启动"、"怎么倒车"、"怎么用定速巡航",每一章独立可读,合在一起就是完整手册。
+
+**最终读者是 AI**:slice 文档会被 AI 直接读取并用于生成代码。这意味着:
+- 任何模糊词("应该""大概""一般来说")都会被 AI 解释为"可选" → 跳过
+- 任何遗漏的反例,AI 都会用训练数据里的错误模式去补
+- 任何不可机械验证的规则,AI 都可能"凑字符串"通过
+
+→ 所以本 spec 用极端强势的语言,是为了让产出的 slice 也具有同样的硬约束力。
+
+---
+
+## 二、Slice 拆分标准
+
+### 强制拆分判断流程(任何一步不可跳过)
+
+新建 slice 前,**必须**按顺序回答以下 4 个问题。任何一个问题答不出 → 不允许新建 slice。
+
+#### 问题 1:能不能一次讲清楚?
+
+**判断标准**:在 PR 描述中粘贴一份 ≤500 字的"客户问这个问题时的一次性回答 demo"。
+- 超过 500 字 → split,本 slice 太大
+- 不到 50 字 → 太小,合并到相关 slice
+- 恰好够讲清原理 + 关键 API + 常见错误码 → ✅ 合格粒度
+
+✅ **正例**:
+- "多端登录老是互踢怎么办?" → 讲策略配置 + 回调处理 + 常见错误码,300 字搞定 ✅
+- "消息发不出去" → 讲发送流程 + 权限检查 + 错误码,400 字搞定 ✅
+
+❌ **反例**:
+- "消息功能怎么做?" → 发送+接收+历史+撤回+已读+推送... 至少 3000 字 ❌(太大,split)
+- "怎么设置消息的优先级字段?" → 一句话回答,30 字 ❌(太小,合并到「发送消息」)
+
+#### 问题 2:出问题时,排查方向一样吗?
+
+**判断标准**:在最近 100 个 ticket 中搜这两类问题,如果它们的 assignee 通常不是同一人,或排查思路完全不同 → 拆。
+### 强制拆分判断流程(任何一步不可跳过)
+
+新建 slice 前,**必须**按顺序回答以下 4 个问题。任何一个问题答不出 → 不允许新建 slice。
+
+#### 问题 1:能不能一次讲清楚?
+
+**判断标准**:在 PR 描述中粘贴一份 ≤500 字的"客户问这个问题时的一次性回答 demo"。
+- 超过 500 字 → split,本 slice 太大
+- 不到 50 字 → 太小,合并到相关 slice
+- 恰好够讲清原理 + 关键 API + 常见错误码 → ✅ 合格粒度
+
+✅ **正例**:
+- "多端登录老是互踢怎么办?" → 讲策略配置 + 回调处理 + 常见错误码,300 字搞定 ✅
+- "消息发不出去" → 讲发送流程 + 权限检查 + 错误码,400 字搞定 ✅
+
+❌ **反例**:
+- "消息功能怎么做?" → 发送+接收+历史+撤回+已读+推送... 至少 3000 字 ❌(太大,split)
+- "怎么设置消息的优先级字段?" → 一句话回答,30 字 ❌(太小,合并到「发送消息」)
+
+#### 问题 2:出问题时,排查方向一样吗?
+
+**判断标准**:在最近 100 个 ticket 中搜这两类问题,如果它们的 assignee 通常不是同一人,或排查思路完全不同 → 拆。
+
+| 场景 | 排查方向 | 结论 |
+|------|---------|------|
+| "消息发不出去" vs "收不到消息" | 发送查网络/权限/格式;接收查监听/登录状态/群设置 | → **拆成两个** |
+| "发文本消息" vs "发图片消息" | 都是查消息格式和网络 | → **合成一个**(发送消息) |
+| "主播无法开播" vs "连麦布局不对" | 开播查权限/配置;布局查模板参数 | → **拆成两个** |
+| "消息发不出去" vs "收不到消息" | 发送查网络/权限/格式;接收查监听/登录状态/群设置 | → **拆成两个** |
+| "发文本消息" vs "发图片消息" | 都是查消息格式和网络 | → **合成一个**(发送消息) |
+| "主播无法开播" vs "连麦布局不对" | 开播查权限/配置;布局查模板参数 | → **拆成两个** |
+
+#### 问题 3:是独立的用户动作吗?
+#### 问题 3:是独立的用户动作吗?
+
+一个 slice = 一个用户能感知到的**独立操作步骤**。
+一个 slice = 一个用户能感知到的**独立操作步骤**。
+
+| 场景 | 用户动作 | 结论 |
+|------|---------|------|
+| 配置准备页 → 点开播 → 进入直播间 | 一个连贯动作 | → **一个** slice(主播开播) |
+| 选择连麦布局模板 | 独立配置决策 | → **单独一个** slice |
+| 隐藏按钮 + 改文案 + 换图标 | 都是"改 UI 外观" | → **合成一个** slice(UI 定制) |
+| 配置准备页 → 点开播 → 进入直播间 | 一个连贯动作 | → **一个** slice(主播开播) |
+| 选择连麦布局模板 | 独立配置决策 | → **单独一个** slice |
+| 隐藏按钮 + 改文案 + 换图标 | 都是"改 UI 外观" | → **合成一个** slice(UI 定制) |
+
+#### 问题 4:能被 ≥2 个场景复用吗?(强制门控)
+
+**这是最常被忽略、也最致命的问题**。一个 slice 必须能被 **2 个及以上** scenario(或其他 slice)引用。
+
+**强制证据要求**:
+- [ ] 在 PR 描述中**列出至少 2 个具体 scenario id**
+- [ ] 在 `index.yaml` 中能搜到这些 scenario 的引用关系
+- [ ] 缺少 ≥2 引用 → **不允许合并**(除非走破例条款)
+#### 问题 4:能被 ≥2 个场景复用吗?(强制门控)
+
+**这是最常被忽略、也最致命的问题**。一个 slice 必须能被 **2 个及以上** scenario(或其他 slice)引用。
+
+**强制证据要求**:
+- [ ] 在 PR 描述中**列出至少 2 个具体 scenario id**
+- [ ] 在 `index.yaml` 中能搜到这些 scenario 的引用关系
+- [ ] 缺少 ≥2 引用 → **不允许合并**(除非走破例条款)
+
+| 场景 | 复用性判断 | 结论 |
+|------|----------|------|
+| 「发送消息」 | 所有 Chat scenario 都用 | → **独立 slice** |
+| 「进房」 | Live、Call、Room 共用 | → **独立 slice** |
+| 「主播开播前的网络探测提示」 | 只在「主播开播」一个场景出现 | → **合并到 `live/anchor-lifecycle`** |
+| 「发送消息」 | 所有 Chat scenario 都用 | → **独立 slice** |
+| 「进房」 | Live、Call、Room 共用 | → **独立 slice** |
+| 「主播开播前的网络探测提示」 | 只在「主播开播」一个场景出现 | → **合并到 `live/anchor-lifecycle`** |
+| 「连麦申请时的倒计时 UI 定制」 | 只有「观众申请连麦」会用 | → **合并到 `live/coguest-apply`** |
+
+**破例条款**(且仅当):能力本身**极度独立、概念自洽、边界清晰**(典型如「错误码速查」「日志诊断入口」)。
+- 必须在 slice 开头**明文写清**:「当前仅 X 场景使用,预留给 Y、Z 场景」
+- 缺少这段声明 → 视为未使用破例 → 拒绝合并
+
+#### 必填项语义三件套(拆分判断)
+
+- **违反后果**:跳过任何一个问题 → 产出孤儿 slice / 重复 slice / 粒度失衡 slice → 知识库治理债累积 → 半年后必须做大批量重构(历史教训:2025-Q1 清理孤儿 slice 花了 1 个月)
+- **验证手段**:PR 描述中**逐条粘贴 4 个问题的回答**;reviewer 检查问题 4 的引用方是否真实存在于 `index.yaml`
+- **绕过条件**:无。这是 slice 存在的合法性前提,不接受任何豁免
+
+---
+**破例条款**(且仅当):能力本身**极度独立、概念自洽、边界清晰**(典型如「错误码速查」「日志诊断入口」)。
+- 必须在 slice 开头**明文写清**:「当前仅 X 场景使用,预留给 Y、Z 场景」
+- 缺少这段声明 → 视为未使用破例 → 拒绝合并
+
+#### 必填项语义三件套(拆分判断)
+
+- **违反后果**:跳过任何一个问题 → 产出孤儿 slice / 重复 slice / 粒度失衡 slice → 知识库治理债累积 → 半年后必须做大批量重构(历史教训:2025-Q1 清理孤儿 slice 花了 1 个月)
+- **验证手段**:PR 描述中**逐条粘贴 4 个问题的回答**;reviewer 检查问题 4 的引用方是否真实存在于 `index.yaml`
+- **绕过条件**:无。这是 slice 存在的合法性前提,不接受任何豁免
+
+---
+
+### 粒度对比示例
+
+以「消息」为例:
+以「消息」为例:
+
+```
+❌ 太粗 → 一个 "消息" slice 包含发送+接收+历史+撤回+转发+已读+推送
+   后果:客户说"消息收不到",AI 要在几千字里找,80% 概率找错段落
+❌ 太粗 → 一个 "消息" slice 包含发送+接收+历史+撤回+转发+已读+推送
+   后果:客户说"消息收不到",AI 要在几千字里找,80% 概率找错段落
+
+❌ 太细 → 把发文本、发图片、发视频、发文件各做一个 slice
+   后果:用法和排障几乎一样,AI 学到 4 份重复内容,生成代码时随机选
+❌ 太细 → 把发文本、发图片、发视频、发文件各做一个 slice
+   后果:用法和排障几乎一样,AI 学到 4 份重复内容,生成代码时随机选
+
+✅ 合适 → 拆成:发送消息 / 接收消息 / 历史消息 / 消息撤回 / 离线推送
+   每个都能一次讲清,排查方向各不相同
+✅ 合适 → 拆成:发送消息 / 接收消息 / 历史消息 / 消息撤回 / 离线推送
+   每个都能一次讲清,排查方向各不相同
+```
+
+---
+
+## 三、Slice 两层架构:主线 + 反馈
+## 三、Slice 两层架构:主线 + 反馈
+
+| 层级 | 名称 | 来源 | 用途 |
+|------|------|------|------|
+| 🅰️ **主线 Slice** | 骨架 | 按 SDK 能力域系统规划(来自官方文档+研发经验) | 保证每个核心功能都有覆盖 |
+| 🅰️ **主线 Slice** | 骨架 | 按 SDK 能力域系统规划(来自官方文档+研发经验) | 保证每个核心功能都有覆盖 |
+| 🅱️ **反馈 Slice** | 血肉 | 从产品/销售收集的用户高频问题中提炼 | 补充真实的坑和边缘场景 |
+
+### 两者的关系
+- **主线是骨架**:每个开发者都要走的路(初始化 → 登录 → 发消息 → ...)
+- **反馈是血肉**:开发者最容易摔跤的坑(互踢死循环、推送不到达、...)
+- 反馈 slice 可以是主线 slice 的深度补充,也可以是全新的边缘场景
+- **主线是骨架**:每个开发者都要走的路(初始化 → 登录 → 发消息 → ...)
+- **反馈是血肉**:开发者最容易摔跤的坑(互踢死循环、推送不到达、...)
+- 反馈 slice 可以是主线 slice 的深度补充,也可以是全新的边缘场景
+
+### 在 per-product platform index 中的标记
+
+```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 和固定的内容结构。
+每个 slice 文件是 Markdown 文件,包含 YAML frontmatter 和固定的内容结构。
+
+### 文件位置
+
+```
+knowledge-base/slices/{product}/{ability}.md          # 产品级概览(跨平台通用)
+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`。
+> **平台实现文件模板**:新建平台 slice 时,请复制 [`platform-slice-template.md`](platform-slice-template.md) 并按批注填写。填写范例见 `slices/live/ios/coguest-apply.md`。
+
+### Section 标签约定
+
+每个 section 标题后面统一标注三种标签之一:
+每个 section 标题后面统一标注三种标签之一:
+
+| 标签 | 含义 | 省略规则 |
+|------|------|---------|
+| `[必填]` | 必须写,否则 slice 不合格 | 不可省 |
+| `[可选]` | 视情况写,不影响合格 | 可整段删除 |
+| `[条件必填:<触发条件>]` | 满足条件时必须写 | 不满足时可整段删除 |
+| `[必填]` | 必须写,否则 slice 不合格 | 不可省 |
+| `[可选]` | 视情况写,不影响合格 | 可整段删除 |
+| `[条件必填:<触发条件>]` | 满足条件时必须写 | 不满足时可整段删除 |
+
+示例:
+示例:
+```markdown
+## 功能说明 [必填]
+## 调用时序 [条件必填:异步回调嵌套 ≥3 层 或 涉及 3 个及以上角色]
+## 调用时序 [条件必填:异步回调嵌套 ≥3 层 或 涉及 3 个及以上角色]
+## 关联知识 [可选]
+```
+
+### Frontmatter 字段
+
+```yaml
+---
+id: chat/msg-send           # [必填] Slice ID，与对应的 per-product platform index 中的 id 一致
+name: 发送消息               # [必填] Slice 名称
+product: chat               # [必填] 所属产品
+tags: [message, send, ...]  # [必填] 搜索标签,至少 3 个
+tags: [message, send, ...]  # [必填] 搜索标签,至少 3 个
+platforms: [web, android, ios, flutter]  # [必填] 支持的平台
+related:                    # [可选] 关联的 slice
+related:                    # [可选] 关联的 slice
+  - chat/msg-receive
+  - chat/msg-custom
+---
+```
+
+> **官方文档链接统一放在平台实现文件的 `api_docs` 字段**,产品级概览不放文档链接——因为教程/指南页通常按平台区分。
+> **官方文档链接统一放在平台实现文件的 `api_docs` 字段**,产品级概览不放文档链接——因为教程/指南页通常按平台区分。
+
+#### 必填项语义三件套(Frontmatter)
+
+- **违反后果**:字段缺失或与 index.yaml 不一致 → AI 路由到错误 slice / 找不到平台实现 → 用户报"找不到"bug → 维护者排查 1 小时定位到 frontmatter 错字
+- **验证手段**:`python scripts/validate_frontmatter.py {file}`(检查必填字段齐全 + 与 index.yaml 一致)
+- **绕过条件**:无
+
+---
+#### 必填项语义三件套(Frontmatter)
+
+- **违反后果**:字段缺失或与 index.yaml 不一致 → AI 路由到错误 slice / 找不到平台实现 → 用户报"找不到"bug → 维护者排查 1 小时定位到 frontmatter 错字
+- **验证手段**:`python scripts/validate_frontmatter.py {file}`(检查必填字段齐全 + 与 index.yaml 一致)
+- **绕过条件**:无
+
+---
+
+### 内容结构
+
+#### 产品级概览(`{product}/{ability}.md`)
+#### 产品级概览(`{product}/{ability}.md`)
+
+产品级概览是**跨平台通用**的,描述"做什么"和"为什么",不涉及"怎么做"。
+产品级概览是**跨平台通用**的,描述"做什么"和"为什么",不涉及"怎么做"。
+
+##### 平台无关性规则
+##### 平台无关性规则
+
+| ✅ 可以出现 | ❌ 不可以出现 |
+|-------------|-------------|
+| 操作语义("观众发起连麦申请") | 具体 API 签名(`applyForSeat(seatIndex:timeout:)` 这种 Swift 命名参数风格) |
+| 通用概念名("连麦管理器"、"事件流") | 平台特有类名/机制(`PassthroughSubject`、`ViewController`、`cancellable`) |
+| 行为级最佳实践("通过前不要开设备") | 代码结构级约束("`[weak self]` 避免循环引用") |
+| 通用排障逻辑("检查主播端是否订阅了事件") | 平台特有排障("检查 cancellable 是否被提前释放") |
+| 操作语义("观众发起连麦申请") | 具体 API 签名(`applyForSeat(seatIndex:timeout:)` 这种 Swift 命名参数风格) |
+| 通用概念名("连麦管理器"、"事件流") | 平台特有类名/机制(`PassthroughSubject`、`ViewController`、`cancellable`) |
+| 行为级最佳实践("通过前不要开设备") | 代码结构级约束("`[weak self]` 避免循环引用") |
+| 通用排障逻辑("检查主播端是否订阅了事件") | 平台特有排障("检查 cancellable 是否被提前释放") |
+| 跨平台统一的错误码 | 仅某平台出现的错误码或异常行为 |
+
+##### 自查方法
+
+把文件中所有 API 名、类名、术语逐一过一遍——如果一个 Android 开发者读到它会觉得困惑或不适用,那就是平台特有内容,应下沉到平台文件。
+
+✅ **自查正例**(产品级概览):
+> 「观众通过『连麦管理器』调用申请操作,主播端通过『事件流』收到申请通知。申请超时由 SDK 内部计时器控制,默认 30 秒。」
+- 用了通用概念名("连麦管理器""事件流"),iOS/Android/Web 开发者读了都能对应到自己的 API
+- 默认值"30 秒"是跨平台一致的常量,可以写
+
+❌ **自查反例**(产品级概览混入平台细节):
+> 「观众调用 `CoGuestStore.shared.applyForSeat(timeout:)`,主播端通过 `PassthroughSubject` 订阅 `applicationReceived` 事件,记得用 `[weak self]` 避免循环引用。」
+- `CoGuestStore.shared.xxx` = Swift 单例语法,Android 开发者懵
+- `PassthroughSubject` = Combine 框架特有,iOS 之外不存在
+- `[weak self]` = Swift 内存管理,跨平台无意义
+- → 整段下沉到 `live/ios/coguest-apply.md`
+
+##### 文件骨架
+##### 自查方法
+
+把文件中所有 API 名、类名、术语逐一过一遍——如果一个 Android 开发者读到它会觉得困惑或不适用,那就是平台特有内容,应下沉到平台文件。
+
+✅ **自查正例**(产品级概览):
+> 「观众通过『连麦管理器』调用申请操作,主播端通过『事件流』收到申请通知。申请超时由 SDK 内部计时器控制,默认 30 秒。」
+- 用了通用概念名("连麦管理器""事件流"),iOS/Android/Web 开发者读了都能对应到自己的 API
+- 默认值"30 秒"是跨平台一致的常量,可以写
+
+❌ **自查反例**(产品级概览混入平台细节):
+> 「观众调用 `CoGuestStore.shared.applyForSeat(timeout:)`,主播端通过 `PassthroughSubject` 订阅 `applicationReceived` 事件,记得用 `[weak self]` 避免循环引用。」
+- `CoGuestStore.shared.xxx` = Swift 单例语法,Android 开发者懵
+- `PassthroughSubject` = Combine 框架特有,iOS 之外不存在
+- `[weak self]` = Swift 内存管理,跨平台无意义
+- → 整段下沉到 `live/ios/coguest-apply.md`
+
+##### 文件骨架
+
+```markdown
+# {名称}(产品级概览)
+# {名称}(产品级概览)
+
+## 功能说明 [必填]
+## 核心概念 [必填]
+## 最佳实践 [必填]
+### ✅ ALWAYS(必须做的)
+### ❌ NEVER(绝不要做的)
+### ✅ ALWAYS(必须做的)
+### ❌ NEVER(绝不要做的)
+## 排障指南 [必填]
+### 常见错误码
+### 排障流程
+## 关联知识 [可选]
+```
+
+各 section 详细要求见下方。
+
+---
+
+##### 功能说明 [必填]
+
+###### 1️⃣ 你必须写什么
+一段 100-200 字的散文,回答三个问题:
+- 这个能力解决什么问题(用客户的语言,不用 SDK 术语)
+- 典型业务场景举 1-2 个
+- 最低 SDK 版本要求(若有)
+
+###### 2️⃣ 写作模板
+```markdown
+## 功能说明
+
+{能力名}解决 {具体业务问题}。典型场景包括 {场景 1}、{场景 2}。
+
+要求 SDK 版本 ≥ {version}。{若有跨平台版本差异,说明}。
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/multi-instance)
+```markdown
+## 功能说明
+
+多端登录指同一用户在多个设备(手机、平板、Web)同时登录 IM 账号的能力。
+解决的问题是:用户在手机上聊天,切换到电脑也能继续,不需要被强制踢下线。
+典型场景:企业 IM(电脑+手机同时在线)、客服系统(坐席多端备份)。
+
+要求 IM SDK ≥ 7.0,需要在控制台开通"多端登录"套餐(基础版不支持)。
+```
+
+为什么这是正例:
+- ✅ 第一句用客户语言("同时登录")而非 SDK 术语("multi-instance")
+- ✅ 写出了"解决什么问题",新人 30 秒能 get
+- ✅ 给了 2 个具体场景,不是空洞的"很多场景"
+- ✅ 标注了版本和套餐要求(常见踩坑点)
+
+###### 4️⃣ ❌ 反例
+```markdown
+## 功能说明
+
+本 slice 介绍 multi-instance 功能。该功能允许用户在多端登录,
+具体使用方式参见后续章节。
+```
+
+为什么这是反例:
+- ❌ "本 slice 介绍" = 元描述,AI 拿不到任何业务信息
+- ❌ "具体使用方式参见后续章节" = 偷懒,等于没写
+- ❌ 没说解决什么问题、没场景、没版本要求
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:功能说明缺失或空洞 → AI 路由准确率下降 30%+(无法判断是否匹配用户意图)→ 客户问对了问题但被引到错误 slice
+- **验证手段**:人工 review,逐条对照"三个问题"是否答全;字数 100-200 之间
+- **绕过条件**:无
+
+---
+
+##### 核心概念 [必填]
+
+###### 1️⃣ 你必须写什么
+用**操作名 + 语义描述**列出该能力涉及的核心概念。不写平台特有 API 签名。
+若有状态机/角色关系,画出来。
+
+###### 2️⃣ 写作模板
+```markdown
+## 核心概念
+
+### 涉及角色
+- **{角色 1}**:{这个角色做什么}
+- **{角色 2}**:{这个角色做什么}
+
+### 关键操作
+| 操作名 | 语义 | 触发方 |
+|--------|------|--------|
+| {操作 1} | {做了什么} | {谁触发} |
+| {操作 2} | {做了什么} | {谁触发} |
+
+### 状态机(如有)
+{状态 A} → [{触发事件}] → {状态 B} → [{事件}] → {状态 C}
+```
+
+###### 3️⃣ ✅ 正例(摘自 live/coguest-apply)
+```markdown
+## 核心概念
+
+### 涉及角色
+- **观众(Audience)**:发起连麦申请的一方,等待主播同意后上麦
+- **主播(Host)**:接收申请并决定是否同意的一方,有最终决策权
+
+### 关键操作
+| 操作名 | 语义 | 触发方 |
+|--------|------|--------|
+| 申请连麦 | 观众请求加入主播的麦位,带超时(默认 30s) | 观众 |
+| 同意申请 | 主播接受请求,观众变为连麦者 | 主播 |
+| 拒绝申请 | 主播拒绝请求,观众回到观众态 | 主播 |
+| 取消申请 | 观众主动撤回未处理的申请 | 观众 |
+
+### 状态机
+观众态 → [申请连麦] → 申请中 → [主播同意] → 连麦中
+                          → [主播拒绝/超时] → 观众态
+                          → [观众取消] → 观众态
+```
+
+为什么这是正例:
+- ✅ 角色定义在最前,后续操作都基于角色
+- ✅ 每个操作有"触发方"列,明确谁能做什么
+- ✅ 状态机用纯文字+箭头,不依赖任何平台框架
+- ✅ 整段没出现任何 Swift/Kotlin/JS 语法
+
+###### 4️⃣ ❌ 反例
+```markdown
+## 核心概念
+
+观众调用 `CoGuestStore.shared.applyForSeat(timeout: 30)` 发起申请,
+主播订阅 `applicationReceived` 事件接收。申请超时会触发 `.failure` 回调。
+```
+
+为什么这是反例:
+- ❌ `CoGuestStore.shared.xxx` = iOS Swift 语法 → 平台特有
+- ❌ `.failure` = Swift Result 类型 → 平台特有
+- ❌ 没区分角色、没状态机
+- → 应整段下沉到 `live/ios/coguest-apply.md`,产品级概览改写为操作语义
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:出现平台特有 API → 跨平台 AI 生成时混淆(Android 开发者拿到 iOS 代码)→ 编译报错投诉
+- **验证手段**:人工 review,过一遍每个 backtick 内的标识符,任一是平台特有 → 打回
+- **绕过条件**:无
+
+---
+
+##### 最佳实践 - ALWAYS [必填,至少 3 条]
+
+###### 1️⃣ 你必须写什么
+列出**行为级**的"必须做的事"。描述"该做什么",不指定"用哪个 API 做"。
+
+###### 2️⃣ 写作模板
+```markdown
+### ✅ ALWAYS
+
+- **必须 {具体行为}** —— {为什么这样做,不这样做的具体后果}。
+- **必须 {具体行为}** —— {后果}。
+- **必须 {具体行为}** —— {后果}。
+```
+
+###### 3️⃣ ✅ 正例(摘自 live/coguest-apply)
+```markdown
+### ✅ ALWAYS
+
+- **必须等主播同意后再开摄像头/麦克风** —— 提前开会让用户以为已上麦,
+  实际未上麦时画面没人看,造成隐私焦虑。
+- **必须为申请操作设置超时** —— 主播长时间不响应时,观众端 UI 卡住,
+  用户以为 App 崩溃。建议默认 30 秒。
+- **必须在断开连麦时关闭设备** —— 否则摄像头指示灯一直亮,被用户截图发微博
+  投诉"偷拍"。
+```
+
+为什么这是正例:
+- ✅ 用强动词("必须等""必须设置""必须关闭"),不用"建议""最好"
+- ✅ 每条都说明了**具体后果**(隐私焦虑/UI 卡住/被投诉偷拍)
+- ✅ 「2024 年发生过」= 失败记忆锚定,让规则有真实重量
+- ✅ 描述行为不指定 API,跨平台都适用
+
+###### 4️⃣ ❌ 反例
+```markdown
+### ✅ ALWAYS
+
+- 建议处理好申请超时的情况。
+- 注意设备的开关时机。
+- 一般来说要给用户友好的提示。
+```
+
+为什么这是反例:
+- ❌ "建议/注意/一般来说" = 软词 → AI 视作可选 → 跳过
+- ❌ "处理好""友好" = 模糊形容词 → AI 不知道具体做什么
+- ❌ 没说后果 → 新人不会重视
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:ALWAYS 不到 3 条 / 含软词("建议""最好""一般来说""尽量")/ 缺少后果说明 → slice 不可合并
+- **验证手段**:
+  ```bash
+  grep -E "建议|最好|一般来说|尽量|可能" {file}  # 必须命中 0 次
+  # ALWAYS 条目数 ≥ 3
+  ```
+- **绕过条件**:能力极简单(<10 行代码)且无历史踩坑 → 可降至 2 条,需在 PR 中证明
+
+---
+
+##### 最佳实践 - NEVER [必填,至少 3 条]
+
+###### 1️⃣ 你必须写什么
+列出用户在该能力上**真实踩过坑**的反向规则。
+NEVER 的本质 = 反合理化——预先驳斥"为什么我可以这样做"的借口。
+
+###### 2️⃣ 写作模板
+```markdown
+### ❌ NEVER
+
+- **绝不要 {具体行为}** —— {如果做了会发生什么具体后果}。
+  即使 {常见的合理化借口},也不可以——{反驳}。
+
+- **绝不要 {具体行为}** —— {后果}。
+  即使 {借口},也不可以——{反驳}。
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/multi-instance)
+```markdown
+### ❌ NEVER
+
+- **绝不要在收到互踢回调时立刻自动重新登录** —— 会形成两端死循环互踢,
+  最终两端都登不上去。即使"用户体验考虑想自动恢复",也不可以——
+  正确做法是弹窗让用户选择(本端继续 / 切回原端)。
+
+- **绝不要把 SDKAppID 和 SecretKey 写在客户端代码里** —— SecretKey 泄露后
+  攻击者可签发任意身份 UserSig。即使"只是 demo 临时用",也不可以——
+  demo 也会被截图、被复制到生产代码。
+
+- **绝不要在登录未完成时调用任何业务 API** —— SDK 内部状态未就绪,
+  调用结果不可预期(可能返回成功但实际未发送)。即使"看起来登录已经
+  发起了",也不可以——必须等 onLoginSuccess 回调。
+```
+
+为什么这是正例:
+- ✅ 用了"绝不要"的**强化语义**,而非"建议不要"
+- ✅ 每条都说明了**具体后果**(死循环 / SecretKey 泄露 / 静默失败)
+- ✅ 预先驳斥了**常见借口**(用户体验 / 只是 demo / 看起来发起了)——这是反合理化
+- ✅ 给出了**替代行为**(弹窗 / 服务端签发 / 等回调)
+
+###### 4️⃣ ❌ 反例
+```markdown
+### ❌ NEVER
+
+- 不建议在互踢回调里自动重登,可能会有问题。
+- 注意 SecretKey 的安全性,最好不要放客户端。
+- 一般来说要处理好登录失败的情况。
+```
+
+为什么这是反例:
+- ❌ "不建议 / 最好 / 一般来说" = 软词,AI 读到判断"可选"而跳过
+- ❌ "可能会有问题" = 没说清后果,新人不会重视
+- ❌ "处理好" = 模糊动词,AI 不知道具体要做什么
+- ❌ 没有反合理化——AI 想跳过时找不到反驳
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:NEVER 不到 3 条 / 含软词 / 缺少后果说明 / 缺少反合理化 → slice 不可合并
+- **验证手段**:
+  ```bash
+  grep -E "不建议|最好|一般来说|可能|建议不要" {file}  # 命中 0 次
+  # NEVER 条目数 ≥ 3
+  # 每条必须含"即使...也不可以"或等价反驳句式
+  ```
+- **绕过条件**:能力本身简单到没有踩坑历史(需在 PR 中证明:搜过 ticket、issue、客户群均无相关问题)
+
+---
+
+##### 排障指南 - 常见错误码 [必填]
+
+###### 1️⃣ 你必须写什么
+列出**跨平台统一**的错误码及其含义、原因、处理动作。仅某平台特有的错误码下沉到平台文件。
+
+###### 2️⃣ 写作模板
+```markdown
+### 常见错误码
+
+| 错误码 | 含义 | 常见原因 | 处理动作 |
+|--------|------|---------|---------|
+| {code} | {一句话含义} | {原因 1} / {原因 2} | {具体动作} |
+| {code} | ... | ... | ... |
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/multi-instance)
+```markdown
+### 常见错误码
+
+| 错误码 | 含义 | 常见原因 | 处理动作 |
+|--------|------|---------|---------|
+| 6206 | 互踢:被同账号其他端踢下线 | 用户在新设备登录;策略=互踢模式 | 弹窗提示用户「您的账号已在其他设备登录」,不要自动重登 |
+| 6208 | 多端登录数超限 | 当前套餐允许的端数已满 | 提示用户先在其他设备退出;或升级套餐 |
+| 70001 | UserSig 校验失败 | UserSig 过期 / 错误 / SDKAppID 不匹配 | 重新从服务端获取 UserSig,不要重试当前 sig |
+```
+
+为什么这是正例:
+- ✅ 4 列结构清晰,每列职责单一
+- ✅ "常见原因"列了 ≥1 个具体原因,不是泛化的"网络问题"
+- ✅ "处理动作"是**具体动作**("弹窗提示""不要自动重登"),不是"处理一下"
+- ✅ 错误码用真实数字,不是 `XXX001`
+
+###### 4️⃣ ❌ 反例
+```markdown
+### 常见错误码
+
+错误码很多,常见的有 6206、6208 等。具体含义参见官方文档。
+出错时一般可以重试或联系技术支持。
+```
+
+为什么这是反例:
+- ❌ 不是表格,无法被 AI 结构化提取
+- ❌ "参见官方文档" = 偷懒,AI 拿不到信息
+- ❌ "可以重试" = 错!互踢错误重试会死循环
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:错误码缺失或处理动作错误 → AI 生成的错误处理代码会让用户陷入死循环或静默失败
+- **验证手段**:必须是表格格式;每行 4 列齐全;"处理动作"列不含"重试""联系技术支持"等空洞词
+- **绕过条件**:该能力没有专属错误码(全部走通用错误码),需在 PR 说明并引用 `{product}/error-codes`
+
+---
+
+##### 排障指南 - 排障流程 [必填]
+
+###### 1️⃣ 你必须写什么
+画一棵**通用排障树**:从症状出发,按"先查什么、再查什么"的顺序展开。平台特有分支标注 → 见平台文件。
+
+###### 2️⃣ 写作模板
+```markdown
+### 排障流程
+
+症状:{用户报的现象}
+├─ 检查 {基础项 1}? 
+│   ├─ 是 → 继续
+│   └─ 否 → {处理动作}
+├─ 检查 {基础项 2}?
+│   ├─ 是 → 继续
+│   └─ 否 → {处理动作}
+└─ 都正常但仍有问题 → 见平台文件 / 升级支持
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/msg-send)
+```markdown
+### 排障流程
+
+症状:消息发送返回失败 / 长时间无回调
+
+├─ 登录是否完成?(loginStatus == LOGGED_IN)
+│   ├─ 是 → 继续
+│   └─ 否 → 等待 onLoginSuccess 后重发(→ chat/login-auth)
+├─ 错误码是否为 70001(UserSig 失败)?
+│   ├─ 是 → 重新从服务端获取 UserSig,不要本地重试
+│   └─ 否 → 继续
+├─ 错误码是否为 80001(消息内容违规)?
+│   ├─ 是 → 检查文本是否含敏感词,提示用户修改内容
+│   └─ 否 → 继续
+├─ 接收方是否被发送方加入黑名单?
+│   ├─ 否 → 继续
+│   └─ 是 → 提示"对方拒绝接收消息"
+└─ 都正常但仍失败 → 平台特有排障(→ chat/{platform}/msg-send)
+```
+
+为什么这是正例:
+- ✅ 从症状出发,符合客户思维顺序
+- ✅ 每个检查项都有"是/否"分支,不留模糊
+- ✅ 引用了其他 slice(`chat/login-auth`、`chat/{platform}/msg-send`),不重复
+- ✅ 兜底分支明确(平台文件)
+
+###### 4️⃣ ❌ 反例
+```markdown
+### 排障流程
+
+如果消息发不出去,先检查网络,再检查登录状态,然后看错误码。
+还不行就联系技术支持。
+```
+
+为什么这是反例:
+- ❌ 不是树形结构,AI 无法按顺序提取检查项
+- ❌ "先...再...然后" = 模糊顺序,没说"否"分支怎么办
+- ❌ "联系技术支持" = 兜底没意义,AI 拿不到任何动作
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:排障流程不成树/不可执行 → AI 排障建议变成"再试一次/联系技术支持"等无效话术 → 用户报"AI 没用"
+- **验证手段**:必须是树形(用 `├─└─` 或类似)、每个分支有明确"是/否"、兜底必须指向具体 slice 或行动
+- **绕过条件**:无
+
+---
+
+##### 关联知识 [可选]
+
+引用相关 slice。如果没有关联,删除整个 section。
+有 ≥2 相关 slice 时**必填**(防止知识孤岛)。
+
+```markdown
+## 关联知识
+
+- [chat/login-auth](./login-auth.md) — 登录认证(本 slice 的前置)
+- [chat/error-codes](./error-codes.md) — 完整错误码总表
+```
+
+---
+
+##### 产品级概览各 section 的必填理由
+
+- `功能说明` / `核心概念` — slice 的身份标识,缺失则无法理解 slice 是做什么的
+- `最佳实践` — slice 区别于官方文档的核心价值。仅抄 API 说明,无需做 slice
+- `排障指南` — slice 面向集成场景的交付标准。至少给出「常见错误码」和「排障流程」两个子项,否则客户报问题时无章可循
+- `关联知识` — 孤立能力可省。有 2+ 相关 slice 时必须写,防止知识孤岛
+```
+
+各 section 详细要求见下方。
+
+---
+
+##### 功能说明 [必填]
+
+###### 1️⃣ 你必须写什么
+一段 100-200 字的散文,回答三个问题:
+- 这个能力解决什么问题(用客户的语言,不用 SDK 术语)
+- 典型业务场景举 1-2 个
+- 最低 SDK 版本要求(若有)
+
+###### 2️⃣ 写作模板
+```markdown
+## 功能说明
+
+{能力名}解决 {具体业务问题}。典型场景包括 {场景 1}、{场景 2}。
+
+要求 SDK 版本 ≥ {version}。{若有跨平台版本差异,说明}。
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/multi-instance)
+```markdown
+## 功能说明
+
+多端登录指同一用户在多个设备(手机、平板、Web)同时登录 IM 账号的能力。
+解决的问题是:用户在手机上聊天,切换到电脑也能继续,不需要被强制踢下线。
+典型场景:企业 IM(电脑+手机同时在线)、客服系统(坐席多端备份)。
+
+要求 IM SDK ≥ 7.0,需要在控制台开通"多端登录"套餐(基础版不支持)。
+```
+
+为什么这是正例:
+- ✅ 第一句用客户语言("同时登录")而非 SDK 术语("multi-instance")
+- ✅ 写出了"解决什么问题",新人 30 秒能 get
+- ✅ 给了 2 个具体场景,不是空洞的"很多场景"
+- ✅ 标注了版本和套餐要求(常见踩坑点)
+
+###### 4️⃣ ❌ 反例
+```markdown
+## 功能说明
+
+本 slice 介绍 multi-instance 功能。该功能允许用户在多端登录,
+具体使用方式参见后续章节。
+```
+
+为什么这是反例:
+- ❌ "本 slice 介绍" = 元描述,AI 拿不到任何业务信息
+- ❌ "具体使用方式参见后续章节" = 偷懒,等于没写
+- ❌ 没说解决什么问题、没场景、没版本要求
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:功能说明缺失或空洞 → AI 路由准确率下降 30%+(无法判断是否匹配用户意图)→ 客户问对了问题但被引到错误 slice
+- **验证手段**:人工 review,逐条对照"三个问题"是否答全;字数 100-200 之间
+- **绕过条件**:无
+
+---
+
+##### 核心概念 [必填]
+
+###### 1️⃣ 你必须写什么
+用**操作名 + 语义描述**列出该能力涉及的核心概念。不写平台特有 API 签名。
+若有状态机/角色关系,画出来。
+
+###### 2️⃣ 写作模板
+```markdown
+## 核心概念
+
+### 涉及角色
+- **{角色 1}**:{这个角色做什么}
+- **{角色 2}**:{这个角色做什么}
+
+### 关键操作
+| 操作名 | 语义 | 触发方 |
+|--------|------|--------|
+| {操作 1} | {做了什么} | {谁触发} |
+| {操作 2} | {做了什么} | {谁触发} |
+
+### 状态机(如有)
+{状态 A} → [{触发事件}] → {状态 B} → [{事件}] → {状态 C}
+```
+
+###### 3️⃣ ✅ 正例(摘自 live/coguest-apply)
+```markdown
+## 核心概念
+
+### 涉及角色
+- **观众(Audience)**:发起连麦申请的一方,等待主播同意后上麦
+- **主播(Host)**:接收申请并决定是否同意的一方,有最终决策权
+
+### 关键操作
+| 操作名 | 语义 | 触发方 |
+|--------|------|--------|
+| 申请连麦 | 观众请求加入主播的麦位,带超时(默认 30s) | 观众 |
+| 同意申请 | 主播接受请求,观众变为连麦者 | 主播 |
+| 拒绝申请 | 主播拒绝请求,观众回到观众态 | 主播 |
+| 取消申请 | 观众主动撤回未处理的申请 | 观众 |
+
+### 状态机
+观众态 → [申请连麦] → 申请中 → [主播同意] → 连麦中
+                          → [主播拒绝/超时] → 观众态
+                          → [观众取消] → 观众态
+```
+
+为什么这是正例:
+- ✅ 角色定义在最前,后续操作都基于角色
+- ✅ 每个操作有"触发方"列,明确谁能做什么
+- ✅ 状态机用纯文字+箭头,不依赖任何平台框架
+- ✅ 整段没出现任何 Swift/Kotlin/JS 语法
+
+###### 4️⃣ ❌ 反例
+```markdown
+## 核心概念
+
+观众调用 `CoGuestStore.shared.applyForSeat(timeout: 30)` 发起申请,
+主播订阅 `applicationReceived` 事件接收。申请超时会触发 `.failure` 回调。
+```
+
+为什么这是反例:
+- ❌ `CoGuestStore.shared.xxx` = iOS Swift 语法 → 平台特有
+- ❌ `.failure` = Swift Result 类型 → 平台特有
+- ❌ 没区分角色、没状态机
+- → 应整段下沉到 `live/ios/coguest-apply.md`,产品级概览改写为操作语义
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:出现平台特有 API → 跨平台 AI 生成时混淆(Android 开发者拿到 iOS 代码)→ 编译报错投诉
+- **验证手段**:人工 review,过一遍每个 backtick 内的标识符,任一是平台特有 → 打回
+- **绕过条件**:无
+
+---
+
+##### 最佳实践 - ALWAYS [必填,至少 3 条]
+
+###### 1️⃣ 你必须写什么
+列出**行为级**的"必须做的事"。描述"该做什么",不指定"用哪个 API 做"。
+
+###### 2️⃣ 写作模板
+```markdown
+### ✅ ALWAYS
+
+- **必须 {具体行为}** —— {为什么这样做,不这样做的具体后果}。
+- **必须 {具体行为}** —— {后果}。
+- **必须 {具体行为}** —— {后果}。
+```
+
+###### 3️⃣ ✅ 正例(摘自 live/coguest-apply)
+```markdown
+### ✅ ALWAYS
+
+- **必须等主播同意后再开摄像头/麦克风** —— 提前开会让用户以为已上麦,
+  实际未上麦时画面没人看,造成隐私焦虑。
+- **必须为申请操作设置超时** —— 主播长时间不响应时,观众端 UI 卡住,
+  用户以为 App 崩溃。建议默认 30 秒。
+- **必须在断开连麦时关闭设备** —— 否则摄像头指示灯一直亮,被用户截图发微博
+  投诉"偷拍"。
+```
+
+为什么这是正例:
+- ✅ 用强动词("必须等""必须设置""必须关闭"),不用"建议""最好"
+- ✅ 每条都说明了**具体后果**(隐私焦虑/UI 卡住/被投诉偷拍)
+- ✅ 「2024 年发生过」= 失败记忆锚定,让规则有真实重量
+- ✅ 描述行为不指定 API,跨平台都适用
+
+###### 4️⃣ ❌ 反例
+```markdown
+### ✅ ALWAYS
+
+- 建议处理好申请超时的情况。
+- 注意设备的开关时机。
+- 一般来说要给用户友好的提示。
+```
+
+为什么这是反例:
+- ❌ "建议/注意/一般来说" = 软词 → AI 视作可选 → 跳过
+- ❌ "处理好""友好" = 模糊形容词 → AI 不知道具体做什么
+- ❌ 没说后果 → 新人不会重视
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:ALWAYS 不到 3 条 / 含软词("建议""最好""一般来说""尽量")/ 缺少后果说明 → slice 不可合并
+- **验证手段**:
+  ```bash
+  grep -E "建议|最好|一般来说|尽量|可能" {file}  # 必须命中 0 次
+  # ALWAYS 条目数 ≥ 3
+  ```
+- **绕过条件**:能力极简单(<10 行代码)且无历史踩坑 → 可降至 2 条,需在 PR 中证明
+
+---
+
+##### 最佳实践 - NEVER [必填,至少 3 条]
+
+###### 1️⃣ 你必须写什么
+列出用户在该能力上**真实踩过坑**的反向规则。
+NEVER 的本质 = 反合理化——预先驳斥"为什么我可以这样做"的借口。
+
+###### 2️⃣ 写作模板
+```markdown
+### ❌ NEVER
+
+- **绝不要 {具体行为}** —— {如果做了会发生什么具体后果}。
+  即使 {常见的合理化借口},也不可以——{反驳}。
+
+- **绝不要 {具体行为}** —— {后果}。
+  即使 {借口},也不可以——{反驳}。
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/multi-instance)
+```markdown
+### ❌ NEVER
+
+- **绝不要在收到互踢回调时立刻自动重新登录** —— 会形成两端死循环互踢,
+  最终两端都登不上去。即使"用户体验考虑想自动恢复",也不可以——
+  正确做法是弹窗让用户选择(本端继续 / 切回原端)。
+
+- **绝不要把 SDKAppID 和 SecretKey 写在客户端代码里** —— SecretKey 泄露后
+  攻击者可签发任意身份 UserSig。即使"只是 demo 临时用",也不可以——
+  demo 也会被截图、被复制到生产代码。
+
+- **绝不要在登录未完成时调用任何业务 API** —— SDK 内部状态未就绪,
+  调用结果不可预期(可能返回成功但实际未发送)。即使"看起来登录已经
+  发起了",也不可以——必须等 onLoginSuccess 回调。
+```
+
+为什么这是正例:
+- ✅ 用了"绝不要"的**强化语义**,而非"建议不要"
+- ✅ 每条都说明了**具体后果**(死循环 / SecretKey 泄露 / 静默失败)
+- ✅ 预先驳斥了**常见借口**(用户体验 / 只是 demo / 看起来发起了)——这是反合理化
+- ✅ 给出了**替代行为**(弹窗 / 服务端签发 / 等回调)
+
+###### 4️⃣ ❌ 反例
+```markdown
+### ❌ NEVER
+
+- 不建议在互踢回调里自动重登,可能会有问题。
+- 注意 SecretKey 的安全性,最好不要放客户端。
+- 一般来说要处理好登录失败的情况。
+```
+
+为什么这是反例:
+- ❌ "不建议 / 最好 / 一般来说" = 软词,AI 读到判断"可选"而跳过
+- ❌ "可能会有问题" = 没说清后果,新人不会重视
+- ❌ "处理好" = 模糊动词,AI 不知道具体要做什么
+- ❌ 没有反合理化——AI 想跳过时找不到反驳
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:NEVER 不到 3 条 / 含软词 / 缺少后果说明 / 缺少反合理化 → slice 不可合并
+- **验证手段**:
+  ```bash
+  grep -E "不建议|最好|一般来说|可能|建议不要" {file}  # 命中 0 次
+  # NEVER 条目数 ≥ 3
+  # 每条必须含"即使...也不可以"或等价反驳句式
+  ```
+- **绕过条件**:能力本身简单到没有踩坑历史(需在 PR 中证明:搜过 ticket、issue、客户群均无相关问题)
+
+---
+
+##### 排障指南 - 常见错误码 [必填]
+
+###### 1️⃣ 你必须写什么
+列出**跨平台统一**的错误码及其含义、原因、处理动作。仅某平台特有的错误码下沉到平台文件。
+
+###### 2️⃣ 写作模板
+```markdown
+### 常见错误码
+
+| 错误码 | 含义 | 常见原因 | 处理动作 |
+|--------|------|---------|---------|
+| {code} | {一句话含义} | {原因 1} / {原因 2} | {具体动作} |
+| {code} | ... | ... | ... |
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/multi-instance)
+```markdown
+### 常见错误码
+
+| 错误码 | 含义 | 常见原因 | 处理动作 |
+|--------|------|---------|---------|
+| 6206 | 互踢:被同账号其他端踢下线 | 用户在新设备登录;策略=互踢模式 | 弹窗提示用户「您的账号已在其他设备登录」,不要自动重登 |
+| 6208 | 多端登录数超限 | 当前套餐允许的端数已满 | 提示用户先在其他设备退出;或升级套餐 |
+| 70001 | UserSig 校验失败 | UserSig 过期 / 错误 / SDKAppID 不匹配 | 重新从服务端获取 UserSig,不要重试当前 sig |
+```
+
+为什么这是正例:
+- ✅ 4 列结构清晰,每列职责单一
+- ✅ "常见原因"列了 ≥1 个具体原因,不是泛化的"网络问题"
+- ✅ "处理动作"是**具体动作**("弹窗提示""不要自动重登"),不是"处理一下"
+- ✅ 错误码用真实数字,不是 `XXX001`
+
+###### 4️⃣ ❌ 反例
+```markdown
+### 常见错误码
+
+错误码很多,常见的有 6206、6208 等。具体含义参见官方文档。
+出错时一般可以重试或联系技术支持。
+```
+
+为什么这是反例:
+- ❌ 不是表格,无法被 AI 结构化提取
+- ❌ "参见官方文档" = 偷懒,AI 拿不到信息
+- ❌ "可以重试" = 错!互踢错误重试会死循环
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:错误码缺失或处理动作错误 → AI 生成的错误处理代码会让用户陷入死循环或静默失败
+- **验证手段**:必须是表格格式;每行 4 列齐全;"处理动作"列不含"重试""联系技术支持"等空洞词
+- **绕过条件**:该能力没有专属错误码(全部走通用错误码),需在 PR 说明并引用 `{product}/error-codes`
+
+---
+
+##### 排障指南 - 排障流程 [必填]
+
+###### 1️⃣ 你必须写什么
+画一棵**通用排障树**:从症状出发,按"先查什么、再查什么"的顺序展开。平台特有分支标注 → 见平台文件。
+
+###### 2️⃣ 写作模板
+```markdown
+### 排障流程
+
+症状:{用户报的现象}
+├─ 检查 {基础项 1}? 
+│   ├─ 是 → 继续
+│   └─ 否 → {处理动作}
+├─ 检查 {基础项 2}?
+│   ├─ 是 → 继续
+│   └─ 否 → {处理动作}
+└─ 都正常但仍有问题 → 见平台文件 / 升级支持
+```
+
+###### 3️⃣ ✅ 正例(摘自 chat/msg-send)
+```markdown
+### 排障流程
+
+症状:消息发送返回失败 / 长时间无回调
+
+├─ 登录是否完成?(loginStatus == LOGGED_IN)
+│   ├─ 是 → 继续
+│   └─ 否 → 等待 onLoginSuccess 后重发(→ chat/login-auth)
+├─ 错误码是否为 70001(UserSig 失败)?
+│   ├─ 是 → 重新从服务端获取 UserSig,不要本地重试
+│   └─ 否 → 继续
+├─ 错误码是否为 80001(消息内容违规)?
+│   ├─ 是 → 检查文本是否含敏感词,提示用户修改内容
+│   └─ 否 → 继续
+├─ 接收方是否被发送方加入黑名单?
+│   ├─ 否 → 继续
+│   └─ 是 → 提示"对方拒绝接收消息"
+└─ 都正常但仍失败 → 平台特有排障(→ chat/{platform}/msg-send)
+```
+
+为什么这是正例:
+- ✅ 从症状出发,符合客户思维顺序
+- ✅ 每个检查项都有"是/否"分支,不留模糊
+- ✅ 引用了其他 slice(`chat/login-auth`、`chat/{platform}/msg-send`),不重复
+- ✅ 兜底分支明确(平台文件)
+
+###### 4️⃣ ❌ 反例
+```markdown
+### 排障流程
+
+如果消息发不出去,先检查网络,再检查登录状态,然后看错误码。
+还不行就联系技术支持。
+```
+
+为什么这是反例:
+- ❌ 不是树形结构,AI 无法按顺序提取检查项
+- ❌ "先...再...然后" = 模糊顺序,没说"否"分支怎么办
+- ❌ "联系技术支持" = 兜底没意义,AI 拿不到任何动作
+- → review 时直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:排障流程不成树/不可执行 → AI 排障建议变成"再试一次/联系技术支持"等无效话术 → 用户报"AI 没用"
+- **验证手段**:必须是树形(用 `├─└─` 或类似)、每个分支有明确"是/否"、兜底必须指向具体 slice 或行动
+- **绕过条件**:无
+
+---
+
+##### 关联知识 [可选]
+
+引用相关 slice。如果没有关联,删除整个 section。
+有 ≥2 相关 slice 时**必填**(防止知识孤岛)。
+
+```markdown
+## 关联知识
+
+- [chat/login-auth](./login-auth.md) — 登录认证(本 slice 的前置)
+- [chat/error-codes](./error-codes.md) — 完整错误码总表
+```
+
+---
+
+##### 产品级概览各 section 的必填理由
+
+- `功能说明` / `核心概念` — slice 的身份标识,缺失则无法理解 slice 是做什么的
+- `最佳实践` — slice 区别于官方文档的核心价值。仅抄 API 说明,无需做 slice
+- `排障指南` — slice 面向集成场景的交付标准。至少给出「常见错误码」和「排障流程」两个子项,否则客户报问题时无章可循
+- `关联知识` — 孤立能力可省。有 2+ 相关 slice 时必须写,防止知识孤岛
+
+> 提交前对照第五节「产品级概览 DoD」逐条打勾,合格后再提交。
+
+---
+> 提交前对照第五节「产品级概览 DoD」逐条打勾,合格后再提交。
+
+---
+
+#### 平台实现文件(`{product}/{platform}/{ability}.md`)
+#### 平台实现文件(`{product}/{platform}/{ability}.md`)
+
+##### Frontmatter 字段
+
+```yaml
+---
+id: {product}/{ability}     # [必填] 与产品级 slice 的 id 一致
+platform: {platform}        # [必填] ios / android / web / flutter / electron
+api_docs:                   # [必填] 该平台 API 参考文档链接(至少 1 条)
+api_docs:                   # [必填] 该平台 API 参考文档链接(至少 1 条)
+  - title: {API 类名/模块名}
+    url: https://...
+---
+```
+
+> 注:`name` / `tags` / `platforms` / `related` 在产品级概览中维护,平台文件不重复。
+
+---
+
+##### `api_docs` 字段 [必填,至少 1 条]
+
+###### 1️⃣ 你必须写什么
+该平台 API 参考文档的**类/模块级**链接,AI 用它校验生成的 API 签名是否真实存在。
+
+###### 2️⃣ 写作模板
+```yaml
+api_docs:
+  - title: {本 slice 涉及的具体类名,如 CoGuestStore}
+    url: https://{平台 SDK 文档站}/.../{类名小写}/
+```
+
+判定链接是否合格:
+- 打开链接,**第一屏**就能看到本 slice 涉及的**具体类的方法签名**(参数名、参数类型、返回值)→ ✅ 合格
+- 第一屏只有概念介绍、教程文字 → ❌ 不合格
+
+###### 3️⃣ ✅ 正例(摘自 live/ios/coguest-apply)
+```yaml
+api_docs:
+  - title: CoGuestStore
+    url: https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore/
+  - title: DeviceStore
+    url: https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/
+```
+
+为什么这是正例:
+- ✅ 链接路径含 `/documentation/` → 是 API 参考站
+- ✅ 路径末尾是具体类名 `cogueststore` → 精确到类
+- ✅ slice 涉及两个 Store → 分别列出,不省略
+
+###### 4️⃣ ❌ 反例
+```yaml
+# 反例 1:SDK 首页
+api_docs:
+  - title: TRTC iOS SDK
+    url: https://trtc.io/sdk
+# → AI 拿首页内容当类签名,会生成不存在的 API
+
+# 反例 2:教程页
+api_docs:
+  - title: 连麦集成指南
+    url: https://trtc.io/zh/document/74598
+# → 教程页的 API 名常被简化(省命名空间),AI 会生成错误的引用语句
+
+# 反例 3:链接为空或 TODO
+api_docs:
+  - title: TODO
+    url: TODO
+# → 占位的链接永远不会被替换,半年后这条 slice 就是废的
+```
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:链接非类级 → AI 生成不存在的 API 名 → 客户编译报错投诉(2025-Q1 真实事故,接入 2 天后才发现)
+- **验证手段**:
+  ```bash
+  python scripts/validate_api_docs.py {file}
+  # 通过标准:每条 url 返回 200;url 含 `/documentation/` 或 `/api/`;
+  #          打开链接的页面 H1 必须包含 frontmatter 里的 title
+  ```
+- **绕过条件**:该平台官方确实无 API 参考站(如某些早期 Electron 模块)→ 必须填头文件 GitHub 永久链接(含 commit hash),且在 PR 中说明
+
+---
+> 注:`name` / `tags` / `platforms` / `related` 在产品级概览中维护,平台文件不重复。
+
+---
+
+##### `api_docs` 字段 [必填,至少 1 条]
+
+###### 1️⃣ 你必须写什么
+该平台 API 参考文档的**类/模块级**链接,AI 用它校验生成的 API 签名是否真实存在。
+
+###### 2️⃣ 写作模板
+```yaml
+api_docs:
+  - title: {本 slice 涉及的具体类名,如 CoGuestStore}
+    url: https://{平台 SDK 文档站}/.../{类名小写}/
+```
+
+判定链接是否合格:
+- 打开链接,**第一屏**就能看到本 slice 涉及的**具体类的方法签名**(参数名、参数类型、返回值)→ ✅ 合格
+- 第一屏只有概念介绍、教程文字 → ❌ 不合格
+
+###### 3️⃣ ✅ 正例(摘自 live/ios/coguest-apply)
+```yaml
+api_docs:
+  - title: CoGuestStore
+    url: https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore/
+  - title: DeviceStore
+    url: https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/
+```
+
+为什么这是正例:
+- ✅ 链接路径含 `/documentation/` → 是 API 参考站
+- ✅ 路径末尾是具体类名 `cogueststore` → 精确到类
+- ✅ slice 涉及两个 Store → 分别列出,不省略
+
+###### 4️⃣ ❌ 反例
+```yaml
+# 反例 1:SDK 首页
+api_docs:
+  - title: TRTC iOS SDK
+    url: https://trtc.io/sdk
+# → AI 拿首页内容当类签名,会生成不存在的 API
+
+# 反例 2:教程页
+api_docs:
+  - title: 连麦集成指南
+    url: https://trtc.io/zh/document/74598
+# → 教程页的 API 名常被简化(省命名空间),AI 会生成错误的引用语句
+
+# 反例 3:链接为空或 TODO
+api_docs:
+  - title: TODO
+    url: TODO
+# → 占位的链接永远不会被替换,半年后这条 slice 就是废的
+```
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:链接非类级 → AI 生成不存在的 API 名 → 客户编译报错投诉(2025-Q1 真实事故,接入 2 天后才发现)
+- **验证手段**:
+  ```bash
+  python scripts/validate_api_docs.py {file}
+  # 通过标准:每条 url 返回 200;url 含 `/documentation/` 或 `/api/`;
+  #          打开链接的页面 H1 必须包含 frontmatter 里的 title
+  ```
+- **绕过条件**:该平台官方确实无 API 参考站(如某些早期 Electron 模块)→ 必须填头文件 GitHub 永久链接(含 commit hash),且在 PR 中说明
+
+---
+
+##### 内容结构
+
+平台实现文件按以下结构编写,每个 section 标题都必须带必填/可选标签:
+平台实现文件按以下结构编写,每个 section 标题都必须带必填/可选标签:
+
+```markdown
+# {名称} — {平台} 实现
+
+## 前置条件 [必填]
+## 代码示例 [必填]
+## 调用时序 [条件必填:多角色异步交互 或 回调嵌套 ≥3 层]
+## 平台特有注意事项 [必填:至少 1 条]
+## 调用时序 [条件必填:多角色异步交互 或 回调嵌套 ≥3 层]
+## 平台特有注意事项 [必填:至少 1 条]
+## 代码生成约束 [必填]
+## 验证矩阵 [必填]
+```
+
+各 section 详细要求见下方。
+
+---
+
+##### 前置条件 [必填]
+
+###### 1️⃣ 你必须写什么
+列出本 slice 代码运行前必须满足的状态,**用引用形式**指向其他 slice,不要重复其他 slice 的安装/配置步骤。
+
+###### 2️⃣ 写作模板
+```markdown
+## 前置条件
+
+- 已完成 SDK 初始化(→ {product}/base-setup)
+- 已完成登录(→ {product}/login-auth),`LoginStore.shared.isLogin == true`
+- 已加入房间(→ {product}/room-lifecycle),房间状态 = JOINED
+- {本 slice 特有的额外前置条件}
+```
+
+###### 3️⃣ ✅ 正例
+```markdown
+## 前置条件
+
+- 已完成 SDK 初始化与登录(→ live/login-auth)
+- 已加入房间且角色为观众(→ live/room-lifecycle),`RoomStore.shared.localUser.role == .audience`
+- 主播端已开播且开启了"接受连麦申请"开关
+```
+
+为什么这是正例:
+- ✅ 用 `→ slice-id` 标注依赖,不重复说明怎么登录
+- ✅ 给出可机械验证的状态条件(`role == .audience`)
+- ✅ 包含跨角色前置(主播端配置)
+
+###### 4️⃣ ❌ 反例
+```markdown
+## 前置条件
 
-**类比**：如果 TRTC SDK 是一台车，slice 就是驾驶手册里的一个章节——"怎么启动"、"怎么倒车"、"怎么用定速巡航"，每一章独立可读，合在一起就是完整手册。
+要先安装 SDK 包 `pod 'TUIKit'`,然后调用 `LoginStore.login(userId:userSig:)` 登录,
+然后调用 `RoomStore.joinRoom(roomId:)` 加入房间,...
+```
+
+为什么这是反例:
+- ❌ 重复了 base-setup / login-auth 的内容
+- ❌ 这些内容会随版本变化,这里写一份等于埋雷
+- → 改为 `→ live/login-auth` 引用
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:重复其他 slice 内容 → 信息漂移(版本升级后这里没同步)→ AI 生成过时代码
+- **验证手段**:全文搜 `pod install`/`npm install`/`implementation` 等安装关键字 → 应命中 0 次(都已下沉到 base-setup)
+- **绕过条件**:无
 
 ---
 
-## 二、Slice 拆分标准
+##### 代码示例 [必填]
 
-### 核心原则
+###### 1️⃣ 你必须写什么
+能让 AI 直接学习并产出**可编译、可运行**的代码块。
+代码示例 = 这份 slice 给 AI 的"训练数据",每个细节都会被复制放大。
 
-> **一个 slice = 用户遇到一个具体问题时，我们能一次性讲清楚的内容。**
+###### 2️⃣ 6 条最低标准
+---
 
-### 判断方法：三个问题
+##### 前置条件 [必填]
 
-#### 问题 1：「能不能一次讲清楚？」
+###### 1️⃣ 你必须写什么
+列出本 slice 代码运行前必须满足的状态,**用引用形式**指向其他 slice,不要重复其他 slice 的安装/配置步骤。
 
-如果客户来问这个问题，技术支持能不能在**一次沟通**中完整解决？
+###### 2️⃣ 写作模板
+```markdown
+## 前置条件
 
-| 判断 | 举例 | 说明 |
-|------|------|------|
-| ✅ 合适 | "多端登录老是互踢怎么办？" | 讲清楚策略配置 + 回调处理 + 常见错误码就行 |
-| ✅ 合适 | "消息发不出去" | 讲清楚发送流程 + 权限检查 + 错误码就行 |
-| ❌ 太大了 | "消息功能怎么做？" | 发送、接收、历史记录、撤回、已读... 一次说不完 |
-| ❌ 太小了 | "怎么设置消息的优先级字段？" | 就一个参数，不值得单独做 |
+- 已完成 SDK 初始化(→ {product}/base-setup)
+- 已完成登录(→ {product}/login-auth),`LoginStore.shared.isLogin == true`
+- 已加入房间(→ {product}/room-lifecycle),房间状态 = JOINED
+- {本 slice 特有的额外前置条件}
+```
 
-**简单判断**：想象客户发来一条微信问这个问题，你用**一段话或一个截图**能不能回答？能 → 合适的粒度。需要连续发好几屏 → 太大。回复一句话就搞定 → 太小，可以合并到相关功能里。
+###### 3️⃣ ✅ 正例
+```markdown
+## 前置条件
 
-#### 问题 2：「出问题时，排查方向一样吗？」
+- 已完成 SDK 初始化与登录(→ live/login-auth)
+- 已加入房间且角色为观众(→ live/room-lifecycle),`RoomStore.shared.localUser.role == .audience`
+- 主播端已开播且开启了"接受连麦申请"开关
+```
 
-如果两个功能出问题后，排查思路完全不同，就应该拆成两个 slice。
+为什么这是正例:
+- ✅ 用 `→ slice-id` 标注依赖,不重复说明怎么登录
+- ✅ 给出可机械验证的状态条件(`role == .audience`)
+- ✅ 包含跨角色前置(主播端配置)
 
-| 场景 | 排查方向 | 结论 |
-|------|---------|------|
-| "消息发不出去" vs "收不到消息" | 发送查网络/权限/格式，接收查监听/登录状态/群设置 | → **拆成两个** |
-| "发文本消息" vs "发图片消息" | 都是查消息格式和网络 | → **合成一个**（发送消息） |
-| "主播无法开播" vs "连麦布局不对" | 开播查权限/配置，布局查模板参数 | → **拆成两个** |
+###### 4️⃣ ❌ 反例
+```markdown
+## 前置条件
 
-**简单判断**：客户报这两个问题的时候，你会不会分给同一个人处理？如果是，多半可以合并；如果你本能想找不同的人来看，就该拆开。
+要先安装 SDK 包 `pod 'TUIKit'`,然后调用 `LoginStore.login(userId:userSig:)` 登录,
+然后调用 `RoomStore.joinRoom(roomId:)` 加入房间,...
+```
 
-#### 问题 3：「是独立的用户动作吗？」
+为什么这是反例:
+- ❌ 重复了 base-setup / login-auth 的内容
+- ❌ 这些内容会随版本变化,这里写一份等于埋雷
+- → 改为 `→ live/login-auth` 引用
 
-一个 slice 应该对应一个用户能感知到的**独立操作步骤**。
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:重复其他 slice 内容 → 信息漂移(版本升级后这里没同步)→ AI 生成过时代码
+- **验证手段**:全文搜 `pod install`/`npm install`/`implementation` 等安装关键字 → 应命中 0 次(都已下沉到 base-setup)
+- **绕过条件**:无
 
-| 场景 | 用户动作 | 结论 |
-|------|---------|------|
-| 配置准备页 → 点开播 → 进入直播间 | 这是一个连贯动作 | → **一个** slice（主播开播） |
-| 选择连麦布局模板 | 独立的配置决策 | → **单独一个** slice |
-| 隐藏某个按钮 + 改文案 + 换图标 | 都是"改 UI 外观"这一个动作 | → **合成一个** slice（UI 定制） |
+---
 
-#### 问题 4：「能被多个场景复用吗？」
+##### 代码示例 [必填]
 
-一个 slice 应该能被 **2 个及以上** scenario（或其他 slice）引用。如果拆出来后只会被一个场景用到，通常说明它只是那个场景的一个步骤，而不是独立能力，应该合并回最相关的 slice。
+###### 1️⃣ 你必须写什么
+能让 AI 直接学习并产出**可编译、可运行**的代码块。
+代码示例 = 这份 slice 给 AI 的"训练数据",每个细节都会被复制放大。
 
-| 场景 | 复用性判断 | 结论 |
-|------|----------|------|
-| 「发送消息」 | 所有 Chat 相关 scenario 都会用 | → **独立 slice** |
-| 「进房」 | Live、Call、Room 所有场景共用 | → **独立 slice** |
-| 「主播开播前的网络探测提示」 | 只在「主播开播」这一个场景出现 | → **合并到 `live/anchor-lifecycle`** |
-| 「连麦申请时的倒计时 UI 定制」 | 只有「观众申请连麦」会用 | → **合并到 `live/coguest-apply`** |
+###### 2️⃣ 6 条最低标准
+
+| 维度 | 最低标准 |
+|------|---------|
+| **可编译** | 含完整 import、完整类/函数闭包,不允许 `...` 省略任何逻辑分支 |
+| **可运行** | 补充业务参数后可直接跑通;业务参数用 `{TODO: 填入 xxx}` 占位 |
+| **有日志锚点** | 关键路径(申请发送成功、主播同意、设备打开、失败分支)必须有 `print`/`console.log`/`Log.d`,带模块前缀如 `[CoGuest]` |
+| **有错误处理** | 每个 `.failure` / `catch` / `error` 分支必须有面向用户的处理(UI 可见的 `errorMessage` 或 `alert`),不允许只 `print` |
+| **多角色分开写** | 主播端 / 观众端这种异构角色,**必须**拆成独立示例代码块 |
+| **可组合性** | 对外暴露清晰输入/输出;依赖用注释标注 `// 前置:登录完成(→ live/login-auth)` |
+
+###### 3️⃣ 写作模板(以 iOS Swift 为例)
+````markdown
+### 场景 X:{场景名,如"观众发起连麦申请"}
+
+```swift
+// 前置:登录完成(→ chat/login-auth)
+// 前置:已加入房间(→ live/room-lifecycle)
+
+import TencentImSDKPlugin
+import Combine
+
+class CoGuestApplyViewModel: ObservableObject {
+    @Published var errorMessage: String?       // ← UI 必需,展示给用户
+    private var cancellables = Set<AnyCancellable>()
+
+    func applyForSeat() {
+        print("[CoGuest] 开始发起连麦申请")  // ← 日志锚点(供验证矩阵层级 3)
+
+        CoGuestStore.shared.applyForSeat(timeout: 30)
+            .sink { [weak self] completion in   // ← [weak self] 必需
+                if case .failure(let error) = completion {
+                    print("[CoGuest] 申请失败: \(error)")
+                    self?.errorMessage = "连麦申请失败,请重试"  // ← 用户可见
+                }
+            } receiveValue: { [weak self] _ in
+                print("[CoGuest] 申请已发送")
+                self?.errorMessage = nil
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+````
+
+###### 4️⃣ ❌ 反例
+```swift
+// 反例 1:用 ... 省略
+func applyForSeat() {
+    CoGuestStore.shared.applyForSeat(...) { result in
+        // 处理结果
+        ...
+    }
+}
+// → "..." 跳过了失败处理 → AI 学到这个模式后到处省略
+
+// 反例 2:仅 print 错误
+.sink { completion in
+    if case .failure(let error) = completion {
+        print("error: \(error)")   // ← 用户看不到!
+    }
+}
+// → 客户线上故障时用户只看到无反应
+
+// 反例 3:省略 import
+class XXX {
+    var cancellables = Set<AnyCancellable>()
+    // ↑ 没 import Combine,代码贴出来不能编译
+}
+
+// 反例 4:业务参数瞎编
+applyForSeat(seatIndex: 1, timeout: 60, reason: "我想连麦")
+// → "我想连麦" 应该用 {TODO: 填入业务申请理由} 占位
+
+// 反例 5:多角色塞一个类里
+class CoGuestManager {
+    func audienceApply() { ... }
+    func hostApprove() { ... }
+}
+// → 主播观众职责混合,AI 生成时随机抽方法
+```
 
-**唯一例外**：如果这个能力本身**极度独立、概念自洽、边界清晰**（即便当前只有一个引用方，未来很可能被复用），可以破例单拆。典型如「错误码速查」「日志诊断入口」这种跨能力的元能力。
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:含 `...` / 仅 print 错误 / 省略 import → AI 学坏 → 跨 slice 蔓延错误模式 → slice 不可合并,**已合并的批量回退**(2025-03 真实事故,2 周返工)
+- **验证手段**:
+  ```bash
+  # 1. 抽取代码块编译
+  python scripts/extract_code.py {file} | xcodebuild build ...
+  # 2. 静态扫描
+  grep -E "\.\.\.|//\s*处理结果|//\s*TODO[^:]" {file}  # 必须命中 0 次
+  grep -E "errorMessage|alert|toast" {file}            # 每个 .failure 块至少 1 处
+  ```
+- **绕过条件**:无。"先占位以后补"的代码示例 = 永远不会补的代码示例
 
-**简单判断**：先问自己「这个 slice 以后能被几个 scenario 引用？」——
-- 答得出 ≥2 个具体场景 → 独立 slice
-- 答不出、或只想得到一个 → 合并回去
-- 答不出但概念极独立、未来明显会被复用 → 可破例单拆，但要在 slice 开头写明「当前仅 X 场景使用，预留给 Y、Z 场景」
+---
 
-### 粒度对比示例
+##### 调用时序 [条件必填:多角色异步交互 或 回调嵌套 ≥3 层]
+
+###### 触发条件
+满足以下任一即必填:
+- 涉及 ≥2 个角色(如主播 + 观众)的异步交互
+- 回调嵌套深度 ≥3 层
+- 状态机分支 ≥3 个
+
+不满足 → 整段删除。
+
+###### 写作模板
+```markdown
+## 调用时序
+
+```
+观众端           SDK              主播端
+  │                                │
+  ├─ applyForSeat ──→               │
+  │                                │
+  │              ←─ onApplication ─┤
+  │                                │
+  │              ←─ approve  ──────┤
+  │                                │
+  ├─ {打开摄像头/麦克风}            │
+  │                                │
+```
+```
+
+###### 必填项语义三件套
+- **违反后果**:多角色交互无时序图 → AI 生成代码角色行为错位 → 上线后双方互相听不到
+- **验证手段**:人工 review,触发条件命中即必有;时序图覆盖所有角色和关键事件
+- **绕过条件**:不满足触发条件 → 可省
+
+---
+
+##### 平台特有注意事项 [必填:至少 1 条]
+
+###### 1️⃣ 你必须写什么
+仅在该平台才会踩的坑。每条标准:**该平台独有 + 不写出来研发会踩**。
+
+跨平台通用的注意事项 → 上移到产品级概览的 ALWAYS/NEVER。
+
+###### 2️⃣ 写作模板
+```markdown
+## 平台特有注意事项
+
+- **{该平台特有的现象/约束}** —— {为什么会发生}。
+  必须做:{具体动作}。
+```
 
-以「消息」为例：
+###### 3️⃣ ✅ 正例(iOS)
+```markdown
+## 平台特有注意事项
+
+- **`AnyCancellable` 必须存为实例属性,不能存为局部变量** —— 局部变量出
+  作用域后 cancellable 被释放,sink 闭包永远不会触发。
+  必须做:声明 `private var cancellables = Set<AnyCancellable>()` 实例属性,
+  调用 `.store(in: &cancellables)`。
 
+- **`sink { [weak self] }` 必须显式写 `[weak self]`** —— 不写会导致
+  ViewModel 与 publisher 循环引用,VC 销毁后 ViewModel 不释放。
+  必须做:所有 `.sink { }` 闭包第一行都加 `[weak self]`。
+
+- **首次申请麦克风权限的弹窗在异步线程触发会被忽略** —— 必须在主线程
+  调用 `applyForSeat`,否则系统不展示权限弹窗、SDK 报权限拒绝。
+  必须做:`DispatchQueue.main.async { applyForSeat() }`。
 ```
-❌ 太粗 → 一个"消息"slice 包含发送+接收+历史+撤回+转发+已读+推送
-   问题：客户说"消息收不到"，要在几千字里找相关部分
 
-❌ 太细 → 把发文本消息、发图片、发视频、发文件各做一个 slice
-   问题：它们的用法和排障方式几乎一样，重复内容太多
+###### 4️⃣ ❌ 反例
+```markdown
+## 平台特有注意事项
 
-✅ 合适 → 拆成：发送消息 / 接收消息 / 历史消息 / 消息撤回 / 离线推送
-   每个都能一次讲清，排查方向各不相同
+- 注意内存管理。
+- iOS 上需要权限。
+- 异步代码要小心。
 ```
 
+为什么这是反例:
+- ❌ "注意""小心" = 软词
+- ❌ "内存管理"/"权限"/"异步" = 模糊,跨平台都有
+- ❌ 没说具体怎么做
+- → review 直接打回
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:平台特有坑没写 → AI 生成代码在该平台报错 / 行为异常 / 内存泄漏
+- **验证手段**:每条必须含"必须做:{具体动作}";描述的现象其他平台不会出现
+- **绕过条件**:无
+
 ---
+| **可编译** | 含完整 import、完整类/函数闭包,不允许 `...` 省略任何逻辑分支 |
+| **可运行** | 补充业务参数后可直接跑通;业务参数用 `{TODO: 填入 xxx}` 占位 |
+| **有日志锚点** | 关键路径(申请发送成功、主播同意、设备打开、失败分支)必须有 `print`/`console.log`/`Log.d`,带模块前缀如 `[CoGuest]` |
+| **有错误处理** | 每个 `.failure` / `catch` / `error` 分支必须有面向用户的处理(UI 可见的 `errorMessage` 或 `alert`),不允许只 `print` |
+| **多角色分开写** | 主播端 / 观众端这种异构角色,**必须**拆成独立示例代码块 |
+| **可组合性** | 对外暴露清晰输入/输出;依赖用注释标注 `// 前置:登录完成(→ live/login-auth)` |
+
+###### 3️⃣ 写作模板(以 iOS Swift 为例)
+````markdown
+### 场景 X:{场景名,如"观众发起连麦申请"}
+
+```swift
+// 前置:登录完成(→ chat/login-auth)
+// 前置:已加入房间(→ live/room-lifecycle)
+
+import TencentImSDKPlugin
+import Combine
+
+class CoGuestApplyViewModel: ObservableObject {
+    @Published var errorMessage: String?       // ← UI 必需,展示给用户
+    private var cancellables = Set<AnyCancellable>()
+
+    func applyForSeat() {
+        print("[CoGuest] 开始发起连麦申请")  // ← 日志锚点(供验证矩阵层级 3)
+
+        CoGuestStore.shared.applyForSeat(timeout: 30)
+            .sink { [weak self] completion in   // ← [weak self] 必需
+                if case .failure(let error) = completion {
+                    print("[CoGuest] 申请失败: \(error)")
+                    self?.errorMessage = "连麦申请失败,请重试"  // ← 用户可见
+                }
+            } receiveValue: { [weak self] _ in
+                print("[CoGuest] 申请已发送")
+                self?.errorMessage = nil
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+````
+
+###### 4️⃣ ❌ 反例
+```swift
+// 反例 1:用 ... 省略
+func applyForSeat() {
+    CoGuestStore.shared.applyForSeat(...) { result in
+        // 处理结果
+        ...
+    }
+}
+// → "..." 跳过了失败处理 → AI 学到这个模式后到处省略
+
+// 反例 2:仅 print 错误
+.sink { completion in
+    if case .failure(let error) = completion {
+        print("error: \(error)")   // ← 用户看不到!
+    }
+}
+// → 客户线上故障时用户只看到无反应
+
+// 反例 3:省略 import
+class XXX {
+    var cancellables = Set<AnyCancellable>()
+    // ↑ 没 import Combine,代码贴出来不能编译
+}
+
+// 反例 4:业务参数瞎编
+applyForSeat(seatIndex: 1, timeout: 60, reason: "我想连麦")
+// → "我想连麦" 应该用 {TODO: 填入业务申请理由} 占位
+
+// 反例 5:多角色塞一个类里
+class CoGuestManager {
+    func audienceApply() { ... }
+    func hostApprove() { ... }
+}
+// → 主播观众职责混合,AI 生成时随机抽方法
+```
 
-## 三、Slice 两层架构：主线 + 反馈
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:含 `...` / 仅 print 错误 / 省略 import → AI 学坏 → 跨 slice 蔓延错误模式 → slice 不可合并,**已合并的批量回退**(2025-03 真实事故,2 周返工)
+- **验证手段**:
+  ```bash
+  # 1. 抽取代码块编译
+  python scripts/extract_code.py {file} | xcodebuild build ...
+  # 2. 静态扫描
+  grep -E "\.\.\.|//\s*处理结果|//\s*TODO[^:]" {file}  # 必须命中 0 次
+  grep -E "errorMessage|alert|toast" {file}            # 每个 .failure 块至少 1 处
+  ```
+- **绕过条件**:无。"先占位以后补"的代码示例 = 永远不会补的代码示例
 
-| 层级 | 名称 | 来源 | 用途 |
-|------|------|------|------|
-| 🅰️ **主线 Slice** | 骨架 | 按 SDK 能力域系统规划（来自官方文档+研发经验） | 保证每个核心功能都有覆盖 |
-| 🅱️ **反馈 Slice** | 血肉 | 从产品/销售收集的用户高频问题中提炼 | 补充真实的坑和边缘场景 |
+---
 
-### 两者的关系
-- **主线是骨架**：每个开发者都要走的路（初始化 → 登录 → 发消息 → ...）
-- **反馈是血肉**：开发者最容易摔跤的坑（互踢死循环、推送不到达、...）
-- 反馈 slice 可以是主线 slice 的深度补充，也可以是全新的边缘场景
+##### 调用时序 [条件必填:多角色异步交互 或 回调嵌套 ≥3 层]
 
-### 在 index.yaml 中的标记
+###### 触发条件
+满足以下任一即必填:
+- 涉及 ≥2 个角色(如主播 + 观众)的异步交互
+- 回调嵌套深度 ≥3 层
+- 状态机分支 ≥3 个
+
+不满足 → 整段删除。
+
+###### 写作模板
+```markdown
+## 调用时序
 
-```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
+```
+观众端           SDK              主播端
+  │                                │
+  ├─ applyForSeat ──→               │
+  │                                │
+  │              ←─ onApplication ─┤
+  │                                │
+  │              ←─ approve  ──────┤
+  │                                │
+  ├─ {打开摄像头/麦克风}            │
+  │                                │
+```
 ```
 
+###### 必填项语义三件套
+- **违反后果**:多角色交互无时序图 → AI 生成代码角色行为错位 → 上线后双方互相听不到
+- **验证手段**:人工 review,触发条件命中即必有;时序图覆盖所有角色和关键事件
+- **绕过条件**:不满足触发条件 → 可省
+
 ---
 
-## 四、Slice 文件结构规范
+##### 平台特有注意事项 [必填:至少 1 条]
 
-每个 slice 文件是一个 Markdown 文件，包含 YAML frontmatter 和固定的内容结构。
+###### 1️⃣ 你必须写什么
+仅在该平台才会踩的坑。每条标准:**该平台独有 + 不写出来研发会踩**。
 
-### 文件位置
+跨平台通用的注意事项 → 上移到产品级概览的 ALWAYS/NEVER。
+
+###### 2️⃣ 写作模板
+```markdown
+## 平台特有注意事项
 
+- **{该平台特有的现象/约束}** —— {为什么会发生}。
+  必须做:{具体动作}。
 ```
-knowledge-base/slices/{product}/{ability}.md          # 产品级概览（跨平台通用）
-knowledge-base/slices/{product}/{platform}/{ability}.md  # 平台实现细节
+
+###### 3️⃣ ✅ 正例(iOS)
+```markdown
+## 平台特有注意事项
+
+- **`AnyCancellable` 必须存为实例属性,不能存为局部变量** —— 局部变量出
+  作用域后 cancellable 被释放,sink 闭包永远不会触发。
+  必须做:声明 `private var cancellables = Set<AnyCancellable>()` 实例属性,
+  调用 `.store(in: &cancellables)`。
+
+- **`sink { [weak self] }` 必须显式写 `[weak self]`** —— 不写会导致
+  ViewModel 与 publisher 循环引用,VC 销毁后 ViewModel 不释放。
+  必须做:所有 `.sink { }` 闭包第一行都加 `[weak self]`。
+
+- **首次申请麦克风权限的弹窗在异步线程触发会被忽略** —— 必须在主线程
+  调用 `applyForSeat`,否则系统不展示权限弹窗、SDK 报权限拒绝。
+  必须做:`DispatchQueue.main.async { applyForSeat() }`。
 ```
 
-> **平台实现文件模板**：新建平台 slice 时，请复制 [`platform-slice-template.md`](platform-slice-template.md) 并按批注填写。填写范例见 `slices/live/ios/coguest-apply.md`。
+###### 4️⃣ ❌ 反例
+```markdown
+## 平台特有注意事项
 
-### Section 标签约定
+- 注意内存管理。
+- iOS 上需要权限。
+- 异步代码要小心。
+```
 
-每个 section 标题后面统一标注三种标签之一，研发写的时候一眼知道要不要填：
+为什么这是反例:
+- ❌ "注意""小心" = 软词
+- ❌ "内存管理"/"权限"/"异步" = 模糊,跨平台都有
+- ❌ 没说具体怎么做
+- → review 直接打回
 
-| 标签 | 含义 | 省略规则 |
-|------|------|---------|
-| `[必填]` | 必须写，否则 slice 不合格 | 不可省 |
-| `[可选]` | 视情况写，不影响合格 | 可整段删除 |
-| `[条件必填：<触发条件>]` | 满足条件时必须写，不满足时可省 | 不满足时可整段删除 |
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:平台特有坑没写 → AI 生成代码在该平台报错 / 行为异常 / 内存泄漏
+- **验证手段**:每条必须含"必须做:{具体动作}";描述的现象其他平台不会出现
+- **绕过条件**:无
+
+---
+
+##### 代码生成约束 [必填]
+
+此 section 是给 AI 读的硬性规则。**只有 apply 能机械验证的规则才能进 MUST/MUST NOT**。
+此 section 是给 AI 读的硬性规则。**只有 apply 能机械验证的规则才能进 MUST/MUST NOT**。
+
+###### 编译必要条件 [必填]
+###### 编译必要条件 [必填]
 
-示例：
 ```markdown
-## 功能说明 [必填]
-## 调用时序 [条件必填：异步回调嵌套 ≥3 层 或 涉及 3 个及以上角色]
-## 关联知识 [可选]
+### 编译必要条件
+
+- **必须导入** `{包名 1}` / `{包名 2}` —— SDK 类型不可用则编译失败。
+- **最低 SDK 版本**:`{version}`(若高于 base-setup 中的版本)
+- **必须的权限声明**:
+  - iOS: Info.plist `{key}` —— {用途}
+  - Android: Manifest `{permission}` —— {用途}
 ```
 
-### Frontmatter 字段
+✅ **正例**:
+```markdown
+### 编译必要条件
+
+- **必须导入** `import TencentImSDKPlugin` 与 `import Combine`
+- **最低 iOS 版本**:`13.0`(Combine 最低要求)
+- **必须的权限声明**:
+  - Info.plist `NSMicrophoneUsageDescription` —— 连麦需要麦克风
+  - Info.plist `NSCameraUsageDescription` —— 连麦需要摄像头
+```
+
+❌ **反例**:
+```markdown
+- 需要导入相关的包。
+- 最低版本参见官方文档。
+- 注意申请权限。
+```
+→ 模糊、不可机械验证、`参见官方文档` = 等于没写
 
-```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
+
+###### MUST(生成时必须包含) [必填,至少 3 条]
+
+####### 1️⃣ 你必须写什么
+MUST 是 AI 生成代码时**机械验证**的硬约束,**只写 apply 能用 grep 验的规则**。
+> **MUST 的语义 = backtick 符号能验的语义**。规则文字不能比 backtick 承诺得更多。
+
+####### 2️⃣ 写作模板
+```markdown
+#### MUST
+
+1. **必须 {强动词} `{可 grep 的符号}`** —— {不这样做的具体后果}。
+   **Verify**: 检查 `{符号}` 出现 ≥1 次。
+### 编译必要条件
+
+- **必须导入** `{包名 1}` / `{包名 2}` —— SDK 类型不可用则编译失败。
+- **最低 SDK 版本**:`{version}`(若高于 base-setup 中的版本)
+- **必须的权限声明**:
+  - iOS: Info.plist `{key}` —— {用途}
+  - Android: Manifest `{permission}` —— {用途}
+```
+
+✅ **正例**:
+```markdown
+### 编译必要条件
+
+- **必须导入** `import TencentImSDKPlugin` 与 `import Combine`
+- **最低 iOS 版本**:`13.0`(Combine 最低要求)
+- **必须的权限声明**:
+  - Info.plist `NSMicrophoneUsageDescription` —— 连麦需要麦克风
+  - Info.plist `NSCameraUsageDescription` —— 连麦需要摄像头
+```
+
+❌ **反例**:
+```markdown
+- 需要导入相关的包。
+- 最低版本参见官方文档。
+- 注意申请权限。
+```
+→ 模糊、不可机械验证、`参见官方文档` = 等于没写
+
 ---
+
+###### MUST(生成时必须包含) [必填,至少 3 条]
+
+####### 1️⃣ 你必须写什么
+MUST 是 AI 生成代码时**机械验证**的硬约束,**只写 apply 能用 grep 验的规则**。
+> **MUST 的语义 = backtick 符号能验的语义**。规则文字不能比 backtick 承诺得更多。
+
+####### 2️⃣ 写作模板
+```markdown
+#### MUST
+
+1. **必须 {强动词} `{可 grep 的符号}`** —— {不这样做的具体后果}。
+   **Verify**: 检查 `{符号}` 出现 ≥1 次。
+
+2. **必须 {强动词} `{符号 A}` 与 `{符号 B}`** —— {后果}。
+   **Verify**: 检查 `{符号 A}` 与 `{符号 B}` 各出现 ≥1 次。
+
+3. **必须在 {场景} 时调用 `{符号}`** —— {后果}。
+   **Verify**: 检查 `{符号}` 出现 ≥1 次。
 ```
 
-> **官方文档链接统一放在平台实现文件的 `api_docs` 字段**，产品级概览不放文档链接——因为教程/指南页通常按平台区分，放在跨平台的产品级文件里不合适。
+> ⚠️ 「在 X 时调用 Y」中的"X"语义 apply **不验**,只验 Y 出现。
+> 这是有意的——调用时机属于软规则,放到「调用时序」section 引导 AI。
 
-**平台实现文件的 frontmatter 字段**见「平台实现文件」小节。
+####### 3️⃣ ✅ 正例(摘自 chat/ios/multi-instance)
+```markdown
+#### MUST
 
-### 内容结构
+1. **必须导入 `import TencentImSDKPlugin`** —— 否则 SDK 类型不可用,编译报错。
+   **Verify**: 检查 `import TencentImSDKPlugin` 出现 ≥1 次。
 
-#### 产品级概览（`{product}/{ability}.md`）
+2. **必须注册互踢监听 `addSimpleMsgListener`** —— 不注册则用户被踢后无感知。
+   **Verify**: 检查 `addSimpleMsgListener` 出现 ≥1 次。
 
-产品级概览是**跨平台通用**的，描述的是"做什么"和"为什么"，不涉及"怎么做"。
+3. **必须在 `onKickedOffline` 回调里展示 UI 反馈 `errorMessage`** ——
+   仅 print 不算,用户看不到。
+   **Verify**: 检查 `onKickedOffline` 与 `errorMessage` 各出现 ≥1 次。
+```
 
-**平台无关性规则**：
+为什么这是正例:
+- ✅ 每条都用强动词("必须导入""必须注册"),不用"应该""建议"
+- ✅ backtick 内是**精确的可 grep 字符串**(类名/方法名)
+- ✅ 规则文字承诺的范围 ≤ Verify 能验的范围(无维度溢出)
+- ✅ 每条都有"违反后果"
 
-| ✅ 可以出现 | ❌ 不可以出现 |
-|-------------|-------------|
-| 操作语义（"观众发起连麦申请"） | 具体 API 签名（`applyForSeat(seatIndex:timeout:)` 这种 Swift 命名参数风格） |
-| 通用概念名（"连麦管理器"、"事件流"） | 平台特有类名/机制（`PassthroughSubject`、`ViewController`、`cancellable`） |
-| 行为级最佳实践（"通过前不要开设备"） | 代码结构级约束（"`[weak self]` 避免循环引用"） |
-| 通用排障逻辑（"检查主播端是否订阅了事件"） | 平台特有排障（"检查 cancellable 是否被提前释放"） |
-| 跨平台统一的错误码 | 仅某平台出现的错误码或异常行为 |
+####### 4️⃣ ❌ 反例
+```markdown
+#### MUST
+
+1. **应该正确处理互踢回调** —— 否则用户体验不好。
+   **Verify**: 检查互踢逻辑是否完整。
+   ↑ 软词"应该" + 模糊动词"处理" + Verify 不可机械化
+
+2. **必须调用 `login()` 或 `loginWithSig()`** —— 没登录无法用 SDK。
+   **Verify**: 检查 `login` 出现。
+   ↑ "或" = 红旗词;只 grep 一个 ≠ 验了选择
+
+3. **必须按业务场景选择互踢策略** —— 业务决定。
+   **Verify**: 检查策略配置是否合理。
+   ↑ "按业务""合理" = 不可机械验证,应下沉到「最佳实践」软规则
+```
+
+为什么这是反例:
+- ❌ 反例 1:用"应该""处理"等软词 → AI 视作可选
+- ❌ 反例 2:含红旗词"或" → 维度溢出
+- ❌ 反例 3:含"按业务""合理" → 不可机械验证,会训练 AI 凑字符串
+- → review 时**任何一条 MUST 含红旗词,整张 PR 打回**
+
+####### 5️⃣ 必填项语义三件套
+- **违反后果**:MUST 含红旗词("或/任一/等价/按业务/根据场景/留给/负责")→ apply 误杀正确代码 + 训练 AI 凑字符串 → slice 不可合并(2024-12 真实事故:room-lifecycle 写"调 A 或 B",apply 验过却生成错误混合代码)
+- **验证手段**:
+  ```bash
+  python scripts/check_must_rules.py {file}
+  # 通过标准:红旗词命中 0 次;每条 MUST 都有 Verify;Verify 内有 backtick
+  ```
+- **绕过条件**:无。MUST 是硬约束区,不接受任何豁免。需要"或/按业务"语义 → 拆原子规则,或下沉到「最佳实践」软规则区
+
+---
 
-**核心概念表的写法**：用操作名 + 语义描述，不写某个平台的方法签名。如果各平台 API 完全一致（同名同参数），可以写通用签名；如果有差异，只写操作语义，具体签名放到平台文件。
+###### MUST NOT(生成时绝不能出现) [必填,至少 2 条]
 
-**自查方法**：把文件中所有 API 名、类名、术语逐一检查 — 如果一个 Android 开发者读到它会觉得困惑或不适用，那就是平台特有内容，应该下沉到平台文件。
+####### 1️⃣ 你必须写什么
+列出**绝不允许出现**的代码模式。同样要求 backtick 可 grep。
 
+####### 2️⃣ 写作模板
 ```markdown
-# {名称}（产品级概览）
+#### MUST NOT
 
-## 功能说明 [必填]
-[功能描述、典型场景、版本要求]
+1. **不要 {动作} `{符号}`** —— {违反后果}。
+   **Verify**: 检查 `{符号}` 出现 0 次。
+```
 
-## 核心概念 [必填]
-[操作语义 + 状态机 + 角色关系，不含平台特有 API 签名]
+####### 3️⃣ ✅ 正例
+```markdown
+#### MUST NOT
 
-## 最佳实践 [必填]
-### ✅ ALWAYS（必须做的）
-[行为级规则：描述"该做什么"，不指定"用哪个 API 做"]
-### ❌ NEVER（绝不要做的）
-[行为级规则：描述"不该做什么"，不指定平台实现细节]
+1. **不要在 `onKickedOffline` 回调里调用 `login()`** —— 自动重登形成
+   两端死循环互踢,最终两端都登不上。
+   **Verify**: 在 `onKickedOffline` 函数体内,`login` 出现 0 次。
 
-## 排障指南 [必填]
-### 常见错误码
-[跨平台统一的错误码表格]
-### 排障流程
-[通用排障逻辑树，平台特有分支标注 → 见平台文件]
+2. **不要在客户端代码里硬编码 `SecretKey`** —— 密钥泄露后可签发任意 UserSig。
+   **Verify**: 全文 `SecretKey` 出现 0 次。
 
-## 关联知识 [可选]
-[引用相关 slice；如果没有关联，删除整个 section]
+3. **不要用 `try?` 吞掉 `loginWithSig` 的错误** —— 静默失败导致后续 API 调用
+   全部失败但无日志可查。
+   **Verify**: `try?\s+.*loginWithSig` 出现 0 次(用 grep -E)。
 ```
 
-**产品级概览中各 section 的必填理由**：
-- `功能说明` / `核心概念` — slice 的身份标识，缺失则无法理解这个 slice 是做什么的
-- `最佳实践` — slice 区别于官方文档的核心价值。如果仅抄 API 说明，无需做 slice
-- `排障指南` — slice 面向集成场景的交付标准。至少给出「常见错误码」和「排障流程」两个子项，否则客户报问题时无章可循
-- `关联知识` — 孤立能力可省。有 2+ 相关 slice 时必须写，防止知识孤岛
+为什么这是正例:
+- ✅ 每条都精确到"哪个上下文里不能出现哪个符号"
+- ✅ Verify 是 0 次匹配,机械可验
 
-> 提交前对照第五节「产品级概览 DoD」逐条打勾，合格后再提交。
+####### 4️⃣ ❌ 反例
+```markdown
+#### MUST NOT
 
-#### 平台实现文件（`{product}/{platform}/{ability}.md`）
+1. 不要写不安全的代码。
+2. 避免循环引用。
+3. 不要忽略错误。
+```
+→ 全部模糊,无 backtick,无 Verify
 
-##### Frontmatter 字段
+####### 5️⃣ 必填项语义三件套
+- **违反后果**:MUST NOT 缺失或模糊 → AI 生成代码引入安全/性能/稳定性问题
+- **验证手段**:同 MUST,跑 `check_must_rules.py`
+- **绕过条件**:无
 
-```yaml
 ---
-id: {product}/{ability}     # [必填] 与产品级 slice 的 id 一致
-platform: {platform}        # [必填] ios / android / web / flutter / electron
-api_docs:                   # [必填] 该平台 API 参考文档链接（至少 1 条）
-  - title: {API 类名/模块名}
-    url: https://...
+
+###### 集成检查点 [必填]
+
+```markdown
+### 集成检查点
+
+- 是否与项目已有 SDK 初始化冲突?(检查 `{初始化函数}` 是否已在别处调用)
+- 是否依赖其他 slice 的前置状态?(本 slice 依赖 → `{slice-id}`)
+- 对已有代码的侵入性:`{新增 X 个文件 / 修改 Y 个文件}`
+```
+
+✅ **正例**:
+```markdown
+### 集成检查点
+
+- 是否与项目已有 SDK 初始化冲突?检查项目中 `V2TIMManager.sharedInstance().initSDK()`
+  是否已被调用,若是则不要重复调用
+- 是否依赖其他 slice?依赖 `chat/login-auth` 完成登录
+- 对已有代码的侵入性:新增 1 个 ViewModel 文件,无需修改现有代码
+```
+
+###### 必填项语义三件套(集成检查点)
+- **违反后果**:不写检查点 → 集成时与已有代码冲突(双重初始化、状态污染)
+- **验证手段**:必须有 ≥3 条;每条引用具体函数/slice/文件数
+- **绕过条件**:无
+
 ---
+
+###### MUST 规则的维度对齐原则 [必填阅读]
+2. **必须 {强动词} `{符号 A}` 与 `{符号 B}`** —— {后果}。
+   **Verify**: 检查 `{符号 A}` 与 `{符号 B}` 各出现 ≥1 次。
+
+3. **必须在 {场景} 时调用 `{符号}`** —— {后果}。
+   **Verify**: 检查 `{符号}` 出现 ≥1 次。
 ```
 
-**`api_docs` 填写质量要求**：
+> ⚠️ 「在 X 时调用 Y」中的"X"语义 apply **不验**,只验 Y 出现。
+> 这是有意的——调用时机属于软规则,放到「调用时序」section 引导 AI。
 
-| 要求 | 说明 | 举例 |
-|------|------|------|
-| ✅ 精确到**类/模块**级 | 一条链接打开就能看到本 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` |
+####### 3️⃣ ✅ 正例(摘自 chat/ios/multi-instance)
+```markdown
+#### MUST
 
-**若该平台没有可用的 API 参考页**（如 Electron/Unity 某些模块）：
-- 优先考虑这个 slice 在该平台是否真的需要独立文件
-- 若确需保留，填入**头文件/类型声明文件**的 GitHub 永久链接（commit hash 固定版本），而不是空链接
+1. **必须导入 `import TencentImSDKPlugin`** —— 否则 SDK 类型不可用,编译报错。
+   **Verify**: 检查 `import TencentImSDKPlugin` 出现 ≥1 次。
 
-> 注：`name` / `tags` / `platforms` / `related` 在产品级概览中维护，平台文件不重复。
+2. **必须注册互踢监听 `addSimpleMsgListener`** —— 不注册则用户被踢后无感知。
+   **Verify**: 检查 `addSimpleMsgListener` 出现 ≥1 次。
 
-##### 内容结构
+3. **必须在 `onKickedOffline` 回调里展示 UI 反馈 `errorMessage`** ——
+   仅 print 不算,用户看不到。
+   **Verify**: 检查 `onKickedOffline` 与 `errorMessage` 各出现 ≥1 次。
+```
 
-平台实现文件按以下结构编写，每个 section 标题后都必须带必填/可选标签：
+为什么这是正例:
+- ✅ 每条都用强动词("必须导入""必须注册"),不用"应该""建议"
+- ✅ backtick 内是**精确的可 grep 字符串**(类名/方法名)
+- ✅ 规则文字承诺的范围 ≤ Verify 能验的范围(无维度溢出)
+- ✅ 每条都有"违反后果"
 
+####### 4️⃣ ❌ 反例
 ```markdown
-# {名称} — {平台} 实现
+#### MUST
 
-## 前置条件 [必填]
-## 代码示例 [必填]
-## 调用时序 [条件必填：多角色异步交互 或 回调嵌套 ≥3 层]
-## 平台特有注意事项 [必填：至少 1 条]
-## 代码生成约束 [必填]
-## 验证矩阵 [必填]
+1. **应该正确处理互踢回调** —— 否则用户体验不好。
+   **Verify**: 检查互踢逻辑是否完整。
+   ↑ 软词"应该" + 模糊动词"处理" + Verify 不可机械化
+
+2. **必须调用 `login()` 或 `loginWithSig()`** —— 没登录无法用 SDK。
+   **Verify**: 检查 `login` 出现。
+   ↑ "或" = 红旗词;只 grep 一个 ≠ 验了选择
+
+3. **必须按业务场景选择互踢策略** —— 业务决定。
+   **Verify**: 检查策略配置是否合理。
+   ↑ "按业务""合理" = 不可机械验证,应下沉到「最佳实践」软规则
 ```
 
-各 section 详细要求见下方。
+为什么这是反例:
+- ❌ 反例 1:用"应该""处理"等软词 → AI 视作可选
+- ❌ 反例 2:含红旗词"或" → 维度溢出
+- ❌ 反例 3:含"按业务""合理" → 不可机械验证,会训练 AI 凑字符串
+- → review 时**任何一条 MUST 含红旗词,整张 PR 打回**
+
+####### 5️⃣ 必填项语义三件套
+- **违反后果**:MUST 含红旗词("或/任一/等价/按业务/根据场景/留给/负责")→ apply 误杀正确代码 + 训练 AI 凑字符串 → slice 不可合并(2024-12 真实事故:room-lifecycle 写"调 A 或 B",apply 验过却生成错误混合代码)
+- **验证手段**:
+  ```bash
+  python scripts/check_must_rules.py {file}
+  # 通过标准:红旗词命中 0 次;每条 MUST 都有 Verify;Verify 内有 backtick
+  ```
+- **绕过条件**:无。MUST 是硬约束区,不接受任何豁免。需要"或/按业务"语义 → 拆原子规则,或下沉到「最佳实践」软规则区
 
-##### 代码示例标准 [必填]
+---
 
-平台 slice 的核心交付物。要求：
+###### MUST NOT(生成时绝不能出现) [必填,至少 2 条]
 
-| 维度 | 最低标准 |
-|------|---------|
-| **可编译** | 包含完整 import、完整类/函数闭包，不允许 `...` 省略任何逻辑分支 |
-| **可运行** | 补充业务参数后可直接跑通；业务参数用 `{TODO: 填入 xxx}` 占位，而不是随意编的字符串 |
-| **有日志锚点** | 关键路径（申请发送成功、主播同意、设备打开、失败分支）必须有 `print`/`console.log`/`Log.d`，供「验证矩阵」在运行时观察；日志统一带模块前缀如 `[CoGuest]` |
-| **有错误处理** | 每一个 `.failure` / `catch` / `error` 分支都必须有面向用户的处理（UI 可见的 `errorMessage` 或 `alert`），不允许只 `print` 就结束 |
-| **多角色分开写** | 主播端 / 观众端 这种异构角色，**必须**拆成独立示例代码块 |
-| **可组合性** | 对外暴露清晰输入/输出；不硬编码其他 slice 的调用（如登录初始化），依赖用注释标注 `// 前置：登录完成（→ live/login-auth）` |
-
-**禁止事项**：
-- ❌ 用伪代码或 `...` 跳过逻辑
-- ❌ 把多个 slice 的职责耦合在一个类里
-- ❌ 省略失败分支处理
+####### 1️⃣ 你必须写什么
+列出**绝不允许出现**的代码模式。同样要求 backtick 可 grep。
 
-##### 代码生成约束 [必填]
+####### 2️⃣ 写作模板
+```markdown
+#### MUST NOT
+
+1. **不要 {动作} `{符号}`** —— {违反后果}。
+   **Verify**: 检查 `{符号}` 出现 0 次。
+```
+
+####### 3️⃣ ✅ 正例
+```markdown
+#### MUST NOT
+
+1. **不要在 `onKickedOffline` 回调里调用 `login()`** —— 自动重登形成
+   两端死循环互踢,最终两端都登不上。
+   **Verify**: 在 `onKickedOffline` 函数体内,`login` 出现 0 次。
+
+2. **不要在客户端代码里硬编码 `SecretKey`** —— 密钥泄露后可签发任意 UserSig。
+   **Verify**: 全文 `SecretKey` 出现 0 次。
 
-此 section 是给 AI 读的硬性规则。**只有 apply 能机械验证的规则才能进 MUST/MUST NOT**——具体什么样的规则算「能机械验证」，见下一节「MUST 规则的维度对齐原则」，必读。
+3. **不要用 `try?` 吞掉 `loginWithSig` 的错误** —— 静默失败导致后续 API 调用
+   全部失败但无日志可查。
+   **Verify**: `try?\s+.*loginWithSig` 出现 0 次(用 grep -E)。
+```
 
-格式示例：
+为什么这是正例:
+- ✅ 每条都精确到"哪个上下文里不能出现哪个符号"
+- ✅ Verify 是 0 次匹配,机械可验
 
+####### 4️⃣ ❌ 反例
 ```markdown
-### 编译必要条件 [必填]
-- 必须导入的模块/包（精确到包名）
-- 最低 SDK 版本（若高于 base）
-- 必须的权限声明或配置
+#### MUST NOT
+
+1. 不要写不安全的代码。
+2. 避免循环引用。
+3. 不要忽略错误。
+```
+→ 全部模糊,无 backtick,无 Verify
 
-### 生成规则 [必填]
+####### 5️⃣ 必填项语义三件套
+- **违反后果**:MUST NOT 缺失或模糊 → AI 生成代码引入安全/性能/稳定性问题
+- **验证手段**:同 MUST,跑 `check_must_rules.py`
+- **绕过条件**:无
 
-#### MUST（生成时必须包含）
+---
 
-1. **<动作> `符号`** — <违反后果>。
-   **Verify**: 检查是否存在 `符号`。
+###### 集成检查点 [必填]
 
-2. **<动作> `符号 A`** — <违反后果>。
-   **Verify**: 检查是否存在 `符号 A`。
+```markdown
+### 集成检查点
 
-#### MUST NOT（生成时绝不能出现）
+- 是否与项目已有 SDK 初始化冲突?(检查 `{初始化函数}` 是否已在别处调用)
+- 是否依赖其他 slice 的前置状态?(本 slice 依赖 → `{slice-id}`)
+- 对已有代码的侵入性:`{新增 X 个文件 / 修改 Y 个文件}`
+```
 
-1. **不要 <动作> `符号`** — <违反后果>。
-   **Verify**: 检查 `符号` 出现 0 次。
+✅ **正例**:
+```markdown
+### 集成检查点
 
-### 集成检查点 [必填]
-- 是否与项目已有 SDK 初始化冲突
-- 是否依赖其他 slice 的前置状态（引用具体 slice ID）
-- 对已有代码的侵入性（新增 vs 修改）
+- 是否与项目已有 SDK 初始化冲突?检查项目中 `V2TIMManager.sharedInstance().initSDK()`
+  是否已被调用,若是则不要重复调用
+- 是否依赖其他 slice?依赖 `chat/login-auth` 完成登录
+- 对已有代码的侵入性:新增 1 个 ViewModel 文件,无需修改现有代码
 ```
 
-**关键约束**：
+###### 必填项语义三件套(集成检查点)
+- **违反后果**:不写检查点 → 集成时与已有代码冲突(双重初始化、状态污染)
+- **验证手段**:必须有 ≥3 条;每条引用具体函数/slice/文件数
+- **绕过条件**:无
 
-- 每条 MUST/MUST NOT 的 `**Verify**:` 字段引用的 backtick 符号 = apply 唯一会 grep 的东西
-- 规则文字描述的所有判断、选择、等价、条件分支，apply **全部不验**——所以这些不要写进 MUST
-- 多 backtick 的规则可以接受，apply 解析为「全部都要出现」（all-of）
+---
 
-##### MUST 规则的维度对齐原则 [必填阅读]
+###### MUST 规则的维度对齐原则 [必填阅读]
 
-###### 核心原则
+####### 核心原则
+####### 核心原则
 
 > **MUST 规则的语义 = 它的 backtick 符号能验的语义。**
 >
-> 如果你写的规则文字比 backtick 符号能表达的更多，规则就「维度溢出」了——AI 写对了你 grep 不到，AI 写错了你也 grep 不到，verifier 反而把 AI 推向凑字符串。
+> 如果你写的规则文字比 backtick 符号能表达的更多,规则就「维度溢出」了——AI 写对了你 grep 不到,AI 写错了你也 grep 不到,verifier 反而把 AI 推向凑字符串。
+> 如果你写的规则文字比 backtick 符号能表达的更多,规则就「维度溢出」了——AI 写对了你 grep 不到,AI 写错了你也 grep 不到,verifier 反而把 AI 推向凑字符串。
 
-###### 红旗词表：以下写法说明 MUST 写错了
+####### 红旗词表:以下写法说明 MUST 写错了
+####### 红旗词表:以下写法说明 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 硬约束
+| **「或 / 任一」** | "出现 `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 |
+| **「或 / 任一」** | "出现 `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 之前问自己)
+####### 自查三问(写完每条 MUST 之前问自己)
+
+1. backtick 里的符号是不是就是 verify 唯一会做的事?规则文字里的其他词能不能删?
+2. 如果 AI 写**等价但不同写法**的代码,verify 会不会误杀?误杀 = 规则太死,要么拆原子要么降级软规则。
+3. 如果 AI 写**只满足 backtick 字符串但语义错**的代码,verify 会不会放过?放过 = 规则太松,应该拆。
+1. backtick 里的符号是不是就是 verify 唯一会做的事?规则文字里的其他词能不能删?
+2. 如果 AI 写**等价但不同写法**的代码,verify 会不会误杀?误杀 = 规则太死,要么拆原子要么降级软规则。
+3. 如果 AI 写**只满足 backtick 字符串但语义错**的代码,verify 会不会放过?放过 = 规则太松,应该拆。
+
+####### 软规则 vs 硬约束
+####### 软规则 vs 硬约束
 
 | 类型 | 写在哪 | apply 行为 | AI 行为 |
 |---|---|---|---|
-| **硬约束**（MUST/MUST NOT） | 「代码生成约束」 | grep backtick，命中失败就 fail | 必须包含/避免符号 |
-| **软规则**（业务选择、架构建议、调用顺序、错误处理建议） | 「最佳实践」「集成检查点」「调用时序」「代码示例」 | 不验，仅作为 AI 上下文 | 阅读后自行判断 |
+| **硬约束**(MUST/MUST NOT) | 「代码生成约束」 | grep backtick,命中失败就 fail | 必须包含/避免符号 |
+| **软规则**(业务选择、架构建议、调用顺序、错误处理建议) | 「最佳实践」「集成检查点」「调用时序」「代码示例」 | 不验,仅作为 AI 上下文 | 阅读后自行判断 |
+| **硬约束**(MUST/MUST NOT) | 「代码生成约束」 | grep backtick,命中失败就 fail | 必须包含/避免符号 |
+| **软规则**(业务选择、架构建议、调用顺序、错误处理建议) | 「最佳实践」「集成检查点」「调用时序」「代码示例」 | 不验,仅作为 AI 上下文 | 阅读后自行判断 |
 
 > **重要 ≠ 能机械验证。**
 >
-> 把重要但验不了的规则放进 MUST，会**误杀正确代码 + 训练 AI 凑字符串**——这是 verifier 反向变成攻击面。
+> 把重要但验不了的规则放进 MUST,会**误杀正确代码 + 训练 AI 凑字符串**——这是 verifier 反向变成攻击面。
+> 把重要但验不了的规则放进 MUST,会**误杀正确代码 + 训练 AI 凑字符串**——这是 verifier 反向变成攻击面。
 >
-> 重要但不能机械验证的规则，**写到软规则区，靠 AI 阅读 + 反例代码**来引导。
+> 重要但不能机械验证的规则,**写到软规则区,靠 AI 阅读 + 反例代码**来引导。
+> 重要但不能机械验证的规则,**写到软规则区,靠 AI 阅读 + 反例代码**来引导。
 
-###### 完整改造示例：room-lifecycle 的失败规则
+####### 完整改造示例:room-lifecycle 的失败规则
+####### 完整改造示例:room-lifecycle 的失败规则
 
-❌ **改前**（现状写法，触发 AI 凑字符串）：
+❌ **改前**(现状写法,触发 AI 凑字符串):
+❌ **改前**(现状写法,触发 AI 凑字符串):
 
 ```
 3. **按业务目标选择 `createAndJoinRoom()` 或 `joinRoom()`** — 房主快速创建并入会、
-   以及无法确认房间是否存在时，都更适合 `createAndJoinRoom()`；只有已知房间已存在
+   以及无法确认房间是否存在时,都更适合 `createAndJoinRoom()`;只有已知房间已存在
+   以及无法确认房间是否存在时,都更适合 `createAndJoinRoom()`;只有已知房间已存在
    时才直接使用 `joinRoom()`。
    **Verify**: 检查是否把"房主创建并入会""已知房间存在直接加入""存在性未知时尝试
    进入"这三类路径明确区分。
 
-5. **为密码房和常见入会错误预留业务反馈** — 无 UI 接入时，密码输入、重试和错误
+5. **为密码房和常见入会错误预留业务反馈** — 无 UI 接入时,密码输入、重试和错误
+5. **为密码房和常见入会错误预留业务反馈** — 无 UI 接入时,密码输入、重试和错误
    提示都需要页面自行承接。
    **Verify**: 检查加入流程是否处理 `ERR_NEED_PASSWORD`、`ERR_WRONG_PASSWORD`
    或等价失败提示。
 ```
 
-红旗词诊断：「按业务」「或」「等价」全部命中。规则文字承诺的语义远超 backtick 能验的范围。
+红旗词诊断:「按业务」「或」「等价」全部命中。规则文字承诺的语义远超 backtick 能验的范围。
+红旗词诊断:「按业务」「或」「等价」全部命中。规则文字承诺的语义远超 backtick 能验的范围。
 
-✅ **改后**：
+✅ **改后**:
+✅ **改后**:
 
-「代码生成约束」→ MUST：
+「代码生成约束」→ MUST:
+「代码生成约束」→ MUST:
 ```
-3. **必须调用房间进入 API（`createAndJoinRoom` 或 `joinRoom` 至少其一）** — 否则
+3. **必须调用房间进入 API(`createAndJoinRoom` 或 `joinRoom` 至少其一)** — 否则
+3. **必须调用房间进入 API(`createAndJoinRoom` 或 `joinRoom` 至少其一)** — 否则
    无法进房。
    **Verify**: 检查 `createAndJoinRoom` 与 `joinRoom` 至少其一出现 ≥1 次。
 ```
 
-「代码示例」→ 增加场景一/二/三，每个场景写完整可 copy 的代码。
+「代码示例」→ 增加场景一/二/三,每个场景写完整可 copy 的代码。
+「代码示例」→ 增加场景一/二/三,每个场景写完整可 copy 的代码。
 
-「最佳实践」→ 新增软规则段（apply 不验，AI 阅读）：
+「最佳实践」→ 新增软规则段(apply 不验,AI 阅读):
+「最佳实践」→ 新增软规则段(apply 不验,AI 阅读):
 ```
-- 房主快速创建会议 → 用 createAndJoinRoom（参考场景一）
-- 已知房间已存在 → 用 joinRoom（参考场景二）
-- 不确定房间是否存在 → 用 createAndJoinRoom（参考场景三）
+- 房主快速创建会议 → 用 createAndJoinRoom(参考场景一)
+- 已知房间已存在 → 用 joinRoom(参考场景二)
+- 不确定房间是否存在 → 用 createAndJoinRoom(参考场景三)
+- 房主快速创建会议 → 用 createAndJoinRoom(参考场景一)
+- 已知房间已存在 → 用 joinRoom(参考场景二)
+- 不确定房间是否存在 → 用 createAndJoinRoom(参考场景三)
 - 密码房 / 入会错误处理 → 见场景四与「常见错误与场景对照」表
 ```
 
-效果：
+效果:
+效果:
 - apply 不再误杀「AI 用 catch 通用错误处理」的正确代码
 - AI 读到「最佳实践」能按业务选 API
 - 业务路径选择即使错了也不会因 verify fail 把 AI 推去凑字符串
 
+---
+
+---
+
 ##### 验证矩阵 [必填]
 
-此 section 是平台 slice 末尾的**统一验证出口**，汇总该 slice 所有可 verify 的项，按 4 层分级。AI 生成代码后或人工 review 时，自上而下跑一遍即可完成验收。
+###### 1️⃣ 你必须写什么
+平台 slice 末尾的**统一验证出口**,汇总所有可 verify 的项,按 4 层分级。
+AI 生成代码后或人工 review 时,自上而下跑一遍即可完成验收。
+###### 1️⃣ 你必须写什么
+平台 slice 末尾的**统一验证出口**,汇总所有可 verify 的项,按 4 层分级。
+AI 生成代码后或人工 review 时,自上而下跑一遍即可完成验收。
+
+这是 SuperPowers「验证门」机制在 slice 层的落地——**禁止在没有跑过验证矩阵的情况下声称完成**。
+
+###### 2️⃣ 写作模板
+这是 SuperPowers「验证门」机制在 slice 层的落地——**禁止在没有跑过验证矩阵的情况下声称完成**。
+
+###### 2️⃣ 写作模板
+```markdown
+## 验证矩阵
+
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| **1. 编译级** | {项} | {命令} | {预期} |
+| **1. 编译级** | {项} | {命令} | {预期} |
+| **2. 静态规则级** | {项} | {grep 命令} | {预期} |
+| **2. 静态规则级** | {项} | {grep 命令} | {预期} |
+| **3. 运行时级** | {项} | {操作 + 查日志} | {预期日志} |
+| **3. 运行时级** | {项} | {操作 + 查日志} | {预期日志} |
+| **4. 业务行为级** | {项} | {人工观察} | {预期现象} |
+| **4. 业务行为级** | {项} | {人工观察} | {预期现象} |
+```
+
+###### 3️⃣ ✅ 正例(摘自 live/ios/coguest-apply)
+```markdown
+## 验证矩阵
+
+| 层级 | 检查项 | 验证手段 | 预期结果 |
+|------|--------|----------|---------|
+| **1. 编译级** | 模块导入齐全 | `xcodebuild build -scheme Demo` | exit code 0 |
+| **1. 编译级** | iOS 最低版本 ≥ 13.0 | 查 `Podfile`/`project.pbxproj` | `IPHONEOS_DEPLOYMENT_TARGET = 13.0` |
+| **1. 编译级** | {项} | {命令} | {预期} |
+| **1. 编译级** | {项} | {命令} | {预期} |
+| **2. 静态规则级** | {项} | {grep 命令} | {预期} |
+| **2. 静态规则级** | {项} | {grep 命令} | {预期} |
+| **3. 运行时级** | {项} | {操作 + 查日志} | {预期日志} |
+| **3. 运行时级** | {项} | {操作 + 查日志} | {预期日志} |
+| **4. 业务行为级** | {项} | {人工观察} | {预期现象} |
+| **4. 业务行为级** | {项} | {人工观察} | {预期现象} |
+```
 
+###### 3️⃣ ✅ 正例(摘自 live/ios/coguest-apply)
 ```markdown
 ## 验证矩阵
 
 | 层级 | 检查项 | 验证手段 | 预期结果 |
 |------|--------|----------|---------|
-| **1. 编译级** | 模块导入齐全 | `xcodebuild build ...` / `./gradlew assembleDebug` / `tsc --noEmit` | exit code 0 |
-| **1. 编译级** | 最低版本达标 | 查项目 deployment target | ≥ {版本} |
+| **1. 编译级** | 模块导入齐全 | `xcodebuild build -scheme Demo` | exit code 0 |
+| **1. 编译级** | iOS 最低版本 ≥ 13.0 | 查 `Podfile`/`project.pbxproj` | `IPHONEOS_DEPLOYMENT_TARGET = 13.0` |
 | **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] 申请已发送...` |
+| **2. 静态规则级** | 每个 .failure 有 errorMessage | `grep -B 5 "case .failure" \| grep errorMessage` | 无裸 print |
+| **3. 运行时级** | 申请发送成功 | 观众点申请 → 查日志 | `[CoGuest] 申请已发送` |
+| **2. 静态规则级** | 每个 .failure 有 errorMessage | `grep -B 5 "case .failure" \| grep errorMessage` | 无裸 print |
+| **3. 运行时级** | 申请发送成功 | 观众点申请 → 查日志 | `[CoGuest] 申请已发送` |
 | **3. 运行时级** | 主播收到事件 | 主播端查日志 | `onGuestApplicationReceived` |
-| **3. 运行时级** | 超时 UI 反馈 | 主播不响应，等 30s | UI 展示"申请超时" |
+| **3. 运行时级** | 超时 UI 反馈 | 主播不响应,等 30s | UI 展示"申请超时" |
+| **3. 运行时级** | 超时 UI 反馈 | 主播不响应,等 30s | UI 展示"申请超时" |
 | **4. 业务行为级** | 通过前设备未开 | 点申请但未同意 | 摄像头指示灯不亮 |
 | **4. 业务行为级** | 断开后设备关闭 | 连麦中主动断开 | 摄像头指示灯熄灭 |
 ```
 
-**4 个层级说明**：
+###### 4️⃣ 4 个层级说明
+###### 4️⃣ 4 个层级说明
 
 | 层级 | 含义 | 谁来跑 |
 |------|------|--------|
 | 1. **编译级** | 代码能编译通过、依赖齐全 | CI / AI 自动 |
-| 2. **静态规则级** | 不跑代码，纯静态扫描/ grep 就能查的规则 | CI / AI 自动 |
+| 2. **静态规则级** | 不跑代码,纯静态扫描/grep 就能查的规则 | CI / AI 自动 |
+| 2. **静态规则级** | 不跑代码,纯静态扫描/grep 就能查的规则 | CI / AI 自动 |
 | 3. **运行时级** | 跑起来后通过日志锚点可观察的行为 | AI 半自动 / 人工 |
 | 4. **业务行为级** | 需要人眼看 UI / 硬件状态的业务语义 | 人工 |
 
-> **与 MUST 规则的对应关系**：
+> **与 MUST 规则的对应关系**:
+> **与 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」的运行时体现）
+> - 「层级 1 编译级」与「层级 2 静态规则级」是 apply 的**硬约束区域**——基本对应「代码生成约束」里的 MUST/MUST NOT,apply 自动跑、命中失败会 fail
+> - 「层级 3 运行时级」与「层级 4 业务行为级」是**软规则区域**——属于运行时观察 / 业务语义校验,apply 不验,需要 AI 半自动或人工跑
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:验证矩阵不全 → AI/人工无法系统性自验 → "应该没问题"上线 → 线上事故
+- **验证手段**:
+  ```bash
+  python scripts/check_verify_matrix.py {file}
+  # 通过标准:
+  # - 4 个层级各 ≥1 行
+  # - 每条「代码生成约束」MUST/MUST NOT 都能在矩阵层级 1 或 2 找到对应行
+  # - 至少 1 条层级 3、1 条层级 4
+  ```
+- **绕过条件**:无
+> - 「层级 1 编译级」与「层级 2 静态规则级」是 apply 的**硬约束区域**——基本对应「代码生成约束」里的 MUST/MUST NOT,apply 自动跑、命中失败会 fail
+> - 「层级 3 运行时级」与「层级 4 业务行为级」是**软规则区域**——属于运行时观察 / 业务语义校验,apply 不验,需要 AI 半自动或人工跑
+
+###### 5️⃣ 必填项语义三件套
+- **违反后果**:验证矩阵不全 → AI/人工无法系统性自验 → "应该没问题"上线 → 线上事故
+- **验证手段**:
+  ```bash
+  python scripts/check_verify_matrix.py {file}
+  # 通过标准:
+  # - 4 个层级各 ≥1 行
+  # - 每条「代码生成约束」MUST/MUST NOT 都能在矩阵层级 1 或 2 找到对应行
+  # - 至少 1 条层级 3、1 条层级 4
+  ```
+- **绕过条件**:无
 
 ---
 
-## 五、完成自查清单（DoD）
+## 五、完成自查清单(DoD)
+## 五、完成自查清单(DoD)
 
-研发写完 slice 后，对照清单逐条打勾。任何一项未满足 = 未完成。
+研发写完 slice 后,对照清单逐条打勾。**任何一项未满足 = 未完成,不允许提 PR**。
+
+> ⚠️ 仅打勾不跑命令 = 视为未验证。每条标了"验证命令"的项,必须在 PR 描述粘贴命令输出。
+研发写完 slice 后,对照清单逐条打勾。**任何一项未满足 = 未完成,不允许提 PR**。
+
+> ⚠️ 仅打勾不跑命令 = 视为未验证。每条标了"验证命令"的项,必须在 PR 描述粘贴命令输出。
 
 ### 产品级概览 DoD
 
-- [ ] Frontmatter 必填字段齐全（id / name / product / tags≥3 / platforms）
+- [ ] Frontmatter 必填字段齐全(id / name / product / tags≥3 / platforms)
+      验证:`python scripts/validate_frontmatter.py {file}` 退出码 0
+- [ ] Frontmatter 必填字段齐全(id / name / product / tags≥3 / platforms)
+      验证:`python scripts/validate_frontmatter.py {file}` 退出码 0
 - [ ] 每个 section 标题都带 `[必填]` / `[可选]` / `[条件必填]` 标签
 - [ ] `功能说明` 能让一个没接触过 TRTC 的开发者 30 秒内明白这个能力是什么
 - [ ] `核心概念` 无平台特有 API 签名（自查：逐个 API 名过一遍，iOS/Android 开发者读到都不应困惑）
 - [ ] `最佳实践` 的每条 ALWAYS/NEVER 都是**行为级**（"做什么"），不含代码结构细节（"怎么写"）
 - [ ] `排障指南` 至少包含 1 张错误码表 + 1 棵排障流程树
-- [ ] `关联知识` 的所有引用 slice ID 在 `index.yaml` 中存在（或标注 `status: planned`）
+- [ ] `关联知识` 的所有引用 slice ID 在对应的 per-product platform index 中存在（或标注 `status: planned`）
 - [ ] 全文不包含具体平台的类名/方法名/关键字（如 `ViewController`、`[weak self]`、`PassthroughSubject`）
 
 ### 平台实现文件 DoD
 
-- [ ] Frontmatter 必填字段齐全（id / platform / api_docs≥1）
-- [ ] `api_docs` 链接精确到**类/模块**级，不是 SDK 首页或教程页
+- [ ] Frontmatter 必填字段齐全(id / platform / api_docs≥1)
+- [ ] `api_docs` 链接精确到**类/模块**级
+      验证:`python scripts/validate_api_docs.py {file}` 全部 200 + 含 `/documentation/` 或 `/api/`
+- [ ] Frontmatter 必填字段齐全(id / platform / api_docs≥1)
+- [ ] `api_docs` 链接精确到**类/模块**级
+      验证:`python scripts/validate_api_docs.py {file}` 全部 200 + 含 `/documentation/` 或 `/api/`
 - [ ] 每个 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（提交合并前）
+- [ ] `前置条件` 不重复 base-setup / login-auth 内容
+      验证:`grep -E "pod install|npm install|implementation" {file}` 命中 0 次
+- [ ] `代码示例` 满足 6 条最低标准
+      验证:抽取代码块编译通过 + `grep -E "\\.\\.\\."` 命中 0 次
+- [ ] 每个 `.failure` / `catch` / `error` 分支都有 UI 可见的处理
+      验证:`grep -E "errorMessage|alert|toast"` 在每个 failure 块至少 1 处
+- [ ] 每段代码有日志锚点(带模块前缀)
+- [ ] `调用时序`:触发条件命中则必有
+- [ ] `平台特有注意事项` ≥ 1 条,每条含"必须做:"
+- [ ] `代码生成约束` MUST ≥ 3 条,MUST NOT ≥ 2 条,每条有 backtick + Verify
+      验证:`python scripts/check_must_rules.py {file}` 通过
+- [ ] 每条 MUST/MUST NOT 通过「自查三问」
+- [ ] 每条 MUST/MUST NOT 不含红旗词
+      验证:`grep -E "或|任一|等价|按业务|根据场景|留给|负责" {file}` 在 MUST 段落命中 0 次
+- [ ] `代码生成约束` 与产品级 ALWAYS/NEVER 不重复(前者管代码结构,后者管运行时行为)
+- [ ] `验证矩阵` 4 个层级各 ≥ 1 行,覆盖所有 MUST/MUST NOT
+      验证:`python scripts/check_verify_matrix.py {file}` 通过
+- [ ] `前置条件` 不重复 base-setup / login-auth 内容
+      验证:`grep -E "pod install|npm install|implementation" {file}` 命中 0 次
+- [ ] `代码示例` 满足 6 条最低标准
+      验证:抽取代码块编译通过 + `grep -E "\\.\\.\\."` 命中 0 次
+- [ ] 每个 `.failure` / `catch` / `error` 分支都有 UI 可见的处理
+      验证:`grep -E "errorMessage|alert|toast"` 在每个 failure 块至少 1 处
+- [ ] 每段代码有日志锚点(带模块前缀)
+- [ ] `调用时序`:触发条件命中则必有
+- [ ] `平台特有注意事项` ≥ 1 条,每条含"必须做:"
+- [ ] `代码生成约束` MUST ≥ 3 条,MUST NOT ≥ 2 条,每条有 backtick + Verify
+      验证:`python scripts/check_must_rules.py {file}` 通过
+- [ ] 每条 MUST/MUST NOT 通过「自查三问」
+- [ ] 每条 MUST/MUST NOT 不含红旗词
+      验证:`grep -E "或|任一|等价|按业务|根据场景|留给|负责" {file}` 在 MUST 段落命中 0 次
+- [ ] `代码生成约束` 与产品级 ALWAYS/NEVER 不重复(前者管代码结构,后者管运行时行为)
+- [ ] `验证矩阵` 4 个层级各 ≥ 1 行,覆盖所有 MUST/MUST NOT
+      验证:`python scripts/check_verify_matrix.py {file}` 通过
+
+### Slice 整体 DoD(提交合并前)
+### Slice 整体 DoD(提交合并前)
 
 - [ ] 通过第二节的 4 个拆分问题自查（特别是**问题 4：能被 ≥2 个场景复用**）
-- [ ] 在 `index.yaml` 中登记，`status` 标记为 `active` 或 `planned`
+- [ ] 在对应的 per-product platform index 中登记，`status` 标记为 `active` 或 `planned`
 - [ ] 如果是反馈 slice（🅱️），在描述中说明其对应的用户高频问题来源
 
 ---
@@ -489,58 +2529,96 @@ api_docs:                   # [必填] 该平台 API 参考文档链接（至少
 
 ### 6.1 Slice 之间的引用规范
 
-目的：避免重复写、避免知识孤岛、让 AI 能沿着引用链找到完整上下文。
+目的:避免重复写、避免知识孤岛、让 AI 沿引用链找到完整上下文。
+目的:避免重复写、避免知识孤岛、让 AI 沿引用链找到完整上下文。
 
 #### 何时必须引用、不允许重复
 
-以下内容已由专门 slice 承载，其他 slice **必须引用、不允许重复**：
-
 | 内容 | 承载 slice |
 |------|-----------|
 | SDK 安装、主包依赖、基础权限声明 | `{product}/login-auth` 或 `{product}/base-setup` |
 | 登录认证流程 | `{product}/login-auth` |
 | 跨 slice 复用的错误码总表 | `{product}/error-codes` |
-| 设备开关（摄像头/麦克风） | `{product}/device-control` |
+| 设备开关(摄像头/麦克风) | `{product}/device-control` |
+| 设备开关(摄像头/麦克风) | `{product}/device-control` |
 
-引用写法统一：
+引用写法统一:
+引用写法统一:
 ```markdown
-见 [login-auth 平台 slice](../login-auth.md)（SDK 安装、Info.plist 权限）
-→ 前置依赖：`LoginStore.shared.isLogin == true`（→ live/login-auth）
+见 [login-auth 平台 slice](../login-auth.md)(SDK 安装、Info.plist 权限)
+→ 前置依赖:`LoginStore.shared.isLogin == true`(→ live/login-auth)
+见 [login-auth 平台 slice](../login-auth.md)(SDK 安装、Info.plist 权限)
+→ 前置依赖:`LoginStore.shared.isLogin == true`(→ live/login-auth)
 ```
 
 #### 何时允许适度重复
 
-仅以下两种情况允许少量重复：
+仅以下两种情况:
+仅以下两种情况:
 
-1. **单行关键代码** — 如果不复述一行代码会让阅读体验跳跃（比如 `import Combine`），可以保留这一行并备注"详见 xxx slice"
-2. **错误码的本地化提示文案** — 可以在各自 slice 中重复出现，因为每个 slice 的错误码含义上下文不同
+1. **单行关键代码** — 不复述会让阅读跳跃(如 `import Combine`),保留一行并备注"详见 xxx slice"
+2. **错误码的本地化提示文案** — 各 slice 上下文不同,可重复
+1. **单行关键代码** — 不复述会让阅读跳跃(如 `import Combine`),保留一行并备注"详见 xxx slice"
+2. **错误码的本地化提示文案** — 各 slice 上下文不同,可重复
 
 #### 引用格式统一
 
 | 场景 | 统一写法 |
 |------|---------|
-| 正文引用其他 slice | `[slice-id](相对路径.md)` 或 `（→ slice-id）` |
-| 代码注释中标注依赖 | `// 前置：xxx 完成（→ slice-id）` |
-| Frontmatter 中的 related | 只写 `slice-id`，不带路径 |
-| 指向官方文档 | 放在平台文件的 `api_docs` 中，正文不重复 URL |
+| 正文引用其他 slice | `[slice-id](相对路径.md)` 或 `(→ slice-id)` |
+| 代码注释中标注依赖 | `// 前置:xxx 完成(→ slice-id)` |
+| Frontmatter 中的 related | 只写 `slice-id`,不带路径 |
+| 指向官方文档 | 放在平台文件 `api_docs`,正文不重复 URL |
+| 正文引用其他 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 内部只声明依赖，不决定生命周期宿主 |
+| 单一能力的完整实现(含所有角色、所有失败分支) | **Slice** | slice 是零件,必须自洽 |
+| 同一能力内部的多步骤先后顺序(申请→等待→开设备) | **Slice** | 属于该能力内部时序 |
+| 多个能力之间的组装顺序(登录→进房→推流→连麦) | **Scenario** | scenario 才知道全局顺序 |
+| 业务选型决策(选 1v1 通话还是多人连麦) | **Scenario** | slice 不关心业务形态 |
+| 跨能力的状态共享(登录 Store 在哪个层级持有) | **Scenario** | slice 内部只声明依赖 |
+| 单一能力的完整实现(含所有角色、所有失败分支) | **Slice** | slice 是零件,必须自洽 |
+| 同一能力内部的多步骤先后顺序(申请→等待→开设备) | **Slice** | 属于该能力内部时序 |
+| 多个能力之间的组装顺序(登录→进房→推流→连麦) | **Scenario** | scenario 才知道全局顺序 |
+| 业务选型决策(选 1v1 通话还是多人连麦) | **Scenario** | slice 不关心业务形态 |
+| 跨能力的状态共享(登录 Store 在哪个层级持有) | **Scenario** | slice 内部只声明依赖 |
 | 某个能力特有的 UI 定制点 | **Slice** | UI 定制依附于能力 |
 | 场景级的 UI 布局/导航流程 | **Scenario** | 属于场景形态 |
 
-**反例自查**：
-- ❌ 一个 slice 的代码示例里写了「先调用登录、再调用本能力」 → 登录的组装应该交给 scenario，slice 只声明 `// 前置：登录完成（→ xxx）`
-- ❌ 一个 scenario 里大段贴某个能力的完整失败处理代码 → 应该是 scenario 引用 slice，而不是抄写 slice
+**反例自查**:
+- ❌ 一个 slice 的代码示例里写了「先调用登录、再调用本能力」 → 登录的组装应该交给 scenario,slice 只声明 `// 前置:登录完成(→ xxx)`
+- ❌ 一个 scenario 里大段贴某个能力的完整失败处理代码 → 应该是 scenario 引用 slice,而不是抄写 slice
+**反例自查**:
+- ❌ 一个 slice 的代码示例里写了「先调用登录、再调用本能力」 → 登录的组装应该交给 scenario,slice 只声明 `// 前置:登录完成(→ xxx)`
+- ❌ 一个 scenario 里大段贴某个能力的完整失败处理代码 → 应该是 scenario 引用 slice,而不是抄写 slice
 
 ---
 
+## 附录:验证脚本清单
+
+本 spec 引用的所有 `python scripts/xxx.py` 必须真实存在,否则三件套是空头支票。脚本位于 `scripts/` 目录:
+
+| 脚本 | 作用 |
+|------|------|
+| `validate_frontmatter.py` | 检查 frontmatter 字段齐全 + 与 index.yaml 一致 |
+| `validate_api_docs.py` | 检查 api_docs 链接可访问 + 路径含 `/documentation/` 或 `/api/` |
+| `check_must_rules.py` | 红旗词扫描 + 每条 MUST 都有 Verify + Verify 内有 backtick |
+| `check_verify_matrix.py` | 验证矩阵 4 层各 ≥1 + 覆盖所有 MUST |
+| `extract_code.py` | 抽取 markdown 中的代码块,供编译验证 |
+## 附录:验证脚本清单
+
+本 spec 引用的所有 `python scripts/xxx.py` 必须真实存在,否则三件套是空头支票。脚本位于 `scripts/` 目录:
+
+| 脚本 | 作用 |
+|------|------|
+| `validate_frontmatter.py` | 检查 frontmatter 字段齐全 + 与 index.yaml 一致 |
+| `validate_api_docs.py` | 检查 api_docs 链接可访问 + 路径含 `/documentation/` 或 `/api/` |
+| `check_must_rules.py` | 红旗词扫描 + 每条 MUST 都有 Verify + Verify 内有 backtick |
+| `check_verify_matrix.py` | 验证矩阵 4 层各 ≥1 + 覆盖所有 MUST |
+| `extract_code.py` | 抽取 markdown 中的代码块,供编译验证 |