# Agent A1 集成手册 (Integration Manual)

**版本**: 2.0
**最后更新**: 2025-12-27
**适用对象**: 后端工程师、系统架构师

## 1. 智能体概览 (Agent Overview)

**Agent A1** 是整个销售洞察系统的“前哨站”。它负责处理非结构化的微信聊天记录，将其转化为结构化的客户画像数据和标准化的知识库条目。

*   **输入**: 原始微信聊天记录 (Raw Text/CSV)。
*   **输出**: 严格的 JSON 对象，包含客户画像 (`client_profile`)、知识挖掘 (`knowledge_mining`) 和面诊建议 (`reception_tip`)。
*   **核心依赖**: LLM (推荐 GPT-4o 或同级推理能力模型)，内置 `Med-3C` 心理推理框架。
*   **延迟敏感度**: 异步处理（建议任务耗时 30s - 60s）。

## 2. 接口定义 (Interface Definition)

建议将 Agent A1 封装为一个独立的服务或 API 接口。

### 2.1 请求格式 (Request)

```json
POST /api/v1/agents/a1/process
Content-Type: application/json

{
  "trace_id": "uuid-v4-string", // 用于全链路追踪
  "input_data": {
    "raw_chat_text": "string",  // 必需。完整的聊天记录文本。建议包含时间戳和发送人ID。
    "consultant_name": "string", // 可选。咨询师的微信昵称，辅助LLM区分角色。
    "client_name": "string",     // 可选。客户的微信昵称。
    "current_date": "YYYY-MM-DD" // 可选。用于推断相对时间（如“上周”）。
  }
}
```

### 2.2 响应格式 (Response)

成功响应 (HTTP 200) 将返回一个标准的 JSON 包体。详细 Schema 请见下文“3. 输出数据结构详情”。

```json
{
  "code": 200,
  "data": {
    "client_profile": { ... },
    "knowledge_mining": [ ... ],
    "consultation_insights": { ... },
    "sales_audit": { ... },
    "reception_tip": "..."
  },
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 800
  }
}
```

## 3. 输出数据结构详情 (Output Schema)

后端系统需按照此 Schema 进行解析和入库。

### 3.1 `client_profile` (客户画像表)
*   **用途**: 更新 CRM 客户档案，作为 Agent B (深度画像) 的输入源。

| 字段名 | 类型 | 说明 | 示例值 |
| :--- | :--- | :--- | :--- |
| `facts.medical_history` | String | 已确认的病史/过往项目 | "玻尿酸填充史；青霉素过敏" |
| `facts.pain_sensitivity` | String | 疼痛敏感度 | "高（曾抱怨打针疼）" |
| `facts.location_context` | String | 地理位置特征 | "异地-天津（需坐高铁）" |
| `facts.occupation_context` | String | 职业/时间特征 | "高压金融从业者" |
| `inferred_persona` | String | 一句话人设总结 | "追求高效的异地商务精英" |
| `life_rhythm` | String | 生活节奏与压力分析 | "时间敏感度[高]，社交压力[中]" |
| `core_needs` | String | 核心显性需求 | "面部抗衰 + 肤质改善" |
| `main_concerns` | String | 主要决策顾虑 | "恢复期是否影响周一开会" |

### 3.2 `knowledge_mining` (知识挖掘表) - *核心资产*
*   **用途**: **直接存入知识库 (Vector DB / KB SQL)**，供 Agent C 检索。
*   **ETL 逻辑**: 该数组中的每一项应作为一条独立的 Record 插入知识库。

| 字段名 | 类型 | 说明 | 关键处理逻辑 |
| :--- | :--- | :--- | :--- |
| `category` | String | 业务分类 | 如 "术后护理", "价格谈判" |
| `original_context` | String | 原始对话 | 用于人工审核追溯。 |
| `refined_text` | String | **金牌话术 (SOP)** | **知识库的 `content` 字段。** |
| `why_it_works` | String | 策略分析 | 知识库的 `reasoning` 字段。 |
| `applicability_tags` | List<String> | **3C 标签** | **知识库的 `tags` 索引字段。** 严格匹配 Agent B 的输出标签。 |

**入库示例 (Pseudo-Code):**
```python
for item in response.data.knowledge_mining:
    KnowledgeBase.insert({
        "content": item.refined_text,
        "tags": item.applicability_tags, # e.g. ["Mem:社交败露恐惧"]
        "metadata": {
            "source": "A1_Chat_Mining",
            "reasoning": item.why_it_works
        }
    })
```

### 3.3 其他字段
*   `reception_tip` (String): 直接展示在医生/前台接待 iPad 端。
*   `sales_audit` (Object): 包含 `strategy_mismatch_alert`。若非 null，应在 CRM 中对该销售主管发送“预警通知”。

## 4. 业务逻辑与处理流程 (Workflow)

1.  **预处理 (Pre-processing)**:
    *   **清洗格式**: 将导出的微信记录（通常是混乱的文本）处理为 `[Time] [Speaker]: [Content]` 的标准格式，减少 Token 消耗。
    *   **截断策略**: 建议仅截取最近 3-6 个月的聊天记录，或限制 Token 数在 10k-20k 之间，避免上下文溢出。

2.  **Prompt 组装**:
    *   加载 `System Prompt` (即上文提供的 Agent A1 V2.0 提示词)。
    *   将预处理后的聊天记录注入 Prompt 的 `User Message` 部分。

3.  **LLM 调用**:
    *   Temperature 建议设置在 `0.2 - 0.4`，保证输出格式的稳定性。
    *   **强制 JSON 模式**: 务必开启 Model 的 `JSON Mode` (如 OpenAI 的 `response_format: { "type": "json_object" }`)。

4.  **后处理与验证 (Post-processing)**:
    *   **JSON Parse**: 解析返回字符串。
    *   **标签白名单校验**: 检查 `applicability_tags` 是否都在允许的 3C 标签列表中。如果出现未知标签，建议在入库前清洗掉或标记为“待人工审核”。

## 5. 异常处理机制 (Exception Handling)

| 异常情况 | 现象 | 建议处理方案 |
| :--- | :--- | :--- |
| **聊天记录为空/过短** | 输入文本 < 50 字符 | 直接返回默认空对象，不调用 LLM，节省成本。 |
| **JSON 解析失败** | LLM 输出非标准 JSON | 记录 Error Log，触发一次 Retry (Temperature 设为 0)。 |
| **无挖掘价值** | `knowledge_mining` 为空数组 | 正常入库 `client_profile`，忽略知识库插入步骤。 |
| **敏感信息残留** | 输出包含人名/手机号 | 在后端增加一层 Regex 过滤器，再次清洗 PII 信息。 |

## 6. 开发与测试 Checklists

### 开发阶段
- [ ] 确认后端可以接收并存储大文本（聊天记录可能很长）。
- [ ] 实现了 3C 标签的 Enum 定义，确保数据库能正确存储 Tag。
- [ ] 实现了将 `knowledge_mining` 数组拆解并批量写入知识库的逻辑。

### 测试阶段 (验收标准)
- [ ] **格式测试**: 输入一段混乱的聊天记录，必须返回合法的 JSON。
- [ ] **标签一致性**: `applicability_tags` 必须包含如 `[Mem: 社交败露恐惧]` 格式的标签。
- [ ] **润色效果**: 对比 `original_context` 和 `refined_text`，后者必须去除口语化词汇（如“亲”、“哈”）。
- [ ] **隐私合规**: 输出结果中不应包含具体的真实姓名。