Add OSS and commercial workspace boundaries

Document multi-tenant workspace architecture
feat(qrcode-login): enhance WeChat login flow with expiration handlin… (#2212 )
2026-06-02 20:14:36 +00:00 · 2026-05-21 07:25:02 -04:00 · 2026-05-21 07:25:02 -04:00 · 2026-05-21 14:28:02 +08:00 · 2026-05-20 21:49:16 +08:00 · 2026-05-20 18:21:40 +08:00
39 changed files with 1779 additions and 610 deletions
--- a/README.md
+++ b/README.md
@@ -47,6 +47,8 @@ LangBot is an **open-source, production-grade platform** for building AI-powered

 [→ Learn more about all features](https://link.langbot.app/en/docs/features)

+📍 Practical guides: [deploy a multi-platform AI bot in 5 minutes](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connect DeepSeek to WeChat, Discord, and Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [run a Dify Agent in Discord, Telegram, and Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/), and [build an n8n-powered chatbot](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
 ---

 ## Quick Start
--- a/README_CN.md
+++ b/README_CN.md
@@ -47,6 +47,8 @@ LangBot 是一个**开源的生产级平台**，用于构建 AI 驱动的即时

 [→ 了解更多功能特性](https://link.langbot.app/zh/docs/features)

+📍 实践指南：[5 分钟部署多平台 AI 机器人](https://blog.langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[将 DeepSeek 接入微信、企业微信与 Discord](https://blog.langbot.app/zh/blog/connect-deepseek-to-wechat/)、[让 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://blog.langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 构建多平台 AI 聊天机器人](https://blog.langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。
+
 ---

 ## 快速开始
--- a/README_ES.md
+++ b/README_ES.md
@@ -46,6 +46,8 @@ LangBot es una **plataforma de código abierto y grado de producción** para con

 [→ Conocer más sobre todas las funcionalidades](https://link.langbot.app/en/docs/features)

+📍 Guías prácticas: [desplegar un bot de IA multiplataforma en 5 minutos](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [conectar DeepSeek a WeChat, Discord y Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [ejecutar un Dify Agent en Discord, Telegram y Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) y [crear un chatbot con n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
 ---

 ## Inicio Rápido
--- a/README_FR.md
+++ b/README_FR.md
@@ -46,6 +46,8 @@ LangBot est une **plateforme open-source de niveau production** pour créer des

 [→ En savoir plus sur toutes les fonctionnalités](https://link.langbot.app/en/docs/features)

+📍 Guides pratiques : [déployer un bot IA multiplateforme en 5 minutes](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connecter DeepSeek à WeChat, Discord et Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [exécuter un Dify Agent dans Discord, Telegram et Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) et [créer un chatbot avec n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
 ---

 ## Démarrage Rapide
--- a/README_JP.md
+++ b/README_JP.md
@@ -46,6 +46,8 @@ LangBot は、AI搭載のインスタントメッセージングボットを構

 [→ すべての機能について詳しく見る](https://link.langbot.app/ja/docs/features)

+📍 実践ガイド: [5分でマルチプラットフォームAIボットをデプロイ](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/)、[DeepSeekをWeChat・Discord・Telegramに接続](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/)、[Dify AgentをDiscord・Telegram・Slackで動かす](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/)、[n8n連携チャットボットを構築](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/)。
+
 ---

 ## クイックスタート
--- a/README_KO.md
+++ b/README_KO.md
@@ -46,6 +46,8 @@ LangBot은 AI 기반 인스턴트 메시징 봇을 구축하기 위한 **오픈

 [→ 모든 기능 자세히 보기](https://link.langbot.app/en/docs/features)

+📍 실전 가이드: [5분 만에 멀티 플랫폼 AI 봇 배포하기](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [DeepSeek를 WeChat, Discord, Telegram에 연결하기](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [Dify Agent를 Discord, Telegram, Slack에서 실행하기](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/), [n8n 기반 챗봇 만들기](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
 ---

 ## 빠른 시작
--- a/README_RU.md
+++ b/README_RU.md
@@ -46,6 +46,8 @@ LangBot — это **платформа с открытым исходным к

 [→ Подробнее обо всех возможностях](https://link.langbot.app/en/docs/features)

+📍 Практические руководства: [развернуть мультиплатформенного ИИ-бота за 5 минут](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [подключить DeepSeek к WeChat, Discord и Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [запустить Dify Agent в Discord, Telegram и Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) и [создать чат-бота на n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
 ---

 ## Быстрый старт
--- a/README_TW.md
+++ b/README_TW.md
@@ -48,6 +48,8 @@ LangBot 是一個**開源的生產級平台**，用於建構 AI 驅動的即時

 [→ 了解更多功能特性](https://link.langbot.app/zh/docs/features)

+📍 實踐指南：[5 分鐘部署多平台 AI 機器人](https://blog.langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[將 DeepSeek 接入微信、企業微信與 Discord](https://blog.langbot.app/zh/blog/connect-deepseek-to-wechat/)、[讓 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://blog.langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 建構多平台 AI 聊天機器人](https://blog.langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。
+
 ---

 ## 快速開始
--- a/README_VI.md
+++ b/README_VI.md
@@ -46,6 +46,8 @@ LangBot là một **nền tảng mã nguồn mở, cấp sản xuất** để x

 [→ Tìm hiểu thêm về tất cả tính năng](https://link.langbot.app/en/docs/features)

+📍 Hướng dẫn thực hành: [triển khai bot AI đa nền tảng trong 5 phút](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [kết nối DeepSeek với WeChat, Discord và Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [chạy Dify Agent trên Discord, Telegram và Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) và [xây dựng chatbot với n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
 ---

 ## Bắt đầu nhanh
--- a/docs/multi-tenant/workspace-multi-user-architecture.md
+++ b/docs/multi-tenant/workspace-multi-user-architecture.md
@@ -0,0 +1,858 @@
+# LangBot 多租户与多用户改造方案
+
+## 目标
+
+本方案面向 LangBot 从“单实例单管理员”演进到 SaaS 友好的“多 workspace、多账户、多权限”架构。
+
+核心定义：
+
+- Account：登录主体。一个自然人或服务账号，可加入多个 workspace。
+- Workspace：租户边界。一个 workspace 内可拥有多个用户、机器人、流水线、模型、知识库、扩展、监控数据与 API Key。
+- Membership：账户与 workspace 的关系，承载角色与权限。
+- Role/Permission：workspace 内权限，不再用“是否是当前唯一用户”来决定访问能力。
+
+目标体验：
+
+- 新用户登录后可以创建 workspace、加入 workspace、切换 workspace。
+- 同一个账户可加入多个 workspace，每个 workspace 权限不同。
+- 一个 workspace 可邀请多个用户协作，并分别设置 owner/admin/editor/viewer 等权限。
+- 所有业务资源默认属于某个 workspace，所有 API 默认在当前 workspace 下工作。
+- Plugin SDK、MCP、知识库、模型调用、监控日志都能拿到稳定的 workspace 上下文，并且不跨租户泄露数据。
+
+## 调研结论
+
+### 当前 LangBot 的单用户假设
+
+LangBot 现在已经有 `users` 表和 JWT 登录，但仍是单用户/单租户模型：
+
+- `src/langbot/pkg/entity/persistence/user.py` 的 `User` 只保存 `user/password/account_type/space_*`，没有角色、状态、workspace 关系。
+- `src/langbot/pkg/api/http/service/user.py` 通过 `is_initialized()` 判断系统是否已有用户；`create_or_update_space_user()` 在系统已初始化且邮箱不匹配时拒绝新用户，这直接限制了多用户登录。
+- `src/langbot/pkg/api/http/controller/group.py` 的 `AuthType.USER_TOKEN` 验证后只向 handler 注入 `user_email`；JWT payload 也只有 `user`，没有 `account_id`、`workspace_id`、`role`、`permissions`。
+- `src/langbot/pkg/api/http/service/apikey.py` 的 API Key 只验证 key 是否存在，没有 owner、scope、workspace。
+- `web/src/app/infra/http/BaseHttpClient.ts` 从 `localStorage.token` 读取单个 token，并在所有请求上加 `Authorization`；前端没有 workspace selector，也没有当前 workspace 上下文。
+
+当前登录流程更像“初始化一个本地管理账号”，而不是 SaaS 账户体系。要支持多用户，必须把“初始化状态”和“首个 workspace 创建”拆开。
+
+### 业务资源当前都是全局资源
+
+主要持久化表没有租户字段：
+
+- Bot：`bots`
+- Pipeline：`legacy_pipelines`、`pipeline_run_records`
+- Model：`model_providers`、`llm_models`、`embedding_models`、`rerank_models`
+- Plugin：`plugin_settings`
+- MCP：`mcp_servers`
+- RAG：`knowledge_bases`、`knowledge_base_files`、`knowledge_base_chunks`
+- Monitoring：`monitoring_messages`、`monitoring_llm_calls`、`monitoring_sessions`、`monitoring_errors`、`monitoring_embedding_calls`、`monitoring_feedback`
+- API Key：`api_keys`
+- Webhook：`webhooks`
+- Metadata：`metadata`
+- Binary storage：`binary_storages`
+
+对应服务也直接 select 全表，例如：
+
+- `BotService.get_bots()` 返回所有 bot。
+- `PipelineService.get_pipelines()` 返回所有 pipeline。
+- `ModelProviderService.get_providers()` 返回所有 provider。
+- `MCPService.get_mcp_servers()` 返回所有 MCP server。
+- 插件和二进制存储没有 workspace 维度，插件 workspace storage 在 SDK 里还硬编码为 `default`。
+
+所以改造重点不是只给用户表加字段，而是给资源访问层统一加入 workspace scope。
+
+### 运行时也存在全局单例假设
+
+`src/langbot/pkg/core/stages/build_app.py` 初始化的是一个全局 `Application`，其中包含单例：
+
+- `platform_mgr`
+- `pipeline_mgr`
+- `model_mgr`
+- `tool_mgr`
+- `plugin_connector`
+- `sess_mgr`
+- `rag_mgr`
+- `vector_db_mgr`
+
+当前运行时把所有 bot、pipeline、model、plugin、MCP 都加载到同一套内存管理器。多租户改造需要决定：是共享运行时并在对象上带 workspace 过滤，还是每个 workspace 拆 runtime shard。第一阶段建议共享进程、强制 workspace-aware；等规模变大后再演进为按 workspace 分片。
+
+### Plugin SDK 对 workspace 的假设
+
+SDK 当前只认识 bot/pipeline/query/session，不认识租户：
+
+- `src/langbot_plugin/api/entities/builtin/pipeline/query.py` 的 `Query` 有 `query_id/launcher_type/launcher_id/sender_id/bot_uuid/pipeline_uuid`，没有 `workspace_id/account_id`。
+- `src/langbot_plugin/api/entities/builtin/provider/session.py` 的 `Session` 只按 `launcher_type + launcher_id` 表达会话。
+- `src/langbot_plugin/api/proxies/langbot_api.py` 暴露 `get_bots/get_llm_models/invoke_llm/list_tools/vector_*` 等 Host API，都是全局语义。
+- `src/langbot_plugin/runtime/io/handlers/plugin.py` 的 `set_workspace_storage/get_workspace_storage` 把 `owner_type` 设为 `workspace`，但 `owner` 固定为 `default`。
+- LangBot 侧 `src/langbot/pkg/plugin/handler.py` 处理插件请求时，会把 `GET_BOTS`、`GET_LLM_MODELS`、`VECTOR_*` 等转到全局服务。
+
+这意味着多租户落地时，不能只在 Web API 层过滤；插件可以通过 Host API 访问全局资源，所以 SDK/Runtime 通信也必须传递 workspace context。
+
+## 开源版与商业版产品边界
+
+LangBot 是开源软件，但多 workspace 能力本质上是 SaaS 控制面能力。如果把完整多 workspace、成员协作、订阅权益和配额代码都放进开源仓库，只靠本地 feature flag 或本地 license check，无法有效避免第三方 fork 后自建 SaaS。因此建议采用 open-core 架构：开源版保留单 workspace 执行能力，账户、订阅、权益和多 workspace 协作能力放到 LangBot Space/Cloud Control Plane 和商业模块中。
+
+### 版本边界
+
+推荐拆成三层：
+
+- `LangBot Core OSS`：开源，自托管，默认只有一个隐式 `default workspace`。它可以在数据结构上兼容 workspace，但产品能力上不提供创建多个 workspace、切换 workspace、成员邀请、成员权限管理、审计和多租户配额。
+- `LangBot Space / Cloud Control Plane`：托管控制面，负责 account、workspace、membership、subscription、billing、entitlement、license token、workspace quota、marketplace 权益等能力。
+- `LangBot Commercial Module`：商业闭源或私有包，承载多 workspace、团队协作、RBAC、自定义角色、审计日志、SAML/SSO、企业私有化授权等能力。
+
+企业私有化版本可以采用 `LangBot Core + Commercial Module + License Token` 的形式交付。开源 Core 仍然可独立运行，但只能作为单 workspace 自托管产品，不提供 SaaS 多租户控制面。
+
+### OSS 中如何保留兼容但不开放多 workspace
+
+为了让后续商业版复用同一套资源隔离模型，OSS 代码里可以保留 `workspace_uuid` 相关字段和默认 workspace 迁移，但应限制为单 workspace：
+
+- 首次初始化时创建一个 `Default Workspace`。
+- 所有资源自动归属这个 default workspace。
+- 不暴露 `POST /api/v1/workspaces`。
+- 不暴露 workspace switcher。
+- 不暴露成员邀请和成员角色管理。
+- 不支持一个 account 加入多个 workspace。
+- 不支持 workspace 数量大于 1。
+- 前端不展示 workspace selector。
+- API 层如果收到非 default workspace 的 `X-Workspace-Id`，直接拒绝。
+
+也就是说，OSS 可以是 workspace-aware，但不是 multi-workspace-enabled。这样做的价值是：代码结构提前适配租户隔离，未来商业版不用重写所有资源模型；同时开源版用户无法直接通过 UI/API 获得 SaaS 型多租户能力。
+
+### 账户、订阅和权益抽到 Space
+
+账户和订阅体系建议从 LangBot Core 中抽出，交给 Space 控制面：
+
+```text
+LangBot Space
+  -> Account
+  -> Workspace
+  -> Membership
+  -> Subscription
+  -> Entitlement
+  -> License Token
+
+LangBot Core
+  -> Validate entitlement / license
+  -> Run bots, pipelines, plugins, MCP, RAG
+  -> Enforce local resource scope
+  -> Report usage
+```
+
+这样做有几个原因：
+
+- 账号体系如果完全在本地，第三方容易直接改库创建 workspace/membership。
+- 订阅、配额和商业权益如果完全在本地，容易绕过。
+- Space 可以统一处理 OAuth、组织、邀请、付款、发票、套餐、权益、Marketplace 分发权限。
+- LangBot Core 只作为执行面消费 Space 下发的 entitlement，减少商业规则暴露。
+
+### Entitlement 设计
+
+Space 向 LangBot Core 下发签名权益，可以是在线校验，也可以为企业版提供短期/长期离线 license token。
+
+示例：
+
+```json
+{
+  "edition": "oss",
+  "workspace_limit": 1,
+  "member_limit": 1,
+  "multi_workspace": false,
+  "rbac": false,
+  "audit_log": false,
+  "custom_roles": false,
+  "sso": false,
+  "commercial_use": false,
+  "expires_at": 1893456000
+}
+```
+
+OSS 默认权益：
+
+- `workspace_limit = 1`
+- `member_limit = 1`
+- `multi_workspace = false`
+- `rbac = false`
+- `audit_log = false`
+- `sso = false`
+
+Cloud/Pro/Enterprise 权益：
+
+- `workspace_limit > 1`
+- `member_limit > 1`
+- `multi_workspace = true`
+- `rbac = true`
+- 可按套餐打开 audit、custom roles、SSO、usage reporting、enterprise support 等能力。
+
+Core 执行面需要在关键入口强制校验 entitlement：
+
+- 创建 workspace。
+- 邀请成员。
+- 修改成员角色。
+- 切换 workspace。
+- 创建超过 quota 的资源。
+- 开启商业模块功能。
+
+### 商业模块边界
+
+以下能力不建议进入 OSS 仓库的完整实现：
+
+- 多 workspace 创建和切换。
+- Workspace 成员邀请。
+- Workspace RBAC 和自定义角色。
+- Workspace 审计日志。
+- Workspace 级用量和配额管理。
+- 订阅、账单、发票。
+- 企业 SSO/SAML/OIDC。
+- 在线/离线 license 管理。
+- 多租户 SaaS 运营控制台。
+
+OSS 仓库可以保留接口占位、默认 workspace 兼容和必要的数据隔离字段，但完整交互、管理 UI、权益校验器和多 workspace policy engine 应由 Space 或商业模块提供。
+
+### 防自建 SaaS 的现实边界
+
+技术上无法 100% 阻止别人 fork 开源代码后自行改造。更可靠的策略是组合：
+
+- 不把完整商业多 workspace 实现放进 OSS。
+- Space 控制面提供账号、订阅、权益、Marketplace 和官方托管能力。
+- 商业模块闭源或私有分发。
+- 使用商标、云服务条款和商业 license 限制“自称官方 LangBot SaaS”或未经授权商用托管。
+- 如果当前开源 license 对托管商用限制不足，需要单独评估 license 策略，必要时引入 open-core license 或新增商业附加条款。具体 license 调整需要法律评审。
+
+结论：多 workspace 的底层 schema 可以在 OSS 中以 default workspace 兼容方式铺路，但多 workspace 产品能力、账户订阅权益、协作管理和 SaaS 控制面应放到 Space/商业模块，不作为开源版可直接使用的能力。
+
+## 推荐总体架构
+
+采用“单实例多 workspace，资源行级隔离，运行时上下文隔离”的架构：
+
+```mermaid
+flowchart TD
+    A["Account"] --> B["WorkspaceMembership"]
+    B --> C["Workspace"]
+    C --> D["Bots"]
+    C --> E["Pipelines"]
+    C --> F["Models & Providers"]
+    C --> G["Knowledge Bases"]
+    C --> H["Extensions: Plugins / MCP"]
+    C --> I["API Keys & Webhooks"]
+    C --> J["Monitoring"]
+    D --> K["Runtime Query"]
+    E --> K
+    K --> L["Plugin Runtime"]
+    K --> M["MCP Runtime"]
+    L --> N["Workspace-scoped Host APIs"]
+```
+
+原则：
+
+- 账户全局唯一，workspace 是所有业务资源的归属边界。
+- 所有 HTTP handler 在进入业务服务前解析出 `RequestContext(account, workspace, membership, permissions)`。
+- 所有 service 方法显式接收 `ctx` 或 `workspace_id`，禁止在业务服务里无条件 select 全表。
+- 运行时对象的 key 从 `uuid` 扩展为 `(workspace_id, uuid)` 或使用全局唯一 uuid 但必须记录 workspace_id 并校验。
+- 插件/MCP/知识库/模型调用都按 query 所属 workspace 过滤可用资源。
+
+## 数据模型设计
+
+### Account
+
+替代现有 `users` 的语义，建议保留表名但升级字段，避免过大迁移：
+
+字段建议：
+
+- `id`
+- `uuid`
+- `email`
+- `password_hash`
+- `display_name`
+- `avatar_url`
+- `account_type`: `local | space`
+- `status`: `active | disabled | deleted`
+- `space_account_uuid`
+- `space_access_token`
+- `space_refresh_token`
+- `space_access_token_expires_at`
+- `space_api_key`
+- `created_at`
+- `updated_at`
+
+兼容策略：
+
+- 旧字段 `user` 迁移为 `email`，可以短期保留 alias。
+- 旧 `password` 迁移为 `password_hash`，也可先保持列名不变，service 层改命名。
+- JWT 中不要继续只放 email，应放 `sub=account_uuid`。
+
+### Workspace
+
+新增 `workspaces`：
+
+- `uuid`
+- `name`
+- `slug`
+- `avatar_url`
+- `type`: `personal | team`
+- `status`: `active | suspended | deleted`
+- `default_language`
+- `created_by_account_uuid`
+- `created_at`
+- `updated_at`
+
+每个账户首次登录时自动创建一个 personal workspace。旧单用户实例迁移时创建一个 `Default Workspace`。
+
+### WorkspaceMembership
+
+新增 `workspace_memberships`：
+
+- `workspace_uuid`
+- `account_uuid`
+- `role`: `owner | admin | developer | operator | viewer`
+- `status`: `active | invited | disabled`
+- `invited_by_account_uuid`
+- `joined_at`
+- `created_at`
+- `updated_at`
+
+唯一索引：
+
+- `(workspace_uuid, account_uuid)`
+
+### WorkspaceInvitation
+
+新增 `workspace_invitations`：
+
+- `uuid`
+- `workspace_uuid`
+- `email`
+- `role`
+- `token_hash`
+- `expires_at`
+- `accepted_at`
+- `created_by_account_uuid`
+- `created_at`
+
+用于邀请外部用户加入 workspace。Space OAuth 登录时可以根据 email 自动匹配未接受邀请。
+
+### Role 与 Permission
+
+先用固定角色，后续再做自定义角色。
+
+建议权限：
+
+- `workspace.manage`
+- `member.view`
+- `member.invite`
+- `member.update_role`
+- `member.remove`
+- `bot.view`
+- `bot.manage`
+- `pipeline.view`
+- `pipeline.manage`
+- `model.view`
+- `model.manage`
+- `knowledge.view`
+- `knowledge.manage`
+- `extension.view`
+- `extension.manage`
+- `monitoring.view`
+- `apikey.manage`
+- `webhook.manage`
+- `billing.view`
+- `billing.manage`
+
+角色映射：
+
+| Role | 说明 | 权限 |
+| --- | --- | --- |
+| owner | workspace 拥有者 | 全部权限；可转让 owner；不可被其他角色移除 |
+| admin | 管理员 | 除 owner 转让和删除 workspace 外的全部权限 |
+| developer | 构建者 | 管理 bot、pipeline、model、knowledge、extension、webhook，可看监控 |
+| operator | 运营者 | 查看和启停 bot、查看监控、查看配置，不可改密钥和删除资源 |
+| viewer | 只读成员 | 只读资源和监控 |
+
+### 业务资源加 workspace_uuid
+
+以下表需要新增 `workspace_uuid`：
+
+- `bots`
+- `legacy_pipelines`
+- `pipeline_run_records`
+- `model_providers`
+- `llm_models`
+- `embedding_models`
+- `rerank_models`
+- `plugin_settings`
+- `mcp_servers`
+- `knowledge_bases`
+- `knowledge_base_files`
+- `knowledge_base_chunks`
+- `monitoring_*`
+- `api_keys`
+- `webhooks`
+- `binary_storages`
+- `metadata`
+
+索引建议：
+
+- 所有资源表加 `(workspace_uuid, created_at)` 或 `(workspace_uuid, updated_at)`。
+- 资源唯一键从单列改为 workspace 复合唯一：
+  - `bots.uuid` 可保持全局唯一，但查询仍必须带 workspace。
+  - `plugin_settings` 主键从 `(plugin_author, plugin_name)` 改为 `(workspace_uuid, plugin_author, plugin_name)`。
+  - `mcp_servers.name` 如果未来要求唯一，必须是 `(workspace_uuid, name)`。
+  - `metadata.key` 改为 `(workspace_uuid, key)`，系统级 metadata 单独放 `system_metadata` 或使用 `workspace_uuid=NULL`。
+  - `binary_storages.unique_key` 建议改为 `workspace_uuid + owner_type + owner + key` 的 hash。
+
+### API Key
+
+API Key 必须归属于 workspace：
+
+- `workspace_uuid`
+- `created_by_account_uuid`
+- `scopes`
+- `expires_at`
+- `last_used_at`
+- `status`
+
+验证 API Key 后生成 `RequestContext`：
+
+- `account_uuid=None` 或 service account uuid
+- `workspace_uuid=key.workspace_uuid`
+- `permissions=key.scopes`
+
+这样 `/api/v1/platform/bots/<uuid>/send_message` 之类接口不会跨 workspace 操作 bot。
+
+## 后端改造方案
+
+### RequestContext
+
+新增统一上下文对象，例如：
+
+```python
+class RequestContext:
+    account_uuid: str | None
+    workspace_uuid: str
+    role: str | None
+    permissions: set[str]
+    auth_type: Literal["user_token", "api_key"]
+```
+
+改造 `RouterGroup.route()`：
+
+- `USER_TOKEN`：验证 JWT，读取 `account_uuid`，再从 header/query/cookie 中解析 current workspace。
+- `API_KEY`：验证 API Key，直接得到 workspace。
+- `USER_TOKEN_OR_API_KEY`：两者都返回同一种 `RequestContext`。
+- handler 参数从可选 `user_email` 升级为可选 `ctx`；兼容期同时支持 `user_email`。
+
+当前 workspace 传递方式：
+
+- 推荐 header：`X-Workspace-Id: <workspace_uuid>`
+- Web 前端同时把当前 workspace 存在 localStorage。
+- 如果未传，后端用账户最近使用 workspace 或第一个 active membership。
+
+JWT payload：
+
+```json
+{
+  "sub": "account_uuid",
+  "email": "user@example.com",
+  "iss": "LangBot-...",
+  "exp": 1234567890
+}
+```
+
+不要把 workspace 写死在 JWT 里，否则切换 workspace 需要刷新 token。可以额外支持短 TTL workspace token，但第一阶段不必。
+
+### 服务层改造模式
+
+所有 service 方法增加 `ctx` 或 `workspace_uuid`：
+
+```python
+async def get_bots(self, ctx: RequestContext, include_secret: bool = True):
+    require(ctx, "bot.view")
+    query = sqlalchemy.select(Bot).where(Bot.workspace_uuid == ctx.workspace_uuid)
+```
+
+需要改造的服务：
+
+- `UserService`：拆成 AccountService + WorkspaceService 更清晰。
+- `ApiKeyService`：按 workspace 管理 key。
+- `BotService`：所有 bot 查询/创建/更新/删除按 workspace。
+- `PipelineService`：所有 pipeline 查询/默认 pipeline 按 workspace。
+- `ModelProviderService` 和 model services：按 workspace 隔离 provider 和 model。
+- `MCPService`：按 workspace 管理 MCP server，运行时按 workspace host。
+- `KnowledgeService/RAGRuntimeService`：按 workspace 管理 KB、文件、collection。
+- `MonitoringService`：记录和查询都带 workspace。
+- `WebhookService`：按 workspace 管理 webhook。
+- `PluginRuntimeConnector`：插件安装、设置、配置按 workspace。
+
+### HTTP API 形态
+
+保留现有路径，靠 `X-Workspace-Id` 表示当前 workspace，可减少前端和 SDK 破坏：
+
+- `GET /api/v1/workspaces`
+- `POST /api/v1/workspaces`
+- `GET /api/v1/workspaces/current`
+- `PUT /api/v1/workspaces/current`
+- `GET /api/v1/workspaces/<workspace_uuid>/members`
+- `POST /api/v1/workspaces/<workspace_uuid>/invitations`
+- `PUT /api/v1/workspaces/<workspace_uuid>/members/<account_uuid>`
+- `DELETE /api/v1/workspaces/<workspace_uuid>/members/<account_uuid>`
+
+现有资源 API：
+
+- `/api/v1/platform/bots`
+- `/api/v1/pipelines`
+- `/api/v1/provider/*`
+- `/api/v1/plugins`
+- `/api/v1/mcp`
+- `/api/v1/knowledge`
+
+继续保留，但必须从 `RequestContext.workspace_uuid` 过滤。
+
+对外 API Key 也使用相同路径，只是由 key 决定 workspace。
+
+### 初始化流程
+
+现有 `/api/v1/user/init` 含义改为“创建首个账号和首个 workspace”：
+
+1. 如果系统没有任何 account：
+   - 创建 account。
+   - 创建 personal/team workspace。
+   - 创建 owner membership。
+   - 创建默认 pipeline。
+   - 标记 wizard status 到该 workspace metadata。
+2. 如果系统已有 account：
+   - 禁止无邀请注册，除非配置允许公开注册。
+   - Space OAuth 登录后，如果没有 membership，引导创建 workspace 或接受邀请。
+
+`/api/v1/user/account-info` 不应再只返回 first user，应返回：
+
+- `initialized`
+- `registration_mode`
+- `space_enabled`
+- `default_login_methods`
+
+登录成功后前端调用 `/api/v1/workspaces` 选择 workspace。
+
+### 运行时隔离
+
+第一阶段采用共享进程 + workspace-aware runtime：
+
+- `RuntimeBot` 增加 `workspace_uuid`。
+- `RuntimePipeline` 增加 `workspace_uuid`。
+- `Query` 增加 `workspace_uuid`，从 bot/pipeline 派生。
+- `SessionManager.get_session()` key 从 `(launcher_type, launcher_id)` 改为 `(workspace_uuid, bot_uuid, launcher_type, launcher_id)`。
+- `PipelineManager.pipeline_dict` key 可保持 pipeline uuid，但所有 load/get 都校验 workspace；如果 uuid 不是全局唯一则改为 `(workspace_uuid, pipeline_uuid)`。
+- `ModelManager` provider/model 加 workspace 过滤；`get_model_by_uuid` 必须确保 query workspace 可访问。
+- `ToolManager` 中 MCP tools、plugin tools 按 query workspace 过滤。
+
+后续规模化时可演进：
+
+- workspace runtime shard：每个 workspace 一套 plugin runtime/MCP runtime。
+- 大客户独立进程或独立数据库。
+
+## Plugin SDK 与 Runtime 改造
+
+### Query/Event 增加 workspace context
+
+SDK `Query` 增加：
+
+- `workspace_uuid: str`
+- `workspace_slug: str | None`
+- `account_uuid: str | None`，仅 Web/API 触发时可能有，聊天平台消息通常为空。
+
+Event 模型通过 `event.query.workspace_uuid` 可拿到租户上下文；序列化时也应包含这些字段。
+
+向后兼容：
+
+- 字段可选，默认 `None`。
+- 老插件不感知这些字段也能跑。
+- 新插件可通过 `ctx.event.query.workspace_uuid` 或新增 `ctx.get_workspace()` 访问。
+
+### Host API 默认按当前 workspace 限制
+
+`LangBotAPIProxy` 的以下方法必须由 Host 端按 workspace 过滤：
+
+- `get_bots`
+- `get_bot_info`
+- `send_message`
+- `get_llm_models`
+- `invoke_llm`
+- `list_plugins_manifest`
+- `list_commands`
+- `list_tools`
+- `call_tool`
+- `invoke_embedding`
+- `vector_*`
+- `list_knowledge_bases`
+- `retrieve_knowledge`
+
+建议新增显式方法：
+
+- `get_workspace_info()`
+- `get_current_account()`
+- `get_workspace_storage(...)`
+
+但不要让插件传入任意 workspace id 来越权访问。插件请求的 workspace 应由 Runtime 根据当前 query/plugin connection 填充。
+
+### Workspace storage 修复
+
+当前 SDK runtime 中：
+
+```python
+data["owner_type"] = "workspace"
+data["owner"] = "default"
+```
+
+必须改为：
+
+- 如果请求来自 query/event：owner 为 `workspace_uuid`。
+- 如果请求来自后台插件任务：owner 为 plugin 安装所属 workspace。
+- Host 侧 `binary_storages` 加 `workspace_uuid`，并在 unique key 中包含 workspace。
+
+Plugin storage 建议也同时加 workspace：
+
+- 现在 plugin storage owner 是 `author/name`，这会导致同一插件在不同 workspace 的私有数据冲突。
+- 应改为 `(workspace_uuid, plugin_id, key)`。
+
+### 插件安装与配置
+
+`plugin_settings` 从全局变为 workspace-scoped：
+
+- 同一个插件可安装到多个 workspace。
+- 每个 workspace 有自己的 enabled、priority、config、install_source、install_info。
+- 插件 runtime 列表需要能按 workspace 过滤。
+
+实现路线有两种：
+
+1. 共享插件进程，插件代码只加载一份，设置和调用时附带 workspace。
+2. 每个 workspace 一个插件容器实例，隔离最彻底但资源占用更高。
+
+推荐第一阶段采用方案 1，但要求：
+
+- 所有 RuntimeToLangBot/PluginToRuntime action 都能携带 `workspace_uuid`。
+- 插件 config 获取时按 workspace 返回。
+- 插件 page API 请求必须校验当前用户在该 workspace 有访问权限。
+
+### MCP
+
+MCP server 是租户资源：
+
+- `mcp_servers.workspace_uuid`。
+- MCP session key 从 `server_name` 改为 `(workspace_uuid, server_name)` 或使用全局 uuid。
+- Pipeline extension preferences 中绑定 MCP server uuid 时，只能绑定同 workspace 的 server。
+- MCP tool 列表在 query 执行时按 query.workspace_uuid + pipeline 绑定关系过滤。
+
+## 前端改造
+
+### Workspace selector
+
+Home layout 顶部或 sidebar 增加 workspace selector：
+
+- 当前 workspace 名称和头像。
+- 切换 workspace 后写入 `localStorage.currentWorkspaceId`。
+- 所有请求自动带 `X-Workspace-Id`。
+- 切换后刷新 sidebar 数据和页面缓存。
+
+`BaseHttpClient` request interceptor 增加：
+
+```ts
+const workspaceId = localStorage.getItem("currentWorkspaceId");
+if (workspaceId) config.headers["X-Workspace-Id"] = workspaceId;
+```
+
+### 用户与成员管理页面
+
+新增页面：
+
+- `/home/workspace/settings`
+- `/home/workspace/members`
+- `/home/workspace/invitations`
+
+能力：
+
+- owner/admin 邀请成员。
+- owner/admin 修改成员角色。
+- owner 移除成员、转让 owner。
+- 所有人可切换 workspace。
+- viewer/operator 在 UI 上隐藏不可操作按钮，但后端仍做权限校验。
+
+### 登录与注册
+
+登录后流程：
+
+1. `authUser` 拿 token。
+2. `initializeUserInfo()` 获取 account info。
+3. `GET /api/v1/workspaces`。
+4. 如果没有 workspace：进入创建 workspace 向导。
+5. 如果有多个 workspace：默认进入最近使用 workspace，可切换。
+
+注册页不再表达“初始化管理员账号”，而是：
+
+- 首次系统启动：创建首个 owner + default workspace。
+- 后续：根据配置允许公开注册，或只能接受邀请。
+
+### 旧页面影响
+
+需要逐个检查这些页面的数据加载是否都依赖当前 workspace：
+
+- Bots
+- Pipelines
+- Plugins/Market/MCP
+- Knowledge
+- Monitoring
+- Models dialog
+- API integration dialog
+- Wizard
+
+## 迁移方案
+
+### 迁移阶段 0：准备
+
+- 引入 `workspaces`、`workspace_memberships`、`workspace_invitations`。
+- 给 `users` 增加 `uuid/status/display_name` 等字段。
+- 创建 `RequestContext`，但先不强制所有服务改完。
+
+### 迁移阶段 1：默认 workspace
+
+对现有实例执行迁移：
+
+1. 创建 `Default Workspace`。
+2. 找到现有第一个 user，设为 owner。
+3. 所有已有资源写入 `workspace_uuid=default_workspace_uuid`。
+4. `metadata` 迁入 default workspace；确实全局的配置放到 `system_metadata`。
+5. `binary_storages` 中 `owner_type=workspace, owner=default` 改为 owner 为 default workspace uuid。
+6. 插件 `plugin_settings` 归入 default workspace。
+
+### 迁移阶段 2：服务层强制 scope
+
+- 改所有 service 查询，必须要求 `workspace_uuid`。
+- API Key 迁移为 workspace key。
+- 所有写操作必须检查权限。
+- 监控和任务查询按 workspace 过滤。
+
+### 迁移阶段 3：运行时上下文
+
+- `Query`、`Session`、`RuntimeBot`、`RuntimePipeline` 增加 workspace。
+- Plugin/MCP/Model/RAG runtime 全部按 workspace 过滤。
+- 修复 SDK workspace storage。
+
+### 迁移阶段 4：前端多 workspace
+
+- 登录后 workspace 选择。
+- Header/sidebar workspace switcher。
+- 成员和邀请管理。
+- 所有 API 请求带 `X-Workspace-Id`。
+
+### 迁移阶段 5：安全收敛
+
+- 添加跨 workspace 越权测试。
+- 添加 API Key scope 测试。
+- 添加插件 Host API 过滤测试。
+- 添加 MCP 和 RAG 隔离测试。
+
+## 安全边界
+
+必须防的场景：
+
+- 用户 A 修改 URL 中 bot uuid，访问用户 B workspace 的 bot。
+- API Key 来自 workspace A，但调用 workspace B 的 bot。
+- 插件通过 `get_bots()` 枚举所有 workspace 的 bot。
+- 插件通过 `workspace_storage` 读取其它 workspace 的数据。
+- MCP server 名称相同导致 session 复用。
+- monitoring session_id 相同导致数据串租户。
+- Space OAuth 登录时，同 email 账户被错误绑定到已有本地 account。
+
+建议策略：
+
+- 所有资源访问都使用 `workspace_uuid + resource_id`。
+- 所有 service 方法入口做权限检查。
+- 插件 Host API 的 workspace 不信任插件入参，只信任 query/runtime connection 上下文。
+- API Key 只授予最小 scope，默认不允许成员管理。
+- owner 角色不能被普通 admin 移除或降权。
+
+## 实施优先级
+
+### P0：基础租户骨架
+
+- Account uuid/status。
+- Workspace / Membership / Invitation。
+- RequestContext。
+- JWT 改为 account uuid。
+- 前端 current workspace header。
+
+### P1：资源行级隔离
+
+- Bots、Pipelines、Models、MCP、Plugins、Knowledge、Monitoring、API Keys 全部加 workspace_uuid。
+- service 查询统一加 workspace filter。
+- 权限矩阵落地。
+
+### P2：运行时隔离
+
+- Query、Session、RuntimeBot、RuntimePipeline 加 workspace。
+- Plugin Host API 和 MCP tools 按 workspace 过滤。
+- SDK workspace storage 从 `default` 改为真实 workspace。
+
+### P3：协作体验
+
+- 邀请成员。
+- 成员列表和角色管理。
+- workspace switcher。
+- 最近使用 workspace。
+
+### P4：SaaS 运维增强
+
+- Workspace 级用量统计。
+- Workspace 级限额：max_bots/max_pipelines/max_extensions/tokens/storage。
+- 审计日志。
+- workspace suspend/delete。
+- 可选自定义角色。
+
+## 测试计划
+
+后端测试：
+
+- 账户可加入多个 workspace。
+- 同账户在不同 workspace 权限不同。
+- viewer 不能创建/修改资源。
+- API Key 只能访问所属 workspace。
+- 所有资源 list/get/update/delete 都不能跨 workspace。
+- 默认 workspace 迁移后旧数据可用。
+
+运行时测试：
+
+- 两个 workspace 使用相同 `launcher_id` 不共享 session。
+- 两个 workspace 使用相同 MCP server name 不共享 MCP session。
+- 插件 `get_bots()` 只能看到当前 workspace bot。
+- 插件 `workspace_storage` 在不同 workspace 读写隔离。
+- Pipeline 只调用当前 workspace 绑定的插件和 MCP tools。
+
+前端测试：
+
+- 登录后自动进入最近 workspace。
+- 切换 workspace 后列表数据变化。
+- 无权限按钮隐藏，直接调用 API 也被后端拒绝。
+- 邀请成员流程完整。
+
+迁移测试：
+
+- SQLite 老实例迁移。
+- PostgreSQL 老实例迁移。
+- 已有 local account 迁移为 default workspace owner。
+- 已有 Space account token 和 Space model provider API key 不丢失。
+
+## 关键实现注意事项
+
+- 不建议在第一版做数据库 schema-per-tenant。LangBot 当前 ORM 和运行时均以单库单表为主，先做 shared schema + workspace_uuid 成本更低。
+- 不建议每个 workspace 立即启动独立 plugin runtime。先共享 runtime，强制 action 带 workspace；大客户隔离可作为后续部署形态。
+- 不要只在前端过滤 workspace。插件、API Key、MCP、RAG 都能绕过前端，必须在后端和运行时层过滤。
+- `metadata` 要拆清楚：wizard status 属于 workspace，系统版本/迁移信息属于 system。
+- `users.user` 用 email 当主键语义不稳，应尽快引入 `account_uuid` 并让 JWT 以 uuid 为准。
+- `plugin_settings` 当前主键没有 workspace，改造时要先改主键/唯一约束，否则同插件无法在多个 workspace 配不同配置。
+
+## 建议落地顺序
+
+1. 新增 workspace/account/membership 表和 RequestContext。
+2. 迁移旧数据到 default workspace。
+3. 改 auth 和前端请求头，让每个请求都有 current workspace。
+4. 从最核心资源开始逐个加 scope：bot -> pipeline -> provider/model -> plugin/MCP -> knowledge -> monitoring。
+5. 改 SDK Query/Event 和 runtime storage。
+6. 上成员管理 UI 和邀请。
+7. 做越权测试和迁移测试。
+
+这个顺序的好处是可以较早让主 UI 在一个 workspace 下继续工作，同时把最危险的跨租户泄露面逐步收紧。
--- a/src/langbot/pkg/api/http/controller/groups/platform/adapters.py
+++ b/src/langbot/pkg/api/http/controller/groups/platform/adapters.py
@@ -179,8 +179,6 @@ class AdaptersRouterGroup(group.RouterGroup):
            """Start WeChat QR code login. Returns session_id + QR code data URL."""
            import uuid
            import time
-            import io
-            import base64

            from langbot.libs.openclaw_weixin_api.client import OpenClawWeixinClient, DEFAULT_BASE_URL

@@ -208,60 +206,32 @@ class AdaptersRouterGroup(group.RouterGroup):

            async def run_login():
                try:
-                    import qrcode as qr_lib

-                    for _attempt in range(3):
-                        qr_resp = await client.fetch_qrcode()
-                        if not qr_resp.qrcode or not qr_resp.qrcode_img_content:
-                            raise Exception('Failed to get QR code from server')
-
-                        # Generate QR code image locally
-                        qr = qr_lib.QRCode(error_correction=qr_lib.constants.ERROR_CORRECT_L)
-                        qr.add_data(qr_resp.qrcode_img_content)
-                        qr.make(fit=True)
-                        img = qr.make_image(fill_color='black', back_color='white')
-                        buf = io.BytesIO()
-                        img.save(buf, format='PNG')
-                        b64 = base64.b64encode(buf.getvalue()).decode('utf-8')
-                        data_url = f'data:image/png;base64,{b64}'
-
-                        def _update_qr():
-                            session['qr_data_url'] = data_url
-                            session['expire_at'] = time.time() + 480  # 8 minutes
+                    def on_qrcode(qr_data_url: str, _qr_url: str):
+                        def _update():
+                            session['qr_data_url'] = qr_data_url
+                            session['expire_at'] = time.time() + 180
                            session['status'] = 'waiting'

-                        loop.call_soon_threadsafe(_update_qr)
-
-                        # Poll for scan status
-                        deadline = loop.time() + 180
-                        while loop.time() < deadline:
-                            try:
-                                status_resp = await client.poll_qrcode_status(qr_resp.qrcode)
-                            except Exception:
-                                await asyncio.sleep(2)
-                                continue
-
-                            if status_resp.status == 'confirmed' and status_resp.bot_token:
-                                session['status'] = 'success'
-                                session['token'] = status_resp.bot_token
-                                session['base_url'] = status_resp.baseurl or client.base_url
-                                session['account_id'] = status_resp.ilink_bot_id or ''
-                                return
-
-                            if status_resp.status == 'expired':
-                                break  # retry with new QR code
-
-                            await asyncio.sleep(1)
-                        else:
-                            pass  # timeout, retry
-
-                    # All retries exhausted
-                    session['status'] = 'error'
-                    session['error'] = 'QR code login failed: max retries exceeded'
+                        loop.call_soon_threadsafe(_update)

+                    result = await client.login(
+                        max_retries=1,
+                        poll_timeout_ms=180_000,
+                        on_qrcode=on_qrcode,
+                    )
+                    session['status'] = 'success'
+                    session['token'] = result.token
+                    session['base_url'] = result.base_url
+                    session['account_id'] = result.account_id
                except Exception as e:
-                    session['status'] = 'error'
-                    session['error'] = str(e)
+                    error_message = str(e)
+                    if 'expired' in error_message.lower() or 'max retries exceeded' in error_message.lower():
+                        session['status'] = 'expired'
+                        session['error'] = 'QR code expired'
+                    else:
+                        session['status'] = 'error'
+                        session['error'] = error_message
                finally:
                    await client.close()

@@ -295,7 +265,11 @@ class AdaptersRouterGroup(group.RouterGroup):
            if not session:
                return self.http_status(404, -1, 'Session not found')

-            data = {'status': session['status']}
+            data = {
+                'status': session['status'],
+                'qr_data_url': session['qr_data_url'],
+                'expire_at': session['expire_at'],
+            }

            if session['status'] == 'success':
                data['token'] = session['token']
@@ -305,6 +279,9 @@ class AdaptersRouterGroup(group.RouterGroup):
            elif session['status'] == 'error':
                data['error'] = session['error']
                _weixin_login_sessions.pop(session_id, None)
+            elif session['status'] == 'expired':
+                data['error'] = session['error']
+                _weixin_login_sessions.pop(session_id, None)

            return self.success(data=data)

--- a/src/langbot/pkg/api/http/controller/groups/plugins.py
+++ b/src/langbot/pkg/api/http/controller/groups/plugins.py
@@ -7,8 +7,10 @@ import httpx
 import uuid
 import os
 import posixpath
+import sqlalchemy

 from .....core import taskmgr
+from .....entity.persistence import plugin as persistence_plugin
 from .. import group
 from langbot_plugin.runtime.plugin.mgr import PluginInstallSource

@@ -148,7 +150,15 @@ class PluginsRouterGroup(group.RouterGroup):
                return self.http_status(404, -1, 'plugin not found')

            if quart.request.method == 'GET':
-                return self.success(data={'config': plugin['plugin_config']})
+                result = await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.select(persistence_plugin.PluginSetting.config)
+                    .where(persistence_plugin.PluginSetting.plugin_author == author)
+                    .where(persistence_plugin.PluginSetting.plugin_name == plugin_name)
+                )
+                persisted_config = result.scalar_one_or_none()
+
+                config = persisted_config if persisted_config is not None else plugin['plugin_config']
+                return self.success(data={'config': config})
            elif quart.request.method == 'PUT':
                data = await quart.request.json

--- a/src/langbot/pkg/api/http/controller/groups/system.py
+++ b/src/langbot/pkg/api/http/controller/groups/system.py
@@ -140,17 +140,6 @@ class SystemRouterGroup(group.RouterGroup):
        async def _() -> str:
            return self.success(data=await self.ap.maintenance_service.get_storage_analysis())

-        @self.route('/debug/exec', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
-        async def _() -> str:
-            if not constants.debug_mode:
-                return self.http_status(403, 403, 'Forbidden')
-
-            py_code = await quart.request.data
-
-            ap = self.ap
-
-            return self.success(data=exec(py_code, {'ap': ap}))
-
        @self.route(
            '/debug/plugin/action',
            methods=['POST'],
--- a/src/langbot/pkg/platform/sources/aiocqhttp.py
+++ b/src/langbot/pkg/platform/sources/aiocqhttp.py
@@ -3,6 +3,7 @@ import typing
 import asyncio
 import traceback
 import datetime
+import json

 import aiocqhttp
 import pydantic
@@ -293,6 +294,29 @@ class AiocqhttpMessageConverter(abstract_platform_adapter.AbstractMessageConvert
            elif msg.type == 'dice':
                face_id = msg.data['result']
                yiri_msg_list.append(platform_message.Face(face_type='dice', face_id=int(face_id), face_name='骰子'))
+            elif msg.type == 'json':
+                try:
+                    raw = msg.data.get('data', {})
+                    if isinstance(raw, str):
+                        raw = json.loads(raw)
+                    if isinstance(raw, dict):
+                        _meta = raw.get('meta', {}) or {}
+                        if isinstance(_meta, dict):
+                            _detail = _meta.get('detail_1') or _meta.get('music') or _meta.get('news') or {}
+                        else:
+                            _detail = {}
+                        if isinstance(_detail, dict):
+                            preview = _detail.get('preview', '')
+                            title = _detail.get('desc', '') or _detail.get('title', '')
+                            url = _detail.get('qqdocurl', '') or _detail.get('jumpUrl', '')
+                        else:
+                            preview = title = url = ''
+                        text = ' '.join([f'[{raw.get("app", "")}]', preview, title, url]).strip()
+                        yiri_msg_list.append(platform_message.Plain(text=text or '[收到一张JSON卡片]'))
+                    else:
+                        yiri_msg_list.append(platform_message.Plain(text=str(raw)))
+                except Exception:
+                    yiri_msg_list.append(platform_message.Plain(text='[收到一张JSON卡片]'))

        chain = platform_message.MessageChain(yiri_msg_list)

--- a/tests/integration/api/conftest.py
+++ b/tests/integration/api/conftest.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import pytest
+
+
+def dedupe_preregistered_groups() -> None:
+    """Keep API integration route registration isolated across test modules."""
+    from langbot.pkg.api.http.controller import group
+
+    seen: set[tuple[str, str]] = set()
+    unique_groups = []
+    for group_cls in group.preregistered_groups:
+        key = (group_cls.name, group_cls.path)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique_groups.append(group_cls)
+
+    group.preregistered_groups[:] = unique_groups
+
+
+@pytest.fixture(scope='module')
+def http_controller_cls(mock_circular_import_chain):
+    """Import HTTPController under each module's circular-import isolation."""
+    from langbot.pkg.api.http.controller.main import HTTPController
+
+    dedupe_preregistered_groups()
+    return HTTPController
--- a/tests/integration/api/test_bots.py
+++ b/tests/integration/api/test_bots.py
@@ -102,11 +102,9 @@ def fake_bot_app():


@pytest.fixture(scope='module')
-async def quart_test_client(fake_bot_app):
+async def quart_test_client(fake_bot_app, http_controller_cls):
    """Create Quart test client (module scope to avoid route re-registration)."""
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_bot_app)
+    controller = http_controller_cls(fake_bot_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
--- a/tests/integration/api/test_embed.py
+++ b/tests/integration/api/test_embed.py
@@ -101,11 +101,9 @@ def fake_embed_app():


@pytest.fixture(scope='module')
-async def quart_test_client(fake_embed_app):
+async def quart_test_client(fake_embed_app, http_controller_cls):
    """Create Quart test client (module scope)."""
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_embed_app)
+    controller = http_controller_cls(fake_embed_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
@@ -299,4 +297,4 @@ class TestEmbedFeedbackEndpoint:
            json={'message_id': 'msg-123', 'feedback_type': 99}
        )

-        assert response.status_code == 400
+        assert response.status_code == 400
--- a/tests/integration/api/test_knowledge.py
+++ b/tests/integration/api/test_knowledge.py
@@ -107,11 +107,9 @@ def fake_knowledge_app():


@pytest.fixture(scope='module')
-async def quart_test_client(fake_knowledge_app):
+async def quart_test_client(fake_knowledge_app, http_controller_cls):
    """Create Quart test client (module scope to avoid route re-registration)."""
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_knowledge_app)
+    controller = http_controller_cls(fake_knowledge_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
--- a/tests/integration/api/test_monitoring.py
+++ b/tests/integration/api/test_monitoring.py
@@ -113,11 +113,9 @@ def fake_monitoring_app():


@pytest.fixture(scope='module')
-async def quart_test_client(fake_monitoring_app):
+async def quart_test_client(fake_monitoring_app, http_controller_cls):
    """Create Quart test client (module scope)."""
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_monitoring_app)
+    controller = http_controller_cls(fake_monitoring_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
@@ -329,4 +327,4 @@ class TestMonitoringExportEndpoint:
            headers={'Authorization': 'Bearer test_token'}
        )

-        assert response.status_code == 200
+        assert response.status_code == 200
--- a/tests/integration/api/test_pipelines.py
+++ b/tests/integration/api/test_pipelines.py
@@ -119,11 +119,9 @@ def fake_pipeline_app():


@pytest.fixture(scope='module')
-async def quart_test_client(fake_pipeline_app):
+async def quart_test_client(fake_pipeline_app, http_controller_cls):
    """Create Quart test client (module scope to avoid route re-registration)."""
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_pipeline_app)
+    controller = http_controller_cls(fake_pipeline_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
--- a/tests/integration/api/test_providers.py
+++ b/tests/integration/api/test_providers.py
@@ -116,11 +116,9 @@ def fake_provider_app():


@pytest.fixture(scope='module')
-async def quart_test_client(fake_provider_app):
+async def quart_test_client(fake_provider_app, http_controller_cls):
    """Create Quart test client (module scope to avoid route re-registration)."""
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_provider_app)
+    controller = http_controller_cls(fake_provider_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
--- a/tests/integration/api/test_smoke.py
+++ b/tests/integration/api/test_smoke.py
@@ -119,15 +119,13 @@ def fake_api_app():
 # ============== QUART TEST CLIENT FIXTURE ==============

@pytest.fixture
-async def quart_test_client(fake_api_app):
+async def quart_test_client(fake_api_app, http_controller_cls):
    """
    Create Quart test client with real HTTPController and route registration.

    Requires mock_circular_import_chain fixture to run first (usefixtures).
    """
-    from langbot.pkg.api.http.controller.main import HTTPController
-
-    controller = HTTPController(fake_api_app)
+    controller = http_controller_cls(fake_api_app)
    await controller.initialize()

    client = controller.quart_app.test_client()
@@ -344,4 +342,4 @@ class TestRealImports:
                break

        assert user_group is not None
-        assert user_group.path == '/api/v1/user'
+        assert user_group.path == '/api/v1/user'
--- a/tests/test_cwe94_debug_exec.py
+++ b/tests/test_cwe94_debug_exec.py
@@ -0,0 +1,66 @@
+"""
+PoC test for CWE-94: Authenticated RCE via exec() on user-supplied Python code.
+
+The /api/v1/system/debug/exec endpoint passes raw HTTP body to exec(),
+allowing arbitrary code execution when debug_mode is True.
+
+This test verifies that:
+1. The exec() endpoint is removed from the codebase entirely.
+2. No route matches /api/v1/system/debug/exec.
+"""
+
+import ast
+import pathlib
+
+# Resolve project root (one level up from tests/)
+_PROJECT_ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+VULN_FILE = (
+    _PROJECT_ROOT
+    / "src"
+    / "langbot"
+    / "pkg"
+    / "api"
+    / "http"
+    / "controller"
+    / "groups"
+    / "system.py"
+)
+
+
+def test_no_exec_call_in_system_controller():
+    """Verify there is no exec() call in system.py that takes user input."""
+    with open(VULN_FILE, "r") as f:
+        source = f.read()
+
+    tree = ast.parse(source)
+
+    exec_calls = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            func = node.func
+            # Match bare exec() call
+            if isinstance(func, ast.Name) and func.id == "exec":
+                exec_calls.append(node.lineno)
+
+    assert len(exec_calls) == 0, (
+        f"Found exec() call(s) at line(s) {exec_calls} in system.py. "
+        "User-supplied code must never be passed to exec()."
+    )
+
+
+def test_no_debug_exec_route():
+    """Verify the /debug/exec route is not registered."""
+    with open(VULN_FILE, "r") as f:
+        source = f.read()
+
+    assert "debug/exec" not in source, (
+        "The /debug/exec route still exists in system.py. "
+        "This endpoint allows arbitrary code execution and must be removed."
+    )
+
+
+if __name__ == "__main__":
+    test_no_exec_call_in_system_controller()
+    test_no_debug_exec_route()
+    print("All tests passed!")
--- a/tests/unit_tests/pipeline/test_aggregator.py
+++ b/tests/unit_tests/pipeline/test_aggregator.py
@@ -479,6 +479,47 @@ class TestMessageAggregatorMerge:
        assert "hello" in merged_str
        assert "world" in merged_str

+    def test_merge_messages_preserves_routed_by_rule_if_any_input_matches(self):
+        """Merged PendingMessage should keep routed_by_rule when any input was rule-routed."""
+        aggregator = get_aggregator_module()
+
+        app = make_aggregator_app()
+        agg = aggregator.MessageAggregator(app)
+
+        chain1 = text_chain("first")
+        chain2 = text_chain("second")
+        event = friend_message_event(chain1)
+        adapter = mock_adapter()
+
+        pending1 = aggregator.PendingMessage(
+            bot_uuid='test-bot',
+            launcher_type=provider_session.LauncherTypes.PERSON,
+            launcher_id=12345,
+            sender_id=12345,
+            message_event=event,
+            message_chain=chain1,
+            adapter=adapter,
+            pipeline_uuid='test-pipeline-uuid',
+            routed_by_rule=False,
+        )
+
+        pending2 = aggregator.PendingMessage(
+            bot_uuid='test-bot',
+            launcher_type=provider_session.LauncherTypes.PERSON,
+            launcher_id=12345,
+            sender_id=12345,
+            message_event=event,
+            message_chain=chain2,
+            adapter=adapter,
+            pipeline_uuid='test-pipeline-uuid',
+            routed_by_rule=True,
+        )
+
+        merged = agg._merge_messages([pending1, pending2])
+
+        assert merged.routed_by_rule is True
+        assert str(merged.message_chain) == 'first\nsecond'
+

 class TestMessageAggregatorFlush:
    """Tests for buffer flush behavior."""
@@ -594,44 +635,3 @@ class TestMessageAggregatorFlushAll:
        # Both buffers should be flushed
        assert len(agg.buffers) == 0
        assert app.query_pool.add_query.call_count == 2
-
-
-class TestMessageAggregatorMergeRoutedFlag:
-    """Tests for preserving routed message state during merge."""
-
-    def test_merge_messages_preserves_routed_by_rule_if_any_input_matches(self):
-        """Merged PendingMessage keeps routed_by_rule when any input was rule-routed."""
-        aggregator = get_aggregator_module()
-        agg = aggregator.MessageAggregator(ap=None)
-        chain1 = text_chain("first")
-        chain2 = text_chain("second")
-        event = friend_message_event(chain1)
-        adapter = mock_adapter()
-
-        pending1 = aggregator.PendingMessage(
-            bot_uuid='test-bot',
-            launcher_type=provider_session.LauncherTypes.PERSON,
-            launcher_id=12345,
-            sender_id=12345,
-            message_event=event,
-            message_chain=chain1,
-            adapter=adapter,
-            pipeline_uuid='test-pipeline',
-            routed_by_rule=False,
-        )
-        pending2 = aggregator.PendingMessage(
-            bot_uuid='test-bot',
-            launcher_type=provider_session.LauncherTypes.PERSON,
-            launcher_id=12345,
-            sender_id=12345,
-            message_event=event,
-            message_chain=chain2,
-            adapter=adapter,
-            pipeline_uuid='test-pipeline',
-            routed_by_rule=True,
-        )
-
-        merged = agg._merge_messages([pending1, pending2])
-
-        assert merged.routed_by_rule is True
-        assert str(merged.message_chain) == 'first\nsecond'
--- a/tests/unit_tests/pipeline/test_cntfilter.py
+++ b/tests/unit_tests/pipeline/test_cntfilter.py
@@ -119,10 +119,10 @@ class TestContentFilterStageInit:

        await stage.initialize(pipeline_config)

-        assert [filter_impl.name for filter_impl in stage.filter_chain] == [
+        assert {filter_impl.name for filter_impl in stage.filter_chain} == {
            'ban-word-filter',
            'content-ignore',
-        ]
+        }


 class TestPreContentFilter:
--- a/tests/unit_tests/pipeline/test_longtext.py
+++ b/tests/unit_tests/pipeline/test_longtext.py
@@ -11,7 +11,7 @@ Tests cover:
 from __future__ import annotations

 import pytest
-from unittest.mock import Mock
+from unittest.mock import AsyncMock, Mock
 from importlib import import_module

 from tests.factories import (
@@ -166,29 +166,6 @@ class TestLongTextProcessStageProcess:
        assert isinstance(components[0], platform_message.Plain)
        assert components[0].text == 'short response'

-    @pytest.mark.asyncio
-    async def test_empty_response_message_chain_continues_without_processing(self):
-        """Empty response chains should be a no-op for long text processing."""
-        longtext = get_longtext_module()
-        entities = get_entities_module()
-
-        app = FakeApp()
-        stage = longtext.LongTextProcessStage(app)
-
-        pipeline_config = make_longtext_config(strategy='forward', threshold=1)
-
-        await stage.initialize(pipeline_config)
-
-        query = text_query("hello")
-        query.pipeline_config = pipeline_config
-        query.resp_message_chain = []
-
-        result = await stage.process(query, 'LongTextProcessStage')
-
-        assert result.result_type == entities.ResultType.CONTINUE
-        assert result.new_query is query
-        assert query.resp_message_chain == []
-
    @pytest.mark.asyncio
    async def test_non_plain_component_skips(self):
        """resp_message_chain with non-Plain components should skip processing."""
@@ -223,6 +200,48 @@ class TestLongTextProcessStageProcess:
        assert components[0].text == 'short'
        assert components[1].url == 'https://example.com/img.png'

+    @pytest.mark.asyncio
+    async def test_empty_resp_message_chain(self):
+        """Empty resp_message_chain should be handled gracefully."""
+        longtext = get_longtext_module()
+        entities = get_entities_module()
+
+        app = FakeApp()
+        stage = longtext.LongTextProcessStage(app)
+
+        pipeline_config = make_longtext_config(strategy='forward')
+
+        await stage.initialize(pipeline_config)
+
+        query = text_query("hello")
+        query.pipeline_config = pipeline_config
+        query.resp_message_chain = []
+
+        result = await stage.process(query, 'LongTextProcessStage')
+
+        assert result.result_type == entities.ResultType.CONTINUE
+        assert result.new_query is query
+
+    @pytest.mark.asyncio
+    async def test_empty_response_message_chain_does_not_call_strategy(self):
+        """Empty response chains should be a no-op for long text processing."""
+        longtext = get_longtext_module()
+        entities = get_entities_module()
+
+        app = FakeApp()
+        stage = longtext.LongTextProcessStage(app)
+        stage.strategy_impl = AsyncMock()
+
+        query = text_query("hello")
+        query.pipeline_config = make_longtext_config(strategy='forward', threshold=1)
+        query.resp_message_chain = []
+
+        result = await stage.process(query, 'LongTextProcessStage')
+
+        assert result.result_type == entities.ResultType.CONTINUE
+        assert result.new_query is query
+        stage.strategy_impl.process.assert_not_called()
+
 class TestForwardStrategy:
    """Tests for ForwardComponentStrategy."""

--- a/tests/unit_tests/provider/test_requester_base.py
+++ b/tests/unit_tests/provider/test_requester_base.py
@@ -223,10 +223,8 @@ def test_token_manager_next_token_empty():
    """Test TokenManager.next_token with empty tokens doesn't error."""
    mgr = token.TokenManager(name='test', tokens=[])

-    mgr.next_token()
-
+    assert mgr.next_token() is None
    assert mgr.get_token() == ''
-    assert mgr.using_token_index == 0


 # ============================================================================
--- a/tests/unit_tests/rag/test_runtime_service.py
+++ b/tests/unit_tests/rag/test_runtime_service.py
@@ -434,6 +434,23 @@ class TestRAGRuntimeServiceGetFileStream:

            assert result == b''

+    @pytest.mark.asyncio
+    async def test_get_file_stream_normalizes_safe_path(self):
+        """Safe relative paths are normalized before loading."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            result = await service.get_file_stream('knowledge/./files/doc.pdf')
+
+            assert result == b'file content'
+            mock_app.storage_mgr.storage_provider.load.assert_called_once_with('knowledge/files/doc.pdf')
+
    @pytest.mark.asyncio
    async def test_get_file_stream_path_traversal_blocked(self):
        """Path traversal attacks are blocked."""
@@ -454,6 +471,37 @@ class TestRAGRuntimeServiceGetFileStream:
            with pytest.raises(ValueError, match='Invalid storage path'):
                await service.get_file_stream('knowledge/../../../etc/passwd')

+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        'storage_path',
+        [
+            '',
+            '../secret.txt',
+            '/absolute/path.txt',
+            '..\\secret.txt',
+            'nested\\..\\secret.txt',
+            '%2e%2e/secret.txt',
+            'nested/%2e%2e/secret.txt',
+            'C:\\secret.txt',
+            'safe/\x00file.txt',
+        ],
+    )
+    async def test_get_file_stream_rejects_unsafe_paths(self, storage_path: str):
+        """Unsafe runtime file paths are rejected before storage load."""
+        mock_app = self._create_mock_app()
+
+        mocks = self._make_rag_import_mocks()
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.rag.service.runtime import RAGRuntimeService
+
+            service = RAGRuntimeService(mock_app)
+
+            with pytest.raises(ValueError, match='Invalid storage path'):
+                await service.get_file_stream(storage_path)
+
+            mock_app.storage_mgr.storage_provider.load.assert_not_called()
+
    @pytest.mark.asyncio
    async def test_get_file_stream_normalizes_path(self):
        """Valid paths with .. in filename (not traversal) should work."""
@@ -472,50 +520,3 @@ class TestRAGRuntimeServiceGetFileStream:
            # Let's test a simple valid path
            await service.get_file_stream('knowledge/files/test.pdf')
            mock_app.storage_mgr.storage_provider.load.assert_called()
-
-    @pytest.mark.asyncio
-    async def test_get_file_stream_normalizes_safe_relative_path(self):
-        """Safe relative paths are normalized before loading."""
-        mock_app = self._create_mock_app()
-
-        mocks = self._make_rag_import_mocks()
-
-        with isolated_sys_modules(mocks):
-            from langbot.pkg.rag.service.runtime import RAGRuntimeService
-
-            service = RAGRuntimeService(mock_app)
-
-            await service.get_file_stream('knowledge/./files/doc.pdf')
-
-            mock_app.storage_mgr.storage_provider.load.assert_called_once_with('knowledge/files/doc.pdf')
-
-    @pytest.mark.asyncio
-    @pytest.mark.parametrize(
-        "storage_path",
-        [
-            "",
-            "../secret.txt",
-            "/absolute/path.txt",
-            "..\\secret.txt",
-            "nested\\..\\secret.txt",
-            "%2e%2e/secret.txt",
-            "nested/%2e%2e/secret.txt",
-            "C:\\secret.txt",
-            "safe/\x00file.txt",
-        ],
-    )
-    async def test_get_file_stream_rejects_unsafe_paths(self, storage_path):
-        """Traversal, absolute, encoded, and Windows-style paths are rejected."""
-        mock_app = self._create_mock_app()
-
-        mocks = self._make_rag_import_mocks()
-
-        with isolated_sys_modules(mocks):
-            from langbot.pkg.rag.service.runtime import RAGRuntimeService
-
-            service = RAGRuntimeService(mock_app)
-
-            with pytest.raises(ValueError, match='Invalid storage path'):
-                await service.get_file_stream(storage_path)
-
-            mock_app.storage_mgr.storage_provider.load.assert_not_called()
--- a/tests/unit_tests/utils/test_funcschema.py
+++ b/tests/unit_tests/utils/test_funcschema.py
@@ -191,19 +191,18 @@ class TestGetFuncSchema:
        assert result['parameters']['properties']['param_name']['description'] == 'This is the param description.'

    def test_missing_parameter_doc_uses_empty_description(self):
-        """Test that undocumented parameters do not crash schema generation."""
+        """Undocumented parameters should not break schema generation."""
        funcschema = get_funcschema_module()

-        def partially_documented_func(documented: str, undocumented: int):
-            """Function with one undocumented param.
+        def sample_function(documented: str, undocumented: int):
+            """Sample function.

            Args:
-                documented: Documented parameter.
+                documented(str): documented parameter description
            """
            pass

-        result = funcschema.get_func_schema(partially_documented_func)
+        result = funcschema.get_func_schema(sample_function)

-        props = result['parameters']['properties']
-        assert props['documented']['description'] == 'Documented parameter.'
-        assert props['undocumented']['description'] == ''
+        assert result['parameters']['properties']['documented']['description'] == 'documented parameter description'
+        assert result['parameters']['properties']['undocumented']['description'] == ''
--- a/tests/unit_tests/utils/test_image.py
+++ b/tests/unit_tests/utils/test_image.py
@@ -56,21 +56,29 @@ class TestGetQQImageDownloadableUrl:
        # Fragment is not included in query string parsing
        assert "http://example.com/image.jpg" in result_url

-    def test_https_url_preserves_scheme(self):
-        """Parse HTTPS URL without downgrading the scheme."""
+    def test_https_url(self):
+        """Parse HTTPS URL and preserve its scheme."""
        url = "https://example.com/image.jpg"
        result_url, query = get_qq_image_downloadable_url(url)

        assert result_url == "https://example.com/image.jpg"
        assert query == {}

-    def test_missing_scheme_defaults_to_http(self):
-        """Parse scheme-less URL with the existing HTTP default."""
-        url = "example.com/image.jpg?param=value"
-        result_url, query = get_qq_image_downloadable_url(url)
+    def test_preserves_qq_https_scheme_and_query(self):
+        """QQ image URLs keep HTTPS and query parameters."""
+        result_url, query = get_qq_image_downloadable_url(
+            'https://gchat.qpic.cn/gchatpic_new/abc/0?term=2&is_origin=1'
+        )

-        assert result_url == "http://example.com/image.jpg"
-        assert query == {"param": ["value"]}
+        assert result_url == 'https://gchat.qpic.cn/gchatpic_new/abc/0'
+        assert query == {'term': ['2'], 'is_origin': ['1']}
+
+    def test_defaults_missing_scheme_to_http(self):
+        """Scheme-less image URLs default to HTTP."""
+        result_url, query = get_qq_image_downloadable_url('gchat.qpic.cn/gchatpic_new/abc/0?term=2')
+
+        assert result_url == 'http://gchat.qpic.cn/gchatpic_new/abc/0'
+        assert query == {'term': ['2']}


 class TestExtractB64AndFormat:
--- a/tests/unit_tests/utils/test_pkgmgr.py
+++ b/tests/unit_tests/utils/test_pkgmgr.py
@@ -75,6 +75,61 @@ class TestPkgMgr:
            ]
            mock_pipmain.assert_called_once_with(expected_args)

+    def test_install_requirements_defaults_extra_params_to_none(self):
+        """install_requirements should not use a mutable default for extra_params."""
+        signature = inspect.signature(pkgmgr.install_requirements)
+
+        assert signature.parameters['extra_params'].default is None
+
+    def test_install_requirements_omitted_extra_params_uses_independent_base_commands(self, monkeypatch):
+        """Omitted extra_params should not share mutable state across calls."""
+        calls = []
+        monkeypatch.setattr(pkgmgr, 'pipmain', calls.append)
+
+        pkgmgr.install_requirements('requirements.txt')
+        pkgmgr.install_requirements('requirements-dev.txt')
+
+        assert calls == [
+            [
+                'install',
+                '-r',
+                'requirements.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+            ],
+            [
+                'install',
+                '-r',
+                'requirements-dev.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+            ],
+        ]
+
+    def test_install_requirements_preserves_explicit_extra_params(self, monkeypatch):
+        """Explicit extra_params should be appended to the generated pip command."""
+        calls = []
+        monkeypatch.setattr(pkgmgr, 'pipmain', calls.append)
+
+        pkgmgr.install_requirements('requirements.txt', extra_params=['--no-deps'])
+
+        assert calls == [
+            [
+                'install',
+                '-r',
+                'requirements.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+                '--no-deps',
+            ]
+        ]
+
    def test_install_requirements_with_extra_params(self):
        """install_requirements handles extra params."""
        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
@@ -100,34 +155,3 @@ class TestPkgMgr:
            call_args = mock_pipmain.call_args[0][0]
            assert '--no-cache-dir' in call_args
            assert '--verbose' in call_args
-
-    def test_install_requirements_defaults_extra_params_to_none(self):
-        """install_requirements does not use a mutable list default."""
-        signature = inspect.signature(pkgmgr.install_requirements)
-
-        assert signature.parameters['extra_params'].default is None
-
-    def test_install_requirements_omitted_extra_params_are_isolated(self):
-        """Repeated calls without extra_params use independent base commands."""
-        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
-            pkgmgr.install_requirements('requirements.txt')
-            pkgmgr.install_requirements('requirements-dev.txt')
-
-            assert mock_pipmain.call_args_list[0].args[0] == [
-                'install',
-                '-r',
-                'requirements.txt',
-                '-i',
-                'https://pypi.tuna.tsinghua.edu.cn/simple',
-                '--trusted-host',
-                'pypi.tuna.tsinghua.edu.cn',
-            ]
-            assert mock_pipmain.call_args_list[1].args[0] == [
-                'install',
-                '-r',
-                'requirements-dev.txt',
-                '-i',
-                'https://pypi.tuna.tsinghua.edu.cn/simple',
-                '--trusted-host',
-                'pypi.tuna.tsinghua.edu.cn',
-            ]
--- a/tests/unit_tests/utils/test_runner.py
+++ b/tests/unit_tests/utils/test_runner.py
@@ -87,6 +87,22 @@ class TestGetRunnerCategory:
        assert get_runner_category("test", "https://example.com") == RunnerCategory.CLOUD
        assert get_runner_category("test", "https://myserver.example.org") == RunnerCategory.CLOUD

+    @pytest.mark.parametrize(
+        'runner_url',
+        [
+            'api.dify.ai/v1',
+            'localhost:7860',
+            'https:///v1',
+            'https://',
+            'https://exa mple.com',
+            'http://[::1',
+            'http://localhost:bad',
+        ],
+    )
+    def test_invalid_urls_return_unknown(self, runner_url):
+        """Invalid or incomplete URLs should return UNKNOWN."""
+        assert get_runner_category("test", runner_url) == RunnerCategory.UNKNOWN
+
    def test_urlparse_exception_returns_unknown(self):
        """Exception during URL parsing should return UNKNOWN."""
        # Test by mocking urlparse to raise an exception
@@ -99,49 +115,36 @@ class TestGetRunnerCategory:
            result = runner.get_runner_category("test", "http://example.com")
            assert result == RunnerCategory.UNKNOWN

-    @pytest.mark.parametrize(
-        "runner_url",
-        [
-            "api.dify.ai/v1",
-            "localhost:7860",
-            "https:///v1",
-            "https://",
-            "https://exa mple.com",
-            "http://[::1",
-            "http://localhost:bad",
-        ],
-    )
-    def test_invalid_urls_return_unknown(self, runner_url):
-        """Invalid or scheme-less URLs should not default to CLOUD."""
-        assert get_runner_category("test", runner_url) == RunnerCategory.UNKNOWN
+    def test_url_without_scheme_returns_unknown(self):
+        """URL without scheme should return UNKNOWN."""
+        assert get_runner_category("test", "example.com") == RunnerCategory.UNKNOWN

    @pytest.mark.parametrize(
-        "runner_url",
+        'runner_url',
        [
-            "http://localhost:7860",
-            "http://127.0.0.1:7860",
-            "http://10.0.0.1:7860",
-            "http://172.16.0.1:7860",
-            "http://172.31.255.255:7860",
-            "http://192.168.1.20:7860",
-            "http://[::1]:7860",
+            'http://localhost:7860',
+            'http://127.0.0.1:7860',
+            'http://10.0.0.1:7860',
+            'http://172.16.0.1:7860',
+            'http://172.31.255.255:7860',
+            'http://192.168.1.20:7860',
+            'http://[::1]:7860',
        ],
    )
-    def test_local_hosts_are_detected_with_ipaddress(self, runner_url):
-        """Loopback/private IP addresses and localhost should be LOCAL."""
-        assert get_runner_category("test", runner_url) == RunnerCategory.LOCAL
+    def test_detects_local_hosts_with_ipaddress(self, runner_url):
+        """Local hostnames and private IPs should be categorized as LOCAL."""
+        assert get_runner_category('langflow-api', runner_url) == RunnerCategory.LOCAL

    @pytest.mark.parametrize(
-        "runner_url",
+        'runner_url',
        [
-            "http://10.evil.com",
-            "http://192.168.example.com",
+            'http://10.evil.com',
+            'http://192.168.example.com',
        ],
    )
    def test_private_ip_prefix_domains_are_not_local(self, runner_url):
        """Domain names that only look like private IP prefixes should not be LOCAL."""
-        assert get_runner_category("test", runner_url) == RunnerCategory.CLOUD
-
+        assert get_runner_category('langflow-api', runner_url) == RunnerCategory.CLOUD

 class TestIsCloudRunner:
    """Test is_cloud_runner helper function."""
--- a/web/src/app/home/components/home-sidebar/HomeSidebar.tsx
+++ b/web/src/app/home/components/home-sidebar/HomeSidebar.tsx
@@ -338,7 +338,9 @@ function NavItems({
                tooltip={config.name}
              >
                {config.icon}
-                <span>{config.name}</span>
+                <span className="cursor-pointer select-none">
+                  {config.name}
+                </span>
              </SidebarMenuButton>
            </SidebarMenuItem>
          );
@@ -728,7 +730,9 @@ function NavItems({
                  }}
                >
                  {config.icon}
-                  <span>{config.name}</span>
+                  <span className="cursor-pointer select-none">
+                    {config.name}
+                  </span>
                  <div className="ml-auto flex items-center gap-0.5 -mr-1">
                    {canCreate &&
                      (isPlugin ? (
@@ -1108,7 +1112,7 @@ function PluginPagesNav() {
                      className="select-none"
                    >
                      {pluginIcon}
-                      <span>{page.name}</span>
+                      <span className="cursor-pointer">{page.name}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                );
@@ -1128,7 +1132,7 @@ function PluginPagesNav() {
                        className="select-none"
                      >
                        {pluginIcon}
-                        <span>{label}</span>
+                        <span className="cursor-pointer">{label}</span>
                        <ChevronRight className="ml-auto size-4 transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
                      </SidebarMenuButton>
                    </CollapsibleTrigger>
@@ -1144,7 +1148,9 @@ function PluginPagesNav() {
                                onClick={() => navigate(route)}
                                className="select-none"
                              >
-                                <span>{page.name}</span>
+                                <span className="cursor-pointer">
+                                  {page.name}
+                                </span>
                              </SidebarMenuSubButton>
                            </SidebarMenuSubItem>
                          );
--- a/web/src/app/home/components/models-dialog/ModelsDialog.tsx
+++ b/web/src/app/home/components/models-dialog/ModelsDialog.tsx
@@ -295,7 +295,7 @@ export default function ModelsDialog({

  async function handleScanModels(
    providerUuid: string,
-    modelType: ModelType,
+    modelType?: ModelType,
  ): Promise<ScanModelsResult> {
    try {
      const resp = await httpClient.scanProviderModels(providerUuid, modelType);
@@ -319,19 +319,26 @@ export default function ModelsDialog({
    setIsSubmitting(true);
    try {
      for (const item of models) {
-        if (modelType === 'llm') {
+        const effectiveType = item.model.type || modelType;
+        if (effectiveType === 'llm') {
          await httpClient.createProviderLLMModel({
            name: item.model.name,
            provider_uuid: providerUuid,
            abilities: item.abilities,
            extra_args: {},
          } as never);
-        } else {
+        } else if (effectiveType === 'embedding') {
          await httpClient.createProviderEmbeddingModel({
            name: item.model.name,
            provider_uuid: providerUuid,
            extra_args: {},
          } as never);
+        } else {
+          await httpClient.createProviderRerankModel({
+            name: item.model.name,
+            provider_uuid: providerUuid,
+            extra_args: {},
+          } as never);
        }
      }
      setAddModelPopoverOpen(null);
--- a/web/src/app/home/components/models-dialog/component/provider-form/ProviderForm.tsx
+++ b/web/src/app/home/components/models-dialog/component/provider-form/ProviderForm.tsx
@@ -73,10 +73,13 @@ export default function ProviderForm({
  >([]);

  useEffect(() => {
-    loadRequesters();
-    if (providerId) {
-      loadProvider(providerId);
+    async function init() {
+      await loadRequesters();
+      if (providerId) {
+        await loadProvider(providerId);
+      }
    }
+    init();
  }, [providerId]);

  async function loadRequesters() {
--- a/web/src/app/home/components/models-dialog/components/AddModelPopover.tsx
+++ b/web/src/app/home/components/models-dialog/components/AddModelPopover.tsx
@@ -8,7 +8,6 @@ import {
  Wrench,
  Check,
  RefreshCw,
-  Search,
 } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -33,6 +32,8 @@ import ExtraArgsEditor from './ExtraArgsEditor';

 interface AddModelPopoverProps {
  isOpen: boolean;
+  initialMode?: 'manual' | 'scan';
+  trigger?: React.ReactNode;
  onOpen: () => void;
  onClose: () => void;
  onAddModel: (
@@ -41,7 +42,7 @@ interface AddModelPopoverProps {
    abilities: string[],
    extraArgs: ExtraArg[],
  ) => Promise<void>;
-  onScanModels: (modelType: ModelType) => Promise<ScanModelsResult>;
+  onScanModels: (modelType?: ModelType) => Promise<ScanModelsResult>;
  onAddScannedModels: (
    modelType: ModelType,
    models: SelectedScannedModel[],
@@ -60,6 +61,8 @@ interface AddModelPopoverProps {

 export default function AddModelPopover({
  isOpen,
+  initialMode = 'manual',
+  trigger,
  onOpen,
  onClose,
  onAddModel,
@@ -92,7 +95,7 @@ export default function AddModelPopover({
    const wasOpen = prevIsOpenRef.current;
    if (isOpen && !wasOpen) {
      setTab('llm');
-      setMode('manual');
+      setMode(initialMode);
      setName('');
      setAbilities([]);
      setExtraArgs([]);
@@ -101,8 +104,12 @@ export default function AddModelPopover({
      setSelectedScannedModels({});
      setScanQuery('');
      onResetTestResult();
+      if (initialMode === 'scan') {
+        handleScan();
+      }
    }
    prevIsOpenRef.current = isOpen;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [isOpen, onResetTestResult]);

  useEffect(() => {
@@ -122,9 +129,8 @@ export default function AddModelPopover({
  const handleScan = async () => {
    setScanLoading(true);
    try {
-      const result = await onScanModels(tab);
+      const result = await onScanModels(trigger ? undefined : tab);

-      // Enrich abilities from debug.response.data (e.g. features.tools.function_calling)
      const debugData = (
        result.debug?.response as { data?: Record<string, unknown>[] }
      )?.data;
@@ -143,9 +149,9 @@ export default function AddModelPopover({
            | undefined;
          const tools = features?.tools as Record<string, unknown> | undefined;
          if (tools?.function_calling === true) {
-            const abilities = new Set(model.abilities || []);
-            abilities.add('func_call');
-            model.abilities = [...abilities];
+            const nextAbilities = new Set(model.abilities || []);
+            nextAbilities.add('func_call');
+            model.abilities = [...nextAbilities];
          }
        }
      }
@@ -247,305 +253,321 @@ export default function AddModelPopover({
      onOpenChange={(open) => (open ? onOpen() : onClose())}
    >
      <PopoverTrigger asChild>
-        <Button
-          variant="ghost"
-          size="sm"
-          className="h-6 text-xs"
-          onClick={(e) => e.stopPropagation()}
-        >
-          <Plus className="h-3 w-3 mr-1" />
-          {t('models.addModel')}
-        </Button>
+        {trigger || (
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-6 text-xs"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Plus className="h-3 w-3 mr-1" />
+            {t('models.addModel')}
+          </Button>
+        )}
      </PopoverTrigger>
      <PopoverContent
-        className="w-[min(24rem,calc(100vw-2rem))] max-h-[70vh] overflow-y-auto overscroll-none focus:outline-none focus-visible:outline-none focus-visible:ring-0"
-        style={{
-          maxHeight: 'min(70vh, var(--radix-popover-content-available-height))',
-        }}
+        className="w-[min(24rem,calc(100vw-2rem))] max-h-[calc(100vh-8rem)] flex flex-col overflow-hidden"
        align="end"
-        side="left"
+        side="bottom"
        sideOffset={8}
        collisionPadding={16}
-        onWheel={(e) => e.stopPropagation()}
-        onTouchMove={(e) => e.stopPropagation()}
        onClick={(e) => e.stopPropagation()}
      >
-        <Tabs value={tab} onValueChange={(v) => setTab(v as ModelType)}>
-          <TabsList className="grid w-full grid-cols-3">
-            <TabsTrigger value="llm">
-              <MessageSquareText className="h-4 w-4 mr-1" />
-              {t('models.chat')}
-            </TabsTrigger>
-            <TabsTrigger value="embedding">
-              <Cpu className="h-4 w-4 mr-1" />
-              {t('models.embedding')}
-            </TabsTrigger>
-            <TabsTrigger value="rerank">
-              <ArrowUpDown className="h-4 w-4 mr-1" />
-              {t('models.rerank')}
-            </TabsTrigger>
-          </TabsList>
+        <Tabs
+          value={tab}
+          onValueChange={(v) => setTab(v as ModelType)}
+          className="flex flex-col min-h-0 flex-1"
+        >
+          <div className="flex-shrink-0">
+            {!(trigger && initialMode === 'scan') && (
+              <TabsList className="grid w-full grid-cols-3">
+                <TabsTrigger value="llm">
+                  <MessageSquareText className="h-4 w-4 mr-1" />
+                  {t('models.chat')}
+                </TabsTrigger>
+                <TabsTrigger value="embedding">
+                  <Cpu className="h-4 w-4 mr-1" />
+                  {t('models.embedding')}
+                </TabsTrigger>
+                <TabsTrigger value="rerank">
+                  <ArrowUpDown className="h-4 w-4 mr-1" />
+                  {t('models.rerank')}
+                </TabsTrigger>
+              </TabsList>
+            )}
+          </div>

-          <Tabs
-            value={mode}
-            onValueChange={(v) => setMode(v as 'manual' | 'scan')}
-          >
-            <TabsList className="grid w-full grid-cols-2 mt-3">
-              <TabsTrigger value="manual">{t('models.manualAdd')}</TabsTrigger>
-              <TabsTrigger value="scan">{t('models.scanAdd')}</TabsTrigger>
-            </TabsList>
+          <div className="overflow-y-auto flex-1 min-h-0">
+            <Tabs
+              value={mode}
+              onValueChange={(v) => setMode(v as 'manual' | 'scan')}
+            >
+              {!trigger && (
+                <TabsList className="grid w-full grid-cols-2 mt-3">
+                  <TabsTrigger value="manual">
+                    {t('models.manualAdd')}
+                  </TabsTrigger>
+                  <TabsTrigger value="scan">{t('models.scanAdd')}</TabsTrigger>
+                </TabsList>
+              )}

-            <TabsContent value="manual" className="mt-3">
-              <div className="space-y-3">
-                <div className="space-y-2">
-                  <Label>{t('models.modelName')}</Label>
-                  <Input
-                    placeholder={t('models.modelName')}
-                    value={name}
-                    onChange={(e) => setName(e.target.value)}
-                  />
-                </div>
-
-                {tab === 'llm' && (
+              <TabsContent value="manual" className="mt-3">
+                <div className="space-y-3">
                  <div className="space-y-2">
-                    <Label>{t('models.abilities')}</Label>
-                    <div className="flex gap-4">
-                      <div className="flex items-center gap-2">
-                        <Checkbox
-                          id="add-vision"
-                          checked={abilities.includes('vision')}
-                          onCheckedChange={(checked) =>
-                            toggleAbility('vision', checked as boolean)
-                          }
-                        />
-                        <Label htmlFor="add-vision" className="text-sm">
-                          <Eye className="h-3 w-3 inline mr-1" />
-                          {t('models.visionAbility')}
-                        </Label>
-                      </div>
-                      <div className="flex items-center gap-2">
-                        <Checkbox
-                          id="add-func-call"
-                          checked={abilities.includes('func_call')}
-                          onCheckedChange={(checked) =>
-                            toggleAbility('func_call', checked as boolean)
-                          }
-                        />
-                        <Label htmlFor="add-func-call" className="text-sm">
-                          <Wrench className="h-3 w-3 inline mr-1" />
-                          {t('models.functionCallAbility')}
-                        </Label>
+                    <Label>{t('models.modelName')}</Label>
+                    <Input
+                      placeholder={t('models.modelName')}
+                      value={name}
+                      onChange={(e) => setName(e.target.value)}
+                    />
+                  </div>
+
+                  {tab === 'llm' && (
+                    <div className="space-y-2">
+                      <Label>{t('models.abilities')}</Label>
+                      <div className="flex gap-4">
+                        <div className="flex items-center gap-2">
+                          <Checkbox
+                            id="add-vision"
+                            checked={abilities.includes('vision')}
+                            onCheckedChange={(checked) =>
+                              toggleAbility('vision', checked as boolean)
+                            }
+                          />
+                          <Label htmlFor="add-vision" className="text-sm">
+                            <Eye className="h-3 w-3 inline mr-1" />
+                            {t('models.visionAbility')}
+                          </Label>
+                        </div>
+                        <div className="flex items-center gap-2">
+                          <Checkbox
+                            id="add-func-call"
+                            checked={abilities.includes('func_call')}
+                            onCheckedChange={(checked) =>
+                              toggleAbility('func_call', checked as boolean)
+                            }
+                          />
+                          <Label htmlFor="add-func-call" className="text-sm">
+                            <Wrench className="h-3 w-3 inline mr-1" />
+                            {t('models.functionCallAbility')}
+                          </Label>
+                        </div>
                      </div>
                    </div>
+                  )}
+
+                  <ExtraArgsEditor
+                    args={extraArgs}
+                    onChange={setExtraArgs}
+                    modelType={tab}
+                  />
+                  <div className="flex gap-2">
+                    <Button
+                      className="flex-1"
+                      size="sm"
+                      onClick={handleAdd}
+                      disabled={isSubmitting || isTesting}
+                    >
+                      {isSubmitting ? t('common.saving') : t('common.add')}
+                    </Button>
+                    <Button
+                      className="flex-1"
+                      size="sm"
+                      variant="outline"
+                      onClick={handleTest}
+                      disabled={isSubmitting || isTesting}
+                    >
+                      {isTesting ? (
+                        t('common.loading')
+                      ) : testResult?.success ? (
+                        <>
+                          <Check className="h-4 w-4 mr-1 text-green-500" />
+                          {(testResult.duration / 1000).toFixed(1)}s
+                        </>
+                      ) : (
+                        t('common.test')
+                      )}
+                    </Button>
                  </div>
+                </div>
+              </TabsContent>
+
+              <TabsContent value="scan" className="space-y-2 mt-0 pt-0">
+                {scanLoading ? (
+                  <div className="flex items-center justify-center py-4">
+                    <RefreshCw className="h-4 w-4 mr-2 animate-spin text-muted-foreground" />
+                    <span className="text-sm text-muted-foreground">
+                      {t('models.scanModels')}...
+                    </span>
+                  </div>
+                ) : (
+                  <>
+                    <div className="space-y-2">
+                      <Input
+                        placeholder={t('models.searchScannedModels')}
+                        value={scanQuery}
+                        onChange={(e) => setScanQuery(e.target.value)}
+                        disabled={scannedModels.length === 0}
+                      />
+                      {selectableModels.length > 0 && (
+                        <div className="flex items-center gap-2 pt-1">
+                          <Checkbox
+                            id="scan-select-all"
+                            checked={allSelected}
+                            onCheckedChange={toggleSelectAll}
+                          />
+                          <Label
+                            htmlFor="scan-select-all"
+                            className="text-sm font-medium"
+                          >
+                            {t('models.selectAll')}
+                            <span className="text-muted-foreground ml-1">
+                              ({Object.keys(selectedScannedModels).length}/
+                              {selectableModels.length})
+                            </span>
+                          </Label>
+                        </div>
+                      )}
+                    </div>
+
+                    <div
+                      className="h-64 overflow-y-auto overscroll-contain rounded-md border"
+                      onWheel={(e) => e.stopPropagation()}
+                    >
+                      <div className="p-3 space-y-2">
+                        {filteredScannedModels.length === 0 ? (
+                          <p className="text-sm text-muted-foreground">
+                            {scannedModels.length === 0
+                              ? t('models.noScannedModels')
+                              : t('models.noScannedModelsMatch')}
+                          </p>
+                        ) : (
+                          filteredScannedModels.map((model) => {
+                            const isSelected = Boolean(
+                              selectedScannedModels[model.id],
+                            );
+                            const selectedAbilities =
+                              selectedScannedModels[model.id]?.abilities || [];
+                            return (
+                              <div
+                                key={model.id}
+                                className="rounded-md border p-3 space-y-2"
+                              >
+                                <div className="flex items-start gap-3">
+                                  <Checkbox
+                                    checked={isSelected || model.already_added}
+                                    disabled={model.already_added}
+                                    onCheckedChange={(checked) =>
+                                      toggleScannedModel(
+                                        model,
+                                        checked as boolean,
+                                      )
+                                    }
+                                  />
+                                  <div className="min-w-0 flex-1">
+                                    <div className="text-sm font-medium break-all">
+                                      {model.name}
+                                    </div>
+                                    <div className="text-xs text-muted-foreground">
+                                      {model.already_added
+                                        ? t('models.alreadyAdded')
+                                        : model.type === 'llm'
+                                          ? t('models.chat')
+                                          : model.type === 'embedding'
+                                            ? t('models.embedding')
+                                            : t('models.rerank')}
+                                    </div>
+                                  </div>
+                                </div>
+
+                                {model.type === 'llm' &&
+                                  isSelected &&
+                                  !model.already_added && (
+                                    <div className="flex gap-4 pl-7">
+                                      <div className="flex items-center gap-2">
+                                        <Checkbox
+                                          id={`scan-vision-${model.id}`}
+                                          checked={selectedAbilities.includes(
+                                            'vision',
+                                          )}
+                                          onCheckedChange={(checked) =>
+                                            toggleScannedModelAbility(
+                                              model.id,
+                                              'vision',
+                                              checked as boolean,
+                                            )
+                                          }
+                                        />
+                                        <Label
+                                          htmlFor={`scan-vision-${model.id}`}
+                                          className="text-sm"
+                                        >
+                                          <Eye className="h-3 w-3 inline mr-1" />
+                                          {t('models.visionAbility')}
+                                        </Label>
+                                      </div>
+                                      <div className="flex items-center gap-2">
+                                        <Checkbox
+                                          id={`scan-func-${model.id}`}
+                                          checked={selectedAbilities.includes(
+                                            'func_call',
+                                          )}
+                                          onCheckedChange={(checked) =>
+                                            toggleScannedModelAbility(
+                                              model.id,
+                                              'func_call',
+                                              checked as boolean,
+                                            )
+                                          }
+                                        />
+                                        <Label
+                                          htmlFor={`scan-func-${model.id}`}
+                                          className="text-sm"
+                                        >
+                                          <Wrench className="h-3 w-3 inline mr-1" />
+                                          {t('models.functionCallAbility')}
+                                        </Label>
+                                      </div>
+                                    </div>
+                                  )}
+                              </div>
+                            );
+                          })
+                        )}
+                      </div>
+                    </div>
+                  </>
                )}

-                <ExtraArgsEditor
-                  args={extraArgs}
-                  onChange={setExtraArgs}
-                  modelType={tab}
-                />
                <div className="flex gap-2">
                  <Button
                    className="flex-1"
                    size="sm"
-                    onClick={handleAdd}
-                    disabled={isSubmitting || isTesting}
+                    onClick={handleAddScanned}
+                    disabled={
+                      isSubmitting ||
+                      scanLoading ||
+                      Object.keys(selectedScannedModels).length === 0
+                    }
                  >
-                    {isSubmitting ? t('common.saving') : t('common.add')}
+                    {isSubmitting
+                      ? t('common.saving')
+                      : t('models.addSelectedModels')}
                  </Button>
                  <Button
-                    className="flex-1"
-                    size="sm"
                    variant="outline"
-                    onClick={handleTest}
-                    disabled={isSubmitting || isTesting}
+                    size="sm"
+                    onClick={handleScan}
+                    disabled={scanLoading || isSubmitting}
                  >
-                    {isTesting ? (
-                      t('common.loading')
-                    ) : testResult?.success ? (
-                      <>
-                        <Check className="h-4 w-4 mr-1 text-green-500" />
-                        {(testResult.duration / 1000).toFixed(1)}s
-                      </>
-                    ) : (
-                      t('common.test')
-                    )}
+                    <RefreshCw
+                      className={`h-3.5 w-3.5 ${scanLoading ? 'animate-spin' : ''}`}
+                    />
                  </Button>
                </div>
-              </div>
-            </TabsContent>
-
-            <TabsContent value="scan" className="space-y-3 mt-3">
-              <div className="text-xs text-muted-foreground">
-                {t('models.scanModelsHint')}
-              </div>
-
-              <div className="flex gap-2">
-                <Button
-                  className="flex-1"
-                  size="sm"
-                  variant="outline"
-                  onClick={handleScan}
-                  disabled={scanLoading || isSubmitting}
-                >
-                  {scanLoading ? (
-                    <RefreshCw className="h-4 w-4 mr-1 animate-spin" />
-                  ) : (
-                    <Search className="h-4 w-4 mr-1" />
-                  )}
-                  {t('models.scanModels')}
-                </Button>
-                <Button
-                  className="flex-1"
-                  size="sm"
-                  onClick={handleAddScanned}
-                  disabled={
-                    isSubmitting ||
-                    scanLoading ||
-                    Object.keys(selectedScannedModels).length === 0
-                  }
-                >
-                  {isSubmitting
-                    ? t('common.saving')
-                    : t('models.addSelectedModels')}
-                </Button>
-              </div>
-
-              <div className="space-y-2">
-                <Label>{t('models.scannedModels')}</Label>
-                <Input
-                  placeholder={t('models.searchScannedModels')}
-                  value={scanQuery}
-                  onChange={(e) => setScanQuery(e.target.value)}
-                  disabled={scannedModels.length === 0}
-                />
-                {selectableModels.length > 0 && (
-                  <div className="flex items-center gap-2 pt-1">
-                    <Checkbox
-                      id="scan-select-all"
-                      checked={allSelected}
-                      onCheckedChange={toggleSelectAll}
-                    />
-                    <Label
-                      htmlFor="scan-select-all"
-                      className="text-sm font-medium"
-                    >
-                      {t('models.selectAll')}
-                      <span className="text-muted-foreground ml-1">
-                        ({Object.keys(selectedScannedModels).length}/
-                        {selectableModels.length})
-                      </span>
-                    </Label>
-                  </div>
-                )}
-              </div>
-
-              <div
-                className="h-64 overflow-y-auto overscroll-none rounded-md border"
-                onWheel={(e) => e.stopPropagation()}
-              >
-                <div className="p-3 space-y-2">
-                  {filteredScannedModels.length === 0 ? (
-                    <p className="text-sm text-muted-foreground">
-                      {scannedModels.length === 0
-                        ? t('models.noScannedModels')
-                        : t('models.noScannedModelsMatch')}
-                    </p>
-                  ) : (
-                    filteredScannedModels.map((model) => {
-                      const isSelected = Boolean(
-                        selectedScannedModels[model.id],
-                      );
-                      const selectedAbilities =
-                        selectedScannedModels[model.id]?.abilities || [];
-                      return (
-                        <div
-                          key={model.id}
-                          className="rounded-md border p-3 space-y-2"
-                        >
-                          <div className="flex items-start gap-3">
-                            <Checkbox
-                              checked={isSelected || model.already_added}
-                              disabled={model.already_added}
-                              onCheckedChange={(checked) =>
-                                toggleScannedModel(model, checked as boolean)
-                              }
-                            />
-                            <div className="min-w-0 flex-1">
-                              <div className="text-sm font-medium break-all">
-                                {model.name}
-                              </div>
-                              <div className="text-xs text-muted-foreground">
-                                {model.already_added
-                                  ? t('models.alreadyAdded')
-                                  : model.type === 'llm'
-                                    ? t('models.chat')
-                                    : model.type === 'embedding'
-                                      ? t('models.embedding')
-                                      : t('models.rerank')}
-                              </div>
-                            </div>
-                          </div>
-
-                          {tab === 'llm' &&
-                            isSelected &&
-                            !model.already_added && (
-                              <div className="flex gap-4 pl-7">
-                                <div className="flex items-center gap-2">
-                                  <Checkbox
-                                    id={`scan-vision-${model.id}`}
-                                    checked={selectedAbilities.includes(
-                                      'vision',
-                                    )}
-                                    onCheckedChange={(checked) =>
-                                      toggleScannedModelAbility(
-                                        model.id,
-                                        'vision',
-                                        checked as boolean,
-                                      )
-                                    }
-                                  />
-                                  <Label
-                                    htmlFor={`scan-vision-${model.id}`}
-                                    className="text-sm"
-                                  >
-                                    <Eye className="h-3 w-3 inline mr-1" />
-                                    {t('models.visionAbility')}
-                                  </Label>
-                                </div>
-                                <div className="flex items-center gap-2">
-                                  <Checkbox
-                                    id={`scan-func-${model.id}`}
-                                    checked={selectedAbilities.includes(
-                                      'func_call',
-                                    )}
-                                    onCheckedChange={(checked) =>
-                                      toggleScannedModelAbility(
-                                        model.id,
-                                        'func_call',
-                                        checked as boolean,
-                                      )
-                                    }
-                                  />
-                                  <Label
-                                    htmlFor={`scan-func-${model.id}`}
-                                    className="text-sm"
-                                  >
-                                    <Wrench className="h-3 w-3 inline mr-1" />
-                                    {t('models.functionCallAbility')}
-                                  </Label>
-                                </div>
-                              </div>
-                            )}
-                        </div>
-                      );
-                    })
-                  )}
-                </div>
-              </div>
-            </TabsContent>
-          </Tabs>
+              </TabsContent>
+            </Tabs>
+          </div>
        </Tabs>
      </PopoverContent>
    </Popover>
--- a/web/src/app/home/components/models-dialog/components/ProviderCard.tsx
+++ b/web/src/app/home/components/models-dialog/components/ProviderCard.tsx
@@ -6,6 +6,7 @@ import {
  Trash2,
  Settings,
  LogIn,
+  Radar,
 } from 'lucide-react';
 import { httpClient, systemInfo } from '@/app/infra/http/HttpClient';
 import { ModelProvider } from '@/app/infra/entities/api';
@@ -60,7 +61,7 @@ interface ProviderCardProps {
    abilities: string[],
    extraArgs: ExtraArg[],
  ) => Promise<void>;
-  onScanModels: (modelType: ModelType) => Promise<ScanModelsResult>;
+  onScanModels: (modelType?: ModelType) => Promise<ScanModelsResult>;
  onAddScannedModels: (
    modelType: ModelType,
    models: SelectedScannedModel[],
@@ -130,6 +131,7 @@ export default function ProviderCard({
  const { t } = useTranslation();
  const [deleteProviderConfirmOpen, setDeleteProviderConfirmOpen] =
    useState(false);
+  const [addModelMode, setAddModelMode] = useState<'manual' | 'scan'>('manual');

  const canDelete =
    !isLangBotModels &&
@@ -310,19 +312,75 @@ export default function ProviderCard({
              <div />
            )}
            {!isLangBotModels && (
-              <AddModelPopover
-                isOpen={addModelPopoverOpen === provider.uuid}
-                onOpen={onOpenAddModel}
-                onClose={onCloseAddModel}
-                onAddModel={onAddModel}
-                onScanModels={onScanModels}
-                onAddScannedModels={onAddScannedModels}
-                onTestModel={onTestModel}
-                isSubmitting={isSubmitting}
-                isTesting={isTesting}
-                testResult={testResult}
-                onResetTestResult={onResetTestResult}
-              />
+              <div className="flex items-center gap-1">
+                <AddModelPopover
+                  isOpen={
+                    addModelPopoverOpen === provider.uuid &&
+                    addModelMode === 'manual'
+                  }
+                  initialMode="manual"
+                  trigger={
+                    <Button
+                      variant="ghost"
+                      size="sm"
+                      className="h-6 text-xs"
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        setAddModelMode('manual');
+                      }}
+                    >
+                      <Plus className="h-3 w-3 mr-1" />
+                      {t('models.addModel')}
+                    </Button>
+                  }
+                  onOpen={() => {
+                    setAddModelMode('manual');
+                    onOpenAddModel();
+                  }}
+                  onClose={onCloseAddModel}
+                  onAddModel={onAddModel}
+                  onScanModels={onScanModels}
+                  onAddScannedModels={onAddScannedModels}
+                  onTestModel={onTestModel}
+                  isSubmitting={isSubmitting}
+                  isTesting={isTesting}
+                  testResult={testResult}
+                  onResetTestResult={onResetTestResult}
+                />
+                <AddModelPopover
+                  isOpen={
+                    addModelPopoverOpen === provider.uuid &&
+                    addModelMode === 'scan'
+                  }
+                  initialMode="scan"
+                  trigger={
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="h-6 w-6"
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        setAddModelMode('scan');
+                      }}
+                    >
+                      <Radar className="h-3 w-3" />
+                    </Button>
+                  }
+                  onOpen={() => {
+                    setAddModelMode('scan');
+                    onOpenAddModel();
+                  }}
+                  onClose={onCloseAddModel}
+                  onAddModel={onAddModel}
+                  onScanModels={onScanModels}
+                  onAddScannedModels={onAddScannedModels}
+                  onTestModel={onTestModel}
+                  isSubmitting={isSubmitting}
+                  isTesting={isTesting}
+                  testResult={testResult}
+                  onResetTestResult={onResetTestResult}
+                />
+              </div>
            )}
          </div>
        </CardHeader>
--- a/web/src/app/home/components/models-dialog/types.ts
+++ b/web/src/app/home/components/models-dialog/types.ts
@@ -90,7 +90,7 @@ export interface ProviderCardProps {
    abilities: string[],
    extraArgs: ExtraArg[],
  ) => Promise<void>;
-  onScanModels: (modelType: ModelType) => Promise<ScanModelsResult>;
+  onScanModels: (modelType?: ModelType) => Promise<ScanModelsResult>;
  onAddScannedModels: (
    modelType: ModelType,
    models: SelectedScannedModel[],
--- a/web/src/app/home/components/qrcode-login/QrCodeLoginDialog.tsx
+++ b/web/src/app/home/components/qrcode-login/QrCodeLoginDialog.tsx
@@ -4,11 +4,16 @@ import {
  DialogContent,
  DialogHeader,
  DialogTitle,
-  DialogFooter,
 } from '@/components/ui/dialog';
 import { Button } from '@/components/ui/button';
 import { useTranslation } from 'react-i18next';
-import { Loader2, RefreshCw, CheckCircle2, XCircle } from 'lucide-react';
+import {
+  Loader2,
+  RefreshCw,
+  RotateCw,
+  CheckCircle2,
+  XCircle,
+} from 'lucide-react';
 import QRCode from 'qrcode';

 export type QrLoginPlatform = 'feishu' | 'weixin' | 'dingtalk' | 'wecombot';
@@ -96,7 +101,7 @@ interface QrCodeLoginDialogProps {
  onSuccess: (credentials: Record<string, string>) => void;
 }

-type DialogState = 'connecting' | 'waiting' | 'success' | 'error';
+type DialogState = 'connecting' | 'waiting' | 'expired' | 'success' | 'error';

 const POLL_INTERVAL_MS = 3000;

@@ -115,8 +120,10 @@ export default function QrCodeLoginDialog({
  const [errorMessage, setErrorMessage] = useState('');
  const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
  const countdownRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const checkExpiredRef = useRef<ReturnType<typeof setInterval> | null>(null);
  const abortRef = useRef<AbortController | null>(null);
  const sessionIdRef = useRef<string | null>(null);
+  const baseUrlRef = useRef('');
  const cleanedRef = useRef(false);

  const onSuccessRef = useRef(onSuccess);
@@ -140,11 +147,14 @@ export default function QrCodeLoginDialog({
      clearInterval(countdownRef.current);
      countdownRef.current = null;
    }
+    if (checkExpiredRef.current) {
+      clearInterval(checkExpiredRef.current);
+      checkExpiredRef.current = null;
+    }
    if (abortRef.current) {
      abortRef.current.abort();
      abortRef.current = null;
    }
-    // Cancel backend session
    if (sessionIdRef.current) {
      const token = localStorage.getItem('token');
      const baseUrl =
@@ -171,6 +181,7 @@ export default function QrCodeLoginDialog({

    const token = localStorage.getItem('token');
    const baseUrl = import.meta.env.VITE_API_BASE_URL || window.location.origin;
+    baseUrlRef.current = baseUrl;
    const cfg = platformConfigRef.current;

    try {
@@ -191,8 +202,6 @@ export default function QrCodeLoginDialog({
      const { session_id, qr_data_url, qr_url, expire_at } = json.data;
      sessionIdRef.current = session_id;

-      // qr_data_url is a pre-rendered data URL (WeChat);
-      // qr_url is a plain URL string (Feishu) that needs local QR generation.
      if (qr_data_url) {
        setQrDataUrl(qr_data_url);
      } else if (qr_url) {
@@ -204,11 +213,9 @@ export default function QrCodeLoginDialog({
      }
      setState('waiting');

-      // Calculate remaining seconds
      const remaining = Math.max(0, Math.floor(expire_at - Date.now() / 1000));
      setExpireIn(remaining);

-      // Start countdown
      countdownRef.current = setInterval(() => {
        setExpireIn((prev) => {
          if (prev <= 1) {
@@ -222,7 +229,35 @@ export default function QrCodeLoginDialog({
        });
      }, 1000);

-      // Start polling
+      // When countdown hits 0, stop polling and show expired state
+      checkExpiredRef.current = setInterval(() => {
+        setExpireIn((current) => {
+          if (current <= 0) {
+            if (checkExpiredRef.current) {
+              clearInterval(checkExpiredRef.current);
+              checkExpiredRef.current = null;
+            }
+            if (pollTimerRef.current) {
+              clearInterval(pollTimerRef.current);
+              pollTimerRef.current = null;
+            }
+            if (sessionIdRef.current) {
+              fetch(
+                `${baseUrlRef.current}${cfg.apiBase}/${sessionIdRef.current}`,
+                {
+                  method: 'DELETE',
+                  headers: { Authorization: `Bearer ${token}` },
+                  keepalive: true,
+                },
+              ).catch(() => {});
+              sessionIdRef.current = null;
+            }
+            setState('expired');
+          }
+          return current;
+        });
+      }, 500);
+
      pollTimerRef.current = setInterval(async () => {
        try {
          const pollRes = await fetch(
@@ -237,7 +272,7 @@ export default function QrCodeLoginDialog({
          const { status, error, ...rest } = pollJson.data;

          if (status === 'success') {
-            sessionIdRef.current = null; // backend already cleaned up
+            sessionIdRef.current = null;
            cleanup();
            setState('success');
            setTimeout(() => {
@@ -249,9 +284,14 @@ export default function QrCodeLoginDialog({
            cleanup();
            setState('error');
            setErrorMessage(error || tRef.current(cfg.failedKey));
+          } else if (status === 'expired') {
+            sessionIdRef.current = null;
+            cleanup();
+            setExpireIn(0);
+            setState('expired');
          }
        } catch {
-          // ignore poll errors, will retry next interval
+          // ignore poll errors
        }
      }, POLL_INTERVAL_MS);
    } catch (err: unknown) {
@@ -323,6 +363,31 @@ export default function QrCodeLoginDialog({
            </div>
          )}

+          {/* QR code expired — click overlay to refresh */}
+          {state === 'expired' && qrDataUrl && (
+            <div className="flex flex-col items-center space-y-3">
+              <p className="text-sm text-muted-foreground text-center">
+                {t(platformConfig.scanQRCodeKey)}
+              </p>
+              <button
+                type="button"
+                className="relative border rounded-lg p-2 bg-white cursor-pointer group"
+                onClick={() => startLogin()}
+              >
+                <img
+                  src={qrDataUrl}
+                  alt="QR Code"
+                  className="w-56 h-56 opacity-40"
+                />
+                <div className="absolute inset-0 flex items-center justify-center bg-white/60 rounded-lg group-hover:bg-white/70 transition-colors">
+                  <div className="flex items-center justify-center w-16 h-16 rounded-full bg-black/5 group-hover:bg-black/10 transition-colors">
+                    <RotateCw className="h-8 w-8 text-muted-foreground" />
+                  </div>
+                </div>
+              </button>
+            </div>
+          )}
+
          {/* Success */}
          {state === 'success' && (
            <div className="flex flex-col items-center space-y-3 py-8">
@@ -350,7 +415,7 @@ export default function QrCodeLoginDialog({
        </div>

        {state === 'error' && (
-          <DialogFooter>
+          <div className="flex justify-end gap-2">
            <Button variant="outline" onClick={() => handleOpenChange(false)}>
              {t('common.cancel')}
            </Button>
@@ -358,7 +423,7 @@ export default function QrCodeLoginDialog({
              <RefreshCw className="h-4 w-4 mr-1.5" />
              {t(platformConfig.retryKey)}
            </Button>
-          </DialogFooter>
+          </div>
        )}
      </DialogContent>
    </Dialog>