@shulex/cxclawctl 0.1.2 → 0.1.4

package/skills/shulex-support/references/badcase-analysis/text/m8-error.md

@@ -1,92 +0,0 @@
-# M8：系统异常模块
-
-**信号**：`type=STOPPED` + `reason=SYSTEM_ERROR` / `reason=AGENT_TIMEOUT` / 任意模块未捕获异常
-
----
-
-## 核心逻辑
-
-系统异常无特定职责模块，全局 AOP 捕获未处理异常后返回 `STOPPED + SYSTEM_ERROR`。
-
-常见来源：
-- LLM 调用超时或连接失败（agentAlgClient 异常）
-- SINGLE_AGENT / MULTI_AGENT：`invokeAiAgent` 调用失败
-- CHAT_FLOW 节点执行失败
-- 外部 HTTP 工具接口异常
-- 数据库/缓存访问失败
-- NPE 或其他运行时异常
-
----
-
-## Log 层（直接查，无 Config 层）
-
-```bash
-# 全局 ERROR 日志（最直接）
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND severity:"ERROR"' --line 20
-# → 类名、方法名、exception message、堆栈首行
-
-# SINGLE_AGENT LLM 调用失败
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"call ai agent stream" AND rest:"call fail"' --line 5
-
-# MULTI_AGENT LLM 调用失败
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"multiAgent, call fail"' --line 5
-
-# CHAT_FLOW 特有错误（精确字符串）
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND (rest:"chatflow return error" OR rest:"chatflow run failed" OR rest:"chatflow no finished data")' \
-  --line 10
-
-# 兜底：afterChat botChatEvent（包含 request + response 完整数据）
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"afterChat[.*botChatEvent"' --line 5
-```
-
-**精确错误日志字符串**：
-```
-executeAgent[<chatId>]: call ai agent stream, currentLoopCount={}, call fail, reason={}
-                                                                    ↑ SINGLE_AGENT（STOPPED）
-executeAgent[<chatId>]: multiAgent, call fail, reason={}
-                                               ↑ MULTI_AGENT（STOPPED）
-executeAgent[<chatId>]: chatflow return error, msg={}
-executeAgent[<chatId>]: chatflow run failed, errorObj={}            ← errorObj 含 node_id、node_title
-executeAgent[<chatId>]: chatflow no finished data
-executeAgent[<chatId>]: chatflow unknown finishdata type={}
-chatflow callTool error chatId={}                                   ← 工具调用异常
-aiReply[{}]: aiContent is empty                                     ← LLM 返回空 → TO_AGENT
-```
-
-**AGENT_TIMEOUT 特殊说明**：SINGLE_AGENT 超过 10 轮未返回 → `STOPPED + AGENT_TIMEOUT`，无独立 ERROR 日志，需看每轮 `call ai agent stream` 记录是否有进展（→ M5）。
-
----
-
-## 分析要点
-
-**从 ERROR 日志定位**：
-- 哪个类（class）的哪个方法（method）抛了异常？
-- exception message 是什么？
-- 是否有 `reason` 字段？（SINGLE_AGENT/MULTI_AGENT call fail 的 reason 字段说明具体失败原因）
-
-**SINGLE_AGENT / MULTI_AGENT call fail 的 reason 字段**：
-- `codeMsg`：LLM 服务返回的错误码/描述
-- `errorReason`：内部错误标识
-- 通常是 LLM 服务端异常（rate limit、timeout、服务不可用）
-
-**从 botChatEvent 兜底**：
-- `afterChat[chatId]: botChatEvent={}` 包含完整 request + response
-- `response.type`、`response.reason`、`response.reasonDesc` 直接可读
-
----
-
-## 常见根因与建议
-
-| 根因 | 建议 |
-|------|------|
-| LLM 服务异常（call fail） | 看 `reason` 中 codeMsg；检查 LLM provider 状态；通常是临时性 |
-| SINGLE_AGENT AGENT_TIMEOUT | 看每轮 arguments 是否有进展；是否陷入工具调用死循环（→ M5） |
-| CHAT_FLOW 节点执行失败 | 从 `errorObj.node_id` 定位节点，看节点配置和工具调用 |
-| 外部 HTTP 工具接口异常 | 检查接口地址、鉴权、网络连通性（→ M6） |
-| NPE / 配置字段缺失 | 从堆栈首行定位代码位置，检查相关配置是否完整 |
-| agentAlgClient 连接失败 | 检查 ChatFlow/AI Agent 服务状态 |

package/skills/shulex-support/references/badcase-analysis/text/m9-knowledge-search.md

@@ -1,147 +0,0 @@
-# M9：知识召回排查
-
-M9 负责判断知识在 query、范围、候选召回、排序、过滤和上下文组装中的问题。知识已经正确进入上下文但回复仍错误时，转 M7 分析 Prompt、LLM 生成和后处理。
-
-ChatFlow 场景先按 M10 读取 graph，确认实际节点配置和知识目录，再进入本模块判断知识链路。
-
-## 诊断顺序
-
-### 1. 对齐问题和目标轮次
-
-先写清用户原问题、实际回复和预期回复。知识排查必须回答具体差异，不能只罗列召回 ID 和分数。
-
-从目标回复的 `messages[].context` 读取：
-
-- `mixedQuery.originTitle/originContent`：原始用户问题。
-- `mixedQuery.userQuery/userEnQuery`：召回和 rerank 使用的用户 query。
-- `mixedQuery.knowledgeQuery/knowledgeEnQuery`：知识检索改写结果。
-- `intents`、变量系统字段和前置轮次：判断 query 是否被错误上下文带偏。
-
-原问题与知识 query 语义不一致时，优先定位 query rewrite / 多轮上下文问题，不直接修改知识。
-
-### 2. 确认调用路径和检索范围
-
-检查：
-
-- `touchPoint`：livechat 与非 livechat 的相关性判断配置可能不同。
-- `directoryIds`：Agent、策略或 ChatFlow 节点限定的目录。
-- `metadata.ai_fields`：pn、pdt 等变量系统字段可能影响 query、目录和字段加权。
-- `useQa/useDoc/useProduct`：是否启用 QA、文档和商品召回。
-- ChatFlow：按 M10 从 graph 读取知识节点的真实目录和参数；会话记录只说明实际执行过哪些节点。
-
-目录过宽会引入噪音，目录过窄会漏召回。不能只看到某条无关知识就断言 rerank 失败。
-
-### 3. 区分候选、排序和实际使用结果
-
-QA 主要看 `retrievedKus`。其中 `retrievedKus[].title/content` 是历史运行时保存的知识内容，先用它还原当时模型实际看到的证据：
-
-| 字段 | 含义 |
-|------|------|
-| `score` | ES / 混合召回阶段分数，不能跨模式直接比较 |
-| `rerankScore` | rerank 分数 |
-| `relevantScore` | 可选的相关性判断分数 |
-| `rank` | rerank 后排名 |
-| `effect` | 是否最终进入知识上下文；受相关性、TopN 和 token 预算影响 |
-| `title/content` | 真实进入判断的知识内容 |
-| `directoryId/tags/conditionTags` | 目录和标签线索 |
-
-文档看 `documentQaContext` 中的 used chunks、chunk 内容和 `usedDocuments`；商品看 `recommendProductContext.usedProducts`。只出现文件名不代表整份文件都进入 Prompt，应尽量确认实际 chunk。
-
-需要判断知识当前是否仍有问题，或准备给出修改方案时，再按知识 ID 读取当前知识详情：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-knowledge --id <knowledge_id> --pretty
-```
-
-报告中明确区分“历史运行时内容”和“当前知识详情”。`list-knowledge --keyword` 可用于找候选，但不能代替按 ID 读取详情；不要为核对单条知识扫描整个知识库。
-
-诊断时分别回答：
-
-1. 正确知识是否进入候选。
-2. 候选排名是否合理。
-3. 正确知识是否 `effect=true` 并进入最终上下文。
-4. 是否同时混入足以误导模型的无关或冲突知识。
-
-### 4. 区分召回问题和生成问题
-
-对比实际使用的知识、`aiContent` 和最终 `content`：
-
-| 现象 | 判断方向 |
-|------|----------|
-| 正确知识未进入候选 | query、目录、过滤条件、索引或混合召回问题 |
-| 正确知识在候选中但排名过低 | rerank、query 或知识标题/内容区分度问题 |
-| 排名合理但 `effect=false` | 相关性判断、TopN 或 token 预算问题 |
-| 无关 QA、文档或商品 `effect=true` | 检索范围、排序、相关性或上下文污染 |
-| 使用知识本身矛盾、过时或缺少目标场景 | 知识内容问题 |
-| 使用知识正确，但 `aiContent` 结论错误 | 召回正确但生成错误，转 M7 |
-| `aiContent` 正确，最终 `content` 错误 | 格式化、检查或后处理问题，转 M7/M11 |
-
-不要把所有“回答不准”都归为召回不准。
-
-## 当前实现事实
-
-- 检索范围按租户走默认 flat 或 `STRICT_ISOLATION` 目录模式。
-- 当前核心路径中 QA / Doc / Product 三路并行召回，再统一 rerank、可选相关性判断、TopN/token 选择和上下文组装。
-- QA 同时使用原始问题与知识 query，对标题和内容进行向量 + BM25 混合召回。
-- rerank 失败会退化为 ES 分数排序，需用日志确认，不能只凭最终排名猜测。
-- livechat 与非 livechat 是否启用相关性判断由租户配置决定。
-- `AiReplyOption` 类型默认值不是运行时事实；普通主路径和 ChatFlow 当前都显式传入 `retrieve_min_score=0.01`。
-- 当前默认 `qaUsedSize/docUsedSize/productUsedSize` 为 `6/4/4`，仍可能被租户配置覆盖。
-- 最终还受 `knowledgeMaxToken` 和单文档 chunk 上限约束。
-
-报告引用阈值或模式前，必须先用请求日志或租户配置确认实际值。
-
-## 何时查配置和日志
-
-会话记录已经能证明“用了哪些知识、内容为何冲突”时，可以直接给出内容层建议。以下情况需要继续查知识检索服务日志：
-
-- 正确知识存在但候选为空。
-- query 看起来正确但排序明显异常。
-- 怀疑目录过滤、变量系统字段加权、embedding、BM25、rerank 或相关性服务异常。
-- 需要确认实际检索模式、阈值、候选漏失阶段或 rerank fallback。
-
-### 服务边界
-
-只有定位代码或查询 SLS 时才需要区分服务：
-
-| 环节 | 主要服务 | 查什么 |
-|------|----------|--------|
-| 原问题、上下文和知识请求组装 | `shulex-gpt` | 实际 query、目录、变量系统字段、调用参数 |
-| query rewrite、相关性算法、部分非 LiveChat 回复生成 | `ShulexService` | 改写是否偏离、相关性判断输入输出 |
-| QA / Doc / Product 召回、rerank、过滤和上下文组装 | `qa-bot` | 候选漏失、排序、过滤、fallback、最终使用知识 |
-| ChatFlow 知识节点参数和结果消费 | ChatFlow 服务 | 先按 M10 对照 graph、节点输入、节点输出和运行路径 |
-| LiveChat 最终生成与后处理 | `shulex-gpt` | 召回正确但模型回复或格式化结果错误时转 M7 |
-
-不要因为最终回复错误就直接查询 `qa-bot`。先用会话记录判断问题发生在 query、召回、上下文还是生成阶段，再选择服务。
-
-先按 `sls-query.md` 获取目标服务可用的关联标识，再聚焦查询：
-
-```text
-searchKnowledge[<chatId>]: req=
-searchKnowledgeFlat[<chatId>]
-searchKnowledgeStrictDirs[<chatId>]
-retrieveQaV2[<chatId>]
-retrieveDocV2[<chatId>]
-retrieveProductV2[<chatId>]
-hybridSearch[<chatId>]
-rerankKnowledgeAdaptive[<chatId>]
-cohere rerank error[<chatId>]
-相关性判断过滤掉
-相关性判断通过
-```
-
-一次只验证一个假设，并遵守 `log-query-rules.md` 的预算和止损规则。
-
-## 根因与建议边界
-
-| 已确认根因 | 建议方向 |
-|------------|----------|
-| query rewrite 偏离原问题 | 修正 rewrite / 多轮上下文，不用堆同义知识掩盖 |
-| 目录范围错误 | 调整 Agent、策略或 ChatFlow 知识目录 |
-| 正确知识缺失 | 新增覆盖该业务场景的知识 |
-| 知识内容冲突或留有推断空白 | 统一相关知识口径，明确场景边界 |
-| 知识区分度不足导致排序差 | 优化问题标题、答案关键词和场景限定；必要时评估 rerank |
-| rerank / relevance 服务异常 | 提供日志证据并交研发处理 |
-| 召回正确但生成错误 | 转 M7 检查运行时 Prompt、知识上下文和 LLM 输出 |
-
-知识建议必须保持用户确认的政策强度。例如原规则是“不建议，可能影响”，不得改写成“禁止”或确定会失效。未确认运行时 Prompt 时，也不能仅凭当前配置断言 PE 已生效。

package/skills/shulex-support/references/badcase-analysis/text/sls-query.md

@@ -1,283 +0,0 @@
-# SLS 日志查询
-
-文本 badcase 的日志查询统一执行 `npx --yes @shulex/cxclawctl@latest sls query`。CLI 先向 `shulex-cloud` 申请 10～15 分钟只读 STS，再由本机使用 `@alicloud/log` 直连 SLS；临时凭据只驻留内存，禁止写入文件、日志或普通命令输出。
-
-## 基础用法
-
-```bash
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <epoch-seconds> \
-  --to <epoch-seconds> \
-  --query '<SLS 查询 DSL>' \
-  --line 50 \
-  --offset 0
-```
-
-返回 JSON：`{"count": N, "logs": [{...contents...}, ...]}`
-
-字段说明：
-
-| 字段 | 含义 |
-|------|------|
-| `fromTime` | 起始时间，epoch 秒 |
-| `toTime` | 结束时间，epoch 秒 |
-| `query` | SLS 查询 DSL，JSON 字符串内的双引号必须写成 `\"` |
-| `line` | 返回条数，默认 50，最大 100 |
-| `offset` | 分页偏移，默认 0 |
-| `reverse` | 是否按时间倒序，默认 false |
-
-## 时间窗口
-
-会话记录顶层 `createdAt` 是 **epoch 毫秒**（例：`1775793526000`），不是 ISO 字符串。
-
-**必须直接用 epoch 秒**做 `fromTime` / `toTime`（等于 `createdAt // 1000`），避免任何时区歧义：
-
-```bash
-# createdAt = 1775793526000 (ms) → 1775793526 (s)
-# ±5/10min 窗口
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from 1775793226 \
-  --to 1775794126 \
-  --query 'rest:"HTTP_ASPECT"' \
-  --line 5
-```
-
-推荐窗口：`createdAt_sec - 300` ~ `createdAt_sec + 600`（即 -5min ~ +10min）；漏查扩到 `±1800`（±30min）。
-
-**不要用 ISO 字符串**：CLI 只接受 epoch 秒。会话记录没有 ISO 格式，人工转换容易踩时区坑（例如 `1775793526000` 转 UTC 是 03:58，而 SLS 控制台里你看到的是 CN 本地时间 11:58，差 8 小时），一旦转错就查不到日志。
-
-## 定位 trace
-
-chatId → trace 一对一。先查 HTTP 入口 aspect 拿到 trace：
-
-> ⚠️ **禁止使用会话记录返回的 `traceId` 字段**——该值不可信，必须通过下面的 HTTP_ASPECT 查询重新定位 trace。
-
-```bash
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <createdAt_sec - 300> \
-  --to <createdAt_sec + 600> \
-  --query 'rest:"HTTP_ASPECT" AND rest:"<chatId>" AND (rest:"/bot/<botId>/chat " OR rest:"/bot/<botId>/chat/async" OR rest:"/bot/<botId>/chat/stream")' \
-  --line 5
-```
-
-- chatId 在 `rest` 字段里（不是 `ext_2`）
-- 结果中 `trace` 字段即后续所有查询的 trace 值
-- 查询约束（次数上限、止损规则、DSL 规范）见 `/skills/shulex-support/references/badcase-analysis/text/log-query-rules.md`
-
-## 跨服务 trace 拼接（qa-bot / ShulexService / chatflow / tars）
-
-文本主链路以 `shulex-gpt` 为入口，qa-bot、ShulexService、chatflow、tars 都是 GPT 发起的下游调用。业务 `trace-id` 通过 HTTP header 透传时可能因异步 / 切线程而衰减，跨服务关联**优先以 `armsTrace` 为准**（SLS 自动注入字段）；目标服务没有 `armsTrace` 时，再用 `chatId` / `request_id` / `tenant_id` / 接口路径 / 时间窗兜底。
-
-> ⚠️ **armsTrace 字段名首次使用时务必实测验证**：本文件中所有 `armsTrace` 字段名均按用户口述写入；如 SLS 控制台实际字段名不是 `armsTrace`（例如 `arms_trace` / `ARMS_Trace`），把本节及 `m9-knowledge-search.md` 中所有出现处一次性替换。
-
-### 标准三步
-
-```bash
-# Step A：和同步路径一样，先用 chatId 拿 shulex-gpt 侧业务 trace
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <createdAt_sec - 300> \
-  --to <createdAt_sec + 600> \
-  --query 'rest:"HTTP_ASPECT" AND rest:"<chatId>" AND (rest:"/bot/<botId>/chat " OR rest:"/bot/<botId>/chat/async" OR rest:"/bot/<botId>/chat/stream")' \
-  --line 5
-# → trace = trace_GPT；同时记录该日志的 armsTrace 字段值
-
-# Step B：用 trace_GPT 拉一条 shulex-gpt 业务日志，取其 armsTrace
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <createdAt_sec - 300> \
-  --to <createdAt_sec + 600> \
-  --query 'trace:"<trace_GPT>" AND rest:"aiReply["' \
-  --line 3
-# → 取返回 JSON 第一条的 armsTrace 字段值，记为 armsTrace_X
-# → 如 aiReply 不存在（未走知识召回），换 shulex-gpt 侧任意业务日志关键字（如 rest:"BOT_REPLY" 或 rest:"chat["），目的只是拿到 armsTrace
-
-# Step C：用 armsTrace_X 查目标下游服务日志
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <createdAt_sec - 300> \
-  --to <createdAt_sec + 600> \
-  --query 'armsTrace:"<armsTrace_X>" AND rest:"searchKnowledge["' \
-  --line 5
-# → 命中即说明跨服务拼接成功，后续下游模块查询都优先用此 armsTrace
-```
-
-### qa-bot（M2 意图 / M9 知识）
-
-```bash
-# qa-bot 知识召回
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"searchKnowledge[" OR rest:"rerankKnowledge[" OR rest:"embeddingSearchAsync[")' \
-  --line 20
-
-# qa-bot 意图识别
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"intentParse" OR rest:"checkIntent" OR rest:"intentIdentify[")' \
-  --line 20
-
-# qa-bot 兜底：armsTrace 不可用
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'rest:"<chatId>" AND (rest:"searchKnowledge[" OR rest:"intentIdentify[" OR rest:"checkIntent")' \
-  --line 20
-```
-
-### ShulexService（M2 / M4 / M11）
-
-```bash
-# ShulexService 通用 request_start / request_end / ERROR
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"request_start" OR rest:"request_end" OR rest:"ERROR" OR rest:"http_cost_time")' \
-  --line 20
-
-# ShulexService 按能力缩小
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"intent_identify" OR rest:"intent_pure" OR rest:"general_ner" OR rest:"batch_classify" OR rest:"query_rewrite" OR rest:"ai_reply")' \
-  --line 20
-
-# ShulexService 兜底：request_id / chatId
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query '(rest:"<request_id>" OR rest:"<chatId>") AND (rest:"request_start" OR rest:"request_end" OR rest:"ERROR")' \
-  --line 20
-```
-
-### chatflow（M10）
-
-```bash
-# chatflow graph / node / condition
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"graph_exec" OR rest:"node_enter" OR rest:"evaluate_condition" OR rest:"case_matched" OR rest:"no_case_matched")' \
-  --line 20
-
-# chatflow RAG / KB / tool / variable
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"rag_reply retrieve" OR rest:"kb_reply retrieve" OR rest:"tool_node" OR rest:"selected variable not found")' \
-  --line 20
-
-# chatflow 兜底：chatId + 节点关键字
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'rest:"<chatId>" AND (rest:"graph_exec" OR rest:"node_enter" OR rest:"tool_node")' \
-  --line 20
-```
-
-### 质检（M12）
-
-先在 GPT 侧确认该轮是否进入后置质检；只有会话记录不足以判断送检、命中或调用失败时才查。`quality-inspection-gate` 是服务端灰度/过滤开关，只能作为“是否可能送检”的运行线索，不能据此改动或推断租户规则。
-
-```bash
-# GPT 回复后质检：实时送检、回复送检、结果与豁免
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'trace:"<trace_GPT>" AND (rest:"QualityCheckPostCheck" OR rest:"realTimeInspection" OR rest:"replyInspection" OR rest:"inspectionDataResponse" OR rest:"quality-inspection-gate" OR rest:"exempt_request" OR rest:"exempt_ai_reply")' \
-  --line 20
-
-# trace 缺失时用 chatId 在 GPT 侧兜底；命中调用异常后再按 armsTrace 查 Intelli
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'rest:"<chatId>" AND (rest:"realTimeInspection" OR rest:"replyInspection" OR rest:"inspectionDataResponse" OR rest:"QualityCheckPostCheck")' \
-  --line 20
-```
-
-从 GPT 日志取得 `armsTrace` 后，再以该值和 `realTimeInspection` / `replyInspection` / `ERROR` 查询 Intelli 侧 HTTP 调用与异常。不要在没有会话或日志事实时，根据当前质检规则倒推历史是否命中。
-
-### tars（M4 变量系统）
-
-```bash
-# tars 变量系统字段抽取
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'armsTrace:"<armsTrace_X>" AND (rest:"/service/field/internal/extract" OR rest:"AiFieldExtractService #")' \
-  --line 20
-
-# tars 兜底：chatId + 变量系统日志
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'rest:"<chatId>" AND (rest:"AiFieldExtractService #" OR rest:"extract aiFieldExtractDTO" OR rest:"extract result aiFieldDbDTOList")' \
-  --line 20
-```
-
-### 失败兜底
-
-- Step C 或服务模板命中为 0：
-  1. 检查字段名是否真为 `armsTrace`（注意大小写 / 真实字段名）
-  2. 时间窗是否覆盖下游调用时刻（±30s 通常足够，最大放宽到 ±30min）
-  3. 该会话是否真正走到了目标服务（参考会话记录的 `reason` / `type` / `chatflow_run_info` / GPT 侧调用日志）
-- 上述均无果 → 退回 GPT 侧结论，按 `log-query-rules.md` 的「连续 3 次空止损」执行，**不再继续追深下游服务**
-
-### 配额
-
-- Step A / B / C 均算入单轮 20 次硬上限
-- 每个跨服务模块自身的日志查询同样计入；**建议每个模块 ≤ 6 次查询**
-
-## 异步路径（/chat/async）
-
-Kafka 生产端和消费端是**两条独立的 trace**，不能跨 Kafka 传播。但 SLS 日志里有 `span` 字段可以把两段串起来。
-
-分三步：
-
-```bash
-# 1a 定位入口请求，拿到 span
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <createdAt_sec - 300> \
-  --to <createdAt_sec + 600> \
-  --query 'rest:"HTTP_ASPECT" AND rest:"<chatId>" AND rest:"/bot/<botId>/chat/async"' \
-  --line 2
-# → 记录返回字段 span
-
-# 1b 用 span 找消费端 trace
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <createdAt_sec - 300> \
-  --to <createdAt_sec + 1800> \
-  --query 'span:"<span>"' \
-  --line 5
-# → 消费端日志的 trace 字段就是后续 M2~M8 查询用的 trace
-
-# Step 2 起：跟同步完全一样，trace 用消费端那条
-```
-
-- `trace_A`（入口）仅用于检查「请求到了 / 生产 Kafka 成功没」，不做 M2~M8 查询
-- `trace_B`（消费端）是 M2~M8 日志真正落在的 trace
-- `trace_A.timestamp` 与 `trace_B.timestamp` 差值 ≈ 消息在 Kafka 里的排队时间
-- 1b 查不到 → 消费端没触达（积压 / consumer group 故障 / 反序列化异常），回到 1a 时间窗附近查 `severity:"ERROR"`
-
-## 通用模板（按 trace 查）
-
-```bash
-# 模块相关日志
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'trace:"<trace>" AND rest:"<关键字>"' \
-  --line <N>
-
-# 所有 ERROR（M8 系统异常排查用）
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <begin> \
-  --to <end> \
-  --query 'trace:"<trace>" AND severity:"ERROR"' \
-  --line 20
-```
-
-## 配置缺失处理
-
-若 `npx --yes @shulex/cxclawctl@latest sls query` 返回未登录、未选择租户或 SLS 配置缺失，依次运行
-`npx --yes @shulex/cxclawctl@latest auth status`、`npx --yes @shulex/cxclawctl@latest tenant current` 定位问题。SLS 长期 AK/SK 只存在于
-`shulex-cloud` 配置；CLI 每次查询前申请短期只读 STS，凭据只驻留进程内存。

package/skills/shulex-support/references/badcase-analysis/voice/core-flow.md

@@ -1,77 +0,0 @@
-# 语音 badcase 核心分析流程
-
-## 进入条件
-
-以下任一情况进入语音流程：
-
-1. 用户明确描述语音、电话、VAPI、Twilio、callId、callSid、断音、延迟、STT、TTS、录音、webhook 问题。
-2. 文本流程执行 `get-transcript --chat-id <chatId>` 查不到、返回空或 404。
-
-## 核心原则
-
-1. 先确认排查对象：默认沿用当前 badcase 上下文；用户显式指定范围时以用户为准。
-2. 先用稳定标识缩小范围：`chatId`、`callId`、`callSid`、`traceId`、电话号码 + 时间段。
-3. SLS 通过本机 `npx --yes @shulex/cxclawctl@latest sls query` 直查；语音会话通过 `npx --yes @shulex/cxclawctl@latest api list-voice-transcripts`
-   和 `npx --yes @shulex/cxclawctl@latest api get-voice-transcript` 查询，客户端不持有 VAPI/Twilio 长期密钥。
-4. 不生成独立语音报告模板；最终按 badcase 回复风格输出。
-5. 不要只凭单一数据源下结论，缺失证据必须说明。
-
-## 1. 识别入口
-
-| 输入 | 优先动作 |
-|------|----------|
-| `chatId` | 查 SLS 定位 callId/callSid/voice trace |
-| VAPI `callId` | 查语音会话详情 + SLS callId 相关日志 |
-| Twilio `callSid` | 查语音会话详情 + SLS callSid 相关日志 |
-| `traceId` / `armsTrace` | 查 SLS 链路日志 |
-| 电话号码 + 时间段 | 先要求用户补充时间窗，再查 SLS/VAPI/Twilio |
-
-不确定字段含义时只问一个澄清问题。
-
-## 2. 查询 SLS
-
-读取 `/skills/shulex-support/references/badcase-analysis/voice/sls-playbook.md`。
-
-优先用 chatId/callId/callSid 做最小时间窗查询。连续 3 次空结果停止扩词，避免无节制查询。
-
-## 3. 查询语音平台数据
-
-读取 `/skills/shulex-support/references/badcase-analysis/voice/platform-api.md`。
-
-- 先用 `npx --yes @shulex/cxclawctl@latest api list-voice-transcripts` 缩小范围，再用
-  `npx --yes @shulex/cxclawctl@latest api get-voice-transcript --history-id <historyId>` 读取详情。
-- 有 `callId` / `callSid` 时同时查 SLS，补齐 provider 原始错误和时间线。
-- 当前本地插件不下发 VAPI/Twilio 长期密钥，也不直接请求 provider 私有 API；产品接口和
-  SLS 都缺少证据时，明确标为“未确认”，不要要求用户粘贴 token。
-
-## 4. 依赖或配置缺失
-
-读取 `/skills/shulex-support/references/badcase-analysis/voice/dependencies.md`。
-
-## 5. 输出方式
-
-按 badcase 风格回复：
-
-```markdown
-## 会话诊断：chatId=<xxx>
-
-### 发生了什么
-<一句话描述语音/通话现象>
-
-### 根因
-<基于 SLS/VAPI/Twilio 证据解释原因；证据不足时说明未确认>
-
-- **问题层级**：客户端 / Twilio / VAPI / 应用服务 / STT / LLM / TTS / 未确认
-- **Log 层**：<关键发现 / 未查询 / 配置缺失>
-- **Platform 层**：<VAPI/Twilio 关键发现 / 未查询 / 配置缺失>
-
-### 关键证据
-<只列最少必要字段；不要粘贴 token、完整客户号码>
-
-### 建议
-1. [可自行调整] <后台配置类建议，如有>
-2. [需联系研发] <代码/平台链路问题，如有>
-
----
-以上分析是否符合你的预期？需要更深入排查吗？
-```

package/skills/shulex-support/references/badcase-analysis/voice/dependencies.md

@@ -1,19 +0,0 @@
-# 语音排查依赖与降级
-
-## 运行依赖
-
-- SLS：由本机 `npx --yes @shulex/cxclawctl@latest sls query` 使用短期只读 STS 直连。
-- 语音会话：由 `npx --yes @shulex/cxclawctl@latest api list-voice-transcripts` / `get-voice-transcript` 查询现有业务 API。
-- 沙箱不需要 VAPI CLI、Twilio CLI、aliyun CLI、本地 `.env` 或平台 token。
-
-## 降级规则
-
-| 缺失项 | 降级方式 |
-|--------|----------|
-| SLS 配置缺失 | 继续查语音会话业务数据；结论中说明日志证据缺失 |
-| 语音会话查不到 | 继续查 SLS；不直接访问 VAPI/Twilio 私有 API |
-| callId 缺失 | 优先用 chatId 在 SLS 中定位 callId |
-| callSid 缺失 | 优先用 callId/VAPI/SLS 定位 callSid |
-| 时间窗缺失 | 向用户追问通话大致时间；不要按电话号码扫全量日志 |
-
-不要让用户在对话中粘贴 token、AccessKey、Twilio Auth Token 或 VAPI API Key。

package/skills/shulex-support/references/badcase-analysis/voice/platform-api.md

@@ -1,23 +0,0 @@
-# VAPI / Twilio 平台数据
-
-本地插件不持有 VAPI/Twilio 长期凭据。优先通过现有语音会话业务 API 和 SLS 取证。
-
-| 平台 | 用途 | 命令 | 使用时机 |
-|------|------|------|----------|
-| 业务平台 | 会话列表 | `npx --yes @shulex/cxclawctl@latest api list-voice-transcripts` | 按时间、状态缩小范围 |
-| 业务平台 | 会话详情 | `npx --yes @shulex/cxclawctl@latest api get-voice-transcript --history-id <historyId>` | 查看 transcript 和已落库平台字段 |
-| SLS | provider 日志 | `npx --yes @shulex/cxclawctl@latest sls query ...` | 按 callId/callSid 补齐原始错误 |
-
-## 调用示例
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-voice-transcripts --begin-ts <ms> --end-ts <ms> --pretty
-npx --yes @shulex/cxclawctl@latest api get-voice-transcript --history-id <historyId> --pretty
-```
-
-## 错误处理
-
-- 业务接口为空：校验环境和时间窗，再按 callId/callSid 查 SLS。
-- SLS 也无结果：记录当前证据边界，结论标为“未确认”。
-
-不要猜测未公开 provider 接口，也不要要求用户提供 VAPI/Twilio token。

package/skills/shulex-support/references/badcase-analysis/voice/sls-playbook.md

@@ -1,31 +0,0 @@
-# 语音链路 SLS 查询 Playbook
-
-所有 SLS 查询都通过本机 `npx --yes @shulex/cxclawctl@latest sls query` 使用 `shulex-cloud` 下发的短期只读 STS 直连阿里云，不经过业务服务查询代理。
-
-## 基础模板
-
-```bash
-npx --yes @shulex/cxclawctl@latest sls query \
-  --from <epoch-seconds> \
-  --to <epoch-seconds> \
-  --query 'rest:"<keyword>"' \
-  --line 50 \
-  --offset 0
-```
-
-## 查询策略
-
-| 标识 | 查询策略 |
-|------|----------|
-| `chatId` | `rest:"<chatId>" AND (rest:"callId" OR rest:"callSid" OR rest:"voice")` |
-| `callId` | `rest:"<callId>"`，必要时加 `severity:"ERROR"` |
-| `callSid` | `rest:"<callSid>"`，必要时加 `rest:"Twilio"` |
-| `trace` | `trace:"<trace>"` |
-| `armsTrace` | `armsTrace:"<armsTrace>"`，字段名首次使用需用实际日志验证 |
-
-## 止损规则
-
-- 单轮语音排查 SLS 查询最多 20 次。
-- 连续 3 次 `count=0` 停止扩词。
-- 查询不到时先检查时间窗、字段名、环境，不要直接下根因结论。
-- 配置缺失时，降级为语音会话业务数据 + 已知输入排查。