@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.5

package/skills/trtc-chat/references/05-slice-loading.md

@@ -0,0 +1,139 @@
+# 05 - Slice 命中机制 + 多候选选择 + 兜底
+
+> dispatcher 在以下三个时机主动 `read_file` 本文件：
+> - 路径 A 的 **A.1.5 被动解析**（命中扩展 slice / 收集 unsupported_intents）
+> - 路径 A 的 A.5 引导菜单选中后
+> - 路径 B 的 B.2 听需求阶段
+
+## 5.1 命中流程
+
+```
+1. Bash `python3 -m tools.kb resolve chat/web/index.yaml` → Read
+   （含所有 slice 的 frontmatter 摘要：id / description / trigger-keywords /
+    applies-to / sdk-version / prerequisites）
+
+2. 解析用户需求（动词 + 名词 + 业务术语）
+   - 动词：发送 / 加 / 实现 / 接 / 显示 / 接收 / 撤回 / 搜索 / ...
+   - 名词：消息 / 卡片 / 群 / 会话 / 已读 / ...
+   - 业务术语：订单 / 商品 / 优惠券 / 红包 / 投票 / 客服 / 评价 / ...
+
+3. 在 trigger-keywords 中找语义匹配的 slice
+   ⚠ 注意：trigger-keywords 是给 LLM 看的元数据，不是 grep 字段。
+     用语义能力做模糊命中，不依赖精确字符串匹配。
+
+4. 多个候选时，按下面 §5.2 排序
+
+5. 命中 → read_file 读 slice 完整内容 → 进入写代码阶段
+
+6. 完全没命中 → §5.3 兜底
+   - 路径 A.1.5 场景：归入 unsupported_intents，A.4 口头收尾时一并提示，**不**进 §5.3 兜底实现
+   - 路径 B B.2 场景：进 §5.3 兜底实现 + 提 issue
+```
+
+## 5.2 多候选排序
+
+按以下优先级降序：
+
+1. `applies-to` 匹配当前项目集成方式（`tuikit-atomicx-vue3`）
+2. `sdk-version` 匹配项目实际 SDK 版本（`package.json` 里的 `tuikit-atomicx-vue3` 版本）
+3. `prerequisites` 链与 `session（session_context.chat）` 已完成项匹配的越多越优
+   - 路径 A.1.5 场景：`base_slices_applied` 视为已完成（4 件套基础 + 已入列的 extensionSlices）
+   - 路径 B 场景：`base_slices_applied` + `extension_slices_applied` 都视为已完成
+4. `trigger-keywords` 命中关键词数量
+
+最后仍并列时：
+
+```
+> 我找到几个 slice 都对得上：
+>   1. send-custom-message（自定义订单卡片）
+>   2. send-image-advanced（图片消息）
+>
+> 你描述的 "我要发订单消息" 是哪种？
+> 还是先做订单卡片，图片放它的字段里？
+```
+
+让用户做最后决策，不要替用户选。
+
+## 5.3 兜底分支（无 slice 命中）
+
+### 路径 A.1.5 场景（被动解析阶段）
+
+❌ **不**走 §5.3 自由实现。命中失败的意图归入 `unsupported_intents`：
+
+```jsonc
+{
+  "raw": "把消息翻译成英文",        // 用户原话
+  "intent": "message-translation",  // dispatcher 抽取的意图标签
+  "askedAt": "2026-05-20T15:22:00Z"
+}
+```
+
+A.4 收尾时在 agent 回复里说一次（按意图类别给 fallback 建议，详见 `./02-path-a-script.md` § A.4），**不写额外文件**。
+
+### 路径 B B.2 场景（已集成项目的二次增量）
+
+❗ **未命中 slice 时，禁止自由实现**——不准基于训练数据猜测 SDK 用法、不准用 `chat.xxx` 旧 API 硬写代码。
+
+输出以下话术后**停止**，等待用户反馈：
+
+```
+> 抱歉，我的知识库里暂时没有找到对应这个功能的实现指南，目前无法为您实现该功能。
+>
+> 您可以通过工单向 即时通信 IM 团队反馈，我们会评估是否将其加入 slice 库：
+> https://console.cloud.tencent.com/workorder/category
+>
+> 如果您有其他功能需求，欢迎继续告诉我。
+```
+
+❌ **以下是典型违规输出，出现即视为执行错误**：
+
+```
+// 违规：读骨架文件自由实现
+const msg = await chat.createCustomMessage({ payload: { data: '...' } })
+await chat.sendMessage({ to: targetID, message: msg })
+// → 旧 API，与 State API 架构冲突，直接导致应用崩溃
+```
+
+```
+// 违规：给"仅供参考"的示例代码
+// 以下是基于 SDK 通用规则的参考实现，仅供参考：
+const store = useMessageInputStore(conversationID)
+await store.sendMessage({ type: 'customMessage', customData: '...' })
+// → 用户会直接复制使用，没有 slice 规范约束，一定会出错，导致不可用
+```
+
+## 5.4 prerequisites 链解析（A.1.5 / B.2 共用）
+
+命中 slice 时必须递归校验 prerequisites：
+
+```
+resolveDeps(sliceId):
+  slice = index[sliceId]
+  for prereq in slice.prerequisites:
+    if prereq in base_slices_applied + extension_slices_applied + currentBatch:
+      continue   // 已满足
+    if prereq in index AND prereq not in base_slices_applied:
+      currentBatch.unshift(prereq)  // 自动补齐前置
+      resolveDeps(prereq)            // 递归
+    else:
+      throw 'unmet-prerequisite'
+
+A.1.5 场景：
+  - 链长 ≤ 2（命中 1 个 slice + 自动补齐 1 个前置）→ 静默补齐
+  - 链长 ≥ 3 → 把整条链显式列给用户："为了实现 X，需要同时装 Y / Z，确认吗？"
+                用户拒绝 → 整个意图降级到 unsupported_intents
+
+B.2 场景：
+  - 任意链长都显式列给用户确认（路径 B 是用户主动驱动，不容易因链长惊到）
+```
+
+## 5.5 命中失败的常见原因（自查清单）
+
+dispatcher 自己使用，不是给用户看的：
+
+- 关键词在 `trigger-keywords` 里漏列了 → 提 issue 补关键词
+- 用户用的是别名（如把 "已读回执" 说成 "看过没") → 适当扩词
+- 用户描述的是组合场景（如 "群里发订单") → 命中两个 slice，先后实现
+- 场景超出当前 features 范围（如客服分配系统） → 走 §5.3 兜底
+- A.1.5 阶段意图 confidence < 0.7 → 直接丢弃，不进 unsupported_intents（避免污染 session（session_context.chat））
+

package/skills/trtc-chat/references/06-a-defensive-coding.md

@@ -0,0 +1,139 @@
+# 06-a - 防御编程统一规范
+
+> 所有 slice 的 API 调用必须遵循本文件规范。dispatcher 写代码前与 `06-hard-rules.md` 并行 `read_file`。
+
+---
+
+## 6a.1 异步 API 调用范式
+
+所有 SDK 异步调用必须遵循以下模板：
+
+```ts
+import { formatError } from '@/im/error-map'
+
+const loading = ref(false)
+
+async function handleAction() {
+  loading.value = true
+  try {
+    await sdkApi(...)
+    // 成功处理
+  } catch (err: any) {
+    showFeedback(formatError(err))  // 见 § 6a.3，必须给用户可见反馈
+  } finally {
+    loading.value = false
+  }
+}
+```
+
+❌ **禁止**：
+- `try/finally` 无 `catch`（失败静默吞掉）
+- `catch` 里只 `console.error` 不给 UI 反馈
+
+---
+
+## 6a.2 错误反馈形式
+
+根据操作类型选择不同的反馈形式：
+
+| 操作类型 | 反馈形式 | 原因 |
+|---|---|---|
+| **发消息** | 输入框附近就近显示小字 | 不打断输入流，用户可直接重试 |
+| **加载消息/会话列表** | 列表区域内空态提示 + 重试按钮 | 不遮挡已有内容 |
+| **写操作**（撤回/删除/置顶/免打扰/清空） | Toast（2-3 秒自动消失） | 轻量提示，不需要用户主动关闭 |
+| **登录失败** | 就地显示错误 | 需要引导用户操作 |
+
+❗ **有 UI 库时优先用 UI 库的 Toast/Message 组件；无 UI 库时自建最小 Toast（有 Tailwind/SCSS）或 `alert()`（空项目，标 TODO）**
+
+### Toast / 错误提示视觉规范
+
+- **颜色**：使用项目 error 色（UI 库的 `type="error"` / `variant="destructive"` / 红色系），不准用默认灰色或 info 色
+- **显示位置**：居中或偏上（`top-center`），不准显示在底部——底部容易被输入框或 toolbar 遮挡
+- **z-index**：`9999`，确保不被页面其他层遮挡
+- **最大宽度**：`max-width: 360px`（或项目 Toast 组件已有的最大宽度约束，跟随项目规范）
+- **文字换行**：`word-break: break-word`，不准单行溢出截断（`text-overflow: ellipsis`）——错误信息必须完整可读，不能被截断
+- **自建 Toast 无 UI 库时**：
+  ```css
+  .toast-error {
+    max-width: 360px;
+    word-break: break-word;
+    /* error 色跟随项目 CSS 变量或 Tailwind token */
+  }
+  ```
+
+---
+
+## 6a.3 错误信息内容
+
+❗ **禁止把 SDK 原始错误 JSON 直接暴露给用户**
+
+❗ **`ERROR_MAP` 和 `formatError` 必须提取为共用模块**，不准在每个组件里各自定义：
+
+```
+src/im/error-map.ts   ← 统一维护，各组件 import 使用
+```
+
+参考实现（`src/im/error-map.ts`）：
+
+```ts
+const ERROR_MAP: Record<number, string> = {
+  20003: '对方账号不存在，请确认 userID 是否正确；可先用该 userID 登录一次，或在腾讯云 IM 控制台手动创建',
+  70001: '登录凭证已过期，请重新生成 UserSig 后再登录',
+  70003: '登录凭证解析失败，请使用官网提供的 API 重新生成 UserSig',
+  70009: 'UserSig 验证失败，请检查请求的 SDKAppID 和生成 UserSig 的密钥或私钥是否一致',
+  70013: '请求的 UserID 与生成 UserSig 时使用的 UserID 不一致，可使用 IM 控制台 UserSig 生成&校验工具校验',
+  70014: '请求的 SDKAppID 与生成 UserSig 时使用的 SDKAppID 不一致，可使用 IM 控制台 UserSig 生成&校验工具校验',
+  10015: '群组不存在或已经被解散，请确认群组 ID 是否正确',
+  2501:  '对方账号不存在，请确认 userID 是否正确；可先用该 userID 登录一次，或在腾讯云 IM 控制台手动创建',
+  2801:  '网络请求超时，请检查网络连接',
+}
+
+export function formatError(err: any): string {
+  const code = err?.code
+  return ERROR_MAP[code] ?? err?.errorMessage ?? '操作失败，请稍后重试'
+}
+```
+
+> `error.errorMessage` 是 SDK 返回的错误描述字段，比 `err.message`（JS 原生 Error）更准确。优先用映射表，映射表未覆盖时才降级显示 `errorMessage`。
+
+各组件使用方式：
+
+```ts
+import { formatError } from '@/im/error-map'
+
+} catch (err: any) {
+  showFeedback(formatError(err))
+}
+```
+
+---
+
+## 6a.4 状态锁规则
+
+状态锁用于表达 loading 态（禁用按钮、显示加载中），必须在 `finally` 里复位：
+
+| 操作类型 | 锁变量命名 |
+|---|---|
+| 发消息 | `sending` |
+| 加载列表/消息 | `loading` / `loadingOlder` |
+| 登录/登出 | `loggingIn` |
+| 写操作（撤回/删除等） | `submitting` / `loading` |
+
+❗ 状态锁必须在 `finally` 里复位，不能在 `try` 里复位（catch 路径会跳过）
+
+---
+
+## 6a.5 入参校验规则
+
+以下情况必须做入参校验，不满足条件直接 `return`（不发请求）：
+
+| 参数 | 校验条件 |
+|---|---|
+| 文本消息内容 | `text.trim().length > 0` |
+| userID | 非空字符串 |
+| conversationID | 非空字符串 |
+| 文件大小 | 图片 ≤ 20MB / 视频 ≤ 100MB / 文件 ≤ 100MB |
+
+❌ **禁止**：空 userID / 空文本直接发请求（会触发 SDK 报错，体验差且浪费请求）
+
+> ❗ **调用顺序约束**（发消息前必须等 login resolve）见 `06-hard-rules.md § 6.1`。

package/skills/trtc-chat/references/06-hard-rules.md

@@ -0,0 +1,190 @@
+# 06 - Hard rules 全量版（含反例）
+
+> 主 SKILL.md 仅保留摘要。dispatcher 在写代码 / 自检前主动 `read_file` 本文件。首次加载后可缓存到当前会话上下文。
+
+## 两大绝对约束（违反任一必须返工，不可跳过）
+
+> **SDK API 正确性** 和 **视觉规范** 是同级的绝对约束，不存在"功能先跑起来、UI 后期再改"的优先级。
+> - SDK API 错误 → 运行时崩溃，交付物不可用
+> - 视觉规范违反 → 交付物不达标，同样视为返工
+
+❗ **写每一个组件前**，先问自己两个问题：
+1. 这个组件调用的 SDK API 是否来自 slice §3，还是从训练数据猜的？
+2. 这个组件打开后视觉上是否达标？容器有没有从底色浮起？颜色是否超过 1 个主色？间距/圆角/字号是否命中锚点值？气泡圆角是否不对称？
+
+---
+
+## 6.1 SDK API 是绝对真理
+
+### ❗ 不准从训练数据猜 API 名称
+LLM 训练数据里有大量过期 / 错版的腾讯云 IM SDK 调用方式（如 `tim.sendMsg` 之类的旧名），**所有 SDK 调用必须从 slice 的"§ 3 SDK API 必读"段落里复制**。
+
+❌ 反例：
+```ts
+// 不准这样写
+tim.sendMsg({ to: 'user1', body: 'hi' });
+```
+
+✅ 正例（来自 slice）：
+```ts
+import { useMessageInputStore } from 'tuikit-atomicx-vue3/chat'
+const { sendMessage } = useMessageInputStore(conversationID)
+await sendMessage({ type: 'textMessage', text: 'hi' })
+```
+
+### ❗ payload 必须 `JSON.stringify` 后传 SDK
+自定义消息的 `data` / `description` / `extension` 等字段，SDK 期望的是字符串。
+
+❌ 反例：
+```ts
+chat.createCustomMessage({ payload: { data: { orderId: 1 } } }); // 直接传对象
+```
+
+✅ 正例：
+```ts
+chat.createCustomMessage({
+  payload: {
+    data: JSON.stringify({ orderId: 1 }),       // ✅ 字符串
+    description: '订单卡片',
+    extension: '',
+  },
+});
+```
+
+### ❗ businessID 必须有可读语义
+- 必须与卡片业务强相关（如 `order` / `product` / `coupon` / `red-packet` / `rating`）
+- 团队若有命名空间约定（如 `trtc/*` / `biz/*` / `shop/*`）→ 跟随团队约定
+- ❌ 不准写 `'1'` / `'123'` / `'custom'` / `'card'` / `'msg'` 等无语义裸值
+- 评价卡片不再是默认 demo（v0.2 起已并入 `send-custom-message` slice，businessID 自定义如 `rating` / `customer-rating`）
+
+### ❗ 发送消息前必须 `await` login resolve
+未登录就调 send → SDK 会抛 60016 / 60005 等。
+
+✅ 正例：
+```ts
+await chat.login({ userID, userSig });   // 必须等
+await chat.sendMessage(message);
+```
+
+### ❗ 不准改用户已有组件内部实现
+- 一律在用户业务代码层用 State API 直接调 SDK
+- 不准 `document.querySelector('.tui-chat-input')` 这类 hack 已有组件 DOM
+- 不准用 `:deep(...)` 强改用户既有组件样式
+- 增量功能写在自己新建的业务组件里，与项目已有组件并存（含可能存在的 UIKit）
+
+---
+
+## 6.2 UI 是自由的，但守 3 条底线
+
+> 样式由 AI 自由发挥，不预设审美规则。但必须遵循项目已有 CSS 方案和 UI 库。
+
+❗ **写任何 UI 组件代码前，必须先** Bash `python3 -m tools.kb resolve slices/chat/web/style-guide.md` → Read（用色 / 圆角 / 间距 / 视觉禁区 / 精细化手法全在里面），所有 starter / feature slice 的 UI 部分均适用。
+
+### ❗ 必须使用项目已有 CSS 方案和 UI 库
+- 探测到 Tailwind → 用 Tailwind utility，不要再引一套 CSS
+- 探测到 Element Plus → 用 `<el-card>` `<el-button>`，不要手撸 div
+- 探测到 shadcn → 用 `<Card>` `<Dialog>`，不要再装新 UI 库
+- 空项目（无已有体系）→ 路径 A 默认装 Tailwind，AI 自由写样式
+
+### ❗ 必须复用项目已存在的同类组件
+- `src/components/ui/card.vue` 存在 → 卡片消息复用，不再新建
+- `src/components/ui/dialog.vue` 存在 → 详情弹窗复用
+
+### ❗ 必须遵循项目现有命名约定
+- 文件名：跟 `src/components/*` 现有大小写一致
+- 组件名：跟现有 `<script setup>` / Options API 风格一致
+- TS 类型：跟现有 interface / type 命名一致
+
+---
+
+## 6.3 增量改动安全
+
+### ❗ patch 文件前必须先 `read_file`
+- 用户可能在你上次 read 之后改过文件
+- 直接 patch 会覆盖未读到的最新改动
+
+### ❗ 不准改用户已有的 SDK 初始化 / 登录代码
+- 路径 B 项目里 `src/im/init.ts` 里的 `chat.create` / `chat.login` 已经在跑
+- 增量功能必须在用户已有的 chat 实例上调 API
+- 如果发现 init 写法陈旧 / 有 bug → 先告知用户，不要默默改
+
+### ❗ Plan 阶段必须显式列出"不会改的东西"
+- 这是给用户的承诺，也是 dispatcher 自己的红线
+- 模板见 `03-path-b-script.md` B.4
+
+### ❗ 写文件前必须确认改动清单（用户可打断）
+- 列出所有要新增 / 修改的文件路径
+- 等用户回"开始" / "调整：xxx" 再动手
+- 用户说"按你判断"等同于"开始"
+
+---
+
+## 6.4 逐 slice 闭环 + 禁止预读（long-context 退化对策）
+
+> 这一节 hard rules 适用于**所有**多 slice 场景：路径 A 的 A.3 基础 4 件套 + A.3.x 扩展 N 件套（N ≤ 3），以及路径 B 一次需求命中多个 slice（如"群里发订单卡片"同时命中 `group-chat` + `send-custom-message`）的情况。
+
+### ❗ 禁止预读
+- 写第 N 个 slice 时，**不准** `read_file` 第 N+1、N+2…个 slice 文件
+- 不准在 Plan 阶段批量装载所有候选 slice 再回头一个个写
+- 下一个 slice 必须在当前 slice 的 read → plan → write → self-check → 内部记账 5 步全部完成后再读
+
+### ❗ 每轮闭环
+每个 slice 的处理必须严格走 5 步：
+
+```
+Step 1  read_file 当前 slice 完整内容
+Step 2  Plan：1-3 句告诉用户本轮要写什么 / 不会改什么
+Step 3  Write：按 slice § 3 SDK API + § 4 hard rules 实现
+Step 4  Self-check：对照本 slice § 反例库
+Step 5  内部记账（仅当前会话上下文，不写盘）：
+        - 本轮已完成 slice 名
+        - 本轮新建 / 修改的文件清单
+        - 用了哪些项目已有组件（供后续轮复用）
+```
+
+Self-check 不通过就在本轮内修，**不准**带着问题进入下一个 slice。
+
+### ❗ 跨轮命名一致性
+- 第 2 个 slice 起，写代码前先回看上一轮 Step 5 的"已用组件清单"
+- 命名必须延续上一轮，不准每个 slice 另起一套
+- 如本轮发现上一轮命名有问题 → 在本轮 Plan 里显式提出"建议把上一轮的 X 改名为 Y"，征求用户同意后改；不准默默改
+
+### ❗ 扩展轮结构前瞻（防止"新卡片塞进旧气泡容器"）
+- 扩展轮（如追加自定义卡片 Bubble / 新消息类型分支）写代码**前**，必须先 `read_file` 上一轮生成的模板文件，确认：
+  1. 新组件要插入的位置——是在现有气泡容器**内部**还是**外部**？
+  2. 如果自定义卡片不应套在气泡容器内，而上一轮模板没有为此预留分支出口 → 本轮 Plan 里**必须显式提出结构重构**（把新分支提到气泡容器外面），不准偷懒直接往已有容器里塞
+  3. 重构范围写进 Plan 的"本轮要改的文件清单"，让用户可打断
+- ❌ 反例：上一轮 `message-list` 把所有 type 统一包在 `<div class="msg-bubble">` 里，扩展轮直接在 `msg-bubble` 内部加了 `<OrderCardBubble>` 组件 → 卡片被套在气泡背景/圆角/阴影里，违反"自定义卡片不套气泡"
+- ✅ 正例：扩展轮发现上一轮没有为 `MessageType.Custom` 预留"跳出气泡"的结构分支 → Plan 里写"需重构 MessageList 模板：Custom 分支提到 msg-bubble 外层" → 用户确认后再写
+
+### 为什么这条规则存在（写给 dispatcher 自己看）
+
+❌ **典型故障模式**（一次性批量读取 5 份 slice → 一次性生成全部代码时观察到的）：
+- 写到第 4、5 个 slice 时，§ 4 hard rules 已"远离视野"，幻觉 SDK API 名 / 漏 `JSON.stringify` payload / businessID 错写成无前缀
+- 不同 slice 之间组件命名不一致（`MessageBubble` vs `MsgItem` vs `ChatBubble` 同一个东西取三个名）
+- 后写的覆盖前写的命名约定，需要回头返工
+
+✅ **机制原理**：长上下文下 LLM 的 attention 对越早出现的内容衰减越严重（recency bias）。逐 slice 闭环让"当前 slice § 3 + § 4"始终是 ≤300 行内的最近上下文，attention 落在它身上；上一轮的输出通过 Step 5 的"已用组件 / token 清单"以**精炼摘要**而非"原文回滚"的方式带入下一轮，是 long-context attention dilution 的标准对策。
+
+---
+
+## 6.5 自检清单（写完后必走）
+
+- [ ] 所有 `chat.createXxxMessage` / `chat.sendMessage` 调用与 slice 一致
+- [ ] 所有 payload `data` 字段都 `JSON.stringify` 过
+- [ ] businessID 都有可读业务语义（`order` / `coupon` / `rating` 等；团队有命名空间约定就跟随），无 `'1'` / `'custom'` / `'card'` 等裸值
+- [ ] 没有引入新的 UI 库（除非 slice 明确要求）
+- [ ] 没有改 `src/im/init.ts` 等已有初始化文件（除非用户明确同意）
+- [ ] `.trtc-session.yaml`（经 `tools.session`） 已写入新 slice 名（写入字段：`extension_slices_applied` 追加 + `changes` append；详见 `08-state-config.md`）；`<projectRoot>` 由 `08-state-config.md` § 8.1.1 找根算法决定
+
+---
+
+## 6.6 引导菜单内容来源
+
+- ❗ 只列 knowledge-base 中实际存在的 slice（以 `tools.kb resolve chat/web/index.yaml` 与 `tools.kb resolve slices/chat/web/<name>.md` 为准）
+- ❗ 未命中任何 slice 的功能不出现在推荐列表中
+- ❌ 根据 SDK 通用能力推测"应该有"的 feature slice
+- [ ] 没有把临时 mock 接口写成永久代码（标 `// TODO: replace with real API`）
+- [ ] **本轮 slice 是 read → plan → write → self-check 单轮闭环完成的**（不是把 N 个 slice 一次读完再批量写；多 slice 场景见 § 6.4）
+- [ ] 所有异步 SDK 调用都有 `try/catch/finally`，`catch` 里调 `showFeedback(formatError(err))`，无静默吞错
+- [ ] 错误反馈形式符合 `06-a-defensive-coding.md § 6a.2`（发消息→就近小字 / 写操作→Toast / 加载→空态+重试）