演示页面故障排查指南

概述

本文档提供演示页面常见问题的排查方法和解决方案，帮助用户快速诊断和修复问题。

快速诊断

1. 服务状态检查

运行以下命令检查所有服务状态：

# 检查 BossAgents 服务
curl -s http://localhost:3006/health

# 检查 MTClaw 服务
curl -s http://localhost:18790/health

# 检查 Ollama 服务
curl -s http://localhost:11434/api/tags

预期响应：

• BossAgents: {"status":"ok"}
• MTClaw: {"status":"ok","tools_loaded":14}
• Ollama: {"models":[...]}

2. 端口占用检查

# Windows
netstat -an | findstr :3006
netstat -an | findstr :18790
netstat -an | findstr :11434

# Linux/Mac
lsof -i :3006
lsof -i :18790
lsof -i :11434

常见问题及解决方案

问题1：演示页面显示乱码（JavaScript代码）

症状：

• 页面显示JavaScript代码片段而不是正常界面
• 看到类似 function validateIntent、async function handleExecute 等代码
• 页面布局异常，代码直接显示在界面上

可能原因：

1. 浏览器缓存了错误的文件版本
2. 通过 file:// 协议直接打开HTML文件（而不是通过HTTP服务器）
3. 服务器返回了错误的Content-Type头
4. HTML文件编码问题

解决方案：

#### 1.1 清除浏览器缓存并强制刷新

• Windows/Linux: 按 Ctrl+F5 或 Ctrl+Shift+R
• Mac: 按 Cmd+Shift+R
• 或者打开开发者工具（F12），在Network标签页勾选"Disable cache"

#### 1.2 通过HTTP服务器访问（推荐）

不要直接双击打开HTML文件，而是通过HTTP服务器访问：

# 确保BossAgents服务已启动
node server.js

然后在浏览器中访问：http://localhost:3006/demo/unified-demo.html

#### 1.3 检查文件编码

确保HTML文件以UTF-8 without BOM编码保存：

# 检查文件编码
file -i public/demo/unified-demo.html
# 应该显示：text/html; charset=utf-8

#### 1.4 检查服务器配置

确保服务器正确设置Content-Type头：

// 在server.js中检查静态文件服务配置
app.use(express.static('public', {
  setHeaders: (res, path) => {
    if (path.endsWith('.html')) {
      res.setHeader('Content-Type', 'text/html; charset=UTF-8');
    }
  }
}));

#### 1.5 页面自动修复机制

最新版本已添加自动修复机制：

• 检测到代码被错误显示时，会自动清除错误内容
• 通过file://协议访问时会显示警告提示
• 页面加载异常时会提示用户强制刷新

问题2：演示页面无法访问

症状：

• 访问 http://localhost:3006/demo/unified-demo.html 返回 404
• 页面空白或显示错误

可能原因：

1. BossAgents 服务未启动
2. 静态文件路径错误
3. 端口被占用

解决方案：

#### 2.1 启动 BossAgents 服务

cd /path/to/bossagents
node server.js

#### 2.2 检查静态文件路径

# 确认演示页面文件存在
ls public/demo/unified-demo.html

# 如果不存在，从源码重新构建

#### 1.3 检查端口占用

# 查找占用3006端口的进程
netstat -ano | findstr :3006
# 终止占用进程（谨慎操作）
taskkill /PID <进程ID> /F

问题2：服务状态显示"未连接"

症状：

• 演示页面显示 MTClaw、Ollama 或 BossAgents 状态为"未连接"
• 环境检测失败

可能原因：

1. 服务未启动
2. 网络连接问题
3. CORS 配置错误
4. 防火墙阻止

解决方案：

#### 2.1 启动缺失的服务

# 启动 MTClaw 服务
cd /path/to/mtclaw
python mtclaw_server.py

# 启动 Ollama 服务
ollama serve

# 启动 BossAgents 服务
cd /path/to/bossagents
node server.js

#### 2.2 检查服务日志

# 查看 BossAgents 日志
tail -f server.log

# 查看 MTClaw 日志
tail -f mtclaw.log

# 查看 Ollama 日志
ollama serve > ollama.log 2>&1 &

#### 2.3 验证 CORS 配置

检查 BossAgents 服务的 CORS 配置：

// 在 server.js 或路由文件中确保有以下配置
res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type');

#### 2.4 检查防火墙设置

# Windows 防火墙
netsh advfirewall firewall show rule name=all

# 添加端口例外
netsh advfirewall firewall add rule name="BossAgents" dir=in action=allow protocol=TCP localport=3006
netsh advfirewall firewall add rule name="MTClaw" dir=in action=allow protocol=TCP localport=18790

问题3：执行请求超时

症状：

• 点击执行按钮后长时间无响应
• 控制台显示超时错误
• 请求耗时超过30秒

可能原因：

1. 网络延迟
2. 服务处理时间过长
3. MTClaw 路由决策慢
4. LLM 响应慢

解决方案：

#### 3.1 增加超时时间

修改演示页面中的超时配置：

// 在 unified-demo.html 中查找 apiPost 函数
const tid=setTimeout(()=>c.abort(),ms||30000); // 修改为60000（60秒）

#### 3.2 检查 MTClaw 性能

# 测试 MTClaw 响应时间
curl -X POST http://localhost:18790/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"mtclaw-router","messages":[{"role":"user","content":"测试"}],"stream":false}' \
  -w "时间: %{time_total}s\n"

#### 3.3 优化 Ollama 模型

# 使用更小的模型
ollama pull deepseek-r1:1.5b

# 检查可用模型
ollama list

问题4：L1路由命中率低

症状：

• 简单请求仍走 L3 路由
• 端侧脚本未触发
• 加速比显示不理想

可能原因：

1. MTClaw 工具配置问题
2. 意图关键词不匹配
3. 工具匹配阈值设置过高

解决方案：

#### 4.1 检查 MTClaw 工具配置

# 查看已加载的工具
curl http://localhost:18790/v1/tools

# 检查工具匹配规则
# 查看 MTClaw 配置文件中的工具定义

#### 4.2 优化意图关键词

使用更明确的意图关键词：

• "查询系统时间"
• "获取当前日期"
• "计算1+1"
• "简单的数学计算"

#### 4.3 调整匹配阈值

修改 MTClaw 配置中的相似度阈值：

# 在 MTClaw 配置中调整
"similarity_threshold": 0.7  # 降低阈值提高匹配率

问题5：性能数据不一致

症状：

• 三场景对比数据异常
• 加速比计算错误
• 路由统计不准确

可能原因：

1. 计时逻辑错误
2. 数据记录不完整
3. 统计计算错误

解决方案：

#### 5.1 验证计时逻辑

检查 executeScene 函数中的计时逻辑：

// 确保使用 Date.now() 计算准确耗时
const startTime = Date.now();
// ... 执行代码 ...
const elapsed = Date.now() - startTime;

#### 5.2 检查数据记录

验证 addExecutionRecord 函数是否正确记录数据：

// 确保记录完整的执行信息
const record = {
  sceneId: ENV.currentScene,
  staffId: currentStaffId,
  intent: intent,
  result: executionResult,
  timestamp: new Date().toISOString()
};

#### 5.3 调试统计计算

在控制台输出性能指标计算过程：

console.log('[PerformanceMetrics]', {
  sceneA: sceneARecords,
  sceneB: sceneBRecords,
  sceneD: sceneDRecords,
  speedupRatio: speedupRatio
});

问题6：页面样式异常

症状：

• 布局错乱
• 样式丢失
• 交互异常

可能原因：

1. CSS 加载失败
2. JavaScript 错误
3. 浏览器兼容性问题

解决方案：

#### 6.1 检查浏览器控制台

按 F12 打开开发者工具，检查：

• Console 标签页中的错误信息
• Network 标签页中的资源加载状态
• Elements 标签页中的 DOM 结构

#### 6.2 验证 CSS 内联

由于演示页面使用内联样式，检查：