智桥 PWA 用户试用指南
📅 试用日期
2026-03-28
✅ 系统状态
服务器运行状态
- WebSocket 中继服务器: ✅ 运行中 (端口 8765)
- HTTP 健康检查服务器: ✅ 运行中 (端口 8080)
- 会话管理器: ✅ 运行中
- 系统健康状态: ✅ 健康
PWA 功能测试结果
- 总测试数: 14
- 通过: 14
- 失败: 0
- 通过率: 100.0%
测试覆盖
✅ 健康检查端点正常 ✅ 文件读取 API (GET /api/files/read) ✅ 文件搜索 API (GET /api/files/search) ✅ 文件统计 API (GET /api/files/stats) ✅ 文件列表 API (GET /api/files/list) ✅ 推送订阅 API (POST /api/notifications/subscribe) ✅ 推送取消订阅 API (POST /api/notifications/unsubscribe) ✅ 路径遍历攻击防护 ✅ 黑名单目录防护
🌐 访问地址
Web UI (推荐使用以下任一地址)
- http://192.168.2.1:8080/web/ui/index.html
- http://192.168.31.99:8080/web/ui/index.html
- http://10.113.22.99:8080/web/ui/index.html
WebSocket 连接
- 默认地址:
ws://10.113.22.99:8765 - 备用地址:
ws://100.66.1.8:8765(如果配置) - 备用地址:
ws://192.168.2.1:8765
API 文档 (交互式 Swagger UI)
- http://192.168.2.1:8080/docs
🎯 试用功能清单
1. 基础功能
- [ ] WebSocket 实时连接测试
- [ ] 会话管理 (创建、停止、删除会话)
- [ ] 多 AI 工具支持 (Crush, Claude Code, iFlow CLI, Cursor, Trae, Droid, OpenClaw, GitHub Copilot)
2. PWA 功能
- [ ] 离线支持: 断开网络后仍可浏览缓存内容
- [ ] 桌面安装: 浏览器地址栏出现"安装"按钮
- [ ] 推送通知: 允许浏览器发送推送通知
- [ ] Service Worker: 检查浏览器开发者工具的 Application 标签
- [ ] PWA 图标: 不同尺寸图标正确显示
3. 文件提及功能
- [ ] 文件读取: 使用 API 读取文件内容
- [ ] 文件搜索: 模糊搜索文件名
- [ ] 文件列表: 浏览目录结构
- [ ] 文件统计: 获取文件元数据
- [ ] 安全特性: 验证路径遍历攻击防护
4. 推送通知功能
- [ ] 订阅推送: 注册推送订阅
- [ ] 接收通知: 测试推送消息接收
- [ ] 取消订阅: 取消推送订阅
- [ ] 通知点击: 点击通知后正确打开应用
📱 试用步骤
步骤 1: 访问应用
- 打开浏览器（推荐 Chrome 90+, Safari 15+, Firefox 88+）
- 访问: http://10.113.22.99:8080/web/ui/index.html
- 等待页面加载完成
步骤 2: 测试 WebSocket 连接
- 查看页面右上角的连接状态指示器
- 应该显示"已连接" (绿色)
- 如果显示"未连接"，点击"连接"按钮
步骤 3: 创建会话
- 选择一个 AI 工具（例如：Crush）
- 输入命令参数（例如：
--help） - 点击"启动会话"按钮
- 观察会话列表中是否出现新会话
- 查看会话输出
步骤 4: 测试 PWA 功能
- 离线测试:
- 打开浏览器开发者工具 (F12)
- 切换到 Network 标签
- 勾选 "Offline" 选项
- 刷新页面
-
应该看到离线缓存的内容
-
安装 PWA:
- 查看浏览器地址栏右侧
- 应该看到"安装"或"添加到主屏幕"图标
- 点击安装
-
PWA 应该作为独立应用运行
-
Service Worker:
- 打开浏览器开发者工具 (F12)
- 切换到 Application 标签
- 展开 Service Workers
- 应该看到 Service Worker 已激活
步骤 5: 测试文件提及功能
- 点击文件面板中的"提及文件"按钮
- 在搜索框中输入文件名（例如：
server.py） - 查看搜索结果
- 点击文件查看内容
- 验证文件元数据显示正确
步骤 6: 测试推送通知
- 点击设置中的"启用推送通知"开关
- 浏览器会弹出权限请求，点击"允许"
- 创建或停止一个会话
- 应该收到推送通知
- 点击通知，应该返回到应用
🔧 API 端点测试
可以使用以下命令测试 API 端点：
健康检查
文件读取
文件搜索
文件列表
文件统计
🐛 已知限制
OAuth2 认证
- 状态: 未配置
- 影响: 不影响 PWA 核心功能
- 计划: 将在后续阶段配置
HTTPS 支持
- 状态: 当前使用 HTTP
- 影响: 某些 PWA 功能需要 HTTPS（如推送通知）
- 计划: 将在 Week 3 配置 HTTPS/Nginx
真实推送通知
- 状态: 使用模拟模式（mock mode）
- 影响: 推送通知可以在浏览器中显示，但不会真正发送到设备
- 计划: 将在配置 HTTPS 后启用真实推送
📊 性能目标
当前性能指标： - 会话创建: < 100ms ✅ - WebSocket 连接: < 50ms ✅ - 页面加载时间: < 2s ✅ - 内存使用: < 100MB ✅
优化目标（Week 3-4）: - 会话创建: < 50ms - WebSocket 连接: < 20ms - 页面加载时间: < 1s - 内存使用: < 50MB - Lighthouse 分数: > 90
🔐 安全特性
已实现
- ✅ 路径遍历攻击防护
- ✅ 黑名单目录访问防护
- ✅ 文件扩展名白名单
- ✅ 文件大小限制 (10MB)
- ✅ 文件权限检查
待实现
- ⏳ HTTPS/TLS 加密
- ⏳ OAuth2 认证
- ⏳ CSRF 保护
📝 试用反馈
请在试用过程中记录以下信息：
- 功能问题
- 哪些功能正常工作？
- 哪些功能出现问题？
-
问题的详细描述和重现步骤
-
性能体验
- 页面加载速度
- WebSocket 连接稳定性
- 会话创建速度
-
整体响应速度
-
用户体验
- UI/UX 界面是否清晰？
- 操作流程是否流畅？
- 错误提示是否友好？
-
文档是否充分？
-
兼容性
- 使用的浏览器及版本
- 操作系统
-
设备类型（桌面/移动）
-
建议
- 功能改进建议
- 性能优化建议
- 文档改进建议
🛠️ 故障排查
WebSocket 连接失败
- 检查 WebSocket 服务器是否运行:
ps aux | grep start_server - 检查防火墙设置
- 尝试使用备用地址连接
PWA 安装按钮未显示
- 确保使用支持的浏览器（Chrome 90+, Safari 15+, Firefox 88+）
- 清除浏览器缓存
- 使用隐身模式测试
推送通知未收到
- 检查浏览器通知权限设置
- 确保已允许站点发送通知
- 检查系统通知设置
文件操作失败
- 检查文件路径是否正确
- 确认文件存在且有读取权限
- 查看浏览器控制台错误信息
📞 技术支持
如遇到问题，请提供以下信息： - 错误截图 - 浏览器控制台日志（F12 → Console） - 浏览器开发者工具网络日志（F12 → Network） - 操作步骤 - 环境信息（浏览器版本、操作系统）
📚 相关文档
最后更新: 2026-03-28 版本: 1.0.0 测试通过率: 100.0% (14/14)