197 lines
7.3 KiB
Markdown
197 lines
7.3 KiB
Markdown
# iConsulting Agent 能力扩展 — P0/P1/P2 实施计划
|
||
|
||
> 生成日期: 2026-02-07
|
||
> 目标：将 iConsulting 从纯咨询 Agent 升级为具备完整业务闭环的智能助手
|
||
|
||
---
|
||
|
||
## 当前状态总结
|
||
|
||
### 已实现 ✅
|
||
- 多 Agent 协调架构 (Coordinator + 6 specialists)
|
||
- 16 个工具 (knowledge search, assessment, memory, web search, etc.)
|
||
- 支付工具 `generate_payment` 已定义但返回 MOCK 数据
|
||
- payment-service 已有完整的 Order/Payment/Adapter 架构（Alipay/WeChat/Stripe adapter 为 mock）
|
||
- WebSocket 已 emit `tool_call` 和 `tool_result` 事件
|
||
- 前端 `ToolCallResult` 组件已识别 `generate_payment` 但只显示占位符
|
||
|
||
### 缺失 ❌
|
||
- conversation-service 没有调用 payment-service 的 HTTP 客户端
|
||
- 没有 `check_payment_status` 工具（Agent 无法查询支付状态）
|
||
- 没有 `query_order_history` 工具（Agent 无法查询用户订单历史）
|
||
- 前端没有安装 `qrcode.react`，无法渲染真实二维码
|
||
- 前端 `tool_call`/`tool_result` WebSocket 事件只 console.log，未处理到消息 metadata
|
||
- 没有发票生成能力
|
||
- 没有前端交互式表单（chat 内嵌表单收集信息）
|
||
|
||
---
|
||
|
||
## P0 — 支付闭环（Payment Closure）
|
||
|
||
### 目标
|
||
Agent 能真正生成支付订单 → 返回支付二维码 → 前端渲染二维码 → Agent 能查询支付状态 → Agent 能查询订单历史
|
||
|
||
### 步骤
|
||
|
||
#### P0-1: PaymentClientService
|
||
**新建** `conversation-service/src/infrastructure/payment/payment-client.service.ts`
|
||
|
||
- 模仿 `KnowledgeClientService` 的 HTTP 客户端模式（使用 native `fetch`）
|
||
- `PAYMENT_SERVICE_URL` 从 ConfigService 读取，默认 `http://payment-service:3002`
|
||
- 方法:
|
||
- `createOrder(params: { userId, serviceType, serviceCategory?, conversationId? })` → 调用 `POST /orders`
|
||
- `createPayment(params: { orderId, method })` → 调用 `POST /payments`
|
||
- `checkPaymentStatus(paymentId: string)` → 调用 `GET /payments/:id/status`
|
||
- `getOrderStatus(orderId: string)` → 调用 `GET /orders/:id/status`
|
||
- `getUserOrders(userId: string)` → 调用 `GET /orders` (header: x-user-id)
|
||
|
||
**新建** `conversation-service/src/infrastructure/payment/payment.module.ts`
|
||
- 提供 `PaymentClientService`，导出供 `AgentsModule` 使用
|
||
|
||
**修改** `agents.module.ts`
|
||
- 导入 `PaymentModule`
|
||
- `ImmigrationToolsService` 构造函数注入 `PaymentClientService`
|
||
|
||
#### P0-2: 重写 generate_payment 工具
|
||
**修改** `immigration-tools.service.ts` 的 `generatePayment()` 方法
|
||
|
||
流程:
|
||
1. 调用 `paymentClient.createOrder(...)` 创建订单
|
||
2. 调用 `paymentClient.createPayment({ orderId, method })` 生成支付
|
||
3. 返回真实的 `{ orderId, paymentId, qrCodeUrl, amount, expiresAt }`
|
||
4. 删除 MOCK 数据
|
||
|
||
#### P0-3: 添加 check_payment_status 工具
|
||
**修改** `immigration-tools.service.ts`:
|
||
- 添加工具定义: `check_payment_status`，输入 `{ orderId }`
|
||
- 添加实现: 调用 `paymentClient.getOrderStatus(orderId)` 返回状态
|
||
|
||
**修改** `coordinator-tools.ts`:
|
||
- 在 `DIRECT_TOOLS` 中添加 `check_payment_status` 工具定义
|
||
- 在 `TOOL_CONCURRENCY_MAP` 中标记为 `true`（只读）
|
||
|
||
#### P0-4: 添加 query_order_history 工具
|
||
**修改** `immigration-tools.service.ts`:
|
||
- 添加工具定义: `query_order_history`，输入 `{ userId }`
|
||
- 添加实现: 调用 `paymentClient.getUserOrders(userId)` 返回订单列表
|
||
|
||
**修改** `coordinator-tools.ts`:
|
||
- 在 `DIRECT_TOOLS` 中添加 `query_order_history` 工具定义
|
||
- 在 `TOOL_CONCURRENCY_MAP` 中标记为 `true`（只读）
|
||
|
||
#### P0-5: 前端 QR 码渲染
|
||
**安装** `qrcode.react` 到 web-client
|
||
|
||
**修改** `MessageBubble.tsx` 的 `ToolCallResult` 组件:
|
||
- 导入 `QRCodeSVG` from `qrcode.react`
|
||
- `generate_payment` 结果中，使用 `<QRCodeSVG value={qrCodeUrl} />` 渲染真实二维码
|
||
- 添加 `check_payment_status` 结果的渲染（状态卡片）
|
||
- 添加 `query_order_history` 结果的渲染（订单列表卡片）
|
||
|
||
#### P0-6: 处理 tool_call/tool_result WebSocket 事件
|
||
**修改** `useChat.ts`:
|
||
- `tool_call` 事件: 存储到临时状态（当前消息正在执行的工具调用）
|
||
- `tool_result` 事件: 将结果收集到 pending toolCalls 数组
|
||
- `stream_end` 事件: 将收集的 toolCalls 注入消息 metadata
|
||
|
||
---
|
||
|
||
## P1 — 信息收集 UX 增强
|
||
|
||
### 目标
|
||
Agent 能在聊天中展示结构化的评估结果卡片，用户能直观看到评分和建议
|
||
|
||
### 步骤
|
||
|
||
#### P1-1: 评估结果卡片组件
|
||
**新建** `web-client/src/features/chat/presentation/components/AssessmentResultCard.tsx`
|
||
|
||
- 针对 `collect_assessment_info` 和 `invoke_assessment_expert` 的工具结果
|
||
- 展示：评估类别、各项得分、总分、建议
|
||
- 使用现有 Tailwind 样式
|
||
- 分数条形图（纯 CSS，不需要 recharts）
|
||
|
||
#### P1-2: 在 ToolCallResult 中集成
|
||
**修改** `MessageBubble.tsx`:
|
||
- 识别 `collect_assessment_info` 工具结果，渲染 `AssessmentResultCard`
|
||
- 识别评估相关结果，渲染评分卡片
|
||
|
||
---
|
||
|
||
## P2 — 财务合规
|
||
|
||
### 目标
|
||
Agent 能查询用户交易记录，支持退款处理（为未来发票功能预留接口）
|
||
|
||
### 步骤
|
||
|
||
#### P2-1: 交易历史查询增强
|
||
**修改** `PaymentClientService`:
|
||
- 添加 `getOrderDetail(orderId)` → 获取含支付详情的完整订单
|
||
|
||
**修改** `immigration-tools.service.ts`:
|
||
- `query_order_history` 工具返回更丰富的信息（支付时间、状态、金额明细）
|
||
|
||
#### P2-2: 退款处理工具
|
||
**修改** `PaymentClientService`:
|
||
- 添加 `requestRefund(orderId, reason)` → 调用 payment-service 退款 API
|
||
|
||
**修改** `immigration-tools.service.ts`:
|
||
- 添加 `request_refund` 工具定义和实现
|
||
- 安全限制：需要确认对话 + 订单在可退款时间窗口内
|
||
|
||
**修改** `coordinator-tools.ts`:
|
||
- 添加 `request_refund` 工具定义
|
||
- `TOOL_CONCURRENCY_MAP` 中标记为 `false`（有副作用）
|
||
|
||
#### P2-3: 前端交易记录展示
|
||
**修改** `MessageBubble.tsx`:
|
||
- 增强 `query_order_history` 的渲染：显示支付方式图标、退款状态
|
||
- 添加 `request_refund` 结果渲染
|
||
|
||
---
|
||
|
||
## 文件变更清单
|
||
|
||
### P0 新建文件 (2)
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `infrastructure/payment/payment-client.service.ts` | Payment-service HTTP 客户端 |
|
||
| `infrastructure/payment/payment.module.ts` | Payment 模块 |
|
||
|
||
### P0 修改文件 (5)
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `agents/agents.module.ts` | +PaymentModule import |
|
||
| `claude/tools/immigration-tools.service.ts` | +PaymentClientService 注入, 重写 generatePayment, +2 新工具 |
|
||
| `agents/tools/coordinator-tools.ts` | +2 新工具定义, +concurrency map |
|
||
| `web-client/.../MessageBubble.tsx` | +QRCodeSVG, +3 工具结果渲染 |
|
||
| `web-client/.../useChat.ts` | +tool_call/tool_result 事件处理 |
|
||
|
||
### P1 新建文件 (1)
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `web-client/.../AssessmentResultCard.tsx` | 评估结果卡片组件 |
|
||
|
||
### P1 修改文件 (1)
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `web-client/.../MessageBubble.tsx` | +评估结果卡片渲染 |
|
||
|
||
### P2 修改文件 (3)
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `infrastructure/payment/payment-client.service.ts` | +getOrderDetail, +requestRefund |
|
||
| `claude/tools/immigration-tools.service.ts` | +request_refund 工具 |
|
||
| `agents/tools/coordinator-tools.ts` | +request_refund 定义 |
|
||
|
||
---
|
||
|
||
## 验证计划
|
||
|
||
每个 P 级别完成后:
|
||
1. `pnpm build` — conversation-service 和 web-client 均编译通过
|
||
2. 详细 commit 备注说明改动内容
|
||
3. `git push` 推送到 remote
|
||
4. 进入下一个 P 级别
|