WeSign人工智能助手-完整文档

🤖 用于文档管理和数字签名的智能多代理系统

![Python 3.9+](https://www.python.org/downloads/) ![AutoGen 0.7.5](https://microsoft.github.io/autogen/) ![FastAPI](https://fastapi.tiangolo.com/) ![OpenAI](https://openai.com/)

🌟 概述

WeSign AI Assistant是一个使用AutoGen v0.7.5构建的复杂多代理编排系统，具有 本地MCP（模型上下文协议）集成, 语音转文本功能，以及 官方OpenAI ChatKit Python SDK 用于无缝的人工智能文档工作流程。

主要特点

✅ 4个专门的人工智能代理 -文档、签名、模板和管理代理 ✅ 本地MCP集成 -AutoGen v0.7.5，内置MCP协议支持 ✅ 拖放文件上传 -直接从浏览器上传文档（PDF、Word、Excel、图像） ✅ WeSign MCP服务器 -基于HTTP的MCP，支持50多种工具进行文档操作 ✅ 语音转文字 -用于语音命令的OpenAI Whisper API集成 ✅ OpenAI GPT-4 -采用最先进的语言模型 ✅ 官方ChatKit Python SDK -OpenAI的官方ChatKit服务器实现 ✅ 现代Web用户界面 -响应式聊天界面，具有实时代理交互功能 ✅ RESTful API -带有自动OpenAPI文档的FastAPI

______________________________________________________________________

🏗️ 建筑

系统概述

┌─────────────────────────────────────────────────────────────┐
│                     WeSign AI Assistant                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌────────────────┐         ┌─────────────────────────┐    │
│  │  ChatKit UI    │────────▶│   FastAPI Backend       │    │
│  │  :8000/ui      │         │   Port 8000             │    │
│  │  + Voice 🎤    │         │   + Whisper API         │    │
│  └────────────────┘         └───────────┬─────────────┘    │
│                                          │                    │
│                              ┌───────────▼─────────────┐    │
│                              │  WeSign Orchestrator    │    │
│                              │  + Native MCP           │    │
│                              └───────────┬─────────────┘    │
│                                          │                    │
│                    ┌─────────────────────┼──────────────┐   │
│          ┌─────────▼───────┐  ┌─────────▼────┐  ┌─────▼───┐
│          │  5 AI Agents    │  │  OpenAI      │  │   MCP   │
│          │  (Specialists)  │  │  GPT-4       │  │ Servers │
│          └─────────────────┘  └──────────────┘  └──────────┘
│               │ Agent Routing                    ├─ FileSystem (14 tools)
│               │                                  └─ WeSign (HTTP)
└─────────────────────────────────────────────────────────────┘

本地MCP集成✨

从自定义MCP客户端迁移到AutoGen本机MCP：

# ✅ NEW: Native AutoGen MCP (orchestrator_new.py)
from autogen_ext.tools.mcp import StdioServerParams, StreamableHttpServerParams, mcp_server_tools

# FileSystem MCP (stdio-based)
filesystem_params = StdioServerParams(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem"] + allowed_dirs
)
tools = await mcp_server_tools(filesystem_params)

# WeSign MCP (HTTP-based)
wesign_params = StreamableHttpServerParams(url="http://localhost:3000")
wesign_tools = await mcp_server_tools(wesign_params)

# Attach to agents
agent = AssistantAgent(tools=tools)

优点：

⚡ 自动工具发现和注册
🔒 类型安全工具执行
🛠️ 内置错误处理
📦 更简单的架构
🚀 更好的性能
🌐 支持stdio和基于HTTP的MCP服务器

OpenAI官方聊天套件集成🎯

由OpenAI的ChatKit Python SDK支持的生产就绪聊天界面：

该系统整合了官方 openai-chatkit 企业级聊天功能包：

后端架构：

# chatkit_server.py - Official ChatKit Server Implementation
from chatkit.server import ChatKitServer
from chatkit.types import ThreadStreamEvent, UserMessageItem, AssistantMessageItem

class WeSignChatKitServer(ChatKitServer):
    """ChatKit server that bridges to AutoGen multi-agent orchestrator"""

    async def respond(self, thread, input_user_message, context):
        # Process through AutoGen orchestrator
        result = await self.orchestrator.process_message(...)

        # Stream back via ChatKit events
        yield ThreadItemAddedEvent(item=assistant_item)
        yield ThreadItemDoneEvent(item=assistant_item)

前端选项：

官方ChatKit用户界面 （当前实施）

- 地点： frontend/official-chatkit.html - CDN： https://cdn.platform.openai.com/deployments/chatkit/chatkit.js - 访问权限：http://localhost:8000/ui

React聊天套件 （高级功能的替代方案）

- 包裹： @openai/chatkit-react - 最适合：具有复杂工作流程的自定义服务器 - 安装： npm install @openai/chatkit-react

关键部件：

组件	目的	位置
`chatkit_server.py`	ChatKit服务器实现	编排器/
`chatkit_store.py`	对话持久性	编排器/
`official-chatkit.html`	官方ChatKit用户界面	前端/
`/chatkit` endpoint	ChatKit通信（SSE）	main.py：281
`/ui` endpoint	为ChatKit用户界面提供服务	main.py：147

通信流程：

User Message → ChatKit UI → /chatkit endpoint → ChatKitServer.respond()
→ AutoGen Orchestrator → AI Agents → MCP Tools → Response Stream
→ Server-Sent Events → ChatKit UI → User

特征：

✅ 通过SSE实时流式响应
✅ 基于线程的会话管理
✅ 文件上传支持
✅ 工具调用可见性
✅ 多代理编排
✅ 持续对话历史

官方文件：

______________________________________________________________________

✨ 特性

1.多代理系统（4名专家）

代理	目的	MCP工具
文件	上传、列出、管理文档	WeSign MCP（50多种工具）
签名代理	创建并完成数字签名	WeSign MCP（50多种工具）
TemplateAgent	管理和使用文档模板	WeSign MCP（50多种工具）
管理员代理	一般协助和指导	无

注： FileSystemAgent已被基于浏览器的拖放文件上传所取代，以获得更好的安全性和用户体验。

2.语音转文本集成🎤

OpenAI Whisper API供电的语音命令：

🎙️ 点击麦克风按钮录制语音
🔊 自然地说出你的命令
✅ 使用Whisper API自动翻译
📝 文本出现在输入字段中以供查看/编辑
🚀 将转录的消息发送给AI助手

支持的音频格式：

WAV、MP3、MP4、M4A、MPEG、MPGA、WEBM
最大文件大小：25MB

语音流：

User Voice → MediaRecorder API → Audio Blob → /api/speech-to-text
→ OpenAI Whisper API → Transcribed Text → Input Field → User Review → Send

浏览器要求：

Chrome 47+、Firefox 25+、Edge 79+、Safari 14.1+
HTTPS连接（或用于开发的localhost）
麦克风权限

看: VOICE_FEATURE_DOCUMENTATION.md 了解完整的实施细节

3.拖放文件上传📎

基于浏览器的安全文件上传，无需文件系统访问：

特征：

🖱️ 将文件直接拖放到聊天界面上
📂 使用文件选择器浏览文件
✅ 实时文件验证（类型和大小）
📊 上传进度跟踪
🗑️ 删除单个文件或全部清除
💾 自动服务器端存储
🔒 无需直接访问文件系统

支持的文件类型：

PDF文档（.PDF）
Word文档（.doc、.docx）
Excel电子表格（.xls、.xlsx）
图片（.png、.jpg、.jpeg）

安全：

✅ 上传前的客户端验证
✅ 服务器端验证和病毒扫描
✅ 带自动清理功能的临时存储
✅ 25MB文件大小限制
✅ 无直接文件系统浏览（沙盒安全）

4.WeSign MCP服务器（基于HTTP）🌐

配置：

服务器URL: http://localhost:3000 （可通过以下方式配置 WESIGN_MCP_URL)
协议：带StreamableHttpServerParams的HTTP
50+WeSign工具可用
准备好进行文档操作、签名工作流、模板管理

状态：已启用并可运行（要求WeSign MCP服务器在端口3000上运行）

5.智能代理选择

基于用户意图的自动路由：

"Upload this document" → DocumentAgent
"Sign this document" → SigningAgent
"Show my templates" → TemplateAgent
"Help me get started" → AdminAgent
"List my documents" → DocumentAgent

______________________________________________________________________

📦 先决条件

Python 3.9+ （3.12推荐）
Node.js 16+ （适用于MCP文件系统服务器）
OpenAI API密钥 （必填）
4GB内存 （推荐8GB）
现代网络浏览器 （用于语音功能）

______________________________________________________________________

🚀 分步启动指南

按照以下步骤从头开始启动WeSign AI Assistant系统：

步骤1：先决条件检查✅

在开始之前，请确保您已经：

# Check Python version (3.9+ required, 3.12 recommended)
python --version

# Check Node.js version (16+ required for WeSign MCP)
node --version

# Check Git
git --version

必修的：

✅ Python 3.9+（推荐3.12）
✅ Node.js 16+（适用于WeSign MCP服务器）
✅ OpenAI API密钥(在这里买一个)
✅ 最低4GB RAM（建议8GB）
✅ 现代网络浏览器（Chrome、Firefox、Edge或Safari）

步骤2：克隆存储库📦

# Navigate to your projects directory
cd /path/to/your/projects

# Clone the repository
git clone https://github.com/GalSened/wesign-ai-dashboard.git

# Enter project directory
cd wesign-ai-dashboard

步骤3：启动WeSign MCP服务器🌐

终端1-WeSign MCP服务器：

# Navigate to WeSign MCP Server directory
cd /c/Users/gals/Desktop/wesign-mcp-server

# Install dependencies (first time only)
npm install

# Start the WeSign MCP Server on port 3000
node dist/mcp-http-server.js

预期产量：

🚀 WeSign MCP Server running on http://localhost:3000
✅ Ready to accept connections

保持此终端运行 -服务器必须保持活动状态才能使用WeSign功能。

步骤4：设置Python环境🐍

2号航站楼-主要应用：

# Navigate to orchestrator directory
cd /path/to/wesign-ai-dashboard/orchestrator

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate

# Upgrade pip
python -m pip install --upgrade pip

# Install all dependencies
pip install -r requirements.txt

预期产量：

Successfully installed autogen-agentchat-0.7.5 autogen-core-0.7.5 autogen-ext-0.7.5 ...

步骤5：配置环境变量🔧

# Copy environment template
cp .env.example .env

# Edit .env file with your preferred editor
# Windows:
notepad .env

# macOS/Linux:
nano .env

中所需的配置 .env:

# OpenAI Configuration (REQUIRED)
OPENAI_API_KEY=sk-proj-YOUR-ACTUAL-KEY-HERE

# WeSign MCP Server Configuration
WESIGN_MCP_URL=http://localhost:3000

# WeSign Credentials (for auto-login in UI)
WESIGN_EMAIL=your-email@example.com
WESIGN_PASSWORD=your-password

# Server Configuration
HOST=0.0.0.0
PORT=8000

⚠️ 重要提示：

替换 sk-proj-YOUR-ACTUAL-KEY-HERE 使用真正的OpenAI API密钥
用您的WeSign凭据替换电子邮件/密码
永不承诺 .env 到版本控制

步骤6：启动编排器🚀

在2号航站楼（venv已激活）：

# Make sure you're in the orchestrator directory
cd /path/to/wesign-ai-dashboard/orchestrator

# Start the FastAPI server
python main.py

预期产量：

🚀 ORCHESTRATOR_NEW.PY LOADED - WITH DRAG-AND-DROP + REFLECTION PATTERN
📍 File: orchestrator_new.py (NOT orchestrator.py)
✨ Features: Hebrew/English support + Drag-and-drop file upload + Response formatting
🤖 Initializing AutoGen agents with WeSign MCP...

🔧 Initializing WeSign MCP server...
📡 Connecting to WeSign MCP at: http://localhost:3000
✅ WeSign MCP: [X] tools available

✅ Initialized 5 agents with WeSign MCP tools:
   👤 Admin Agent: General assistance and guidance
   📄 Document Agent: Upload and manage documents (WeSign tools)
   ✍️  Signing Agent: Create and complete signatures (WeSign tools)
   📋 Template Agent: Manage document templates (WeSign tools)
   📁 Filesystem Agent (REMOVED - use drag-and-drop instead)

🌟 MCP Tools Available:
   📡 WeSign tools: [X]
   🎯 Ready for document operations!

🚀 Starting FastAPI server...
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [XXXX] using WatchFiles
INFO:     Started server process [XXXX]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

保持此终端运行 -这是您的主应用服务器。

步骤7：访问应用程序🌐

打开您的网络浏览器并导航到：

🌐 主用户界面（登录）: http://localhost:8000/login
💬 聊天界面: http://localhost:8000/ui（登录后）
🏥 健康检查: http://localhost:8000/health
📚 API文件: http://localhost:8000/docs

第8步：登录WeSign🔐

打开http://localhost:8000/login
输入您的WeSign凭据：

- 电子邮件：您的电子邮件 .env 文件 - 密码：您的密码 .env 文件

勾选“保持我登录”（可选）
点击“登录WeSign”

预期： 重定向到http://localhost:8000/ui（聊天界面）

步骤9：验证系统状态✅

测试1-健康检查：

curl http://localhost:8000/health

预期响应：

{
  "status": "healthy",
  "version": "v2.9-drag-and-drop-2025-11-19",
  "orchestrator": "orchestrator_new.py",
  "agents": {
    "total_agents": 5,
    "agents": ["admin", "document", "signing", "template"]
  },
  "mcp_integration": {
    "wesign": {
      "status": "connected",
      "url": "http://localhost:3000",
      "tools_count": 50
    }
  }
}

测试2-可用工具：

curl http://localhost:8000/api/tools

测试3-在浏览器中聊天：

在聊天界面中http://localhost:8000/ui，尝试：

💬 "Hello! What can you help me with?"
💬 "List my recent documents"
💬 "Show me my templates"

步骤10：上传测试文件📎

在聊天界面中，查找拖放区域
将PDF、Word或Excel文件拖动到区域上
请参阅“附件”部分中显示的文件
发送消息：“请总结此文档”
AI将处理上传的文件

支持的文件类型：

PDF（.PDF）
Word（.doc、.docx）
Excel（.xls、.xlsx）
图片（.png、.jpg、.jpeg）

文件大小限制： 每个文件25MB

步骤11：可选-语音输入🎤

点击麦克风按钮(🎤) 在聊天界面中
提示时允许麦克风权限
清楚地说出你的命令
单击停止(⏹️) 完成时
审阅转录文本
单击发送或按Enter键

______________________________________________________________________

🎯 快速参考

启动系统（初始设置后）

每次您想使用该系统时：

# Terminal 1 - WeSign MCP Server
cd /c/Users/gals/Desktop/wesign-mcp-server
node dist/mcp-http-server.js

# Terminal 2 - Main Application
cd /path/to/wesign-ai-dashboard/orchestrator
venv\Scripts\activate  # Windows
# OR: source venv/bin/activate  # macOS/Linux
python main.py

然后打开： http://localhost:8000/login

停止系统

# In Terminal 1 (WeSign MCP):
Ctrl+C

# In Terminal 2 (Main Application):
Ctrl+C

应用程序URL

URL	目的
http://localhost:8000/login	登录页面
http://localhost:8000/ui	主聊天界面（登录后）
http://localhost:8000/health	系统健康检查
http://localhost:8000/docs	API文档
http://localhost:3000	WeSign MCP服务器

______________________________________________________________________

🎯 用法示例

Web用户界面（ChatKit）

打开http://localhost:8000/ui在浏览器中尝试：

💬 "List files in my Documents folder"
💬 "Read the first 20 lines of README.md in Downloads"
💬 "Help me sign a document"
💬 "Show me available templates"
💬 "What can you help me with?"

语音输入：

点击麦克风按钮🎤
允许麦克风权限
说出你的命令
点击停止按钮⏹️
审阅转录文本
单击发送或按Enter键

API使用

健康检查：

curl http://localhost:8000/health

答复：

{
  "status": "healthy",
  "version": "2.0.0-native-mcp",
  "mcp_integration": "native_autogen",
  "agents": {
    "total_agents": 5,
    "agents": ["document", "signing", "template", "admin", "filesystem"],
    "conversations": 0,
    "mcp_tools": {
      "wesign": 0,
      "filesystem": 14
    }
  }
}

发送聊天消息：

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "List files in my Documents",
    "context": {
      "userId": "user-123",
      "companyId": "company-456",
      "userName": "John Doe"
    }
  }'

列出可用工具：

curl http://localhost:8000/api/tools

答复：

{
  "count": 14,
  "categories": {
    "wesign": 0,
    "filesystem": 14
  },
  "integration_type": "native_autogen_mcp",
  "tools": {
    "filesystem": [
      "list_allowed_directories",
      "list_directory",
      "read_file",
      "read_multiple_files",
      "write_file",
      "create_directory",
      "move_file",
      "search_files",
      "get_file_info",
      "..."
    ]
  }
}

语音转录：

# Record audio file first, then:
curl -X POST http://localhost:8000/api/speech-to-text \
  -H "Content-Type: multipart/form-data" \
  -F "file=@recording.wav"

答复：

{
  "text": "List files in my Documents folder",
  "filename": "recording.wav",
  "size": 123456
}

______________________________________________________________________

📡 API文档

核心终点

端点	方法	描述
`/`	GET	服务信息和状态
`/health`	GET	使用代理状态进行健康检查
`/ui`	获取	提供ChatKit用户界面
`/official-chatkit.html`	GET	提供OpenAI官方ChatKit用户界面
`/api/chat`	POST	向AI助手发送消息
`/api/speech-to-text`	POST	语音转文本转录（Whisper API）
`/api/tools`	GET	列出可用的MCP工具
`/api/upload`	POST	上传文件进行处理
`/api/chatkit/session`	POST	创建ChatKit身份验证会话
`/api/chatkit-client-token`	POST	传统ChatKit令牌端点
`/api/chatkit-status`	GET	ChatKit服务器统计信息
`/chatkit`	ALL	ChatKit通信端点（SSE）
`/docs`	GET	OpenAPI文档

聊天API请求

{
  "message": "string",
  "context": {
    "userId": "string",
    "companyId": "string",
    "userName": "string",
    "conversationId": "string (optional)"
  },
  "files": [
    {
      "fileId": "string",
      "fileName": "string",
      "filePath": "string"
    }
  ]
}

聊天API响应

{
  "response": "string",
  "conversationId": "string",
  "toolCalls": [
    {
      "tool": "string",
      "action": "string",
      "parameters": {},
      "result": "string"
    }
  ],
  "metadata": {
    "agent": "string",
    "user_name": "string",
    "files_count": 0
  }
}

语音转文本API

请求：

方法：POST
内容类型：多部分/表单数据
主体： file （音频文件）

答复：

{
  "text": "Transcribed text from audio",
  "filename": "recording.wav",
  "size": 12345
}

错误：

400:文件太大（最大25MB）或文件为空
500:转录失败（检查OPENAI_API_KEY）

______________________________________________________________________

🔒 安全

文件系统MCP安全

✅ 沙盒访问：只能访问允许的目录
✅ 路径验证：所有路径在访问前都经过验证
✅ 无系统目录：无法访问 /etc, /usr, /var
✅ 用户确认：FileSystemAgent与用户确认路径

配置最佳实践

# ✅ GOOD: Specific user directories
FILESYSTEM_ALLOWED_DIRS=$HOME/Documents,$HOME/Downloads

# ❌ BAD: System directories
FILESYSTEM_ALLOWED_DIRS=/etc,/usr,/var

# ❌ BAD: Root directory
FILESYSTEM_ALLOWED_DIRS=/

API密钥安全

✅ 将API密钥存储在 .env （永远不要使用git）
✅ 添加 .env 到 .gitignore
✅ 在生产中使用环境变量
✅ 定期旋转按键
✅ 服务器端处理的语音转录（API密钥从未暴露在前端）

语音功能安全

✅ 在隔离目录中创建的临时音频文件
✅ 转录后自动清理
✅ 路径验证阻止目录遍历
✅ 仅在服务器端存储OpenAI API密钥
✅ 没有记录或保存音频数据

______________________________________________________________________

🛠️ 发展

项目结构

wesign-ai-dashboard/
├── orchestrator/               # Main FastAPI application
│   ├── main.py                # FastAPI server & routes
│   ├── orchestrator_new.py    # AutoGen orchestrator with native MCP
│   ├── chatkit_server.py      # ChatKit integration
│   ├── chatkit_store.py       # ChatKit storage
│   ├── requirements.txt       # Python dependencies
│   ├── .env                   # Environment variables (gitignored)
│   ├── .env.example           # Environment template
│   └── venv/                  # Python virtual environment
├── frontend/                   # Web UI
│   ├── official-chatkit.html  # Official OpenAI ChatKit UI
│   └── chatkit-index.html     # Legacy custom UI (deprecated)
├── scripts/                    # Utility scripts
│   ├── start-all.sh           # Complete startup script
│   └── start-filesystem-mcp.sh # FileSystem MCP standalone
├── tests/                      # Test suites
│   └── e2e/                   # End-to-end tests
│       └── wesign-assistant.spec.js  # Playwright E2E tests
├── VOICE_FEATURE_DOCUMENTATION.md  # Voice feature details
├── TEST_RESULTS_REPORT.md     # MCP testing evidence
└── README.md                   # This file

关键文件说明

orchestrator_new.py （436行）：

带有原生MCP的WeSignOrchestrator类
5种专业代理创建方法
MCP服务器初始化（文件系统+WeSign）
消息处理和代理路由
工具调用提取和响应格式化

main.py （700+行）：

FastAPI应用程序设置
所有API端点
ChatKit集成端点
语音转录端点
文件上传处理
健康检查和监测

chatkit_server.py:

WeSignChatKitServer类
OpenAI ChatKit服务器实现
AutoGen编排器桥
服务器发送事件流

chatkit_store.py:

内存对话存储（仅限开发人员）
线程和消息管理
用户上下文跟踪

测试

1.健康检查：

curl http://localhost:8000/health | python3 -m json.tool

2.工具验证：

curl http://localhost:8000/api/tools | python3 -m json.tool

3.聊天集成：

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!","context":{"userId":"test","companyId":"test","userName":"Test"}}' \
  | python3 -m json.tool

4.用户界面手动测试： 打开http://localhost:8000/ui并验证：

✅ UI正确加载
✅ 状态显示“已连接”
✅ 健康检查成功
✅ 可以发送短信
✅ 接收AI响应
✅ 语音按钮可见(🎤)
✅ 麦克风权限工作
✅ 录音功能
✅ 转录作品

5.E2E测试（编剧）：

cd tests/e2e
npm install
npx playwright test wesign-assistant.spec.js

测试覆盖范围：

UI加载和元素
短信发送/接收
录音按钮可见性
空消息处理
健康检查请求
代理路由（文件系统查询）
特殊字符安全
网络请求监控

看: TEST_RESULTS_REPORT.md 有证据的综合测试结果

______________________________________________________________________

🐛 故障排除

问题：“ModuleNotFoundError:没有名为'autogen_agentchat'的模块”

解决方案：

cd orchestrator
source venv/bin/activate
pip install autogen-agentchat autogen-core autogen-ext[mcp]

问题：“地址已在使用中”（端口8000）

解决方案：

# Find and kill process using port 8000
lsof -i :8000 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Or use shorter version
lsof -ti:8000 | xargs kill -9

问题：OpenAI API错误“API密钥无效”

解决方案：

检查API密钥 .env 是正确的
访问https://platform.openai.com/api-keys
如果需要，生成新密钥
更新 .env 使用新密钥： OPENAI_API_KEY=sk-proj-YOUR-KEY-HERE
重新启动编排器： python main.py

问题：文件系统MCP错误“找不到目录”

解决方案：

# Create required directories
mkdir -p ~/Documents ~/Downloads /tmp/wesign-assistant

# Update .env with correct paths
FILESYSTEM_ALLOWED_DIRS=$HOME/Documents,$HOME/Downloads,/tmp/wesign-assistant

# Restart orchestrator
python main.py

问题：UI未加载

解决方案：

检查服务器是否正在运行： curl http://localhost:8000/health
检查前端目录是否存在： ls -la frontend/
验证 chatkit-index.html 存在
检查浏览器控制台是否有错误（F12→ 控制台）
清除浏览器缓存并重新加载

问题：录音不起作用

解决方案：

在浏览器中检查麦克风权限
验证HTTPS或localhost连接（MediaRecorder API需要）
在系统设置中测试麦克风
检查浏览器控制台是否有错误
验证中的OPENAI_API_KEY .env
检查后端日志是否存在转录错误

问题：“转录失败”错误

解决方案：

验证中的OPENAI_API_KEY .env 文件
检查音频文件格式（WAV、MP3等）
验证文件大小是否小于25MB
检查后端日志： python main.py 输出
直接测试API： curl -X POST http://localhost:8000/api/speech-to-text

问题：WeSign MCP显示0个工具

解决方案： 如果WeSign MCP服务器未运行，则会出现这种情况。要启用：

在端口3000上启动WeSign MCP服务器
集 WESIGN_MCP_URL=http://localhost:3000 在 .env
重新启动编排器
检查日志中的“✅ WeSign MCP:X工具可用”

备注：即使WeSign MCP不可用，系统仍继续使用FileSystem MCP（14个工具）。

问题：代理路线错误专家

解决方案： 使用关键字更具体：

✅ “列出文档中的文件”→ 文件系统代理
✅ “签署此文档”→ 签名代理
✅ “显示模板”→ TemplateAgent
❌ “文件帮助”→ 可能路由到AdminAgent（不明确）

路由关键字：

文件系统：“文件”、“浏览”、“列出文件”、”读取文件”
签名：“签名”、“签名”和“签名”
Template:“模板”，“模板”
文档：“上传”、“文档”、“pdf”

______________________________________________________________________

🚀 服务器部署指南

将WeSign AI Assistant部署到生产服务器（Linux/Ubuntu）。

要手动传输的文件

部署到服务器时，这些文件是 不在git存储库中 并且必须手动传输：

1.环境配置文件🔐

wesign ai仪表板/编排器/.env

OPENAI_API_KEY=sk-proj-YOUR-ACTUAL-KEY
WESIGN_MCP_URL=http://localhost:3000
WESIGN_EMAIL=your-email@example.com
WESIGN_PASSWORD=your-password
HOST=0.0.0.0
PORT=8000

wesign mcp服务器/.env （如果存在）

PORT=3000
# Any other WeSign-specific environment variables

2.WeSign MCP服务器构建文件

这 dist/ 文件夹被忽略。您有两个选择：

选项A：传输预构建文件

# Copy entire dist/ folder from local machine
scp -r wesign-mcp-server/dist/ user@server:/opt/wesign-mcp-server/

选项B：在服务器上构建（推荐）

# After cloning, build on server:
cd /opt/wesign-mcp-server
npm install
npm run build

逐步部署服务器

步骤1：准备服务器环境

# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y python3 python3-pip python3-venv nodejs npm nginx git curl

# Install Node.js 18+ (if needed)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Verify versions
python3 --version  # Should be 3.9+
node --version     # Should be 16+
npm --version

步骤2：克隆存储库

# Create deployment directory
sudo mkdir -p /opt
cd /opt

# Clone wesign-ai-dashboard
sudo git clone https://github.com/GalSened/wesign-ai-dashboard.git
sudo chown -R $USER:$USER wesign-ai-dashboard

# Clone wesign-mcp-server (adjust URL to your repo)
sudo git clone 
sudo chown -R $USER:$USER wesign-mcp-server

步骤3：安全地传输环境文件

# From your local machine, use SCP
scp orchestrator/.env user@server:/opt/wesign-ai-dashboard/orchestrator/.env

# Or create directly on server
nano /opt/wesign-ai-dashboard/orchestrator/.env
# Paste your configuration and save

步骤4：设置WeSign MCP服务器

cd /opt/wesign-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Verify dist/ folder exists
ls -la dist/

# Install PM2 for process management
sudo npm install -g pm2

# Start WeSign MCP Server
pm2 start dist/mcp-http-server.js --name wesign-mcp

# Configure PM2 to start on boot
pm2 save
pm2 startup
# Follow the command output instructions

# Check status
pm2 status
pm2 logs wesign-mcp

步骤5：设置Python编排器

cd /opt/wesign-ai-dashboard/orchestrator

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Test the application
python main.py
# Press Ctrl+C to stop after verifying it starts

步骤6：为编排器创建系统服务

# Create systemd service file
sudo nano /etc/systemd/system/wesign-orchestrator.service

粘贴此配置：

[Unit]
Description=WeSign AI Orchestrator
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/wesign-ai-dashboard/orchestrator
Environment="PATH=/opt/wesign-ai-dashboard/orchestrator/venv/bin"
ExecStart=/opt/wesign-ai-dashboard/orchestrator/venv/bin/python main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Set permissions
sudo chown -R www-data:www-data /opt/wesign-ai-dashboard

# Reload systemd
sudo systemctl daemon-reload

# Enable service
sudo systemctl enable wesign-orchestrator

# Start service
sudo systemctl start wesign-orchestrator

# Check status
sudo systemctl status wesign-orchestrator

# View logs
sudo journalctl -u wesign-orchestrator -f

步骤7：配置防火墙

# Allow required ports
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 22/tcp    # SSH (if not already enabled)

# Internal ports (only if accessing from outside)
# sudo ufw allow 8000/tcp  # Orchestrator (not recommended, use Nginx)
# sudo ufw allow 3000/tcp  # WeSign MCP (not recommended, use Nginx)

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

步骤8：设置Nginx反向代理

# Create Nginx configuration
sudo nano /etc/nginx/sites-available/wesign

粘贴此配置：

server {
    listen 80;
    server_name your-domain.com;  # Replace with your domain or IP

    # Increase max body size for file uploads
    client_max_body_size 25M;

    # Main application
    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    # WeSign MCP Server (if needed externally)
    location /mcp/ {
        proxy_pass http://localhost:3000/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

# Enable the site
sudo ln -s /etc/nginx/sites-available/wesign /etc/nginx/sites-enabled/

# Remove default site (optional)
sudo rm /etc/nginx/sites-enabled/default

# Test Nginx configuration
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx

# Check status
sudo systemctl status nginx

步骤9：使用Let’s Encrypt设置SSL（生产）

# Install Certbot
sudo apt install -y certbot python3-certbot-nginx

# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com

# Follow the prompts
# Certbot will automatically configure Nginx for HTTPS

# Test auto-renewal
sudo certbot renew --dry-run

# Certificate will auto-renew

步骤10：验证部署

# Check all services
pm2 status                              # WeSign MCP Server
sudo systemctl status wesign-orchestrator  # Orchestrator
sudo systemctl status nginx             # Nginx

# Check health endpoint
curl http://localhost:8000/health
curl http://your-domain.com/health

# Check logs
pm2 logs wesign-mcp
sudo journalctl -u wesign-orchestrator -f
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

步骤11：监控和维护

# View orchestrator logs
sudo journalctl -u wesign-orchestrator -f

# View WeSign MCP logs
pm2 logs wesign-mcp

# Restart services
sudo systemctl restart wesign-orchestrator
pm2 restart wesign-mcp

# Update application
cd /opt/wesign-ai-dashboard
git pull
sudo systemctl restart wesign-orchestrator

cd /opt/wesign-mcp-server
git pull
npm install
npm run build
pm2 restart wesign-mcp

服务器部署清单

\[\]服务器有Python 3.9+，Node.js 16+，Nginx
\[\]两个存储库都克隆到 /opt/
\[ \] .env 安全传输的文件
\[\]WeSign MCP服务器已构建并正在运行（PM2）
\[\]Python依赖项已安装在venv中
\[\]作为systemd服务运行的编排器
\[\]已配置防火墙（端口80、443）
\[\]已配置Nginx反向代理
\[\]已安装SSL证书（Let's Encrypt）
\[\]健康端点正确响应
\[\]正在监视的日志
\[\]已配置重启时自动启动

生产最佳实践

安全：

- 在生产环境中使用HTTPS（SSL证书） - 保持 .env 文件安全（600权限） - 使用机密管理（例如HashiCorp Vault） - 定期更新依赖关系 - 启用具有最小开放端口的防火墙

监控：

- 设置日志轮换： sudo nano /etc/logrotate.d/wesign - 监控上传文件的磁盘空间 - 设置健康检查监控（UptimeRobot等） - 配置服务故障警报

备份：

- 备份 .env 定期归档 - 备份上传文件目录 - 备份数据库（如适用） - 文档服务器配置

演出

- 对静态资产使用CDN - 启用Nginx缓存 - 监控资源使用情况（CPU、RAM、磁盘） - 如果需要，可水平缩放（负载平衡器）

常见服务器问题

问题：端口8000已在使用中

sudo lsof -i :8000
sudo kill -9 

sudo systemctl restart wesign-orchestrator

问题：权限被拒绝

sudo chown -R www-data:www-data /opt/wesign-ai-dashboard
sudo chmod 600 /opt/wesign-ai-dashboard/orchestrator/.env

问题：服务无法启动

sudo journalctl -u wesign-orchestrator -n 50
sudo systemctl status wesign-orchestrator

问题：Nginx 502网关错误

# Check orchestrator is running
sudo systemctl status wesign-orchestrator
curl http://localhost:8000/health

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

______________________________________________________________________

📊 系统状态

当前版本：2.0.0-active-mcp MCP集成：本地_自主_mcp 自动生成版本: 0.7.5 Python版本：3.9+（建议3.12） FastAPI版本: 0.104+ OpenAI SDK版本: 1.0.0+

代理状态

✅ 文件 -准备就绪（WeSign MCP工具）
✅ 签名代理 -准备就绪（WeSign MCP工具）
✅ TemplateAgent -准备就绪（WeSign MCP工具）
✅ 管理员代理 -准备就绪（无需工具）
✅ 文件系统代理 -准备就绪（14种工具可用）

MCP服务器状态

文件系统MCP：

状态：✅ 可操作的
类型：基于stdio（npx@modelcontextprotocol/服务器文件系统）
工具：14个可用
目录：~/文档、~/下载、/tmp/wesign助手

WeSign MCP：

状态：⚠️ 已启用，正在等待服务器启动
类型：基于HTTP（StreamableHttpServerParams）
网址：http://localhost:3000（可配置）
工具：0（将在服务器启动时填充）
回退：优雅（系统继续使用FileSystem MCP）

语音功能状态

✅ Whisper API集成：活动
✅ 语音转文本端点：/api/语音转文本
✅ 支持的格式：WAV、MP3、MP4、M4A、MPEG、WEBM
✅ 最大文件大小：25MB
✅ 浏览器支持：Chrome 47+、Firefox 25+、Edge 79+、Safari 14.1+

______________________________________________________________________

🚀 性能提示

为了获得最佳性能

使用适当的代理路由:

- 具体使用关键字以路由到正确的代理 - 文件系统查询最好使用显式路径

优化文件操作:

- 保持允许的目录集中（避免大目录） - 在搜索查询中使用特定的文件模式 - 分块读取大文件

API使用:

- 重用 conversationId 用于多回合对话 - 操作前使用健康检查来验证系统 - 监视器 /api/chatkit-status 服务器负载

语音输入:

- 将录音时间控制在60秒以内，以便快速转录 - 清晰地说话以提高准确性 - 使用安静的环境来减少背景噪音

______________________________________________________________________

📝 开发说明

代码质量

✅ 没有模拟实现-所有集成都是真实的
✅ 正确的错误处理和记录
✅ 在整个代码库中键入提示
✅ 全面的文档字符串
✅ 遵循安全最佳实践

测试覆盖

✅ Playwright的E2E测试
✅ API终点测试
✅ MCP集成测试
✅ 语音功能测试
✅ 代理路由验证

看 TEST_RESULTS_REPORT.md 详细的测试结果和证据。

🤝 贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支： git checkout -b feature/your-feature
通过明确的提交进行更改
彻底测试（手动+E2E）
必要时更新文档
提交带有详细描述的拉取请求

贡献领域：

其他MCP服务器集成
增强的代理功能
UI/UX改进
测试覆盖范围扩展
性能优化
文档改进

______________________________________________________________________

📄 许可证

\[您的许可证在这里\]

______________________________________________________________________

🔗 链接

官方文件

项目文件

______________________________________________________________________

💡 提示和最佳实践

对于用户

🎯 明确你的要求，以获得更好的回应
📁 在允许的目录中组织文件以便于访问
🔄 使用对话上下文进行多步骤工作流
✅ 在确认操作之前查看工具调用
🎤 使用语音输入实现更快的交互
📝 发送前查看转录文本

对于开发者

📚 有关最新功能，请阅读AutoGen v0.7.5文档
🔧 尽可能使用本地MCP（更简单、更可靠）
🧪 集成前单独测试代理
📝 保持 .env.example 用新变量更新
🔍 监控调试日志： python main.py
🛡️ 遵循API密钥的安全最佳实践
📊 使用健康端点验证系统状态

用于集成

🌐 使用 /api/chat 用于基于文本的集成
🎤 使用 /api/speech-to-text 用于语音功能
📡 监视器 /health 系统状态端点
🔧 检查 /api/tools 验证可用工具
📖 参考 /docs OpenAPI规范

______________________________________________________________________

📞 支持与联系

对于问题、疑问或贡献：

仔细检查此README
审查 VOICE_FEATURE_DOCUMENTATION.md 用于语音功能
检查 TEST_RESULTS_REPORT.md 用于测试示例
查看后端日志： python main.py 输出
检查浏览器控制台：F 12→控制台选项卡
提交包含详细信息的问题

______________________________________________________________________

内置于❤️ 使用AutoGen v0.7.5、OpenAI GPT-4、Whisper API和模型上下文协议

*最后更新日期：2025-10-28*

Wesign AI Dashboard

快速接入

详细介绍

WeSign人工智能助手-完整文档

🌟 概述

主要特点

🏗️ 建筑

系统概述

本地MCP集成✨

OpenAI官方聊天套件集成🎯

✨ 特性

1.多代理系统（4名专家）

2.语音转文本集成🎤

3.拖放文件上传📎

4.WeSign MCP服务器（基于HTTP）🌐

5.智能代理选择

📦 先决条件

🚀 分步启动指南

步骤1：先决条件检查✅

步骤2：克隆存储库📦

步骤3：启动WeSign MCP服务器🌐

步骤4：设置Python环境🐍

步骤5：配置环境变量🔧

步骤6：启动编排器🚀

步骤7：访问应用程序🌐

第8步：登录WeSign🔐

步骤9：验证系统状态✅

步骤10：上传测试文件📎

步骤11：可选-语音输入🎤

🎯 快速参考

启动系统（初始设置后）

停止系统

应用程序URL

🎯 用法示例

Web用户界面（ChatKit）

API使用

📡 API文档

核心终点

聊天API请求

聊天API响应

语音转文本API

🔒 安全

文件系统MCP安全

配置最佳实践

API密钥安全

语音功能安全

🛠️ 发展

项目结构

关键文件说明

测试

🐛 故障排除

问题：“ModuleNotFoundError:没有名为'autogen_agentchat'的模块”

问题：“地址已在使用中”（端口8000）

问题：OpenAI API错误“API密钥无效”

问题：文件系统MCP错误“找不到目录”

问题：UI未加载

问题：录音不起作用

问题：“转录失败”错误

问题：WeSign MCP显示0个工具

问题：代理路线错误专家

🚀 服务器部署指南

要手动传输的文件

1.环境配置文件🔐

2.WeSign MCP服务器构建文件

逐步部署服务器

步骤1：准备服务器环境

步骤2：克隆存储库

步骤3：安全地传输环境文件

步骤4：设置WeSign MCP服务器

步骤5：设置Python编排器

步骤6：为编排器创建系统服务

步骤7：配置防火墙

步骤8：设置Nginx反向代理

步骤9：使用Let’s Encrypt设置SSL（生产）

步骤10：验证部署

步骤11：监控和维护

服务器部署清单

生产最佳实践

常见服务器问题

📊 系统状态