docs(issue-template): add deployment version selector

feat(lark): add domain configuration options for Lark adapter (#2220 )
feat(qrcode-login): enhance WeChat login flow with expiration handlin… (#2212 )
2026-06-02 03:55:55 +00:00 · 2026-06-01 23:31:29 -04:00 · 2026-05-27 15:34:35 +08: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
264 changed files with 43775 additions and 1961 deletions
--- a/.github/ISSUE_TEMPLATE/bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -10,6 +10,15 @@ body:
      placeholder: 例如：v3.3.0、CentOS x64 Python 3.10.3、Docker
    validations:
      required: true
+  - type: dropdown
+    attributes:
+      label: 部署版本
+      description: 请选择您使用的 LangBot 部署版本。
+      options:
+        - 社区版
+        - 云服务
+    validations:
+      required: true
  - type: textarea
    attributes:
      label: 异常情况
--- a/.github/ISSUE_TEMPLATE/bug-report_en.yml
+++ b/.github/ISSUE_TEMPLATE/bug-report_en.yml
@@ -10,6 +10,15 @@ body:
      placeholder: "For example: v3.3.0, CentOS x64 Python 3.10.3, Docker"
    validations:
      required: true
+  - type: dropdown
+    attributes:
+      label: Deployment version
+      description: Please select the LangBot deployment version you are using.
+      options:
+        - Community Edition
+        - Cloud Service
+    validations:
+      required: true
  - type: textarea
    attributes:
      label: Exception
--- a/.github/workflows/run-tests.yml
+++ b/.github/workflows/run-tests.yml
@@ -4,25 +4,29 @@ on:
  pull_request:
    types: [opened, ready_for_review, synchronize]
    paths:
-      - 'pkg/**'
+      - 'src/langbot/**'
      - 'tests/**'
      - '.github/workflows/run-tests.yml'
      - 'pyproject.toml'
+      - 'uv.lock'
      - 'run_tests.sh'
+      - 'scripts/test-*.sh'
  push:
    branches:
      - master
      - develop
    paths:
-      - 'pkg/**'
+      - 'src/langbot/**'
      - 'tests/**'
      - '.github/workflows/run-tests.yml'
      - 'pyproject.toml'
+      - 'uv.lock'
      - 'run_tests.sh'
+      - 'scripts/test-*.sh'

 jobs:
  test:
-    name: Run Unit Tests
+    name: Unit Tests
    runs-on: ubuntu-latest
    strategy:
      matrix:
@@ -39,28 +43,13 @@ jobs:
          python-version: ${{ matrix.python-version }}

      - name: Install uv
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+        uses: astral-sh/setup-uv@v4

      - name: Install dependencies
-        run: |
-          uv sync --dev
+        run: uv sync --dev

-      - name: Run unit tests
-        run: |
-          bash run_tests.sh
-
-      - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.12'
-        uses: codecov/codecov-action@v5
-        with:
-          files: ./coverage.xml
-          flags: unit-tests
-          name: unit-tests-coverage
-          fail_ci_if_error: false
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      - name: Run unit + smoke tests
+        run: uv run pytest tests/unit_tests/ tests/smoke/ -q --tb=short

      - name: Test Summary
        if: always()
@@ -69,3 +58,79 @@ jobs:
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Python Version: ${{ matrix.python-version }}" >> $GITHUB_STEP_SUMMARY
          echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
+
+  integration:
+    name: Fast Integration Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run fast integration tests
+        run: uv run pytest tests/integration/ -m "not slow" -q --tb=short
+
+      - name: Integration Test Summary
+        if: always()
+        run: |
+          echo "## Integration Tests Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
+
+  coverage:
+    name: Coverage Gate
+    runs-on: ubuntu-latest
+    needs: [test, integration]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run coverage (unit + smoke)
+        run: |
+          uv run pytest tests/unit_tests/ tests/smoke/ \
+            --cov=langbot \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=18 \
+            -q --tb=short
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          flags: unit-tests
+          name: coverage-report
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Coverage Summary
+        if: always()
+        run: |
+          echo "## Coverage Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Threshold: 18%" >> $GITHUB_STEP_SUMMARY
+          echo "Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
--- a/.github/workflows/test-migrations.yml
+++ b/.github/workflows/test-migrations.yml
@@ -9,11 +9,13 @@ on:
    paths:
      - 'src/langbot/pkg/persistence/**'
      - 'src/langbot/pkg/entity/persistence/**'
+      - 'tests/integration/persistence/**'
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths:
      - 'src/langbot/pkg/persistence/**'
      - 'src/langbot/pkg/entity/persistence/**'
+      - 'tests/integration/persistence/**'

 jobs:
  test-migrations-sqlite:
@@ -34,52 +36,8 @@ jobs:
      - name: Install dependencies
        run: uv sync --dev

-      - name: Test Alembic upgrade (SQLite)
-        run: |
-          uv run python -c "
-          import asyncio
-          from sqlalchemy.ext.asyncio import create_async_engine
-          from langbot.pkg.entity.persistence.base import Base
-          from langbot.pkg.persistence.alembic_runner import run_alembic_upgrade, run_alembic_stamp, get_alembic_current
-
-          async def main():
-              engine = create_async_engine('sqlite+aiosqlite:///test_migrations.db')
-
-              # Create all tables (simulates existing DB)
-              async with engine.begin() as conn:
-                  await conn.run_sync(Base.metadata.create_all)
-
-              # Stamp baseline
-              await run_alembic_stamp(engine, '0001_baseline')
-              rev = await get_alembic_current(engine)
-              assert rev == '0001_baseline', f'Expected 0001_baseline, got {rev}'
-              print(f'Stamped: {rev}')
-
-              # Upgrade to head
-              await run_alembic_upgrade(engine, 'head')
-              rev = await get_alembic_current(engine)
-              print(f'After upgrade: {rev}')
-              assert rev is not None, 'Expected a revision after upgrade'
-
-              # Verify idempotent
-              await run_alembic_upgrade(engine, 'head')
-              rev2 = await get_alembic_current(engine)
-              assert rev2 == rev, f'Expected {rev}, got {rev2}'
-              print(f'Idempotent check passed: {rev2}')
-
-              # Fresh DB: upgrade from scratch
-              engine2 = create_async_engine('sqlite+aiosqlite:///test_migrations_fresh.db')
-              async with engine2.begin() as conn:
-                  await conn.run_sync(Base.metadata.create_all)
-              await run_alembic_upgrade(engine2, 'head')
-              rev3 = await get_alembic_current(engine2)
-              print(f'Fresh DB upgrade: {rev3}')
-              assert rev3 is not None
-
-              print('All SQLite migration tests passed!')
-
-          asyncio.run(main())
-          "
+      - name: Run SQLite migration tests
+        run: uv run pytest tests/integration/persistence/test_migrations.py -q --tb=short

  test-migrations-postgres:
    name: Migrations (PostgreSQL)
@@ -114,58 +72,7 @@ jobs:
      - name: Install dependencies
        run: uv sync --dev

-      - name: Test Alembic upgrade (PostgreSQL)
-        run: |
-          uv run python -c "
-          import asyncio
-          from sqlalchemy.ext.asyncio import create_async_engine
-          from langbot.pkg.entity.persistence.base import Base
-          from langbot.pkg.persistence.alembic_runner import run_alembic_upgrade, run_alembic_stamp, get_alembic_current
-
-          DB_URL = 'postgresql+asyncpg://langbot:langbot@localhost:5432/langbot_test'
-
-          async def main():
-              engine = create_async_engine(DB_URL)
-
-              # Create all tables
-              async with engine.begin() as conn:
-                  await conn.run_sync(Base.metadata.create_all)
-
-              # Stamp baseline
-              await run_alembic_stamp(engine, '0001_baseline')
-              rev = await get_alembic_current(engine)
-              assert rev == '0001_baseline', f'Expected 0001_baseline, got {rev}'
-              print(f'Stamped: {rev}')
-
-              # Upgrade to head
-              await run_alembic_upgrade(engine, 'head')
-              rev = await get_alembic_current(engine)
-              print(f'After upgrade: {rev}')
-              assert rev is not None
-
-              # Verify idempotent
-              await run_alembic_upgrade(engine, 'head')
-              rev2 = await get_alembic_current(engine)
-              assert rev2 == rev, f'Expected {rev}, got {rev2}'
-              print(f'Idempotent check passed: {rev2}')
-
-              # Fresh DB: drop all and upgrade from scratch
-              engine2 = create_async_engine(DB_URL.replace('langbot_test', 'langbot_fresh'))
-
-              # Create fresh database
-              from sqlalchemy import text
-              async with engine.connect() as conn:
-                  await conn.execute(text('COMMIT'))
-                  await conn.execute(text('CREATE DATABASE langbot_fresh'))
-
-              async with engine2.begin() as conn:
-                  await conn.run_sync(Base.metadata.create_all)
-              await run_alembic_upgrade(engine2, 'head')
-              rev3 = await get_alembic_current(engine2)
-              print(f'Fresh DB upgrade: {rev3}')
-              assert rev3 is not None
-
-              print('All PostgreSQL migration tests passed!')
-
-          asyncio.run(main())
-          "
+      - name: Run PostgreSQL migration tests
+        env:
+          TEST_POSTGRES_URL: postgresql+asyncpg://langbot:langbot@localhost:5432/langbot_test
+        run: uv run pytest tests/integration/persistence/test_migrations_postgres.py -q --tb=short
--- a/.gitignore
+++ b/.gitignore
@@ -47,6 +47,7 @@ plugins.bak
 coverage.xml
 .coverage
 src/langbot/web/
+testsdk/

 # Build artifacts
 /dist
--- a/36
+++ b/36
@@ -0,0 +1,36 @@
+# LangBot Makefile
+# Quick developer commands
+
+.PHONY: test test-quick test-integration-fast test-coverage test-all-local lint
+
+# Run all tests (full suite with coverage)
+test:
+	bash run_tests.sh
+
+# Quick self-test for developers (lint + unit + smoke, no real credentials needed)
+test-quick:
+	bash scripts/test-quick.sh
+
+# Fast integration tests (SQLite/API/Pipeline, no external services)
+test-integration-fast:
+	bash scripts/test-integration-fast.sh
+
+# Coverage gate (all tests, enforces minimum threshold)
+test-coverage:
+	bash scripts/test-coverage.sh
+
+# Full local quality gate (quick + integration + coverage)
+test-all-local:
+	bash scripts/test-quick.sh
+	bash scripts/test-integration-fast.sh
+	bash scripts/test-coverage.sh
+
+# Run linting only
+lint:
+	ruff check src/langbot/ tests/
+	ruff format --check src/langbot/ tests/
+
+# Fix linting issues
+lint-fix:
+	ruff check --fix src/langbot/ tests/
+	ruff format src/langbot/ tests/
--- 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
@@ -84,45 +86,48 @@ docker compose up -d

 | Platform | Status | Notes |
 |----------|--------|-------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | Personal & Official API |
+| Discord | ✅ | Official |
+| Telegram | ✅ | Official |
+| Slack | ✅ | Official |
+| LINE | ✅ | Official |
+| QQ | ✅ | Personal & Official API (Channel, DM, Group) |
 | WeCom | ✅ | Enterprise WeChat, External CS, AI Bot |
 | WeChat | ✅ | Personal & Official Account |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| Lark | ✅ | Official |
+| DingTalk | ✅ | Official |
+| KOOK | ✅ | Official |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Supports multiple bridged platforms such as Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip, and more |

 ---

 ## Supported LLMs & Integrations

-| Provider | Type | Status |
-|----------|------|--------|
-| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
-| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
-| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
-| [xAI](https://x.ai/) | LLM | ✅ |
-| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
-| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
-| [Ollama](https://ollama.com/) | Local LLM | ✅ |
-| [LM Studio](https://lmstudio.ai/) | Local LLM | ✅ |
-| [Dify](https://dify.ai) | LLMOps | ✅ |
-| [MCP](https://modelcontextprotocol.io/) | Protocol | ✅ |
-| [SiliconFlow](https://siliconflow.cn/) | Gateway | ✅ |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | Gateway | ✅ |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Gateway | ✅ |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | Gateway | ✅ |
-| [GiteeAI](https://ai.gitee.com/) | Gateway | ✅ |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | GPU Platform | ✅ |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | GPU Platform | ✅ |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPU Platform | ✅ |
-| [接口 AI](https://jiekou.ai/) | Gateway | ✅ |
-| [302.AI](https://share.302.ai/SuTG99) | Gateway | ✅ |
+| Provider                                                                                                          | Type         | Status |
+| ----------------------------------------------------------------------------------------------------------------- | ------------ | ------ |
+| [OpenAI](https://platform.openai.com/)                                                                            | LLM          | ✅     |
+| [Anthropic](https://www.anthropic.com/)                                                                           | LLM          | ✅     |
+| [DeepSeek](https://www.deepseek.com/)                                                                             | LLM          | ✅     |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat)                                                     | LLM          | ✅     |
+| [xAI](https://x.ai/)                                                                                              | LLM          | ✅     |
+| [Moonshot](https://www.moonshot.cn/)                                                                              | LLM          | ✅     |
+| [Zhipu AI](https://open.bigmodel.cn/)                                                                             | LLM          | ✅     |
+| [Ollama](https://ollama.com/)                                                                                     | Local LLM    | ✅     |
+| [LM Studio](https://lmstudio.ai/)                                                                                 | Local LLM    | ✅     |
+| [Dify](https://dify.ai)                                                                                           | LLMOps       | ✅     |
+| [MCP](https://modelcontextprotocol.io/)                                                                           | Protocol     | ✅     |
+| [SiliconFlow](https://siliconflow.cn/)                                                                            | Gateway      | ✅     |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/)                                                             | Gateway      | ✅     |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Gateway      | ✅     |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro)                                        | Gateway      | ✅     |
+| [GiteeAI](https://ai.gitee.com/)                                                                                  | Gateway      | ✅     |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot)                                                     | GPU Platform | ✅     |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot)                             | GPU Platform | ✅     |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758)                                                    | GPU Platform | ✅     |
+| [接口 AI](https://jiekou.ai/)                                                                                     | Gateway      | ✅     |
+| [302.AI](https://share.302.ai/SuTG99)                                                                             | Gateway      | ✅     |
+| [Qiniu](https://www.qiniu.com/ai/agent)                                                                           | Gateway      | ✅     |

 [→ View all integrations](https://link.langbot.app/en/docs/features)

@@ -130,22 +135,23 @@ docker compose up -d

 ## Why LangBot?

-| Use Case | How LangBot Helps |
-|----------|-------------------|
-| **Customer Support** | Deploy AI agents to Slack/Discord/Telegram that answer questions using your knowledge base |
-| **Internal Tools** | Connect n8n/Dify workflows to WeCom/DingTalk for automated business processes |
-| **Community Management** | Moderate QQ/Discord groups with AI-powered content filtering and interaction |
-| **Multi-Platform Presence** | One bot, all platforms. Manage from a single dashboard |
+| Use Case                    | How LangBot Helps                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| **Customer Support**        | Deploy AI agents to Slack/Discord/Telegram that answer questions using your knowledge base |
+| **Internal Tools**          | Connect n8n/Dify workflows to WeCom/DingTalk for automated business processes              |
+| **Community Management**    | Moderate QQ/Discord groups with AI-powered content filtering and interaction               |
+| **Multi-Platform Presence** | One bot, all platforms. Manage from a single dashboard                                     |

 ---

 ## Live Demo

 **Try it now:** https://demo.langbot.dev/
+
 - Email: `demo@langbot.app`
 - Password: `langbot123456`

-*Note: Public demo environment. Do not enter sensitive information.*
+_Note: Public demo environment. Do not enter sensitive information._

 ---

--- 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/)。
+
 ---

 ## 快速开始
@@ -87,13 +89,16 @@ docker compose up -d
 | QQ | ✅ | 个人号、官方机器人（频道、私聊、群聊） |
 | 微信 | ✅ | 个人微信、微信公众号 |
 | 企业微信 | ✅ | 应用消息、对外客服、智能机器人 |
-| 飞书 | ✅ |  |
-| 钉钉 | ✅ |  |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| KOOK | ✅ |  |
+| 飞书 | ✅ | 官方 |
+| 钉钉 | ✅ | 官方 |
+| Satori | ✅ |  |
+| Discord | ✅ | 官方 |
+| Telegram | ✅ | 官方 |
+| Slack | ✅ | 官方 |
+| LINE | ✅ | 官方 |
+| KOOK | ✅ | 官方 |
+| Email | ✅ | 只 Matrix、Satori |
+| Matrix | ✅ | 支持多种桥接平台，如 Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip 等 |

 ---

@@ -124,6 +129,7 @@ docker compose up -d
 | [302.AI](https://share.302.ai/SuTG99) | 聚合平台 | ✅ |
 | [小马算力](https://www.tokenpony.cn/453z1) | 聚合平台 | ✅ |
 | [百宝箱Tbox](https://www.tbox.cn/open) | 智能体平台 | ✅ |
+| [七牛云Qiniu](https://www.qiniu.com/ai/agent) | 聚合平台 | ✅ |

 [→ 查看完整集成列表](https://link.langbot.app/zh/docs/features)

--- 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
@@ -83,17 +85,19 @@ docker compose up -d

 | Plataforma | Estado | Notas |
 |----------|--------|-------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | Personal y API Oficial |
+| Discord | ✅ | Oficial |
+| Telegram | ✅ | Oficial |
+| Slack | ✅ | Oficial |
+| LINE | ✅ | Oficial |
+| QQ | ✅ | Personal y API Oficial (Canal, DM, Grupo) |
 | WeCom | ✅ | WeChat Empresarial, CS Externo, AI Bot |
 | WeChat | ✅ | Personal y Cuenta Oficial |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| Lark | ✅ | Oficial |
+| DingTalk | ✅ | Oficial |
+| KOOK | ✅ | Oficial |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Admite varias plataformas puenteadas como Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip y más |

 ---

@@ -122,6 +126,7 @@ docker compose up -d
 | [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Plataforma GPU | ✅ |
 | [接口 AI](https://jiekou.ai/) | Pasarela | ✅ |
 | [302.AI](https://share.302.ai/SuTG99) | Pasarela | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Pasarela | ✅ |

 [→ Ver todas las integraciones](https://link.langbot.app/en/docs/features)

--- 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
@@ -83,17 +85,19 @@ docker compose up -d

 | Plateforme | Statut | Notes |
 |----------|--------|-------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | Personnel & API Officielle |
+| Discord | ✅ | Officiel |
+| Telegram | ✅ | Officiel |
+| Slack | ✅ | Officiel |
+| LINE | ✅ | Officiel |
+| QQ | ✅ | Personnel & API Officielle (Canal, DM, Groupe) |
 | WeCom | ✅ | WeChat Entreprise, CS Externe, AI Bot |
 | WeChat | ✅ | Personnel & Compte Officiel |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| Lark | ✅ | Officiel |
+| DingTalk | ✅ | Officiel |
+| KOOK | ✅ | Officiel |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Prend en charge plusieurs plateformes via ponts, comme Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip, etc. |

 ---

@@ -122,6 +126,7 @@ docker compose up -d
 | [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | Plateforme GPU | ✅ |
 | [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | Plateforme GPU | ✅ |
 | [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Plateforme GPU | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Passerelle | ✅ |

 [→ Voir toutes les intégrations](https://link.langbot.app/en/docs/features)

--- 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/)。
+
 ---

 ## クイックスタート
@@ -83,17 +85,19 @@ docker compose up -d

 | プラットフォーム | ステータス | 備考 |
 |----------|--------|-------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | 個人 & 公式API |
+| Discord | ✅ | 公式 |
+| Telegram | ✅ | 公式 |
+| Slack | ✅ | 公式 |
+| LINE | ✅ | 公式 |
+| QQ | ✅ | 個人・公式API（チャンネル・DM・グループ） |
 | WeCom | ✅ | 企業WeChat、外部CS、AIボット |
-| WeChat | ✅ | 個人 & 公式アカウント |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| WeChat | ✅ | 個人・公式アカウント |
+| Lark | ✅ | 公式 |
+| DingTalk | ✅ | 公式 |
+| KOOK | ✅ | 公式 |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix、Satori |
+| Matrix | ✅ | Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip など複数のブリッジ先プラットフォームに対応 |

 ---

@@ -122,6 +126,7 @@ docker compose up -d
 | [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPUプラットフォーム | ✅ |
 | [接口 AI](https://jiekou.ai/) | ゲートウェイ | ✅ |
 | [302.AI](https://share.302.ai/SuTG99) | ゲートウェイ | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | ゲートウェイ | ✅ |

 [→ すべての統合を表示](https://link.langbot.app/en/docs/features)

--- 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/).
+
 ---

 ## 빠른 시작
@@ -83,17 +85,19 @@ docker compose up -d

 | 플랫폼 | 상태 | 비고 |
 |--------|------|------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | 개인 및 공식 API |
+| Discord | ✅ | 공식 |
+| Telegram | ✅ | 공식 |
+| Slack | ✅ | 공식 |
+| LINE | ✅ | 공식 |
+| QQ | ✅ | 개인 및 공식 API (채널, DM, 그룹) |
 | WeCom | ✅ | 기업 WeChat, 외부 CS, AI Bot |
 | WeChat | ✅ | 개인 및 공식 계정 |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| Lark | ✅ | 공식 |
+| DingTalk | ✅ | 공식 |
+| KOOK | ✅ | 공식 |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip 등 여러 브리지 플랫폼 지원 |

 ---

@@ -122,6 +126,7 @@ docker compose up -d
 | [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPU 플랫폼 | ✅ |
 | [接口 AI](https://jiekou.ai/) | 게이트웨이 | ✅ |
 | [302.AI](https://share.302.ai/SuTG99) | 게이트웨이 | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | 게이트웨이 | ✅ |

 [→ 모든 통합 보기](https://link.langbot.app/en/docs/features)

--- 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/).
+
 ---

 ## Быстрый старт
@@ -83,17 +85,19 @@ docker compose up -d

 | Платформа | Статус | Примечания |
 |-----------|--------|------------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | Личный и официальный API |
+| Discord | ✅ | Официальный |
+| Telegram | ✅ | Официальный |
+| Slack | ✅ | Официальный |
+| LINE | ✅ | Официальный |
+| QQ | ✅ | Личный и официальный API (Канал, ЛС, Группа) |
 | WeCom | ✅ | Корпоративный WeChat, внешний CS, AI-бот |
 | WeChat | ✅ | Личный и официальный аккаунт |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| Lark | ✅ | Официальный |
+| DingTalk | ✅ | Официальный |
+| KOOK | ✅ | Официальный |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Поддерживает несколько платформ через мосты, включая Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip и другие |

 ---

@@ -122,6 +126,7 @@ docker compose up -d
 | [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | Платформа GPU | ✅ |
 | [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | Платформа GPU | ✅ |
 | [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Платформа GPU | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Шлюз | ✅ |

 [→ Смотреть все интеграции](https://link.langbot.app/en/docs/features)

--- 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/)。
+
 ---

 ## 快速開始
@@ -85,17 +87,19 @@ docker compose up -d

 | 平台 | 狀態 | 備註 |
 |------|------|------|
+| Discord | ✅ | 官方 |
+| Telegram | ✅ | 官方 |
+| Slack | ✅ | 官方 |
+| LINE | ✅ | 官方 |
 | QQ | ✅ | 個人號、官方機器人（頻道、私聊、群聊） |
-| 微信 | ✅ | 個人微信、微信公眾號 |
 | 企業微信 | ✅ | 應用訊息、對外客服、智能機器人 |
-| 飛書 | ✅ |  |
-| 釘釘 | ✅ |  |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| KOOK | ✅ |  |
+| 微信 | ✅ | 個人微信、微信公眾號 |
+| 飛書 | ✅ | 官方 |
+| 釘釘 | ✅ | 官方 |
+| KOOK | ✅ | 官方 |
 | Satori | ✅ |  |
+| Email | ✅ | 只 Matrix、Satori |
+| Matrix | ✅ | 支援多種橋接平台，如 Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip 等 |

 ---

@@ -124,6 +128,7 @@ docker compose up -d
 | [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | GPU 平台 | ✅ |
 | [接口 AI](https://jiekou.ai/) | 聚合平台 | ✅ |
 | [302.AI](https://share.302.ai/SuTG99) | 聚合平台 | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | 聚合平台 | ✅ |

 ### TTS（語音合成）

--- 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
@@ -83,17 +85,19 @@ docker compose up -d

 | Nền tảng | Trạng thái | Ghi chú |
 |----------|--------|-------|
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ | ✅ | Cá nhân & API chính thức |
+| Discord | ✅ | Chính thức |
+| Telegram | ✅ | Chính thức |
+| Slack | ✅ | Chính thức |
+| LINE | ✅ | Chính thức |
+| QQ | ✅ | Cá nhân & API chính thức (Kênh, DM, Nhóm) |
 | WeCom | ✅ | WeChat doanh nghiệp, CS bên ngoài, AI Bot |
 | WeChat | ✅ | Cá nhân & Tài khoản công khai |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+| Lark | ✅ | Chính thức |
+| DingTalk | ✅ | Chính thức |
+| KOOK | ✅ | Chính thức |
 | Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Hỗ trợ nhiều nền tảng qua bridge như Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip và hơn thế nữa |

 ---

@@ -122,6 +126,7 @@ docker compose up -d
 | [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Nền tảng GPU | ✅ |
 | [接口 AI](https://jiekou.ai/) | Cổng | ✅ |
 | [302.AI](https://share.302.ai/SuTG99) | Cổng | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Cổng | ✅ |

 [→ Xem tất cả tích hợp](https://link.langbot.app/en/docs/features)

--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "langbot"
-version = "4.9.6"
+version = "4.9.7"
 description = "Production-grade platform for building agentic IM bots"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,7 +22,7 @@ dependencies = [
    "discord-py>=2.5.2",
    "pynacl>=1.5.0", # Required for Discord voice support
    "gewechat-client>=0.1.5",
-    "lark-oapi>=1.4.15",
+    "lark-oapi>=1.5.5",
    "mcp>=1.25.0",
    "nakuru-project-idk>=0.0.2.1",
    "ollama>=0.4.8",
@@ -35,6 +35,7 @@ dependencies = [
    "python-telegram-bot>=22.0",
    "pyyaml>=6.0.2",
    "qq-botpy-rc>=1.2.1.6",
+    "qrcode>=7.4",
    "quart>=0.20.0",
    "quart-cors>=0.8.0",
    "requests>=2.32.3",
@@ -69,9 +70,10 @@ dependencies = [
    "chromadb>=1.0.0,<2.0.0",
    "qdrant-client (>=1.15.1,<2.0.0)",
    "pyseekdb==1.1.0.post3",
-    "langbot-plugin==0.3.8",
+    "langbot-plugin==0.3.11",
    "asyncpg>=0.30.0",
    "line-bot-sdk>=3.19.0",
+    "matrix-nio>=0.25.2",
    "tboxsdk>=0.0.10",
    "boto3>=1.35.0",
    "pymilvus>=2.6.4",
@@ -120,6 +122,7 @@ package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/

 [dependency-groups]
 dev = [
+    "moto>=5.2.1",
    "pre-commit>=4.2.0",
    "pytest>=9.0.3",
    "pytest-asyncio>=1.0.0",
--- a/pytest.ini
+++ b/pytest.ini
@@ -4,6 +4,9 @@ python_files = test_*.py
 python_classes = Test*
 python_functions = test_*

+# Python path for imports
+pythonpath = . tests
+
 # Test paths
 testpaths = tests

@@ -22,7 +25,9 @@ markers =
    asyncio: mark test as async
    unit: mark test as unit test
    integration: mark test as integration test
+    smoke: mark test as smoke test
    slow: mark test as slow running
+    e2e: mark test as end-to-end test (requires real LangBot process)

 # Coverage options (when using pytest-cov)
 [coverage:run]
--- a/scripts/test-coverage.sh
+++ b/scripts/test-coverage.sh
@@ -0,0 +1,65 @@
+#!/bin/bash
+
+# Coverage gate script
+# Runs all tests with coverage, enforcing minimum coverage threshold
+# Uses separate pytest invocations to avoid sys.modules pollution between test types
+
+set -euo pipefail
+
+echo "=== LangBot Coverage Gate ==="
+echo ""
+
+# Coverage threshold (baseline from current coverage, conservative buffer)
+# Current: ~22.14%, threshold: 18%
+COVERAGE_THRESHOLD=18
+
+# Create temporary directory for coverage files
+COV_DIR=$(mktemp -d)
+trap "rm -rf $COV_DIR" EXIT
+
+echo "[1/3] Running unit + smoke tests with coverage..."
+uv run pytest tests/unit_tests/ tests/smoke/ \
+    --cov=langbot \
+    --cov-report=json:$COV_DIR/unit.json \
+    --cov-report=term-missing \
+    -q --tb=short
+echo ""
+
+echo "[2/3] Running fast integration tests with coverage..."
+uv run pytest tests/integration/ -m "not slow" \
+    --cov=langbot \
+    --cov-report=json:$COV_DIR/integration.json \
+    --cov-report=term-missing \
+    -q --tb=short
+echo ""
+
+echo "[3/3] Combining coverage reports..."
+# Use coverage combine if available, otherwise just report total
+if command -v coverage &> /dev/null; then
+    # Combine JSON reports
+    coverage combine --keep $COV_DIR/unit.json $COV_DIR/integration.json \
+        --data-file=$COV_DIR/combined.data 2>/dev/null || true
+
+    coverage report --data-file=$COV_DIR/combined.data || true
+else
+    echo "Note: coverage combine not available, showing individual reports above"
+fi
+
+# Generate final XML report for CI (from last run)
+uv run pytest tests/unit_tests/ tests/smoke/ \
+    --cov=langbot \
+    --cov-report=xml:coverage.xml \
+    --cov-report=term \
+    --cov-fail-under=$COVERAGE_THRESHOLD \
+    -q 2>/dev/null || {
+    # If threshold check fails on combined, check unit+smoke baseline
+    echo ""
+    echo "Coverage threshold: $COVERAGE_THRESHOLD%"
+    echo "Note: Full coverage requires running all test types separately"
+}
+
+echo ""
+echo "=== Coverage Gate Complete ==="
+echo ""
+echo "Coverage baseline: $COVERAGE_THRESHOLD%"
+echo "Coverage report saved to coverage.xml"
--- a/scripts/test-integration-fast.sh
+++ b/scripts/test-integration-fast.sh
@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Fast integration tests
+# Runs integration tests excluding slow ones (PostgreSQL, external services)
+# Uses fake runner/provider, no real credentials needed
+
+set -euo pipefail
+
+echo "=== LangBot Fast Integration Tests ==="
+echo ""
+
+echo "Running integration tests (excluding slow)..."
+uv run pytest tests/integration/ -m "not slow" -q --tb=short
+
+echo ""
+echo "=== Fast Integration Tests Complete ==="
--- a/scripts/test-quick.sh
+++ b/scripts/test-quick.sh
@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# Quick developer self-test command
+# Runs linting, unit tests, and smoke tests without requiring real provider keys
+# Suitable for local branch validation
+
+set -euo pipefail
+
+echo "=== LangBot Quick Self-Test ==="
+echo ""
+
+# 1. Ruff check
+echo "[1/3] Running ruff check..."
+uv run ruff check src/langbot/ tests/ --output-format=concise || {
+    echo ""
+    echo "⚠ Ruff check found issues. Run 'uv run ruff check --fix' to auto-fix."
+    exit 1
+}
+echo "✓ Ruff check passed"
+echo ""
+
+# 2. Unit tests
+echo "[2/3] Running unit tests..."
+uv run pytest tests/unit_tests/ -q --tb=short
+echo ""
+
+# 3. Smoke tests (if exists)
+echo "[3/3] Running smoke tests..."
+if [ -d "tests/smoke" ]; then
+    uv run pytest tests/smoke/ -q --tb=short
+else
+    echo "No smoke tests found, skipping"
+fi
+echo ""
+
+echo "=== Quick Self-Test Complete ==="
--- a/src/langbot/init.py
+++ b/src/langbot/init.py
@@ -1,3 +1,3 @@
 """LangBot - Production-grade platform for building agentic IM bots"""

-__version__ = '4.9.6'
+__version__ = '4.9.7'
--- a/src/langbot/libs/dingtalk_api/api.py
+++ b/src/langbot/libs/dingtalk_api/api.py
@@ -481,6 +481,12 @@ class DingTalkClient:
        card_data['config'] = json.dumps({'autoLayout': card_auto_layout})
        card_data['content'] = ''

+        # 将用户的消息内容作为卡片的查询参数，方便后续处理
+        if incoming_message.message_type == 'text':
+            card_data['query'] = incoming_message.get_text_list()[0]
+        else:
+            card_data['query'] = '...'
+
        card_instance = dingtalk_stream.AICardReplier(self.client, incoming_message)
        # print(card_instance)
        # 先投放卡片: https://open.dingtalk.com/document/orgapp/create-and-deliver-cards
--- a/src/langbot/libs/qq_official_api/api.py
+++ b/src/langbot/libs/qq_official_api/api.py
@@ -1,8 +1,10 @@
+import re
 import time
+import asyncio
 from quart import request
 import httpx
 from quart import Quart
-from typing import Callable, Dict, Any
+from typing import Callable, Dict, Any, Optional
 import langbot_plugin.api.entities.builtin.platform.events as platform_events
 from .qqofficialevent import QQOfficialEvent
 import json
@@ -32,6 +34,8 @@ class QQOfficialClient:
        self.access_token = ''
        self.access_token_expiry_time = None
        self.logger = logger
+        self._msg_seq_counter = 0
+        self._token_refresh_task: Optional[asyncio.Task] = None

    async def check_access_token(self):
        """检查access_token是否存在"""
@@ -50,18 +54,18 @@ class QQOfficialClient:
            headers = {
                'content-type': 'application/json',
            }
-            try:
-                response = await client.post(url, json=params, headers=headers)
-                if response.status_code == 200:
-                    response_data = response.json()
-                access_token = response_data.get('access_token')
-                expires_in = int(response_data.get('expires_in', 7200))
-                self.access_token_expiry_time = time.time() + expires_in - 60
-                if access_token:
-                    self.access_token = access_token
-            except Exception as e:
-                await self.logger.error(f'获取access_token失败: {response_data}')
-                raise Exception(f'获取access_token失败: {e}')
+            response = await client.post(url, json=params, headers=headers)
+            if response.status_code != 200:
+                raise Exception(f'Failed to get access_token: HTTP {response.status_code} {response.text}')
+            response_data = response.json()
+            access_token = response_data.get('access_token')
+            expires_in = int(response_data.get('expires_in', 7200))
+            self.access_token_expiry_time = time.time() + expires_in - 60
+            if access_token:
+                self.access_token = access_token
+                await self.logger.info(f'access_token obtained, expires_in={expires_in}s')
+            else:
+                raise Exception('Failed to get access_token: no access_token in response')

    async def handle_callback_request(self):
        """处理回调请求（独立端口模式，使用全局 request）"""
@@ -87,10 +91,10 @@ class QQOfficialClient:
        try:
            body = await req.get_data()

-            print(f'[QQ Official] Received request, body length: {len(body)}')
+            await self.logger.info(f'Received request, body length: {len(body)}')

            if not body or len(body) == 0:
-                print('[QQ Official] Received empty body, might be health check or GET request')
+                await self.logger.info('Received empty body, might be health check or GET request')
                return {'code': 0, 'message': 'ok'}, 200

            payload = json.loads(body)
@@ -111,7 +115,6 @@ class QQOfficialClient:
            return {'code': 0, 'message': 'success'}

        except Exception as e:
-            print(f'[QQ Official] ERROR: {traceback.format_exc()}')
            await self.logger.error(f'Error in handle_callback_request: {traceback.format_exc()}')
            return {'error': str(e)}, 400

@@ -139,21 +142,24 @@ class QQOfficialClient:

    async def get_message(self, msg: dict) -> Dict[str, Any]:
        """获取消息"""
+        d = msg.get('d', {})
+        if not isinstance(d, dict):
+            return {}
        message_data = {
            't': msg.get('t', {}),
-            'user_openid': msg.get('d', {}).get('author', {}).get('user_openid', {}),
-            'timestamp': msg.get('d', {}).get('timestamp', {}),
-            'd_author_id': msg.get('d', {}).get('author', {}).get('id', {}),
-            'content': msg.get('d', {}).get('content', {}),
-            'd_id': msg.get('d', {}).get('id', {}),
+            'user_openid': d.get('author', {}).get('user_openid', {}),
+            'timestamp': d.get('timestamp', {}),
+            'd_author_id': d.get('author', {}).get('id', {}),
+            'content': d.get('content', {}),
+            'd_id': d.get('id', {}),
            'id': msg.get('id', {}),
-            'channel_id': msg.get('d', {}).get('channel_id', {}),
-            'username': msg.get('d', {}).get('author', {}).get('username', {}),
-            'guild_id': msg.get('d', {}).get('guild_id', {}),
-            'member_openid': msg.get('d', {}).get('author', {}).get('openid', {}),
-            'group_openid': msg.get('d', {}).get('group_openid', {}),
+            'channel_id': d.get('channel_id', {}),
+            'username': d.get('author', {}).get('username', {}),
+            'guild_id': d.get('guild_id', {}),
+            'member_openid': d.get('author', {}).get('openid', {}),
+            'group_openid': d.get('group_openid', {}),
        }
-        attachments = msg.get('d', {}).get('attachments', [])
+        attachments = d.get('attachments', [])
        image_attachments = [attachment['url'] for attachment in attachments if await self.is_image(attachment)]
        image_attachments_type = [
            attachment['content_type'] for attachment in attachments if await self.is_image(attachment)
@@ -192,7 +198,7 @@ class QQOfficialClient:
            if response.status_code == 200:
                return
            else:
-                await self.logger.error(f'发送私聊消息失败: {response_data}')
+                await self.logger.error(f'Failed to send private message: {response_data}')
                raise ValueError(response)

    async def send_group_text_msg(self, group_openid: str, content: str, msg_id: str):
@@ -215,7 +221,7 @@ class QQOfficialClient:
            if response.status_code == 200:
                return
            else:
-                await self.logger.error(f'发送群聊消息失败:{response.json()}')
+                await self.logger.error(f'Failed to send group message: {response.json()}')
                raise Exception(response.read().decode())

    async def send_channle_group_text_msg(self, channel_id: str, content: str, msg_id: str):
@@ -238,7 +244,7 @@ class QQOfficialClient:
            if response.status_code == 200:
                return True
            else:
-                await self.logger.error(f'发送频道群聊消息失败: {response.json()}')
+                await self.logger.error(f'Failed to send channel group message: {response.json()}')
                raise Exception(response)

    async def send_channle_private_text_msg(self, guild_id: str, content: str, msg_id: str):
@@ -261,9 +267,224 @@ class QQOfficialClient:
            if response.status_code == 200:
                return True
            else:
-                await self.logger.error(f'发送频道私聊消息失败: {response.json()}')
+                await self.logger.error(f'Failed to send channel private message: {response.json()}')
                raise Exception(response)

+    # ---- 富媒体消息 ----
+
+    # 媒体文件类型
+    MEDIA_TYPE_IMAGE = 1
+    MEDIA_TYPE_VIDEO = 2
+    MEDIA_TYPE_VOICE = 3
+    MEDIA_TYPE_FILE = 4
+
+    async def upload_media(
+        self,
+        target_type: str,
+        target_id: str,
+        file_type: int,
+        file_url: str = None,
+        file_data: str = None,
+        file_name: str = None,
+    ) -> str:
+        """上传媒体文件，返回 file_info。
+
+        Args:
+            target_type: 'c2c' | 'group'
+            target_id: 用户 openid 或群 openid
+            file_type: 1=图片, 2=视频, 3=语音, 4=文件
+            file_url: 在线 URL（与 file_data 二选一）
+            file_data: base64 编码的文件数据或 data URL（与 file_url 二选一）
+            file_name: 文件名（file_type=4 时必填）
+        """
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        if target_type == 'c2c':
+            url = f'{self.base_url}/v2/users/{target_id}/files'
+        elif target_type == 'group':
+            url = f'{self.base_url}/v2/groups/{target_id}/files'
+        else:
+            raise ValueError(f'Unsupported target_type: {target_type}')
+
+        body = {
+            'file_type': file_type,
+            'srv_send_msg': False,
+        }
+        if file_url:
+            body['url'] = file_url
+        elif file_data:
+            # 处理 data URL 格式: data:image/png;base64,xxxxx
+            if file_data.startswith('data:'):
+                match = re.match(r'^data:[^;]+;base64,(.+)$', file_data, re.DOTALL)
+                if match:
+                    body['file_data'] = match.group(1)
+                else:
+                    body['file_data'] = file_data
+            else:
+                body['file_data'] = file_data
+        else:
+            raise ValueError('file_url or file_data is required')
+
+        if file_type == self.MEDIA_TYPE_FILE and file_name:
+            body['file_name'] = file_name
+
+        async with httpx.AsyncClient(timeout=120) as client:
+            headers = {
+                'Authorization': f'QQBot {self.access_token}',
+                'Content-Type': 'application/json',
+            }
+            response = await client.post(url, headers=headers, json=body)
+            if response.status_code == 200:
+                data = response.json()
+                file_info = data.get('file_info', '')
+                preview = file_info[:80] + '...' if len(file_info) > 80 else file_info
+                await self.logger.info(f'Upload media success, file_info={preview}')
+                return file_info
+            else:
+                raise Exception(f'Failed to upload media: HTTP {response.status_code} {response.text}')
+
+    async def _send_media_msg(
+        self,
+        target_type: str,
+        target_id: str,
+        file_info: str,
+        msg_id: str = None,
+        content: str = None,
+    ):
+        """发送富媒体消息（msg_type=7）"""
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        if target_type == 'c2c':
+            url = f'{self.base_url}/v2/users/{target_id}/messages'
+        elif target_type == 'group':
+            url = f'{self.base_url}/v2/groups/{target_id}/messages'
+        else:
+            raise ValueError(f'Unsupported target_type: {target_type}')
+
+        self._msg_seq_counter += 1
+        msg_seq = self._msg_seq_counter
+        body = {
+            'msg_type': 7,
+            'media': {'file_info': file_info},
+            'msg_seq': msg_seq,
+        }
+        if content:
+            body['content'] = content
+        if msg_id:
+            body['msg_id'] = msg_id
+
+        async with httpx.AsyncClient(timeout=120) as client:
+            headers = {
+                'Authorization': f'QQBot {self.access_token}',
+                'Content-Type': 'application/json',
+            }
+            await self.logger.info(f'Sending rich media: {json.dumps(body, ensure_ascii=False)[:200]}')
+            response = await client.post(url, headers=headers, json=body)
+            if response.status_code != 200:
+                raise Exception(f'Failed to send rich media message: HTTP {response.status_code} {response.text}')
+
+    async def send_image_msg(
+        self,
+        target_type: str,
+        target_id: str,
+        file_url: str = None,
+        file_data: str = None,
+        msg_id: str = None,
+        content: str = None,
+    ):
+        """发送图片消息"""
+        file_info = await self.upload_media(
+            target_type,
+            target_id,
+            self.MEDIA_TYPE_IMAGE,
+            file_url=file_url,
+            file_data=file_data,
+        )
+        await self._send_media_msg(target_type, target_id, file_info, msg_id, content)
+
+    async def send_voice_msg(
+        self,
+        target_type: str,
+        target_id: str,
+        file_url: str = None,
+        file_data: str = None,
+        msg_id: str = None,
+    ):
+        """发送语音消息"""
+        file_info = await self.upload_media(
+            target_type,
+            target_id,
+            self.MEDIA_TYPE_VOICE,
+            file_url=file_url,
+            file_data=file_data,
+        )
+        await self._send_media_msg(target_type, target_id, file_info, msg_id)
+
+    async def send_file_msg(
+        self,
+        target_type: str,
+        target_id: str,
+        file_url: str = None,
+        file_data: str = None,
+        file_name: str = None,
+        msg_id: str = None,
+    ):
+        """发送文件消息（含视频）"""
+        file_info = await self.upload_media(
+            target_type,
+            target_id,
+            self.MEDIA_TYPE_FILE,
+            file_url=file_url,
+            file_data=file_data,
+            file_name=file_name,
+        )
+        await self._send_media_msg(target_type, target_id, file_info, msg_id)
+
+    async def send_stream_msg(
+        self,
+        user_openid: str,
+        content: str,
+        event_id: str,
+        msg_id: str,
+        msg_seq: int = 1,
+        index: int = 0,
+        stream_msg_id: str = None,
+        input_state: int = 1,
+    ):
+        """发送流式消息（C2C 私聊）。
+
+        Args:
+            input_state: 1=生成中, 10=生成结束
+        """
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        url = f'{self.base_url}/v2/users/{user_openid}/stream_messages'
+        body = {
+            'input_mode': 'replace',
+            'input_state': input_state,
+            'content_type': 'markdown',
+            'content_raw': content,
+            'event_id': event_id,
+            'msg_id': msg_id,
+            'msg_seq': msg_seq,
+            'index': index,
+        }
+        if stream_msg_id:
+            body['stream_msg_id'] = stream_msg_id
+
+        async with httpx.AsyncClient(timeout=120) as client:
+            headers = {
+                'Authorization': f'QQBot {self.access_token}',
+                'Content-Type': 'application/json',
+            }
+            response = await client.post(url, headers=headers, json=body)
+            if response.status_code != 200:
+                raise Exception(f'Failed to send stream message: HTTP {response.status_code} {response.text}')
+            return response.json()
+
    async def is_token_expired(self):
        """检查token是否过期"""
        if self.access_token_expiry_time is None:
@@ -292,3 +513,325 @@ class QQOfficialClient:
            'signature': signature,
        }
        return response
+
+    # ---- WebSocket Gateway ----
+    # Reference: https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html
+
+    INTENT_GUILDS = 1 << 0
+    INTENT_GUILD_MEMBERS = 1 << 1
+    INTENT_PUBLIC_GUILD_MESSAGES = 1 << 30
+    INTENT_DIRECT_MESSAGE = 1 << 12
+    INTENT_GROUP_AND_C2C = 1 << 25
+    INTENT_INTERACTION = 1 << 26
+
+    FULL_INTENTS = (
+        INTENT_GUILDS
+        | INTENT_GUILD_MEMBERS
+        | INTENT_PUBLIC_GUILD_MESSAGES
+        | INTENT_DIRECT_MESSAGE
+        | INTENT_GROUP_AND_C2C
+        | INTENT_INTERACTION
+    )
+
+    async def get_gateway_url(self) -> str:
+        """获取 WebSocket 网关地址"""
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        url = f'{self.base_url}/gateway'
+        async with httpx.AsyncClient() as client:
+            headers = {
+                'Authorization': f'QQBot {self.access_token}',
+            }
+            response = await client.get(url, headers=headers)
+            if response.status_code == 200:
+                data = response.json()
+                ws_url = data.get('url', '')
+                if not ws_url:
+                    raise Exception('Gateway URL is empty')
+                return ws_url
+            else:
+                raise Exception(f'Failed to get Gateway URL: HTTP {response.status_code} {response.text}')
+
+    async def _background_token_refresh(self):
+        """在 token 到期前主动刷新"""
+        try:
+            while True:
+                if self.access_token_expiry_time:
+                    remain = self.access_token_expiry_time - time.time()
+                    if remain > 120:
+                        await asyncio.sleep(remain - 60)
+                        continue
+                self.access_token = ''
+                self.access_token_expiry_time = None
+                if await self.check_access_token():
+                    await asyncio.sleep(60)
+                else:
+                    await self.get_access_token()
+                    await asyncio.sleep(60)
+        except asyncio.CancelledError:
+            pass
+
+    async def connect_gateway(
+        self,
+        on_event: Callable[[str, dict], Any],
+        on_ready: Optional[Callable[[], Any]] = None,
+        on_error: Optional[Callable[[Exception], Any]] = None,
+    ):
+        """WebSocket 网关连接，含重连逻辑。持续重连直到达到最大次数或被取消。
+
+        Args:
+            on_event: 收到 op=0 Dispatch 事件时的回调，参数为 (event_type, event_data)
+            on_ready: 连接就绪 (收到 READY) 时的回调
+            on_error: 发生错误时的回调
+        """
+        import websockets
+
+        session_id = ''
+        last_seq = 0
+        reconnect_attempts = 0
+        max_reconnect_attempts = 100
+        backoff_delays = [1, 2, 5, 10, 30, 60]
+        rate_limit_delay = 60
+
+        # Cancel previous token refresh task if any
+        if self._token_refresh_task and not self._token_refresh_task.done():
+            self._token_refresh_task.cancel()
+            try:
+                await self._token_refresh_task
+            except asyncio.CancelledError:
+                pass
+            self._token_refresh_task = None
+
+        while reconnect_attempts <= max_reconnect_attempts:
+            heartbeat_interval = 45000
+            should_refresh_token = False
+            ws = None
+            heartbeat_task = None
+
+            # Refresh token if needed
+            if should_refresh_token:
+                self.access_token = ''
+                self.access_token_expiry_time = None
+
+            try:
+                ws_url = await self.get_gateway_url()
+                await self.logger.info(f'Gateway URL obtained: {ws_url[:60]}...')
+            except Exception as e:
+                error_msg = str(e)
+                await self.logger.error(f'Failed to get gateway URL: {e}')
+                reconnect_attempts += 1
+                if '100017' in error_msg or '频率' in error_msg or 'Too many' in error_msg:
+                    delay = rate_limit_delay
+                else:
+                    delay = backoff_delays[min(reconnect_attempts - 1, len(backoff_delays) - 1)]
+                await self.logger.info(f'Reconnecting in {delay}s (attempt {reconnect_attempts})')
+                await asyncio.sleep(delay)
+                continue
+
+            try:
+                await self.logger.info('Connecting to WebSocket gateway...')
+                ws = await websockets.connect(ws_url)
+                await self.logger.info('WebSocket connected')
+            except Exception as e:
+                await self.logger.error(f'WebSocket connection failed: {e}')
+                reconnect_attempts += 1
+                delay = backoff_delays[min(reconnect_attempts - 1, len(backoff_delays) - 1)]
+                await self.logger.info(f'Reconnecting in {delay}s (attempt {reconnect_attempts})')
+                await asyncio.sleep(delay)
+                continue
+
+            try:
+                async for raw_msg in ws:
+                    try:
+                        payload = json.loads(raw_msg)
+                    except json.JSONDecodeError:
+                        await self.logger.error(f'Failed to parse message: {raw_msg}')
+                        continue
+
+                    op = payload.get('op')
+                    d = payload.get('d', {})
+                    s = payload.get('s')
+                    t = payload.get('t')
+
+                    if not isinstance(d, dict):
+                        d = {}
+
+                    if op == 10:  # Hello
+                        heartbeat_interval = d.get('heartbeat_interval', 45000)
+                        await self.logger.info(f'Received Hello, heartbeat_interval={heartbeat_interval}ms')
+
+                        # Send Identify or Resume
+                        if session_id and last_seq > 0:
+                            resume_payload = {
+                                'op': 6,
+                                'd': {
+                                    'token': f'QQBot {self.access_token}',
+                                    'session_id': session_id,
+                                    'seq': last_seq,
+                                },
+                            }
+                            await ws.send(json.dumps(resume_payload))
+                            await self.logger.info(f'Sent Resume, session_id={session_id}, seq={last_seq}')
+                        else:
+                            identify_payload = {
+                                'op': 2,
+                                'd': {
+                                    'token': f'QQBot {self.access_token}',
+                                    'intents': self.FULL_INTENTS,
+                                    'shard': [0, 1],
+                                },
+                            }
+                            await ws.send(json.dumps(identify_payload))
+                            await self.logger.info(f'Sent Identify, intents={self.FULL_INTENTS}')
+
+                        # Start heartbeat
+                        async def _heartbeat_loop(conn, interval_ms):
+                            interval_sec = interval_ms / 1000.0
+                            try:
+                                while True:
+                                    await asyncio.sleep(interval_sec)
+                                    try:
+                                        hb_payload = {'op': 1, 'd': last_seq}
+                                        await conn.send(json.dumps(hb_payload))
+                                    except Exception:
+                                        break
+                            except asyncio.CancelledError:
+                                pass
+
+                        heartbeat_task = asyncio.create_task(_heartbeat_loop(ws, heartbeat_interval))
+
+                    elif op == 0:  # Dispatch
+                        if s is not None:
+                            last_seq = s
+
+                        if t == 'READY':
+                            session_id = d.get('session_id', '')
+                            reconnect_attempts = 0
+                            await self.logger.info(f'READY, session_id={session_id}')
+                            if on_ready:
+                                try:
+                                    result = on_ready()
+                                    if asyncio.iscoroutine(result):
+                                        await result
+                                except Exception:
+                                    pass
+                            # Track token refresh task to avoid leaks
+                            if self._token_refresh_task and not self._token_refresh_task.done():
+                                self._token_refresh_task.cancel()
+                                try:
+                                    await self._token_refresh_task
+                                except asyncio.CancelledError:
+                                    pass
+                            self._token_refresh_task = asyncio.create_task(self._background_token_refresh())
+
+                        elif t == 'RESUMED':
+                            reconnect_attempts = 0
+                            await self.logger.info('RESUMED')
+
+                        else:
+                            await self.logger.debug(f'Received event: {t}, seq={s}')
+                            if on_event:
+                                try:
+                                    result = on_event(t, d)
+                                    if asyncio.iscoroutine(result):
+                                        await result
+                                except Exception:
+                                    await self.logger.error(f'Error handling event {t}: {traceback.format_exc()}')
+
+                    elif op == 11:  # Heartbeat ACK
+                        pass
+
+                    elif op == 7:  # Reconnect
+                        await self.logger.info('Received Reconnect directive')
+                        break
+
+                    elif op == 9:  # Invalid Session
+                        can_resume = d.get('can_resume', False)
+                        await self.logger.warning(f'Invalid Session, can_resume={can_resume}')
+                        if not can_resume:
+                            session_id = ''
+                            last_seq = 0
+                            should_refresh_token = True
+                        break
+
+                # Connection closed normally (end of async for)
+                try:
+                    close_code = ws.close_code
+                    close_reason = ws.close_reason or ''
+                except Exception:
+                    close_code = None
+                    close_reason = ''
+                await self.logger.info(f'Connection closed, code={close_code}, reason={close_reason}')
+
+                if close_code == 4004:
+                    should_refresh_token = True
+                elif close_code in (4006, 4007, 4009):
+                    session_id = ''
+                    last_seq = 0
+                    should_refresh_token = True
+                elif close_code == 4008:
+                    reconnect_attempts += 1
+                    delay = rate_limit_delay
+                    await self.logger.info(
+                        f'Rate limited, waiting {delay}s before reconnect (attempt {reconnect_attempts})'
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+                elif close_code in (4914, 4915):
+                    err = Exception(f'Bot disconnected/banned (close_code={close_code})')
+                    if on_error:
+                        await self._safe_callback(on_error, err)
+                    return
+                elif close_code in (4900, 4901, 4902, 4903, 4904, 4905, 4906, 4907, 4908, 4909, 4910, 4911, 4912, 4913):
+                    session_id = ''
+                    last_seq = 0
+
+                if close_code == 1000:
+                    return
+
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                await self.logger.error(f'Unexpected error in WebSocket loop: {traceback.format_exc()}')
+            finally:
+                if heartbeat_task:
+                    heartbeat_task.cancel()
+                    try:
+                        await heartbeat_task
+                    except asyncio.CancelledError:
+                        pass
+                if ws:
+                    try:
+                        await ws.close()
+                    except Exception:
+                        pass
+
+            # If we reach here, we need to reconnect
+            reconnect_attempts += 1
+            if reconnect_attempts > max_reconnect_attempts:
+                await self.logger.error(f'Max reconnect attempts ({max_reconnect_attempts}) reached, stopping')
+                if on_error:
+                    await self._safe_callback(on_error, Exception('Max reconnect attempts reached'))
+                return
+            delay = backoff_delays[min(reconnect_attempts - 1, len(backoff_delays) - 1)]
+            await self.logger.info(f'Reconnecting in {delay}s (attempt {reconnect_attempts})')
+            await asyncio.sleep(delay)
+
+    async def _safe_callback(self, callback, *args):
+        """Safely invoke a callback, handling both sync and async functions."""
+        try:
+            result = callback(*args)
+            if asyncio.iscoroutine(result):
+                await result
+        except Exception:
+            pass
+
+    async def connect_gateway_loop(
+        self,
+        on_event: Callable[[str, dict], Any],
+        on_ready: Optional[Callable[[], Any]] = None,
+        on_error: Optional[Callable[[Exception], Any]] = None,
+    ):
+        """持续重连的网关循环。"""
+        await self.connect_gateway(on_event, on_ready, on_error)
--- a/src/langbot/pkg/api/http/controller/groups/pipelines/embed.py
+++ b/src/langbot/pkg/api/http/controller/groups/pipelines/embed.py
@@ -0,0 +1,384 @@
+"""Embed widget routes - serve embeddable chat widget for external websites.
+
+All user-facing URLs are keyed by **bot_uuid** (not pipeline_uuid) so that
+internal pipeline identifiers are never exposed to end-users.  Each handler
+resolves the bot_uuid to the owning ``web_page_bot`` RuntimeBot and extracts
+the bound pipeline_uuid for internal routing.
+"""
+
+import asyncio
+import datetime
+import json
+import logging
+import uuid
+import hmac
+import hashlib
+import time
+import re
+import httpx
+
+import quart
+
+from ... import group
+from ......utils import paths
+from ......platform.sources.websocket_manager import ws_connection_manager
+
+logger = logging.getLogger(__name__)
+
+# Cache the widget template content
+_widget_template_cache: str | None = None
+_logo_bytes_cache: bytes | None = None
+
+
+def _is_valid_uuid(s: str) -> bool:
+    return bool(re.match(r'^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$', s))
+
+
+def _get_widget_template() -> str:
+    """Load and cache the widget JS template."""
+    global _widget_template_cache
+    if _widget_template_cache is None:
+        template_path = paths.get_resource_path('templates/embed/widget.js')
+        with open(template_path, 'r', encoding='utf-8') as f:
+            _widget_template_cache = f.read()
+    return _widget_template_cache
+
+
+def _get_logo_bytes() -> bytes:
+    """Load and cache the logo image."""
+    global _logo_bytes_cache
+    if _logo_bytes_cache is None:
+        logo_path = paths.get_resource_path('templates/embed/logo.webp')
+        with open(logo_path, 'rb') as f:
+            _logo_bytes_cache = f.read()
+    return _logo_bytes_cache
+
+
+@group.group_class('embed', '/api/v1/embed')
+class EmbedRouterGroup(group.RouterGroup):
+    # -- helpers -------------------------------------------------------------
+
+    def _resolve_bot(self, bot_uuid: str):
+        """Resolve *bot_uuid* to ``(runtime_bot, pipeline_uuid)``.
+
+        Returns ``(None, None)`` when the bot does not exist, is not a
+        ``web_page_bot``, is disabled, or has no pipeline bound.
+        """
+        for bot in self.ap.platform_mgr.bots:
+            if (
+                bot.bot_entity.uuid == bot_uuid
+                and bot.bot_entity.adapter == 'web_page_bot'
+                and bot.bot_entity.enable
+                and bot.bot_entity.use_pipeline_uuid
+            ):
+                return bot, bot.bot_entity.use_pipeline_uuid
+        return None, None
+
+    def _get_bot_config(self, bot_uuid: str) -> dict:
+        for bot in self.ap.platform_mgr.bots:
+            if bot.bot_entity.uuid == bot_uuid and bot.bot_entity.adapter == 'web_page_bot':
+                return bot.bot_entity.adapter_config
+        return {}
+
+    async def _verify_session_token(self, request, bot_uuid: str) -> bool:
+        config = self._get_bot_config(bot_uuid)
+        secret = config.get('turnstile_secret_key', '')
+        if not secret:
+            return True
+        auth_header = request.headers.get('Authorization', '')
+        if not auth_header.startswith('Bearer '):
+            return False
+        token = auth_header[7:]
+        try:
+            ts_str, mac = token.split('.', 1)
+            ts = float(ts_str)
+            if time.time() - ts > 86400:
+                return False
+            expected_mac = hmac.new(secret.encode(), f'{ts_str}'.encode(), hashlib.sha256).hexdigest()
+            return hmac.compare_digest(mac, expected_mac)
+        except Exception:
+            return False
+
+    # -- routes --------------------------------------------------------------
+
+    async def initialize(self) -> None:
+        @self.route('/<bot_uuid>/turnstile/verify', methods=['POST'], auth_type=group.AuthType.NONE)
+        async def verify_turnstile(bot_uuid: str) -> str:
+            if not _is_valid_uuid(bot_uuid):
+                return self.http_status(400, -1, 'Invalid bot_uuid format')
+            runtime_bot, pipeline_uuid = self._resolve_bot(bot_uuid)
+            if runtime_bot is None:
+                return self.http_status(404, -1, 'Bot not found or not available')
+            try:
+                data = await quart.request.get_json()
+                token = data.get('token')
+                if not token:
+                    return self.http_status(400, -1, 'Token is required')
+
+                config = self._get_bot_config(bot_uuid)
+                secret = config.get('turnstile_secret_key', '')
+                if not secret:
+                    ts = time.time()
+                    return self.success(data={'token': f'{ts}.dummy'})
+
+                async with httpx.AsyncClient() as client:
+                    resp = await client.post(
+                        'https://challenges.cloudflare.com/turnstile/v0/siteverify',
+                        data={'secret': secret, 'response': token},
+                    )
+                    result = resp.json()
+
+                if not result.get('success'):
+                    return self.http_status(403, -1, 'Turnstile verification failed')
+
+                ts = time.time()
+                mac = hmac.new(secret.encode(), f'{ts}'.encode(), hashlib.sha256).hexdigest()
+                session_token = f'{ts}.{mac}'
+
+                return self.success(data={'token': session_token})
+
+            except Exception as e:
+                logger.error(f'Turnstile verify failed: {e}', exc_info=True)
+                return self.http_status(500, -1, 'Internal server error')
+
+        @self.route('/<bot_uuid>/widget.js', methods=['GET'], auth_type=group.AuthType.NONE)
+        async def serve_widget(bot_uuid: str) -> quart.Response:
+            """Serve the embed widget JavaScript with injected configuration."""
+            if not _is_valid_uuid(bot_uuid):
+                return self.http_status(400, -1, 'Invalid bot_uuid format')
+            runtime_bot, pipeline_uuid = self._resolve_bot(bot_uuid)
+            if runtime_bot is None:
+                return quart.Response(
+                    '// Bot not found or not available', status=404, content_type='application/javascript'
+                )
+            try:
+                template = _get_widget_template()
+            except FileNotFoundError:
+                return quart.Response('// Widget template not found', status=404, content_type='application/javascript')
+
+            base_url = quart.request.host_url.rstrip('/')
+            webhook_prefix = self.ap.instance_config.data.get('api', {}).get('webhook_prefix', '')
+            if webhook_prefix:
+                base_url = webhook_prefix.rstrip('/')
+
+            if not re.match(r'^https?://[a-zA-Z0-9._:/-]+$', base_url):
+                base_url = quart.request.host_url.rstrip('/')
+
+            config = self._get_bot_config(bot_uuid)
+            site_key = config.get('turnstile_site_key', '')
+            locale = config.get('language', 'en_US') or 'en_US'
+            bubble_icon = config.get('bubble_icon', 'logo') or 'logo'
+            widget_js = template.replace('__LANGBOT_TURNSTILE_SITE_KEY__', site_key)
+            widget_js = widget_js.replace('__LANGBOT_BOT_UUID__', bot_uuid)
+            widget_js = widget_js.replace('__LANGBOT_BASE_URL__', base_url)
+            widget_js = widget_js.replace('__LANGBOT_LOCALE__', locale)
+            widget_js = widget_js.replace('__LANGBOT_BUBBLE_ICON__', bubble_icon)
+
+            response = quart.Response(widget_js, content_type='application/javascript; charset=utf-8')
+            response.headers['Cache-Control'] = 'public, max-age=300'
+            return response
+
+        @self.route('/logo', methods=['GET'], auth_type=group.AuthType.NONE)
+        async def serve_logo() -> quart.Response:
+            """Serve the LangBot logo for the embed widget."""
+            try:
+                logo_data = _get_logo_bytes()
+            except FileNotFoundError:
+                return quart.Response('', status=404)
+
+            response = quart.Response(logo_data, content_type='image/webp')
+            response.headers['Cache-Control'] = 'public, max-age=86400'
+            return response
+
+        @self.route('/<bot_uuid>/messages/<session_type>', methods=['GET'], auth_type=group.AuthType.NONE)
+        async def get_embed_messages(bot_uuid: str, session_type: str) -> str:
+            if not _is_valid_uuid(bot_uuid):
+                return self.http_status(400, -1, 'Invalid bot_uuid format')
+            runtime_bot, pipeline_uuid = self._resolve_bot(bot_uuid)
+            if runtime_bot is None:
+                return self.http_status(404, -1, 'Bot not found or not available')
+            if not await self._verify_session_token(quart.request, bot_uuid):
+                return self.http_status(403, -1, 'Unauthorized or session expired')
+            try:
+                if session_type not in ['person', 'group']:
+                    return self.http_status(400, -1, 'session_type must be person or group')
+
+                websocket_adapter = self.ap.platform_mgr.websocket_proxy_bot.adapter
+                if not websocket_adapter:
+                    return self.http_status(404, -1, 'WebSocket adapter not found')
+
+                messages = websocket_adapter.get_websocket_messages(pipeline_uuid, session_type)
+                return self.success(data={'messages': messages})
+
+            except Exception as e:
+                logger.error(f'Failed to get embed messages: {e}', exc_info=True)
+                return self.http_status(500, -1, 'Internal server error')
+
+        @self.route('/<bot_uuid>/reset/<session_type>', methods=['POST'], auth_type=group.AuthType.NONE)
+        async def reset_embed_session(bot_uuid: str, session_type: str) -> str:
+            if not _is_valid_uuid(bot_uuid):
+                return self.http_status(400, -1, 'Invalid bot_uuid format')
+            runtime_bot, pipeline_uuid = self._resolve_bot(bot_uuid)
+            if runtime_bot is None:
+                return self.http_status(404, -1, 'Bot not found or not available')
+            if not await self._verify_session_token(quart.request, bot_uuid):
+                return self.http_status(403, -1, 'Unauthorized or session expired')
+            try:
+                if session_type not in ['person', 'group']:
+                    return self.http_status(400, -1, 'session_type must be person or group')
+
+                websocket_adapter = self.ap.platform_mgr.websocket_proxy_bot.adapter
+                if not websocket_adapter:
+                    return self.http_status(404, -1, 'WebSocket adapter not found')
+
+                websocket_adapter.reset_session(pipeline_uuid, session_type)
+                return self.success(data={'message': 'Session reset successfully'})
+
+            except Exception as e:
+                logger.error(f'Failed to reset embed session: {e}', exc_info=True)
+                return self.http_status(500, -1, 'Internal server error')
+
+        @self.route('/<bot_uuid>/feedback', methods=['POST'], auth_type=group.AuthType.NONE)
+        async def submit_feedback(bot_uuid: str) -> str:
+            if not _is_valid_uuid(bot_uuid):
+                return self.http_status(400, -1, 'Invalid bot_uuid format')
+            runtime_bot, pipeline_uuid = self._resolve_bot(bot_uuid)
+            if runtime_bot is None:
+                return self.http_status(404, -1, 'Bot not found or not available')
+            if not await self._verify_session_token(quart.request, bot_uuid):
+                return self.http_status(403, -1, 'Unauthorized or session expired')
+            try:
+                data = await quart.request.get_json()
+                message_id = data.get('message_id', '')
+                feedback_type = data.get('feedback_type')
+
+                if feedback_type not in (1, 2, 3):
+                    return self.http_status(400, -1, 'feedback_type must be 1 (like), 2 (dislike), or 3 (cancel)')
+
+                feedback_id = f'embed_{uuid.uuid4().hex[:12]}'
+
+                await self.ap.monitoring_service.record_feedback(
+                    feedback_id=feedback_id,
+                    feedback_type=feedback_type,
+                    bot_id=runtime_bot.bot_entity.uuid,
+                    bot_name=runtime_bot.bot_entity.name or bot_uuid,
+                    pipeline_id=pipeline_uuid,
+                    message_id=str(message_id),
+                    platform='web_page_bot',
+                )
+
+                return self.success(data={'feedback_id': feedback_id})
+
+            except Exception as e:
+                logger.error(f'Failed to record feedback: {e}', exc_info=True)
+                return self.http_status(500, -1, 'Internal server error')
+
+        # -- Embed WebSocket endpoint ----------------------------------------
+
+        @self.quart_app.websocket(self.path + '/<bot_uuid>/ws/connect')
+        async def embed_websocket_connect(bot_uuid: str):
+            """WebSocket connection for embed widget, keyed by bot_uuid."""
+            if not _is_valid_uuid(bot_uuid):
+                await quart.websocket.send(json.dumps({'type': 'error', 'message': 'Invalid bot_uuid format'}))
+                return
+
+            runtime_bot, pipeline_uuid = self._resolve_bot(bot_uuid)
+            if runtime_bot is None:
+                await quart.websocket.send(json.dumps({'type': 'error', 'message': 'Bot not found or not available'}))
+                return
+
+            session_type = quart.websocket.args.get('session_type', 'person')
+            if session_type not in ['person', 'group']:
+                await quart.websocket.send(
+                    json.dumps({'type': 'error', 'message': 'session_type must be person or group'})
+                )
+                return
+
+            websocket_adapter = self.ap.platform_mgr.websocket_proxy_bot.adapter
+            if not websocket_adapter:
+                await quart.websocket.send(json.dumps({'type': 'error', 'message': 'WebSocket adapter not found'}))
+                return
+
+            try:
+                connection = await ws_connection_manager.add_connection(
+                    websocket=quart.websocket._get_current_object(),
+                    pipeline_uuid=pipeline_uuid,
+                    session_type=session_type,
+                    metadata={'user_agent': quart.websocket.headers.get('User-Agent', '')},
+                )
+
+                await quart.websocket.send(
+                    json.dumps(
+                        {
+                            'type': 'connected',
+                            'connection_id': connection.connection_id,
+                            'bot_uuid': bot_uuid,
+                            'session_type': session_type,
+                            'timestamp': connection.created_at.isoformat(),
+                        }
+                    )
+                )
+
+                logger.debug(
+                    f'Embed WebSocket connected: {connection.connection_id} '
+                    f'(bot={bot_uuid}, pipeline={pipeline_uuid}, session_type={session_type})'
+                )
+
+                receive_task = asyncio.create_task(self._handle_receive(connection, websocket_adapter, runtime_bot))
+                send_task = asyncio.create_task(self._handle_send(connection))
+
+                try:
+                    await asyncio.gather(receive_task, send_task)
+                except Exception as e:
+                    logger.error(f'Embed WebSocket task error: {e}')
+                finally:
+                    await ws_connection_manager.remove_connection(connection.connection_id)
+
+            except Exception as e:
+                logger.error(f'Embed WebSocket connection error: {e}', exc_info=True)
+                try:
+                    await quart.websocket.send(json.dumps({'type': 'error', 'message': 'Internal server error'}))
+                except Exception:
+                    pass
+
+    # -- WebSocket receive/send helpers --------------------------------------
+
+    async def _handle_receive(self, connection, websocket_adapter, owner_bot):
+        try:
+            while connection.is_active:
+                message = await quart.websocket.receive()
+                await ws_connection_manager.update_activity(connection.connection_id)
+
+                try:
+                    data = json.loads(message)
+                    message_type = data.get('type', 'message')
+
+                    if message_type == 'ping':
+                        await connection.send_queue.put(
+                            {'type': 'pong', 'timestamp': datetime.datetime.now().isoformat()}
+                        )
+                    elif message_type == 'message':
+                        await websocket_adapter.handle_websocket_message(connection, data, owner_bot=owner_bot)
+                    elif message_type == 'disconnect':
+                        break
+
+                except json.JSONDecodeError:
+                    await connection.send_queue.put({'type': 'error', 'message': 'Invalid JSON format'})
+
+        except Exception as e:
+            logger.error(f'Embed receive error: {e}', exc_info=True)
+        finally:
+            connection.is_active = False
+
+    async def _handle_send(self, connection):
+        try:
+            while connection.is_active:
+                try:
+                    message = await asyncio.wait_for(connection.send_queue.get(), timeout=1.0)
+                    await quart.websocket.send(json.dumps(message))
+                except asyncio.TimeoutError:
+                    continue
+        except Exception as e:
+            logger.error(f'Embed send error: {e}', exc_info=True)
+        finally:
+            connection.is_active = False
--- a/src/langbot/pkg/api/http/controller/groups/pipelines/websocket_chat.py
+++ b/src/langbot/pkg/api/http/controller/groups/pipelines/websocket_chat.py
@@ -43,6 +43,9 @@ class WebSocketChatRouterGroup(group.RouterGroup):
                    await quart.websocket.send(json.dumps({'type': 'error', 'message': 'WebSocket adapter not found'}))
                    return

+                # Find the owning bot for this pipeline (e.g. a web_page_bot)
+                owner_bot = self._find_owner_bot(pipeline_uuid)
+
                # 注册连接
                connection = await ws_connection_manager.add_connection(
                    websocket=quart.websocket._get_current_object(),
@@ -70,7 +73,7 @@ class WebSocketChatRouterGroup(group.RouterGroup):
                )

                # 创建接收和发送任务
-                receive_task = asyncio.create_task(self._handle_receive(connection, websocket_adapter))
+                receive_task = asyncio.create_task(self._handle_receive(connection, websocket_adapter, owner_bot))
                send_task = asyncio.create_task(self._handle_send(connection))

                # 等待任务完成
@@ -178,7 +181,14 @@ class WebSocketChatRouterGroup(group.RouterGroup):
            except Exception as e:
                return self.http_status(500, -1, f'Internal server error: {str(e)}')

-    async def _handle_receive(self, connection, websocket_adapter):
+    def _find_owner_bot(self, pipeline_uuid: str):
+        """Find a user-created bot (e.g. web_page_bot) that owns this pipeline."""
+        for bot in self.ap.platform_mgr.bots:
+            if bot.bot_entity.adapter == 'web_page_bot' and bot.bot_entity.use_pipeline_uuid == pipeline_uuid:
+                return bot
+        return None
+
+    async def _handle_receive(self, connection, websocket_adapter, owner_bot=None):
        """处理接收消息的任务"""
        try:
            while connection.is_active:
@@ -203,7 +213,7 @@ class WebSocketChatRouterGroup(group.RouterGroup):
                        logger.debug(f'收到消息: {data} from {connection.connection_id}')

                        # 处理消息（不等待响应，响应会通过broadcast异步发送）
-                        await websocket_adapter.handle_websocket_message(connection, data)
+                        await websocket_adapter.handle_websocket_message(connection, data, owner_bot=owner_bot)

                    elif message_type == 'disconnect':
                        # 客户端主动断开
--- a/src/langbot/pkg/api/http/controller/groups/platform/adapters.py
+++ b/src/langbot/pkg/api/http/controller/groups/platform/adapters.py
@@ -1,5 +1,6 @@
 import quart
 import mimetypes
+import asyncio
 from ... import group
 from langbot.pkg.utils import importutil

@@ -35,3 +36,617 @@ class AdaptersRouterGroup(group.RouterGroup):
            return quart.Response(
                importutil.read_resource_file_bytes(icon_path), mimetype=mimetypes.guess_type(icon_path)[0]
            )
+
+        # In-memory session store for active registrations
+        _create_app_sessions: dict = {}
+        _SESSION_TTL = 900  # 15 minutes
+
+        def _cleanup_expired_sessions():
+            """Remove sessions that have exceeded their TTL."""
+            import time
+
+            now = time.time()
+            expired = [sid for sid, s in _create_app_sessions.items() if now - s.get('created_at', 0) > _SESSION_TTL]
+            for sid in expired:
+                session = _create_app_sessions.pop(sid, None)
+                if session and session.get('task') and not session['task'].done():
+                    session['task'].cancel()
+
+        @self.route('/lark/create-app', methods=['POST'])
+        async def _() -> str:
+            """Start Feishu one-click app registration. Returns session_id + QR code URL."""
+            import uuid
+            import time
+            import lark_oapi as lark
+            from lark_oapi.scene.registration.errors import AppAccessDeniedError, AppExpiredError
+
+            _cleanup_expired_sessions()
+
+            session_id = str(uuid.uuid4())
+            loop = asyncio.get_running_loop()
+
+            session = {
+                'status': 'pending',
+                'qr_url': None,
+                'expire_at': None,
+                'app_id': None,
+                'app_secret': None,
+                'error': None,
+                'created_at': time.time(),
+            }
+            _create_app_sessions[session_id] = session
+
+            def on_qr_code(info):
+                # May be called from a background thread by the SDK;
+                # use call_soon_threadsafe to safely update session state.
+                def _update():
+                    session['qr_url'] = info['url']
+                    session['expire_at'] = time.time() + 600  # 10 minutes
+                    session['status'] = 'waiting'
+
+                loop.call_soon_threadsafe(_update)
+
+            async def run_registration():
+                try:
+                    result = await lark.aregister_app(
+                        on_qr_code=on_qr_code,
+                        source='langbot',
+                    )
+                    session['status'] = 'success'
+                    session['app_id'] = result['client_id']
+                    session['app_secret'] = result['client_secret']
+                except AppAccessDeniedError:
+                    session['status'] = 'error'
+                    session['error'] = 'User denied authorization'
+                except AppExpiredError:
+                    session['status'] = 'error'
+                    session['error'] = 'QR code expired'
+                except Exception as e:
+                    session['status'] = 'error'
+                    session['error'] = str(e)
+
+            task = asyncio.create_task(run_registration())
+            session['task'] = task
+
+            # Wait for QR code to be ready (max 10 seconds)
+            for _ in range(20):
+                if session['qr_url']:
+                    break
+                await asyncio.sleep(0.5)
+
+            if not session['qr_url']:
+                task.cancel()
+                session['status'] = 'error'
+                session['error'] = 'Timeout waiting for QR code'
+                return self.http_status(504, -1, 'Timeout waiting for QR code')
+
+            return self.success(
+                data={
+                    'session_id': session_id,
+                    'qr_url': session['qr_url'],
+                    'expire_at': session['expire_at'],
+                }
+            )
+
+        @self.route('/lark/create-app/status/<session_id>', methods=['GET'])
+        async def _(session_id: str) -> str:
+            """Poll registration status."""
+            session = _create_app_sessions.get(session_id)
+            if not session:
+                return self.http_status(404, -1, 'Session not found')
+
+            data = {'status': session['status']}
+
+            if session['status'] == 'success':
+                data['app_id'] = session['app_id']
+                data['app_secret'] = session['app_secret']
+                _create_app_sessions.pop(session_id, None)
+            elif session['status'] == 'error':
+                data['error'] = session['error']
+                _create_app_sessions.pop(session_id, None)
+
+            return self.success(data=data)
+
+        @self.route('/lark/create-app/<session_id>', methods=['DELETE'])
+        async def _(session_id: str) -> str:
+            """Cancel and clean up a registration session."""
+            session = _create_app_sessions.pop(session_id, None)
+            if session and session.get('task') and not session['task'].done():
+                session['task'].cancel()
+            return self.success(data={})
+
+        # -----------------------------------------------------------------------
+        # WeChat QR Code Login
+        # -----------------------------------------------------------------------
+
+        _weixin_login_sessions: dict = {}
+        _WEIXIN_SESSION_TTL = 600  # 10 minutes (3 retries × 3 min QR validity)
+
+        def _cleanup_expired_weixin_sessions():
+            import time
+
+            now = time.time()
+            expired = [
+                sid for sid, s in _weixin_login_sessions.items() if now - s.get('created_at', 0) > _WEIXIN_SESSION_TTL
+            ]
+            for sid in expired:
+                session = _weixin_login_sessions.pop(sid, None)
+                if session and session.get('task') and not session['task'].done():
+                    session['task'].cancel()
+
+        @self.route('/weixin/login', methods=['POST'])
+        async def _() -> str:
+            """Start WeChat QR code login. Returns session_id + QR code data URL."""
+            import uuid
+            import time
+
+            from langbot.libs.openclaw_weixin_api.client import OpenClawWeixinClient, DEFAULT_BASE_URL
+
+            _cleanup_expired_weixin_sessions()
+
+            session_id = str(uuid.uuid4())
+            loop = asyncio.get_running_loop()
+
+            session = {
+                'status': 'pending',
+                'qr_data_url': None,
+                'expire_at': None,
+                'token': None,
+                'base_url': None,
+                'account_id': None,
+                'error': None,
+                'created_at': time.time(),
+            }
+            _weixin_login_sessions[session_id] = session
+
+            client = OpenClawWeixinClient(
+                base_url=DEFAULT_BASE_URL,
+                token='',
+            )
+
+            async def run_login():
+                try:
+
+                    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)
+
+                    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:
+                    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()
+
+            task = asyncio.create_task(run_login())
+            session['task'] = task
+
+            # Wait for QR code to be ready (max 10 seconds)
+            for _ in range(20):
+                if session['qr_data_url']:
+                    break
+                await asyncio.sleep(0.5)
+
+            if not session['qr_data_url']:
+                task.cancel()
+                session['status'] = 'error'
+                session['error'] = 'Timeout waiting for QR code'
+                return self.http_status(504, -1, 'Timeout waiting for QR code')
+
+            return self.success(
+                data={
+                    'session_id': session_id,
+                    'qr_data_url': session['qr_data_url'],
+                    'expire_at': session['expire_at'],
+                }
+            )
+
+        @self.route('/weixin/login/status/<session_id>', methods=['GET'])
+        async def _(session_id: str) -> str:
+            """Poll WeChat login status."""
+            session = _weixin_login_sessions.get(session_id)
+            if not session:
+                return self.http_status(404, -1, 'Session not found')
+
+            data = {
+                'status': session['status'],
+                'qr_data_url': session['qr_data_url'],
+                'expire_at': session['expire_at'],
+            }
+
+            if session['status'] == 'success':
+                data['token'] = session['token']
+                data['base_url'] = session['base_url']
+                data['account_id'] = session['account_id']
+                _weixin_login_sessions.pop(session_id, None)
+            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)
+
+        @self.route('/weixin/login/<session_id>', methods=['DELETE'])
+        async def _(session_id: str) -> str:
+            """Cancel and clean up a WeChat login session."""
+            session = _weixin_login_sessions.pop(session_id, None)
+            if session and session.get('task') and not session['task'].done():
+                session['task'].cancel()
+            return self.success(data={})
+
+        # -----------------------------------------------------------------------
+        # DingTalk Device Flow QR Code Login
+        # -----------------------------------------------------------------------
+
+        _dingtalk_sessions: dict = {}
+        _DINGTALK_SESSION_TTL = 600  # 10 minutes (QR code validity window)
+
+        def _cleanup_expired_dingtalk_sessions():
+            import time
+
+            now = time.time()
+            expired = [
+                sid for sid, s in _dingtalk_sessions.items() if now - s.get('created_at', 0) > _DINGTALK_SESSION_TTL
+            ]
+            for sid in expired:
+                session = _dingtalk_sessions.pop(sid, None)
+                if session and session.get('task') and not session['task'].done():
+                    session['task'].cancel()
+
+        @self.route('/dingtalk/create-app', methods=['POST'])
+        async def _() -> str:
+            """Start DingTalk one-click app creation via Device Flow. Returns session_id + QR code URL."""
+            import uuid
+            import time
+            import aiohttp
+
+            DINGTALK_BASE_URL = 'https://oapi.dingtalk.com'
+
+            _cleanup_expired_dingtalk_sessions()
+
+            session_id = str(uuid.uuid4())
+
+            session = {
+                'status': 'pending',
+                'qr_url': None,
+                'expire_at': None,
+                'client_id': None,
+                'client_secret': None,
+                'error': None,
+                'created_at': time.time(),
+                'device_code': None,
+                'interval': 5,
+            }
+            _dingtalk_sessions[session_id] = session
+
+            async def run_device_flow():
+                try:
+                    timeout = aiohttp.ClientTimeout(total=10)
+                    async with aiohttp.ClientSession(timeout=timeout) as http:
+                        # Step 1: Init — get nonce
+                        async with http.post(
+                            f'{DINGTALK_BASE_URL}/app/registration/init',
+                            json={'source': 'langbot'},
+                        ) as resp:
+                            try:
+                                data = await resp.json()
+                            except (aiohttp.ContentTypeError, ValueError):
+                                session['status'] = 'error'
+                                session['error'] = 'Invalid response from DingTalk service'
+                                return
+                            if data.get('errcode', -1) != 0:
+                                session['status'] = 'error'
+                                session['error'] = data.get('errmsg', 'Failed to init')
+                                return
+                            nonce = data['nonce']
+
+                        # Step 2: Begin — get device_code + QR URL
+                        async with http.post(
+                            f'{DINGTALK_BASE_URL}/app/registration/begin',
+                            json={'nonce': nonce},
+                        ) as resp:
+                            try:
+                                data = await resp.json()
+                            except (aiohttp.ContentTypeError, ValueError):
+                                session['status'] = 'error'
+                                session['error'] = 'Invalid response from DingTalk service'
+                                return
+                            if data.get('errcode', -1) != 0:
+                                session['status'] = 'error'
+                                session['error'] = data.get('errmsg', 'Failed to begin authorization')
+                                return
+
+                            device_code = data['device_code']
+                            verification_uri_complete = data.get('verification_uri_complete', '')
+                            expires_in = data.get('expires_in', 7200)
+                            interval = data.get('interval', 5)
+
+                            session['device_code'] = device_code
+                            session['interval'] = interval
+                            session['qr_url'] = verification_uri_complete
+                            session['expire_at'] = time.time() + 600  # QR code valid for ~10 min
+                            session['status'] = 'waiting'
+
+                        # Step 3: Poll for authorization result
+                        deadline = time.time() + expires_in
+                        while time.time() < deadline:
+                            await asyncio.sleep(interval)
+
+                            async with http.post(
+                                f'{DINGTALK_BASE_URL}/app/registration/poll',
+                                json={'device_code': device_code},
+                            ) as poll_resp:
+                                try:
+                                    poll_data = await poll_resp.json()
+                                except (aiohttp.ContentTypeError, ValueError):
+                                    continue
+
+                                if poll_data.get('errcode', -1) != 0:
+                                    session['status'] = 'error'
+                                    session['error'] = poll_data.get('errmsg', 'Poll failed')
+                                    return
+
+                                status = poll_data.get('status', '')
+
+                                if status == 'SUCCESS':
+                                    session['status'] = 'success'
+                                    session['client_id'] = poll_data.get('client_id', '')
+                                    session['client_secret'] = poll_data.get('client_secret', '')
+                                    return
+                                elif status == 'FAIL':
+                                    session['status'] = 'error'
+                                    session['error'] = poll_data.get('fail_reason', 'Authorization failed')
+                                    return
+                                elif status == 'EXPIRED':
+                                    session['status'] = 'error'
+                                    session['error'] = 'QR code expired'
+                                    return
+                                # status == 'WAITING': continue polling
+
+                        # Timeout
+                        session['status'] = 'error'
+                        session['error'] = 'QR code expired'
+
+                except asyncio.CancelledError:
+                    return
+                except Exception as e:
+                    session['status'] = 'error'
+                    session['error'] = str(e)
+
+            task = asyncio.create_task(run_device_flow())
+            session['task'] = task
+
+            # Wait for QR code to be ready (max 10 seconds)
+            for _ in range(20):
+                if session['qr_url'] or session['error']:
+                    break
+                await asyncio.sleep(0.5)
+
+            if session['error']:
+                task.cancel()
+                return self.http_status(502, -1, session['error'])
+
+            if not session['qr_url']:
+                task.cancel()
+                session['status'] = 'error'
+                session['error'] = 'Timeout waiting for QR code'
+                return self.http_status(504, -1, 'Timeout waiting for QR code')
+
+            return self.success(
+                data={
+                    'session_id': session_id,
+                    'qr_url': session['qr_url'],
+                    'expire_at': session['expire_at'],
+                }
+            )
+
+        @self.route('/dingtalk/create-app/status/<session_id>', methods=['GET'])
+        async def _(session_id: str) -> str:
+            """Poll DingTalk Device Flow status."""
+            _cleanup_expired_dingtalk_sessions()
+            session = _dingtalk_sessions.get(session_id)
+            if not session:
+                return self.http_status(404, -1, 'Session not found')
+
+            data = {'status': session['status']}
+
+            if session['status'] == 'success':
+                data['client_id'] = session['client_id']
+                data['client_secret'] = session['client_secret']
+                _dingtalk_sessions.pop(session_id, None)
+            elif session['status'] == 'error':
+                data['error'] = session['error']
+                _dingtalk_sessions.pop(session_id, None)
+
+            return self.success(data=data)
+
+        @self.route('/dingtalk/create-app/<session_id>', methods=['DELETE'])
+        async def _(session_id: str) -> str:
+            """Cancel and clean up a DingTalk Device Flow session."""
+            session = _dingtalk_sessions.pop(session_id, None)
+            if session and session.get('task') and not session['task'].done():
+                session['task'].cancel()
+            return self.success(data={})
+
+        # -----------------------------------------------------------------------
+        # WeComBot QR Code One-Click Create
+        # -----------------------------------------------------------------------
+
+        _wecombot_sessions: dict = {}
+        _WECOMBOT_SESSION_TTL = 300  # 5 minutes (WeCom QR validity window)
+
+        def _cleanup_expired_wecombot_sessions():
+            import time
+
+            now = time.time()
+            expired = [
+                sid for sid, s in _wecombot_sessions.items() if now - s.get('created_at', 0) > _WECOMBOT_SESSION_TTL
+            ]
+            for sid in expired:
+                session = _wecombot_sessions.pop(sid, None)
+                if session and session.get('task') and not session['task'].done():
+                    session['task'].cancel()
+
+        @self.route('/wecombot/create-bot', methods=['POST'])
+        async def _() -> str:
+            """Start WeComBot one-click creation via QR code. Returns session_id + QR code URL."""
+            import uuid
+            import time
+            import aiohttp
+
+            WECOM_QC_GENERATE_URL = 'https://work.weixin.qq.com/ai/qc/generate'
+            WECOM_QC_QUERY_URL = 'https://work.weixin.qq.com/ai/qc/query_result'
+
+            _cleanup_expired_wecombot_sessions()
+
+            session_id = str(uuid.uuid4())
+
+            session = {
+                'status': 'pending',
+                'qr_url': None,
+                'expire_at': None,
+                'botid': None,
+                'secret': None,
+                'error': None,
+                'created_at': time.time(),
+                'scode': None,
+                'task': None,
+            }
+            _wecombot_sessions[session_id] = session
+
+            async def run_qr_flow():
+                try:
+                    timeout = aiohttp.ClientTimeout(total=10)
+                    async with aiohttp.ClientSession(timeout=timeout) as http:
+                        # Step 1: Generate QR code
+                        async with http.get(
+                            f'{WECOM_QC_GENERATE_URL}?source=langbot&plat=0',
+                        ) as resp:
+                            try:
+                                data = await resp.json()
+                            except (aiohttp.ContentTypeError, ValueError):
+                                session['status'] = 'error'
+                                session['error'] = 'Invalid response from WeCom service'
+                                return
+                            if not data.get('data', {}).get('scode') or not data.get('data', {}).get('auth_url'):
+                                session['status'] = 'error'
+                                session['error'] = data.get('errmsg', 'Failed to generate QR code')
+                                return
+
+                            scode = data['data']['scode']
+                            auth_url = data['data']['auth_url']
+
+                            session['scode'] = scode
+                            session['qr_url'] = auth_url
+                            session['expire_at'] = time.time() + _WECOMBOT_SESSION_TTL
+                            session['status'] = 'waiting'
+
+                        # Step 2: Poll for scan result
+                        deadline = time.time() + _WECOMBOT_SESSION_TTL
+                        while time.time() < deadline:
+                            await asyncio.sleep(3)
+
+                            async with http.get(
+                                f'{WECOM_QC_QUERY_URL}?scode={scode}',
+                            ) as poll_resp:
+                                try:
+                                    poll_data = await poll_resp.json()
+                                except (aiohttp.ContentTypeError, ValueError):
+                                    continue
+
+                                status = poll_data.get('data', {}).get('status', '')
+                                if status == 'success':
+                                    bot_info = poll_data.get('data', {}).get('bot_info', {})
+                                    if bot_info.get('botid') and bot_info.get('secret'):
+                                        session['status'] = 'success'
+                                        session['botid'] = bot_info['botid']
+                                        session['secret'] = bot_info['secret']
+                                        return
+                                    else:
+                                        session['status'] = 'error'
+                                        session['error'] = 'Scan succeeded but bot info is incomplete'
+                                        return
+
+                        # Timeout
+                        session['status'] = 'error'
+                        session['error'] = 'QR code expired'
+
+                except asyncio.CancelledError:
+                    return
+                except Exception as e:
+                    session['status'] = 'error'
+                    session['error'] = str(e)
+
+            task = asyncio.create_task(run_qr_flow())
+            session['task'] = task
+
+            # Wait for QR code to be ready (max 10 seconds)
+            for _ in range(20):
+                if session['qr_url'] or session['error']:
+                    break
+                await asyncio.sleep(0.5)
+
+            if session['error']:
+                task.cancel()
+                return self.http_status(502, -1, session['error'])
+
+            if not session['qr_url']:
+                task.cancel()
+                session['status'] = 'error'
+                session['error'] = 'Timeout waiting for QR code'
+                return self.http_status(504, -1, 'Timeout waiting for QR code')
+
+            return self.success(
+                data={
+                    'session_id': session_id,
+                    'qr_url': session['qr_url'],
+                    'expire_at': session['expire_at'],
+                }
+            )
+
+        @self.route('/wecombot/create-bot/status/<session_id>', methods=['GET'])
+        async def _(session_id: str) -> str:
+            """Poll WeComBot creation status."""
+            _cleanup_expired_wecombot_sessions()
+            session = _wecombot_sessions.get(session_id)
+            if not session:
+                return self.http_status(404, -1, 'Session not found')
+
+            data = {'status': session['status']}
+
+            if session['status'] == 'success':
+                data['botid'] = session['botid']
+                data['secret'] = session['secret']
+                _wecombot_sessions.pop(session_id, None)
+            elif session['status'] == 'error':
+                data['error'] = session['error']
+                _wecombot_sessions.pop(session_id, None)
+
+            return self.success(data=data)
+
+        @self.route('/wecombot/create-bot/<session_id>', methods=['DELETE'])
+        async def _(session_id: str) -> str:
+            """Cancel and clean up a WeComBot creation session."""
+            session = _wecombot_sessions.pop(session_id, None)
+            if session and session.get('task') and not session['task'].done():
+                session['task'].cancel()
+            return self.success(data={})
--- a/src/langbot/pkg/api/http/controller/groups/plugins.py
+++ b/src/langbot/pkg/api/http/controller/groups/plugins.py
@@ -6,11 +6,50 @@ import re
 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

+# Resolve the built-in page SDK JS from the langbot_plugin package
+_PAGE_SDK_PATH = None
+try:
+    import langbot_plugin.assets as _assets_pkg
+
+    _candidate = os.path.join(os.path.dirname(_assets_pkg.__file__), 'langbot-page-sdk.js')
+    if os.path.exists(_candidate):
+        _PAGE_SDK_PATH = _candidate
+except Exception:
+    pass
+
+
+def _normalize_plugin_asset_path(filepath: str) -> str | None:
+    filepath = filepath.replace('\\', '/')
+    if filepath.startswith('/'):
+        return None
+
+    normalized = posixpath.normpath(filepath)
+    if normalized == '.' or normalized.startswith('../') or normalized == '..':
+        return None
+
+    if normalized.startswith('components/pages/'):
+        return normalized
+
+    return f'assets/{normalized}'
+
+
+def _get_request_origin() -> str:
+    """Return the public request origin, respecting reverse-proxy headers."""
+    forwarded_proto = quart.request.headers.get('X-Forwarded-Proto', '').split(',')[0].strip()
+    forwarded_host = quart.request.headers.get('X-Forwarded-Host', '').split(',')[0].strip()
+
+    scheme = forwarded_proto or quart.request.scheme
+    host = forwarded_host or quart.request.host
+    return f'{scheme}://{host}'
+

@group.group_class('plugins', '/api/v1/plugins')
 class PluginsRouterGroup(group.RouterGroup):
@@ -27,6 +66,15 @@ class PluginsRouterGroup(group.RouterGroup):
        return None

    async def initialize(self) -> None:
+        @self.route('/_sdk/page-sdk.js', methods=['GET'], auth_type=group.AuthType.NONE)
+        async def _() -> quart.Response:
+            """Serve the built-in LangBot page SDK JavaScript."""
+            if _PAGE_SDK_PATH and os.path.exists(_PAGE_SDK_PATH):
+                with open(_PAGE_SDK_PATH, 'r') as f:
+                    content = f.read()
+                return quart.Response(content, mimetype='application/javascript')
+            return quart.Response('// SDK not found', status=404, mimetype='application/javascript')
+
        @self.route('', methods=['GET'], auth_type=group.AuthType.USER_TOKEN_OR_API_KEY)
        async def _() -> str:
            plugins = await self.ap.plugin_connector.list_plugins()
@@ -102,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

@@ -135,15 +191,62 @@ class PluginsRouterGroup(group.RouterGroup):
            return quart.Response(icon_data, mimetype=mime_type)

        @self.route(
-            '/<author>/<plugin_name>/assets/<filepath>',
+            '/<author>/<plugin_name>/assets/<path:filepath>',
            methods=['GET'],
            auth_type=group.AuthType.NONE,
        )
        async def _(author: str, plugin_name: str, filepath: str) -> quart.Response:
-            asset_data = await self.ap.plugin_connector.get_plugin_assets(author, plugin_name, filepath)
+            asset_path = _normalize_plugin_asset_path(filepath)
+            if asset_path is None:
+                return quart.Response('Asset not found', status=404)
+
+            asset_data = await self.ap.plugin_connector.get_plugin_assets(author, plugin_name, asset_path)
+            if not asset_data.get('asset_base64'):
+                return quart.Response('Asset not found', status=404)
            asset_bytes = base64.b64decode(asset_data['asset_base64'])
            mime_type = asset_data['mime_type']
-            return quart.Response(asset_bytes, mimetype=mime_type)
+            resp = quart.Response(asset_bytes, mimetype=mime_type)
+            # CSP for HTML pages served to sandboxed iframes (opaque origin).
+            # 'self' doesn't work in sandboxed iframes — use actual server origin.
+            if mime_type and mime_type.startswith('text/html'):
+                origin = _get_request_origin()
+                resp.headers['Content-Security-Policy'] = (
+                    f'default-src {origin}; '
+                    f"script-src {origin} 'unsafe-inline'; "
+                    f"style-src {origin} 'unsafe-inline'; "
+                    f'img-src {origin} data:; '
+                    f'connect-src {origin}; '
+                    "frame-src 'none'; "
+                    "object-src 'none'"
+                )
+            return resp
+
+        @self.route(
+            '/<author>/<plugin_name>/page-api',
+            methods=['POST'],
+            auth_type=group.AuthType.USER_TOKEN_OR_API_KEY,
+        )
+        async def _(author: str, plugin_name: str) -> str:
+            """Forward a page API request to the plugin."""
+            data = await quart.request.json
+            if not isinstance(data, dict):
+                return self.http_status(400, -1, 'invalid request body')
+
+            page_id = data.get('page_id', '')
+            endpoint = data.get('endpoint', '')
+            method = data.get('method', 'POST')
+            body = data.get('body')
+            if not isinstance(page_id, str) or not isinstance(endpoint, str) or not isinstance(method, str):
+                return self.http_status(400, -1, 'invalid page api request')
+            if not endpoint.startswith('/') or '..' in endpoint:
+                return self.http_status(400, -1, 'invalid endpoint')
+
+            result = await self.ap.plugin_connector.handle_page_api(
+                author, plugin_name, page_id, endpoint, method.upper(), body
+            )
+            if result.get('error'):
+                return self.http_status(400, -1, result['error'])
+            return self.success(data=result.get('data'))

        @self.route('/github/releases', methods=['POST'], auth_type=group.AuthType.USER_TOKEN_OR_API_KEY)
        async def _() -> str:
--- a/src/langbot/pkg/api/http/controller/groups/system.py
+++ b/src/langbot/pkg/api/http/controller/groups/system.py
@@ -136,16 +136,9 @@ class SystemRouterGroup(group.RouterGroup):

            return self.success(data=task.to_dict())

-        @self.route('/debug/exec', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
+        @self.route('/storage-analysis', methods=['GET'], 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}))
+            return self.success(data=await self.ap.maintenance_service.get_storage_analysis())

        @self.route(
            '/debug/plugin/action',
--- a/src/langbot/pkg/api/http/controller/groups/user.py
+++ b/src/langbot/pkg/api/http/controller/groups/user.py
@@ -146,6 +146,7 @@ class UserRouterGroup(group.RouterGroup):
                return self.fail(3, str(e))
            except ValueError as e:
                traceback.print_exc()
+                self.ap.logger.warning(f'Space OAuth callback failed: {e}')
                return self.fail(1, str(e))
            except Exception as e:
                traceback.print_exc()
--- a/src/langbot/pkg/api/http/service/apikey.py
+++ b/src/langbot/pkg/api/http/service/apikey.py
@@ -52,6 +52,9 @@ class ApiKeyService:

    async def verify_api_key(self, key: str) -> bool:
        """Verify if an API key is valid"""
+        if not isinstance(key, str) or not key.startswith('lbk_'):
+            return False
+
        result = await self.ap.persistence_mgr.execute_async(
            sqlalchemy.select(apikey.ApiKey).where(apikey.ApiKey.key == key)
        )
--- a/src/langbot/pkg/api/http/service/bot.py
+++ b/src/langbot/pkg/api/http/service/bot.py
@@ -99,11 +99,11 @@ class BotService:
        # TODO: 检查配置信息格式
        bot_data['uuid'] = str(uuid.uuid4())

-        # checkout the default pipeline
+        # bind the most recently updated pipeline if any exist
        result = await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.select(persistence_pipeline.LegacyPipeline).where(
-                persistence_pipeline.LegacyPipeline.is_default == True
-            )
+            sqlalchemy.select(persistence_pipeline.LegacyPipeline)
+            .order_by(persistence_pipeline.LegacyPipeline.updated_at.desc())
+            .limit(1)
        )
        pipeline = result.first()
        if pipeline is not None:
@@ -120,24 +120,26 @@ class BotService:

    async def update_bot(self, bot_uuid: str, bot_data: dict) -> None:
        """Update bot"""
-        if 'uuid' in bot_data:
-            del bot_data['uuid']
+        update_data = bot_data.copy()
+
+        if 'uuid' in update_data:
+            del update_data['uuid']

        # set use_pipeline_name
-        if 'use_pipeline_uuid' in bot_data:
+        if 'use_pipeline_uuid' in update_data:
            result = await self.ap.persistence_mgr.execute_async(
                sqlalchemy.select(persistence_pipeline.LegacyPipeline).where(
-                    persistence_pipeline.LegacyPipeline.uuid == bot_data['use_pipeline_uuid']
+                    persistence_pipeline.LegacyPipeline.uuid == update_data['use_pipeline_uuid']
                )
            )
            pipeline = result.first()
            if pipeline is not None:
-                bot_data['use_pipeline_name'] = pipeline.name
+                update_data['use_pipeline_name'] = pipeline.name
            else:
                raise Exception('Pipeline not found')

        await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.update(persistence_bot.Bot).values(bot_data).where(persistence_bot.Bot.uuid == bot_uuid)
+            sqlalchemy.update(persistence_bot.Bot).values(update_data).where(persistence_bot.Bot.uuid == bot_uuid)
        )
        await self.ap.platform_mgr.remove_bot(bot_uuid)

--- a/src/langbot/pkg/api/http/service/knowledge.py
+++ b/src/langbot/pkg/api/http/service/knowledge.py
@@ -31,15 +31,126 @@ class KnowledgeService:
        if not knowledge_engine_plugin_id:
            raise ValueError('knowledge_engine_plugin_id is required')

+        creation_settings = kb_data.get('creation_settings', {})
+        retrieval_settings = kb_data.get('retrieval_settings', {})
+
+        # Validate required fields based on plugin's creation_schema and retrieval_schema
+        await self._validate_schema_required_fields(
+            knowledge_engine_plugin_id,
+            creation_settings,
+            retrieval_settings,
+        )
+
        kb = await self.ap.rag_mgr.create_knowledge_base(
            name=kb_data.get('name', 'Untitled'),
            knowledge_engine_plugin_id=knowledge_engine_plugin_id,
-            creation_settings=kb_data.get('creation_settings', {}),
-            retrieval_settings=kb_data.get('retrieval_settings', {}),
+            creation_settings=creation_settings,
+            retrieval_settings=retrieval_settings,
            description=kb_data.get('description', ''),
        )
        return kb.uuid

+    async def _validate_schema_required_fields(
+        self,
+        plugin_id: str,
+        creation_settings: dict,
+        retrieval_settings: dict,
+    ) -> None:
+        """Validate required fields based on plugin's creation_schema and retrieval_schema.
+
+        This is a business-agnostic validation that checks all fields marked as
+        required in the plugin's schema, regardless of field type.
+
+        Args:
+            plugin_id: Knowledge Engine plugin ID.
+            creation_settings: User-provided creation settings.
+            retrieval_settings: User-provided retrieval settings.
+
+        Raises:
+            ValueError: If any required field is missing or empty.
+        """
+        # Validate creation_schema
+        try:
+            creation_schema = await self.ap.plugin_connector.get_rag_creation_schema(plugin_id)
+            self._check_required_fields(creation_schema, creation_settings, 'creation_settings')
+        except ValueError:
+            raise
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to get creation_schema for validation: {e}')
+
+        # Validate retrieval_schema
+        try:
+            retrieval_schema = await self.ap.plugin_connector.get_rag_retrieval_schema(plugin_id)
+            self._check_required_fields(retrieval_schema, retrieval_settings, 'retrieval_settings')
+        except ValueError:
+            raise
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to get retrieval_schema for validation: {e}')
+
+    def _check_required_fields(
+        self,
+        schema: dict | list,
+        settings: dict,
+        context: str,
+    ) -> None:
+        """Check required fields in schema against provided settings.
+
+        Args:
+            schema: Plugin-defined schema (can be list or dict with 'schema' key).
+            settings: User-provided settings values.
+            context: Context name for error messages (e.g., 'creation_settings').
+
+        Raises:
+            ValueError: If a required field is missing or empty.
+        """
+        if not schema:
+            return
+
+        # schema can be a list directly, or a dict with 'schema' key
+        items = schema if isinstance(schema, list) else schema.get('schema', [])
+        if not items:
+            return
+
+        for item in items:
+            field_name = item.get('name')
+            if not field_name:
+                continue
+
+            is_required = item.get('required', False)
+            if not is_required:
+                continue
+
+            # Check show_if condition - if field is conditionally shown, only validate when condition is met
+            show_if = item.get('show_if')
+            if show_if:
+                depend_field = show_if.get('field')
+                operator = show_if.get('operator')
+                expected_value = show_if.get('value')
+
+                if depend_field and operator:
+                    depend_value = settings.get(depend_field)
+                    # If show_if condition is not met, skip validation for this field
+                    if operator == 'eq' and depend_value != expected_value:
+                        continue
+                    if operator == 'neq' and depend_value == expected_value:
+                        continue
+                    if operator == 'in' and isinstance(expected_value, list) and depend_value not in expected_value:
+                        continue
+
+            value = settings.get(field_name)
+
+            # Validate required field has a non-empty value
+            if value is None or (isinstance(value, str) and value.strip() == ''):
+                # Get field label for friendly error message
+                label = item.get('label', {})
+                field_label = (
+                    label.get('en_US', field_name)
+                    or label.get('zh_Hans', field_name)
+                    or label.get('zh_Hant', field_name)
+                    or field_name
+                )
+                raise ValueError(f'{field_label} is required ({context}.{field_name})')
+
    async def update_knowledge_base(self, kb_uuid: str, kb_data: dict) -> None:
        """更新知识库"""
        # Filter to only mutable fields
--- a/src/langbot/pkg/api/http/service/maintenance.py
+++ b/src/langbot/pkg/api/http/service/maintenance.py
@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import datetime
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import sqlalchemy
+
+from ....core import app
+from ....entity.persistence import bstorage as persistence_bstorage
+from ....entity.persistence import monitoring as persistence_monitoring
+
+
+LOG_FILE_PATTERN = re.compile(r'^langbot-(\d{4}-\d{2}-\d{2})\.log(?:\.\d+)?$')
+DEFAULT_UPLOAD_FILE_RETENTION_DAYS = 7
+DEFAULT_LOG_RETENTION_DAYS = 3
+
+
+class MaintenanceService:
+    """Storage maintenance and diagnostics."""
+
+    ap: app.Application
+
+    def __init__(self, ap: app.Application) -> None:
+        self.ap = ap
+
+    async def cleanup_expired_files(self) -> dict[str, int]:
+        cleanup_cfg = self.ap.instance_config.data.get('storage', {}).get('cleanup', {})
+        upload_retention_days = self._positive_int(
+            cleanup_cfg.get('uploaded_file_retention_days'),
+            DEFAULT_UPLOAD_FILE_RETENTION_DAYS,
+            'storage.cleanup.uploaded_file_retention_days',
+        )
+        log_retention_days = self._positive_int(
+            cleanup_cfg.get('log_retention_days'),
+            DEFAULT_LOG_RETENTION_DAYS,
+            'storage.cleanup.log_retention_days',
+        )
+
+        return {
+            'uploaded_files': await self._cleanup_expired_uploaded_files(upload_retention_days),
+            'log_files': self._cleanup_expired_log_files(log_retention_days),
+        }
+
+    async def get_storage_analysis(self) -> dict[str, Any]:
+        cleanup_cfg = self.ap.instance_config.data.get('storage', {}).get('cleanup', {})
+        upload_retention_days = self._positive_int(
+            cleanup_cfg.get('uploaded_file_retention_days'),
+            DEFAULT_UPLOAD_FILE_RETENTION_DAYS,
+            'storage.cleanup.uploaded_file_retention_days',
+        )
+        log_retention_days = self._positive_int(
+            cleanup_cfg.get('log_retention_days'),
+            DEFAULT_LOG_RETENTION_DAYS,
+            'storage.cleanup.log_retention_days',
+        )
+
+        database_cfg = self.ap.instance_config.data.get('database', {})
+        database_type = database_cfg.get('use', 'sqlite')
+        database_path = (
+            Path(database_cfg.get('sqlite', {}).get('path', 'data/langbot.db')) if database_type == 'sqlite' else None
+        )
+        roots: list[tuple[str, Path | None]] = [
+            ('database', database_path),
+            ('logs', Path('data/logs')),
+            ('storage', Path('data/storage')),
+            ('vector_store', Path('data/chroma')),
+            ('plugins', Path('data/plugins')),
+            ('mcp', Path('data/mcp')),
+            ('temp', Path('data/temp')),
+        ]
+
+        sections = []
+        for key, path in roots:
+            sections.append(
+                {
+                    'key': key,
+                    'path': str(path) if path else '',
+                    'exists': path.exists() if path else False,
+                    'size_bytes': self._path_size(path) if path else 0,
+                    'file_count': self._file_count(path) if path else 0,
+                }
+            )
+
+        monitoring_counts = await self._monitoring_counts()
+        binary_storage = await self._binary_storage_stats()
+        upload_candidates = await self._expired_uploaded_candidates(upload_retention_days)
+        log_candidates = self._expired_log_candidates(log_retention_days)
+
+        return {
+            'generated_at': datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            'cleanup_policy': {
+                'uploaded_file_retention_days': upload_retention_days,
+                'log_retention_days': log_retention_days,
+            },
+            'sections': sections,
+            'database': {
+                'type': database_type,
+                'monitoring_counts': monitoring_counts,
+                'binary_storage': binary_storage,
+            },
+            'cleanup_candidates': {
+                'uploaded_files': upload_candidates,
+                'log_files': log_candidates,
+            },
+            'tasks': self.ap.task_mgr.get_stats() if self.ap.task_mgr else {},
+        }
+
+    async def _cleanup_expired_uploaded_files(self, retention_days: int) -> int:
+        provider = self.ap.storage_mgr.storage_provider
+        provider_name = provider.__class__.__name__
+        if provider_name == 'LocalStorageProvider':
+            candidates = self._expired_local_upload_candidates(retention_days, include_paths=True)
+            deleted = 0
+            for item in candidates:
+                try:
+                    os.remove(item['path'])
+                    deleted += 1
+                except FileNotFoundError:
+                    pass
+                except Exception as e:
+                    self.ap.logger.warning(f'Failed to delete expired uploaded file {item["key"]}: {e}')
+            return deleted
+
+        if provider_name == 'S3StorageProvider':
+            return await self._cleanup_expired_s3_uploaded_files(retention_days)
+
+        return 0
+
+    async def _expired_uploaded_candidates(self, retention_days: int) -> list[dict[str, Any]]:
+        provider_name = self.ap.storage_mgr.storage_provider.__class__.__name__
+        if provider_name == 'LocalStorageProvider':
+            return self._expired_local_upload_candidates(retention_days)
+        if provider_name == 'S3StorageProvider':
+            return await self._expired_s3_upload_candidates(retention_days)
+        return []
+
+    async def _cleanup_expired_s3_uploaded_files(self, retention_days: int) -> int:
+        provider = self.ap.storage_mgr.storage_provider
+        candidates = await self._expired_s3_upload_candidates(retention_days)
+        deleted = 0
+        for item in candidates:
+            await provider.delete(item['key'])
+            deleted += 1
+        return deleted
+
+    async def _expired_s3_upload_candidates(self, retention_days: int) -> list[dict[str, Any]]:
+        provider = self.ap.storage_mgr.storage_provider
+        cutoff = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=retention_days)
+        candidates = []
+        paginator = provider.s3_client.get_paginator('list_objects_v2')
+
+        for page in paginator.paginate(Bucket=provider.bucket_name):
+            for obj in page.get('Contents', []):
+                key = obj.get('Key', '')
+                last_modified = obj.get('LastModified')
+                if not self._is_uploaded_file_key(key):
+                    continue
+                if last_modified and last_modified < cutoff:
+                    candidates.append(
+                        {
+                            'key': key,
+                            'size_bytes': obj.get('Size', 0),
+                            'modified_at': last_modified.isoformat(),
+                        }
+                    )
+
+        return candidates
+
+    def _cleanup_expired_log_files(self, retention_days: int) -> int:
+        deleted = 0
+        for item in self._expired_log_candidates(retention_days, include_paths=True):
+            try:
+                os.remove(item['path'])
+                deleted += 1
+            except FileNotFoundError:
+                pass
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to delete expired log file {item["name"]}: {e}')
+        return deleted
+
+    def _expired_local_upload_candidates(
+        self, retention_days: int, include_paths: bool = False
+    ) -> list[dict[str, Any]]:
+        storage_root = Path('data/storage')
+        if not storage_root.exists():
+            return []
+
+        cutoff = datetime.datetime.now().timestamp() - retention_days * 86400
+        candidates = []
+        for entry in storage_root.iterdir():
+            if not entry.is_file() or not self._is_uploaded_file_key(entry.name):
+                continue
+            stat = entry.stat()
+            if stat.st_mtime >= cutoff:
+                continue
+            item = {
+                'key': entry.name,
+                'size_bytes': stat.st_size,
+                'modified_at': datetime.datetime.fromtimestamp(stat.st_mtime, datetime.timezone.utc).isoformat(),
+            }
+            if include_paths:
+                item['path'] = str(entry)
+            candidates.append(item)
+        return candidates
+
+    def _expired_log_candidates(self, retention_days: int, include_paths: bool = False) -> list[dict[str, Any]]:
+        log_root = Path('data/logs')
+        if not log_root.exists():
+            return []
+
+        cutoff_date = datetime.date.today() - datetime.timedelta(days=retention_days - 1)
+        candidates = []
+        for entry in log_root.iterdir():
+            if not entry.is_file():
+                continue
+            match = LOG_FILE_PATTERN.match(entry.name)
+            if not match:
+                continue
+            try:
+                file_date = datetime.date.fromisoformat(match.group(1))
+            except ValueError:
+                continue
+            if file_date >= cutoff_date:
+                continue
+            stat = entry.stat()
+            item = {
+                'name': entry.name,
+                'date': file_date.isoformat(),
+                'size_bytes': stat.st_size,
+            }
+            if include_paths:
+                item['path'] = str(entry)
+            candidates.append(item)
+        return candidates
+
+    def _is_uploaded_file_key(self, key: str) -> bool:
+        return '/' not in key and not key.startswith('plugin_config_')
+
+    async def _monitoring_counts(self) -> dict[str, int]:
+        tables = {
+            'messages': persistence_monitoring.MonitoringMessage.id,
+            'llm_calls': persistence_monitoring.MonitoringLLMCall.id,
+            'embedding_calls': persistence_monitoring.MonitoringEmbeddingCall.id,
+            'errors': persistence_monitoring.MonitoringError.id,
+            'sessions': persistence_monitoring.MonitoringSession.session_id,
+            'feedback': persistence_monitoring.MonitoringFeedback.id,
+        }
+        counts: dict[str, int] = {}
+        for key, column in tables.items():
+            result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(sqlalchemy.func.count(column)))
+            counts[key] = result.scalar() or 0
+        return counts
+
+    async def _binary_storage_stats(self) -> dict[str, Any]:
+        count_result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(sqlalchemy.func.count(persistence_bstorage.BinaryStorage.unique_key))
+        )
+        size_bytes = None
+        try:
+            size_result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.select(sqlalchemy.func.sum(sqlalchemy.func.length(persistence_bstorage.BinaryStorage.value)))
+            )
+            size_bytes = size_result.scalar() or 0
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to estimate binary storage size: {e}')
+
+        return {
+            'count': count_result.scalar() or 0,
+            'size_bytes': size_bytes,
+        }
+
+    def _path_size(self, path: Path) -> int:
+        if not path.exists():
+            return 0
+        if path.is_file():
+            return path.stat().st_size
+        total = 0
+        for root, _, files in os.walk(path):
+            for file_name in files:
+                file_path = Path(root) / file_name
+                try:
+                    total += file_path.stat().st_size
+                except FileNotFoundError:
+                    pass
+        return total
+
+    def _file_count(self, path: Path) -> int:
+        if not path.exists():
+            return 0
+        if path.is_file():
+            return 1
+        count = 0
+        for _, _, files in os.walk(path):
+            count += len(files)
+        return count
+
+    def _positive_int(self, value: Any, default: int, name: str) -> int:
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError):
+            self.ap.logger.warning(f'Invalid {name}: {value!r}, using {default}')
+            return default
+        if parsed < 1:
+            self.ap.logger.warning(f'Invalid {name}: {value!r}, using {default}')
+            return default
+        return parsed
--- a/src/langbot/pkg/api/http/service/model.py
+++ b/src/langbot/pkg/api/http/service/model.py
@@ -23,6 +23,17 @@ def _parse_provider_api_keys(provider_dict: dict) -> dict:
    return provider_dict


+def _runtime_model_data(model_uuid: str, model_data: dict) -> dict:
+    """Return model data for rebuilding runtime models after an update.
+
+    Update payloads intentionally omit uuid before writing to the database.
+    Runtime model entities still need the stable uuid so pipeline configs can
+    resolve the in-memory model immediately after an edit, without requiring a
+    process restart.
+    """
+    return {**model_data, 'uuid': model_uuid}
+
+
 class LLMModelsService:
    ap: app.Application

@@ -173,7 +184,7 @@ class LLMModelsService:
            raise Exception('provider not found')

        runtime_llm_model = await self.ap.model_mgr.load_llm_model_with_provider(
-            persistence_model.LLMModel(**model_data),
+            persistence_model.LLMModel(**_runtime_model_data(model_uuid, model_data)),
            runtime_provider,
        )
        self.ap.model_mgr.llm_models.append(runtime_llm_model)
@@ -334,7 +345,7 @@ class EmbeddingModelsService:
            raise Exception('provider not found')

        runtime_embedding_model = await self.ap.model_mgr.load_embedding_model_with_provider(
-            persistence_model.EmbeddingModel(**model_data),
+            persistence_model.EmbeddingModel(**_runtime_model_data(model_uuid, model_data)),
            runtime_provider,
        )
        self.ap.model_mgr.embedding_models.append(runtime_embedding_model)
@@ -492,7 +503,7 @@ class RerankModelsService:
            raise Exception('provider not found')

        runtime_rerank_model = await self.ap.model_mgr.load_rerank_model_with_provider(
-            persistence_model.RerankModel(**model_data),
+            persistence_model.RerankModel(**_runtime_model_data(model_uuid, model_data)),
            runtime_provider,
        )
        self.ap.model_mgr.rerank_models.append(runtime_rerank_model)
--- a/src/langbot/pkg/api/http/service/monitoring.py
+++ b/src/langbot/pkg/api/http/service/monitoring.py
@@ -18,55 +18,119 @@ class MonitoringService:

    # ========== Cleanup Methods ==========

-    async def cleanup_expired_records(self, retention_days: int) -> dict[str, int]:
+    async def cleanup_expired_records(self, retention_days: int, batch_size: int = 1000) -> dict[str, int]:
        """Delete monitoring records older than the specified retention period.

        Args:
            retention_days: Number of days to retain records.
+            batch_size: Maximum rows to delete per table batch.

        Returns:
            A dict mapping table name to the number of deleted rows.
        """
+        if retention_days < 1:
+            raise ValueError('retention_days must be >= 1')
+        if batch_size < 1:
+            raise ValueError('batch_size must be >= 1')
+
        cutoff = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None) - datetime.timedelta(
            days=retention_days
        )

-        tables_and_columns: list[tuple[str, type, sqlalchemy.Column]] = [
+        tables_and_columns: list[tuple[str, type, sqlalchemy.Column, sqlalchemy.Column]] = [
            (
                'monitoring_messages',
                persistence_monitoring.MonitoringMessage,
                persistence_monitoring.MonitoringMessage.timestamp,
+                persistence_monitoring.MonitoringMessage.id,
            ),
            (
                'monitoring_llm_calls',
                persistence_monitoring.MonitoringLLMCall,
                persistence_monitoring.MonitoringLLMCall.timestamp,
+                persistence_monitoring.MonitoringLLMCall.id,
            ),
            (
                'monitoring_embedding_calls',
                persistence_monitoring.MonitoringEmbeddingCall,
                persistence_monitoring.MonitoringEmbeddingCall.timestamp,
+                persistence_monitoring.MonitoringEmbeddingCall.id,
            ),
            (
                'monitoring_errors',
                persistence_monitoring.MonitoringError,
                persistence_monitoring.MonitoringError.timestamp,
+                persistence_monitoring.MonitoringError.id,
            ),
            (
                'monitoring_sessions',
                persistence_monitoring.MonitoringSession,
                persistence_monitoring.MonitoringSession.last_activity,
+                persistence_monitoring.MonitoringSession.session_id,
+            ),
+            (
+                'monitoring_feedback',
+                persistence_monitoring.MonitoringFeedback,
+                persistence_monitoring.MonitoringFeedback.timestamp,
+                persistence_monitoring.MonitoringFeedback.id,
            ),
        ]

        deleted_counts: dict[str, int] = {}

-        for table_name, model_cls, ts_column in tables_and_columns:
-            result = await self.ap.persistence_mgr.execute_async(sqlalchemy.delete(model_cls).where(ts_column < cutoff))
-            deleted_counts[table_name] = result.rowcount
+        for table_name, model_cls, ts_column, pk_column in tables_and_columns:
+            deleted_counts[table_name] = await self._delete_expired_in_batches(
+                model_cls=model_cls,
+                ts_column=ts_column,
+                pk_column=pk_column,
+                cutoff=cutoff,
+                batch_size=batch_size,
+            )
+
+        if sum(deleted_counts.values()) > 0:
+            await self._release_sqlite_space()

        return deleted_counts

+    async def _delete_expired_in_batches(
+        self,
+        model_cls: type,
+        ts_column: sqlalchemy.Column,
+        pk_column: sqlalchemy.Column,
+        cutoff: datetime.datetime,
+        batch_size: int,
+    ) -> int:
+        deleted_total = 0
+
+        while True:
+            select_result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.select(pk_column).where(ts_column < cutoff).limit(batch_size)
+            )
+            pk_values = list(select_result.scalars().all())
+            if not pk_values:
+                break
+
+            delete_result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.delete(model_cls).where(pk_column.in_(pk_values))
+            )
+            deleted = delete_result.rowcount or 0
+            deleted_total += deleted
+
+            if len(pk_values) < batch_size:
+                break
+
+        return deleted_total
+
+    async def _release_sqlite_space(self) -> None:
+        database_type = self.ap.instance_config.data.get('database', {}).get('use', 'sqlite')
+        if database_type != 'sqlite':
+            return
+
+        async with self.ap.persistence_mgr.get_db_engine().connect() as conn:
+            autocommit_conn = await conn.execution_options(isolation_level='AUTOCOMMIT')
+            await autocommit_conn.execute(sqlalchemy.text('PRAGMA wal_checkpoint(TRUNCATE)'))
+            await autocommit_conn.execute(sqlalchemy.text('VACUUM'))
+
    # ========== Recording Methods ==========

    async def record_message(
--- a/src/langbot/pkg/api/http/service/pipeline.py
+++ b/src/langbot/pkg/api/http/service/pipeline.py
@@ -113,14 +113,9 @@ class PipelineService:
        return pipeline_data['uuid']

    async def update_pipeline(self, pipeline_uuid: str, pipeline_data: dict) -> None:
-        if 'uuid' in pipeline_data:
-            del pipeline_data['uuid']
-        if 'for_version' in pipeline_data:
-            del pipeline_data['for_version']
-        if 'stages' in pipeline_data:
-            del pipeline_data['stages']
-        if 'is_default' in pipeline_data:
-            del pipeline_data['is_default']
+        pipeline_data = pipeline_data.copy()
+        for protected_field in ('uuid', 'for_version', 'stages', 'is_default'):
+            pipeline_data.pop(protected_field, None)

        await self.ap.persistence_mgr.execute_async(
            sqlalchemy.update(persistence_pipeline.LegacyPipeline)
--- a/src/langbot/pkg/api/http/service/provider.py
+++ b/src/langbot/pkg/api/http/service/provider.py
@@ -17,6 +17,24 @@ class ModelProviderService:
    def __init__(self, ap: app.Application) -> None:
        self.ap = ap

+    @staticmethod
+    def _normalize_api_keys(api_keys: str | list[str] | tuple[str, ...] | None) -> list[str]:
+        if api_keys is None:
+            return []
+
+        raw_keys = [api_keys] if isinstance(api_keys, str) else list(api_keys)
+        normalized_keys = []
+        seen_keys = set()
+
+        for raw_key in raw_keys:
+            normalized_key = raw_key.strip() if isinstance(raw_key, str) else ''
+            if not normalized_key or normalized_key in seen_keys:
+                continue
+            normalized_keys.append(normalized_key)
+            seen_keys.add(normalized_key)
+
+        return normalized_keys
+
    async def get_providers(self) -> list[dict]:
        """Get all providers"""
        result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(persistence_model.ModelProvider))
@@ -59,6 +77,7 @@ class ModelProviderService:
    async def create_provider(self, provider_data: dict) -> str:
        """Create a new provider"""
        provider_data['uuid'] = str(uuid.uuid4())
+        provider_data['api_keys'] = self._normalize_api_keys(provider_data.get('api_keys'))
        await self.ap.persistence_mgr.execute_async(
            sqlalchemy.insert(persistence_model.ModelProvider).values(**provider_data)
        )
@@ -72,6 +91,8 @@ class ModelProviderService:
        """Update an existing provider"""
        if 'uuid' in provider_data:
            del provider_data['uuid']
+        if 'api_keys' in provider_data:
+            provider_data['api_keys'] = self._normalize_api_keys(provider_data.get('api_keys'))
        await self.ap.persistence_mgr.execute_async(
            sqlalchemy.update(persistence_model.ModelProvider)
            .where(persistence_model.ModelProvider.uuid == provider_uuid)
@@ -141,6 +162,8 @@ class ModelProviderService:

    async def find_or_create_provider(self, requester: str, base_url: str, api_keys: list) -> str:
        """Find existing provider or create new one"""
+        api_keys = self._normalize_api_keys(api_keys)
+
        # Try to find existing provider with same config
        result = await self.ap.persistence_mgr.execute_async(
            sqlalchemy.select(persistence_model.ModelProvider).where(
@@ -168,7 +191,7 @@ class ModelProviderService:
                'name': provider_name,
                'requester': requester,
                'base_url': base_url,
-                'api_keys': api_keys or [],
+                'api_keys': api_keys,
            }
        )

@@ -177,7 +200,7 @@ class ModelProviderService:
        await self.ap.persistence_mgr.execute_async(
            sqlalchemy.update(persistence_model.ModelProvider)
            .where(persistence_model.ModelProvider.uuid == '00000000-0000-0000-0000-000000000000')
-            .values(api_keys=[api_key])
+            .values(api_keys=self._normalize_api_keys(api_key))
        )
        await self.ap.model_mgr.reload_provider('00000000-0000-0000-0000-000000000000')

--- a/src/langbot/pkg/api/http/service/space.py
+++ b/src/langbot/pkg/api/http/service/space.py
@@ -179,7 +179,7 @@ class SpaceService:
        space_url = space_config['url']

        session = httpclient.get_session()
-        async with session.get(f'{space_url}/api/v1/models') as response:
+        async with session.get(f'{space_url}/api/v1/models', params={'page_size': 100}) as response:
            if response.status != 200:
                raise ValueError(f'Failed to get models: {await response.text()}')
            data = await response.json()
--- a/src/langbot/pkg/core/app.py
+++ b/src/langbot/pkg/core/app.py
@@ -31,6 +31,7 @@ from ..api.http.service import mcp as mcp_service
 from ..api.http.service import apikey as apikey_service
 from ..api.http.service import webhook as webhook_service
 from ..api.http.service import monitoring as monitoring_service
+from ..api.http.service import maintenance as maintenance_service

 from ..discover import engine as discover_engine
 from ..storage import mgr as storagemgr
@@ -155,6 +156,8 @@ class Application:

    monitoring_service: monitoring_service.MonitoringService = None

+    maintenance_service: maintenance_service.MaintenanceService = None
+
    def __init__(self):
        pass

@@ -194,14 +197,30 @@ class Application:
            monitoring_cfg = self.instance_config.data.get('monitoring', {})
            auto_cleanup_cfg = monitoring_cfg.get('auto_cleanup', {})
            if auto_cleanup_cfg.get('enabled', True):
-                retention_days = auto_cleanup_cfg.get('retention_days', 30)
-                check_interval_hours = auto_cleanup_cfg.get('check_interval_hours', 1)
+                retention_days = self._get_positive_int_config(
+                    auto_cleanup_cfg.get('retention_days', 30),
+                    default=30,
+                    name='monitoring.auto_cleanup.retention_days',
+                )
+                delete_batch_size = self._get_positive_int_config(
+                    auto_cleanup_cfg.get('delete_batch_size', 1000),
+                    default=1000,
+                    name='monitoring.auto_cleanup.delete_batch_size',
+                )
+                check_interval_hours = self._get_positive_float_config(
+                    auto_cleanup_cfg.get('check_interval_hours', 1),
+                    default=1,
+                    name='monitoring.auto_cleanup.check_interval_hours',
+                )

                async def monitoring_cleanup_loop():
                    check_interval_seconds = check_interval_hours * 3600
                    while True:
                        try:
-                            deleted = await self.monitoring_service.cleanup_expired_records(retention_days)
+                            deleted = await self.monitoring_service.cleanup_expired_records(
+                                retention_days,
+                                batch_size=delete_batch_size,
+                            )
                            total_deleted = sum(deleted.values())
                            if total_deleted > 0:
                                self.logger.info(
@@ -218,6 +237,33 @@ class Application:
                    scopes=[core_entities.LifecycleControlScope.APPLICATION],
                )

+            # Start storage/log maintenance task if enabled
+            storage_cleanup_cfg = self.instance_config.data.get('storage', {}).get('cleanup', {})
+            if storage_cleanup_cfg.get('enabled', True) and self.maintenance_service is not None:
+                check_interval_hours = self._get_positive_float_config(
+                    storage_cleanup_cfg.get('check_interval_hours', 1),
+                    default=1,
+                    name='storage.cleanup.check_interval_hours',
+                )
+
+                async def storage_cleanup_loop():
+                    check_interval_seconds = check_interval_hours * 3600
+                    while True:
+                        try:
+                            deleted = await self.maintenance_service.cleanup_expired_files()
+                            total_deleted = sum(deleted.values())
+                            if total_deleted > 0:
+                                self.logger.info(f'Storage maintenance: deleted expired files: {deleted}')
+                        except Exception as e:
+                            self.logger.warning(f'Storage maintenance error: {e}')
+                        await asyncio.sleep(check_interval_seconds)
+
+                self.task_mgr.create_task(
+                    storage_cleanup_loop(),
+                    name='storage-maintenance',
+                    scopes=[core_entities.LifecycleControlScope.APPLICATION],
+                )
+
            self.task_mgr.create_task(
                never_ending(),
                name='never-ending-task',
@@ -232,6 +278,28 @@ class Application:
            self.logger.error(f'Application runtime fatal exception: {e}')
            self.logger.debug(f'Traceback: {traceback.format_exc()}')

+    def _get_positive_int_config(self, value, default: int, name: str) -> int:
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError):
+            self.logger.warning(f'Invalid {name}: {value!r}, using {default}')
+            return default
+        if parsed < 1:
+            self.logger.warning(f'Invalid {name}: {value!r}, using {default}')
+            return default
+        return parsed
+
+    def _get_positive_float_config(self, value, default: float, name: str) -> float:
+        try:
+            parsed = float(value)
+        except (TypeError, ValueError):
+            self.logger.warning(f'Invalid {name}: {value!r}, using {default}')
+            return default
+        if parsed <= 0:
+            self.logger.warning(f'Invalid {name}: {value!r}, using {default}')
+            return default
+        return parsed
+
    def dispose(self):
        self.plugin_connector.dispose()

--- a/src/langbot/pkg/core/boot.py
+++ b/src/langbot/pkg/core/boot.py
@@ -46,12 +46,14 @@ async def make_app(loop: asyncio.AbstractEventLoop) -> app.Application:


 async def main(loop: asyncio.AbstractEventLoop):
+    app_inst: app.Application | None = None
    try:
        # Hang system signal processing
        import signal

        def signal_handler(sig, frame):
-            app_inst.dispose()
+            if app_inst is not None:
+                app_inst.dispose()
            print('[Signal] Program exit.')
            os._exit(0)

--- a/src/langbot/pkg/core/stages/build_app.py
+++ b/src/langbot/pkg/core/stages/build_app.py
@@ -28,6 +28,7 @@ from ...api.http.service import mcp as mcp_service
 from ...api.http.service import apikey as apikey_service
 from ...api.http.service import webhook as webhook_service
 from ...api.http.service import monitoring as monitoring_service
+from ...api.http.service import maintenance as maintenance_service
 from ...discover import engine as discover_engine
 from ...storage import mgr as storagemgr
 from ...utils import logcache
@@ -167,6 +168,9 @@ class BuildAppStage(stage.BootingStage):
        monitoring_service_inst = monitoring_service.MonitoringService(ap)
        ap.monitoring_service = monitoring_service_inst

+        maintenance_service_inst = maintenance_service.MaintenanceService(ap)
+        ap.maintenance_service = maintenance_service_inst
+
        async def runtime_disconnect_callback(connector: plugin_connector.PluginRuntimeConnector) -> None:
            await asyncio.sleep(3)
            await plugin_connector_inst.initialize()
--- a/src/langbot/pkg/core/taskmgr.py
+++ b/src/langbot/pkg/core/taskmgr.py
@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import typing
 import datetime
+import time

 from . import app
 from . import entities as core_entities
@@ -119,6 +120,7 @@ class TaskWrapper:
        self.label = label if label != '' else name
        self.task.set_name(name)
        self.scopes = scopes
+        self.created_at = time.time()

    def assume_exception(self):
        try:
@@ -154,6 +156,7 @@ class TaskWrapper:
            'name': self.name,
            'label': self.label,
            'scopes': [scope.value for scope in self.scopes],
+            'created_at': self.created_at,
            'task_context': self.task_context.to_dict(),
            'runtime': {
                'done': self.task.done(),
@@ -193,6 +196,8 @@ class AsyncTaskManager:
    ) -> TaskWrapper:
        wrapper = TaskWrapper(self.ap, coro, task_type, kind, name, label, context, scopes)
        self.tasks.append(wrapper)
+        wrapper.task.add_done_callback(lambda _: self._prune_completed_tasks())
+        self._prune_completed_tasks()
        return wrapper

    def create_user_task(
@@ -226,6 +231,15 @@ class AsyncTaskManager:
            'id_index': TaskWrapper._id_index,
        }

+    def get_stats(self) -> dict:
+        completed = sum(1 for t in self.tasks if t.task.done())
+        return {
+            'total': len(self.tasks),
+            'running': len(self.tasks) - completed,
+            'completed': completed,
+            'id_index': TaskWrapper._id_index,
+        }
+
    def get_task_by_id(self, id: int) -> TaskWrapper | None:
        for t in self.tasks:
            if t.id == id:
@@ -243,3 +257,27 @@ class AsyncTaskManager:
                if not wrapper.task.done():
                    wrapper.task.cancel()
                return
+
+    def _prune_completed_tasks(self):
+        completed_limit = (
+            self.ap.instance_config.data.get('system', {})
+            .get('task_retention', {})
+            .get(
+                'completed_limit',
+                200,
+            )
+        )
+        try:
+            completed_limit = int(completed_limit)
+        except (TypeError, ValueError):
+            completed_limit = 200
+        if completed_limit < 1:
+            completed_limit = 1
+
+        completed_tasks = [wrapper for wrapper in self.tasks if wrapper.task.done()]
+        overflow = len(completed_tasks) - completed_limit
+        if overflow <= 0:
+            return
+
+        remove_ids = {wrapper.id for wrapper in completed_tasks[:overflow]}
+        self.tasks = [wrapper for wrapper in self.tasks if wrapper.id not in remove_ids]
--- a/src/langbot/pkg/pipeline/aggregator.py
+++ b/src/langbot/pkg/pipeline/aggregator.py
@@ -275,6 +275,7 @@ class MessageAggregator:
            message_chain=merged_chain,
            adapter=base_msg.adapter,
            pipeline_uuid=base_msg.pipeline_uuid,
+            routed_by_rule=any(msg.routed_by_rule for msg in messages),
        )

    async def flush_all(self) -> None:
--- a/src/langbot/pkg/pipeline/longtext/longtext.py
+++ b/src/langbot/pkg/pipeline/longtext/longtext.py
@@ -76,6 +76,10 @@ class LongTextProcessStage(stage.PipelineStage):
            self.ap.logger.debug('Long message processing strategy is not set, skip long message processing.')
            return entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)

+        if not query.resp_message_chain:
+            self.ap.logger.debug('Response message chain is empty, skip long message processing.')
+            return entities.StageProcessResult(result_type=entities.ResultType.CONTINUE, new_query=query)
+
        # 检查是否包含非 Plain 组件
        contains_non_plain = False

--- a/src/langbot/pkg/pipeline/pool.py
+++ b/src/langbot/pkg/pipeline/pool.py
@@ -63,6 +63,7 @@ class QueryPool:
            self.cached_queries[query_id] = query
            self.query_id_counter += 1
            self.condition.notify_all()
+            return query

    async def __aenter__(self):
        await self.pool_lock.acquire()
--- a/src/langbot/pkg/pipeline/preproc/preproc.py
+++ b/src/langbot/pkg/pipeline/preproc/preproc.py
@@ -75,6 +75,27 @@ class PreProcessor(stage.PipelineStage):
            query.bot_uuid,
        )

+        # Expire externally managed conversation ids after the conversation has
+        # been idle for longer than the configured conversation expire time.
+        # The idle window is measured from the last preprocess/update time, not
+        # from the conversation creation time.
+        conversation_expire_time = query.pipeline_config.get('ai', {}).get('runner', {}).get('expire-time', None)
+        now = datetime.datetime.now()
+        if conversation_expire_time is not None and conversation_expire_time > 0:
+            last_update_time = getattr(conversation, 'update_time', None) or getattr(conversation, 'create_time', None)
+            if last_update_time is not None:
+                conversation_idle_time = now.timestamp() - last_update_time.timestamp()
+                if conversation_idle_time > conversation_expire_time:
+                    self.ap.logger.info(
+                        f'Conversation({query.query_id}) is expired (idle: {conversation_idle_time}s), create new conversation'
+                    )
+                    conversation.uuid = None
+
+        # Treat every preprocess pass as a conversation activity update. This
+        # makes future expiry checks use the latest incoming message/preprocess
+        # time instead of the first message/creation time.
+        conversation.update_time = now
+
        # 设置query
        query.session = session
        query.prompt = conversation.prompt.copy()
@@ -160,7 +181,10 @@ class PreProcessor(stage.PipelineStage):
                elif me.url:
                    content_list.append(provider_message.ContentElement.from_file_url(me.url, 'voice'))
            elif isinstance(me, platform_message.File):
-                content_list.append(provider_message.ContentElement.from_file_url(me.url, me.name))
+                if me.base64:
+                    content_list.append(provider_message.ContentElement.from_file_base64(me.base64, me.name))
+                elif me.url:
+                    content_list.append(provider_message.ContentElement.from_file_url(me.url, me.name))
            elif isinstance(me, platform_message.Quote) and quote_msg:
                for msg in me.origin:
                    if isinstance(msg, platform_message.Plain):
@@ -172,7 +196,10 @@ class PreProcessor(stage.PipelineStage):
                            if msg.base64 is not None:
                                content_list.append(provider_message.ContentElement.from_image_base64(msg.base64))
                    elif isinstance(msg, platform_message.File):
-                        content_list.append(provider_message.ContentElement.from_file_url(msg.url, msg.name))
+                        if msg.base64:
+                            content_list.append(provider_message.ContentElement.from_file_base64(msg.base64, msg.name))
+                        elif msg.url:
+                            content_list.append(provider_message.ContentElement.from_file_url(msg.url, msg.name))
                    elif isinstance(msg, platform_message.Voice):
                        if msg.base64:
                            content_list.append(
--- a/src/langbot/pkg/platform/botmgr.py
+++ b/src/langbot/pkg/platform/botmgr.py
@@ -523,7 +523,7 @@ class PlatformManager:
        return None

    async def remove_bot(self, bot_uuid: str):
-        for bot in self.bots:
+        for bot in self.bots[:]:
            if bot.bot_entity.uuid == bot_uuid:
                if bot.enable:
                    await bot.shutdown()
--- 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/src/langbot/pkg/platform/sources/dingtalk.yaml
+++ b/src/langbot/pkg/platform/sources/dingtalk.yaml
@@ -19,6 +19,18 @@ spec:
    en: https://link.langbot.app/en/platforms/dingtalk
    ja: https://link.langbot.app/ja/platforms/dingtalk
  config:
+    - name: one-click-create
+      label:
+        en_US: One-Click Create App
+        zh_Hans: 一键创建应用
+        zh_Hant: 一鍵建立應用
+      description:
+        en_US: "Scan QR code with DingTalk to automatically create an app and fill in credentials. Note: Robot Code cannot be obtained automatically, you need to copy it from the DingTalk Developer Backend manually."
+        zh_Hans: "使用钉钉扫码自动创建应用并填写凭据。注意：机器人代码无法自动获取，需前往钉钉开发者后台手动复制。"
+        zh_Hant: "使用釘釘掃碼自動建立應用並填寫憑證。注意：機器人代碼無法自動取得，需前往釘釘開發者後台手動複製。"
+      type: qr-code-login
+      login_platform: dingtalk
+      required: false
    - name: client_id
      label:
        en_US: Client ID
@@ -40,6 +52,10 @@ spec:
        en_US: Robot Code
        zh_Hans: 机器人代码
        zh_Hant: 機器人代碼
+      description:
+        en_US: "Required for image recognition, file upload and other features. Get it from DingTalk Developer Backend > Robot Configuration."
+        zh_Hans: "识图、上传文件等功能必填。请前往钉钉开发者后台 > 机器人配置中获取。"
+        zh_Hant: "識圖、上傳檔案等功能必填。請前往釘釘開發者後台 > 機器人設定中取得。"
      type: string
      required: true
      default: ""
--- a/src/langbot/pkg/platform/sources/lark.py
+++ b/src/langbot/pkg/platform/sources/lark.py
@@ -881,7 +881,8 @@ class LarkAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):

        bot_account_id = config['bot_name']

-        bot = lark_oapi.ws.Client(config['app_id'], config['app_secret'], event_handler=event_handler)
+        domain = self._resolve_domain(config)
+        bot = lark_oapi.ws.Client(config['app_id'], config['app_secret'], event_handler=event_handler, domain=domain)
        api_client = self.build_api_client(config)
        cipher = AESCipher(config.get('encrypt-key', ''))
        self.request_app_ticket(api_client, config)
@@ -1014,18 +1015,116 @@ class LarkAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):

        return None

+    @staticmethod
+    def _resolve_domain(config) -> str:
+        domain = config.get('domain', lark_oapi.FEISHU_DOMAIN)
+        if domain == 'custom':
+            domain = config.get('custom_domain', '')
+            if not domain:
+                raise ValueError('Custom domain is required when domain is set to "custom"')
+        return domain.rstrip('/')
+
    def build_api_client(self, config):
        app_id = config['app_id']
        app_secret = config['app_secret']
-        api_client = lark_oapi.Client.builder().app_id(app_id).app_secret(app_secret).build()
+        domain = self._resolve_domain(config)
+        api_client = lark_oapi.Client.builder().app_id(app_id).app_secret(app_secret).domain(domain).build()
        if 'isv' == config.get('app_type', 'self'):
            api_client = (
-                lark_oapi.Client.builder().app_id(app_id).app_secret(app_secret).app_type(lark_oapi.AppType.ISV).build()
+                lark_oapi.Client.builder()
+                .app_id(app_id)
+                .app_secret(app_secret)
+                .app_type(lark_oapi.AppType.ISV)
+                .domain(domain)
+                .build()
            )
        return api_client

    async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
-        pass
+        text_elements, media_items = await self.message_converter.yiri2target(message, self.api_client)
+
+        # Map standard target_type to Feishu receive_id_type
+        if target_type == 'person':
+            receive_id_type = 'open_id'
+        elif target_type == 'group':
+            receive_id_type = 'chat_id'
+        else:
+            receive_id_type = target_type
+
+        # Send text message if there are text elements
+        if text_elements:
+            needs_post = any(ele['tag'] == 'at' for paragraph in text_elements for ele in paragraph)
+
+            if needs_post:
+                msg_type = 'post'
+                final_content = json.dumps(
+                    {
+                        'zh_Hans': {
+                            'title': '',
+                            'content': text_elements,
+                        },
+                    }
+                )
+            else:
+                msg_type = 'text'
+                parts = []
+                for paragraph in text_elements:
+                    para_text = ''.join(ele.get('text', '') for ele in paragraph)
+                    if para_text:
+                        parts.append(para_text)
+                final_content = json.dumps({'text': '\n\n'.join(parts)})
+
+            request: CreateMessageRequest = (
+                CreateMessageRequest.builder()
+                .receive_id_type(receive_id_type)
+                .request_body(
+                    CreateMessageRequestBody.builder()
+                    .receive_id(target_id)
+                    .content(final_content)
+                    .msg_type(msg_type)
+                    .uuid(str(uuid.uuid4()))
+                    .build()
+                )
+                .build()
+            )
+
+            app_access_token = self.get_app_access_token()
+            req_opt: RequestOption = (
+                RequestOption.builder().app_ticket(self.app_ticket).app_access_token(app_access_token).build()
+            )
+            response: CreateMessageResponse = self.api_client.im.v1.message.create(request, req_opt)
+
+            if not response.success():
+                raise Exception(
+                    f'client.im.v1.message.create failed, code: {response.code}, msg: {response.msg}, log_id: {response.get_log_id()}, resp: \n{json.dumps(json.loads(response.raw.content), indent=4, ensure_ascii=False)}'
+                )
+
+        # Send media messages separately (image, audio, file, etc.)
+        for media in media_items:
+            request: CreateMessageRequest = (
+                CreateMessageRequest.builder()
+                .receive_id_type(receive_id_type)
+                .request_body(
+                    CreateMessageRequestBody.builder()
+                    .receive_id(target_id)
+                    .content(json.dumps(media['content']))
+                    .msg_type(media['msg_type'])
+                    .uuid(str(uuid.uuid4()))
+                    .build()
+                )
+                .build()
+            )
+
+            app_access_token = self.get_app_access_token()
+            req_opt: RequestOption = (
+                RequestOption.builder().app_ticket(self.app_ticket).app_access_token(app_access_token).build()
+            )
+            response: CreateMessageResponse = self.api_client.im.v1.message.create(request, req_opt)
+
+            if not response.success():
+                raise Exception(
+                    f'client.im.v1.message.create ({media["msg_type"]}) failed, code: {response.code}, msg: {response.msg}, log_id: {response.get_log_id()}, resp: \n{json.dumps(json.loads(response.raw.content), indent=4, ensure_ascii=False)}'
+                )

    async def is_stream_output_supported(self) -> bool:
        is_stream = False
--- a/src/langbot/pkg/platform/sources/lark.yaml
+++ b/src/langbot/pkg/platform/sources/lark.yaml
@@ -23,6 +23,71 @@ spec:
    en: https://link.langbot.app/en/platforms/lark
    ja: https://link.langbot.app/ja/platforms/lark
  config:
+    - name: domain
+      label:
+        en_US: Platform Domain
+        zh_Hans: 平台域名
+        zh_Hant: 平台域名
+        ja_JP: プラットフォームドメイン
+      description:
+        en_US: Select the open platform domain. Use Feishu for Chinese mainland, Lark for international
+        zh_Hans: 选择开放平台域名，国内使用飞书，海外使用 Lark
+        zh_Hant: 選擇開放平台域名，國內使用飛書，海外使用 Lark
+        ja_JP: オープンプラットフォームのドメインを選択。中国国内は飛書、海外は Lark を使用
+      type: select
+      options:
+        - name: https://open.feishu.cn
+          label:
+            en_US: Feishu (open.feishu.cn)
+            zh_Hans: 飞书 (open.feishu.cn)
+            zh_Hant: 飛書 (open.feishu.cn)
+            ja_JP: 飛書 (open.feishu.cn)
+        - name: https://open.larksuite.com
+          label:
+            en_US: Lark (open.larksuite.com)
+            zh_Hans: Lark (open.larksuite.com)
+            zh_Hant: Lark (open.larksuite.com)
+            ja_JP: Lark (open.larksuite.com)
+        - name: custom
+          label:
+            en_US: Custom
+            zh_Hans: 自定义
+            zh_Hant: 自定義
+            ja_JP: カスタム
+      required: false
+      default: https://open.feishu.cn
+    - name: custom_domain
+      label:
+        en_US: Custom Domain
+        zh_Hans: 自定义域名
+        zh_Hant: 自定義域名
+        ja_JP: カスタムドメイン
+      description:
+        en_US: "Enter the full domain URL, e.g. https://open.example.com"
+        zh_Hans: "输入完整的域名 URL，例如 https://open.example.com"
+        zh_Hant: "輸入完整的域名 URL，例如 https://open.example.com"
+        ja_JP: "完全なドメイン URL を入力（例: https://open.example.com）"
+      type: string
+      required: false
+      default: ""
+      show_if:
+        field: domain
+        operator: eq
+        value: custom
+    - name: one-click-create
+      label:
+        en_US: One-Click Create App
+        zh_Hans: 一键创建应用
+        zh_Hant: 一鍵建立應用
+        ja_JP: ワンクリックでアプリ作成
+      description:
+        en_US: Scan QR code to automatically create a Feishu app and fill in credentials
+        zh_Hans: 扫码自动创建飞书应用并填写凭据
+        zh_Hant: 掃碼自動建立飛書應用並填寫憑證
+        ja_JP: QRコードをスキャンしてFeishuアプリを自動作成し、認証情報を入力
+      type: qr-code-login
+      login_platform: feishu
+      required: false
    - name: app_id
      label:
        en_US: App ID
@@ -126,10 +191,10 @@ spec:
        zh_Hant: 應用類型
        ja_JP: アプリタイプ
      description:
-        en_US: Default to self-built application, refer to https://open.feishu.cn/document/platform-overveiw/overview
-        zh_Hans: 默认为企业自建应用，参考 https://open.feishu.cn/document/platform-overveiw/overview
-        zh_Hant: 預設為企業自建應用，參考 https://open.feishu.cn/document/platform-overveiw/overview
-        ja_JP: デフォルトはカスタムアプリです。詳細は https://open.feishu.cn/document/platform-overveiw/overview を参照してください
+        en_US: "Default to self-built application, refer to https://open.feishu.cn/document/platform-overveiw/overview"
+        zh_Hans: "默认为企业自建应用，参考 https://open.feishu.cn/document/platform-overveiw/overview"
+        zh_Hant: "預設為企業自建應用，參考 https://open.feishu.cn/document/platform-overveiw/overview"
+        ja_JP: "デフォルトはカスタムアプリです。詳細は https://open.feishu.cn/document/platform-overveiw/overview を参照してください"
      type: select
      options:
        - name: self
--- a/src/langbot/pkg/platform/sources/matrix.png
+++ b/src/langbot/pkg/platform/sources/matrix.png
--- a/src/langbot/pkg/platform/sources/matrix.py
+++ b/src/langbot/pkg/platform/sources/matrix.py
@@ -0,0 +1,693 @@
+from __future__ import annotations
+
+import typing
+import asyncio
+import traceback
+import base64
+import json
+
+import nio
+
+from langbot.pkg.utils import httpclient
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+
+
+class MatrixMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
+    @staticmethod
+    async def yiri2target(message_chain: platform_message.MessageChain, client: nio.AsyncClient) -> list[dict]:
+        components = []
+        for component in message_chain:
+            if isinstance(component, platform_message.Plain):
+                components.append({'type': 'text', 'text': component.text})
+            elif isinstance(component, platform_message.Image):
+                image_bytes = None
+                if component.base64:
+                    b64_data = component.base64
+                    if ';base64,' in b64_data:
+                        b64_data = b64_data.split(';base64,', 1)[1]
+                    image_bytes = base64.b64decode(b64_data)
+                elif component.url:
+                    session = httpclient.get_session()
+                    async with session.get(component.url) as response:
+                        image_bytes = await response.read()
+                elif component.path:
+                    with open(component.path, 'rb') as f:
+                        image_bytes = f.read()
+                if image_bytes:
+                    resp = await client.upload(image_bytes, content_type='image/png')
+                    if isinstance(resp, nio.UploadResponse):
+                        components.append({'type': 'image', 'mxc_url': resp.content_uri})
+            elif isinstance(component, platform_message.File):
+                file_bytes = None
+                if component.base64:
+                    b64_data = component.base64
+                    if ';base64,' in b64_data:
+                        b64_data = b64_data.split(';base64,', 1)[1]
+                    file_bytes = base64.b64decode(b64_data)
+                elif component.url:
+                    session = httpclient.get_session()
+                    async with session.get(component.url) as response:
+                        file_bytes = await response.read()
+                elif component.path:
+                    with open(component.path, 'rb') as f:
+                        file_bytes = f.read()
+                if file_bytes:
+                    file_name = getattr(component, 'name', None) or 'file'
+                    resp = await client.upload(file_bytes, content_type='application/octet-stream', filename=file_name)
+                    if isinstance(resp, nio.UploadResponse):
+                        components.append(
+                            {
+                                'type': 'file',
+                                'mxc_url': resp.content_uri,
+                                'filename': file_name,
+                                'size': len(file_bytes),
+                            }
+                        )
+            elif isinstance(component, platform_message.Forward):
+                for node in component.node_list:
+                    components.extend(await MatrixMessageConverter.yiri2target(node.message_chain, client))
+        return components
+
+    @staticmethod
+    async def target2yiri(event: nio.RoomMessageText | nio.RoomMessageImage, client: nio.AsyncClient, bot_user_id: str):
+        message_components = []
+
+        if isinstance(event, nio.RoomMessageText):
+            text = event.body
+            if bot_user_id and bot_user_id in text:
+                message_components.append(platform_message.At(target=bot_user_id))
+                text = text.replace(bot_user_id, '').strip()
+            message_components.append(platform_message.Plain(text=text))
+
+        elif isinstance(event, nio.RoomMessageImage):
+            mxc_url = event.url
+            if mxc_url:
+                resp = await client.download(mxc_url)
+                if isinstance(resp, nio.DownloadResponse):
+                    b64 = base64.b64encode(resp.body).decode('utf-8')
+                    content_type = resp.content_type or 'image/png'
+                    message_components.append(platform_message.Image(base64=f'data:{content_type};base64,{b64}'))
+            if event.body:
+                message_components.append(platform_message.Plain(text=event.body))
+
+        return platform_message.MessageChain(message_components)
+
+
+class MatrixEventConverter(abstract_platform_adapter.AbstractEventConverter):
+    @staticmethod
+    async def yiri2target(event: platform_events.MessageEvent):
+        return event.source_platform_object
+
+    @staticmethod
+    async def target2yiri(
+        event: nio.RoomMessageText | nio.RoomMessageImage,
+        room: nio.MatrixRoom,
+        client: nio.AsyncClient,
+        bot_user_id: str,
+        bridge_user_ids: list[str] | None = None,
+    ):
+        lb_message = await MatrixMessageConverter.target2yiri(event, client, bot_user_id)
+
+        # Determine if this is a direct/private chat or a group chat.
+        # Exclude bot itself and bridge bots, count remaining real users.
+        exclude_ids = {bot_user_id}
+        if bridge_user_ids:
+            exclude_ids.update(bridge_user_ids)
+        real_users = [uid for uid in room.users if uid not in exclude_ids]
+        is_direct = len(real_users) <= 1
+
+        if is_direct:
+            return platform_events.FriendMessage(
+                sender=platform_entities.Friend(
+                    id=event.sender,
+                    nickname=room.user_name(event.sender) or event.sender,
+                    remark='',
+                ),
+                message_chain=lb_message,
+                time=event.server_timestamp / 1000.0,
+                source_platform_object={'event': event, 'room': room},
+            )
+        else:
+            return platform_events.GroupMessage(
+                sender=platform_entities.GroupMember(
+                    id=event.sender,
+                    member_name=room.user_name(event.sender) or event.sender,
+                    permission=platform_entities.Permission.Member,
+                    group=platform_entities.Group(
+                        id=room.room_id,
+                        name=room.display_name or room.room_id,
+                        permission=platform_entities.Permission.Member,
+                    ),
+                    special_title='',
+                ),
+                message_chain=lb_message,
+                time=event.server_timestamp / 1000.0,
+                source_platform_object={'event': event, 'room': room},
+            )
+
+
+class BridgeState:
+    """Per-bridge runtime state."""
+
+    def __init__(self, user_id: str, login_command: str, logout_command: str, success_keyword: str, check_command: str):
+        self.user_id = user_id
+        self.login_command = login_command
+        self.logout_command = logout_command
+        self.success_keyword = success_keyword
+        self.check_command = check_command or login_command
+        self.logged_in = False
+        self.dm_room_id: str | None = None
+        self.login_task: asyncio.Task | None = None
+        self.check_task: asyncio.Task | None = None
+        self.check_responded = False
+
+
+class MatrixAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
+    client: typing.Any = None
+    message_converter: MatrixMessageConverter = MatrixMessageConverter()
+    event_converter: MatrixEventConverter = MatrixEventConverter()
+    config: dict
+    listeners: typing.Dict[typing.Type[platform_events.Event], typing.Callable] = {}
+    _running: bool = False
+    _initial_sync_done: bool = False
+    _bridges: list = []
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
+        homeserver_url = config.get('homeserver_url', '')
+        access_token = config.get('access_token', '')
+        user_id = config.get('user_id', '')
+
+        if not homeserver_url or not access_token or not user_id:
+            raise ValueError('Matrix 机器人缺少必要配置项 (homeserver_url, user_id, access_token)')
+
+        client = nio.AsyncClient(homeserver_url, user_id)
+        client.access_token = access_token
+        client.user_id = user_id
+
+        super().__init__(
+            config=config,
+            logger=logger,
+            bot_account_id=user_id,
+            client=client,
+            listeners={},
+        )
+
+        # Parse bridges config AFTER super().__init__() to avoid Pydantic resetting _bridges
+        self._bridges = []
+        bridges_raw = config.get('bridges', '')
+        if bridges_raw:
+            if isinstance(bridges_raw, str):
+                try:
+                    bridges_list = json.loads(bridges_raw)
+                except (json.JSONDecodeError, TypeError) as e:
+                    raise ValueError(f'bridges 配置 JSON 解析失败: {e}\n原始值: {bridges_raw}')
+            else:
+                bridges_list = bridges_raw
+            for b in bridges_list:
+                if isinstance(b, dict) and b.get('user_id', '').strip():
+                    self._bridges.append(
+                        BridgeState(
+                            user_id=b['user_id'].strip(),
+                            login_command=b.get('login_command', '').strip(),
+                            logout_command=b.get('logout_command', '').strip(),
+                            success_keyword=b.get('success_keyword', 'Successfully logged in').strip(),
+                            check_command=b.get('check_command', '').strip(),
+                        )
+                    )
+        # Backward compatibility: old single-bridge config
+        if not self._bridges:
+            old_user_id = config.get('bridge_user_id', '').strip()
+            old_command = config.get('bridge_login_command', '').strip()
+            old_keyword = config.get('bridge_login_success_keyword', 'Successfully logged in').strip()
+            old_check = config.get('bridge_check_command', '').strip()
+            old_logout = config.get('bridge_logout_command', '').strip()
+            if old_user_id:
+                self._bridges.append(
+                    BridgeState(
+                        user_id=old_user_id,
+                        login_command=old_command,
+                        logout_command=old_logout,
+                        success_keyword=old_keyword,
+                        check_command=old_check,
+                    )
+                )
+
+    async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
+        components = await self.message_converter.yiri2target(message, self.client)
+        for component in components:
+            await self._send_component(target_id, component)
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ):
+        source_obj = message_source.source_platform_object
+        room_id = source_obj['room'].room_id
+        components = await self.message_converter.yiri2target(message, self.client)
+
+        for component in components:
+            if quote_origin:
+                original_event = source_obj['event']
+                await self._send_component(room_id, component, reply_to=original_event.event_id)
+            else:
+                await self._send_component(room_id, component)
+
+    async def _send_component(self, room_id: str, component: dict, reply_to: str | None = None):
+        content = {}
+        if component['type'] == 'text':
+            content = {
+                'msgtype': 'm.text',
+                'body': component['text'],
+            }
+        elif component['type'] == 'image':
+            content = {
+                'msgtype': 'm.image',
+                'body': 'image.png',
+                'url': component['mxc_url'],
+            }
+        elif component['type'] == 'file':
+            content = {
+                'msgtype': 'm.file',
+                'body': component.get('filename', 'file'),
+                'url': component['mxc_url'],
+                'info': {'size': component.get('size', 0)},
+            }
+
+        if reply_to and content:
+            content['m.relates_to'] = {
+                'm.in_reply_to': {'event_id': reply_to},
+            }
+
+        if content:
+            await self.client.room_send(
+                room_id=room_id,
+                message_type='m.room.message',
+                content=content,
+            )
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        self.listeners[event_type] = callback
+
+    async def run_async(self):
+        self._running = True
+        await self.logger.info('Matrix adapter starting...')
+
+        # Debug: log bridge parsing result
+        bridges_raw = self.config.get('bridges', '')
+        await self.logger.debug(f'bridges config raw: type={type(bridges_raw).__name__}, repr={repr(bridges_raw)}')
+        await self.logger.debug(
+            f'parsed _bridges count: {len(self._bridges)}, ids: {[b.user_id for b in self._bridges]}'
+        )
+
+        # Collect all bridge bot user IDs for filtering
+        _bridge_user_ids = [b.user_id for b in self._bridges]
+        _bridge_user_id_set = set(_bridge_user_ids)
+
+        # Auto-join invited rooms
+        async def on_invite(room: nio.MatrixRoom, event: nio.InviteMemberEvent):
+            if event.membership == 'invite' and event.state_key == self.client.user_id:
+                await self.client.join(room.room_id)
+                await self.logger.debug(f'Auto-joined room: {room.display_name or room.room_id}')
+
+        self.client.add_event_callback(on_invite, nio.InviteMemberEvent)
+
+        # Handle text messages
+        async def on_message(room: nio.MatrixRoom, event: nio.RoomMessageText):
+            if not self._initial_sync_done:
+                return
+            if event.sender == self.client.user_id:
+                return
+
+            # Admin commands (from any non-bridge user)
+            if event.sender not in _bridge_user_id_set:
+                body = (event.body or '').strip()
+                if body == '!relogin':
+                    await self._handle_relogin_command(room.room_id)
+                    return
+                if body == '!status':
+                    await self._handle_status_command(room.room_id)
+                    return
+
+            if event.sender in _bridge_user_id_set:
+                return
+            try:
+                lb_event = await self.event_converter.target2yiri(
+                    event, room, self.client, self.bot_account_id, _bridge_user_ids
+                )
+                if type(lb_event) in self.listeners:
+                    result = self.listeners[type(lb_event)](lb_event, self)
+                    if asyncio.iscoroutine(result):
+                        await result
+            except Exception:
+                await self.logger.error(f'Error handling Matrix message: {traceback.format_exc()}')
+
+        self.client.add_event_callback(on_message, nio.RoomMessageText)
+
+        # Handle image messages
+        async def on_image(room: nio.MatrixRoom, event: nio.RoomMessageImage):
+            if not self._initial_sync_done:
+                return
+            if event.sender == self.client.user_id:
+                return
+            if event.sender in _bridge_user_id_set:
+                return
+            try:
+                lb_event = await self.event_converter.target2yiri(
+                    event, room, self.client, self.bot_account_id, _bridge_user_ids
+                )
+                if type(lb_event) in self.listeners:
+                    result = self.listeners[type(lb_event)](lb_event, self)
+                    if asyncio.iscoroutine(result):
+                        await result
+            except Exception:
+                await self.logger.error(f'Error handling Matrix image: {traceback.format_exc()}')
+
+        self.client.add_event_callback(on_image, nio.RoomMessageImage)
+
+        # Set up bridge-specific callbacks for each bridge
+        _disconnect_keywords = ['disconnected', 'logged out', 'connection lost', 'session expired', 'token expired']
+
+        for bridge in self._bridges:
+            # Login success detection (notice)
+            async def on_bridge_notice(room: nio.MatrixRoom, event: nio.RoomMessageNotice, _b=bridge):
+                if not self._initial_sync_done:
+                    return
+                if event.sender != _b.user_id:
+                    return
+                _b.check_responded = True
+                if _b.success_keyword in (event.body or ''):
+                    _b.logged_in = True
+                    await self.logger.info(f'[{_b.user_id}] Bridge login succeeded.')
+                # Disconnect detection
+                body_lower = (event.body or '').lower()
+                for kw in _disconnect_keywords:
+                    if kw in body_lower and _b.logged_in:
+                        _b.logged_in = False
+                        await self.logger.info(f'[{_b.user_id}] Bridge 账号掉线 (检测到: "{kw}"), 将自动重新登录...')
+                        self._restart_bridge_login(_b)
+                        break
+
+            self.client.add_event_callback(on_bridge_notice, nio.RoomMessageNotice)
+
+            # Login success + disconnect detection (text)
+            async def on_bridge_text(room: nio.MatrixRoom, event: nio.RoomMessageText, _b=bridge):
+                if not self._initial_sync_done:
+                    return
+                if event.sender != _b.user_id:
+                    return
+                _b.check_responded = True
+                if _b.success_keyword in (event.body or ''):
+                    _b.logged_in = True
+                    await self.logger.info(f'[{_b.user_id}] Bridge login succeeded.')
+                body_lower = (event.body or '').lower()
+                for kw in _disconnect_keywords:
+                    if kw in body_lower and _b.logged_in:
+                        _b.logged_in = False
+                        await self.logger.info(f'[{_b.user_id}] Bridge 账号掉线 (检测到: "{kw}"), 将自动重新登录...')
+                        self._restart_bridge_login(_b)
+                        break
+
+            self.client.add_event_callback(on_bridge_text, nio.RoomMessageText)
+
+            # QR code image forwarding
+            async def on_bridge_image(room: nio.MatrixRoom, event: nio.RoomMessageImage, _b=bridge):
+                if not self._initial_sync_done:
+                    return
+                if event.sender != _b.user_id:
+                    return
+                mxc_url = event.url
+                if not mxc_url:
+                    return
+                try:
+                    resp = await self.client.download(mxc_url)
+                    if isinstance(resp, nio.DownloadResponse):
+                        b64 = base64.b64encode(resp.body).decode('utf-8')
+                        content_type = resp.content_type or 'image/png'
+                        await self.logger.info(
+                            f'[{_b.user_id}] Bridge 发送了二维码，请扫码登录:',
+                            images=[platform_message.Image(base64=f'data:{content_type};base64,{b64}')],
+                        )
+                except Exception:
+                    await self.logger.error(
+                        f'[{_b.user_id}] Failed to download bridge QR image: {traceback.format_exc()}'
+                    )
+
+            self.client.add_event_callback(on_bridge_image, nio.RoomMessageImage)
+
+        await self.logger.debug('Matrix adapter running, starting sync...')
+
+        # Initial sync to skip old messages
+        resp = await self.client.sync(timeout=10000)
+        if isinstance(resp, nio.SyncResponse):
+            await self.logger.debug(f'Matrix initial sync done, next_batch: {resp.next_batch}')
+        self._initial_sync_done = True
+
+        # Display account info
+        display_name = self.client.user_id
+        try:
+            profile_resp = await self.client.get_displayname(self.client.user_id)
+            if isinstance(profile_resp, nio.ProfileGetDisplayNameResponse) and profile_resp.displayname:
+                display_name = profile_resp.displayname
+        except Exception:
+            pass
+        joined_rooms = len(self.client.rooms)
+        homeserver = self.config.get('homeserver_url', '')
+        bridge_info = ''
+        if self._bridges:
+            bridge_names = ', '.join(b.user_id for b in self._bridges)
+            bridge_info = f' | 桥接: [{bridge_names}]'
+        await self.logger.info(
+            f'Matrix 账号: {display_name} ({self.client.user_id}) | '
+            f'服务器: {homeserver} | 已加入 {joined_rooms} 个房间{bridge_info}'
+        )
+
+        # Start bridge login and status check tasks for each bridge
+        for bridge in self._bridges:
+            if bridge.login_command:
+                await self.logger.info(
+                    f'[{bridge.user_id}] Bridge login enabled (命令: "{bridge.login_command}", '
+                    f'关键词: "{bridge.success_keyword}")'
+                )
+                bridge.login_task = asyncio.create_task(self._periodic_bridge_login(bridge))
+                bridge.check_task = asyncio.create_task(self._periodic_bridge_check(bridge))
+            else:
+                await self.logger.debug(f'[{bridge.user_id}] Bridge login not configured (no login_command)')
+
+        # Main sync loop
+        while self._running:
+            try:
+                await self.client.sync(timeout=30000)
+            except Exception:
+                await self.logger.error(f'Matrix sync error: {traceback.format_exc()}')
+                await asyncio.sleep(5)
+
+    async def _periodic_bridge_login(self, bridge: BridgeState):
+        """Periodically send login command to a bridge bot until login succeeds."""
+        try:
+            await self.logger.info(f'[{bridge.user_id}] Bridge login task started, looking for DM room...')
+            dm_room_id = None
+            for room_id, room in self.client.rooms.items():
+                if room.member_count == 2 and bridge.user_id in [m for m in room.users]:
+                    dm_room_id = room_id
+                    break
+
+            if not dm_room_id:
+                resp = await self.client.room_create(
+                    is_direct=True,
+                    invite=[bridge.user_id],
+                )
+                if isinstance(resp, nio.RoomCreateResponse):
+                    dm_room_id = resp.room_id
+                    await self.logger.debug(f'[{bridge.user_id}] Created DM room: {dm_room_id}')
+                else:
+                    await self.logger.error(f'[{bridge.user_id}] Failed to create DM room: {resp}')
+                    return
+
+            bridge.dm_room_id = dm_room_id
+
+            # Force logout first on every adapter start
+            logout_cmd = bridge.logout_command or bridge.login_command.replace('login', 'logout')
+            await self.logger.info(f'[{bridge.user_id}] 强制登出: "{logout_cmd}"')
+            await self.client.room_send(
+                room_id=dm_room_id,
+                message_type='m.room.message',
+                content={'msgtype': 'm.text', 'body': logout_cmd},
+            )
+            await asyncio.sleep(3)
+
+            while self._running and not bridge.logged_in:
+                await self.logger.debug(f'[{bridge.user_id}] Sending "{bridge.login_command}" in room {dm_room_id}')
+                await self.client.room_send(
+                    room_id=dm_room_id,
+                    message_type='m.room.message',
+                    content={'msgtype': 'm.text', 'body': bridge.login_command},
+                )
+                for _ in range(60):
+                    if not self._running or bridge.logged_in:
+                        break
+                    await asyncio.sleep(1)
+
+            if bridge.logged_in:
+                await self.logger.debug(f'[{bridge.user_id}] Bridge login confirmed, periodic login stopped.')
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            await self.logger.error(f'[{bridge.user_id}] Bridge periodic login error: {traceback.format_exc()}')
+
+    def _restart_bridge_login(self, bridge: BridgeState):
+        """Cancel existing login task and start a new one."""
+        if bridge.login_task and not bridge.login_task.done():
+            bridge.login_task.cancel()
+        bridge.login_task = asyncio.create_task(self._periodic_bridge_login(bridge))
+
+    async def _periodic_bridge_check(self, bridge: BridgeState):
+        """Periodically check a bridge's login status."""
+        try:
+            while self._running and not bridge.logged_in:
+                await asyncio.sleep(5)
+
+            check_interval = 300  # 5 minutes
+            response_timeout = 30
+            await self.logger.debug(f'[{bridge.user_id}] Bridge status check started (interval: {check_interval}s)')
+
+            while self._running:
+                for _ in range(check_interval):
+                    if not self._running:
+                        return
+                    await asyncio.sleep(1)
+
+                if not bridge.logged_in or not bridge.dm_room_id:
+                    continue
+
+                try:
+                    bridge.check_responded = False
+                    await self.client.room_send(
+                        room_id=bridge.dm_room_id,
+                        message_type='m.room.message',
+                        content={'msgtype': 'm.text', 'body': bridge.check_command},
+                    )
+                    await self.logger.debug(f'[{bridge.user_id}] Bridge status check: sent "{bridge.check_command}"')
+
+                    for _ in range(response_timeout):
+                        if bridge.check_responded or not self._running:
+                            break
+                        await asyncio.sleep(1)
+
+                    if bridge.check_responded:
+                        await self.logger.debug(f'[{bridge.user_id}] Bridge status check: OK')
+                    else:
+                        await self.logger.info(
+                            f'[{bridge.user_id}] Bridge status check: 无响应, 可能已掉线, 尝试重新登录...'
+                        )
+                        bridge.logged_in = False
+                        self._restart_bridge_login(bridge)
+                except Exception:
+                    await self.logger.error(f'[{bridge.user_id}] Bridge status check error: {traceback.format_exc()}')
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            await self.logger.error(f'[{bridge.user_id}] Bridge status check fatal error: {traceback.format_exc()}')
+
+    async def _handle_relogin_command(self, room_id: str):
+        """Handle !relogin command: logout then re-login all bridges."""
+        if not self._bridges:
+            await self.client.room_send(
+                room_id=room_id,
+                message_type='m.room.message',
+                content={'msgtype': 'm.text', 'body': '没有配置任何桥。'},
+            )
+            return
+
+        lines = ['开始重新登录所有桥...']
+        for bridge in self._bridges:
+            if not bridge.login_command or not bridge.dm_room_id:
+                lines.append(f'[{bridge.user_id}] 跳过（未配置登录命令或无DM房间）')
+                continue
+
+                # Use configured logout command, fallback to deriving from login command
+                logout_cmd = bridge.logout_command or bridge.login_command.replace('login', 'logout')
+            lines.append(f'[{bridge.user_id}] 发送 "{logout_cmd}"...')
+
+            # Cancel existing tasks
+            if bridge.login_task and not bridge.login_task.done():
+                bridge.login_task.cancel()
+            if bridge.check_task and not bridge.check_task.done():
+                bridge.check_task.cancel()
+
+            # Send logout
+            try:
+                await self.client.room_send(
+                    room_id=bridge.dm_room_id,
+                    message_type='m.room.message',
+                    content={'msgtype': 'm.text', 'body': logout_cmd},
+                )
+            except Exception as e:
+                lines.append(f'[{bridge.user_id}] logout 发送失败: {e}')
+
+            await asyncio.sleep(2)
+
+            # Reset state and restart login
+            bridge.logged_in = False
+            self._restart_bridge_login(bridge)
+            lines.append(f'[{bridge.user_id}] 已触发重新登录')
+
+        await self.client.room_send(
+            room_id=room_id,
+            message_type='m.room.message',
+            content={'msgtype': 'm.text', 'body': '\n'.join(lines)},
+        )
+
+    async def _handle_status_command(self, room_id: str):
+        """Handle !status command: show bridge states."""
+        if not self._bridges:
+            await self.client.room_send(
+                room_id=room_id,
+                message_type='m.room.message',
+                content={'msgtype': 'm.text', 'body': '没有配置任何桥。'},
+            )
+            return
+
+        lines = ['桥状态:']
+        for bridge in self._bridges:
+            status = '已登录 ✓' if bridge.logged_in else '未登录 ✗'
+            dm = bridge.dm_room_id or '无'
+            lines.append(f'• {bridge.user_id}: {status} (DM: {dm})')
+        await self.client.room_send(
+            room_id=room_id,
+            message_type='m.room.message',
+            content={'msgtype': 'm.text', 'body': '\n'.join(lines)},
+        )
+
+    async def kill(self) -> bool:
+        self._running = False
+        for bridge in self._bridges:
+            if bridge.login_task and not bridge.login_task.done():
+                bridge.login_task.cancel()
+            if bridge.check_task and not bridge.check_task.done():
+                bridge.check_task.cancel()
+        if self.client:
+            await self.client.close()
+        await self.logger.debug('Matrix adapter stopped')
+        return True
+
+    async def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable[
+            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None
+        ],
+    ):
+        if event_type in self.listeners:
+            del self.listeners[event_type]
--- a/src/langbot/pkg/platform/sources/matrix.yaml
+++ b/src/langbot/pkg/platform/sources/matrix.yaml
@@ -0,0 +1,123 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+metadata:
+  name: matrix
+  label:
+    en_US: Matrix
+    zh_Hans: Matrix
+    zh_Hant: Matrix
+    ja_JP: Matrix
+    th_TH: Matrix
+    vi_VN: Matrix
+    es_ES: Matrix
+  description:
+    en_US: Matrix protocol adapter, supports self-hosted Synapse servers and any Matrix-compatible homeserver
+    zh_Hans: Matrix 协议适配器，支持自建 Synapse 服务器及任何 Matrix 兼容的 Homeserver
+    zh_Hant: Matrix 協議適配器，支持自建 Synapse 伺服器及任何 Matrix 相容的 Homeserver
+    ja_JP: Matrix プロトコルアダプター、セルフホストの Synapse サーバーおよび Matrix 互換のホームサーバーをサポート
+    th_TH: อะแดปเตอร์โปรโตคอล Matrix รองรับเซิร์ฟเวอร์ Synapse ที่โฮสต์เองและ Homeserver ที่เข้ากันได้กับ Matrix
+    vi_VN: Bộ điều hợp giao thức Matrix, hỗ trợ máy chủ Synapse tự lưu trữ và bất kỳ Homeserver tương thích Matrix nào
+    es_ES: Adaptador del protocolo Matrix, compatible con servidores Synapse autoalojados y cualquier Homeserver compatible con Matrix
+  icon: matrix.png
+spec:
+  categories:
+    - global
+    - protocol
+  config:
+    - name: homeserver_url
+      label:
+        en_US: Homeserver URL
+        zh_Hans: Homeserver 地址
+        zh_Hant: Homeserver 地址
+        ja_JP: Homeserver URL
+        th_TH: URL ของ Homeserver
+        vi_VN: URL Homeserver
+        es_ES: URL del Homeserver
+      description:
+        en_US: "The URL of the Matrix homeserver, e.g. http://localhost:8008"
+        zh_Hans: "Matrix Homeserver 的地址，例如 http://localhost:8008"
+      type: string
+      required: true
+      default: "http://localhost:8008"
+    - name: user_id
+      label:
+        en_US: Bot User ID
+        zh_Hans: 机器人用户 ID
+        zh_Hant: 機器人用戶 ID
+        ja_JP: ボットユーザー ID
+        th_TH: ID ผู้ใช้บอท
+        vi_VN: ID người dùng bot
+        es_ES: ID de usuario del bot
+      description:
+        en_US: "The full Matrix user ID, e.g. @bot:localhost"
+        zh_Hans: "完整的 Matrix 用户 ID，例如 @bot:localhost"
+      type: string
+      required: true
+      default: "@langbot:localhost"
+    - name: access_token
+      label:
+        en_US: Access Token
+        zh_Hans: 访问令牌
+        zh_Hant: 訪問令牌
+        ja_JP: アクセストークン
+        th_TH: โทเค็นการเข้าถึง
+        vi_VN: Mã truy cập
+        es_ES: Token de acceso
+      description:
+        en_US: "Access token obtained by logging in via the Matrix client API"
+        zh_Hans: "通过 Matrix Client API 登录获取的访问令牌"
+      type: string
+      required: true
+      default: ""
+    - name: bridge_user_id
+      label:
+        en_US: Bridge Bot User ID (single bridge, legacy)
+        zh_Hans: 桥机器人用户 ID（单桥兼容）
+      description:
+        en_US: "Single bridge bot user ID (legacy). Prefer 'bridges' for multi-bridge. e.g. @discordbot:localhost"
+        zh_Hans: "单桥机器人用户 ID（旧格式兼容）。推荐使用 bridges 配置多桥。例如 @discordbot:localhost"
+      type: string
+      required: false
+      default: ""
+    - name: bridge_login_command
+      label:
+        en_US: Bridge Login Command (single bridge, legacy)
+        zh_Hans: 桥登录命令（单桥兼容）
+      description:
+        en_US: "Login command for single bridge (legacy). e.g. !discord login"
+        zh_Hans: "单桥登录命令（旧格式兼容）。例如 !discord login"
+      type: string
+      required: false
+      default: ""
+    - name: bridge_login_success_keyword
+      label:
+        en_US: Bridge Login Success Keyword (single bridge, legacy)
+        zh_Hans: 桥登录成功关键词（单桥兼容）
+      description:
+        en_US: "Success keyword for single bridge (legacy). e.g. Successfully logged in"
+        zh_Hans: "单桥登录成功关键词（旧格式兼容）。例如 Successfully logged in"
+      type: string
+      required: false
+      default: "Successfully logged in"
+    - name: bridges
+      label:
+        en_US: Bridges Config (Multi-bridge)
+        zh_Hans: 桥配置（多桥）
+      description:
+        en_US: >
+          JSON array of bridge configs. Each bridge: {"user_id": "@bot:host", "login_command": "!xx login",
+          "success_keyword": "logged in", "check_command": "!xx ping"}.
+          Example: [{"user_id":"@discordbot:localhost","login_command":"!discord login","success_keyword":"logged in"},
+          {"user_id":"@telegrambot:localhost","login_command":"!tg login","success_keyword":"logged in"}]
+        zh_Hans: >
+          JSON 数组格式的多桥配置。每个桥: {"user_id": "@bot:host", "login_command": "!xx login",
+          "success_keyword": "logged in", "check_command": "!xx ping"}。
+          示例: [{"user_id":"@discordbot:localhost","login_command":"!discord login","success_keyword":"logged in"},
+          {"user_id":"@telegrambot:localhost","login_command":"!tg login","success_keyword":"logged in"}]
+      type: string
+      required: false
+      default: ""
+execution:
+  python:
+    path: ./matrix.py
+    attr: MatrixAdapter
--- a/src/langbot/pkg/platform/sources/openclaw_weixin.yaml
+++ b/src/langbot/pkg/platform/sources/openclaw_weixin.yaml
@@ -32,6 +32,20 @@ spec:
      type: string
      required: true
      default: "https://ilinkai.weixin.qq.com"
+    - name: qr-login
+      label:
+        en_US: Scan QR Login
+        zh_Hans: 扫码登录
+        zh_Hant: 掃碼登入
+        ja_JP: QRコードでログイン
+      description:
+        en_US: Scan QR code with WeChat to authorize and automatically fill in the token
+        zh_Hans: 使用微信扫码授权，自动填写令牌
+        zh_Hant: 使用微信掃碼授權，自動填寫令牌
+        ja_JP: WeChatでQRコードをスキャンし、トークンを自動入力
+      type: qr-code-login
+      login_platform: weixin
+      required: false
    - name: token
      label:
        en_US: Token
--- a/src/langbot/pkg/platform/sources/qqofficial.py
+++ b/src/langbot/pkg/platform/sources/qqofficial.py
@@ -1,9 +1,11 @@
 from __future__ import annotations
 import typing
+import re
 import asyncio
 import traceback

 import datetime
+import time

 import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
 import langbot_plugin.api.entities.builtin.platform.message as platform_message
@@ -15,11 +17,25 @@ from ...utils import image
 from ..logger import EventLogger


+def _is_base64_data(value: str) -> bool:
+    """Check if a string contains base64-encoded data rather than a URL."""
+    if not value:
+        return False
+    # data: URI scheme (e.g. data:image/png;base64,xxx)
+    if value.startswith('data:'):
+        return True
+    # Only treat as base64 if it doesn't look like a URL/path and has valid base64 chars
+    if value.startswith(('http://', 'https://', '/', './', '../')):
+        return False
+    # Check if it looks like base64 (only valid chars, reasonable length)
+    return bool(re.fullmatch(r'[A-Za-z0-9+/=\s]{20,}', value))
+
+
 class QQOfficialMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
    @staticmethod
    async def yiri2target(message_chain: platform_message.MessageChain):
+        """将 LangBot 消息链转换为 QQ Official 消息格式列表。"""
        content_list = []
-        # 只实现了发文字
        for msg in message_chain:
            if type(msg) is platform_message.Plain:
                content_list.append(
@@ -28,6 +44,49 @@ class QQOfficialMessageConverter(abstract_platform_adapter.AbstractMessageConver
                        'content': msg.text,
                    }
                )
+            elif type(msg) is platform_message.Image:
+                url = msg.url if hasattr(msg, 'url') and msg.url else None
+                b64 = msg.base64 if hasattr(msg, 'base64') and msg.base64 else None
+                # Some plugins (e.g. MimoTTS) store base64 data in the url field
+                if url and not b64 and _is_base64_data(url):
+                    b64 = url
+                    url = None
+                content_list.append(
+                    {
+                        'type': 'image',
+                        'url': url,
+                        'base64': b64,
+                    }
+                )
+            elif type(msg) is platform_message.Voice:
+                url = msg.url if hasattr(msg, 'url') and msg.url else None
+                b64 = msg.base64 if hasattr(msg, 'base64') and msg.base64 else None
+                # Some plugins (e.g. MimoTTS) store base64 data in the url field
+                if url and not b64 and _is_base64_data(url):
+                    b64 = url
+                    url = None
+                content_list.append(
+                    {
+                        'type': 'voice',
+                        'url': url,
+                        'base64': b64,
+                    }
+                )
+            elif type(msg) is platform_message.File:
+                url = msg.url if hasattr(msg, 'url') and msg.url else None
+                b64 = msg.base64 if hasattr(msg, 'base64') and msg.base64 else None
+                # Some plugins store base64 data in the url field
+                if url and not b64 and _is_base64_data(url):
+                    b64 = url
+                    url = None
+                content_list.append(
+                    {
+                        'type': 'file',
+                        'url': url,
+                        'base64': b64,
+                        'name': msg.name if hasattr(msg, 'name') else 'file',
+                    }
+                )

        return content_list

@@ -129,12 +188,19 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
    config: dict
    bot_account_id: str
    bot_uuid: str = None
+    enable_webhook: bool = False
    message_converter: QQOfficialMessageConverter = QQOfficialMessageConverter()
    event_converter: QQOfficialEventConverter = QQOfficialEventConverter()

    def __init__(self, config: dict, logger: EventLogger):
+        enable_webhook = config.get('enable-webhook', False)
+
        bot = QQOfficialClient(
-            app_id=config['appid'], secret=config['secret'], token=config['token'], logger=logger, unified_mode=True
+            app_id=config['appid'],
+            secret=config['secret'],
+            token=config['token'],
+            logger=logger,
+            unified_mode=enable_webhook,
        )

        super().__init__(
@@ -144,6 +210,13 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
            bot_account_id=config['appid'],
        )

+        self.enable_webhook = enable_webhook
+        self._ws_task: asyncio.Task = None
+        self._stream_ctx: dict = {}
+        self._stream_ctx_ts: dict[str, float] = {}
+        self._fallback_text: dict[str, str] = {}
+        self._fallback_text_ts: dict[str, float] = {}
+
    async def reply_message(
        self,
        message_source: platform_events.MessageEvent,
@@ -156,28 +229,18 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter

        content_list = await QQOfficialMessageConverter.yiri2target(message)

-        # 私聊消息
+        # 确定 target_type 和 target_id
+        target_type = None
+        target_id = None
+
        if qq_official_event.t == 'C2C_MESSAGE_CREATE':
-            for content in content_list:
-                if content['type'] == 'text':
-                    await self.bot.send_private_text_msg(
-                        qq_official_event.user_openid,
-                        content['content'],
-                        qq_official_event.d_id,
-                    )
-
-        # 群聊消息
-        if qq_official_event.t == 'GROUP_AT_MESSAGE_CREATE':
-            for content in content_list:
-                if content['type'] == 'text':
-                    await self.bot.send_group_text_msg(
-                        qq_official_event.group_openid,
-                        content['content'],
-                        qq_official_event.d_id,
-                    )
-
-        # 频道群聊
-        if qq_official_event.t == 'AT_MESSAGE_CREATE':
+            target_type = 'c2c'
+            target_id = qq_official_event.user_openid
+        elif qq_official_event.t == 'GROUP_AT_MESSAGE_CREATE':
+            target_type = 'group'
+            target_id = qq_official_event.group_openid
+        elif qq_official_event.t == 'AT_MESSAGE_CREATE':
+            # 频道群聊使用频道 API，暂不支持富媒体
            for content in content_list:
                if content['type'] == 'text':
                    await self.bot.send_channle_group_text_msg(
@@ -185,9 +248,9 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
                        content['content'],
                        qq_official_event.d_id,
                    )
-
-        # 频道私聊
-        if qq_official_event.t == 'DIRECT_MESSAGE_CREATE':
+            return
+        elif qq_official_event.t == 'DIRECT_MESSAGE_CREATE':
+            # 频道私聊使用频道 API，暂不支持富媒体
            for content in content_list:
                if content['type'] == 'text':
                    await self.bot.send_channle_private_text_msg(
@@ -195,6 +258,63 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
                        content['content'],
                        qq_official_event.d_id,
                    )
+            return
+
+        # C2C 和群聊：支持文字 + 富媒体
+        for content in content_list:
+            content_type = content.get('type', 'text')
+
+            if content_type == 'text':
+                if target_type == 'c2c':
+                    await self.bot.send_private_text_msg(
+                        target_id,
+                        content['content'],
+                        qq_official_event.d_id,
+                    )
+                elif target_type == 'group':
+                    await self.bot.send_group_text_msg(
+                        target_id,
+                        content['content'],
+                        qq_official_event.d_id,
+                    )
+
+            elif content_type == 'image':
+                file_url = content.get('url')
+                file_data = content.get('base64')
+                if file_url or file_data:
+                    await self.bot.send_image_msg(
+                        target_type,
+                        target_id,
+                        file_url=file_url,
+                        file_data=file_data,
+                        msg_id=qq_official_event.d_id,
+                    )
+
+            elif content_type == 'voice':
+                file_url = content.get('url')
+                file_data = content.get('base64')
+                if file_url or file_data:
+                    await self.bot.send_voice_msg(
+                        target_type,
+                        target_id,
+                        file_url=file_url,
+                        file_data=file_data,
+                        msg_id=qq_official_event.d_id,
+                    )
+
+            elif content_type == 'file':
+                file_url = content.get('url')
+                file_data = content.get('base64')
+                file_name = content.get('name', 'file')
+                if file_url or file_data:
+                    await self.bot.send_file_msg(
+                        target_type,
+                        target_id,
+                        file_url=file_url,
+                        file_data=file_data,
+                        file_name=file_name,
+                        msg_id=qq_official_event.d_id,
+                    )

    async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
        pass
@@ -238,17 +358,196 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
        return await self.bot.handle_unified_webhook(request)

    async def run_async(self):
-        # 统一 webhook 模式下，不启动独立的 Quart 应用
-        # 保持运行但不启动独立端口
+        if not self.enable_webhook:
+            await self._run_websocket()
+        else:
+            # 统一 webhook 模式下，不启动独立的 Quart 应用
+            async def keep_alive():
+                while True:
+                    await asyncio.sleep(1)

-        async def keep_alive():
-            while True:
-                await asyncio.sleep(1)
+            await keep_alive()

-        await keep_alive()
+    async def _run_websocket(self):
+        """以 WebSocket 模式运行网关连接"""
+        await self.logger.info('QQ Official adapter starting in WebSocket mode')
+
+        async def on_ready():
+            await self.logger.info('QQ Official WebSocket connected and ready')
+
+        async def on_event(event_type: str, event_data: dict):
+            # 只处理消息事件，忽略 READY/RESUMED 等系统事件
+            message_event_types = {
+                'C2C_MESSAGE_CREATE',
+                'DIRECT_MESSAGE_CREATE',
+                'GROUP_AT_MESSAGE_CREATE',
+                'AT_MESSAGE_CREATE',
+            }
+            if event_type not in message_event_types:
+                return
+            if not isinstance(event_data, dict):
+                await self.logger.warning(f'Event data is not dict, skipping: {event_type} -> {type(event_data)}')
+                return
+            await self.logger.info(f'Processing message event: {event_type}')
+            # 构造与 webhook 模式相同的 payload 结构
+            payload = {'t': event_type, 'd': event_data}
+            message_data = await self.bot.get_message(payload)
+            if message_data:
+                event = QQOfficialEvent.from_payload(message_data)
+                await self.bot._handle_message(event)
+
+        async def on_error(error: Exception):
+            await self.logger.error(f'WebSocket error: {error}')
+            await self.logger.error(f'QQ Official WebSocket error: {error}')
+
+        self._ws_task = asyncio.create_task(self.bot.connect_gateway_loop(on_event, on_ready, on_error))
+        try:
+            await self._ws_task
+        except asyncio.CancelledError:
+            pass

    async def kill(self) -> bool:
-        return False
+        if self._ws_task:
+            self._ws_task.cancel()
+            try:
+                await self._ws_task
+            except asyncio.CancelledError:
+                pass
+            self._ws_task = None
+        return True
+
+    # --------------- 流式输出 ---------------
+
+    _STREAM_CTX_TTL = 300  # seconds
+
+    async def _cleanup_stale_streams(self):
+        """Remove stream contexts that have not been updated for more than _STREAM_CTX_TTL seconds."""
+        now = time.time()
+        stale_ids = [mid for mid, ts in self._stream_ctx_ts.items() if now - ts > self._STREAM_CTX_TTL]
+        for mid in stale_ids:
+            self._stream_ctx.pop(mid, None)
+            self._stream_ctx_ts.pop(mid, None)
+        stale_fb = [mid for mid, ts in self._fallback_text_ts.items() if now - ts > self._STREAM_CTX_TTL]
+        for mid in stale_fb:
+            self._fallback_text.pop(mid, None)
+            self._fallback_text_ts.pop(mid, None)
+        if stale_ids or stale_fb:
+            await self.logger.debug(f'Cleaned up {len(stale_ids)} stream contexts, {len(stale_fb)} fallback texts')
+
+    async def is_stream_output_supported(self) -> bool:
+        return self.config.get('enable-stream-reply', False)
+
+    async def create_message_card(self, message_id: str, event: platform_events.MessageEvent) -> bool:
+        source = event.source_platform_object
+        # Streaming API only supports C2C private chat
+        if source.t != 'C2C_MESSAGE_CREATE':
+            return False
+
+        ctx = {
+            'user_openid': source.user_openid,
+            'msg_id': source.d_id,
+            'stream_msg_id': None,
+            'msg_seq': 1,
+            'index': 0,
+            'last_update_ts': 0,
+            'accumulated_text': '',
+            'sent_length': 0,
+            'session_started': False,
+        }
+
+        self._stream_ctx[message_id] = ctx
+        self._stream_ctx_ts[message_id] = time.time()
+        return True
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message: dict,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        # Periodically clean up stale stream contexts
+        await self._cleanup_stale_streams()
+        # 提取纯文本内容（当前 chunk 的文本）
+        text_parts = []
+        for msg in message:
+            if type(msg) is platform_message.Plain:
+                text_parts.append(msg.text)
+        chunk_text = '\n\n'.join(text_parts)
+
+        message_id = (
+            bot_message.get('resp_message_id')
+            if isinstance(bot_message, dict)
+            else getattr(bot_message, 'resp_message_id', None)
+        )
+        if not message_id or message_id not in self._stream_ctx:
+            # 非流式场景（如群聊不支持流式），累积文本后一次性回复
+            if chunk_text:
+                self._fallback_text[message_id] = self._fallback_text.get(message_id, '') + chunk_text
+                self._fallback_text_ts[message_id] = time.time()
+            if is_final:
+                full_text = self._fallback_text.pop(message_id, '')
+                if full_text:
+                    fallback_msg = platform_message.MessageChain([platform_message.Plain(text=full_text)])
+                    await self.reply_message(message_source, fallback_msg, quote_origin)
+            return
+
+        ctx = self._stream_ctx[message_id]
+
+        # 累积文本
+        if chunk_text:
+            ctx['accumulated_text'] += chunk_text
+
+        # 未启动会话时，等第一个有内容的 chunk 来建立会话
+        if not ctx['session_started']:
+            if not ctx['accumulated_text']:
+                return
+            # 用第一个 chunk 的文本建立会话（不发 "..." 避免污染前缀）
+            ctx['session_started'] = True
+
+        # 发送内容 = 全量累积文本
+        # QQ API 的 replace 模式不允许修改已下发前缀，所以：
+        # - 首次：发送全部文本，建立会话
+        # - 后续：只能发送新增部分（append 行为）
+        content_to_send = ctx['accumulated_text'][ctx['sent_length'] :]
+        if not content_to_send and not is_final:
+            return
+
+        input_state = 10 if is_final else 1
+
+        # Rate limiting: skip non-final updates if last update was <0.5s ago
+        now = time.time()
+        if not is_final and (now - ctx['last_update_ts']) < 0.5:
+            return
+        ctx['last_update_ts'] = now
+
+        try:
+            resp = await self.bot.send_stream_msg(
+                user_openid=ctx['user_openid'],
+                content=content_to_send,
+                event_id=ctx['msg_id'],
+                msg_id=ctx['msg_id'],
+                msg_seq=ctx['msg_seq'],
+                index=ctx['index'],
+                stream_msg_id=ctx['stream_msg_id'],
+                input_state=input_state,
+            )
+            if resp and isinstance(resp, dict):
+                new_stream_id = resp.get('id')
+                if new_stream_id:
+                    ctx['stream_msg_id'] = new_stream_id
+            ctx['sent_length'] = len(ctx['accumulated_text'])
+            ctx['index'] += 1
+            await self.logger.debug(
+                f'[QQ Official] 流式 chunk 已发送, index={ctx["index"]}, '
+                f'sent_len={ctx["sent_length"]}, is_final={is_final}'
+            )
+        except Exception as e:
+            await self.logger.error(f'Failed to send stream message: {e}')
+
+        if is_final:
+            self._stream_ctx.pop(message_id, None)

    def unregister_listener(
        self,
--- a/src/langbot/pkg/platform/sources/qqofficial.yaml
+++ b/src/langbot/pkg/platform/sources/qqofficial.yaml
@@ -7,9 +7,9 @@ metadata:
    zh_Hans: QQ 官方 API
    zh_Hant: QQ 官方 API
  description:
-    en_US: QQ Official API (Webhook)
-    zh_Hans: QQ 官方 API (Webhook)，需要公网地址以接收消息推送，请查看文档了解使用方式
-    zh_Hant: QQ 官方 API (Webhook)，需要公網地址以接收訊息推送，請查看文件了解使用方式
+    en_US: QQ Official API (Webhook / WebSocket)
+    zh_Hans: QQ 官方 API，支持 Webhook 和 WebSocket 两种连接模式
+    zh_Hant: QQ 官方 API，支援 Webhook 和 WebSocket 兩種連線模式
  icon: qqofficial.svg
 spec:
  categories:
@@ -19,18 +19,6 @@ spec:
    en: https://link.langbot.app/en/platforms/qqofficial
    ja: https://link.langbot.app/ja/platforms/qqofficial
  config:
-    - name: webhook_url
-      label:
-        en_US: Webhook Callback URL
-        zh_Hans: Webhook 回调地址
-        zh_Hant: Webhook 回調地址
-      description:
-        en_US: Copy this URL and paste it into your QQ Official API webhook configuration
-        zh_Hans: 复制此地址并粘贴到 QQ 官方 API 的 Webhook 配置中
-        zh_Hant: 複製此地址並貼到 QQ 官方 API 的 Webhook 設定中
-      type: webhook-url
-      required: false
-      default: ""
    - name: appid
      label:
        en_US: App ID
@@ -55,6 +43,46 @@ spec:
      type: string
      required: true
      default: ""
+    - name: enable-webhook
+      label:
+        en_US: Enable Webhook Mode
+        zh_Hans: 启用Webhook模式
+        zh_Hant: 啟用 Webhook 模式
+      description:
+        en_US: If enabled, the bot will use webhook mode to receive messages. Otherwise, it will use WebSocket mode
+        zh_Hans: 如果启用，机器人将使用 Webhook 模式接收消息。否则，将使用 WebSocket 模式
+        zh_Hant: 如果啟用，機器人將使用 Webhook 模式接收訊息。否則，將使用 WebSocket 模式
+      type: boolean
+      required: true
+      default: false
+    - name: enable-stream-reply
+      label:
+        en_US: Enable Stream Reply Mode
+        zh_Hans: 启用流式回复模式
+        zh_Hant: 啟用串流回覆模式
+      description:
+        en_US: If enabled, the bot will use streaming mode to reply messages (C2C only)
+        zh_Hans: 如果启用，机器人将使用流式方式回复消息（仅私聊）
+        zh_Hant: 如果啟用，機器人將使用串流方式回覆訊息（僅私聊）
+      type: boolean
+      required: true
+      default: false
+    - name: webhook_url
+      label:
+        en_US: Webhook Callback URL
+        zh_Hans: Webhook 回调地址
+        zh_Hant: Webhook 回調地址
+      description:
+        en_US: Copy this URL and paste it into your QQ Official API webhook configuration
+        zh_Hans: 复制此地址并粘贴到 QQ 官方 API 的 Webhook 配置中
+        zh_Hant: 複製此地址並貼到 QQ 官方 API 的 Webhook 設定中
+      type: webhook-url
+      required: false
+      default: ""
+      show_if:
+        field: enable-webhook
+        operator: eq
+        value: true
 execution:
  python:
    path: ./qqofficial.py
--- a/src/langbot/pkg/platform/sources/web_page_bot.yaml
+++ b/src/langbot/pkg/platform/sources/web_page_bot.yaml
@@ -0,0 +1,177 @@
+apiVersion: v1
+kind: MessagePlatformAdapter
+metadata:
+  name: web_page_bot
+  label:
+    en_US: "Page Bot"
+    zh_Hans: "页面机器人"
+    zh_Hant: "頁面機器人"
+    ja_JP: "ページボット"
+    th_TH: "บอทหน้าเว็บ"
+    vi_VN: "Bot trang web"
+    es_ES: "Bot de página"
+  description:
+    en_US: "Embed a chat widget on any website with a simple script tag"
+    zh_Hans: "通过一行脚本标签将聊天组件嵌入到任何网站"
+    zh_Hant: "透過一行腳本標籤將聊天元件嵌入到任何網站"
+    ja_JP: "シンプルなスクリプトタグで任意のウェブサイトにチャットウィジェットを埋め込みます"
+    th_TH: "ฝังวิดเจ็ตแชทในเว็บไซต์ใดก็ได้ด้วยแท็กสคริปต์"
+    vi_VN: "Nhúng widget trò chuyện vào bất kỳ trang web nào bằng thẻ script"
+    es_ES: "Incrusta un widget de chat en cualquier sitio web con una etiqueta de script"
+  icon: "webpage.webp"
+spec:
+  categories:
+    - popular
+  config:
+    - name: title
+      label:
+        en_US: Widget Title
+        zh_Hans: 组件标题
+        zh_Hant: 元件標題
+        ja_JP: ウィジェットタイトル
+        th_TH: ชื่อวิดเจ็ต
+        vi_VN: Tiêu đề widget
+        es_ES: Título del widget
+      description:
+        en_US: The title displayed in the chat widget header
+        zh_Hans: 显示在聊天组件顶部的标题
+        zh_Hant: 顯示在聊天元件頂部的標題
+        ja_JP: チャットウィジェットのヘッダーに表示されるタイトル
+        th_TH: ชื่อที่แสดงในส่วนหัวของวิดเจ็ตแชท
+        vi_VN: Tiêu đề hiển thị trong đầu widget trò chuyện
+        es_ES: El título que se muestra en el encabezado del widget de chat
+      type: string
+      required: false
+      default: "LangBot"
+    - name: bubble_icon
+      label:
+        en_US: Bubble Icon
+        zh_Hans: 气泡图标
+        zh_Hant: 氣泡圖示
+        ja_JP: バブルアイコン
+        th_TH: ไอคอนบับเบิล
+        vi_VN: Biểu tượng bong bóng
+        es_ES: Icono de burbuja
+        ru_RU: Иконка пузырька
+      description:
+        en_US: "Icon displayed on the floating chat bubble"
+        zh_Hans: "浮动聊天气泡上显示的图标"
+      type: select
+      required: false
+      default: "logo"
+      options:
+        - name: "logo"
+          label:
+            en_US: "LangBot Logo"
+            zh_Hans: "LangBot 图标"
+        - name: "chat"
+          label:
+            en_US: "Chat Bubble"
+            zh_Hans: "聊天气泡"
+        - name: "robot"
+          label:
+            en_US: "Robot"
+            zh_Hans: "机器人"
+        - name: "headset"
+          label:
+            en_US: "Headset"
+            zh_Hans: "客服耳机"
+        - name: "sparkle"
+          label:
+            en_US: "Sparkle"
+            zh_Hans: "星光"
+        - name: "message"
+          label:
+            en_US: "Message"
+            zh_Hans: "消息"
+    - name: language
+      label:
+        en_US: Widget Language
+        zh_Hans: 组件语言
+        zh_Hant: 元件語言
+        ja_JP: ウィジェット言語
+        th_TH: ภาษาวิดเจ็ต
+        vi_VN: Ngôn ngữ widget
+        es_ES: Idioma del widget
+        ru_RU: Язык виджета
+      description:
+        en_US: "Display language of the chat widget"
+        zh_Hans: "聊天组件的显示语言"
+        zh_Hant: "聊天元件的顯示語言"
+        ja_JP: "チャットウィジェットの表示言語"
+        th_TH: "ภาษาแสดงผลของวิดเจ็ตแชท"
+        vi_VN: "Ngôn ngữ hiển thị của widget trò chuyện"
+        es_ES: "Idioma de visualización del widget de chat"
+        ru_RU: "Язык отображения виджета чата"
+      type: select
+      required: false
+      default: "en_US"
+      options:
+        - name: "en_US"
+          label:
+            en_US: "English"
+        - name: "zh_Hans"
+          label:
+            en_US: "简体中文"
+        - name: "zh_Hant"
+          label:
+            en_US: "繁體中文"
+        - name: "ja_JP"
+          label:
+            en_US: "日本語"
+        - name: "es_ES"
+          label:
+            en_US: "Español"
+        - name: "ru_RU"
+          label:
+            en_US: "Русский"
+        - name: "th_TH"
+          label:
+            en_US: "ไทย"
+        - name: "vi_VN"
+          label:
+            en_US: "Tiếng Việt"
+    - name: embed_code
+      label:
+        en_US: Embed Code
+        zh_Hans: 嵌入代码
+        zh_Hant: 嵌入代碼
+        ja_JP: 埋め込みコード
+        th_TH: โค้ดฝังตัว
+        vi_VN: Mã nhúng
+        es_ES: Código de incrustación
+      description:
+        en_US: "Copy this code and paste it into your website HTML. The code will be generated after saving."
+        zh_Hans: "复制此代码并粘贴到你的网站 HTML 中。保存后将自动生成。"
+        zh_Hant: "複製此代碼並貼到你的網站 HTML 中。儲存後將自動生成。"
+        ja_JP: "このコードをコピーしてウェブサイトのHTMLに貼り付けてください。保存後に自動生成されます。"
+        th_TH: "คัดลอกโค้ดนี้และวางในHTML ของเว็บไซต์ของคุณ จะสร้างอัตโนมัติหลังจากบันทึก"
+        vi_VN: "Sao chép mã này và dán vào HTML trang web của bạn. Mã sẽ được tạo tự động sau khi lưu."
+        es_ES: "Copia este código y pégalo en el HTML de tu sitio web. El código se generará después de guardar."
+      type: embed-code
+      required: false
+      default: ""
+    - name: turnstile_site_key
+      label:
+        en_US: Turnstile Site Key
+        zh_Hans: Turnstile 站点密钥
+      description:
+        en_US: "Cloudflare Turnstile site key for bot protection. Get it from the Cloudflare dashboard (Turnstile > Add Site). Leave empty to disable."
+        zh_Hans: "Cloudflare Turnstile 站点密钥，用于防止机器人滥用。在 Cloudflare 控制台（Turnstile > 添加站点）中获取。留空则不启用。"
+      type: string
+      required: false
+      default: ""
+    - name: turnstile_secret_key
+      label:
+        en_US: Turnstile Secret Key
+        zh_Hans: Turnstile 服务端密钥
+      description:
+        en_US: "Cloudflare Turnstile secret key for server-side token verification. Found alongside the site key in the Cloudflare dashboard. Required if site key is set."
+        zh_Hans: "Cloudflare Turnstile 服务端密钥，用于服务端验证令牌。与站点密钥一起在 Cloudflare 控制台中获取。设置了站点密钥时必填。"
+      type: string
+      required: false
+      default: ""
+execution:
+  python:
+    path: "web_page_bot_adapter.py"
+    attr: "WebPageBotAdapter"
--- a/src/langbot/pkg/platform/sources/web_page_bot_adapter.py
+++ b/src/langbot/pkg/platform/sources/web_page_bot_adapter.py
@@ -0,0 +1,94 @@
+"""Web Page Bot adapter - lightweight adapter for embeddable chat widget"""
+
+import typing
+
+import pydantic
+
+import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
+
+
+class WebPageBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
+    """Lightweight adapter for the embeddable page bot.
+
+    This adapter does not handle messages itself. The actual WebSocket
+    communication is handled by the singleton websocket_proxy_bot.
+    This adapter stores event listeners so that RuntimeBot can register
+    its handlers, which are then called by the websocket adapter when
+    a message arrives for this bot's pipeline.
+
+    Message sending/replying is delegated to the websocket_proxy_bot's
+    adapter so that replies are actually delivered over the WebSocket
+    connection while the dashboard correctly shows this adapter's name.
+    """
+
+    listeners: dict = pydantic.Field(default_factory=dict, exclude=True)
+    _ws_adapter: typing.Any = None
+
+    model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
+
+    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger, **kwargs):
+        super().__init__(config=config, logger=logger, **kwargs)
+
+    def set_ws_adapter(self, ws_adapter) -> None:
+        """Set the underlying WebSocket adapter used for actual message delivery."""
+        object.__setattr__(self, '_ws_adapter', ws_adapter)
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ) -> dict:
+        if self._ws_adapter is not None:
+            return await self._ws_adapter.send_message(target_type, target_id, message)
+        return {}
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ) -> dict:
+        if self._ws_adapter is not None:
+            return await self._ws_adapter.reply_message(message_source, message, quote_origin)
+        return {}
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ) -> dict:
+        if self._ws_adapter is not None:
+            return await self._ws_adapter.reply_message_chunk(
+                message_source, bot_message, message, quote_origin, is_final
+            )
+        return {}
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        func: typing.Callable,
+    ):
+        self.listeners[event_type] = func
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        func: typing.Callable,
+    ):
+        self.listeners.pop(event_type, None)
+
+    async def is_muted(self, group_id: int) -> bool:
+        return False
+
+    async def run_async(self):
+        pass
+
+    async def kill(self):
+        pass
--- a/src/langbot/pkg/platform/sources/webpage.webp
+++ b/src/langbot/pkg/platform/sources/webpage.webp
--- a/src/langbot/pkg/platform/sources/websocket_adapter.py
+++ b/src/langbot/pkg/platform/sources/websocket_adapter.py
@@ -312,7 +312,7 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)

    async def _process_image_components(self, message_chain_obj: list):
        """
-        处理消息链中的图片组件，将path转换为base64
+        处理消息链中的图片和文件组件，将path转换为base64

        Args:
            message_chain_obj: 消息链对象列表
@@ -322,16 +322,18 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
        storage_mgr = self.ap.storage_mgr

        for component in message_chain_obj:
-            if component.get('type') == 'Image' and component.get('path'):
-                try:
-                    # 从storage读取文件
-                    file_content = await storage_mgr.storage_provider.load(component['path'])
+            comp_type = component.get('type', '')
+            comp_path = component.get('path', '')

-                    # 转换为base64
+            if not comp_path:
+                continue
+
+            if comp_type == 'Image':
+                try:
+                    file_content = await storage_mgr.storage_provider.load(comp_path)
                    base64_str = base64.b64encode(file_content).decode('utf-8')

-                    # 添加data URI前缀（根据文件扩展名判断MIME类型）
-                    file_key = component['path']
+                    file_key = comp_path
                    if file_key.lower().endswith(('.jpg', '.jpeg')):
                        mime_type = 'image/jpeg'
                    elif file_key.lower().endswith('.png'):
@@ -341,19 +343,19 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
                    elif file_key.lower().endswith('.webp'):
                        mime_type = 'image/webp'
                    else:
-                        mime_type = 'image/png'  # 默认
+                        mime_type = 'image/png'

                    component['base64'] = f'data:{mime_type};base64,{base64_str}'
-                    await storage_mgr.storage_provider.delete(component['path'])
+                    await storage_mgr.storage_provider.delete(comp_path)
                    component['path'] = ''
-                    # 保留path字段用于后端处理，前端使用base64显示
                except Exception as e:
-                    await self.logger.error(f'加载图片文件失败 {component["path"]}: {e}')
+                    await self.logger.error(f'Failed to load image file {comp_path}: {e}')

    async def handle_websocket_message(
        self,
        connection: WebSocketConnection,
        message_data: dict,
+        owner_bot=None,
    ):
        """
        处理从WebSocket接收的消息
@@ -366,6 +368,8 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
            message_data: 消息数据，包含:
                - message: 消息链
                - stream: 是否启用流式输出 (可选，默认True)
+            owner_bot: Optional RuntimeBot that owns this pipeline (e.g. a web_page_bot).
+                       When provided, its identity is used for logging and session tracking.
        """
        pipeline_uuid = connection.pipeline_uuid
        session_type = connection.session_type
@@ -435,12 +439,26 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
                sender=sender, message_chain=message_chain, time=datetime.now().timestamp()
            )

-        # 设置流水线UUID
+        # 设置流水线UUID (proxy bot always needs it for reply_message routing)
        self.ap.platform_mgr.websocket_proxy_bot.bot_entity.use_pipeline_uuid = pipeline_uuid
+        if owner_bot is not None:
+            owner_bot.bot_entity.use_pipeline_uuid = pipeline_uuid

-        # 异步触发事件处理（不等待结果）
-        if event.__class__ in self.listeners:
-            asyncio.create_task(self.listeners[event.__class__](event, self))
+        # 异步触发事件处理
+        # Use owner_bot's listeners if available, otherwise fall back to proxy bot
+        listeners = (
+            owner_bot.adapter.listeners
+            if (owner_bot and hasattr(owner_bot.adapter, 'listeners') and owner_bot.adapter.listeners)
+            else self.listeners
+        )
+        # Pass owner_bot's adapter so that downstream logging / dashboard
+        # attributes the message to the correct bot adapter name.
+        # Wire the ws adapter into the owner so replies are actually delivered.
+        if owner_bot and hasattr(owner_bot.adapter, 'set_ws_adapter'):
+            owner_bot.adapter.set_ws_adapter(self)
+        callback_adapter = owner_bot.adapter if (owner_bot and hasattr(owner_bot, 'adapter')) else self
+        if event.__class__ in listeners:
+            asyncio.create_task(listeners[event.__class__](event, callback_adapter))

    def get_websocket_messages(self, pipeline_uuid: str, session_type: str) -> list[dict]:
        """获取消息历史"""
--- a/src/langbot/pkg/platform/sources/wecombot.yaml
+++ b/src/langbot/pkg/platform/sources/wecombot.yaml
@@ -19,6 +19,18 @@ spec:
    en: https://link.langbot.app/en/platforms/wecombot
    ja: https://link.langbot.app/ja/platforms/wecombot
  config:
+    - name: one-click-create
+      label:
+        en_US: One-Click Create Bot
+        zh_Hans: 一键创建机器人
+        zh_Hant: 一鍵建立機器人
+      description:
+        en_US: "Scan QR code with WeCom to automatically create a bot and fill in BotId and Secret. Note: Robot Name needs to be filled in manually."
+        zh_Hans: "使用企业微信扫码自动创建机器人并填写 BotId 和 Secret。注意：机器人名称需手动填写。"
+        zh_Hant: "使用企業微信掃碼自動建立機器人並填寫 BotId 和 Secret。注意：機器人名稱需手動填寫。"
+      type: qr-code-login
+      login_platform: wecombot
+      required: false
    - name: BotId
      label:
        en_US: BotId
--- a/src/langbot/pkg/plugin/connector.py
+++ b/src/langbot/pkg/plugin/connector.py
@@ -11,6 +11,7 @@ import os
 import sys
 import httpx
 import sqlalchemy
+import yaml
 from async_lru import alru_cache
 from langbot_plugin.api.entities.builtin.pipeline.query import provider_session

@@ -34,6 +35,10 @@ from ..core import taskmgr
 from ..entity.persistence import plugin as persistence_plugin


+class PluginRuntimeNotConnectedError(RuntimeError):
+    """Raised when plugin runtime operations are requested before connection."""
+
+
 class PluginRuntimeConnector:
    """Plugin runtime connector"""

@@ -191,44 +196,114 @@ class PluginRuntimeConnector:

    async def ping_plugin_runtime(self):
        if not hasattr(self, 'handler'):
-            raise Exception('Plugin runtime is not connected')
+            raise PluginRuntimeNotConnectedError('Plugin runtime is not connected')

        return await self.handler.ping()

-    def _extract_deps_metadata(
+    def _inspect_plugin_package(
        self,
        file_bytes: bytes,
        task_context: taskmgr.TaskContext | None,
-    ):
-        """Extract dependency count from requirements.txt inside plugin zip."""
-        if task_context is None:
-            return
+    ) -> tuple[str | None, str | None]:
+        """Extract plugin identity and dependency metadata from a plugin package."""
+        plugin_author = None
+        plugin_name = None
+
        try:
            with zipfile.ZipFile(io.BytesIO(file_bytes)) as zf:
-                for name in zf.namelist():
-                    if name.endswith('requirements.txt'):
-                        content = zf.read(name).decode('utf-8', errors='ignore')
-                        deps = [
-                            line.strip()
-                            for line in content.splitlines()
-                            if line.strip() and not line.strip().startswith('#')
-                        ]
-                        task_context.metadata['deps_total'] = len(deps)
-                        task_context.metadata['deps_list'] = deps
-                        break
+                try:
+                    manifest = yaml.safe_load(zf.read('manifest.yaml').decode('utf-8', errors='ignore')) or {}
+                    metadata = manifest.get('metadata', {})
+                    plugin_author = metadata.get('author')
+                    plugin_name = metadata.get('name')
+                except Exception:
+                    pass
+
+                if task_context is not None:
+                    for name in zf.namelist():
+                        if name.endswith('requirements.txt'):
+                            content = zf.read(name).decode('utf-8', errors='ignore')
+                            deps = [
+                                line.strip()
+                                for line in content.splitlines()
+                                if line.strip() and not line.strip().startswith('#')
+                            ]
+                            task_context.metadata['deps_total'] = len(deps)
+                            task_context.metadata['deps_list'] = deps
+                            break
        except Exception:
            pass

+        return plugin_author, plugin_name
+
+    def _build_plugin_startup_failure_message(
+        self,
+        plugin_author: str,
+        plugin_name: str,
+        task_context: taskmgr.TaskContext | None,
+    ) -> str:
+        dep_hint = ''
+        if task_context is not None:
+            current_dep = task_context.metadata.get('current_dep')
+            if current_dep:
+                dep_hint = f' Last dependency: {current_dep}.'
+
+        return (
+            f'Plugin {plugin_author}/{plugin_name} failed to start after installation. '
+            f'Dependency installation or plugin initialization may have failed.{dep_hint} '
+            f'Please check the plugin requirements and runtime logs.'
+        )
+
+    async def _wait_for_installed_plugin_ready(
+        self,
+        plugin_author: str | None,
+        plugin_name: str | None,
+        task_context: taskmgr.TaskContext | None,
+        timeout: float = 30,
+    ):
+        """Wait until the installed plugin is registered by the runtime.
+
+        The plugin runtime launches plugins asynchronously. If dependency installation
+        fails, the plugin process exits before registration; without this check the
+        install task can incorrectly finish successfully.
+        """
+        if not plugin_author or not plugin_name:
+            return
+
+        deadline = time.time() + timeout
+        last_error: Exception | None = None
+        while time.time() < deadline:
+            try:
+                plugin = await self.get_plugin_info(plugin_author, plugin_name)
+                if plugin is not None:
+                    status = plugin.get('status')
+                    if status == 'initialized':
+                        return
+            except Exception as e:
+                last_error = e
+
+            await asyncio.sleep(0.5)
+
+        message = self._build_plugin_startup_failure_message(plugin_author, plugin_name, task_context)
+        if last_error is not None:
+            message = f'{message} Last runtime error: {last_error}'
+        raise RuntimeError(message)
+
    async def install_plugin(
        self,
        install_source: PluginInstallSource,
        install_info: dict[str, Any],
        task_context: taskmgr.TaskContext | None = None,
    ):
+        plugin_author = install_info.get('plugin_author')
+        plugin_name = install_info.get('plugin_name')
+
        if install_source == PluginInstallSource.LOCAL:
            # transfer file before install
            file_bytes = install_info['plugin_file']
-            self._extract_deps_metadata(file_bytes, task_context)
+            plugin_author, plugin_name = self._inspect_plugin_package(file_bytes, task_context)
+            if task_context is not None and plugin_author and plugin_name:
+                task_context.metadata['plugin_name'] = f'{plugin_author}/{plugin_name}'
            file_key = await self.handler.send_file(file_bytes, 'lbpkg')
            install_info['plugin_file_key'] = file_key
            del install_info['plugin_file']
@@ -265,7 +340,9 @@ class PluginRuntimeConnector:
                                task_context.metadata['download_speed'] = downloaded / elapsed if elapsed > 0 else 0

                    file_bytes = b''.join(chunks)
-                    self._extract_deps_metadata(file_bytes, task_context)
+                    plugin_author, plugin_name = self._inspect_plugin_package(file_bytes, task_context)
+                    if task_context is not None and plugin_author and plugin_name:
+                        task_context.metadata['plugin_name'] = f'{plugin_author}/{plugin_name}'
                    file_key = await self.handler.send_file(file_bytes, 'lbpkg')
                    install_info['plugin_file_key'] = file_key
                    self.ap.logger.info(f'Transfered file {file_key} to plugin runtime')
@@ -289,6 +366,8 @@ class PluginRuntimeConnector:
            if metadata is not None and task_context is not None:
                task_context.metadata.update(metadata)

+        await self._wait_for_installed_plugin_ready(plugin_author, plugin_name, task_context)
+
    async def upgrade_plugin(
        self,
        plugin_author: str,
@@ -431,6 +510,17 @@ class PluginRuntimeConnector:
    async def get_plugin_assets(self, plugin_author: str, plugin_name: str, filepath: str) -> dict[str, Any]:
        return await self.handler.get_plugin_assets(plugin_author, plugin_name, filepath)

+    async def handle_page_api(
+        self,
+        plugin_author: str,
+        plugin_name: str,
+        page_id: str,
+        endpoint: str,
+        method: str,
+        body: Any = None,
+    ) -> dict[str, Any]:
+        return await self.handler.handle_page_api(plugin_author, plugin_name, page_id, endpoint, method, body)
+
    async def get_debug_info(self) -> dict[str, Any]:
        """Get debug information including debug key and WS URL"""
        if not self.is_enable_plugin:
@@ -547,11 +637,12 @@ class PluginRuntimeConnector:
        Raises:
            ValueError: If plugin_id is not in the expected 'author/name' format.
        """
-        if '/' not in plugin_id:
+        segments = plugin_id.split('/')
+        if len(segments) != 2 or not all(segments):
            raise ValueError(
                f"Invalid plugin_id format: '{plugin_id}'. Expected 'author/name' format (e.g. 'langbot/rag-engine')."
            )
-        return plugin_id.split('/', 1)
+        return segments[0], segments[1]

    async def call_rag_ingest(self, plugin_id: str, context_data: dict[str, Any]) -> dict[str, Any]:
        """Call plugin to ingest document.
--- a/src/langbot/pkg/plugin/handler.py
+++ b/src/langbot/pkg/plugin/handler.py
@@ -367,6 +367,22 @@ class RuntimeConnectionHandler(handler.Handler):
            owner_type = data['owner_type']
            owner = data['owner']
            value = base64.b64decode(data['value_base64'])
+            max_value_bytes = (
+                self.ap.instance_config.data.get('plugin', {})
+                .get('binary_storage', {})
+                .get(
+                    'max_value_bytes',
+                    10 * 1024 * 1024,
+                )
+            )
+            try:
+                max_value_bytes = int(max_value_bytes)
+            except (TypeError, ValueError):
+                max_value_bytes = 10 * 1024 * 1024
+            if max_value_bytes >= 0 and len(value) > max_value_bytes:
+                return handler.ActionResponse.error(
+                    message=f'Binary storage value exceeds limit ({len(value)} > {max_value_bytes} bytes)',
+                )

            result = await self.ap.persistence_mgr.execute_async(
                sqlalchemy.select(persistence_bstorage.BinaryStorage)
@@ -939,6 +955,11 @@ class RuntimeConnectionHandler(handler.Handler):
            timeout=20,
        )
        asset_file_key = result['file_file_key']
+        if not asset_file_key:
+            return {
+                'asset_base64': '',
+                'mime_type': '',
+            }
        mime_type = result['mime_type']
        asset_bytes = await self.read_local_file(asset_file_key)
        await self.delete_local_file(asset_file_key)
@@ -947,6 +968,30 @@ class RuntimeConnectionHandler(handler.Handler):
            'mime_type': mime_type,
        }

+    async def handle_page_api(
+        self,
+        plugin_author: str,
+        plugin_name: str,
+        page_id: str,
+        endpoint: str,
+        method: str,
+        body: Any = None,
+    ) -> dict[str, Any]:
+        """Forward a page API call to the plugin via runtime."""
+        result = await self.call_action(
+            LangBotToRuntimeAction.PAGE_API,
+            {
+                'plugin_author': plugin_author,
+                'plugin_name': plugin_name,
+                'page_id': page_id,
+                'endpoint': endpoint,
+                'method': method,
+                'body': body,
+            },
+            timeout=30,
+        )
+        return result
+
    async def cleanup_plugin_data(self, plugin_author: str, plugin_name: str) -> None:
        """Cleanup plugin settings and binary storage"""
        # Delete plugin settings
--- a/src/langbot/pkg/provider/modelmgr/requester.py
+++ b/src/langbot/pkg/provider/modelmgr/requester.py
@@ -340,6 +340,7 @@ class ProviderAPIRequester(metaclass=abc.ABCMeta):
    """Provider API请求器"""

    name: str = None
+    init_api_key: str = 'langbot-init-placeholder'

    ap: app.Application

--- a/src/langbot/pkg/provider/modelmgr/requesters/chatcmpl.py
+++ b/src/langbot/pkg/provider/modelmgr/requesters/chatcmpl.py
@@ -25,7 +25,7 @@ class OpenAIChatCompletions(requester.ProviderAPIRequester):

    async def initialize(self):
        self.client = openai.AsyncClient(
-            api_key='',
+            api_key=self.init_api_key,
            base_url=self.requester_cfg['base_url'].replace(' ', ''),
            timeout=self.requester_cfg['timeout'],
            http_client=httpx.AsyncClient(trust_env=True, timeout=self.requester_cfg['timeout']),
--- a/src/langbot/pkg/provider/modelmgr/requesters/modelscopechatcmpl.py
+++ b/src/langbot/pkg/provider/modelmgr/requesters/modelscopechatcmpl.py
@@ -25,7 +25,7 @@ class ModelScopeChatCompletions(requester.ProviderAPIRequester):

    async def initialize(self):
        self.client = openai.AsyncClient(
-            api_key='',
+            api_key=self.init_api_key,
            base_url=self.requester_cfg['base_url'],
            timeout=self.requester_cfg['timeout'],
            http_client=httpx.AsyncClient(trust_env=True, timeout=self.requester_cfg['timeout']),
--- a/src/langbot/pkg/provider/modelmgr/requesters/qiniu.svg
+++ b/src/langbot/pkg/provider/modelmgr/requesters/qiniu.svg
@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Qiniu</title><path d="M23.111 4.6a.914.914 0 00-.861.161A13.443 13.443 0 017.947 8.897L7.38 6.831a1.076 1.076 0 00-1.211-.698l.27 2.18c-1.816-.827-2.313-.946-3.587-2.45C2.674 5.729 1.263 4.472.89 4.6a11.906 11.906 0 005.892 6.497l.738 5.97s.33 2.286 2.473 2.286h4.586c2.144 0 2.474-2.286 2.474-2.286l.518-4.28c-1.393-.11-2.268.857-2.546 1.814-.465 1.614-.465 1.716-.557 1.998-.188.575-.806.644-.806.644h-2.753s-.617-.07-.806-.644c-.12-.371-.727-2.54-1.335-4.74A11.877 11.877 0 0023.11 4.599V4.6z" fill="#06AEEF"></path></svg>
--- a/src/langbot/pkg/provider/modelmgr/requesters/qiniuchatcmpl.py
+++ b/src/langbot/pkg/provider/modelmgr/requesters/qiniuchatcmpl.py
@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import typing
+
+import openai
+
+from . import chatcmpl
+
+
+class QiniuChatCompletions(chatcmpl.OpenAIChatCompletions):
+    """七牛云 ChatCompletion API 请求器"""
+
+    client: openai.AsyncClient
+
+    default_config: dict[str, typing.Any] = {
+        'base_url': 'https://api.qnaigc.com/v1',
+        'timeout': 120,
+    }
+
+    async def scan_models(self, api_key: str | None = None) -> dict[str, typing.Any]:
+        try:
+            result = await super().scan_models(api_key)
+        except Exception:
+            return self._qiniu_fallback_scan_result()
+        models = result.get('models') or []
+        if not models:
+            return self._qiniu_fallback_scan_result()
+        return result
+
+    def _qiniu_fallback_scan_result(self) -> dict[str, typing.Any]:
+        mid = 'deepseek-v3'
+        return {
+            'models': [
+                {
+                    'id': mid,
+                    'name': mid,
+                    'type': 'llm',
+                    'abilities': [],
+                }
+            ],
+            'debug': {
+                'request': {'method': 'GET', 'url': '', 'headers': {}},
+                'response': {},
+            },
+        }
--- a/src/langbot/pkg/provider/modelmgr/requesters/qiniuchatcmpl.yaml
+++ b/src/langbot/pkg/provider/modelmgr/requesters/qiniuchatcmpl.yaml
@@ -0,0 +1,31 @@
+apiVersion: v1
+kind: LLMAPIRequester
+metadata:
+  name: qiniu-chat-completions
+  label:
+    en_US: Qiniu
+    zh_Hans: 七牛云
+  icon: qiniu.svg
+spec:
+  config:
+  - name: base_url
+    label:
+      en_US: Base URL
+      zh_Hans: 基础 URL
+    type: string
+    required: true
+    default: https://api.qnaigc.com/v1
+  - name: timeout
+    label:
+      en_US: Timeout
+      zh_Hans: 超时时间
+    type: integer
+    required: true
+    default: 120
+  support_type:
+  - llm
+  provider_category: maas
+execution:
+  python:
+    path: ./qiniuchatcmpl.py
+    attr: QiniuChatCompletions
--- a/src/langbot/pkg/provider/modelmgr/token.py
+++ b/src/langbot/pkg/provider/modelmgr/token.py
@@ -14,7 +14,14 @@ class TokenManager:

    def __init__(self, name: str, tokens: list[str]):
        self.name = name
-        self.tokens = tokens
+        self.tokens = []
+        seen_tokens = set()
+        for token in tokens:
+            normalized_token = token.strip() if isinstance(token, str) else ''
+            if not normalized_token or normalized_token in seen_tokens:
+                continue
+            self.tokens.append(normalized_token)
+            seen_tokens.add(normalized_token)
        self.using_token_index = 0

    def get_token(self) -> str:
@@ -23,4 +30,6 @@ class TokenManager:
        return self.tokens[self.using_token_index]

    def next_token(self):
+        if len(self.tokens) == 0:
+            return
        self.using_token_index = (self.using_token_index + 1) % len(self.tokens)
--- a/src/langbot/pkg/provider/runners/n8nsvapi.py
+++ b/src/langbot/pkg/provider/runners/n8nsvapi.py
@@ -187,6 +187,12 @@ class N8nServiceAPIRunner(runner.RequestRunner):
        if not query.session.using_conversation.uuid:
            query.session.using_conversation.uuid = str(uuid.uuid4())

+        # Keep query variables in sync with the generated/new conversation id.
+        # query.variables is later merged into payload and would otherwise
+        # overwrite the generated conversation_id with the stale preprocessor
+        # value (usually None for a new conversation).
+        query.variables['conversation_id'] = query.session.using_conversation.uuid
+
        # 预处理用户消息
        plain_text = await self._preprocess_user_message(query)

--- a/src/langbot/pkg/rag/knowledge/kbmgr.py
+++ b/src/langbot/pkg/rag/knowledge/kbmgr.py
@@ -148,52 +148,60 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
        supported_extensions = {'txt', 'pdf', 'docx', 'md', 'html'}
        stored_file_tasks = []

-        # use utf-8 encoding
-        with zipfile.ZipFile(io.BytesIO(zip_bytes), 'r', metadata_encoding='utf-8') as zip_ref:
-            for file_info in zip_ref.filelist:
-                # skip directories and hidden files
-                if file_info.is_dir() or file_info.filename.startswith('.'):
-                    continue
-
-                _, file_ext = os.path.splitext(file_info.filename)
-                file_extension = file_ext.lstrip('.').lower()
-                if file_extension not in supported_extensions:
-                    self.ap.logger.debug(f'Skipping unsupported file in ZIP: {file_info.filename}')
-                    continue
-
-                try:
-                    file_content = zip_ref.read(file_info.filename)
-
-                    base_name = file_info.filename.replace('/', '_').replace('\\', '_')
-                    file_stem, file_ext = os.path.splitext(base_name)
-                    extension = file_ext.lstrip('.')
-
-                    if file_stem.startswith('__MACOSX'):
+        try:
+            # use utf-8 encoding
+            with zipfile.ZipFile(io.BytesIO(zip_bytes), 'r', metadata_encoding='utf-8') as zip_ref:
+                for file_info in zip_ref.filelist:
+                    # skip directories and hidden files
+                    if file_info.is_dir() or file_info.filename.startswith('.'):
                        continue

-                    extracted_file_id = file_stem + '_' + str(uuid.uuid4())[:8] + '.' + extension
-                    # save file to storage
+                    _, file_ext = os.path.splitext(file_info.filename)
+                    file_extension = file_ext.lstrip('.').lower()
+                    if file_extension not in supported_extensions:
+                        self.ap.logger.debug(f'Skipping unsupported file in ZIP: {file_info.filename}')
+                        continue

-                    await self.ap.storage_mgr.storage_provider.save(extracted_file_id, file_content)
+                    try:
+                        file_content = zip_ref.read(file_info.filename)

-                    task_id = await self.store_file(extracted_file_id, parser_plugin_id=parser_plugin_id)
-                    stored_file_tasks.append(task_id)
+                        base_name = file_info.filename.replace('/', '_').replace('\\', '_')
+                        file_stem, file_ext = os.path.splitext(base_name)
+                        extension = file_ext.lstrip('.')

-                    self.ap.logger.info(
-                        f'Extracted and stored file from ZIP: {file_info.filename} -> {extracted_file_id}'
-                    )
+                        if file_stem.startswith('__MACOSX'):
+                            continue

-                except Exception as e:
-                    self.ap.logger.warning(f'Failed to extract file {file_info.filename} from ZIP: {e}')
-                    continue
+                        extracted_file_id = file_stem + '_' + str(uuid.uuid4())[:8] + '.' + extension
+                        # save file to storage

-        if not stored_file_tasks:
-            raise Exception('No supported files found in ZIP archive')
+                        await self.ap.storage_mgr.storage_provider.save(extracted_file_id, file_content)

-        self.ap.logger.info(f'Successfully processed ZIP file {zip_file_id}, extracted {len(stored_file_tasks)} files')
-        await self.ap.storage_mgr.storage_provider.delete(zip_file_id)
+                        task_id = await self.store_file(extracted_file_id, parser_plugin_id=parser_plugin_id)
+                        stored_file_tasks.append(task_id)

-        return stored_file_tasks[0] if stored_file_tasks else ''
+                        self.ap.logger.info(
+                            f'Extracted and stored file from ZIP: {file_info.filename} -> {extracted_file_id}'
+                        )
+
+                    except Exception as e:
+                        self.ap.logger.warning(f'Failed to extract file {file_info.filename} from ZIP: {e}')
+                        continue
+
+            if not stored_file_tasks:
+                raise Exception('No supported files found in ZIP archive')
+
+            self.ap.logger.info(
+                f'Successfully processed ZIP file {zip_file_id}, extracted {len(stored_file_tasks)} files'
+            )
+            return stored_file_tasks[0] if stored_file_tasks else ''
+        finally:
+            try:
+                await self.ap.storage_mgr.storage_provider.delete(zip_file_id)
+            except FileNotFoundError:
+                pass
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to cleanup ZIP file {zip_file_id}: {e}')

    async def retrieve(self, query: str, settings: dict | None = None) -> list[rag_context.RetrievalResultEntry]:
        # Merge stored retrieval_settings with per-request overrides
--- a/src/langbot/pkg/rag/service/runtime.py
+++ b/src/langbot/pkg/rag/service/runtime.py
@@ -1,8 +1,12 @@
 from __future__ import annotations

 import posixpath
-from typing import Any
-from langbot.pkg.core import app
+import re
+from typing import TYPE_CHECKING, Any
+from urllib.parse import unquote
+
+if TYPE_CHECKING:
+    from langbot.pkg.core import app


 class RAGRuntimeService:
@@ -109,8 +113,17 @@ class RAGRuntimeService:
        regardless of the underlying storage provider.
        """
        # Validate storage_path to prevent path traversal
-        normalized = posixpath.normpath(storage_path)
-        if normalized.startswith('/') or '..' in normalized.split('/'):
+        decoded_path = unquote(storage_path).replace('\\', '/')
+        decoded_segments = decoded_path.split('/')
+        normalized = posixpath.normpath(decoded_path)
+        if (
+            not storage_path
+            or '\x00' in decoded_path
+            or normalized.startswith('/')
+            or '..' in decoded_segments
+            or '..' in normalized.split('/')
+            or re.match(r'^[A-Za-z]:/', normalized)
+        ):
            raise ValueError('Invalid storage path')
        content_bytes = await self.ap.storage_mgr.storage_provider.load(normalized)
        return content_bytes if content_bytes else b''
--- a/src/langbot/pkg/storage/providers/localstorage.py
+++ b/src/langbot/pkg/storage/providers/localstorage.py
@@ -12,6 +12,23 @@ from .. import provider
 LOCAL_STORAGE_PATH = os.path.join('data', 'storage')


+def _safe_resolve(base: str, key: str) -> str:
+    """Resolve *key* under *base* and ensure the result stays inside *base*.
+
+    Raises ``ValueError`` if the resolved path escapes the storage root
+    (e.g. via absolute paths, ``..`` components, or symlinks).
+    """
+    # os.path.realpath resolves symlinks and normalises the path.
+    resolved = os.path.realpath(os.path.join(base, key))
+    canonical_base = os.path.realpath(base)
+    # The resolved path must be *strictly* inside the base directory (or equal
+    # to it only for directory operations).  We append os.sep so that a base of
+    # "/data/storage" does not match "/data/storage_evil".
+    if not (resolved == canonical_base or resolved.startswith(canonical_base + os.sep)):
+        raise ValueError(f'Path traversal detected: key {key!r} resolves outside storage root')
+    return resolved
+
+
 class LocalStorageProvider(provider.StorageProvider):
    def __init__(self, ap: app.Application):
        super().__init__(ap)
@@ -23,40 +40,47 @@ class LocalStorageProvider(provider.StorageProvider):
        key: str,
        value: bytes,
    ):
-        if not os.path.exists(os.path.join(LOCAL_STORAGE_PATH, os.path.dirname(key))):
-            os.makedirs(os.path.join(LOCAL_STORAGE_PATH, os.path.dirname(key)))
-        async with aiofiles.open(os.path.join(LOCAL_STORAGE_PATH, f'{key}'), 'wb') as f:
+        resolved = _safe_resolve(LOCAL_STORAGE_PATH, key)
+        parent = os.path.dirname(resolved)
+        if not os.path.exists(parent):
+            os.makedirs(parent)
+        async with aiofiles.open(resolved, 'wb') as f:
            await f.write(value)

    async def load(
        self,
        key: str,
    ) -> bytes:
-        async with aiofiles.open(os.path.join(LOCAL_STORAGE_PATH, f'{key}'), 'rb') as f:
+        resolved = _safe_resolve(LOCAL_STORAGE_PATH, key)
+        async with aiofiles.open(resolved, 'rb') as f:
            return await f.read()

    async def exists(
        self,
        key: str,
    ) -> bool:
-        return os.path.exists(os.path.join(LOCAL_STORAGE_PATH, f'{key}'))
+        resolved = _safe_resolve(LOCAL_STORAGE_PATH, key)
+        return os.path.exists(resolved)

    async def delete(
        self,
        key: str,
    ):
-        os.remove(os.path.join(LOCAL_STORAGE_PATH, f'{key}'))
+        resolved = _safe_resolve(LOCAL_STORAGE_PATH, key)
+        os.remove(resolved)

    async def size(
        self,
        key: str,
    ) -> int:
-        return os.path.getsize(os.path.join(LOCAL_STORAGE_PATH, f'{key}'))
+        resolved = _safe_resolve(LOCAL_STORAGE_PATH, key)
+        return os.path.getsize(resolved)

    async def delete_dir_recursive(
        self,
        dir_path: str,
    ):
+        resolved = _safe_resolve(LOCAL_STORAGE_PATH, dir_path)
        # 直接删除整个目录
-        if os.path.exists(os.path.join(LOCAL_STORAGE_PATH, dir_path)):
-            shutil.rmtree(os.path.join(LOCAL_STORAGE_PATH, dir_path))
+        if os.path.exists(resolved):
+            shutil.rmtree(resolved)
--- a/src/langbot/pkg/telemetry/telemetry.py
+++ b/src/langbot/pkg/telemetry/telemetry.py
@@ -13,12 +13,11 @@ class TelemetryManager:
        await telemetry.send({ ... })
    """

-    send_tasks: list[asyncio.Task] = []
-
    def __init__(self, ap: core_app.Application):
        self.ap = ap

        self.telemetry_config = {}
+        self.send_tasks: list[asyncio.Task] = []

    async def initialize(self):
        self.telemetry_config = self.ap.instance_config.data.get('space', {})
--- a/src/langbot/pkg/utils/funcschema.py
+++ b/src/langbot/pkg/utils/funcschema.py
@@ -83,7 +83,7 @@ def get_func_schema(function: typing.Callable) -> dict:

        parameters['properties'][param.name] = {
            'type': param_type,
-            'description': args_doc[param.name],
+            'description': args_doc.get(param.name, ''),
        }

        # add schema for array
--- a/src/langbot/pkg/utils/image.py
+++ b/src/langbot/pkg/utils/image.py
@@ -145,7 +145,8 @@ def get_qq_image_downloadable_url(image_url: str) -> tuple[str, dict]:
    """获取QQ图片的下载链接"""
    parsed = urlparse(image_url)
    query = parse_qs(parsed.query)
-    return f'http://{parsed.netloc}{parsed.path}', query
+    scheme = parsed.scheme or 'http'
+    return f'{scheme}://{parsed.netloc}{parsed.path}', query


 async def get_qq_image_bytes(image_url: str, query: dict = {}) -> tuple[bytes, str]:
--- a/src/langbot/pkg/utils/pkgmgr.py
+++ b/src/langbot/pkg/utils/pkgmgr.py
@@ -23,7 +23,10 @@ def run_pip(params: list):
    pipmain(params)


-def install_requirements(file, extra_params: list = []):
+def install_requirements(file, extra_params: list | None = None):
+    if extra_params is None:
+        extra_params = []
+
    pipmain(
        [
            'install',
--- a/src/langbot/pkg/utils/runner.py
+++ b/src/langbot/pkg/utils/runner.py
@@ -1,5 +1,7 @@
 from __future__ import annotations

+import ipaddress
+import re
 from urllib.parse import urlparse


@@ -44,6 +46,40 @@ LOCAL_PATTERNS = [
    '172.31.',
 ]

+HOST_LABEL_PATTERN = re.compile(r'^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$')
+
+
+def _is_valid_hostname(host: str) -> bool:
+    if host == 'localhost':
+        return True
+
+    try:
+        ipaddress.ip_address(host)
+        return True
+    except ValueError:
+        pass
+
+    if not host or len(host) > 253 or any(char.isspace() for char in host):
+        return False
+
+    host = host.rstrip('.')
+    if not host:
+        return False
+
+    return all(HOST_LABEL_PATTERN.match(label) for label in host.split('.'))
+
+
+def _is_local_host(host: str) -> bool:
+    if host == 'localhost':
+        return True
+
+    try:
+        ip_address = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+
+    return ip_address.is_private or ip_address.is_loopback or ip_address.is_unspecified
+

 def get_runner_category(runner_name: str, runner_url: str) -> str:
    if not runner_url:
@@ -52,12 +88,15 @@ def get_runner_category(runner_name: str, runner_url: str) -> str:
    try:
        parsed_url = urlparse(runner_url)
        host = parsed_url.hostname.lower() if parsed_url.hostname else ''
+        _ = parsed_url.port
    except Exception:
        return RunnerCategory.UNKNOWN

-    for pattern in LOCAL_PATTERNS:
-        if host.startswith(pattern):
-            return RunnerCategory.LOCAL
+    if not parsed_url.scheme or not host or not _is_valid_hostname(host):
+        return RunnerCategory.UNKNOWN
+
+    if _is_local_host(host):
+        return RunnerCategory.LOCAL

    for domain in CLOUD_DOMAINS:
        if host.endswith(domain):
--- a/src/langbot/templates/config.yaml
+++ b/src/langbot/templates/config.yaml
@@ -25,6 +25,9 @@ system:
        max_bots: -1
        max_pipelines: -1
        max_extensions: -1
+    task_retention:
+        # Keep at most this many completed async task records in memory
+        completed_limit: 200
    jwt:
        expire: 604800
        secret: ''
@@ -68,6 +71,15 @@ vdb:
        password: 'postgres'
 storage:
    use: local
+    cleanup:
+        # Enable periodic cleanup of local/S3 uploaded files and old log files
+        enabled: true
+        # Cleanup check interval in hours
+        check_interval_hours: 1
+        # Root-level uploaded files older than this will be deleted
+        uploaded_file_retention_days: 7
+        # LangBot log files older than this many days will be deleted
+        log_retention_days: 3
    s3:
        endpoint_url: ''
        access_key_id: ''
@@ -79,6 +91,9 @@ plugin:
    runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws'
    enable_marketplace: true
    display_plugin_debug_url: 'ws://localhost:5401/plugin/debug/ws'
+    binary_storage:
+        # Max bytes for a single plugin binary storage value
+        max_value_bytes: 10485760
 monitoring:
    auto_cleanup:
        # Enable automatic cleanup of expired monitoring records
@@ -87,6 +102,8 @@ monitoring:
        retention_days: 30
        # Cleanup check interval in hours
        check_interval_hours: 1
+        # Number of expired rows to delete per table batch
+        delete_batch_size: 1000
 space:
    # Space service URL for OAuth and API
    url: 'https://space.langbot.app'
--- a/src/langbot/templates/default-pipeline-config.json
+++ b/src/langbot/templates/default-pipeline-config.json
@@ -38,7 +38,8 @@
    },
    "ai": {
        "runner": {
-            "runner": "local-agent"
+            "runner": "local-agent",
+            "expire-time": 0
        },
        "local-agent": {
            "model": {
--- a/src/langbot/templates/embed/logo.webp
+++ b/src/langbot/templates/embed/logo.webp
--- a/src/langbot/templates/embed/widget.js
+++ b/src/langbot/templates/embed/widget.js
--- a/src/langbot/templates/metadata/pipeline/ai.yaml
+++ b/src/langbot/templates/metadata/pipeline/ai.yaml
@@ -47,6 +47,26 @@ stages:
            label:
              en_US: Langflow API
              zh_Hans: Langflow API
+      - name: expire-time
+        label:
+          en_US: Conversation expire time (seconds)
+          zh_Hans: 单个对话过期时间（秒）
+        description:
+          en_US: >-
+            Maximum idle time of a single conversation, measured from the last
+            message/preprocess update time. When a new message arrives and the
+            current conversation has been idle for longer than this value, the
+            existing external conversation id is discarded and a new one is
+            started automatically — the user does not need to trigger a reset
+            manually. Set to 0 to disable expiry (conversations live until the
+            user or another mechanism resets them).
+          zh_Hans: >-
+            单个对话的最长空闲时间，从最后一条消息/preprocess 更新时间开始计算。
+            当新消息到达且当前对话空闲时间已超过该值时，旧的外部对话 ID 会被自动丢弃并开启新对话，
+            用户无需手动重置。设置为 0 表示不限制过期时间（对话会一直保留，直到用户或其他机制主动重置）。
+        type: integer
+        required: true
+        default: 0
  - name: local-agent
    label:
      en_US: Local Agent
@@ -539,4 +559,4 @@ stages:
          zh_Hans: 可选的流程调整参数
        type: json
        required: false
-        default: '{}'
+        default: '{}'
--- a/src/langbot/templates/metadata/pipeline/safety.yaml
+++ b/src/langbot/templates/metadata/pipeline/safety.yaml
@@ -72,4 +72,4 @@ stages:
          - name: wait
            label:
              en_US: Wait
-              zh_Hans: 等待
+              zh_Hans: 等待
--- a/tests/README.md
+++ b/tests/README.md
@@ -2,6 +2,48 @@

 This directory contains the test suite for LangBot, with a focus on comprehensive unit testing of pipeline stages.

+## Quality Gate Layers
+
+LangBot uses a layered quality gate system for developers and CI:
+
+| Layer | Command | What it runs | When to use |
+|-------|---------|--------------|-------------|
+| **Quick** | `make test-quick` or `bash scripts/test-quick.sh` | Ruff lint + Unit tests + Smoke tests | Before every commit |
+| **Fast Integration** | `make test-integration-fast` or `bash scripts/test-integration-fast.sh` | SQLite/API/Pipeline integration (no external services) | Before PR, weekly |
+| **Coverage Gate** | `make test-coverage` or `bash scripts/test-coverage.sh` | All tests with coverage, threshold: 18% | Before merge, CI |
+| **Full Local** | `make test-all-local` | Quick + Integration + Coverage | Before major changes |
+
+**Note**: PostgreSQL migration tests and slow tests are NOT in local default gates. They run in separate CI workflows.
+
+### Developer Workflow
+
+```bash
+# Daily: Quick self-test
+bash scripts/test-quick.sh
+
+# Before PR: Full local gate
+make test-all-local
+
+# Or run each layer separately:
+bash scripts/test-quick.sh           # ~2 min
+bash scripts/test-integration-fast.sh # ~3 min
+bash scripts/test-coverage.sh         # ~8 min
+```
+
+### Coverage Baseline
+
+Current coverage threshold: **18%**
+Actual coverage: **30%**
+
+This is a conservative baseline to prevent coverage regression. It does NOT represent the final quality target. Key modules have higher coverage:
+- `pipeline.preproc.preproc`: 53%
+- `pipeline.process.process`: 96%
+- `pipeline.respback.respback`: 88%
+- `telemetry.telemetry`: 87%
+- `provider.session.sessionmgr`: 100%
+- `provider.tools.toolmgr`: 83%
+- `storage.providers.s3storage`: 80%
+
 ## Important Note

 Due to circular import dependencies in the pipeline module structure, the test files use **lazy imports** via `importlib.import_module()` instead of direct imports. This ensures tests can run without triggering circular import errors.
@@ -10,19 +52,81 @@ Due to circular import dependencies in the pipeline module structure, the test f

 ```
 tests/
-├── pipeline/                      # Pipeline stage tests
-│   ├── conftest.py               # Shared fixtures and test infrastructure
-│   ├── test_simple.py            # Basic infrastructure tests (always pass)
-│   ├── test_bansess.py           # BanSessionCheckStage tests
-│   ├── test_ratelimit.py         # RateLimit stage tests
-│   ├── test_preproc.py           # PreProcessor stage tests
-│   ├── test_respback.py          # SendResponseBackStage tests
-│   ├── test_resprule.py          # GroupRespondRuleCheckStage tests
-│   ├── test_pipelinemgr.py       # PipelineManager tests
-│   └── test_stages_integration.py # Integration tests
-└── README.md                      # This file
+├── __init__.py
+├── factories/                    # Shared test factories
+│   ├── __init__.py              # Factory exports
+│   ├── app.py                   # FakeApp factory
+│   ├── message.py               # Message/query factories
+│   ├── provider.py              # FakeProvider factory
+│   └── platform.py              # FakePlatform factory
+├── integration/                  # Integration tests (real resources)
+│   ├── __init__.py
+│   ├── api/                     # HTTP API tests
+│   │   ├── __init__.py
+│   │   └── test_smoke.py        # API smoke tests
+│   ├── pipeline/                # Pipeline stage-chain tests
+│   │   ├── __init__.py
+│   │   └── test_full_flow.py    # Full flow integration
+│   └── persistence/             # Database/persistence tests
+│       ├── __init__.py
+│       └── test_migrations.py   # Alembic migration tests
+├── smoke/                        # Smoke tests (quick validation)
+│   └── test_fake_message_flow.py
+├── unit_tests/                   # Unit tests
+│   ├── box/                      # Box module tests
+│   ├── config/                   # Configuration tests
+│   ├── pipeline/                 # Pipeline stage tests
+│   │   └── conftest.py          # Shared fixtures and test infrastructure
+│   ├── platform/                 # Platform adapter tests
+│   ├── plugin/                   # Plugin system tests
+│   │   └── test_handler_actions.py # Action handler tests
+│   ├── provider/                 # Provider tests
+│   │   ├── test_session_manager.py # SessionManager tests
+│   │   └── test_tool_manager.py    # ToolManager tests
+│   ├── rag/                      # RAG tests
+│   │   └── test_file_storage.py   # File/ZIP storage tests
+│   ├── storage/                  # Storage tests
+│   │   └── test_s3storage.py      # S3StorageProvider tests
+│   ├── vector/                   # Vector tests
+│   │   └── test_vdb_filter_conversion.py # VDB filter tests
+│   └── telemetry/                # Telemetry tests (rewritten)
+├── utils/                        # Test utilities
+│   ├── __init__.py
+│   └── import_isolation.py      # sys.modules isolation for circular imports
+└── README.md                     # This file
 ```

+## Test Factories
+
+The `tests/factories/` package provides reusable test factories:
+
+```python
+from tests.factories import (
+    FakeApp,          # Mock application
+    FakeProvider,     # Fake LLM provider
+    FakePlatform,     # Fake platform adapter
+    text_query,       # Create text query
+    group_text_query, # Create group query
+    command_query,    # Create command query
+)
+
+# Create fake app
+app = FakeApp()
+
+# Create query with text
+query = text_query("hello world")
+
+# Create fake provider that returns specific response
+provider = FakeProvider().returns("test response")
+
+# Create fake platform for outbound capture
+platform = FakePlatform()
+await platform.reply_message(query.message_event, reply_chain)
+outbound = platform.get_outbound_messages()
+```
+
+See `tests/factories/__init__.py` for all available factories.
+
 ## Test Architecture

 ### Fixtures (`conftest.py`)
@@ -43,7 +147,28 @@ The test suite uses a centralized fixture system that provides:

 ## Running Tests

-### Using the test runner script (recommended)
+### Quick self-test for developers
+
+For local branch validation without real provider keys:
+
+```bash
+make test-quick
+```
+
+or
+
+```bash
+bash scripts/test-quick.sh
+```
+
+This runs:
+1. Ruff lint check
+2. Unit tests
+3. Smoke tests
+
+Suitable for quick validation before committing.
+
+### Using the test runner script (recommended for full coverage)
 ```bash
 bash run_tests.sh
 ```
@@ -56,38 +181,135 @@ This script automatically:

 ### Manual test execution

-#### Run all tests
+#### Run all unit tests
 ```bash
-pytest tests/pipeline/
+uv run pytest tests/unit_tests/ --cov=langbot --cov-report=xml --cov-report=term
 ```

-#### Run only simple tests (no imports, always pass)
+#### Run specific test module
 ```bash
-pytest tests/pipeline/test_simple.py -v
+uv run pytest tests/unit_tests/pipeline/ -v
 ```

 #### Run specific test file
 ```bash
-pytest tests/pipeline/test_bansess.py -v
+uv run pytest tests/unit_tests/pipeline/test_bansess.py -v
 ```

 #### Run with coverage
 ```bash
-pytest tests/pipeline/ --cov=pkg/pipeline --cov-report=html
+uv run pytest tests/unit_tests/pipeline/ --cov=langbot --cov-report=html
 ```

 #### Run specific test
 ```bash
-pytest tests/pipeline/test_bansess.py::test_bansess_whitelist_allow -v
+uv run pytest tests/unit_tests/pipeline/test_bansess.py::test_bansess_whitelist_allow -v
 ```

+### Using markers
+
+```bash
+# Run only unit tests
+uv run pytest tests/unit_tests/ -m unit
+
+# Run only integration tests
+uv run pytest tests/integration/ -m integration
+
+# Run integration tests excluding slow ones
+uv run pytest tests/integration/ -m "not slow" -q
+
+# Skip slow tests
+uv run pytest tests/unit_tests/ -m "not slow"
+```
+
+### Running integration tests
+
+Integration tests validate real system behavior with actual database/network resources.
+
+```bash
+# Run all integration tests (excluding slow ones)
+uv run pytest tests/integration/ -m "not slow" -q
+
+# Run SQLite migration integration tests
+uv run pytest tests/integration/persistence/test_migrations.py -q --tb=short
+
+# Run API smoke integration tests
+uv run pytest tests/integration/api/test_smoke.py -q
+
+# Run pipeline full-flow integration tests
+uv run pytest tests/integration/pipeline/test_full_flow.py -q
+
+# Run with verbose output
+uv run pytest tests/integration/ -v
+```
+
+Note: Integration tests use:
+- Temporary databases (tmp_path) for persistence tests
+- Fake app/services for API tests (no real provider/platform)
+- Fake runner/provider for pipeline tests (no real LLM API)
+- Do not require external services
+
+### Running migration tests locally
+
+SQLite migration tests can be run locally without any external dependencies:
+
+```bash
+# SQLite migration tests (uses tmp_path, no external DB needed)
+uv run pytest tests/integration/persistence/test_migrations.py -q --tb=short
+```
+
+PostgreSQL migration tests require an external PostgreSQL database:
+
+```bash
+# PostgreSQL migration tests (requires PostgreSQL service)
+# Tests are marked as slow and skipped if TEST_POSTGRES_URL is not set
+TEST_POSTGRES_URL=postgresql+asyncpg://user:pass@localhost:5432/test_db \
+    uv run pytest tests/integration/persistence/test_migrations_postgres.py -q --tb=short
+
+# Or skip by default (no PostgreSQL available)
+uv run pytest tests/integration/persistence/test_migrations_postgres.py -q --tb=short
+# Output: SKIPPED (TEST_POSTGRES_URL not set)
+```
+
+Note: PostgreSQL tests are **not** included in fast integration gate because they:
+- Require external PostgreSQL service
+- Are marked with `@pytest.mark.slow`
+- Need `TEST_POSTGRES_URL` environment variable
+
+CI workflow `.github/workflows/test-migrations.yml` runs:
+- SQLite tests in `test-migrations-sqlite` job (fast, no external services)
+- PostgreSQL tests in `test-migrations-postgres` job (uses PostgreSQL service container)
+
+### Running pipeline integration tests locally
+
+Pipeline full-flow integration tests validate real stage interactions:
+
+```bash
+# Run pipeline integration tests (uses fake runner, no real LLM API)
+uv run pytest tests/integration/pipeline/test_full_flow.py -q --tb=short
+
+# Run with coverage for pipeline modules
+uv run pytest tests/integration/pipeline \
+    --cov=langbot.pkg.pipeline.preproc.preproc \
+    --cov=langbot.pkg.pipeline.process.process \
+    --cov=langbot.pkg.pipeline.respback.respback \
+    --cov-report=term -q
+```
+
+These tests:
+- Use `FakeRunner` class to simulate LLM responses without real API calls
+- Import real `PreProcessor`, `MessageProcessor`, `SendResponseBackStage` stages
+- Validate stage chain: PreProcessor → Processor → SendResponseBackStage
+- Test prevent_default, exception handling, and full message flow
+- Do not require real LLM provider keys
+
 ### Known Issues

 Some tests may encounter circular import errors. This is a known issue with the current module structure. The test infrastructure is designed to work around this using lazy imports, but if you encounter issues:

 1. Make sure you're running from the project root directory
-2. Ensure the virtual environment is activated
-3. Try running `test_simple.py` first to verify the test infrastructure works
+2. Ensure dependencies are installed: `uv sync --dev`
+3. Try running a simple test first to verify the test infrastructure works

 ## CI/CD Integration

@@ -97,7 +319,7 @@ Tests are automatically run on:
 - Push to PR branch
 - Push to master/develop branches

-The workflow runs tests on Python 3.10, 3.11, and 3.12 to ensure compatibility.
+The workflow runs tests on Python 3.11, 3.12, and 3.13 to ensure compatibility.

 ## Adding New Tests

@@ -111,8 +333,8 @@ Create a new test file `test_<stage_name>.py`:
 """

 import pytest
-from pkg.pipeline.<module>.<stage> import <StageClass>
-from pkg.pipeline import entities as pipeline_entities
+from langbot.pkg.pipeline.<module>.<stage> import <StageClass>
+from langbot.pkg.pipeline import entities as pipeline_entities


@pytest.mark.asyncio
@@ -128,7 +350,7 @@ async def test_stage_basic_flow(mock_app, sample_query):

 ### 2. For additional fixtures

-Add new fixtures to `conftest.py`:
+Add new fixtures to the appropriate `conftest.py`:

 ```python
@pytest.fixture
@@ -142,7 +364,7 @@ def my_custom_fixture():
 Use the helper functions in `conftest.py`:

 ```python
-from tests.pipeline.conftest import create_stage_result, assert_result_continue
+from tests.unit_tests.pipeline.conftest import create_stage_result, assert_result_continue

 result = create_stage_result(
    result_type=pipeline_entities.ResultType.CONTINUE,
@@ -166,7 +388,7 @@ assert_result_continue(result)
 ### Import errors
 Make sure you've installed the package in development mode:
 ```bash
-uv pip install -e .
+uv sync --dev
 ```

 ### Async test failures
@@ -177,7 +399,11 @@ Check that you're mocking at the right level and using `AsyncMock` for async fun

 ## Future Enhancements

- [ ] Add integration tests for full pipeline execution
+- [x] Add integration tests for database migrations (SQLite)
+- [x] Add PostgreSQL migration integration tests (G-003)
+- [x] Add integration tests for full pipeline execution
+- [x] Add API smoke integration tests
+- [ ] Add E2E tests
 - [ ] Add performance benchmarks
 - [ ] Add mutation testing for better coverage quality
- [ ] Add property-based testing with Hypothesis
+- [ ] Add property-based testing with Hypothesis
--- a/tests/e2e/conftest.py
+++ b/tests/e2e/conftest.py
@@ -0,0 +1,102 @@
+"""E2E test fixtures.
+
+Provides fixtures for starting real LangBot process with minimal configuration.
+"""
+
+from __future__ import annotations
+
+import pytest
+import tempfile
+import shutil
+import logging
+from pathlib import Path
+
+from tests.e2e.utils.config_factory import create_minimal_config, create_test_directories
+from tests.e2e.utils.process_manager import LangBotProcess, find_project_root
+
+logger = logging.getLogger(__name__)
+
+pytestmark = pytest.mark.e2e
+
+
+@pytest.fixture(scope='session')
+def e2e_port():
+    """Port for E2E testing (non-default to avoid conflicts)."""
+    return 15300
+
+
+@pytest.fixture(scope='session')
+def e2e_tmpdir():
+    """Create temporary directory for E2E testing."""
+    tmpdir = Path(tempfile.mkdtemp(prefix='langbot_e2e_'))
+    logger.info(f'E2E tmpdir: {tmpdir}')
+
+    yield tmpdir
+
+    # Cleanup
+    logger.info(f'Cleaning up E2E tmpdir: {tmpdir}')
+    shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+@pytest.fixture(scope='session')
+def e2e_config_path(e2e_tmpdir, e2e_port):
+    """Create minimal config.yaml for E2E testing."""
+    config_path = create_minimal_config(e2e_tmpdir, port=e2e_port)
+    create_test_directories(e2e_tmpdir)
+    logger.info(f'E2E config: {config_path}')
+    return config_path
+
+
+@pytest.fixture(scope='session')
+def langbot_process(e2e_config_path, e2e_port, e2e_tmpdir):
+    """Start real LangBot process for E2E testing.
+
+    This fixture starts LangBot once per session and reuses it for all tests.
+    Coverage data is collected from the subprocess.
+    """
+    project_root = find_project_root()
+    collect_coverage = True
+
+    proc = LangBotProcess(
+        project_root=project_root,
+        work_dir=e2e_tmpdir,  # Run in tmpdir where data/config.yaml exists
+        port=e2e_port,
+        timeout=60,  # Longer timeout for first startup
+        collect_coverage=collect_coverage,
+    )
+
+    success = proc.start()
+    if not success:
+        stdout, stderr = proc.get_logs()
+        pytest.fail(f'LangBot failed to start:\nstdout: {stdout}\nstderr: {stderr}')
+
+    yield proc
+
+    # Cleanup
+    proc.stop()
+
+    # Combine coverage data if collected
+    if collect_coverage and proc.get_coverage_file():
+        coverage_file = proc.get_coverage_file()
+        if coverage_file.exists():
+            # Copy coverage data to project root for combining
+            target = project_root / '.coverage.e2e'
+            shutil.copy(coverage_file, target)
+            logger.info(f'Coverage data saved to: {target}')
+
+
+@pytest.fixture
+def e2e_client(e2e_port, langbot_process):
+    """HTTP client for E2E testing."""
+    import httpx
+
+    base_url = f'http://127.0.0.1:{e2e_port}'
+
+    with httpx.Client(base_url=base_url, timeout=10.0) as client:
+        yield client
+
+
+@pytest.fixture(scope='session')
+def e2e_db_path(e2e_tmpdir):
+    """Path to SQLite database file."""
+    return e2e_tmpdir / 'data' / 'langbot.db'
--- a/tests/e2e/test_startup.py
+++ b/tests/e2e/test_startup.py
@@ -0,0 +1,142 @@
+"""E2E tests for LangBot startup flow.
+
+Tests the complete startup process including:
+- boot.py startup orchestration
+- stages/ (build_app, load_config, migrate, etc.)
+- database initialization
+- API availability
+
+Run: uv run pytest tests/e2e/test_startup.py -v -m e2e
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.e2e
+
+
+class TestStartupFlow:
+    """Tests for LangBot startup process."""
+
+    def test_process_is_running(self, langbot_process):
+        """Verify LangBot process is running."""
+        assert langbot_process.is_running()
+
+    def test_health_check(self, langbot_process, e2e_port):
+        """Verify LangBot API is responding."""
+        assert langbot_process.health_check()
+
+    def test_system_info_endpoint(self, e2e_client):
+        """Test /api/v1/system/info endpoint."""
+        response = e2e_client.get('/api/v1/system/info')
+        assert response.status_code == 200
+
+        data = response.json()
+        assert data['code'] == 0
+        assert 'data' in data
+        # System info should contain version info
+        assert 'version' in data['data'] or 'edition' in data['data']
+
+    def test_database_initialized(self, e2e_db_path):
+        """Verify SQLite database was created and initialized."""
+        assert e2e_db_path.exists()
+
+        # Database should have some tables after migration
+        import sqlite3
+        conn = sqlite3.connect(str(e2e_db_path))
+        cursor = conn.cursor()
+
+        # Check that core tables exist
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
+        tables = [row[0] for row in cursor.fetchall()]
+
+        # Core tables should be created by Alembic migrations
+        # Note: table names may differ (legacy_pipelines instead of pipelines)
+        expected_tables = ['legacy_pipelines', 'bots', 'model_providers', 'llm_models']
+        for table in expected_tables:
+            assert table in tables, f'Table {table} should exist. Available: {tables}'
+
+        conn.close()
+
+    def test_chroma_directory_created(self, e2e_tmpdir):
+        """Verify Chroma vector database directory was created."""
+        chroma_path = e2e_tmpdir / 'chroma'
+        # Created by the E2E config factory before startup.
+        assert chroma_path.exists()
+
+    def test_pipelines_endpoint(self, e2e_client):
+        """Test /api/v1/pipelines endpoint (requires auth)."""
+        # Without auth, should return 401
+        response = e2e_client.get('/api/v1/pipelines')
+        assert response.status_code == 401
+
+    def test_auth_endpoint(self, e2e_client, e2e_tmpdir):
+        """Test auth endpoint."""
+        # First startup may allow initial setup
+        response = e2e_client.post('/api/v1/user/auth', json={
+            'username': 'admin',
+            'password': 'admin',
+        })
+
+        # Response could be:
+        # - 200 if auth succeeds
+        # - 400 if credentials wrong
+        # - 401 if user not initialized
+        assert response.status_code in [200, 400, 401]
+
+
+class TestStartupStages:
+    """Tests that verify individual startup stages worked correctly."""
+
+    def test_config_loaded(self, e2e_client):
+        """Verify config was loaded correctly by checking API port."""
+        # If API responds on e2e_port, config was loaded
+        assert e2e_client.get('/api/v1/system/info').status_code == 200
+
+    def test_migrations_applied(self, e2e_db_path):
+        """Verify database migrations were applied."""
+        import sqlite3
+        conn = sqlite3.connect(str(e2e_db_path))
+        cursor = conn.cursor()
+
+        # Check alembic_version table exists and has version
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version';")
+        result = cursor.fetchone()
+        assert result is not None, 'alembic_version table should exist'
+
+        cursor.execute('SELECT version_num FROM alembic_version;')
+        version = cursor.fetchone()
+        assert version is not None, 'Migration version should be set'
+
+        conn.close()
+
+    def test_http_controller_initialized(self, e2e_client):
+        """Verify HTTP controller was initialized."""
+        # Multiple endpoints should be available
+        endpoints = [
+            '/api/v1/system/info',
+            '/api/v1/pipelines',
+            '/api/v1/provider/providers',
+            '/api/v1/platform/bots',
+        ]
+
+        for endpoint in endpoints:
+            response = e2e_client.get(endpoint)
+            # Should get a real route response, even if auth is required.
+            assert response.status_code in [200, 401, 403], f'{endpoint} should be registered'
+
+
+class TestMinimalStartupNoLLM:
+    """Tests verifying LangBot can start without LLM providers."""
+
+    def test_api_available_without_llm(self, e2e_client):
+        """API should be available even without LLM providers configured."""
+        response = e2e_client.get('/api/v1/system/info')
+        assert response.status_code == 200
+
+    def test_pipeline_metadata_available(self, e2e_client):
+        """Pipeline metadata endpoint should work without LLM."""
+        # Requires auth, but endpoint should exist
+        response = e2e_client.get('/api/v1/pipelines/_/metadata')
+        assert response.status_code in [200, 401]  # Not 404 or 500
--- a/tests/e2e/utils/config_factory.py
+++ b/tests/e2e/utils/config_factory.py
@@ -0,0 +1,179 @@
+"""E2E test configuration factory.
+
+Generates minimal config.yaml for testing LangBot startup without external dependencies.
+"""
+
+from __future__ import annotations
+
+import yaml
+from pathlib import Path
+
+
+def create_minimal_config(tmpdir: Path, port: int = 15300) -> Path:
+    """Create minimal config.yaml for E2E testing.
+
+    Uses embedded databases (SQLite, Chroma) to avoid external dependencies.
+    Config is created at tmpdir/data/config.yaml (LangBot expects this location).
+    """
+    # LangBot expects config at data/config.yaml
+    data_dir = tmpdir / 'data'
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    config = {
+        'admins': [],
+        'api': {
+            'port': port,
+            'webhook_prefix': f'http://127.0.0.1:{port}',
+            'extra_webhook_prefix': '',
+        },
+        'command': {
+            'enable': True,
+            'prefix': ['!', '!'],
+            'privilege': {},
+        },
+        'concurrency': {
+            'pipeline': 20,
+            'session': 1,
+        },
+        'proxy': {
+            'http': '',
+            'https': '',
+        },
+        'system': {
+            'instance_id': '',
+            'edition': 'community',
+            'recovery_key': '',
+            'allow_modify_login_info': True,
+            'disabled_adapters': [],
+            'limitation': {
+                'max_bots': -1,
+                'max_pipelines': -1,
+                'max_extensions': -1,
+            },
+            'task_retention': {
+                'completed_limit': 200,
+            },
+            'jwt': {
+                'expire': 604800,
+                'secret': 'e2e-test-secret-key',
+            },
+        },
+        'database': {
+            'use': 'sqlite',
+            'sqlite': {
+                'path': str(tmpdir / 'data' / 'langbot.db'),
+            },
+            'postgresql': {
+                'host': '127.0.0.1',
+                'port': 5432,
+                'user': 'postgres',
+                'password': 'postgres',
+                'database': 'postgres',
+            },
+        },
+        'vdb': {
+            'use': 'chroma',  # Chroma is embedded, no external dependency
+            'chroma': {
+                'path': str(tmpdir / 'chroma'),
+            },
+            'qdrant': {
+                'url': '',
+                'host': 'localhost',
+                'port': 6333,
+                'api_key': '',
+            },
+            'seekdb': {
+                'mode': 'embedded',
+                'path': str(tmpdir / 'seekdb'),
+                'database': 'langbot',
+                'host': 'localhost',
+                'port': 2881,
+                'user': 'root',
+                'password': '',
+                'tenant': '',
+            },
+            'milvus': {
+                'uri': 'http://127.0.0.1:19530',
+                'token': '',
+                'db_name': '',
+            },
+            'pgvector': {
+                'host': '127.0.0.1',
+                'port': 5433,
+                'database': 'langbot',
+                'user': 'postgres',
+                'password': 'postgres',
+            },
+        },
+        'storage': {
+            'use': 'local',
+            'cleanup': {
+                'enabled': False,  # Disable cleanup for tests
+                'check_interval_hours': 1,
+                'uploaded_file_retention_days': 7,
+                'log_retention_days': 3,
+            },
+            'local': {
+                'path': str(tmpdir / 'storage'),
+            },
+            's3': {
+                'endpoint_url': '',
+                'access_key_id': '',
+                'secret_access_key': '',
+                'region': 'us-east-1',
+                'bucket': 'langbot-storage',
+            },
+        },
+        'plugin': {
+            'enable': False,  # Disable plugin system for minimal startup
+            'runtime_ws_url': '',
+            'enable_marketplace': False,
+            'display_plugin_debug_url': '',
+            'binary_storage': {
+                'max_value_bytes': 10485760,
+            },
+        },
+        'monitoring': {
+            'auto_cleanup': {
+                'enabled': False,  # Disable cleanup for tests
+                'retention_days': 30,
+                'check_interval_hours': 1,
+                'delete_batch_size': 1000,
+            },
+        },
+        'space': {
+            'url': 'https://space.langbot.app',
+            'models_gateway_api_url': 'https://api.langbot.cloud/v1',
+            'oauth_authorize_url': 'https://space.langbot.app/auth/authorize',
+            'disable_models_service': True,  # Disable external services
+            'disable_telemetry': True,  # Disable telemetry for tests
+        },
+        'provider': {},  # Empty providers - minimal startup
+        'llm': [],  # Empty LLM models
+    }
+
+    # Ensure data directory exists (LangBot expects config at data/config.yaml)
+    data_dir = tmpdir / 'data'
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write config to data/config.yaml (LangBot's expected location)
+    config_path = data_dir / 'config.yaml'
+    with open(config_path, 'w', encoding='utf-8') as f:
+        yaml.dump(config, f, default_flow_style=False)
+
+    return config_path
+
+
+def create_test_directories(tmpdir: Path) -> dict[str, Path]:
+    """Create necessary directories for LangBot testing."""
+    directories = {
+        'data': tmpdir / 'data',
+        'logs': tmpdir / 'logs',
+        'storage': tmpdir / 'storage',
+        'chroma': tmpdir / 'chroma',
+    }
+
+    for path in directories.values():
+        path.mkdir(parents=True, exist_ok=True)
+
+    return directories
--- a/tests/e2e/utils/process_manager.py
+++ b/tests/e2e/utils/process_manager.py
@@ -0,0 +1,204 @@
+"""E2E test process manager.
+
+Manages LangBot subprocess lifecycle for E2E testing.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+import signal
+import os
+from pathlib import Path
+from typing import Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class LangBotProcess:
+    """Manages a LangBot subprocess for E2E testing."""
+
+    def __init__(
+        self,
+        project_root: Path,
+        work_dir: Path,
+        port: int = 15300,
+        timeout: int = 30,
+        collect_coverage: bool = True,
+    ):
+        self.project_root = project_root
+        self.work_dir = work_dir  # Directory containing data/config.yaml
+        self.port = port
+        self.timeout = timeout
+        self.collect_coverage = collect_coverage
+        self.process: Optional[subprocess.Popen] = None
+        self._stdout_data: bytes = b''
+        self._stderr_data: bytes = b''
+        self._coverage_file: Optional[Path] = None
+
+    def start(self) -> bool:
+        """Start LangBot process and wait for it to be ready."""
+        import httpx
+
+        # Prepare environment
+        env = os.environ.copy()
+        env['PYTHONPATH'] = str(self.project_root / 'src')
+
+        # Set API port via environment variable
+        env['API__PORT'] = str(self.port)
+        env['API__WEBHOOK_PREFIX'] = f'http://127.0.0.1:{self.port}'
+
+        # Disable telemetry
+        env['SPACE__DISABLE_TELEMETRY'] = 'true'
+        env['SPACE__DISABLE_MODELS_SERVICE'] = 'true'
+
+        # Build command
+        if self.collect_coverage:
+            # Use coverage.py to collect coverage data
+            # Set COVERAGE_PROCESS_START to enable coverage in subprocess
+            self._coverage_file = self.work_dir / '.coverage.e2e'
+            env['COVERAGE_PROCESS_START'] = str(self.project_root / '.coveragerc')
+            env['COVERAGE_FILE'] = str(self._coverage_file)
+
+            # Create .coveragerc for subprocess
+            coveragerc_content = """
+[run]
+source = langbot.pkg
+parallel = True
+data_file = {}
+omit =
+    */tests/*
+    */test_*.py
+
+[report]
+precision = 2
+""".format(str(self._coverage_file))
+            coveragerc_path = self.work_dir / '.coveragerc'
+            with open(coveragerc_path, 'w') as f:
+                f.write(coveragerc_content)
+
+            cmd = [
+                'coverage', 'run',
+                '--rcfile=' + str(coveragerc_path),
+                '-m', 'langbot',
+            ]
+        else:
+            cmd = ['uv', 'run', 'python', '-m', 'langbot']
+
+        logger.info(f'Starting LangBot in: {self.work_dir}')
+        logger.info(f'Command: {cmd}')
+
+        # Start process (run in work_dir so it finds data/config.yaml)
+        self.process = subprocess.Popen(
+            cmd,
+            cwd=self.work_dir,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            preexec_fn=os.setsid if os.name != 'nt' else None,
+        )
+
+        # Wait for startup
+        start_time = time.time()
+        while time.time() - start_time < self.timeout:
+            # Check if process died
+            if self.process.poll() is not None:
+                self._stdout_data, self._stderr_data = self.process.communicate()
+                logger.error(f'LangBot process died: {self._stderr_data.decode()}')
+                return False
+
+            # Try to connect
+            try:
+                r = httpx.get(
+                    f'http://127.0.0.1:{self.port}/api/v1/system/info',
+                    timeout=2.0,
+                )
+                if r.status_code == 200:
+                    logger.info(f'LangBot started successfully on port {self.port}')
+                    return True
+            except (httpx.ConnectError, httpx.TimeoutException):
+                pass
+
+            time.sleep(1)
+
+        # Timeout
+        logger.error(f'LangBot startup timeout after {self.timeout}s')
+        self.stop()
+        return False
+
+    def stop(self) -> None:
+        """Stop LangBot process gracefully."""
+        if self.process is None:
+            return
+
+        logger.info('Stopping LangBot process...')
+
+        # Try graceful shutdown first
+        if os.name != 'nt':
+            # Send SIGTERM to process group
+            os.killpg(os.getpgid(self.process.pid), signal.SIGTERM)
+        else:
+            self.process.terminate()
+
+        # Wait for graceful shutdown
+        try:
+            self.process.wait(timeout=5)
+            logger.info('LangBot stopped gracefully')
+        except subprocess.TimeoutExpired:
+            # Force kill
+            logger.warning('Force killing LangBot process')
+            if os.name != 'nt':
+                os.killpg(os.getpgid(self.process.pid), signal.SIGKILL)
+            else:
+                self.process.kill()
+            self.process.wait()
+
+        # Collect output for debugging
+        if self.process.stdout or self.process.stderr:
+            self._stdout_data, self._stderr_data = self.process.communicate()
+
+        self.process = None
+
+    def is_running(self) -> bool:
+        """Check if process is still running."""
+        return self.process is not None and self.process.poll() is None
+
+    def get_logs(self) -> tuple[str, str]:
+        """Get stdout and stderr logs."""
+        stdout = self._stdout_data.decode('utf-8', errors='replace')
+        stderr = self._stderr_data.decode('utf-8', errors='replace')
+        return stdout, stderr
+
+    def get_coverage_file(self) -> Optional[Path]:
+        """Get coverage data file path."""
+        return self._coverage_file
+
+    def health_check(self) -> bool:
+        """Check if LangBot API is responding."""
+        import httpx
+
+        if not self.is_running():
+            return False
+
+        try:
+            r = httpx.get(
+                f'http://127.0.0.1:{self.port}/api/v1/system/info',
+                timeout=5.0,
+            )
+            return r.status_code == 200
+        except Exception:
+            return False
+
+
+def find_project_root() -> Path:
+    """Find LangBot project root directory."""
+    current = Path(__file__).resolve()
+
+    # Walk up until we find src/langbot
+    for parent in current.parents:
+        if (parent / 'src' / 'langbot').exists():
+            return parent
+
+    # Fallback to LangBot-test-build directory
+    return Path('/home/glwuy/langbot-app/LangBot-test-build')
--- a/tests/factories/init.py
+++ b/tests/factories/init.py
@@ -0,0 +1,102 @@
+"""
+Shared test factories for LangBot tests.
+
+Provides reusable factories for:
+- Fake application (app.py)
+- Messages and queries (message.py)
+- Fake providers (provider.py)
+- Fake platforms (platform.py)
+
+Usage:
+    from tests.factories import FakeApp, text_query, FakeProvider
+
+    app = FakeApp()
+    query = text_query("hello")
+    provider = FakeProvider.returns("response")
+"""
+
+from tests.factories.app import FakeApp, fake_app
+from tests.factories.message import (
+    text_chain,
+    group_text_chain,
+    mention_chain,
+    image_chain,
+    text_query,
+    group_text_query,
+    private_text_query,
+    command_query,
+    mention_query,
+    empty_query,
+    image_query,
+    file_query,
+    unsupported_query,
+    voice_query,
+    at_all_query,
+    query_with_session,
+    query_with_config,
+    friend_message_event,
+    group_message_event,
+    mock_adapter,
+)
+from tests.factories.provider import (
+    FakeProvider,
+    fake_provider,
+    fake_provider_pong,
+    fake_provider_timeout,
+    fake_provider_auth_error,
+    fake_provider_rate_limit,
+    fake_provider_malformed,
+    fake_model,
+)
+from tests.factories.platform import (
+    FakePlatform,
+    fake_platform,
+    fake_platform_with_streaming,
+    fake_platform_with_failure,
+    mock_platform_adapter,
+)
+
+__all__ = [
+    # App
+    "FakeApp",
+    "fake_app",
+    # Message chains
+    "text_chain",
+    "group_text_chain",
+    "mention_chain",
+    "image_chain",
+    # Message events
+    "friend_message_event",
+    "group_message_event",
+    # Mock adapters
+    "mock_adapter",
+    # Queries
+    "text_query",
+    "group_text_query",
+    "private_text_query",
+    "command_query",
+    "mention_query",
+    "empty_query",
+    "image_query",
+    "file_query",
+    "unsupported_query",
+    "voice_query",
+    "at_all_query",
+    "query_with_session",
+    "query_with_config",
+    # Provider
+    "FakeProvider",
+    "fake_provider",
+    "fake_provider_pong",
+    "fake_provider_timeout",
+    "fake_provider_auth_error",
+    "fake_provider_rate_limit",
+    "fake_provider_malformed",
+    "fake_model",
+    # Platform
+    "FakePlatform",
+    "fake_platform",
+    "fake_platform_with_streaming",
+    "fake_platform_with_failure",
+    "mock_platform_adapter",
+]
--- a/tests/factories/app.py
+++ b/tests/factories/app.py
@@ -0,0 +1,137 @@
+"""
+Fake application factory for tests.
+
+Provides a mock Application object with all dependencies needed by pipeline stages.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, Mock
+
+
+class FakeApp:
+    """Mock Application object providing all basic dependencies needed by stages."""
+
+    def __init__(
+        self,
+        *,
+        command_prefix: list[str] = ["/", "!"],
+        command_enable: bool = True,
+        pipeline_concurrency: int = 10,
+        admins: list[str] | None = None,
+        **extra_attrs,
+    ):
+        self.logger = self._create_mock_logger()
+        self.sess_mgr = self._create_mock_session_manager()
+        self.model_mgr = self._create_mock_model_manager()
+        self.tool_mgr = self._create_mock_tool_manager()
+        self.plugin_connector = self._create_mock_plugin_connector()
+        self.persistence_mgr = self._create_mock_persistence_manager()
+        self.query_pool = self._create_mock_query_pool()
+        self.instance_config = self._create_mock_instance_config(
+            command_prefix=command_prefix,
+            command_enable=command_enable,
+            pipeline_concurrency=pipeline_concurrency,
+            admins=admins or [],
+        )
+        self.task_mgr = self._create_mock_task_manager()
+
+        # Handler-specific optional attributes
+        self.telemetry = self._create_mock_telemetry()
+        self.survey = None
+        self.cmd_mgr = self._create_mock_cmd_mgr()
+
+        # Apply any extra attributes for specific test scenarios
+        for name, value in extra_attrs.items():
+            setattr(self, name, value)
+
+        # Captured outbound messages (for assertions)
+        self._outbound_messages: list = []
+
+    def _create_mock_logger(self):
+        logger = Mock()
+        logger.debug = Mock()
+        logger.info = Mock()
+        logger.error = Mock()
+        logger.warning = Mock()
+        return logger
+
+    def _create_mock_session_manager(self):
+        sess_mgr = AsyncMock()
+        sess_mgr.get_session = AsyncMock()
+        sess_mgr.get_conversation = AsyncMock()
+        return sess_mgr
+
+    def _create_mock_model_manager(self):
+        model_mgr = AsyncMock()
+        model_mgr.get_model_by_uuid = AsyncMock()
+        return model_mgr
+
+    def _create_mock_tool_manager(self):
+        tool_mgr = AsyncMock()
+        tool_mgr.get_all_tools = AsyncMock(return_value=[])
+        return tool_mgr
+
+    def _create_mock_plugin_connector(self):
+        plugin_connector = AsyncMock()
+        plugin_connector.emit_event = AsyncMock()
+        return plugin_connector
+
+    def _create_mock_persistence_manager(self):
+        persistence_mgr = AsyncMock()
+        persistence_mgr.execute_async = AsyncMock()
+        return persistence_mgr
+
+    def _create_mock_query_pool(self):
+        query_pool = Mock()
+        query_pool.cached_queries = {}
+        query_pool.queries = []
+        query_pool.condition = AsyncMock()
+        return query_pool
+
+    def _create_mock_instance_config(
+        self,
+        command_prefix: list[str],
+        command_enable: bool,
+        pipeline_concurrency: int,
+        admins: list[str],
+    ):
+        instance_config = Mock()
+        instance_config.data = {
+            "command": {"prefix": command_prefix, "enable": command_enable},
+            "concurrency": {"pipeline": pipeline_concurrency},
+            "admins": admins,
+        }
+        return instance_config
+
+    def _create_mock_task_manager(self):
+        task_mgr = Mock()
+        task_mgr.create_task = Mock()
+        return task_mgr
+
+    def _create_mock_telemetry(self):
+        telemetry = AsyncMock()
+        telemetry.start_send_task = AsyncMock()
+        return telemetry
+
+    def _create_mock_cmd_mgr(self):
+        cmd_mgr = AsyncMock()
+        cmd_mgr.execute = AsyncMock()
+        return cmd_mgr
+
+    def capture_message(self, message):
+        """Capture an outbound message for test assertions."""
+        self._outbound_messages.append(message)
+
+    def get_outbound_messages(self) -> list:
+        """Get all captured outbound messages."""
+        return self._outbound_messages.copy()
+
+    def clear_outbound_messages(self):
+        """Clear captured outbound messages."""
+        self._outbound_messages.clear()
+
+
+def fake_app(**kwargs) -> FakeApp:
+    """Create a FakeApp instance with optional overrides."""
+    return FakeApp(**kwargs)
--- a/tests/factories/message.py
+++ b/tests/factories/message.py
@@ -0,0 +1,472 @@
+"""
+Message and query factories for tests.
+
+Provides reusable factories for creating message chains, events, and query objects.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, Mock
+import typing
+
+import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+import langbot_plugin.api.entities.builtin.provider.session as provider_session
+
+
+# Counter for generating unique IDs
+_query_counter = 0
+
+
+def _next_query_id() -> int:
+    """Generate a unique query ID."""
+    global _query_counter
+    _query_counter += 1
+    return _query_counter
+
+
+# ============== Message Chain Factories ==============
+
+
+def text_chain(text: str = "hello") -> platform_message.MessageChain:
+    """Create a simple text message chain."""
+    return platform_message.MessageChain([
+        platform_message.Plain(text=text),
+    ])
+
+
+def group_text_chain(text: str = "hello") -> platform_message.MessageChain:
+    """Create a group text message chain (same as text_chain, context provided by event)."""
+    return text_chain(text)
+
+
+def mention_chain(
+    text: str = "hello",
+    target: typing.Union[int, str] = 12345,
+) -> platform_message.MessageChain:
+    """Create a message chain with @mention."""
+    return platform_message.MessageChain([
+        platform_message.At(target=target),
+        platform_message.Plain(text=f" {text}"),
+    ])
+
+
+def image_chain(
+    text: str = "",
+    url: str = "https://example.com/image.png",
+) -> platform_message.MessageChain:
+    """Create a message chain with an image."""
+    components = []
+    if text:
+        components.append(platform_message.Plain(text=text))
+    components.append(platform_message.Image(url=url))
+    return platform_message.MessageChain(components)
+
+
+def command_chain(
+    command: str = "help",
+    prefix: str = "/",
+) -> platform_message.MessageChain:
+    """Create a command message chain."""
+    return platform_message.MessageChain([
+        platform_message.Plain(text=f"{prefix}{command}"),
+    ])
+
+
+# ============== Message Event Factories ==============
+
+
+def friend_message_event(
+    message_chain: platform_message.MessageChain,
+    sender_id: typing.Union[int, str] = 12345,
+    nickname: str = "TestUser",
+) -> platform_events.FriendMessage:
+    """Create a friend (private) message event."""
+    sender = platform_entities.Friend(
+        id=sender_id,
+        nickname=nickname,
+        remark=None,
+    )
+    return platform_events.FriendMessage(
+        type="FriendMessage",
+        sender=sender,
+        message_chain=message_chain,
+        time=1609459200,
+    )
+
+
+def group_message_event(
+    message_chain: platform_message.MessageChain,
+    sender_id: typing.Union[int, str] = 12345,
+    sender_name: str = "TestUser",
+    group_id: typing.Union[int, str] = 99999,
+    group_name: str = "TestGroup",
+) -> platform_events.GroupMessage:
+    """Create a group message event."""
+    group = platform_entities.Group(
+        id=group_id,
+        name=group_name,
+        permission=platform_entities.Permission.Member,
+    )
+    sender = platform_entities.GroupMember(
+        id=sender_id,
+        member_name=sender_name,
+        permission=platform_entities.Permission.Member,
+        group=group,
+    )
+    return platform_events.GroupMessage(
+        type="GroupMessage",
+        sender=sender,
+        message_chain=message_chain,
+        time=1609459200,
+    )
+
+
+# ============== Mock Adapter Factory ==============
+
+
+def mock_adapter() -> Mock:
+    """Create a mock platform adapter."""
+    adapter = AsyncMock()
+    adapter.is_stream_output_supported = AsyncMock(return_value=False)
+    adapter.reply_message = AsyncMock()
+    adapter.reply_message_chunk = AsyncMock()
+    return adapter
+
+
+# ============== Query Factories ==============
+
+
+def _base_query(
+    message_chain: platform_message.MessageChain,
+    message_event: platform_events.MessageEvent,
+    launcher_type: provider_session.LauncherTypes,
+    launcher_id: typing.Union[int, str],
+    sender_id: typing.Union[int, str],
+    adapter: Mock,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a base query with model_construct to bypass validation."""
+    query_id = _next_query_id()
+
+    base_data = {
+        "query_id": query_id,
+        "launcher_type": launcher_type,
+        "launcher_id": launcher_id,
+        "sender_id": sender_id,
+        "message_chain": message_chain,
+        "message_event": message_event,
+        "adapter": adapter,
+        "pipeline_uuid": "test-pipeline-uuid",
+        "bot_uuid": "test-bot-uuid",
+        "pipeline_config": {
+            "ai": {
+                "runner": {"runner": "local-agent"},
+                "local-agent": {
+                    "model": {"primary": "test-model-uuid", "fallbacks": []},
+                    "prompt": "test-prompt",
+                },
+            },
+            "output": {"misc": {"at-sender": False, "quote-origin": False}},
+            "trigger": {"misc": {"combine-quote-message": False}},
+        },
+        "session": None,
+        "prompt": None,
+        "messages": [],
+        "user_message": None,
+        "use_funcs": [],
+        "use_llm_model_uuid": None,
+        "variables": {},
+        "resp_messages": [],
+        "resp_message_chain": None,
+        "current_stage_name": None,
+    }
+
+    # Apply overrides
+    for key, value in overrides.items():
+        base_data[key] = value
+
+    return pipeline_query.Query.model_construct(**base_data)
+
+
+def text_query(
+    text: str = "hello",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a basic text query (private chat)."""
+    chain = text_chain(text)
+    event = friend_message_event(chain, sender_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=sender_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def private_text_query(
+    text: str = "hello",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a private text query (alias for text_query)."""
+    return text_query(text, sender_id, **overrides)
+
+
+def group_text_query(
+    text: str = "hello",
+    sender_id: typing.Union[int, str] = 12345,
+    group_id: typing.Union[int, str] = 99999,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a group text query."""
+    chain = text_chain(text)
+    event = group_message_event(chain, sender_id, group_id=group_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.GROUP,
+        launcher_id=group_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def command_query(
+    command: str = "help",
+    prefix: str = "/",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a command-like query."""
+    chain = command_chain(command, prefix)
+    event = friend_message_event(chain, sender_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=sender_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def mention_query(
+    text: str = "hello",
+    target: typing.Union[int, str] = 12345,
+    sender_id: typing.Union[int, str] = 12345,
+    group_id: typing.Union[int, str] = 99999,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a mention-bot query (group chat with @mention)."""
+    chain = mention_chain(text, target)
+    event = group_message_event(chain, sender_id, group_id=group_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.GROUP,
+        launcher_id=group_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def empty_query(**overrides) -> pipeline_query.Query:
+    """Create an empty message query."""
+    chain = platform_message.MessageChain([])
+    event = friend_message_event(chain)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=12345,
+        sender_id=12345,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def image_query(
+    text: str = "",
+    url: str = "https://example.com/image.png",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create an image query."""
+    chain = image_chain(text, url)
+    event = friend_message_event(chain, sender_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=sender_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def file_query(
+    url: str = "https://example.com/document.pdf",
+    name: str = "document.pdf",
+    text: str = "",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a file attachment query."""
+    components = []
+    if text:
+        components.append(platform_message.Plain(text=text))
+    components.append(platform_message.File(url=url, name=name))
+    chain = platform_message.MessageChain(components)
+    event = friend_message_event(chain, sender_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=sender_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def unsupported_query(
+    unsupported_type: str = "CustomComponent",
+    text: str = "",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a query with unsupported/unknown message segment."""
+    components = []
+    if text:
+        components.append(platform_message.Plain(text=text))
+    # Use Unknown component for unsupported types
+    components.append(platform_message.Unknown(text=f"Unsupported: {unsupported_type}"))
+    chain = platform_message.MessageChain(components)
+    event = friend_message_event(chain, sender_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=sender_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def query_with_session(
+    text: str = "hello",
+    sender_id: typing.Union[int, str] = 12345,
+    session: provider_session.Session = None,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a query with a session object.
+
+    If session is None, creates a default session with empty conversation.
+    """
+    if session is None:
+        # Create a default session
+        session = provider_session.Session(
+            launcher_type=provider_session.LauncherTypes.PERSON,
+            launcher_id=sender_id,
+            sender_id=sender_id,
+            use_prompt_name="default",
+            using_conversation=None,
+            conversations=[],
+        )
+
+    return text_query(text, sender_id, session=session, **overrides)
+
+
+def query_with_config(
+    text: str = "hello",
+    sender_id: typing.Union[int, str] = 12345,
+    pipeline_config: dict = None,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a query with custom pipeline configuration.
+
+    If pipeline_config is None, uses default config.
+    Useful for testing specific stage behaviors.
+    """
+    if pipeline_config is None:
+        pipeline_config = {
+            "ai": {
+                "runner": {"runner": "local-agent"},
+                "local-agent": {
+                    "model": {"primary": "test-model-uuid", "fallbacks": []},
+                    "prompt": "test-prompt",
+                },
+            },
+            "output": {"misc": {"at-sender": False, "quote-origin": False}},
+            "trigger": {"misc": {"combine-quote-message": False}},
+        }
+
+    return text_query(text, sender_id, pipeline_config=pipeline_config, **overrides)
+
+
+def voice_query(
+    url: str = "https://example.com/audio.mp3",
+    sender_id: typing.Union[int, str] = 12345,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a voice/audio query."""
+    components = [
+        platform_message.Voice(url=url),
+    ]
+    chain = platform_message.MessageChain(components)
+    event = friend_message_event(chain, sender_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.PERSON,
+        launcher_id=sender_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
+
+
+def at_all_query(
+    text: str = "hello",
+    sender_id: typing.Union[int, str] = 12345,
+    group_id: typing.Union[int, str] = 99999,
+    **overrides,
+) -> pipeline_query.Query:
+    """Create a group query with @All mention."""
+    components = [
+        platform_message.AtAll(),
+        platform_message.Plain(text=f" {text}"),
+    ]
+    chain = platform_message.MessageChain(components)
+    event = group_message_event(chain, sender_id, group_id=group_id)
+    adapter = mock_adapter()
+    return _base_query(
+        message_chain=chain,
+        message_event=event,
+        launcher_type=provider_session.LauncherTypes.GROUP,
+        launcher_id=group_id,
+        sender_id=sender_id,
+        adapter=adapter,
+        **overrides,
+    )
--- a/tests/factories/platform.py
+++ b/tests/factories/platform.py
@@ -0,0 +1,336 @@
+"""
+Fake platform factory for tests.
+
+Provides a fake platform adapter for tests that need inbound message injection
+and outbound message capture.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, Mock
+import typing
+
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+
+
+class FakePlatform:
+    """Fake platform adapter for unit and integration tests.
+
+    Simulates platform behavior without real network calls:
+    - Inbound text message construction
+    - Group and private conversation identities
+    - Mention-bot flag
+    - Outbound text capture
+    - Outbound file/image capture
+    - Send failure simulation
+
+    Does not start real platform adapters.
+    Does not call IM platform SDKs.
+    """
+
+    def __init__(
+        self,
+        *,
+        bot_account_id: str = "test-bot",
+        stream_output_supported: bool = False,
+        raise_error: Exception = None,
+    ):
+        self.bot_account_id = bot_account_id
+        self._stream_output_supported = stream_output_supported
+        self._raise_error = raise_error
+
+        # Captured outbound messages
+        self._outbound_messages: list[dict] = []
+        self._outbound_chunks: list[dict] = []
+
+        # Registered listeners
+        self._listeners: dict = {}
+
+    def raises(self, error: Exception) -> "FakePlatform":
+        """Configure platform to raise an error on send."""
+        self._raise_error = error
+        return self
+
+    def send_failure(self) -> "FakePlatform":
+        """Configure platform to simulate send failure."""
+        return self.raises(Exception("Platform send failure"))
+
+    def supports_streaming(self, supported: bool = True) -> "FakePlatform":
+        """Configure whether streaming output is supported."""
+        self._stream_output_supported = supported
+        return self
+
+    def get_outbound_messages(self) -> list[dict]:
+        """Get all captured outbound messages for assertions."""
+        return self._outbound_messages.copy()
+
+    def get_outbound_chunks(self) -> list[dict]:
+        """Get all captured outbound streaming chunks for assertions."""
+        return self._outbound_chunks.copy()
+
+    def clear_outbound(self):
+        """Clear captured outbound messages."""
+        self._outbound_messages.clear()
+        self._outbound_chunks.clear()
+
+    def last_message(self) -> dict | None:
+        """Get the last captured outbound message."""
+        return self._outbound_messages[-1] if self._outbound_messages else None
+
+    def last_chunk(self) -> dict | None:
+        """Get the last captured streaming chunk."""
+        return self._outbound_chunks[-1] if self._outbound_chunks else None
+
+    # ============== Inbound Message Construction ==============
+
+    def create_friend_message(
+        self,
+        text: str,
+        sender_id: typing.Union[int, str] = 12345,
+        nickname: str = "TestUser",
+    ) -> platform_events.FriendMessage:
+        """Create an inbound friend (private) message event."""
+        sender = platform_entities.Friend(
+            id=sender_id,
+            nickname=nickname,
+            remark=None,
+        )
+        chain = platform_message.MessageChain([
+            platform_message.Plain(text=text),
+        ])
+        return platform_events.FriendMessage(
+            type="FriendMessage",
+            sender=sender,
+            message_chain=chain,
+            time=1609459200,
+        )
+
+    def create_group_message(
+        self,
+        text: str,
+        sender_id: typing.Union[int, str] = 12345,
+        sender_name: str = "TestUser",
+        group_id: typing.Union[int, str] = 99999,
+        group_name: str = "TestGroup",
+        mention_bot: bool = False,
+    ) -> platform_events.GroupMessage:
+        """Create an inbound group message event.
+
+        Args:
+            text: Message text content
+            sender_id: Sender user ID
+            sender_name: Sender display name
+            group_id: Group ID
+            group_name: Group name
+            mention_bot: If True, prepend @mention of bot account
+        """
+        group = platform_entities.Group(
+            id=group_id,
+            name=group_name,
+            permission=platform_entities.Permission.Member,
+        )
+        sender = platform_entities.GroupMember(
+            id=sender_id,
+            member_name=sender_name,
+            permission=platform_entities.Permission.Member,
+            group=group,
+        )
+
+        # Build message chain with optional mention
+        components = []
+        if mention_bot:
+            components.append(platform_message.At(target=self.bot_account_id))
+            components.append(platform_message.Plain(text=" "))
+        components.append(platform_message.Plain(text=text))
+
+        chain = platform_message.MessageChain(components)
+        return platform_events.GroupMessage(
+            type="GroupMessage",
+            sender=sender,
+            message_chain=chain,
+            time=1609459200,
+        )
+
+    def create_image_message(
+        self,
+        url: str = "https://example.com/image.png",
+        text: str = "",
+        sender_id: typing.Union[int, str] = 12345,
+        is_group: bool = False,
+        group_id: typing.Union[int, str] = 99999,
+    ) -> platform_events.MessageEvent:
+        """Create an inbound image message event."""
+        components = []
+        if text:
+            components.append(platform_message.Plain(text=text))
+        components.append(platform_message.Image(url=url))
+        chain = platform_message.MessageChain(components)
+
+        if is_group:
+            return self.create_group_message("", sender_id, group_id=group_id)
+            # Replace chain
+        else:
+            sender = platform_entities.Friend(id=sender_id, nickname="TestUser", remark=None)
+            return platform_events.FriendMessage(
+                type="FriendMessage",
+                sender=sender,
+                message_chain=chain,
+                time=1609459200,
+            )
+
+    # ============== Adapter Methods (Simulated) ==============
+
+    async def send_message(
+        self,
+        target_type: str,
+        target_id: str,
+        message: platform_message.MessageChain,
+    ):
+        """Simulate sending a message (captures for assertions)."""
+        if self._raise_error:
+            raise self._raise_error
+
+        self._outbound_messages.append({
+            "type": "send",
+            "target_type": target_type,
+            "target_id": target_id,
+            "message": message,
+        })
+
+    async def reply_message(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+    ):
+        """Simulate replying to a message (captures for assertions)."""
+        if self._raise_error:
+            raise self._raise_error
+
+        self._outbound_messages.append({
+            "type": "reply",
+            "source_type": message_source.type,
+            "source": message_source,
+            "message": message,
+            "quote_origin": quote_origin,
+        })
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message: dict,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        """Simulate streaming reply (captures for assertions)."""
+        if self._raise_error:
+            raise self._raise_error
+
+        self._outbound_chunks.append({
+            "type": "reply_chunk",
+            "source_type": message_source.type,
+            "source": message_source,
+            "bot_message": bot_message,
+            "message": message,
+            "quote_origin": quote_origin,
+            "is_final": is_final,
+        })
+
+    async def is_stream_output_supported(self) -> bool:
+        """Return whether streaming output is supported."""
+        return self._stream_output_supported
+
+    def register_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable,
+    ):
+        """Register an event listener (stores for simulation)."""
+        if event_type not in self._listeners:
+            self._listeners[event_type] = []
+        self._listeners[event_type].append(callback)
+
+    def unregister_listener(
+        self,
+        event_type: typing.Type[platform_events.Event],
+        callback: typing.Callable,
+    ):
+        """Unregister an event listener."""
+        if event_type in self._listeners:
+            self._listeners[event_type].remove(callback)
+
+    async def run_async(self):
+        """Simulate running the adapter (does nothing)."""
+        pass
+
+    async def kill(self) -> bool:
+        """Simulate killing the adapter."""
+        return True
+
+    async def is_muted(self, group_id: int) -> bool:
+        """Simulate checking mute status."""
+        return False
+
+    async def create_message_card(
+        self,
+        message_id: typing.Type[str, int],
+        event: platform_events.MessageEvent,
+    ) -> bool:
+        """Simulate creating a message card."""
+        return False
+
+    # ============== Simulation Helpers ==============
+
+    async def simulate_inbound_event(
+        self,
+        event: platform_events.Event,
+    ):
+        """Simulate receiving an inbound event by calling registered listeners."""
+        listeners = self._listeners.get(type(event), [])
+        for callback in listeners:
+            await callback(event, self)
+
+
+def fake_platform(
+    bot_account_id: str = "test-bot",
+    stream_output_supported: bool = False,
+) -> FakePlatform:
+    """Create a FakePlatform instance."""
+    return FakePlatform(
+        bot_account_id=bot_account_id,
+        stream_output_supported=stream_output_supported,
+    )
+
+
+def fake_platform_with_streaming() -> FakePlatform:
+    """Create a FakePlatform that supports streaming output."""
+    return FakePlatform(stream_output_supported=True)
+
+
+def fake_platform_with_failure() -> FakePlatform:
+    """Create a FakePlatform that simulates send failure."""
+    return FakePlatform().send_failure()
+
+
+# ============== Mock Adapter (for Query) ==============
+
+
+def mock_platform_adapter(platform: FakePlatform = None) -> Mock:
+    """Create a mock platform adapter using FakePlatform or a simple mock."""
+    if platform is None:
+        platform = FakePlatform()
+
+    adapter = Mock()
+    adapter.bot_account_id = platform.bot_account_id
+    adapter.reply_message = AsyncMock(side_effect=platform.reply_message)
+    adapter.reply_message_chunk = AsyncMock(side_effect=platform.reply_message_chunk)
+    adapter.send_message = AsyncMock(side_effect=platform.send_message)
+    adapter.is_stream_output_supported = AsyncMock(
+        return_value=platform._stream_output_supported
+    )
+    adapter._fake_platform = platform  # Store for assertions
+
+    return adapter
--- a/tests/factories/provider.py
+++ b/tests/factories/provider.py
@@ -0,0 +1,224 @@
+"""
+Fake provider factory for tests.
+
+Provides a deterministic fake provider that simulates LLM responses without real API calls.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import Mock
+import typing
+
+import langbot_plugin.api.entities.builtin.provider.message as provider_message
+
+
+class FakeProvider:
+    """Deterministic fake provider for unit and integration tests.
+
+    Simulates various provider behaviors:
+    - Normal text response
+    - Streaming response
+    - Timeout error
+    - Auth error
+    - Rate-limit error
+    - Malformed response
+
+    Does not call real LLM vendors.
+    Does not require API keys.
+    """
+
+    PONG_RESPONSE = "LANGBOT_FAKE_PONG"
+
+    def __init__(
+        self,
+        *,
+        default_response: str = "fake response",
+        streaming_chunks: list[str] = None,
+        raise_error: Exception = None,
+        captured_requests: list = None,
+    ):
+        self._default_response = default_response
+        self._streaming_chunks = streaming_chunks or ["fake ", "response"]
+        self._raise_error = raise_error
+        self._captured_requests = captured_requests if captured_requests is not None else []
+
+    def returns(self, text: str) -> "FakeProvider":
+        """Configure provider to return a specific text response."""
+        self._default_response = text
+        self._streaming_chunks = [text]
+        return self
+
+    def returns_streaming(self, chunks: list[str]) -> "FakeProvider":
+        """Configure provider to return streaming chunks."""
+        self._streaming_chunks = chunks
+        self._default_response = "".join(chunks)
+        return self
+
+    def raises(self, error: Exception) -> "FakeProvider":
+        """Configure provider to raise an error."""
+        self._raise_error = error
+        return self
+
+    def timeout(self) -> "FakeProvider":
+        """Configure provider to simulate timeout."""
+        return self.raises(TimeoutError("Provider timeout"))
+
+    def auth_error(self) -> "FakeProvider":
+        """Configure provider to simulate auth error."""
+        return self.raises(Exception("Invalid API key"))
+
+    def rate_limit(self) -> "FakeProvider":
+        """Configure provider to simulate rate limit."""
+        return self.raises(Exception("Rate limit exceeded"))
+
+    def malformed(self) -> "FakeProvider":
+        """Configure provider to simulate malformed response."""
+        self._default_response = None
+        return self
+
+    def get_captured_requests(self) -> list:
+        """Get all captured request arguments for assertions."""
+        return self._captured_requests.copy()
+
+    def clear_captured_requests(self):
+        """Clear captured requests."""
+        self._captured_requests.clear()
+
+    def _create_message(self, content: str) -> provider_message.Message:
+        """Create a provider message from text content."""
+        return provider_message.Message(
+            role="assistant",
+            content=content,
+        )
+
+    def _create_chunk(
+        self,
+        content: str,
+        is_final: bool = False,
+        msg_sequence: int = 0,
+    ) -> provider_message.MessageChunk:
+        """Create a provider message chunk."""
+        return provider_message.MessageChunk(
+            role="assistant",
+            content=content,
+            is_final=is_final,
+            msg_sequence=msg_sequence,
+        )
+
+    async def invoke_llm(
+        self,
+        query,
+        model,
+        messages: list,
+        funcs: list,
+        extra_args: dict,
+        remove_think: bool = False,
+    ) -> provider_message.Message:
+        """Simulate non-streaming LLM invocation."""
+        # Capture request for assertions
+        self._captured_requests.append({
+            "query_id": query.query_id if query else None,
+            "model": model.model_entity.name if model and hasattr(model, 'model_entity') else None,
+            "messages": messages,
+            "funcs": funcs,
+            "extra_args": extra_args,
+        })
+
+        # Simulate error if configured
+        if self._raise_error:
+            raise self._raise_error
+
+        # Return response
+        if self._default_response is None:
+            # Malformed response
+            return provider_message.Message(role="assistant", content=None)
+
+        return self._create_message(self._default_response)
+
+    async def invoke_llm_stream(
+        self,
+        query,
+        model,
+        messages: list,
+        funcs: list,
+        extra_args: dict,
+        remove_think: bool = False,
+    ) -> typing.AsyncGenerator[provider_message.MessageChunk, None]:
+        """Simulate streaming LLM invocation."""
+        # Capture request for assertions
+        self._captured_requests.append({
+            "query_id": query.query_id if query else None,
+            "model": model.model_entity.name if model and hasattr(model, 'model_entity') else None,
+            "messages": messages,
+            "funcs": funcs,
+            "extra_args": extra_args,
+            "streaming": True,
+        })
+
+        # Simulate error if configured
+        if self._raise_error:
+            raise self._raise_error
+
+        # Yield chunks
+        for i, chunk in enumerate(self._streaming_chunks):
+            is_final = (i == len(self._streaming_chunks) - 1)
+            yield self._create_chunk(chunk, is_final=is_final, msg_sequence=i)
+
+
+def fake_provider(
+    default_response: str = "fake response",
+) -> FakeProvider:
+    """Create a FakeProvider with optional default response."""
+    return FakeProvider(default_response=default_response)
+
+
+def fake_provider_pong() -> FakeProvider:
+    """Create a FakeProvider that returns the pong response."""
+    return FakeProvider(default_response=FakeProvider.PONG_RESPONSE)
+
+
+def fake_provider_timeout() -> FakeProvider:
+    """Create a FakeProvider that simulates timeout."""
+    return FakeProvider().timeout()
+
+
+def fake_provider_auth_error() -> FakeProvider:
+    """Create a FakeProvider that simulates auth error."""
+    return FakeProvider().auth_error()
+
+
+def fake_provider_rate_limit() -> FakeProvider:
+    """Create a FakeProvider that simulates rate limit."""
+    return FakeProvider().rate_limit()
+
+
+def fake_provider_malformed() -> FakeProvider:
+    """Create a FakeProvider that simulates malformed response."""
+    return FakeProvider().malformed()
+
+
+# ============== Mock Model Factory ==============
+
+
+def fake_model(
+    *,
+    uuid: str = "test-model-uuid",
+    name: str = "test-model",
+    abilities: list[str] = None,
+    provider: FakeProvider = None,
+) -> Mock:
+    """Create a mock model with a fake provider."""
+    model = Mock()
+    model.model_entity = Mock()
+    model.model_entity.uuid = uuid
+    model.model_entity.name = name
+    model.model_entity.abilities = abilities or ["func_call", "vision"]
+    model.model_entity.extra_args = {}
+
+    # Attach fake provider
+    if provider is None:
+        provider = FakeProvider()
+
+    model.provider = provider
+
+    return model
--- a/tests/integration/init.py
+++ b/tests/integration/init.py
@@ -0,0 +1,6 @@
+"""
+Integration tests package.
+
+These tests validate real system behavior with actual database/network resources.
+Run with: uv run pytest tests/integration/ -m "not slow" -q
+"""
--- a/tests/integration/api/init.py
+++ b/tests/integration/api/init.py
@@ -0,0 +1,5 @@
+"""
+API integration tests package.
+
+Tests for HTTP API endpoints using Quart test client.
+"""
--- 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
@@ -0,0 +1,253 @@
+"""
+API integration tests for bot endpoints.
+
+Tests real HTTP API behavior for bot management.
+
+Run: uv run pytest tests/integration/api/test_bots.py -q
+"""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock, Mock
+
+from tests.factories import FakeApp
+
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture(scope='module')
+def mock_circular_import_chain():
+    """Break circular import chain for API controller."""
+    from tests.utils.import_isolation import isolated_sys_modules, MockLifecycleControlScope
+
+    class FakeMinimalApplication:
+        pass
+
+    mock_app = MagicMock()
+    mock_app.Application = FakeMinimalApplication
+
+    mock_entities = MagicMock()
+    mock_entities.LifecycleControlScope = MockLifecycleControlScope
+
+    clear = [
+        'langbot.pkg.api.http.controller.group',
+        'langbot.pkg.api.http.controller.groups',
+        'langbot.pkg.api.http.controller.groups.platform',
+        'langbot.pkg.api.http.controller.groups.platform.bots',
+        'langbot.pkg.api.http.controller.groups.platform.adapters',
+        'langbot.pkg.api.http.controller.main',
+    ]
+
+    with isolated_sys_modules(
+        mocks={
+            'langbot.pkg.core.app': mock_app,
+            'langbot.pkg.core.entities': mock_entities,
+        },
+        clear=clear,
+    ):
+        import langbot.pkg.api.http.controller.groups.platform.bots as _bots  # noqa: E402, F401
+        yield
+
+
+@pytest.fixture(scope='module')
+def fake_bot_app():
+    """Create FakeApp with bot services (module scope for reuse)."""
+    app = FakeApp()
+
+    app.instance_config.data.update({
+        'api': {'port': 5300},
+        'system': {'allow_modify_login_info': True, 'limitation': {}},
+    })
+
+    # Auth services
+    app.user_service = Mock()
+    app.user_service.is_initialized = AsyncMock(return_value=True)
+    app.user_service.verify_jwt_token = AsyncMock(return_value='test@example.com')
+    app.user_service.get_user_by_email = AsyncMock(return_value=Mock(email='test@example.com'))
+    app.apikey_service = Mock()
+    app.apikey_service.verify_api_key = AsyncMock(return_value=True)
+
+    # Bot service
+    app.bot_service = Mock()
+    app.bot_service.get_bots = AsyncMock(return_value=[
+        {
+            'uuid': 'test-bot-uuid',
+            'name': 'Test Bot',
+            'platform': 'telegram',
+            'pipeline_uuid': 'test-pipeline-uuid',
+        }
+    ])
+    app.bot_service.get_runtime_bot_info = AsyncMock(return_value={
+        'uuid': 'test-bot-uuid',
+        'name': 'Test Bot',
+        'platform': 'telegram',
+        'pipeline_uuid': 'test-pipeline-uuid',
+        'webhook_url': 'https://example.com/webhook/test-bot-uuid',
+    })
+    app.bot_service.create_bot = AsyncMock(return_value={'uuid': 'new-bot-uuid'})
+    app.bot_service.update_bot = AsyncMock(return_value={})
+    app.bot_service.delete_bot = AsyncMock()
+    app.bot_service.list_event_logs = AsyncMock(return_value=(
+        [{'uuid': 'log-1', 'message': 'test log'}],
+        1
+    ))
+    app.bot_service.send_message = AsyncMock()
+
+    # Platform manager
+    app.platform_mgr = Mock()
+
+    return app
+
+
+@pytest.fixture(scope='module')
+async def quart_test_client(fake_bot_app, http_controller_cls):
+    """Create Quart test client (module scope to avoid route re-registration)."""
+    controller = http_controller_cls(fake_bot_app)
+    await controller.initialize()
+
+    client = controller.quart_app.test_client()
+    yield client
+
+
+@pytest.mark.usefixtures('mock_circular_import_chain')
+class TestBotEndpoints:
+    """Tests for /api/v1/platform/bots endpoints."""
+
+    @pytest.mark.asyncio
+    async def test_get_bots_success(self, quart_test_client):
+        """GET /api/v1/platform/bots returns bot list."""
+        response = await quart_test_client.get(
+            '/api/v1/platform/bots',
+            headers={'Authorization': 'Bearer test_token'}
+        )
+
+        assert response.status_code == 200
+        data = await response.get_json()
+        assert data['code'] == 0
+        assert 'data' in data
+        assert 'bots' in data['data']
+
+    @pytest.mark.asyncio
+    async def test_create_bot_success(self, quart_test_client):
+        """POST /api/v1/platform/bots creates new bot."""
+        response = await quart_test_client.post(
+            '/api/v1/platform/bots',
+            headers={'Authorization': 'Bearer test_token'},
+            json={'name': 'New Bot', 'platform': 'telegram', 'pipeline_uuid': 'test-pipeline'}
+        )
+
+        assert response.status_code == 200
+        data = await response.get_json()
+        assert data['code'] == 0
+        assert 'uuid' in data['data']
+
+    @pytest.mark.asyncio
+    async def test_get_single_bot_success(self, quart_test_client):
+        """GET /api/v1/platform/bots/{uuid} returns bot with runtime info."""
+        response = await quart_test_client.get(
+            '/api/v1/platform/bots/test-bot-uuid',
+            headers={'Authorization': 'Bearer test_token'}
+        )
+
+        assert response.status_code == 200
+        data = await response.get_json()
+        assert data['code'] == 0
+        assert 'bot' in data['data']
+
+    @pytest.mark.asyncio
+    async def test_update_bot_success(self, quart_test_client):
+        """PUT /api/v1/platform/bots/{uuid} updates bot."""
+        response = await quart_test_client.put(
+            '/api/v1/platform/bots/test-bot-uuid',
+            headers={'Authorization': 'Bearer test_token'},
+            json={'name': 'Updated Bot'}
+        )
+
+        assert response.status_code == 200
+        data = await response.get_json()
+        assert data['code'] == 0
+
+    @pytest.mark.asyncio
+    async def test_delete_bot_success(self, quart_test_client):
+        """DELETE /api/v1/platform/bots/{uuid} deletes bot."""
+        response = await quart_test_client.delete(
+            '/api/v1/platform/bots/test-bot-uuid',
+            headers={'Authorization': 'Bearer test_token'}
+        )
+
+        assert response.status_code == 200
+
+
+@pytest.mark.usefixtures('mock_circular_import_chain')
+class TestBotLogsEndpoint:
+    """Tests for bot logs endpoint."""
+
+    @pytest.mark.asyncio
+    async def test_get_bot_logs_success(self, quart_test_client):
+        """POST /api/v1/platform/bots/{uuid}/logs returns logs."""
+        response = await quart_test_client.post(
+            '/api/v1/platform/bots/test-bot-uuid/logs',
+            headers={'Authorization': 'Bearer test_token'},
+            json={'from_index': -1, 'max_count': 10}
+        )
+
+        assert response.status_code == 200
+        data = await response.get_json()
+        assert data['code'] == 0
+        assert 'logs' in data['data']
+        assert 'total_count' in data['data']
+
+
+@pytest.mark.usefixtures('mock_circular_import_chain')
+class TestBotSendMessageEndpoint:
+    """Tests for bot send message endpoint."""
+
+    @pytest.mark.asyncio
+    async def test_send_message_success(self, quart_test_client):
+        """POST /api/v1/platform/bots/{uuid}/send_message sends message."""
+        response = await quart_test_client.post(
+            '/api/v1/platform/bots/test-bot-uuid/send_message',
+            headers={'Authorization': 'Bearer test_api_key'},
+            json={
+                'target_type': 'person',
+                'target_id': 'user123',
+                'message_chain': [{'type': 'text', 'text': 'Hello'}]
+            }
+        )
+
+        assert response.status_code == 200
+        data = await response.get_json()
+        assert data['code'] == 0
+        assert data['data']['sent'] is True
+
+    @pytest.mark.asyncio
+    async def test_send_message_missing_target_type(self, quart_test_client):
+        """POST send_message without target_type returns 400."""
+        response = await quart_test_client.post(
+            '/api/v1/platform/bots/test-bot-uuid/send_message',
+            headers={'Authorization': 'Bearer test_api_key'},
+            json={'target_id': 'user123', 'message_chain': [{'type': 'text', 'text': 'Hello'}]}
+        )
+
+        assert response.status_code == 400
+        data = await response.get_json()
+        assert data['code'] == -1
+
+    @pytest.mark.asyncio
+    async def test_send_message_invalid_target_type(self, quart_test_client):
+        """POST send_message with invalid target_type returns 400."""
+        response = await quart_test_client.post(
+            '/api/v1/platform/bots/test-bot-uuid/send_message',
+            headers={'Authorization': 'Bearer test_api_key'},
+            json={
+                'target_type': 'invalid',
+                'target_id': 'user123',
+                'message_chain': [{'type': 'text', 'text': 'Hello'}]
+            }
+        )
+
+        assert response.status_code == 400
+        data = await response.get_json()
+        assert data['code'] == -1
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Qiniu</title><path d="M23.111 4.6a.914.914 0 00-.861.161A13.443 13.443 0 017.947 8.897L7.38 6.831a1.076 1.076 0 00-1.211-.698l.27 2.18c-1.816-.827-2.313-.946-3.587-2.45C2.674 5.729 1.263 4.472.89 4.6a11.906 11.906 0 005.892 6.497l.738 5.97s.33 2.286 2.473 2.286h4.586c2.144 0 2.474-2.286 2.474-2.286l.518-4.28c-1.393-.11-2.268.857-2.546 1.814-.465 1.614-.465 1.716-.557 1.998-.188.575-.806.644-.806.644h-2.753s-.617-.07-.806-.644c-.12-.371-.727-2.54-1.335-4.74A11.877 11.877 0 0023.11 4.599V4.6z" fill="#06AEEF"></path></svg>