Почетна Преглед Помоћ
Пријавите Се
zhangyice
/
ax-frontend-app
Прати 1
Волим 0
Креирај огранак 0
Датотеке Дискусије 0 Захтеви за спајање 0 Вики
Дрво: 3ff53beab0
Гране Ознаке
ax-frontend-...
/
docs
/
WORKFLOW_INTEGRATION.md

WORKFLOW_INTEGRATION.md 11 KB
Историја Датотека

工作流集成文档 (Workflow Integration)

概述

本文档描述了外部AI平台工作流与AX文档编辑器前端的集成。通过此集成，用户可以在聊天界面输入自然语言指令（如"生成一个地质报告"），系统会自动触发工作流，生成文档并返回可下载的URL链接。

架构设计

整体流程图

用户输入（聊天）
    ↓
Chat Store (检查是否触发工作流)
    ↓
Workflow Service (调用外部AI平台 v2 API)
    ↓
外部工作流平台 (http://114.242.25.27:3000/api/v2/chat/completions)
    ↓
本地后端 API (http://192.168.0.200:8000/api/v1/export/records)
    ↓
返回导出记录 (Export Record with downloadUrl)
    ↓
在聊天中显示文档卡片
    ↓
用户点击查看/下载文档

核心组件

1. Workflow Service (src/services/workflowService.ts)

作用: 处理与外部工作流API的通信。

关键函数:

shouldTriggerWorkflow(input: string): boolean

判断用户输入是否应该触发文档生成工作流。

触发模式:

  • 生成动作: 生成、创建、制作、编写、generate、create
  • 文档类型: 报告、文档、方案、总结、分析、report、document、doc

示例:

shouldTriggerWorkflow("生成一个地质报告") // true
shouldTriggerWorkflow("创建技术文档")     // true
shouldTriggerWorkflow("你好")           // false

triggerDocumentWorkflow(userInput: string, chatId: string)

调用工作流API生成文档并返回导出记录。

API端点:

POST http://114.242.25.27:3000/api/v2/chat/completions

请求头:

Content-Type: application/json
Authorization: Bearer XAgent-mWHBqQw06psUYRqx6PrHWiKdfY05ebt7I9drDBHzaG9QQesIkVEICj

请求体:

{
  "chatId": "session-uuid",
  "stream": false,
  "detail": false,
  "messages": [
    {
      "role": "user",
      "content": "生成一个地质报告"
    }
  ]
}

响应格式:

{
  "content": "已为您生成地质报告",
  "exportRecord": {
    "recordId": "rec-e22bbf07350d",
    "userId": "default-user",
    "fileName": "地质报告_1782369497876.doc",
    "fileSize": 39076,
    "downloadUrl": "http://192.168.0.200:8000/api/v1/export/records/rec-e22bbf07350d/download?userId=default-user",
    "documentId": "doc-d2ef5b701b5c",
    "styleId": "default",
    "createdAt": 1782369497764
  }
}

或者数组格式：

{
  "content": "已为您生成地质报告",
  "records": [
    {
      "recordId": "rec-e22bbf07350d",
      ...
    }
  ]
}

2. Chat Store (src/stores/chatStore.ts)

修改内容:

导入工作流服务

import { shouldTriggerWorkflow, triggerDocumentWorkflow } from '../services/workflowService';

修改 sendMessage 函数

// 检查是否需要触发工作流
const shouldUseWorkflow = shouldTriggerWorkflow(content);

if (shouldUseWorkflow) {
  // 使用工作流生成文档
  const workflowResult = await triggerDocumentWorkflow(content, sessionId);
  aiResponse = workflowResult.content;
  exportRecord = workflowResult.exportRecord;
} else {
  // 使用常规AI服务
  const aiResult = await getAIResponse(content, sessionId, get().messages);
  aiResponse = aiResult.response;
}

// 创建AI消息并附加导出记录
const aiMessage: ChatMessage = {
  id: uuidv4(),
  role: 'assistant',
  content: aiResponse,
  timestamp: Date.now(),
  exportRecord: exportRecord, // 附加导出记录
};

3. Message Item Component (src/components/ChatPanel/MessageItem.tsx)

功能: 已有支持渲染导出记录为可点击文档卡片。

当消息中包含 exportRecord 时，会显示一个文档卡片：

  • Word图标
  • 文件名
  • "点击预览文档"文本
  • 眼睛图标

用户点击卡片会触发 onDocumentClick 回调。

4. App Component (src/App.tsx)

功能: 处理文档点击事件，在编辑器中打开文档。

const handleDocumentClick = useCallback((exportRecord: ExportRecordInfo) => {
  setPreviewDocument({
    downloadUrl: exportRecord.downloadUrl,
    fileName: exportRecord.fileName,
    recordId: exportRecord.recordId,
    userId: exportRecord.userId,
    documentId: exportRecord.documentId,
  });
  setPreviewMode('editor');
}, []);

配置

环境变量

在 .env 文件中添加：

# 工作流API配置
# 工作流API URL（v2 - 带工作流）
VITE_WORKFLOW_API_URL=http://114.242.25.27:3000/api/v2/chat/completions

# 工作流API密钥
VITE_WORKFLOW_API_KEY=XAgent-mWHBqQw06psUYRqx6PrHWiKdfY05ebt7I9drDBHzaG9QQesIkVEICj

在 .env.example 文件中添加（示例）：

# 工作流API配置
VITE_WORKFLOW_API_URL=http://114.242.25.27:3000/api/v2/chat/completions
VITE_WORKFLOW_API_KEY=your_workflow_api_key_here

使用方法

终端用户使用

  1. 打开聊天面板

  2. 输入文档生成请求，例如：

    • "生成一个地质报告"
    • "创建技术文档"
    • "制作项目分析报告"

  3. 系统自动处理：

    • 检测到文档生成请求
    • 触发工作流
    • 调用外部AI平台
    • 生成文档
    • 返回导出记录

  4. 查看结果：

    • AI回复消息
    • 文档卡片出现在消息下方
    • 显示文件名和预览按钮

  5. 点击文档卡片：

    • 在编辑器中打开文档
    • 或在新标签页下载文档

触发条件示例

✅ 会触发工作流:

  • "生成一个地质报告"
  • "创建技术文档"
  • "制作项目分析报告"
  • "编写总结文档"
  • "generate a report"

❌ 不会触发工作流:

  • "你好" (无生成动作或文档类型)
  • "生成图片" (无文档类型关键词)
  • "打开文档" (无生成动作)
  • "分析一下数据" (无生成动作)

错误处理

优雅降级

工作流集成设计为优雅降级：

  1. API密钥未配置:

    • 跳过工作流
    • 控制台警告
    • 返回提示消息

  2. 工作流API调用失败:

    • 错误记录到控制台
    • 返回错误消息给用户
    • 不中断聊天体验

  3. 工作流未返回导出记录:

    • 控制台警告
    • 显示AI响应
    • 不显示文档卡片

调试日志

在浏览器控制台可以看到工作流执行日志：

  • 🔄 Using workflow for document generation - 开始使用工作流
  • 🔄 Triggering document generation workflow... - 触发工作流
  • 📝 User input: 生成一个地质报告 - 用户输入
  • ✅ Workflow response received: - 收到工作流响应
  • 📄 Export record extracted: - 提取导出记录
  • ⚠️ No export record found in workflow response - 未找到导出记录
  • ❌ Workflow API error: - 工作流API错误

测试

手动测试步骤

  1. 启动开发服务器:

    cd d:\work space\ax-shell\ax-frontend-app
npm run dev

  2. 打开应用: 浏览器访问 http://localhost:5173

  3. 创建新会话: 点击聊天面板

  4. 输入文档生成请求:

    生成一个地质报告

  5. 验证工作流:

    • 检查浏览器控制台日志
    • 等待AI响应
    • 查看消息下方的文档卡片
    • 验证文件名显示正确

  6. 测试文档下载:

    • 点击文档卡片
    • 文档应在编辑器中打开
    • 或在新标签页下载

预期行为

  1. 用户输入："生成一个地质报告"
  2. 聊天显示加载指示器
  3. 工作流在后台触发
  4. AI响应显示
  5. 文档卡片出现，显示：
    • 文件图标
    • 文件名（例如："地质报告_1782369497876.doc"）
    • "点击预览文档"文本
  6. 点击卡片在编辑器中打开文档
  7. 显示成功提示："✅ 文档已生成，点击下方卡片查看"

后端集成

导出记录API

工作流内部调用本地后端导出记录API：

GET http://192.168.0.200:8000/api/v1/export/records?userId=default-user&page=1&pageSize=20

此API返回生成的导出记录列表，工作流将其转发给前端。

文档下载

文档通过以下端点下载：

GET http://192.168.0.200:8000/api/v1/export/records/{recordId}/download?userId={userId}

工作流平台配置

工作流设置

在外部AI平台 (http://114.242.25.27:3000) 中，工作流应该配置为：

  1. 接收用户输入: 从聊天消息中提取文档生成请求
  2. 处理请求: 根据请求类型（地质报告、技术文档等）生成文档
  3. 调用后端API: 调用 http://192.168.0.200:8000/api/v1/export/records
  4. 返回结果: 将导出记录数据返回给前端

API响应格式

工作流API应该返回以下格式之一：

格式1：单个导出记录

{
  "content": "AI响应文本",
  "exportRecord": {
    "recordId": "rec-xxx",
    "fileName": "地质报告_xxx.doc",
    "downloadUrl": "http://192.168.0.200:8000/api/v1/export/records/rec-xxx/download?userId=xxx",
    "documentId": "doc-xxx",
    "userId": "default-user",
    "fileSize": 39076,
    "styleId": "default",
    "createdAt": 1782369497764
  }
}

格式2：导出记录数组

{
  "content": "AI响应文本",
  "records": [
    {
      "recordId": "rec-xxx",
      "fileName": "地质报告_xxx.doc",
      "downloadUrl": "http://...",
      ...
    }
  ]
}

安全考虑

  1. API密钥存储:

    • 存储在环境变量中
    • 不提交到版本控制
    • .env.example 中使用占位符

  2. 身份验证:

    • 使用 Bearer token 进行工作流认证
    • 每个请求包含用户ID用于授权

  3. CORS:

    • 工作流API必须允许来自前端源的CORS
    • 后端API必须允许来自前端源的CORS

故障排查

问题：工作流未触发

检查:

  1. .env 中是否设置了 VITE_WORKFLOW_API_KEY？
  2. 输入是否匹配触发模式？
  3. 检查浏览器控制台错误
  4. 验证工作流API可访问性

问题：未显示文档链接

检查:

  1. 工作流是否返回了记录？检查控制台日志
  2. exportRecord 是否正确附加到消息？
  3. 检查网络标签中的工作流API响应
  4. 验证响应格式是否匹配预期结构

问题：文档下载失败

检查:

  1. 后端API是否运行？
  2. 下载URL是否包含正确的记录ID？
  3. 检查后端日志错误
  4. 验证文件在服务器上存在

未来增强

  1. 多文档生成:

    • 支持一次请求生成多个文档
    • 显示多个文档卡片

  2. 文档模板:

    • 允许用户在生成前选择模板
    • 将模板ID传递给工作流

  3. 进度指示:

    • 显示文档生成进度条
    • 显示预计剩余时间

  4. 重试逻辑:

    • 工作流失败时自动重试
    • 指数退避策略

  5. 文档预览:

    • 聊天中内联文档预览
    • 下载前预览

相关文档

版本历史

  • v1.0 (2026-06-25): 工作流集成初始实现
    • 添加工作流服务
    • 集成到聊天store
    • 更新消息渲染
    • 添加环境配置