# 10 - 实施计划详解 (Implementation Plan)

## 1. 总体时间线

```
Week 1          Week 2          Week 2-3        Week 3          Week 4          Week 5
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ Phase 1  │   │ Phase 2  │   │ Phase 3  │   │ Phase 4  │   │ Phase 5+6│   │ Phase 7  │
│          │   │          │   │          │   │          │   │          │   │          │
│ 架构文档 │──→│ 基础设施  │──→│ 专家Agent│──→│ Coordinator│──→│ 集成+前端│──→│ 测试+优化│
│ + 类型   │   │          │   │          │   │          │   │          │   │          │
│ 定义     │   │ Queue    │   │ 6个Agent │   │ 核心Loop  │   │ Module   │   │ 场景测试 │
│          │   │ Context  │   │ 6份Prompt│   │ 主Prompt  │   │ Gateway  │   │ 性能优化 │
│          │   │ Base     │   │          │   │          │   │ Frontend │   │ 旧代码清理│
└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
```

## 2. Phase 1: 架构文档 + 类型定义 (Week 1)

### 2.1 架构文档（12份）

| 序号 | 文件 | 内容 | 状态 |
|------|------|------|------|
| 00 | `00-overview.md` | 总览 + 架构图 | ✅ 已完成 |
| 01 | `01-coordinator-agent.md` | Coordinator 设计 | ✅ 已完成 |
| 02 | `02-specialist-agents.md` | 6 个专家 Agent 设计 | 待完成 |
| 03 | `03-agent-communication.md` | Agent 间通信协议 | 待完成 |
| 04 | `04-streaming-protocol.md` | 流式传输协议 | 待完成 |
| 05 | `05-frontend-integration.md` | 前端集成方案 | 待完成 |
| 06 | `06-token-cost-management.md` | Token 与成本管理 | 待完成 |
| 07 | `07-testing-strategy.md` | 测试策略 | 待完成 |
| 08 | `08-context-injection.md` | 动态上下文注入 | ✅ 已完成 |
| 09 | `09-tool-execution.md` | 工具并发执行 | ✅ 已完成 |
| 10 | `10-implementation-plan.md` | 实施计划（本文档） | ✅ 已完成 |
| 11 | `11-prompt-templates.md` | 所有 Prompt 模板 | ✅ 已完成 |

### 2.2 类型定义文件

需要创建以下类型定义文件：

```
packages/services/conversation-service/src/infrastructure/agents/
├── types/
│   ├── agent.types.ts          # Agent 相关类型
│   ├── stream.types.ts         # 流式事件类型
│   └── context.types.ts        # 上下文注入类型
```

**agent.types.ts**：
```typescript
// 核心 Agent 类型定义

/** Agent 名称枚举 */
export enum AgentName {
  COORDINATOR = 'coordinator',
  POLICY_EXPERT = 'policy_expert',
  ASSESSMENT_EXPERT = 'assessment_expert',
  STRATEGIST = 'strategist',
  OBJECTION_HANDLER = 'objection_handler',
  CASE_ANALYST = 'case_analyst',
  MEMORY_MANAGER = 'memory_manager',
}

/** Agent 使用的模型 */
export enum AgentModel {
  SONNET = 'claude-sonnet-4-20250514',
  HAIKU = 'claude-haiku-4-20250514',
}

/** Agent 配置 */
export interface AgentConfig {
  name: AgentName;
  model: AgentModel;
  maxTokens: number;
  maxTurns: number;           // Agent mini-loop 最大轮次
  timeoutMs: number;          // 超时时间
  tools: string[];            // 可用工具名列表
  systemPromptFile: string;   // Prompt 文件路径
}

/** Agent 执行上下文 */
export interface AgentExecutionContext {
  userId: string;
  conversationId: string;
  coordinatorTurn: number;    // Coordinator 当前轮次
  parentToolUseId: string;    // 触发此 Agent 的 tool_use ID
}

/** Agent Loop 参数 */
export interface AgentLoopParams {
  messages: Anthropic.MessageParam[];
  systemPrompt: string[] | Anthropic.TextBlockParam[];
  tools: Anthropic.Tool[];
  maxTurns: number;
  maxBudgetUsd: number;
  conversationId: string;
  userId: string;
  abortSignal?: AbortSignal;
}

/** 咨询状态（从 consulting_state XML tag 提取） */
export interface ConsultingStateReport {
  currentStage: string;
  collectedFields: string[];
  nextAction: string;
  confidenceLevel: 'low' | 'medium' | 'high';
  recommendedPrograms?: string[];
}
```

**stream.types.ts**：
```typescript
// 流式事件类型

/** 所有可能的 Stream 事件 */
export type StreamEvent =
  | TextStreamEvent
  | AgentStartEvent
  | AgentProgressEvent
  | AgentCompleteEvent
  | ToolStartEvent
  | ToolCompleteEvent
  | ToolErrorEvent
  | StateUpdateEvent
  | UsageEvent
  | ErrorEvent
  | EndEvent;

export interface TextStreamEvent {
  type: 'text';
  content: string;
}

export interface AgentStartEvent {
  type: 'agent_start';
  agentName: string;
  toolUseId: string;
}

export interface AgentProgressEvent {
  type: 'agent_progress';
  agentName: string;
  turn: number;
  maxTurns: number;
}

export interface AgentCompleteEvent {
  type: 'agent_complete';
  agentName: string;
  durationMs: number;
  tokensUsed?: { input: number; output: number };
}

export interface StateUpdateEvent {
  type: 'state_update';
  state: ConsultingStateReport;
}

export interface UsageEvent {
  type: 'usage';
  usage: { inputTokens: number; outputTokens: number };
  totalCostUsd: number;
}

export interface ErrorEvent {
  type: 'error';
  code: string;
  message: string;
}

export interface EndEvent {
  type: 'end';
  totalTokens: { input: number; output: number };
  totalCostUsd: number;
  turnsUsed: number;
  agentsCalled: string[];
}
```

**context.types.ts**：
- 详见 [08-context-injection.md](./08-context-injection.md) 第 3 节

**交付标准**：
- 所有类型文件通过 `tsc --noEmit` 类型检查
- 每个 interface 有 JSDoc 注释
- 导出为 barrel file (`types/index.ts`)

## 3. Phase 2: 基础设施 (Week 2)

### 3.1 文件结构

```
packages/services/conversation-service/src/infrastructure/agents/
├── types/                          # Phase 1 产物
│   ├── agent.types.ts
│   ├── stream.types.ts
│   ├── context.types.ts
│   └── index.ts
├── core/                           # Phase 2 产物
│   ├── tool-execution-queue.ts     # 工具并发执行队列
│   ├── context-injector.service.ts # 上下文注入器
│   ├── base-specialist.service.ts  # 专家 Agent 基类
│   ├── agent-executor.ts           # Agent 执行器工厂
│   └── token-tracker.ts            # Token 追踪器
```

### 3.2 tool-execution-queue.ts

- 完整实现详见 [09-tool-execution.md](./09-tool-execution.md) 第 4 节
- **关键依赖**: `tool-execution.types.ts`
- **单测覆盖**:
  - 纯并发批次（所有 safe 工具）
  - 纯串行批次（所有 unsafe 工具）
  - 混合批次（safe + unsafe 交替）
  - 单个工具超时
  - 批次中一个工具失败
  - 空请求
  - 结果排序正确性

```typescript
// 单测示例
describe('ToolExecutionQueue', () => {
  it('should execute concurrent-safe tools in parallel', async () => {
    const queue = new ToolExecutionQueue();
    const executionOrder: string[] = [];

    queue.registerTool('tool_a', {
      isConcurrencySafe: true,
      executor: async () => {
        executionOrder.push('a_start');
        await sleep(100);
        executionOrder.push('a_end');
        return { content: 'a', success: true };
      },
      // ...
    });

    queue.registerTool('tool_b', {
      isConcurrencySafe: true,
      executor: async () => {
        executionOrder.push('b_start');
        await sleep(50);
        executionOrder.push('b_end');
        return { content: 'b', success: true };
      },
      // ...
    });

    const results = await queue.executeAll([
      { toolUseId: '1', toolName: 'tool_a', input: {}, originalIndex: 0 },
      { toolUseId: '2', toolName: 'tool_b', input: {}, originalIndex: 1 },
    ]);

    // 两个工具应该几乎同时开始
    expect(executionOrder[0]).toBe('a_start');
    expect(executionOrder[1]).toBe('b_start');
    // b 先完成（50ms vs 100ms）
    expect(executionOrder[2]).toBe('b_end');
    expect(executionOrder[3]).toBe('a_end');
    // 结果按 originalIndex 排序
    expect(results[0].toolName).toBe('tool_a');
    expect(results[1].toolName).toBe('tool_b');
  });
});
```

### 3.3 context-injector.service.ts

- 完整实现详见 [08-context-injection.md](./08-context-injection.md) 第 5 节
- **关键依赖**: `KnowledgeClientService`, `context.types.ts`
- **单测覆盖**:
  - 所有 8 种上下文的独立构建
  - 缓存命中/未命中
  - Token 预算裁剪
  - P0 上下文不被裁剪
  - 缓存失效
  - auto-compaction 触发条件

### 3.4 base-specialist.service.ts

- 完整实现详见 [09-tool-execution.md](./09-tool-execution.md) 第 6 节
- **关键依赖**: `@anthropic-ai/sdk`
- **单测覆盖**:
  - Mini-loop 正常完成（1轮无工具调用）
  - Mini-loop 有工具调用（2轮）
  - 达到 maxTurns 强制终止
  - API 错误处理
  - Token 追踪回调

### 3.5 交付标准

- 所有基础设施组件可以独立运行单测
- 不依赖具体的 Specialist Agent 实现
- 使用 mock 的 Claude API 进行测试

## 4. Phase 3: 专家 Agent (Week 2-3)

### 4.1 文件结构

```
packages/services/conversation-service/src/infrastructure/agents/
├── specialists/
│   ├── policy-expert.service.ts        # 政策专家
│   ├── assessment-expert.service.ts    # 评估专家
│   ├── strategist.service.ts           # 策略顾问
│   ├── objection-handler.service.ts    # 异议处理
│   ├── case-analyst.service.ts         # 案例分析
│   └── memory-manager.service.ts       # 记忆管理
├── prompts/
│   ├── coordinator-system-prompt.ts    # Phase 4
│   ├── policy-expert-prompt.ts
│   ├── assessment-expert-prompt.ts
│   ├── strategist-prompt.ts
│   ├── objection-handler-prompt.ts
│   ├── case-analyst-prompt.ts
│   └── memory-manager-prompt.ts
```

### 4.2 各 Agent 实现计划

| Agent | 继承 | Model | 工具 | 预估代码量 | 优先级 |
|-------|------|-------|------|-----------|--------|
| `PolicyExpertService` | `BaseSpecialistService` | Sonnet | `search_knowledge` | ~120 行 | P0 |
| `AssessmentExpertService` | `BaseSpecialistService` | Sonnet | `search_knowledge`, `get_user_context` | ~200 行 | P0 |
| `MemoryManagerService` | `BaseSpecialistService` | Haiku | `save_user_memory`, `get_user_context` | ~150 行 | P0 |
| `StrategistService` | `BaseSpecialistService` | Sonnet | `get_user_context` | ~100 行 | P1 |
| `ObjectionHandlerService` | `BaseSpecialistService` | Sonnet | `search_knowledge`, `get_user_context` | ~120 行 | P1 |
| `CaseAnalystService` | `BaseSpecialistService` | Haiku | `search_knowledge`, `get_user_context` | ~100 行 | P2 |

### 4.3 开发顺序

建议按以下顺序开发（优先级 + 依赖关系）：

```
1. MemoryManagerService     → 最简单，验证 BaseSpecialist + 工具执行
   ↓
2. PolicyExpertService      → 最常用，验证 knowledge-service 集成
   ↓
3. AssessmentExpertService  → 核心业务，需要 knowledge + 用户上下文
   ↓
4. StrategistService        → 辅助 Coordinator 决策
   ↓
5. ObjectionHandlerService  → 异议处理，依赖 knowledge
   ↓
6. CaseAnalystService       → 最后实现，依赖度最低
```

### 4.4 每个 Agent 的独立测试策略

```typescript
// 以 PolicyExpertService 为例的独立测试

describe('PolicyExpertService', () => {
  let service: PolicyExpertService;
  let mockAnthropicClient: jest.Mocked<Anthropic>;
  let mockKnowledgeClient: jest.Mocked<KnowledgeClientService>;

  beforeEach(() => {
    mockAnthropicClient = createMockAnthropicClient();
    mockKnowledgeClient = createMockKnowledgeClient();
    service = new PolicyExpertService(mockAnthropicClient, mockKnowledgeClient);
  });

  it('should answer policy questions without tool calls', async () => {
    // Mock: Claude 直接回答，不调用工具
    mockAnthropicClient.messages.create.mockResolvedValue({
      content: [{ type: 'text', text: '高才通B类要求...' }],
      usage: { input_tokens: 500, output_tokens: 200 },
      stop_reason: 'end_turn',
    });

    const result = await service.execute({
      input: { query: '高才通B类条件是什么' },
      maxTurns: 3,
    });

    expect(result.output).toContain('高才通');
    expect(result.turnsUsed).toBe(1);
  });

  it('should use search_knowledge tool when needed', async () => {
    // Mock: Claude 调用 search_knowledge，再用结果生成回答
    mockAnthropicClient.messages.create
      .mockResolvedValueOnce({
        content: [
          { type: 'tool_use', id: 't1', name: 'search_knowledge', input: { query: 'TTPS B类 条件' } },
        ],
        usage: { input_tokens: 500, output_tokens: 100 },
        stop_reason: 'tool_use',
      })
      .mockResolvedValueOnce({
        content: [{ type: 'text', text: '根据查询结果，高才通B类...' }],
        usage: { input_tokens: 800, output_tokens: 300 },
        stop_reason: 'end_turn',
      });

    mockKnowledgeClient.retrieveKnowledge.mockResolvedValue({
      content: '高才通B类要求全球百强大学学士学位...',
      sources: [{ articleId: '1', title: '高才通指南', similarity: 0.92 }],
    });

    const result = await service.execute({
      input: { query: '高才通B类条件' },
      maxTurns: 3,
      onToolCall: jest.fn(),
    });

    expect(result.output).toContain('根据查询结果');
    expect(result.turnsUsed).toBe(2);
    expect(mockKnowledgeClient.retrieveKnowledge).toHaveBeenCalled();
  });
});
```

### 4.5 交付标准

- 每个 Agent 有独立的单元测试（mock Claude API + mock 外部服务）
- 每个 Agent 的 Prompt 是独立文件，可以独立调整
- 所有 Agent 通过 `BaseSpecialistService.execute()` 统一调用

## 5. Phase 4: Coordinator (Week 3)

### 5.1 文件结构

```
packages/services/conversation-service/src/infrastructure/agents/
├── coordinator/
│   ├── coordinator-agent.service.ts    # 主服务
│   ├── agent-loop.ts                   # 核心递归循环
│   └── state-extractor.ts             # 从回复中提取 consulting_state
├── prompts/
│   └── coordinator-system-prompt.ts    # 500+ 行 Prompt
```

### 5.2 coordinator-system-prompt.ts

这是整个系统最重要的文件，详见 [11-prompt-templates.md](./11-prompt-templates.md)。

关键结构：
```typescript
export function buildCoordinatorSystemPrompt(config: {
  expertContact: { wechat: string; phone: string; workingHours: string };
  paidServices: { assessmentPrice: number; description: string };
  currentDate: string;
}): string {
  return `
# 身份定义
...（约 30 行）

# 你的专家团队
...（约 80 行）

# 六大移民类别
...（约 200 行）

# 对话策略
...（约 100 行）

# 回复规范
...（约 40 行）

# 状态报告格式
...（约 30 行）

# 业务规则
...（约 20 行）
  `;
}
```

### 5.3 agent-loop.ts

核心递归循环，详见 [01-coordinator-agent.md](./01-coordinator-agent.md) 第 4 节。

关键特性：
- `async function* agentLoop()`: AsyncGenerator 模式
- 递归调用自身（tool_results → 再次调用 Claude）
- 集成 ContextInjector
- 集成 ToolExecutionQueue
- 集成 state extractor
- abort 信号支持

### 5.4 coordinator-agent.service.ts

NestJS 服务，封装 agent-loop，对外暴露与旧 `ClaudeAgentServiceV2` 相同的接口：

```typescript
@Injectable()
export class CoordinatorAgentService {
  constructor(
    private contextInjector: ContextInjectorService,
    private toolExecutionQueue: ToolExecutionQueue,
    // ... 各 Specialist Agent
  ) {}

  async *sendMessage(params: {
    conversationContext: ConversationContext;
    userMessage: string;
    attachments?: FileAttachment[];
    userId: string;
    conversationId: string;
    deviceInfo?: DeviceInfo;
  }): AsyncGenerator<StreamEvent> {
    // 委托给 agentLoop
    yield* agentLoop({
      messages: this.buildMessages(params),
      systemPrompt: this.buildSystemPrompt(),
      tools: this.toolExecutionQueue.getClaudeTools(),
      maxTurns: 15,
      maxBudgetUsd: 0.50,
      conversationId: params.conversationId,
      userId: params.userId,
    });
  }
}
```

### 5.5 交付标准

- Coordinator 可以独立运行集成测试（使用真实 Claude API）
- agent-loop 有完整的单元测试（mock API）
- System Prompt 经过人工审查
- 通过 5 个核心对话场景的 E2E 测试

## 6. Phase 5: 集成 (Week 4 前半)

### 6.1 NestJS Module 集成

**新增 agents.module.ts**：
```typescript
// packages/services/conversation-service/src/infrastructure/agents/agents.module.ts

@Module({
  imports: [KnowledgeModule],  // 依赖 KnowledgeClientService
  providers: [
    // Core
    ToolExecutionQueue,
    ContextInjectorService,
    // Specialists
    PolicyExpertService,
    AssessmentExpertService,
    StrategistService,
    ObjectionHandlerService,
    CaseAnalystService,
    MemoryManagerService,
    // Coordinator
    CoordinatorAgentService,
  ],
  exports: [CoordinatorAgentService],
})
export class AgentsModule {}
```

**修改 claude.module.ts**：
```typescript
// 在 claude.module.ts 中导入 AgentsModule
@Module({
  imports: [AgentsModule],  // 新增
  providers: [
    ClaudeAgentServiceV2,  // 保留旧服务（过渡期）
    // ...
  ],
  exports: [
    ClaudeAgentServiceV2,      // 保留旧导出
    CoordinatorAgentService,   // 新增导出
  ],
})
export class ClaudeModule {}
```

**修改 conversation.service.ts**：
```typescript
// 切换注入（使用 feature flag）
@Injectable()
export class ConversationService {
  constructor(
    @Inject(CONVERSATION_REPOSITORY)
    private readonly conversationRepo: IConversationRepository,
    @Inject(MESSAGE_REPOSITORY)
    private readonly messageRepo: IMessageRepository,
    // 旧服务（过渡期保留）
    private readonly claudeAgentService: ClaudeAgentServiceV2,
    // 新服务
    private readonly coordinatorAgentService: CoordinatorAgentService,
    private readonly configService: ConfigService,
  ) {}

  private get useNewArchitecture(): boolean {
    return this.configService.get<boolean>('USE_MULTI_AGENT', false);
  }

  async *sendMessage(params: SendMessageParams): AsyncGenerator<StreamChunk> {
    if (this.useNewArchitecture) {
      yield* this.sendMessageV3(params);  // 新架构
    } else {
      yield* this.sendMessageV2(params);  // 旧架构
    }
  }
}
```

**更新 conversation.gateway.ts**：
```typescript
// 新增 Agent 相关的 WebSocket 事件
// stream_chunk 保持不变
// 新增:
//   agent_start  { agentName, conversationId }
//   agent_progress { agentName, turn, maxTurns, conversationId }
//   agent_complete { agentName, durationMs, conversationId }
```

### 6.2 Feature Flag 策略

```
环境变量: USE_MULTI_AGENT=true/false

开发环境: true  (直接使用新架构)
测试环境: true  (测试新架构)
生产环境: false (等全部测试通过后切换)
```

### 6.3 共享类型更新

```typescript
// packages/shared/types/src/conversation.ts
// 新增 StreamEvent 类型供前端使用

export interface AgentStatusEvent {
  type: 'agent_start' | 'agent_progress' | 'agent_complete';
  agentName: string;
  conversationId: string;
  // agent_progress only
  turn?: number;
  maxTurns?: number;
  // agent_complete only
  durationMs?: number;
}
```

### 6.4 交付标准

- Feature flag 可以在不重启服务的情况下切换
- 旧架构在 `USE_MULTI_AGENT=false` 时完全不受影响
- WebSocket 事件向后兼容（新事件是追加的，不修改已有事件）

## 7. Phase 6: 前端 (Week 4 后半)

### 7.1 前端文件修改

```
packages/clients/web-client/src/
├── stores/
│   └── chatStore.ts            # 新增 agentStatus 状态
├── components/
│   ├── chat/
│   │   ├── ChatWindow.tsx      # 处理新的 WebSocket 事件
│   │   ├── MessageBubble.tsx   # 可能需要微调
│   │   └── AgentStatus.tsx     # 新增：Agent 工作状态组件
│   └── shared/
│       └── AgentBadge.tsx      # 新增：Agent 名称+状态徽章
```

### 7.2 chatStore 更新

```typescript
// chatStore.ts (Zustand)

interface AgentStatus {
  name: string;
  displayName: string;       // 中文显示名
  status: 'idle' | 'working' | 'completed';
  startedAt?: number;
  completedAt?: number;
  durationMs?: number;
}

interface ChatState {
  // 已有状态...
  messages: Message[];
  isStreaming: boolean;

  // 新增：Agent 状态
  activeAgents: AgentStatus[];
  agentHistory: AgentStatus[];  // 本次对话中所有 Agent 调用记录
}

// Agent 名称映射
const AGENT_DISPLAY_NAMES: Record<string, string> = {
  policy_expert: '政策专家',
  assessment_expert: '评估专家',
  strategist: '策略顾问',
  objection_handler: '异议处理',
  case_analyst: '案例分析',
  memory_manager: '记忆管理',
};
```

### 7.3 AgentStatus 组件

```tsx
// AgentStatus.tsx
// 显示在聊天窗口中，消息气泡和输入框之间

function AgentStatus({ agents }: { agents: AgentStatus[] }) {
  const workingAgents = agents.filter(a => a.status === 'working');

  if (workingAgents.length === 0) return null;

  return (
    <div className="agent-status-bar">
      {workingAgents.map(agent => (
        <div key={agent.name} className="agent-badge working">
          <span className="agent-icon">🔄</span>
          <span className="agent-name">{agent.displayName}</span>
          <span className="agent-time">
            {formatElapsedTime(Date.now() - (agent.startedAt || 0))}
          </span>
        </div>
      ))}
      <span className="agent-hint">正在分析中...</span>
    </div>
  );
}
```

### 7.4 ChatWindow 事件处理

```typescript
// ChatWindow.tsx - WebSocket 事件处理更新

socket.on('agent_start', (data: { agentName: string; conversationId: string }) => {
  chatStore.addActiveAgent({
    name: data.agentName,
    displayName: AGENT_DISPLAY_NAMES[data.agentName] || data.agentName,
    status: 'working',
    startedAt: Date.now(),
  });
});

socket.on('agent_complete', (data: { agentName: string; durationMs: number }) => {
  chatStore.completeAgent(data.agentName, data.durationMs);
});

socket.on('stream_end', () => {
  chatStore.clearActiveAgents();  // 清除所有工作中的 Agent 状态
});
```

### 7.5 交付标准

- Agent 状态在 UI 中实时显示
- Agent 完成后自动消失（带淡出动画）
- 在弱网环境下不会出现 Agent 状态 "卡住" 的问题（超时自动清除）
- 旧架构模式下不显示 Agent 状态

## 8. Phase 7: 测试 + 优化 + 清理 (Week 5)

### 8.1 测试场景矩阵

| 场景编号 | 场景描述 | 涉及 Agent | 预期行为 |
|----------|---------|-----------|---------|
| S01 | 新用户首次咨询 | Coordinator + Memory | 破冰 → 收集信息 → 保存记忆 |
| S02 | 询问高才通条件 | Coordinator + Policy | 检索知识库 → 准确回答 |
| S03 | 信息收集后评估 | Coordinator + Assessment + Memory | 评估资格 → 推荐方案 |
| S04 | 用户表示犹豫 | Coordinator + Objection + Strategist | 识别异议 → 策略回应 |
| S05 | 用户要求付费评估 | Coordinator + (Payment tool) | 生成支付链接 |
| S06 | 老用户回访 | Coordinator + Memory | 加载历史记忆 → 个性化问候 |
| S07 | 并发工具调用 | Coordinator + Policy + Case | 并行执行两个 Agent |
| S08 | 超长对话 (30+ 轮) | All | Auto-compaction 触发 |
| S09 | API 错误恢复 | Coordinator | 降级到 Haiku / 友好错误 |
| S10 | 用户中途取消 | Coordinator | AbortSignal 生效 |

### 8.2 性能优化清单

| 优化项 | 目标 | 方法 |
|--------|------|------|
| 首次回复延迟 | < 3s | Prompt Caching + 预热 |
| 并发 Agent 延迟 | < 5s (3 个 Agent 并行) | ToolExecutionQueue 并行 |
| Context Injection 延迟 | < 200ms | 缓存 + 并行获取 |
| Auto-compaction 延迟 | < 2s | Haiku 摘要 |
| Token 成本 (每对话) | < $0.30 | Haiku for 辅助 Agent + Caching |
| 内存使用 | < 100MB per 1000 并发对话 | 对话结束清理缓存 |

### 8.3 旧代码清理计划

**阶段 A: 标记废弃 (Week 5)**
```typescript
// 不删除代码，只标记 @deprecated
/** @deprecated Use CoordinatorAgentService instead. Will be removed in v4. */
export class ClaudeAgentServiceV2 { ... }

/** @deprecated Replaced by Coordinator Prompt. */
export class StrategyEngineService { ... }

/** @deprecated Intent classification now handled by LLM. */
export const intentClassifier = { ... };

/** @deprecated Response quality now handled by Prompt. */
export const responseGate = { ... };
```

**阶段 B: 删除代码 (Week 6+, after 1 week in production)**
- 删除 `strategy-engine.service.ts`
- 删除 `intent-classifier.ts`
- 删除 `response-gate.ts`
- 删除 `default-strategy.ts`
- 删除 `claude-agent-v2.service.ts`
- 移除 feature flag

### 8.4 Rollback 计划

```
如果新架构在生产中出现严重问题：

1. 即时回滚 (< 1 分钟):
   设置环境变量 USE_MULTI_AGENT=false
   → 自动切回 ClaudeAgentServiceV2
   → 不需要重新部署

2. 部署回滚 (< 5 分钟):
   git revert 到 Phase 5 之前的 commit
   → 重新部署 conversation-service

3. 数据恢复:
   新架构不修改数据库 schema
   ConsultingState 格式向后兼容
   → 无需数据迁移
```

## 9. 组件依赖图

```
                              ┌─────────────────┐
                              │   agents.module  │
                              └────────┬────────┘
                                       │ exports
                          ┌────────────▼────────────┐
                          │ CoordinatorAgentService  │
                          └────────────┬────────────┘
                                       │ depends on
                    ┌──────────────────┼──────────────────┐
                    │                  │                   │
          ┌────────▼───────┐ ┌────────▼────────┐ ┌───────▼────────┐
          │ ContextInjector │ │ ToolExecution   │ │ agentLoop()    │
          │ Service         │ │ Queue           │ │ (function)     │
          └────────┬───────┘ └────────┬────────┘ └───────┬────────┘
                   │                  │                   │
          ┌────────▼───────┐ ┌────────▼────────┐         │
          │ Knowledge      │ │ Agent Executors  │         │
          │ ClientService  │ │ (factory)        │         │
          └────────────────┘ └────────┬────────┘         │
                                      │                   │
                              ┌───────▼───────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │ BaseSpecialist     │
                    │ Service (abstract) │
                    └─────────┬─────────┘
                              │ extends
          ┌───────┬───────┬───┴───┬───────┬───────┐
          │       │       │       │       │       │
        Policy  Assess  Strat  Object  Case   Memory
        Expert  Expert  gist   Handler  Analyst Manager
```

## 10. 风险与缓解

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| Coordinator Prompt 效果不佳 | 高 | 高 | Phase 4 投入大量时间测试 Prompt，准备多个版本 A/B 测试 |
| Token 成本超预期 | 中 | 中 | 监控每次对话成本，设置 maxBudgetUsd 硬上限 |
| 并发 Agent 导致 Rate Limit | 中 | 中 | 实现指数退避重试，降级到 Haiku |
| Context Window 不够用 | 低 | 高 | Auto-compaction + 严格的 token 预算 |
| 前端 Agent 状态同步问题 | 中 | 低 | WebSocket 事件超时自动清理 |
| 旧代码删除导致回归 | 低 | 高 | Feature flag 过渡期，完善的回滚计划 |

## 11. 交付 Checklist

### Phase 1 Checklist
- [ ] 12 份架构文档全部完成
- [ ] `agent.types.ts` 通过类型检查
- [ ] `stream.types.ts` 通过类型检查
- [ ] `context.types.ts` 通过类型检查
- [ ] 所有类型有 JSDoc 注释

### Phase 2 Checklist
- [ ] `ToolExecutionQueue` 通过所有单元测试
- [ ] `ContextInjectorService` 通过所有单元测试
- [ ] `BaseSpecialistService` 通过所有单元测试
- [ ] 所有组件可以独立测试（不依赖 Claude API）

### Phase 3 Checklist
- [ ] 6 个 Specialist Agent 全部实现
- [ ] 6 份 Prompt 文件全部编写
- [ ] 每个 Agent 有独立的单元测试
- [ ] 每个 Agent 使用真实 API 的集成测试（可选，按需运行）

### Phase 4 Checklist
- [ ] Coordinator System Prompt 完成（500+ 行）
- [ ] agent-loop 通过所有单元测试
- [ ] CoordinatorAgentService 通过集成测试
- [ ] 5 个核心场景 E2E 测试通过

### Phase 5 Checklist
- [ ] `agents.module.ts` 编写完成
- [ ] Feature flag 切换工作正常
- [ ] 旧架构在 flag=false 时不受影响
- [ ] WebSocket 事件向后兼容

### Phase 6 Checklist
- [ ] chatStore 更新完成
- [ ] AgentStatus 组件实现
- [ ] ChatWindow 处理新事件
- [ ] 前端无 regression

### Phase 7 Checklist
- [ ] 10 个测试场景全部通过
- [ ] 性能指标达标
- [ ] 旧代码标记 @deprecated
- [ ] 回滚计划验证通过
- [ ] 文档更新完成