跳到主要内容

核心模块重构与功能增强技术报告

日期：2026年3月10日 — 2026年3月11日

本报告详细记录了 SayClaw 系统在此期间进行的核心模块重构与功能增强工作，涵盖 LLM 日志关联、WebChat 架构重写、API Key 管理重构以及移动端体验的全面升级。

1. LLM 日志与聊天消息关联​

1.1 背景​

系统已于此前完成了 LiteLLM → OneAPI 的迁移（refactor: admin-api + portal-api 清除 LiteLLM 遗留 → One API），OneAPI 直连 MySQL，实现了请求日志的实时记录。本次更新在此基础上，打通了 LLM 调用日志与用户聊天消息之间的双向关联。

1.2 实现细节​

接口文件关联逻辑
chatHistoryHandlerportal-api/cmd/server/main.goassistant 消息通过 instance_id + ±5s 时间窗口匹配 oneapi.logs，返回 prompt_tokens / completion_tokens / cost_usd / latency_ms / model
usageLogsHandlerportal-api/cmd/server/usage_handlers.go（新增）LLM 调用日志反向关联 chat_messages，返回 user_message / ai_message 预览

涉及 Commits：

  • f1b1425 feat: LLM 日志与聊天消息关联（backend）
  • f050c41 feat: WebChat 和使用记录页面展示 LLM 关联信息（frontend）

2. WebChat WebSocket 架构重写​

2.1 消息投递与持久化​

WebChat 模块在已有 WebSocket 直连架构的基础上，完成了以下关键修复：

  • Telegram 消息互通：将消息发送的 deliver 参数从 false 修改为 true，实现 Web 端发送的消息同步推送至用户绑定的 Telegram Bot。
  • 聊天历史加载：页面加载时优先从 Portal API /me/chat/history 获取持久化的聊天记录，fallback 到 OC Gateway 的 chat.history 事件。
  • 消息持久化 (saveChatMsg)：前端在收发消息后，调用 Portal API 的 POST /me/chat/save 端点，将聊天记录写入 sayclaw_portal.chat_messages 表。

2.2 后端支持​

  • portal-api 新增 POST /me/chat/save 端点，接收 instance_id、role、content 参数。
  • 修复 WebChat session verify 流程，确保 Nginx auth_request 鉴权链路正常工作。

涉及 Commits：

  • 0fd3c23 feat: 重写 API Key 管理模块和 WebChat WS 架构（backend）
  • 4c9eabe feat: WebChat 页面修复 - deliver=true, 历史记录加载（frontend）

3. API Key 管理模块重构​

为配合 OneAPI 架构，管理后台（admin-api）的 API Key 管理模块进行了彻底重写。

模块文件变更说明
Master Key 管理admin-api/cmd/server/api_master_keys.go重写主密钥管理逻辑，实现与 OneAPI Channel 的自动同步。添加/修改主密钥时自动在 OneAPI 中创建或更新对应 Channel
Sub Key 派生admin-api/cmd/server/deprecated_sub_keys.go重写子密钥（Token）派生逻辑，基于实例信息自动在 OneAPI 中生成 Token 并设置额度限制

涉及 Commits：

  • 0fd3c23 feat: 重写 API Key 管理模块和 WebChat WS 架构（backend）
  • e172e89 Merge feature-webchat-tg-integration into main（backend）

4. 移动端 (H5) 体验全面升级​

4.1 功能同步​

移动端 Chat 和 Usage 页面从静态/简化版本升级为与 Web 端功能完全一致：

页面同步功能
/portal/m/chat/WebSocket 直连、deliver=true 消息互通、saveChatMsg 持久化、Portal API 优先加载历史、AI 回复展示 token/费用/延迟/模型
/portal/m/usage/接入真实 API（summary/daily/logs）、今日/本月用量统计、7/14/30 天趋势图、调用日志关联消息展开

4.2 全局移动端自动跳转​

新增 portal/shared/js/mobile-redirect.js 统一检测脚本，覆盖所有 Web 端页面：

  • 检测逻辑：User-Agent 匹配（Android / iPhone / iPad / iPod / Mobile / WeChat）或 window.innerWidth < 768
  • 跳转规则：/portal/xxx/ → /portal/m/xxx/
  • 覆盖页面：dashboard、chat、usage、marketplace、settings、login、根 index.html
  • OAuth 兼容：/auth/callback 回调也支持移动端跳转

4.3 Dashboard UI 修复​

  • 添加底部导航菜单（tab-bar-mount + renderTabBar('dashboard')），与其他移动端页面一致
  • 添加统一的 mobile-header（标题 + Logo）
  • 调整内容区间距（page-content 容器，padding: 20px 16px）

涉及 Commits：

  • 7b0eee5 feat: 移动端 chat 和 usage 页面同步 Web 端完整功能
  • 986cb3b feat: 移动端自动跳转
  • 3a9fe74 fix: 移动端 dashboard 添加底部导航菜单和 header

5. 完整 Commit 清单​

sayclaw-backend（/opt/sayclaw-backend-repo）​

Commit时间说明
0fd3c2303-10 20:45feat: 重写 API Key 管理模块和 WebChat WS 架构
e172e8903-10 20:54Merge feature-webchat-tg-integration into main
f1b142503-11 15:44feat: LLM 日志与聊天消息关联

sayclaw-app（/var/www/sayclaw-app）​

Commit时间说明
4c9eabe03-10 20:48feat: WebChat 页面修复 - deliver=true, 历史记录加载
37427cb03-10 20:55Merge feature-webchat-tg-integration into main
f050c4103-11 15:45feat: WebChat 和使用记录页面展示 LLM 关联信息
7b0eee503-11 16:39feat: 移动端 chat 和 usage 页面同步 Web 端完整功能
986cb3b03-11 17:02feat: 移动端自动跳转
3a9fe7403-11 17:09fix: 移动端 dashboard 添加底部导航菜单和 header