@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/scenario-spec.md

@@ -0,0 +1,350 @@
+# Scenario 文件写作规范（Spec）
+
+> 本文档定义 `knowledge-base/scenarios/{scenario-id}.md` 的标准结构。
+> 新建场景文件按本规范写；老文件按本规范逐步对齐。
+> 配套：`slice-spec.md`（slice 级规范）、`index.yaml`（场景索引）。
+
+---
+
+## 一、scenario 文件的角色
+
+scenario 文件是 **topic skill 的场景剧本**。topic 接到一个场景 id 后，把这份文件当 ground truth，按它说的：
+
+- 列出场景包含哪些能力（slice）
+- 决定是否让用户在"主链路 / 完整版"之间选 coverage
+- 走每一步 slice 集成
+
+→ **写 scenario 文件 = 给 topic 提供执行剧本**，措辞应面向"AI 读这份文件后该做什么"。
+
+---
+
+## 二、两种场景形态：A vs B
+
+每个场景按自身性质二选一形态，**不强制都要分层**。
+
+| 形态 | 适用场景 | 特征 | 用户是否参与 coverage 选择 |
+|---|---|---|---|
+| **A：单一完整能力** | 所有 slice 缺一不可：1v1 通话、秀场直播间、电商直播等 | 能力不可拆，少一个就不成场景 | 否 |
+| **B：主链路 + 可选增强** | 有清晰的"开箱可用最小集 + 推荐增强"边界：通用会议、协作工具等 | 主链路是默认，增强按需 | 是（minimal / complete 二选一，或可选模块多选） |
+
+**形态 B 的两种 coverage 粒度：**
+
+- **B-二选一（minimal / complete）**：增强项作为一个整体,用户在"主链路"和"完整版"之间二选一。写 `enhancement_level`。
+- **B-多选（必装骨架 + 可选模块多选）**：增强项彼此独立、用户通常只要其中几项(典型如通用会议:要屏幕共享和预约,但不要美颜)。此时**必装骨架 always on,可选模块逐项多选,默认只勾选命中用户 `target_features` / 原始 prompt 的项**,结果写入 `confirmed_plan = 必装骨架 + 选中模块`。
+  - 选这种粒度的判据:可选项之间没有"要就全要"的耦合,且默认全装会给用户塞他没要的功能(over-integration)。
+  - 反模式:把这类场景写成 Form A(整张 `slices:` 全集默认安装)——这正是"用户没要美颜却被装上美颜"的根因,**禁止**。
+  - 章节写法见下方「形态 B：能力展示 + coverage」的多选变体说明;参考实现 `scenarios/conference/base/general-conference.md`。
+
+形态判断准则：
+- 写 P1 之前先问自己——"如果不选这条增强，场景还能成立吗？" 能 → P1；不能 → P0。
+- 整个场景全部 slice 都"少一个就不成立" → 直接走 A 形态，不必硬掰。
+
+不确定时 default 走 A，将来发现确实有可选项再升级到 B。
+
+---
+
+## 三、必备章节
+
+每个 active scenario 文件 **必须** 包含以下章节。命名可微调，章节角色和顺序不能动。带 (A) (B) 标记的章节按形态二选一写法。
+
+### 1. `## 场景概述`
+
+一段 2-4 行散文，回答三个问题：
+- 这个场景对应什么真实业务（举 1-2 个具体例子）
+- 用户做这种场景的核心诉求是什么
+- 与其他相似场景如何区分（边界划清）
+
+**用途**：topic Step 1.5 展示给用户的"我帮你定位到了什么场景"的依据。
+
+### 2. `## 能力清单` (A) 或 `## 能力分层` (B)
+
+**slice id 必须与 `index.yaml` 一致**。
+
+#### 形态 A：能力清单
+
+```markdown
+## 能力清单
+
+- `<product>/<slice-id>` —— {一句话功能描述（中文，UI 上能直接用做按钮 label / 设置项标题）}
+- ...
+```
+
+#### 形态 B：能力分层
+
+```markdown
+## 能力分层
+
+### P0 主链路（必装）
+
+- `<product>/<slice-id>` —— {一句话}
+- ...
+
+### P1 常见增强（可选）
+
+- `<product>/<slice-id>` —— {一句话}
+  - 推荐默认勾选：是 / 否
+- ...
+```
+
+**P1 字段说明（仅形态 B）**：
+
+| 字段 | 含义 | 取值 |
+|---|---|---|
+| `推荐默认勾选` | minimal coverage 时是否仍当作必装；complete 时是否预选 | 是 / 否 |
+
+### 3. `## 能力展示` (A) 或 `## 能力展示与 coverage 选择` (B)
+
+**topic Step 1.5 直接照抄的展示模板**。包含展示文案 + (B 形态特有) AskUserQuestion 选项。
+
+#### 形态 A：能力展示
+
+```markdown
+## 能力展示
+
+### 展示文案
+
+我帮你定位到「{场景中文名}」场景，包含以下 {总数} 项能力：
+
+  • {slice 1 中文名} (`{slice id}`)
+  • {slice 2 中文名} (`{slice id}`)
+  ...
+
+接下来开始集成。
+```
+
+A 形态不向用户提问 coverage，topic 展示完直接进 Step 2。
+
+#### 形态 B：能力展示 + coverage
+
+```markdown
+## 能力展示与 coverage 选择
+
+### 展示文案
+
+我帮你定位到「{场景中文名}」场景，包含以下能力：
+
+📋 主链路（必装，{P0 count} 项）
+  • {P0 slice 1 中文名} (`{slice id}`)
+  • {P0 slice 2 中文名} (`{slice id}`)
+  ...
+
+➕ 增强能力（可选，{P1 count} 项）
+  • {P1 slice 1 中文名} (`{slice id}`) {如"推荐默认勾选 = 是"，加 ✓}
+  ...
+
+集成哪种？
+1) 主链路（最快，开箱可用基础{场景类型}）
+2) 完整版（含全部 {总数} 项能力，推荐）
+
+### AskUserQuestion 选项
+
+| 选项 | label | 写入 session |
+|---|---|---|
+| 1 | 主链路 | `enhancement_level: minimal` |
+| 2 | 完整版 | `enhancement_level: complete` |
+```
+
+**B-多选变体（必装骨架 + 可选模块多选）**：当增强项彼此独立、不应默认全装时,用这种写法替代上面的二选一表。章节里必须包含:
+
+```markdown
+## 能力展示与 coverage 选择
+
+### 必装骨架(always on,不向用户提问)
+- `<product>/<skeleton-slice>` —— ...
+
+### 可选模块(多选,默认只勾选命中用户需求的项)
+- `<product>/<optional-slice>` —— ...
+
+### 执行规则(topic 必须遵守)
+1. 预勾选 = 仅命中 `target_features` / 原始 prompt 的可选模块;其余默认不勾。
+2. 展示文案(说明骨架默认装 + 已识别到的增强项)。
+3. AskUserQuestion 多选(超 4 项分组拆问)。**每组必须包含「以上都不需要」选项（value=`none`），放在末尾，作为用户显式拒绝该组所有能力的出口。选中`none`时该组其他选项视为未勾选。**
+4. 写 `confirmed_plan = 必装骨架 + 选中模块`(唯一下游真源)。
+5. 未选中的模块不得进 `confirmed_plan`,也不得在代码里顺手生成。
+6. `enhancement_level` 仅兼容:全选 → complete,否则 → minimal。
+```
+
+topic Step 1.5 会识别这种章节并按「执行规则」走,而不是把整张 `slices:` 当默认全集。
+
+### 4. `## 前置条件`
+
+集成前用户必须做的事（控制台配置、SDK 版本、账号开通、平台权限等）。topic Step 2 展示给用户。
+
+```markdown
+- 已开通 TRTC 服务并获取 SDKAppID 和 SecretKey
+- {平台} SDK 版本 ≥ {version}
+- {权限 / 配置 / 其他}
+```
+
+### 5. `## 验收 Checklist`
+
+集成完成后用户用来自检"我这套真的跑起来了吗"的清单。topic Step 完成后展示。
+
+```markdown
+- [ ] 用户能登录并进入会议
+- [ ] 摄像头 / 麦克风可以正常打开关闭
+- [ ] {针对本场景的特有验收点}
+- [ ] {...}
+```
+
+### 6. `## 排障速查`（可选但强烈建议）
+
+把场景下高频出错的 3-5 个症状 → 排查路径列出。**不重复 slice 内的排障**，只列**跨 slice、属于场景级的**问题。
+
+例如通用会议场景：
+- "进得去房但是看不到别人画面" → 检查推流 + 拉流 + 视频布局三个 slice 的状态
+- "聊天发不出去" → 检查会控秩序是否禁聊 + room-chat slice 状态
+
+---
+
+## 四、可选章节
+
+按需写，不强制：
+
+- `## 子场景命中差异` —— 同一场景下不同子形态（如"日常团队会议" vs "培训会议"）的 slice 增减建议
+- `## 跨产品依赖` —— 本场景依赖其他产品 SDK 时的说明
+- `## 设计取舍` —— 为什么这个场景这么拆、和兄弟场景的边界（给后续 scenario 作者看的设计笔记）
+
+---
+
+## 五、字段一致性检查
+
+写完 scenario 文件，检查：
+
+| 检查项 | 哪两处必须一致 |
+|---|---|
+| slice id 列表 | `index.yaml` `scenarios.<id>.slices` 数组 ↔ 本文件「能力清单」(A) 或 「能力分层」(B) 总和 |
+| 中文名 | 「能力清单 / 能力分层」中的 slice 名 ↔ 「能力展示」展示文案中的 slice 名 |
+| `推荐默认勾选 = 是`（仅 B） | 必须在「能力展示」展示文案的 ✓ 标记列表 |
+
+未来可加 `scripts/validate_scenario.py` 自动跑这些检查。
+
+---
+
+## 六、模板骨架
+
+### A 形态模板（单一完整能力）
+
+适合：1v1-video-call、entertainment-live-room 等场景所有 slice 缺一不可的情况。
+
+```markdown
+# {场景中文名}（{scenario-id}）
+
+## 场景概述
+
+{2-4 行散文}
+
+## 能力清单
+
+- `{product}/{slice-id-1}` —— {一句话}
+- `{product}/{slice-id-2}` —— {一句话}
+- ...
+
+## 能力展示
+
+### 展示文案
+
+我帮你定位到「{场景中文名}」场景，包含以下 {总数} 项能力：
+
+  • {slice 1 中文名} (`{slice id}`)
+  • {slice 2 中文名} (`{slice id}`)
+  • ...
+
+接下来开始集成。
+
+## 前置条件
+
+- {条件 1}
+- {条件 2}
+
+## 验收 Checklist
+
+- [ ] {验收点 1}
+- [ ] {验收点 2}
+
+## 排障速查
+
+| 症状 | 可能原因 | 排查方向 |
+|---|---|---|
+| {症状 1} | {原因} | {slice / 配置项} |
+```
+
+### B 形态模板（主链路 + 可选增强）
+
+适合：general-conference、协作工具等有清晰 P0/P1 边界的场景。
+
+```markdown
+# {场景中文名}（{scenario-id}）
+
+## 场景概述
+
+{2-4 行散文}
+
+## 能力分层
+
+### P0 主链路（必装）
+
+- `{product}/{slice-id-1}` —— {一句话}
+- `{product}/{slice-id-2}` —— {一句话}
+
+### P1 常见增强（可选）
+
+- `{product}/{slice-id-3}` —— {一句话}
+  - 推荐默认勾选：是
+- `{product}/{slice-id-4}` —— {一句话}
+  - 推荐默认勾选：否
+
+## 能力展示与 coverage 选择
+
+### 展示文案
+
+我帮你定位到「{场景中文名}」场景，包含以下能力：
+
+📋 主链路（必装，{P0 count} 项）
+  • {P0 slice 1 中文名} (`{slice id}`)
+  • ...
+
+➕ 增强能力（可选，{P1 count} 项）
+  • {P1 slice 1 中文名} (`{slice id}`) ✓
+  • {P1 slice 2 中文名} (`{slice id}`)
+  • ...
+
+集成哪种？
+1) 主链路（最快，开箱可用基础{场景类型}）
+2) 完整版（含全部 {总数} 项能力，推荐）
+
+### AskUserQuestion 选项
+
+| 选项 | label | 写入 session |
+|---|---|---|
+| 1 | 主链路 | `enhancement_level: minimal` |
+| 2 | 完整版 | `enhancement_level: complete` |
+
+## 前置条件
+
+- {条件 1}
+- {条件 2}
+
+## 验收 Checklist
+
+- [ ] {验收点 1}
+- [ ] {验收点 2}
+
+## 排障速查
+
+| 症状 | 可能原因 | 排查方向 |
+|---|---|---|
+| {症状 1} | {原因} | {slice / 配置项} |
+```
+
+---
+
+## 七、对老文件的迁移建议
+
+老文件不强制立刻按 spec 重写。建议路径：
+
+1. **`general-conference.md`** → 走 B 形态。原文里已有"P0 默认会议骨架 / P1 按需补命中"分层结构，只需补「能力展示与 coverage 选择」「验收 Checklist」两节，其他内容可移到「设计取舍」可选章节。
+
+2. **`entertainment-live-room.md`** → 走 A 形态。原文按"主播端流程 / 观众端流程 / 阶段一 / 阶段二"组织，先按 spec 改为「能力清单」「能力展示」+ 验收 Checklist；流程描述可保留为「子场景命中差异」可选章节。
+
+3. **新建场景** → 直接走 spec，按形态选 A 或 B 模板。