6.6 KiB

Raw Blame History

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)

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. 输出数据结构详情”。

{
  "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	3C 标签	知识库的 `tags` 索引字段。严格匹配 Agent B 的输出标签。

入库示例 (Pseudo-Code):

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)

预处理 (Pre-processing):
- 清洗格式: 将导出的微信记录（通常是混乱的文本）处理为 [Time] [Speaker]: [Content] 的标准格式，减少 Token 消耗。
- 截断策略: 建议仅截取最近 3-6 个月的聊天记录，或限制 Token 数在 10k-20k 之间，避免上下文溢出。
Prompt 组装:
- 加载 System Prompt (即上文提供的 Agent A1 V2.0 提示词)。
- 将预处理后的聊天记录注入 Prompt 的 User Message 部分。
LLM 调用:
- Temperature 建议设置在 0.2 - 0.4，保证输出格式的稳定性。
- 强制 JSON 模式: 务必开启 Model 的 JSON Mode (如 OpenAI 的 response_format: { "type": "json_object" })。
后处理与验证 (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，后者必须去除口语化词汇（如“亲”、“哈”）。
隐私合规: 输出结果中不应包含具体的真实姓名。

6.6 KiB Raw Blame History Unescape Escape