yunxin-techsupport

核心约束

自动推进：下一步为再取证或重新定向时，自动执行，不等 TSE
等待 TSE：需要补充信息或排查方向穷尽时，必须等 TSE 响应
重新定向条件：取证结果出现原始排查方向未覆盖的新维度时，回 Phase 2a
穷尽标准：所有假设已验证/排除，且无法不依赖 TSE 新信息继续推进
循环上限：Phase 2a 重新定向 ≤ 3 次，Phase 2b 取证行动 ≤ 5 次，超限强制进入穷尽状态

工作模式

Phase 1：结构化接收 + 意图识别
         ↓
Phase 2a：知识定向（所有问题，并行检索三个知识源）
         ↓
    ┌────────────────────────┐
    │ 意图=咨询 且已有答案？  │
    └────────────────────────┘
         ↓ 否                   ↓ 是
Phase 2b：数据取证         直接进 Phase 3
（排查/取证/定责）               ↑
每轮更新「当前问题进展」         │
         ↓                      │
Phase 3：结果汇报与收敛 ─────────┤
         │                      │
         ├─ 下一步=再取证   ────▶ Phase 2b（自动）
         ├─ 下一步=重新定向 ────▶ Phase 2a（自动）
         └─ 需要 TSE 输入   ────▶ 等待 TSE 响应

Phase 1：结构化接收 + 意图识别

目标

从 TSE 的初始描述中提取结构化信息，识别意图，为行动循环提供输入。不做路由判断，不触发任何原子工具调用。

提取字段（Phase 1 通用字段，固定 4 个）

字段	说明	来源
`product`	产品域（IM / RTC / 推送 / 呼叫组件 / UIKit 等）	从描述中推断或追问
`feature`	功能域（消息发送 / 登录 / 聊天室 / 群组等）	从描述中推断
`description`	问题描述（优先保留原文关键句，自由文本，不重新归纳）	直接提取
`customer`	客户名称	从描述中提取，无则留空

注： accid、time_range、error_code、stack_trace、sdk_version 等专属字段，Phase 1 优先从 TSE 的初始描述中尝试提取；若描述中未提及，则由 Phase 2b 在执行对应取证行动前，按 action-catalog.md 中该行动的 required_inputs 声明向 TSE 追问。

意图识别

参考 references/intent-signals.md 进行意图推断，输出以下四个标签之一：

排查：有具体现象，目标是找根因
咨询：想了解功能/实现方式
取证：目标是获取线上数据证据
定责：需要判断问题责任方

意图识别结果展示在信息状态面板中，TSE 可随时纠正。

信息状态面板

每轮响应顶部固定展示，分为三层：

━━━ 信息状态 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【基础信息】
  产品：        ✓ NIM SDK
  功能：        ✓ 消息发送
  问题描述：    ✓ 群消息发不出去，私聊正常
  客户名：      ✗
  意图：        排查

【行动所需字段】
  QS 取证查询
    appkey：    ✗ 应用标识，所有查询模块基础入参
    时间范围：  ✓ 2026-04-14 20:00 前后（可选）

  SDK 源码分析
    product：   ✗ SDK 产品线（IM V9 / IM V10）
    platform：  ✗ 运行平台（Android / iOS / PC / 鸿蒙 / Flutter）
    sdk_version：✗ SDK 版本（强烈建议提供）

【当前问题进展】
  发送侧正常（7-1=200），问题定位在接收链路，
  接收方当时已离线，下一步聚焦离线推送/漫游同步。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

展示规则：

【基础信息】：Phase 1 提取的 4 个通用字段 + 意图标签，首轮即展示
【行动所需字段】：Phase 2b 首次执行前展示，按「归属行动」分组，每组标注字段用途
【当前问题进展】：Phase 2b 每轮执行后追加，覆盖式更新（不累积原始数据），作为下一轮行动的上下文输入
✓ 已确认字段（补充后永久留在面板，不消失）
✗ 待补充字段（注明所属行动及用途，TSE 可选择提供哪组）
意图识别结果可被 TSE 随时纠正
咨询路径：仅展示【基础信息】，无需展示【行动所需字段】和【当前问题进展】

Phase 2a：知识定向

目标

在执行任何取证行动前，先通过三个知识源了解问题背景、历史案例和排查方向。所有问题类型均经过此阶段。

执行方式

并行检索以下三个知识源（参考 references/action-catalog.md 定向层）：

知识源	Skill	目的
官方文档	`yunxin-official-docs`	了解功能规范和正常行为
历史案例	`nim-kb-search`	检索相似问题的历史解决方案
内部排查手册	`yunxin-internal-docs`	获取专属排查 playbook

输出：两条路径

条件	输出	下一步
意图为"咨询"且知识源已足够回答	直接答案	跳过 Phase 2b，进入 Phase 3
意图为"咨询"但知识源无法回答	缺口说明	向 TSE 追问补充信息，补充后重新检索
意图为"排查 / �取证 / 定责"	排查方向（假设 + 分支）	进入 Phase 2b

Phase 2b：数据取证

目标

基于 Phase 2a 输出的排查方向，动态选择取证行动，逐步缩小问题空间。每次行动后更新"当前问题进展"。

仅在意图为"排查 / 取证 / 定责"时执行。

执行步骤（每轮）

① 根据排查方向选择行动

结合"排查方向"和"当前问题进展"，从取证工具中选择最适合的下一步（参考 references/action-catalog.md 取证层）：

取证工具	Skill	适用场景	路径
QS 取证查询	`qs-techsupport`	需要线上数据（日志、消息记录、用户状态等，含登录事件）	已注册 action（快速路径）
SDK 源码分析	`yunxin-sdk-source-analyzer`	有崩溃堆栈，或需要验证 SDK 侧行为	已注册 action（快速路径）

② 运行时 skill 发现（回退路径）

当 action-catalog.md 取证层无合适工具时，尝试从当前运行环境中发现可用 skill：

用任何可行的方式找到与排查方向语义相关的 skill（例如：调用已安装的 skill 搜索工具、查阅已知 skill 列表、或凭上下文推断）
找到候选后，进入「展示与确认」流程（见下方规则）
未找到任何候选时，标记为能力缺口并进入 Phase 3 等待 TSE 指示

「展示与确认」规则：

发现候选 skill 后，向 TSE 展示以下信息并等待确认：

发现候选工具：[skill 名称]
匹配原因：[说明与排查方向的语义关联]
是否使用此工具？（是 / 否）

TSE 确认 → 将该 skill 作为本轮取证工具执行，继续后续步骤
TSE 拒绝 → 跳过该候选，继续匹配下一个候选；若无更多候选则标记能力缺口
若同时发现多个候选，逐一展示，待 TSE 逐一确认

② 执行前检查必要输入

参考 action-catalog.md 中该行动的 required_inputs：

✅ 全部具备 → 直接执行
❌ 有缺失 → 向 TSE 说明缺少哪些字段及其用途，等待补充后继续

③ 执行行动

调用对应的原子 Skill，获取结果。

④ 更新当前问题进展

综合已有信息和本次结果，覆盖式更新"当前问题进展"摘要（不累积原始数据，只保留当前对问题的最新理解）。

⑤ 进入 Phase 3

每完成一次取证行动后，均进入 Phase 3 汇报本轮发现并说明下一步。Phase 3 默认自动推进（TSE 沉默即继续），TSE 随时可干预调整方向或停止。

意图约束

意图	约束
`咨询`	不进入 Phase 2b
`取证`	优先选择 QS 取证查询
`定责`	同时考虑 QS 取证 + SDK 分析（双向取证）
`排查`	按排查方向自由选择

Phase 3：结果汇报与收敛

目标

每轮行动完成后，展示发现并说明下一步。有后续行动时默认自动继续，TSE 随时可干预调整方向或停止；排查方向穷尽时必须等待 TSE 明确指示。

展示格式（统一自适应）

━━━ 本轮结论 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 发现
  [咨询路径] 知识源检索到的答案摘要
  [取证路径] 本轮取证的关键发现（发现了什么 / 排除了什么）

💡 下一步（若有，自动执行；无需 TSE 确认）
  [咨询路径] 答案已完整时省略；不完整时说明缺失的方向
  [取证路径 · 再取证]   继续执行下一个取证行动（Phase 2b）
  [取证路径 · 重新定向] 基于新发现重新检索知识源，更新排查方向（Phase 2a）
  [取证路径 · 穷尽]     排查方向已穷尽，省略此项，等待 TSE 指示

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[咨询路径] 以上是否解答了你的问题？
[取证路径 · 有下一步] 若需调整方向或停止，请说明；否则自动继续。
[取证路径 · 需 TSE 输入] 需要补充以下信息才能继续：[具体说明缺少什么]
[取证路径 · 穷尽] 当前排查路径已穷尽，请指示下一步方向或确认问题已定位。

收敛规则

下一步 = 再取证（Phase 2b） → 自动执行，不等 TSE
下一步 = 重新知识定向（Phase 2a） → 自动执行，携带「当前问题进展」重新检索，不等 TSE
需要 TSE 补充新信息 → 说明缺少什么，等待 TSE 提供后继续
排查方向已穷尽 → 必须等 TSE 明确响应，不自动继续
TSE 随时说"停" / 调整方向 → 立即中断，按 TSE 指引处理
TSE 确认已解答 / 已定位 → 输出最终结论摘要，进入收尾注册检查后结束本次会话

收尾：动态发现 skill 注册提议

触发条件： 本次会话在 Phase 2b 中使用了运行时发现的 skill，且该 skill 的取证结果对排查有效贡献。

满足触发条件时，在最终结论摘要之后，输出注册提议：

📌 注册建议
本次使用了通过运行时发现的工具：[skill 名称]
建议将其注册到 action-catalog.md 取证层，以便后续会话直接调用。

以下为生成的 action 草稿，可在确认前修改：

action: <kebab-case-action-name>
name: <中文行动名称>
skill: <skill目录名>
layer: investigation
discovered_from: runtime-discovery
required_inputs:
  - <结合该 skill 的 SKILL.md 内容与本次实际使用情况推断，列出调用时需要的关键字段>
guidance: >
  <何时选用，以及关键注意事项>

是否将此条目追加到 action-catalog.md？（是 / 否）

注册流程：

TSE 确认（含修改后确认）→ 将 action 条目追加到 references/action-catalog.md 取证层末尾（query-login-events 之后），并告知 TSE 已写入
TSE 拒绝 → 跳过，不修改文件，直接结束会话
未触发条件（本次会话未使用运行时发现的 skill，或结果无效）→ 跳过此环节，直接结束会话

原子工具 Skill 清单

Skill	类型	说明
`yunxin-official-docs`	原子工具	公开 API / 功能文档检索
`nim-kb-search`	原子工具	历史客户案例检索
`qs-techsupport`	原子工具	线上数据查询
`yunxin-sdk-source-analyzer`	原子工具	SDK 源码分析
`yunxin-internal-docs`	原子工具	内部技术文档检索

参考文件

references/action-catalog.md：所有可执行行动的定义（核心扩展接口）
references/intent-signals.md：意图识别信号词规则库
references/product-features.md：产品功能域映射表