@shulex/cxclawctl 0.1.2 → 0.1.3

package/skills/shulex-support/references/badcase-analysis/text/m3-strategy.md

@@ -1,126 +0,0 @@
-# M3：策略匹配排查
-
-M3 负责确认已经得到的意图和变量值如何命中策略，以及命中后选择了什么动作。先对齐会话里实际使用的输入、策略和动作，再读取当前策略配置逐条比较。
-
----
-
-## 边界
-
-M3 只处理意图识别完成之后、Agent 或回复动作执行之前的问题：
-
-- 有候选意图但没有策略命中。
-- 命中了非预期策略，或更宽泛的策略提前命中。
-- 策略条件引用的意图、触点或变量值与会话事实不匹配。
-- 策略命中正确，但配置的动作类型或目标对象不符合预期。
-- 请求显式指定策略或 Agent，导致常规策略匹配被绕过。
-
-用户意图本身识别错误时回 M2；策略依赖的变量系统字段缺失或值错时转 M4；策略已正确路由到 Agent 后的执行问题转 M5，CHAT_FLOW 内部问题转 M10。
-
----
-
-## 排查顺序
-
-### 1. 对齐会话记录中的目标事实
-
-| 字段 | 要回答的问题 |
-|------|--------------|
-| `context.intents[]/intent` | 策略实际拿到的意图结果是什么 |
-| `context.metadata.ai_fields` 及相关 metadata | 条件依赖的实际值是什么，字段是否存在、为空或类型不同 |
-| `context.strategyId/strategyName` | 当轮最终记录了哪条策略；为空时是否最终进入 `CONFUSED/NOTHING` |
-| `context.strategyAction` | 命中后选择了回复、模板、转人工、不处理还是 Agent |
-| 回复 `type/handoff/reason/reasonDesc` | 策略动作最终表现成什么用户可见结果 |
-| `contextComparison.strategyAction` | 当前策略动作是什么，只用于与历史结果比较 |
-| `contextComparison.contextModifiedList` | 历史使用的策略是否后来被修改或删除 |
-
-先形成一条最短链路：
-
-```text
-意图与条件实际值 -> strategyId / strategyName -> strategyAction -> 最终回复类型
-```
-
-不要用 `originIntent` 代替策略输入。策略消费的是配置意图 ID、触点及 metadata 等条件值；`originIntent != intent` 也不是策略过滤意图的证据。
-
-### 2. 读取当前配置
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-strategies --pretty
-```
-
-先按 `strategyId` 定位当轮实际策略，再找业务上预期命中的策略。条件字段含义不明确时读取：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-entities --pretty
-```
-
-比较以下内容：
-
-- `status/trigger`：策略是否启用，是否处理消息触发。
-- `rank`：策略匹配有先后顺序；先满足条件的策略会阻止后续策略继续匹配。
-- `condition`：逐条记录 `apiName/apiType/relation/values`，不要只复述整段 JSON。
-- 实际值：从目标轮次 `intents[]`、触点和 metadata 中找到每条条件对应的值。
-- `action`：动作类型及关联的 Agent、模板、知识目录或转人工配置是否符合预期。
-
-对实际策略和预期策略都做同样比较。只证明“预期策略条件满足”还不够，还要确认是否有更靠前的策略也满足。
-
-### 3. 结合字段值判断
-
-对每条关键条件写清楚：
-
-```text
-条件字段 -> 会话实际值 -> 策略期望值 -> relation -> 是否应匹配
-```
-
-| 会话事实 | 判断 |
-|----------|------|
-| `intents[]` 已错误 | 策略只是消费了错误输入，主根因在 M2 |
-| `intents[]` 正确，`strategyName` 为空，回复为 `CONFUSED` | 检查预期策略状态、顺序和每条条件，不要说“意图没识别到” |
-| 命中非预期 `strategyName` | 先验证该策略为何满足，再检查它是否排在预期策略之前 |
-| 策略条件引用的变量系统字段缺失或为空 | M3 记录条件未满足，字段为什么为空转 M4 |
-| 实际值与期望值文本相同但类型不同 | 仍可能不匹配；按 `apiType` 和实际 JSON 类型比较 |
-| `strategyName` 正确但 `strategyAction` 不符合业务预期 | 属于策略动作配置问题；再对照最终回复类型确认影响 |
-| `strategyAction` 正确路由到 Agent，但 Agent 内部走错 | M3 已完成，转 M5；CHAT_FLOW 节点问题转 M10 |
-| 当前配置无法解释当轮 `strategyId` | 查历史修改信息；仍无法解释时考虑显式指定或历史版本，不能直接断言系统随机路由 |
-
-`__intent_ids` 等 ID 条件按数字比较；不要把字符串形式的 ID 当作等价配置。数组、多选值和嵌套字段要同时核对 relation 语义，不能只看“列表里好像包含”。
-
-### 4. 最后才查日志
-
-第一版诊断默认不查日志。只有以下问题在会话事实和当前策略配置中仍无法回答时，才读取 `sls-query.md`：
-
-- 无法确认当轮是否走了常规策略匹配，还是显式指定策略或 Agent。
-- 需要证明多条策略的实际检查顺序和第一条命中项。
-- 会话记录只有“未命中”，但无法确认具体哪条条件失败。
-- 当前策略与历史 `strategyId/strategyAction` 矛盾，且没有修改记录可解释。
-
-日志只补齐当轮匹配事实。没有日志时，列出尚未确认的条件或历史版本，不要猜测内部执行路径。
-
----
-
-## 历史与当前状态边界
-
-- `context.strategyId/strategyName/strategyAction` 是当轮保存的执行结果。
-- `list-strategies/list-entities` 是当前配置，适合解释现在的条件、顺序和动作。
-- `contextComparison.strategyAction` 不是当轮动作；它用于展示当前资源状态。
-- 策略后来被改过时，当前条件不能用于证明历史为什么命中或未命中。
-
----
-
-## 常见根因与建议
-
-| 根因 | 建议 |
-|------|------|
-| 正确意图没有对应启用策略 | `[可自行调整]` 为意图补充策略并确认动作 |
-| 条件字段缺失或实际值为空 | 先转 M4 判断字段来源，再决定改字段还是放宽条件 |
-| 实际值与条件值类型不一致 | `[可自行调整]` 统一字段类型和条件值格式 |
-| 宽泛策略排在前面先命中 | `[可自行调整]` 收紧宽泛条件或调整策略顺序 |
-| 策略命中正确但动作配置错误 | `[可自行调整]` 修改该策略的 action 目标，不要调整意图掩盖问题 |
-| 当前配置无法解释历史结果 | `[需联系研发]` 提供当轮策略字段和当前配置差异，继续确认历史版本或指定路由 |
-
----
-
-## 报告口径
-
-- 必须写出实际策略和预期策略的 ID / 名称、关键条件、实际值、期望值和顺序。
-- 先解释为什么命中或未命中，再说明动作造成的用户影响。
-- 不要把 `originIntent` 与 `intent` 的差异描述成策略修改了意图。
-- 字段值错误时，M3 只说明它如何影响条件；字段为什么错误交给 M4。

package/skills/shulex-support/references/badcase-analysis/text/m4-aifield.md

@@ -1,121 +0,0 @@
-# M4：变量系统字段排查
-
-M4 负责确认目标轮次实际携带了哪些变量系统字段、字段值是否符合用户表达和当前配置，以及错误值如何影响策略、Agent、工具或 CHAT_FLOW。先判断目标字段是否真的参与了本次异常，再分析字段本身。
-
----
-
-## 边界
-
-M4 处理 Agent 执行前已经形成的变量系统字段问题：
-
-- 业务需要的字段在 `metadata.ai_fields` 中缺失、为空或值错误。
-- 字段值类型、父子结构或多值形式与下游预期不一致。
-- 当前字段配置的描述、状态、数据类型或应用范围不适合目标场景。
-- 上游已有值与当轮重新抽取结果之间可能发生覆盖。
-- 字段正确，但策略、工具或节点引用了错误字段。
-
-如果字段值正确而策略条件仍未命中，转 M3；字段值正确而工具参数为空，转 M6；CHAT_FLOW 内部赋值或覆盖问题转 M10。
-
----
-
-## 排查顺序
-
-### 1. 对齐会话记录中的目标事实
-
-先从用户描述和异常结果反推“哪个变量系统字段可能影响了结果”，不要无差别检查全部字段。
-
-| 字段 | 要回答的问题 |
-|------|--------------|
-| 用户消息、必要前置轮次和附件 | 用户是否真实提供了目标信息，值是什么，是否有多个互相冲突的值 |
-| `context.metadata.ai_fields` | 当轮后续环节实际拿到哪些字段 |
-| `ai_fields[].id/name` | 当前结果对应哪个变量系统字段，避免只按相似名称猜测 |
-| `ai_fields[].value/values` | 单值兼容字段与多值结果分别是什么；下游实际需要哪种形态 |
-| `ai_fields[].dataType/bizType` | 值的类型和业务类别是否符合下游用途 |
-| `ai_fields[].children` | 订单等父字段的目标值是否实际位于子字段中 |
-| `ai_fields[].aiExtract` | 该结果是否标记为 AI 抽取；不能仅凭此字段还原完整调用方 |
-| 策略条件、工具参数或 ChatFlow 变量引用 | 目标字段是否真的被异常路径消费 |
-
-`metadata.ai_fields` 通常是字段对象列表，不要把它想当然地当成 `ai_fields.xxx` 平铺字典。按 ID / 名称找到目标对象，再检查 `value`、`values` 和 `children`。
-
-先形成一条最短影响链：
-
-```text
-用户提供的信息 -> ai_fields 中的目标对象和值 -> 下游引用位置 -> 异常结果
-```
-
-目标字段没有被下游引用时，即使值为空也通常不是本次 badcase 根因。
-
-### 2. 读取当前配置
-
-```bash
-npx --yes @shulex/cxclawctl@latest api list-ai-fields --pretty
-```
-
-按会话中的字段 ID / 名称定位当前配置，比较：
-
-- `state`：字段当前是否启用。
-- `description`：说明是否明确要从什么表达中提取什么值。
-- `dataType`：字符串、日期、下拉等类型是否和会话值及下游条件一致。
-- `applyRang`：字段是否覆盖策略、Agent、模板或其它实际使用范围。
-- `parentId/children`：目标是父级业务对象还是具体子字段。
-- 可选值配置：分类或下拉字段的允许值是否覆盖本次表达。
-
-当前配置只说明现在应该怎样抽取和使用。不要因为当前字段存在，就断言当轮一定加载了它；也不要因为当前字段被关闭，就断言当轮没有抽取。
-
-### 3. 结合字段值判断
-
-| 会话事实 | 判断 |
-|----------|------|
-| 用户没有提供目标信息，字段值为空 | 通常是正常结果；检查下游是否不合理地把它设为必需条件 |
-| 用户明确提供了信息，但目标字段对象不存在 | 可能是当轮未加载该字段、应用范围不覆盖或结果未保存；当前配置不足以单独定因 |
-| 字段对象存在，但 `value/values` 为空 | 确认描述、类型、父子位置和用户表达；只能确认没有得到有效值，不能直接断言某个服务失败 |
-| `value` 与 `values[0]` 不一致 | 记录下游实际消费的形态；不要任选一个值作为正确结果 |
-| 父字段为空，但 `children` 中目标子字段有值 | 不能判定整体抽取失败；按下游引用的具体字段判断 |
-| 字段值正确但 JSON 类型与策略条件不同 | 字段抽取可能正确，影响点在类型契约；转 M3 核对条件 |
-| 字段值正确但工具参数为空 | 转 M6 核对参数来源和字段映射 |
-| 字段在 CHAT_FLOW 中被再次赋值或覆盖 | 转 M10，对齐节点执行记录和变量覆盖结果 |
-| 当前字段配置与会话结果不一致 | 先看 `contextComparison` 或修改时间；没有历史证据时只报告当前差异 |
-
-多轮会话中，目标值可能来自前置轮次，也可能被新值覆盖。必须读取影响当前结果的最少前置轮次，不能只看最后一句是否出现该值。
-
-### 4. 最后才查日志
-
-第一版诊断默认不查日志。只有以下问题仍无法由会话事实和当前配置解释时，才读取 `sls-query.md`：
-
-- 需要确认字段是随请求传入、沿用历史值，还是当轮重新抽取。
-- 用户明确提供了值，但会话记录无法说明字段为何缺失或被覆盖。
-- 需要确认实际加载了哪些字段、输入文本或附件，以及返回的原始字段结果。
-- 会话记录与当前字段配置冲突，且没有历史变更信息。
-
-若后续证据表明是字段抽取内部异常，再进入对应服务或 M11。没有日志时，不要从“没看到某段调用”推断它一定没有发生。
-
----
-
-## 历史与当前状态边界
-
-- `context.metadata.ai_fields` 是当轮后续环节实际保存和消费的字段结果，优先作为历史事实。
-- `list-ai-fields` 返回当前字段定义，不是当轮加载字段的快照。
-- 当前描述、类型、状态或应用范围发生变化时，只能说明现在的配置不同。
-- `contextComparison` 可以提示资源变化，但不会重新抽取字段。
-
----
-
-## 常见根因与建议
-
-| 根因 | 建议 |
-|------|------|
-| 用户没有提供字段值，但策略强依赖该字段 | `[可自行调整]` 增加兜底条件或在进入该路径前收集信息 |
-| 字段描述未覆盖真实表达 | `[可自行调整]` 明确提取对象、典型表达和期望值示例 |
-| 字段类型与策略条件不一致 | `[可自行调整]` 统一字段数据类型和条件值格式 |
-| 父子字段引用错误 | `[可自行调整]` 让下游引用实际承载值的子字段 |
-| 字段值正确但策略或工具未使用 | 转 M3 / M6 修正引用，不重复修改抽取配置 |
-| 用户提供值但当轮字段仍缺失，且当前配置无法解释 | `[需联系研发]` 提供目标字段 ID、用户原话和会话中的 `ai_fields` 结果继续定位 |
-
----
-
-## 报告口径
-
-- 先写目标字段为什么与本次异常有关，再写用户原话、字段对象和值、下游引用位置。
-- 区分“字段对象不存在”“字段存在但为空”“字段值错误”“字段正确但未被消费”。
-- 配置问题标明当前字段 ID / 名称、类型和应用范围；不要只说“实体提取失败”。
-- 未进入日志阶段时，不要写具体调用方或服务异常作为确定根因。

package/skills/shulex-support/references/badcase-analysis/text/m5-agent.md

@@ -1,208 +0,0 @@
-# M5：Agent 执行模块
-
-**职责代码**：`AgentService.executeAgent()`
-
----
-
-## 三种 Agent 类型
-
-策略 action 为 `AGENT` / `FLOW_AGENT` 时，进入 `executeAgent()`。根据 `agent.type` 分三个分支：
-
-| 类型 | 特征 | 执行方式 |
-|------|------|---------|
-| `CHAT_FLOW` | 图形化节点流程 | `agentAlgClient.invokeChatFlow()` 流式 |
-| `MULTI_AGENT` | 多 Agent 图路由 | `agentAlgClient.invokeAiAgent()` 流式（单次） |
-| `SINGLE_AGENT`（else） | 单 Agent 循环调用 | `agentAlgClient.invokeAiAgent()` 流式循环（最多 10 次） |
-
-**MAX_TURN_EXCEED**：在进入分支前检查：
-- 条件：`currentAgentTurn > maxInvokeCount`（默认 30）
-- 结果：`TO_AGENT + MAX_TURN_EXCEED`
-- **无日志**，仅在会话记录目标回复的 `reason` 中体现
-
----
-
-## CHAT_FLOW 分支
-
-### 核心流程
-
-```
-agentAlgClient.invokeChatFlow(flowRequest, debug, flowResponse -> {
-  switch (flowResponse.eventEnum) {
-    CHAT_STARTED  → 记录 prepareTimeMillis
-    NODE_STARTED  → 存 runInfoList（后续写入 chatflow_run_info）
-    NODE_FINISHED → 存 runInfoList（含 node_id、status、out_handle、outputs、elapsed_time）
-    MESSAGE_DELTA → 流式推送内容片段
-    MESSAGE       → 处理 text（AI 回复）/ tool_request / tool_response
-    CHAT_FINISHED → 存 finishedData（status、error、handoff、graph_finished）
-  }
-})
-```
-
-### finishedData.status 映射
-
-| status | 结果 | 备注 |
-|--------|------|------|
-| `success` | `MESSAGE` 或 `NOTHING` | graph_finished=true 时加 AGENT_HAS_FINISHED reason |
-| `failed` | `STOPPED`（或 `TO_AGENT`） | ToolInvokeError / GraphNodeMissingError → TO_AGENT |
-| `transfer_to_human` | `MESSAGE` 或 `TO_AGENT` + handoff | reason 来自 handoff.reason |
-
-### 信号判断
-
-会话记录的 `context.ext.chatflow_run_info` 已存储节点序列，**优先从这里分析**，通常不需要查日志：
-
-| 信号 | 含义 |
-|------|------|
-| `graph_finished=false` 且对话结束 | 流程未到终止节点（缺少出边） |
-| 节点序列与预期不符 | IF_ELSE/INTENT 走了错误分支 |
-| `type=STOPPED` + status=failed | 看 error.node_id 和 error.name |
-| `reason=MAX_TURN_EXCEED` | agentTurn > maxInvokeCount（无日志） |
-
-### Log 层
-
-```bash
-# ChatFlow 错误日志（精确匹配）
-$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
-```
-
-**精确错误字符串**：
-```
-executeAgent[<chatId>]: chatflow return error, msg={}
-executeAgent[<chatId>]: chatflow run failed, errorObj={}    ← 含 node_id、node_title
-executeAgent[<chatId>]: chatflow no finished data
-executeAgent[<chatId>]: chatflow unknown finishdata type={}
-```
-
----
-
-## MULTI_AGENT 分支
-
-### 核心流程
-
-```
-agentAlgClient.invokeAiAgent(aiAgentRequest, aiAgentResponse -> {
-  switch (aiAgentResponse.eventEnum) {
-    conversation_message_completed:
-      type=answer       → isReturnUserMsg=true → 返回 MESSAGE
-      type=function_call → isCallTool=true → 处理工具类型
-    conversation_chat_failed → isCallFail=true → STOPPED
-  }
-})
-```
-
-### function_call 工具路由
-
-| toolType | 处理 |
-|----------|------|
-| `TRANSFER_TO_HUMAN` | TO_AGENT 或 MESSAGE + handoff；reason 来自 reason_description |
-| `FINISH_AGENT` | MESSAGE 或 NOTHING + AGENT_HAS_FINISHED |
-| `KNOWLEDGE_AI_REPLY` | 调用 `aiReplyService.aiReply()`（→ M7） |
-
-**转人工 reason 判断**（来自 `toolArgs.reason_description`）：
-- `Lack of knowledge` → `LACK_OF_KNOWLEDGE`
-- `Knowledge irrelevant` → `KNOWLEDGE_NOT_RELEVANT`
-- `tool action` → `CALL_TOOL_STATUS_TO_HUMAN` 或 `HANDOFF_TOOL_STATUS`
-- `llm invoke` → `CALL_AGENT_TRANSFER_TO_HUMAN`
-
-### Log 层
-
-```bash
-# MULTI_AGENT 流式日志（含完整 aiAgentResponse，token 消耗大）
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"multiAgent stream"' --line 20
-
-# MULTI_AGENT 失败
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"multiAgent, call fail"' --line 5
-```
-
-**精确日志字符串**：
-```
-executeAgent[<chatId>]: multiAgent stream, aiAgentResponse={}
-executeAgent[<chatId>]: multiAgent, call fail, reason={}
-executeAgent[<chatId>]: multiAgent, call kb_reply fail, knowledgeAiReplyRes={}
-```
-
----
-
-## SINGLE_AGENT 分支
-
-### 核心流程
-
-```
-while (currentLoopCount++ < 10):  // 最多循环 10 次
-  agentAlgClient.invokeAiAgent(aiAgentRequest, response -> {
-    conversation_message_completed:
-      type=answer        → return MESSAGE（退出循环）
-      type=function_call → callPluginId → 执行工具 → 追加 tool_response 消息 → 下一轮循环
-    conversation_chat_failed → return STOPPED
-  })
-
-// 超过 10 轮未返回 → STOPPED + AGENT_TIMEOUT
-```
-
-### 工具调用类型
-
-| pluginType | 处理 |
-|------------|------|
-| `EXTERNAL_HTTP_CALL` | 调用外部 HTTP 接口（→ M6） |
-| `FINISH_AGENT` | 结束 Agent，返回模板回复 |
-| `TRANSFER_TO_HUMAN` | 转人工（带话术或空） |
-| `KNOWLEDGE_AI_REPLY` | 调用知识库（→ M7） |
-| `PRODUCT_RECALL` | Shopify 商品检索 |
-| `QUERY_SHOPIFY_ORDER` | 订单查询 |
-| `LOGISTICS_17_TRACK` | 物流追踪 |
-
-### Log 层
-
-```bash
-# SINGLE_AGENT 每轮调用（含完整请求，token 大，按需查）
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"call ai agent,"' --line 10
-
-# SINGLE_AGENT 工具调用结果
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"call tool, currentLoopCount"' --line 10
-
-# SINGLE_AGENT 失败
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"call ai agent stream" AND rest:"call fail"' --line 5
-```
-
-**精确日志字符串**：
-```
-executeAgent[<chatId>]: call ai agent, currentLoopCount={}, aiAgentRequest={}
-executeAgent[<chatId>]: call ai agent stream, currentLoopCount={}, aiAgentResponse={}
-executeAgent[<chatId>]: call tool, currentLoopCount={}, pluginName={}, request={}, response={}
-executeAgent[<chatId>]: call ai agent stream, currentLoopCount={}, call fail, reason={}
-```
-
----
-
-## Config 层
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-agent --id <agentId> --pretty
-```
-
-检查点：
-- `agent.type`：确认是 CHAT_FLOW / MULTI_AGENT / SINGLE_AGENT
-- `meta.maxInvokeCount`：MAX_TURN_EXCEED 阈值（默认 30）
-- CHAT_FLOW：`meta.chatFlowGraph` 中的节点定义和边配置
-- SINGLE_AGENT：`usedPlugins` 列表和 `prompt`
-- MULTI_AGENT：`meta.multiAgentGraph` 中的子 Agent 配置
-
----
-
-## 常见根因与建议
-
-| 根因 | 建议 |
-|------|------|
-| MAX_TURN_EXCEED | 检查循环分支，确保有终止出口；或调大 `maxInvokeCount` |
-| CHAT_FLOW graph_finished=false | 补充缺失的终止出边 |
-| CHAT_FLOW chatflow run failed | 从 errorObj.node_id 定位失败节点 |
-| SINGLE_AGENT AGENT_TIMEOUT（10轮用尽）| 检查是否陷入工具调用循环；看每轮的 aiAgentRequest 是否有进展 |
-| SINGLE_AGENT call fail | 看 errorReason/codeMsg，通常是 LLM 服务异常（→ M8） |
-| MULTI_AGENT call fail | 同上 |
-| 转人工 reason 不符合预期 | 检查 TRANSFER_TO_HUMAN 工具的 reason_description 逻辑 |

package/skills/shulex-support/references/badcase-analysis/text/m6-tool.md

@@ -1,115 +0,0 @@
-# M6：工具调用模块
-
-**职责**：SINGLE_AGENT / CHAT_FLOW 中对 EXTERNAL_HTTP_CALL 工具的执行。
-
----
-
-## 核心逻辑
-
-### SINGLE_AGENT 路径（主要路径）
-
-```
-executeAgent() → function_call 消息 → callPluginId → 找 usedPlugins
-  → plugin.type == EXTERNAL_HTTP_CALL:
-      HttpParamUtils.updateArguments() → 更新参数（绑定 metadata 值）
-      → 发起 HTTP 请求（带 headerParams 认证）
-      → 解析 resultStr → 写入 toolResponse(metadata)
-      → 下一循环继续
-```
-
-**参数来源（`source`）**：
-- `LLM`：由 LLM 从对话上下文推断
-- `CUSTOMIZE`：固定值（`value` 或 `ref`）
-- `METADATA`：从 metadata（ai_fields）读取
-
-### CHAT_FLOW 路径
-
-```
-ChatFlowService.callTool(request)
-  → EXTERNAL_HTTP_CALL → callExternHttp()
-  → KNOWLEDGE_AI_REPLY → callKnowledgeReply()
-  → TEMPLATE_REPLY → callTemplateReply()
-```
-
----
-
-## 信号判断
-
-从会话记录读取：
-
-| 信号 | 含义 |
-|------|------|
-| `ai_fields.xxx = null` | `source=LLM` 参数无法填充 |
-| SINGLE_AGENT 循环次数多但无结果 | 工具反复调用未成功 |
-| CHAT_FLOW: chatflow_run_info 中 TOOL 节点 `status=failed` | 工具执行失败 |
-
----
-
-## Config 层
-
-```bash
-# 查工具列表（精简信息）
-npx --yes @shulex/cxclawctl@latest api list-plugins --pretty
-
-# 查工具详情（request/response params、actionStatus）
-npx --yes @shulex/cxclawctl@latest api get-plugin --id <tool_id> --pretty
-
-# 查变量系统字段（LLM source 的参数需要对应变量系统字段）
-npx --yes @shulex/cxclawctl@latest api list-ai-fields --pretty
-```
-
-检查点：
-- `requestParam.items` 中 `required=true & source=LLM` 的参数：是否有对应变量系统字段？
-- `responseParam.items`：映射路径是否与实际接口响应匹配？
-- 接口地址、认证 header 是否正确？
-
----
-
-## Log 层
-
-### SINGLE_AGENT
-
-```bash
-# 工具调用结果（request + response）
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"call tool, currentLoopCount"' --line 10
-# → pluginName, request（入参）, response（出参）
-```
-
-**精确日志字符串**：
-```
-executeAgent[<chatId>]: call tool, currentLoopCount={}, pluginName={}, request={}, response={}
-executeAgent[<chatId>]: call plugin, currentLoopCount={}, arguments={}, headers={}, httpResult={}, plugin={}
-```
-
-### CHAT_FLOW
-
-```bash
-# callTool 入口和出口
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"chatflow callTool"' --line 15
-
-# HTTP 工具详情
-$BASE --from $BEGIN --to $END \
-  --query 'trace:"<trace>" AND rest:"chatflow call http tool"' --line 15
-```
-
-**精确日志字符串**：
-```
-chatflow callTool request={}                      ← 完整入参
-chatflow callTool chatId={} ...                   ← 完整出参
-chatflow call http tool, toolId={}, chatId={}, url={}, method={}, params={}, inputs={}
-chatflow call http tool, toolId={}, chatId={}, resultStr={}
-chatflow callTool error chatId={}                 ← 异常
-```
-
----
-
-## 常见根因与建议
-
-| 根因 | 建议 |
-|------|------|
-| `source=LLM` 参数提取失败（null） | 优化变量系统字段 prompt；或改为 `METADATA` source |
-| HTTP 接口返回错误 | 检查接口鉴权、URL、参数格式 |
-| responseParam 路径映射错误 | 对照实际 HTTP 响应修正路径 |
-| SINGLE_AGENT 工具循环（参数反复错误） | 检查 arguments 是否每轮都相同，找循环根因 |

package/skills/shulex-support/references/badcase-analysis/text/m7-reply.md

@@ -1,72 +0,0 @@
-# M7：回复生成排查
-
-M7 负责知识或业务上下文进入回复模型之后的 Prompt 组装、LLM 生成、格式化和检查。query、召回范围、排序、相关性和使用知识本身的问题转 M9；ChatFlow 内先按 M10 确认 graph 和节点。
-
-## 当前主路径
-
-普通 AI 回复的知识路径：
-
-```text
-AiReplyService.aiReply
-  -> 构建 KnowledgeSearchReq
-  -> qa-bot searchKnowledge
-  -> contextContent / systemContent
-  -> livechat: invokeGpt
-     非 livechat: ShulexService docReply
-  -> aiContent
-  -> postHandle / product card / format
-  -> 最终 AgentAction
-```
-
-qa-bot 当前会把最终使用的 QA、文档和商品组装到上下文，再进入生成链路。知识上下文为空时通常返回 `CONFUSED + LACK_OF_KNOWLEDGE`；生成内容为空时返回 `TO_AGENT + AI_CONTENT_IS_EMPTY`。
-
-## 诊断顺序
-
-1. 先按 M9 确认哪些知识 `effect=true`、哪些文档 chunk 或商品实际进入上下文。
-2. 对比 `context.aiContent` 与最终 `messages[].content`。
-3. 检查 Prompt/PE、知识上下文和历史消息是否同时包含冲突指令。
-4. 若 `aiContent` 已正确，继续检查格式化、语言处理、输入输出检查和过滤。
-
-| 现象 | 判断 |
-|------|------|
-| 使用知识错误或缺失 | M9 召回问题 |
-| 使用知识正确，但 `aiContent` 结论错误 | Prompt、上下文冲突或生成不遵循 |
-| `aiContent` 正确，最终回复错误 | 后处理、格式化或算法检查 |
-| `filteredContent` 有值且 `metadata.real_time_inspection_tags` 或 reason 指向合规/质检 | 转 M12 |
-| `filteredContent` 有值但没有质检信号 | 原回复被检查或拦截，结合 reason 转 M8/M11 |
-| `AI_CONTENT_IS_EMPTY` | LLM 返回空、超时或异常，转 M8 |
-| 回复语言错误 | 检查请求语言、模型输出和语言后处理 |
-
-## Prompt 证据边界
-
-- 会话记录保存的 Agent 历史、知识 tool response 和 `aiContent` 是重要运行事实。
-- `currentPrompt` 为空时，读取会话记录的接口可能用当前 Agent Prompt 补填；它不一定是历史运行快照。
-- `get-agent` 返回的是当前配置，不能单独证明目标轮次收到同一 Prompt。
-- 要确认运行时完整 Prompt、PE 和知识上下文是否注入，查询该轮实际 LLM 请求日志。
-
-因此只能在运行时请求得到验证后写“Prompt 已注入但模型未遵循”；否则应写“当前配置存在该规则，但运行时注入尚未确认”。
-
-## 配置与日志
-
-按调用路径读取当前 Agent 或 ChatFlow 图。ChatFlow 的 Agent/RAG/回复节点由 M10 负责定位，M7 只分析其生成输入和输出。
-
-聚焦日志：
-
-```text
-aiReply[<chatId>]: useKnowledgeSearch=
-aiReply[<chatId>]: aiContent=
-aiReply[<chatId>]: formatAiContent=
-invokeGpt[<chatId>]
-detected response language
-chatflow call kbreply
-```
-
-日志用于确认实际 system prompt、历史消息、知识上下文、模型原始输出和后处理。没有运行时请求证据时，不要把知识冲突、Prompt 优先级或模型行为写成确定根因。
-
-## 建议边界
-
-- 知识内容冲突：回 M9 统一知识口径。
-- Prompt 与知识冲突：明确优先级并消除冲突，随后用原 badcase 回归。
-- 生成未遵循已确认的运行时规则：缩短和强化规则、减少冲突上下文，并增加针对性测试。
-- 后处理改变正确答案：提供 `aiContent` 与最终 content 对比，交对应检查模块修复。
-- 任何配置建议都必须保持原业务口径，不擅自加强限制、承诺或风险结论。