# 04 - Conversation Strategist Agent (策略顾问) 设计详解

## 1. 核心职责

Strategist 是系统中的**幕后军师**。它的输出**不直接展示给用户**，而是为 Coordinator 提供对话策略建议。它替代了旧架构中 `StrategyEngineService` 的阶段判断和引导逻辑。

核心能力：
1. **情绪感知** -- 分析用户当前的情绪状态（积极/中立/犹豫/抗拒）
2. **阶段判断** -- 判断对话处于哪个咨询阶段（开场/了解需求/信息收集/评估推荐/异议处理/转化促成）
3. **转化信号检测** -- 识别用户是否释放了购买意向信号
4. **信息缺口分析** -- 判断还缺哪些关键信息，以及收集优先级
5. **策略推荐** -- 建议 Coordinator 下一步应该做什么（继续收集信息/推进评估/处理异议/促成转化）
6. **语气调节** -- 建议回复的语气和节奏

> 设计原则：**Strategist 是 Coordinator 的私人顾问，用户永远看不到它的输出。** 它帮助 Coordinator 做更好的对话决策，而不是直接生成用户回复。

## 2. 模型与参数

```typescript
{
  model: 'claude-sonnet-4-20250514',  // 情商和推理能力要求高
  max_tokens: 1500,                    // 策略建议不需要太长
  temperature: 0.3,                    // 允许少量创造性（策略建议需要灵活性）
  system: [
    {
      type: 'text',
      text: strategistPrompt,
      cache_control: { type: 'ephemeral' }
    }
  ],
}
```

选用 Sonnet 的理由：
- 需要深层次的情绪分析和对话理解
- 需要综合考虑商业目标和用户体验的平衡
- 策略建议的质量直接影响转化率

## 3. 可用工具 (Available Tools)

Strategist 只有 **1 个工具**：

### 3.1 get_user_context

```typescript
{
  name: 'get_user_context',
  description: '获取用户的历史背景信息和过往对话记忆，用于制定更精准的对话策略。',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '检索用户记忆的查询，如"用户的购买意向和顾虑"'
      }
    },
    required: ['query']
  }
}
```

> Strategist **不需要** search_knowledge，因为它不回答政策问题。它只需要理解用户是谁、想什么、担心什么。

## 4. System Prompt 要点

```
# 身份
你是 iConsulting 的对话策略顾问。你的建议仅供 Coordinator 参考，不会展示给用户。

# 核心目标
在确保用户体验的前提下，最大化咨询转化率。转化路径：
1. 免费咨询 → 收集信息 → 初步评估 → 付费详细评估（¥99-199）
2. 付费评估 → 推荐方案 → 预约人工专家对接

# 对话阶段定义
- GREETING: 开场寒暄，建立信任（1-2轮）
- DISCOVERY: 了解需求，初步分类（2-3轮）
- INFO_COLLECTION: 收集评估所需信息（3-5轮）
- ASSESSMENT: 展示评估结果和推荐方案（1-2轮）
- OBJECTION_HANDLING: 处理用户顾虑和异议（1-3轮）
- CONVERSION: 促成付费或专家对接（1-2轮）
- FOLLOW_UP: 售后跟进（持续）

# 分析维度
1. 用户情绪：enthusiastic / positive / neutral / hesitant / resistant / frustrated
2. 转化信号：
   - 强信号：询问价格、如何付款、下一步怎么做
   - 中信号：频繁追问细节、表达时间紧迫感
   - 弱信号：问了3个以上问题、主动分享个人信息
   - 负信号：表达"太贵了""再考虑""不急"
3. 信息缺口优先级：
   - P0（评估必需）：年龄、学历、工作经验
   - P1（精准匹配）：院校、年收入、行业
   - P2（细化方案）：语言能力、家庭情况、时间规划

# 策略原则
- 不要一次问超过2个问题
- 每3轮信息收集后给一个小结或正面反馈
- 用户表现出犹豫时，先共情再提供事实
- 不要过早推销付费服务，先让用户感受到价值
- 检测到强转化信号时，建议 Coordinator 适时引入付费评估
```

## 5. 输入/输出格式

### 输入 (Coordinator 传入)

```typescript
interface StrategistInput {
  /** 对话摘要：最近几轮的概括 */
  conversationSummary: string;
  /** Coordinator 判断的当前阶段 */
  currentStage: string;
  /** 用户最新一条消息 */
  latestUserMessage?: string;
  /** 已收集的用户信息键值对 */
  collectedInfo?: Record<string, unknown>;
  /** 当前对话轮次 */
  turnCount?: number;
}
```

### 输出 (返回给 Coordinator)

```typescript
interface StrategistOutput {
  /** 策略建议（最核心的内容） */
  strategy_advice: {
    /** 建议的下一步行动 */
    recommended_next_action:
      | 'continue_collecting_info'    // 继续收集信息
      | 'provide_assessment'          // 给出评估结果
      | 'address_objection'           // 处理异议
      | 'offer_paid_service'          // 推荐付费服务
      | 'connect_expert'              // 推荐人工专家
      | 'provide_policy_info'         // 提供政策信息
      | 'build_rapport'               // 建立关系（闲聊/共情）
      | 'summarize_progress';         // 小结当前进展

    /** 行动的具体建议描述 */
    action_detail: string;

    /** 信息收集优先级（如果推荐继续收集） */
    missing_info_priorities: Array<{
      field: string;                  // 字段名
      priority: 'P0' | 'P1' | 'P2';
      suggested_question: string;     // 建议的提问方式
    }>;
  };

  /** 转化信号分析 */
  conversion_signals: {
    signal_strength: 'strong' | 'medium' | 'weak' | 'negative';
    signals_detected: string[];       // 检测到的具体信号
    conversion_readiness: number;     // 0-100 转化就绪度
  };

  /** 情绪分析 */
  sentiment_analysis: {
    current_mood: 'enthusiastic' | 'positive' | 'neutral' | 'hesitant' | 'resistant' | 'frustrated';
    mood_trend: 'improving' | 'stable' | 'declining';
    key_concerns: string[];           // 用户当前主要顾虑
  };

  /** 语气调节建议 */
  tone_adjustment: {
    suggested_tone: 'professional' | 'warm' | 'encouraging' | 'empathetic' | 'urgent';
    response_length: 'short' | 'medium' | 'long';
    should_use_emoji: boolean;
    special_notes: string;            // 特殊注意事项
  };

  /** 阶段建议 */
  stage_assessment: {
    current_stage: string;
    should_transition: boolean;
    suggested_next_stage?: string;
    transition_reason?: string;
  };
}
```

## 6. 触发时机 (When to Trigger)

Coordinator 在以下场景调用 `invoke_strategist`：

| 场景 | 触发条件 | 目的 |
|------|----------|------|
| 对话初期定调 | 第 2-3 轮对话时 | 获取初始策略定位 |
| 用户情绪变化 | 用户语气/态度明显变化 | 及时调整对话策略 |
| 信息收集中期 | 每收集 2-3 条信息后 | 判断是否该给评估了 |
| 转化决策点 | 评估结果呈现后 | 判断是否该推付费服务 |
| 异议出现 | 用户表达顾虑/犹豫 | 获取处理建议（配合 Objection Handler） |
| 对话停滞 | 用户回复变短/间隔变长 | 获取重新激活策略 |

**不应触发的场景**：
- 第一轮开场白（还没有足够信息做策略分析）
- 用户提的是纯政策问题（直接调 Policy Expert 即可）
- 对话已经进入支付流程

**调用频率控制**：建议每 2-3 轮调用一次，避免每轮都调（浪费 token）。

## 7. 内部循环 (Internal Loop)

Strategist 的内部循环非常简洁，通常 **1 轮**即可完成：

```
┌─────────────────────────────────────────────────┐
│  Strategist Internal Loop (max 2 turns)         │
│                                                  │
│  Turn 0: 分析输入                                │
│  ├── 如果 Coordinator 传入的信息足够             │
│  │   └── 直接生成策略建议（大多数情况）           │
│  │                                               │
│  ├── 如果需要更多用户历史                        │
│  │   └── get_user_context() 获取用户记忆          │
│  │                                               │
│  Turn 1: 综合分析                                │
│  ├── 结合用户记忆 + 对话摘要                     │
│  └── 生成策略建议                                │
└─────────────────────────────────────────────────┘
```

> Strategist 的设计偏向**轻量级**：快速分析、快速返回。它不需要搜索知识库，不需要多轮推理。

## 8. 与其他 Agent 的关系

```
┌──────────────┐        invoke_strategist           ┌──────────────┐
│              │ ──────────────────────────────────→ │              │
│  Coordinator │        StrategistOutput            │  Strategist  │
│              │ ←────────────────────────────────── │              │
└──────┬───────┘                                     └──────┬───────┘
       │                                                     │
       │  Coordinator 根据策略建议决定：                        │ get_user_context
       │                                                     ↓
       │  ┌────────────────────────────────────┐    ┌──────────────┐
       │  │ 如果 recommended = 'address_objection' │    │ Knowledge    │
       │  │  → invoke_objection_handler             │    │ Service      │
       │  │                                         │    │ (Memory)     │
       │  │ 如果 recommended = 'provide_assessment' │    └──────────────┘
       │  │  → invoke_assessment_expert             │
       │  │                                         │
       │  │ 如果 recommended = 'provide_policy_info'│
       │  │  → invoke_policy_expert                 │
       │  │                                         │
       │  │ 如果 recommended = 'offer_paid_service' │
       │  │  → generate_payment                     │
       │  └────────────────────────────────────┘
       │
       │  Strategist 输出 → Coordinator 的下一次决策参考
       │  （不缓存，每次调用都是独立判断）
```

**与旧架构的对应关系**：

| 旧架构 | 新架构 |
|--------|--------|
| `StrategyEngineService.evaluateTransition()` | Strategist 的 `stage_assessment` |
| `StrategyEngineService.buildStageGuidance()` | Strategist 的 `strategy_advice` |
| `DEFAULT_CONSULTING_STRATEGY` 中的 8 阶段状态机 | Strategist LLM 自主判断阶段 |
| 程序化的 `detectUserIntents()` | Strategist 的 `sentiment_analysis` + `conversion_signals` |

**核心区别**：旧架构用规则引擎判断阶段转移，新架构用 LLM 做整体性判断，更灵活、更能理解语境。

## 9. 示例场景

### 场景 1：信息收集中期 -- 用户开始犹豫

**Coordinator 调用**：

```json
{
  "tool": "invoke_strategist",
  "input": {
    "conversationSummary": "用户是一位35岁的金融从业者，已告知学历为本科（非百强大学），年收入约60万人民币，工作经验10年。上一轮用户主动分享了这些信息。这一轮用户说'好的，其实我也不确定自己到底适不适合移民'",
    "currentStage": "INFO_COLLECTION",
    "latestUserMessage": "好的，其实我也不确定自己到底适不适合移民",
    "collectedInfo": {
      "age": 35,
      "education": "本科",
      "annualIncome": 600000,
      "totalYearsOfExperience": 10,
      "currentIndustry": "金融"
    },
    "turnCount": 6
  }
}
```

**返回结果**：

```json
{
  "strategy_advice": {
    "recommended_next_action": "build_rapport",
    "action_detail": "用户开始出现犹豫情绪，此时不宜继续追问信息。建议先肯定用户已经分享的信息，给出一些积极反馈（如年龄和工作经验在优才计划中是加分项），让用户感受到希望。然后自然过渡到给一个初步评估，让用户看到具体可能性。",
    "missing_info_priorities": [
      {
        "field": "university",
        "priority": "P1",
        "suggested_question": "暂不追问，等用户情绪稳定后再自然引出"
      },
      {
        "field": "languageSkills",
        "priority": "P2",
        "suggested_question": "可在评估时顺带确认"
      }
    ]
  },
  "conversion_signals": {
    "signal_strength": "weak",
    "signals_detected": ["主动分享了较多个人信息", "但出现了犹豫表达"],
    "conversion_readiness": 35
  },
  "sentiment_analysis": {
    "current_mood": "hesitant",
    "mood_trend": "declining",
    "key_concerns": ["对自身条件缺乏信心", "移民决策本身的不确定性"]
  },
  "tone_adjustment": {
    "suggested_tone": "encouraging",
    "response_length": "medium",
    "should_use_emoji": false,
    "special_notes": "先共情'确实移民是个大决定'，然后用已有信息给出一些积极评价，避免继续追问"
  },
  "stage_assessment": {
    "current_stage": "INFO_COLLECTION",
    "should_transition": false,
    "suggested_next_stage": null,
    "transition_reason": "虽然信息基本够做初步评估，但用户情绪需要先稳定。建议在下一轮给出鼓励性的初步反馈后，再过渡到评估阶段。"
  }
}
```

### 场景 2：用户释放强转化信号

**Coordinator 调用**：

```json
{
  "tool": "invoke_strategist",
  "input": {
    "conversationSummary": "用户32岁，清华大学硕士，8年IT经验。已完成评估，TTPS B类高度推荐（88分）。上一轮展示了评估结果，用户回复'这个评估很详细！那如果我想正式申请，下一步应该怎么做？'",
    "currentStage": "ASSESSMENT",
    "latestUserMessage": "这个评估很详细！那如果我想正式申请，下一步应该怎么做？",
    "collectedInfo": {
      "age": 32,
      "education": "硕士",
      "university": "清华大学",
      "totalYearsOfExperience": 8,
      "currentIndustry": "IT/科技"
    },
    "turnCount": 8
  }
}
```

**返回结果**：

```json
{
  "strategy_advice": {
    "recommended_next_action": "offer_paid_service",
    "action_detail": "用户主动询问下一步，这是非常强的转化信号。建议：1）先肯定用户的条件确实很好（TTPS B类高匹配），增强信心；2）说明免费咨询只能给到初步方向，付费详细评估可以提供完整的材料清单、时间规划、风险评估；3）自然引出付费评估服务（¥99），强调性价比。不要硬推，用'如果您想更详细了解'的方式。",
    "missing_info_priorities": []
  },
  "conversion_signals": {
    "signal_strength": "strong",
    "signals_detected": [
      "主动询问下一步行动",
      "对评估结果表达积极认可",
      "使用了感叹号表达兴奋"
    ],
    "conversion_readiness": 85
  },
  "sentiment_analysis": {
    "current_mood": "enthusiastic",
    "mood_trend": "improving",
    "key_concerns": []
  },
  "tone_adjustment": {
    "suggested_tone": "professional",
    "response_length": "medium",
    "should_use_emoji": false,
    "special_notes": "保持专业，不要因为用户热情就过度推销。提供清晰的选项：付费评估 or 预约专家。让用户自己选择。"
  },
  "stage_assessment": {
    "current_stage": "ASSESSMENT",
    "should_transition": true,
    "suggested_next_stage": "CONVERSION",
    "transition_reason": "用户已认可评估结果并主动询问下一步，时机成熟，进入转化阶段。"
  }
}
```
