# iConsulting Agent 能力评估报告

> 本报告通过代码分析，评估 iConsulting 系统的 Agent 成熟度级别

---

## 评估结论

**当前定位：初级 Agent（Level 2）**

iConsulting 已具备 Agent 的基础架构，但核心功能尚未完全实现。系统设计理念超前，架构合理，但当前主要以 LLM + 工具定义 的形式运行，距离**全能咨询 Agent** 还有差距。

---

## 评估维度与得分

| 维度 | 满分 | 得分 | 成熟度 |
|------|------|------|--------|
| Tool Use（工具调用） | 20 | 14 | 70% |
| Memory（记忆系统） | 20 | 12 | 60% |
| RAG（知识增强） | 20 | 10 | 50% |
| Planning（规划能力） | 20 | 4 | 20% |
| Self-Evolution（自我进化） | 20 | 8 | 40% |
| **总分** | **100** | **48** | **Level 2** |

### 等级说明

| Level | 名称 | 分数范围 | 特征 |
|-------|------|----------|------|
| Level 0 | 纯 LLM | 0-20 | 仅有对话能力，无工具、无记忆 |
| Level 1 | LLM + RAG | 20-40 | 有知识检索增强 |
| **Level 2** | **初级 Agent** | **40-60** | **有工具定义，部分实现** |
| Level 3 | 标准 Agent | 60-80 | 工具链完整，有记忆和规划 |
| Level 4 | 高级 Agent | 80-90 | 多 Agent 协作，自我进化 |
| Level 5 | 全能 Agent | 90-100 | 完全自主，持续学习 |

---

## 详细分析

### 1. Tool Use（工具调用）- 14/20

**代码位置**: [immigration-tools.service.ts](../packages/services/conversation-service/src/infrastructure/claude/tools/immigration-tools.service.ts)

#### 已实现 ✅

```typescript
// 定义了 5 个工具
getTools(): Tool[] {
  return [
    { name: 'search_knowledge', ... },      // RAG 搜索
    { name: 'check_off_topic', ... },       // 离题检测
    { name: 'collect_assessment_info', ... }, // 信息收集
    { name: 'generate_payment', ... },      // 支付生成
    { name: 'save_user_memory', ... },      // 记忆保存
  ];
}
```

**代码位置**: [claude-agent.service.ts:187-338](../packages/services/conversation-service/src/infrastructure/claude/claude-agent.service.ts#L187)

```typescript
// 工具循环实现
const maxIterations = 10; // 安全限制
while (iterations < maxIterations) {
  // 1. 调用 Claude API（含 tools 参数）
  // 2. 处理 tool_use 事件
  // 3. 执行工具并返回 tool_result
  // 4. 继续循环直到无工具调用
}
```

#### 未完成 ⚠️

```typescript
// immigration-tools.service.ts:185-202
private async searchKnowledge(input: Record<string, unknown>): Promise<unknown> {
  // TODO: Implement actual RAG search via Knowledge Service
  return {
    success: true,
    results: [...],
    message: '知识库搜索功能即将上线，目前请基于内置知识回答', // 占位符
  };
}
```

**问题**：
- 5 个工具中 4 个返回占位符数据
- 工具执行结果未真正影响对话
- 缺少外部 API 调用能力（网络搜索、入境处官网查询等）

---

### 2. Memory（记忆系统）- 12/20

**代码位置**: [memory.service.ts](../packages/services/knowledge-service/src/memory/memory.service.ts)

#### 已实现 ✅

```typescript
// 用户记忆保存（带向量化）
async saveUserMemory(params: {
  userId: string;
  memoryType: MemoryType;  // FACT | PREFERENCE | INTENT
  content: string;
  importance?: number;
}): Promise<UserMemoryEntity> {
  const memory = UserMemoryEntity.create(params);

  // 生成向量
  const embedding = await this.embeddingService.getEmbedding(params.content);
  memory.setEmbedding(embedding);

  // 保存到 PostgreSQL
  await this.memoryRepo.save(memory);

  // 记录到 Neo4j 时间线
  await this.neo4jService.recordUserEvent({...});
}
```

**代码位置**: [neo4j.service.ts](../packages/services/knowledge-service/src/infrastructure/database/neo4j/neo4j.service.ts)

```typescript
// Neo4j 时间线实现
async recordUserEvent(params: {
  userId: string;
  eventId: string;
  eventType: string;
  content: string;
}): Promise<void> {
  // 创建事件节点
  // 建立 HAS_EVENT 关系
  // 建立 FOLLOWED_BY 时序关系
}
```

#### 未完成 ⚠️

```typescript
// conversation-service 中的 save_user_memory 工具
private async saveUserMemory(...): Promise<unknown> {
  console.log(`[Memory] User ${context.userId} - Type: ${memoryType}, Content: ${content}`);
  // TODO: Save to Neo4j via Knowledge Service  ← 未实际调用 knowledge-service
  return { success: true, memoryId: `MEM_${Date.now()}` };
}
```

**问题**：
- conversation-service 未真正调用 knowledge-service 的记忆 API
- 短期记忆（对话历史）限于 `previousMessages` 数组
- 缺少记忆检索并注入到上下文的完整流程

---

### 3. RAG（知识增强）- 10/20

**代码位置**: [rag.service.ts](../packages/services/knowledge-service/src/application/services/rag.service.ts)

#### 已实现 ✅

```typescript
// RAG 检索实现
async retrieve(params: {
  query: string;
  userId?: string;
  category?: string;
}): Promise<RAGResult> {
  // 1. 生成查询向量
  const queryEmbedding = await this.embeddingService.getEmbedding(query);

  // 2. 并行检索（知识块 + 用户记忆 + 系统经验）
  const [chunkResults, memoryResults, experienceResults] = await Promise.all([
    this.knowledgeRepo.searchChunksByVector(queryEmbedding, {...}),
    this.memoryRepo.searchByVector(userId, queryEmbedding, {...}),
    this.experienceRepo.searchByVector(queryEmbedding, {...}),
  ]);

  // 3. 格式化并返回
  return { content, sources, userMemories, systemExperiences };
}
```

**代码位置**: [embedding.service.ts](../packages/services/knowledge-service/src/infrastructure/embedding/embedding.service.ts)

```typescript
// 向量化服务
async getEmbedding(text: string): Promise<number[]> {
  if (!this.openai) {
    return this.getMockEmbedding(text); // 降级到 Mock
  }
  const response = await this.openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: this.preprocessText(text),
  });
  return response.data[0].embedding;
}
```

#### 未完成 ⚠️

```typescript
// conversation-service 的 search_knowledge 工具
private async searchKnowledge(input): Promise<unknown> {
  // TODO: Implement actual RAG search via Knowledge Service
  return {
    message: '知识库搜索功能即将上线，目前请基于内置知识回答',
  };
}
```

**问题**：
- knowledge-service 的 RAG 逻辑完整，但未被 conversation-service 调用
- 知识库无实际数据（需要管理员导入）
- Claude 依赖内置知识而非 RAG 增强

---

### 4. Planning（规划能力）- 4/20

#### 已实现 ✅

```typescript
// 工具循环可视为最基础的"规划"
const maxIterations = 10;
while (iterations < maxIterations) {
  // Claude 自主决定是否调用工具
  // 执行后继续对话
}
```

#### 未实现 ❌

**缺少的 Agent 规划能力**：

| 能力 | 说明 | 状态 |
|------|------|------|
| 任务分解 | 将复杂咨询分解为子任务 | ❌ |
| 多步骤规划 | 制定咨询流程计划 | ❌ |
| 条件分支 | 根据用户情况选择不同路径 | ❌ |
| 自我反思 | 评估回答质量并改进 | ❌ |
| 目标追踪 | 追踪咨询目标完成度 | ❌ |

**典型 Agent 规划示例（当前未实现）**：

```
用户: "我想移民香港"

Agent 规划:
1. [了解背景] 询问年龄、学历、工作经验
2. [初步评估] 分析适合的移民类别
3. [详细分析] 针对最匹配类别深入咨询
4. [引导转化] 推荐付费评估服务
5. [持续跟进] 记录用户意向，后续关怀
```

---

### 5. Self-Evolution（自我进化）- 8/20

**代码位置**: [experience-extractor.service.ts](../packages/services/evolution-service/src/infrastructure/claude/experience-extractor.service.ts)

#### 已实现 ✅

```typescript
// 经验提取提示词设计
async analyzeConversation(params: {
  messages: Array<{ role: 'user' | 'assistant'; content: string }>;
  hasConverted: boolean;
  rating?: number;
}): Promise<ConversationAnalysis> {
  const prompt = `你是一个专门分析香港移民咨询对话的AI专家...
    提取:
    - experiences (系统经验)
    - userInsights (用户洞察)
    - knowledgeGaps (知识缺口)
    - conversionSignals (转化信号)
  `;

  const response = await this.client.messages.create({...});
  return this.parseAnalysisResult(response);
}
```

**代码位置**: [evolution.service.ts](../packages/services/evolution-service/src/evolution/evolution.service.ts)

```typescript
// 进化任务执行
async runEvolutionTask(): Promise<EvolutionTaskResult> {
  // 1. 获取已结束的对话
  const conversations = await this.conversationRepo.find({
    where: { status: 'ENDED', messageCount: MoreThan(4) },
  });

  // 2. 分析每个对话
  for (const conversation of conversations) {
    const analysis = await this.experienceExtractor.analyzeConversation({...});

    // 3. 保存提取的经验（带去重）
    for (const exp of analysis.experiences) {
      await this.saveExperience(exp);
    }
  }
}
```

**代码位置**: [system-prompt.ts](../packages/services/conversation-service/src/infrastructure/claude/prompts/system-prompt.ts)

```typescript
// 系统提示词支持动态更新
export const buildSystemPrompt = (config: SystemPromptConfig): string => `
...
## 已积累的经验
${config.accumulatedExperience || '暂无'}

## 管理员特别指示
${config.adminInstructions || '暂无'}
`;
```

#### 未完成 ⚠️

```typescript
// evolution-service 与 conversation-service 未集成
// claude-agent.service.ts 中的 systemPromptConfig 是静态的
this.systemPromptConfig = {
  identity: '专业、友善、耐心的香港移民顾问',
  conversationStyle: '专业但不生硬，用简洁明了的语言解答',
  // accumulatedExperience: ← 未从 evolution-service 获取
  // adminInstructions: ← 未从 evolution-service 获取
};
```

**问题**：
- 经验提取逻辑完整，但未形成闭环
- 提取的经验未自动注入到系统提示词
- 管理员审批后的经验未同步到对话服务
- 缺少定时任务自动执行进化

---

## 架构对比

### 当前架构 vs 理想 Agent 架构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                          当前 iConsulting 架构                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   用户输入 ─────────────────────────────────────────────────────────►       │
│                                                                             │
│   ┌─────────────────────────────────────────────────────────────────┐      │
│   │                    Claude API 调用                               │      │
│   │                                                                 │      │
│   │   System Prompt (静态) + Messages + Tools (定义但未真正执行)    │      │
│   │                           │                                     │      │
│   │                           ▼                                     │      │
│   │                    流式响应输出                                  │      │
│   └─────────────────────────────────────────────────────────────────┘      │
│                                                                             │
│   ◄──────────────────────────────────────────────────────── AI 回复        │
│                                                                             │
│   ❌ 工具执行返回占位符                                                     │
│   ❌ 记忆未持久化                                                           │
│   ❌ RAG 未真正检索                                                         │
│   ❌ 经验未注入提示词                                                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                          理想 Agent 架构                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   用户输入 ──┬──────────────────────────────────────────────────────►       │
│              │                                                              │
│              ▼                                                              │
│   ┌──────────────────┐                                                     │
│   │   Context 构建    │◄─── RAG 检索 (知识库)                              │
│   │                  │◄─── Memory 检索 (用户记忆)                          │
│   │                  │◄─── Experience 检索 (系统经验)                      │
│   └────────┬─────────┘                                                     │
│            │                                                                │
│            ▼                                                                │
│   ┌──────────────────┐                                                     │
│   │   Planning 规划   │  "用户想了解优才，先收集背景信息"                    │
│   └────────┬─────────┘                                                     │
│            │                                                                │
│            ▼                                                                │
│   ┌──────────────────┐      ┌──────────────────┐                          │
│   │   Claude 推理     │─────►│   Tool 执行       │                          │
│   │   (ReAct Loop)   │◄─────│   - search_kb    │                          │
│   │                  │      │   - save_memory  │                          │
│   │                  │      │   - generate_pay │                          │
│   └────────┬─────────┘      └──────────────────┘                          │
│            │                                                                │
│            ▼                                                                │
│   ┌──────────────────┐                                                     │
│   │   Self-Reflect    │  "回答是否完整？需要补充什么？"                      │
│   └────────┬─────────┘                                                     │
│            │                                                                │
│            ▼                                                                │
│   ◄──────────────────────────────────────────────────────── AI 回复        │
│                                                                             │
│            │                                                                │
│            ▼                                                                │
│   ┌──────────────────┐                                                     │
│   │   Evolution 学习  │  异步提取经验 → 管理员审批 → 更新系统提示词          │
│   └──────────────────┘                                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 代码证据汇总

### 证明是 Agent（而非纯 LLM）

| 特征 | 代码位置 | 状态 |
|------|----------|------|
| 工具定义 | `immigration-tools.service.ts:19-151` | ✅ 已实现 |
| 工具循环 | `claude-agent.service.ts:187-338` | ✅ 已实现 |
| 记忆实体 | `user-memory.entity.ts` | ✅ 已实现 |
| 向量检索 | `rag.service.ts:53-131` | ✅ 已实现 |
| 经验提取 | `experience-extractor.service.ts:63-93` | ✅ 已实现 |
| 动态提示词 | `system-prompt.ts:12-94` | ✅ 已实现 |

### 证明未完全落地

| 缺陷 | 代码位置 | 证据 |
|------|----------|------|
| RAG 返回占位符 | `immigration-tools.service.ts:189-202` | `TODO: Implement actual RAG search` |
| 记忆未保存 | `immigration-tools.service.ts:319-329` | `TODO: Save to Neo4j` |
| 支付是 Mock | `immigration-tools.service.ts:266-303` | `qrCodeUrl: placeholder...` |
| 服务未集成 | `claude-agent.service.ts:66-70` | 配置是静态的 |
| 进化未运行 | `evolution.service.ts` | 无定时任务触发 |

---

## 升级路线图

### Phase 1: 完成基础 Agent（目标 Level 3: 60分）

| 任务 | 优先级 | 预期得分提升 |
|------|--------|-------------|
| 实现 conversation → knowledge-service RAG 调用 | P0 | +8 |
| 实现 conversation → knowledge-service Memory 调用 | P0 | +6 |
| 实现 evolution → conversation 经验注入 | P1 | +6 |
| 添加定时进化任务 | P1 | +2 |

### Phase 2: 增强 Agent 能力（目标 Level 4: 80分）

| 任务 | 优先级 | 预期得分提升 |
|------|--------|-------------|
| 添加任务规划模块 | P1 | +8 |
| 添加自我反思机制 | P2 | +4 |
| 添加外部 API 工具（入境处官网查询） | P2 | +4 |
| 多轮对话状态管理 | P2 | +4 |

### Phase 3: 高级 Agent（目标 Level 5: 90分）

| 任务 | 优先级 | 预期得分提升 |
|------|--------|-------------|
| Multi-Agent 协作（咨询 Agent + 评估 Agent） | P3 | +6 |
| 自动知识库更新 | P3 | +2 |
| A/B 测试不同提示词策略 | P3 | +2 |

---

## 总结

### iConsulting 当前是什么？

**一个「架构完善但功能未完全实现」的初级 Agent**

- 设计理念：✅ 具备完整 Agent 架构思想
- 工具调用：⚠️ 有定义但执行返回占位符
- 记忆系统：⚠️ 有完整设计但未被调用
- RAG 增强：⚠️ 有完整实现但未集成
- 自我进化：⚠️ 有提取逻辑但未形成闭环
- 规划能力：❌ 基本缺失

### 与竞品对比

| 系统 | 定位 | 特点 |
|------|------|------|
| ChatGPT | Level 0-1 | 纯 LLM，无工具 |
| ChatGPT Plus (GPTs) | Level 2 | 有工具但无记忆 |
| Claude Projects | Level 2-3 | 有知识库但无进化 |
| **iConsulting** | **Level 2** | **架构超前，实现滞后** |
| AutoGPT | Level 3-4 | 完整 Agent 但不稳定 |
| Devin | Level 4-5 | 全能 Agent |

### 最终评价

> iConsulting 是一个**设计优秀但实现不完整**的 Agent 系统。
>
> 它已经具备了成为高级咨询 Agent 的所有架构基础（工具、记忆、RAG、进化），
> 但当前各模块之间的集成尚未完成，实际运行时更接近一个**带有工具定义的 LLM 应用**。
>
> 完成 Phase 1 的集成工作后，系统将真正成为一个可用的 Agent。

---

*报告生成时间：2025-01-22*
*分析基于 iConsulting 代码库 commit: e6e69f1*
