@shulex/cxclawctl 0.1.2 → 0.1.4

package/skills/runtime-inspector/scripts/verify_persistence.py

@@ -1,101 +0,0 @@
-#!/usr/bin/env python3
-"""
-跨轮持久化断言脚本。
-
-eager 模型下 workspace/state/ 与 workspace/outputs/ 都由运行时在 build 时
-自动 eager 还原到原路径，脚本直接读即可，无需 read_file 物化。
-"""
-import os, sys
-sys.path.insert(0, os.path.join(os.environ["SOLVEA_LIB_DIR"], "skill-runtime"))
-from bootstrap import *
-import json
-
-_SECTION = "=" * 64
-_failures: list[str] = []
-
-
-def check(label: str, condition: bool, detail: str = "") -> None:
-    if condition:
-        print(f"  ✅  {label}")
-    else:
-        msg = f"{label}" + (f" — {detail}" if detail else "")
-        print(f"  ❌  {msg}")
-        _failures.append(msg)
-
-
-print(_SECTION)
-print("VERIFY PERSISTENCE — 跨轮持久化断言")
-print(_SECTION)
-
-# ── 1. 上一轮 state 是否还原到 workspace ─────────────────────────────────────
-print("\n[1] 上一轮 state 还原（workspace/state/）")
-state_path = STATE_DIR / "inspect.json"
-check("state 文件已还原", state_path.exists(), str(state_path))
-
-if state_path.exists():
-    try:
-        prev_state = json.loads(state_path.read_text(encoding="utf-8"))
-        check("status == 'done'", prev_state.get("status") == "done",
-              f"actual status={prev_state.get('status')!r}")
-        check("total_processed > 0", (prev_state.get("total_processed") or 0) > 0,
-              f"total_processed={prev_state.get('total_processed')}")
-        check("results_path 字段存在", bool(prev_state.get("results_path")))
-    except Exception as e:
-        check("state 文件可解析", False, str(e))
-
-# ── 2. 上一轮 outputs 是否还原（workspace/outputs/，eager 模型） ──────────
-# 关键断言：脚本直接通过绝对路径 open() 就能读到，**没有任何 read_file 物化操作**。
-# 如果还原走的是 lazy（旧模型），这里会失败 —— 这就是 eager 模型的保障验证点。
-print("\n[2] 上一轮 outputs eager 还原（workspace/outputs/）")
-check("outputs 目录已落盘", OUTPUTS_DIR.exists(), str(OUTPUTS_DIR))
-
-if OUTPUTS_DIR.exists():
-    result_files = sorted(OUTPUTS_DIR.glob("results_*.json"))
-    check("至少一个 results 文件存在", len(result_files) > 0)
-
-    if result_files:
-        latest = result_files[-1]
-        # 直接用 open()/read_text，不经任何工具，等价于 bash 脚本里 cat / Path.read_text
-        try:
-            data = json.loads(latest.read_text(encoding="utf-8"))
-            total = data.get("total", 0)
-            check("records 数量 > 0", total > 0, f"total={total}")
-            check("records 字段存在", "records" in data)
-            check("脚本直接 open() 可读（eager 还原已就位）", True,
-                  f"{latest.name} {latest.stat().st_size}B")
-        except FileNotFoundError as e:
-            check("脚本直接 open() 可读（eager 还原已就位）", False,
-                  f"FileNotFoundError —— eager 还原可能未生效: {e}")
-        except Exception as e:
-            check(f"{latest.name} 可解析", False, str(e))
-
-# ── 3. SKILL_NAME 推断正确 ────────────────────────────────────────────────────
-print("\n[3] SKILL_NAME 推断")
-check("SKILL_NAME == 'runtime-inspector'", SKILL_NAME == "runtime-inspector",
-      f"actual={SKILL_NAME!r}")
-
-# 写一个带 SKILL_NAME 的标记文件，验证 OUTPUTS_DIR 路径包含正确的 skill 名
-OUTPUTS_DIR.mkdir(parents=True, exist_ok=True)
-marker = OUTPUTS_DIR / f"skill_name_check_{timestamp()}.txt"
-marker.write_text(SKILL_NAME, encoding="utf-8")
-check("OUTPUTS_DIR 包含正确 skill 名",
-      "runtime-inspector" in str(marker),
-      f"actual path={marker}")
-
-# ── 4. lib 可 import ──────────────────────────────────────────────────────────
-print("\n[4] lib 可 import")
-try:
-    import client as _solvea_client  # solvea-api/client.py
-    check("solvea-api client 可 import", True)
-except ImportError as e:
-    check("solvea-api client 可 import", False, str(e))
-
-# ── 结果汇总 ──────────────────────────────────────────────────────────────────
-print(f"\n{_SECTION}")
-if _failures:
-    print(f"RESULT: ❌ FAIL  ({len(_failures)} 项断言失败)")
-    for f in _failures:
-        print(f"  - {f}")
-else:
-    print("RESULT: ✅ PASS  所有断言通过")
-print(_SECTION)

package/skills/runtime-inspector/scripts/write_test.py

@@ -1,41 +0,0 @@
-#!/usr/bin/env python3
-"""向 workspace/outputs 和 workspace/state 写入测试文件，验证写入机制和 S3 上传路径。"""
-import os, sys
-sys.path.insert(0, os.path.join(os.environ["SOLVEA_LIB_DIR"], "skill-runtime"))
-from bootstrap import *
-import json
-from datetime import datetime, timezone
-
-now = datetime.now(timezone.utc).isoformat()
-
-# 1. outputs — 每轮不同文件名（模拟 run_id 命名）
-run_id = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
-out_dir = OUTPUTS_DIR
-out_dir.mkdir(parents=True, exist_ok=True)
-out_file = out_dir / f"{run_id}_test.json"
-out_file.write_text(json.dumps({
-    "run_id": run_id,
-    "written_at": now,
-    "note": "此文件每轮新建，S3 上累积保留",
-}, indent=2))
-print(f"[outputs] Written: {out_file}")
-
-# 2. state — 固定文件名（模拟跨轮状态覆盖）
-state_file = STATE_DIR / "inspect.json"
-existing = {}
-if state_file.exists():
-    try:
-        existing = json.loads(state_file.read_text(encoding="utf-8"))
-    except Exception:
-        pass
-existing.update({
-    "last_run_id": run_id,
-    "last_written_at": now,
-    "write_count": existing.get("write_count", 0) + 1,
-    "note": "固定文件名，S3 上传时覆盖旧版本",
-})
-state_file.parent.mkdir(parents=True, exist_ok=True)
-state_file.write_text(json.dumps(existing, ensure_ascii=False, indent=2), encoding="utf-8")
-print(f"[state] Written: {state_file}  (write_count={existing['write_count']})")
-
-print("\n✅ 写入完成。下一轮运行 read_state.py 验证跨轮持久化。")

package/skills/setup/SKILL.md

@@ -1,17 +0,0 @@
----
-name: setup
-description: 安装 CXClaw 后完成钉钉登录、租户选择和本地环境自检。
----
-
-# CXClaw Setup
-
-1. 后续命令统一使用 `npx --yes @shulex/cxclawctl@latest`。运行
-   `npx --yes @shulex/cxclawctl@latest auth status`；已经登录时不要重复授权，未登录再运行
-   `npx --yes @shulex/cxclawctl@latest auth login --server <公司提供的 shulex-cloud 授权地址>`。
-2. 请用户在钉钉授权页完成验证。不要代替用户授权，也不要展示或记录 token。
-3. 用户要求测试环境时运行 `npx --yes @shulex/cxclawctl@latest tenant search <租户名称> --env test`；生产环境必须明确使用 `--env prod`，不能自行推断。
-4. 用户确认目标租户后，运行 `npx --yes @shulex/cxclawctl@latest tenant use <accountId> --env <test|prod> --purpose <用途>`。
-5. 运行 `npx --yes @shulex/cxclawctl@latest doctor` 和
-   `npx --yes @shulex/cxclawctl@latest update --install-scheduler`。只有两步都成功才报告安装完成。
-
-写操作必须先调用同一业务命令的 `--phase preview` 并展示结果；等待用户明确确认后，使用 `--phase commit --confirmation-token-stdin --idempotency-key <key>` 提交。不得把确认凭证写入命令参数、文件或日志。

package/skills/shulex-support/SKILL.md

@@ -1,39 +0,0 @@
----
-name: shulex-support
-description: Shulex 产品支持统一入口。凡用户提到 badcase、异常回复、失败节点、报错、卡住、排查，或提供 ChatId / 会话 ID / External ID 要求定位会话，优先使用本 skill；也用于产品咨询、功能需求和售后工单。
-requires:
-  libs:
-    - solvea-api
----
-
-# Shulex Support
-
-处理 Shulex 产品咨询、Agent 会话诊断和售后工单。先判断用户属于哪一种场景，只进入对应流程；不要先把三套材料全部读完。
-
-## 入口优先级
-
-**Agent 会话诊断优先于运营分析。** 用户只要描述异常、badcase、错误、失败、卡住、答非所问，或要求根据 ChatId / 会话 ID / External ID 查原因，主流程先进入本 skill 的 Agent 会话诊断场景，读取 `references/badcase-analysis/overview.md`。如需整体指标或样本统计，可再调用 `agent-analytics` 提供辅助证据，不要因此改变 badcase 的主责入口。
-
-只有用户明确要统计指标、趋势、排行、分页列表或运营报表，且不要求解释某次会话异常时，才使用 `agent-analytics`。
-
-## 场景分流
-
-| 用户意图 | 处理方式 |
-|---|---|
-| 咨询产品使用、配置、排障、售后政策 | 读取 `references/product-docs.md`，基于产品文档回答 |
-| 提出功能需求、产品改进建议，或明确说“提个需求/希望支持/能不能增加” | 读取 `references/tickets.md`，按 `ticket_feature` 整理需求工单；先确认明细再创建 |
-| 提供 ChatId / 会话 ID / 外部会话 ID，要求分析 badcase、异常回复、失败节点或语音通话问题 | 读取 `references/badcase-analysis/overview.md`，按文本 / 语音流程诊断 |
-| 明确要提交工单，或文档查询无法解决 | 读取 `references/tickets.md`，收集必要信息并确认后创建 |
-| 查询某个工单怎么样了 | 读取 `references/tickets.md`，根据工单号查询状态和最新消息 |
-| 继续补充某个工单的问题 | 读取 `references/tickets.md`，根据工单号追加用户消息 |
-| 只提供任意 ID，未说明目的 | 默认按会话 ID 进入 Agent 会话诊断；只有 `ST...` 开头或用户明确说“售后工单/查询工单/追加工单”时才走售后工单 |
-| 只说"售后""工单"但目标不清楚 | 先问用户目标；确认后再读取 `references/tickets.md` |
-
-## 处理原则
-
-1. **先分流再处理**：ChatId 会话异常直接诊断；普通产品问题先查文档；用户提出功能需求/改进建议，或明确要提单、诊断后需要人工跟进时，进入工单流程。
-2. **不伪造工单状态**：没有查到工单或当前运行时没有可用接口时，直接说明无法确认，不要编造状态、客服回复或预计处理时间。
-3. **区分会话 ID 与售后工单号**：ChatId、会话 ID、外部会话 ID用于 Agent 会话诊断，也可作为 `agent_badcase` 工单的扩展字段；孤立 ID 默认视为会话 ID。只有 `ST...` 开头的 ID，或用户明确提到售后工单、查询工单、追加工单时，才把 ID 当售后工单号处理。
-4. **信息最小化**：提交工单只收集当前问题需要的信息，不主动索要无关隐私。
-5. **邮箱可选**：有邮箱时可用于后续通知；没有邮箱也不阻塞工单链路。
-6. **先确认后提交**：调用 `create-ticket` 之前，必须先把整理好的工单明细列给用户，得到用户明确确认后才提交，绝不能直接创建。

package/skills/shulex-support/references/badcase-analysis/overview.md

@@ -1,34 +0,0 @@
-# Agent 会话诊断入口
-
-**原则**：本文件只做信息收集和文本/语音Agent会话分流。不要在入口文件里展开完整分析流程，不要预加载全部 references。
-
-## 启动时必须收集信息
-
-先从当前消息和会话上下文提取会话标识与问题描述。用户已经给出 ChatId、会话 ID 或外部会话 ID 时直接开始，不要重复询问；缺少会话标识时只补问缺失信息。
-
-用户只提供一个 ID、或明确说这是 chatId / 会话 ID 时，默认进入本流程。只有 `ST...` 开头的 ID，或用户明确提到售后工单、查询工单、追加工单时，才切到售后工单流程。
-
-```text
-需要以下信息来帮你诊断这条会话：
-
-1. **chatId / 会话 ID / 外部会话 ID**（必填）：请提供要诊断的会话标识
-2. **问题描述**（选填）：这条会话哪里有问题？如果是语音/电话问题，请说明是否有 callId、callSid、VAPI/Twilio 信息。
-
-请提供以上信息后我开始分析。
-```
-
-收到会话标识后才执行后续诊断流程。若用户未提供会话标识，不得开始任何数据拉取。
-
-## 分流规则
-
-1. 用户明确提到语音、电话、VAPI、Twilio、callId、callSid、断音、延迟、STT、TTS、录音、webhook：读取 `/skills/shulex-support/references/badcase-analysis/voice/core-flow.md`。
-2. 用户描述普通 AI 客服文本回复问题：读取 `/skills/shulex-support/references/badcase-analysis/text/core-flow.md`。
-3. 不确定时先按文本流程走：读取 `/skills/shulex-support/references/badcase-analysis/text/core-flow.md`。
-4. 文本流程中 `get-transcript --chat-id` 查不到、返回空或 404：停止文本流程，读取 `/skills/shulex-support/references/badcase-analysis/voice/core-flow.md` 做语音兜底排查。
-
-## 读取规则
-
-- 只先读取对应的 `core-flow.md`。
-- 其它 references 由 core-flow 指引按需读取。
-- 不要使用 `cat` 读取 `/workspace` 或 `/skills` 路径；单纯读文件统一用 read_file 工具。
-- 语音排查不生成独立报告模板，最终仍按 badcase 风格说明发生了什么、为什么、关键证据和建议。

package/skills/shulex-support/references/badcase-analysis/text/conversation-record.md

@@ -1,105 +0,0 @@
-# 会话记录读取
-
-`get-transcript` 获取单条会话记录详情。后端对象名为 `Transcript`，诊断说明统一称“会话记录”。
-
-## 基本原则
-
-始终结合用户的问题描述读取会话记录。先定位用户认为有问题的目标轮次、实际结果和预期结果，再查看影响该问题的字段及必要的前置轮次。不要脱离问题描述扫描所有字段，也不要从单个字段直接跳到根因。
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-transcript --chat-id <chatId> --pretty
-```
-
-CLI 默认请求 `isCompare=true`，因此每条消息通常同时返回保存的 `context` 和根据当前资源生成的 `contextComparison`。
-
-## 读取顺序
-
-1. 从用户描述提取异常现象、目标轮次、实际结果和预期结果。
-2. 在 `messages[]` 中定位目标用户消息和对应回复。
-3. 多轮上下文可能影响结果时，再向前读取必要轮次，不默认分析整段会话。
-4. 读取目标回复的 `context`，还原意图、策略、Agent、知识、工具和流程信号。
-5. 读取 `contextComparison` 判断历史资源后来是否被修改或删除。
-6. 将直接事实、当前状态和推断分开记录，再进入对应模块。
-
-## 四层结构
-
-### 会话层
-
-| 字段 | 用途 |
-|------|------|
-| `chatId` | 会话标识 |
-| `touchPoint` | email、livechat 等入口，会影响检索和回复链路 |
-| `subject` / `snippet` | 邮件主题和摘要，只作上下文，不能代替原始消息 |
-| `createdAt` | 会话开始时间，查询日志的时间基准 |
-| `handoff` / `handoffAt` / `takeoverAt` | 是否转人工及人工介入情况 |
-| `stat` / `error` / `debug` | 会话状态、顶层错误和调试标记 |
-| `metadata.__bot_id` | Bot ID；不是稳定的顶层 `botId` 字段 |
-| `messages[]` | 原始用户、AI、人工和流程消息 |
-
-### 消息层 `messages[]`
-
-| 字段 | 用途 |
-|------|------|
-| `id` / `turn` / `createdAt` | 定位目标消息、轮次和时间 |
-| `role` / `messageRole` | USER、ASSISTANT、人工等角色 |
-| `content` / `attachments` | 原始消息和附件，优先于摘要 |
-| `type` | MESSAGE、TO_AGENT、STOPPED、CONFUSED、HUMAN_REVIEW 等动作结果 |
-| `handoff` / `reason` / `reasonDesc` | 本条消息是否转人工及原因 |
-| `reasonList` / `reasonsDescList` | 同一回复的多个原因 |
-| `filteredContent` | 回复被检查或拦截时的原始候选内容 |
-| `context` | 该轮保存的执行上下文 |
-| `contextComparison` | 保存上下文与当前资源的比较结果 |
-
-`type`、`reason`、意图、策略等通常属于目标回复，不要误当成会话顶层字段。
-
-### 执行上下文 `messages[].context`
-
-按问题读取，不要求每次全部展开：
-
-| 字段 | 用途 |
-|------|------|
-| `mixedQuery` | 原始问题、用户 query、知识 query 及翻译/改写结果 |
-| `intents[]` / `intent` / `originIntent` | 候选意图及兼容字段；值不同是排查信号，不自动等于意图漂移 |
-| `strategyId` / `strategyName` / `strategyAction` | 命中策略及动作 |
-| `metadata` | 变量系统字段和运行元数据；`ai_fields` 等值位于此层 |
-| `retrievedKus` | 历史召回的 QA 候选、分数、排名及是否实际生效 |
-| `directoryIds` | 本轮知识检索范围 |
-| `documentQaContext` / `recommendProductContext` | 实际使用的文档、chunk 和商品上下文 |
-| `toolCalls` | 工具名、参数和错误信息 |
-| `aiContent` / `filteredContent` | LLM 原始回复及后处理前后的差异线索 |
-| `metadata.real_time_inspection_tags` | 实时质检命中的标签；是本轮送检结果的首要事实证据 |
-| `currentPrompt` | Prompt 线索，注意下面的历史快照限制 |
-| `context.timing.__stage_time_total` | 本轮总耗时；不要使用不存在的 `perf.total` |
-| `ext` | Agent/ChatFlow 执行信息，如 `invoke_agent_id`、`chatflow_run_info`、`graph_finished`、`ai_agent_history_msg` |
-
-### 当前状态比较 `messages[].contextComparison`
-
-| 字段 | 用途 |
-|------|------|
-| `chatContext` | 用当前资源信息补充后的上下文 |
-| `contextModifiedList` | 历史使用的知识、意图或策略后来被修改/删除 |
-| `unusedKus` | 历史候选全部未生效时展示的知识 |
-| `kuFolderCount` | 历史知识涉及的目录数量 |
-| `entities` / `strategyAction` | 当前可展示的实体与策略动作 |
-
-`contextComparison` 不是重新执行目标轮次，也不会重新跑意图、知识召回、工具或 Agent。
-
-## 历史与当前状态边界
-
-- `context` 主要来自当次保存的执行上下文，可作为历史事实来源。
-- `contextComparison` 是读取时与当前资源的比较结果，不能当成当次运行配置。
-- 当历史 `currentPrompt` 为空时，后端可能用当前 Agent Prompt 补填；因此它不一定是历史运行快照。
-- 当前 Agent、意图、策略、知识或 ChatFlow 图只能说明现在的配置。要证明历史运行时配置，需结合保存的版本、`contextModifiedList` 或日志。
-
-## 常见路由
-
-| 会话记录信号 | 下一步 |
-|--------------|--------|
-| 意图、策略与预期不符 | M2 / M3 |
-| 变量系统字段缺失或错误 | M4 |
-| Agent 类型、调用轮次或工具循环异常 | M5 / M6 |
-| 召回内容正确但 `aiContent` 或最终回复错误 | M7 |
-| `retrievedKus`、query、目录、排序或使用知识异常 | M9 |
-| `metadata.real_time_inspection_tags` 有值，或回复被合规原因拦截/转人工 | M12 |
-| `ext.chatflow_run_info` 出现节点执行或路由问题 | M10 |
-| 算法 rewrite / NER / reply / check 异常 | M11 |

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

@@ -1,89 +0,0 @@
-# 文本 badcase 核心流程
-
-本文件只负责编排。字段解释、配置检查和日志查询由会话记录说明及对应模块文档负责。
-
-## 1. 理解问题并获取会话记录
-
-始终围绕用户的问题描述排查。先明确用户指出的异常、实际结果、预期结果和可能的目标轮次；信息已经给出时不要重复询问。
-
-所有用户提供的会话标识都先按内部 `chatId` 查询，包括看起来像外部系统 ID 的值：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api get-transcript --chat-id <用户提供的会话标识> --pretty
-```
-
-只有 `get-transcript --chat-id` 查不到、返回空或 404 时，才把同一个值作为外部会话 ID 走 Inbox 同源搜索解析内部 chatId，再拉详情：
-
-```bash
-npx --yes @shulex/cxclawctl@latest api resolve-transcript-chat-id --external-id <用户提供的会话标识> --page-size 10 --pretty
-npx --yes @shulex/cxclawctl@latest api get-transcript --chat-id <resolvedChatId> --pretty
-```
-
-解析返回多个候选时，优先使用 `matchedBy=exactExternalId` 的结果；没有精确匹配时，先向用户说明候选并确认目标会话，不要随意拿 keyword 首条继续诊断。
-
-命令默认携带 `isCompare=true`。返回的是会话记录详情，`Transcript` 只是后端对象和命令中的技术名称。
-
-## 2. 定位目标事实
-
-读取 `/skills/shulex-support/references/badcase-analysis/text/conversation-record.md`，定位目标消息及必要的前置轮次，先回答：
-
-- 用户实际说了什么，系统实际回复或执行了什么。
-- 目标轮次经过了哪些与问题相关的模块。
-- 会话记录直接证明了什么，哪些只是当前状态或推断。
-
-不要脱离用户描述遍历全部字段，也不要因为看到某个异常信号就擅自改变排查目标。
-
-## 3. 进入对应模块排查
-
-根据目标事实按需读取模块文档。配置、图和日志的检查规则由模块文档决定，不在本文件重复。
-
-| 主要信号 | 模块 |
-|----------|------|
-| 请求入口、HumanReview 旁路 | M1 入口：`m1-entry.md` |
-| 意图识别或改写错误 | M2 意图识别：`m2-intent.md` |
-| 策略未命中或命中错误 | M3 策略匹配：`m3-strategy.md` |
-| 变量系统字段缺失或值错误 | M4 变量系统：`m4-aifield.md` |
-| Agent 类型选择、调用次数或 SINGLE_AGENT / MULTI_AGENT 执行异常 | M5 Agent 执行：`m5-agent.md` |
-| 外部工具请求、响应或状态异常 | M6 工具调用：`m6-tool.md` |
-| 召回正确但回复生成、Prompt 或后处理异常 | M7 回复生成：`m7-reply.md` |
-| 系统错误、超时、空回复 | M8 系统异常：`m8-error.md` |
-| 回复后被质检标记、拦截或因合规原因转人工 | M12 质检：`m12-quality-inspection.md` |
-| query、检索范围、召回、排序、过滤或知识内容异常 | M9 知识召回：`m9-knowledge-search.md` |
-| ChatFlow 图、节点、边、变量或节点内知识/工具异常 | M10 ChatFlow 服务：`m10-chatflow-service.md` |
-| ShulexService 的 intent / NER / classify / rewrite / reply / check 异常 | M11 算法服务：`m11-algorithm-service.md` |
-
-一个 badcase 可以涉及多个模块，但报告要指出主根因和上游诱因。现有证据不足以确认根因时，按模块文档查询当前配置或聚焦日志；不要无差别拉取所有资源和日志。
-
-## 4. 输出结论和建议
-
-先写发生了什么，再写为什么。明确区分：
-
-- **已确认**：会话记录、配置或日志直接证明。
-- **当前状态**：读取时的当前配置或知识状态，不一定是历史运行快照。
-- **待确认**：证据不足的推断及缺失证据。
-
-建议必须对应已确认根因，保持用户给出的业务口径，不得把“可能”“不建议”等表述擅自加强为确定承诺或禁止规则。
-
-### 排查不清或用户无法理解时
-
-- 完成必要的会话、配置或日志检查后根因仍不清晰，必须如实说明缺少什么证据，不要用推测填满结论。
-- 用户表示不理解当前结论、不知道如何处理，或希望由售后继续跟进时，切换到本 skill 的售后工单流程。
-- 转入售后前先整理 ChatId、问题现象、已确认事实、待确认项、失败节点以及 trace / armsTrace（如有），减少用户重复描述。
-- 这里只整理提单信息并征得用户确认，不得直接创建工单；创建、查询或追加工单必须读取 `/skills/shulex-support/references/tickets.md`，并遵守“先确认后提交”。
-
-```markdown
-## 会话诊断：chatId=<chatId>
-
-### 结论
-<发生了什么，主根因是什么>
-
-### 实际执行链路
-<只列与目标问题相关的关键步骤>
-
-### 根因与证据
-<区分已确认、当前状态、待确认>
-
-### 建议
-1. [可自行调整] <准确的配置或内容建议>
-2. [需联系研发] <代码、服务或运行时问题>
-```

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

@@ -1,36 +0,0 @@
-# 日志查询约束
-
-统一证据收集阶段调用 `npx --yes @shulex/cxclawctl@latest sls query` 时必须遵守以下规则，避免无节制地查日志。
-
-## 硬上限
-
-- **单轮诊断最多 20 次 SLS 查询**（含 Step 1 定位 trace 的查询）
-- 达到上限即停止查询，在报告中写明：「当前日志层面已分析到位，建议联系研发团队进一步排查。」
-
-## 连续空结果止损
-
-- 连续 3 次查询返回 `count=0` → **停止继续扩词或换关键字**
-- 优先自查：
-  1. trace 是否定位到了？Step 1 的 `rest:"<chatId>"` 和入口路径是否写对？
-  2. query DSL 字段名是否拼错（`rest` / `trace` / `severity`）？
-  3. 时间窗是否包含了会话记录的 `createdAt`？
-- 若三项自查后仍无结果，停止继续查日志，用已收集到的会话记录、配置和手册证据出报告，并说明日志未能确认。
-
-## 查询策略
-
-- **必须先定位 trace 再查模块日志**：不允许无 trace 的全库检索。
-- 模块日志严格按会话记录、配置和模块手册信号选择，不要批量拉所有模块。
-- 同一模块先用 `"line": 20`，定位到关键行再决定是否扩量；禁止一次请求 `"line": 500`。
-
-## DSL 写法规范
-
-- 字段名不带引号：`rest` / `trace` / `severity` / `ext_2` 等
-- 字符串值必须加双引号：`rest:"HTTP_ASPECT"`（不是 `rest:HTTP_ASPECT`）
-- 关键字大写：`AND` / `OR` / `NOT`
-- 多条件用括号分组：`trace:"xxx" AND (rest:"A" OR rest:"B")`
-
-## 时间窗
-
-- 应用日志保留一个月；带上 trace 后时间窗放宽到 ±30min 甚至更宽都安全
-- 默认先用 `createdAt ± 5~10min`，漏查再扩到 ±30min
-- **禁止反复拉取相同 trace + 相同 query + 相同时间窗**，这是浪费配额

package/skills/shulex-support/references/badcase-analysis/text/m1-entry.md

@@ -1,53 +0,0 @@
-# M1：入口模块
-
-**职责**：`BotController` 接收外部请求，统一转发到核心 chat 方法。
-
----
-
-## 三条 HTTP 入口
-
-所有入口最终汇聚至同一个核心方法：
-`BotController.chat(Bot, Cactus, BotChatRequest, Consumer<StreamChatResponse>)`
-
-| 入口 | 路径 | 触发方式 | Consumer |
-|------|------|----------|---------|
-| 同步 | `POST /bot/{botId}/chat` | 直接 HTTP | null |
-| 流式 | `POST /bot/{botId}/chat/stream` / `chatStream` | SSE | lambda 写 SSE |
-| 异步 | `POST /bot/{botId}/chat/async` | Kafka `@KafkaListener` | null |
-
-异步路径：请求写 Kafka → `@KafkaListener` 消费 `BotChatAsyncTask` → 解包 → 调用同一 `chat()` 方法。
-
----
-
-## 核心 chat() 方法
-
-```
-chat(Bot, Cactus, BotChatRequest, Consumer)
-  → 初始化 thread context、chatAliveKey、performance profile
-  → beforeChat()         ← 前置处理（权限、限流等）
-  → bot.chat()           ← DefaultChatbot.chat()（主逻辑）
-  → afterChat()          ← 同步票据、inbox、Prometheus 指标、perf 对象
-```
-
-**日志**：`CHAT[{}]: botId = {}, tenantId = {}, userId = {}, request = {}`
-
----
-
-## HumanReview 旁路
-
-在 `DefaultChatbot.chat()` 内，某些场景会跳过意图识别 + 策略匹配，**直接**进入 `agentService.executeAgent()`：
-
-- **HumanReview 通过**：上一轮人工审核通过后，下一轮直接继续 Agent 执行
-- **多轮 Agent 对话**：`useLastTurnParseResult=true` 时跳过 intent parse，复用上轮结果
-
-HumanReview 旁路时，会话记录中无 `strategyName`，意图识别相关字段也不更新。
-
----
-
-## 分析要点
-
-- `HTTP_ASPECT` 是 SLS 中标记入口请求的关键字，用于定位 trace（见 `sls-query.md`）
-- chatId 在 `rest` 字段里（不是 `ext_2`）
-- **异步的 trace 在 Kafka 处断开**：生产端 trace_A 与消费端 trace_B 是两条独立 trace，但日志里有 `span` 字段可以跨 Kafka 串联（入口日志里的 span 值 = 消费端日志的 span 值）。M2~M8 的日志落在消费端 trace_B 下。详见 `sls-query.md` 的「异步路径」小节。
-- `trace_A.timestamp` 与 `trace_B.timestamp` 差值 ≈ 消息排队时间，可用于判断消费积压
-- `context.timing.__stage_time_total` 在 `afterChat()` 后保存，覆盖消费端端到端时间（异步时不含排队）