mcpField
C
cxas-loss-analysis

cxas-loss-analysis

github.com/googlecloudplatform数据与数据库11347 次安装今天更新
代码仓库

关于 cxas-loss-analysis

cxas-loss-analysis 是分析 CCAI Insights 近期升级或未解决会话的 AI Agent 技能。它将真实失败归纳为模式，排除一开始就排斥 AI 的会话，并生成包含会话分类的 Markdown 报告。

主要功能

  1. 01提取失败会话记录
  2. 02识别并排除 AI 排斥情况
  3. 03概述升级原因
  4. 04将失败聚类为模式
  5. 05生成 Markdown 报告

适用场景

  1. 01复查虚拟 Agent 升级转接
  2. 02发现反复出现的解决失败
  3. 03区分 AI 排斥与服务问题
  4. 04生成会话失败分析报告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/googlecloudplatform/cxas-scrapi --skill cxas-loss-analysis

安装后在 Claude Code 中输入/cxas-loss-analysis确认已加载。

附带文件scripts/fetch_losses.py

详细介绍

Insights 流失分析与报告生成器

此技能指导你（AI Agent）从 CCAI Insights 获取近期对话，筛选出已升级/未解决的会话（流失），分析其根本原因并归纳为失败模式，然后撰写专业的 Markdown 报告。

执行流程

请严格按以下顺序执行这些步骤：

步骤 1：参数验证

确认用户已提供以下必需参数：

  • project_id：托管 Insights 的 GCP 项目 ID。
  • location：Insights 位置（例如，us）。
  • app_id：目标 CXAS 应用 ID（例如，db9ee866-28db-458b-b835-78137c974779）。
  • output_dir：用于保存最终报告和测试用例的目录。

如果用户希望限定分析范围，还需确认以下可选参数：

  • start_time：时间段的起始 RFC 3339 时间戳（例如，2026-05-20T00:00:00Z）。
  • end_time：时间段的结束 RFC 3339 时间戳（例如，2026-05-26T23:59:59Z）。
  • filter：要应用的自定义 API 过滤字符串（覆盖默认的流失过滤条件 -labels.sessionContained="true"）。
  • limit：要获取并处理的最大对话数（默认值：500）。
步骤 2：提取流失对话记录

运行轻量级数据提取脚本，将流失对话记录导出为工作区中的分块 JSON 文件。

命令模板：

python3 -P .agents/skills/cxas-loss-analysis/scripts/fetch_losses.py \
  --project-id "{project_id}" \
  --location "{location}" \
  --app-id "{app_id}" \
  --limit {limit} \
  --output-file "{output_dir}/raw_losses.json" \
  [--start-time "{start_time}"] \
  [--end-time "{end_time}"] \
  [--filter "{filter}"]

注意：始终使用虚拟环境的可执行文件运行 python，并添加 -P 标志（例如，.venv/bin/python -P），以避免路径污染。

步骤 3：读取对话记录并总结升级情况

使用 view_file 或其他文件读取工具读取生成的 {output_dir}/raw_losses.json 文件。提取 chunks 列表（其中包含分块 JSON 文件的路径）。

对于 chunks 列表中的每个分块文件：

  1. 读取分块文件，加载其中的一批对话记录。
  2. 对于每份对话记录： a. 分析客户（user）与虚拟 Agent（agent）之间的对话。 b. 判断用户是否表现出 “排斥 AI”：
    • 定义：用户未与 Agent 进行实质性互动，或强烈表示希望与人工客服交流的会话（例如，在前 1～2 轮对话中，没有说明问题就立即要求“人工客服”“客服”或“代表”，或者明确表示不想与 AI/机器人交谈）。
    • 如果检测到“排斥 AI”，则将该会话标记为排除，不纳入核心流失分析。记录原因（例如，“排斥 AI：用户立即要求转接人工客服”）。 c. 对于未排除的真实流失会话：
    • 找出对话升级或未解决的原因。
    • 用简洁的 1 句话概括失败/升级的主要原因（最多 20 个单词）。例如，“虚拟 Agent 因用户多次输入 PIN 错误而未能完成身份验证。”
步骤 4：将失败归纳为流失模式

查看步骤 3 中生成的全部真实（未排除）失败原因。运用分析能力，将这些失败原因归纳为 8 到 10 种不同且互斥的失败模式，以提供细致的洞察。

为每种模式定义：

  1. 模式 ID：简单的键（例如，pattern_1、pattern_2……）。
  2. 名称：简短且具有描述性的名称（例如，“身份验证循环”、“不支持的客户意图”、“澄清时转接 Agent”）。
  3. 描述：用 1～2 句话清楚说明该模式及其触发条件。
步骤 5：对所有会话进行分类

将每个已分析的 conversation_id 映射到以下其中一项：

  • 8 到 10 种已定义的失败模式之一。
  • 如果用户表现出排斥 AI，则映射到 ignored_ai_aversion。

保留此映射，以供最终报告使用。

步骤 6：撰写 Markdown 报告

将分析整理为结构化的 Markdown 报告，并写入 {output_dir}/loss_patterns_report.md。使用以下结构：

# Loss Patterns Analysis Report

**Project**: `{project_id}`
**App ID**: `{app_id}`

## Executive Summary

A sample of up to {limit} conversations matching the filter was selected for detailed manual analysis and clustering to identify key patterns.

## Loss Patterns Distribution

| Pattern ID | Name | Count | Percentage of Genuine Losses |
| --- | --- | --- | --- |
| `pattern_1` | Pattern Name | Count | Pct% |
| ... | ... | ... | ... |

*Note: Ignored AI aversion sessions are excluded from the pattern distribution.*

## Detailed Patterns Breakdown

### `pattern_1`: Pattern Name

**Description**: Pattern description.
**Total Conversations**: Count

#### Examples & Failure Reasons:
- **Session `{conversation_id_1}`**: Failure reason from Step 3.
- **Session `{conversation_id_2}`**: Failure reason from Step 3.

---

## Appendix: Ignored Sessions (AI Aversion)
The following sessions were ignored from the pattern analysis because the user displayed AI aversion:
- **Session `{conversation_id_3}`**: AI aversion reason (e.g., *"User demanded human agent immediately"*).
- **Session `{conversation_id_4}`**: AI aversion reason.
步骤 7：向用户呈现摘要

在聊天中直接清晰地总结你的发现，指引用户查看 {output_dir}/loss_patterns_report.md，并突出显示关键模式和调整后的遏制率。

评论

支持 Markdown