# Agent A2: 医美面诊复盘与挖掘智能体 - 集成开发手册

## 1. 智能体简介 (Agent Overview)

**Agent A2 (Consultation Reviewer)** 是“销售洞察智能体系统”中的核心质检与资产挖掘引擎。它处于业务流程的“事后复盘”环节。

* **核心职责**：将非结构化的面诊录音文本（ASR转写结果）转化为结构化的 JSON 数据。
* **业务价值**：
    1. **合规风控**：自动识别医疗禁忌症询问缺失和违规承诺。
    2. **销售洞察**：分析未成交原因，还原现场博弈逻辑。
    3. **资产沉淀**：自动挖掘金牌话术，反哺知识库。

---

## 2. 系统集成架构 (Integration Architecture)

Agent A2 位于 **清洗层** 与 **洞察层** 之间：

```mermaid
graph LR
    A[ASR 服务] -->|raw_transcript| B(Agent A2)
    B -->|JSON Report| C[业务数据库]
    C -->|compliance_data| D[质检看板]
    C -->|psych_insight| E[Agent B: 深度画像]
    C -->|mined_scripts| F[知识库管理后台]
```

---

## 3. 接口规范 (Interface Specification)

该智能体通常通过 LLM API 调用实现。以下定义 Prompt 填充的数据契约。

### 3.1 输入参数 (Inputs)

在构建 Prompt 时，你需要将以下变量替换进提示词模板：

| 参数名 | 类型 | 必填 | 描述 | 示例值 |
| :--- | :--- | :--- | :--- | :--- |
| `transcript_text` | String | **Yes** | 完整的面诊录音转写文本。建议包含时间戳和说话人标识（如“发言人1”），Agent 会自动区分角色。 | `"发言人1: 您好... \n 发言人2:我想做眼睛..."` |
| `doctor_name` | String | No | 医生/咨询师姓名（若已知）。有助于 Agent 更准确地定位角色。 | `"刘医师"` |
| `consultation_date` | String | No | 面诊发生的日期。用于 JSON 中的 meta 信息填充。 | `"2025-09-05"` |
| `is_deal` | Boolean | No | 面诊后是否完成销售。用于 JSON 中的 meta 信息填充。 | `"False"` |

### 3.2 输出规范 (Outputs)

Agent A2 **严格保证**输出纯 JSON 格式数据。开发人员可直接进行 `JSON.parse()`。

#### 3.2.1 顶层结构

```json
{
  "meta_info": { ... },           // 基础元数据
  "module_1_complaint_expectations": { ... }, // 主诉与期望
  "module_2_medical_history": { ... },        // 病史与禁忌症 (重点关注 safety_protocol_check)
  "module_3_diagnosis": { ... },              // 诊断评估
  "module_4_treatment_plan": { ... },         // 方案逻辑
  "module_5_risk_disclosure": { ... },        // 风险合规 (重点关注 compliance_alert_level)
  "module_6_cost_negotiation": { ... },       // 价格博弈
  "module_7_psych_insight": { ... },          // 心理洞察 (流转给 Agent B)
  "module_8_doctor_coaching": { ... },        // 医生教练建议
  "module_9_script_mining": { ... }           // 话术挖掘 (流转给 知识库)
}
```

#### 3.2.2 关键业务字段解析 (用于后端逻辑处理)

后端开发需重点关注以下字段，用于触发业务逻辑或告警：

1. **合规熔断/告警**
    * 路径: `module_5_risk_disclosure.compliance_alert_level`
    * 值域: `"高" | "中" | "低"`
    * *Action*: 若值为 "高"，建议在后台标记该工单为“人工复核”，并推送消息给质检主管。

2. **SOP 执行率统计**
    * 路径: `module_2_medical_history.safety_protocol_check.is_fully_compliant`
    * 值域: `Boolean`
    * *Action*: 用于计算医生的“SOP执行规范率”KPI。

3. **违规词监控**
    * 路径: `module_5_risk_disclosure.prohibited_words_detected`
    * 值域: `Array<String>`
    * *Action*: 若数组非空，高亮展示违规词汇。

4. **知识库资产入库**
    * 路径: `module_9_script_mining.scripts`
    * 值域: `Array<Object>`
    * *Action*: 将数组中的 `refined_text` 和 `applicability_tag` 存入“待审核话术池”，供人工审核入库。

---

## 4. 异常处理建议 (Exception Handling)

由于 LLM 的非确定性，建议在代码层做以下容错：

1. **JSON 解析失败**:
    * 虽然提示词做了约束，但 LLM 偶尔可能输出 Markdown 代码块（如 ` ```json `）。建议先用正则清洗掉代码块标记，再 Parse。
2. **角色混淆**:
    * 如果录音质量极差，Agent 可能无法区分医生和患者。检查 `meta_info.doctor_name` 是否为空或 `null`，若无法识别，前端展示时应提示“自动分析置信度低”。
3. **字段缺失**:
    * 所有字段都可能返回 `null`（如果对话中未提及）。前端渲染时需做空值保护（Null Safety）。

---

## 5. 开发调试 Tips

* **Prompt 注入位置**: 将完整的系统提示词（Core Layer 到 Operation Layer）放入 API 的 `system_message` 或 `system_prompt` 参数中。
* **Temperature 设置**: 建议设置为 **0.3 - 0.5**。
  * A2 需要一定的逻辑分析能力（不能太低），但输出格式又要严格受控（不能太高）。
  * *不要*设置为 0，否则生成的“话术挖掘”和“深度分析”会过于板正，缺乏灵气。
* **Max Tokens**: 建议预留 **2000 - 4000 tokens** 用于输出。一份包含深度分析和话术挖掘的完整报告通常较长。

---

## 6. 示例数据流 (Data Flow Example)

**Input (ASR Text):**
> “医生，我想打个瘦脸针，多少钱？... 不会有副作用吧？... 好的，我今天就打。”

**Agent A2 Processing...**

**Output (JSON Snippet):**

```json
{
  "module_2_medical_history": {
    "safety_protocol_check": {
      "is_fully_compliant": false,
      "missing_critical_items": ["重症肌无力史", "过敏史"],
      "risk_assessment_analysis": "严重违规。医生在客户决定'今天就打'之前，完全未确认禁忌症。"
    }
  },
  "module_5_risk_disclosure": {
    "compliance_alert_level": "高",
    "risk_disclosure_analysis": "医生对副作用问题采取了回避态度..."
  },
  "module_9_script_mining": {
    "scripts": [] // 本次对话无亮点话术
  }
}
```

**System Action:**

* 触发【高危告警】。
* SOP 评分扣除。
* 知识库无新增。