cxas-cuj-report-generator

关键用户旅程（CUJ）转录与报告生成器技能

当需要从客户需求文档目录（例如图表、BRD、代码等）中提取对话转录或编制交互式关键用户旅程（CUJ）报告时，使用此技能。

核心协议

为确保 100% 覆盖且不丢失任何数据，必须遵循以下核心规则：

• 稳健提取：遵循 cxas-protocol-robust-extraction 技能中定义的协议。
• 两阶段摄取：遵循 protocols/cxas-protocol-two-phase-ingestion/ 中 cxas-protocol-two-phase-ingestion 子协议定义的协议。
• 清单要求：协调器和所有子 Agent 都必须遵循 agent-protocol-checklist 协议，维护本地 task_checklist.json 文件，以跟踪进度并确保执行过程中不遗漏任何内容。
• 协调器交付保障：协调器必须充当严格、独立的交付审计员。在关闭子 Agent、终止看门狗或向用户报告任务成功之前，协调器必须实际验证磁盘上所有已登记交付物（特别是 gecx_customer_report.html 和 gecx_cuj_report.html）的存在、大小范围和架构合规性。任何情况下，协调器都不得在未执行实际文件存在性检查的情况下假定任务已完成。
• 审计：协调器必须定期检查子 Agent 的临时目录，确保正在创建和维护 task_checklist.json 文件。如果文件缺失或未更新，协调器必须终止该子 Agent，并在加强执行要求后重新启动。

核心工作流步骤

按照以下 5 步结构化工作流执行任务：

1. 范围界定与类型发现：准备环境并识别所需技能。

   • 访问文件：确保可以访问本地工作区中的源资料。

     • 提示（云端硬盘链接）：如果源资料是 Google Drive 链接或文件夹 ID，必须使用 gdrive 技能访问。

   • 检测清单类型：为识别框架特征并将其映射到正确的摄取器，必须使用 agents/framework_detector.md 中定义的框架检测器 Agent。使用该 Agent 扫描输入文件，统计所有文件扩展名并检测潜在框架。启动多个并行的框架检测器子 Agent，分别扫描文件树的不同分区。

   • 映射摄取器：使用框架检测器生成的范围界定报告，从 ingestors/frameworks/ 或 ingestors/files/ 中选择或创建合适的专用技能。

     • 优先级规则：框架专用摄取器优先于通用文件扩展名摄取器（例如，如果两者都适用，则使用 ingestors/frameworks/adk/ 而不是 ingestors/files/py/）。

2. 发现：根据发现的类型启动专用专家子 Agent，以识别子意图（角色定义见 agents/ 目录）。动态发现并使用 ingestors/frameworks/ 和 ingestors/files/ 中的专用摄取器技能。

   • 强制交接：子 Agent 必须报告：

     1. 检测到的框架，
     2. 已解析的文件类型，以及
     3. 因超出范围而跳过的任何文件／模式。

   • 穷尽使用：使用所有相关摄取器，为每个文件应用最具体的适用摄取器。

   • 回退方案：如果没有适用于超出范围文件类型的专用摄取器，协调器必须委派分析：

     1. 生成分析器：生成一个专门的分析子 Agent，检查未知文件的样本。
     2. 研究：如果结构不明确，指示子 Agent 在线搜索或查阅内部文档，了解格式标准。
     3. 报告与编码：子 Agent 必须向编排器报告最佳解析策略，并且应尝试在 ingestors/frameworks/ 或 ingestors/files/ 中创建新的专用技能，以记录这些知识。

3. 穷尽搜索：循环执行，直到不再发现新的意图。

4. 聚类：归入父级 CUJ。为确保类别发现一致且准确：

   • 降低噪声：不要传入包含原始转录或代码的完整对象。
   • 摘要格式：提供整洁的 YAML 列表，包含 id、name（去除技术标签）和用一句话概括的 intent。
   • 指导：告知 Agent，合理的类别数量通常在 5 到 10 个之间。

5. 执行：使用此目录中的工具生成转录和报告。

   • 强制要求：将每个子 Agent 的批次大小限制为 5 到 10 项，以防止大模型上下文耗尽和内容截断。
   • 标题概括：对于每份转录，Agent 必须根据对话内容和 CUJ 标题，概括出简短、易读的场景标题，并将其存入 subintent_name 字段，而不是使用原始技术 ID。
   • 立即验证 ID：始终假设用户提供敏感号码（例如账户号码或订单 ID）后，后台系统会立即核查，并相应地插入 webhook_call 或 tool_call。
   • Agent 优先的转录：每份转录都必须以标准欢迎语开头：“Hello! Thanks for calling [Brand]. How can I help you today?”（如果未指定品牌，则使用通用欢迎语，例如：“Hello! Thanks for calling. How can I help you today?”）。绝无例外或其他说法，即使原始要求建议使用其他名称也不例外。
   • 语音真实感（不口述 URL）：语音渠道中的 Agent 不能口述很长的 URL。Agent 发言中绝不能写出原始 URL（例如，https://...）。相反，Agent 必须口头说明会通过短信或电子邮件发送链接（例如：“I've texted that tracking link to your phone”）。
   • 标准化结束会话：每段对话都必须以结构化的 3 轮告别序列结束：
     1. Agent：“Is there anything else I can help you with today?”
     2. 用户：“No, that's all. Thank you.”
     3. Agent：“Thank you for calling [Brand]! Goodbye.”（或相应的品牌告别语，例如：“Thank you for calling Customer Support! Goodbye.”；如果未指定品牌，则使用：“Thank you for calling! Goodbye.”）。绝不允许使用其他说法。Agent 的最后一轮发言必须触发 end_session 系统工具调用。在任何情况下都不得省略此工具调用。它必须符合以下 CXAS 架构：yaml tool_call: name: end_session payload: session_escalated: false reason: "Conversation completed successfully" response: result: "success"
   • 双报告：Agent 必须同时生成 CUJ 报告（示例最多 3 个）和完整报告（包含所有示例）。
   • 用法：运行 construct_report.py，使用 --cuj_report=True 生成 CUJ 报告，使用 --cuj_report=False 生成完整报告。

自主执行护栏

默认情况下，此工作流会长时间运行，并且需要自主执行。你 MUST 遵守以下护栏：

1. 自动看门狗：开始任务时，你 MUST 自动 安排一个重复计时器（例如使用 schedule 工具，每 5 分钟触发一次）， 中断并检查是否有卡住的子 Agent 或任务。
2. 初始确认：在你对用户的第一条回复中，你 MUST 明确说明你正在 应用稳健提取协议，并且已设置看门狗计时器。
3. 动态二分：如果某个批次因缺少项目而连续两次未通过验证门槛， 则自动将该批次二分，并生成两个并行子 Agent 来处理较小的工作量。

核心架构

所有生成的转录内容 MUST 遵循 resources/schemas/transcript_schema.yml 规范：

• subintent_id：唯一的 slug。
• subintent_name：便于理解的名称。
• parent_cuj：高层类别。
• turns：对话对象列表。

对话轮次要求

• **说话者：**必须是 Agent 或 User。请确保函数调用轮次紧接在用户轮次之后。
• **文本：**实际说出的字符串。
• 根级调用字段：tool_call（例如 end_session）和 webhook_call 字段 MUST 写在 YAML 转录中各个轮次对象的根级，而 MUST NOT 嵌套在 enrichment 或 任何其他父键之下。
• 增强信息：
  • intent_detected：在适用时指定 NLU 意图。
  • tool_call：Agent 调用本地函数时使用。
  • webhook_call：Agent 触发外部 API 时使用。
  • system_action：用于状态转换或后台逻辑。

语言与语音自然度标准

所有生成的口语对话轮次（Agent 语音轮次）MUST 严格遵守高保真口语标准。子 Agent 必须确保：

1. 数字语音规范化：Agent 的口语轮次 MUST NOT 包含原始数字、格式化货币或表示数字的标点符号（例如，不要写 "450"、"$909"、"555-0199"）。应将数字明确地按语音读法拼写出来：
   • 正确示例："four hundred fifty points"、"nine hundred nine dollars"。
   • ID、时间、订单号、百分比和电话号码：所有数字 ID、时间、计数、奖励积分、百分比或任何类型的数字，都必须逐位或逐词按语音读法拼写，且绝对不能使用标点或冒号分隔："five five five, zero, one, nine, nine"、"seven thirty PM"、"eight o'clock PM"、"order number nine nine eight eight"、"twenty percent discount"。
   • 预约确认：对于任何安排或告知具体时间、时段或预约日期的预订或配送更新（例如“二十分钟后就绪”“十分钟后送达”“已预约明天晚上八点”），MUST 明确征求用户确认（例如 “这样可以吗？”、“您觉得这样合适吗？” 或 “我们就这样安排好吗？”）。
2. 口语呼吸跨度限制：Agent 轮次必须简洁、自然且符合对话习惯。单个轮次中的口语文本块 MUST NOT 超过 300 个字符。
3. 用词流畅度：避免机械地重复相同的长词（单个轮次中，同一个长度为 5 个或更多字符的词不得重复超过 4 次）。
4. 对话礼貌性：每个 Agent 口语轮次 MUST 至少包含一个常用的礼貌用语（please、thank you、thanks、certainly、happy to help、welcome、goodbye、great day、my pleasure、certainly help），以确保为用户带来亲切自然的体验。

执行阶段详情

在执行阶段，子 Agent 不得直接写入对话记录文件。

1. 生成一个包含单轮数据的小型 YAML 文件。
2. 将其传递给 append_turn.py 脚本，以增量方式构建对话记录。
3. 验证所有批次后，运行 construct_report.py 生成最终的交互式 HTML 报告。

强制子 Agent 提示词要求：为批量执行启动子 Agent 时，编排器必须在其提示词中包含以下指令：

"每一轮都必须使用 append_turn.py。不要总结对话。为批次中的每个项目生成完整、自然的对话。"