docs(eba): record agent-unified orchestration direction and final product form

# Conflicts:
#	pyproject.toml
#	uv.lock

.github/workflows/frontend-tests.yml

@@ -1,46 +0,0 @@
-name: Frontend Tests
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
-    paths:
-      - 'web/**'
-      - '.github/workflows/frontend-tests.yml'
-  push:
-    branches:
-      - master
-      - develop
-    paths:
-      - 'web/**'
-      - '.github/workflows/frontend-tests.yml'
-
-jobs:
-  playwright-smoke:
-    name: Playwright Smoke
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '25'
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 8.9.2
-
-      - name: Install dependencies
-        working-directory: web
-        run: pnpm install --frozen-lockfile
-
-      - name: Install Playwright browsers
-        working-directory: web
-        run: pnpm exec playwright install --with-deps chromium
-
-      - name: Run Playwright smoke tests
-        working-directory: web
-        run: pnpm test:e2e

.github/workflows/lint.yml

@@ -29,7 +29,7 @@ jobs:
         run: uv sync --dev
 
       - name: Run ruff check
-        run: uv run ruff check src/langbot/ tests/ --output-format=concise
+        run: uv run ruff check src
 
       - name: Run ruff format
         run: uv run ruff format src --check

.github/workflows/run-tests.yml

@@ -84,67 +84,6 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
 
-  e2e:
-    name: E2E Startup 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 E2E startup tests
-        run: uv run pytest tests/e2e -q --tb=short
-
-      - name: E2E Test Summary
-        if: always()
-        run: |
-          echo "## E2E Startup Test Results" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
-
-  box-integration:
-    name: Box 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: Check Docker runtime
-        run: docker info
-
-      - name: Run Box integration tests
-        run: uv run pytest tests/integration_tests -q --tb=short
-
-      - name: Box Integration Test Summary
-        if: always()
-        run: |
-          echo "## Box Integration Test Results" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
-
   coverage:
     name: Coverage Gate
     runs-on: ubuntu-latest

AGENTS.md

@@ -125,35 +125,6 @@ uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "descriptio
 
 Review and edit the generated script before committing. Migrations execute automatically on startup. `autogenerate` detects schema changes (add/drop columns, tables, type changes) but **data migrations** (e.g. mutating JSON field contents) must be hand-written into the generated script. `env.py` sets `render_as_batch=True`, so SQLite's ALTER TABLE limits are handled automatically — no need to branch per database. More in the wiki ["开发配置"](https://docs.langbot.app/zh/develop/dev-config#数据库迁移).
 
-When writing a migration, follow these rules:
-
-- **Revision id ≤ 32 characters.** PostgreSQL stores `alembic_version.version_num` as `varchar(32)`; a longer id raises `StringDataRightTruncationError` at runtime. Prefer short, descriptive ids like `0005_add_llm_context_length`.
-- **Guard every operation against missing tables/columns.** Fresh installs build the schema via `create_all()` and then stamp the Alembic baseline, so a migration may run against a table that already has the change — or, in tests, against an empty database. Check `inspector.get_table_names()` / `inspector.get_columns(...)` before `add_column` / `drop_column`, mirroring the existing migrations.
-- **Keep a single linear head.** Chain `down_revision` to the current head; do not create branches. Run the migration tests after adding one: `uv run pytest tests/integration/persistence/ -q` (the PostgreSQL test needs a running PG via `TEST_POSTGRES_URL`).
-
-> **Legacy migration system (deprecated — do not extend).** The old 3.x migration system under `src/langbot/pkg/persistence/migrations/` (`DBMigration` subclasses in `dbmXXX_*.py`, run from `pkg/persistence/mgr.py`) is **frozen**. Do **not** add new `dbmXXX_*.py` files. The chain is capped at `required_database_version = 25` (`pkg/utils/constants.py`); those files only exist to upgrade pre-existing 3.x databases up to the Alembic baseline and are kept read-only. All new schema changes go through Alembic.
-
-## Agent-Facing Surfaces (MCP + Skills)
-
-LangBot is built to be **agent-friendly**. Three surfaces let AI agents work
-with LangBot, and they MUST be kept in lockstep with the HTTP API:
-
-1. **MCP server** — `src/langbot/pkg/api/mcp/` exposes a curated subset of the
-   API as MCP tools at `/mcp` (API-key authenticated, including the
-   `api.global_api_key` from config.yaml). `server.py` defines the tools (they
-   call the service layer directly); `mount.py` is the ASGI dispatcher.
-2. **In-repo skills** — `skills/` is the **single source of truth** for agent
-   skills (plugin/core/deploy/e2e/MCP-ops). Docs and the landing page link here
-   rather than embedding their own copies.
-3. **API-key auth** — `api.global_api_key` (config.yaml) authenticates the API
-   and MCP without a login session; see `docs/API_KEY_AUTH.md`.
-
-> **Maintenance rule (important).** When you add, remove, or change an HTTP API
-> endpoint that should be agent-accessible, you MUST update **both** the matching
-> MCP tool in `src/langbot/pkg/api/mcp/server.py` **and** the relevant skill under
-> `skills/` (especially `skills/skills/langbot-mcp-ops`). The API, the MCP tool
-> surface, and the skills are one system — drift between them is a bug.
-
 ## Some Principles
 
 - Keep it simple, stupid.

README.md

@@ -36,10 +36,6 @@ English / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本
 
 LangBot is an **open-source, production-grade platform** for building AI-powered instant messaging bots. It connects Large Language Models (LLMs) to any chat platform, enabling you to create intelligent agents that can converse, execute tasks, and integrate with your existing workflows.
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="LangBot web management dashboard — real-time monitoring of message volume, model calls, success rate and active sessions" width="720"/>
-</p>
-
 ### Key Capabilities
 
 - **AI Conversations & Agents** — Multi-turn dialogues, tool calling, multi-modal support, streaming output. Built-in RAG (knowledge base) with deep integration to [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io), [Langflow](https://langflow.org), [Deerflow](https://deerflow.tech), [Weknora](https://weknora.weixin.qq.com).
@@ -148,19 +144,6 @@ docker compose up -d
 
 ---
 
-## Built for AI Agents 🤖
-
-LangBot is **agent-friendly by design** — your coding agents (Claude Code, Codex, Copilot, Cursor, …) can operate, extend, and deploy LangBot with first-class support:
-
-- **MCP Server** — LangBot exposes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) endpoint at `/mcp`, mirroring the HTTP API so an agent can manage bots, pipelines, plugins, and models programmatically. Authenticate with the same API key (set a global key in `config.yaml` or use a per-user key) — no login flow required. Configure it in the Web panel's **API & MCP** tab.
-- **In-repo Skills** — The [`skills/`](skills/) directory is the **single source of truth** for working with LangBot: plugin development, core development, end-to-end testing, deployment, and operating the LangBot / LangBot Space MCP servers. Point your agent at this directory and it knows how to build.
-- **AGENTS.md** — Every repo ships an [`AGENTS.md`](AGENTS.md) (symlinked to `CLAUDE.md`) describing architecture, conventions, and the rule that API changes must keep the MCP server and skills in sync.
-- **`llms.txt`** — Machine-readable project context for LLMs is published on the website.
-
-> **Cloud / Marketplace:** [LangBot Space](https://space.langbot.app) also exposes an MCP server so agents can search and inspect the plugin / MCP / skill marketplace, authenticated with a Personal Access Token.
-
----
-
 ## Live Demo
 
 **Try it now:** https://demo.langbot.dev/

README_CN.md

@@ -36,10 +36,6 @@
 
 LangBot 是一个**开源的生产级平台**，用于构建 AI 驱动的即时通信机器人。它将大语言模型（LLM）连接到各种聊天平台，帮助你创建能够对话、执行任务、并集成到现有工作流程中的智能 Agent。
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="LangBot Web 管理面板仪表盘 — 实时监控消息量、模型调用、成功率与活跃会话" width="720"/>
-</p>
-
 ### 核心能力
 
 - **AI 对话与 Agent** — 多轮对话、工具调用、多模态、流式输出。自带 RAG（知识库），深度集成 [Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io)、[Langflow](https://langflow.org)、[Deerflow](https://deerflow.tech)、[Weknora](https://weknora.weixin.qq.com)等 LLMOps 平台。
@@ -174,19 +170,6 @@ docker compose up -d
 
 ---
 
-## 为 AI Agent 而生 🤖
-
-LangBot **从设计上就对 Agent 友好** —— 你的编码 Agent（Claude Code、Codex、Copilot、Cursor 等）可以一等公民般地操作、扩展和部署 LangBot：
-
-- **MCP Server** —— LangBot 内置 [Model Context Protocol](https://modelcontextprotocol.io/) 端点 `/mcp`，与 HTTP API 对齐，Agent 可编程式管理机器人、流水线、插件和模型。使用同一套 API Key 鉴权（可在 `config.yaml` 配置全局 Key，或使用用户 Key），无需登录流程。在 Web 面板的 **API 与 MCP** 标签页中配置。
-- **仓库内 Skills** —— [`skills/`](skills/) 目录是使用 LangBot 的**唯一事实来源**：插件开发、核心开发、端到端测试、部署，以及操作 LangBot / LangBot Space MCP Server。把 Agent 指向这个目录，它就知道如何动手。
-- **AGENTS.md** —— 每个仓库都提供 [`AGENTS.md`](AGENTS.md)（软链到 `CLAUDE.md`），描述架构、规范，以及「API 变更必须同步更新 MCP Server 和 skills」的约定。
-- **`llms.txt`** —— 面向 LLM 的机器可读项目上下文已发布在官网。
-
-> **云端 / 市场：** [LangBot Space](https://space.langbot.app) 同样开放 MCP Server，Agent 可搜索和查看插件 / MCP / Skill 市场，使用 Personal Access Token 鉴权。
-
----
-
 ## 社区
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)

README_ES.md

@@ -35,10 +35,6 @@
 
 LangBot es una **plataforma de código abierto y grado de producción** para construir bots de mensajería instantánea impulsados por IA. Conecta modelos de lenguaje de gran escala (LLMs) con cualquier plataforma de chat, permitiéndole crear agentes inteligentes que pueden conversar, ejecutar tareas e integrarse con sus flujos de trabajo existentes.
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="Panel de gestión web de LangBot — monitoreo en tiempo real de volumen de mensajes, llamadas a modelos, tasa de éxito y sesiones activas" width="720"/>
-</p>
-
 ### Capacidades Clave
 
 - **Conversaciones e Agentes IA** — Diálogos de múltiples turnos, llamadas a herramientas, soporte multimodal, salida en streaming. RAG (base de conocimientos) incorporado con integración profunda con [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io), [Langflow](https://langflow.org), [Deerflow](https://deerflow.tech)、[Weknora](https://weknora.weixin.qq.com).
@@ -155,17 +151,6 @@ docker compose up -d
 
 *Nota: Entorno de demostración público. No ingrese información confidencial.*
 
-## Diseñado para Agentes de IA 🤖
-
-LangBot es **agent-friendly por diseño** —— tus agentes de codificación (Claude Code, Codex, Copilot, Cursor, …) pueden operar, extender y desplegar LangBot con soporte de primera clase:
-
-- **Servidor MCP** —— LangBot expone un endpoint integrado de [Model Context Protocol](https://modelcontextprotocol.io/) en `/mcp`, replicando la API HTTP para que un agente gestione bots, pipelines, plugins y modelos de forma programática. Autentícate con la misma API key (configura una clave global en `config.yaml` o usa una clave por usuario) —— sin flujo de login. Configúralo en la pestaña **API & MCP** del panel web.
-- **Skills en el repositorio** —— El directorio [`skills/`](skills/) es la **única fuente de verdad** para trabajar con LangBot: desarrollo de plugins, desarrollo del core, pruebas end-to-end, despliegue y operación de los servidores MCP de LangBot / LangBot Space. Apunta tu agente a este directorio y sabrá cómo construir.
-- **AGENTS.md** —— Cada repo incluye un [`AGENTS.md`](AGENTS.md) (enlazado simbólicamente a `CLAUDE.md`) que describe la arquitectura, las convenciones y la regla de que los cambios en la API deben mantener sincronizados el servidor MCP y los skills.
-- **`llms.txt`** —— El contexto del proyecto legible por máquina para LLMs está publicado en el sitio web.
-
-> **Nube / Marketplace:** [LangBot Space](https://space.langbot.app) también expone un servidor MCP para que los agentes busquen e inspeccionen el marketplace de plugins / MCP / skills, autenticados con un Personal Access Token.
-
 ---
 
 ## Comunidad

README_FR.md

@@ -35,10 +35,6 @@
 
 LangBot est une **plateforme open-source de niveau production** pour créer des bots de messagerie instantanée alimentés par l'IA. Elle connecte les grands modèles de langage (LLMs) à n'importe quelle plateforme de chat, vous permettant de créer des agents intelligents capables de converser, d'exécuter des tâches et de s'intégrer à vos workflows existants.
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="Tableau de bord de gestion web LangBot — surveillance en temps réel du volume de messages, des appels de modèles, du taux de réussite et des sessions actives" width="720"/>
-</p>
-
 ### Capacités Clés
 
 - **Conversations IA & Agents** — Dialogues multi-tours, appels d'outils, support multimodal, sortie en streaming. RAG (base de connaissances) intégré avec intégration profonde de [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io), [Langflow](https://langflow.org), [Deerflow](https://deerflow.tech), [Weknora](https://weknora.weixin.qq.com).
@@ -155,17 +151,6 @@ docker compose up -d
 
 *Note : Environnement de démonstration public. Ne saisissez pas d'informations sensibles.*
 
-## Conçu pour les agents IA 🤖
-
-LangBot est **agent-friendly par conception** —— vos agents de codage (Claude Code, Codex, Copilot, Cursor, …) peuvent exploiter, étendre et déployer LangBot avec un support de premier ordre :
-
-- **Serveur MCP** —— LangBot expose un endpoint [Model Context Protocol](https://modelcontextprotocol.io/) intégré sur `/mcp`, reflétant l'API HTTP pour qu'un agent gère bots, pipelines, plugins et modèles de façon programmatique. Authentifiez-vous avec la même clé API (définissez une clé globale dans `config.yaml` ou utilisez une clé par utilisateur) —— sans flux de connexion. Configurez-le dans l'onglet **API & MCP** du panneau web.
-- **Skills dans le dépôt** —— Le répertoire [`skills/`](skills/) est la **source unique de vérité** pour travailler avec LangBot : développement de plugins, développement du cœur, tests de bout en bout, déploiement et exploitation des serveurs MCP de LangBot / LangBot Space. Pointez votre agent vers ce répertoire et il saura construire.
-- **AGENTS.md** —— Chaque dépôt fournit un [`AGENTS.md`](AGENTS.md) (lien symbolique vers `CLAUDE.md`) décrivant l'architecture, les conventions et la règle selon laquelle les changements d'API doivent garder le serveur MCP et les skills synchronisés.
-- **`llms.txt`** —— Le contexte projet lisible par machine pour les LLM est publié sur le site web.
-
-> **Cloud / Marketplace :** [LangBot Space](https://space.langbot.app) expose également un serveur MCP pour que les agents recherchent et inspectent le marketplace de plugins / MCP / skills, authentifiés avec un Personal Access Token.
-
 ---
 
 ## Communauté

README_JP.md

@@ -35,10 +35,6 @@
 
 LangBot は、AI搭載のインスタントメッセージングボットを構築するための**オープンソースの本番グレードプラットフォーム**です。大規模言語モデル（LLM）をあらゆるチャットプラットフォームに接続し、会話、タスク実行、既存のワークフローとの統合が可能なインテリジェントエージェントを作成できます。
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="LangBot Web 管理パネルのダッシュボード — メッセージ量、モデル呼び出し、成功率、アクティブセッションをリアルタイム監視" width="720"/>
-</p>
-
 ### 主な機能
 
 - **AI対話とエージェント** — マルチターン対話、ツール呼び出し、マルチモーダル対応、ストリーミング出力。RAG（ナレッジベース）を内蔵し、[Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io)、[Langflow](https://langflow.org)、[Deerflow](https://deerflow.tech)、[Weknora](https://weknora.weixin.qq.com) と深く統合。
@@ -155,17 +151,6 @@ docker compose up -d
 
 *注意: 公開デモ環境です。機密情報を入力しないでください。*
 
-## AI エージェントのために 🤖
-
-LangBot は **設計段階からエージェントフレンドリー** です。お使いのコーディングエージェント（Claude Code、Codex、Copilot、Cursor など）が、ファーストクラスのサポートで LangBot を操作・拡張・デプロイできます：
-
-- **MCP サーバー** —— LangBot は組み込みの [Model Context Protocol](https://modelcontextprotocol.io/) エンドポイント `/mcp` を公開し、HTTP API とミラーリングされているため、エージェントがボット・パイプライン・プラグイン・モデルをプログラム的に管理できます。同じ API キーで認証（`config.yaml` でグローバルキーを設定、またはユーザーキーを使用）—— ログインフロー不要。Web パネルの **API & MCP** タブで設定します。
-- **リポジトリ内 Skills** —— [`skills/`](skills/) ディレクトリは LangBot を扱うための**唯一の信頼できる情報源**です：プラグイン開発、コア開発、E2E テスト、デプロイ、LangBot / LangBot Space MCP サーバーの操作。エージェントをこのディレクトリに向ければ、構築方法を理解します。
-- **AGENTS.md** —— すべてのリポジトリに [`AGENTS.md`](AGENTS.md)（`CLAUDE.md` へのシンボリックリンク）があり、アーキテクチャ・規約、そして「API 変更時は MCP サーバーと skills を同期する」というルールを記述しています。
-- **`llms.txt`** —— LLM 向けの機械可読なプロジェクトコンテキストを公式サイトで公開しています。
-
-> **クラウド / マーケット：** [LangBot Space](https://space.langbot.app) も MCP サーバーを公開しており、エージェントが Personal Access Token で認証してプラグイン / MCP / Skill マーケットを検索・確認できます。
-
 ---
 
 ## コミュニティ

README_KO.md

@@ -35,10 +35,6 @@
 
 LangBot은 AI 기반 인스턴트 메시징 봇을 구축하기 위한 **오픈소스 프로덕션 등급 플랫폼**입니다. 대규모 언어 모델(LLM)을 모든 채팅 플랫폼에 연결하여 대화, 작업 실행, 기존 워크플로우와의 통합이 가능한 지능형 에이전트를 만들 수 있습니다.
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="LangBot 웹 관리 패널 대시보드 — 메시지 양, 모델 호출, 성공률, 활성 세션 실시간 모니터링" width="720"/>
-</p>
-
 ### 핵심 기능
 
 - **AI 대화 및 에이전트** — 멀티턴 대화, 도구 호출, 멀티모달 지원, 스트리밍 출력. 내장 RAG(지식 베이스)와 [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io), [Langflow](https://langflow.org), [Deerflow](https://deerflow.tech), [Weknora](https://weknora.weixin.qq.com) 심층 통합.
@@ -155,17 +151,6 @@ docker compose up -d
 
 *참고: 공개 데모 환경입니다. 민감한 정보를 입력하지 마세요.*
 
-## AI 에이전트를 위한 설계 🤖
-
-LangBot은 **설계 단계부터 에이전트 친화적**입니다 —— 코딩 에이전트(Claude Code, Codex, Copilot, Cursor 등)가 일급 지원으로 LangBot을 운영·확장·배포할 수 있습니다:
-
-- **MCP 서버** —— LangBot은 내장 [Model Context Protocol](https://modelcontextprotocol.io/) 엔드포인트 `/mcp`를 제공하며, HTTP API와 동일하게 미러링되어 에이전트가 봇·파이프라인·플러그인·모델을 프로그래밍 방식으로 관리할 수 있습니다. 동일한 API 키로 인증하며(`config.yaml`에 전역 키 설정 또는 사용자 키 사용) 로그인 절차가 필요 없습니다. 웹 패널의 **API & MCP** 탭에서 설정합니다.
-- **저장소 내 Skills** —— [`skills/`](skills/) 디렉터리는 LangBot 작업의 **단일 진실 공급원**입니다: 플러그인 개발, 코어 개발, E2E 테스트, 배포, LangBot / LangBot Space MCP 서버 운영. 에이전트를 이 디렉터리로 안내하면 빌드 방법을 알게 됩니다.
-- **AGENTS.md** —— 모든 저장소에는 [`AGENTS.md`](AGENTS.md)(`CLAUDE.md`로 심볼릭 링크)가 있으며 아키텍처, 규약, 그리고 API 변경 시 MCP 서버와 skills를 동기화해야 한다는 규칙을 설명합니다.
-- **`llms.txt`** —— LLM을 위한 기계 판독 가능한 프로젝트 컨텍스트가 웹사이트에 게시되어 있습니다.
-
-> **클라우드 / 마켓플레이스:** [LangBot Space](https://space.langbot.app)도 MCP 서버를 제공하여 에이전트가 Personal Access Token으로 인증해 플러그인 / MCP / Skill 마켓플레이스를 검색하고 조회할 수 있습니다.
-
 ---
 
 ## 커뮤니티

README_RU.md

@@ -35,10 +35,6 @@
 
 LangBot — это **платформа с открытым исходным кодом производственного уровня** для создания ИИ-ботов в мессенджерах. Она связывает большие языковые модели (LLM) с любой чат-платформой, позволяя создавать интеллектуальных агентов, которые могут вести диалоги, выполнять задачи и интегрироваться с вашими существующими рабочими процессами.
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="Панель веб-управления LangBot — мониторинг объёма сообщений, вызовов моделей, успешности и активных сессий в реальном времени" width="720"/>
-</p>
-
 ### Ключевые возможности
 
 - **ИИ-диалоги и агенты** — Многораундовые диалоги, вызов инструментов, мультимодальная поддержка, потоковый вывод. Встроенная реализация RAG (база знаний) с глубокой интеграцией в [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io), [Langflow](https://langflow.org), [Deerflow](https://deerflow.tech), [Weknora](https://weknora.weixin.qq.com).
@@ -155,17 +151,6 @@ docker compose up -d
 
 *Примечание: Публичная демо-среда. Не вводите конфиденциальную информацию.*
 
-## Создано для ИИ-агентов 🤖
-
-LangBot **дружелюбен к агентам по своей архитектуре** —— ваши кодинг-агенты (Claude Code, Codex, Copilot, Cursor и др.) могут управлять, расширять и развёртывать LangBot с первоклассной поддержкой:
-
-- **MCP-сервер** —— LangBot предоставляет встроенную конечную точку [Model Context Protocol](https://modelcontextprotocol.io/) по адресу `/mcp`, зеркалирующую HTTP API, чтобы агент мог программно управлять ботами, пайплайнами, плагинами и моделями. Аутентификация той же API-ключом (задайте глобальный ключ в `config.yaml` или используйте пользовательский ключ) —— без процедуры входа. Настраивается на вкладке **API & MCP** веб-панели.
-- **Skills в репозитории** —— Каталог [`skills/`](skills/) является **единственным источником истины** для работы с LangBot: разработка плагинов, разработка ядра, сквозное тестирование, развёртывание и работа с MCP-серверами LangBot / LangBot Space. Направьте агента в этот каталог, и он будет знать, как собирать.
-- **AGENTS.md** —— Каждый репозиторий содержит [`AGENTS.md`](AGENTS.md) (символическая ссылка на `CLAUDE.md`), описывающий архитектуру, соглашения и правило: изменения API должны синхронизировать MCP-сервер и skills.
-- **`llms.txt`** —— Машиночитаемый контекст проекта для LLM опубликован на сайте.
-
-> **Облако / Маркетплейс:** [LangBot Space](https://space.langbot.app) также предоставляет MCP-сервер, чтобы агенты могли искать и просматривать маркетплейс плагинов / MCP / skills, аутентифицируясь с помощью Personal Access Token.
-
 ---
 
 ## Сообщество

README_TW.md

@@ -37,10 +37,6 @@
 
 LangBot 是一個**開源的生產級平台**，用於建構 AI 驅動的即時通訊機器人。它將大語言模型（LLM）連接到各種聊天平台，幫助你創建能夠對話、執行任務、並整合到現有工作流程中的智能 Agent。
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="LangBot Web 管理面板儀表板 — 即時監控訊息量、模型調用、成功率與活躍工作階段" width="720"/>
-</p>
-
 ### 核心能力
 
 - **AI 對話與 Agent** — 多輪對話、工具調用、多模態、流式輸出。自帶 RAG（知識庫），深度整合 [Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io)、[Langflow](https://langflow.org)、 [Deerflow](https://deerflow.tech)、[Weknora](https://weknora.weixin.qq.com)等 LLMOps 平台。
@@ -171,17 +167,6 @@ docker compose up -d
 
 *注意：公開演示環境，請不要在其中填入任何敏感資訊。*
 
-## 為 AI Agent 而生 🤖
-
-LangBot **從設計上就對 Agent 友善** —— 你的編碼 Agent（Claude Code、Codex、Copilot、Cursor 等）可以一等公民般地操作、擴充和部署 LangBot：
-
-- **MCP Server** —— LangBot 內建 [Model Context Protocol](https://modelcontextprotocol.io/) 端點 `/mcp`，與 HTTP API 對齊，Agent 可程式化管理機器人、流水線、外掛和模型。使用同一套 API Key 鑑權（可在 `config.yaml` 設定全域 Key，或使用使用者 Key），無需登入流程。在 Web 面板的 **API 與 MCP** 分頁中設定。
-- **倉庫內 Skills** —— [`skills/`](skills/) 目錄是使用 LangBot 的**唯一事實來源**：外掛開發、核心開發、端到端測試、部署，以及操作 LangBot / LangBot Space MCP Server。把 Agent 指向這個目錄，它就知道如何動手。
-- **AGENTS.md** —— 每個倉庫都提供 [`AGENTS.md`](AGENTS.md)（軟連結到 `CLAUDE.md`），描述架構、規範，以及「API 變更必須同步更新 MCP Server 和 skills」的約定。
-- **`llms.txt`** —— 面向 LLM 的機器可讀專案上下文已發布在官網。
-
-> **雲端 / 市集：** [LangBot Space](https://space.langbot.app) 同樣開放 MCP Server，Agent 可搜尋和檢視外掛 / MCP / Skill 市集，使用 Personal Access Token 鑑權。
-
 ---
 
 ## 社群

README_VI.md

@@ -35,10 +35,6 @@
 
 LangBot là một **nền tảng mã nguồn mở, cấp sản xuất** để xây dựng bot nhắn tin tức thời được hỗ trợ bởi AI. Nó kết nối các Mô hình Ngôn ngữ Lớn (LLM) với bất kỳ nền tảng chat nào, cho phép bạn tạo các agent thông minh có thể trò chuyện, thực hiện tác vụ và tích hợp với quy trình làm việc hiện có của bạn.
 
-<p align="center">
-<img src="res/dashboard-overview.png" alt="Bảng điều khiển quản lý web LangBot — giám sát thời gian thực khối lượng tin nhắn, lệnh gọi mô hình, tỷ lệ thành công và phiên hoạt động" width="720"/>
-</p>
-
 ### Khả năng chính
 
 - **Hội thoại AI & Agent** — Đối thoại nhiều lượt, gọi công cụ, hỗ trợ đa phương thức, đầu ra streaming. RAG (cơ sở kiến thức) tích hợp sẵn với tích hợp sâu vào [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io), [Langflow](https://langflow.org), [Deerflow](https://deerflow.tech), [Weknora](https://weknora.weixin.qq.com).
@@ -155,17 +151,6 @@ docker compose up -d
 
 *Lưu ý: Môi trường demo công khai. Không nhập thông tin nhạy cảm.*
 
-## Được xây dựng cho AI Agent 🤖
-
-LangBot **thân thiện với agent ngay từ thiết kế** —— các coding agent của bạn (Claude Code, Codex, Copilot, Cursor, …) có thể vận hành, mở rộng và triển khai LangBot với sự hỗ trợ hạng nhất:
-
-- **MCP Server** —— LangBot cung cấp endpoint [Model Context Protocol](https://modelcontextprotocol.io/) tích hợp tại `/mcp`, phản chiếu HTTP API để agent quản lý bot, pipeline, plugin và model theo cách lập trình. Xác thực bằng cùng một API key (đặt key toàn cục trong `config.yaml` hoặc dùng key theo người dùng) —— không cần luồng đăng nhập. Cấu hình tại tab **API & MCP** trong bảng điều khiển Web.
-- **Skills trong repo** —— Thư mục [`skills/`](skills/) là **nguồn sự thật duy nhất** để làm việc với LangBot: phát triển plugin, phát triển core, kiểm thử end-to-end, triển khai và vận hành MCP Server của LangBot / LangBot Space. Trỏ agent của bạn vào thư mục này và nó sẽ biết cách xây dựng.
-- **AGENTS.md** —— Mỗi repo đều có [`AGENTS.md`](AGENTS.md) (liên kết tượng trưng tới `CLAUDE.md`) mô tả kiến trúc, quy ước và quy tắc rằng thay đổi API phải giữ MCP Server và skills đồng bộ.
-- **`llms.txt`** —— Ngữ cảnh dự án có thể đọc bằng máy dành cho LLM được công bố trên website.
-
-> **Cloud / Marketplace:** [LangBot Space](https://space.langbot.app) cũng cung cấp MCP Server để agent tìm kiếm và kiểm tra marketplace plugin / MCP / skill, xác thực bằng Personal Access Token.
-
 ---
 
 ## Cộng đồng

docs/API_KEY_AUTH.md

@@ -10,38 +10,6 @@ API keys can be managed through the web interface:
 2. Click the "API Keys" button at the bottom of the sidebar
 3. Create, view, copy, or delete API keys as needed
 
-## Global API Key (config.yaml)
-
-In addition to web-UI-created keys (stored in the database, prefixed `lbk_`),
-LangBot supports a **global API key** defined directly in `data/config.yaml`.
-This is useful for automated deployments, infrastructure-as-code, and AI agents
-that need API/MCP access **without a login session and without creating a
-database record first**.
-
-```yaml
-api:
-    port: 5300
-    # ...
-    global_api_key: 'your-strong-secret-here'   # leave empty to disable
-```
-
-Behavior:
-
-- When `api.global_api_key` is a non-empty string, that exact value is accepted
-  anywhere a normal API key is accepted — the `X-API-Key` header or
-  `Authorization: Bearer <key>` — across the HTTP service API **and the MCP
-  server**.
-- The global key does **not** require the `lbk_` prefix; use any sufficiently
-  strong secret.
-- Leave it empty (`''`, the default) to disable it entirely; only database-backed
-  `lbk_` keys will then be accepted.
-- Existing installs are unaffected until you add the key — config completion only
-  backfills top-level keys, and the lookup is defensive when the field is absent.
-
-> **Security:** the global key is stored in plaintext in `config.yaml`. Only
-> enable it on trusted/internal deployments, keep the file permissions tight,
-> always serve over HTTPS, and rotate the value if it may have leaked.
-
 ## Using API Keys
 
 ### Authentication Headers

docs/event-based-agents/00-overview.md

@@ -0,0 +1,200 @@
+# Event Based Agents 架构设计总览
+
+## 1. 背景与动机
+
+### 当前架构的局限性
+
+LangBot 当前的平台适配器架构围绕**消息事件**单一场景设计：
+
+- **事件层面**：只监听 `FriendMessage`（私聊消息）和 `GroupMessage`（群消息）两种事件
+- **API 层面**：只暴露 `send_message` 和 `reply_message` 两个平台 API
+- **处理层面**：所有消息统一进入 Pipeline 流水线处理，无法为不同事件类型配置不同处理逻辑
+- **适配器结构**：每个适配器是单个 Python 文件（200-800 行），随着功能增加难以维护
+
+这导致以下问题：
+
+1. **无法处理非消息事件**：新成员入群、好友请求、消息撤回、消息编辑等大部分平台都支持的事件被完全忽略
+2. **平台能力未充分利用**：编辑消息、撤回消息、获取群成员列表、管理群组等 API 无法使用
+3. **插件能力受限**：插件只能监听消息事件、只能发送/回复消息，无法实现更丰富的交互
+4. **处理逻辑不灵活**：所有消息走同一条 Pipeline，无法为入群欢迎、好友自动通过等场景配置独立的处理流程
+
+### 设计目标
+
+Event Based Agents（EBA）架构旨在将 LangBot 从"消息处理平台"升级为"事件驱动的智能代理平台"：
+
+- **丰富事件**：支持消息、群组、好友、Bot 状态等多种事件类型
+- **丰富 API**：支持消息编辑/撤回、群组管理、用户信息查询等通用 API，以及适配器特有 API 的透传调用
+- **灵活编排**：用户可在 WebUI 上为每个 Bot 的每种事件类型配置不同的处理器
+- **可扩展**：适配器可声明自己支持的事件和 API，平台特有能力通过标准机制暴露
+- **向后兼容**：现有插件无需修改即可在新架构下运行
+
+## 2. 架构对比
+
+### 现有架构
+
+```
+消息平台 (Telegram/Discord/...)
+    │
+    ▼
+平台适配器 (单文件, 只处理消息)
+    │ FriendMessage / GroupMessage
+    ▼
+RuntimeBot (注册 on_friend_message / on_group_message 回调)
+    │
+    ▼
+MessageAggregator (消息聚合)
+    │
+    ▼
+QueryPool → Controller → Pipeline (固定阶段链)
+    │                         │
+    │                         ▼
+    │                    RequestRunner (local-agent / dify / n8n / ...)
+    │
+    ▼
+adapter.reply_message() / adapter.send_message()
+```
+
+关键代码路径：
+- 适配器基类：`langbot-plugin-sdk/.../abstract/platform/adapter.py` — `AbstractMessagePlatformAdapter`
+- 事件定义：`langbot-plugin-sdk/.../builtin/platform/events.py` — 仅 `FriendMessage` / `GroupMessage`
+- Bot 管理：`LangBot/src/langbot/pkg/platform/botmgr.py` — `RuntimeBot` 只注册两个消息回调
+- 流水线控制：`LangBot/src/langbot/pkg/pipeline/controller.py` — 从 QueryPool 消费并执行 Pipeline
+
+### 新架构（Event Based Agents）
+
+```
+消息平台 (Telegram/Discord/...)
+    │
+    ▼
+平台适配器 (独立目录, 监听所有事件, 实现丰富 API)
+    │ MessageReceived / MemberJoined / FriendRequest / ...
+    ▼
+EventBus (统一事件总线)
+    │
+    ▼
+EventRouter (事件路由引擎, 读取 Bot 的 event_handlers 配置)
+    │
+    ├─→ PipelineHandler   — 现有流水线（完整 Stage 链）
+    ├─→ AgentHandler      — 直接调用 RequestRunner（轻量 AI 处理）
+    ├─→ WebhookHandler    — POST 到外部服务（Dify/n8n webhook 等）
+    └─→ PluginHandler     — 分发给插件 EventListener
+    │
+    ▼
+统一平台 API
+  send / reply / edit / delete / getGroupInfo / getUserInfo / callPlatformApi / ...
+```
+
+## 3. 核心概念
+
+### 3.1 统一事件体系
+
+所有平台事件统一为命名空间式的事件类型：
+
+| 命名空间 | 事件 | 说明 |
+|----------|------|------|
+| `message.*` | `message.received`, `message.edited`, `message.deleted`, `message.reaction` | 消息相关 |
+| `feedback.*` | `feedback.received` | 用户对 Bot 回复的点赞、点踩、取消反馈等评价事件 |
+| `group.*` | `group.member_joined`, `group.member_left`, `group.member_banned`, `group.info_updated` | 群组相关 |
+| `friend.*` | `friend.request_received`, `friend.added`, `friend.removed` | 好友相关 |
+| `bot.*` | `bot.invited_to_group`, `bot.removed_from_group`, `bot.muted`, `bot.unmuted` | Bot 状态 |
+| `platform.*` | `platform.{adapter}.{action}` | 适配器特有事件 |
+
+详见 [01-event-system.md](./01-event-system.md)。
+
+### 3.2 统一平台 API
+
+扩展适配器基类，提供通用 API + 透传机制：
+
+| 类别 | API | 必需/可选 |
+|------|-----|----------|
+| 消息 | `send_message`, `reply_message`, `edit_message`, `delete_message`, `forward_message` | send/reply 必需，其余可选 |
+| 群组 | `get_group_info`, `get_group_member_list`, `get_group_member_info`, `mute_member`, `kick_member` | 全部可选 |
+| 用户 | `get_user_info`, `get_friend_list` | 全部可选 |
+| 媒体 | `upload_file`, `get_file_url` | 全部可选 |
+| 透传 | `call_platform_api(action, params)` | 可选 |
+
+详见 [02-platform-api.md](./02-platform-api.md)。
+
+### 3.3 适配器新结构
+
+每个适配器从单文件迁移到独立目录：
+
+```
+pkg/platform/adapters/
+├── _base/                    # 基类和通用定义
+│   ├── adapter.py
+│   ├── events.py
+│   ├── entities.py
+│   └── api.py
+├── telegram/
+│   ├── __init__.py
+│   ├── adapter.py            # 主适配器类
+│   ├── event_converter.py    # 事件转换（多种事件类型）
+│   ├── message_converter.py  # 消息链转换
+│   ├── api_impl.py           # 通用 API 实现
+│   ├── platform_api.py       # 平台特有 API
+│   ├── types.py              # 平台特有类型
+│   └── manifest.yaml
+├── discord/
+│   └── ...
+```
+
+详见 [03-adapter-structure.md](./03-adapter-structure.md)。
+
+### 3.4 事件处理器（Event Handler）
+
+> **2026-06 方向修订**：四种处理器的分类法已演进为「事件 → Agent」统一编排——所有编排目标（流水线、RequestRunner、webhook、工作流）收编为 Agent 抽象，插件 EventListener 保留为观察者角色。详见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本节保留原设计供对照。
+
+四种处理器类型，用户在 WebUI 的 Bot 管理页面配置：
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| **pipeline** | 现有流水线机制，完整的多 Stage 处理链（PreProcessor → MessageProcessor → PostProcessor 等） | 复杂消息处理，需要完整的预处理/后处理流程 |
+| **agent** | 直接调用 RequestRunner（local-agent / dify / n8n / coze / dashscope / langflow / tbox），从 Pipeline 中解耦 | 轻量级 AI 处理、直接对接外部 LLMOps 平台处理各类事件 |
+| **webhook** | 将事件 POST 到外部 URL，根据响应执行动作 | 对接自建服务、Dify/n8n 的 Webhook 触发器、自定义后端 |
+| **plugin** | 分发给插件 EventListener 处理 | 插件自定义逻辑 |
+
+配置存储在 Bot 表的 `event_handlers` JSON 字段中，通过 WebUI 编排面板管理。
+
+详见 [04-event-routing.md](./04-event-routing.md)。
+
+### 3.5 插件 SDK 改造
+
+- 新事件类型全部暴露给插件
+- 新 API 全部通过 `LangBotAPIProxy` 暴露
+- 兼容层保证现有插件零修改运行
+
+详见 [05-plugin-sdk.md](./05-plugin-sdk.md)。
+
+## 4. 关键设计决策
+
+| # | 决策点 | 选择 | 理由 |
+|---|--------|------|------|
+| 1 | 事件处理器配置粒度 | 每个 Bot 独立配置 | Bot 是用户操作的核心单元，不同 Bot 可能对接不同业务场景 |
+| 2 | 适配器特有 API | 统一抽象 + `call_platform_api` 透传 | 通用 API 覆盖大部分场景，透传机制保证灵活性，避免每个适配器导出独立的类型化 API 包 |
+| 3 | 向后兼容策略 | 兼容层适配 | 保留旧事件类型和 API 作为新系统的 alias/wrapper，现有插件无需修改 |
+| 4 | 处理器配置存储 | Bot 表新增 `event_handlers` JSON 字段 | 简单直接，避免新增关联表；替代现有 `use_pipeline_uuid` |
+| 5 | Agent 处理器定位 | 从 Pipeline 中解耦 RequestRunner | 不是所有事件都需要完整 Pipeline Stage 链；Agent 处理器提供轻量级 AI 处理路径，支持所有现有 Runner |
+| 6 | 事件命名方式 | 命名空间式（`message.received`） | 清晰的分类层级，便于通配匹配（`message.*`），与 WebUI 配置天然对应 |
+
+## 5. 文档索引
+
+| 文档 | 内容 |
+|------|------|
+| [01-event-system.md](./01-event-system.md) | 统一事件体系：事件分类、定义、生命周期 |
+| [02-platform-api.md](./02-platform-api.md) | 统一平台 API：通用 API、透传 API、实体定义 |
+| [03-adapter-structure.md](./03-adapter-structure.md) | 适配器新结构：目录布局、基类、注册机制 |
+| [04-event-routing.md](./04-event-routing.md) | 事件路由与编排：路由引擎、处理器类型、WebUI 数据模型 |
+| [05-plugin-sdk.md](./05-plugin-sdk.md) | 插件 SDK 改造：新事件/API、兼容层 |
+| [06-migration-plan.md](./06-migration-plan.md) | 分阶段迁移计划 |
+| [07-agent-orchestration.md](./07-agent-orchestration.md) | **产品最终形态（2026-06 修订）**：Agent 统一编排、SDK Agent 组件契约、发布火车 |
+
+## 6. 涉及的代码仓库
+
+| 仓库 | 改动范围 |
+|------|----------|
+| **langbot-plugin-sdk** | 事件定义、实体模型、API 接口、适配器基类、通信协议扩展 |
+| **LangBot**（后端） | 适配器实现、事件路由引擎、Bot 实体扩展、数据库迁移、RequestRunner 解耦 |
+| **LangBot**（前端） | Bot 事件处理器编排面板 |
+| **langbot-wiki** | 新架构文档、插件开发指南更新、适配器开发指南 |
+| **langbot-plugin-demo** | 示例更新（使用新事件和 API） |

docs/event-based-agents/01-event-system.md

@@ -0,0 +1,561 @@
+# 统一事件体系
+
+## 1. 设计原则
+
+- **命名空间分类**：事件类型采用 `{namespace}.{action}` 格式，如 `message.received`
+- **通用优先**：大部分平台都支持的事件抽象为通用事件，定义统一的字段格式
+- **平台特有事件标准化**：各适配器的独有事件通过 `PlatformSpecificEvent` 承载，保留原始数据
+- **向后兼容**：现有 `FriendMessage` / `GroupMessage` 通过兼容层映射到新的 `message.received` 事件
+
+## 2. 事件基类层次
+
+```
+Event (事件基类)
+├── MessageEvent (消息相关事件)
+│   ├── MessageReceivedEvent       # message.received
+│   ├── MessageEditedEvent         # message.edited
+│   ├── MessageDeletedEvent        # message.deleted
+│   └── MessageReactionEvent       # message.reaction
+├── FeedbackEvent (用户反馈事件)
+│   └── FeedbackReceivedEvent      # feedback.received
+├── GroupEvent (群组相关事件)
+│   ├── MemberJoinedEvent          # group.member_joined
+│   ├── MemberLeftEvent            # group.member_left
+│   ├── MemberBannedEvent          # group.member_banned
+│   ├── MemberUnbannedEvent        # group.member_unbanned
+│   └── GroupInfoUpdatedEvent      # group.info_updated
+├── FriendEvent (好友相关事件)
+│   ├── FriendRequestReceivedEvent # friend.request_received
+│   ├── FriendAddedEvent           # friend.added
+│   └── FriendRemovedEvent         # friend.removed
+├── BotEvent (Bot 状态事件)
+│   ├── BotInvitedToGroupEvent     # bot.invited_to_group
+│   ├── BotRemovedFromGroupEvent   # bot.removed_from_group
+│   ├── BotMutedEvent              # bot.muted
+│   └── BotUnmutedEvent            # bot.unmuted
+└── PlatformSpecificEvent          # platform.{adapter}.{action}
+```
+
+## 3. 通用事件定义
+
+### 3.1 事件基类
+
+```python
+class Event(pydantic.BaseModel):
+    """事件基类"""
+
+    type: str
+    """事件类型标识，如 'message.received'"""
+
+    timestamp: float
+    """事件发生的时间戳"""
+
+    bot_uuid: str
+    """接收到此事件的 Bot UUID"""
+
+    adapter_name: str
+    """产生此事件的适配器名称"""
+
+    source_platform_object: typing.Optional[typing.Any] = None
+    """原始平台事件对象，供适配器内部使用"""
+```
+
+### 3.2 消息事件
+
+#### MessageReceivedEvent (`message.received`)
+
+收到新消息。这是最核心的事件，替代现有的 `FriendMessage` / `GroupMessage`。
+
+```python
+class MessageReceivedEvent(Event):
+    """收到新消息"""
+
+    type: str = "message.received"
+
+    message_id: typing.Union[int, str]
+    """消息 ID"""
+
+    message_chain: MessageChain
+    """消息内容"""
+
+    sender: User
+    """发送者"""
+
+    chat_type: ChatType  # "private" | "group"
+    """会话类型"""
+
+    chat_id: typing.Union[int, str]
+    """会话 ID（私聊为对方用户 ID，群聊为群 ID）"""
+
+    group: typing.Optional[Group] = None
+    """群信息（仅群聊时存在）"""
+```
+
+与现有类型的映射关系：
+- `chat_type == "private"` → 等价于现有 `FriendMessage`
+- `chat_type == "group"` → 等价于现有 `GroupMessage`
+
+`ChatType` 枚举：
+
+```python
+class ChatType(str, Enum):
+    PRIVATE = "private"
+    GROUP = "group"
+```
+
+#### MessageEditedEvent (`message.edited`)
+
+消息被编辑。
+
+```python
+class MessageEditedEvent(Event):
+    """消息被编辑"""
+
+    type: str = "message.edited"
+
+    message_id: typing.Union[int, str]
+    """被编辑的消息 ID"""
+
+    new_content: MessageChain
+    """编辑后的新内容"""
+
+    editor: User
+    """编辑者"""
+
+    chat_type: ChatType
+    chat_id: typing.Union[int, str]
+    group: typing.Optional[Group] = None
+```
+
+#### MessageDeletedEvent (`message.deleted`)
+
+消息被删除/撤回。
+
+```python
+class MessageDeletedEvent(Event):
+    """消息被删除/撤回"""
+
+    type: str = "message.deleted"
+
+    message_id: typing.Union[int, str]
+    """被删除的消息 ID"""
+
+    operator: typing.Optional[User] = None
+    """操作者（可能是发送者自己撤回，也可能是管理员删除）"""
+
+    chat_type: ChatType
+    chat_id: typing.Union[int, str]
+    group: typing.Optional[Group] = None
+```
+
+#### MessageReactionEvent (`message.reaction`)
+
+消息收到表情回应。
+
+```python
+class MessageReactionEvent(Event):
+    """消息收到表情回应"""
+
+    type: str = "message.reaction"
+
+    message_id: typing.Union[int, str]
+    """被回应的消息 ID"""
+
+    user: User
+    """回应者"""
+
+    reaction: str
+    """回应的表情标识（emoji 或平台特定表情 ID）"""
+
+    is_add: bool
+    """True 为添加回应，False 为移除回应"""
+
+    chat_type: ChatType
+    chat_id: typing.Union[int, str]
+    group: typing.Optional[Group] = None
+```
+
+### 3.3 用户反馈事件
+
+#### FeedbackReceivedEvent (`feedback.received`)
+
+用户对 Bot 回复提交反馈。该事件用于承载平台提供的点赞、点踩、取消反馈以及点踩原因等评价信息；典型来源包括企业微信 AI Bot 的 `feedback_event`、飞书卡片按钮回调、Web Embed 的反馈入口等。
+
+```python
+class FeedbackReceivedEvent(Event):
+    """收到用户反馈"""
+
+    type: str = "feedback.received"
+
+    feedback_id: str
+    """平台侧反馈 ID，用于幂等记录或取消反馈"""
+
+    feedback_type: int
+    """1 = like, 2 = dislike, 3 = cancel/remove feedback"""
+
+    feedback_content: typing.Optional[str] = None
+    """用户填写的自由文本反馈"""
+
+    inaccurate_reasons: typing.Optional[list[str]] = None
+    """点踩时平台提供的预设不准确原因"""
+
+    user_id: typing.Optional[str] = None
+    """提交反馈的用户 ID"""
+
+    session_id: typing.Optional[str] = None
+    """会话 ID，例如 person_xxx 或 group_xxx"""
+
+    message_id: typing.Optional[str] = None
+    """被评价的 Bot 回复消息 ID"""
+
+    stream_id: typing.Optional[str] = None
+    """流式回复 ID，用于关联 streaming response"""
+```
+
+设计约定：
+
+- `feedback_id` 是幂等键；同一个 `feedback_id` 的后续事件应更新已有记录。
+- `feedback_type == 3` 表示用户取消/移除反馈，处理器可删除对应记录或标记为取消。
+- 如果平台只能给出原始回调 payload，差异字段保留在 `source_platform_object` 或 `PlatformSpecificEvent.data` 中；通用字段仍优先映射到 `FeedbackReceivedEvent`。
+- 该事件保留向后兼容映射：EBA 事件可转换为旧的 `FeedbackEvent`，字段语义保持一致。
+
+### 3.4 群组事件
+
+#### MemberJoinedEvent (`group.member_joined`)
+
+新成员加入群组。
+
+```python
+class MemberJoinedEvent(Event):
+    """新成员加入群组"""
+
+    type: str = "group.member_joined"
+
+    group: Group
+    """群组"""
+
+    member: User
+    """加入的成员"""
+
+    inviter: typing.Optional[User] = None
+    """邀请者（如有）"""
+
+    join_type: typing.Optional[str] = None
+    """加入方式：'invite' / 'request' / 'direct' / None"""
+```
+
+#### MemberLeftEvent (`group.member_left`)
+
+成员离开群组。
+
+```python
+class MemberLeftEvent(Event):
+    """成员离开群组"""
+
+    type: str = "group.member_left"
+
+    group: Group
+    member: User
+
+    is_kicked: bool = False
+    """是否被踢出"""
+
+    operator: typing.Optional[User] = None
+    """操作者（踢出时为管理员）"""
+```
+
+#### MemberBannedEvent (`group.member_banned`)
+
+成员被禁言。
+
+```python
+class MemberBannedEvent(Event):
+    """成员被禁言"""
+
+    type: str = "group.member_banned"
+
+    group: Group
+    member: User
+    operator: typing.Optional[User] = None
+    duration: typing.Optional[int] = None
+    """禁言时长（秒），None 表示永久"""
+```
+
+#### MemberUnbannedEvent (`group.member_unbanned`)
+
+成员被解除禁言。
+
+```python
+class MemberUnbannedEvent(Event):
+    """成员被解除禁言"""
+
+    type: str = "group.member_unbanned"
+
+    group: Group
+    member: User
+    operator: typing.Optional[User] = None
+```
+
+#### GroupInfoUpdatedEvent (`group.info_updated`)
+
+群组信息被修改。
+
+```python
+class GroupInfoUpdatedEvent(Event):
+    """群组信息被修改"""
+
+    type: str = "group.info_updated"
+
+    group: Group
+    """更新后的群组信息"""
+
+    operator: typing.Optional[User] = None
+    """操作者"""
+
+    changed_fields: list[str] = []
+    """发生变更的字段名列表，如 ['name', 'description']"""
+```
+
+### 3.5 好友事件
+
+#### FriendRequestReceivedEvent (`friend.request_received`)
+
+收到好友请求。
+
+```python
+class FriendRequestReceivedEvent(Event):
+    """收到好友请求"""
+
+    type: str = "friend.request_received"
+
+    request_id: typing.Union[int, str]
+    """请求 ID，用于后续 approve/reject 操作"""
+
+    user: User
+    """请求者"""
+
+    message: typing.Optional[str] = None
+    """验证消息"""
+```
+
+#### FriendAddedEvent (`friend.added`)
+
+成功添加好友。
+
+```python
+class FriendAddedEvent(Event):
+    """成功添加好友"""
+
+    type: str = "friend.added"
+
+    user: User
+    """新好友"""
+```
+
+#### FriendRemovedEvent (`friend.removed`)
+
+好友被移除。
+
+```python
+class FriendRemovedEvent(Event):
+    """好友被移除"""
+
+    type: str = "friend.removed"
+
+    user: User
+    """被移除的好友"""
+```
+
+### 3.6 Bot 状态事件
+
+#### BotInvitedToGroupEvent (`bot.invited_to_group`)
+
+Bot 被邀请加入群组。
+
+```python
+class BotInvitedToGroupEvent(Event):
+    """Bot 被邀请加入群组"""
+
+    type: str = "bot.invited_to_group"
+
+    group: Group
+    inviter: typing.Optional[User] = None
+
+    request_id: typing.Optional[typing.Union[int, str]] = None
+    """邀请请求 ID，某些平台需要 Bot 确认才加入"""
+```
+
+#### BotRemovedFromGroupEvent (`bot.removed_from_group`)
+
+Bot 被移出群组。
+
+```python
+class BotRemovedFromGroupEvent(Event):
+    """Bot 被移出群组"""
+
+    type: str = "bot.removed_from_group"
+
+    group: Group
+    operator: typing.Optional[User] = None
+```
+
+#### BotMutedEvent / BotUnmutedEvent (`bot.muted` / `bot.unmuted`)
+
+Bot 被禁言/解除禁言。
+
+```python
+class BotMutedEvent(Event):
+    """Bot 被禁言"""
+
+    type: str = "bot.muted"
+
+    group: Group
+    operator: typing.Optional[User] = None
+    duration: typing.Optional[int] = None
+
+
+class BotUnmutedEvent(Event):
+    """Bot 被解除禁言"""
+
+    type: str = "bot.unmuted"
+
+    group: Group
+    operator: typing.Optional[User] = None
+```
+
+### 3.7 平台特有事件
+
+对于无法抽象为通用事件的平台特有事件，使用统一的 `PlatformSpecificEvent` 承载：
+
+```python
+class PlatformSpecificEvent(Event):
+    """平台特有事件
+
+    适配器无法映射到通用事件类型时，使用此类型承载。
+    插件可以通过 adapter_name + action 来识别和处理。
+    """
+
+    type: str = "platform.specific"
+
+    action: str
+    """平台特有的事件动作标识，如 'channel_created', 'pin_message'"""
+
+    data: dict = {}
+    """事件数据，结构由具体适配器定义"""
+```
+
+事件类型字符串格式为 `platform.{adapter_name}.{action}`，例如：
+- `platform.telegram.chat_member_updated` — Telegram 的群成员信息更新
+- `platform.discord.channel_created` — Discord 的频道创建
+- `platform.discord.voice_state_update` — Discord 的语音状态变更
+- `platform.slack.app_home_opened` — Slack 的 App Home 打开
+
+## 4. 各平台事件支持矩阵
+
+下表标注各通用事件在主要平台上的支持情况：
+
+| 事件 | Telegram | Discord | OneBot(QQ) | 飞书 | 钉钉 | Slack | 微信 | LINE | KOOK |
+|------|----------|---------|-----------|------|------|-------|------|------|------|
+| `message.received` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `message.edited` | Y | Y | N | Y | N | Y | N | N | Y |
+| `message.deleted` | Y | Y | Y | Y | N | Y | Y | N | Y |
+| `message.reaction` | Y | Y | Y | Y | Y | Y | N | N | Y |
+| `feedback.received` | N | N | N | Y | N | N | Y | N | N |
+| `group.member_joined` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `group.member_left` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `group.member_banned` | Y | Y | Y | N | N | N | N | N | N |
+| `group.info_updated` | Y | Y | Y | Y | Y | Y | N | N | Y |
+| `friend.request_received` | N | Y | Y | N | N | N | Y | Y | Y |
+| `friend.added` | N | Y | Y | N | N | N | Y | Y | N |
+| `bot.invited_to_group` | Y | Y | Y | Y | Y | Y | Y | N | Y |
+| `bot.removed_from_group` | Y | Y | Y | Y | N | N | Y | N | Y |
+| `bot.muted` | Y | N | Y | N | N | N | N | N | N |
+| `bot.unmuted` | Y | N | Y | N | N | N | N | N | N |
+| `platform.specific` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+
+> 注：此表为初步评估，具体以各平台 SDK/API 文档为准，实施时逐个确认。
+
+## 5. 事件生命周期
+
+```
+1. 平台 SDK 回调触发
+      │
+2. 适配器 EventConverter.target2yiri(raw_event)
+      │  将平台原生事件转换为统一 Event 对象
+      │  无法映射的事件 → PlatformSpecificEvent
+      │
+3. 适配器回调注册的 listener(event, adapter)
+      │
+4. RuntimeBot 接收事件
+      │
+5. EventBus 分发
+      │
+6. EventRouter 查询 Bot 的 event_handlers 配置
+      │  匹配事件类型 → 找到对应的 Handler
+      │  支持通配符：'message.*' 匹配所有消息事件
+      │  未匹配到 → 走默认 Handler（plugin，保持向后兼容）
+      │
+7. Handler 处理事件
+      │  PipelineHandler → 进入 Pipeline 流水线
+      │  AgentHandler    → 调用 RequestRunner
+      │  WebhookHandler  → POST 到外部 URL
+      │  PluginHandler   → 分发给插件 EventListener
+      │
+8. Handler 执行完毕，可能通过 API 执行响应动作
+      （发消息、编辑消息、踢人、同意好友请求等）
+```
+
+## 6. 与现有事件类型的兼容映射
+
+为保证现有插件不受影响，建立以下映射关系：
+
+| 新事件 | 条件 | 旧事件 |
+|--------|------|--------|
+| `MessageReceivedEvent` (chat_type=private) | — | `FriendMessage` |
+| `MessageReceivedEvent` (chat_type=group) | — | `GroupMessage` |
+
+在插件 SDK 层面：
+
+| 新事件 | 旧插件事件 |
+|--------|-----------|
+| `MessageReceivedEvent` (chat_type=private, 非命令) | `PersonNormalMessageReceived` |
+| `MessageReceivedEvent` (chat_type=group, 非命令) | `GroupNormalMessageReceived` |
+| `MessageReceivedEvent` (chat_type=private, 命令) | `PersonCommandSent` |
+| `MessageReceivedEvent` (chat_type=group, 命令) | `GroupCommandSent` |
+| `MessageReceivedEvent` (处理完毕后) | `NormalMessageResponded` |
+
+兼容层在事件分发给插件 EventListener 时自动生成旧格式事件，确保监听旧事件类型的插件仍能正常工作。
+
+## 7. 事件类型注册表
+
+适配器在 manifest.yaml 中声明自己支持的事件类型：
+
+```yaml
+kind: MessagePlatformAdapter
+metadata:
+  name: telegram
+spec:
+  supported_events:
+    - message.received
+    - message.edited
+    - message.deleted
+    - message.reaction
+    - feedback.received
+    - group.member_joined
+    - group.member_left
+    - group.member_banned
+    - group.info_updated
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - bot.muted
+    - bot.unmuted
+    - platform.specific
+  platform_specific_events:
+    - chat_member_updated
+    - chat_join_request
+```
+
+这份声明用于：
+1. WebUI 在配置事件处理器时，只显示当前 Bot 的适配器支持的事件类型
+2. EventRouter 在路由时校验事件类型有效性
+3. 文档自动生成

docs/event-based-agents/02-platform-api.md

@@ -0,0 +1,546 @@
+# 统一平台 API 与实体定义
+
+## 1. 设计原则
+
+- **通用 API 抽象**：大部分平台都支持的操作（发消息、获取群信息等）定义为通用 API 方法
+- **required / optional 标记**：每个 API 标记为必需或可选，适配器未实现可选 API 时抛出 `NotSupportedError`
+- **透传机制**：适配器特有的操作通过 `call_platform_api(action, params)` 统一入口透传调用
+- **能力声明**：适配器在 manifest 中声明自己支持的 API 列表，供 WebUI 和插件查询
+- **实体统一**：通用实体（User、Group 等）在 SDK 层面统一定义，适配器负责转换
+
+## 2. 通用实体定义
+
+### 2.1 现有实体回顾
+
+当前 SDK 已有以下实体（`langbot_plugin/api/entities/builtin/platform/entities.py`）：
+
+```python
+Entity(id)
+├── Friend(id, nickname, remark)
+├── Group(id, name, permission)
+└── GroupMember(id, member_name, permission, group, special_title)
+```
+
+### 2.2 新实体设计
+
+扩展实体体系，保持向后兼容：
+
+```python
+class User(pydantic.BaseModel):
+    """用户实体（统一表示）"""
+
+    id: typing.Union[int, str]
+    """用户 ID"""
+
+    nickname: str = ""
+    """昵称"""
+
+    avatar_url: typing.Optional[str] = None
+    """头像 URL"""
+
+    is_bot: bool = False
+    """是否为 Bot"""
+
+    # 以下为可选的扩展信息，不同平台可能部分为空
+    username: typing.Optional[str] = None
+    """用户名（如 Telegram 的 @username）"""
+
+    remark: typing.Optional[str] = None
+    """备注名"""
+
+
+class Group(pydantic.BaseModel):
+    """群组实体"""
+
+    id: typing.Union[int, str]
+    """群组 ID"""
+
+    name: str = ""
+    """群组名称"""
+
+    description: typing.Optional[str] = None
+    """群组描述"""
+
+    member_count: typing.Optional[int] = None
+    """成员数量"""
+
+    avatar_url: typing.Optional[str] = None
+    """群组头像 URL"""
+
+    owner_id: typing.Optional[typing.Union[int, str]] = None
+    """群主 ID"""
+
+
+class GroupMember(pydantic.BaseModel):
+    """群成员实体"""
+
+    user: User
+    """用户信息"""
+
+    group_id: typing.Union[int, str]
+    """所属群组 ID"""
+
+    role: MemberRole
+    """群内角色"""
+
+    display_name: typing.Optional[str] = None
+    """群内显示名"""
+
+    joined_at: typing.Optional[float] = None
+    """加入群组的时间戳"""
+
+    title: typing.Optional[str] = None
+    """群头衔/特殊称号"""
+
+
+class MemberRole(str, Enum):
+    """群成员角色"""
+    OWNER = "owner"
+    ADMIN = "admin"
+    MEMBER = "member"
+```
+
+### 2.3 与现有实体的兼容映射
+
+| 新实体 | 旧实体 | 映射方式 |
+|--------|--------|----------|
+| `User` | `Friend` | `User(id=friend.id, nickname=friend.nickname, remark=friend.remark)` |
+| `Group` | `Group`（旧） | `Group(id=old.id, name=old.name)` + `permission` 字段弃用 |
+| `GroupMember` | `GroupMember`（旧） | `GroupMember(user=User(...), role=..., display_name=old.member_name)` |
+| `MemberRole` | `Permission` | `OWNER↔Owner`, `ADMIN↔Administrator`, `MEMBER↔Member` |
+
+旧实体类保留，标记为 `@deprecated`，内部通过转换方法桥接到新实体。
+
+## 3. 通用 API 定义
+
+### 3.1 API 方法一览
+
+#### 消息 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `send_message(target_type, target_id, message)` | **必需** | 主动发送消息 |
+| `reply_message(event, message, quote_origin)` | **必需** | 回复一个消息事件 |
+| `edit_message(chat_type, chat_id, message_id, new_content)` | 可选 | 编辑已发送的消息 |
+| `delete_message(chat_type, chat_id, message_id)` | 可选 | 删除/撤回消息 |
+| `forward_message(from_chat, message_id, to_chat_type, to_chat_id)` | 可选 | 转发消息到另一个会话 |
+| `get_message(chat_type, chat_id, message_id)` | 可选 | 获取指定消息的内容 |
+
+#### 群组 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `get_group_info(group_id)` | 可选 | 获取群组信息 |
+| `get_group_list()` | 可选 | 获取 Bot 加入的群组列表 |
+| `get_group_member_list(group_id)` | 可选 | 获取群成员列表 |
+| `get_group_member_info(group_id, user_id)` | 可选 | 获取指定群成员信息 |
+| `set_group_name(group_id, name)` | 可选 | 修改群名称 |
+| `mute_member(group_id, user_id, duration)` | 可选 | 禁言群成员 |
+| `unmute_member(group_id, user_id)` | 可选 | 解除禁言 |
+| `kick_member(group_id, user_id)` | 可选 | 踢出群成员 |
+| `leave_group(group_id)` | 可选 | Bot 退出群组 |
+
+#### 用户 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `get_user_info(user_id)` | 可选 | 获取用户信息 |
+| `get_friend_list()` | 可选 | 获取好友列表 |
+| `approve_friend_request(request_id, approve, remark)` | 可选 | 处理好友请求 |
+| `approve_group_invite(request_id, approve)` | 可选 | 处理入群邀请 |
+
+#### 媒体 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `upload_file(file_data, filename)` | 可选 | 上传文件，返回可引用的文件 ID 或 URL |
+| `get_file_url(file_id)` | 可选 | 获取文件下载 URL |
+
+#### 透传 API
+
+| 方法 | 必需/可选 | 说明 |
+|------|----------|------|
+| `call_platform_api(action, params)` | 可选 | 调用适配器特有 API |
+
+### 3.2 API 方法签名详解
+
+```python
+class AbstractPlatformAdapter(pydantic.BaseModel, metaclass=abc.ABCMeta):
+    """平台适配器基类（新版）"""
+
+    # ======== 必需方法 ========
+
+    @abc.abstractmethod
+    async def send_message(
+        self,
+        target_type: str,          # "private" | "group"
+        target_id: typing.Union[int, str],
+        message: MessageChain,
+    ) -> MessageResult:
+        """主动发送消息
+
+        Returns:
+            MessageResult: 包含 message_id 等发送结果
+        """
+        ...
+
+    @abc.abstractmethod
+    async def reply_message(
+        self,
+        event: MessageReceivedEvent,
+        message: MessageChain,
+        quote_origin: bool = False,
+    ) -> MessageResult:
+        """回复一个消息事件"""
+        ...
+
+    # ======== 可选消息方法 ========
+
+    async def edit_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: MessageChain,
+    ) -> None:
+        """编辑已发送的消息"""
+        raise NotSupportedError("edit_message")
+
+    async def delete_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """删除/撤回消息"""
+        raise NotSupportedError("delete_message")
+
+    async def forward_message(
+        self,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> MessageResult:
+        """转发消息"""
+        raise NotSupportedError("forward_message")
+
+    async def get_message(
+        self,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> MessageReceivedEvent:
+        """获取指定消息"""
+        raise NotSupportedError("get_message")
+
+    # ======== 可选群组方法 ========
+
+    async def get_group_info(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> Group:
+        """获取群组信息"""
+        raise NotSupportedError("get_group_info")
+
+    async def get_group_list(self) -> list[Group]:
+        """获取 Bot 加入的群组列表"""
+        raise NotSupportedError("get_group_list")
+
+    async def get_group_member_list(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> list[GroupMember]:
+        """获取群成员列表"""
+        raise NotSupportedError("get_group_member_list")
+
+    async def get_group_member_info(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> GroupMember:
+        """获取指定群成员信息"""
+        raise NotSupportedError("get_group_member_info")
+
+    async def set_group_name(
+        self,
+        group_id: typing.Union[int, str],
+        name: str,
+    ) -> None:
+        """修改群名称"""
+        raise NotSupportedError("set_group_name")
+
+    async def mute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        """禁言群成员，duration 为秒数，0 表示永久"""
+        raise NotSupportedError("mute_member")
+
+    async def unmute_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """解除禁言"""
+        raise NotSupportedError("unmute_member")
+
+    async def kick_member(
+        self,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """踢出群成员"""
+        raise NotSupportedError("kick_member")
+
+    async def leave_group(
+        self,
+        group_id: typing.Union[int, str],
+    ) -> None:
+        """Bot 退出群组"""
+        raise NotSupportedError("leave_group")
+
+    # ======== 可选用户方法 ========
+
+    async def get_user_info(
+        self,
+        user_id: typing.Union[int, str],
+    ) -> User:
+        """获取用户信息"""
+        raise NotSupportedError("get_user_info")
+
+    async def get_friend_list(self) -> list[User]:
+        """获取好友列表"""
+        raise NotSupportedError("get_friend_list")
+
+    async def approve_friend_request(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """处理好友请求"""
+        raise NotSupportedError("approve_friend_request")
+
+    async def approve_group_invite(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """处理入群邀请"""
+        raise NotSupportedError("approve_group_invite")
+
+    # ======== 可选媒体方法 ========
+
+    async def upload_file(
+        self,
+        file_data: bytes,
+        filename: str,
+    ) -> str:
+        """上传文件，返回文件 ID 或 URL"""
+        raise NotSupportedError("upload_file")
+
+    async def get_file_url(
+        self,
+        file_id: str,
+    ) -> str:
+        """获取文件下载 URL"""
+        raise NotSupportedError("get_file_url")
+
+    # ======== 透传 API ========
+
+    async def call_platform_api(
+        self,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """调用适配器特有 API
+
+        Args:
+            action: 平台特有的 API 动作标识
+            params: 参数字典
+
+        Returns:
+            dict: 返回结果
+
+        Examples:
+            # Telegram: pin 消息
+            await adapter.call_platform_api("pin_message", {
+                "chat_id": 123456,
+                "message_id": 789
+            })
+
+            # Discord: 创建频道
+            await adapter.call_platform_api("create_channel", {
+                "guild_id": "...",
+                "name": "new-channel",
+                "type": "text"
+            })
+        """
+        raise NotSupportedError("call_platform_api")
+
+    # ======== 流式输出（保留现有机制） ========
+
+    async def reply_message_chunk(
+        self,
+        event: MessageReceivedEvent,
+        bot_message: dict,
+        message: MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        """流式回复消息"""
+        raise NotSupportedError("reply_message_chunk")
+
+    async def is_stream_output_supported(self) -> bool:
+        """是否支持流式输出"""
+        return False
+
+    # ======== 生命周期方法（保留现有） ========
+
+    @abc.abstractmethod
+    async def run_async(self):
+        """启动适配器"""
+        ...
+
+    @abc.abstractmethod
+    async def kill(self) -> bool:
+        """停止适配器"""
+        ...
+
+    @abc.abstractmethod
+    def register_listener(self, event_type, callback):
+        """注册事件监听器"""
+        ...
+
+    @abc.abstractmethod
+    def unregister_listener(self, event_type, callback):
+        """注销事件监听器"""
+        ...
+```
+
+### 3.3 返回值类型
+
+```python
+class MessageResult(pydantic.BaseModel):
+    """消息发送结果"""
+
+    message_id: typing.Optional[typing.Union[int, str]] = None
+    """发送成功后的消息 ID"""
+
+    raw: typing.Optional[dict] = None
+    """平台原始返回数据"""
+
+
+class NotSupportedError(Exception):
+    """适配器未实现此 API"""
+
+    def __init__(self, api_name: str):
+        self.api_name = api_name
+        super().__init__(f"API not supported by this adapter: {api_name}")
+```
+
+## 4. API 能力声明
+
+适配器在 manifest.yaml 中声明支持的 API：
+
+```yaml
+kind: MessagePlatformAdapter
+metadata:
+  name: telegram
+spec:
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - edit_message
+      - delete_message
+      - get_group_info
+      - get_group_member_list
+      - get_user_info
+      - upload_file
+      - get_file_url
+      - call_platform_api
+  platform_specific_apis:
+    - action: pin_message
+      description: "Pin a message in a chat"
+      params_schema:
+        chat_id: { type: "string", required: true }
+        message_id: { type: "string", required: true }
+    - action: unpin_message
+      description: "Unpin a message"
+      params_schema:
+        chat_id: { type: "string", required: true }
+        message_id: { type: "string", required: true }
+```
+
+用途：
+1. **WebUI**：在配置界面展示当前 Bot 可用的 API 能力
+2. **插件**：插件可查询某个 Bot 是否支持特定 API，据此决定行为
+3. **文档**：自动生成各适配器的 API 支持矩阵
+
+## 5. 各平台 API 支持矩阵
+
+| API | Telegram | Discord | OneBot(QQ) | 飞书 | 钉钉 | Slack | 微信 | LINE | KOOK |
+|-----|----------|---------|-----------|------|------|-------|------|------|------|
+| `send_message` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `reply_message` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `edit_message` | Y | Y | N | Y | N | Y | N | N | Y |
+| `delete_message` | Y | Y | Y | Y | N | Y | Y | N | Y |
+| `forward_message` | Y | N | Y | Y | N | N | Y | N | N |
+| `get_group_info` | Y | Y | Y | Y | Y | Y | N | Y | Y |
+| `get_group_member_list` | Y | Y | Y | Y | Y | Y | N | Y | Y |
+| `get_user_info` | Y | Y | Y | Y | Y | Y | N | Y | Y |
+| `get_friend_list` | N | Y | Y | N | N | N | Y | N | N |
+| `mute_member` | Y | Y | Y | N | N | N | N | N | N |
+| `kick_member` | Y | Y | Y | N | N | N | N | N | Y |
+| `upload_file` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| `call_platform_api` | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+
+> 注：此表为初步评估，具体以各平台 SDK/API 文档为准。
+
+## 6. MessageChain 扩展
+
+### 6.1 保留的通用组件
+
+以下 MessageComponent 类型保持不变，继续作为通用消息元素：
+
+- `Source` — 消息元信息
+- `Plain` — 纯文本
+- `Quote` — 引用回复
+- `At` / `AtAll` — @提及
+- `Image` — 图片
+- `Voice` — 语音
+- `File` — 文件
+- `Forward` — 合并转发
+- `Face` — 表情
+- `Unknown` — 未知类型
+
+### 6.2 平台特有组件处理
+
+当前 MessageChain 中存在大量微信特有的组件类型（`WeChatMiniPrograms`, `WeChatEmoji`, `WeChatLink` 等）。在新架构下：
+
+- 这些类型**继续保留**在 SDK 中以保持兼容
+- 新增的平台特有消息组件统一使用 `PlatformComponent` 基类：
+
+```python
+class PlatformComponent(MessageComponent):
+    """平台特有的消息组件"""
+
+    type: str = "Platform"
+
+    platform: str
+    """平台标识"""
+
+    component_type: str
+    """组件类型"""
+
+    data: dict = {}
+    """组件数据"""
+```
+
+适配器在转换消息链时，对于无法映射到通用组件的平台特有内容，使用 `PlatformComponent` 承载。

docs/event-based-agents/03-adapter-structure.md

@@ -0,0 +1,483 @@
+# 适配器新目录结构
+
+## 1. 设计目标
+
+- **模块化**：每个适配器从单文件拆分到独立目录，各模块职责清晰
+- **可维护**：随着事件和 API 的增加，代码量会显著增长，目录结构有助于管理复杂度
+- **一致性**：所有适配器遵循相同的目录布局和文件命名约定
+- **兼容现有发现机制**：保持 YAML manifest + ComponentDiscoveryEngine 的注册体系
+
+## 2. 新目录布局
+
+### 2.1 整体结构
+
+```
+pkg/platform/
+├── __init__.py
+├── botmgr.py                  # PlatformManager + RuntimeBot（重构）
+├── event_bus.py               # EventBus（新增）
+├── event_router.py            # EventRouter（新增）
+├── logger.py                  # EventLogger（保留）
+├── webhook_pusher.py          # WebhookPusher（重构为 WebhookHandler）
+│
+├── adapters/                  # 适配器（新目录）
+│   ├── __init__.py
+│   │
+│   ├── telegram/
+│   │   ├── __init__.py
+│   │   ├── adapter.py         # TelegramAdapter 主类
+│   │   ├── event_converter.py # 平台事件 → 统一事件
+│   │   ├── message_converter.py # MessageChain 互转
+│   │   ├── api_impl.py        # 通用 API 实现
+│   │   ├── platform_api.py    # call_platform_api 的动作映射
+│   │   ├── types.py           # 平台特有类型定义
+│   │   └── manifest.yaml      # 适配器清单
+│   │
+│   ├── discord/
+│   │   ├── __init__.py
+│   │   ├── adapter.py
+│   │   ├── event_converter.py
+│   │   ├── message_converter.py
+│   │   ├── api_impl.py
+│   │   ├── platform_api.py
+│   │   ├── types.py
+│   │   ├── voice.py           # Discord 语音连接管理（特有）
+│   │   └── manifest.yaml
+│   │
+│   ├── aiocqhttp/             # OneBot v11 (QQ)
+│   │   └── ...
+│   ├── qqofficial/
+│   │   └── ...
+│   ├── lark/                  # 飞书
+│   │   └── ...
+│   ├── dingtalk/
+│   │   └── ...
+│   ├── slack/
+│   │   └── ...
+│   ├── wechatpad/
+│   │   └── ...
+│   ├── officialaccount/       # 微信公众号
+│   │   └── ...
+│   ├── wecom/                 # 企业微信
+│   │   └── ...
+│   ├── wecombot/
+│   │   └── ...
+│   ├── wecomcs/
+│   │   └── ...
+│   ├── kook/
+│   │   └── ...
+│   ├── line/
+│   │   └── ...
+│   ├── satori/
+│   │   └── ...
+│   ├── websocket/             # 内置 WebSocket 适配器
+│   │   ├── __init__.py
+│   │   ├── adapter.py
+│   │   ├── manager.py         # WebSocket 连接管理
+│   │   └── manifest.yaml
+│   │
+│   └── legacy/                # 旧版适配器（保留一段时间后移除）
+│       ├── gewechat/
+│       ├── nakuru/
+│       └── qqbotpy/
+│
+└── handlers/                  # 事件处理器实现（新增）
+    ├── __init__.py
+    ├── base.py                # AbstractEventHandler 基类
+    ├── pipeline_handler.py    # PipelineHandler
+    ├── agent_handler.py       # AgentHandler
+    ├── webhook_handler.py     # WebhookHandler
+    └── plugin_handler.py      # PluginHandler
+```
+
+### 2.2 适配器目录内各文件职责
+
+以 Telegram 为例：
+
+| 文件 | 职责 | 关键类/函数 |
+|------|------|------------|
+| `adapter.py` | 主入口，继承 `AbstractPlatformAdapter`，组装其他模块 | `TelegramAdapter` |
+| `event_converter.py` | 将 Telegram 原生事件转换为统一事件类型 | `TelegramEventConverter` — 支持 Message/Edit/Delete/Reaction/MemberJoin 等所有事件 |
+| `message_converter.py` | `MessageChain` 与 Telegram 消息格式互转 | `TelegramMessageConverter.yiri2target()` / `target2yiri()` |
+| `api_impl.py` | 实现通用 API 方法（edit_message, delete_message, get_group_info 等） | 各 API 方法的 Telegram 实现 |
+| `platform_api.py` | 实现 `call_platform_api` 的动作分发表 | `PLATFORM_API_MAP = {"pin_message": ..., "unpin_message": ...}` |
+| `types.py` | 平台特有的类型定义 | Telegram 特有的枚举、配置结构等 |
+| `manifest.yaml` | 适配器清单：名称、配置 schema、支持的事件和 API 列表 | — |
+
+## 3. 新基类设计
+
+### 3.1 AbstractPlatformAdapter
+
+新基类继承自现有 `AbstractMessagePlatformAdapter` 并扩展，位于 `langbot-plugin-sdk` 中：
+
+```python
+# langbot_plugin/api/definition/abstract/platform/adapter.py
+
+class AbstractPlatformAdapter(pydantic.BaseModel, metaclass=abc.ABCMeta):
+    """平台适配器基类（EBA 版本）
+
+    相比旧版 AbstractMessagePlatformAdapter：
+    - 新增通用 API 方法（edit_message, delete_message, get_group_info 等）
+    - 新增透传 API（call_platform_api）
+    - 新增能力声明（get_supported_events, get_supported_apis）
+    - 事件监听器支持所有事件类型，不仅限于消息事件
+    """
+
+    bot_account_id: str = ""
+    config: dict
+    logger: AbstractEventLogger = pydantic.Field(exclude=True)
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    # ---- 能力声明 ----
+
+    def get_supported_events(self) -> list[str]:
+        """返回此适配器支持的事件类型列表
+
+        默认实现从 manifest.yaml 读取。
+        适配器也可以 override 此方法动态声明。
+        """
+        return ["message.received"]
+
+    def get_supported_apis(self) -> list[str]:
+        """返回此适配器支持的 API 列表
+
+        默认实现从 manifest.yaml 读取。
+        """
+        return ["send_message", "reply_message"]
+
+    # ---- 必需方法（抽象） ----
+
+    @abc.abstractmethod
+    async def send_message(self, target_type, target_id, message) -> MessageResult:
+        ...
+
+    @abc.abstractmethod
+    async def reply_message(self, event, message, quote_origin=False) -> MessageResult:
+        ...
+
+    @abc.abstractmethod
+    async def run_async(self):
+        ...
+
+    @abc.abstractmethod
+    async def kill(self) -> bool:
+        ...
+
+    @abc.abstractmethod
+    def register_listener(self, event_type, callback):
+        ...
+
+    @abc.abstractmethod
+    def unregister_listener(self, event_type, callback):
+        ...
+
+    # ---- 可选方法（默认抛 NotSupportedError） ----
+    # edit_message, delete_message, forward_message,
+    # get_group_info, get_group_member_list, ...
+    # call_platform_api, ...
+    # （完整签名见 02-platform-api.md）
+
+    # ---- 流式输出（保留） ----
+
+    async def reply_message_chunk(self, event, bot_message, message,
+                                   quote_origin=False, is_final=False):
+        raise NotSupportedError("reply_message_chunk")
+
+    async def is_stream_output_supported(self) -> bool:
+        return False
+
+    # ---- 消息卡片（保留） ----
+
+    async def create_message_card(self, message_id, event) -> bool:
+        return False
+
+    async def is_muted(self, group_id) -> bool:
+        return False
+```
+
+### 3.2 AbstractMessagePlatformAdapter 兼容
+
+旧的 `AbstractMessagePlatformAdapter` 保留为 `AbstractPlatformAdapter` 的类型别名：
+
+```python
+# 向后兼容
+AbstractMessagePlatformAdapter = AbstractPlatformAdapter
+```
+
+现有适配器代码中的 `AbstractMessagePlatformAdapter` 引用不需要立即修改。
+
+### 3.3 EventConverter 新设计
+
+现有 `AbstractEventConverter` 只有 `target2yiri` 和 `yiri2target` 两个静态方法，且只处理消息事件。
+
+新设计支持多种事件类型：
+
+```python
+class AbstractEventConverter:
+    """事件转换器基类（EBA 版本）
+
+    适配器需要实现此转换器，将平台原生事件转换为统一事件。
+    """
+
+    @staticmethod
+    def target2yiri(raw_event: typing.Any) -> typing.Optional[Event]:
+        """将平台原生事件转换为统一事件
+
+        Args:
+            raw_event: 平台 SDK 回调传入的原始事件对象
+
+        Returns:
+            统一 Event 对象，如果无法转换或不需要处理则返回 None
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def yiri2target(event: Event) -> typing.Any:
+        """将统一事件转换为平台原生事件（一般不需要）"""
+        raise NotImplementedError
+```
+
+具体适配器的 EventConverter 实现会是一个分发式的结构：
+
+```python
+class TelegramEventConverter(AbstractEventConverter):
+    """Telegram 事件转换器"""
+
+    @staticmethod
+    def target2yiri(update: telegram.Update) -> typing.Optional[Event]:
+        # 消息事件
+        if update.message:
+            return TelegramEventConverter._convert_message(update)
+        # 消息编辑
+        if update.edited_message:
+            return TelegramEventConverter._convert_edited_message(update)
+        # 成员变动
+        if update.chat_member:
+            return TelegramEventConverter._convert_chat_member(update)
+        # 回调查询（按钮点击等）
+        if update.callback_query:
+            return TelegramEventConverter._convert_callback_query(update)
+        # 其他 → PlatformSpecificEvent
+        return TelegramEventConverter._convert_platform_specific(update)
+
+    @staticmethod
+    def _convert_message(update) -> MessageReceivedEvent:
+        ...
+
+    @staticmethod
+    def _convert_edited_message(update) -> MessageEditedEvent:
+        ...
+
+    @staticmethod
+    def _convert_chat_member(update) -> typing.Union[
+        MemberJoinedEvent, MemberLeftEvent, ...
+    ]:
+        ...
+
+    @staticmethod
+    def _convert_platform_specific(update) -> PlatformSpecificEvent:
+        ...
+```
+
+## 4. Manifest 文件格式扩展
+
+现有 manifest.yaml 只声明 `kind`, `metadata`, `spec.config`, `execution`。
+
+新增 `spec.supported_events` 和 `spec.supported_apis`：
+
+```yaml
+apiVersion: v1
+kind: MessagePlatformAdapter
+
+metadata:
+  name: telegram
+  label:
+    en_US: Telegram
+    zh_Hans: Telegram
+  icon: telegram.svg
+  description:
+    en_US: Telegram Bot adapter
+    zh_Hans: Telegram Bot 适配器
+
+spec:
+  config:
+    # 现有配置 schema（保持不变）
+    - key: token
+      label: { en_US: "Bot Token", zh_Hans: "Bot Token" }
+      type: string
+      required: true
+      sensitive: true
+    # ...
+
+  supported_events:
+    - message.received
+    - message.edited
+    - message.deleted
+    - message.reaction
+    - feedback.received
+    - group.member_joined
+    - group.member_left
+    - group.member_banned
+    - group.info_updated
+    - bot.invited_to_group
+    - bot.removed_from_group
+    - bot.muted
+    - bot.unmuted
+    - platform.specific
+
+  supported_apis:
+    required:
+      - send_message
+      - reply_message
+    optional:
+      - edit_message
+      - delete_message
+      - get_group_info
+      - get_group_member_list
+      - get_group_member_info
+      - get_user_info
+      - upload_file
+      - get_file_url
+      - call_platform_api
+
+  platform_specific_apis:
+    - action: pin_message
+      description: { en_US: "Pin a message", zh_Hans: "置顶消息" }
+    - action: unpin_message
+      description: { en_US: "Unpin a message", zh_Hans: "取消置顶" }
+    - action: get_chat_administrators
+      description: { en_US: "Get chat admins", zh_Hans: "获取群管理员列表" }
+
+execution:
+  python:
+    path: pkg/platform/adapters/telegram/adapter.py
+    attr: TelegramAdapter
+```
+
+## 5. 适配器注册与发现
+
+### 5.1 Blueprint 更新
+
+`templates/components.yaml` 中更新扫描路径：
+
+```yaml
+kind: Blueprint
+spec:
+  components:
+    MessagePlatformAdapter:
+      fromDirs:
+        - path: pkg/platform/adapters/     # 新路径
+```
+
+`ComponentDiscoveryEngine` 的递归扫描逻辑不变——它会扫描所有子目录中的 `.yaml` 文件。因此每个适配器目录下的 `manifest.yaml` 会被自动发现。
+
+### 5.2 PlatformManager 适配
+
+`PlatformManager.initialize()` 的核心逻辑基本不变：
+
+```python
+async def initialize(self):
+    # 1. 发现适配器组件（自动扫描新目录结构）
+    self.adapter_components = self.ap.discover.get_components_by_kind('MessagePlatformAdapter')
+
+    # 2. 动态导入适配器类
+    for component in self.adapter_components:
+        self.adapter_dict[component.metadata.name] = component.get_python_component_class()
+
+    # 3. 从数据库加载 Bot 并实例化适配器（不变）
+    await self.load_bots_from_db()
+```
+
+变更点：
+- `execution.python.path` 从 `pkg/platform/sources/telegram.py` 变为 `pkg/platform/adapters/telegram/adapter.py`
+- `get_python_component_class()` 正常工作，因为它按路径动态导入
+
+## 6. RuntimeBot 重构
+
+### 6.1 现有问题
+
+当前 `RuntimeBot.initialize()` 硬编码注册了两个回调：
+
+```python
+# 现有代码
+self.adapter.register_listener(platform_events.FriendMessage, on_friend_message)
+self.adapter.register_listener(platform_events.GroupMessage, on_group_message)
+```
+
+### 6.2 新设计
+
+`RuntimeBot` 改为注册一个通用的事件回调：
+
+```python
+class RuntimeBot:
+    async def initialize(self):
+        # 注册通用事件回调，接收所有事件类型
+        self.adapter.register_listener(Event, self._on_event)
+
+    async def _on_event(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+    ):
+        """统一事件入口"""
+
+        # 1. 设置事件的 bot_uuid 和 adapter_name
+        event.bot_uuid = self.bot_entity.uuid
+        event.adapter_name = self.bot_entity.adapter
+
+        # 2. 日志记录
+        await self._log_event(event)
+
+        # 3. 提交给 EventBus
+        await self.ap.event_bus.emit(event, adapter)
+```
+
+适配器侧的 `register_listener` 实现也需调整：
+- 当 `event_type` 为 `Event`（基类）时，注册为"接收所有事件"的通配回调
+- 适配器在收到平台原生事件时，通过 `EventConverter.target2yiri()` 转换后，调用所有匹配的回调
+
+## 7. 从现有单文件适配器迁移
+
+### 7.1 迁移模式
+
+以 Telegram 为例，从 `sources/telegram.py`（445 行）拆分：
+
+| 原代码位置 | → 新文件 |
+|-----------|----------|
+| `TelegramMessageConverter` 类 | `telegram/message_converter.py` |
+| `TelegramEventConverter` 类 | `telegram/event_converter.py`（扩展，支持更多事件） |
+| `TelegramAdapter.__init__` / `run_async` / `kill` / `register_listener` | `telegram/adapter.py` |
+| `TelegramAdapter.send_message` / `reply_message` / `reply_message_chunk` | `telegram/adapter.py`（消息方法保留在主类）+ `telegram/api_impl.py`（新增 API） |
+| 新增代码 | `telegram/api_impl.py`（edit_message, delete_message, get_group_info 等） |
+| 新增代码 | `telegram/platform_api.py`（pin_message, unpin_message 等的映射） |
+| `telegram.yaml` | `telegram/manifest.yaml`（扩展 supported_events/apis） |
+
+### 7.2 迁移顺序建议
+
+1. **Telegram** — 功能最完整的适配器之一，适合作为模板
+2. **Discord** — 第二个迁移，验证模式的通用性
+3. **AioCQHTTP (OneBot)** — 国内最常用，确保兼容
+4. **其他适配器** — 按使用频率排序
+
+### 7.3 渐进式迁移
+
+不需要一次性迁移所有适配器。可以采用渐进策略：
+
+1. 先在 `adapters/` 下建立新适配器
+2. `Blueprint` 同时扫描 `sources/` 和 `adapters/` 两个目录
+3. 旧适配器在 `sources/` 中继续工作
+4. 逐个迁移到新结构
+5. 全部迁移完成后移除 `sources/` 目录
+
+```yaml
+# 过渡期的 Blueprint
+kind: Blueprint
+spec:
+  components:
+    MessagePlatformAdapter:
+      fromDirs:
+        - path: pkg/platform/sources/      # 旧路径（尚未迁移的适配器）
+        - path: pkg/platform/adapters/      # 新路径（已迁移的适配器）
+```

docs/event-based-agents/04-event-routing.md

@@ -0,0 +1,745 @@
+# 事件路由与编排
+
+> **2026-06 方向修订**：本文档的四种 handler_type（pipeline / agent / webhook / plugin）分类法已被「事件 → Agent」统一编排取代，收编映射与新数据模型见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本文档中的事件匹配规则（§4）、`use_pipeline_uuid` 迁移策略（§6）、WebUI 交互骨架（§7）与 webhook 请求/响应格式（§5.4）仍然有效，将在 Agent 模型下沿用。
+
+## 1. 概述
+
+事件路由是 EBA 架构的核心机制：事件从适配器产生后，经由 EventBus 进入 EventRouter，由 EventRouter 根据 Bot 的配置将事件分发到对应的处理器（Handler）。
+
+**配置方式**：用户在 WebUI 的 Bot 管理页面通过可视化编排面板管理事件处理器配置，配置数据存储在数据库的 Bot 表 `event_handlers` JSON 字段中。
+
+## 2. 数据模型
+
+### 2.1 Bot 实体扩展
+
+在 `bots` 表新增 `event_handlers` 字段：
+
+```python
+class Bot(Base):
+    __tablename__ = "bots"
+
+    uuid: str               # 主键
+    name: str
+    description: str
+    adapter: str
+    adapter_config: dict    # JSON
+    enable: bool
+
+    # 新增
+    event_handlers: list    # JSON — 事件处理器配置列表
+
+    # 保留（过渡期后弃用）
+    use_pipeline_name: str  # deprecated
+    use_pipeline_uuid: str  # deprecated
+
+    created_at: datetime
+    updated_at: datetime
+```
+
+### 2.2 EventHandler 配置结构
+
+`event_handlers` 字段存储一个 JSON 数组，每个元素定义一条事件路由规则：
+
+```python
+class EventHandlerConfig(pydantic.BaseModel):
+    """单条事件处理器配置"""
+
+    event_type: str
+    """匹配的事件类型
+
+    支持精确匹配和通配符：
+    - "message.received"       — 精确匹配
+    - "message.*"              — 匹配 message 命名空间下所有事件
+    - "group.*"                — 匹配 group 命名空间下所有事件
+    - "*"                      — 匹配所有事件（兜底）
+    """
+
+    handler_type: str
+    """处理器类型: "pipeline" | "agent" | "webhook" | "plugin" """
+
+    handler_config: dict = {}
+    """处理器的具体配置，结构取决于 handler_type"""
+
+    enabled: bool = True
+    """是否启用此规则"""
+
+    priority: int = 0
+    """优先级，数字越大越先匹配（同一事件类型有多条规则时）"""
+
+    description: str = ""
+    """规则描述（供 WebUI 显示）"""
+```
+
+### 2.3 各 Handler 类型的 handler_config 结构
+
+#### pipeline
+
+```json
+{
+    "handler_type": "pipeline",
+    "handler_config": {
+        "pipeline_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    }
+}
+```
+
+将事件作为消息事件传入现有 Pipeline 流水线。仅适用于 `message.received` 事件。
+
+#### agent
+
+```json
+{
+    "handler_type": "agent",
+    "handler_config": {
+        "runner": "local-agent",
+        "runner_config": {
+            "model_uuid": "...",
+            "prompt": "你是一个群组助理，请处理以下事件：{event_summary}",
+            "tools_enabled": true
+        }
+    }
+}
+```
+
+```json
+{
+    "handler_type": "agent",
+    "handler_config": {
+        "runner": "dify-service-api",
+        "runner_config": {
+            "base_url": "https://api.dify.ai/v1",
+            "api_key": "...",
+            "app_type": "agent"
+        }
+    }
+}
+```
+
+直接调用 RequestRunner 处理事件。可用的 runner 包括：
+- `local-agent` — 内置 LLM Agent
+- `dify-service-api` — Dify 平台
+- `n8n-service-api` — n8n 工作流
+- `coze-api` — Coze (扣子)
+- `dashscope-app-api` — 阿里百炼
+- `langflow-api` — Langflow
+- `tbox-app-api` — 蚂蚁 Tbox
+
+Agent 处理器不经过 Pipeline 的多 Stage 流程，而是直接构建上下文并调用 Runner。适用于所有事件类型。
+
+**Agent Handler 与 Pipeline 的关系**：
+- Pipeline 是完整的多 Stage 处理链（PreProcessor → MessageProcessor(内含Runner) → PostProcessor → ...），适合复杂消息处理
+- Agent Handler 是轻量级的，直接调用 Runner，跳过 PreProcessor/PostProcessor 等阶段
+- Pipeline 内部的 AI Stage 仍然使用 Runner，所以 Runner 本身被两种 Handler 共享
+- 用户可以根据场景选择：消息处理用 Pipeline（更多控制），其他事件用 Agent（更直接）
+
+#### webhook
+
+```json
+{
+    "handler_type": "webhook",
+    "handler_config": {
+        "url": "https://example.com/webhook/langbot-events",
+        "method": "POST",
+        "headers": {
+            "Authorization": "Bearer xxx"
+        },
+        "timeout": 30,
+        "retry_count": 3,
+        "retry_interval": 5,
+        "response_actions": true
+    }
+}
+```
+
+将事件序列化为 JSON POST 到外部 URL。支持的特性：
+- **认证**：通过 headers 配置（Bearer Token、API Key 等）
+- **重试**：配置重试次数和间隔
+- **响应动作**：如果 `response_actions` 为 true，解析响应 JSON 中的 `actions` 字段并执行（如发送消息、同意好友请求等）
+
+Webhook 请求体格式：
+
+```json
+{
+    "event": {
+        "type": "group.member_joined",
+        "timestamp": 1700000000.0,
+        "bot_uuid": "...",
+        "adapter_name": "telegram",
+        "group": { "id": "...", "name": "..." },
+        "member": { "id": "...", "nickname": "..." }
+    },
+    "bot": {
+        "uuid": "...",
+        "name": "...",
+        "adapter": "telegram"
+    }
+}
+```
+
+响应体格式（当 `response_actions` 为 true 时）：
+
+```json
+{
+    "actions": [
+        {
+            "type": "send_message",
+            "params": {
+                "target_type": "group",
+                "target_id": "123456",
+                "message": [{ "type": "Plain", "text": "欢迎新成员！" }]
+            }
+        },
+        {
+            "type": "call_platform_api",
+            "params": {
+                "action": "pin_message",
+                "params": { "chat_id": "123456", "message_id": "789" }
+            }
+        }
+    ]
+}
+```
+
+#### plugin
+
+```json
+{
+    "handler_type": "plugin",
+    "handler_config": {
+        "plugin_filter": []
+    }
+}
+```
+
+将事件分发给插件的 EventListener 处理。
+
+- `plugin_filter`：可选的插件名过滤列表，为空表示分发给所有插件
+- 沿用现有的插件事件分发机制（按优先级遍历插件，支持 `prevent_postorder`）
+
+### 2.4 完整配置示例
+
+一个 Bot 的 `event_handlers` 配置示例：
+
+```json
+[
+    {
+        "event_type": "message.received",
+        "handler_type": "pipeline",
+        "handler_config": {
+            "pipeline_uuid": "default-pipeline-uuid"
+        },
+        "enabled": true,
+        "priority": 10,
+        "description": "消息事件使用默认流水线处理"
+    },
+    {
+        "event_type": "group.member_joined",
+        "handler_type": "agent",
+        "handler_config": {
+            "runner": "local-agent",
+            "runner_config": {
+                "model_uuid": "gpt-4o-mini",
+                "prompt": "有新成员 {member_name} 加入了群组 {group_name}，请生成一条欢迎消息。"
+            }
+        },
+        "enabled": true,
+        "priority": 0,
+        "description": "新成员入群时用 AI 生成欢迎消息"
+    },
+    {
+        "event_type": "friend.request_received",
+        "handler_type": "webhook",
+        "handler_config": {
+            "url": "https://my-server.com/api/friend-request",
+            "response_actions": true
+        },
+        "enabled": true,
+        "priority": 0,
+        "description": "好友请求转发到自建服务处理"
+    },
+    {
+        "event_type": "*",
+        "handler_type": "plugin",
+        "handler_config": {},
+        "enabled": true,
+        "priority": -100,
+        "description": "所有事件兜底发给插件处理"
+    }
+]
+```
+
+## 3. EventBus 设计
+
+EventBus 是事件的中转站，接收来自各个 RuntimeBot 的事件，交由 EventRouter 处理。
+
+```python
+class EventBus:
+    """事件总线"""
+
+    def __init__(self, ap: Application):
+        self.ap = ap
+        self.event_router = EventRouter(ap)
+
+    async def emit(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+    ):
+        """接收并分发事件
+
+        Args:
+            event: 统一事件对象
+            adapter: 产生此事件的适配器实例
+        """
+        # 1. 全局事件日志
+        self.ap.logger.debug(
+            f"EventBus: {event.type} from bot {event.bot_uuid}"
+        )
+
+        # 2. 交由 EventRouter 路由处理
+        await self.event_router.route(event, adapter)
+```
+
+## 4. EventRouter 设计
+
+EventRouter 是事件路由引擎，根据 Bot 的 `event_handlers` 配置决定事件的处理方式。
+
+```python
+class EventRouter:
+    """事件路由引擎"""
+
+    def __init__(self, ap: Application):
+        self.ap = ap
+        self.handlers: dict[str, AbstractEventHandler] = {
+            "pipeline": PipelineHandler(ap),
+            "agent": AgentHandler(ap),
+            "webhook": WebhookHandler(ap),
+            "plugin": PluginHandler(ap),
+        }
+
+    async def route(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+    ):
+        """路由事件到对应处理器"""
+
+        # 1. 获取 Bot 配置
+        bot = await self.ap.platform_mgr.get_bot_by_uuid(event.bot_uuid)
+        if not bot:
+            return
+
+        # 2. 获取事件处理器配置
+        event_handlers = bot.bot_entity.event_handlers or []
+
+        # 3. 匹配规则（按 priority 降序排列）
+        matched_handlers = self._match_handlers(event.type, event_handlers)
+
+        if not matched_handlers:
+            # 未匹配到任何规则 → 默认交给插件处理（向后兼容）
+            await self.handlers["plugin"].handle(event, adapter, {})
+            return
+
+        # 4. 执行第一个匹配的 Handler
+        #    （未来可扩展为多个 Handler 串行/并行执行）
+        handler_config = matched_handlers[0]
+        handler = self.handlers.get(handler_config.handler_type)
+
+        if handler:
+            await handler.handle(event, adapter, handler_config.handler_config)
+        else:
+            self.ap.logger.warning(
+                f"Unknown handler type: {handler_config.handler_type}"
+            )
+
+    def _match_handlers(
+        self,
+        event_type: str,
+        handlers: list[EventHandlerConfig],
+    ) -> list[EventHandlerConfig]:
+        """匹配事件类型到处理器配置
+
+        匹配规则：
+        1. 精确匹配：event_type == handler.event_type
+        2. 命名空间通配：handler.event_type 为 "message.*" 时匹配所有 "message.xxx"
+        3. 全局通配：handler.event_type 为 "*" 时匹配所有事件
+        4. 按 priority 降序排列
+        5. 只返回 enabled=True 的规则
+        """
+        matched = []
+        for handler in handlers:
+            if not handler.enabled:
+                continue
+            if self._event_type_matches(event_type, handler.event_type):
+                matched.append(handler)
+
+        matched.sort(key=lambda h: h.priority, reverse=True)
+        return matched
+
+    @staticmethod
+    def _event_type_matches(event_type: str, pattern: str) -> bool:
+        """判断事件类型是否匹配模式"""
+        if pattern == "*":
+            return True
+        if pattern == event_type:
+            return True
+        if pattern.endswith(".*"):
+            namespace = pattern[:-2]
+            return event_type.startswith(namespace + ".")
+        return False
+```
+
+## 5. 事件处理器（Handler）实现
+
+### 5.1 Handler 基类
+
+```python
+class AbstractEventHandler(abc.ABC):
+    """事件处理器基类"""
+
+    def __init__(self, ap: Application):
+        self.ap = ap
+
+    @abc.abstractmethod
+    async def handle(
+        self,
+        event: Event,
+        adapter: AbstractPlatformAdapter,
+        config: dict,
+    ) -> None:
+        """处理事件
+
+        Args:
+            event: 统一事件对象
+            adapter: 适配器实例（用于调用平台 API 发送响应）
+            config: handler_config 配置
+        """
+        ...
+```
+
+### 5.2 PipelineHandler
+
+将消息事件注入现有 Pipeline 流水线处理。
+
+```python
+class PipelineHandler(AbstractEventHandler):
+    """Pipeline 处理器 — 将事件送入现有 Pipeline 流水线"""
+
+    async def handle(self, event, adapter, config):
+        pipeline_uuid = config.get("pipeline_uuid")
+
+        if not isinstance(event, MessageReceivedEvent):
+            self.ap.logger.warning(
+                f"PipelineHandler only supports MessageReceivedEvent, "
+                f"got {event.type}"
+            )
+            return
+
+        # 将 MessageReceivedEvent 转换为现有的 Query 并投入 QueryPool
+        # 复用现有的 MessageAggregator + QueryPool + Pipeline 机制
+        launcher_type = (
+            LauncherTypes.PERSON
+            if event.chat_type == ChatType.PRIVATE
+            else LauncherTypes.GROUP
+        )
+
+        await self.ap.msg_aggregator.add_message(
+            bot_uuid=event.bot_uuid,
+            launcher_type=launcher_type,
+            launcher_id=event.chat_id,
+            sender_id=event.sender.id,
+            message_event=event.to_legacy_event(),  # 转换为 FriendMessage/GroupMessage
+            message_chain=event.message_chain,
+            adapter=adapter,
+            pipeline_uuid=pipeline_uuid,
+        )
+```
+
+### 5.3 AgentHandler
+
+直接调用 RequestRunner 处理事件，不经过 Pipeline Stage 链。
+
+```python
+class AgentHandler(AbstractEventHandler):
+    """Agent 处理器 — 直接调用 RequestRunner 处理事件"""
+
+    async def handle(self, event, adapter, config):
+        runner_name = config.get("runner", "local-agent")
+        runner_config = config.get("runner_config", {})
+
+        # 1. 查找 Runner 类
+        runner_cls = None
+        for r in preregistered_runners:
+            if r.name == runner_name:
+                runner_cls = r
+                break
+
+        if not runner_cls:
+            self.ap.logger.error(f"Runner not found: {runner_name}")
+            return
+
+        # 2. 构建事件上下文（将事件信息整理为 Runner 可处理的格式）
+        event_context = self._build_event_context(event, runner_config)
+
+        # 3. 实例化并调用 Runner
+        runner = runner_cls(self.ap, self._build_runner_pipeline_config(config))
+
+        response_messages = []
+        async for result in runner.run(event_context):
+            response_messages.append(result)
+
+        # 4. 发送响应（如果 Runner 产生了回复）
+        if response_messages and isinstance(event, MessageReceivedEvent):
+            # 将 Runner 输出转换为 MessageChain 并回复
+            reply_chain = self._build_reply_chain(response_messages)
+            await adapter.reply_message(event, reply_chain)
+
+    def _build_event_context(self, event, runner_config):
+        """将事件构建为 Runner 可处理的上下文
+
+        对于消息事件，直接使用消息内容。
+        对于其他事件，根据 runner_config 中的 prompt 模板生成描述文本。
+        """
+        ...
+
+    def _build_runner_pipeline_config(self, config):
+        """将 handler_config 转换为 Runner 需要的 pipeline_config 格式"""
+        ...
+```
+
+### 5.4 WebhookHandler
+
+将事件 POST 到外部 URL。
+
+```python
+class WebhookHandler(AbstractEventHandler):
+    """Webhook 处理器 — 将事件 POST 到外部 URL"""
+
+    async def handle(self, event, adapter, config):
+        url = config.get("url")
+        method = config.get("method", "POST")
+        headers = config.get("headers", {})
+        timeout = config.get("timeout", 30)
+        retry_count = config.get("retry_count", 3)
+        response_actions = config.get("response_actions", False)
+
+        # 1. 构建请求体
+        bot = await self.ap.platform_mgr.get_bot_by_uuid(event.bot_uuid)
+        payload = {
+            "event": event.model_dump(),
+            "bot": {
+                "uuid": bot.bot_entity.uuid,
+                "name": bot.bot_entity.name,
+                "adapter": bot.bot_entity.adapter,
+            }
+        }
+
+        # 2. 发送请求（带重试）
+        response = await self._send_with_retry(
+            url, method, headers, payload, timeout, retry_count
+        )
+
+        # 3. 处理响应动作
+        if response_actions and response:
+            await self._execute_response_actions(
+                response, adapter, event
+            )
+
+    async def _execute_response_actions(self, response, adapter, event):
+        """执行响应中的动作列表"""
+        actions = response.get("actions", [])
+        for action in actions:
+            action_type = action.get("type")
+            params = action.get("params", {})
+
+            if action_type == "send_message":
+                chain = MessageChain.model_validate(params.get("message", []))
+                await adapter.send_message(
+                    params["target_type"],
+                    params["target_id"],
+                    chain,
+                )
+            elif action_type == "reply":
+                chain = MessageChain.model_validate(params.get("message", []))
+                await adapter.reply_message(event, chain)
+            elif action_type == "call_platform_api":
+                await adapter.call_platform_api(
+                    params["action"],
+                    params.get("params", {}),
+                )
+            elif action_type == "approve_friend_request":
+                await adapter.approve_friend_request(
+                    params["request_id"],
+                    params.get("approve", True),
+                )
+            # ... 更多动作类型
+```
+
+### 5.5 PluginHandler
+
+将事件分发给插件的 EventListener。
+
+```python
+class PluginHandler(AbstractEventHandler):
+    """Plugin 处理器 — 分发给插件 EventListener"""
+
+    async def handle(self, event, adapter, config):
+        plugin_filter = config.get("plugin_filter", [])
+
+        # 复用现有的插件事件分发机制
+        # 通过 plugin_connector 将事件发送给 Plugin Runtime
+        await self.ap.plugin_connector.emit_event(
+            event=event,
+            adapter=adapter,
+            plugin_filter=plugin_filter,
+        )
+```
+
+## 6. use_pipeline_uuid 迁移
+
+### 6.1 自动迁移
+
+数据库迁移脚本将现有的 `use_pipeline_uuid` 自动转换为 `event_handlers`：
+
+```python
+# 迁移逻辑
+for bot in all_bots:
+    if bot.use_pipeline_uuid and not bot.event_handlers:
+        bot.event_handlers = [
+            {
+                "event_type": "message.received",
+                "handler_type": "pipeline",
+                "handler_config": {
+                    "pipeline_uuid": bot.use_pipeline_uuid
+                },
+                "enabled": True,
+                "priority": 10,
+                "description": "Auto-migrated from use_pipeline_uuid"
+            },
+            {
+                "event_type": "*",
+                "handler_type": "plugin",
+                "handler_config": {},
+                "enabled": True,
+                "priority": -100,
+                "description": "Default plugin handler"
+            }
+        ]
+```
+
+### 6.2 过渡期兼容
+
+在过渡期内，如果 `event_handlers` 为空且 `use_pipeline_uuid` 非空，EventRouter 自动回退到旧行为：
+
+```python
+# EventRouter.route() 中的兼容逻辑
+if not event_handlers and bot.bot_entity.use_pipeline_uuid:
+    # 回退：消息事件走 Pipeline，其他事件走 Plugin
+    if isinstance(event, MessageReceivedEvent):
+        await self.handlers["pipeline"].handle(
+            event, adapter,
+            {"pipeline_uuid": bot.bot_entity.use_pipeline_uuid}
+        )
+    else:
+        await self.handlers["plugin"].handle(event, adapter, {})
+    return
+```
+
+## 7. WebUI 编排面板数据模型
+
+### 7.1 交互设计概要
+
+在 WebUI 的 Bot 管理页面，新增"事件处理器"标签页（或区域），呈现为一个**规则列表**：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  事件处理器                                       [+ 添加规则]  │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─ 规则 1 ─────────────────────────────────── [启用] [删除] ─┐ │
+│  │  事件类型: [message.received    ▾]                         │ │
+│  │  处理器:   [Pipeline           ▾]                         │ │
+│  │  Pipeline: [默认流水线          ▾]                         │ │
+│  │  优先级:   [10]                                           │ │
+│  │  描述:     消息事件使用默认流水线处理                         │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                             │
+│  ┌─ 规则 2 ─────────────────────────────────── [启用] [删除] ─┐ │
+│  │  事件类型: [group.member_joined ▾]                         │ │
+│  │  处理器:   [Agent              ▾]                         │ │
+│  │  Runner:   [local-agent        ▾]                         │ │
+│  │  模型:     [gpt-4o-mini        ▾]                         │ │
+│  │  Prompt:   [有新成员加入...]                                │ │
+│  │  优先级:   [0]                                            │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                             │
+│  ┌─ 规则 3 (兜底) ──────────────────────────── [启用] [删除] ─┐ │
+│  │  事件类型: [*                   ▾]                         │ │
+│  │  处理器:   [Plugin             ▾]                         │ │
+│  │  优先级:   [-100]                                         │ │
+│  └──────────────────────────────────────────────────────────┘ │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 前端数据结构
+
+```typescript
+interface EventHandlerRule {
+  event_type: string;       // 下拉选择，选项从适配器 manifest 的 supported_events 获取
+  handler_type: string;     // "pipeline" | "agent" | "webhook" | "plugin"
+  handler_config: Record<string, any>;  // 根据 handler_type 动态渲染不同的配置表单
+  enabled: boolean;
+  priority: number;
+  description: string;
+}
+
+// Bot 编辑接口扩展
+interface BotConfig {
+  uuid: string;
+  name: string;
+  adapter: string;
+  adapter_config: Record<string, any>;
+  enable: boolean;
+  event_handlers: EventHandlerRule[];  // 新增
+}
+```
+
+### 7.3 事件类型下拉选项
+
+从 Bot 关联的适配器 manifest 中获取 `supported_events`，加上通配符选项：
+
+```
+- message.received
+- message.edited
+- message.deleted
+- message.reaction
+- feedback.received
+- group.member_joined
+- group.member_left
+- group.member_banned
+- group.info_updated
+- friend.request_received
+- friend.added
+- bot.invited_to_group
+- bot.removed_from_group
+- bot.muted
+- bot.unmuted
+- platform.specific
+─────────────────
+- message.*          (所有消息事件)
+- feedback.*         (所有反馈事件)
+- group.*            (所有群组事件)
+- friend.*           (所有好友事件)
+- bot.*              (所有 Bot 事件)
+- *                  (所有事件)
+```
+
+### 7.4 HTTP API
+
+```
+GET    /api/v1/bots/{uuid}/event-handlers         获取 Bot 的事件处理器配置
+PUT    /api/v1/bots/{uuid}/event-handlers         更新 Bot 的事件处理器配置
+GET    /api/v1/adapters/{name}/supported-events    获取适配器支持的事件类型
+GET    /api/v1/adapters/{name}/supported-apis      获取适配器支持的 API
+```

docs/event-based-agents/05-plugin-sdk.md

@@ -0,0 +1,738 @@
+# 插件 SDK 改造
+
+## 1. 概述
+
+插件 SDK 需要配合 EBA 架构进行以下改造：
+
+1. **新事件类型**：将所有通用事件暴露给插件
+2. **新 API**：将新增的平台 API 通过 `LangBotAPIProxy` 暴露给插件
+3. **兼容层**：保证现有插件零修改运行
+4. **通信协议扩展**：新增 action 枚举支持新 API
+
+## 2. 新事件类型暴露
+
+### 2.1 插件事件模型扩展
+
+当前插件 SDK 的事件模型（`api/entities/events.py`）只有消息相关事件。需要新增所有通用事件的插件级包装：
+
+```python
+# api/entities/events.py — 新增事件
+
+# ---- 消息事件（扩展） ----
+
+class MessageEditedReceived(BaseEventModel):
+    """消息被编辑事件"""
+    launcher_type: str
+    launcher_id: typing.Union[int, str]
+    message_id: typing.Union[int, str]
+    editor_id: typing.Union[int, str]
+    new_content: MessageChain
+    chat_type: str  # "private" | "group"
+
+class MessageDeletedReceived(BaseEventModel):
+    """消息被删除/撤回事件"""
+    launcher_type: str
+    launcher_id: typing.Union[int, str]
+    message_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    chat_type: str
+
+class MessageReactionReceived(BaseEventModel):
+    """消息表情回应事件"""
+    launcher_type: str
+    launcher_id: typing.Union[int, str]
+    message_id: typing.Union[int, str]
+    user_id: typing.Union[int, str]
+    reaction: str
+    is_add: bool
+
+# ---- 用户反馈事件 ----
+
+class FeedbackReceived(BaseEventModel):
+    """用户对 Bot 回复提交反馈"""
+    feedback_id: str
+    feedback_type: int  # 1=like, 2=dislike, 3=cancel/remove feedback
+    feedback_content: typing.Optional[str] = None
+    inaccurate_reasons: typing.Optional[list[str]] = None
+    user_id: typing.Optional[str] = None
+    session_id: typing.Optional[str] = None
+    message_id: typing.Optional[str] = None
+    stream_id: typing.Optional[str] = None
+
+# ---- 群组事件 ----
+
+class GroupMemberJoined(BaseEventModel):
+    """新成员加入群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    member_id: typing.Union[int, str]
+    member_name: str
+    inviter_id: typing.Optional[typing.Union[int, str]] = None
+    join_type: typing.Optional[str] = None
+
+class GroupMemberLeft(BaseEventModel):
+    """成员离开群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    member_id: typing.Union[int, str]
+    member_name: str
+    is_kicked: bool = False
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+class GroupMemberBanned(BaseEventModel):
+    """成员被禁言"""
+    group_id: typing.Union[int, str]
+    member_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    duration: typing.Optional[int] = None
+
+class GroupMemberUnbanned(BaseEventModel):
+    """成员被解除禁言"""
+    group_id: typing.Union[int, str]
+    member_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+class GroupInfoUpdated(BaseEventModel):
+    """群组信息被修改"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    changed_fields: list[str] = []
+
+# ---- 好友事件 ----
+
+class FriendRequestReceived(BaseEventModel):
+    """收到好友请求"""
+    request_id: typing.Union[int, str]
+    user_id: typing.Union[int, str]
+    user_name: str
+    message: typing.Optional[str] = None
+
+class FriendAdded(BaseEventModel):
+    """成功添加好友"""
+    user_id: typing.Union[int, str]
+    user_name: str
+
+class FriendRemoved(BaseEventModel):
+    """好友被移除"""
+    user_id: typing.Union[int, str]
+    user_name: str
+
+# ---- Bot 状态事件 ----
+
+class BotInvitedToGroup(BaseEventModel):
+    """Bot 被邀请加入群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    inviter_id: typing.Optional[typing.Union[int, str]] = None
+    request_id: typing.Optional[typing.Union[int, str]] = None
+
+class BotRemovedFromGroup(BaseEventModel):
+    """Bot 被移出群组"""
+    group_id: typing.Union[int, str]
+    group_name: str
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+class BotMuted(BaseEventModel):
+    """Bot 被禁言"""
+    group_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+    duration: typing.Optional[int] = None
+
+class BotUnmuted(BaseEventModel):
+    """Bot 被解除禁言"""
+    group_id: typing.Union[int, str]
+    operator_id: typing.Optional[typing.Union[int, str]] = None
+
+# ---- 平台特有事件 ----
+
+class PlatformSpecificEventReceived(BaseEventModel):
+    """平台特有事件"""
+    adapter_name: str
+    action: str
+    data: dict = {}
+```
+
+### 2.2 EventListener 注册方式
+
+插件的 EventListener 继续使用 `@self.handler(EventType)` 装饰器注册，只是可以注册的事件类型大幅增加：
+
+```python
+class MyEventListener(EventListener):
+    def __init__(self, host):
+        super().__init__(host)
+
+        # 现有方式（继续工作）
+        @self.handler(PersonNormalMessageReceived)
+        async def on_person_message(ctx: EventContext):
+            ...
+
+        # 新事件类型
+        @self.handler(GroupMemberJoined)
+        async def on_member_joined(ctx: EventContext):
+            group_name = ctx.event.group_name
+            member_name = ctx.event.member_name
+            await ctx.reply(MessageChain([
+                Plain(f"欢迎 {member_name} 加入 {group_name}！")
+            ]))
+
+        @self.handler(FriendRequestReceived)
+        async def on_friend_request(ctx: EventContext):
+            # 自动通过好友请求
+            await ctx.approve_friend_request(
+                ctx.event.request_id, approve=True
+            )
+
+        @self.handler(FeedbackReceived)
+        async def on_feedback(ctx: EventContext):
+            if ctx.event.feedback_type == 2:
+                await self.log_warning(
+                    f"用户点踩了回复: {ctx.event.feedback_content or ''}"
+                )
+
+        @self.handler(PlatformSpecificEventReceived)
+        async def on_platform_event(ctx: EventContext):
+            if ctx.event.adapter_name == "telegram" and ctx.event.action == "chat_join_request":
+                ...
+```
+
+## 3. 新 API 暴露
+
+### 3.1 LangBotAPIProxy 扩展
+
+在 `LangBotAPIProxy` 中新增以下方法，插件通过 `self.xxx()` 调用（在 BasePlugin 中继承）：
+
+```python
+class LangBotAPIProxy:
+    # ---- 现有方法（保留） ----
+    # get_langbot_version, get_bots, get_bot_info,
+    # send_message, invoke_llm, get/set/delete_plugin_storage, ...
+
+    # ---- 新增消息 API ----
+
+    async def edit_message(
+        self,
+        bot_uuid: str,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        new_content: MessageChain,
+    ) -> None:
+        """编辑已发送的消息"""
+        ...
+
+    async def delete_message(
+        self,
+        bot_uuid: str,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """删除/撤回消息"""
+        ...
+
+    async def forward_message(
+        self,
+        bot_uuid: str,
+        from_chat_type: str,
+        from_chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+        to_chat_type: str,
+        to_chat_id: typing.Union[int, str],
+    ) -> dict:
+        """转发消息"""
+        ...
+
+    async def get_message(
+        self,
+        bot_uuid: str,
+        chat_type: str,
+        chat_id: typing.Union[int, str],
+        message_id: typing.Union[int, str],
+    ) -> dict:
+        """获取指定消息"""
+        ...
+
+    # ---- 新增群组 API ----
+
+    async def get_group_info(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+    ) -> dict:
+        """获取群组信息"""
+        ...
+
+    async def get_group_list(
+        self,
+        bot_uuid: str,
+    ) -> list[dict]:
+        """获取 Bot 加入的群组列表"""
+        ...
+
+    async def get_group_member_list(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+    ) -> list[dict]:
+        """获取群成员列表"""
+        ...
+
+    async def get_group_member_info(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> dict:
+        """获取指定群成员信息"""
+        ...
+
+    async def mute_member(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+        duration: int = 0,
+    ) -> None:
+        """禁言群成员"""
+        ...
+
+    async def unmute_member(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """解除禁言"""
+        ...
+
+    async def kick_member(
+        self,
+        bot_uuid: str,
+        group_id: typing.Union[int, str],
+        user_id: typing.Union[int, str],
+    ) -> None:
+        """踢出群成员"""
+        ...
+
+    # ---- 新增用户 API ----
+
+    async def get_user_info(
+        self,
+        bot_uuid: str,
+        user_id: typing.Union[int, str],
+    ) -> dict:
+        """获取用户信息"""
+        ...
+
+    async def get_friend_list(
+        self,
+        bot_uuid: str,
+    ) -> list[dict]:
+        """获取好友列表"""
+        ...
+
+    async def approve_friend_request(
+        self,
+        bot_uuid: str,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """处理好友请求"""
+        ...
+
+    async def approve_group_invite(
+        self,
+        bot_uuid: str,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """处理入群邀请"""
+        ...
+
+    # ---- 新增透传 API ----
+
+    async def call_platform_api(
+        self,
+        bot_uuid: str,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """调用适配器特有 API
+
+        Examples:
+            # Telegram: pin 消息
+            result = await self.call_platform_api(
+                bot_uuid, "pin_message",
+                {"chat_id": 123456, "message_id": 789}
+            )
+
+            # Discord: 创建频道
+            result = await self.call_platform_api(
+                bot_uuid, "create_channel",
+                {"guild_id": "...", "name": "new-channel"}
+            )
+        """
+        ...
+
+    # ---- 新增能力查询 API ----
+
+    async def get_supported_events(
+        self,
+        bot_uuid: str,
+    ) -> list[str]:
+        """获取指定 Bot 的适配器支持的事件类型"""
+        ...
+
+    async def get_supported_apis(
+        self,
+        bot_uuid: str,
+    ) -> list[str]:
+        """获取指定 Bot 的适配器支持的 API"""
+        ...
+```
+
+### 3.2 QueryBasedAPIProxy 扩展
+
+在事件处理上下文中（EventContext），通过 `QueryBasedAPIProxy` 新增便捷方法：
+
+```python
+class QueryBasedAPIProxy:
+    # ---- 现有方法（保留） ----
+    # reply, get_bot_uuid, set_query_var, get_query_var,
+    # create_new_conversation, ...
+
+    # ---- 新增便捷方法 ----
+
+    async def edit_message(
+        self,
+        message_id: typing.Union[int, str],
+        new_content: MessageChain,
+    ) -> None:
+        """在当前会话中编辑消息（自动使用当前 bot_uuid 和 chat 信息）"""
+        ...
+
+    async def delete_message(
+        self,
+        message_id: typing.Union[int, str],
+    ) -> None:
+        """在当前会话中删除消息"""
+        ...
+
+    async def approve_friend_request(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+        remark: typing.Optional[str] = None,
+    ) -> None:
+        """处理好友请求（上下文中自动获取 bot_uuid）"""
+        ...
+
+    async def approve_group_invite(
+        self,
+        request_id: typing.Union[int, str],
+        approve: bool = True,
+    ) -> None:
+        """处理入群邀请"""
+        ...
+
+    async def get_group_info(self) -> dict:
+        """获取当前群组信息（仅群聊事件中可用）"""
+        ...
+
+    async def get_group_member_list(self) -> list[dict]:
+        """获取当前群组成员列表（仅群聊事件中可用）"""
+        ...
+
+    async def call_platform_api(
+        self,
+        action: str,
+        params: dict = {},
+    ) -> dict:
+        """调用平台特有 API（自动使用当前 bot_uuid）"""
+        ...
+```
+
+## 4. 兼容层设计
+
+### 4.1 事件兼容层
+
+当 PluginHandler 将新的 `MessageReceivedEvent` 分发给插件时，需要同时生成旧格式事件：
+
+```python
+class PluginEventCompatLayer:
+    """插件事件兼容层
+
+    将新的统一事件转换为旧的插件事件格式，
+    确保监听旧事件类型的插件仍能正常工作。
+    """
+
+    @staticmethod
+    def convert_to_legacy_events(
+        event: Event,
+    ) -> list[BaseEventModel]:
+        """将统一事件转换为旧插件事件列表
+
+        一个统一事件可能生成多个旧插件事件。
+        例如 MessageReceivedEvent 会同时生成：
+        - PersonMessageReceived / GroupMessageReceived（总是生成）
+        - PersonNormalMessageReceived / GroupNormalMessageReceived（非命令时）
+        - PersonCommandSent / GroupCommandSent（命令时）
+        """
+        legacy_events = []
+
+        if isinstance(event, MessageReceivedEvent):
+            if event.chat_type == ChatType.PRIVATE:
+                legacy_events.append(
+                    PersonMessageReceived(
+                        launcher_type="person",
+                        launcher_id=event.chat_id,
+                        sender_id=event.sender.id,
+                        message_event=event.to_legacy_friend_message(),
+                        message_chain=event.message_chain,
+                    )
+                )
+                # 命令检测后还会生成 PersonNormalMessageReceived
+                # 或 PersonCommandSent，在 Pipeline 阶段处理
+            elif event.chat_type == ChatType.GROUP:
+                legacy_events.append(
+                    GroupMessageReceived(
+                        launcher_type="group",
+                        launcher_id=event.chat_id,
+                        sender_id=event.sender.id,
+                        message_event=event.to_legacy_group_message(),
+                        message_chain=event.message_chain,
+                    )
+                )
+
+        # 新事件类型没有旧的对应物，不生成兼容事件
+        # 只有监听了新事件类型的插件才会收到
+
+        return legacy_events
+```
+
+### 4.2 分发流程
+
+```
+统一事件 (MessageReceivedEvent)
+    │
+    ├─→ 转换为旧格式 (PersonMessageReceived / GroupMessageReceived)
+    │   └─→ 分发给监听旧事件类型的插件 EventListener
+    │
+    └─→ 直接分发为新格式 (MessageReceivedEvent → 对应的插件事件)
+        └─→ 分发给监听新事件类型的插件 EventListener
+```
+
+插件 Runtime 在分发事件时检查每个 EventListener 注册的事件类型：
+- 如果注册的是旧类型（`PersonMessageReceived` 等），发送兼容层生成的旧格式事件
+- 如果注册的是新类型（`GroupMemberJoined` 等），发送新格式事件
+- 两者可以共存，同一个插件可以同时监听新旧类型
+
+### 4.3 API 兼容层
+
+现有插件使用的 API 不受影响：
+
+| 现有 API | 新架构行为 |
+|---------|----------|
+| `self.send_message(bot_uuid, target_type, target_id, message_chain)` | 不变，直接调用适配器的 `send_message` |
+| `ctx.reply(message_chain, quote_origin)` | 不变，在 MessageReceivedEvent 上下文中调用适配器的 `reply_message` |
+| `self.get_bots()` | 不变 |
+| `self.get_bot_info(bot_uuid)` | 不变 |
+
+新 API 只是额外新增的方法，不影响现有方法。
+
+## 5. 通信协议扩展
+
+### 5.1 新增 Action 枚举
+
+在 `entities/io/actions/enums.py` 中新增 action：
+
+```python
+class PluginToRuntimeAction(str, Enum):
+    # ---- 现有 actions（保留） ----
+    REGISTER_PLUGIN = "register_plugin"
+    REPLY = "reply"
+    SEND_MESSAGE = "send_message"
+    # ...
+
+    # ---- 新增消息 API ----
+    EDIT_MESSAGE = "edit_message"
+    DELETE_MESSAGE = "delete_message"
+    FORWARD_MESSAGE = "forward_message"
+    GET_MESSAGE = "get_message"
+
+    # ---- 新增群组 API ----
+    GET_GROUP_INFO = "get_group_info"
+    GET_GROUP_LIST = "get_group_list"
+    GET_GROUP_MEMBER_LIST = "get_group_member_list"
+    GET_GROUP_MEMBER_INFO = "get_group_member_info"
+    MUTE_MEMBER = "mute_member"
+    UNMUTE_MEMBER = "unmute_member"
+    KICK_MEMBER = "kick_member"
+
+    # ---- 新增用户 API ----
+    GET_USER_INFO = "get_user_info"
+    GET_FRIEND_LIST = "get_friend_list"
+    APPROVE_FRIEND_REQUEST = "approve_friend_request"
+    APPROVE_GROUP_INVITE = "approve_group_invite"
+
+    # ---- 新增透传 API ----
+    CALL_PLATFORM_API = "call_platform_api"
+
+    # ---- 新增能力查询 ----
+    GET_SUPPORTED_EVENTS = "get_supported_events"
+    GET_SUPPORTED_APIS = "get_supported_apis"
+
+
+class RuntimeToPluginAction(str, Enum):
+    # ---- 现有 actions（保留） ----
+    EMIT_EVENT = "emit_event"
+    # ...
+    # EMIT_EVENT 的 data 结构扩展以支持新事件类型
+```
+
+### 5.2 新增 Action 的请求/响应格式
+
+以 `EDIT_MESSAGE` 为例：
+
+```json
+// 请求 (Plugin → Runtime)
+{
+    "action": "edit_message",
+    "seq_id": 12345,
+    "data": {
+        "bot_uuid": "...",
+        "chat_type": "group",
+        "chat_id": "123456",
+        "message_id": "789",
+        "new_content": [
+            { "type": "Plain", "text": "edited message" }
+        ]
+    }
+}
+
+// 响应 (Runtime → Plugin)
+{
+    "seq_id": 12345,
+    "code": 0,
+    "message": "ok",
+    "data": {}
+}
+```
+
+以 `GET_GROUP_MEMBER_LIST` 为例：
+
+```json
+// 请求
+{
+    "action": "get_group_member_list",
+    "seq_id": 12346,
+    "data": {
+        "bot_uuid": "...",
+        "group_id": "123456"
+    }
+}
+
+// 响应
+{
+    "seq_id": 12346,
+    "code": 0,
+    "message": "ok",
+    "data": {
+        "members": [
+            {
+                "user": { "id": "111", "nickname": "Alice" },
+                "group_id": "123456",
+                "role": "admin",
+                "display_name": "管理员Alice"
+            },
+            ...
+        ]
+    }
+}
+```
+
+以 `CALL_PLATFORM_API` 为例：
+
+```json
+// 请求
+{
+    "action": "call_platform_api",
+    "seq_id": 12347,
+    "data": {
+        "bot_uuid": "...",
+        "action": "pin_message",
+        "params": {
+            "chat_id": "123456",
+            "message_id": "789"
+        }
+    }
+}
+
+// 响应
+{
+    "seq_id": 12347,
+    "code": 0,
+    "message": "ok",
+    "data": {
+        "result": { ... }
+    }
+}
+```
+
+### 5.3 LangBot 侧 Handler 实现
+
+在 `ControlConnectionHandler`（LangBot → Runtime 侧）和 `PluginConnectionHandler`（Runtime → Plugin 侧）中新增对应的 action 处理逻辑：
+
+```python
+# PluginConnectionHandler 中新增
+async def _handle_edit_message(self, data):
+    bot_uuid = data["bot_uuid"]
+    bot = await self.ap.platform_mgr.get_bot_by_uuid(bot_uuid)
+    await bot.adapter.edit_message(
+        chat_type=data["chat_type"],
+        chat_id=data["chat_id"],
+        message_id=data["message_id"],
+        new_content=MessageChain.model_validate(data["new_content"]),
+    )
+    return {}
+
+async def _handle_call_platform_api(self, data):
+    bot_uuid = data["bot_uuid"]
+    bot = await self.ap.platform_mgr.get_bot_by_uuid(bot_uuid)
+    result = await bot.adapter.call_platform_api(
+        action=data["action"],
+        params=data.get("params", {}),
+    )
+    return {"result": result}
+```
+
+## 6. 插件开发者迁移指南
+
+### 6.1 无需迁移（零修改运行）
+
+以下场景的现有插件**不需要任何修改**：
+
+- 使用 `PersonNormalMessageReceived` / `GroupNormalMessageReceived` 监听消息
+- 使用 `PersonCommandSent` / `GroupCommandSent` 处理命令
+- 使用 `ctx.reply()` 回复消息
+- 使用 `self.send_message()` 主动发消息
+- 使用 LLM / 存储 / RAG 等现有 API
+
+### 6.2 推荐迁移（获得新能力）
+
+如果插件希望利用新功能，可以：
+
+1. **监听新事件类型**：在 EventListener 中注册新事件类型的 handler
+2. **使用新 API**：调用 `self.edit_message()`, `self.get_group_info()` 等
+3. **使用透传 API**：调用 `self.call_platform_api()` 使用平台特有功能
+
+### 6.3 SDK 版本号
+
+新功能通过提升 SDK minor 版本发布：
+
+- 现有版本：`langbot-plugin-sdk >= x.y.z`
+- 新版本：`langbot-plugin-sdk >= x.(y+1).0`
+
+插件的 `manifest.yaml` 中的 `min_sdk_version` 决定是否能使用新 API。使用旧 SDK 版本的插件在新 LangBot 上正常运行（兼容层保证），只是无法调用新 API。

docs/event-based-agents/06-migration-plan.md

@@ -0,0 +1,431 @@
+# 分阶段迁移计划
+
+> **2026-06 方向修订**：Phase 3 的「四种 Handler 框架」与 Phase 5 的编排面板形态，按 [07-agent-orchestration.md](./07-agent-orchestration.md) 调整为「事件 → Agent」统一编排（EventRouter + Agent 实体 + 绑定模型 + SDK Agent 组件契约）。阶段划分、依赖关系与验收标准仍然适用，按 Agent 模型重新解读即可；发布节奏见 07 §5「发布火车」。
+
+## 1. 概述
+
+EBA 架构涉及 langbot-plugin-sdk、LangBot 后端、LangBot 前端、文档和示例插件等多个仓库的改动。为降低风险、保证系统稳定性，采用分阶段渐进式迁移策略。
+
+### 1.1 阶段总览
+
+| 阶段 | 名称 | 范围 | 依赖 |
+|------|------|------|------|
+| Phase 1 | SDK 实体层 | langbot-plugin-sdk | 无 |
+| Phase 2 | 适配器重构 | LangBot 后端 | Phase 1 |
+| Phase 3 | 核心系统 | LangBot 后端 | Phase 2 |
+| Phase 4 | 插件 SDK 集成 | langbot-plugin-sdk + LangBot | Phase 3 |
+| Phase 5 | WebUI 编排面板 | LangBot 前端 | Phase 3 |
+| Phase 6 | 文档与示例 | langbot-wiki + langbot-plugin-demo | Phase 4, 5 |
+
+### 1.2 核心原则
+
+- **每个阶段结束后系统可运行**：任何阶段完成后，现有功能不受影响
+- **向后兼容贯穿全程**：旧接口在整个迁移期间保持可用
+- **先 SDK 后实现**：先定义好接口和模型，再做具体实现
+- **先核心适配器后边缘**：优先迁移用户量大的适配器
+
+---
+
+## 2. Phase 1：SDK 实体层
+
+**目标**：在 langbot-plugin-sdk 中定义新的事件体系、通用实体、API 接口和适配器基类。
+
+**仓库**：`langbot-plugin-sdk`
+
+### 2.1 任务清单
+
+| # | 任务 | 文件/模块 | 说明 |
+|---|------|----------|------|
+| 1.1 | 定义通用事件基类层次 | `api/entities/builtin/platform/events.py` | 新增 `MessageReceivedEvent`, `MessageEditedEvent`, `GroupMemberJoinedEvent` 等，保留现有 `FriendMessage`/`GroupMessage` |
+| 1.2 | 定义平台特有事件基类 | `api/entities/builtin/platform/events.py` | 新增 `PlatformSpecificEvent` |
+| 1.3 | 扩展通用实体 | `api/entities/builtin/platform/entities.py` | 新增 `User`（统一 Friend/GroupMember 的基础）、`Channel` 等，保留现有实体 |
+| 1.4 | 清理消息组件 | `api/entities/builtin/platform/message.py` | 将 `WeChatMiniPrograms` 等 WeChat 特有组件标记为 platform-specific，不再作为通用组件 |
+| 1.5 | 定义新适配器基类 | `api/definition/abstract/platform/adapter.py` | 新增 `AbstractPlatformAdapter`（继承现有 `AbstractMessagePlatformAdapter` 并扩展通用 API 方法），保留旧基类 |
+| 1.6 | 定义 API 能力声明 | `api/definition/abstract/platform/capabilities.py`（新文件） | `AdapterCapabilities` 数据类，声明适配器支持的事件和 API |
+| 1.7 | 定义 `NotSupportedError` | `api/entities/builtin/platform/errors.py`（新文件） | 可选 API 未实现时抛出的异常 |
+
+### 2.2 关键设计约束
+
+- 所有新增定义以**新增文件或新增类**的方式引入，**不修改**现有类的字段和方法签名
+- 现有 `AbstractMessagePlatformAdapter` 保留不动，新基类 `AbstractPlatformAdapter` 继承它
+- 新事件类与旧事件类并存，通过 `event_type` 字段（命名空间字符串）区分
+
+### 2.3 验收标准
+
+- [ ] 所有新增类可正常 import 且通过类型检查
+- [ ] 现有 `FriendMessage`, `GroupMessage`, `AbstractMessagePlatformAdapter` 等类行为不变
+- [ ] 新增单元测试覆盖事件序列化/反序列化、实体构造
+- [ ] SDK 版本号 minor bump（如 `0.x.0` → `0.x+1.0`）
+
+---
+
+## 3. Phase 2：适配器重构
+
+**目标**：将现有单文件适配器迁移到独立目录结构，实现新事件监听和通用 API。
+
+**仓库**：`LangBot`（后端）
+
+### 3.1 适配器迁移优先级
+
+根据用户量和代表性，建议按以下顺序迁移：
+
+| 优先级 | 适配器 | 理由 |
+|--------|--------|------|
+| P0 | **Telegram** | 用户量大，API 最完善，适合作为参考实现 |
+| P0 | **Discord** | 国际用户主要平台，事件类型丰富 |
+| P1 | **aiocqhttp**（OneBot v11） | 国内 QQ 用户主要适配器 |
+| P1 | **Satori** | 通用协议适配器，覆盖多个平台 |
+| P2 | **Lark** / **DingTalk** / **Slack** | 企业平台，用户量中等 |
+| P2 | **qqofficial** / **WeChat 系列** | 国内用户 |
+| P3 | **Kook** / **LINE** / **WeCom 系列** | 用户量较小 |
+| P3 | **WebSocket** | 内置适配器，相对简单 |
+| P4 | **legacy/*** | 遗留适配器，按需决定是否迁移或废弃 |
+
+### 3.2 单个适配器迁移步骤（以 Telegram 为例）
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 2.1 | 创建目录结构 | `pkg/platform/adapters/telegram/` 下创建 `__init__.py`, `adapter.py`, `event_converter.py`, `message_converter.py`, `api_impl.py`, `types.py`, `manifest.yaml` |
+| 2.2 | 迁移消息转换器 | 将 `TelegramMessageConverter` 从 `sources/telegram.py` 搬到 `adapters/telegram/message_converter.py`，逻辑不变 |
+| 2.3 | 重写事件转换器 | 新的 `TelegramEventConverter` 支持将 Telegram Update 转换为所有通用事件类型（不只是消息），不支持的事件转为 `PlatformSpecificEvent` |
+| 2.4 | 实现通用 API | 在 `api_impl.py` 中实现 `edit_message`, `delete_message`, `get_group_info` 等 Telegram 支持的通用 API |
+| 2.5 | 实现透传 API | 在 `adapter.py` 中实现 `call_platform_api`，将 action 映射到 Telegram Bot API 调用 |
+| 2.6 | 声明能力 | 在 `manifest.yaml` 或适配器类中声明支持的事件和 API 列表 |
+| 2.7 | 新建 Adapter 主类 | `TelegramAdapter` 继承 `AbstractPlatformAdapter`（新基类），委托各模块实现 |
+| 2.8 | 更新 manifest.yaml | 更新 `execution.python.path` 指向新位置 |
+| 2.9 | 验证 | 确保新适配器通过现有消息收发流程的测试 |
+
+### 3.3 基础设施任务
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 2.A | 创建 `adapters/_base/` | 将 SDK 中新基类的运行时辅助代码放在此处（如事件分发辅助函数） |
+| 2.B | 更新 ComponentDiscovery | 使 `discover_blueprint` 支持扫描 `adapters/` 子目录中的 YAML |
+| 2.C | 更新 `templates/components.yaml` | 将 `fromDirs` 从 `pkg/platform/sources/` 改为 `pkg/platform/adapters/`（过渡期两个都扫描） |
+| 2.D | 保留旧 sources/ | 过渡期不删除旧文件，通过 manifest 的 `deprecated: true` 标记 |
+
+### 3.4 验收标准
+
+- [ ] 已迁移的适配器在新目录结构下正常启动和收发消息
+- [ ] 新事件（如 `message.edited`）在支持的平台上正确触发
+- [ ] 通用 API（如 `edit_message`）在支持的平台上正确执行
+- [ ] 未迁移的适配器（仍在 `sources/`）继续正常工作
+- [ ] ComponentDiscovery 同时扫描新旧目录
+
+---
+
+## 4. Phase 3：核心系统
+
+**目标**：实现 EventBus、EventRouter 和事件处理器框架，将事件从适配器分发到不同的处理器。
+
+**仓库**：`LangBot`（后端）
+
+### 4.1 任务清单
+
+| # | 任务 | 文件/模块 | 说明 |
+|---|------|----------|------|
+| 3.1 | 实现 EventBus | `pkg/platform/event_bus.py`（新文件） | 事件总线：接收适配器事件，进行日志记录，分发给 EventRouter |
+| 3.2 | 实现 EventRouter | `pkg/platform/event_router.py`（新文件） | 事件路由引擎：读取 Bot 的 `event_handlers` 配置，匹配事件类型，分发到对应 Handler |
+| 3.3 | 实现 PipelineHandler | `pkg/platform/handlers/pipeline_handler.py` | 将 `message.received` 事件转为现有 Query，进入 Pipeline 流水线 |
+| 3.4 | 实现 AgentHandler | `pkg/platform/handlers/agent_handler.py` | 直接调用 RequestRunner 处理事件，不经过 Pipeline 多 Stage 流程 |
+| 3.5 | 实现 WebhookHandler | `pkg/platform/handlers/webhook_handler.py` | 将事件 POST 到外部 URL，解析响应执行动作（重构现有 WebhookPusher） |
+| 3.6 | 实现 PluginHandler | `pkg/platform/handlers/plugin_handler.py` | 将事件分发给插件 EventListener（复用现有 plugin_connector 机制） |
+| 3.7 | Bot 实体扩展 | `pkg/entity/persistence/bot.py` | 新增 `event_handlers` JSON 字段 |
+| 3.8 | 数据库迁移 | `pkg/persistence/migrations/` | 新增迁移脚本：添加 `event_handlers` 列，将现有 `use_pipeline_uuid` 数据迁移为 `event_handlers` 格式 |
+| 3.9 | 重构 RuntimeBot | `pkg/platform/botmgr.py` | 将 `initialize()` 中硬编码的 `on_friend_message`/`on_group_message` 回调替换为通过 EventBus 分发所有事件 |
+| 3.10 | 重构 MessageAggregator | `pkg/pipeline/aggregator.py` | 从 RuntimeBot 解耦，作为 PipelineHandler 的内部机制（只对 `message.received` 事件生效） |
+| 3.11 | Agent Handler 中 RequestRunner 解耦 | `pkg/provider/runner.py` + handlers | RequestRunner 需要能独立于 Pipeline Stage 运行，为 Agent Handler 提供轻量调用路径 |
+| 3.12 | HTTP API 扩展 | `pkg/api/http/controller/` | 新增/更新 Bot API 端点以支持 `event_handlers` 的 CRUD |
+
+### 4.2 数据迁移策略
+
+现有 Bot 表有 `use_pipeline_uuid` 字段，需要自动迁移为 `event_handlers`：
+
+```python
+# 迁移逻辑伪代码
+for bot in all_bots:
+    if bot.use_pipeline_uuid:
+        bot.event_handlers = [
+            {
+                "event_type": "message.received",
+                "handler_type": "pipeline",
+                "handler_config": {
+                    "pipeline_uuid": bot.use_pipeline_uuid
+                }
+            }
+        ]
+    else:
+        bot.event_handlers = []
+```
+
+### 4.3 RuntimeBot 重构要点
+
+当前 `RuntimeBot.initialize()` 硬编码注册两个回调：
+
+```python
+# 现有代码 (botmgr.py)
+self.adapter.register_listener(FriendMessage, on_friend_message)
+self.adapter.register_listener(GroupMessage, on_group_message)
+```
+
+重构后改为注册通用事件回调：
+
+```python
+# 新代码
+async def on_event(event: Event, adapter: AbstractPlatformAdapter):
+    await self.event_bus.emit(
+        bot_uuid=self.bot_entity.uuid,
+        event=event,
+        adapter=adapter,
+    )
+
+# 注册所有事件类型的统一回调
+self.adapter.register_listener(Event, on_event)
+```
+
+EventBus 接收事件后，调用 EventRouter 按配置分发。
+
+### 4.4 事件处理器执行流程
+
+```
+EventBus.emit(bot_uuid, event, adapter)
+    │
+    ▼
+EventRouter.route(bot_uuid, event)
+    │ 查询 bot.event_handlers 配置
+    │ 匹配 event_type（精确匹配 > 通配符 *）
+    ▼
+匹配到的 Handler(s)
+    │
+    ├── PipelineHandler.handle(event, adapter)
+    │   │ 仅支持 message.received
+    │   │ 构造 Query → MessageAggregator → QueryPool → Pipeline
+    │   └── 沿用现有完整流水线机制
+    │
+    ├── AgentHandler.handle(event, adapter)
+    │   │ 根据 handler_config 选择 RequestRunner
+    │   │ 直接调用 runner.run() 处理事件
+    │   └── 将结果通过 adapter API 回复
+    │
+    ├── WebhookHandler.handle(event, adapter)
+    │   │ 序列化事件为 JSON
+    │   │ POST 到 handler_config.url
+    │   └── 解析响应，执行动作（回复消息、调用 API 等）
+    │
+    └── PluginHandler.handle(event, adapter)
+        │ 通过 plugin_connector 分发给插件
+        └── 插件 EventListener 处理
+```
+
+### 4.5 验收标准
+
+- [ ] `message.received` 事件通过 PipelineHandler 正确进入现有 Pipeline（与旧行为一致）
+- [ ] 新增事件（如 `group.member_joined`）能通过 PluginHandler 分发给插件
+- [ ] AgentHandler 能直接调用 RequestRunner（至少 `local-agent`）处理事件并回复
+- [ ] WebhookHandler 能将事件 POST 到外部 URL
+- [ ] 数据库迁移正确执行，`use_pipeline_uuid` 数据迁移到 `event_handlers`
+- [ ] 现有 Bot 在不修改配置的情况下行为不变（自动迁移保证）
+
+---
+
+## 5. Phase 4：插件 SDK 集成
+
+**目标**：将新事件和 API 通过插件 SDK 暴露给插件开发者，同时实现兼容层。
+
+**仓库**：`langbot-plugin-sdk` + `LangBot`
+
+### 5.1 任务清单
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 4.1 | 新增插件事件包装 | 在 `api/entities/events.py` 中为每个通用事件新增插件级事件类（如 `MessageEditedReceived`, `MemberJoinedReceived`） |
+| 4.2 | 兼容层实现 | `PersonMessageReceived` / `GroupMessageReceived` 由新的 `MessageReceivedEvent` 自动生成，旧事件作为新事件的 alias |
+| 4.3 | 新 API 暴露 | 在 `LangBotAPIProxy` 中新增方法：`edit_message`, `delete_message`, `get_group_info`, `get_user_info`, `call_platform_api` 等 |
+| 4.4 | 通信协议扩展 | 在 `entities/io/actions/enums.py` 中新增 action 枚举（如 `EDIT_MESSAGE`, `DELETE_MESSAGE`, `GET_GROUP_INFO`, `CALL_PLATFORM_API`） |
+| 4.5 | Runtime Handler 扩展 | 在 PluginConnectionHandler / ControlConnectionHandler 中添加新 action 的处理逻辑 |
+| 4.6 | EventListener 扩展 | 确保 `@handler()` 装饰器支持注册新事件类型 |
+| 4.7 | QueryBasedAPI 扩展 | 在 `QueryBasedAPIProxy` 中新增事件上下文相关的 API（如 `get_event_source_adapter`） |
+
+### 5.2 兼容层详细设计
+
+```
+新事件系统                         旧事件系统（兼容层）
+─────────────                    ─────────────────
+MessageReceivedEvent             ┌→ PersonMessageReceived (chat_type == "private")
+  (chat_type: "private"|"group") ┤
+                                 └→ GroupMessageReceived  (chat_type == "group")
+```
+
+**实现方式**：在 RuntimeEventDispatcher 中，当分发 `MessageReceivedEvent` 给插件时，同时生成对应的旧事件类实例。插件可以用新事件类或旧事件类注册 handler，都能收到。
+
+### 5.3 验收标准
+
+- [ ] 现有插件（使用旧事件和 API）无需修改即可运行
+- [ ] 新插件可以使用新事件类型（如 `MemberJoinedReceived`）注册 handler
+- [ ] 新 API（如 `edit_message`）可通过 `self.edit_message()` 或 `event_context.edit_message()` 调用
+- [ ] 透传 API `call_platform_api` 可正常调用适配器特有功能
+- [ ] 所有新 action 的通信协议正确工作（stdio / WebSocket）
+
+---
+
+## 6. Phase 5：WebUI 编排面板
+
+**目标**：在 WebUI 的 Bot 管理页面实现事件处理器的可视化编排。
+
+**仓库**：`LangBot`（前端 `web/`）
+
+### 6.1 任务清单
+
+| # | 任务 | 说明 |
+|---|------|------|
+| 5.1 | Bot 编辑页面扩展 | 在 Bot 编辑页面新增「事件处理」面板 |
+| 5.2 | 事件处理器列表组件 | 可视化展示当前 Bot 的 `event_handlers` 列表，支持增删改排序 |
+| 5.3 | 事件类型选择器 | 下拉选择事件类型（命名空间分组展示），支持通配符 `*` |
+| 5.4 | Handler 类型选择与配置 | 选择 handler 类型后展示对应的配置表单（Pipeline 选择器、Runner 选择器、Webhook URL 等） |
+| 5.5 | Pipeline Handler 配置 | 复用现有的 Pipeline 选择 UI（从现有 `use_pipeline_uuid` 选择器迁移） |
+| 5.6 | Agent Handler 配置 | Runner 选择器（local-agent / dify / n8n / coze 等）+ Runner 参数配置表单 |
+| 5.7 | Webhook Handler 配置 | URL 输入、认证方式选择、Header 配置 |
+| 5.8 | Plugin Handler 配置 | 通常无需额外配置，分发给所有匹配的插件 EventListener |
+| 5.9 | HTTP API 对接 | 前端调用后端 API 保存/读取 `event_handlers` 配置 |
+| 5.10 | 迁移提示 | 对于从旧版本升级的用户，如果检测到 `use_pipeline_uuid` 已自动迁移，展示提示说明 |
+
+### 6.2 UI 交互设计概要
+
+```
+┌─ Bot 编辑页面 ─────────────────────────────────────┐
+│                                                     │
+│  基本信息  │  适配器配置  │  ★ 事件处理  │           │
+│                                                     │
+│  ┌─ 事件处理器列表 ────────────────────────────┐    │
+│  │                                              │    │
+│  │  ① message.received → Pipeline: "主流水线"   │    │
+│  │     [编辑] [删除]                            │    │
+│  │                                              │    │
+│  │  ② group.member_joined → Agent: local-agent  │    │
+│  │     [编辑] [删除]                            │    │
+│  │                                              │    │
+│  │  ③ * (默认) → Plugin                         │    │
+│  │     [编辑] [删除]                            │    │
+│  │                                              │    │
+│  │  [+ 添加事件处理器]                           │    │
+│  │                                              │    │
+│  └──────────────────────────────────────────────┘    │
+│                                                     │
+│                              [保存]  [取消]          │
+└─────────────────────────────────────────────────────┘
+```
+
+### 6.3 验收标准
+
+- [ ] 用户可以在 WebUI 上为 Bot 添加/编辑/删除事件处理器
+- [ ] 四种 Handler 类型均有对应的配置表单
+- [ ] 配置保存后正确写入数据库 `event_handlers` 字段
+- [ ] 旧版本升级后，自动迁移的配置在 UI 上正确展示
+- [ ] Pipeline Handler 的行为与旧的 `use_pipeline_uuid` 完全一致
+
+---
+
+## 7. Phase 6：文档与示例
+
+**目标**：更新所有面向开发者的文档和示例。
+
+**仓库**：`langbot-wiki`, `langbot-plugin-demo`
+
+### 7.1 任务清单
+
+| # | 任务 | 仓库 | 说明 |
+|---|------|------|------|
+| 6.1 | EBA 架构概览文档 | langbot-wiki | 面向用户的新架构说明 |
+| 6.2 | 适配器开发指南更新 | langbot-wiki | 如何开发一个新的适配器（新目录结构、新基类、事件转换等） |
+| 6.3 | 插件开发指南更新 | langbot-wiki | 新事件类型、新 API 的使用说明 |
+| 6.4 | 插件迁移指南 | langbot-wiki | 现有插件如何迁移到新事件/API（如果需要使用新能力） |
+| 6.5 | 事件处理器配置指南 | langbot-wiki | WebUI 上如何配置事件处理器 |
+| 6.6 | 示例插件更新 | langbot-plugin-demo | HelloPlugin 增加新事件监听示例、新 API 调用示例 |
+| 6.7 | 新示例插件 | langbot-plugin-demo | 新建一个示例展示非消息事件处理（如入群欢迎） |
+
+---
+
+## 8. 风险评估与缓解
+
+### 8.1 技术风险
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| 适配器迁移中断现有功能 | 高 | 中 | 新旧目录并存，ComponentDiscovery 同时扫描两个目录，逐个适配器迁移验证 |
+| 事件模型不兼容导致插件崩溃 | 高 | 低 | 兼容层保证旧事件类型继续工作，新增类不修改旧类 |
+| 数据库迁移失败 | 高 | 低 | 迁移脚本做前置校验，`use_pipeline_uuid` 在过渡期保留不删除 |
+| RequestRunner 解耦破坏 Pipeline | 高 | 中 | Agent Handler 调用 Runner 的路径独立于 Pipeline，不修改现有 Pipeline Stage 中的 Runner 调用逻辑 |
+| 性能回退（EventBus 额外开销） | 中 | 低 | EventBus 在进程内同步分发，无额外序列化/网络开销 |
+| 各平台事件差异大难以统一 | 中 | 中 | 通用事件只抽象最大公约数字段，差异部分保留在 `source_platform_object`；不支持的事件走 `PlatformSpecificEvent` |
+
+### 8.2 兼容性风险
+
+| 风险 | 缓解措施 |
+|------|----------|
+| 现有插件使用旧事件类 | 兼容层自动将新事件转为旧事件分发，两种事件类都能注册 handler |
+| 现有插件调用 `reply()` / `send_message()` | 这两个 API 保持不变，只是底层实现可能微调 |
+| 第三方基于 `AbstractMessagePlatformAdapter` 开发的适配器 | 旧基类保留，新基类继承旧基类，第三方适配器无需立即迁移 |
+| 用户自定义 Pipeline 配置 | Pipeline 机制完整保留，PipelineHandler 只是入口变了（从 RuntimeBot 硬编码变为 EventRouter 配置） |
+
+### 8.3 回滚策略
+
+每个 Phase 独立可回滚：
+
+- **Phase 1**（SDK 新增类）：删除新增文件，回退 SDK 版本号
+- **Phase 2**（适配器目录）：恢复 `components.yaml` 的 `fromDirs` 指向旧目录，旧 sources/ 未删除
+- **Phase 3**（核心系统）：回退数据库迁移，恢复 RuntimeBot 旧的硬编码回调
+- **Phase 4**（插件集成）：回退 SDK 版本，插件使用旧版 SDK
+- **Phase 5**（WebUI）：前端回退，Bot 编辑页面隐藏事件处理面板
+
+---
+
+## 9. 里程碑与时间线建议
+
+| 里程碑 | 阶段 | 预期产出 |
+|--------|------|----------|
+| M1 | Phase 1 完成 | SDK 新版本发布，包含新事件/实体/基类定义 |
+| M2 | Phase 2 首批适配器（Telegram + Discord） | 两个参考实现，验证目录结构和事件/API 体系 |
+| M3 | Phase 3 核心系统 | EventBus + EventRouter + 四种 Handler 可用 |
+| M4 | Phase 2 剩余适配器 | 所有活跃适配器迁移完成 |
+| M5 | Phase 4 插件集成 | 新 SDK 发布，插件可使用新事件和 API |
+| M6 | Phase 5 WebUI | 事件处理器编排面板上线 |
+| M7 | Phase 6 文档 | 开发者文档和示例更新完毕 |
+
+建议 M1-M3 作为第一个大版本发布（如 v5.0），M4-M7 在后续小版本迭代中完成。
+
+---
+
+## 10. 开发指引
+
+### 10.1 分支策略
+
+建议在主仓库创建 `feature/eba` 长期特性分支，各 Phase 在子分支上开发后合入特性分支：
+
+```
+main
+  └── feature/eba
+        ├── feature/eba-sdk-entities      (Phase 1)
+        ├── feature/eba-adapter-telegram   (Phase 2)
+        ├── feature/eba-adapter-discord    (Phase 2)
+        ├── feature/eba-core-system        (Phase 3)
+        ├── feature/eba-plugin-sdk         (Phase 4)
+        └── feature/eba-webui              (Phase 5)
+```
+
+### 10.2 测试策略
+
+| 层次 | 测试内容 | 工具 |
+|------|----------|------|
+| 单元测试 | 事件序列化/反序列化、实体构造、API 调用 mock | pytest |
+| 集成测试 | EventBus → EventRouter → Handler 全链路 | pytest + asyncio |
+| 适配器测试 | 各适配器的事件转换、消息转换、API 调用 | pytest + mock SDK |
+| 端到端测试 | 从模拟平台事件到完整处理流程 | staging 环境 |
+| 插件兼容性测试 | 旧插件在新系统下的行为 | langbot-plugin-demo |
+
+### 10.3 代码审查关注点
+
+- 新增代码是否影响现有行为
+- 兼容层是否正确映射所有旧事件/API 场景
+- 数据库迁移是否可逆
+- 新 API 的错误处理（`NotSupportedError`）是否一致
+- 事件模型的序列化在 stdio/WebSocket 通信中是否正确

docs/event-based-agents/07-agent-orchestration.md

@@ -0,0 +1,187 @@
+# Agent 统一编排（产品最终形态）
+
+> **状态**：方向修订稿（2026-06-12），供「适配器改造 / Agent 插件化 / 工作流引擎」三条工作线评审。
+>
+> 本文档修订 [00-overview.md](./00-overview.md) §3.4 与 [04-event-routing.md](./04-event-routing.md) 中"四种 Handler"的编排模型：**所有编排目标统一收编为 Agent 抽象**。事件路由的匹配机制、数据迁移策略、WebUI 交互骨架等内容仍以 04 为准，仅 handler 分类法被本文档取代。
+
+## 1. 产品最终形态
+
+**适配器接收各种事件 → 用户编排处理逻辑 → Agent 统一抽象**，实现从 0 代码到低代码再到全代码的全层面支持：
+
+```
+消息平台 (Telegram / Discord / 企微 / ...)
+  │ 各类平台事件
+  ▼
+平台适配器（EBA 新结构，已迁移 12 个）
+  │ EBAEvent (message.* / group.* / friend.* / bot.* / feedback.* / platform.*)
+  ▼
+EventRouter（事件 → Agent 绑定）
+  ├─→ 选中的 Agent（响应者，单一仲裁）
+  │     ├─ 内置：pipeline-wrapper（旧流水线收编）/ local-agent
+  │     ├─ 插件：SDK Agent 组件（全代码）
+  │     ├─ 低代码：工作流定义的 Agent（内部工作流引擎）
+  │     └─ 外部：dify / n8n / coze / dashscope / webhook（RequestRunner 体系收编）
+  │
+  └─→ 插件 EventListener（观察者，N 个广播，可 prevent_default）
+```
+
+| 编写方式 | Agent 形态 | 代码化程度 |
+|----------|-----------|-----------|
+| WebUI 配置模型 + 提示词 + 工具 | 内置 local-agent | 0 代码 |
+| 沿用现有流水线 | pipeline-wrapper 内置 Agent | 0 代码（兼容） |
+| 市场安装 | Agent 插件（市场分发） | 0 代码（使用者视角） |
+| 可视化工作流 | 工作流引擎定义的 Agent | 低代码 |
+| 对接外部平台 | dify / n8n / coze / webhook 外部 Agent | 集成 |
+| SDK 编写 | Agent 插件组件 | 全代码 |
+
+### 1.1 三条并行工作线与汇合点
+
+| 工作线 | 范围 | 在本架构中的位置 |
+|--------|------|------------------|
+| 适配器改造（refactor/eba，本分支） | 事件体系、适配器结构、平台 API、EventRouter | 事件的**生产侧** + 路由层 |
+| Agent 插件化 | Agent 抽象、Agent 组件类型、市场分发 | 事件的**消费侧**统一抽象 |
+| 工作流引擎 | 内部低代码工作流 | Agent 的一种**编写方式** |
+
+**汇合点是 SDK 的 Agent 组件契约（§4）与 event→agent 绑定模型（§3）**。这两个接口冻结后，三条线可彼此 mock 独立推进。契约由本分支（EBA）牵头起草，三线评审后在 langbot-plugin-sdk 落地（发布通道：0.5.0aX pre-release 已打通）。
+
+## 2. 从四种 Handler 到 Agent 统一抽象
+
+### 2.1 演进理由
+
+04 文档中的 pipeline / agent / webhook / plugin 四种 handler_type，本质上都是"对事件作出响应的逻辑"，差别只在编写和部署方式。为四种类型分别设计配置表单、执行语义和扩展机制，等于把同一个概念做四遍。统一为 Agent 后：
+
+- **产品**：用户只学一个概念——"给 Bot 的事件绑 Agent"；
+- **工程**：路由层退化为很薄的 event → agent 分发，所有扩展集中到 Agent 抽象；
+- **生态**：Agent 成为市场上可分发、可复用的一等公民。
+
+### 2.2 收编映射
+
+| 原 handler_type（04 文档） | 收编后 |
+|---------------------------|--------|
+| `pipeline` | 内置 `pipeline-wrapper` Agent：实例配置为 `pipeline_uuid`，进程内直接复用 MessageAggregator → QueryPool → Pipeline 机制 |
+| `agent`（RequestRunner） | 现有 Runner 体系（local-agent / dify / n8n / coze / dashscope / langflow / tbox）整体收编为内置 Agent 家族——Runner 本来就是"Agent 抽象"的前身 |
+| `webhook` | 外部 Agent 的一种：事件 POST 出去、响应解析为动作（保留 04 §5.4 的请求/响应格式） |
+| `plugin`（EventListener 分发） | **不收编**——角色不同，见 §2.3 |
+
+### 2.3 响应者与观察者的角色切分
+
+事件的消费方有两种角色，不应混为一谈：
+
+- **响应者（Agent）**：路由选中**一个**，负责对事件作出回应（回复消息、执行动作）。多条绑定匹配同一事件时按 priority 仲裁，只取最高者。
+- **观察者（插件 EventListener）**：**广播**给所有注册插件，做旁路逻辑（日志、审计、风控、统计）。沿用现有机制不变，包括 `prevent_default()`——观察者可拦截本次事件，使 Agent 不被调用（与现有"插件拦截流水线"行为完全兼容）。
+
+执行顺序：事件到达 → 先广播观察者（按插件优先级）→ 若未被 prevent_default → 分发给选中的 Agent。
+
+## 3. 数据模型：event → agent 绑定
+
+### 3.1 Agent 实体化（推荐）
+
+Agent 作为一等实体（独立表），用户先创建/安装 Agent，再在 Bot 上把事件绑定到 Agent。好处：跨 Bot 复用、市场分发、独立的配置页面。
+
+```python
+class Agent(Base):
+    """Agent 实例：一个具体配置过的、可被事件绑定的响应者"""
+    uuid: str                # 主键
+    name: str
+    kind: str                # "builtin" | "plugin"
+    component_ref: str       # 内置: "pipeline-wrapper" / "local-agent" / "dify" / "webhook" / ...
+                             # 插件: "<plugin_author>/<plugin_name>/<agent_component_name>"
+    config: dict             # JSON — 实例配置（pipeline_uuid / 模型与提示词 / 外部平台凭据 / 工作流 id ...）
+    # 多租户预留：归属主体字段（tenant/workspace），首版可空
+```
+
+Bot 上的绑定配置（替代 04 §2.2 的 EventHandlerConfig，沿用其匹配语义）：
+
+```python
+class EventBinding(pydantic.BaseModel):
+    event_type: str          # 精确 / "message.*" / "*"，匹配规则同 04 §4
+    agent_uuid: str          # 绑定的 Agent 实例
+    enabled: bool = True
+    priority: int = 0        # 多条匹配时取最高者（单一仲裁）
+    description: str = ''
+```
+
+`use_pipeline_uuid` 自动迁移：为每个被引用的 pipeline 生成一个 `pipeline-wrapper` Agent 实例，并写入 `{"event_type": "message.received", "agent_uuid": <wrapper>}` 绑定。观察者广播不需要配置（始终发生），04 中"兜底 plugin 规则"不再需要。
+
+## 4. SDK Agent 组件契约（草案）
+
+Agent 成为插件系统的第七种组件（现有：Command / Tool / EventListener / KnowledgeEngine / Parser / Page）。
+
+### 4.1 Manifest
+
+```yaml
+apiVersion: v1
+kind: Agent
+metadata:
+  name: group-assistant
+  label: { en_US: Group Assistant, zh_Hans: 群助理 }
+spec:
+  handled_events:            # 声明可处理的事件类型；绑定 UI 据此过滤
+    - message.received
+    - group.member_joined
+  config:                    # 实例化配置 schema，复用现有组件配置体系
+    - name: model
+      type: llm-model-selector
+    - name: persona
+      type: prompt-editor
+execution:
+  python: { path: agent.py, attr: GroupAssistant }
+```
+
+### 4.2 运行时接口
+
+```python
+class Agent(BaseComponent):
+    async def handle(self, ctx: AgentContext) -> typing.AsyncGenerator[AgentChunk, None]:
+        """处理一次事件，流式产出回复与动作。每次事件调用一次。"""
+        ...
+
+class AgentContext:
+    event: EBAEvent              # 触发事件（统一事件体系）
+    bot: BotHandle               # 来源 Bot 信息
+    session: SessionHandle       # 会话句柄：历史消息、会话变量（LangBot 侧管理，Agent 保持无状态）
+    config: dict                 # 该 Agent 实例的配置
+
+    # 能力面（经 runtime RPC 回 LangBot 执行）：
+    async def reply(self, chain: MessageChain, quote: bool = False): ...
+    async def send_message(self, target_type: str, target_id: str, chain: MessageChain): ...
+    async def call_platform_api(self, action: str, params: dict) -> dict: ...
+    async def invoke_llm(self, model_uuid: str, messages: list, funcs: list = None) -> dict: ...
+    # + 工具调用 / KB 检索 / 插件存储（沿用 LangBotAPIProxy 既有方法）
+
+class AgentChunk:
+    delta_message: MessageChain | None = None   # 增量回复（流式）
+    actions: list[dict] | None = None           # 平台动作（同 webhook response_actions 格式）
+    final: bool = False
+```
+
+**流式**：复用 SDK 通信协议既有的 `chunk_status: continue/end` 机制，`handle()` 的每次 yield 对应一个 chunk。
+**内置与插件同构**：内置 Agent（pipeline-wrapper、local-agent、各外部平台）在 LangBot 进程内实现同一接口注册，不过 RPC；插件 Agent 经 plugin runtime 分发。对路由层二者不可区分。
+
+### 4.3 执行语义与可靠性
+
+| 关注点 | 约定 |
+|--------|------|
+| 仲裁 | 单响应者：priority 最高的匹配绑定生效，其余忽略 |
+| 性能 | 内置 Agent 进程内零额外开销；插件 Agent 每事件过一次 RPC 边界，消息场景需设延迟预算（评审项：目标 P95 附加延迟） |
+| 会话状态 | 归 LangBot 侧（SessionHandle），插件 Agent 原则上无状态，崩溃重启不丢会话 |
+| 降级 | Agent 调用失败/超时：可配置 fallback（回错误提示，或指定备用 Agent）；pipeline-wrapper 作为进程内兜底与性能对照组 |
+| 多租户预留 | AgentContext / SessionHandle / 存储接口显式携带归属主体标识，禁止新增全局单例状态——为后续轻量 SaaS 多租户铺路 |
+
+## 5. 发布火车
+
+| 版本 | 内容 | 备注 |
+|------|------|------|
+| 4.11（可选） | 现状成果：12 个 EBA 适配器、插件全事件订阅、`call_platform_api` | 对用户不可见的管道工程 + 插件新能力，不动产品概念 |
+| **5.0** | 产品形态首发：EventRouter + event→agent 绑定 + WebUI 编排 + 数据迁移 + 内置 Agent（pipeline-wrapper、local-agent、外部平台家族）+ SDK Agent 组件契约（可标 experimental） | 资格线不依赖其他两线交付；配 SDK 0.5.0 正式版；走 beta 周期；deprecation（旧 sources 适配器、legacy/*、use_pipeline_uuid）集中在此窗口处理 |
+| 5.x | 工作流 Agent（工作流引擎线挂入）、Agent 市场生态、剩余适配器（satori 等）、Agent 插件化收尾 | 验证开放注册机制 |
+| 多租户 | 独立评估：仅数据隔离 → 5.x 部署选项；伴随权限/计费/产品定位变化 → 6.0 | 前置条件是 §4.3 的归属主体预留已落实 |
+
+## 6. 开放问题（评审清单）
+
+1. **webhook 的最终定位**：作为外部 Agent（响应者，现方案）之外，是否还需要"纯通知观察者"形态（现 WebhookPusher 的角色）？
+2. **多 Agent 协作**：单一仲裁之外，是否需要"串联/并联多个 Agent"的场景？（建议 5.0 不做，留给工作流引擎表达）
+3. **工作流引擎的宿主**：核心内置，还是自身也作为一个插件交付（解释工作流定义的 Agent 插件）？
+4. **插件 Agent 的延迟预算**：消息主链路过 RPC 的 P95 目标值与压测方案。
+5. **Pipeline 的长期命运**：pipeline-wrapper 兼容期多长，Stage 体系是否在 6.0 退役或被工作流引擎吸收。
+6. **SDK 1.0 时机**：Agent 契约稳定后是否随 LangBot 5.x 给插件生态一个 API 稳定承诺。

docs/event-based-agents/adapters/00-index.md

@@ -0,0 +1,41 @@
+# EBA Adapter Migration Records
+
+This directory records adapter-level migration details for the Event-Based Agents architecture. Each adapter document should be kept close to the implementation and must answer four questions:
+
+1. What changed in the adapter structure.
+2. Which configuration fields are required.
+3. Which events and APIs are supported.
+4. What has been verified end to end.
+
+## Adapter Documents
+
+General acceptance checklist: [EBA Adapter Acceptance Checklist](./acceptance-checklist.md)
+
+Current acceptance report: [EBA Adapter Acceptance Report](./acceptance-report.md)
+
+| Adapter | Status | Document |
+|---------|--------|----------|
+| Telegram | Migrated; partial plugin E2E, real UI inbound image/file verified | [Telegram](./telegram.md) |
+| Discord | Migrated; partial plugin E2E, media-inbound gaps remain | [Discord](./discord.md) |
+| OneBot v11 / aiocqhttp | Migrated; Matcha UI plus protocol-level multi-component coverage | [OneBot v11 / aiocqhttp](./aiocqhttp.md) |
+| DingTalk | Migrated; partial plugin E2E, real UI inbound image/file verified; group gap remains | [DingTalk](./dingtalk.md) |
+| Lark / Feishu | Migrated; partial live text E2E, media-inbound gap remains | [Lark / Feishu](./lark.md) |
+| WeCom | Migrated; private text plugin E2E verified, media/group gaps remain | [WeCom](./wecom.md) |
+| WeComBot | Migrated; private text and outbound/API plugin E2E verified, feedback/group gaps remain | [WeComBot](./wecombot.md) |
+| Official Account | Migrated; private text plugin E2E verified, proactive outbound not supported | [Official Account](./officialaccount.md) |
+| QQ Official API | Migrated; WebSocket inbound reached LangBot, model config blocked reply | [QQ Official API](./qqofficial.md) |
+| Slack | Migrated; private text and outbound/API plugin E2E verified | [Slack](./slack.md) |
+| WeCom Customer Service | Migrated; customer-side UI text plugin E2E verified, inbound media and platform-API live coverage pending | [WeCom Customer Service](./wecomcs.md) |
+| Kook | Migrated; unit/mocked converter and API coverage only, live acceptance pending | [Kook](./kook.md) |
+
+## Documentation Checklist
+
+When migrating a new adapter, add one document here with:
+
+- Configuration table matching the adapter manifest.
+- Supported event list.
+- Supported common API list.
+- Supported `call_platform_api` action list.
+- Known unsupported APIs and the reason.
+- Live test notes, including platform, channel type, destructive operations, and residual risks.
+- A clear distinction between real UI inbound media, protocol-level injected inbound media, and bot outbound media.

docs/event-based-agents/adapters/acceptance-checklist.md

@@ -0,0 +1,208 @@
+# EBA Adapter Acceptance Checklist
+
+This checklist is the architecture-level acceptance standard for every Event-Based Agents platform adapter. It is not platform-specific. Adapter migration is not complete until the adapter has a written result against this checklist.
+
+## Evidence Levels
+
+Use these evidence levels consistently in adapter records:
+
+| Level | Meaning | Can Mark Complete |
+|-------|---------|-------------------|
+| `plugin-e2e-ui` | Real SDK plugin running through standalone runtime, LangBot core, the migrated adapter, and a real platform/simulator UI action. | Yes |
+| `plugin-e2e-protocol` | Real SDK plugin running through standalone runtime, LangBot core, and the migrated adapter from a protocol-boundary event injection, such as a OneBot reverse WebSocket event. | Partial; must not be claimed as UI coverage |
+| `plugin-e2e-outbound` | Real SDK plugin calls an API and the bot output is visible in the real platform/simulator UI. | Yes for send/API coverage only |
+| `adapter-live` | Direct adapter probe connected to a real or simulator platform endpoint, bypassing plugin runtime. | No, auxiliary only |
+| `unit` | Unit/API-shape tests with mocked platform SDK objects or mocked APIs. | No, auxiliary only |
+| `not-supported` | Platform protocol or SDK has no equivalent capability. Must include reason and source. | Yes, as explicitly unsupported |
+| `blocked` | Intended capability could not be verified because of credentials, permissions, endpoint gaps, or simulator gaps. | No |
+
+The primary acceptance path must be `plugin-e2e-ui` for inbound UI-triggered behavior and `plugin-e2e-outbound` for bot send/API behavior. `adapter-live`, `plugin-e2e-protocol`, and `unit` tests are useful, but they must be labelled precisely.
+
+## Required Architecture Path
+
+Every adapter must prove this full path:
+
+```text
+Real platform / simulator UI
+  -> platform SDK native event
+  -> adapter event converter
+  -> unified EBA event/entity/message types
+  -> LangBot core event dispatch
+  -> standalone SDK runtime
+  -> real test plugin listener
+  -> plugin calls platform APIs through SDK
+  -> LangBot core API dispatch
+  -> adapter API implementation
+  -> real platform / simulator UI
+```
+
+The test plugin must record JSONL evidence containing:
+
+- event class and `event.type`
+- `bot_uuid` and `adapter_name` as received by the plugin
+- adapter name
+- chat type and chat ID
+- sender/user/group IDs with secrets redacted
+- message component list for received messages
+- API action name, input summary, result or error
+- raw unsupported/blocked reason when an item is skipped
+
+## Required Message Receive Tests
+
+For every adapter, inbound message conversion must be tested through `plugin-e2e-ui` for each component the platform can receive. If a protocol-level injection is used, label it `plugin-e2e-protocol`; it proves the adapter/core/plugin path, but it does not prove that the user-facing platform UI can send that component. If the platform UI/simulator cannot create a component, record it as `blocked` with the endpoint limitation.
+
+| Component | Required Receive Assertion |
+|-----------|----------------------------|
+| `Source` | Message ID and timestamp are present and stable enough for reply/get/delete APIs. |
+| `Plain` | Text is preserved exactly, including spaces and multi-line content. |
+| `At` | Mentioned user ID is converted to common `At.target`. |
+| `AtAll` | Broadcast mention is converted to common `AtAll`, if platform supports it. |
+| `Image` | Image ID, URL, path, or base64 is represented without leaking platform-native segment shape. |
+| `Voice` | Voice/audio component is represented as `Voice` when the platform exposes it. |
+| `File` | File name, ID/URL, and size are represented as `File` when available. |
+| `Quote` | Reply/quote source ID and origin content are represented when the platform exposes it. |
+| `Face` | Native emoji/sticker/dice/rps-like components are represented as `Face` or documented as platform-specific. |
+| `Forward` | Merged/forwarded messages are represented as `Forward` when the platform exposes structured content. |
+| `Unknown` | Unsupported native segments become `Unknown` or `PlatformSpecificEvent` data, not crashes. |
+| Mixed chain | A message containing multiple component types preserves order. |
+
+The plugin must subscribe to `MessageReceivedEvent` and assert that `message_chain` contains common `langbot_plugin.api.entities.builtin.platform.message` components, not platform-native SDK objects.
+
+## Required Message Send Tests
+
+For every adapter, outbound message conversion must be tested through `plugin-e2e-outbound` by having the plugin call SDK platform APIs and verifying the platform UI/simulator receives the expected message.
+
+| Component | Required Send Assertion |
+|-----------|-------------------------|
+| `Plain` | Text appears exactly on the platform. |
+| `At` | User mention renders as a mention or platform equivalent. |
+| `AtAll` | Broadcast mention renders or is explicitly unsupported. |
+| `Image` | URL, path, or base64 image sends and renders/downloads correctly. |
+| `Voice` | Voice/audio sends when supported. |
+| `File` | File sends with name and content/link when supported. |
+| `Quote` | Quoted reply points to the original message when supported. |
+| `Face` | Native emoji/sticker/dice/rps sends or is explicitly unsupported. |
+| `Forward` | Forward/merged-forward sends when supported; otherwise fallback behavior is documented. |
+| Mixed chain | A mixed chain preserves component order as closely as the platform allows. |
+
+If a platform supports a component only in one direction, the adapter record must say so explicitly.
+
+## Required Event Tests
+
+The plugin must subscribe to every event declared in `manifest.yaml -> spec.supported_events` and record one of `plugin-e2e-ui`, `plugin-e2e-protocol`, `not-supported`, or `blocked`.
+
+| Event | Required Assertion |
+|-------|--------------------|
+| `message.received` | Real message reaches plugin as `MessageReceivedEvent`. |
+| `message.edited` | Edited message reaches plugin with message ID and new content, if declared. |
+| `message.deleted` | Deleted/recalled message reaches plugin with message ID and operator when available, if declared. |
+| `message.reaction` | Reaction add/remove reaches plugin with message ID, user, reaction, and direction, if declared. |
+| `feedback.received` | Feedback payload reaches plugin with feedback type and message/session IDs, if declared. |
+| `group.member_joined` | Join event reaches plugin with group and member. |
+| `group.member_left` | Leave/kick event reaches plugin with group, member, and kick flag. |
+| `group.member_banned` | Mute/ban event reaches plugin with group, member, operator, and duration. |
+| `group.info_updated` | Group metadata update reaches plugin with changed fields, if declared. |
+| `friend.request_received` | Friend request reaches plugin with request ID and message. |
+| `friend.added` | Friend-added event reaches plugin. |
+| `friend.removed` | Friend-removed event reaches plugin, if declared. |
+| `bot.invited_to_group` | Bot invite/join request reaches plugin with group and inviter/request ID. |
+| `bot.removed_from_group` | Bot removal reaches plugin with group and operator when available. |
+| `bot.muted` | Bot mute reaches plugin with duration. |
+| `bot.unmuted` | Bot unmute reaches plugin. |
+| `platform.specific` | At least one unmapped native event is delivered as structured platform-specific data, if declared. |
+
+Do not declare an event in the manifest unless there is an implementation path and an acceptance entry.
+
+## Required Common API Tests
+
+The plugin must call every common API declared in `manifest.yaml -> spec.supported_apis.required` and `optional`. Each call must be recorded with input summary and result.
+
+| API | Required Assertion |
+|-----|--------------------|
+| `send_message` | Plugin sends to private and group/channel targets where supported. |
+| `reply_message` | Plugin replies to the triggering message, with quoted mode tested when supported. |
+| `edit_message` | Plugin edits a bot-sent message, if declared. |
+| `delete_message` | Plugin deletes/recalls a bot-sent message, if declared and permissions allow. |
+| `forward_message` | Plugin forwards or emulates forwarding a real message, if declared. |
+| `get_message` | Plugin retrieves a real message and receives common `MessageReceivedEvent` shape. |
+| `get_group_info` | Plugin receives `UserGroup` with ID/name/count where available. |
+| `get_group_list` | Plugin receives joined groups/channels list where supported. |
+| `get_group_member_list` | Plugin receives list of `UserGroupMember` where supported. |
+| `get_group_member_info` | Plugin receives one member with role/display name where available. |
+| `set_group_name` | Plugin changes and restores a disposable group name, if declared. |
+| `mute_member` | Plugin mutes a disposable target, if declared. |
+| `unmute_member` | Plugin unmutes the same target, if declared. |
+| `kick_member` | Plugin kicks a disposable target only in destructive test mode, if declared. |
+| `leave_group` | Plugin leaves only in destructive test mode and only at the end, if declared. |
+| `get_user_info` | Plugin receives common `User` shape. |
+| `get_friend_list` | Plugin receives friend/contact list where supported. |
+| `approve_friend_request` | Plugin accepts/rejects a disposable friend request, if declared. |
+| `approve_group_invite` | Plugin accepts/rejects a disposable group invite, if declared. |
+| `upload_file` | Plugin uploads a real small file, if declared. |
+| `get_file_url` | Plugin resolves a real file ID to a URL, if declared. |
+| `call_platform_api` | Plugin calls every declared platform-specific action with safe parameters. |
+
+Destructive APIs must be opt-in and documented with the exact target used.
+
+The SDK must expose a plugin-side platform API escape hatch for adapter-specific actions. The acceptance plugin should call it from the same EBA event handler that received the real platform event, so the evidence proves both directions of the path:
+
+```text
+plugin -> SDK call_platform_api -> LangBot core -> adapter call_platform_api -> platform SDK/API
+```
+
+The result must be serialized into JSON-safe values before it is returned to the plugin runtime.
+
+## Platform-Specific API Tests
+
+Every action listed in `manifest.yaml -> spec.platform_specific_apis` must have one acceptance entry:
+
+- `plugin-e2e-ui` or `plugin-e2e-outbound`: called by the plugin against the live/simulator endpoint.
+- `plugin-e2e-protocol`: called by the plugin after a protocol-boundary injected event; useful for endpoint-specific simulators but must be labelled.
+- `not-supported`: removed from manifest or explained if the platform SDK exposes it but this adapter intentionally does not.
+- `blocked`: endpoint did not implement it, permissions missing, or safe fixture unavailable.
+
+Do not leave a platform-specific API in the manifest without a corresponding test record.
+
+## Required Compatibility Tests
+
+Each migrated adapter must also prove:
+
+- Manifest supported events match `adapter.get_supported_events()`.
+- Manifest supported APIs match `adapter.get_supported_apis()`.
+- Manifest platform-specific actions match `PLATFORM_API_MAP`.
+- Legacy `FriendMessage` / `GroupMessage` listeners still work when the core registers them.
+- EBA listener dispatch prefers the most specific event class, then `EBAEvent`, then base `Event`.
+- Self-message filtering prevents bot echo loops without dropping edit/delete/moderation events needed for API tests.
+- `source_platform_object` is present for reply/debug but not required by plugins for common behavior.
+
+## Required Documentation Per Adapter
+
+Each adapter document must include:
+
+- adapter directory and manifest name
+- config table
+- supported event table with evidence level per event
+- supported common API table with evidence level per API
+- platform-specific API table with evidence level per action
+- receive component table with evidence level per component
+- send component table with evidence level per component
+- exact test date
+- exact platform endpoint or simulator used
+- standalone runtime command
+- plugin path/name used for testing
+- evidence JSONL path
+- destructive operations performed or explicitly skipped
+- blocked items and reasons
+
+## Acceptance Rule
+
+An adapter can be marked migrated only when:
+
+1. All declared events have `plugin-e2e-ui`, justified `plugin-e2e-protocol`, or `not-supported` evidence.
+2. All declared APIs have `plugin-e2e-outbound` or `not-supported` evidence.
+3. All platform-supported receive components have `plugin-e2e-ui` evidence; protocol-only receive coverage keeps the status partial.
+4. All platform-supported send components have `plugin-e2e-outbound` evidence.
+5. Unit tests cover conversion and API-shape boundaries.
+6. The adapter document lists every blocked or skipped item honestly.
+
+If any declared capability is only covered by `adapter-live` or `unit`, the adapter status must remain partial.

docs/event-based-agents/adapters/acceptance-report.md

@@ -0,0 +1,171 @@
+# EBA Adapter Acceptance Report
+
+Date: May 10, 2026
+
+Scope:
+
+- `telegram-eba`
+- `discord-eba`
+- `aiocqhttp-eba`
+- `dingtalk-eba`
+- `lark-eba`
+- `wecom-eba`
+- `wecombot-eba`
+- `wecomcs-eba`
+- `officialaccount-eba`
+- `qqofficial-eba`
+- `slack-eba`
+
+This report follows `acceptance-checklist.md`. Evidence levels are intentionally strict:
+
+- `plugin-e2e-ui`: real platform or simulator UI event reached LangBot, standalone runtime, and `EBAEventProbe`.
+- `plugin-e2e-protocol`: real adapter endpoint event reached LangBot, standalone runtime, and `EBAEventProbe`, but the event was injected at the platform protocol boundary rather than sent through the UI.
+- `plugin-e2e-outbound`: the plugin called SDK APIs and the resulting bot message was visible on the platform.
+- `unit`: mocked converter/API coverage only.
+- `blocked`: not completed, either because the platform/simulator/client could not trigger it or because a safe disposable fixture was unavailable.
+- `not-supported`: the platform has no equivalent capability.
+
+## Summary
+
+| Adapter | Status | Honest acceptance summary |
+|---------|--------|---------------------------|
+| Telegram | Partial EBA acceptance | Real Telegram UI covered private text, group mention text, bot invite, inbound private image/file, outbound component sweep, safe SDK APIs, and safe Telegram platform APIs. Real UI inbound voice/quote was not completed in the latest plugin run. |
+| Discord | Partial EBA acceptance | Real Discord UI covered group text, outbound image/file/quote/mention components, safe SDK APIs, and safe Discord platform APIs. Real UI inbound attachment/image/file/reply/mention was not completed. A later UI retry was blocked because the Discord client kept the send button disabled. |
+| OneBot v11 / aiocqhttp | Partial EBA acceptance | Matcha UI covered real group text and outbound supported components/APIs. Multi-component inbound `Source/Plain/At/Face/Image/Voice/File/Quote` was verified through the real OneBot reverse WebSocket adapter endpoint, but not through Matcha UI upload/send. Matcha blocks file-send and merged-forward APIs. |
+| DingTalk | Partial EBA acceptance | Real DingTalk UI covered private text, emoji-as-text inbound, private inbound image/file, outbound image/file/quote/mention fallback components, safe SDK APIs, and safe DingTalk platform APIs. Real UI inbound voice/quote and group trigger were not completed. |
+| Lark / Feishu | Partial EBA acceptance | EBA adapter structure, self-built/store app config, WebSocket/Webhook mode handling, converters, common APIs, platform APIs, and unit tests are in place. One real LangBot organization WebSocket private text event reached `EBAEventProbe`; outbound component sweep was visible in Feishu. Latest real UI image/file sends did not reach local plugin evidence, so media receive remains blocked. |
+| WeCom | Partial EBA acceptance | Regular WeCom application-message adapter is split into the EBA directory with manifest, converters, API mixin, platform API map, and unit tests. Private text reached `EBAEventProbe` through standalone runtime and the real WeCom client; safe plugin APIs passed. Real inbound media and broader event coverage remain pending. |
+| WeComBot | Partial EBA acceptance | WeCom AI Bot is split into the EBA directory with WebSocket long connection mode and optional webhook mode, EBA message/feedback/platform-specific conversion, cache-backed common APIs, platform API map, unit tests, and a direct live probe. Private text, outbound component sweep, safe common APIs, and all declared WeComBot platform APIs reached `EBAEventProbe`; group, real inbound media, and feedback callback evidence remain pending. |
+| WeCom Customer Service | Partial EBA acceptance | WeCom Customer Service is split into the EBA directory with manifest, converters, API mixin, platform API map, unit tests, docs, and a direct live probe scaffold. Real WeChat customer-side UI text reached `EBAEventProbe`; plugin outbound text/image and safe cache-backed common APIs passed. Inbound media and platform-specific API live coverage remain pending; later fallback text sends were blocked by WeCom `95001 send msg count limit`. |
+| Official Account | Partial EBA acceptance | WeChat Official Account is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, and a direct live probe scaffold. Real WeChat Official Account UI private text reached `EBAEventProbe`; safe cache-backed common APIs and declared platform APIs passed. Proactive outbound `send_message` is not supported because replies must be tied to inbound webhook windows; inbound image/voice live UI evidence remains pending. |
+| QQ Official API | Partial EBA acceptance | QQ Official API is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, docs, and a direct live probe scaffold. A real WebSocket-mode QQ Official bot reached the LangBot pipeline on `dev.rockchin.top`; reply/outbound evidence is blocked by the test model provider returning `model_not_found` for `deepseek-v3`. |
+| Slack | Partial EBA acceptance | Slack is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, docs, and a direct live probe scaffold. Real Slack private text reached `EBAEventProbe`; safe common APIs, outbound component fallback sweep, and declared Slack platform APIs passed. Channel mention and real inbound media evidence remain pending. |
+
+Telegram and DingTalk now have real user-side UI image/file upload evidence in plugin JSONL. Discord and aiocqhttp do not yet have real UI inbound image/file evidence.
+
+## Evidence Files
+
+| Adapter | Endpoint | Evidence |
+|---------|----------|----------|
+| Telegram private | Telegram Lite, `@rockchinq_bot` private chat | `data/temp/telegram-plugin-e2e-rerun.jsonl` |
+| Telegram private media | Telegram Lite, `@rockchinq_bot` private chat | `data/temp/telegram-plugin-e2e-media-ui.jsonl` |
+| Telegram group | Telegram Lite, `Rock'sBotGroup` | `data/temp/telegram-plugin-e2e-group.jsonl` |
+| Discord | Discord client, LangBot server, `#debugging` | `data/temp/discord-plugin-e2e-20260510-final.jsonl` |
+| aiocqhttp UI | local Matcha, group `test group` | `data/temp/aiocqhttp-plugin-e2e-20260510-multiformat.jsonl` |
+| aiocqhttp protocol | OneBot reverse WebSocket endpoint `127.0.0.1:2280/ws` | `data/temp/aiocqhttp-plugin-e2e-20260510-multiformat.jsonl` |
+| DingTalk | DingTalk Mac, `LangBot Team` org private chat | `data/temp/dingtalk-plugin-e2e-20260510-rerun.jsonl` |
+| DingTalk private media | DingTalk Mac, `LangBot Team` org private chat | `data/temp/dingtalk-plugin-e2e-media-ui.jsonl` |
+| Lark / Feishu unit | local mocked Feishu SDK/client paths | `tests/unit_tests/platform/test_lark_eba_adapter.py` |
+| Lark / Feishu partial live | Feishu Mac, LangBot organization `LangBotDev` private chat | `data/temp/lark-plugin-e2e-ws.jsonl` |
+| WeCom Customer Service | WeChat customer-side UI, `客服消息 -> 浪波智能客服` on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/wecomcs_eba_plugin_probe.jsonl` |
+| Official Account | WeChat desktop client, subscribed Official Account on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl` |
+| QQ Official API unit | local mocked QQ Official client paths | `tests/unit_tests/platform/test_qqofficial_eba_adapter.py` |
+| Slack unit | local mocked Slack client paths | `tests/unit_tests/platform/test_slack_eba_adapter.py` |
+| Slack private | Slack workspace private DM on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/slack_eba_plugin_probe.jsonl` |
+
+All plugin runs used SDK standalone runtime ports `5400/5401`, LangBot `--standalone-runtime`, and the real plugin at `langbot-plugin-demo/EBAEventProbe`.
+
+## Unified Shape Verification
+
+All four adapters deliver common SDK entities to plugins before LangBot core/plugin logic handles the event.
+
+| Requirement | Telegram | Discord | aiocqhttp | DingTalk | Lark / Feishu |
+|-------------|----------|---------|-----------|----------|---------------|
+| `bot_uuid` filled | plugin-e2e | plugin-e2e | plugin-e2e | plugin-e2e | live plugin-e2e pending |
+| `adapter_name` filled | `telegram` | `discord` | `aiocqhttp` | `dingtalk` | `lark-eba` in current unit/code; older live text evidence recorded `lark` before the naming fix |
+| common `MessageChain` delivered | `Plain`, group `At + Plain`, private `Image`, private `File` | `Source + Plain` | UI `Source + Plain`; protocol `Source + Plain + At + Face + Image + Voice + File + Quote + Plain` | `Source + Plain`, private `Source + Image`, private `Source + File` | live private `Source + Plain`; unit `Source + Plain + At/Image/File`; latest live image/file blocked |
+| common user/group entities | plugin-e2e | plugin-e2e | plugin-e2e | plugin-e2e private user; group not completed | live private user; unit private/group |
+| raw native object isolation | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` | raw data stays in `source_platform_object` |
+
+## Message Receive Components
+
+| Component | Telegram | Discord | aiocqhttp | DingTalk | Lark / Feishu |
+|-----------|----------|---------|-----------|----------|---------------|
+| `Source` | design gap: event has message id but chain omits `Source` | plugin-e2e-ui | plugin-e2e-ui/protocol | plugin-e2e-ui | plugin-e2e-ui private text |
+| `Plain` | plugin-e2e-ui private/group | plugin-e2e-ui | plugin-e2e-ui/protocol | plugin-e2e-ui | plugin-e2e-ui private text |
+| `At` | plugin-e2e-ui group mention | unit; real UI mention not completed in latest run | plugin-e2e-protocol; unit | unit; group trigger not completed | unit; group trigger not completed |
+| `AtAll` | not-supported | unit only | unit only | unit/send fallback only | unit only |
+| `Image` | plugin-e2e-ui private | converter/unit; real UI attachment not completed | plugin-e2e-protocol, not Matcha UI | plugin-e2e-ui private | unit; real UI image sent but not observed in plugin evidence |
+| `Voice` | converter/unit; real UI inbound not completed | not-supported as native voice; audio is attachment/file | plugin-e2e-protocol, not Matcha UI | converter/unit; real UI inbound not completed | unit; real UI inbound not completed |
+| `File` | plugin-e2e-ui private | converter/unit; real UI attachment not completed | plugin-e2e-protocol, not Matcha UI | plugin-e2e-ui private | unit; real UI file sent but not observed in plugin evidence |
+| `Quote` | converter/unit; real UI reply not completed | unit; real UI reply not completed | plugin-e2e-protocol | converter/unit; real UI quote not completed | unit/API-backed quote lookup; real UI quote not completed |
+| `Face` | not-supported as common `Face` | not-supported as common `Face` | plugin-e2e-protocol | UI emoji becomes `Plain` (`[smile]` text), not `Face` | not-supported as common `Face` |
+| `Forward` | not-supported inbound | not-supported inbound | unit; Matcha forward UI/action blocked | not-supported inbound | not-supported inbound |
+| Mixed chain | group `At + Plain`; media tested as separate messages | not completed inbound | plugin-e2e-protocol | media tested as separate messages; mixed inbound not completed | unit only |
+
+## Message Send Components
+
+| Component | Telegram | Discord | aiocqhttp | DingTalk | Lark / Feishu |
+|-----------|----------|---------|-----------|----------|---------------|
+| `Plain` | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound |
+| `At` | plugin-e2e-outbound equivalent | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound fallback/equivalent | plugin-e2e-outbound |
+| `AtAll` | plugin-e2e-outbound fallback | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound fallback | unit; group live not completed |
+| `Image` | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound |
+| `Voice` | not-supported in current send converter | not-supported as native voice | converter path; not completed against Matcha UI | fallback as file/text depending DingTalk media support | converter path; live not completed |
+| `File` | plugin-e2e-outbound | plugin-e2e-outbound | blocked by Matcha endpoint error | plugin-e2e-outbound | plugin-e2e-outbound |
+| `Quote` | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound fallback | plugin-e2e-outbound fallback |
+| `Face` | not-supported | not-supported | plugin-e2e-outbound attempted in mixed chain | fallback text | not-supported |
+| `Forward` | flattened fallback | flattened fallback | blocked by Matcha unsupported action | flattened fallback | plugin-e2e-outbound flattened fallback |
+| Mixed chain | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound except blocked file/forward | plugin-e2e-outbound | plugin-e2e-outbound |
+
+## Event Acceptance
+
+| Event category | Telegram | Discord | aiocqhttp | DingTalk |
+|----------------|----------|---------|-----------|----------|
+| `message.received` | plugin-e2e-ui | plugin-e2e-ui | plugin-e2e-ui and plugin-e2e-protocol | plugin-e2e-ui private |
+| `message.edited` | implemented/unit, not plugin-e2e-ui | historical/direct only, not latest plugin-e2e | unit | not declared |
+| `message.deleted` | implemented/unit, not plugin-e2e-ui | historical/direct only, not latest plugin-e2e | unit | not declared |
+| `message.reaction` | implemented/unit, not plugin-e2e-ui | historical/direct only, not latest plugin-e2e | not-supported in standard OneBot message path | not declared |
+| member join/left/ban | implemented/unit or blocked without disposable users | blocked without disposable users | unit; Matcha fixture unavailable | not declared |
+| bot invited/removed | invite plugin-e2e-ui for Telegram; removal blocked | invite historical/plugin-series; removal blocked | unit; Matcha fixture unavailable | not declared |
+| requests/friend events | not applicable | not applicable | unit; Matcha fixture unavailable | not declared |
+| `platform.specific` | implemented; not latest plugin-e2e | not latest plugin-e2e | adapter lifecycle observed; plugin focus was message path | declared for fallback; not reproduced in UI run |
+
+## Common API Acceptance
+
+| API area | Telegram | Discord | aiocqhttp | DingTalk |
+|----------|----------|---------|-----------|----------|
+| send/reply | plugin-e2e-outbound | plugin-e2e-outbound | plugin-e2e-outbound, with Matcha file/forward gaps | plugin-e2e-outbound |
+| edit/delete | historical/direct or unit; destructive/current UI not repeated | historical/direct; destructive/current UI not repeated | unit/destructive blocked | not declared or blocked |
+| message lookup | not-supported | not-supported | plugin-e2e | inbound cache-backed where available; limited live coverage |
+| group info/member info | plugin-e2e safe subset | plugin-e2e safe subset | plugin-e2e safe subset | private path only; group not completed |
+| user/friend info | plugin-e2e where platform allows | plugin-e2e where platform allows | plugin-e2e | plugin-e2e private user |
+| moderation/leave | blocked without disposable safe targets | blocked without disposable safe targets | blocked without disposable safe targets | blocked/not declared |
+| `get_file_url` | implemented; latest inbound `File` carried downloadable file data in plugin evidence | URL passthrough for attachments; inbound attachment not completed | not portable/endpoint-dependent | implemented through DingTalk media API; latest inbound `File` carried a platform file URL |
+| `call_platform_api` | plugin-e2e safe actions | plugin-e2e safe actions | plugin-e2e safe actions, Matcha gaps documented | plugin-e2e safe `check_access_token` |
+
+## Platform-Specific API Acceptance
+
+| Adapter | plugin-e2e verified | Blocked or not reproduced |
+|---------|---------------------|---------------------------|
+| Telegram | safe chat/admin/member count/chat-action actions | mutating actions and callback-only actions were not repeated |
+| Discord | safe channel/guild/role/typing actions | mutating pin/reaction/invite actions were not repeated in the latest plugin run; inbound attachment paths not completed |
+| aiocqhttp | safe OneBot actions such as status/version/can-send checks | `get_group_honor_info` unsupported by Matcha; admin/card/title/ban/record/file/forward require better endpoint fixtures |
+| DingTalk | `check_access_token`; real inbound file produced a file URL in the common `File` component | separate media-download replay APIs and group actions need a working follow-up fixture |
+
+## SDK API Acceptance
+
+`EBAEventProbe` exercised the standalone runtime path for:
+
+- bot discovery and bot info lookup
+- send message
+- component sweep where enabled
+- platform API sweep where enabled
+- plugin storage
+- workspace storage
+- plugin/command/tool/knowledge-base list APIs
+
+The probe logs set `ok=true` when the sweep completed with only expected unsupported/blocked items. Individual call details are stored in the JSONL evidence files.
+
+## Residual Risks And Required Follow-Up
+
+- Discord still requires real UI inbound image/file upload evidence before it can be called media-complete.
+- aiocqhttp has rich inbound component evidence only at the OneBot reverse WebSocket boundary; Matcha UI did not provide image/file upload coverage.
+- DingTalk group trigger remains unclosed; current evidence is private chat only.
+- Lark / Feishu requires a clean follow-up live pass: the latest LangBot organization WebSocket run connected, but UI-sent text/image/file after the loop-scheduling fix did not append plugin events.
+- Discord UI retry on May 10, 2026 was blocked by the client keeping the send button disabled even after text was entered.
+- Destructive moderation and leave APIs are intentionally blocked until disposable users/groups are available.
+
+## Conclusion
+
+The EBA conversion path is implemented and partially proven for the migrated adapters. Telegram and DingTalk now have real UI private-chat image/file inbound evidence. Discord, aiocqhttp, and Lark / Feishu still have explicit UI-level media gaps, so the overall adapter set remains partial acceptance rather than production-complete media acceptance.

docs/event-based-agents/adapters/aiocqhttp.md

@@ -0,0 +1,162 @@
+# OneBot v11 / aiocqhttp EBA Adapter
+
+## Status
+
+OneBot v11 has been migrated to the EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/aiocqhttp/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+├── types.py
+└── onebot.svg
+```
+
+The EBA adapter is registered as `aiocqhttp-eba`. The legacy adapter remains at `src/langbot/pkg/platform/sources/aiocqhttp.py`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `host` | Yes | `0.0.0.0` | Host for the reverse WebSocket server that the OneBot endpoint connects to. |
+| `port` | Yes | `2280` | Reverse WebSocket listen port. |
+| `access-token` | No | `""` | OneBot access token, if the endpoint is configured to use one. |
+
+## Events
+
+The adapter declares these EBA events:
+
+- `message.received`
+- `message.deleted`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `friend.request_received`
+- `friend.added`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `bot.muted`
+- `bot.unmuted`
+- `platform.specific`
+
+`platform.specific` is used for OneBot notice/request/meta events that do not yet have a common EBA event type, such as group admin changes, group file uploads, pokes, honor changes, and group join requests from non-bot users.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Supports private and group text, mentions, images, voice, files, faces, and flattened forwards. Group merged forwards are sent through OneBot forward APIs when possible. |
+| `reply_message` | Supported | Uses the original OneBot event and can prepend a reply segment. |
+| `edit_message` | Not supported | OneBot v11 has no standard message edit action. |
+| `delete_message` | Supported | Uses `delete_msg`; permission depends on endpoint and group role. |
+| `forward_message` | Supported | Emulates forward by fetching the source message with `get_msg` and sending its content to the target chat. |
+| `get_message` | Supported | Uses `get_msg` and converts the response into `MessageReceivedEvent`. |
+| `get_group_info` | Supported | Uses `get_group_info`. |
+| `get_group_list` | Supported | Uses `get_group_list`. |
+| `get_group_member_list` | Supported | Uses `get_group_member_list`. |
+| `get_group_member_info` | Supported | Uses `get_group_member_info`. |
+| `set_group_name` | Supported | Uses `set_group_name`; may be unsupported by mock endpoints. |
+| `get_user_info` | Supported | Uses `get_stranger_info`. |
+| `get_friend_list` | Supported | Uses `get_friend_list`. |
+| `approve_friend_request` | Supported | Uses `set_friend_add_request`. |
+| `approve_group_invite` | Supported | Uses `set_group_add_request` with `sub_type=invite`. |
+| `upload_file` | Not supported | OneBot v11 has endpoint-specific file upload extensions but no portable standalone upload action. |
+| `get_file_url` | Not supported | OneBot v11 file URL resolution is endpoint-specific. Use `call_platform_api("get_image")`, `get_record`, or endpoint extensions when available. |
+| `mute_member` | Supported | Uses `set_group_ban`. |
+| `unmute_member` | Supported | Uses `set_group_ban` with duration `0`. |
+| `kick_member` | Supported | Destructive; test only with disposable members. |
+| `leave_group` | Supported | Destructive; should run last in live tests. |
+| `call_platform_api` | Supported | See below. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `get_login_info`
+- `get_status`
+- `get_version_info`
+- `get_group_honor_info`
+- `set_group_card`
+- `set_group_special_title`
+- `set_group_admin`
+- `set_group_whole_ban`
+- `send_group_forward_msg`
+- `get_forward_msg`
+- `get_record`
+- `get_image`
+- `can_send_image`
+- `can_send_record`
+
+## Message Conversion Notes
+
+Incoming OneBot segments are converted into common `MessageChain` components before LangBot core/plugin dispatch:
+
+- `text` -> `Plain`
+- `at` -> `At` / `AtAll`
+- `image` -> `Image` or `Face` for OneBot emoji-package images
+- `record` -> `Voice`
+- `file` -> `File`
+- `reply` -> `Quote`
+- `face`, `rps`, `dice` -> `Face`
+- unsupported segments -> `Unknown`
+
+Outgoing `MessageChain` components are converted back into `aiocqhttp.Message` segments. Base64 media strings are normalized to OneBot `base64://...` format.
+
+## Live Test Record
+
+The direct live probe is:
+
+```bash
+PYTHONPATH=/Users/qinjunyan/code/projects/langbot/langbot-plugin-sdk/src \
+uv run python tests/e2e/live_aiocqhttp_eba_probe.py --host 127.0.0.1 --port 2280
+```
+
+It starts the reverse WebSocket adapter directly, records observed EBA events to `data/temp/aiocqhttp_eba_live_probe.jsonl`, waits for a real Matcha or OneBot message, then tries reply/send/get/delete/group/user/platform API calls as far as the endpoint supports them.
+
+Verified on May 10, 2026 with local Matcha connected to `ws://127.0.0.1:2280/ws`:
+
+- Real inbound group message converted to `MessageReceivedEvent`.
+- Real lifecycle connection converted to `PlatformSpecificEvent`.
+- Real reply API succeeded and rendered a quoted bot reply in Matcha.
+- Real proactive send API succeeded and rendered a bot group message in Matcha.
+- Real outgoing component sweep succeeded for text, `At`, `AtAll`, `Face`, and base64 `Image`.
+- Real `get_message`, `get_group_info`, `get_login_info`, `get_status`, `get_version_info`, `can_send_image`, and `can_send_record` calls succeeded against Matcha.
+- Unit conversion and API-shape tests passed for `Plain`, `At`, `AtAll`, `Image`, `Voice`, `File`, `Quote`, `Face`, `rps`, `dice`, `Forward`, `Unknown`, private/group message events, delete notices, group join/leave/ban notices, bot mute notices, friend requests, group invites, friend added notices, dispatch specificity, send, reply, delete, forward, get message, group APIs, user APIs, request approval APIs, moderation APIs, leave group, unsupported file APIs, and all declared `call_platform_api` actions.
+
+Skipped or residual live-test items:
+
+- `edit_message`: not implemented because OneBot v11 has no standard edit action.
+- `upload_file` and `get_file_url`: not implemented as common APIs because portable OneBot v11 file upload/download URL semantics are endpoint-specific.
+- `kick_member` and `leave_group`: destructive; run only with explicit `--destructive` and disposable Matcha/OneBot state.
+- `group.info_updated`, message reactions, and message edits are not declared because OneBot v11 does not provide standard equivalents for them.
+- Matcha returned `ActionFailed` for outgoing `File` segment rendering and did not support merged-forward actions in this run. The adapter keeps the conversion/API implementations because they are valid OneBot/NapCat-style capabilities, but the Matcha live probe records them as skipped.
+- Matcha returned an empty `get_group_member_list` for the test group, so `get_group_member_info`, mute/unmute, kick, and leave were covered by unit/API-shape tests only in this run.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 10, 2026 with `EBAEventProbe`, SDK standalone runtime, LangBot `--standalone-runtime`, local Matcha, and group `测试群`.
+
+Evidence:
+
+- Plugin JSONL: `data/temp/aiocqhttp-plugin-e2e-20260510-multiformat.jsonl`
+
+Observed and verified:
+
+- A real Matcha group message reached the plugin as `MessageReceived` with `bot_uuid=eba-aiocqhttp-matcha`, `adapter_name=aiocqhttp`, common `Source`/`Plain` message components, common sender, and common group identifiers.
+- A protocol-level OneBot reverse WebSocket event reached the plugin as `MessageReceived` with a mixed common chain: `Source`, `Plain`, `At`, `Face`, `Image`, `Voice`, `File`, `Quote`, and trailing `Plain`. This proves the real adapter + LangBot + standalone runtime + plugin path for mixed inbound OneBot payloads, but it was not sent through Matcha UI.
+- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Outbound component sweep succeeded for plain text plus `At`/`Face`, `AtAll`, base64 `Image`, and quoted reply.
+- Common APIs succeeded through the plugin path: `get_message`, `get_user_info`, `get_friend_list`, `get_group_info`, `get_group_list`, `get_group_member_list`, and `get_group_member_info`.
+- Safe OneBot platform APIs succeeded through `call_platform_api`: `get_login_info`, `get_status`, `get_version_info`, `can_send_image`, and `can_send_record`.
+
+Documented Matcha limits in this E2E run:
+
+- Matcha UI did not provide a completed image/file upload/send path for inbound media. The rich inbound media evidence is `plugin-e2e-protocol`, not UI-level media upload evidence.
+- Outbound `File` failed in Matcha even after the adapter emitted an official `file` segment shape.
+- Outbound `Forward` failed because Matcha returned unsupported action for merged-forward.
+- `get_group_honor_info` failed because Matcha returned unsupported action.
+- Destructive/admin APIs such as mute, unmute, kick, leave, group rename, card/title/admin/whole-ban changes, and request approvals were not run without disposable fixtures.

docs/event-based-agents/adapters/dingtalk.md

@@ -0,0 +1,114 @@
+# DingTalk EBA Adapter Migration Record
+
+Status: migrated with partial plugin E2E evidence.
+
+Adapter directory: `src/langbot/pkg/platform/adapters/dingtalk/`
+
+## What Changed
+
+The DingTalk adapter now has an Event-Based Agents adapter package with:
+
+- `manifest.yaml` for adapter metadata, configuration, events, common APIs, and platform-specific APIs.
+- `adapter.py` for DingTalk client startup, native callback handling, legacy compatibility, and EBA dispatch.
+- `event_converter.py` for native DingTalk events to common EBA events.
+- `message_converter.py` for DingTalk message payloads to/from common `MessageChain` components.
+- `api_impl.py` for common EBA API implementations.
+- `platform_api.py` for DingTalk-specific `call_platform_api` actions.
+
+The legacy DingTalk HTTP client now returns successful JSON response bodies from proactive send methods and raises with response details on non-200 responses.
+
+## Configuration
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `client-id` | yes | DingTalk robot/client identifier. |
+| `client-secret` | yes | DingTalk client secret. |
+| `robot-code` | yes | Robot code used for send APIs. |
+| `robot-name` | no | Used for bot mention/self filtering and display. |
+| `encrypt-key` | no | DingTalk callback encryption key when configured. |
+| `verification-token` | no | DingTalk callback verification token when configured. |
+
+## Supported Events
+
+| Event | Support | Evidence |
+|-------|---------|----------|
+| `message.received` | implemented | `plugin-e2e-ui` private text and emoji-as-text. |
+| `platform.specific` | implemented | Not reproduced in the latest UI run. |
+
+## Receive Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Source` | supported | `plugin-e2e-ui` private message. |
+| `Plain` | supported | `plugin-e2e-ui` private text. DingTalk emoji currently arrives as plain text such as `[smile]`. |
+| `At` | converter path | Group trigger was not completed in the latest run. |
+| `AtAll` | fallback/send-side only | Not completed inbound. |
+| `Image` | supported | Real DingTalk Mac private-chat image upload reached the plugin as common `Image`. |
+| `Voice` | converter path | Real UI inbound voice was not completed. |
+| `File` | supported | Real DingTalk Mac private-chat file upload reached the plugin as common `File`. |
+| `Quote` | converter path | Real UI inbound quote was not completed. |
+| `Face` | not native common mapping | DingTalk emoji was observed as `Plain`, not `Face`. |
+| `Forward` | not-supported inbound | DingTalk does not expose a portable structured forward event in this adapter. |
+
+## Send Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Plain` | supported | `plugin-e2e-outbound`. |
+| `At` | supported or text fallback | `plugin-e2e-outbound`. |
+| `AtAll` | fallback | `plugin-e2e-outbound`. |
+| `Image` | supported | `plugin-e2e-outbound`. |
+| `File` | supported | `plugin-e2e-outbound`. |
+| `Quote` | fallback | `plugin-e2e-outbound`. |
+| `Face` | fallback | `plugin-e2e-outbound` as text fallback. |
+| `Forward` | flattened fallback | `plugin-e2e-outbound`. |
+| `Voice` | fallback/endpoint-dependent | Not separately verified as a native DingTalk voice send. |
+
+## Common APIs
+
+| API | Support | Notes |
+|-----|---------|-------|
+| `send_message` | supported | Verified through `EBAEventProbe`. |
+| `reply_message` | supported | Verified through quoted/fallback send path. |
+| `get_message` | cache-backed | Requires the message to have been observed by this adapter process. |
+| `get_group_info` | cache-backed/API-backed where available | Group path not completed in latest UI run. |
+| `get_group_list` | supported where DingTalk API allows | Limited live coverage. |
+| `get_group_member_info` | supported where DingTalk API allows | Limited live coverage. |
+| `get_user_info` | supported | Private sender path verified. |
+| `get_friend_list` | limited | DingTalk does not expose a portable friend-list equivalent. |
+| `get_file_url` | supported with media/file identifiers | Real inbound file yielded a platform file URL in the converted `File` component. |
+| `call_platform_api` | supported | Safe action `check_access_token` verified. |
+
+## Platform-Specific APIs
+
+| Action | Support | Evidence |
+|--------|---------|----------|
+| `check_access_token` | supported | `plugin-e2e`. |
+| `refresh_access_token` | supported | Implemented; not separately reproduced in the latest plugin run. |
+| `get_file_url` | supported | Real inbound file yielded a platform file URL in the converted `File` component. |
+| `get_audio_base64` | supported | Needs real inbound audio/media ID. |
+| `download_image_base64` | supported | Real inbound image reached the plugin as `Image`; separate image-download API replay was not completed. |
+
+## End-to-End Evidence
+
+Evidence files:
+
+- Text/API/component JSONL: `data/temp/dingtalk-plugin-e2e-20260510-rerun.jsonl`
+- Real UI inbound media JSONL: `data/temp/dingtalk-plugin-e2e-media-ui.jsonl`
+
+Verified:
+
+- DingTalk Mac private chat in the `LangBot Team` organization produced `MessageReceived` through LangBot standalone runtime and `EBAEventProbe`.
+- The common chain was `Source + Plain` for normal text.
+- DingTalk emoji was received as `Source + Plain`, not common `Face`.
+- Real DingTalk Mac private-chat image upload was received as `Source + Image`.
+- Real DingTalk Mac private-chat file upload was received as `Source + File`.
+- The plugin sent outbound text, mention/fallback, image, quote/fallback, file, and forward/fallback messages visible in DingTalk.
+- The plugin called safe SDK and DingTalk platform APIs.
+
+Not completed:
+
+- Real UI inbound voice.
+- Real UI inbound quote.
+- Group trigger with a real robot mention.
+- Destructive or organization-mutating APIs.

docs/event-based-agents/adapters/discord.md

@@ -0,0 +1,147 @@
+# Discord EBA Adapter
+
+## Status
+
+Discord has been migrated from the legacy source adapter:
+
+```text
+src/langbot/pkg/platform/sources/discord.py
+src/langbot/pkg/platform/sources/discord.yaml
+```
+
+EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/discord/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+├── types.py
+└── voice.py
+```
+
+The adapter is registered as `discord-eba`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `client_id` | Yes | `""` | Discord application client ID. |
+| `token` | Yes | `""` | Discord bot token. |
+
+The bot needs gateway permissions and intents for the target test server. Message Content intent is required for message bodies, Server Members intent is required for member APIs/events, and reaction events require the Reactions intent and channel permissions.
+
+## Events
+
+Discord declares these EBA events:
+
+- `message.received`
+- `message.edited`
+- `message.deleted`
+- `message.reaction`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `platform.specific`
+
+Discord-specific events that do not map cleanly to common events should be surfaced as `platform.specific`.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|-----------------|-------|
+| `send_message` | Supported | Supports text, image, file, and mixed message chains through Discord messages and attachments. |
+| `reply_message` | Supported | Uses Discord message references when replying to a received EBA message event. |
+| `edit_message` | Supported | Bot can edit its own messages. File edits are implemented by clearing old attachments and sending replacement files when needed. |
+| `delete_message` | Supported | Requires message management permissions for non-bot messages. |
+| `forward_message` | Emulated | Discord has no native forward API; the adapter copies content and attachments. |
+| `get_group_info` | Supported | Maps Discord guild metadata to EBA group info. |
+| `get_group_member_list` | Supported | Requires member cache or the Server Members intent/fetch permission. |
+| `get_group_member_info` | Supported | Maps Discord roles/permissions into EBA member roles. |
+| `get_user_info` | Supported | Uses Discord user fetch/cache. |
+| `upload_file` | Not supported | Discord uploads files as message attachments; standalone upload raises `NotSupportedError`. |
+| `get_file_url` | Supported | Discord attachment URLs are already downloadable URLs, so the adapter returns the input URL. |
+| `mute_member` | Supported where possible | Uses Discord timeout API and requires guild moderation permission. |
+| `unmute_member` | Supported where possible | Clears timeout and requires guild moderation permission. |
+| `kick_member` | Supported | Destructive; test only with a disposable account/bot. |
+| `leave_group` | Supported | Bot leaves a guild; destructive and should run last. |
+| `call_platform_api` | Supported | Discord-specific actions live here. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `get_channel`
+- `get_guild`
+- `get_guild_channels`
+- `get_guild_roles`
+- `create_invite`
+- `pin_message`
+- `unpin_message`
+- `add_reaction`
+- `remove_reaction`
+- `typing`
+
+Voice helpers are intentionally kept Discord-specific:
+
+- `join_voice_channel`
+- `leave_voice_channel`
+- `get_voice_connection_status`
+- `list_active_voice_connections`
+- `get_voice_channel_info`
+
+## Live Test Record
+
+The live probe is:
+
+```bash
+uv run python tests/e2e/live_discord_eba_probe.py --help
+```
+
+Verified on May 7, 2026 with a newly created Discord application/bot named `LangBot EBA Test 0507`, the LangBot Discord server, and the `#🐞-debugging` channel:
+
+- SDK standalone runtime started with WebSocket control/debug ports, and the `EBAEventProbe` plugin connected through `lbp run`.
+- Plugin runtime received real Discord events through LangBot: `BotInvitedToGroup`, `MessageReceived`, `MessageReactionReceived` add/remove, `MessageEdited`, and `MessageDeleted`.
+- Plugin runtime API calls succeeded through the standalone runtime: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage APIs, workspace storage APIs, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Direct live adapter probe observed `message.received`, `message.edited`, `message.deleted`, and `bot.removed_from_group`.
+- Message APIs verified: send, reply, edit, delete, forward, text/image/file mixed message chains.
+- User and guild APIs verified: `get_user_info`, `get_group_info`, `get_group_member_list`, `get_group_member_info`.
+- Platform-specific APIs verified: `get_channel`, `get_guild`, `get_guild_channels`, `get_guild_roles`, `create_invite`, `typing`, `pin_message`, `unpin_message`, `add_reaction`, `remove_reaction`.
+- Unsupported API behavior verified: `upload_file` raises `NotSupportedError`.
+- Destructive API verified at the end: `leave_group`, which emitted `bot.removed_from_group`.
+
+Not verified in the shared LangBot server live run: `mute_member`, `unmute_member`, and `kick_member`, because the run did not use a disposable target member. They are implemented through Discord timeout/kick APIs and should only be exercised against a disposable account or bot.
+
+The test fixed one real test-fixture issue: `EBAEventProbe` previously assumed `get_bots()` returned UUID strings. The current standalone runtime returns bot dictionaries, so the probe now selects an enabled bot dictionary and passes its `uuid` to `get_bot_info` and `send_message`. The probe also now subscribes to `MessageDeleted`.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified again on May 10, 2026 with SDK standalone runtime, LangBot `--standalone-runtime`, Discord web client, the LangBot server, and `#🐞-debugging`.
+
+Evidence:
+
+- Main plugin JSONL: `data/temp/discord-plugin-e2e-20260510-final.jsonl`
+- LangBot runtime log: `data/temp/discord-langbot-e2e-20260510-rerun.log`
+
+Observed and verified:
+
+- A newly invited Discord bot connected to the LangBot server and received a real web-client message in `#🐞-debugging`.
+- `MessageReceived` reached the plugin with `bot_uuid=eba-discord-live`, `adapter_name=discord`, common `Source`/`Plain` message components, common `User`, and common `UserGroup` for the guild.
+- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Outbound component sweep succeeded: plain text plus user mention, `AtAll`/`@everyone`, base64 image, quoted reply, file attachment, and flattened forward fallback.
+- Common APIs succeeded: `get_user_info`, `get_group_info`, `get_group_member_list`, and `get_group_member_info`.
+- Discord platform APIs succeeded through `call_platform_api`: `get_channel`, `typing`, `get_guild`, `get_guild_channels`, and `get_guild_roles`.
+
+Documented limits in this E2E run:
+
+- Real Discord UI inbound attachment/image/file, reply/quote, and fresh mention-chain messages were not completed in the plugin E2E evidence. Outbound image/file attachments from the bot do not prove inbound attachment conversion.
+- A later May 10 UI retry could write text into the Discord message box, but the client kept the send button disabled and did not send the message, so it produced no new plugin evidence.
+- `get_message`, `get_friend_list`, and `get_group_list` are not supported by this Discord adapter.
+- Destructive moderation and guild-leave APIs were not repeated against the shared LangBot server.
+- Native Discord voice is not represented as common `Voice`; audio-like payloads are treated as file attachments.
+- `create_invite`, pin/unpin, and reaction mutation were covered by prior direct live probes but were not repeated by the final plugin run to avoid extra shared-server side effects.

docs/event-based-agents/adapters/kook.md

@@ -0,0 +1,108 @@
+# KOOK EBA Adapter
+
+## Status
+
+KOOK has been migrated to the EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/kook/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `kook-eba`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `token` | Yes | `""` | KOOK bot token. |
+| `enable-stream-reply` | Yes | `false` | Reserved for shared platform configuration compatibility. |
+
+## Events
+
+| Event | Evidence | Notes |
+|-------|----------|-------|
+| `message.received` | `plugin-e2e-ui` | Real KOOK UI channel message reached `EBAEventProbe` as `MessageReceivedEvent`. |
+| `platform.specific` | `plugin-e2e-ui` | KOOK gateway event without a common EBA mapping reached `EBAEventProbe` as `PlatformSpecificEventReceived`. |
+
+## Common APIs
+
+| API | Evidence | Notes |
+|-----|----------|-------|
+| `send_message` | `plugin-e2e-outbound` | Probe plugin sent channel messages through SDK `send_message`; KOOK returned message IDs. |
+| `reply_message` | `unit` | Supports `reply_msg_id` and optional quoted replies when the source message ID is available. |
+| `get_message` | `plugin-e2e-outbound` | Probe plugin fetched the cached triggering message. |
+| `get_group_info` | `plugin-e2e-outbound` | Probe plugin received cached KOOK channel info. |
+| `get_group_list` | `plugin-e2e-outbound` | Probe plugin received cached channel/group entities observed by the adapter. |
+| `get_group_member_info` | `plugin-e2e-outbound` | Probe plugin received cached sender info as a group member. |
+| `get_user_info` | `plugin-e2e-outbound` | Probe plugin received cached sender user info. |
+| `get_friend_list` | `plugin-e2e-outbound` | Probe plugin received cached users. |
+| `upload_file` | `unit` | Uses KOOK `asset/create` and returns URL/ID. |
+| `get_file_url` | `unit` | KOOK media IDs are URL-like in the adapter path; returns the ID unchanged. |
+| `delete_message` | `unit` | Calls KOOK delete endpoints. Live permission verification is still required. |
+| `forward_message` | `plugin-e2e-outbound` | Probe plugin sent flattened forward content through SDK `send_message`. |
+| `call_platform_api` | `plugin-e2e-outbound` | Probe plugin called safe KOOK platform-specific APIs through SDK `call_platform_api`. |
+
+## Platform-Specific APIs
+
+| Action | Evidence | Notes |
+|--------|----------|-------|
+| `get_current_user` | `plugin-e2e-outbound` | Probe plugin called `user/me`. |
+| `get_user` | `plugin-e2e-outbound` | Probe plugin called `user/view` for the triggering sender. |
+| `get_channel` | `plugin-e2e-outbound` | Probe plugin called `channel/view` for the triggering channel. |
+| `get_guild` | `plugin-e2e-outbound` | Probe plugin called `guild/view`; gateway URLs redact token query values. |
+| `get_gateway` | `plugin-e2e-outbound` | Probe plugin called `gateway/index`; returned token query values are redacted. |
+| `send_direct_message` | `unit` | Calls `direct-message/create`. |
+
+## Components
+
+| Component | Receive Evidence | Send Evidence | Notes |
+|-----------|------------------|---------------|-------|
+| `Source` | `plugin-e2e-ui` | N/A | KOOK message ID and timestamp are preserved. |
+| `Plain` | `plugin-e2e-ui` | `plugin-e2e-outbound` | Text and KMarkdown are represented as plain common text. |
+| `At` | `plugin-e2e-ui` | `plugin-e2e-outbound` | KOOK `(met)<id>(met)` mentions map to common `At`. |
+| `AtAll` | `unit` | `plugin-e2e-outbound` | KOOK `(met)all(met)` maps to common `AtAll`; real inbound UI AtAll was not tested. |
+| `Image` | `unit` | `unit` | URL/image ID based path only; live rendering still needs verification. |
+| `Voice` | `unit` | `unit` | URL based path only; live rendering still needs verification. |
+| `File` | `unit` | `unit` | URL based path only; upload API is exposed separately. |
+| `Forward` | `unit` | `unit` | Outbound forwards are flattened; inbound structured forwards are not exposed by current legacy implementation. |
+| `Unknown` | `unit` | N/A | Unsupported KOOK message types become `Unknown` or `PlatformSpecificEvent`. |
+
+## Acceptance Record
+
+Test date: June 4, 2026.
+
+Plugin E2E verified on June 4, 2026 with `EBAEventProbe`, SDK standalone runtime, KOOK WebSocket adapter, and a real KOOK channel UI message.
+
+Evidence:
+
+- JSONL: `data/temp/kook_eba_plugin_probe.jsonl`
+- Plugin log: `data/logs/eba-probe-kook.log`
+
+Observed and verified:
+
+- A real KOOK UI channel message reached the plugin as `MessageReceived` with `bot_uuid=7ab5b065-6e4e-4def-95f0-3c265366e26f`, `adapter_name=kook`, common sender/group/chat fields, and common `MessageChain` components.
+- KOOK gateway-specific event reached the plugin as `PlatformSpecificEventReceived`.
+- Probe plugin called SDK `send_message`; KOOK returned message IDs for text, At, AtAll, image URL/base64 fallback path, quote fallback, file fallback, and flattened forward cases.
+- Probe plugin called common API methods through the SDK path: `get_message`, `get_user_info`, `get_friend_list`, `get_group_info`, `get_group_list`, and `get_group_member_info`.
+- Probe plugin called safe KOOK platform-specific APIs through SDK `call_platform_api`: `get_current_user`, `get_user`, `get_channel`, `get_gateway`, and `get_guild`.
+
+Run:
+
+```bash
+uv run pytest tests/unit_tests/platform/test_kook_eba_adapter.py
+git diff --check
+```
+
+Blocked or partial items:
+
+- `plugin-e2e-ui` inbound coverage for image, file, voice, AtAll, quote, and forward.
+- `plugin-e2e-outbound` visual verification in KOOK UI for image/file/voice rendering. KOOK returned message IDs, but UI inspection was not performed in this run.
+- `reply_message` and `delete_message` live permission verification.
+- Destructive or permission-sensitive APIs were not declared beyond delete; KOOK mute/kick/leave remain explicit `NotSupportedError` paths until a safe fixture is available.

docs/event-based-agents/adapters/lark.md

@@ -0,0 +1,135 @@
+# Lark / Feishu EBA Adapter Migration Record
+
+Status: migrated with unit coverage and partial live plugin E2E. WebSocket text reached the standalone runtime once in the LangBot organization test app, but the latest real UI image/file inbound attempts did not reach the local adapter log, so media receive is not release-complete yet.
+
+Adapter directory: `src/langbot/pkg/platform/adapters/lark/`
+
+## What Changed
+
+The Lark/Feishu adapter now has an Event-Based Agents adapter package with:
+
+- `manifest.yaml` for adapter metadata, configuration, events, common APIs, platform-specific APIs, app type, and communication mode.
+- `adapter.py` for self-built/store app token handling, WebSocket long connection startup, Webhook callback handling, card feedback, streaming-card replies, and EBA dispatch.
+- `event_converter.py` for native Feishu events to common EBA events.
+- `message_converter.py` for Feishu text/post/image/file/audio payloads to/from common `MessageChain` components.
+- `api_impl.py` for common EBA API implementations.
+- `platform_api.py` for Feishu-specific `call_platform_api` actions.
+
+The legacy `lark` adapter remains available while the EBA adapter is registered separately as `lark-eba`.
+
+## Configuration
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `app_id` | yes | Feishu/Lark application App ID. |
+| `app_secret` | yes | Feishu/Lark application App Secret. |
+| `bot_name` | yes | Must match the bot name so group mentions can be recognized. |
+| `enable-webhook` | yes | `false` uses WebSocket long connection; `true` uses Request URL/Webhook callbacks. |
+| `webhook_url` | no | Generated callback URL for Webhook mode. |
+| `encrypt-key` | no | Webhook decrypt key when event encryption is enabled. |
+| `enable-stream-reply` | yes | Enables streaming replies through an updating Feishu card. |
+| `app_type` | no | `self` for self-built apps; `isv` for store apps. |
+| `bot_added_welcome` | no | Optional group welcome message sent after bot-added events. |
+
+## Application And Communication Modes
+
+| Mode | Support | Implementation |
+|------|---------|----------------|
+| Self-built application | implemented | Uses standard app credentials and tenant token behavior from the Feishu SDK client. |
+| Store application | implemented | Builds an ISV client, requests app tickets, and resolves app/tenant access tokens with per-tenant caching. |
+| WebSocket long connection | implemented | Registers `im.message.receive_v1` and card-action callbacks through `lark_oapi.ws.Client`. |
+| Webhook Request URL | implemented | Handles URL verification, encrypted payloads, message events, app-ticket events, bot-added events, and card-action feedback. |
+
+## Supported Events
+
+| Event | Support | Evidence |
+|-------|---------|----------|
+| `message.received` | implemented | Unit coverage for private and group native events to common EBA events. |
+| `bot.invited_to_group` | implemented | Webhook bot-added event maps to common bot invite event and optional welcome send. |
+| `platform.specific` | implemented | Unknown callback events are preserved as `platform.specific`. |
+| `FeedbackEvent` | compatibility event | Card button feedback is still dispatched through the existing SDK `FeedbackEvent` type. |
+
+## Receive Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Source` | supported | Unit coverage; live private text evidence. |
+| `Plain` | supported | Text and post payloads convert to common text; live private text evidence. |
+| `At` | supported | Feishu mentions map to common `At` with user ID and display name. |
+| `AtAll` | supported | `user_id=all` maps to common `AtAll`. |
+| `Image` | supported | Image payloads download through message resource API and map to common `Image`; real UI image send attempted, but not observed in local plugin evidence yet. |
+| `Voice` | supported | Audio payloads download through message resource API and map to common `Voice`. |
+| `File` | supported | File payloads download through message resource API and map to common `File`; real UI file send attempted, but not observed in local plugin evidence yet. |
+| `Quote` | supported | Parent/thread reply lookup maps quoted content into common `Quote`. |
+| `Face` | not native common mapping | Feishu emoji/stickers are not exposed as a portable common `Face` component here. |
+| `Forward` | not-supported inbound | Feishu does not expose a portable structured forward event in this adapter. |
+
+## Send Components
+
+| Component | Support | Evidence |
+|-----------|---------|----------|
+| `Plain` | supported | Unit coverage; sends Feishu `text`. |
+| `At` | supported | Unit coverage; sends Feishu `post` at element. |
+| `AtAll` | supported | Unit coverage; sends Feishu `post` at-all element. |
+| `Image` | supported | Uploads image resource and sends Feishu `image`. |
+| `Voice` | supported | Uploads OPUS/audio resource and sends Feishu `audio`. |
+| `File` | supported | Uploads file resource and sends Feishu `file`. |
+| `Quote` | supported/fallback | Sends quote marker plus origin content. |
+| `Face` | not-supported | No portable send mapping. |
+| `Forward` | flattened fallback | Flattens forward nodes into text/media messages. |
+
+## Common APIs
+
+| API | Support | Notes |
+|-----|---------|-------|
+| `send_message` | supported | Supports private/open_id and group/chat_id targets; live plugin outbound component sweep produced visible Feishu messages. |
+| `reply_message` | supported | Replies to the source Feishu message; fixed to recover the native Feishu message ID from legacy-wrapped source events. |
+| `get_message` | cache-backed/API-backed | Returns cached inbound event where possible and converts uncached Feishu message API items into common `MessageReceivedEvent`. |
+| `get_group_info` | supported | Uses cached group or Feishu chat metadata. |
+| `get_group_member_info` | limited | Uses cached user data when available. |
+| `get_user_info` | limited | Uses cached user data when available. |
+| `get_file_url` | limited | Returns `file://` paths from downloaded inbound resources; remote Feishu resource download uses platform-specific API params. |
+| `call_platform_api` | supported | See below. |
+
+## Platform-Specific APIs
+
+| Action | Support | Evidence |
+|--------|---------|----------|
+| `check_tenant_access_token` | supported | Unit coverage. |
+| `refresh_app_access_token` | supported | Store-app token path implemented. |
+| `refresh_tenant_access_token` | supported | Store-app tenant token path implemented. |
+| `get_chat` | supported | Feishu chat metadata API wrapper. |
+| `get_message` | supported | Feishu message API wrapper with JSON-safe return values for plugin calls. |
+| `get_message_resource` | supported | Feishu message resource download wrapper. |
+
+## End-to-End Evidence
+
+Current code-level evidence:
+
+- `tests/unit_tests/platform/test_lark_eba_adapter.py`
+- `PYTHONPATH=../langbot-plugin-sdk/src uv run pytest tests/unit_tests/platform/test_lark_eba_adapter.py -q`
+
+Live evidence collected on May 11, 2026:
+
+- Standalone runtime: `uv run lbp rt --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check`
+- LangBot: `uv run main.py --standalone-runtime --debug`
+- Plugin: `LangBot__EBAEventProbe`
+- Feishu org/app: LangBot organization, `LangBotDev` private chat.
+- Observed plugin JSONL: one private `MessageReceived` event with `Source + Plain`; plugin API probe then exercised bot discovery, bot info, `send_message`, outbound component sweep, storage/list APIs, and safe platform API calls.
+- Real UI sends attempted after the fixes: private text, local file, and image/video image upload. These appeared in the Feishu client but did not append new `EBAEventProbe` records in the local JSONL during this run.
+- Fixes from live testing: reply path now extracts the native Feishu `message_id` from legacy-wrapped source events; WebSocket callbacks are scheduled onto the adapter event loop instead of assuming the SDK callback has a running asyncio loop; platform API results are converted to JSON-safe values.
+
+Live E2E items still required before marking release-complete:
+
+- WebSocket self-built app in LangBot organization: repeat private text after callback-loop fix, plus private image/file/audio and group mention message received by `EBAEventProbe`.
+- Webhook self-built app in LangBot organization: URL verification plus text/image/file message received by `EBAEventProbe`.
+- Store app token path: at least token acquisition/tenant-token safe API through `call_platform_api`; full message E2E if a LangBot organization store-app fixture is available.
+- Outbound component sweep: text, mention, at-all, image, file, voice where Feishu accepts the fixture, quote/fallback, and forward/fallback.
+- Safe platform API sweep: token check, chat metadata, message lookup, and message resource download using real inbound IDs.
+
+## Known Limits
+
+- Store-app live E2E requires a real ISV app ticket/tenant installation fixture.
+- Current LangBot organization WebSocket run connected successfully but did not deliver the latest UI-sent image/file attempts to local plugin evidence; this blocks release-complete media acceptance.
+- Feishu native emoji/sticker semantics are not represented as common `Face`.
+- Destructive org or chat mutations are not declared in this adapter.

docs/event-based-agents/adapters/officialaccount.md

@@ -0,0 +1,101 @@
+# OfficialAccount EBA Adapter
+
+Adapter directory: `src/langbot/pkg/platform/adapters/officialaccount/`
+
+Manifest name: `officialaccount-eba`
+
+Status: partial migration. Unit/API-shape coverage is present, and private text `plugin-e2e-ui` plus safe API evidence has been verified against the `dev.rockchin.top` Official Account fixture. Proactive outbound `send_message` remains not supported by this adapter because WeChat Official Account replies must be tied to inbound webhook windows.
+
+## Config
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `webhook_url` | no | Generated by LangBot and copied into the Official Account callback settings. |
+| `token` | yes | WeChat callback token. |
+| `EncodingAESKey` | yes | WeChat message encryption key. |
+| `AppID` | yes | Official Account app ID. |
+| `AppSecret` | yes | Official Account app secret. |
+| `Mode` | yes | `drop` waits for an in-callback reply; `passive` returns the loading text first and queues the answer for the user's next message. |
+| `LoadingMessage` | no | Only used by `passive` mode. |
+| `api_base_url` | no | Optional API base URL for proxy deployments. |
+
+## Events
+
+| Event | Evidence | Notes |
+| --- | --- | --- |
+| `message.received` | plugin-e2e-ui, unit | Text UI message verified through WeChat Official Account on `dev.rockchin.top`; image and voice webhook payloads are covered by unit tests. |
+| `platform.specific` | unit | Subscribe/menu/etc. native events are emitted as structured `PlatformSpecificEvent`. |
+
+## Common APIs
+
+| API | Evidence | Notes |
+| --- | --- | --- |
+| `reply_message` | unit | Queues/passively returns text through the inbound webhook source event. |
+| `get_message` | plugin-e2e-ui, unit | Cached inbound message retrieved by `EBAEventProbe` platform API sweep. |
+| `get_user_info` | plugin-e2e-ui, unit | Cached inbound sender retrieved by `EBAEventProbe` platform API sweep. |
+| `get_friend_list` | plugin-e2e-ui, unit | Cached inbound sender list retrieved by `EBAEventProbe` platform API sweep. |
+| `call_platform_api` | plugin-e2e-ui, unit | Safe diagnostic actions verified through `get_mode` and `get_cached_response_status`. |
+| `send_message` | not-supported | Official Account customer-service proactive messaging is not implemented by the existing SDK adapter; only webhook reply is supported here. |
+
+## Platform APIs
+
+| Action | Evidence | Notes |
+| --- | --- | --- |
+| `get_mode` | plugin-e2e-ui, unit | Returned `{"mode": "drop", "longer_response": false}` in live probe. |
+| `get_cached_response_status` | plugin-e2e-ui, unit | Returned `{"pending": false}` in live probe. |
+
+## Components
+
+| Receive Component | Evidence | Notes |
+| --- | --- | --- |
+| `Source` | plugin-e2e-ui, unit | Uses `MsgId` and `CreateTime`; live UI text message included `Source`. |
+| `Plain` | plugin-e2e-ui, unit | Live UI text message mapped to `Plain`. |
+| `Image` | unit | `PicUrl` and `MediaId` map to common `Image`. |
+| `Voice` | unit | `MediaId` maps to common `Voice`. |
+| `Unknown` | unit | Unsupported message/event types do not crash. |
+| `At`, `AtAll`, `File`, `Quote`, `Face`, `Forward`, mixed chain | not-supported | WeChat Official Account inbound webhook payloads used by the current SDK do not expose these as common structured components. |
+
+| Send Component | Evidence | Notes |
+| --- | --- | --- |
+| `Plain` | unit | Sent as webhook reply text. |
+| `Image`, `Voice`, `File`, `Quote`, `At`, `AtAll`, `Face`, `Forward`, mixed chain | not-supported | Existing SDK reply path is text XML only; non-text components degrade to readable placeholders in tests and are not declared as supported outbound components. |
+
+## Verification Record
+
+Test date: 2026-05-28
+
+Endpoint/simulator: `dev.rockchin.top` with WeChat desktop client and a real subscribed Official Account conversation. The running EBA test stack used SDK standalone runtime ports `5400/5401`, LangBot from `/home/wgc/LangBotxg/LangBotEbaTest`, and `EBAEventProbe`.
+
+Verified UI message: `EBA officialaccount single probe 2026-05-28 16:53`
+
+Observed event/API evidence:
+
+- `MessageReceived`: `bot_uuid=d7c46880-a9f8-431a-9172-5d3e0d663dbc`, `adapter_name=officialaccount-eba`, `chat_type=private`, `chat_id=ovH9L7OW6hNpWZWvp_NMmypVh26w`, `message_chain=[Source, Plain]`.
+- Common safe APIs through probe platform sweep: `get_message`, `get_user_info`, `get_friend_list`.
+- Platform APIs through `call_platform_api`: `get_mode`, `get_cached_response_status`.
+- `send_message` and outbound component sweep returned explicit `NotSupportedError: send_message:official_account_requires_inbound_webhook_reply`, as expected for this adapter.
+
+Standalone runtime command:
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+```
+
+Probe plugin: `data/plugins/LangBot__EBAEventProbe` when live credentials are available.
+
+Adapter live probe:
+
+```bash
+uv run python -m py_compile tests/e2e/live_officialaccount_eba_probe.py
+OFFICIALACCOUNT_TOKEN=... OFFICIALACCOUNT_ENCODING_AES_KEY=... OFFICIALACCOUNT_APP_SECRET=... OFFICIALACCOUNT_APP_ID=... uv run python tests/e2e/live_officialaccount_eba_probe.py
+```
+
+Evidence JSONL path: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl` for plugin E2E, or `data/temp/officialaccount_eba_probe.jsonl` for direct adapter live probe.
+
+Destructive operations: none.
+
+Blocked items:
+
+- `plugin-e2e-outbound`: proactive `send_message` is not supported for this adapter; Official Account responses must be produced through the inbound webhook reply window.
+- Inbound image and voice live UI evidence remains pending; webhook conversion is covered by unit tests.

docs/event-based-agents/adapters/qqofficial.md

@@ -0,0 +1,114 @@
+# QQOfficial EBA Adapter
+
+Adapter directory: `src/langbot/pkg/platform/adapters/qqofficial/`
+
+Manifest name: `qqofficial-eba`
+
+Status: partial migration. The EBA adapter structure, manifest, converters, cache-backed safe APIs, platform API map, unit tests, and direct live probe scaffold are in place. A real QQ Official WebSocket bot on `dev.rockchin.top` received an inbound user message and drove LangBot into the normal pipeline path; the response path was blocked by the test environment model service returning `model_not_found` for `deepseek-v3`.
+
+## Config
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `appid` | yes | QQ Official app ID. |
+| `secret` | yes | QQ Official app secret. |
+| `token` | yes | QQ Official callback token. |
+| `enable-webhook` | yes | Uses LangBot unified webhook when true; otherwise uses the QQ WebSocket gateway. |
+| `enable-stream-reply` | yes | Enables C2C streaming replies when supported by the QQ Official endpoint. |
+| `webhook_url` | no | Generated by LangBot and copied into the QQ Official callback settings in webhook mode. |
+
+## Events
+
+| Event | Evidence | Notes |
+| --- | --- | --- |
+| `message.received` | adapter-live, unit | `C2C_MESSAGE_CREATE`, `DIRECT_MESSAGE_CREATE`, `GROUP_AT_MESSAGE_CREATE`, and `AT_MESSAGE_CREATE` map to common `MessageReceivedEvent`. A real WebSocket-mode QQ Official bot reached the LangBot pipeline on `dev.rockchin.top`; plugin JSONL evidence remains pending. |
+| `platform.specific` | unit, blocked | Unmapped gateway events are emitted as structured `PlatformSpecificEvent`; live evidence is pending. |
+
+## Common APIs
+
+| API | Evidence | Notes |
+| --- | --- | --- |
+| `send_message` | unit, blocked | Sends private C2C, group, and text-only channel messages through the existing QQ Official client. Live outbound UI verification is pending because the test pipeline failed before producing a bot response. |
+| `reply_message` | unit, blocked | Replies using the source `QQOfficialEvent` message ID when available. Live reply was blocked by the test environment model service returning `model_not_found`. |
+| `get_message` | unit | Returns cached inbound `MessageReceivedEvent`. |
+| `get_user_info` | unit | Returns cached inbound sender. |
+| `get_friend_list` | unit | Returns cached private senders. |
+| `get_group_info` | unit | Returns cached group/channel metadata from inbound events. |
+| `get_group_member_info` | unit | Returns cached group sender as a common member. |
+| `get_group_member_list` | unit | Returns cached group members observed by the adapter. |
+| `call_platform_api` | unit, blocked | Safe diagnostic actions are implemented; live calls are pending credentials. |
+
+## Platform APIs
+
+| Action | Evidence | Notes |
+| --- | --- | --- |
+| `check_access_token` | unit, blocked | Calls the existing client token check. |
+| `refresh_access_token` | unit, blocked | Forces token refresh. |
+| `get_gateway_url` | unit, blocked | Fetches the WebSocket gateway URL. |
+| `get_mode` | unit | Returns webhook and stream-reply mode. |
+
+## Components
+
+| Receive Component | Evidence | Notes |
+| --- | --- | --- |
+| `Source` | unit | Uses QQ message/event IDs and timestamp. |
+| `Plain` | unit | Preserves text content. |
+| `At` | unit | Group and channel mention events insert an adapter bot mention marker. |
+| `Image` | unit | QQ image attachment URL is converted to common `Image`; falls back to URL if download fails. |
+| `Unknown` | unit | Unsupported/empty native payloads become `Unknown`. |
+| `Voice`, `File`, `Quote`, `Face`, `Forward`, mixed chain | blocked | Current native parser only exposes text and image attachments; live endpoint behavior still needs verification. |
+
+| Send Component | Evidence | Notes |
+| --- | --- | --- |
+| `Plain` | unit, blocked | Sends through private, group, or channel text APIs. |
+| `At`, `AtAll` | unit, blocked | Converted to readable mention text. |
+| `Image` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
+| `Voice` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
+| `File` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
+| `Quote`, `Forward`, mixed chain | unit, blocked | Flattened to ordered send payloads where possible. |
+| `Face` | not-supported | No common QQ Official face mapping is implemented. |
+
+## Verification Record
+
+Test date: 2026-06-02
+
+Endpoint/simulator: `dev.rockchin.top` with a real QQ Official WebSocket bot (`qqofficial-eba`, bot UUID `80a5560b-52b1-40e7-b7d6-4a2341eb4780`) and LangBot running from `/home/wgc/LangBotxg/LangBotEbaTest`.
+
+Observed evidence:
+
+- The QQ Official WebSocket bot was enabled with `enable-webhook=false`.
+- A real user message reached LangBot and entered the standard pipeline path.
+- The response path stopped at the model layer with `model_not_found` for `deepseek-v3`; this is a model/provider configuration issue, not an adapter conversion failure.
+- `qq-webhook.langbot.dev` was temporarily routed through Caddy to `127.0.0.1:5301` for webhook checks, but the observed EBA bot used WebSocket mode.
+
+Standalone runtime command:
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+```
+
+Probe plugin: `data/plugins/LangBot__EBAEventProbe` when live credentials are available.
+
+Adapter live probe:
+
+```bash
+uv run python -m py_compile tests/e2e/live_qqofficial_eba_probe.py
+QQOFFICIAL_APPID=... QQOFFICIAL_SECRET=... QQOFFICIAL_TOKEN=... uv run python tests/e2e/live_qqofficial_eba_probe.py
+```
+
+Webhook-mode probe:
+
+```bash
+QQOFFICIAL_APPID=... QQOFFICIAL_SECRET=... QQOFFICIAL_TOKEN=... uv run python tests/e2e/live_qqofficial_eba_probe.py --webhook --host 0.0.0.0 --port 5312
+```
+
+Evidence JSONL path: `data/temp/qqofficial_eba_probe.jsonl` for direct adapter live probe; plugin E2E evidence should use `data/temp/qqofficial_eba_plugin_probe.jsonl`.
+
+Destructive operations: none implemented.
+
+Blocked items:
+
+- `plugin-e2e-ui`: standalone probe plugin JSONL evidence is still pending; the observed live run reached LangBot core/pipeline but was not recorded by the EBA probe plugin.
+- `plugin-e2e-outbound`: waiting for visible QQ client verification of plugin `send_message`/`reply_message` output after a working model/provider is configured.
+- Inbound non-text media and platform lifecycle events require endpoint evidence before they can be marked complete.

docs/event-based-agents/adapters/slack.md

@@ -0,0 +1,84 @@
+# Slack EBA Adapter
+
+## Structure
+
+Slack is migrated into `src/langbot/pkg/platform/adapters/slack/` with the standard EBA adapter layout:
+
+- `adapter.py` owns lifecycle, listener dispatch, unified webhook handling, outbound send/reply, and event caches.
+- `event_converter.py` maps Slack `im` and `app_mention` channel events to `message.received`.
+- `message_converter.py` maps common `MessageChain` components to Slack text fallback and maps inbound Slack text/image payloads back to EBA components.
+- `api_impl.py` provides cache-backed common read APIs.
+- `platform_api.py` declares safe Slack-specific API actions.
+- `manifest.yaml` declares `slack-eba`.
+
+The legacy `src/langbot/pkg/platform/sources/slack.py` adapter is kept unchanged.
+
+## Configuration
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `webhook_url` | No | Generated by LangBot. Paste it into Slack Event Subscriptions. |
+| `bot_token` | Yes | Slack bot token, usually `xoxb-...`. |
+| `signing_secret` | Yes | Slack app signing secret. |
+
+## Events
+
+| Event | Notes |
+|-------|-------|
+| `message.received` | Emitted for private `im` messages and channel `app_mention` events. Channel messages are mapped to group chats. |
+| `platform.specific` | Reserved for Slack event types that are not converted into common message events. |
+
+## Common APIs
+
+Required:
+
+- `send_message`
+- `reply_message`
+
+Optional:
+
+- `get_message`
+- `get_user_info`
+- `get_friend_list`
+- `get_group_info`
+- `get_group_list`
+- `get_group_member_list`
+- `get_group_member_info`
+- `call_platform_api`
+
+Cache-backed APIs are only available after the relevant inbound event has been observed.
+
+## Platform APIs
+
+| Action | Notes |
+|--------|-------|
+| `get_mode` | Returns webhook mode and configured bot account id. |
+| `auth_test` | Calls Slack `auth.test` with the configured bot token. |
+
+## Known Limits
+
+- Slack file/image outbound is currently represented as text fallback because the existing Slack SDK wrapper only exposes `chat_postMessage`.
+- Inbound channel coverage follows the legacy adapter behavior: only `app_mention` events are treated as group messages.
+- Real live testing requires a public callback URL configured in Slack Event Subscriptions.
+
+## Verification
+
+Local mocked unit coverage validates manifest parity, event conversion, legacy listener compatibility, cache-backed APIs, send/reply routing, and declared platform APIs.
+
+Plugin E2E evidence was captured on June 2, 2026 against `dev.rockchin.top` with Slack private DM input and `EBAEventProbe` through the standalone runtime.
+
+Evidence file: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/slack_eba_plugin_probe.jsonl`.
+
+Observed:
+
+- Real Slack private text produced `MessageReceived` with `adapter_name=slack-eba`, `Source + Plain`, private chat type, and filled `bot_uuid`.
+- Safe common APIs passed: `get_message`, `get_user_info`, `get_friend_list`.
+- Outbound component fallback sweep passed through `send_message`: plain/at/face, image, quote, file, and forward.
+- Declared Slack platform APIs passed: `get_mode`, `auth_test`.
+
+Still pending:
+
+- Channel `app_mention` plugin E2E.
+- Real inbound Slack file/image UI evidence.
+
+Live probe scaffold: `tests/e2e/live_slack_eba_probe.py`.

docs/event-based-agents/adapters/telegram.md

@@ -0,0 +1,139 @@
+# Telegram EBA Adapter
+
+## Status
+
+Telegram has been migrated to the EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/telegram/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `telegram-eba`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `token` | Yes | `""` | Telegram Bot API token from BotFather. |
+| `markdown_card` | No | `true` | Whether to render Markdown card style replies. |
+| `enable-stream-reply` | Yes | `false` | Whether to use Telegram streaming reply mode. |
+
+## Events
+
+Telegram declares these EBA events:
+
+- `message.received`
+- `message.edited`
+- `message.reaction`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `bot.muted`
+- `bot.unmuted`
+- `platform.specific`
+
+`platform.specific` is currently used for Telegram-only callback and chat-member update payloads that do not yet have a more specific common event type.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Supports text, image, file, and mixed message chains. |
+| `reply_message` | Supported | Supports quoted replies through the original message event. |
+| `edit_message` | Supported | Uses Telegram message editing APIs. |
+| `delete_message` | Supported | Deletes messages where bot permissions allow it. |
+| `forward_message` | Supported | Forwards a message between Telegram chats. |
+| `get_group_info` | Supported | Uses Telegram chat metadata. |
+| `get_group_member_list` | Supported | Telegram only exposes administrators through the Bot API; this returns the available member set. |
+| `get_group_member_info` | Supported | Maps Telegram member status to EBA member roles. |
+| `get_user_info` | Supported | Uses Telegram `get_chat` for user chat metadata. |
+| `upload_file` | Not supported | Telegram has no standalone upload endpoint; files are uploaded as part of messages. The adapter raises `NotSupportedError`. |
+| `get_file_url` | Supported | Returns the Bot API file URL. Test output redacts the bot token. |
+| `mute_member` | Supported | Requires a supergroup and bot moderation permission. |
+| `unmute_member` | Supported | Uses current `telegram.ChatPermissions` fields. |
+| `kick_member` | Supported | Destructive; should only be run against disposable users/bots in tests. |
+| `leave_group` | Supported | Destructive; should run at the end of a live test. |
+| `call_platform_api` | Supported | See below. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `pin_message`
+- `unpin_message`
+- `unpin_all_messages`
+- `get_chat_administrators`
+- `set_chat_title`
+- `set_chat_description`
+- `get_chat_member_count`
+- `send_chat_action`
+- `create_chat_invite_link`
+- `answer_callback_query`
+
+## Live Test Record
+
+The live probe is:
+
+```bash
+uv run python tests/e2e/live_telegram_eba_probe.py --help
+```
+
+It supports private chat tests, group/supergroup tests, moderation tests, destructive tests, and a callback-only mode.
+
+Verified on May 7, 2026:
+
+- Private chat message APIs: send, reply, edit, delete, forward.
+- Private chat media APIs: image/file sending and `get_file_url`.
+- User API: `get_user_info`.
+- Supergroup APIs: group info, member list, member info, administrators, member count, invite link.
+- Supergroup mutation APIs: pin, unpin, unpin all, set title, restore title, set description, restore description.
+- Moderation APIs: mute and unmute against a non-owner target bot.
+- Destructive APIs: kick a disposable target bot, then make the test bot leave the test group.
+- Event conversion observed for `message.received`, `group.member_banned`, `group.member_left`, `bot.removed_from_group`, and Telegram-specific chat-member updates.
+
+The test fixed one real compatibility issue: `unmute_member` previously used Telegram's removed `can_send_media_messages` permission field. It now uses the split media permission fields required by current `python-telegram-bot`.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 10, 2026 with `EBAEventProbe`, SDK standalone runtime, Telegram Lite, `@rockchinq_bot`, and `Rock'sBotGroup`.
+
+Evidence:
+
+- Private chat JSONL: `data/temp/telegram-plugin-e2e-rerun.jsonl`
+- Group chat JSONL: `data/temp/telegram-plugin-e2e-group.jsonl`
+- Private media JSONL: `data/temp/telegram-plugin-e2e-media-ui.jsonl`
+
+Observed and verified:
+
+- `MessageReceived` reached the plugin with `bot_uuid=eba-telegram-live`, `adapter_name=telegram`, common sender/chat fields, and common `MessageChain` content.
+- `BotInvitedToGroup` reached the plugin after adding the bot to `Rock'sBotGroup`.
+- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
+- Outbound component sweep succeeded in private and group chats: plain text, mention text/equivalent, base64 image, quoted reply, file/document, and flattened forward fallback. Group mode also covered `AtAll` fallback behavior.
+- Real Telegram Lite private-chat inbound media was verified through the plugin path: a sent document arrived as common `File`, and a sent photo arrived as common `Image`.
+- Telegram platform API sweep succeeded for safe group actions: `get_chat_administrators`, `get_chat_member_count`, and `send_chat_action`.
+- Common group/user APIs succeeded in group mode: `get_user_info`, `get_group_info`, `get_group_member_list`, and `get_group_member_info`.
+
+Documented limits in this E2E run:
+
+- Real Telegram UI inbound voice, sticker/emoji-as-common-component, and reply/quote messages were not completed in the plugin E2E evidence.
+- `get_message`, `get_friend_list`, and `get_group_list` are not supported by this Telegram adapter.
+- Mutating/destructive Telegram-specific actions such as pin/unpin, title/description changes, invite-link creation, moderation, kick, and leave were not repeated in the plugin run. They remain opt-in live-probe cases.
+- Telegram does not expose a portable common `Face` component for native sticker/emoji semantics in the current adapter.
+
+## Notes for Future Adapters
+
+Telegram is the reference implementation for:
+
+- Keeping platform-specific actions behind `call_platform_api`.
+- Treating unsupported common APIs as explicit `NotSupportedError`.
+- Marking destructive live test operations behind CLI flags.
+- Redacting access tokens from live probe output.

docs/event-based-agents/adapters/wecom.md

@@ -0,0 +1,130 @@
+# WeCom EBA Adapter
+
+## Status
+
+WeCom application messages now have an EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/wecom/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `wecom-eba`.
+
+This record covers the regular WeCom application-message adapter. WeCom AI Bot (`wecombot-eba`) uses a different protocol flow and is documented separately in `wecombot.md`. WeCom Customer Service (`wecomcs`) remains a separate follow-up migration.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `webhook_url` | No | `""` | Unified webhook URL copied into the WeCom application callback settings. |
+| `corpid` | Yes | `""` | WeCom corporate ID. |
+| `secret` | Yes | `""` | WeCom application secret. |
+| `token` | Yes | `""` | WeCom callback token. |
+| `EncodingAESKey` | Yes | `""` | WeCom callback encryption key. |
+| `contacts_secret` | No | `""` | Contacts secret for contact-list based helper APIs. |
+| `api_base_url` | No | `https://qyapi.weixin.qq.com/cgi-bin` | WeCom API base URL, overrideable for proxy/private-network deployments. |
+
+## Events
+
+WeCom declares these EBA events:
+
+- `message.received`
+- `platform.specific`
+
+`message.received` currently covers text and image application callbacks. Other WeCom callback types are surfaced as `platform.specific` so plugins can inspect the raw structured payload without crashing the common message path.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Private/person target only. `target_id` must be `user_id|agent_id`. Supports text, image, voice, file, flattened forward, and quote fallback. |
+| `reply_message` | Supported | Replies to the original WeCom sender and application agent from `source_platform_object`. |
+| `get_message` | Supported from cache | Returns cached inbound `MessageReceivedEvent` by message ID. |
+| `get_user_info` | Supported | Uses cached event users first, then WeCom `user/get`. |
+| `get_friend_list` | Partial | Returns users seen by this adapter instance. Full contacts listing is not declared as common coverage. |
+| `call_platform_api` | Supported | See below. |
+| `edit_message` | Not supported | WeCom application messages do not expose a general edit endpoint for sent messages. |
+| `delete_message` | Not supported | WeCom application messages do not expose a general delete endpoint for sent messages. |
+| `get_group_info` / member APIs | Not supported | Regular WeCom application callbacks handled here are private user messages, not group-chat bot messages. |
+| `upload_file` / `get_file_url` | Not supported as common APIs | WeCom media upload is used internally while sending image/voice/file components; no portable standalone common file URL is exposed. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `check_access_token`
+- `refresh_access_token`
+- `get_user_info`
+- `send_to_all`
+
+`send_to_all` requires a configured `contacts_secret` with suitable contact visibility and should be treated as a broad-send operation in live testing.
+
+## Unit Verification
+
+Covered by:
+
+```bash
+uv run pytest tests/unit_tests/platform/test_wecom_eba_adapter.py
+```
+
+The unit tests cover:
+
+- Manifest events/APIs/platform actions match adapter declarations.
+- Outbound component conversion for text, image, voice, file, quote fallback, and byte-safe text splitting.
+- Text callback conversion to `MessageReceivedEvent`.
+- Legacy `FriendMessage` compatibility.
+- EBA listener dispatch and inbound message/user cache.
+- `send_message`, `reply_message`, and safe platform API dispatch against a mocked WeCom client.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 27, 2026 with `EBAEventProbe`, SDK standalone runtime, LangBot core, and a real WeCom desktop client against the server test environment.
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+
+cd LangBot
+uv run main.py --standalone-runtime
+
+cd data/plugins/LangBot__EBAEventProbe
+EBA_PROBE_API=1 EBA_PROBE_COMPONENT_SWEEP=1 EBA_PROBE_PLATFORM_API=1 \
+uv --project /absolute/path/to/langbot-plugin-sdk run python -m langbot_plugin.cli.__init__ run
+```
+
+Evidence:
+
+- JSONL: `data/temp/wecom_eba_plugin_probe.jsonl`
+- Bot: `wecom-eba`
+- Client: real WeCom desktop client
+- Environment: `dev.rockchin.top` test server
+
+Observed and verified:
+
+- A real private WeCom user message reached the plugin as `MessageReceived` with `adapter_name=wecom-eba`, common sender/chat fields, and `Source + Plain`.
+- SDK API calls succeeded through the standalone runtime, including `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin/workspace storage, and manifest/list APIs.
+- Safe adapter API checks succeeded through the plugin path for cached message/user data and declared safe platform API actions.
+
+Still required for stricter acceptance:
+
+- Send a private image and confirm common `Image` reaches the plugin.
+- Have the plugin call `send_message` and `reply_message` for text and one media component, then verify the WeCom client receives the bot output.
+- Exercise `send_to_all` only with a disposable visible-contact scope.
+- Trigger one non-text/image callback, if available, and confirm it becomes `PlatformSpecificEventReceived`.
+
+## Current Acceptance
+
+Current status is **partial EBA acceptance**.
+
+Blocked items:
+
+- Real inbound image/voice/file evidence was not completed in this run.
+- Inbound voice/file callback parsing is not present in the legacy `WecomClient.get_message()` path, so the EBA adapter does not claim those receive components yet.
+- Group/member/moderation APIs do not apply to this regular WeCom application-message adapter.

docs/event-based-agents/adapters/wecombot.md

@@ -0,0 +1,148 @@
+# WeComBot EBA Adapter
+
+## Status
+
+WeCom AI Bot now has an EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/wecombot/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `wecombot-eba`.
+
+This is separate from regular WeCom internal applications (`wecom-eba`). WeComBot supports WebSocket long connection mode, which does not require a webhook URL. Webhook mode remains available when `enable-webhook=true`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `BotId` | Yes for WebSocket mode | `""` | WeCom AI Bot ID. |
+| `robot_name` | Yes | `""` | Bot display name used to strip bot mentions from incoming group text. |
+| `enable-webhook` | Yes | `false` | `false` uses WebSocket long connection mode; `true` uses webhook callback mode. |
+| `webhook_url` | No | `""` | Unified webhook URL, only needed when webhook mode is enabled. |
+| `Secret` | Yes for WebSocket mode | `""` | WeCom AI Bot secret for long connection mode. |
+| `Corpid` | Yes for webhook mode | `""` | WeCom corporate ID for webhook callback mode. |
+| `Token` | Yes for webhook mode | `""` | WeCom callback token. |
+| `EncodingAESKey` | Yes for webhook mode; optional for WebSocket media decrypt | `""` | Message encryption/decryption key. |
+| `enable-stream-reply` | No | `true` | Enables WeComBot streaming replies. |
+
+## Events
+
+WeComBot declares these EBA events:
+
+- `message.received`
+- `feedback.received`
+- `platform.specific`
+
+`message.received` covers private and group messages from the WeComBot SDK. `feedback.received` covers WeComBot like/dislike feedback callbacks. Native SDK events without a common EBA equivalent are emitted as `platform.specific`.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported in WebSocket mode | Sends proactive markdown/text to a person or group chat ID. Webhook mode raises `NotSupportedError` because the platform callback flow has no proactive send path here. |
+| `reply_message` | Supported | Replies through native `req_id` in WebSocket mode or stream finalization/cache in webhook mode. |
+| `get_message` | Supported from cache | Returns cached inbound `MessageReceivedEvent` by message ID. |
+| `get_user_info` | Supported from cache | WeComBot events carry user info; no full user lookup endpoint is declared. |
+| `get_friend_list` | Partial | Returns users observed by this adapter instance. |
+| `get_group_info` | Supported from cache | Returns groups observed from inbound group messages. |
+| `get_group_member_info` | Supported from cache | Returns observed sender/group-member pairs. |
+| `get_group_member_list` | Partial | Returns observed members for the cached group only. |
+| `call_platform_api` | Supported | See below. |
+| `edit_message` / `delete_message` / `forward_message` | Not supported | WeComBot does not expose portable common APIs for these operations in the current SDK wrapper. |
+| `upload_file` / `get_file_url` | Not supported as common APIs | Media is represented inside messages; no portable standalone file upload/URL API is declared. |
+| moderation / leave APIs | Not supported | WeComBot does not expose equivalent common moderation operations through this adapter. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `is_websocket_mode`
+- `get_stream_session_status`
+- `send_markdown`
+
+`send_markdown` is only available in WebSocket mode.
+
+## Unit Verification
+
+Covered by:
+
+```bash
+PYTHONPATH=/Users/wangqiang/code/python/langbot-plugin-sdk/src uv run pytest tests/unit_tests/platform/test_wecombot_eba_adapter.py
+```
+
+The unit tests cover:
+
+- Manifest events/APIs/platform actions match adapter declarations.
+- Outbound common components flatten to WeComBot markdown/text.
+- Private and group native events become `MessageReceivedEvent`.
+- Inbound image, file, voice, and quote components map to common `MessageChain`.
+- Legacy `FriendMessage`/`GroupMessage` compatibility.
+- EBA listener dispatch, message/user/group/member cache, reply, send, streaming chunk, feedback, and platform API calls.
+
+## Live Probe
+
+The direct adapter probe is:
+
+```bash
+PYTHONPATH=/absolute/path/to/langbot-plugin-sdk/src uv run python tests/e2e/live_wecombot_eba_probe.py --help
+```
+
+Default mode is WebSocket long connection and requires:
+
+- `WECOMBOT_BOT_ID`
+- `WECOMBOT_SECRET`
+- `WECOMBOT_ROBOT_NAME`
+- optional `WECOMBOT_ENCODING_AES_KEY`
+
+Webhook mode uses `--webhook` and requires:
+
+- `WECOMBOT_TOKEN`
+- `WECOMBOT_ENCODING_AES_KEY`
+- `WECOMBOT_CORPID`
+
+The probe writes JSONL evidence to `data/temp/wecombot_eba_live_probe.jsonl`, waits for a real WeComBot message, records common EBA event fields and message components, then runs safe cached/common/platform API checks.
+
+## Standalone Runtime Plugin E2E Record
+
+Verified on May 27, 2026 with `EBAEventProbe`, SDK standalone runtime, LangBot core, and the real WeCom desktop client in a WeCom AI Bot private chat.
+
+Evidence:
+
+- JSONL: `data/temp/wecombot_eba_plugin_probe.jsonl`
+- Bot UUID: `9f5d4125-7b6d-4c98-8ca2-111111111111`
+- Adapter: `wecombot-eba`
+- Client: real WeCom desktop client, private `LangBot` BOT chat
+- Mode: WebSocket long connection (`enable-webhook=false`)
+
+Observed and verified:
+
+- A real user-side message reached the plugin as `MessageReceived` with `adapter_name=wecombot-eba`, common sender/chat fields, and `Source + Plain`.
+- SDK API calls succeeded through the standalone runtime: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin/workspace storage, manifest/list APIs, and safe cached common platform APIs.
+- Outbound component sweep was visible in the WeCom client and returned `errcode=0`: plain/mention/face fallback, base64 image marker, quote fallback, file marker, and flattened forward fallback.
+- Declared WeComBot platform APIs succeeded through `plugin.call_platform_api`: `is_websocket_mode`, `get_stream_session_status`, and `send_markdown`.
+- The `send_markdown` platform API produced visible bot output in the WeCom client.
+
+Not completed:
+
+- Clicking the visible WeCom AI feedback button did not produce a `FeedbackReceived` JSONL entry in this run, so `feedback.received` remains unverified at plugin E2E level.
+- Group chat inbound and group cache/member coverage still need a real group-side trigger.
+- Real inbound image/file/voice from the WeCom client was not exercised.
+
+## Current Acceptance
+
+Current status is **partial EBA acceptance**.
+
+Blocked or limited items:
+
+- `feedback.received` is implemented and unit-covered, but real plugin E2E feedback evidence was not observed from the desktop client click.
+- Outbound image/voice/file are flattened as textual markers because the WeComBot SDK reply/proactive path used here is markdown/text oriented.
+- Group member APIs are cache-backed and only know members observed in received messages.
+- Destructive or moderation APIs are not declared because the current WeComBot protocol surface does not provide safe common equivalents.

docs/event-based-agents/adapters/wecomcs.md

@@ -0,0 +1,161 @@
+# WeCom Customer Service EBA Adapter
+
+## Status
+
+WeCom Customer Service now has an EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/wecomcs/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `wecomcs-eba`. It is separate from regular WeCom application messages (`wecom-eba`) and WeCom AI Bot (`wecombot-eba`).
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `webhook_url` | No | `""` | Unified webhook URL copied into the WeCom Customer Service callback settings. |
+| `corpid` | Yes | `""` | WeCom corporate ID. |
+| `secret` | Yes | `""` | Customer Service secret used for access tokens. |
+| `token` | Yes | `""` | Customer Service callback token. |
+| `EncodingAESKey` | Yes | `""` | Customer Service callback encryption key. |
+| `api_base_url` | No | `https://qyapi.weixin.qq.com/cgi-bin` | WeCom API base URL, overrideable for proxy/private-network deployments. |
+
+## Events
+
+| Event | Status | Notes |
+|-------|--------|-------|
+| `message.received` | Plugin E2E UI covered for text | Text, image, file, and voice payloads convert to common EBA message components in unit tests. Real WeChat customer-side UI text reached `EBAEventProbe` on May 27, 2026. |
+| `platform.specific` | Unit covered | Non-message or unknown Customer Service payloads become structured `PlatformSpecificEvent` records. |
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Plugin E2E outbound covered | Private/person target only. `target_id` must be `external_userid|open_kfid`. Text and image are implemented; voice/file are explicitly unsupported. |
+| `reply_message` | Plugin E2E partial | Replies through Customer Service `kf/send_msg` using the original `source_platform_object`. The pipeline reply path reached the send API, but the dev account later hit WeCom `95001 send msg count limit`. |
+| `get_message` | Plugin E2E covered from cache | Returns cached inbound `MessageReceivedEvent` by message ID. |
+| `get_user_info` | Plugin E2E covered | Uses cached event users first, then Customer Service `customer/batchget`. |
+| `get_friend_list` | Plugin E2E covered, partial | Returns customer users seen by this adapter instance. |
+| `call_platform_api` | Unit covered | See platform-specific APIs below. |
+| `edit_message` / `delete_message` | Not supported | WeCom Customer Service does not expose a general edit/delete endpoint for bot-sent messages in this adapter. |
+| Group/member/moderation APIs | Not supported | Customer Service conversations handled here are private customer sessions, not group chats. |
+| `upload_file` / `get_file_url` | Not supported | Media upload is used internally for outbound image; no portable file URL common API is exposed. |
+
+## Platform-Specific APIs
+
+| Action | Status | Notes |
+|--------|--------|-------|
+| `check_access_token` | Unit covered | Checks whether the current access token is present. |
+| `refresh_access_token` | Unit covered | Refreshes the Customer Service access token. |
+| `get_customer_info` | Unit covered | Calls Customer Service customer lookup by `external_userid`. |
+
+## Message Components
+
+Receive:
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `Source` | Unit covered | Uses Customer Service `msgid` and `send_time`. |
+| `Plain` | Unit covered | Text payload content is preserved. |
+| `Image` | Unit covered | Uses the base64 data URL produced by the existing SDK image download path. |
+| `Voice` | Unit covered | Maps exposed voice media ID to common `Voice.voice_id`; live UI evidence pending. |
+| `File` | Unit covered | Maps exposed file media ID/name/size to common `File`; live UI evidence pending. |
+| `Quote`, `At`, `AtAll`, `Face`, `Forward` | Not supported inbound | The current Customer Service SDK event model does not expose these as structured inbound fields. |
+| `Unknown` | Unit covered | Unsupported message types become `Unknown` in message conversion or `platform.specific` at event level. |
+
+Send:
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `Plain` | Plugin E2E outbound covered | Sends through `kf/send_msg` text. |
+| `Image` | Plugin E2E outbound covered | Uploads media as WeCom image media and sends through `kf/send_msg` image. |
+| `Quote`, `At`, `AtAll`, `Forward` | Unit covered fallback, live partially blocked | Flattened to text where possible. In the May 27 sweep, later text sends hit WeCom `95001 send msg count limit` after the successful text/image sends. |
+| `Voice`, `File`, `Face` | Not supported | The adapter raises `NotSupportedError`; no tested Customer Service send path is implemented. |
+
+## Unit Verification
+
+Covered by:
+
+```bash
+PYTHONPATH=/Users/wangqiang/code/python/langbot-plugin-sdk/src uv run pytest tests/unit_tests/platform/test_wecomcs_eba_adapter.py
+```
+
+Result on May 27, 2026: `10 passed`.
+
+The local `PYTHONPATH` is required in this workspace because the installed SDK package in the LangBot venv does not contain the newer `langbot_plugin.api.entities.builtin.platform.errors` module; the existing EBA adapter tests need the same SDK override.
+
+## Live Probe
+
+Auxiliary direct adapter probe:
+
+```bash
+PYTHONPATH=/path/to/langbot-plugin-sdk/src uv run python -m py_compile tests/e2e/live_wecomcs_eba_probe.py
+
+WECOMCS_CORPID=... \
+WECOMCS_SECRET=... \
+WECOMCS_TOKEN=... \
+WECOMCS_ENCODING_AES_KEY=... \
+PYTHONPATH=/path/to/langbot-plugin-sdk/src \
+uv run python tests/e2e/live_wecomcs_eba_probe.py \
+  --path /wecomcs/callback \
+  --log data/temp/wecomcs_eba_live_probe.jsonl
+```
+
+This probe is diagnostic only. Final EBA acceptance still requires the standalone SDK runtime plus `EBAEventProbe` plugin path.
+
+## Standalone Runtime Plugin E2E Record
+
+Completed partial plugin E2E on May 27, 2026 against `dev.rockchin.top` and the WeChat customer-side UI entry `微信 -> 客服消息 -> 浪波智能客服`.
+
+Evidence:
+
+- Server JSONL: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/wecomcs_eba_plugin_probe.jsonl`
+- Trigger text: `EBA wecomcs dedupe probe 2026-05-27`
+- `bot_uuid`: `cc810d2c-91f3-4f92-8f27-e1bf9f7b6cb4`
+- `adapter_name`: `wecomcs-eba`
+- Observed common event: `MessageReceived`, `event.type=message.received`
+- Observed message chain: `Source + Plain`
+- Observed chat: `chat_type=private`, `chat_id=external_userid|open_kfid`
+- Observed sender: customer `User` with nickname/avatar from Customer Service lookup
+- Plugin API probe: `send_message`, `get_message`, `get_user_info`, `get_friend_list`, plugin/workspace storage, and manifest/list APIs succeeded
+- Component sweep: outbound `Plain` and `Image` succeeded; `Face` and `File` returned explicit `NotSupportedError`; later quote/forward fallback sends were blocked by WeCom `95001 send msg count limit`
+
+Command shape used:
+
+```bash
+cd langbot-plugin-sdk
+uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
+
+cd LangBot
+PYTHONPATH=/absolute/path/to/langbot-plugin-sdk/src uv run main.py --standalone-runtime
+
+cd data/plugins/LangBot__EBAEventProbe
+DEBUG_RUNTIME_WS_URL=ws://127.0.0.1:5401/plugin/ws \
+EBA_PROBE_LOG=/absolute/path/to/LangBot/data/temp/wecomcs_eba_plugin_probe.jsonl \
+EBA_PROBE_API=1 \
+EBA_PROBE_COMPONENT_SWEEP=1 \
+EBA_PROBE_PLATFORM_API=1 \
+uv --project /absolute/path/to/langbot-plugin-sdk run python -m langbot_plugin.cli.__init__ run
+```
+
+Required real UI trigger: send a Customer Service message from the WeCom/WeChat customer-side UI to the configured `dev.rockchin.top` Customer Service account.
+
+## Current Acceptance
+
+Current status is **partial EBA acceptance**.
+
+Blocked or pending items:
+
+- Inbound UI media (`Image`, `Voice`, `File`) was not sent from the real WeChat customer UI during this run, so receive-side media remains unit-covered only.
+- Pipeline auto-reply reached `kf/send_msg`, but the test account hit WeCom `95001 send msg count limit` after successful plugin outbound text/image sends. This is recorded as an account/platform rate-limit block, not a conversion or API-shape failure.
+- The current `EBAEventProbe` run did not call the adapter-specific `call_platform_api` actions (`check_access_token`, `refresh_access_token`, `get_customer_info`); the platform API map remains unit-covered.
+- Inbound voice/file depends on whether the real Customer Service callback plus `sync_msg` endpoint returns those fields in the shape the local SDK models.
+- Group, member, edit, delete, moderation, and standalone file URL APIs are intentionally not declared because this Customer Service protocol path does not provide tested common equivalents.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot"
-version = "4.10.2"
+version = "4.10.1"
 description = "Production-grade platform for building agentic IM bots"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -70,7 +70,7 @@ dependencies = [
     "chromadb>=1.0.0,<2.0.0",
     "qdrant-client (>=1.15.1,<2.0.0)",
     "pyseekdb==1.1.0.post3",
-    "langbot-plugin==0.4.5",
+    "langbot-plugin==0.5.0a2",
     "asyncpg>=0.30.0",
     "line-bot-sdk>=3.19.0",
     "matrix-nio>=0.25.2",
@@ -79,7 +79,6 @@ dependencies = [
     "pymilvus>=2.6.4",
     "pgvector>=0.4.1",
     "botocore>=1.42.39",
-    "litellm>=1.0.0",
 ]
 keywords = [
     "bot",
@@ -119,7 +118,7 @@ requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/*", "pkg/platform/sources/*", "web/dist/**", "pkg/persistence/alembic/**"] }
+package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/*", "pkg/platform/sources/*", "pkg/platform/adapters/**", "web/dist/**", "pkg/persistence/alembic/**"] }
 
 [dependency-groups]
 dev = [

skills/.gitignore

@@ -1,9 +0,0 @@
-node_modules/
-coverage/
-.tap/
-__pycache__/
-*.pyc
-skills/.env.local
-reports/
-skills/*/reports/
-.browser/

skills/AGENTS.md

@@ -1,68 +0,0 @@
-# Agent Workflow
-
-This repository stores reusable LangBot agent-testing assets. Keep changes structured so the next agent does not need to rediscover paths.
-
-## First Steps
-
-1. Read `skills/.env` before using local URLs, paths, browser profiles, or proxy defaults. If present, `skills/.env.local` overrides it for this machine and must not be committed. On a new machine, copy `skills/.env.example` to `skills/.env.local` first.
-2. Pick the smallest relevant skill:
-   - `langbot-env-setup` for environment, browser, OAuth, proxy, and startup.
-   - `langbot-testing` for WebUI, provider, pipeline, cases, and troubleshooting.
-   - `langbot-skills-maintenance` for adding, deduplicating, or auditing this skills repository.
-3. Prefer existing cases and troubleshooting entries before exploring from scratch.
-
-## Editing Rules
-
-- UI/browser testing is the primary QA path. API/curl checks are diagnostic only and cannot make a UI case pass by themselves.
-- Put skills under `skills/<name>/`.
-- Keep `SKILL.md` concise; move detailed workflows to `references/`.
-- Put reusable test paths in `cases/*.yaml`.
-- New or edited cases must include `priority`, `risk`, `ci_eligible`, and `evidence_required` so agents can select the right test set without rereading every file.
-- Use `env_any` / `automation_env_any` for one-of machine inputs, such as `LANGBOT_PIPELINE_URL|LANGBOT_PIPELINE_NAME`; do not list those alternatives as separate all-required env keys.
-- Put reusable groups of cases in `suites/*.yaml` rather than hardcoding test sets in docs or CLI code.
-- Put growing failure knowledge in `troubleshooting/*.yaml`.
-- Do not hardcode local ports in testing docs; use `skills/.env` variables and machine-local `skills/.env.local` overrides.
-- Do not store secrets, API keys, OAuth tokens, or localStorage token values.
-
-## Required Checks
-
-After structural changes, run:
-
-```bash
-bin/lbs validate
-```
-
-After changing skills, cases, or troubleshooting assets, run:
-
-```bash
-bin/lbs index
-```
-
-Use `bin/lbs env show` to inspect defaults and `bin/lbs env doctor` when diagnosing local environment readiness. Env output is redacted by default; do not work around that by printing raw secrets.
-`bin/lbs` is a generated local wrapper. If it is missing on a fresh checkout, run `npm run bootstrap` from this directory first; `npm install` also regenerates it via `prepare`.
-Use `bin/lbs fixture check` before fixture-heavy cases such as MCP, RAG, multimodal, or plugin smoke tests.
-Use `bin/lbs case list --ready` for cases that have no missing machine inputs and no manual preconditions. Use `bin/lbs case list --machine-ready` when you want to keep `manual-check` candidates and confirm their preconditions yourself.
-
-Before executing a saved QA path, generate the agent-facing plan:
-
-```bash
-bin/lbs test plan <case-id>
-```
-
-Read the plan readiness sections before running the browser path. Missing env,
-automation env, or fixture readiness means the case is not ready to execute and
-should be marked `blocked` or fixed first.
-`manual_check` means machine inputs are present but the agent must verify the
-declared `preconditions` or `setup` items before executing the UI path. Do not
-turn a `manual_check` case into `pass` until those items were checked in the
-same run.
-
-Before executing a group of saved QA paths, generate the suite plan:
-
-```bash
-bin/lbs suite plan <suite-id>
-```
-
-Use `bin/lbs suite start <suite-id>` to create a shared suite run id, suite evidence root, per-case evidence directories, and `suite-start.json`/`suite-start.md` handoff files. Then run `bin/lbs suite report <suite-id> --evidence-dir <dir>` to aggregate case results.
-Automation scripts write `automation-result.json`; write the final per-case `result.json` with `bin/lbs test result <case-id> --result <status> --reason <text> --evidence-dir <dir> --evidence <comma-list>` after collecting the required evidence. A `pass` result must include all required evidence.
-For runner-specific Debug Chat cases, prefer case-specific pipeline env keys such as `LANGBOT_LOCAL_AGENT_PIPELINE_URL` over the generic `LANGBOT_PIPELINE_URL`; otherwise an agent can accidentally test the wrong runner.

skills/README.md

@@ -1,58 +0,0 @@
-# LangBot Skills
-
-This directory is the **single source of truth** for LangBot's agent skills —
-reusable, on-demand instruction packs for AI agents (Claude Code, Codex, Cursor,
-and LangBot's own Local Agent) working with the LangBot ecosystem.
-
-> These skills were consolidated here from the former `langbot-app/langbot-skills`
-> repository (now archived). Documentation and the landing page link here; do not
-> re-copy skill content elsewhere — link to this directory instead.
-
-## Skill catalog
-
-| Skill | What it covers |
-| --- | --- |
-| [`langbot-dev`](skills/langbot-dev) | Core backend + web frontend development (Quart, Vite, API, migrations, MCP server) |
-| [`langbot-plugin-dev`](skills/langbot-plugin-dev) | Plugin SDK / component development, debugging, WebSocket testing |
-| [`langbot-deploy`](skills/langbot-deploy) | Docker / Compose / Kubernetes deployment, config.yaml, Box runtime, global API key |
-| [`langbot-testing`](skills/langbot-testing) | WebUI / e2e QA harness, cases, fixtures, troubleshooting (the `bin/lbs` CLI) |
-| [`langbot-env-setup`](skills/langbot-env-setup) | Local dev/test environment, browser access, OAuth, proxy, startup |
-| [`langbot-mcp-ops`](skills/langbot-mcp-ops) | Operating a LangBot instance through its MCP server (`/mcp`) |
-| [`langbot-space-ops`](skills/langbot-space-ops) | Browsing the LangBot Space marketplaces through the Space MCP server |
-| [`langbot-eba-adapter-dev`](skills/langbot-eba-adapter-dev) | Building platform adapters for the Event-Based Agents architecture |
-| [`langbot-skills-maintenance`](skills/langbot-skills-maintenance) | Adding, deduplicating, and auditing skills in this directory |
-
-`skills.index.json` is the machine-readable index (regenerate with `bin/lbs index`).
-
-## Quick start (for an AI agent)
-
-1. Read this README, `AGENTS.md`, and `qa-agent-docs/` to understand the layout.
-2. Read `skills/.env` for shared local defaults. On a new machine, copy
-   `skills/.env.example` to `skills/.env.local` (gitignored) and override
-   machine-specific values there. Never commit secrets.
-3. Pick the smallest relevant skill from the catalog above and follow its
-   `SKILL.md`.
-
-## The `lbs` CLI
-
-The testing assets ship with a small CLI (`bin/lbs`, Node >= 22.6). The
-`bin/lbs` wrapper is a generated local entrypoint; on a fresh checkout, run
-`npm run bootstrap` once if it is missing. `npm install` also regenerates it via
-the `prepare` script.
-
-```bash
-npm run bootstrap    # create bin/lbs if missing
-bin/lbs validate     # validate skills/cases/troubleshooting structure
-bin/lbs index        # regenerate skills.index.json
-bin/lbs env show     # inspect resolved env defaults (redacted)
-bin/lbs env doctor   # diagnose local environment readiness
-bin/lbs case list --ready
-bin/lbs test plan <case-id>
-```
-
-## Maintenance rule
-
-When the LangBot / LangBot Space **API or MCP server changes**, the
-corresponding skill here MUST be updated in the same change. The MCP tool
-surface, the API, and these skills are kept in lockstep — see each repo's
-`AGENTS.md`.

skills/package.json

@@ -1,29 +0,0 @@
-{
-  "private": true,
-  "type": "module",
-  "bin": {
-    "lbs": "./bin/lbs"
-  },
-  "scripts": {
-    "bootstrap": "node scripts/bootstrap-lbs.mjs",
-    "prepare": "node scripts/bootstrap-lbs.mjs",
-    "prevalidate": "node scripts/bootstrap-lbs.mjs",
-    "preindex": "node scripts/bootstrap-lbs.mjs",
-    "preindex:check": "node scripts/bootstrap-lbs.mjs",
-    "pretest": "node scripts/bootstrap-lbs.mjs",
-    "precheck": "node scripts/bootstrap-lbs.mjs",
-    "lbs": "node src/lbs.ts",
-    "test": "node test/lbs-cli.test.ts",
-    "validate": "node src/lbs.ts validate",
-    "index": "node src/lbs.ts index",
-    "index:check": "node src/lbs.ts index --check",
-    "check:syntax": "find src test scripts -type f \\( -name '*.ts' -o -name '*.mjs' \\) -print0 | xargs -0 -n1 node --check",
-    "check": "npm run check:syntax && npm run validate && npm test"
-  },
-  "engines": {
-    "node": ">=22.6"
-  },
-  "devDependencies": {
-    "playwright": "^1.60.0"
-  }
-}

skills/qa-agent-docs/qa-agent/00-technology-options.md

@@ -1,117 +0,0 @@
-# LangBot Agent Testing 技术选型
-
-## 状态
-
-这是技术选型背景文档，不是当前路线图。当前黑盒 E2E QA 的实施顺序见：
-
-```text
-docs/qa-agent/04-black-box-e2e-roadmap.md
-```
-
-## 目标
-
-`langbot-skills` 的目标不是替代测试框架，而是沉淀 agent 可复用的测试资产，让开发者 clone 仓库后，可以让 Codex、Claude Code、Computer Use 或 Playwright MCP 复用已有路径完成 LangBot 功能验证。
-
-核心原则：
-
-- Skill 负责路由和少量规则。
-- Reference 负责可读流程和背景知识。
-- Case 负责结构化测试路径。
-- Troubleshooting 负责结构化故障资产。
-- `lbs` 负责结构校验、索引、资产创建和未来的运行/报告能力。
-- UI/browser 是产品 QA 的主路径；API/curl 只用于诊断。
-
-## 浏览器控制层
-
-不同开发者可用的浏览器控制能力不同，所以浏览器层必须可替换。
-
-| 方案 | 适用场景 | 优点 | 代价 |
-|---|---|---|---|
-| Codex / Claude Computer Use | agent 可以直接控制可见浏览器 | 登录和交互路径最自然，通常不需要额外 MCP 浏览器桥接 | 依赖具体 agent 工具能力 |
-| Playwright MCP | 没有 Computer Use，但有 MCP 浏览器工具 | 稳定、可脚本化、适合回归路径 | OAuth 登录通常需要额外 visible profile |
-| 直接 Playwright 脚本 | 测试路径非常稳定，适合 CI | 可重复性强 | 需要维护脚本和 selector |
-| 商业 AI QA 平台 | 团队希望外包测试运行平台 | 报告和 PR 集成完整 | 成本和平台绑定 |
-
-## 当前推荐
-
-先采用分层降级：
-
-```text
-有 Computer Use？
-  是 -> 使用 Computer Use 控制浏览器
-  否 -> 使用 Playwright MCP
-
-需要 GitHub OAuth？
-  是 -> 使用持久浏览器 profile，让用户手动完成登录
-  否 -> 直接使用已有登录态或测试账号状态
-```
-
-具体选择逻辑沉淀在：
-
-```text
-skills/langbot-env-setup/references/browser-access-selection.md
-```
-
-测试原则固定在：
-
-```text
-docs/qa-agent/03-agent-browser-qa-principles.md
-```
-
-## 环境变量层
-
-测试文档不应写死端口。共享默认值放在：
-
-```text
-skills/.env
-```
-
-关键变量：
-
-```text
-LANGBOT_FRONTEND_URL
-LANGBOT_BACKEND_URL
-LANGBOT_DEV_FRONTEND_URL
-LANGBOT_REPO
-LANGBOT_WEB_REPO
-LANGBOT_BROWSER_PROFILE
-```
-
-Agent 执行测试前应先读取 `skills/.env`，再用用户提供的当前环境或已启动服务覆盖默认值。
-
-## 测试资产层
-
-测试资产分两类：
-
-```text
-skills/<skill>/
-  references/        # Markdown 流程说明
-  cases/             # 结构化测试用例
-  troubleshooting/   # 结构化故障记录
-```
-
-当前已实现：
-
-- `SKILL.md` 路由
-- `references/*.md`
-- `lbs case new/list/show`
-- `lbs trouble show/search`
-- `lbs test plan`
-- `lbs test report`
-- `lbs list / validate / index`
-
-下一步重点：
-
-- 日志守卫规则补充
-- 报告产物管理
-
-## 关键判断
-
-不要强制所有内容只能通过 CLI 修改。更好的模式是：
-
-- 新增 case/troubleshooting：优先使用 `lbs`
-- 大段流程说明：允许直接编辑 Markdown
-- 结构性变更后：必须运行 `lbs validate`
-- 任何生成索引的变更后：运行 `lbs index`
-
-这样既能沉淀结构化资产，又不会在 schema 未稳定时拖慢迭代。

skills/qa-agent-docs/qa-agent/01-qa-agent-harness-plan.md

@@ -1,231 +0,0 @@
-# LangBot Skills 测试资产库规划
-
-## 状态
-
-这是早期测试资产库规划文档，保留用于解释 `langbot-skills` 的分层来源。
-
-当前路线已经收敛为黑盒 E2E QA：开发者用 agent 通过浏览器测试 LangBot，
-稳定路径沉淀为 case，失败知识沉淀为 troubleshooting。`lbs test report` 和
-日志守卫已有 MVP，后续重点是报告证据、case 元数据和少量稳定路径自动化。当前优先级见：
-
-```text
-docs/qa-agent/04-black-box-e2e-roadmap.md
-```
-
-本文中关于 `case list/show`、`trouble show/search`、`test plan` 的“计划实现”
-内容已经部分过时，因为这些能力已经落地。
-
-## 目标
-
-让开发者 clone `langbot-skills` 后，可以把测试意图交给 agent，由 agent 复用已有环境配置、测试路径和故障知识完成 LangBot 功能验证。
-
-典型场景：
-
-- 冒烟测试：验证 pipeline Debug Chat、provider、常见页面是否正常。
-- Provider 测试：添加 DeepSeek/OpenAI/Claude 等供应商并验证模型可用。
-- 新 feature 测试：探索新 UI 路径，并在稳定后沉淀成 case/reference。
-- 回归测试：复用旧路径，避免每个窗口重新探索登录、模型配置、pipeline 调试。
-- 故障沉淀：把 runtime 超时、代理不一致、WebSocket 问题记录为可搜索资产。
-
-核心方向见 `03-agent-browser-qa-principles.md`：agent 必须以浏览器/UI 为主路径，API/curl 只能作为诊断手段。
-
-## 当前仓库结构
-
-```text
-skills/
-  .env                         # 共享默认变量
-  langbot-env-setup/           # 环境准备、浏览器控制路径、代理、登录态
-  langbot-testing/             # WebUI / provider / pipeline 测试入口
-  langbot-plugin-dev/          # 插件开发测试
-  langbot-eba-adapter-dev/     # 平台适配器开发测试
-src/
-  lbs.ts                       # CLI 源码
-bin/
-  lbs                          # CLI 入口
-docs/
-  qa-agent/                    # 规划文档，历史目录名保留
-```
-
-## 设计分层
-
-### 1. Skill 层
-
-`SKILL.md` 只做触发和路由，不承载大段流程。
-
-例子：
-
-```text
-langbot-env-setup -> 选择 Computer Use / Playwright MCP / OAuth profile / proxy
-langbot-testing -> 选择 WebUI / pipeline / provider / troubleshooting
-```
-
-### 2. Reference 层
-
-Markdown 记录人和 agent 都能读的流程说明。
-
-适合内容：
-
-- 如何选择浏览器控制方式
-- 如何启动/检查服务
-- 如何执行 pipeline Debug Chat
-- 如何处理 OAuth 登录态
-
-### 3. Case 层
-
-使用 YAML 记录可重复测试路径。
-
-建议结构：
-
-```text
-skills/langbot-testing/cases/
-  pipeline-debug-chat.yaml
-  provider-deepseek.yaml
-```
-
-建议格式：
-
-```yaml
-id: pipeline-debug-chat
-title: Pipeline Debug Chat returns a bot response
-mode: agent-browser
-area: pipeline
-type: smoke
-skills:
-  - langbot-env-setup
-  - langbot-testing
-env:
-  - LANGBOT_FRONTEND_URL
-  - LANGBOT_BACKEND_URL
-steps:
-  - Open LANGBOT_FRONTEND_URL
-  - Navigate to Pipelines
-  - Open target pipeline
-  - Select Debug Chat
-  - Send deterministic prompt
-checks:
-  - "UI: User message appears"
-  - "UI: Bot message appears"
-  - "Console: No unexpected frontend errors"
-  - "Logs: Backend log includes Conversation(0) Streaming completed"
-diagnostics:
-  - "Use API/curl only after the UI path is attempted, to distinguish frontend display failure from backend/runtime failure."
-troubleshooting:
-  - plugin-runtime-timeout
-  - proxy-env-mismatch
-```
-
-### 4. Troubleshooting 层
-
-故障资产会逐渐变大，适合结构化记录。
-
-历史 Markdown 入口保留在：
-
-```text
-skills/langbot-testing/references/troubleshooting.md
-```
-
-当前 canonical 结构化故障资产在：
-
-```text
-skills/langbot-testing/troubleshooting/
-  plugin-runtime-timeout.yaml
-  proxy-env-mismatch.yaml
-```
-
-### 5. CLI 层
-
-`lbs` 是统一入口，不再引入独立 `qa` 命令。
-
-已实现或当前可用：
-
-```bash
-bin/lbs list
-bin/lbs validate
-bin/lbs index
-bin/lbs new-skill <name>
-bin/lbs new-ref <skill> <name>
-bin/lbs case new pipeline-debug-chat --title "Pipeline Debug Chat"
-bin/lbs case list
-bin/lbs case show pipeline-debug-chat
-bin/lbs trouble list <skill>
-bin/lbs trouble show plugin-runtime-timeout
-bin/lbs trouble search runtime
-bin/lbs trouble add <skill> --title ... --symptom ... --cause ... --fix ...
-bin/lbs test plan pipeline-debug-chat
-bin/lbs test start pipeline-debug-chat
-bin/lbs test run pipeline-debug-chat --dry-run
-bin/lbs test report pipeline-debug-chat
-bin/lbs test report pipeline-debug-chat --backend-log /path/to/backend.log
-```
-
-## 测试库位置
-
-不要使用隐藏 `.qa/` 作为主测试库。测试资产应该和 skill 放在一起，便于触发和维护：
-
-```text
-skills/langbot-testing/
-  references/
-  cases/
-  troubleshooting/
-  reports/          # 可选，本地运行产物可按需忽略或输出到外部目录
-```
-
-如果未来需要项目本地测试库，可以允许 `lbs` 支持 `--workspace` 或项目根目录配置，但 canonical 资产仍保存在 `langbot-skills`。
-
-## 阶段规划
-
-### 阶段一：环境和测试路径沉淀
-
-状态：基本完成，持续维护。
-
-- `skills/.env` 管共享默认变量。
-- `langbot-env-setup` 拆出 Computer Use、Playwright MCP、OAuth profile、proxy、service startup。
-- `langbot-testing` 记录 WebUI、pipeline、provider 测试路径。
-- `lbs validate/index` 维护结构。
-
-完成标准：
-
-- agent 可以从 `skills/.env` 和 references 中找到当前测试入口。
-- pipeline Debug Chat 这类路径不再需要从头探索。
-
-### 阶段二：结构化 case/troubleshooting
-
-状态：主体已完成，继续补齐元数据和资产质量。
-
-目标：
-
-- `lbs case new/list/show`
-- `lbs trouble show/search`
-- case id 去重、字段校验、索引生成
-
-完成标准：
-
-- 冒烟测试路径可以用结构化 case 表示。
-- 下一个 agent 窗口可以直接读取 case 执行。
-
-### 阶段三：计划和报告
-
-状态：已有 MVP，继续完善。
-
-目标：
-
-- `lbs test plan <case>`
-- agent 按 plan 使用浏览器执行 UI QA
-- `lbs test report`
-- 日志守卫集成
-- 报告产物和 evidence 约定
-
-完成标准：
-
-- agent 可以按 case plan 执行浏览器测试。
-- 结果报告包含 UI 结果、后端日志、console 错误和 troubleshooting 建议。
-
-## 执行规则
-
-- agent 可以直接编辑 Markdown reference。
-- 新增结构化 case/troubleshooting 时，优先使用 `lbs`。
-- 每次结构变更后运行 `bin/lbs validate`。
-- 每次索引相关变更后运行 `bin/lbs index`。
-- 测试文档不写死端口，使用 `skills/.env` 中的 URL 变量。
-- 测试 case 的 `mode` 固定为 `agent-browser`。
-- API/curl 只能写入 `diagnostics`，不能替代 UI 步骤和 UI 检查。

skills/qa-agent-docs/qa-agent/02-log-guard-plan.md

@@ -1,161 +0,0 @@
-# 日志守卫规划
-
-## 状态
-
-这是当前活跃设计，已有第一版文件扫描 MVP。实现边界需要和黑盒 E2E 路线保持一致：
-
-- 日志守卫服务于 `lbs test report`。
-- 它不替代浏览器/UI 判断。
-- 它不发展成独立后端 API 测试框架。
-- 第一版默认扫描 `LANGBOT_REPO/data/logs/` 下最新的 `langbot-*.log`，也可扫描 agent
-  显式提供的 backend/frontend/console 日志文件。
-
-当前总体路线见：
-
-```text
-docs/qa-agent/04-black-box-e2e-roadmap.md
-```
-
-## 目标
-
-日志守卫是 `lbs test report` 的一部分，用来在 agent 执行测试期间捕获 UI 断言之外的运行时问题。
-
-当前命令方向已收敛为 `lbs test plan` / `lbs test report`。日志守卫服务于 agent-browser QA，不是独立的后端 API 测试入口。
-
-LangBot 是异步且集成度高的系统，有些问题不会直接表现为页面失败：
-
-- 后台任务异常
-- 未等待的协程
-- Provider 流式调用失败
-- 插件 runtime 超时
-- 平台发送失败
-- 数据库连接问题
-- 敏感信息泄露
-
-日志守卫负责把这些信号结构化地放进测试报告，并关联到 troubleshooting 资产。
-
-## 输入
-
-日志守卫应从环境和运行上下文读取配置：
-
-- `skills/.env` 中的 `LANGBOT_BACKEND_URL`
-- `skills/.env` 中的 `LANGBOT_REPO`，用于自动发现 LangBot 后端日志
-- `lbs test plan` / report 记录的 case id
-- LangBot 后端进程输出
-- 前端 dev server 输出
-- 浏览器 console/network 错误
-- case 声明的 success/failure patterns 和 expected failures
-
-## MVP 范围
-
-- 读取一个或多个日志流或日志文件。
-- 检测错误模式。
-- 支持按 case id 或 pattern 白名单。
-- 输出 JSON/Markdown 摘要。
-- 发现非预期错误时让测试报告标记失败；未来如果有自动执行器，再返回非零退出码。
-
-## 错误分类
-
-### 永远非预期
-
-除非 case 明确声明，否则应失败：
-
-- `Traceback`
-- `Task exception was never retrieved`
-- `RuntimeWarning: coroutine .* was never awaited`
-- `Unclosed client session`
-- `Unclosed connector`
-- `KeyError`
-- `TypeError`
-- `AttributeError`
-- 密钥、token、secret 明文泄露
-
-### Case 预期错误
-
-只有当前 case 声明时允许：
-
-- 无效 provider key
-- Provider 认证失败
-- 无效 webhook payload
-- 插件测试故意抛错
-- 超时测试
-- 限流测试
-
-### 仅警告
-
-报告但默认不失败：
-
-- 可恢复重试
-- 恢复的超时
-- 废弃配置
-- 慢请求
-- 版本检查失败
-
-## 与 Troubleshooting 集成
-
-日志守卫不只输出错误文本，还应尽量匹配已知 troubleshooting id。
-
-例子：
-
-```text
-Action list_plugins call timed out
-Action list_agent_runners call timed out
-Action invoke_llm_stream call timed out
-```
-
-可映射到：
-
-```text
-plugin-runtime-timeout
-```
-
-```text
-uppercase proxy points to one host, lowercase proxy points to another
-```
-
-可映射到：
-
-```text
-proxy-env-mismatch
-```
-
-## 未来命令
-
-```bash
-bin/lbs test plan pipeline-debug-chat
-bin/lbs test start pipeline-debug-chat
-bin/lbs test run pipeline-debug-chat --dry-run
-bin/lbs test report pipeline-debug-chat
-bin/lbs test report --output report.md
-bin/lbs test report pipeline-debug-chat --backend-log /path/to/backend.log --console-log /path/to/console.log
-bin/lbs test report pipeline-debug-chat --since "2026-05-21T10:30:00+08:00"
-bin/lbs test report pipeline-debug-chat --tail-lines 2000
-bin/lbs test report pipeline-debug-chat --since "2026-05-21T10:30:00+08:00" --tail-lines 2000
-bin/lbs test report pipeline-debug-chat --no-auto-log
-```
-
-运行报告应包含：
-
-- case id
-- URL 和环境变量摘要，不能包含 secrets
-- 浏览器可见结果
-- 后端日志摘要
-- console/network 错误
-- 匹配到的 troubleshooting id
-- 通过/失败结论
-
-## MVP 完成标准
-
-- 可以自动扫描最新 LangBot 后端日志，也可以扫描前端日志和 console 日志文件。
-- 可以用 `--since` 或 `--tail-lines` 把扫描范围限制到本次测试窗口。
-- 可以检测明显 Python/运行时错误和 secret 泄露风险。
-- 可以识别 case 声明的 success/failure patterns。
-- 可以识别 troubleshooting pattern，包括 `plugin-runtime-timeout` 和 `proxy-env-mismatch`。
-- 支持 case 级白名单。
-- 输出机器可读摘要。
-- 至少一个 `langbot-testing` case 使用它。
-
-当前 MVP 已覆盖自动发现 LangBot 后端日志、文件扫描、`--since`/`--tail-lines` 扫描窗口、
-基础错误检测、case success/failure signal、troubleshooting 匹配、secret 脱敏和 `--json`
-输出。仍待继续完善的是 live log 采集、更多规则、case 级 expected failure 的资产化和真实
-E2E report 样例。

skills/qa-agent-docs/qa-agent/03-agent-browser-qa-principles.md

@@ -1,57 +0,0 @@
-# Agent Browser QA Principles
-
-This document fixes the direction of LangBot agent testing so the project does not drift into a backend API smoke-test framework.
-
-## Primary Goal
-
-`langbot-skills` should help an agent behave like a QA engineer using the product, not like a backend curl script.
-
-The primary path is:
-
-```text
-developer intent -> lbs test plan -> agent controls browser -> UI result + console + logs -> report/assets
-```
-
-## Rules
-
-1. Browser/UI interaction is the source of truth for product QA cases.
-2. A backend API or curl response is never enough to mark a UI case passed.
-3. API/curl/log checks are allowed as diagnostics after a UI path is attempted or when debugging environment readiness.
-4. A case passes only when the user-visible UI result is correct.
-5. The agent should inspect browser console/network output when available.
-6. If screenshot or vision capability is available, the agent should check for blank pages, overlap, hidden actions, broken layout, and error toasts.
-7. If no visual model is available, use DOM/accessibility snapshots and console output instead.
-8. New stable UI paths should be added as `cases/*.yaml`.
-9. New recurring failure modes should be added as `troubleshooting/*.yaml`.
-10. Secrets, tokens, API keys, and localStorage token values must never be printed.
-
-## Command Semantics
-
-`lbs` manages assets and produces plans. It does not replace the agent's browser-control ability.
-
-```bash
-bin/lbs test plan pipeline-debug-chat
-```
-
-This command outputs:
-
-- environment variables to use
-- required skills
-- browser steps
-- UI/console/visual/log checks
-- diagnostic options
-- related troubleshooting patterns
-- report template
-
-The active agent then executes the plan with Computer Use, Playwright MCP, or another available browser-control tool.
-
-## Diagnostics
-
-Diagnostics can include:
-
-- `bin/lbs env doctor`
-- browser console/network inspection
-- backend logs
-- targeted API/curl checks
-
-Diagnostics answer "where did it fail?" They do not replace "did the user-visible UI work?"

skills/qa-agent-docs/qa-agent/04-black-box-e2e-roadmap.md

@@ -1,299 +0,0 @@
-# 黑盒 E2E QA 路线图
-
-## 定位
-
-LangBot 有大量外部依赖：模型供应商、plugin runtime、浏览器登录态、
-marketplace/network、RAG engine、sandbox backend、平台适配器等。单测仍然有价值，
-但这个 QA 方向当前不优先解决 LangBot core 的单测覆盖率问题，因为重 mock 往往不能
-真实代表产品路径。
-
-`langbot-skills` 当前目标是让黑盒 E2E 测试变得可执行、可沉淀、可复用：
-
-```text
-开发者测试意图
--> 复用或新增 case
--> agent 通过浏览器执行
--> UI + console + network + log 证据
--> report
--> 反哺 case / troubleshooting
-```
-
-这是面向开发者的 QA 资产库。开发者可以让 agent 测一个 feature；如果路径稳定，
-就把路径正规化为 case，让下一个开发者或 QA agent 继续复用。
-
-## 非目标
-
-- 这一阶段不优先建设 LangBot core 单测覆盖率。
-- 不把 API/curl 作为 WebUI 行为的通过标准。
-- 不要求每个 case 都能进 CI。
-- 不在 report 和日志守卫有用之前急着做完整 browser runner。
-- 不把外部 provider、OAuth、marketplace 抖动直接判成产品失败，除非证据明确。
-
-## 当前状态
-
-仓库已经具备第一层基础设施：
-
-- `skills/.env` 和 `skills/.env.local` 管理测试环境；
-- `langbot-env-setup`、`langbot-testing`、`langbot-plugin-dev` 等 skill；
-- `skills/langbot-testing/cases` 下的结构化 case；
-- `skills/langbot-testing/troubleshooting` 下的结构化故障资产；
-- RAG、多模态、plugin、MCP 等 fixture；
-- `bin/lbs validate`、`bin/lbs index`、`bin/lbs case`、`bin/lbs trouble`、
-  `bin/lbs test plan`、`bin/lbs test start`、`bin/lbs test report`。
-
-所以当前已经不是“先把路径写进 Markdown”的阶段，而是进入“让每次运行有证据、
-有报告、能沉淀”的阶段。
-
-## 测试模型
-
-UI case 只有在用户可见行为正确时才能通过。辅助证据必须解释同一次运行。
-
-通过一个 UI case 的最低证据：
-
-- 用户可见的成功信号，例如 bot 回复、provider 保存成功、文件上传完成、plugin 页面渲染；
-- 没有意外 browser console error；
-- 相关时间窗口内没有意外后端/runtime 错误；
-- 有截图、DOM snapshot 或同等视觉/结构证据，如果当前 agent 能获取；
-- API/curl 只在解释同一条 UI 路径时作为诊断证据。
-
-失败报告需要保留足够信息，让开发者能复现或分流：
-
-- case id 和实际测试 URL；
-- 使用的 browser path；
-- 最后可见 UI 状态；
-- console/network 症状；
-- 相关后端/前端日志；
-- 匹配到的 troubleshooting id；
-- 这是产品失败、环境问题、外部依赖抖动，还是证据不足。
-
-## 结果词汇
-
-统一使用这些结果：
-
-- `pass`：UI 行为正确，辅助证据干净。
-- `fail`：UI 行为错误，或同一次运行的 console/log 出现意外产品错误。
-- `blocked`：缺登录、缺 provider credentials、服务未启动等原因导致目标路径没有跑起来。
-- `env_issue`：失败在目标行为之外，例如 proxy、OAuth、provider quota、marketplace outage、
-  本地服务启动问题。
-- `flaky`：同一环境下结果不稳定，进入门禁前需要先稳定。
-
-做 merge/release 判断时，`env_issue` 和 `blocked` 不能算产品通过。
-
-## 路线图
-
-### Phase 0：对齐文档
-
-目标：明确当前黑盒 E2E 方向。
-
-交付物：
-
-- `docs/qa-agent/README.md` 文档状态导航；
-- 本路线图；
-- 给旧规划文档加状态说明。
-
-完成标准：
-
-- 新贡献者不用通读所有旧文档，也能知道当前重点。
-
-### Phase 1：Test Report MVP
-
-状态：已有第一版。
-
-目标：让每次 agent browser 测试都有一致报告格式，即使 browser 执行还没自动化。
-
-建议命令：
-
-```bash
-bin/lbs test start <case-id>
-bin/lbs test report <case-id> --output reports/<timestamp>-<case-id>.md
-```
-
-MVP 行为：
-
-- 读取 case 和关联 troubleshooting；
-- 生成 Markdown report 模板；
-- 生成 run handoff，固定本次测试的 start timestamp 和推荐 report command；
-- 写入脱敏后的环境摘要；
-- 提供 `pass/fail/blocked/env_issue/flaky` 结果选项；
-- 包含 UI result、console errors、network symptoms、logs、screenshots、
-  diagnostics、matched troubleshooting、assets to update 等 section；
-- 支持 `--json`，输出机器可读报告。
-
-第一版已经是 report generator，不急着做自动判定。先把 evidence 收集格式统一起来，
-再做自动化更稳。
-
-完成标准：
-
-- agent 可以先跑 `lbs test start <case-id>`，用它给出的时间窗口执行浏览器路径，
-  然后按固定格式填写 report，不需要每次重新发明报告结构。
-
-### Phase 2：日志守卫 MVP
-
-状态：已有第一版文件扫描。
-
-目标：捕获 UI 不一定明显展示的 runtime 问题。
-
-日志守卫应集成进 `lbs test report`，不要发展成独立后端 API 测试框架。
-
-建议命令形态：
-
-```bash
-bin/lbs test report <case-id> \
-  --backend-log /path/to/backend.log \
-  --frontend-log /path/to/frontend.log \
-  --console-log /path/to/console.log \
-  --evidence-dir reports/evidence/<run-id> \
-  --since "2026-05-21T10:30:00+08:00" \
-  --tail-lines 2000 \
-  --output reports/<timestamp>-<case-id>.md
-```
-
-MVP 行为：
-
-- 默认从 `LANGBOT_REPO/data/logs/` 扫描最新 `langbot-*.log`；
-- 支持 agent 显式提供 backend、frontend、console 日志文件；
-- 支持读取 evidence 目录下的 `automation-result.json`，把浏览器自动化脚本结论纳入报告；
-- 支持 `lbs test result` 为人工/agent browser 运行写入标准 `result.json`，供 suite 聚合；
-- 支持 `--since` 和 `--tail-lines`，避免历史日志污染本次报告；
-- 检测默认非预期模式，例如 `Traceback`、未 await coroutine、unclosed client/connector、
-  `KeyError`、`TypeError`、`AttributeError`、明显 secret 泄露；
-- 匹配 case 声明的 `success_patterns` 和 `failure_patterns`；
-- 匹配已知 troubleshooting，先支持 `plugin-runtime-timeout` 和 `proxy-env-mismatch`；
-- 只有 case 明确声明时，才允许 expected failure；
-- 将发现分类为 fail、warning、matched troubleshooting、ignored expected issue；
-- 永远不打印 secret 值。
-
-完成标准：
-
-- 至少 `pipeline-debug-chat` 能生成包含日志摘要和 troubleshooting 匹配结果的 report。
-
-### Phase 3：Case 元数据加固
-
-状态：已有第一版。
-
-目标：让 case 更容易选择、执行和晋级。
-
-字段逐步补充，保持向后兼容：
-
-```yaml
-priority: p0 | p1 | p2
-risk: low | medium | high
-ci_eligible: false
-preconditions:
-  - "Authenticated browser profile is available."
-setup:
-  - "Start LangBot backend and frontend."
-cleanup:
-  - "Remove temporary provider, plugin, or knowledge base if created."
-expected_failures: []
-success_patterns:
-  - "Conversation(0) Streaming completed"
-failure_patterns:
-  - "Action invoke_llm_stream call timed out"
-evidence:
-  required:
-    - ui
-    - console
-    - backend_log
-```
-
-当前实现采用扁平字段 `evidence_required`，避免轻量 YAML 解析器在 case 文件里承载嵌套结构。
-`bin/lbs validate` 会校验 `priority`、`risk`、`ci_eligible`、`evidence_required`、
-`automation` 脚本路径、case 关联 skill 和 troubleshooting 交叉引用。`bin/lbs case list`
-支持 `--json`、`--type`、`--area`、`--tag`、`--priority`、`--risk`、`--automation`、`--ci`
-、`--ready` 和 `--machine-ready` 过滤，方便 agent 快速选择测试集。
-`env_any` 和 `automation_env_any` 用于表达 URL-or-name 这类 one-of 输入，避免把可替代变量误判为全部必填。
-
-当前也有 `skills/<skill>/suites/*.yaml` 和 `bin/lbs suite plan <suite-id>`，用于组织常跑测试集，
-例如 `core-smoke`、`local-agent-gate` 和
-`agent-runner-release-gate`。发布门禁使用 `agent-runner-release-preflight`
-先分类配置 blockers 和 runtime env issues，再运行较重的浏览器 Debug Chat case。
-依赖 fixture 的 case 可以在浏览器执行前先跑 `bin/lbs fixture check`，检查
-`fixtures/fixtures.json` 登记的 deterministic 文件、plugin 包和本地测试 server 是否存在。
-`bin/lbs suite start <suite-id>` 会生成 suite run id、suite evidence root、per-case evidence 目录、
-`suite-start.json`/`suite-start.md` handoff 文件和 per-case evidence 命令；
-浏览器自动化脚本会写入 `automation-result.json`，供 `bin/lbs test report` 展示原始自动化结论；
-`bin/lbs test result <case-id>` 会在人工/agent browser case 完成后写入最终 `result.json`；
-`bin/lbs suite report <suite-id> --evidence-dir <dir>` 会聚合各 case 的 `result.json`，并且
-不会把缺少 required evidence 的 `pass` 当作 suite 通过。
-Runner 专用 Debug Chat case 通过 `automation_pipeline_url_env` 和
-`automation_pipeline_name_env` 绑定专用 pipeline 变量，避免 local-agent、Codex 或
-Claude Code case 误用通用 `LANGBOT_PIPELINE_URL` 后产生假阳性。
-Debug Chat case 还可以通过 `automation_stream_output` 固定流式或非流式发送路径。
-多模态 Debug Chat case 可以通过 `automation_image_base64_fixture` 复用 deterministic 图片 fixture。
-`test plan` 和 `suite plan` 会输出 readiness，让 agent 在执行浏览器前就看到缺失的 env、
-自动化变量、fixture，以及需要人工确认的 `manual_check` 前置条件。
-
-完成标准：
-
-- `lbs case list` 或后续 filter 能回答“smoke 跑哪些”、“哪些适合 CI”、
-  “哪些需要真实 provider credentials”。
-
-### Phase 4：开发者沉淀流程
-
-目标：开发者让 agent 测新 feature 后，稳定路径不会丢在聊天记录里。
-
-流程：
-
-1. 开发者要求 agent 通过浏览器测试某个 feature。
-2. agent 先按 UI 主路径探索。
-3. agent 用 `lbs test start` 固定运行窗口，再用 `lbs test report` 写报告。
-4. 如果路径稳定，agent 新增或更新 case。
-5. 如果出现可复用故障，agent 新增或更新 troubleshooting。
-6. agent 跑 `bin/lbs validate` 和 `bin/lbs index`。
-
-完成标准：
-
-- feature QA 的结果能进入资产库，而不是只留在一次对话里。
-
-### Phase 5：选择性浏览器自动化
-
-状态：已有第一版 `test run` 入口和两个 Playwright 脚本。
-
-目标：只自动化少量稳定、值得重复跑的黑盒路径。
-
-建议顺序：
-
-1. `webui-login-state`
-2. `pipeline-debug-chat`
-3. `local-agent-basic-debug-chat`
-4. `local-agent-rag-debug-chat`
-5. 一个基于 deterministic fixture 的 plugin 或 MCP smoke path
-
-执行策略：
-
-- 继续把 Computer Use 或 Playwright MCP 作为默认交互路径；
-- 只给稳定、确定性的路径补直接 Playwright script；
-- 保存 screenshots、console logs、trace/video；
-- flaky 或强依赖真实 credentials 的 provider case 暂时不要进 CI。
-
-当前已经绑定：
-
-- `webui-login-state` -> `scripts/e2e/webui-login-state.mjs`
-- `pipeline-debug-chat` -> `scripts/e2e/pipeline-debug-chat.mjs`
-
-第一版自动化先产出 `reports/evidence/<run-id>/` 下的 console、network、screenshot 和
-result JSON。真实执行后仍要用 `lbs test report --since ... --console-log ...` 做日志守卫和
-最终报告。开发期间可以先用 `bin/lbs test run <case-id> --dry-run` 检查命令和 evidence 路径。
-Debug Chat 类脚本应复用 `scripts/e2e/lib/debug-chat.mjs`，避免重复实现 visible response leaf
-判断和已知失败信号分类。
-
-完成标准：
-
-- 小规模 smoke subset 可以不靠人工决定每一步点击；更大的资产库仍然服务于人工/agent
-  驱动的探索式 E2E。
-
-## 下一批动工切片
-
-在做 browser runner 之前，继续做这些：
-
-1. 等 LangBot 当前开发状态稳定后，用一次真实 `pipeline-debug-chat` 跑通
-   `test start -> test run -> test report -> test result -> suite report`，产出 sample report。
-2. 只给 smoke/local-agent 首批 case 补必要元数据。
-3. 继续补日志守卫规则，尤其是 WebSocket、plugin runtime、provider streaming、前端
-   chunk/rendering failure。
-4. 约定 report 产物目录、截图和 console/network 导出的命名方式。
-5. 再评估是否开始给 `webui-login-state` 和 `pipeline-debug-chat` 做直接 Playwright
-   自动化。
-
-这样 infra 会立刻有用，同时保留后续自动化 browser execution 的空间。

skills/qa-agent-docs/qa-agent/README.md

@@ -1,46 +0,0 @@
-# LangBot QA Agent 文档导航
-
-这个目录记录 `langbot-skills` 当前的 QA 方向和后续建设顺序。
-
-## 当前判断
-
-当前重点是 LangBot 的黑盒 E2E QA，不是 LangBot core 的单测覆盖率建设。
-
-`langbot-skills` 要帮助开发者和 QA agent 做接近人工测试的 WebUI 验证：
-
-- 打开真实 LangBot WebUI；
-- 按用户路径点击和输入；
-- 检查用户可见的 UI 结果；
-- 查看 console、network、截图、后端和前端日志；
-- 输出可复用的测试报告；
-- 把稳定 feature 路径沉淀为 case；
-- 把重复故障沉淀为 troubleshooting。
-
-API 和 curl 只做诊断。它们可以解释失败原因，但不能让一个 UI case 通过。
-
-## 文档状态
-
-| 文档 | 状态 | 用途 |
-| --- | --- | --- |
-| `04-black-box-e2e-roadmap.md` | 当前主路线图 | 决定下一步建设什么。 |
-| `03-agent-browser-qa-principles.md` | 当前原则文档 | 定义 browser-first QA 的通过标准。 |
-| `02-log-guard-plan.md` | 当前活跃设计 | 设计 `lbs test report` 里的日志守卫。 |
-| `../user-guide.md` | 当前使用手册 | 开发者日常使用。 |
-| `00-technology-options.md` | 背景文档 | 选择 Computer Use、Playwright MCP 或未来直接 Playwright。 |
-| `01-qa-agent-harness-plan.md` | 历史规划，部分过时 | 解释最初分层和目录设计；使用前先看状态说明。 |
-
-## 已过时的点
-
-`01-qa-agent-harness-plan.md` 还保留早期规划状态。现在结构化 cases、
-结构化 troubleshooting、`validate`、`index`、`lbs test plan` 都已经落地。
-
-已经补上第一版 `lbs test start`、`lbs test run`、`lbs test report` 和日志守卫文件扫描。
-`webui-login-state`、`pipeline-debug-chat` 已经绑定直接 Playwright 自动化脚本。后续重点是：
-
-- 报告 evidence 字段继续打磨；
-- case success/failure signal 和日志守卫规则继续补充；
-- 报告产物和 evidence 约定；
-- 等 LangBot 当前开发状态稳定后跑真实 sample report。
-
-不要再把旧阶段列表当成当前 source of truth。后续排序以
-`04-black-box-e2e-roadmap.md` 为准。

skills/qa-agent-docs/user-guide.md

@@ -1,521 +0,0 @@
-# LangBot Skills 用户使用手册
-
-## 这个仓库解决什么
-
-`langbot-skills` 是给 agent 使用的 LangBot 测试资产库。开发者 clone 后，可以让 Codex、Claude Code、Computer Use 或 Playwright MCP 复用已有环境配置、测试路径和故障知识，像 QA 一样操作 LangBot WebUI。
-
-核心目标：
-
-- 不让下一个 agent 窗口从头探索登录、模型配置、pipeline 调试。
-- 把稳定 UI 测试路径沉淀为 case。
-- 把常见故障沉淀为 troubleshooting。
-- 让 agent 优先通过浏览器点击验证产品行为。
-- API/curl/log 只作为诊断手段，不作为 UI case 通过标准。
-
-## 快速开始
-
-1. Clone 仓库。
-
-2. 检查本地默认变量：
-
-```bash
-bin/lbs env show
-```
-
-默认变量在：
-
-```text
-skills/.env
-```
-
-本机专用覆盖写到：
-
-```text
-skills/.env.local
-```
-
-它会覆盖 `skills/.env` 中的同名变量，并且不应该提交。
-`skills/.env` 是共享默认值，不应写入本机绝对路径、浏览器 profile、provider key 或其他凭据。
-新机器建议从模板开始：
-
-```bash
-cp skills/.env.example skills/.env.local
-```
-
-常用变量：
-
-```text
-LANGBOT_FRONTEND_URL
-LANGBOT_BACKEND_URL
-LANGBOT_DEV_FRONTEND_URL
-LANGBOT_REPO
-LANGBOT_WEB_REPO
-LANGBOT_BROWSER_PROFILE
-```
-
-3. 检查环境是否就绪：
-
-```bash
-bin/lbs env doctor
-bin/lbs fixture check
-```
-
-`env doctor` 会检查 URL、路径、代理变量等。代理变量是可选项；只有大小写代理变量互相冲突时才会报错。失败不一定代表仓库坏了，通常说明本地 LangBot 没启动、代理不一致或浏览器 profile 不存在。
-`fixture check` 会检查仓库内测试 fixture 是否存在，例如 MCP stdio server、RAG 文档、多模态图片、qa-plugin-smoke 包和 QA AgentRunner 包。它也会校验 `.lbpkg` 是 zip 包，并检查 QA AgentRunner fixture 的入口文件未漂移。
-
-4. 查看已有测试 case：
-
-```bash
-bin/lbs case list
-bin/lbs case list --json --priority p0 --automation
-bin/lbs case list --ready
-bin/lbs case list --machine-ready
-bin/lbs suite list
-bin/lbs suite plan core-smoke
-bin/lbs suite plan agent-runner-release-gate
-bin/lbs suite start core-smoke
-bin/lbs suite start core-smoke --run-id core-smoke-local --evidence-dir reports/evidence/core-smoke-local
-```
-
-`case list` 支持按 `--type`、`--area`、`--tag`、`--priority`、`--risk`、`--automation`
-、`--ci`、`--ready` 和 `--machine-ready` 过滤。`--ready` 只显示没有缺机器输入且没有人工前置条件的 case；
-`--machine-ready` 过滤掉缺机器输入的 case，但保留 `manual-check`，表示执行前还要确认前置条件。需要交给 agent 自动选择测试集时，优先使用 `--json`，
-其中包含 `priority`、`risk`、`ci_eligible`、`automation`、`evidence_required` 以及
-env/automation/fixture/manual readiness。
-Case metadata 中的 `env` 和 `automation_env` 表示全部必填；URL 或 name 这类二选一输入会放在
-`env_any` 或 `automation_env_any`，readiness 只要求组合里至少一个变量有值。
-
-如果要跑一组已沉淀的测试路径，优先使用 suite。Suite 位于 `skills/<skill>/suites/*.yaml`，
-只负责组织 case，不改变 UI/browser 作为通过标准的原则。
-`suite plan` 会聚合 readiness：缺环境变量、缺自动化变量、缺 fixture 或需要
-`manual_check` 时，会在执行前标出受影响的 case。`manual_check` 不是产品通过，
-它表示机器配置已满足但 agent 必须先确认 case 里的 `preconditions` 或 `setup`。
-Runner externalization 发布判断使用 `agent-runner-release-gate`。先跑
-`agent-runner-release-preflight`，把缺 pipeline、runner id 错误、插件未安装这类
-`blocked`，以及 provider key、Box、插件运行时这类 `env_issue` 分开，再执行较重的
-浏览器 Debug Chat case。
-
-5. 生成 agent 执行计划：
-
-```bash
-bin/lbs test plan pipeline-debug-chat
-```
-
-然后把计划交给当前 agent 执行。agent 应使用 Computer Use、Playwright MCP 或其他浏览器控制能力去操作 UI。
-`test plan` 中的 Environment、Automation Readiness、Fixture Readiness 和 Manual
-Readiness 是执行前门禁；如果 readiness 缺失，应先补配置或将本次 case 标记为
-`blocked`。如果状态是 `manual_check`，先确认 `preconditions` 和 `setup`，再开始 UI
-执行。不要把后续 curl/API 诊断当成 UI case 通过。
-
-## 推荐使用方式
-
-### 冒烟测试
-
-你可以直接对 agent 说：
-
-```text
-帮我跑一下 LangBot 新前端 smoke test。
-```
-
-agent 应该：
-
-- 读 `skills/.env`
-- 优先查看 `bin/lbs suite plan core-smoke`，或查找 `type: smoke` 的 cases
-- 生成 test plan
-- 用浏览器执行 UI 操作
-- 检查 console、截图、后端日志
-- 输出简短 QA 报告
-
-### Runner Externalization 发布门禁
-
-你可以直接对 agent 说：
-
-```text
-按 agent-runner release gate 跑完整矩阵，先做 preflight，再跑浏览器 case，并把 blocked/env_issue/fail 分开。
-```
-
-agent 应该先查看 `skills/langbot-testing/references/agent-runner-release-gate.md`，
-再执行：
-
-```bash
-bin/lbs test recommend
-bin/lbs suite plan agent-runner-release-gate
-bin/lbs test run agent-runner-release-preflight --dry-run
-bin/lbs suite start agent-runner-release-gate --run-id agent-runner-release-local --evidence-dir reports/evidence/agent-runner-release-local
-```
-
-`test recommend` 输出的 run 命令默认带 `--dry-run`；确认 readiness 和 `manual_check` 前置条件后，再去掉 `--dry-run` 执行。
-
-完成所有 case 后，用：
-
-```bash
-bin/lbs suite report agent-runner-release-gate --evidence-dir reports/evidence/agent-runner-release-local
-```
-
-没有最终 `result.json`、缺 required evidence、或把 `blocked`/`env_issue` 当成 pass，
-都不能算发布门禁通过。
-
-### 新 Feature 测试
-
-你可以说：
-
-```text
-我改了 provider 页面，帮我测一下 DeepSeek provider 添加、测试、绑定 pipeline 是否正常。
-```
-
-agent 应该：
-
-- 查找相关 case 和 reference
-- 如果没有稳定路径，先探索 UI
-- 用浏览器执行真实交互
-- 失败时用日志/API 辅助定位
-- 稳定后新增或更新 case/reference
-- 新故障沉淀为 troubleshooting
-
-### 定点排错
-
-你可以说：
-
-```text
-Debug Chat 点了没回复，帮我查是前端问题还是后端问题。
-```
-
-agent 应该：
-
-- 先通过 UI 复现
-- 看 console/network
-- 看后端日志
-- 必要时用 API/curl 做诊断
-- 匹配 troubleshooting
-- 给出修复建议或直接修复
-
-## 重要原则
-
-这些原则固定在：
-
-```text
-docs/qa-agent/03-agent-browser-qa-principles.md
-```
-
-简化版：
-
-- UI/browser 是测试主路径。
-- API/curl/log 只做诊断。
-- 后端接口成功不等于 UI case 通过。
-- case 通过必须以用户可见 UI 结果为准。
-- 有视觉能力时应检查截图。
-- 没有视觉能力时用 DOM/accessibility snapshot 和 console。
-- 不要打印 token、API key、OAuth secret 或 localStorage token 值。
-
-## 规划文档
-
-如果要判断下一步建设什么，先看：
-
-```text
-docs/qa-agent/README.md
-docs/qa-agent/04-black-box-e2e-roadmap.md
-```
-
-`01-qa-agent-harness-plan.md` 是早期规划，部分内容已经被当前实现和路线图替代。
-
-## 常用命令
-
-### 环境
-
-```bash
-bin/lbs env show
-bin/lbs env show --json
-bin/lbs env doctor
-bin/lbs fixture list
-bin/lbs fixture check
-bin/lbs fixture check --json
-```
-
-`env show` 和 `env doctor` 默认会对 token、API key、password、secret 以及 URL basic auth
-做脱敏。不要把 `.env.local` 里的原始凭据复制进测试报告。
-
-### Skill 和索引
-
-```bash
-bin/lbs list
-bin/lbs validate
-bin/lbs index --check
-bin/lbs index
-```
-
-### Case
-
-```bash
-bin/lbs case list
-bin/lbs case list --type smoke
-bin/lbs case list --json --priority p1 --tag local-agent
-bin/lbs case list --ready
-bin/lbs case list --machine-ready
-bin/lbs case show pipeline-debug-chat
-bin/lbs case new my-feature --title "My Feature Works"
-```
-
-### Suite
-
-```bash
-bin/lbs suite list
-bin/lbs suite list --json --priority p1
-bin/lbs suite show local-agent-gate
-bin/lbs suite plan core-smoke
-bin/lbs suite plan local-agent-gate --json
-bin/lbs suite start core-smoke
-bin/lbs suite start core-smoke --run-id core-smoke-local --evidence-dir reports/evidence/core-smoke-local
-bin/lbs suite run core-smoke --dry-run --json
-bin/lbs suite run core-smoke --run-id core-smoke-local --evidence-dir reports/evidence/core-smoke-local
-bin/lbs suite start core-smoke --json
-bin/lbs suite report core-smoke --evidence-dir reports/evidence/<suite-run-id>
-bin/lbs suite report core-smoke --evidence-dir reports/evidence/<suite-run-id> --json
-bin/lbs suite new my-feature-gate --title "My Feature Gate"
-```
-
-`suite start` 不直接控制浏览器。它生成统一 run id、suite evidence root、每个 case 的 evidence
-目录、`suite-start.json`/`suite-start.md` handoff 文件，以及每个 case 的 `test run`、`test report`
-和 `test result` 命令模板。需要固定路径时，使用 `--run-id` 和 `--evidence-dir`。
-`suite run --dry-run --json` 只预览 planned/skipped case，不创建 evidence，也不执行 automation。
-`suite run` 会顺序执行 suite 中已有 automation、机器 readiness 已满足且不需要 `manual_check` 的 case，并在最后聚合 `suite report`。
-缺 env、automation env 或 fixture 的 case 默认会跳过；确实要强制执行时，加 `--include-not-ready`。
-确认前置条件后，才用 `--include-manual-check` 执行这类 case。
-所有 case 执行完并写入最终 `result.json` 后，
-`suite report` 会读取各 case evidence 目录并汇总为 `pass`、`fail`、`blocked`、`env_issue`、
-`flaky`、`incomplete` 等状态。`pass` 必须声明已经收集 case 的全部 required evidence；
-否则 suite 会保持 `incomplete`，避免把缺证据的运行误判成通过。
-
-### Test Plan
-
-```bash
-bin/lbs test plan pipeline-debug-chat
-bin/lbs test plan pipeline-debug-chat --json
-```
-
-### Test Start
-
-```bash
-bin/lbs test start pipeline-debug-chat
-bin/lbs test start pipeline-debug-chat --json
-```
-
-`test start` 用于 agent 开始一次浏览器测试前记录 run id、开始时间和推荐 report 命令。
-它会把 `--since "<started_at_local>"` 写进后续报告命令，减少历史日志污染本次判断。
-如果 case 绑定了自动化脚本，输出里也会包含 `test run` 命令和 evidence 目录。
-
-### Test Automation
-
-```bash
-bin/lbs test run webui-login-state --dry-run
-bin/lbs test run pipeline-debug-chat --dry-run
-bin/lbs test run webui-login-state --run-id login-smoke --output reports/evidence/login-smoke
-bin/lbs test run pipeline-debug-chat --run-id pipeline-smoke --output reports/evidence/pipeline-smoke
-```
-
-查看当前所有带自动化脚本的 case：
-
-```bash
-bin/lbs case list --automation
-bin/lbs case list --json --automation
-```
-
-当前自动化覆盖包括登录态、通用 Pipeline Debug Chat、local-agent runner 的基础回复、
-PromptPreProcessing、RAG、plugin tool、MCP stdio tool、非流式、多模态和 RAG+多模态路径。
-不要在文档里手工维护静态 case 清单；以 `case list --automation` 和 suite 定义为准。
-
-自动化脚本位于 `scripts/e2e/`。它们会保存：
-
-- `console.log`
-- `network.log`
-- `screenshot.png`
-- `automation-result.json`
-
-新增 Debug Chat 类自动化时，优先复用 `scripts/e2e/lib/debug-chat.mjs` 中的 pipeline 打开、
-prompt 发送、visible response leaf 判断和失败信号分类，不要在新脚本里复制 DOM 扫描逻辑。
-
-脚本需要本地安装 Playwright 后才能真正执行：
-
-```bash
-npm install
-npx playwright install chromium
-```
-
-`pipeline-debug-chat` 通用自动化建议配置 `LANGBOT_PIPELINE_URL`。如果没有 direct URL，
-脚本会尝试通过 `LANGBOT_PIPELINE_NAME` 从 Pipelines 页面进入目标 pipeline。两者都没有时，
-该自动化会返回 `blocked`，不会伪造通过。
-
-Runner 专用 case 不应复用通用 pipeline 变量。Local Agent、Codex AgentRunner 和
-Claude Code AgentRunner 这类 case 会通过 `automation_pipeline_url_env` /
-`automation_pipeline_name_env` 映射到 case-specific env，例如
-`LANGBOT_LOCAL_AGENT_PIPELINE_URL`。这些 case 如果缺少专用变量，会返回 `blocked`，
-不会退回到 `LANGBOT_PIPELINE_URL`，避免跑错 pipeline 后产生假阳性。
-如果 case 声明了 `setup_automation`，只有 `bin/lbs test run <case-id>` 的真实执行路径会先运行这些 setup；
-`test plan`、`suite plan`、`case list` 和 `--dry-run` 只展示它们，不会修改本地环境。
-setup 可以是 `case:<case-id>` 或仓库内 `node:scripts/... --flag`，每一步证据会写到主 evidence 目录下的
-`setup/` 子目录。setup 失败时主 automation 不会继续执行；setup 写入 `.env.local` 后，主 automation
-会重新读取环境。用 `setup_provides_env` 声明 setup 会生成的变量，可以让 readiness 正确显示机器可准备状态。
-如果 Debug Chat case 需要固定流式/非流式路径，可以在 case 中设置
-`automation_stream_output: "1"` 或 `"0"`，脚本会在发送消息前切换 Debug Chat 的 Stream 控件。
-如果 case 需要上传图片，可以设置 `automation_image_base64_fixture` 指向仓库内的 base64 PNG fixture，
-脚本会在 evidence 目录写出临时 PNG 并通过 Debug Chat 上传控件发送。
-`bin/lbs test plan <case-id> --json` 和 `bin/lbs suite plan <suite-id> --json`
-都会显示这些专用变量是否已配置。
-
-### Test Report 和日志守卫
-
-```bash
-bin/lbs test report pipeline-debug-chat
-bin/lbs test report pipeline-debug-chat --output reports/pipeline-debug-chat.md
-bin/lbs test report pipeline-debug-chat \
-  --backend-log /path/to/backend.log \
-  --frontend-log /path/to/frontend.log \
-  --console-log /path/to/console.log
-bin/lbs test report pipeline-debug-chat --evidence-dir reports/evidence/pipeline-smoke
-bin/lbs test report pipeline-debug-chat --backend-log /path/to/backend.log --json
-bin/lbs test report pipeline-debug-chat --since "2026-05-21T10:30:00+08:00"
-bin/lbs test report pipeline-debug-chat --tail-lines 2000
-bin/lbs test report pipeline-debug-chat --since "2026-05-21T10:30:00+08:00" --tail-lines 2000
-```
-
-`test report` 会生成报告模板，并默认从 `LANGBOT_REPO/data/logs/` 自动选择最新的
-`langbot-*.log` 作为 LangBot 后端日志扫描。也可以用 `--backend-log` 覆盖，或用
-`--no-auto-log` 只生成模板。
-
-如果提供 `--evidence-dir`，或 `--console-log` 指向 `reports/evidence/<run-id>/console.log`，
-报告会优先读取同目录的 `automation-result.json`，并展示自动化脚本的 `status`、`reason`、
-起止时间和目标 URL。
-
-日志守卫会扫描常见错误、secret 泄露风险、case 声明的 success/failure patterns，以及已知
-troubleshooting pattern。它不控制浏览器，也不替代 UI 通过判断。`success_patterns`
-命中会作为通过证据写入 `success_signals`；声明了 success pattern 但本次扫描窗口没有命中，
-会给 warning；`failure_patterns` 命中会让本次日志守卫 fail。
-
-建议在执行浏览器 case 前记录当前时间，然后在报告阶段使用 `--since`。如果只想快速看
-最近日志，可以使用 `--tail-lines`。
-
-### Runtime Log Guard
-
-如果还没有进入某个具体 UI case，只是想观察 LangBot 后端日志，可以直接使用 `log`
-命令。它和 `test report` 使用同一套扫描器、secret 脱敏、troubleshooting pattern 和
-case success/failure pattern。
-
-```bash
-bin/lbs log scan --tail-lines 300
-bin/lbs log scan --case pipeline-debug-chat --since "2026-05-21T10:30:00+08:00"
-bin/lbs log scan --backend-log /path/to/langbot.log --json
-bin/lbs log scan --failure-pattern "runner.tool_loop_error|Action invoke_llm_stream call timed out" --strict
-```
-
-`log scan` 默认从 `LANGBOT_REPO/data/logs/` 自动选择最新的 `langbot-*.log`。传入
-`--case <case-id>` 后，会额外应用该 case 声明的 `success_patterns`、`failure_patterns`
-和 related troubleshooting。默认用于观察，返回码保持 0；加 `--strict` 后，`fail` 或
-`env_issue` 会返回非 0，适合脚本门禁。
-
-运行期观察可以用 `watch`：
-
-```bash
-bin/lbs log watch --case pipeline-debug-chat
-bin/lbs log watch --backend-log /path/to/langbot.log --interval-ms 500
-bin/lbs log watch --duration-ms 30000 --strict --json
-```
-
-`log watch` 默认从启动时的文件末尾开始，只观察新追加的日志；加 `--from-start` 可从文件开头扫。
-它会实时打印新命中的 findings 和 success signals。为了避免当前历史日志噪声影响观察，默认不因
-异常返回非 0；加 `--strict` 后，退出时如果看到 `fail` 或 `env_issue` 会返回非 0。
-
-给一次 QA 运行包日志窗口时，用 `guard start/stop`：
-
-```bash
-bin/lbs log guard start --run-id local-debug --case pipeline-debug-chat
-# 执行浏览器或手工测试
-bin/lbs log guard stop --run-id local-debug
-```
-
-`start` 会在 `reports/log-guards/<run-id>.json` 记录起始时间、case 和当前后端日志路径；
-`stop` 会用 start/stop 时间作为扫描窗口，生成 `reports/log-guards/<run-id>.md`，并默认按
-strict guard 返回码处理。临时只想收集报告、不想让命令失败，可以加 `--no-strict`。
-
-当前 LangBot core 日志还不是完全结构化日志，runtime guard 主要依赖时间窗口和文本 pattern。
-已支持 ISO 时间戳和 LangBot 当前的 `[MM-DD HH:mm:ss.SSS]` 前缀；没有时间戳的连续行会跟随上一条
-带时间戳的日志块。如果后续 core 能提供稳定 request id、conversation id、plugin action id 或
-JSON log field，guard 可以从“时间窗口 + 文本匹配”升级为更精确的关联分析。
-
-### Test Result
-
-```bash
-bin/lbs test result pipeline-debug-chat \
-  --result pass \
-  --reason "Debug Chat returned OK and the report log guard was clean." \
-  --evidence-dir reports/evidence/pipeline-smoke \
-  --started-at "2026-05-21T10:30:00+08:00" \
-  --evidence ui,screenshot,console,backend_log
-```
-
-`test result` 用于把一次人工/agent browser 运行的最终判断写成标准 `result.json`，
-供 `suite report` 聚合。它不会替代 UI 测试：如果写 `--result pass`，`--evidence`
-必须覆盖该 case 的 `evidence_required`，否则命令会失败。自动化脚本写
-`automation-result.json`；如果 case 还要求 backend log、API diagnostic 或 filesystem
-evidence，agent 需要在报告和诊断完成后再用 `test result` 写最终 `result.json`。
-
-### Troubleshooting
-
-```bash
-bin/lbs trouble list langbot-testing
-bin/lbs trouble show plugin-runtime-timeout
-bin/lbs trouble search runtime
-bin/lbs trouble add langbot-testing --title "..." --symptom "..." --cause "..." --fix "..."
-```
-
-## 目录说明
-
-```text
-skills/
-  .env                         # 共享默认变量
-  langbot-env-setup/           # 环境、浏览器、登录态、代理
-  langbot-testing/             # WebUI / provider / pipeline 测试
-schemas/                       # 结构化资产 schema
-src/                           # lbs TypeScript 源码
-bin/                           # lbs 入口
-docs/                          # 设计文档和用户手册
-AGENTS.md                      # agent 维护协议
-```
-
-## 添加一个新测试路径
-
-1. 先让 agent 通过浏览器探索并执行路径。
-2. 稳定后创建 case：
-
-```bash
-bin/lbs case new provider-xxx --title "Provider XXX can be configured" --area provider --type provider
-```
-
-3. 编辑生成的 `cases/*.yaml`，补充真实步骤、检查点和 troubleshooting。
-
-4. 校验：
-
-```bash
-bin/lbs validate
-bin/lbs index --check
-bin/lbs index
-```
-
-## 添加一个新故障
-
-```bash
-bin/lbs trouble add langbot-testing \
-  --title "Plugin runtime actions time out" \
-  --symptom "Debug Chat shows Agent runner temporarily unavailable" \
-  --cause "Old plugin runtime survived backend restart" \
-  --fix "Stop old runtime processes and restart LangBot"
-```
-
-然后编辑生成的 YAML，补充 `patterns`、`related_cases` 和验证方式。
-
-## 当前边界
-
-- `lbs test plan` 只生成测试计划，不直接控制浏览器。
-- `lbs test report` 生成报告，默认扫描最新 LangBot 后端日志；也可扫描显式提供的
-  backend/frontend/console 日志文件。
-- 真正的 UI 操作由当前 agent 的浏览器能力执行。
-- `env doctor` 是 readiness check，不是产品测试。
-- `curl/API` 是诊断工具，不是主要测试路径。

skills/schemas/README.md

@@ -1,59 +0,0 @@
-# Schemas
-
-这个目录存放 LangBot skills 结构化资产的 JSON Schema。
-
-它们不是测试脚本，也不会执行浏览器动作。它们的作用是定义 agent 和维护者后续新增资产时应该遵守的文件结构。
-
-## 文件说明
-
-- `skills/<skill>/fixtures/fixtures.json`
-  不是 JSON Schema，但由 `bin/lbs validate` 校验。
-  它登记 deterministic fixture 文件、类型和关联 case，供 `bin/lbs fixture check` 做 readiness 检查。
-
-- `case.schema.json`
-  约束 `skills/<skill>/cases/*.yaml` 的格式。
-  Case 描述 agent-browser 或 probe QA 路径，包括前置条件、步骤、检查点、诊断手段和关联故障。
-
-- `suite.schema.json`
-  约束 `skills/<skill>/suites/*.yaml` 的格式。
-  Suite 只组织 case 集合，用于 smoke、regression 或 release gate 等测试入口。
-
-- `troubleshooting.schema.json`
-  约束 `skills/<skill>/troubleshooting/*.yaml` 的格式。
-  Troubleshooting 条目描述症状、日志/错误模式、可能原因、修复步骤和验证信号。
-
-- `skill-index.schema.json`
-  约束生成文件 `skills.index.json` 的格式。
-  这个索引用于让 agent 快速发现已有 skills、references、cases、suites 和 troubleshooting。
-
-- `reports/evidence/<run-id>/result.json`
-  不是 catalog schema，而是执行期最终裁定产物，由 `bin/lbs test result` 写入。
-  `suite report` 读取其中的 `status`、`reason`、起止时间和 `evidence_collected`，
-  并用 `evidence_missing` 防止缺证据的 `pass` 被当作完整通过。
-
-- `reports/evidence/<run-id>/automation-result.json`
-  不是 catalog schema，而是浏览器自动化脚本的原始运行结论，供 `bin/lbs test report`
-  展示和推断日志扫描窗口。
-
-## 为什么需要 schemas
-
-Schemas 是基础设施护栏：
-
-- 防止 case、suite 和 troubleshooting 随着增长变得格式混乱
-- 让 `bin/lbs validate` 能发现缺字段和错误结构
-- 为未来编辑器提示和 CI 校验留接口
-- 帮助 agent 新增资产时知道应该写哪些字段
-
-## 当前校验方式
-
-`bin/lbs validate` 做轻量、schema 对齐的校验，不引入额外依赖。它会检查必填字段、
-枚举值、boolean 字段、重复列表项、automation 脚本存在性，以及 case、suite、skill、
-troubleshooting 之间的交叉引用。这里的 schema 仍是格式契约；如果未来引入正式 JSON
-Schema validator，应继续保持这些本地交叉引用检查。
-
-Case 里的 `env` / `automation_env` 表示所有列出的变量都需要配置。遇到二选一输入时，
-使用 `env_any` / `automation_env_any`，每一项写成 `LANGBOT_PIPELINE_URL|LANGBOT_PIPELINE_NAME`
-这类 one-of 组合，避免 agent 因为只配置了 URL 或 name 其中之一而误判未就绪。
-`setup` 和 `preconditions` 是人工确认项，会让 readiness 进入 `manual_check`；
-`setup_automation` 是 `test run` 可以自动执行的准备步骤，配合 `setup_provides_env`
-声明它会生成的机器变量。

skills/schemas/case.schema.json

@@ -1,219 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://langbot.app/schemas/langbot-skills/case.schema.json",
-  "title": "LangBot Skill Test Case",
-  "type": "object",
-  "required": [
-    "id",
-    "title",
-    "mode",
-    "area",
-    "type",
-    "priority",
-    "risk",
-    "ci_eligible",
-    "tags",
-    "skills",
-    "steps",
-    "checks",
-    "evidence_required"
-  ],
-  "allOf": [
-    {
-      "if": {
-        "properties": {
-          "mode": { "const": "agent-browser" }
-        }
-      },
-      "then": {
-        "required": ["env"]
-      }
-    }
-  ],
-  "additionalProperties": true,
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9_-]*$"
-    },
-    "title": {
-      "type": "string"
-    },
-    "mode": {
-      "type": "string",
-      "enum": ["agent-browser", "probe"]
-    },
-    "area": {
-      "type": "string"
-    },
-    "type": {
-      "type": "string",
-      "enum": ["smoke", "regression", "feature", "provider", "exploratory"]
-    },
-    "priority": {
-      "type": "string",
-      "enum": ["p0", "p1", "p2"]
-    },
-    "risk": {
-      "type": "string",
-      "enum": ["low", "medium", "high"]
-    },
-    "ci_eligible": {
-      "type": "boolean"
-    },
-    "tags": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "skills": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "env": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "env_any": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^[A-Z][A-Z0-9_]*(\\|[A-Z][A-Z0-9_]*)+$"
-      }
-    },
-    "steps": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "checks": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "evidence_required": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": [
-          "ui",
-          "screenshot",
-          "console",
-          "network",
-          "backend_log",
-          "frontend_log",
-          "api_diagnostic",
-          "filesystem"
-        ]
-      },
-      "minItems": 1
-    },
-    "preconditions": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "setup": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "setup_automation": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^(?:case:[a-z0-9][a-z0-9_-]*|node:scripts/[A-Za-z0-9_./-]+\\.(?:mjs|js|ts)(?:\\s+--[A-Za-z0-9][A-Za-z0-9_-]*(?:=[A-Za-z0-9_./:@-]+)?)*)$"
-      }
-    },
-    "setup_provides_env": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^[A-Z][A-Z0-9_]*$"
-      }
-    },
-    "cleanup": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "diagnostics": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "automation": {
-      "type": "string"
-    },
-    "automation_env": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "automation_env_any": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^[A-Z][A-Z0-9_]*(\\|[A-Z][A-Z0-9_]*)+$"
-      }
-    },
-    "automation_prompt": {
-      "type": "string"
-    },
-    "automation_prompts_json": {
-      "type": "string"
-    },
-    "automation_expected_text": {
-      "type": "string"
-    },
-    "automation_response_timeout_ms": {
-      "type": "string"
-    },
-    "automation_stream_output": {
-      "type": "string",
-      "enum": ["0", "1", "false", "true"]
-    },
-    "automation_image_base64_fixture": {
-      "type": "string"
-    },
-    "automation_runner_config_patch_json": {
-      "type": "string"
-    },
-    "automation_restore_runner_config": {
-      "type": "string",
-      "enum": ["0", "1", "false", "true"]
-    },
-    "automation_expected_runner_id": {
-      "type": "string"
-    },
-    "automation_reset_debug_chat": {
-      "type": "string",
-      "enum": ["0", "1", "false", "true"]
-    },
-    "automation_debug_chat_session_type": {
-      "type": "string",
-      "enum": ["person", "group"]
-    },
-    "automation_filesystem_checks_json": {
-      "type": "string"
-    },
-    "automation_pipeline_url_env": {
-      "type": "string",
-      "pattern": "^[A-Z][A-Z0-9_]*$"
-    },
-    "automation_pipeline_name_env": {
-      "type": "string",
-      "pattern": "^[A-Z][A-Z0-9_]*$"
-    },
-    "success_patterns": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "failure_patterns": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "expected_failures": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "troubleshooting": {
-      "type": "array",
-      "items": { "type": "string" }
-    }
-  }
-}

skills/schemas/skill-index.schema.json

@@ -1,147 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://langbot.app/schemas/langbot-skills/skill-index.schema.json",
-  "title": "LangBot Skills Index",
-  "type": "object",
-  "required": ["generated_by", "skills"],
-  "additionalProperties": false,
-  "properties": {
-    "generated_by": {
-      "type": "string"
-    },
-    "skills": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": [
-          "directory",
-          "name",
-          "description",
-          "references",
-          "cases",
-          "case_summaries",
-          "suites",
-          "suite_summaries",
-          "fixtures",
-          "troubleshooting",
-          "troubleshooting_summaries"
-        ],
-        "additionalProperties": false,
-        "properties": {
-          "directory": { "type": "string" },
-          "name": { "type": "string" },
-          "description": { "type": "string" },
-          "references": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "cases": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "case_summaries": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": ["id", "title", "mode", "area", "type", "priority", "risk", "ci_eligible", "tags", "automation", "setup_automation", "setup_provides_env", "evidence_required"],
-              "additionalProperties": false,
-              "properties": {
-                "id": { "type": "string" },
-                "title": { "type": "string" },
-                "mode": { "type": "string", "enum": ["agent-browser", "probe"] },
-                "area": { "type": "string" },
-                "type": { "type": "string" },
-                "priority": { "type": "string" },
-                "risk": { "type": "string" },
-                "ci_eligible": { "type": "boolean" },
-                "tags": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                },
-                "automation": { "type": "string" },
-                "setup_automation": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                },
-                "setup_provides_env": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                },
-                "evidence_required": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                }
-              }
-            }
-          },
-          "suites": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "suite_summaries": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": ["id", "title", "description", "type", "priority", "tags", "cases"],
-              "additionalProperties": false,
-              "properties": {
-                "id": { "type": "string" },
-                "title": { "type": "string" },
-                "description": { "type": "string" },
-                "type": { "type": "string" },
-                "priority": { "type": "string" },
-                "tags": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                },
-                "cases": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                }
-              }
-            }
-          },
-          "fixtures": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": ["id", "title", "kind", "path", "related_cases"],
-              "additionalProperties": false,
-              "properties": {
-                "id": { "type": "string" },
-                "title": { "type": "string" },
-                "kind": { "type": "string" },
-                "path": { "type": "string" },
-                "related_cases": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                }
-              }
-            }
-          },
-          "troubleshooting": {
-            "type": "array",
-            "items": { "type": "string" }
-          },
-          "troubleshooting_summaries": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": ["id", "title", "category", "related_cases"],
-              "additionalProperties": false,
-              "properties": {
-                "id": { "type": "string" },
-                "title": { "type": "string" },
-                "category": { "type": "string" },
-                "related_cases": {
-                  "type": "array",
-                  "items": { "type": "string" }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

skills/schemas/suite.schema.json

@@ -1,38 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://langbot.app/schemas/langbot-skills/suite.schema.json",
-  "title": "LangBot Skill Test Suite",
-  "type": "object",
-  "required": ["id", "title", "description", "type", "priority", "tags", "cases"],
-  "additionalProperties": true,
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9_-]*$"
-    },
-    "title": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
-    },
-    "type": {
-      "type": "string",
-      "enum": ["smoke", "regression", "release_gate", "exploratory"]
-    },
-    "priority": {
-      "type": "string",
-      "enum": ["p0", "p1", "p2"]
-    },
-    "tags": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "cases": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    }
-  }
-}

skills/schemas/troubleshooting.schema.json

@@ -1,51 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://langbot.app/schemas/langbot-skills/troubleshooting.schema.json",
-  "title": "LangBot Skill Troubleshooting Entry",
-  "type": "object",
-  "required": ["id", "title", "symptoms", "patterns", "likely_causes", "fix_steps", "verification"],
-  "additionalProperties": true,
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9_-]*$"
-    },
-    "title": {
-      "type": "string"
-    },
-    "date": {
-      "type": "string"
-    },
-    "category": {
-      "type": "string",
-      "enum": ["product", "env_issue", "external_dependency", "blocked", "flaky"]
-    },
-    "symptoms": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "patterns": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "likely_causes": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "fix_steps": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1
-    },
-    "verification": {
-      "type": "string"
-    },
-    "related_cases": {
-      "type": "array",
-      "items": { "type": "string" }
-    }
-  }
-}

skills/scripts/bootstrap-lbs.mjs

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const binDir = resolve(root, "bin");
-const lbsPath = resolve(binDir, "lbs");
-const wrapper = [
-  "#!/usr/bin/env bash",
-  "set -euo pipefail",
-  "",
-  'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
-  'exec node "$SCRIPT_DIR/../src/lbs.ts" "$@"',
-  "",
-].join("\n");
-
-await mkdir(binDir, { recursive: true });
-
-let current = "";
-try {
-  current = await readFile(lbsPath, "utf8");
-} catch {
-  // Missing wrapper is the normal first-run path.
-}
-
-if (current !== wrapper) {
-  await writeFile(lbsPath, wrapper, "utf8");
-  await chmod(lbsPath, 0o755);
-}

skills/scripts/e2e/agent-runner-release-preflight.mjs

@@ -1,476 +0,0 @@
-#!/usr/bin/env node
-
-import { existsSync, readFileSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  localIsoWithOffset,
-  safeScreenshot,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-function loadEnvDefaults(path) {
-  if (!existsSync(path)) return;
-  for (const rawLine of readFileSync(path, "utf8").split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-    const sep = line.indexOf("=");
-    if (sep === -1) continue;
-    const key = line.slice(0, sep).trim();
-    if (env[key]) continue;
-    env[key] = line.slice(sep + 1).trim().replace(/^["']|["']$/g, "");
-  }
-}
-
-function boolFromEnv(value, defaultValue) {
-  if (value === undefined || value === "") return defaultValue;
-  if (/^(0|false|no|off)$/i.test(value)) return false;
-  if (/^(1|true|yes|on)$/i.test(value)) return true;
-  return defaultValue;
-}
-
-function firstEnv(...keys) {
-  for (const key of keys) {
-    if (env[key]) return env[key];
-  }
-  return "";
-}
-
-function redactMessage(text) {
-  return String(text ?? "")
-    .replace(/\bbearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer [redacted]")
-    .replace(/\bsk-[A-Za-z0-9_-]{6,}\b/g, "[redacted]")
-    .replace(/(api[_-]?key|authorization|credential|jwt|oauth|password|secret|token)\s*[:=]\s*["']?[^"',\s]+/gi, "$1=[redacted]");
-}
-
-function isEnvironmentError(message) {
-  return /Playwright is not installed|LANGBOT_FRONTEND_URL|LANGBOT_BACKEND_URL|ERR_CONNECTION_REFUSED|ECONNREFUSED|net::ERR_|fetch failed|timed out/i
-    .test(message);
-}
-
-loadEnvDefaults("skills/.env");
-loadEnvDefaults("skills/.env.local");
-
-const caseId = env.LBS_CASE_ID || "agent-runner-release-preflight";
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const frontendUrl = env.LANGBOT_FRONTEND_URL || backendUrl;
-const testModels = boolFromEnv(env.LANGBOT_PREFLIGHT_TEST_MODELS, true);
-const requireVision = boolFromEnv(env.LANGBOT_PREFLIGHT_REQUIRE_VISION, true);
-const diagnosticPath = resolve(paths.evidenceDir, "api-diagnostic.json");
-const startedAt = new Date();
-
-const targets = [
-  {
-    id: "local-agent",
-    expected_runner_id: "plugin:langbot/local-agent/default",
-    pipeline_url: firstEnv("LANGBOT_LOCAL_AGENT_PIPELINE_URL"),
-    pipeline_name: firstEnv("LANGBOT_LOCAL_AGENT_PIPELINE_NAME"),
-    require_func_call_model: true,
-    require_vision_model: requireVision,
-    require_langbot_mcp: false,
-  },
-  {
-    id: "acp-agent-runner",
-    expected_runner_id: "plugin:langbot/acp-agent-runner/default",
-    pipeline_url: firstEnv("LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL", "LANGBOT_AGENT_RUNNER_PIPELINE_URL"),
-    pipeline_name: firstEnv("LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME", "LANGBOT_AGENT_RUNNER_PIPELINE_NAME"),
-    require_func_call_model: false,
-    require_vision_model: false,
-  },
-];
-
-let browser;
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  started_at: startedAt.toISOString(),
-  started_at_local: localIsoWithOffset(startedAt),
-  finished_at: "",
-  finished_at_local: "",
-  status: "fail",
-  reason: "",
-  frontend_url: frontendUrl,
-  backend_url: backendUrl,
-  test_models: testModels,
-  require_vision_model: requireVision,
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    api_diagnostic_json: diagnosticPath,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["ui", "screenshot", "console", "network", "api_diagnostic"],
-};
-
-async function run() {
-  if (!backendUrl || !frontendUrl) {
-    result.status = "env_issue";
-    result.reason = "LANGBOT_FRONTEND_URL and LANGBOT_BACKEND_URL must be configured.";
-    return;
-  }
-
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  await page.goto(frontendUrl, { waitUntil: "domcontentloaded" });
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-
-  const diagnostic = await page.evaluate(async ({ backendUrl, targets, testModels }) => {
-    const blockers = [];
-    const envIssues = [];
-    const warnings = [];
-    const checks = [];
-
-    const addCheck = (name, status, detail = {}) => {
-      checks.push({ name, status, ...detail });
-      if (status === "blocked") blockers.push({ name, ...detail });
-      if (status === "env_issue") envIssues.push({ name, ...detail });
-    };
-    const safeMessage = (value) => String(value ?? "")
-      .replace(/\bbearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer [redacted]")
-      .replace(/\bsk-[A-Za-z0-9_-]{6,}\b/g, "[redacted]")
-      .replace(/(api[_-]?key|authorization|credential|jwt|oauth|password|secret|token)\s*[:=]\s*["']?[^"',\s]+/gi, "$1=[redacted]");
-
-    const token = localStorage.getItem("token");
-    if (!token) {
-      addCheck("browser-auth", "blocked", { reason: "Browser profile has no localStorage token." });
-      return { authenticated: false, blockers, env_issues: envIssues, warnings, checks };
-    }
-
-    const headers = {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-    };
-    const getJson = async (path) => {
-      const response = await fetch(`${backendUrl}${path}`, { headers });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-    const postJson = async (path, body) => {
-      const response = await fetch(`${backendUrl}${path}`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-      });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-
-    const tokenCheck = await getJson("/api/v1/user/check-token");
-    addCheck(
-      "browser-auth",
-      tokenCheck.status < 400 && (tokenCheck.json.code ?? 0) === 0 ? "pass" : "blocked",
-      { http_status: tokenCheck.status, code: tokenCheck.json.code ?? null, reason: safeMessage(tokenCheck.json.msg || "") },
-    );
-
-    const systemInfo = await getJson("/api/v1/system/info");
-    addCheck(
-      "backend-system-info",
-      systemInfo.status < 400 ? "pass" : "env_issue",
-      {
-        http_status: systemInfo.status,
-        version: systemInfo.json.data?.version || systemInfo.json.data?.system?.version || "",
-      },
-    );
-
-    const pluginSystem = await getJson("/api/v1/system/status/plugin-system");
-    addCheck(
-      "plugin-system",
-      pluginSystem.status < 400 && (pluginSystem.json.code ?? 0) === 0 ? "pass" : "env_issue",
-      {
-        http_status: pluginSystem.status,
-        code: pluginSystem.json.code ?? null,
-        status: pluginSystem.json.data?.status || pluginSystem.json.data?.state || "",
-        reason: safeMessage(pluginSystem.json.msg || ""),
-      },
-    );
-
-    const boxStatus = await getJson("/api/v1/box/status");
-    addCheck(
-      "box-runtime",
-      boxStatus.status < 400 && (boxStatus.json.code ?? 0) === 0 ? "pass" : "env_issue",
-      {
-        http_status: boxStatus.status,
-        code: boxStatus.json.code ?? null,
-        status: boxStatus.json.data?.status || "",
-        backend: boxStatus.json.data?.backend || "",
-        reason: safeMessage(boxStatus.json.msg || ""),
-      },
-    );
-
-    const plugins = await getJson("/api/v1/plugins");
-    const installedPluginIds = (plugins.json.data?.plugins || [])
-      .map((plugin) => {
-        const metadata = plugin.manifest?.manifest?.metadata || plugin.manifest?.metadata || plugin.metadata || {};
-        return metadata.author && metadata.name ? `${metadata.author}/${metadata.name}` : "";
-      })
-      .filter(Boolean);
-    const requiredPlugins = ["langbot/local-agent", "langbot/acp-agent-runner", "qa/plugin-smoke"];
-    const pluginPresence = Object.fromEntries(requiredPlugins.map((id) => [id, installedPluginIds.includes(id)]));
-    for (const [id, present] of Object.entries(pluginPresence)) {
-      addCheck(`plugin:${id}`, present ? "pass" : "blocked", { plugin_id: id, reason: present ? "" : "Required plugin is not listed by /api/v1/plugins." });
-    }
-
-    const tools = await getJson("/api/v1/tools");
-    const toolNames = (tools.json.data?.tools || [])
-      .map((tool) => tool.name || tool.tool_name || tool.function?.name || "")
-      .filter(Boolean)
-      .sort();
-    addCheck(
-      "tool:qa_plugin_echo",
-      toolNames.includes("qa_plugin_echo") ? "pass" : "blocked",
-      { reason: toolNames.includes("qa_plugin_echo") ? "" : "qa-plugin-smoke tool qa_plugin_echo is not exposed through /api/v1/tools." },
-    );
-    if (!toolNames.includes("qa_mcp_echo")) {
-      warnings.push({
-        name: "tool:qa_mcp_echo",
-        reason: "qa_mcp_echo is not currently exposed. This is acceptable before mcp-stdio-register, but mcp-stdio-tool-call must run after registration.",
-      });
-    }
-
-    const modelResponse = await getJson("/api/v1/provider/models/llm");
-    const models = (modelResponse.json.data?.models || []).map((model) => ({
-      uuid: model.uuid,
-      name: model.name,
-      abilities: Array.isArray(model.abilities) ? model.abilities : [],
-      provider_uuid: model.provider_uuid || model.provider?.uuid || "",
-      provider_name: model.provider_name || model.provider?.name || "",
-      requester: model.requester || model.provider?.requester || "",
-    }));
-    addCheck(
-      "llm-model-list",
-      modelResponse.status < 400 && (modelResponse.json.code ?? 0) === 0 ? "pass" : "env_issue",
-      { http_status: modelResponse.status, model_count: models.length, reason: safeMessage(modelResponse.json.msg || "") },
-    );
-    const modelById = new Map(models.map((model) => [model.uuid, model]));
-
-    const pipelineList = await getJson("/api/v1/pipelines");
-    const pipelines = pipelineList.json.data?.pipelines || [];
-    addCheck(
-      "pipeline-list",
-      pipelineList.status < 400 && (pipelineList.json.code ?? 0) === 0 ? "pass" : "blocked",
-      { http_status: pipelineList.status, pipeline_count: pipelines.length, reason: safeMessage(pipelineList.json.msg || "") },
-    );
-
-    const resolvedPipelines = [];
-    const modelTested = new Set();
-    for (const target of targets) {
-      let pipelineId = "";
-      let matchedBy = "";
-      if (target.pipeline_url) {
-        try {
-          pipelineId = new URL(target.pipeline_url).searchParams.get("id") || "";
-          matchedBy = pipelineId ? "url" : "";
-        } catch {
-          pipelineId = "";
-        }
-      }
-      if (!pipelineId && target.pipeline_name) {
-        const match = pipelines.find((pipeline) => pipeline.name === target.pipeline_name);
-        if (match) {
-          pipelineId = match.uuid;
-          matchedBy = "name";
-        }
-      }
-      if (!pipelineId) {
-        addCheck(`pipeline:${target.id}`, "blocked", {
-          target: target.id,
-          reason: "Required pipeline env is missing or could not resolve to a pipeline id.",
-        });
-        continue;
-      }
-
-      const response = await getJson(`/api/v1/pipelines/${encodeURIComponent(pipelineId)}`);
-      const pipeline = response.json.data?.pipeline;
-      if (response.status >= 400 || !pipeline) {
-        addCheck(`pipeline:${target.id}`, "blocked", {
-          target: target.id,
-          pipeline_id: pipelineId,
-          http_status: response.status,
-          reason: safeMessage(response.json.msg || "Could not load pipeline."),
-        });
-        continue;
-      }
-
-      const config = pipeline.config || {};
-      const aiConfig = config.ai && typeof config.ai === "object" ? config.ai : {};
-      const runner = aiConfig.runner && typeof aiConfig.runner === "object" ? aiConfig.runner : {};
-      const runnerId = runner.id || runner.runner || "";
-      const runnerConfigs = aiConfig.runner_config && typeof aiConfig.runner_config === "object" ? aiConfig.runner_config : {};
-      const runnerConfig = runnerConfigs[runnerId] && typeof runnerConfigs[runnerId] === "object" ? runnerConfigs[runnerId] : {};
-      const pipelineSummary = {
-        target: target.id,
-        pipeline_id: pipelineId,
-        pipeline_name: pipeline.name,
-        matched_by: matchedBy,
-        runner_id: runnerId,
-        expected_runner_id: target.expected_runner_id,
-        runner_config_keys: Object.keys(runnerConfig).sort(),
-      };
-      resolvedPipelines.push(pipelineSummary);
-
-      addCheck(
-        `pipeline:${target.id}:runner`,
-        runnerId === target.expected_runner_id ? "pass" : "blocked",
-        {
-          ...pipelineSummary,
-          reason: runnerId === target.expected_runner_id ? "" : `Expected ${target.expected_runner_id}, got ${runnerId || "<missing>"}.`,
-        },
-      );
-
-      if (target.require_func_call_model || target.require_vision_model || (testModels && target.id === "local-agent")) {
-        const modelConfig = runnerConfig.model;
-        const primaryModelId = typeof modelConfig === "string"
-          ? modelConfig
-          : modelConfig && typeof modelConfig === "object"
-            ? modelConfig.primary || ""
-            : "";
-        if (!primaryModelId) {
-          addCheck(`pipeline:${target.id}:primary-model`, "blocked", {
-            ...pipelineSummary,
-            reason: "Local-agent runner config has no primary model.",
-          });
-          continue;
-        }
-        const model = modelById.get(primaryModelId);
-        if (!model) {
-          addCheck(`pipeline:${target.id}:primary-model`, "blocked", {
-            ...pipelineSummary,
-            model_uuid: primaryModelId,
-            reason: "Primary model is not listed by /api/v1/provider/models/llm.",
-          });
-          continue;
-        }
-        addCheck(`pipeline:${target.id}:primary-model`, "pass", {
-          ...pipelineSummary,
-          model: {
-            uuid: model.uuid,
-            name: model.name,
-            abilities: model.abilities,
-            provider_name: model.provider_name,
-            requester: model.requester,
-          },
-        });
-        if (target.require_func_call_model) {
-          addCheck(
-            `pipeline:${target.id}:func-call-model`,
-            model.abilities.includes("func_call") ? "pass" : "env_issue",
-            {
-              model_uuid: model.uuid,
-              model_name: model.name,
-              abilities: model.abilities,
-              reason: model.abilities.includes("func_call") ? "" : "Release gate includes tool-call cases; the local-agent primary model must advertise func_call.",
-            },
-          );
-        }
-        if (target.require_vision_model) {
-          addCheck(
-            `pipeline:${target.id}:vision-model`,
-            model.abilities.includes("vision") ? "pass" : "env_issue",
-            {
-              model_uuid: model.uuid,
-              model_name: model.name,
-              abilities: model.abilities,
-              reason: model.abilities.includes("vision") ? "" : "Release gate includes multimodal cases; the local-agent primary model must advertise vision.",
-            },
-          );
-        }
-        if (testModels && !modelTested.has(model.uuid)) {
-          modelTested.add(model.uuid);
-          const modelTest = await postJson(`/api/v1/provider/models/llm/${encodeURIComponent(model.uuid)}/test`, { extra_args: {} });
-          const passed = modelTest.status < 400 && (modelTest.json.code ?? 0) === 0;
-          addCheck(
-            `model-test:${model.name}`,
-            passed ? "pass" : "env_issue",
-            {
-              model_uuid: model.uuid,
-              model_name: model.name,
-              http_status: modelTest.status,
-              code: modelTest.json.code ?? null,
-              reason: passed ? "" : safeMessage(modelTest.json.msg || modelTest.json.message || "Model test failed."),
-            },
-          );
-        }
-      }
-    }
-
-    return {
-      authenticated: true,
-      blockers,
-      env_issues: envIssues,
-      warnings,
-      checks,
-      resolved_pipelines: resolvedPipelines,
-      tools: {
-        required: ["qa_plugin_echo"],
-        optional_before_register: ["qa_mcp_echo"],
-        present: toolNames.filter((name) => ["qa_plugin_echo", "qa_mcp_echo"].includes(name)),
-      },
-      models,
-    };
-  }, { backendUrl, targets, testModels });
-
-  diagnostic.blockers = (diagnostic.blockers || []).map((item) => ({ ...item, reason: redactMessage(item.reason || "") }));
-  diagnostic.env_issues = (diagnostic.env_issues || []).map((item) => ({ ...item, reason: redactMessage(item.reason || "") }));
-  await writeFile(diagnosticPath, `${JSON.stringify(diagnostic, null, 2)}\n`, "utf8");
-  await safeScreenshot(page, paths.screenshot);
-
-  const blockers = diagnostic.blockers || [];
-  const envIssues = diagnostic.env_issues || [];
-  if (blockers.length > 0) {
-    result.status = "blocked";
-    result.reason = `Preflight blocked: ${blockers.map((item) => item.name).join(", ")}`;
-  } else if (envIssues.length > 0) {
-    result.status = "env_issue";
-    result.reason = `Preflight environment issue: ${envIssues.map((item) => item.name).join(", ")}`;
-  } else {
-    result.status = "pass";
-    result.reason = "Release gate preflight passed: auth, plugin runtime, required pipelines, runner ids, tools, and local-agent model checks are ready.";
-  }
-  result.check_count = Array.isArray(diagnostic.checks) ? diagnostic.checks.length : 0;
-  result.warning_count = Array.isArray(diagnostic.warnings) ? diagnostic.warnings.length : 0;
-}
-
-try {
-  await run();
-} catch (error) {
-  const message = redactMessage(error instanceof Error ? error.message : String(error));
-  result.status = isEnvironmentError(message) ? "env_issue" : "fail";
-  result.reason = message;
-  await writeFile(diagnosticPath, `${JSON.stringify({
-    authenticated: false,
-    blockers: [],
-    env_issues: result.status === "env_issue" ? [{ name: "preflight-runtime", reason: message }] : [],
-    warnings: [],
-    checks: [
-      {
-        name: "preflight-runtime",
-        status: result.status,
-        reason: message,
-      },
-    ],
-  }, null, 2)}\n`, "utf8").catch(() => {});
-} finally {
-  if (browser) await browser.close().catch(() => {});
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));

skills/scripts/e2e/ensure-acp-agent-runner-pipeline.mjs

@@ -1,263 +0,0 @@
-#!/usr/bin/env node
-
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  apiJson,
-  ensureEvidence,
-  evidencePaths,
-  loadEnvFiles,
-  resetAndAuthLocalUser,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const RUNNER_ID = "plugin:langbot/acp-agent-runner/default";
-const DEFAULT_PIPELINE_NAME = "Agent QA ACP Claude Debug Chat";
-const DEFAULT_LOCAL_PASSWORD = "LangBotE2ELocalPass!2026";
-const caseId = "ensure-acp-agent-runner-pipeline";
-
-await loadEnvFiles();
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const writeEnv = process.argv.includes("--write-env");
-const frontendUrl = env.LANGBOT_FRONTEND_URL || "";
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const pipelineName = env.LANGBOT_E2E_CREATE_PIPELINE_NAME || env.LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME || DEFAULT_PIPELINE_NAME;
-const sshTarget = env.LANGBOT_ACP_AGENT_RUNNER_SSH_TARGET || "yhh@101.34.71.12";
-const sshConnectTimeout = env.LANGBOT_ACP_AGENT_RUNNER_SSH_CONNECT_TIMEOUT || "8";
-const sshPort = env.LANGBOT_ACP_AGENT_RUNNER_SSH_PORT || "22";
-const sshIdentityFile = env.LANGBOT_ACP_AGENT_RUNNER_SSH_IDENTITY_FILE || "";
-const sshExtraOptions = env.LANGBOT_ACP_AGENT_RUNNER_SSH_EXTRA_OPTIONS || "";
-const remoteWorkspace = env.LANGBOT_ACP_AGENT_RUNNER_REMOTE_WORKSPACE || "/home/yhh/langbot-e2e/acp-workspace";
-const envLocalPath = resolve("skills/.env.local");
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  status: "fail",
-  reason: "",
-  frontend_url: frontendUrl,
-  backend_url: backendUrl,
-  pipeline_name: pipelineName,
-  pipeline_id: "",
-  pipeline_url: "",
-  runner_id: RUNNER_ID,
-  ssh_target: sshTarget,
-  ssh_port: sshPort,
-  remote_workspace: remoteWorkspace,
-  wrote_env: false,
-  auth: null,
-  evidence: {
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["api_diagnostic"],
-};
-
-try {
-  if (!frontendUrl) throw new Error("LANGBOT_FRONTEND_URL is not configured.");
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-
-  const user = env.LANGBOT_E2E_LOGIN_USER || "";
-  const password = env.LANGBOT_E2E_LOGIN_PASSWORD || DEFAULT_LOCAL_PASSWORD;
-  if (!user) {
-    throw new Error("LANGBOT_E2E_LOGIN_USER is required so this setup can create/update the pipeline via backend API.");
-  }
-
-  const auth = await resetAndAuthLocalUser({ backendUrl, user, password });
-  result.auth = {
-    source: "local_recovery_login",
-    user,
-    backend_token_check: auth.check,
-  };
-
-  const runnerConfig = {
-    provider: "claude-code",
-    location: "remote-ssh",
-    workspace: remoteWorkspace,
-    "ssh-target": sshTarget,
-    "ssh-port": Number.parseInt(sshPort, 10),
-    "ssh-identity-file": sshIdentityFile,
-    "ssh-connect-timeout": Number.parseInt(sshConnectTimeout, 10),
-    "ssh-extra-options": sshExtraOptions,
-    "langbot-assets-enabled": true,
-    "mcp-bridge-request-timeout": 90,
-    "reuse-session": false,
-    "create-session-if-missing": true,
-    "append-run-scope-prompt": true,
-    "startup-timeout": 30,
-    "initialize-timeout": 120,
-    timeout: 300,
-  };
-
-  const prepared = await ensurePipeline({
-    backendUrl,
-    token: auth.token,
-    pipelineName,
-    runnerId: RUNNER_ID,
-    runnerConfig,
-  });
-  Object.assign(result, prepared);
-  if (result.pipeline_id) {
-    result.pipeline_url = `${frontendUrl.replace(/\/$/, "")}/home/pipelines?id=${encodeURIComponent(result.pipeline_id)}`;
-  }
-
-  if (writeEnv && result.pipeline_id) {
-    await upsertEnvLocal(envLocalPath, {
-      LANGBOT_E2E_LOGIN_USER: user,
-      LANGBOT_ACP_AGENT_RUNNER_SSH_TARGET: sshTarget,
-      LANGBOT_ACP_AGENT_RUNNER_SSH_PORT: sshPort,
-      LANGBOT_ACP_AGENT_RUNNER_SSH_IDENTITY_FILE: sshIdentityFile,
-      LANGBOT_ACP_AGENT_RUNNER_SSH_EXTRA_OPTIONS: sshExtraOptions,
-      LANGBOT_ACP_AGENT_RUNNER_REMOTE_WORKSPACE: remoteWorkspace,
-      LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL: result.pipeline_url,
-      LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME: result.pipeline_name || pipelineName,
-    });
-    result.wrote_env = true;
-  }
-} catch (error) {
-  result.reason = result.reason || error.message;
-} finally {
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(result.status === "pass" ? 0 : result.status === "env_issue" ? 2 : 1);
-
-async function ensurePipeline({ backendUrl, token, pipelineName, runnerId, runnerConfig }) {
-  const pipelineList = await apiJson(backendUrl, "/api/v1/pipelines", { token });
-  if (isApiFailure(pipelineList)) {
-    return {
-      status: "fail",
-      reason: pipelineList.json.msg || "Failed to list pipelines.",
-      list_status: pipelineList.status,
-    };
-  }
-
-  const pipelines = pipelineList.json.data?.pipelines || [];
-  let pipeline = pipelines.find((item) => item.name === pipelineName) || null;
-  let created = false;
-
-  if (!pipeline) {
-    const createdResponse = await apiJson(backendUrl, "/api/v1/pipelines", {
-      method: "POST",
-      token,
-      body: {
-        name: pipelineName,
-        description: "Local QA pipeline for real ACP Claude AgentRunner Debug Chat smoke tests.",
-        emoji: "QA",
-      },
-    });
-    if (isApiFailure(createdResponse)) {
-      return {
-        status: "fail",
-        reason: createdResponse.json.msg || "Failed to create pipeline.",
-        create_status: createdResponse.status,
-      };
-    }
-    const pipelineId = createdResponse.json.data?.uuid || "";
-    const loaded = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipelineId)}`, { token });
-    pipeline = loaded.json.data?.pipeline || null;
-    created = true;
-  }
-
-  if (!pipeline?.uuid) {
-    return {
-      status: "fail",
-      reason: "Pipeline was not created or resolved.",
-    };
-  }
-
-  const loaded = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipeline.uuid)}`, { token });
-  if (isApiFailure(loaded) || !loaded.json.data?.pipeline) {
-    return {
-      status: "fail",
-      reason: loaded.json.msg || "Failed to load pipeline.",
-      get_status: loaded.status,
-      pipeline_id: pipeline.uuid,
-    };
-  }
-  pipeline = loaded.json.data.pipeline;
-
-  const config = pipeline.config && typeof pipeline.config === "object" ? pipeline.config : {};
-  const ai = config.ai && typeof config.ai === "object" ? config.ai : {};
-  const runnerConfigs = ai.runner_config && typeof ai.runner_config === "object" ? ai.runner_config : {};
-  const updatedConfig = {
-    ...config,
-    ai: {
-      ...ai,
-      runner: {
-        ...(ai.runner && typeof ai.runner === "object" ? ai.runner : {}),
-        id: runnerId,
-        "expire-time": 0,
-      },
-      runner_config: {
-        ...runnerConfigs,
-        [runnerId]: runnerConfig,
-      },
-    },
-  };
-
-  const updateResponse = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipeline.uuid)}`, {
-    method: "PUT",
-    token,
-    body: {
-      name: pipelineName,
-      description: "Local QA pipeline for real ACP Claude AgentRunner Debug Chat smoke tests.",
-      emoji: "QA",
-      config: updatedConfig,
-    },
-  });
-  if (isApiFailure(updateResponse)) {
-    return {
-      status: "fail",
-      reason: updateResponse.json.msg || "Failed to update pipeline.",
-      update_status: updateResponse.status,
-      pipeline_id: pipeline.uuid,
-    };
-  }
-
-  return {
-    status: "pass",
-    reason: created ? "ACP AgentRunner pipeline created and configured." : "ACP AgentRunner pipeline updated.",
-    pipeline_id: pipeline.uuid,
-    pipeline_name: pipelineName,
-    created,
-    updated: true,
-  };
-}
-
-function isApiFailure(response) {
-  return response.status >= 400 || (response.json && response.json.code !== undefined && response.json.code !== 0);
-}
-
-async function upsertEnvLocal(path, values) {
-  let text = "";
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    text = "";
-  }
-  const lines = text.split(/\r?\n/);
-  const keys = new Set(Object.keys(values));
-  const output = [];
-  for (const line of lines) {
-    const match = line.match(/^([A-Z][A-Z0-9_]*)=/);
-    if (match && keys.has(match[1])) {
-      output.push(`${match[1]}=${values[match[1]]}`);
-      keys.delete(match[1]);
-    } else if (line !== "" || output.length > 0) {
-      output.push(line);
-    }
-  }
-  if (keys.size > 0 && output.length > 0 && output[output.length - 1] !== "") {
-    output.push("");
-  }
-  for (const key of keys) {
-    output.push(`${key}=${values[key]}`);
-  }
-  await writeFile(path, `${output.join("\n").replace(/\n+$/, "")}\n`, "utf8");
-}

skills/scripts/e2e/ensure-langrag-sentinel-kb.mjs

@@ -1,293 +0,0 @@
-#!/usr/bin/env node
-
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  apiJson,
-  ensureEvidence,
-  evidencePaths,
-  loadEnvFiles,
-  resetAndAuthLocalUser,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const caseId = env.LBS_CASE_ID || "ensure-langrag-sentinel-kb";
-
-await loadEnvFiles();
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const user = env.LANGBOT_E2E_LOGIN_USER || "";
-const password = env.LANGBOT_E2E_LOGIN_PASSWORD || "LangBotE2ELocalPass!2026";
-const expectedText = env.LANGBOT_E2E_EXPECTED_TEXT || "azalea-cobalt-7421";
-const query = env.LANGBOT_E2E_RETRIEVE_QUERY || "What is the local agent runner retrieval sentinel?";
-const writeEnv = process.argv.includes("--write-env");
-const checkOnly = process.argv.includes("--check-only");
-const envLocalPath = resolve("skills/.env.local");
-const kbName = env.LANGBOT_E2E_RAG_KB_NAME || "qa-local-agent-rag";
-const sentinelPath = resolve(env.LANGBOT_E2E_RAG_SENTINEL_DOC || "skills/langbot-testing/fixtures/rag/sentinel-doc.txt");
-const waitMs = Number(env.LANGBOT_E2E_RAG_WAIT_MS || 180_000);
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  status: "fail",
-  reason: "",
-  backend_url: backendUrl,
-  expected_text: expectedText,
-  query,
-  kb_uuid: "",
-  kb_name: "",
-  kb_created: false,
-  uploaded_file_id: "",
-  store_task_id: "",
-  embedding_model_uuid: "",
-  engine_plugin_id: "",
-  checked_bases: [],
-  file_statuses: [],
-  wrote_env: false,
-  evidence: {
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["api_diagnostic"],
-};
-
-try {
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-  if (!user) throw new Error("LANGBOT_E2E_LOGIN_USER is required.");
-
-  const auth = await resetAndAuthLocalUser({ backendUrl, user, password });
-  const basesResponse = await apiJson(backendUrl, "/api/v1/knowledge/bases", { token: auth.token });
-  if (basesResponse.status >= 400 || basesResponse.json.code !== 0) {
-    throw new Error(basesResponse.json.msg || `Failed to list knowledge bases: HTTP ${basesResponse.status}.`);
-  }
-
-  let bases = basesResponse.json.data?.bases || [];
-  await findSentinelBase(backendUrl, auth.token, bases, result);
-
-  if (!result.kb_uuid && !checkOnly) {
-    const targetBase = bases.find((base) => {
-      const uuid = base.uuid || base.id || "";
-      return (base.name || "") === kbName && !hasRetrieveFailure(result.checked_bases, uuid);
-    });
-    result.kb_uuid = targetBase?.uuid || targetBase?.id || "";
-    result.kb_name = targetBase?.name || kbName;
-
-    if (!result.kb_uuid) {
-      const setup = await createKnowledgeBase(backendUrl, auth.token, kbName);
-      result.kb_uuid = setup.kbUuid;
-      result.kb_name = kbName;
-      result.kb_created = true;
-      result.embedding_model_uuid = setup.embeddingModelUuid;
-      result.engine_plugin_id = setup.enginePluginId;
-    }
-
-    const upload = await uploadDocument(backendUrl, auth.token, sentinelPath);
-    result.uploaded_file_id = upload.fileId;
-
-    const store = await apiJson(backendUrl, `/api/v1/knowledge/bases/${encodeURIComponent(result.kb_uuid)}/files`, {
-      method: "POST",
-      token: auth.token,
-      body: { file_id: upload.fileId },
-    });
-    if (store.status >= 400 || store.json.code !== 0) {
-      throw new Error(store.json.msg || `Failed to store file in knowledge base: HTTP ${store.status}.`);
-    }
-    result.store_task_id = store.json.data?.task_id || "";
-
-    const ready = await waitForSentinel(backendUrl, auth.token, result.kb_uuid, query, expectedText, waitMs);
-    result.file_statuses = ready.fileStatuses;
-    if (ready.matched) {
-      result.checked_bases.push(ready.checked);
-    }
-  }
-
-  if (!result.kb_uuid) {
-    result.status = "env_issue";
-    result.reason = checkOnly
-      ? `No existing knowledge base retrieved expected sentinel: ${expectedText}`
-      : `Could not create or verify LangRAG sentinel knowledge base: ${expectedText}`;
-  } else {
-    if (writeEnv) {
-      await upsertEnvLocal(envLocalPath, {
-        LANGBOT_LOCAL_AGENT_RAG_KB_UUID: result.kb_uuid,
-      });
-      result.wrote_env = true;
-    }
-    result.status = "pass";
-    result.reason = `Found LangRAG sentinel knowledge base: ${result.kb_uuid}`;
-  }
-} catch (error) {
-  result.status = /not configured|required|No existing knowledge base/.test(error.message) ? "env_issue" : "fail";
-  result.reason = error.message;
-} finally {
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(result.status === "pass" ? 0 : result.status === "env_issue" ? 2 : 1);
-
-async function findSentinelBase(backendUrl, token, bases, result) {
-  for (const base of bases) {
-    const uuid = base.uuid || base.id || "";
-    if (!uuid) continue;
-    const checked = await retrieveSentinel(backendUrl, token, uuid, base.name || "", result.query, result.expected_text);
-    result.checked_bases.push(checked);
-    if (checked.matched) {
-      result.kb_uuid = uuid;
-      result.kb_name = checked.name;
-      return;
-    }
-  }
-}
-
-async function createKnowledgeBase(backendUrl, token, name) {
-  const enginesResponse = await apiJson(backendUrl, "/api/v1/knowledge/engines", { token });
-  if (enginesResponse.status >= 400 || enginesResponse.json.code !== 0) {
-    throw new Error(enginesResponse.json.msg || `Failed to list knowledge engines: HTTP ${enginesResponse.status}.`);
-  }
-  const engines = enginesResponse.json.data?.engines || [];
-  const engine = engines.find((item) => item.plugin_id === "langbot-team/LangRAG")
-    || engines.find((item) => JSON.stringify(item.name || item.label || "").includes("LangRAG"));
-  const enginePluginId = engine?.plugin_id || "";
-  if (!enginePluginId) throw new Error("LangRAG knowledge engine is not installed.");
-
-  const embeddingModelUuid = await pickEmbeddingModel(backendUrl, token);
-  const create = await apiJson(backendUrl, "/api/v1/knowledge/bases", {
-    method: "POST",
-    token,
-    body: {
-      name,
-      description: "Automated LangBot agent-runner RAG sentinel knowledge base.",
-      knowledge_engine_plugin_id: enginePluginId,
-      creation_settings: {
-        embedding_model_uuid: embeddingModelUuid,
-        index_type: "chunk",
-        chunk_size: 512,
-        overlap: 50,
-      },
-      retrieval_settings: {
-        top_k: 5,
-        search_type: "vector",
-        query_rewrite: "off",
-        rerank: "off",
-        context_window: 0,
-      },
-    },
-  });
-  const kbUuid = create.json.data?.uuid || "";
-  if (create.status >= 400 || create.json.code !== 0 || !kbUuid) {
-    throw new Error(create.json.msg || `Failed to create knowledge base: HTTP ${create.status}.`);
-  }
-  return { kbUuid, embeddingModelUuid, enginePluginId };
-}
-
-async function pickEmbeddingModel(backendUrl, token) {
-  const configured = env.LANGBOT_LOCAL_AGENT_RAG_EMBEDDING_MODEL_UUID || env.LANGBOT_RAG_EMBEDDING_MODEL_UUID || "";
-  if (configured) return configured;
-
-  const modelsResponse = await apiJson(backendUrl, "/api/v1/provider/models/embedding", { token });
-  if (modelsResponse.status >= 400 || modelsResponse.json.code !== 0) {
-    throw new Error(modelsResponse.json.msg || `Failed to list embedding models: HTTP ${modelsResponse.status}.`);
-  }
-  const models = modelsResponse.json.data?.models || [];
-  const preferred = models.find((model) => /chroma|MiniLM/i.test(model.name || ""))
-    || models.find((model) => /text-embedding-3-small/i.test(model.name || ""))
-    || [...models].sort((a, b) => (a.prefered_ranking ?? 9999) - (b.prefered_ranking ?? 9999))[0];
-  const uuid = preferred?.uuid || "";
-  if (!uuid) throw new Error("No embedding model is configured.");
-  return uuid;
-}
-
-async function uploadDocument(backendUrl, token, path) {
-  const bytes = await readFile(path);
-  const form = new FormData();
-  form.append("file", new Blob([bytes], { type: "text/plain" }), "sentinel-doc.txt");
-  const response = await fetch(`${backendUrl.replace(/\/$/, "")}/api/v1/files/documents`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
-    body: form,
-  });
-  const json = await response.json().catch(() => ({}));
-  const fileId = json.data?.file_id || "";
-  if (response.status >= 400 || json.code !== 0 || !fileId) {
-    throw new Error(json.msg || `Failed to upload sentinel document: HTTP ${response.status}.`);
-  }
-  return { fileId };
-}
-
-async function waitForSentinel(backendUrl, token, kbUuid, query, expectedText, timeoutMs) {
-  const started = Date.now();
-  let fileStatuses = [];
-  let lastChecked = null;
-  while (Date.now() - started < timeoutMs) {
-    const files = await apiJson(backendUrl, `/api/v1/knowledge/bases/${encodeURIComponent(kbUuid)}/files`, { token });
-    fileStatuses = files.json.data?.files || fileStatuses;
-    lastChecked = await retrieveSentinel(backendUrl, token, kbUuid, kbName, query, expectedText);
-    if (lastChecked.matched) {
-      return { matched: true, fileStatuses, checked: lastChecked };
-    }
-    if (fileStatuses.some((item) => item.status === "failed")) break;
-    await sleep(2_000);
-  }
-  result.reason = lastChecked?.msg
-    || `LangRAG sentinel was not retrievable within ${timeoutMs}ms; file statuses: ${JSON.stringify(fileStatuses)}`;
-  result.kb_uuid = "";
-  return { matched: false, fileStatuses, checked: lastChecked };
-}
-
-async function retrieveSentinel(backendUrl, token, uuid, name, query, expectedText) {
-  const retrieve = await apiJson(backendUrl, `/api/v1/knowledge/bases/${encodeURIComponent(uuid)}/retrieve`, {
-    method: "POST",
-    token,
-    body: { query },
-  });
-  const text = JSON.stringify(retrieve.json.data?.results || []);
-  return {
-    uuid,
-    name,
-    http_status: retrieve.status,
-    code: retrieve.json.code ?? null,
-    msg: retrieve.json.msg || "",
-    matched: text.includes(expectedText),
-  };
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function hasRetrieveFailure(checkedBases, uuid) {
-  const checked = checkedBases.find((item) => item.uuid === uuid);
-  return checked && (checked.http_status >= 500 || (typeof checked.code === "number" && checked.code < 0));
-}
-
-async function upsertEnvLocal(path, values) {
-  let text = "";
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    text = "";
-  }
-  const lines = text.split(/\r?\n/);
-  const keys = new Set(Object.keys(values));
-  const output = [];
-  for (const line of lines) {
-    const match = line.match(/^([A-Z][A-Z0-9_]*)=/);
-    if (match && keys.has(match[1])) {
-      output.push(`${match[1]}=${values[match[1]]}`);
-      keys.delete(match[1]);
-    } else if (line !== "" || output.length > 0) {
-      output.push(line);
-    }
-  }
-  if (keys.size > 0 && output.length > 0 && output[output.length - 1] !== "") output.push("");
-  for (const key of keys) output.push(`${key}=${values[key]}`);
-  await writeFile(path, `${output.join("\n").replace(/\n+$/, "")}\n`, "utf8");
-}

skills/scripts/e2e/ensure-local-agent-pipeline.mjs

@@ -1,312 +0,0 @@
-#!/usr/bin/env node
-
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  apiJson,
-  bodyText,
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  loadEnvFiles,
-  resetAndAuthLocalUser,
-  safeScreenshot,
-  setBrowserToken,
-  verifyBrowserToken,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const RUNNER_ID = "plugin:langbot/local-agent/default";
-const DEFAULT_PIPELINE_NAME = "Agent QA Local Agent Debug Chat";
-const DEFAULT_LOCAL_PASSWORD = "LangBotE2ELocalPass!2026";
-const caseId = "ensure-local-agent-pipeline";
-
-await loadEnvFiles();
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const writeEnv = process.argv.includes("--write-env");
-const pipelineName = env.LANGBOT_E2E_CREATE_PIPELINE_NAME || env.LANGBOT_LOCAL_AGENT_PIPELINE_NAME || DEFAULT_PIPELINE_NAME;
-const frontendUrl = env.LANGBOT_FRONTEND_URL || "";
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const envLocalPath = resolve("skills/.env.local");
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  status: "fail",
-  reason: "",
-  frontend_url: frontendUrl,
-  backend_url: backendUrl,
-  pipeline_name: pipelineName,
-  pipeline_id: "",
-  pipeline_url: "",
-  runner_id: RUNNER_ID,
-  selected_model_id: "",
-  model_count: 0,
-  created: false,
-  updated: false,
-  wrote_env: false,
-  auth: null,
-  browser_token_check: null,
-  page_signal: "",
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["api_diagnostic", "console", "network", "screenshot"],
-};
-
-let browser;
-
-try {
-  if (!frontendUrl) throw new Error("LANGBOT_FRONTEND_URL is not configured.");
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-
-  const user = env.LANGBOT_E2E_LOGIN_USER || "";
-  const password = env.LANGBOT_E2E_LOGIN_PASSWORD || DEFAULT_LOCAL_PASSWORD;
-  if (!user) {
-    throw new Error("LANGBOT_E2E_LOGIN_USER is required so this setup can create/update the pipeline via backend API.");
-  }
-
-  const auth = await resetAndAuthLocalUser({ backendUrl, user, password });
-  result.auth = {
-    source: "local_recovery_login",
-    user,
-    backend_token_check: auth.check,
-  };
-
-  const prepared = await ensureLocalAgentPipeline({
-    backendUrl,
-    token: auth.token,
-    pipelineName,
-    runnerId: RUNNER_ID,
-  });
-  Object.assign(result, prepared);
-  if (result.pipeline_id) {
-    result.pipeline_url = `${frontendUrl.replace(/\/$/, "")}/home/pipelines?id=${encodeURIComponent(result.pipeline_id)}`;
-  }
-
-  if (writeEnv && result.pipeline_id) {
-    await upsertEnvLocal(envLocalPath, {
-      LANGBOT_E2E_LOGIN_USER: user,
-      LANGBOT_PIPELINE_URL: result.pipeline_url,
-      LANGBOT_PIPELINE_NAME: result.pipeline_name || pipelineName,
-      LANGBOT_LOCAL_AGENT_PIPELINE_URL: result.pipeline_url,
-      LANGBOT_LOCAL_AGENT_PIPELINE_NAME: result.pipeline_name || pipelineName,
-    });
-    result.wrote_env = true;
-  }
-
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  await setBrowserToken(page, frontendUrl, auth.token);
-  const browserCheck = await verifyBrowserToken(page, backendUrl);
-  result.browser_token_check = browserCheck;
-  if (!browserCheck.authenticated) {
-    throw new Error(browserCheck.reason || "Browser token check failed after setup.");
-  }
-  await page.goto(result.pipeline_url || frontendUrl, { waitUntil: "domcontentloaded" });
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-  const text = await bodyText(page);
-  result.page_signal = ["Pipelines", "流水线", pipelineName].find((signal) => text.includes(signal)) || "";
-} catch (error) {
-  result.status = result.status === "env_issue" ? "env_issue" : "fail";
-  result.reason = result.reason || error.message;
-} finally {
-  if (browser?.page) await safeScreenshot(browser.page, paths.screenshot);
-  if (browser) await browser.close().catch(() => {});
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(result.status === "pass" ? 0 : result.status === "env_issue" ? 2 : 1);
-
-async function ensureLocalAgentPipeline({ backendUrl, token, pipelineName, runnerId }) {
-  const [pipelineList, modelList] = await Promise.all([
-    apiJson(backendUrl, "/api/v1/pipelines", { token }),
-    apiJson(backendUrl, "/api/v1/provider/models/llm", { token }),
-  ]);
-
-  if (isApiFailure(pipelineList)) {
-    return {
-      status: "fail",
-      reason: pipelineList.json.msg || "Failed to list pipelines.",
-      list_status: pipelineList.status,
-    };
-  }
-  if (isApiFailure(modelList)) {
-    return {
-      status: "fail",
-      reason: modelList.json.msg || "Failed to list LLM models.",
-      model_status: modelList.status,
-    };
-  }
-
-  const models = modelList.json.data?.models || [];
-  const selectedModel = models.find((model) => model.uuid) || null;
-  const pipelines = pipelineList.json.data?.pipelines || [];
-  let pipeline = pipelines.find((item) => item.name === pipelineName) || null;
-  let created = false;
-
-  if (!pipeline) {
-    const createdResponse = await apiJson(backendUrl, "/api/v1/pipelines", {
-      method: "POST",
-      token,
-      body: {
-        name: pipelineName,
-        description: "Local QA pipeline for AgentRunner Debug Chat smoke tests.",
-        emoji: "QA",
-      },
-    });
-    if (isApiFailure(createdResponse)) {
-      return {
-        status: "fail",
-        reason: createdResponse.json.msg || "Failed to create pipeline.",
-        create_status: createdResponse.status,
-        model_count: models.length,
-      };
-    }
-    const pipelineId = createdResponse.json.data?.uuid || "";
-    const loaded = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipelineId)}`, { token });
-    pipeline = loaded.json.data?.pipeline || null;
-    created = true;
-  }
-
-  if (!pipeline?.uuid) {
-    return {
-      status: "fail",
-      reason: "Pipeline was not created or resolved.",
-      model_count: models.length,
-    };
-  }
-
-  const loaded = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipeline.uuid)}`, { token });
-  if (isApiFailure(loaded) || !loaded.json.data?.pipeline) {
-    return {
-      status: "fail",
-      reason: loaded.json.msg || "Failed to load pipeline.",
-      get_status: loaded.status,
-      pipeline_id: pipeline.uuid,
-      model_count: models.length,
-    };
-  }
-  pipeline = loaded.json.data.pipeline;
-
-  const config = pipeline.config && typeof pipeline.config === "object" ? pipeline.config : {};
-  const ai = config.ai && typeof config.ai === "object" ? config.ai : {};
-  const runnerConfig = ai.runner_config && typeof ai.runner_config === "object" ? ai.runner_config : {};
-  const rawExistingLocalAgentConfig = runnerConfig[runnerId] && typeof runnerConfig[runnerId] === "object"
-    ? runnerConfig[runnerId]
-    : {};
-  const existingLocalAgentConfig = rawExistingLocalAgentConfig;
-  const existingModel = existingLocalAgentConfig.model && typeof existingLocalAgentConfig.model === "object"
-    ? existingLocalAgentConfig.model
-    : {};
-  const requestedModelId = env.LANGBOT_LOCAL_AGENT_MODEL_UUID || env.LANGBOT_E2E_MODEL_UUID || "";
-  const selectedModelId = requestedModelId || existingModel.primary || selectedModel?.uuid || "";
-  const localAgentConfig = {
-    timeout: 300,
-    prompt: [{ role: "system", content: "You are a helpful assistant." }],
-    "remove-think": false,
-    "knowledge-bases": [],
-    "retrieval-top-k": 5,
-    "rerank-model": "",
-    "rerank-top-k": 5,
-    "max-tool-iterations": 20,
-    "tool-execution-mode": "parallel",
-    "max-tool-result-chars": 20000,
-    "context-history-fetch-limit": 50,
-    "context-window-tokens": 200000,
-    "context-reserve-tokens": 16384,
-    "context-keep-recent-tokens": 20000,
-    "context-summary-tokens": 8000,
-    ...existingLocalAgentConfig,
-    model: {
-      primary: selectedModelId,
-      fallbacks: requestedModelId ? [] : Array.isArray(existingModel.fallbacks) ? existingModel.fallbacks : [],
-    },
-  };
-  const updatedConfig = {
-    ...config,
-    ai: {
-      ...ai,
-      runner: {
-        ...(ai.runner && typeof ai.runner === "object" ? ai.runner : {}),
-        id: runnerId,
-        "expire-time": 0,
-      },
-      runner_config: {
-        ...runnerConfig,
-        [runnerId]: localAgentConfig,
-      },
-    },
-  };
-
-  const updateResponse = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipeline.uuid)}`, {
-    method: "PUT",
-    token,
-    body: {
-      name: pipelineName,
-      description: "Local QA pipeline for AgentRunner Debug Chat smoke tests.",
-      emoji: "QA",
-      config: updatedConfig,
-    },
-  });
-  if (isApiFailure(updateResponse)) {
-    return {
-      status: "fail",
-      reason: updateResponse.json.msg || "Failed to update pipeline config.",
-      update_status: updateResponse.status,
-      pipeline_id: pipeline.uuid,
-      model_count: models.length,
-      selected_model_id: selectedModelId,
-    };
-  }
-
-  return {
-    status: selectedModelId ? "pass" : "env_issue",
-    reason: selectedModelId
-      ? "Local-agent pipeline is configured for Debug Chat."
-      : "Pipeline was created but no LLM model is configured in this LangBot instance.",
-    pipeline_id: pipeline.uuid,
-    pipeline_name: pipeline.name,
-    model_count: models.length,
-    selected_model_id: selectedModelId,
-    created,
-    updated: true,
-  };
-}
-
-function isApiFailure(response) {
-  return response.status >= 400 || (response.json.code !== undefined && response.json.code !== 0);
-}
-
-async function upsertEnvLocal(path, updates) {
-  let text = "";
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    text = "";
-  }
-  const lines = text.split(/\r?\n/);
-  const seen = new Set();
-  const next = lines.map((line) => {
-    const trimmed = line.trim();
-    const equals = trimmed.indexOf("=");
-    if (equals <= 0 || trimmed.startsWith("#")) return line;
-    const key = trimmed.slice(0, equals).trim();
-    if (!(key in updates)) return line;
-    seen.add(key);
-    return `${key}=${updates[key]}`;
-  });
-  for (const [key, value] of Object.entries(updates)) {
-    if (!seen.has(key)) next.push(`${key}=${value}`);
-  }
-  await writeFile(path, `${next.filter((line, index) => line !== "" || index < next.length - 1).join("\n")}\n`, "utf8");
-}

skills/scripts/e2e/ensure-qa-agent-runner-pipeline.mjs

@@ -1,230 +0,0 @@
-#!/usr/bin/env node
-
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  apiJson,
-  ensureEvidence,
-  evidencePaths,
-  loadEnvFiles,
-  resetAndAuthLocalUser,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const RUNNER_ID = "plugin:qa/agent-runner/default";
-const DEFAULT_PIPELINE_NAME = "Agent QA Deterministic Runner Debug Chat";
-const DEFAULT_LOCAL_PASSWORD = "LangBotE2ELocalPass!2026";
-const caseId = "ensure-qa-agent-runner-pipeline";
-
-await loadEnvFiles();
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const writeEnv = process.argv.includes("--write-env");
-const frontendUrl = env.LANGBOT_FRONTEND_URL || "";
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const pipelineName = env.LANGBOT_E2E_CREATE_PIPELINE_NAME || env.LANGBOT_QA_AGENT_RUNNER_PIPELINE_NAME || DEFAULT_PIPELINE_NAME;
-const envLocalPath = resolve("skills/.env.local");
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  status: "fail",
-  reason: "",
-  frontend_url: frontendUrl,
-  backend_url: backendUrl,
-  pipeline_name: pipelineName,
-  pipeline_id: "",
-  pipeline_url: "",
-  runner_id: RUNNER_ID,
-  wrote_env: false,
-  auth: null,
-  evidence: {
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["api_diagnostic"],
-};
-
-try {
-  if (!frontendUrl) throw new Error("LANGBOT_FRONTEND_URL is not configured.");
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-
-  const user = env.LANGBOT_E2E_LOGIN_USER || "";
-  const password = env.LANGBOT_E2E_LOGIN_PASSWORD || DEFAULT_LOCAL_PASSWORD;
-  if (!user) {
-    throw new Error("LANGBOT_E2E_LOGIN_USER is required so this setup can create/update the pipeline via backend API.");
-  }
-
-  const auth = await resetAndAuthLocalUser({ backendUrl, user, password });
-  result.auth = {
-    source: "local_recovery_login",
-    user,
-    backend_token_check: auth.check,
-  };
-
-  const prepared = await ensurePipeline({
-    backendUrl,
-    token: auth.token,
-    pipelineName,
-    runnerId: RUNNER_ID,
-    runnerConfig: {},
-  });
-  Object.assign(result, prepared);
-  if (result.pipeline_id) {
-    result.pipeline_url = `${frontendUrl.replace(/\/$/, "")}/home/pipelines?id=${encodeURIComponent(result.pipeline_id)}`;
-  }
-
-  if (writeEnv && result.pipeline_id) {
-    await upsertEnvLocal(envLocalPath, {
-      LANGBOT_E2E_LOGIN_USER: user,
-      LANGBOT_QA_AGENT_RUNNER_PIPELINE_URL: result.pipeline_url,
-      LANGBOT_QA_AGENT_RUNNER_PIPELINE_NAME: result.pipeline_name || pipelineName,
-    });
-    result.wrote_env = true;
-  }
-} catch (error) {
-  result.reason = result.reason || error.message;
-} finally {
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(result.status === "pass" ? 0 : result.status === "env_issue" ? 2 : 1);
-
-async function ensurePipeline({ backendUrl, token, pipelineName, runnerId, runnerConfig }) {
-  const pipelineList = await apiJson(backendUrl, "/api/v1/pipelines", { token });
-  if (isApiFailure(pipelineList)) {
-    return {
-      status: "fail",
-      reason: pipelineList.json.msg || "Failed to list pipelines.",
-      list_status: pipelineList.status,
-    };
-  }
-
-  const pipelines = pipelineList.json.data?.pipelines || [];
-  let pipeline = pipelines.find((item) => item.name === pipelineName) || null;
-  let created = false;
-
-  if (!pipeline) {
-    const createdResponse = await apiJson(backendUrl, "/api/v1/pipelines", {
-      method: "POST",
-      token,
-      body: {
-        name: pipelineName,
-        description: "Local QA pipeline for deterministic QA AgentRunner Debug Chat smoke tests.",
-        emoji: "QA",
-      },
-    });
-    if (isApiFailure(createdResponse)) {
-      return {
-        status: "fail",
-        reason: createdResponse.json.msg || "Failed to create pipeline.",
-        create_status: createdResponse.status,
-      };
-    }
-    const pipelineId = createdResponse.json.data?.uuid || "";
-    const loaded = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipelineId)}`, { token });
-    pipeline = loaded.json.data?.pipeline || null;
-    created = true;
-  }
-
-  if (!pipeline?.uuid) {
-    return {
-      status: "fail",
-      reason: "Pipeline was not created or resolved.",
-    };
-  }
-
-  const loaded = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipeline.uuid)}`, { token });
-  if (isApiFailure(loaded) || !loaded.json.data?.pipeline) {
-    return {
-      status: "fail",
-      reason: loaded.json.msg || "Failed to load pipeline.",
-      get_status: loaded.status,
-      pipeline_id: pipeline.uuid,
-    };
-  }
-  pipeline = loaded.json.data.pipeline;
-
-  const config = pipeline.config && typeof pipeline.config === "object" ? pipeline.config : {};
-  const ai = config.ai && typeof config.ai === "object" ? config.ai : {};
-  const runnerConfigs = ai.runner_config && typeof ai.runner_config === "object" ? ai.runner_config : {};
-  const updatedConfig = {
-    ...config,
-    ai: {
-      ...ai,
-      runner: {
-        ...(ai.runner && typeof ai.runner === "object" ? ai.runner : {}),
-        id: runnerId,
-        "expire-time": 0,
-      },
-      runner_config: {
-        ...runnerConfigs,
-        [runnerId]: runnerConfig,
-      },
-    },
-  };
-
-  const updateResponse = await apiJson(backendUrl, `/api/v1/pipelines/${encodeURIComponent(pipeline.uuid)}`, {
-    method: "PUT",
-    token,
-    body: {
-      name: pipelineName,
-      description: "Local QA pipeline for deterministic QA AgentRunner Debug Chat smoke tests.",
-      emoji: "QA",
-      config: updatedConfig,
-    },
-  });
-  if (isApiFailure(updateResponse)) {
-    return {
-      status: "fail",
-      reason: updateResponse.json.msg || "Failed to update pipeline.",
-      update_status: updateResponse.status,
-      pipeline_id: pipeline.uuid,
-    };
-  }
-
-  return {
-    status: "pass",
-    reason: created ? "QA AgentRunner pipeline created and configured." : "QA AgentRunner pipeline updated.",
-    pipeline_id: pipeline.uuid,
-    pipeline_name: pipelineName,
-    created,
-    updated: true,
-  };
-}
-
-function isApiFailure(response) {
-  return response.status >= 400 || (response.json && response.json.code !== undefined && response.json.code !== 0);
-}
-
-async function upsertEnvLocal(path, values) {
-  let text = "";
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    text = "";
-  }
-  const lines = text.split(/\r?\n/);
-  const keys = new Set(Object.keys(values));
-  const output = [];
-  for (const line of lines) {
-    const match = line.match(/^([A-Z][A-Z0-9_]*)=/);
-    if (match && keys.has(match[1])) {
-      output.push(`${match[1]}=${values[match[1]]}`);
-      keys.delete(match[1]);
-    } else if (line !== "" || output.length > 0) {
-      output.push(line);
-    }
-  }
-  if (keys.size > 0 && output.length > 0 && output[output.length - 1] !== "") {
-    output.push("");
-  }
-  for (const key of keys) {
-    output.push(`${key}=${values[key]}`);
-  }
-  await writeFile(path, `${output.join("\n").replace(/\n+$/, "")}\n`, "utf8");
-}

skills/scripts/e2e/install-qa-plugin-smoke.mjs

@@ -1,198 +0,0 @@
-#!/usr/bin/env node
-
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  apiJson,
-  ensureEvidence,
-  evidencePaths,
-  loadEnvFiles,
-  resetAndAuthLocalUser,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const caseId = env.LBS_CASE_ID || "install-qa-plugin-smoke";
-const paths = evidencePaths(caseId);
-await loadEnvFiles();
-await ensureEvidence(paths);
-
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const user = env.LANGBOT_E2E_LOGIN_USER || "";
-const password = env.LANGBOT_E2E_LOGIN_PASSWORD || "LangBotE2ELocalPass!2026";
-const packagePath = resolve(
-  env.LANGBOT_E2E_PLUGIN_PACKAGE
-    || env.LANGBOT_QA_PLUGIN_SMOKE_PACKAGE
-    || "skills/langbot-testing/fixtures/plugins/qa-plugin-smoke/dist/qa-plugin-smoke-0.1.0.lbpkg",
-);
-const expectedPluginId = env.LANGBOT_E2E_EXPECTED_PLUGIN_ID || "qa/plugin-smoke";
-const expectedTool = env.LANGBOT_E2E_EXPECTED_TOOL || (expectedPluginId === "qa/plugin-smoke" ? "qa_plugin_echo" : "");
-const expectedRunnerId = env.LANGBOT_E2E_EXPECTED_RUNNER_ID || "";
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  status: "fail",
-  reason: "",
-  backend_url: backendUrl,
-  package_path: packagePath,
-  package_preview: null,
-  task_id: null,
-  task: null,
-  plugin_present_before: false,
-  plugin_present_after: false,
-  tool_names: [],
-  runner_ids: [],
-  evidence: {
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["api_diagnostic", "filesystem"],
-};
-
-try {
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-  if (!user) throw new Error("LANGBOT_E2E_LOGIN_USER is required.");
-  const bytes = await readFile(packagePath);
-
-  const auth = await resetAndAuthLocalUser({ backendUrl, user, password });
-  result.package_preview = await previewPackage(backendUrl, auth.token, bytes, packagePath);
-  const metadata = result.package_preview.metadata || {};
-  if (`${metadata.author}/${metadata.name}` !== expectedPluginId) {
-    throw new Error(`Fixture package metadata is ${metadata.author}/${metadata.name}, expected ${expectedPluginId}.`);
-  }
-  result.plugin_present_before = await hasPlugin(backendUrl, auth.token);
-
-  if (!result.plugin_present_before) {
-    const form = new FormData();
-    form.set("file", new Blob([bytes]), packagePath.split("/").pop());
-    const response = await fetch(`${backendUrl.replace(/\/$/, "")}/api/v1/plugins/install/local`, {
-      method: "POST",
-      headers: { Authorization: `Bearer ${auth.token}` },
-      body: form,
-    });
-    const json = await response.json().catch(() => ({}));
-    if (response.status >= 400 || json.code !== 0) {
-      throw new Error(json.msg || `Plugin install request failed with HTTP ${response.status}.`);
-    }
-    result.task_id = json.data?.task_id ?? null;
-    if (!result.task_id) throw new Error("Plugin install response did not include task_id.");
-    result.task = await waitForTask(backendUrl, auth.token, result.task_id);
-    if (!isTaskComplete(result.task)) {
-      throw new Error(`Plugin install task did not complete successfully: ${JSON.stringify(result.task)}`);
-    }
-  }
-
-  await sleep(1000);
-  result.plugin_present_after = await hasPlugin(backendUrl, auth.token);
-  if (!result.plugin_present_after) throw new Error(`${expectedPluginId} is not listed by /api/v1/plugins after install.`);
-  if (expectedTool) {
-    result.tool_names = await listToolNames(backendUrl, auth.token);
-    if (!result.tool_names.includes(expectedTool)) {
-      throw new Error(`${expectedTool} is not listed by /api/v1/tools after install.`);
-    }
-  }
-  if (expectedRunnerId) {
-    result.runner_ids = await listRunnerIds(backendUrl, auth.token);
-    if (!result.runner_ids.includes(expectedRunnerId)) {
-      throw new Error(`${expectedRunnerId} is not listed by /api/v1/pipelines/_/metadata after install.`);
-    }
-  }
-
-  result.status = "pass";
-  result.reason = `${expectedPluginId} is installed.`;
-} catch (error) {
-  result.status = "fail";
-  result.reason = error.message;
-} finally {
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(result.status === "pass" ? 0 : 1);
-
-async function hasPlugin(backendUrl, token) {
-  const response = await apiJson(backendUrl, "/api/v1/plugins", { token });
-  const plugins = response.json.data?.plugins || [];
-  return plugins.some((plugin) => {
-    const metadata = plugin.manifest?.manifest?.metadata || plugin.manifest?.metadata || plugin.metadata || {};
-    return `${metadata.author}/${metadata.name}` === expectedPluginId;
-  });
-}
-
-async function previewPackage(backendUrl, token, bytes, packagePath) {
-  const form = new FormData();
-  form.set("file", new Blob([bytes]), packagePath.split("/").pop());
-  const response = await fetch(`${backendUrl.replace(/\/$/, "")}/api/v1/plugins/install/local/preview`, {
-    method: "POST",
-    headers: { Authorization: `Bearer ${token}` },
-    body: form,
-  });
-  const json = await response.json().catch(() => ({}));
-  if (response.status >= 400 || json.code !== 0) {
-    throw new Error(json.msg || `Plugin package preview failed with HTTP ${response.status}.`);
-  }
-  return {
-    metadata: json.data?.metadata || {},
-    component_types: json.data?.component_types || [],
-    file_count: json.data?.file_count ?? null,
-  };
-}
-
-async function listToolNames(backendUrl, token) {
-  const response = await apiJson(backendUrl, "/api/v1/tools", { token });
-  return (response.json.data?.tools || [])
-    .map((tool) => tool.name || tool.tool_name || tool.function?.name || "")
-    .filter(Boolean)
-    .sort();
-}
-
-async function listRunnerIds(backendUrl, token) {
-  const response = await apiJson(backendUrl, "/api/v1/pipelines/_/metadata", { token });
-  const configs = response.json.data?.configs || [];
-  return configs
-    .flatMap((section) => section.stages || [])
-    .flatMap((stage) => stage.config || [])
-    .filter((item) => item.name === "id")
-    .flatMap((item) => item.options || [])
-    .map((option) => option.name || option.value || option.id || "")
-    .filter(Boolean)
-    .sort();
-}
-
-async function waitForTask(backendUrl, token, taskId) {
-  const deadline = Date.now() + Number(env.LANGBOT_PLUGIN_INSTALL_TIMEOUT_MS || 120000);
-  let last = null;
-  while (Date.now() < deadline) {
-    const response = await apiJson(backendUrl, `/api/v1/system/tasks/${encodeURIComponent(taskId)}`, { token });
-    last = response.json.data || response.json;
-    if (isTaskComplete(last) || isTaskFailed(last)) return last;
-    await sleep(1000);
-  }
-  return last;
-}
-
-function isTaskComplete(task) {
-  const status = String(task?.status || task?.state || "").toLowerCase();
-  const runtimeStatus = String(task?.runtime?.status || task?.runtime?.state || "").toLowerCase();
-  return ["done", "completed", "success", "succeeded", "finished"].includes(status)
-    || ["done", "completed", "success", "succeeded", "finished"].includes(runtimeStatus)
-    || task?.done === true
-    || task?.completed === true
-    || (task?.runtime?.done === true && !task?.runtime?.exception);
-}
-
-function isTaskFailed(task) {
-  const status = String(task?.status || task?.state || "").toLowerCase();
-  const runtimeStatus = String(task?.runtime?.status || task?.runtime?.state || "").toLowerCase();
-  return ["failed", "error", "cancelled", "canceled"].includes(status)
-    || ["failed", "error", "cancelled", "canceled"].includes(runtimeStatus)
-    || task?.failed === true
-    || Boolean(task?.error)
-    || Boolean(task?.runtime?.exception);
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

skills/scripts/e2e/langrag-kb-retrieve.mjs

@@ -1,134 +0,0 @@
-#!/usr/bin/env node
-
-import {
-  bodyText,
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  isLoginUrl,
-  localIsoWithOffset,
-  safeScreenshot,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const caseId = process.env.LBS_CASE_ID || "langrag-kb-retrieve";
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const startedAt = new Date();
-const frontendUrl = process.env.LANGBOT_FRONTEND_URL || "";
-const backendUrl = process.env.LANGBOT_BACKEND_URL || "";
-const kbUuid = process.env.LANGBOT_LOCAL_AGENT_RAG_KB_UUID || process.env.LANGBOT_RAG_KB_UUID || "";
-const query = process.env.LANGBOT_E2E_RETRIEVE_QUERY || "What is the local agent runner retrieval sentinel?";
-const expectedText = process.env.LANGBOT_E2E_EXPECTED_TEXT || "azalea-cobalt-7421";
-
-let browser;
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  started_at: startedAt.toISOString(),
-  started_at_local: localIsoWithOffset(startedAt),
-  finished_at: "",
-  finished_at_local: "",
-  status: "fail",
-  reason: "",
-  url: "",
-  kb_uuid: kbUuid,
-  query,
-  expected_text: expectedText,
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["ui", "screenshot", "console", "network", "api_diagnostic"],
-};
-
-try {
-  if (!frontendUrl) throw new Error("LANGBOT_FRONTEND_URL is not configured.");
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-  if (!kbUuid) throw new Error("LANGBOT_LOCAL_AGENT_RAG_KB_UUID or LANGBOT_RAG_KB_UUID is required.");
-
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  await page.goto(`${frontendUrl.replace(/\/$/, "")}/home/knowledge`, { waitUntil: "domcontentloaded" });
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-  result.url = page.url();
-
-  const text = await bodyText(page);
-  if (isLoginUrl(page.url()) || /登录|Login|Sign in/i.test(text)) {
-    result.status = "blocked";
-    result.reason = "Browser profile is not authenticated for LANGBOT_FRONTEND_URL.";
-  } else if (!/Knowledge|知识库|qa-local-agent-rag/i.test(text)) {
-    result.status = "fail";
-    result.reason = "Knowledge page opened, but no Knowledge UI signal or QA KB name was visible.";
-  } else {
-    const retrieve = await page.evaluate(async ({ backendUrl, kbUuid, query }) => {
-      const token = localStorage.getItem("token");
-      if (!token) {
-        return { status: "blocked", authenticated: false, reason: "Browser profile has no localStorage token." };
-      }
-      const response = await fetch(`${backendUrl}/api/v1/knowledge/bases/${encodeURIComponent(kbUuid)}/retrieve`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ query }),
-      });
-      const json = await response.json().catch(() => ({}));
-      return {
-        status: response.status >= 400 ? "fail" : "ready",
-        authenticated: true,
-        http_status: response.status,
-        code: json.code ?? null,
-        msg: json.msg || "",
-        results: json.data?.results || [],
-      };
-    }, { backendUrl, kbUuid, query });
-
-    result.retrieve = {
-      ...retrieve,
-      results: Array.isArray(retrieve.results)
-        ? retrieve.results.map((item) => ({
-            score: item.score ?? item.distance ?? null,
-            text: String(item.text || item.content || "").slice(0, 500),
-            metadata: item.metadata || {},
-          }))
-        : [],
-    };
-
-    const resultText = JSON.stringify(result.retrieve.results || []);
-    if (retrieve.status === "blocked") {
-      result.status = "blocked";
-      result.reason = retrieve.reason || "Retrieve API blocked.";
-    } else if (retrieve.status === "fail") {
-      result.status = "fail";
-      result.reason = retrieve.msg || "Retrieve API failed.";
-    } else if (!resultText.includes(expectedText)) {
-      result.status = "fail";
-      result.reason = `Retrieve results did not contain expected text: ${expectedText}`;
-    } else {
-      result.status = "pass";
-      result.reason = `Knowledge retrieve returned expected sentinel: ${expectedText}`;
-    }
-  }
-
-  await safeScreenshot(page, paths.screenshot);
-} catch (error) {
-  result.status = /Playwright is not installed|not configured|required/.test(error.message) ? "env_issue" : "fail";
-  result.reason = error.message;
-} finally {
-  if (browser) await browser.close().catch(() => {});
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));

skills/scripts/e2e/lib/debug-chat.mjs

@@ -1,416 +0,0 @@
-import {
-  bodyText,
-  clickFirstVisible,
-  countOccurrences,
-  gotoFrontend,
-  isLoginUrl,
-} from "./langbot-e2e.mjs";
-
-export const DEBUG_CHAT_FAILURE_SIGNALS = [
-  "Agent runner temporarily unavailable",
-  "All models failed during streaming setup",
-  "调用超时",
-  "超时",
-];
-
-export function minExpectedOccurrences(beforeText, expectedText, prompt) {
-  const beforeCount = countOccurrences(beforeText, expectedText);
-  return beforeCount + (String(prompt).includes(expectedText) ? 2 : 1);
-}
-
-export function latestExpectedLeafMatches(latestExpectedLeaf, prompt) {
-  return Boolean(latestExpectedLeaf)
-    && latestExpectedLeaf !== prompt
-    && !String(latestExpectedLeaf).includes(prompt);
-}
-
-export function findNewFailureSignal(beforeText, afterText, failureSignals = DEBUG_CHAT_FAILURE_SIGNALS) {
-  return failureSignals.find((signal) => countOccurrences(afterText, signal) > countOccurrences(beforeText, signal)) || "";
-}
-
-function findFailureSignalInText(text, failureSignals = DEBUG_CHAT_FAILURE_SIGNALS) {
-  return failureSignals.find((signal) => String(text || "").includes(signal)) || "";
-}
-
-function countExpectedInMessages(messages, expectedText) {
-  return messages
-    .filter((message) => message.role === "assistant")
-    .reduce((count, message) => count + countOccurrences(message.text, expectedText), 0);
-}
-
-function debugChatInput(page) {
-  return page
-    .locator('input[placeholder*="message"], input[placeholder*="消息"], textarea[placeholder*="message"], textarea[placeholder*="消息"]')
-    .last();
-}
-
-async function clickDebugChatTab(page) {
-  const tabByRole = page.getByRole("tab", { name: /Debug Chat|调试聊天|调试对话|Debug|调试/i }).first();
-  if (await tabByRole.isVisible({ timeout: 3_000 }).catch(() => false)) {
-    await tabByRole.click();
-    return true;
-  }
-
-  const tabBySelector = page.locator('[role="tab"]').filter({ hasText: /Debug Chat|调试聊天|调试对话|Debug|调试/i }).first();
-  if (await tabBySelector.isVisible({ timeout: 2_000 }).catch(() => false)) {
-    await tabBySelector.click();
-    return true;
-  }
-
-  return Boolean(await clickFirstVisible(page, ["Debug Chat", "调试聊天", "调试对话"], 2_000));
-}
-
-async function waitForDebugChatReady(page, timeout = 20_000) {
-  const input = debugChatInput(page);
-  const visible = await input.isVisible({ timeout }).catch(() => false);
-  if (!visible) {
-    return {
-      ready: false,
-      reason: "Debug Chat tab was clicked, but the Debug Chat input did not become visible.",
-    };
-  }
-
-  const enabled = await input.isEnabled({ timeout }).catch(() => false);
-  if (!enabled) {
-    return {
-      ready: false,
-      reason: "Debug Chat input is visible but disabled; WebSocket may not be connected.",
-    };
-  }
-
-  return { ready: true, reason: "" };
-}
-
-export function classifyDebugChatResult({
-  beforeText,
-  afterText,
-  expectedText,
-  prompt,
-  latestExpectedLeaf,
-  latestFailureLeaf,
-  beforeMessages = null,
-  afterMessages = null,
-  latestAssistantText = "",
-  failureSignals = DEBUG_CHAT_FAILURE_SIGNALS,
-}) {
-  const minExpectedCount = minExpectedOccurrences(beforeText, expectedText, prompt);
-  const finalCount = countOccurrences(afterText, expectedText);
-  const failureText = findNewFailureSignal(beforeText, afterText, failureSignals);
-  const promptContainsExpected = String(prompt).includes(expectedText);
-  const hasMessageEvidence = Array.isArray(beforeMessages) && Array.isArray(afterMessages);
-  const beforeAssistantExpectedCount = hasMessageEvidence
-    ? countExpectedInMessages(beforeMessages, expectedText)
-    : null;
-  const afterAssistantExpectedCount = hasMessageEvidence
-    ? countExpectedInMessages(afterMessages, expectedText)
-    : null;
-  const assistantExpectedIncreased = hasMessageEvidence
-    ? afterAssistantExpectedCount > beforeAssistantExpectedCount
-    : false;
-
-  if (hasMessageEvidence) {
-    const latestAssistantFailure = findFailureSignalInText(latestAssistantText, failureSignals);
-    if (latestAssistantFailure) {
-      return {
-        status: "fail",
-        reason: `Debug Chat displayed a known failure signal in the latest assistant message: ${latestAssistantFailure}`,
-        min_expected_count: minExpectedCount,
-        final_count: finalCount,
-        failure_signal: latestAssistantFailure,
-        before_assistant_expected_count: beforeAssistantExpectedCount,
-        after_assistant_expected_count: afterAssistantExpectedCount,
-      };
-    }
-    if (assistantExpectedIncreased && String(latestAssistantText).includes(expectedText)) {
-      return {
-        status: "pass",
-        reason: `Expected text appeared in a new assistant message: ${expectedText}`,
-        min_expected_count: minExpectedCount,
-        final_count: finalCount,
-        before_assistant_expected_count: beforeAssistantExpectedCount,
-        after_assistant_expected_count: afterAssistantExpectedCount,
-      };
-    }
-    if (failureText) {
-      return {
-        status: "fail",
-        reason: `Debug Chat displayed a known failure signal: ${failureText}`,
-        min_expected_count: minExpectedCount,
-        final_count: finalCount,
-        failure_signal: failureText,
-        before_assistant_expected_count: beforeAssistantExpectedCount,
-        after_assistant_expected_count: afterAssistantExpectedCount,
-      };
-    }
-    return {
-      status: "fail",
-      reason: `Expected text did not appear in a new assistant message. Expected assistant occurrences to increase above ${beforeAssistantExpectedCount}, saw ${afterAssistantExpectedCount}.`,
-      min_expected_count: minExpectedCount,
-      final_count: finalCount,
-      before_assistant_expected_count: beforeAssistantExpectedCount,
-      after_assistant_expected_count: afterAssistantExpectedCount,
-    };
-  }
-  if (failureText) {
-    return {
-      status: "fail",
-      reason: `Debug Chat displayed a known failure signal: ${failureText}`,
-      min_expected_count: minExpectedCount,
-      final_count: finalCount,
-      failure_signal: failureText,
-      before_assistant_expected_count: beforeAssistantExpectedCount,
-      after_assistant_expected_count: afterAssistantExpectedCount,
-    };
-  }
-  if (latestExpectedLeafMatches(latestExpectedLeaf, prompt) && finalCount >= minExpectedCount) {
-    return {
-      status: "pass",
-      reason: `Expected text appeared in the latest visible response leaf: ${expectedText}`,
-      min_expected_count: minExpectedCount,
-      final_count: finalCount,
-    };
-  }
-  if (!promptContainsExpected && finalCount >= minExpectedCount) {
-    return {
-      status: "pass",
-      reason: `Expected text appeared enough times for user prompt plus bot response: ${expectedText}`,
-      min_expected_count: minExpectedCount,
-      final_count: finalCount,
-    };
-  }
-  return {
-    status: "fail",
-    reason: `Bot response did not appear. Expected ${minExpectedCount} occurrences of ${expectedText}, saw ${finalCount}.`,
-    min_expected_count: minExpectedCount,
-    final_count: finalCount,
-  };
-}
-
-export async function openPipelineDebugChat(page, { pipelineUrl, pipelineName, envHint = "LANGBOT_PIPELINE_URL or LANGBOT_PIPELINE_NAME" }) {
-  if (pipelineUrl) {
-    await page.goto(pipelineUrl, { waitUntil: "domcontentloaded" });
-    await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-  } else {
-    if (!pipelineName) {
-      return {
-        opened: false,
-        status: "blocked",
-        reason: `Set ${envHint} before running pipeline-debug-chat automation.`,
-      };
-    }
-    await gotoFrontend(page);
-    if (isLoginUrl(page.url())) {
-      return {
-        opened: false,
-        status: "blocked",
-        reason: "Browser profile is not authenticated for LANGBOT_FRONTEND_URL.",
-      };
-    }
-    const clickedPipelines = await clickFirstVisible(page, ["Pipelines", "流水线"], 4_000);
-    if (!clickedPipelines) {
-      return { opened: false, status: "fail", reason: "Could not find Pipelines navigation." };
-    }
-    await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-    const clickedPipeline = await clickFirstVisible(page, [pipelineName], 5_000);
-    if (!clickedPipeline) {
-      return { opened: false, status: "blocked", reason: `Could not find pipeline named ${pipelineName}.` };
-    }
-  }
-
-  if (isLoginUrl(page.url())) {
-    return {
-      opened: false,
-      status: "blocked",
-      reason: "Browser profile is not authenticated for LANGBOT_FRONTEND_URL.",
-    };
-  }
-
-  const clickedDebug = await clickDebugChatTab(page);
-  if (!clickedDebug) {
-    return { opened: false, status: "fail", reason: "Could not find the Debug Chat tab." };
-  }
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-  const ready = await waitForDebugChatReady(page);
-  if (!ready.ready) {
-    return { opened: false, status: "fail", reason: ready.reason };
-  }
-  return { opened: true };
-}
-
-export async function latestVisibleLeafText(page, needles) {
-  return await page.evaluate((items) => {
-    const isVisible = (element) => {
-      const style = window.getComputedStyle(element);
-      const rect = element.getBoundingClientRect();
-      return style.visibility !== "hidden"
-        && style.display !== "none"
-        && rect.width > 0
-        && rect.height > 0;
-    };
-    const leaves = [];
-    for (const element of document.body.querySelectorAll("*")) {
-      if (!isVisible(element)) continue;
-      const text = element.innerText?.trim();
-      if (!text || text.length > 4000) continue;
-      const visibleChildHasText = Array.from(element.children).some((child) => (
-        isVisible(child) && child.innerText?.trim()
-      ));
-      if (visibleChildHasText) continue;
-      if (!items.some((needle) => text.includes(needle))) continue;
-      leaves.push(text);
-    }
-    return leaves.at(-1) || "";
-  }, needles);
-}
-
-export async function visibleDebugChatMessages(page) {
-  return await page.evaluate(() => {
-    const isVisible = (element) => {
-      const style = window.getComputedStyle(element);
-      const rect = element.getBoundingClientRect();
-      return style.visibility !== "hidden"
-        && style.display !== "none"
-        && rect.width > 0
-        && rect.height > 0;
-    };
-    const classText = (element) => String(element.getAttribute("class") || "");
-    return Array.from(document.querySelectorAll("div.max-w-3xl"))
-      .filter((element) => isVisible(element))
-      .map((element) => {
-        const row = element.parentElement;
-        const text = element.innerText?.trim() || "";
-        const isUser = classText(element).includes("user-message-bubble")
-          || classText(row).includes("justify-end");
-        return {
-          role: isUser ? "user" : "assistant",
-          text,
-        };
-      })
-      .filter((message) => message.text);
-  });
-}
-
-export async function waitForExpectedDebugChatText(page, { expectedText, minExpectedCount, timeoutMs }) {
-  await page.waitForFunction(
-    ({ expected, min }) => {
-      return document.body.innerText.split(expected).length - 1 >= min;
-    },
-    { expected: expectedText, min: minExpectedCount },
-    { timeout: timeoutMs },
-  ).catch(() => {});
-}
-
-export async function waitForDebugChatTextStable(page, { timeoutMs = 5_000, quietMs = 750 } = {}) {
-  const startedAt = Date.now();
-  let lastText = await bodyText(page);
-  let stableSince = Date.now();
-  while (Date.now() - startedAt < timeoutMs) {
-    await page.waitForTimeout(250);
-    const currentText = await bodyText(page);
-    if (currentText !== lastText) {
-      lastText = currentText;
-      stableSince = Date.now();
-      continue;
-    }
-    if (Date.now() - stableSince >= quietMs) return;
-  }
-}
-
-export async function attachDebugChatImage(page, imagePath) {
-  if (!imagePath) return { status: "not_required", reason: "" };
-  const input = page.locator('input[type="file"][accept*="image"], input[type="file"]').first();
-  if (!await input.count()) {
-    return { status: "fail", reason: "Could not find a Debug Chat image upload input." };
-  }
-  await input.setInputFiles(imagePath);
-  await page.locator("img").last().waitFor({ state: "visible", timeout: 10_000 }).catch(() => {});
-  return { status: "ready", reason: `Attached image fixture: ${imagePath}` };
-}
-
-export async function sendDebugChatPrompt(page, prompt, imagePath = "") {
-  const imageResult = await attachDebugChatImage(page, imagePath);
-  if (imageResult.status === "fail") return imageResult;
-
-  const input = debugChatInput(page);
-  const inputVisible = await input.isVisible({ timeout: 5_000 }).catch(() => false);
-  const inputEnabled = inputVisible && await input.isEnabled({ timeout: 10_000 }).catch(() => false);
-  if (!inputVisible || !inputEnabled) return false;
-  await input.fill(prompt).catch(async () => {
-    await input.click();
-    await input.pressSequentially(prompt);
-  });
-  const clickedSend = await clickFirstVisible(page, ["Send", "发送", "提交"], 1_500);
-  if (!clickedSend) await page.keyboard.press("Enter");
-  await page.getByText(prompt, { exact: false }).last().waitFor({ state: "visible", timeout: 10_000 }).catch(() => {});
-  return true;
-}
-
-export async function runDebugChatPrompt(page, { prompt, expectedText, responseTimeoutMs, imagePath = "", failureSignals = DEBUG_CHAT_FAILURE_SIGNALS }) {
-  const beforeText = await bodyText(page);
-  const beforeMessages = await visibleDebugChatMessages(page);
-  const minExpectedCount = minExpectedOccurrences(beforeText, expectedText, prompt);
-  const sent = await sendDebugChatPrompt(page, prompt, imagePath);
-  if (sent !== true) {
-    if (sent && typeof sent === "object" && typeof sent.reason === "string") return sent;
-    return { status: "fail", reason: "Could not find a Debug Chat text input." };
-  }
-
-  await waitForExpectedDebugChatText(page, {
-    expectedText,
-    minExpectedCount,
-    prompt,
-    timeoutMs: responseTimeoutMs,
-  });
-  await waitForDebugChatTextStable(page);
-
-  const afterText = await bodyText(page);
-  const afterMessages = await visibleDebugChatMessages(page);
-  const latestAssistantText = afterMessages.filter((message) => message.role === "assistant").at(-1)?.text || "";
-  const latestExpectedLeaf = await latestVisibleLeafText(page, [expectedText]);
-  const failureText = findNewFailureSignal(beforeText, afterText, failureSignals);
-  const latestFailureLeaf = failureText ? await latestVisibleLeafText(page, [failureText]) : "";
-
-  return classifyDebugChatResult({
-    beforeText,
-    afterText,
-    expectedText,
-    prompt,
-    latestExpectedLeaf,
-    latestFailureLeaf,
-    beforeMessages,
-    afterMessages,
-    latestAssistantText,
-    failureSignals,
-  });
-}
-
-export async function setDebugChatStreamOutput(page, desired) {
-  if (desired === null || desired === undefined) return { status: "not_required", reason: "" };
-
-  const streamSwitch = page.locator('[role="switch"]').first();
-  if (!await streamSwitch.isVisible({ timeout: 5_000 }).catch(() => false)) {
-    return { status: "blocked", reason: "Debug Chat stream switch was not visible." };
-  }
-  if (!await streamSwitch.isEnabled({ timeout: 10_000 }).catch(() => false)) {
-    return { status: "blocked", reason: "Debug Chat stream switch was visible but disabled." };
-  }
-
-  const checked = (await streamSwitch.getAttribute("aria-checked").catch(() => null)) === "true";
-  if (checked !== desired) {
-    await streamSwitch.click();
-    await page.waitForFunction(
-      ({ selector, expected }) => document.querySelector(selector)?.getAttribute("aria-checked") === String(expected),
-      { selector: '[role="switch"]', expected: desired },
-      { timeout: 5_000 },
-    ).catch(() => {});
-  }
-
-  const finalChecked = (await streamSwitch.getAttribute("aria-checked").catch(() => null)) === "true";
-  if (finalChecked !== desired) {
-    return {
-      status: "fail",
-      reason: `Debug Chat stream switch did not reach requested state: ${desired ? "on" : "off"}.`,
-    };
-  }
-  return { status: "ready", reason: `Debug Chat stream switch is ${desired ? "on" : "off"}.` };
-}

skills/scripts/e2e/lib/langbot-e2e.mjs

@@ -1,341 +0,0 @@
-import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { env } from "node:process";
-
-const secretRe = /(?:authorization|bearer|token|secret|password|api[_-]?key|jwt|oauth)\s*[:=]\s*["']?[^"',\s]+/gi;
-
-export function redact(text) {
-  return String(text ?? "")
-    .replace(secretRe, (match) => match.replace(/[:=]\s*["']?.*$/, "=[redacted]"))
-    .replace(/\bbearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer [redacted]")
-    .replace(/\bsk-[A-Za-z0-9_-]{6,}\b/g, "[redacted]");
-}
-
-export function timestampSlug(date = new Date()) {
-  return date.toISOString().replace(/\.\d{3}Z$/, "Z").replace(/[^0-9A-Za-z]+/g, "-").replace(/^-|-$/g, "");
-}
-
-export function localIsoWithOffset(date = new Date()) {
-  const offsetMinutes = -date.getTimezoneOffset();
-  const sign = offsetMinutes >= 0 ? "+" : "-";
-  const absolute = Math.abs(offsetMinutes);
-  const pad = (value) => String(value).padStart(2, "0");
-  const yyyy = date.getFullYear();
-  const mm = pad(date.getMonth() + 1);
-  const dd = pad(date.getDate());
-  const hh = pad(date.getHours());
-  const mi = pad(date.getMinutes());
-  const ss = pad(date.getSeconds());
-  const ms = String(date.getMilliseconds()).padStart(3, "0");
-  return `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}.${ms}${sign}${pad(Math.floor(absolute / 60))}:${pad(absolute % 60)}`;
-}
-
-export function evidencePaths(caseId) {
-  const runId = env.LBS_RUN_ID || `${timestampSlug()}-${caseId}`;
-  const evidenceDir = resolve(env.LBS_EVIDENCE_DIR || join("reports", "evidence", runId));
-  return {
-    runId,
-    evidenceDir,
-    consoleLog: join(evidenceDir, "console.log"),
-    networkLog: join(evidenceDir, "network.log"),
-    screenshot: join(evidenceDir, "screenshot.png"),
-    automationResultJson: join(evidenceDir, "automation-result.json"),
-    resultJson: join(evidenceDir, "result.json"),
-  };
-}
-
-export async function ensureEvidence(paths) {
-  await mkdir(paths.evidenceDir, { recursive: true });
-  await appendFile(paths.consoleLog, "", "utf8");
-  await appendFile(paths.networkLog, "", "utf8");
-}
-
-export async function pathExists(path) {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function appendLine(path, line) {
-  await appendFile(path, `[${localIsoWithOffset()}] ${redact(line)}\n`, "utf8");
-}
-
-export async function writeResult(paths, result) {
-  const text = `${JSON.stringify(result, null, 2)}\n`;
-  if (paths.automationResultJson) await writeFile(paths.automationResultJson, text, "utf8");
-  if (paths.resultJson && paths.resultJson !== paths.automationResultJson) {
-    await writeFile(paths.resultJson, text, "utf8");
-  }
-}
-
-export async function loadEnvFiles(paths = ["skills/.env", "skills/.env.local"]) {
-  for (const path of paths) {
-    let text = "";
-    try {
-      text = await readFile(path, "utf8");
-    } catch {
-      continue;
-    }
-    for (const line of text.split(/\r?\n/)) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const equals = trimmed.indexOf("=");
-      if (equals <= 0) continue;
-      const key = trimmed.slice(0, equals).trim();
-      const value = trimmed.slice(equals + 1).trim().replace(/^["']|["']$/g, "");
-      if (!(key in env)) env[key] = value;
-    }
-  }
-}
-
-export async function readRecoveryKey(repo = env.LANGBOT_REPO || "../LangBot") {
-  const configPath = resolve(repo, "data/config.yaml");
-  const config = await readFile(configPath, "utf8");
-  const match = config.match(/^\s*recovery_key:\s*['"]?([^'"\s#]+)['"]?\s*$/m);
-  return match?.[1] || "";
-}
-
-export async function apiJson(backendUrl, path, { method = "GET", token = "", body } = {}) {
-  const headers = { "Content-Type": "application/json" };
-  if (token) headers.Authorization = `Bearer ${token}`;
-  const response = await fetch(`${backendUrl.replace(/\/$/, "")}${path}`, {
-    method,
-    headers,
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  return {
-    status: response.status,
-    json: await response.json().catch(() => ({})),
-  };
-}
-
-export async function checkBackendToken(backendUrl, token) {
-  if (!token) {
-    return { authenticated: false, http_status: 0, code: null, reason: "No token." };
-  }
-  const response = await apiJson(backendUrl, "/api/v1/user/check-token", { token });
-  const code = response.json.code ?? null;
-  const authenticated = response.status < 400 && code === 0;
-  return {
-    authenticated,
-    http_status: response.status,
-    code,
-    reason: authenticated ? "Token accepted by backend." : response.json.msg || "Backend rejected token.",
-  };
-}
-
-export async function resetAndAuthLocalUser({ backendUrl, user, password, recoveryKey = "" }) {
-  const key = recoveryKey || await readRecoveryKey();
-  if (!key) throw new Error("Could not read recovery_key from LangBot config.");
-
-  const reset = await apiJson(backendUrl, "/api/v1/user/reset-password", {
-    method: "POST",
-    body: {
-      user,
-      recovery_key: key,
-      new_password: password,
-    },
-  });
-  if (reset.status >= 400 || reset.json.code !== 0) {
-    throw new Error(reset.json.msg || `Password reset failed with HTTP ${reset.status}.`);
-  }
-
-  const auth = await apiJson(backendUrl, "/api/v1/user/auth", {
-    method: "POST",
-    body: { user, password },
-  });
-  const token = auth.json.data?.token || "";
-  if (auth.status >= 400 || auth.json.code !== 0 || !token) {
-    throw new Error(auth.json.msg || `Auth failed with HTTP ${auth.status}.`);
-  }
-
-  const check = await checkBackendToken(backendUrl, token);
-  if (!check.authenticated) {
-    throw new Error(check.reason || "Authenticated token failed backend token check.");
-  }
-
-  return { token, check };
-}
-
-export async function setBrowserToken(page, frontendUrl, token) {
-  await page.addInitScript((value) => {
-    localStorage.setItem("token", value);
-  }, token);
-  await page.goto(frontendUrl, { waitUntil: "domcontentloaded" });
-  await page.evaluate((value) => localStorage.setItem("token", value), token);
-}
-
-export async function verifyBrowserToken(page, backendUrl) {
-  return await page.evaluate(async (baseUrl) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return { authenticated: false, http_status: 0, code: null, reason: "No localStorage token." };
-    }
-    try {
-      const response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/user/check-token`, {
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-      });
-      const json = await response.json().catch(() => ({}));
-      const code = json.code ?? null;
-      const authenticated = response.status < 400 && code === 0;
-      return {
-        authenticated,
-        http_status: response.status,
-        code,
-        reason: authenticated ? "Token accepted by backend." : json.msg || "Backend rejected token.",
-      };
-    } catch (error) {
-      return {
-        authenticated: false,
-        http_status: 0,
-        code: null,
-        reason: error.message,
-      };
-    }
-  }, backendUrl);
-}
-
-export function exitCode(status) {
-  if (status === "pass") return 0;
-  if (status === "blocked" || status === "env_issue") return 2;
-  return 1;
-}
-
-export async function loadPlaywright() {
-  try {
-    return await import("playwright");
-  } catch {
-    throw new Error(
-      "Playwright is not installed. Install it in this repo with `npm install --save-dev playwright`, then run `npx playwright install chromium`.",
-    );
-  }
-}
-
-export async function createBrowser(paths) {
-  const { chromium } = await loadPlaywright();
-  const headed = env.LBS_HEADED === "1";
-  const launchOptions = {
-    headless: !headed,
-  };
-  if (env.LANGBOT_CHROMIUM_EXECUTABLE && await pathExists(env.LANGBOT_CHROMIUM_EXECUTABLE)) {
-    launchOptions.executablePath = env.LANGBOT_CHROMIUM_EXECUTABLE;
-  }
-
-  let browser;
-  let context;
-  if (env.LANGBOT_BROWSER_PROFILE) {
-    context = await chromium.launchPersistentContext(resolve(env.LANGBOT_BROWSER_PROFILE), {
-      ...launchOptions,
-      viewport: { width: 1440, height: 960 },
-    });
-  } else {
-    browser = await chromium.launch(launchOptions);
-    context = await browser.newContext({ viewport: { width: 1440, height: 960 } });
-  }
-  const page = context.pages()[0] || await context.newPage();
-
-  page.on("console", (message) => {
-    appendLine(paths.consoleLog, `[${message.type()}] ${message.text()}`).catch(() => {});
-  });
-  page.on("pageerror", (error) => {
-    appendLine(paths.consoleLog, `[pageerror] ${error.message}`).catch(() => {});
-  });
-  page.on("requestfailed", (request) => {
-    appendLine(paths.networkLog, `[requestfailed] ${request.method()} ${request.url()} ${request.failure()?.errorText ?? ""}`).catch(() => {});
-  });
-  page.on("response", (response) => {
-    if (response.status() < 400) return;
-    appendLine(paths.networkLog, `[response] ${response.status()} ${response.url()}`).catch(() => {});
-  });
-
-  return {
-    page,
-    context,
-    async close() {
-      await context.close();
-      if (browser) await browser.close();
-    },
-  };
-}
-
-export async function safeScreenshot(page, path) {
-  try {
-    await page.screenshot({ path, fullPage: true });
-  } catch {
-    // Screenshot evidence is useful, but a screenshot failure should not hide the real test result.
-  }
-}
-
-export async function gotoFrontend(page) {
-  const frontendUrl = env.LANGBOT_FRONTEND_URL;
-  if (!frontendUrl) {
-    throw new Error("LANGBOT_FRONTEND_URL is not configured.");
-  }
-  await page.goto(frontendUrl, { waitUntil: "domcontentloaded" });
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-}
-
-export function isLoginUrl(url) {
-  return /\/login(?:[/?#]|$)/.test(url);
-}
-
-export async function bodyText(page) {
-  return await page.locator("body").innerText({ timeout: 5_000 }).catch(() => "");
-}
-
-export function countOccurrences(haystack, needle) {
-  if (!needle) return 0;
-  return String(haystack).split(needle).length - 1;
-}
-
-export async function clickFirstVisible(page, labels, timeout = 2_000) {
-  for (const label of labels) {
-    const roleButton = page.getByRole("button", { name: label }).first();
-    if (await roleButton.isVisible({ timeout }).catch(() => false)) {
-      await roleButton.click();
-      return label;
-    }
-
-    const roleLink = page.getByRole("link", { name: label }).first();
-    if (await roleLink.isVisible({ timeout }).catch(() => false)) {
-      await roleLink.click();
-      return label;
-    }
-
-    const text = page.getByText(label, { exact: false }).first();
-    if (await text.isVisible({ timeout }).catch(() => false)) {
-      await text.click();
-      return label;
-    }
-  }
-  return null;
-}
-
-export async function fillFirstTextInput(page, value) {
-  const candidates = [
-    page.getByRole("textbox").last(),
-    page.locator("textarea").last(),
-    page.locator("[contenteditable=true]").last(),
-    page.locator("input[type=text]").last(),
-  ];
-
-  for (const locator of candidates) {
-    if (!await locator.isVisible({ timeout: 2_000 }).catch(() => false)) continue;
-    await locator.fill(value).catch(async () => {
-      await locator.click();
-      await locator.pressSequentially(value);
-    });
-    return true;
-  }
-  return false;
-}
-
-export async function waitForVisibleText(page, text, timeout = 20_000) {
-  await page.getByText(text, { exact: false }).last().waitFor({ state: "visible", timeout });
-}

skills/scripts/e2e/local-agent-steering-debug-chat.mjs

@@ -1,565 +0,0 @@
-#!/usr/bin/env node
-
-import { writeFile } from "node:fs/promises";
-import { env } from "node:process";
-import {
-  DEBUG_CHAT_FAILURE_SIGNALS,
-  openPipelineDebugChat,
-  setDebugChatStreamOutput,
-  visibleDebugChatMessages,
-  waitForDebugChatTextStable,
-} from "./lib/debug-chat.mjs";
-import {
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  localIsoWithOffset,
-  loadEnvFiles,
-  pathExists,
-  safeScreenshot,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-await loadEnvFiles();
-
-const caseId = env.LBS_CASE_ID || "local-agent-steering-debug-chat";
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const backendUrl = (env.LANGBOT_BACKEND_URL || "").replace(/\/$/, "");
-const pipelineUrl = env.LANGBOT_E2E_PIPELINE_URL || env.LANGBOT_LOCAL_AGENT_PIPELINE_URL || env.LANGBOT_PIPELINE_URL || "";
-const pipelineName = env.LANGBOT_E2E_PIPELINE_NAME || env.LANGBOT_LOCAL_AGENT_PIPELINE_NAME || env.LANGBOT_PIPELINE_NAME || "";
-const expectedRunnerId = env.LANGBOT_E2E_EXPECTED_RUNNER_ID || "plugin:langbot/local-agent/default";
-const expectedText = env.LANGBOT_E2E_EXPECTED_TEXT || "qa_steering_sentinel_6194";
-const responseTimeoutMs = positiveInt(env.LANGBOT_E2E_RESPONSE_TIMEOUT_MS, 240000);
-const followupDelayMs = 1000;
-const followupEnabledTimeoutMs = 1500;
-const firstPrompt = env.LANGBOT_E2E_PROMPT || [
-  "You are running the LangBot steering E2E test.",
-  "First call the qa_plugin_sleep tool with seconds=8 and text=steering-e2e-anchor.",
-  "Do not answer before the tool result is available.",
-  "After the tool returns, answer the latest user follow-up.",
-  "If no follow-up was injected, reply only STEERING_NO_FOLLOWUP.",
-].join(" ");
-const followupPrompt = [
-  "This is a steering follow-up sent while the first tool call is still active.",
-  `Return only ${expectedText}.`,
-].join(" ");
-
-const pipelineConfigDiagnosticPath = `${paths.evidenceDir}/pipeline-config-diagnostic.json`;
-const debugChatResetDiagnosticPath = `${paths.evidenceDir}/debug-chat-reset-diagnostic.json`;
-const toolDiagnosticPath = `${paths.evidenceDir}/tool-diagnostic.json`;
-
-let browser;
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  status: "fail",
-  reason: "",
-  started_at: new Date().toISOString(),
-  started_at_local: localIsoWithOffset(new Date()),
-  url: "",
-  backend_url: backendUrl,
-  pipeline_url: pipelineUrl,
-  pipeline_name: pipelineName,
-  expected_runner_id: expectedRunnerId,
-  first_prompt: firstPrompt,
-  followup_prompt: followupPrompt,
-  expected_text: expectedText,
-  followup_delay_ms: followupDelayMs,
-  followup_enabled_timeout_ms: followupEnabledTimeoutMs,
-  response_timeout_ms: responseTimeoutMs,
-  pipeline_config: null,
-  debug_chat_reset: null,
-  tool_diagnostic: null,
-  steering: null,
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["ui", "console", "network", "screenshot"],
-};
-
-try {
-  if (!backendUrl) {
-    result.status = "env_issue";
-    result.reason = "LANGBOT_BACKEND_URL is required.";
-    throw new Error(result.reason);
-  }
-
-  browser = await createBrowser(paths);
-  const { page } = browser;
-
-  const openResult = await openPipelineDebugChat(page, {
-    pipelineUrl,
-    pipelineName,
-    envHint: "case-specific pipeline env mapped to LANGBOT_E2E_PIPELINE_URL or LANGBOT_E2E_PIPELINE_NAME",
-  });
-  result.url = page.url();
-  if (!openResult.opened) {
-    result.status = openResult.status;
-    result.reason = openResult.reason;
-  } else {
-    const pipelineDiagnostic = await inspectPipeline(page, {
-      backendUrl,
-      pipelineUrl,
-      pipelineName,
-      expectedRunnerId,
-    });
-    await writeFile(pipelineConfigDiagnosticPath, `${JSON.stringify(pipelineDiagnostic, null, 2)}\n`, "utf8");
-    result.evidence.pipeline_config_diagnostic_json = pipelineConfigDiagnosticPath;
-    result.pipeline_config = pipelineDiagnostic;
-    if (!result.evidence_collected.includes("api_diagnostic")) result.evidence_collected.push("api_diagnostic");
-
-    const toolDiagnostic = await inspectToolNames(page, { backendUrl });
-    await writeFile(toolDiagnosticPath, `${JSON.stringify(toolDiagnostic, null, 2)}\n`, "utf8");
-    result.evidence.tool_diagnostic_json = toolDiagnosticPath;
-    result.tool_diagnostic = toolDiagnostic;
-
-    if (pipelineDiagnostic.status === "fail" || pipelineDiagnostic.status === "blocked") {
-      result.status = pipelineDiagnostic.status;
-      result.reason = pipelineDiagnostic.reason || "Pipeline diagnostic failed.";
-    } else if (toolDiagnostic.status === "fail" || toolDiagnostic.status === "blocked") {
-      result.status = toolDiagnostic.status;
-      result.reason = toolDiagnostic.reason || "Tool diagnostic failed.";
-    } else if (!toolDiagnostic.tool_names.includes("qa_plugin_sleep")) {
-      result.status = "blocked";
-      result.reason = "qa_plugin_sleep is not exposed by /api/v1/tools; rebuild/reinstall qa-plugin-smoke before running steering E2E.";
-    } else {
-      const resetDiagnostic = await resetPipelineDebugChat(page, {
-        backendUrl,
-        pipelineId: pipelineDiagnostic.pipeline_id,
-        sessionType: "person",
-      });
-      await writeFile(debugChatResetDiagnosticPath, `${JSON.stringify(resetDiagnostic, null, 2)}\n`, "utf8");
-      result.evidence.debug_chat_reset_diagnostic_json = debugChatResetDiagnosticPath;
-      result.debug_chat_reset = resetDiagnostic;
-
-      if (resetDiagnostic.status === "fail" || resetDiagnostic.status === "blocked") {
-        result.status = resetDiagnostic.status;
-        result.reason = resetDiagnostic.reason || "Debug Chat reset failed.";
-      } else {
-        await page.waitForTimeout(1000);
-        const reopenResult = await openPipelineDebugChat(page, {
-          pipelineUrl,
-          pipelineName,
-          envHint: "case-specific pipeline env mapped to LANGBOT_E2E_PIPELINE_URL or LANGBOT_E2E_PIPELINE_NAME",
-        });
-        result.url = page.url();
-        if (!reopenResult.opened) {
-          result.status = reopenResult.status;
-          result.reason = reopenResult.reason;
-        } else {
-          const streamResult = await setDebugChatStreamOutput(page, true);
-          if (streamResult.status === "blocked" || streamResult.status === "fail") {
-            result.status = streamResult.status;
-            result.reason = streamResult.reason;
-          } else {
-            result.steering = await runSteeringProbe(page);
-            result.status = result.steering.status;
-            result.reason = result.steering.reason;
-          }
-        }
-      }
-    }
-  }
-} catch (error) {
-  if (!["env_issue", "blocked", "fail", "pass"].includes(result.status) || !result.reason) {
-    result.status = /Playwright is not installed|LANGBOT_FRONTEND_URL/.test(error.message) ? "env_issue" : "fail";
-  }
-  result.reason = result.reason || error.message;
-} finally {
-  if (browser?.page) await safeScreenshot(browser.page, paths.screenshot);
-  if (browser) await browser.close().catch(() => {});
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  const existingEvidence = {};
-  for (const [key, value] of Object.entries(result.evidence)) {
-    if (typeof value !== "string") continue;
-    const isResultFile = value === paths.automationResultJson || value === paths.resultJson;
-    if (isResultFile || await pathExists(value)) existingEvidence[key] = value;
-  }
-  result.evidence = existingEvidence;
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));
-
-async function runSteeringProbe(page) {
-  const beforeMessages = await visibleDebugChatMessages(page);
-  const beforeAssistantCount = countRole(beforeMessages, "assistant");
-  const beforeUserCount = countRole(beforeMessages, "user");
-  const firstStartedAt = Date.now();
-  const firstSend = await sendPrompt(page, firstPrompt, { enabledTimeoutMs: 5000 });
-  if (!firstSend.sent) {
-    return {
-      status: "fail",
-      reason: firstSend.reason || "Could not send first Debug Chat prompt.",
-      first_send: firstSend,
-      before_assistant_count: beforeAssistantCount,
-      before_user_count: beforeUserCount,
-    };
-  }
-
-  await page.waitForTimeout(followupDelayMs);
-  const preFollowupMessages = await visibleDebugChatMessages(page);
-  const preFollowupAssistantCount = countRole(preFollowupMessages, "assistant");
-  const followupStartedAt = Date.now();
-  const followupSend = await sendPrompt(page, followupPrompt, { enabledTimeoutMs: followupEnabledTimeoutMs });
-  const followupSentAt = Date.now();
-  if (!followupSend.sent) {
-    return {
-      status: "fail",
-      reason: followupSend.reason || "Could not send steering follow-up while the first run was active.",
-      first_send: firstSend,
-      followup_send: followupSend,
-      first_to_followup_attempt_ms: followupStartedAt - firstStartedAt,
-      followup_send_latency_ms: followupSentAt - followupStartedAt,
-      before_assistant_count: beforeAssistantCount,
-      pre_followup_assistant_count: preFollowupAssistantCount,
-      before_user_count: beforeUserCount,
-    };
-  }
-
-  const waitResult = await waitForLatestAssistantContaining(page, {
-    expectedText,
-    beforeAssistantCount,
-    timeoutMs: responseTimeoutMs,
-  });
-  await waitForDebugChatTextStable(page);
-  const afterMessages = await visibleDebugChatMessages(page);
-  const afterAssistantCount = countRole(afterMessages, "assistant");
-  const afterUserCount = countRole(afterMessages, "user");
-  const latestAssistantText = latestRoleText(afterMessages, "assistant");
-  const failureSignal = findFailureSignal(latestAssistantText) || findFailureSignal(messagesText(afterMessages));
-  const newAssistantCount = afterAssistantCount - beforeAssistantCount;
-  const newUserCount = afterUserCount - beforeUserCount;
-
-  const base = {
-    first_send: firstSend,
-    followup_send: followupSend,
-    first_to_followup_attempt_ms: followupStartedAt - firstStartedAt,
-    followup_send_latency_ms: followupSentAt - followupStartedAt,
-    before_assistant_count: beforeAssistantCount,
-    pre_followup_assistant_count: preFollowupAssistantCount,
-    after_assistant_count: afterAssistantCount,
-    new_assistant_count: newAssistantCount,
-    before_user_count: beforeUserCount,
-    after_user_count: afterUserCount,
-    new_user_count: newUserCount,
-    latest_assistant_text: latestAssistantText,
-    assistant_containing_expected_seen: waitResult.seen,
-    failure_signal: failureSignal,
-  };
-
-  if (failureSignal) {
-    return {
-      ...base,
-      status: "fail",
-      reason: `Debug Chat displayed a known failure signal: ${failureSignal}`,
-    };
-  }
-  if (!waitResult.seen) {
-    return {
-      ...base,
-      status: "fail",
-      reason: `No new assistant message contained steering sentinel ${expectedText}.`,
-    };
-  }
-  if (!latestAssistantText.includes(expectedText)) {
-    return {
-      ...base,
-      status: "fail",
-      reason: `Latest assistant message did not contain steering sentinel ${expectedText}.`,
-    };
-  }
-  if (newUserCount < 2) {
-    return {
-      ...base,
-      status: "fail",
-      reason: `Expected two new user messages, saw ${newUserCount}.`,
-    };
-  }
-  if (newAssistantCount !== 1) {
-    return {
-      ...base,
-      status: "fail",
-      reason: `Expected one assistant response for one claimed steering run, saw ${newAssistantCount}. More than one usually means the follow-up became a separate run.`,
-    };
-  }
-  if (latestAssistantText.includes("STEERING_NO_FOLLOWUP")) {
-    return {
-      ...base,
-      status: "fail",
-      reason: "Runner answered the no-follow-up branch, so steering was not injected.",
-    };
-  }
-
-  return {
-    ...base,
-    status: "pass",
-    reason: `Follow-up sentinel ${expectedText} appeared in the only new assistant response after two user messages.`,
-  };
-}
-
-function debugChatInput(page) {
-  return page
-    .locator('input[placeholder*="message"], input[placeholder*="消息"], textarea[placeholder*="message"], textarea[placeholder*="消息"]')
-    .last();
-}
-
-async function sendPrompt(page, prompt, { enabledTimeoutMs }) {
-  const input = debugChatInput(page);
-  const inputVisible = await input.isVisible({ timeout: 5000 }).catch(() => false);
-  if (!inputVisible) return { sent: false, reason: "Debug Chat input is not visible." };
-  const inputEnabled = await input.isEnabled({ timeout: enabledTimeoutMs }).catch(() => false);
-  if (!inputEnabled) return { sent: false, reason: `Debug Chat input was not enabled within ${enabledTimeoutMs}ms.` };
-
-  await input.fill(prompt).catch(async () => {
-    await input.click();
-    await input.pressSequentially(prompt);
-  });
-  await input.press("Enter");
-  await page.getByText(prompt, { exact: false }).last().waitFor({ state: "visible", timeout: 10000 }).catch(() => {});
-  return {
-    sent: true,
-    submitted_by: "keyboard_enter",
-  };
-}
-
-async function waitForLatestAssistantContaining(page, { expectedText, beforeAssistantCount, timeoutMs }) {
-  const deadline = Date.now() + timeoutMs;
-  let lastMessages = [];
-  let latestAssistantText = "";
-  while (Date.now() < deadline) {
-    const messages = await visibleDebugChatMessages(page);
-    lastMessages = messages;
-    latestAssistantText = latestRoleText(messages, "assistant");
-    if (countRole(messages, "assistant") > beforeAssistantCount && latestAssistantText.includes(expectedText)) {
-      return {
-        seen: true,
-        latest_assistant_text: latestAssistantText,
-        messages,
-      };
-    }
-    const failureSignal = findFailureSignal(latestAssistantText);
-    if (failureSignal) {
-      return {
-        seen: false,
-        latest_assistant_text: latestAssistantText,
-        messages,
-        failure_signal: failureSignal,
-      };
-    }
-    await page.waitForTimeout(500);
-  }
-  return {
-    seen: false,
-    latest_assistant_text: latestAssistantText,
-    messages: lastMessages,
-  };
-}
-
-async function inspectPipeline(page, { backendUrl, pipelineUrl, pipelineName, expectedRunnerId }) {
-  const pipelineIdFromUrl = pipelineIdFromUrlValue(pipelineUrl);
-  return await page.evaluate(async ({ backendUrl, pipelineIdFromUrl, pipelineName, expectedRunnerId }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        status: "blocked",
-        authenticated: false,
-        reason: "Browser profile has no localStorage token.",
-      };
-    }
-    const getJson = async (path) => {
-      const response = await fetch(`${backendUrl}${path}`, {
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-      });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-
-    let pipelineId = pipelineIdFromUrl;
-    let matchedBy = pipelineId ? "url" : "";
-    if (!pipelineId) {
-      if (!pipelineName) {
-        return {
-          status: "blocked",
-          authenticated: true,
-          pipeline_resolved: false,
-          reason: "Set LANGBOT_LOCAL_AGENT_PIPELINE_URL or LANGBOT_LOCAL_AGENT_PIPELINE_NAME.",
-        };
-      }
-      const list = await getJson("/api/v1/pipelines");
-      const pipelines = list.json.data?.pipelines || [];
-      const match = pipelines.find((pipeline) => pipeline.name === pipelineName);
-      if (!match) {
-        return {
-          status: "blocked",
-          authenticated: true,
-          pipeline_resolved: false,
-          list_status: list.status,
-          reason: `Could not find pipeline named ${pipelineName}.`,
-        };
-      }
-      pipelineId = match.uuid;
-      matchedBy = "name";
-    }
-
-    const loaded = await getJson(`/api/v1/pipelines/${encodeURIComponent(pipelineId)}`);
-    const pipeline = loaded.json.data?.pipeline;
-    if (loaded.status >= 400 || !pipeline) {
-      return {
-        status: "fail",
-        authenticated: true,
-        pipeline_resolved: false,
-        pipeline_id: pipelineId,
-        get_status: loaded.status,
-        reason: loaded.json.msg || "Could not load pipeline.",
-      };
-    }
-    const config = pipeline.config || {};
-    const runner = config.ai?.runner || {};
-    const runnerId = runner.id || runner.runner || "";
-    if (!runnerId) {
-      return {
-        status: "blocked",
-        authenticated: true,
-        pipeline_resolved: true,
-        pipeline_id: pipelineId,
-        pipeline_name: pipeline.name,
-        matched_by: matchedBy,
-        reason: "Pipeline has no ai.runner.id or legacy ai.runner.runner.",
-      };
-    }
-    if (expectedRunnerId && runnerId !== expectedRunnerId) {
-      return {
-        status: "blocked",
-        authenticated: true,
-        pipeline_resolved: true,
-        pipeline_id: pipelineId,
-        pipeline_name: pipeline.name,
-        matched_by: matchedBy,
-        runner_id: runnerId,
-        expected_runner_id: expectedRunnerId,
-        reason: `Pipeline runner mismatch: expected ${expectedRunnerId}, got ${runnerId}.`,
-      };
-    }
-    return {
-      status: "ready",
-      authenticated: true,
-      pipeline_resolved: true,
-      pipeline_id: pipelineId,
-      pipeline_name: pipeline.name,
-      matched_by: matchedBy,
-      runner_id: runnerId,
-      expected_runner_id: expectedRunnerId || "",
-    };
-  }, { backendUrl, pipelineIdFromUrl, pipelineName, expectedRunnerId });
-}
-
-async function inspectToolNames(page, { backendUrl }) {
-  return await page.evaluate(async ({ backendUrl }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        status: "blocked",
-        authenticated: false,
-        tool_names: [],
-        reason: "Browser profile has no localStorage token.",
-      };
-    }
-    const response = await fetch(`${backendUrl}/api/v1/tools`, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-      },
-    });
-    const json = await response.json().catch(() => ({}));
-    const toolNames = (json.data?.tools || [])
-      .map((tool) => tool.name || tool.tool_name || tool.function?.name || "")
-      .filter(Boolean)
-      .sort();
-    return {
-      status: response.status >= 400 ? "fail" : "ready",
-      authenticated: true,
-      http_status: response.status,
-      code: json.code ?? null,
-      tool_names: toolNames,
-      reason: response.status >= 400 ? json.msg || "Could not list tools." : "Tool list loaded.",
-    };
-  }, { backendUrl });
-}
-
-async function resetPipelineDebugChat(page, { backendUrl, pipelineId, sessionType }) {
-  return await page.evaluate(async ({ backendUrl, pipelineId, sessionType }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        status: "blocked",
-        authenticated: false,
-        pipeline_id: pipelineId,
-        session_type: sessionType,
-        reason: "Browser profile has no localStorage token.",
-      };
-    }
-    const response = await fetch(
-      `${backendUrl}/api/v1/pipelines/${encodeURIComponent(pipelineId)}/ws/reset/${encodeURIComponent(sessionType)}`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-      },
-    );
-    const json = await response.json().catch(() => ({}));
-    return {
-      status: response.status >= 400 ? "fail" : "ready",
-      authenticated: true,
-      pipeline_id: pipelineId,
-      session_type: sessionType,
-      reset_status: response.status,
-      reset_code: json.code ?? null,
-      reason: response.status >= 400 ? json.msg || "Debug Chat reset failed." : "Debug Chat session reset.",
-    };
-  }, { backendUrl, pipelineId, sessionType });
-}
-
-function pipelineIdFromUrlValue(value) {
-  const match = String(value || "").match(/\/pipelines?\/([^/?#]+)/i);
-  return match ? decodeURIComponent(match[1]) : "";
-}
-
-function countRole(messages, role) {
-  return messages.filter((message) => message.role === role).length;
-}
-
-function latestRoleText(messages, role) {
-  return messages.filter((message) => message.role === role).at(-1)?.text || "";
-}
-
-function messagesText(messages) {
-  return messages.map((message) => message.text).join("\n");
-}
-
-function findFailureSignal(text) {
-  return DEBUG_CHAT_FAILURE_SIGNALS.find((signal) => String(text || "").includes(signal)) || "";
-}
-
-function positiveInt(value, fallback) {
-  const parsed = Number.parseInt(String(value || ""), 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}

skills/scripts/e2e/mcp-stdio-fixture.mjs

@@ -1,185 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  localIsoWithOffset,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-function loadEnvDefaults(path) {
-  if (!existsSync(path)) return;
-  for (const rawLine of readFileSync(path, "utf8").split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-    const sep = line.indexOf("=");
-    if (sep === -1) continue;
-    const key = line.slice(0, sep).trim();
-    if (env[key]) continue;
-    env[key] = line.slice(sep + 1).trim().replace(/^["']|["']$/g, "");
-  }
-}
-
-loadEnvDefaults("skills/.env");
-loadEnvDefaults("skills/.env.local");
-
-const caseId = env.LBS_CASE_ID || "mcp-stdio-fixture-direct";
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const startedAt = new Date();
-const fixturePath = resolve(env.LANGBOT_MCP_FIXTURE_PATH || "skills/langbot-testing/fixtures/mcp/qa_mcp_echo_server.py");
-const langbotRepo = env.LANGBOT_REPO ? resolve(env.LANGBOT_REPO) : "";
-const uvCandidates = [
-  env.LANGBOT_MCP_FIXTURE_UV,
-  "uv",
-].filter(Boolean);
-const uv = uvCandidates.find((candidate) => candidate === "uv" || existsSync(candidate));
-const pythonCandidates = [
-  env.LANGBOT_MCP_FIXTURE_PYTHON,
-  langbotRepo ? `${langbotRepo}/.venv/bin/python` : "",
-  "python3",
-].filter(Boolean);
-const python = pythonCandidates.find((candidate) => candidate === "python3" || existsSync(candidate));
-const command = langbotRepo && uv
-  ? { executable: uv, args: ["run", "python", fixturePath], cwd: langbotRepo, mode: "uv" }
-  : python
-    ? { executable: python, args: [fixturePath], cwd: resolve("."), mode: "python" }
-    : null;
-const expectedText = "qa_mcp_echo:mcp-stdio-fixture-ok";
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  started_at: startedAt.toISOString(),
-  started_at_local: localIsoWithOffset(startedAt),
-  finished_at: "",
-  finished_at_local: "",
-  status: "fail",
-  reason: "",
-  fixture_path: fixturePath,
-  command,
-  expected_text: expectedText,
-  evidence: {
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-};
-
-function parseJsonLines(buffer) {
-  return buffer
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => {
-      try {
-        return JSON.parse(line);
-      } catch {
-        return null;
-      }
-    })
-    .filter(Boolean);
-}
-
-async function request(child, id, method, params) {
-  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
-}
-
-async function run() {
-  if (!command) {
-    result.status = "env_issue";
-    result.reason = "No uv or Python interpreter found. Set LANGBOT_REPO, LANGBOT_MCP_FIXTURE_UV, or LANGBOT_MCP_FIXTURE_PYTHON.";
-    return;
-  }
-  if (!existsSync(fixturePath)) {
-    result.status = "env_issue";
-    result.reason = `MCP fixture not found: ${fixturePath}`;
-    return;
-  }
-
-  const child = spawn(command.executable, command.args, {
-    cwd: command.cwd,
-    stdio: ["pipe", "pipe", "pipe"],
-  });
-  let stdout = "";
-  let stderr = "";
-  child.stdout.setEncoding("utf8");
-  child.stderr.setEncoding("utf8");
-  child.stdout.on("data", (chunk) => {
-    stdout += chunk;
-  });
-  child.stderr.on("data", (chunk) => {
-    stderr += chunk;
-  });
-
-  const timeout = setTimeout(() => child.kill("SIGTERM"), 10_000);
-  try {
-    await new Promise((resolveReady) => setTimeout(resolveReady, 100));
-    await request(child, 1, "initialize", {
-      protocolVersion: "2024-11-05",
-      capabilities: {},
-      clientInfo: { name: "langbot-skills", version: "0" },
-    });
-    await new Promise((resolveReady) => setTimeout(resolveReady, 200));
-    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} })}\n`);
-    await request(child, 2, "tools/list", {});
-    await request(child, 3, "tools/call", {
-      name: "qa_mcp_echo",
-      arguments: { text: "mcp-stdio-fixture-ok" },
-    });
-    await new Promise((resolveDone) => setTimeout(resolveDone, 1500));
-  } finally {
-    clearTimeout(timeout);
-    child.kill("SIGTERM");
-  }
-
-  const messages = parseJsonLines(stdout);
-  if (/No module named ['"]mcp['"]|ModuleNotFoundError/i.test(stderr)) {
-    result.status = "env_issue";
-    result.reason = `Python environment cannot import mcp. Set LANGBOT_MCP_FIXTURE_PYTHON to a LangBot venv Python. stderr=${stderr.trim()}`;
-    return;
-  }
-  const listResult = messages.find((message) => message.id === 2)?.result;
-  const callResult = messages.find((message) => message.id === 3)?.result;
-  const toolNames = Array.isArray(listResult?.tools)
-    ? listResult.tools.map((tool) => tool.name)
-    : [];
-  const callText = Array.isArray(callResult?.content)
-    ? callResult.content.map((item) => item.text || "").join("\n")
-    : "";
-
-  if (!toolNames.includes("qa_mcp_echo")) {
-    result.status = "fail";
-    result.reason = `MCP fixture did not list qa_mcp_echo. stderr=${stderr.trim()}`;
-    return;
-  }
-  if (!callText.includes(expectedText)) {
-    result.status = "fail";
-    result.reason = `MCP fixture call did not return ${expectedText}. stderr=${stderr.trim()}`;
-    return;
-  }
-
-  result.status = "pass";
-  result.reason = "MCP stdio fixture listed qa_mcp_echo and returned the deterministic tool result without a model provider.";
-}
-
-try {
-  await run();
-} catch (error) {
-  result.status = "fail";
-  result.reason = error instanceof Error ? error.message : String(error);
-} finally {
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));

skills/scripts/e2e/mcp-stdio-register.mjs

@@ -1,234 +0,0 @@
-#!/usr/bin/env node
-
-import { existsSync, readFileSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  localIsoWithOffset,
-  safeScreenshot,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-function loadEnvDefaults(path) {
-  if (!existsSync(path)) return;
-  for (const rawLine of readFileSync(path, "utf8").split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-    const sep = line.indexOf("=");
-    if (sep === -1) continue;
-    const key = line.slice(0, sep).trim();
-    if (env[key]) continue;
-    env[key] = line.slice(sep + 1).trim().replace(/^["']|["']$/g, "");
-  }
-}
-
-loadEnvDefaults("skills/.env");
-loadEnvDefaults("skills/.env.local");
-
-const caseId = env.LBS_CASE_ID || "mcp-stdio-register";
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const startedAt = new Date();
-const serverName = env.LANGBOT_MCP_SERVER_NAME || "qa-local-stdio";
-const expectedTool = env.LANGBOT_MCP_EXPECTED_TOOL || "qa_mcp_echo";
-const fixturePath = resolve(env.LANGBOT_MCP_FIXTURE_PATH || "skills/langbot-testing/fixtures/mcp/qa_mcp_echo_server.py");
-const fixtureCommand = env.LANGBOT_MCP_FIXTURE_COMMAND || "python";
-const fixtureArgs = env.LANGBOT_MCP_FIXTURE_ARGS
-  ? JSON.parse(env.LANGBOT_MCP_FIXTURE_ARGS)
-  : [fixturePath];
-const startupTimeoutSec = Number(env.LANGBOT_MCP_STARTUP_TIMEOUT_SEC || "300");
-const readyTimeoutMs = Number(env.LANGBOT_MCP_READY_TIMEOUT_MS || "360000");
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const apiDiagnosticPath = resolve(paths.evidenceDir, "api-diagnostic.json");
-
-let browser;
-const result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  started_at: startedAt.toISOString(),
-  started_at_local: localIsoWithOffset(startedAt),
-  finished_at: "",
-  finished_at_local: "",
-  status: "fail",
-  reason: "",
-  server_name: serverName,
-  fixture_path: fixturePath,
-  expected_tool: expectedTool,
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    api_diagnostic_json: apiDiagnosticPath,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["api_diagnostic"],
-};
-
-async function run() {
-  if (!backendUrl) {
-    result.status = "env_issue";
-    result.reason = "LANGBOT_BACKEND_URL is not configured.";
-    return;
-  }
-  if (!existsSync(fixturePath)) {
-    result.status = "env_issue";
-    result.reason = `MCP fixture not found: ${fixturePath}`;
-    return;
-  }
-
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  await page.goto(env.LANGBOT_FRONTEND_URL, { waitUntil: "domcontentloaded" });
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-
-  const diagnostic = await page.evaluate(async ({
-    backendUrl,
-    serverName,
-    expectedTool,
-    fixturePath,
-    fixtureCommand,
-    fixtureArgs,
-    startupTimeoutSec,
-    readyTimeoutMs,
-  }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        authenticated: false,
-        save_status: 0,
-        save_code: null,
-        save_msg: "Browser profile has no localStorage token.",
-        tool_names: [],
-        has_expected_tool: false,
-        runtime_status: null,
-        runtime_tool_names: [],
-        runtime_error: "",
-      };
-    }
-
-    const headers = {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-    };
-    const serverConfig = {
-      name: serverName,
-      mode: "stdio",
-      enable: true,
-      extra_args: {
-        command: fixtureCommand,
-        args: fixtureArgs,
-        env: {},
-        box: {
-          startup_timeout_sec: startupTimeoutSec,
-        },
-      },
-    };
-    const getJson = async (path) => {
-      const response = await fetch(`${backendUrl}${path}`, { headers });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-    const sendJson = async (method, path, body) => {
-      const response = await fetch(`${backendUrl}${path}`, {
-        method,
-        headers,
-        body: JSON.stringify(body),
-      });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-
-    const serverPath = `/api/v1/mcp/servers/${encodeURIComponent(serverName)}`;
-    const beforeServer = await getJson(serverPath);
-    const save = beforeServer.status === 404
-      ? await sendJson("POST", "/api/v1/mcp/servers", serverConfig)
-      : await sendJson("PUT", serverPath, serverConfig);
-
-    const deadline = Date.now() + readyTimeoutMs;
-    let lastTools = [];
-    let lastRuntime = null;
-    while (Date.now() < deadline) {
-      await new Promise((resolveReady) => setTimeout(resolveReady, 500));
-      const tools = await getJson("/api/v1/tools");
-      const server = await getJson(serverPath);
-      lastTools = (tools.json.data?.tools || [])
-        .map((tool) => tool.name || tool.tool_name || tool.function?.name || "")
-        .filter(Boolean)
-        .sort();
-      lastRuntime = server.json.data?.server?.runtime_info || null;
-      if (lastTools.includes(expectedTool)) break;
-    }
-
-    return {
-      authenticated: true,
-      before_status: beforeServer.status,
-      save_status: save.status,
-      save_code: save.json.code ?? null,
-      save_msg: save.json.msg || "",
-      tool_names: lastTools,
-      has_expected_tool: lastTools.includes(expectedTool),
-      runtime_status: lastRuntime?.status || null,
-      runtime_tool_names: (lastRuntime?.tools || [])
-        .map((tool) => tool.name || tool.tool_name || "")
-        .filter(Boolean)
-        .sort(),
-      runtime_tool_count: lastRuntime?.tool_count ?? null,
-      runtime_error: lastRuntime?.error_message || "",
-    };
-  }, { backendUrl, serverName, expectedTool, fixturePath, fixtureCommand, fixtureArgs, startupTimeoutSec, readyTimeoutMs });
-
-  await writeFile(apiDiagnosticPath, `${JSON.stringify(diagnostic, null, 2)}\n`, "utf8");
-  await safeScreenshot(page, paths.screenshot);
-
-  if (!diagnostic.authenticated) {
-    result.status = "blocked";
-    result.reason = "Browser profile is not authenticated for LangBot; cannot update MCP server.";
-    return;
-  }
-  if (diagnostic.save_status >= 400 || diagnostic.save_code !== 0) {
-    result.status = "fail";
-    result.reason = `Failed to save MCP server ${serverName}: ${diagnostic.save_status} ${diagnostic.save_msg}`;
-    return;
-  }
-  if (diagnostic.runtime_status !== "connected") {
-    result.status = "fail";
-    result.reason = `MCP server ${serverName} is not connected after save: ${diagnostic.runtime_status || "missing runtime"}. ${diagnostic.runtime_error}`;
-    return;
-  }
-  if (!diagnostic.has_expected_tool || !diagnostic.runtime_tool_names.includes(expectedTool)) {
-    result.status = "fail";
-    result.reason = `MCP server ${serverName} did not expose ${expectedTool}. See ${apiDiagnosticPath}.`;
-    return;
-  }
-
-  result.status = "pass";
-  result.reason = `MCP server ${serverName} is connected and exposes ${expectedTool} through LangBot /api/v1/tools.`;
-}
-
-try {
-  await run();
-} catch (error) {
-  result.status = /Playwright is not installed|LANGBOT_FRONTEND_URL/.test(error.message) ? "env_issue" : "fail";
-  result.reason = error instanceof Error ? error.message : String(error);
-} finally {
-  if (browser) await browser.close().catch(() => {});
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));

skills/scripts/e2e/pipeline-debug-chat.mjs

@@ -1,728 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { env } from "node:process";
-import {
-  openPipelineDebugChat,
-  runDebugChatPrompt,
-  setDebugChatStreamOutput,
-} from "./lib/debug-chat.mjs";
-import {
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  localIsoWithOffset,
-  pathExists,
-  safeScreenshot,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const caseId = env.LBS_CASE_ID || "pipeline-debug-chat";
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const expectedText = env.LANGBOT_E2E_EXPECTED_TEXT || "OK";
-const prompt = env.LANGBOT_E2E_PROMPT || `请只回复 ${expectedText}，用于前端调试测试。`;
-const responseTimeoutMs = Number.parseInt(env.LANGBOT_E2E_RESPONSE_TIMEOUT_MS || "120000", 10);
-const safeResponseTimeoutMs = Number.isFinite(responseTimeoutMs) && responseTimeoutMs > 0 ? responseTimeoutMs : 120000;
-const streamOutput = /^(0|false)$/i.test(env.LANGBOT_E2E_STREAM_OUTPUT || "")
-  ? false
-  : /^(1|true)$/i.test(env.LANGBOT_E2E_STREAM_OUTPUT || "")
-    ? true
-    : null;
-const failureSignals = (env.LANGBOT_E2E_FAILURE_SIGNALS || "")
-  .split(/\r?\n/)
-  .map((item) => item.trim())
-  .filter(Boolean);
-const imageBase64Path = env.LANGBOT_E2E_IMAGE_BASE64_PATH || "";
-const imagePathEnv = env.LANGBOT_E2E_IMAGE_PATH || "";
-const backendUrl = env.LANGBOT_BACKEND_URL || "";
-const pipelineRequired = env.LANGBOT_E2E_PIPELINE_REQUIRED === "1";
-const pipelineUrl = pipelineRequired
-  ? env.LANGBOT_E2E_PIPELINE_URL
-  : (env.LANGBOT_E2E_PIPELINE_URL || env.LANGBOT_PIPELINE_URL);
-const pipelineName = pipelineRequired
-  ? env.LANGBOT_E2E_PIPELINE_NAME
-  : (env.LANGBOT_E2E_PIPELINE_NAME || env.LANGBOT_PIPELINE_NAME);
-const expectedRunnerId = env.LANGBOT_E2E_EXPECTED_RUNNER_ID || "";
-const resetDebugChat = boolFromEnv(env.LANGBOT_E2E_RESET_DEBUG_CHAT, false);
-const restoreRunnerConfig = boolFromEnv(env.LANGBOT_E2E_RESTORE_RUNNER_CONFIG, true);
-const debugChatSessionType = env.LANGBOT_E2E_DEBUG_CHAT_SESSION_TYPE || "person";
-const pipelineConfigDiagnosticPath = resolve(paths.evidenceDir, "pipeline-config-diagnostic.json");
-const debugChatResetDiagnosticPath = resolve(paths.evidenceDir, "debug-chat-reset-diagnostic.json");
-const pipelineConfigRestoreDiagnosticPath = resolve(paths.evidenceDir, "pipeline-config-restore-diagnostic.json");
-const startedAt = new Date();
-
-let browser;
-let restorePlan = null;
-let result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  started_at: startedAt.toISOString(),
-  started_at_local: localIsoWithOffset(startedAt),
-  finished_at: "",
-  finished_at_local: "",
-  status: "fail",
-  reason: "",
-  url: "",
-  prompt,
-  expected_text: expectedText,
-  response_timeout_ms: safeResponseTimeoutMs,
-  stream_output: streamOutput,
-  image_fixture: imageBase64Path || imagePathEnv,
-  prompt_count: 1,
-  chat_results: [],
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["ui", "screenshot", "console", "network"],
-};
-
-function boolFromEnv(value, defaultValue) {
-  if (value === undefined || value === "") return defaultValue;
-  if (/^(0|false|no|off)$/i.test(value)) return false;
-  if (/^(1|true|yes|on)$/i.test(value)) return true;
-  return defaultValue;
-}
-
-function parseJsonEnv(key, fallback) {
-  const raw = env[key];
-  if (!raw) return fallback;
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`${key} must be valid JSON: ${error.message}`);
-  }
-}
-
-function promptStepsFromEnv() {
-  const rawSteps = parseJsonEnv("LANGBOT_E2E_PROMPTS_JSON", null);
-  if (rawSteps === null) {
-    return [{ prompt, expectedText, responseTimeoutMs: safeResponseTimeoutMs }];
-  }
-  if (!Array.isArray(rawSteps) || rawSteps.length === 0) {
-    throw new Error("LANGBOT_E2E_PROMPTS_JSON must be a non-empty JSON array.");
-  }
-  return rawSteps.map((item, index) => {
-    if (typeof item === "string") {
-      return { prompt: item, expectedText, responseTimeoutMs: safeResponseTimeoutMs };
-    }
-    if (!item || typeof item !== "object" || typeof item.prompt !== "string" || !item.prompt) {
-      throw new Error(`LANGBOT_E2E_PROMPTS_JSON[${index}] must be a string or an object with a prompt string.`);
-    }
-    const stepTimeout = Number.parseInt(String(item.response_timeout_ms || item.responseTimeoutMs || safeResponseTimeoutMs), 10);
-    return {
-      prompt: item.prompt,
-      expectedText: String(item.expected_text || item.expectedText || expectedText),
-      responseTimeoutMs: Number.isFinite(stepTimeout) && stepTimeout > 0 ? stepTimeout : safeResponseTimeoutMs,
-    };
-  });
-}
-
-function expandEnvRefs(value) {
-  return String(value || "").replace(/\$\{([A-Z][A-Z0-9_]*)\}|\$([A-Z][A-Z0-9_]*)/g, (_match, braced, bare) => {
-    return env[braced || bare] || "";
-  });
-}
-
-function textList(value) {
-  if (value === undefined || value === null || value === "") return [];
-  return Array.isArray(value) ? value.map(String) : [String(value)];
-}
-
-function runArgv(argv, { cwd = "", timeoutMs = 30_000 } = {}) {
-  return new Promise((resolveRun) => {
-    if (!Array.isArray(argv) || argv.length === 0 || !argv.every((item) => typeof item === "string" && item)) {
-      resolveRun({
-        status: "fail",
-        reason: "Filesystem command check requires a non-empty argv string array.",
-        exit_code: null,
-        stdout: "",
-        stderr: "",
-      });
-      return;
-    }
-
-    const child = spawn(argv[0], argv.slice(1), {
-      cwd: cwd ? resolve(cwd) : undefined,
-      env,
-      shell: false,
-    });
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      child.kill("SIGTERM");
-    }, timeoutMs);
-
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.on("error", (error) => {
-      clearTimeout(timer);
-      resolveRun({
-        status: "fail",
-        reason: error.message,
-        exit_code: null,
-        stdout,
-        stderr,
-      });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolveRun({
-        status: timedOut ? "fail" : "pass",
-        reason: timedOut ? `Command timed out after ${timeoutMs} ms.` : "",
-        exit_code: code,
-        stdout,
-        stderr,
-      });
-    });
-  });
-}
-
-async function runFilesystemChecks(checks) {
-  if (!Array.isArray(checks) || checks.length === 0) {
-    return { status: "not_required", checks: [] };
-  }
-  const results = [];
-  for (let index = 0; index < checks.length; index += 1) {
-    const check = checks[index];
-    if (!check || typeof check !== "object") {
-      results.push({ index, status: "fail", reason: "Filesystem check must be an object." });
-      continue;
-    }
-    const contains = textList(check.contains);
-    const notContains = textList(check.not_contains || check.notContains);
-    const expectedExitCode = Number.isInteger(check.exit_code)
-      ? check.exit_code
-      : Number.isInteger(check.expected_exit_code)
-        ? check.expected_exit_code
-        : 0;
-    const expectedStdout = textList(check.stdout_contains || check.expected_stdout || check.expectedStdout);
-
-    if (check.path) {
-      const path = resolve(expandEnvRefs(check.path));
-      let text = "";
-      try {
-        text = await readFile(path, "utf8");
-      } catch (error) {
-        results.push({ index, status: "fail", type: "file", path, reason: error.message });
-        continue;
-      }
-      const missing = contains.filter((needle) => !text.includes(needle));
-      const forbidden = notContains.filter((needle) => text.includes(needle));
-      results.push({
-        index,
-        status: missing.length || forbidden.length ? "fail" : "pass",
-        type: "file",
-        path,
-        missing,
-        forbidden,
-        reason: missing.length
-          ? `Missing expected text: ${missing.join(", ")}`
-          : forbidden.length
-            ? `Found forbidden text: ${forbidden.join(", ")}`
-            : "",
-      });
-      continue;
-    }
-
-    if (check.argv) {
-      const cwd = check.cwd ? expandEnvRefs(check.cwd) : "";
-      const timeoutMs = Number.parseInt(String(check.timeout_ms || check.timeoutMs || "30000"), 10);
-      const run = await runArgv(check.argv.map(expandEnvRefs), {
-        cwd,
-        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 30_000,
-      });
-      const missingStdout = expectedStdout.filter((needle) => !run.stdout.includes(needle));
-      const exitMatches = run.exit_code === expectedExitCode;
-      results.push({
-        index,
-        status: run.status === "pass" && exitMatches && missingStdout.length === 0 ? "pass" : "fail",
-        type: "command",
-        argv: check.argv,
-        cwd,
-        exit_code: run.exit_code,
-        expected_exit_code: expectedExitCode,
-        missing_stdout: missingStdout,
-        stdout_preview: run.stdout.slice(0, 2000),
-        stderr_preview: run.stderr.slice(0, 2000),
-        reason: run.reason
-          || (!exitMatches ? `Expected exit code ${expectedExitCode}, saw ${run.exit_code}.` : "")
-          || (missingStdout.length ? `Missing stdout text: ${missingStdout.join(", ")}` : ""),
-      });
-      continue;
-    }
-
-    results.push({ index, status: "fail", reason: "Filesystem check requires either path or argv." });
-  }
-  const failed = results.filter((item) => item.status !== "pass");
-  return {
-    status: failed.length ? "fail" : "pass",
-    checks: results,
-    reason: failed.length ? `Filesystem checks failed: ${failed.map((item) => item.index).join(", ")}` : "",
-  };
-}
-
-function pipelineIdFromUrl(url) {
-  if (!url) return "";
-  try {
-    const parsed = new URL(url);
-    return parsed.searchParams.get("id") || "";
-  } catch {
-    return "";
-  }
-}
-
-function sanitizePipelineDiagnostic(diagnostic) {
-  const { restore_config: _restoreConfig, ...safe } = diagnostic || {};
-  return safe;
-}
-
-async function prepareImageFixture(paths) {
-  if (imagePathEnv) return resolve(imagePathEnv);
-  if (!imageBase64Path) return "";
-  const source = resolve(imageBase64Path);
-  const target = resolve(paths.evidenceDir, "image-fixture.png");
-  const encoded = await readFile(source, "utf8");
-  await writeFile(target, Buffer.from(encoded.replace(/\s+/g, ""), "base64"));
-  return target;
-}
-
-async function inspectAndPatchPipelineConfig(page, {
-  backendUrl,
-  pipelineUrl,
-  pipelineName,
-  runnerConfigPatch,
-  expectedRunnerId,
-}) {
-  const pipelineIdFromUrlValue = pipelineIdFromUrl(pipelineUrl) || pipelineIdFromUrl(page.url());
-  return await page.evaluate(async ({
-    backendUrl,
-    pipelineIdFromUrlValue,
-    pipelineName,
-    runnerConfigPatch,
-    expectedRunnerId,
-  }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        status: "blocked",
-        authenticated: false,
-        reason: "Browser profile has no localStorage token.",
-      };
-    }
-
-    const headers = {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-    };
-    const getJson = async (path) => {
-      const response = await fetch(`${backendUrl}${path}`, { headers });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-    const putJson = async (path, body) => {
-      const response = await fetch(`${backendUrl}${path}`, {
-        method: "PUT",
-        headers,
-        body: JSON.stringify(body),
-      });
-      return {
-        status: response.status,
-        json: await response.json().catch(() => ({})),
-      };
-    };
-
-    let pipelineId = pipelineIdFromUrlValue || "";
-    let matchedBy = pipelineId ? "url" : "";
-    if (!pipelineId && pipelineName) {
-      const list = await getJson("/api/v1/pipelines");
-      const pipelines = list.json.data?.pipelines || [];
-      const match = pipelines.find((pipeline) => pipeline.name === pipelineName);
-      if (!match) {
-        return {
-          status: "blocked",
-          authenticated: true,
-          pipeline_resolved: false,
-          list_status: list.status,
-          reason: `Could not find pipeline named ${pipelineName}.`,
-        };
-      }
-      pipelineId = match.uuid;
-      matchedBy = "name";
-    }
-
-    if (!pipelineId) {
-      return {
-        status: "blocked",
-        authenticated: true,
-        pipeline_resolved: false,
-        reason: "Could not resolve pipeline id from URL or pipeline name.",
-      };
-    }
-
-    const before = await getJson(`/api/v1/pipelines/${encodeURIComponent(pipelineId)}`);
-    const pipeline = before.json.data?.pipeline;
-    if (before.status >= 400 || !pipeline) {
-      return {
-        status: "fail",
-        authenticated: true,
-        pipeline_resolved: false,
-        pipeline_id: pipelineId,
-        get_status: before.status,
-        reason: before.json.msg || "Could not load pipeline.",
-      };
-    }
-
-    const config = JSON.parse(JSON.stringify(pipeline.config || {}));
-    const aiConfig = config.ai && typeof config.ai === "object" ? config.ai : {};
-    const runner = aiConfig.runner && typeof aiConfig.runner === "object" ? aiConfig.runner : {};
-    const runnerId = runner.id || runner.runner || "";
-    if (!runnerId) {
-      return {
-        status: "blocked",
-        authenticated: true,
-        pipeline_resolved: true,
-        pipeline_id: pipelineId,
-        pipeline_name: pipeline.name,
-        matched_by: matchedBy,
-        reason: "Pipeline has no ai.runner.id or legacy ai.runner.runner.",
-      };
-    }
-    if (expectedRunnerId && runnerId !== expectedRunnerId) {
-      return {
-        status: "blocked",
-        authenticated: true,
-        pipeline_resolved: true,
-        pipeline_id: pipelineId,
-        pipeline_name: pipeline.name,
-        matched_by: matchedBy,
-        runner_id: runnerId,
-        expected_runner_id: expectedRunnerId,
-        reason: `Pipeline runner mismatch: expected ${expectedRunnerId}, got ${runnerId}.`,
-      };
-    }
-
-    const runnerConfigs = aiConfig.runner_config && typeof aiConfig.runner_config === "object"
-      ? aiConfig.runner_config
-      : {};
-    const currentRunnerConfig = runnerConfigs[runnerId] && typeof runnerConfigs[runnerId] === "object"
-      ? runnerConfigs[runnerId]
-      : {};
-    const patchKeys = Object.keys(runnerConfigPatch || {});
-    const baseDiagnostic = {
-      status: "ready",
-      authenticated: true,
-      pipeline_resolved: true,
-      pipeline_id: pipelineId,
-      pipeline_name: pipeline.name,
-      matched_by: matchedBy,
-      runner_id: runnerId,
-      expected_runner_id: expectedRunnerId || "",
-      patch_keys: patchKeys,
-      runner_config_before_keys: Object.keys(currentRunnerConfig),
-      patched: patchKeys.length > 0,
-    };
-
-    if (patchKeys.length === 0) {
-      return baseDiagnostic;
-    }
-
-    const updatedRunnerConfig = {
-      ...currentRunnerConfig,
-      ...runnerConfigPatch,
-    };
-    const updatedConfig = {
-      ...config,
-      ai: {
-        ...aiConfig,
-        runner: {
-          ...runner,
-          id: runnerId,
-        },
-        runner_config: {
-          ...runnerConfigs,
-          [runnerId]: updatedRunnerConfig,
-        },
-      },
-    };
-
-    const update = await putJson(`/api/v1/pipelines/${encodeURIComponent(pipelineId)}`, {
-      config: updatedConfig,
-    });
-    if (update.status >= 400) {
-      return {
-        ...baseDiagnostic,
-        status: "fail",
-        put_status: update.status,
-        put_code: update.json.code ?? null,
-        reason: update.json.msg || "Pipeline config update failed.",
-      };
-    }
-
-    return {
-      ...baseDiagnostic,
-      put_status: update.status,
-      put_code: update.json.code ?? null,
-      runner_config_after_keys: Object.keys(updatedRunnerConfig),
-      restore_config: config,
-    };
-  }, {
-    backendUrl,
-    pipelineIdFromUrlValue,
-    pipelineName,
-    runnerConfigPatch,
-    expectedRunnerId,
-  });
-}
-
-async function restorePipelineConfig(page, { backendUrl, pipelineId, config }) {
-  return await page.evaluate(async ({ backendUrl, pipelineId, config }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        status: "blocked",
-        authenticated: false,
-        pipeline_id: pipelineId,
-        reason: "Browser profile has no localStorage token.",
-      };
-    }
-    const response = await fetch(`${backendUrl}/api/v1/pipelines/${encodeURIComponent(pipelineId)}`, {
-      method: "PUT",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ config }),
-    });
-    const json = await response.json().catch(() => ({}));
-    return {
-      status: response.status >= 400 ? "fail" : "ready",
-      authenticated: true,
-      pipeline_id: pipelineId,
-      put_status: response.status,
-      put_code: json.code ?? null,
-      reason: response.status >= 400 ? json.msg || "Pipeline config restore failed." : "Pipeline config restored.",
-    };
-  }, { backendUrl, pipelineId, config });
-}
-
-async function resetPipelineDebugChat(page, { backendUrl, pipelineId, sessionType }) {
-  return await page.evaluate(async ({ backendUrl, pipelineId, sessionType }) => {
-    const token = localStorage.getItem("token");
-    if (!token) {
-      return {
-        status: "blocked",
-        authenticated: false,
-        pipeline_id: pipelineId,
-        session_type: sessionType,
-        reason: "Browser profile has no localStorage token.",
-      };
-    }
-    const response = await fetch(
-      `${backendUrl}/api/v1/pipelines/${encodeURIComponent(pipelineId)}/ws/reset/${encodeURIComponent(sessionType)}`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-      },
-    );
-    const json = await response.json().catch(() => ({}));
-    return {
-      status: response.status >= 400 ? "fail" : "ready",
-      authenticated: true,
-      pipeline_id: pipelineId,
-      session_type: sessionType,
-      reset_status: response.status,
-      reset_code: json.code ?? null,
-      reason: response.status >= 400 ? json.msg || "Debug Chat reset failed." : "Debug Chat session reset.",
-    };
-  }, { backendUrl, pipelineId, sessionType });
-}
-
-try {
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  const imagePath = await prepareImageFixture(paths);
-  const promptSteps = promptStepsFromEnv();
-  const filesystemChecks = parseJsonEnv("LANGBOT_E2E_FILESYSTEM_CHECKS_JSON", []);
-  const runnerConfigPatch = parseJsonEnv("LANGBOT_E2E_RUNNER_CONFIG_PATCH_JSON", {});
-  const runnerPatchKeys = Object.keys(runnerConfigPatch);
-  if (runnerPatchKeys.length > 0 || resetDebugChat || expectedRunnerId) {
-    if (!backendUrl) {
-      result.status = "env_issue";
-      result.reason = "LANGBOT_BACKEND_URL is required for runner config patch, runner assertion, or Debug Chat reset.";
-      throw new Error(result.reason);
-    }
-  }
-  result.prompt_count = promptSteps.length;
-  result.prompt = promptSteps.length === 1 ? promptSteps[0].prompt : `${promptSteps.length} prompts`;
-  result.expected_text = promptSteps.at(-1)?.expectedText || expectedText;
-
-  const openResult = await openPipelineDebugChat(page, {
-    pipelineUrl,
-    pipelineName,
-    envHint: pipelineRequired
-      ? "case-specific pipeline env mapped to LANGBOT_E2E_PIPELINE_URL or LANGBOT_E2E_PIPELINE_NAME"
-      : "LANGBOT_PIPELINE_URL or LANGBOT_PIPELINE_NAME",
-  });
-  result.url = page.url();
-
-  if (!openResult.opened) {
-    result.status = openResult.status;
-    result.reason = openResult.reason;
-  } else {
-    result.status = "running";
-    result.reason = "";
-    if (runnerPatchKeys.length > 0 || resetDebugChat || expectedRunnerId) {
-      const pipelineDiagnostic = await inspectAndPatchPipelineConfig(page, {
-        backendUrl,
-        pipelineUrl,
-        pipelineName,
-        runnerConfigPatch,
-        expectedRunnerId,
-      });
-      const safeDiagnostic = sanitizePipelineDiagnostic(pipelineDiagnostic);
-      await writeFile(pipelineConfigDiagnosticPath, `${JSON.stringify(safeDiagnostic, null, 2)}\n`, "utf8");
-      result.evidence.pipeline_config_diagnostic_json = pipelineConfigDiagnosticPath;
-      result.pipeline_config = safeDiagnostic;
-      if (!result.evidence_collected.includes("api_diagnostic")) result.evidence_collected.push("api_diagnostic");
-
-      if (pipelineDiagnostic.status === "fail" || pipelineDiagnostic.status === "blocked") {
-        result.status = pipelineDiagnostic.status;
-        result.reason = pipelineDiagnostic.reason || "Pipeline config preparation failed.";
-      } else {
-        if (pipelineDiagnostic.restore_config && restoreRunnerConfig) {
-          restorePlan = {
-            backendUrl,
-            pipelineId: pipelineDiagnostic.pipeline_id,
-            config: pipelineDiagnostic.restore_config,
-          };
-        }
-        if (resetDebugChat) {
-          const resetDiagnostic = await resetPipelineDebugChat(page, {
-            backendUrl,
-            pipelineId: pipelineDiagnostic.pipeline_id,
-            sessionType: debugChatSessionType,
-          });
-          await writeFile(debugChatResetDiagnosticPath, `${JSON.stringify(resetDiagnostic, null, 2)}\n`, "utf8");
-          result.evidence.debug_chat_reset_diagnostic_json = debugChatResetDiagnosticPath;
-          result.debug_chat_reset = resetDiagnostic;
-          if (resetDiagnostic.status === "fail" || resetDiagnostic.status === "blocked") {
-            result.status = resetDiagnostic.status;
-            result.reason = resetDiagnostic.reason || "Debug Chat reset failed.";
-          } else {
-            await page.waitForTimeout(1000);
-            const reopenResult = await openPipelineDebugChat(page, {
-              pipelineUrl,
-              pipelineName,
-              envHint: pipelineRequired
-                ? "case-specific pipeline env mapped to LANGBOT_E2E_PIPELINE_URL or LANGBOT_E2E_PIPELINE_NAME"
-                : "LANGBOT_PIPELINE_URL or LANGBOT_PIPELINE_NAME",
-            });
-            result.url = page.url();
-            if (!reopenResult.opened) {
-              result.status = reopenResult.status;
-              result.reason = reopenResult.reason;
-            }
-          }
-        }
-      }
-    }
-
-    if (result.status === "fail" || result.status === "blocked" || result.status === "env_issue") {
-      // Preparation already determined the outcome.
-    } else {
-      const streamResult = await setDebugChatStreamOutput(page, streamOutput);
-      if (streamResult.status === "blocked" || streamResult.status === "fail") {
-        result.status = streamResult.status;
-        result.reason = streamResult.reason;
-      } else {
-        for (let index = 0; index < promptSteps.length; index += 1) {
-          const step = promptSteps[index];
-          const chatResult = await runDebugChatPrompt(page, {
-            prompt: step.prompt,
-            expectedText: step.expectedText,
-            responseTimeoutMs: step.responseTimeoutMs,
-            imagePath: index === 0 ? imagePath : "",
-            failureSignals: failureSignals.length > 0 ? failureSignals : undefined,
-          });
-          result.chat_results.push({
-            index,
-            expected_text: step.expectedText,
-            status: chatResult.status,
-            reason: chatResult.reason,
-            min_expected_count: chatResult.min_expected_count,
-            final_count: chatResult.final_count,
-            before_assistant_expected_count: chatResult.before_assistant_expected_count,
-            after_assistant_expected_count: chatResult.after_assistant_expected_count,
-            failure_signal: chatResult.failure_signal || "",
-          });
-          result.status = chatResult.status;
-          result.reason = `Prompt ${index + 1}/${promptSteps.length}: ${chatResult.reason}`;
-          if (chatResult.status !== "pass") break;
-        }
-      }
-    }
-
-    if (result.status === "pass" && filesystemChecks.length > 0) {
-      const filesystemResult = await runFilesystemChecks(filesystemChecks);
-      result.filesystem_checks = filesystemResult;
-      if (!result.evidence_collected.includes("filesystem")) result.evidence_collected.push("filesystem");
-      if (filesystemResult.status === "fail") {
-        result.status = "fail";
-        result.reason = filesystemResult.reason || "Filesystem checks failed.";
-      }
-    }
-  }
-} catch (error) {
-  if (!["env_issue", "blocked", "fail", "pass"].includes(result.status) || !result.reason) {
-    result.status = /Playwright is not installed|LANGBOT_FRONTEND_URL/.test(error.message) ? "env_issue" : "fail";
-  }
-  result.reason = result.reason || error.message;
-} finally {
-  if (browser?.page) await safeScreenshot(browser.page, paths.screenshot);
-  if (browser?.page && restorePlan) {
-    const restoreDiagnostic = await restorePipelineConfig(browser.page, restorePlan).catch((error) => ({
-      status: "fail",
-      pipeline_id: restorePlan.pipelineId,
-      reason: error.message,
-    }));
-    await writeFile(pipelineConfigRestoreDiagnosticPath, `${JSON.stringify(restoreDiagnostic, null, 2)}\n`, "utf8");
-    result.evidence.pipeline_config_restore_diagnostic_json = pipelineConfigRestoreDiagnosticPath;
-    result.pipeline_config_restore = restoreDiagnostic;
-  }
-  if (browser) await browser.close().catch(() => {});
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  const existingEvidence = {};
-  for (const [key, value] of Object.entries(result.evidence)) {
-    if (typeof value !== "string") continue;
-    const isResultFile = value === paths.automationResultJson || value === paths.resultJson;
-    if (isResultFile || await pathExists(value)) existingEvidence[key] = value;
-  }
-  result.evidence = existingEvidence;
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));

skills/scripts/e2e/refresh-local-login.mjs

@@ -1,84 +0,0 @@
-#!/usr/bin/env node
-
-import { env } from "node:process";
-import {
-  bodyText,
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  loadEnvFiles,
-  resetAndAuthLocalUser,
-  safeScreenshot,
-  setBrowserToken,
-  verifyBrowserToken,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const caseId = "refresh-local-login";
-const paths = evidencePaths(caseId);
-await loadEnvFiles();
-await ensureEvidence(paths);
-
-const result = {
-  source: "automation",
-  case_id: caseId,
-  status: "fail",
-  reason: "",
-  user: env.LANGBOT_E2E_LOGIN_USER || "",
-  frontend_url: env.LANGBOT_FRONTEND_URL || "",
-  backend_url: env.LANGBOT_BACKEND_URL || "",
-  backend_token_check: null,
-  browser_token_check: null,
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["ui", "screenshot", "console", "api_diagnostic"],
-};
-
-let browser;
-
-try {
-  const backendUrl = env.LANGBOT_BACKEND_URL;
-  const frontendUrl = env.LANGBOT_FRONTEND_URL;
-  const user = env.LANGBOT_E2E_LOGIN_USER;
-  const password = env.LANGBOT_E2E_LOGIN_PASSWORD || "LangBotE2ELocalPass!2026";
-  if (!backendUrl) throw new Error("LANGBOT_BACKEND_URL is not configured.");
-  if (!frontendUrl) throw new Error("LANGBOT_FRONTEND_URL is not configured.");
-  if (!user) throw new Error("LANGBOT_E2E_LOGIN_USER is required.");
-
-  const auth = await resetAndAuthLocalUser({ backendUrl, user, password });
-  result.backend_token_check = auth.check;
-
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  await setBrowserToken(page, frontendUrl, auth.token);
-  const browserCheck = await verifyBrowserToken(page, backendUrl);
-  result.browser_token_check = browserCheck;
-  if (!browserCheck.authenticated) {
-    throw new Error(browserCheck.reason || "Browser token check failed.");
-  }
-
-  await page.goto(`${frontendUrl.replace(/\/$/, "")}/home/monitoring`, { waitUntil: "domcontentloaded" });
-  await page.waitForLoadState("networkidle", { timeout: 10_000 }).catch(() => {});
-  const text = await bodyText(page);
-  if (!text.includes("Dashboard") && !text.includes("Pipelines") && !text.includes("流水线")) {
-    throw new Error("Token was written, but authenticated navigation was not visible.");
-  }
-
-  result.status = "pass";
-  result.reason = "Browser profile localStorage token refreshed.";
-} catch (error) {
-  result.status = "fail";
-  result.reason = error.message;
-} finally {
-  if (browser?.page) await safeScreenshot(browser.page, paths.screenshot);
-  if (browser) await browser.close().catch(() => {});
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(result.status === "pass" ? 0 : 1);

skills/scripts/e2e/webui-login-state.mjs

@@ -1,107 +0,0 @@
-#!/usr/bin/env node
-
-import {
-  bodyText,
-  createBrowser,
-  ensureEvidence,
-  evidencePaths,
-  exitCode,
-  gotoFrontend,
-  isLoginUrl,
-  loadEnvFiles,
-  localIsoWithOffset,
-  safeScreenshot,
-  verifyBrowserToken,
-  writeResult,
-} from "./lib/langbot-e2e.mjs";
-
-const caseId = "webui-login-state";
-await loadEnvFiles();
-const paths = evidencePaths(caseId);
-await ensureEvidence(paths);
-
-const startedAt = new Date();
-let browser;
-let result = {
-  source: "automation",
-  case_id: caseId,
-  run_id: paths.runId,
-  started_at: startedAt.toISOString(),
-  started_at_local: localIsoWithOffset(startedAt),
-  finished_at: "",
-  finished_at_local: "",
-  status: "fail",
-  reason: "",
-  url: "",
-  auth: null,
-  evidence: {
-    console_log: paths.consoleLog,
-    network_log: paths.networkLog,
-    screenshot: paths.screenshot,
-    automation_result_json: paths.automationResultJson,
-    result_json: paths.resultJson,
-  },
-  evidence_collected: ["ui", "screenshot", "console"],
-};
-
-try {
-  browser = await createBrowser(paths);
-  const { page } = browser;
-  await gotoFrontend(page);
-  result.url = page.url();
-
-  const backendUrl = process.env.LANGBOT_BACKEND_URL || "";
-  if (!backendUrl) {
-    result.status = "env_issue";
-    result.reason = "LANGBOT_BACKEND_URL is not configured.";
-    await safeScreenshot(page, paths.screenshot);
-    throw new Error(result.reason);
-  }
-
-  const auth = await verifyBrowserToken(page, backendUrl);
-  result.auth = auth;
-  const text = await bodyText(page);
-  const navigationSignals = [
-    "Dashboard",
-    "Bots",
-    "Pipelines",
-    "Knowledge",
-    "Plugins",
-    "首页",
-    "机器人",
-    "流水线",
-    "知识库",
-    "插件",
-  ];
-  const matchedSignal = navigationSignals.find((signal) => text.includes(signal));
-
-  if (!auth.authenticated) {
-    result.status = "blocked";
-    result.reason = auth.reason || "Browser profile token was not accepted by backend.";
-  } else if (isLoginUrl(page.url()) || /登录|Login|Sign in/i.test(text)) {
-    result.status = "fail";
-    result.reason = "Backend accepted the token, but the WebUI still showed the login page.";
-  } else if (!matchedSignal) {
-    result.status = "fail";
-    result.reason = "Opened WebUI, but no known LangBot navigation signal was visible.";
-  } else {
-    result.status = "pass";
-    result.reason = `Authenticated navigation signal visible: ${matchedSignal}`;
-  }
-
-  await safeScreenshot(page, paths.screenshot);
-} catch (error) {
-  if (!["env_issue", "blocked", "fail", "pass"].includes(result.status) || !result.reason) {
-    result.status = /Playwright is not installed|LANGBOT_FRONTEND_URL/.test(error.message) ? "env_issue" : "fail";
-    result.reason = error.message;
-  }
-} finally {
-  if (browser) await browser.close().catch(() => {});
-  const finishedAt = new Date();
-  result.finished_at = finishedAt.toISOString();
-  result.finished_at_local = localIsoWithOffset(finishedAt);
-  await writeResult(paths, result);
-  console.log(JSON.stringify(result, null, 2));
-}
-
-process.exit(exitCode(result.status));

skills/skills/.env

@@ -1,46 +0,0 @@
-# Shared defaults for LangBot skills.
-# Agents should read this file first, then load machine-local overrides from
-# skills/.env.local. Do not put workstation-specific absolute paths or secrets
-# in this committed file.
-
-# The UI URL that testing skills should open.
-# Default to the standalone Vite frontend. Set this to the backend WebUI URL
-# instead if your LangBot checkout serves the frontend from the backend.
-LANGBOT_FRONTEND_URL=http://127.0.0.1:3000
-
-# LangBot API/backend URL.
-LANGBOT_BACKEND_URL=http://127.0.0.1:5300
-
-# Common standalone frontend dev URL. This is a candidate, not the default.
-LANGBOT_DEV_FRONTEND_URL=http://127.0.0.1:3000
-
-# Local repository paths. Copy skills/.env.example to skills/.env.local and set
-# these for your checkout.
-LANGBOT_REPO=
-LANGBOT_WEB_REPO=
-LANGBOT_RAG_PLUGIN_REPO=
-LANGBOT_PARSER_PLUGIN_REPO=
-
-# Browser profile and Playwright/Chromium paths.
-LANGBOT_BROWSER_PROFILE=
-LANGBOT_CHROMIUM_EXECUTABLE=
-
-# Optional local proxy defaults. Do not store secrets here.
-LANGBOT_PROXY_HTTP=
-LANGBOT_PROXY_SOCKS=
-LANGBOT_NO_PROXY=localhost,127.0.0.1,::1
-
-# Optional case-specific pipeline targets. Put machine-local values in
-# skills/.env.local so runner-specific cases do not accidentally reuse the
-# generic LANGBOT_PIPELINE_URL.
-# LANGBOT_PIPELINE_URL=http://127.0.0.1:3000/home/pipelines?id=<generic-pipeline-uuid>
-# LANGBOT_PIPELINE_NAME=Generic QA Pipeline
-# LANGBOT_LOCAL_AGENT_PIPELINE_URL=http://127.0.0.1:3000/home/pipelines?id=<local-agent-pipeline-uuid>
-# LANGBOT_LOCAL_AGENT_PIPELINE_NAME=Local Agent QA Pipeline
-# LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL=http://127.0.0.1:3000/home/pipelines?id=<acp-agent-runner-pipeline-uuid>
-# LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME=ACP AgentRunner QA Pipeline
-# LANGBOT_ACP_AGENT_RUNNER_SSH_TARGET=yhh@101.34.71.12
-# LANGBOT_ACP_AGENT_RUNNER_SSH_PORT=22
-# LANGBOT_ACP_AGENT_RUNNER_SSH_IDENTITY_FILE=
-# LANGBOT_ACP_AGENT_RUNNER_SSH_EXTRA_OPTIONS=
-# LANGBOT_ACP_AGENT_RUNNER_REMOTE_WORKSPACE=/home/yhh/langbot-e2e/acp-workspace

skills/skills/.env.example

@@ -1,36 +0,0 @@
-# Copy this file to skills/.env.local and adjust it for your machine.
-# Do not put API keys, OAuth tokens, browser localStorage tokens, or provider
-# credentials in committed files.
-
-# LangBot WebUI and backend endpoints.
-LANGBOT_FRONTEND_URL=http://127.0.0.1:3000
-LANGBOT_BACKEND_URL=http://127.0.0.1:5300
-LANGBOT_DEV_FRONTEND_URL=http://127.0.0.1:3000
-
-# Local repository paths.
-LANGBOT_REPO=/path/to/LangBot
-LANGBOT_WEB_REPO=/path/to/LangBot/web
-LANGBOT_RAG_PLUGIN_REPO=/path/to/langbot-rag
-LANGBOT_PARSER_PLUGIN_REPO=/path/to/langbot-parser
-
-# Browser profile and Playwright/Chromium paths.
-LANGBOT_BROWSER_PROFILE=/path/to/langbot-playwright-profile
-LANGBOT_CHROMIUM_EXECUTABLE=/path/to/ms-playwright/chromium/chrome
-
-# Optional local proxy defaults. Leave blank if not needed.
-LANGBOT_PROXY_HTTP=
-LANGBOT_PROXY_SOCKS=
-LANGBOT_NO_PROXY=localhost,127.0.0.1,::1
-
-# Optional generic pipeline target for generic Debug Chat smoke tests.
-LANGBOT_PIPELINE_URL=
-LANGBOT_PIPELINE_NAME=
-
-# Optional case-specific runner targets. Prefer these for runner-specific cases
-# so the automation cannot silently test the wrong runner.
-LANGBOT_LOCAL_AGENT_PIPELINE_URL=
-LANGBOT_LOCAL_AGENT_PIPELINE_NAME=
-LANGBOT_CODEX_AGENT_PIPELINE_URL=
-LANGBOT_CODEX_AGENT_PIPELINE_NAME=
-LANGBOT_CLAUDE_CODE_AGENT_PIPELINE_URL=
-LANGBOT_CLAUDE_CODE_AGENT_PIPELINE_NAME=

skills/skills/langbot-deploy/SKILL.md

@@ -1,84 +0,0 @@
----
-name: langbot-deploy
-description: Deploy and configure a LangBot instance — Docker / Docker Compose, Kubernetes, the config.yaml model, the Box sandbox runtime, the plugin runtime, and the global API key. Use when installing, deploying, upgrading, or configuring LangBot in production or self-hosted environments. Triggers on "deploy langbot", "langbot docker", "langbot compose", "langbot kubernetes", "langbot config.yaml", "langbot box runtime", "langbot global api key".
----
-
-# LangBot Deployment & Configuration
-
-Covers running LangBot in production. For development see `langbot-dev`.
-
-## Docker Compose (recommended)
-
-```bash
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
-
-# Full stack (sandbox/Box + stdio MCP hosting + skill add/edit enabled)
-docker compose --profile all up
-
-# Basic (no Box runtime)
-docker compose up
-```
-
-The `all` / `box` profile starts three services:
-
-- `langbot` — main app, serves API + UI on `:5300`.
-- `langbot_plugin_runtime` — plugin runtime (control `:5400`, debug `:5401`).
-- `langbot_box` — Box sandbox runtime (`:5410`). Uses the host Docker socket to
-  spawn sandbox containers, so the **Box root host path and in-container path
-  must be identical** (`BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}`).
-
-With Box off, the dashboard/skills list stays visible (read-only) but sandbox
-tools, skill add/edit, and stdio MCP are disabled. Set `box.enabled: false`
-(or `BOX__ENABLED=false`) to match.
-
-## Kubernetes
-
-See `docker/kubernetes.yaml` and the deployment guide at
-https://docs.langbot.app. `docker/deploy-k8s-test.sh` is a test helper.
-
-## config.yaml (generated at `data/config.yaml` on first run)
-
-Top-level sections: `api`, `system`, `command`, `concurrency`, `proxy`,
-`database`, `vdb`, `storage`, `plugin`, `monitoring`, `box`, `space`.
-
-Key settings:
-
-| Key | Meaning |
-| --- | --- |
-| `api.port` | HTTP API + UI port (default 5300) |
-| `api.global_api_key` | **Global API key** for the HTTP API + MCP server. Non-empty = accepted with no login/DB record; no `lbk_` prefix required. Empty = disabled. Plaintext — trusted/internal only, serve over HTTPS. |
-| `plugin.runtime_ws_url` | Standalone plugin runtime WS URL (e.g. `ws://langbot_plugin_runtime:5400/control/ws`) |
-| `box.enabled` | Master switch for the Box sandbox runtime |
-| `box.backend` | `local` (Docker/nsjail autopick) / `docker` / `nsjail` / `e2b`; env override `BOX__BACKEND` |
-| `box.runtime.endpoint` | External Box runtime URL (e.g. `ws://127.0.0.1:5410`); empty = local auto-managed |
-
-Many keys have `ENV__SUBKEY` overrides (e.g. `BOX__BACKEND`, `BOX__ENABLED`).
-
-## Runtimes & flags
-
-- LangBot started directly spawns the plugin runtime over **stdio**.
-- In containers it connects to a standalone runtime over **WebSocket**; start
-  with `--standalone-runtime`.
-- Box has a parallel `--standalone-box` flag; the Docker box host is
-  `langbot_box:5410`.
-
-## Global API key — enabling for agents/automation
-
-```yaml
-# data/config.yaml
-api:
-    port: 5300
-    global_api_key: 'a-strong-secret'   # empty disables it
-```
-
-This key authenticates both the HTTP API and the MCP server (`/mcp`) without a
-login session. See `langbot-mcp-ops` for using it, and `docs/API_KEY_AUTH.md`.
-
-## Pitfalls
-
-- "No supported sandbox backend (Docker / nsjail / E2B)" with Docker running
-  usually means the user isn't in the `docker` group →
-  `sudo usermod -aG docker <user>` and restart in a new shell.
-- Box root host/container path mismatch breaks sandbox container creation.
-- Don't commit a non-empty `api.global_api_key` to version control.

skills/skills/langbot-dev/SKILL.md

@@ -1,116 +0,0 @@
----
-name: langbot-dev
-description: Develop, build, and debug the LangBot core backend and web frontend. Use when working inside the LangBot repository — backend (Python/Quart, src/langbot/pkg), the Vite/React web UI, HTTP API controllers/services, Alembic migrations, or the MCP server. Covers the dev environment (uv, pnpm), repo layout, the API auth model (user token / API key / global key), adding API endpoints, and the rule that API changes must update the MCP server and skills. Triggers on "langbot backend", "langbot dev", "langbot api", "add langbot endpoint", "langbot migration".
----
-
-# LangBot Core Development
-
-This skill covers developing the LangBot core (the main repo), distinct from
-plugin development (see `langbot-plugin-dev`) and deployment (`langbot-deploy`).
-
-## Stack
-
-- **Backend**: Python `>=3.11,<4.0`, deps via `uv`. Framework: **Quart** (async
-  Flask). Serves the HTTP API + pre-built web UI on `http://127.0.0.1:5300`.
-- **Frontend** (`web/`): **Vite + React Router 7 + shadcn/ui + Tailwind**,
-  managed by `pnpm`. Dev server on `:3000`. (NOT Next.js — `dev` script is `vite`.)
-
-## Dev environment
-
-```bash
-# Backend
-pip install uv
-uv sync --dev
-uv run main.py            # API + UI on http://127.0.0.1:5300
-
-# Frontend (separate terminal)
-cd web
-cp .env.example .env
-pnpm install
-pnpm dev                  # http://127.0.0.1:3000 (reads VITE_API_BASE_URL)
-
-# Lint/format hooks (CI runs the same checks)
-uv run pre-commit install
-```
-
-First run generates `data/config.yaml`; DB defaults to SQLite (PostgreSQL
-supported). Migrations run automatically on startup.
-
-## Repo layout (key paths)
-
-```
-src/langbot/
-├── __main__.py             # entrypoint, CLI flags (--standalone-runtime/-box/--debug)
-├── pkg/
-│   ├── api/
-│   │   ├── http/           # Quart controllers + services
-│   │   │   ├── controller/groups/   # route groups (@group.group_class)
-│   │   │   └── service/             # business logic (called by controllers AND MCP)
-│   │   └── mcp/            # MCP server (server.py = tools, mount.py = ASGI dispatch)
-│   ├── core/               # app bootstrap, stages, task manager
-│   ├── platform/ provider/ pipeline/ plugin/ box/ skill/ rag/ vector/
-│   ├── command/ persistence/ storage/ config/ entity/ telemetry/
-│   └── templates/config.yaml        # config template (top-level: api, system, plugin, box, space...)
-├── web/                    # Vite SPA
-└── docker/                 # compose deployment
-```
-
-## HTTP API auth model
-
-Route auth is declared per-route via `AuthType` in
-`pkg/api/http/controller/group.py`:
-
-- `NONE` — public.
-- `USER_TOKEN` — web UI JWT (`Authorization: Bearer <jwt>`).
-- `API_KEY` — `X-API-Key` or `Authorization: Bearer <key>`.
-- `USER_TOKEN_OR_API_KEY` — either.
-
-API keys are verified by `apikey_service.verify_api_key()`, which accepts:
-1. the **global key** from `config.yaml` `api.global_api_key` (no DB, no login,
-   no `lbk_` prefix required), then
-2. **web-UI keys** (DB-stored, `lbk_` prefix).
-
-Route groups self-register via `@group.group_class(name, path)` and are
-discovered by `importutil.import_modules_in_pkg`.
-
-## Adding an API endpoint
-
-1. Add/extend a controller in `pkg/api/http/controller/groups/` and the matching
-   service method in `pkg/api/http/service/`.
-2. Pick the right `AuthType`.
-3. **If the endpoint should be agent-accessible, add/adjust the matching MCP tool
-   in `pkg/api/mcp/server.py` and update the `langbot-mcp-ops` skill.** API and
-   MCP surface must stay aligned (see `AGENTS.md`).
-4. Update `docs/service-api-openapi.json` if you maintain the OpenAPI overview.
-
-## Database migrations (Alembic)
-
-Single migration set supports SQLite + PostgreSQL. Files in
-`src/langbot/pkg/persistence/alembic/versions/`.
-
-```bash
-# From project root (needs data/config.yaml)
-uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description"
-```
-
-## Standards
-
-- All code comments/docstrings in **English**; user-facing strings need **i18n**
-  (`en_US` + `zh_Hans` minimum, `ja_JP` where present).
-- Consider toC and toB compatibility + security.
-- Commit format: `<type>(<scope>): <subject>` (feat/fix/docs/refactor/...).
-
-## Tests
-
-```bash
-uv run pytest tests/unit_tests -q          # unit tests
-uv run pytest tests/unit_tests/api -q      # API service tests
-uv run python tests/manual/mcp_smoke.py    # MCP server e2e smoke
-```
-
-## See also
-
-- `langbot-plugin-dev` — plugin SDK / runtime development.
-- `langbot-testing` — WebUI/e2e QA harness (`bin/lbs`).
-- `langbot-deploy` — Docker/compose deployment + config.
-- `langbot-mcp-ops` — operating the LangBot MCP server.

skills/skills/langbot-eba-adapter-dev/SKILL.md

@@ -1,301 +0,0 @@
----
-name: langbot-eba-adapter-dev
-description: Build, refactor, and test LangBot platform adapters for the Event-Based Agents architecture. Use when adding or migrating Telegram, Discord, or other messaging platform adapters to the EBA adapter layout, validating unified event/message conversion, writing live adapter probes, or using standalone plugin runtime plus Computer Use for end-to-end platform testing.
----
-
-# LangBot EBA Adapter Development
-
-Use this skill when implementing or reviewing a LangBot platform adapter under the Event-Based Agents architecture.
-
-## Controlling a running instance via MCP
-
-Beyond writing code, you can **drive a live LangBot instance over MCP** — no raw
-HTTP needed. Two MCP servers exist (both reuse existing API keys; see `AGENTS.md`):
-
-- **LangBot instance** — `http://<host>:5300/mcp` (auth: web-UI `lbk_` key or the
-  `api.global_api_key` from `config.yaml`). Manage bots, pipelines, models,
-  knowledge bases, and skills. See the **`langbot-mcp-ops`** skill.
-- **LangBot Space marketplace** — `https://space.langbot.app/mcp` (auth: Personal
-  Access Token). Search plugins / MCP servers / skills. See the
-  **`langbot-space-ops`** skill.
-
-> Any change to an agent-accessible HTTP API endpoint must keep the matching MCP
-> tool and these skills in sync.
-
-## Core Rule
-
-Do not let platform-native event or message shapes leak into LangBot's common path. Each adapter must convert incoming SDK objects into unified EBA entities before dispatch:
-
-- Events: `langbot_plugin.api.entities.builtin.platform.events`
-- Message chains: `langbot_plugin.api.entities.builtin.platform.message.MessageChain`
-- Users/groups/members: `langbot_plugin.api.entities.builtin.platform.entities`
-- Raw platform objects may remain only in `source_platform_object` for debugging or platform-specific escape hatches.
-
-## Start Here
-
-1. Read the EBA design docs in `LangBot/docs/event-based-agents/`.
-2. Read the architecture-level acceptance checklist before writing or validating code:
-   - `LangBot/docs/event-based-agents/adapters/acceptance-checklist.md`
-3. Read the current reference adapter before writing code. Prefer Telegram first:
-   - `LangBot/src/langbot/pkg/platform/adapters/telegram/`
-   - `LangBot/docs/event-based-agents/adapters/telegram.md`
-4. Read the legacy source adapter for the target platform:
-   - `LangBot/src/langbot/pkg/platform/sources/<platform>.py`
-   - `LangBot/src/langbot/pkg/platform/sources/<platform>.yaml`
-5. Inspect SDK entity definitions in `langbot-plugin-sdk/src/langbot_plugin/api/entities/builtin/platform/`.
-6. Search before assuming APIs. Platform SDKs change often.
-
-## Adapter Layout
-
-Create one directory per adapter:
-
-```text
-LangBot/src/langbot/pkg/platform/adapters/<platform>/
-├── __init__.py
-├── adapter.py
-├── api_impl.py
-├── event_converter.py
-├── manifest.yaml
-├── message_converter.py
-├── platform_api.py
-├── types.py
-└── <platform>.svg
-```
-
-Add optional helpers such as `voice.py` only when the platform has a real domain-specific surface.
-
-Ensure `pyproject.toml` package data includes adapter assets:
-
-```toml
-package-data = { "langbot" = ["templates/**", "pkg/platform/sources/*", "pkg/platform/adapters/**", ...] }
-```
-
-## Implementation Checklist
-
-- `manifest.yaml` declares `metadata.name`, config schema, supported events, common APIs, and platform-specific APIs.
-- `adapter.py` creates the platform client, subscribes to native events, filters self/bot loops where appropriate, calls `event_converter.target2yiri(...)`, then dispatches the EBA event.
-- `event_converter.py` maps native events to EBA event classes such as `MessageReceivedEvent`, `MessageEditedEvent`, `MessageDeletedEvent`, `MessageReactionEvent`, `MemberJoinedEvent`, `BotInvitedToGroupEvent`, and `PlatformSpecificEvent`.
-- `message_converter.py` maps native messages to `MessageChain`, and maps `MessageChain` back to the platform send format.
-- `api_impl.py` implements common EBA APIs: send, reply, edit, delete, forward, user/group/member lookup, moderation, upload/file URL, leave group.
-- `platform_api.py` keeps platform-specific calls behind `call_platform_api(action, params)`.
-- Unsupported common APIs must raise explicit SDK platform errors such as `NotSupportedError`; do not silently no-op.
-- Destructive APIs such as kick, ban, leave, delete, or moderation must be gated in live tests and documented.
-
-## Conversion Contract
-
-For message events, the common shape should look like this regardless of platform:
-
-```python
-platform_events.MessageReceivedEvent(
-    type="message.received",
-    adapter_name="<platform>",
-    message_id=<platform_message_id>,
-    message_chain=platform_message.MessageChain([...]),
-    sender=platform_entities.User(...),
-    chat_type=platform_entities.ChatType.PRIVATE or ChatType.GROUP,
-    chat_id=<conversation_or_channel_id>,
-    group=platform_entities.UserGroup(...) or None,
-    source_platform_object=<raw_object>,
-)
-```
-
-Message content should use common components:
-
-- `Source` for original message id/time when available.
-- `Plain` for text.
-- `At` / `AtAll` for mentions.
-- `Image`, `Voice`, `File` for media.
-- `Forward` only when the platform can represent or emulate it safely.
-
-If a platform event cannot cleanly map to a common event, emit `PlatformSpecificEvent` with a compact `action` and structured `data`.
-
-## Unit Tests
-
-Add focused tests under `LangBot/tests/unit_tests/platform/test_<platform>_eba_adapter.py`.
-
-Cover at least:
-
-- Manifest supported events match adapter `supported_events()`.
-- Manifest supported APIs match adapter `supported_apis()`.
-- Platform API map matches manifest actions.
-- Dispatcher chooses the most specific EBA listener.
-- Message converter maps every supported common component both directions where possible:
-  - `Source`
-  - `Plain`
-  - `At`
-  - `AtAll`
-  - `Image`
-  - `Voice`
-  - `File`
-  - `Quote`
-  - `Face`
-  - `Forward`
-  - `Unknown`
-  - mixed chains preserving order
-- Event converter maps message received/edited/deleted/reaction, raw uncached gateway events, member events, and bot join/leave events.
-- Send/reply methods pass correct platform kwargs and return `MessageResult`.
-
-Run the existing reference adapter tests too:
-
-```bash
-cd LangBot
-uv run pytest tests/unit_tests/platform/test_<platform>_eba_adapter.py tests/unit_tests/platform/test_telegram_eba_adapter.py
-uv run python -m py_compile tests/e2e/live_<platform>_eba_probe.py
-git diff --check
-```
-
-## Live Test Workflow
-
-Direct adapter live probes are useful diagnostics, but they are not sufficient acceptance evidence for EBA. Treat `tests/e2e/live_<platform>_eba_probe.py` as an auxiliary tool only. The final adapter record must distinguish:
-
-- `plugin-e2e-ui`: real SDK plugin through standalone runtime, LangBot core, adapter, and a real/simulator UI action. This can mark an inbound UI item complete.
-- `plugin-e2e-protocol`: real SDK plugin through standalone runtime, LangBot core, adapter, and a protocol-boundary injected event. This is useful evidence but must not be claimed as UI coverage.
-- `plugin-e2e-outbound`: real SDK plugin calls an API and the bot output is visible in the real/simulator UI. This can mark send/API coverage complete.
-- `adapter-live`: direct adapter probe connected to a real/simulator endpoint. This is auxiliary only.
-- `unit`: mocked conversion/API-shape coverage. This is auxiliary only.
-- `not-supported`: platform protocol or SDK has no equivalent. Must include the reason.
-- `blocked`: intended capability could not be verified. This is not complete.
-
-Write a live probe in `LangBot/tests/e2e/live_<platform>_eba_probe.py`. It should:
-
-1. Read token/client ids from environment variables or CLI args.
-2. Start the adapter directly.
-3. Register an EBA listener and write JSONL evidence to `LangBot/data/temp/`.
-4. Wait for a real user/platform event instead of fabricating the entrypoint.
-5. Exercise common APIs and `call_platform_api` actions.
-6. Observe returned gateway events for edit/delete/reaction/member/bot lifecycle where available.
-7. Print a summary containing passed, failed, skipped, and observed event types.
-8. Redact or avoid printing secrets.
-9. Keep destructive operations behind flags and run them last.
-
-Use Computer Use when the user asks for real platform end-to-end coverage. Actually send messages/click reactions in the platform UI or otherwise trigger real user-side events; do not replace that with unit tests.
-
-For media/component acceptance, keep the direction and trigger source explicit:
-
-- Real inbound media only counts when a human-side platform UI or simulator UI sends the image/file/voice to the bot and the plugin JSONL records the corresponding common component.
-- Bot outbound media only proves `send_message`/adapter send conversion. It does not prove inbound conversion.
-- Protocol-boundary injection, such as sending a OneBot event directly into a reverse WebSocket adapter, is useful and should be labelled `plugin-e2e-protocol`, but it must not be reported as UI-level end-to-end media upload.
-- If the UI cannot send or upload the media, record the item as `blocked` with the exact client/simulator limitation.
-
-## Standalone Runtime + Plugin Test
-
-When validating the whole LangBot EBA path, test with the SDK standalone runtime and a real test plugin. This is the required acceptance path; direct adapter calls do not prove the EBA architecture path.
-
-The required path is:
-
-```text
-Real platform / simulator UI
-  -> platform SDK native event
-  -> adapter event converter
-  -> unified EBA event/entity/message types
-  -> LangBot core event dispatch
-  -> standalone SDK runtime
-  -> real test plugin listener
-  -> plugin calls platform APIs through SDK
-  -> LangBot core API dispatch
-  -> adapter API implementation
-  -> real platform / simulator UI
-```
-
-Typical shape:
-
-```bash
-# Terminal 1, SDK repo
-cd langbot-plugin-sdk
-uv run python -m langbot_plugin.cli.__init__ rt \
-  --debug-only \
-  --ws-control-port 5400 \
-  --ws-debug-port 5401 \
-  --skip-deps-check
-
-# Terminal 2, LangBot repo
-cd LangBot
-export PYTHONPATH=/absolute/path/to/langbot-plugin-sdk/src:${PYTHONPATH:-}
-uv run main.py --standalone-runtime
-
-# Terminal 3, plugin directory
-export DEBUG_RUNTIME_WS_URL=ws://127.0.0.1:5401/plugin/ws
-export EBA_PROBE_LOG=/absolute/path/to/LangBot/data/temp/<platform>_eba_plugin_probe.jsonl
-export EBA_PROBE_API=1
-export EBA_PROBE_COMPONENT_SWEEP=1
-export EBA_PROBE_PLATFORM_API=1
-uv --project /absolute/path/to/langbot-plugin-sdk run python -m langbot_plugin.cli.__init__ run
-```
-
-Use an EBA probe plugin that subscribes to all relevant EBA event classes and runs SDK API calls after the first `MessageReceived`.
-
-The plugin evidence should be JSONL and include:
-
-- event class and `event.type`
-- adapter name
-- chat type and chat ID
-- sender/user/group IDs with secrets redacted
-- `bot_uuid` and `adapter_name`, proving LangBot filled common routing fields before plugin dispatch
-- received `message_chain` component list
-- API action name, input summary, result or error
-- unsupported or blocked reason when an item is skipped
-
-For full adapter acceptance, enable both probe sweeps:
-
-- `EBA_PROBE_COMPONENT_SWEEP=1` sends the required outbound message components through `send_message`.
-- `EBA_PROBE_PLATFORM_API=1` calls common safe APIs plus selected `call_platform_api` actions for the adapter.
-
-The SDK must support `plugin.call_platform_api(bot_uuid, action, params)` for platform-specific acceptance. If the SDK cannot call a platform-specific action from the plugin, the adapter cannot be fully accepted even if direct adapter probes pass.
-
-## Required EBA Acceptance Coverage
-
-Before marking an adapter migrated, fill out an adapter record against `LangBot/docs/event-based-agents/adapters/acceptance-checklist.md`.
-
-At minimum, the record must cover these categories:
-
-- Message receive component tests through `plugin-e2e-ui`: `Source`, `Plain`, `At`, `AtAll`, `Image`, `Voice`, `File`, `Quote`, `Face`, `Forward`, `Unknown`, and mixed chains where the platform supports them. Protocol-only receive evidence must be labelled `plugin-e2e-protocol`.
-- Message send component tests through `plugin-e2e-outbound`: `Plain`, `At`, `AtAll`, `Image`, `Voice`, `File`, `Quote`, `Face`, `Forward`, and mixed chains where the platform supports them.
-- Every event declared in `manifest.yaml -> spec.supported_events`.
-- Every common API declared in `manifest.yaml -> spec.supported_apis.required` and `optional`.
-- Every action declared in `manifest.yaml -> spec.platform_specific_apis`.
-- Compatibility tests for manifest declarations, legacy message listener fallback, EBA listener specificity, bot self-message filtering, and `source_platform_object` reply/debug behavior.
-
-Do not declare an event or API in the manifest unless it has an implementation path and an acceptance entry. If a platform or simulator lacks a capability, document it as `not-supported` or `blocked` rather than silently omitting the test.
-
-## Common Pitfalls
-
-- `get_bots()` may return bot dictionaries, not UUID strings. Probe plugins should select an enabled dict and pass `bot["uuid"]` to `get_bot_info()` and `send_message()`.
-- Make sure the probe subscribes to every event you claim to verify. Missing `MessageDeleted` subscription can make a working adapter look untested.
-- Some platforms emit both cached and raw gateway events, producing duplicate evidence for delete/reaction. Count this explicitly; do not treat duplicates as failure unless semantics differ.
-- Self-message filtering is platform-specific. Filter bot-originated `message.received` loops, but do not accidentally filter edit/delete events needed for bot-owned API probes.
-- Reaction events may be filtered for bot self reactions. To test user reaction add/remove, use real UI interaction or a real user token path if permitted.
-- File uploads usually happen as message attachments. A standalone `upload_file` API may need to be `NotSupportedError`.
-- Live probes should not leak bot tokens through command output, logs, docs, or final answers.
-- Discord requires privileged intents for message content and members. Missing intents can look like converter bugs.
-- Telegram Bot API exposes only limited member lists; document capability gaps.
-- Do not mark moderation APIs verified unless they ran against a disposable target member/bot.
-- If `leave_group` is tested, run it last because the test bot will be removed from the server/group.
-- Restore local LangBot DB/test state after live runs if you enabled temporary bots or changed plugin settings.
-
-## Documentation Record
-
-Add or update `LangBot/docs/event-based-agents/adapters/<platform>.md` in the same style as Telegram:
-
-- Status and adapter directory.
-- Configuration table matching manifest fields.
-- Supported EBA event list.
-- Common API table with support and limitations.
-- `call_platform_api` action list.
-- Receive component table with evidence level per component.
-- Send component table with evidence level per component.
-- Event table with evidence level per event.
-- Common API table with evidence level per API.
-- Platform-specific API table with evidence level per action.
-- Live test record with exact date, endpoint/simulator, standalone runtime command, test plugin path/name, JSONL evidence path, channel/group type, observed events, APIs exercised, destructive operations, and skipped items.
-
-Be honest. Put untested or skipped APIs in the document with the reason. Do not imply full parity when a platform cannot provide the same information density.
-
-## Before Finishing
-
-- Run unit tests and compile the live probe.
-- Run the standalone runtime plugin E2E path for every required acceptance item that the platform supports.
-- Run `git diff --check`.
-- Summarize live JSONL evidence by event type.
-- Stop all long-running runtimes and probes.
-- Confirm no secrets are staged.
-- Leave unrelated untracked files alone.

skills/skills/langbot-env-setup/SKILL.md

@@ -1,28 +0,0 @@
----
-name: langbot-env-setup
-description: Prepare a local LangBot development and testing environment for an AI agent. Use when setting up WSL or Linux development, shared local URL variables, proxy variables, backend/frontend startup, Playwright MCP browser access, GitHub OAuth browser login, persisted Chrome profiles, or future Codex computer-use environment paths.
----
-
-# LangBot Environment Setup
-
-Use this skill when a task needs LangBot to be in a testable state before product testing or development verification.
-
-## Routing
-
-- **Shared local variables**: read `../.env` before using URL, path, browser profile, or proxy defaults.
-- **Always start here**: read `references/browser-access-selection.md` to choose the browser-control path.
-- **LangBot service checks and startup**: read `references/service-startup.md`.
-- **Computer Use available**: read `references/computer-use.md`. This path usually needs less browser/MCP setup.
-- **No Computer Use, browser automation required**: read `references/playwright-mcp.md`.
-- **GitHub OAuth or persisted login profile**: read `references/oauth-browser-profile.md`.
-- **WSL-specific notes**: read `references/wsl-notes.md` only when running under WSL.
-- **Proxy setup**: read `references/proxy.md` when external login, model provider tests, or package downloads time out.
-- **Headless-only automation**: use only after a profile already contains a valid LangBot login. Do not ask the agent to enter GitHub credentials or 2FA.
-
-## Rules
-
-- Never handle the user's GitHub password, passkey, recovery code, or 2FA secret.
-- For OAuth login, open a visible browser and let the user complete the credential steps.
-- Reuse a fixed browser profile path so the agent can later access the logged-in LangBot session.
-- Keep environment-specific paths and commands in `references/`, not in this file.
-- Treat environment setup as complete only after the target LangBot services are reachable and the browser profile can access the WebUI.

skills/skills/langbot-env-setup/references/browser-access-selection.md

@@ -1,15 +0,0 @@
-# Browser Access Selection
-
-Choose the lightest browser-control path that can complete the task.
-
-## Decision Order
-
-1. If Codex Computer Use, Claude Computer Use, or another visible browser-control tool is available, use `computer-use.md`.
-2. If no computer-control tool is available but Playwright MCP is available, use `playwright-mcp.md`.
-3. If the browser session must survive restarts or OAuth login is required, also use `oauth-browser-profile.md`.
-4. If running under WSL, add `wsl-notes.md`.
-5. If external sites or model providers time out, add `proxy.md`.
-
-## Principle
-
-Computer Use and Playwright MCP are alternative browser-control paths. Both still need LangBot services to be reachable, so service checks stay in `service-startup.md`.

skills/skills/langbot-env-setup/references/computer-use.md

@@ -1,20 +0,0 @@
-# Computer Use Browser Path
-
-Use this path when Codex Computer Use, Claude Computer Use, or another agent-visible browser-control capability is available.
-
-## Why This Path Is Simpler
-
-Computer Use can interact with a visible browser directly, so it usually does not need Playwright MCP configuration or a separate MCP browser bridge.
-
-## Workflow
-
-1. Verify LangBot backend/frontend with `service-startup.md`.
-2. Open the WebUI in the controlled browser.
-3. If login is needed, let the user complete GitHub OAuth. Never handle credentials or 2FA.
-4. Keep the browser/profile available for later testing.
-5. Hand off to `langbot-testing` after the page shows the logged-in WebUI.
-
-## Still Required
-
-- Proxy may still be needed for GitHub OAuth or model provider tests. Use `proxy.md`.
-- Persisted profile details may still matter if the computer-control browser is restarted. Use `oauth-browser-profile.md` if login state must survive.

skills/skills/langbot-env-setup/references/oauth-browser-profile.md

@@ -1,62 +0,0 @@
-# OAuth Browser Profile
-
-Use this reference when LangBot or LangBot Space needs GitHub OAuth login and the agent must reuse the authenticated browser state later.
-
-Read `skills/.env` first for `LANGBOT_BACKEND_URL`, `LANGBOT_FRONTEND_URL`, `LANGBOT_BROWSER_PROFILE`, `LANGBOT_CHROMIUM_EXECUTABLE`, and proxy defaults.
-
-## Rules
-
-- Never handle the user's GitHub password, passkey, recovery code, or 2FA secret.
-- Open a visible browser and let the user complete credential steps.
-- Reuse a fixed browser profile path.
-- Do not print token values. It is acceptable to report localStorage key names.
-
-## Manual Visible Login Flow
-
-1. Verify LangBot backend is reachable with `service-startup.md`.
-2. Launch a visible Chromium window with the persistent profile:
-
-```bash
-setsid "$LANGBOT_CHROMIUM_EXECUTABLE" \
-  --no-sandbox \
-  --ozone-platform=x11 \
-  --user-data-dir="$LANGBOT_BROWSER_PROFILE" \
-  --proxy-server="$LANGBOT_PROXY_SOCKS" \
-  --proxy-bypass-list="$LANGBOT_NO_PROXY" \
-  "$LANGBOT_BACKEND_URL/login" \
-  >/tmp/langbot-visible-chrome.log 2>&1 < /dev/null &
-```
-
-3. The user completes:
-
-```text
-Login with Space -> Login with GitHub -> GitHub credentials / 2FA -> authorize
-```
-
-4. The agent can then reuse the same profile for automated checks.
-
-## Expected Successful State
-
-After login, LangBot should redirect away from `/login`, for example to a `/home/...` URL on the selected origin.
-
-Expected visible signals:
-
-```text
-LangBot
-Dashboard
-Home
-Bots
-Pipelines
-Knowledge
-Extensions
-```
-
-Expected localStorage key names:
-
-```text
-token
-userEmail
-langbot_language
-```
-
-If the user logged in on one origin but `LANGBOT_FRONTEND_URL` still shows `/login`, copy only the auth state needed between origins. Do not print token values.

skills/skills/langbot-env-setup/references/playwright-mcp.md

@@ -1,30 +0,0 @@
-# Playwright MCP Browser Path
-
-Use this path when the agent needs browser automation but no Computer Use browser-control path is available.
-
-## Known Paths
-
-- Persistent browser profile: `LANGBOT_BROWSER_PROFILE` from `skills/.env.local`
-- Chromium executable: `LANGBOT_CHROMIUM_EXECUTABLE` from `skills/.env.local`
-- Codex MCP config: `$CODEX_HOME/config.toml` or the config path used by the active agent.
-
-## MCP Config
-
-Keep the profile path fixed so the agent can reuse authenticated state.
-
-```toml
-[mcp_servers.playwright]
-command = "npx"
-args = ["-y", "@playwright/mcp@latest", "--no-sandbox", "--executable-path", "<LANGBOT_CHROMIUM_EXECUTABLE>", "--proxy-server", "<LANGBOT_PROXY_SOCKS>", "--proxy-bypass", "localhost,127.0.0.1", "--user-data-dir", "<LANGBOT_BROWSER_PROFILE>"]
-```
-
-After changing MCP config, restart Codex so the MCP server is relaunched with the new args.
-
-## Visible Login
-
-For OAuth login, Playwright MCP's headless browser is not enough. Launch a visible browser with the same profile and let the user complete login. Use `oauth-browser-profile.md`.
-
-## Common Failures
-
-- MCP still uses old args after editing config: restart Codex or kill old `playwright-mcp` processes and restart the session.
-- Browser is headless during OAuth: use the visible login command from `oauth-browser-profile.md`.

skills/skills/langbot-env-setup/references/proxy.md

@@ -1,30 +0,0 @@
-# Proxy Setup
-
-Use this reference when GitHub OAuth, package installation, model provider tests, or external API calls time out.
-
-Read defaults from `skills/.env` first.
-
-## Standard Local Proxy
-
-```bash
-export HTTP_PROXY="$LANGBOT_PROXY_HTTP"
-export HTTPS_PROXY="$LANGBOT_PROXY_HTTP"
-export ALL_PROXY="$LANGBOT_PROXY_SOCKS"
-export http_proxy="$LANGBOT_PROXY_HTTP"
-export https_proxy="$LANGBOT_PROXY_HTTP"
-export all_proxy="$LANGBOT_PROXY_SOCKS"
-export NO_PROXY="$LANGBOT_NO_PROXY"
-export no_proxy="$LANGBOT_NO_PROXY"
-```
-
-## Rule
-
-Keep uppercase and lowercase proxy variables consistent. Different libraries read different names.
-
-## Checks
-
-```bash
-env | rg -i '^(http|https|all|no)_?proxy='
-curl -I --max-time 8 --proxy "$LANGBOT_PROXY_SOCKS" https://github.com
-curl -I --max-time 3 "$LANGBOT_BACKEND_URL"
-```

skills/skills/langbot-env-setup/references/service-startup.md

@@ -1,73 +0,0 @@
-# Service Startup
-
-Use this reference for LangBot backend/frontend readiness checks regardless of OS or browser-control method. Read `skills/.env` first and override those defaults with user-provided values or detected running services.
-
-## Variables
-
-- `LANGBOT_REPO`
-- `LANGBOT_WEB_REPO`
-- `LANGBOT_BACKEND_URL`
-- `LANGBOT_FRONTEND_URL`
-- `LANGBOT_DEV_FRONTEND_URL`
-
-## Backend
-
-Start LangBot from the backend repo:
-
-```bash
-cd "$LANGBOT_REPO"
-uv run main.py
-```
-
-Healthy startup includes:
-
-```text
-Running on http://0.0.0.0:<backend-port>
-Connected to plugin runtime.
-Plugin langbot/local-agent initialized
-```
-
-Quick check:
-
-```bash
-curl -I --max-time 3 "$LANGBOT_BACKEND_URL/login"
-```
-
-If `bin/lbs env doctor` reports that `LANGBOT_BACKEND_URL` has no TCP listener,
-the backend is not running at the configured host and port. A reachable
-standalone frontend on `LANGBOT_FRONTEND_URL` does not prove backend readiness.
-
-Prefer a visible terminal session while debugging backend startup. Detached
-background startup methods can hide early process exits in local agent runs; if
-you use one, immediately verify both the process and the listener:
-
-```bash
-ps -eo pid,cmd | rg 'main.py|uv run main|langbot'
-ss -ltnp | rg ':5300'
-curl -I --max-time 3 "$LANGBOT_BACKEND_URL/login"
-```
-
-## Frontend
-
-Start the new frontend from the web repo:
-
-```bash
-cd "$LANGBOT_WEB_REPO"
-npm run dev
-```
-
-Healthy startup includes:
-
-```text
-Local: <frontend-url>
-```
-
-Quick check:
-
-```bash
-curl -I --max-time 3 "$LANGBOT_FRONTEND_URL"
-```
-
-## Completion Signal
-
-Environment setup is not complete until the required frontend/backend URLs are reachable and the chosen browser-control path can open the WebUI.

skills/skills/langbot-env-setup/references/wsl-notes.md

@@ -1,36 +0,0 @@
-# WSL Notes
-
-Use this reference only for WSL-specific details. Do not put generic LangBot startup or browser-login steps here.
-
-## Network
-
-GitHub login and model provider calls may require proxy access from WSL.
-
-Working proxy form:
-
-```bash
-socks5://127.0.0.1:7890
-```
-
-Bypass local LangBot:
-
-```bash
-localhost,127.0.0.1
-```
-
-Quick checks:
-
-```bash
-curl -I --max-time 8 --proxy socks5h://127.0.0.1:7890 https://github.com
-curl -I --max-time 3 "$LANGBOT_BACKEND_URL"
-```
-
-## Visible Browser
-
-If OAuth requires a visible browser, WSL must have a usable display path. If a visible Chromium launch fails, check the local WSL GUI/X11 setup before changing LangBot config.
-
-## Common Failures
-
-- `ERR_NETWORK_CHANGED` or GitHub timeout: browser is not using the SOCKS proxy.
-- LangBot connection refused: backend is not running or not reachable from WSL.
-- User cannot type credentials: browser is headless or not visible to the user.

skills/skills/langbot-mcp-ops/SKILL.md

@@ -1,99 +0,0 @@
----
-name: langbot-mcp-ops
-description: Operate a LangBot instance through its built-in MCP (Model Context Protocol) server. Use when an AI agent needs to manage LangBot — list/create/update/delete bots, pipelines, models, knowledge bases, MCP servers, and skills — over MCP instead of raw HTTP. Covers the /mcp endpoint, API-key auth (web-UI lbk_ keys and the config.yaml global key), the tool surface, and client configuration. Triggers on "langbot mcp", "manage langbot via mcp", "langbot /mcp", "langbot mcp server".
----
-
-# LangBot MCP Operations
-
-LangBot exposes an **MCP server** so AI agents can manage an instance
-programmatically. It mirrors a curated subset of the HTTP service API.
-
-## Endpoint
-
-```
-http://<langbot-host>:5300/mcp
-```
-
-Transport: **streamable HTTP** (stateless, JSON responses). Same host/port as
-the web UI and HTTP API.
-
-## Authentication
-
-Reuses the same API keys as the HTTP API. Send either header:
-
-```
-X-API-Key: <api-key>
-# or
-Authorization: Bearer <api-key>
-```
-
-Two kinds of key are accepted:
-
-1. **Web-UI key** — created in the web UI (sidebar → API Keys), prefixed `lbk_`,
-   stored in the database.
-2. **Global API key** — set in `data/config.yaml` under `api.global_api_key`.
-   Requires no login session and no DB record; does not need the `lbk_` prefix.
-   Leave empty to disable. See the `langbot-deploy` skill for config details.
-
-Requests without a valid key get `401 Unauthorized`.
-
-## Client configuration
-
-```json
-{
-  "mcpServers": {
-    "langbot": {
-      "url": "http://<langbot-host>:5300/mcp",
-      "headers": { "X-API-Key": "<api-key>" }
-    }
-  }
-}
-```
-
-## Tool surface
-
-The tools wrap the LangBot service layer. Current tools (v1):
-
-| Tool | Purpose |
-| --- | --- |
-| `get_system_info` | Version, edition, instance id |
-| `list_bots` / `get_bot` / `create_bot` / `update_bot` / `delete_bot` | Manage messaging-platform bots (secrets redacted on read) |
-| `list_pipelines` / `get_pipeline` / `create_pipeline` / `update_pipeline` / `delete_pipeline` | Manage pipelines |
-| `list_llm_models` / `get_llm_model` / `list_embedding_models` / `list_model_providers` | Inspect models & providers |
-| `list_knowledge_bases` / `get_knowledge_base` / `retrieve_knowledge_base` | RAG knowledge bases (incl. semantic search) |
-| `list_mcp_servers` | External MCP servers LangBot connects to (as a client) |
-| `list_skills` / `get_skill` | Installed skills |
-
-Mutating tools (`create_*`, `update_*`) take a JSON object matching the same
-shape as the corresponding HTTP API request body. Discover resources with the
-`list_*` / `get_*` tools before mutating; identifiers are UUIDs.
-
-## How to use
-
-1. Get an API key (web UI key, or set `api.global_api_key` in config.yaml).
-2. Point your MCP client at `http://<host>:5300/mcp` with the key header.
-3. Call `get_system_info` to confirm connectivity.
-4. Use `list_*` tools to discover, then `get_*` / `create_*` / `update_*` /
-   `delete_*` as needed.
-
-## Implementation & maintenance (for LangBot developers)
-
-- Server: `src/langbot/pkg/api/mcp/server.py` (FastMCP). Tools call the service
-  layer directly, so the MCP surface stays aligned with the API.
-- Mount: `src/langbot/pkg/api/mcp/mount.py` — an ASGI dispatcher fronting Quart,
-  authenticating `/mcp` requests, running the streamable-HTTP session manager.
-- Smoke test: `tests/manual/mcp_smoke.py`.
-
-> When you add, remove, or change an HTTP API endpoint that should be
-> agent-accessible, update the corresponding MCP tool **and** this skill. The
-> MCP tool surface and the API must stay aligned (see `AGENTS.md`).
-
-## Pitfalls
-
-- `/mcp` is the **server** LangBot exposes. The `/api/v1/mcp` routes are the
-  **client** side (managing external MCP servers LangBot connects to). Don't
-  confuse them.
-- A `401` means the key is wrong, missing, or (for the global key)
-  `api.global_api_key` is empty in config.yaml.
-- The global key is plaintext in config.yaml — only enable it on trusted/internal
-  deployments and serve over HTTPS.

skills/skills/langbot-plugin-dev/SKILL.md

@@ -1,452 +0,0 @@
----
-name: langbot-plugin-dev
-description: Develop, debug, and test LangBot plugins. Use when creating new LangBot plugins, fixing plugin bugs, setting up a LangBot test environment, or testing plugins via WebSocket. Covers plugin component architecture (EventListener, Command, Tool), the plugin SDK API (invoke_llm, get_llm_models, send_message, plugin storage), common pitfalls, and automated WebSocket-based testing. Triggers on "langbot plugin", "lbp", "GroupChatSummary", "plugin debug", "langbot test".
----
-
-# LangBot Plugin Development & Debugging
-
-## Controlling a running instance via MCP
-
-Beyond writing code, you can **drive a live LangBot instance over MCP** — no raw
-HTTP needed. Two MCP servers exist (both reuse existing API keys; see `AGENTS.md`):
-
-- **LangBot instance** — `http://<host>:5300/mcp` (auth: web-UI `lbk_` key or the
-  `api.global_api_key` from `config.yaml`). Manage bots, pipelines, models,
-  knowledge bases, and skills. See the **`langbot-mcp-ops`** skill.
-- **LangBot Space marketplace** — `https://space.langbot.app/mcp` (auth: Personal
-  Access Token). Search plugins / MCP servers / skills. See the
-  **`langbot-space-ops`** skill.
-
-> Any change to an agent-accessible HTTP API endpoint must keep the matching MCP
-> tool and these skills in sync.
-
-## Plugin Architecture
-
-A LangBot plugin consists of:
-
-```
-MyPlugin/
-├── manifest.yaml          # Plugin metadata, config schema
-├── main.py                # BasePlugin subclass (entry point, shared state)
-├── components/
-│   ├── event_listener/    # Hook pipeline events
-│   │   ├── collector.yaml
-│   │   └── collector.py
-│   ├── commands/          # !command handlers
-│   │   ├── mycommand.yaml
-│   │   └── mycommand.py
-│   └── tools/             # LLM function-call tools
-│       ├── mytool.yaml
-│       └── mytool.py
-```
-
-Each component has a `.yaml` (metadata) and `.py` (implementation).
-
-## Critical SDK Pitfalls
-
-### 1. MessageChain is a RootModel — iterate directly
-
-```python
-# ❌ WRONG — MessageChain has no .components attribute
-for component in event.message_chain.components:
-
-# ✅ CORRECT — MessageChain is a Pydantic RootModel, iterate directly
-for component in event.message_chain:
-```
-
-### 2. Message.content must be `list[ContentElement]` or `str`, not a single ContentElement
-
-```python
-from langbot_plugin.api.entities.builtin.provider import message as provider_message
-
-# ❌ WRONG — single ContentElement
-Message(role="user", content=ContentElement.from_text("hello"))
-
-# ✅ CORRECT — list of ContentElement
-Message(role="user", content=[ContentElement.from_text("hello")])
-
-# ✅ ALSO CORRECT — plain string
-Message(role="user", content="hello")
-```
-
-### 3. invoke_llm does NOT accept timeout
-
-```python
-# ❌ WRONG
-await self.invoke_llm(llm_model_uuid=uuid, messages=msgs, timeout=60)
-
-# ✅ CORRECT
-await self.invoke_llm(llm_model_uuid=uuid, messages=msgs)
-```
-
-### 4. invoke_llm response.content can be str OR list
-
-```python
-response = await self.invoke_llm(...)
-if response.content:
-    if isinstance(response.content, str):
-        return response.content
-    elif isinstance(response.content, list):
-        parts = [e.text for e in response.content if hasattr(e, "text") and e.text]
-        return "\n".join(parts)
-```
-
-### 5. get_llm_models() returns UUIDs
-
-```python
-# Returns list[str] of model UUIDs
-models = await self.get_llm_models()
-model_uuid = models[0]  # First available model UUID
-```
-
-**Known bug (v4.9.3):** The host handler may return `list[dict]` instead of `list[str]`. If you hit `TypeError: unhashable type: 'dict'` in `invoke_llm`, the fix is in `LangBot/src/langbot/pkg/plugin/handler.py` — change `'llm_models': llm_models` to `'llm_models': [m['uuid'] for m in llm_models]`.
-
-### 6. invoke_llm parameter is `llm_model_uuid`, NOT `model_uuid`
-
-```python
-# ❌ WRONG — will throw "got an unexpected keyword argument"
-await self.invoke_llm(messages=msgs, model_uuid=uuid)
-
-# ✅ CORRECT
-await self.invoke_llm(messages=msgs, llm_model_uuid=uuid)
-```
-
-### 7. prevent_default() alone does NOT block LLM response
-
-To fully prevent the default LLM pipeline from responding when your EventListener handles the message, you must call **both**:
-
-```python
-event_context.prevent_default()    # Block default behavior
-event_context.prevent_postorder()  # Block subsequent plugins/pipeline
-```
-
-Using only `prevent_default()` still allows the LLM to generate a response.
-
-### 8. get_plugin_storage / set_plugin_storage may throw KeyError: 'owner'
-
-This is a version mismatch between the SDK and host. Wrap storage calls in try/except:
-
-```python
-try:
-    data = await self.get_plugin_storage("my_key")
-except Exception:
-    data = None  # Fallback gracefully
-```
-
-### 9. Component YAML must have full structure, not just name/description
-
-```yaml
-# ❌ WRONG — will silently fail to register the component
-name: translator
-description:
-  en_US: 'Does stuff'
-
-# ✅ CORRECT — full component YAML
-apiVersion: v1
-kind: EventListener
-metadata:
-  name: translator
-  label:
-    en_US: Translator
-spec:
-execution:
-  python:
-    path: translator.py
-    attr: Translator
-```
-
-### 10. BasePlugin import path
-
-```python
-# ❌ WRONG
-from langbot_plugin.api.definition.base_plugin import BasePlugin
-
-# ✅ CORRECT
-from langbot_plugin.api.definition.plugin import BasePlugin
-```
-
-## Pipeline Events
-
-Events the EventListener can hook (from most general to most specific):
-
-| Event | When |
-|---|---|
-| `GroupMessageReceived` | **Any** group message arrives (before trigger rules) |
-| `PersonMessageReceived` | **Any** private message arrives |
-| `GroupNormalMessageReceived` | Group message passes trigger rules, going to LLM |
-| `PersonNormalMessageReceived` | Private message going to LLM |
-| `GroupCommandSent` | Group message matched as command |
-| `PersonCommandSent` | Private message matched as command |
-| `NormalMessageResponded` | LLM generated a response |
-| `PromptPreProcessing` | About to build LLM context |
-
-**Key insight:** `*MessageReceived` fires for ALL messages regardless of trigger rules. `*NormalMessageReceived` only fires for messages that match the pipeline's trigger rules (e.g., @bot, prefix, random%). Use `*MessageReceived` for message collection/logging.
-
-## EventContext API
-
-```python
-@self.handler(events.GroupMessageReceived)
-async def on_msg(event_context: context.EventContext):
-    event = event_context.event
-    event.launcher_id    # Group ID
-    event.sender_id      # Sender ID
-    event.message_chain  # MessageChain (iterate directly)
-
-    # Reply to the current conversation
-    await event_context.reply(MessageChain([Plain(text="hello")]))
-
-    # Block default pipeline behavior
-    event_context.prevent_default()
-
-    # Block subsequent plugins
-    event_context.prevent_postorder()
-```
-
-## Setting Up a Test Environment
-
-### Deploy via Docker (GitOps + Portainer)
-
-See `references/test-env-setup.md` for full deployment steps.
-
-Quick summary:
-1. Create `docker-compose.yaml` in `server-deploy` repo
-2. Deploy via Portainer git repository method
-3. Set up admin account via `/api/v1/user/init` POST
-4. Configure LLM provider and model via API
-5. Copy plugin to `data/plugins/` directory
-
-### WebSocket Testing
-
-LangBot's WebUI chat uses WebSocket. Connect to test message flow:
-
-```
-ws://<host>:<port>/api/v1/pipelines/<pipeline_uuid>/ws/connect?session_type=group
-```
-
-- `session_type=group` for group chat simulation
-- `session_type=person` for private chat (always triggers pipeline)
-
-**Requires Origin header** to pass CORS:
-```javascript
-const ws = new WebSocket(url, {
-  headers: { Origin: 'https://your-langbot-domain' }
-});
-```
-
-Send messages:
-```json
-{"type": "message", "message": [{"type": "Plain", "text": "hello"}]}
-```
-
-Receive:
-- `{"type": "connected", ...}` — connection established
-- `{"type": "user_message", "data": {...}}` — echo of sent message
-- `{"type": "response", "data": {"content": "...", "is_final": true/false}}` — bot reply (streamed)
-
-### Group Trigger Rules
-
-Group messages only enter the pipeline if trigger rules are met:
-
-```json
-{
-  "group-respond-rules": {
-    "at": true,          // Respond when @bot
-    "prefix": ["ai"],    // Respond to messages starting with "ai"
-    "random": 0.0,       // Probability of responding to any message (0.0-1.0)
-    "regexp": []         // Regex patterns
-  }
-}
-```
-
-For testing, set `random: 1.0` via PUT `/api/v1/pipelines/<uuid>` to respond to all messages.
-
-**Important:** EventListener hooks like `GroupMessageReceived` fire regardless of trigger rules. Only the LLM processing (`GroupNormalMessageReceived` and beyond) requires trigger rules.
-
-### Plugin Hot-Reload
-
-There is **no hot-reload**. After changing plugin files:
-
-```bash
-docker restart <runtime-container>
-# Wait ~5 seconds for plugin to re-mount
-```
-
-The main LangBot container does NOT need restart for plugin changes — only the runtime container.
-
-## API Quick Reference
-
-### Admin Setup
-
-```bash
-# Initialize admin account (first time only)
-curl -X POST $BASE/api/v1/user/init \
-  -H "Content-Type: application/json" \
-  -d '{"user":"admin@test.com","password":"test123"}'
-
-# Login
-curl -X POST $BASE/api/v1/user/auth \
-  -H "Content-Type: application/json" \
-  -d '{"user":"admin@test.com","password":"test123"}'
-# Returns: {"data":{"token":"eyJ..."}}
-```
-
-### Provider & Model Setup
-
-```bash
-# Create provider
-curl -X POST $BASE/api/v1/provider/providers \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"MyProvider","requester":"new-api-chat-completions","base_url":"https://api.example.com/v1","api_keys":["sk-xxx"]}'
-
-# Create LLM model
-curl -X POST $BASE/api/v1/provider/models/llm \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"gpt-4o-mini","provider_uuid":"<uuid>","abilities":["chat","tool-use"]}'
-
-# List models
-curl $BASE/api/v1/provider/models/llm -H "Authorization: Bearer $TOKEN"
-```
-
-### Pipeline Config
-
-```bash
-# Get pipeline
-curl $BASE/api/v1/pipelines -H "Authorization: Bearer $TOKEN"
-
-# Update pipeline (e.g., set model, modify trigger rules)
-curl -X PUT $BASE/api/v1/pipelines/<uuid> \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '<full pipeline JSON>'
-```
-
-## Plugin Config Types
-
-Supported `type` values in `manifest.yaml` `spec.config`:
-
-| Type | Description | Value |
-|---|---|---|
-| `string` | Text input | string |
-| `int` / `integer` | Number input | int |
-| `float` | Decimal input | float |
-| `bool` / `boolean` | Toggle | bool |
-| `select` | Dropdown (needs `options`) | string |
-| `prompt-editor` | Multi-line prompt editor | string |
-| `llm-model-selector` | LLM model picker UI | UUID string |
-| `bot-selector` | Bot picker UI | UUID string |
-
-Example — let users choose which model the plugin uses:
-
-```yaml
-spec:
-  config:
-    - name: model
-      type: llm-model-selector
-      label:
-        en_US: 'LLM Model'
-        zh_Hans: 'LLM 模型'
-      description:
-        en_US: 'Select the LLM model. Falls back to first available if not set.'
-        zh_Hans: '选择 LLM 模型。未设置时使用第一个可用模型。'
-      required: false
-```
-
-Read config in plugin code:
-
-```python
-model_uuid = self.get_config().get("model")
-```
-
-## Container Restart Timing
-
-After plugin file changes, **only the runtime container needs restart**:
-
-```bash
-docker restart langbot-test-runtime
-# Wait ~15 seconds before testing
-```
-
-**When to restart both (runtime first, then host):**
-- Added/removed Command or Tool components (host caches component lists)
-- Changed `manifest.yaml` structure
-
-```bash
-docker restart langbot-test-runtime
-sleep 8
-docker restart langbot-test
-sleep 8
-```
-
-**⚠️ Do NOT restart both simultaneously** — the host may connect before plugins are mounted, causing 502 errors or missing plugin registrations.
-
-## Debugging Checklist
-
-When a plugin doesn't work:
-
-1. **Check runtime logs**: `docker logs <runtime-container>` — look for mount/init errors
-2. **Check host logs**: `docker logs <langbot-container>` — look for pipeline processing errors
-3. **Verify plugin loaded**: `GET /api/v1/plugins` — should list your plugin
-4. **Test person mode first**: `session_type=person` always triggers pipeline, isolating trigger rule issues
-5. **Check trigger rules**: Group mode requires @bot, prefix match, or random% to enter pipeline
-6. **Verify model configured**: Pipeline's `config.ai.local-agent.model.primary` must point to a valid model UUID with working API keys
-
-## Publishing Plugins
-
-After testing, publish via `lbp publish`:
-
-```bash
-cd /path/to/MyPlugin
-lbp publish
-```
-
-This builds `.lbpkg` and uploads to Space marketplace as a draft. Then go to https://space.langbot.app/market to upload screenshots and submit for review.
-
-**Prerequisite:** Must be logged in via `lbp login --token lbpat_xxx` (PAT from Space profile page).
-
-## Reference: EventListener-Only Plugin Pattern
-
-For plugins that react to messages without commands or tools (e.g., auto-summarize URLs, collect messages, translate):
-
-```
-MyPlugin/
-├── manifest.yaml       # Only EventListener in spec.components
-├── main.py             # BasePlugin with shared logic (fetch, LLM calls)
-├── components/
-│   └── event_listener/
-│       ├── detector.yaml
-│       └── detector.py
-└── requirements.txt
-```
-
-**manifest.yaml** — only declare EventListener:
-```yaml
-spec:
-  components:
-    EventListener:
-      fromDirs:
-      - path: components/event_listener/
-```
-
-**detector.py** — hook `*MessageReceived`, extract text, process, reply:
-```python
-@self.handler(events.PersonMessageReceived)
-async def on_msg(event_context: context.EventContext):
-    event = event_context.event
-    text_parts = []
-    for component in event.message_chain:
-        if isinstance(component, platform_message.Plain):
-            text_parts.append(component.text)
-    text = "".join(text_parts).strip()
-    
-    if should_handle(text):
-        event_context.prevent_default()
-        event_context.prevent_postorder()
-        result = await self.plugin.process(text)
-        await event_context.reply(platform_message.MessageChain([
-            platform_message.Plain(text=result)
-        ]))
-```
-
-**Key:** Access shared plugin logic via `self.plugin` (the BasePlugin instance).

skills/skills/langbot-plugin-dev/references/test-env-setup.md

@@ -1,116 +0,0 @@
-# Test Environment Setup
-
-## Docker Compose (GitOps)
-
-Create in `server-deploy` repo under `servers/<hostname>/langbot-test/docker-compose.yaml`:
-
-```yaml
-version: "3"
-services:
-  langbot_plugin_runtime:
-    image: rockchin/langbot:latest
-    container_name: langbot-test-runtime
-    volumes:
-      - /opt/docker-data/langbot-test/data/plugins:/app/data/plugins
-    ports:
-      - "5411:5401"
-    restart: on-failure
-    environment:
-      - TZ=Asia/Shanghai
-    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "rt"]
-    networks:
-      - langbot_test_network
-
-  langbot:
-    image: rockchin/langbot:latest
-    container_name: langbot-test
-    volumes:
-      - /opt/docker-data/langbot-test/data:/app/data
-    ports:
-      - "5310:5300"
-    restart: on-failure
-    depends_on:
-      - langbot_plugin_runtime
-    environment:
-      - TZ=Asia/Shanghai
-    networks:
-      - langbot_test_network
-
-networks:
-  langbot_test_network:
-    driver: bridge
-```
-
-## Post-Deploy Configuration
-
-After first start, LangBot auto-generates `data/config.yaml`. You need to update `plugin.runtime_ws_url` to match the runtime container name:
-
-```bash
-# On the host, edit config
-sed -i 's|ws://localhost:5400/control/ws|ws://langbot-test-runtime:5400/control/ws|' \
-  /opt/docker-data/langbot-test/data/config.yaml
-docker restart langbot-test
-```
-
-## Installing a Plugin
-
-Copy plugin directory to `data/plugins/` on the host:
-
-```bash
-scp -r MyPlugin/ user@host:/opt/docker-data/langbot-test/data/plugins/MyPlugin/
-docker restart langbot-test-runtime  # Runtime picks up new plugins on restart
-```
-
-## Caddy Reverse Proxy (Optional)
-
-If testing externally, add to Caddyfile on the same host:
-
-```
-langbot-test.example.com {
-    reverse_proxy langbot-test:5300
-}
-```
-
-Then reload: `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`
-
-The WebSocket endpoint works through Caddy without special config.
-
-## WebSocket Test Script (Node.js)
-
-```javascript
-const WebSocket = require('ws');
-
-const PIPELINE_UUID = '<your-pipeline-uuid>';
-const BASE = 'wss://langbot-test.example.com';
-const URL = `${BASE}/api/v1/pipelines/${PIPELINE_UUID}/ws/connect?session_type=group`;
-
-const ws = new WebSocket(URL, {
-  headers: { Origin: BASE }
-});
-
-const send = (text) => {
-  ws.send(JSON.stringify({
-    type: 'message',
-    message: [{ type: 'Plain', text }]
-  }));
-  console.log('[SENT]', text);
-};
-
-ws.on('message', (data) => {
-  const msg = JSON.parse(data.toString());
-  if (msg.type === 'connected') {
-    console.log('Connected!');
-    // Send test messages
-    send('Message 1');
-    setTimeout(() => send('Message 2'), 500);
-    setTimeout(() => send('!summary'), 2000);
-  } else if (msg.type === 'response' && msg.data?.is_final) {
-    console.log('[BOT]', msg.data.content);
-  }
-});
-
-ws.on('error', (e) => console.error('Error:', e.message));
-setTimeout(() => { ws.close(); process.exit(); }, 60000);
-```
-
-Requires: `npm install ws`

skills/skills/langbot-skills-maintenance/SKILL.md

@@ -1,40 +0,0 @@
----
-name: langbot-skills-maintenance
-description: Maintain the langbot-skills repository with low duplication. Use when adding, editing, or auditing LangBot skills, references, cases, troubleshooting entries, indexes, or periodic entropy-control checks for this skills repository.
----
-
-# LangBot Skills Maintenance
-
-Use this skill before changing reusable assets in this repository.
-
-## Workflow
-
-1. Read `AGENTS.md`, `skills/.env`, and the relevant existing skill files.
-2. Classify the change:
-   - `SKILL.md` for routing and concise operating rules.
-   - `references/*.md` for canonical detailed workflows.
-   - `cases/*.yaml` for executable test-plan skeletons.
-   - `suites/*.yaml` for reusable groups of case ids.
-   - `fixtures/fixtures.json` for deterministic fixture readiness metadata.
-   - `reports/evidence/<run-id>/automation-result.json` as automation output and `reports/evidence/<run-id>/result.json` as final judgment output; neither is a catalog asset to commit.
-   - `troubleshooting/*.yaml` for one reusable failure mode.
-3. Search existing assets before adding new files:
-   - `rg "<feature|error|case id>" skills`
-   - `bin/lbs case list`
-   - `bin/lbs suite list`
-   - `bin/lbs fixture list`
-4. Put detail in one canonical place and link to it from cases or routing bullets.
-5. Run the checks in `AGENTS.md` after edits.
-
-## Entropy Rules
-
-- Prefer extending an existing reference or troubleshooting entry when the root cause is the same.
-- Keep cases short: setup, action, evidence, pass/fail checks. Do not paste long prompts or debug transcripts when a reference exists.
-- Put machine-checkable inputs in `env`, `automation_env`, or fixtures; put operator-confirmed assumptions in `preconditions` so `test plan` can surface `manual_check`.
-- Keep suites short: title, intent, tags, and ordered case ids. Do not duplicate case steps inside a suite.
-- Keep fixture manifests factual: id, title, path, kind, and related case ids. Do not encode environment-specific absolute paths.
-- Keep troubleshooting entries narrow: symptoms, patterns, likely causes, fixes, related assets.
-- Do not hardcode local ports, browser profile paths, secrets, tokens, or provider keys.
-- Use `bin/lbs index --check` to verify the committed index is current without writing it; run `bin/lbs index` when the index needs regeneration.
-
-For periodic repository audits, read `references/curation-workflow.md`.

skills/skills/langbot-skills-maintenance/references/curation-workflow.md

@@ -1,70 +0,0 @@
-# Curation Workflow
-
-Use this checklist when the repository starts accumulating repeated cases, copied steps, or overlapping troubleshooting entries.
-
-## Audit Pass
-
-1. Inspect the current surface:
-   - `bin/lbs case list`
-   - `bin/lbs case list --json --priority p0 --automation`
-   - `bin/lbs case list --ready`
-   - `bin/lbs case list --machine-ready`
-   - `bin/lbs suite list`
-   - `bin/lbs fixture list`
-   - `rg "sandbox|provider|pipeline|plugin|knowledge|mcp" skills`
-   - `rg "If .* fails|Known Pitfalls|Debug Chat|/api/v1" skills`
-2. Group nearby assets by intent, not by file path:
-   - user-facing scenario
-   - backend or provider dependency
-   - failure signature
-   - pass/fail evidence
-3. Pick one canonical owner:
-   - stable procedures belong in `references/`
-   - deterministic files and packages belong in `fixtures/` plus `fixtures/fixtures.json`
-   - repeated failure signatures belong in `troubleshooting/`
-   - runnable QA paths belong in `cases/`
-   - reusable groups of QA paths belong in `suites/`
-   - skill entry points belong in `SKILL.md`
-
-## Merge Or Split
-
-Merge when two files share the same trigger, root cause, and fix. Keep the stronger id and move missing patterns into it.
-
-Split when a file mixes unrelated failure modes or requires different fixes. Each troubleshooting id should map to one diagnosis path.
-
-Move repeated step lists out of cases and into a reference when more than one case would need the same prompt, UI path, or log interpretation.
-
-Add or update a suite when developers repeatedly run the same ordered group of cases. Do not copy case steps into suites; use `bin/lbs suite plan <suite-id>` to expand the group.
-Use `bin/lbs suite start <suite-id>` and `bin/lbs suite report <suite-id> --evidence-dir <dir>` when validating that a suite is operational end to end.
-
-Add or update `fixtures/fixtures.json` when a case depends on a deterministic file, plugin package, or local test server. The manifest should use repo-relative paths under the owning skill and should not contain machine-local absolute paths.
-
-When adding Debug Chat Playwright automation, reuse `scripts/e2e/lib/debug-chat.mjs` for navigation, prompt send, response leaf matching, and known failure classification. Keep case-specific prompts and expected sentinels in case YAML automation fields when possible.
-
-## Case Review
-
-For every changed case:
-
-1. Ensure `steps` describe what to execute, not every command in the underlying implementation.
-2. Ensure `checks` contain observable UI, log, network, or filesystem evidence.
-3. Ensure `diagnostics` are fallback investigation hints, not pass criteria.
-4. Ensure `priority`, `risk`, `ci_eligible`, and `evidence_required` match the actual repeatability and evidence burden.
-5. Put must-have env vars in `env` / `automation_env`; put one-of choices such as URL-or-name in `env_any` / `automation_env_any`.
-6. Ensure linked `skills` and `troubleshooting` ids exist.
-7. Run:
-
-   ```bash
-   bin/lbs validate
-   bin/lbs index --check
-   bin/lbs index
-   bin/lbs test plan <case-id>
-   ```
-
-## Final Gate
-
-Before handing off:
-
-- `git diff --stat` should show a focused change set.
-- `skills.index.json` should be regenerated only by `bin/lbs index`.
-- No new asset should contain local credentials, OAuth tokens, API keys, or copied localStorage values.
-- The final note should say which checks ran and which cases or troubleshooting ids changed.

skills/skills/langbot-space-ops/SKILL.md

@@ -1,79 +0,0 @@
----
-name: langbot-space-ops
-description: Browse and search the LangBot Space marketplaces (plugins, MCP servers, skills) through the Space MCP server. Use when an AI agent needs to discover LangBot extensions on space.langbot.app over MCP. Covers the /mcp endpoint, Personal Access Token (PAT) auth, the tool surface, and client configuration. Triggers on "langbot space mcp", "search langbot plugins", "langbot marketplace mcp", "space.langbot.app mcp".
----
-
-# LangBot Space MCP Operations
-
-LangBot Space (space.langbot.app) exposes an **MCP server** so user-facing AI
-agents can browse and search the marketplaces (plugins, MCP servers, skills).
-
-## Endpoint
-
-```
-https://space.langbot.app/mcp
-```
-
-Transport: **streamable HTTP** (stateless, JSON responses). For a self-hosted
-Space instance: `http://<host>:8383/mcp`.
-
-## Authentication
-
-Reuses the existing **Personal Access Token (PAT)** — the same token the `lbp`
-CLI uses. Create one in your Space account (Profile → Personal Access Tokens),
-then send it as a Bearer token:
-
-```
-Authorization: Bearer lbpat_...uests without a valid PAT get `401 Unauthorized`.
-
-## Client configuration
-
-```json
-{
-  "mcpServers": {
-    "langbot-space": {
-      "url": "https://space.langbot.app/mcp",
-      "headers": { "Authorization": "Bearer <your-pat>" }
-    }
-  }
-}
-```
-
-## Tool surface
-
-| Tool | Purpose |
-| --- | --- |
-| `list_plugins` / `search_plugins` / `get_plugin` | Plugin marketplace |
-| `list_mcp_servers` / `search_mcp_servers` / `get_mcp_server` | MCP-server marketplace |
-| `list_skills` / `search_skills` / `get_skill` | Skill marketplace |
-
-`list_*` and `search_*` are paged (`page`, `page_size`). `get_*` takes
-`author` + `name`. The tool surface mirrors the REST endpoints under
-`/api/v1/marketplace/*` and is read/browse only.
-
-## How to use
-
-1. Create a PAT in your Space account settings.
-2. Point your MCP client at `https://space.langbot.app/mcp` with the Bearer PAT.
-3. Use `search_plugins` / `search_mcp_servers` / `search_skills` to find items,
-   then `get_*` for details (e.g. to obtain author/name for installation in
-   LangBot itself).
-
-## Implementation & maintenance (for Space developers)
-
-- Server: `internal/controller/mcp/server.go` (official Go MCP SDK
-  `github.com/modelcontextprotocol/go-sdk`). Tools call the service layer
-  (`PluginService`, `MCPService`, `SkillService`) directly.
-- Mount: `internal/controller/api.go` at `/mcp` and `/mcp/*any`.
-- Auth: PAT via `AccountService.ValidatePersonalAccessToken`.
-- Docs: `docs/MCP_SERVER.md`.
-
-> When you add, remove, or change a marketplace API endpoint that should be
-> agent-accessible, update the corresponding MCP tool **and** this skill. The
-> MCP tool surface and the API must stay aligned (see `AGENTS.md`).
-
-## Pitfalls
-
-- The PAT prefix is `lbpat_` (Space), distinct from LangBot's `lbk_` API keys.
-- This server is read/browse only; it does not publish or modify marketplace
-  items. Use the web UI or REST API (with appropriate auth) for that.

skills/skills/langbot-testing/SKILL.md

@@ -1,41 +0,0 @@
----
-name: langbot-testing
-description: Test LangBot WebUI and core product flows with an automated browser and backend logs. Use when validating the configured LangBot frontend, pipeline Debug Chat, model provider setup and test buttons, bot and knowledge-base UI flows, or troubleshooting failed LangBot end-to-end tests.
----
-
-# LangBot Testing
-
-Use this skill when an agent needs to verify LangBot behavior through the WebUI instead of only reading code.
-
-## Routing
-
-- **General WebUI testing**: read `references/web-ui-testing.md`.
-- **Pipeline Debug Chat**: read `references/pipeline-debug-chat.md`.
-- **Dify AgentRunner**: read `references/dify-agent-runner.md`.
-- **Model provider setup or test button**: read `references/model-provider-testing.md`.
-- **Plugin install/runtime/tool/page smoke**: read `references/plugin-e2e-smoke.md`.
-- **Local Agent Runner**: read `references/local-agent-runner.md`.
-- **Local Agent Runner path coverage**: read `references/local-agent-runner-coverage.md`.
-- **Diff-aware AgentRunner QA after code changes**: read `references/agent-runner-qa-workflow.md`.
-- **Agent Runner release gate**: read `references/agent-runner-release-gate.md`.
-- **Sandbox-backed skill authoring**: read `references/sandbox-skill-authoring.md`.
-- **LangRAG knowledge bases**: read `references/langrag-knowledge-base.md`.
-- **MCP stdio tool testing**: read `references/mcp-stdio-testing.md`.
-- **Drive a live instance over MCP (not raw HTTP)**: use the `langbot-mcp-ops` skill — the instance exposes an MCP server at `http://<host>:5300/mcp` (reuses API keys). Useful for setting up bots/pipelines/models as test fixtures programmatically.
-- **Known failures and fixes**: read `references/troubleshooting.md`.
-- **Reusable test groups**: run `bin/lbs suite list` and `bin/lbs suite plan <suite-id>` before manually assembling a case set.
-
-## Rules
-
-- Read `../.env` first and use `LANGBOT_FRONTEND_URL` and `LANGBOT_BACKEND_URL` instead of hardcoded ports.
-- If a standalone frontend dev server is running, `LANGBOT_FRONTEND_URL` may point to `LANGBOT_DEV_FRONTEND_URL`; otherwise it may point to the backend WebUI.
-- Confirm the backend and frontend are actually running before testing.
-- Run `bin/lbs fixture check` before fixture-heavy MCP, RAG, multimodal, or plugin smoke tests.
-- For runner externalization release checks, run `bin/lbs test run agent-runner-release-preflight` before the full `agent-runner-release-gate` suite so configuration blockers are separated from product failures.
-- Read `Manual Readiness` in `bin/lbs test plan <case-id>`; `manual_check` means the declared preconditions or setup still need operator confirmation for this run.
-- Use an authenticated browser profile prepared by `langbot-env-setup`.
-- Do not expose API keys, OAuth secrets, tokens, or localStorage token values in output.
-- A WebUI test is not complete until the visible UI result is checked against backend logs or network behavior.
-- For a suite, use `bin/lbs suite start <suite-id>` to create the suite evidence root, per-case directories, and `suite-start.json`/`suite-start.md` handoff files; use `bin/lbs test result <case-id>` to write final per-case `result.json`, then run `bin/lbs suite report <suite-id> --evidence-dir <dir>`.
-- Do not mark a case `pass` until `test result --evidence` covers every value in the case's `evidence_required`.
-- For runner-specific Debug Chat cases, use the case-specific pipeline env declared by `automation_pipeline_url_env` / `automation_pipeline_name_env`; do not silently reuse a generic `LANGBOT_PIPELINE_URL`.

skills/skills/langbot-testing/cases/acp-agent-runner-debug-chat.yaml

@@ -1,79 +0,0 @@
-id: acp-agent-runner-debug-chat
-title: "ACP AgentRunner can answer through Debug Chat using real remote Claude"
-mode: agent-browser
-area: pipeline
-type: regression
-priority: p2
-risk: high
-ci_eligible: false
-tags:
-  - agent-runner
-  - acp
-  - claude
-  - external-runner
-  - pipeline
-skills:
-  - langbot-env-setup
-  - langbot-testing
-env:
-  - LANGBOT_FRONTEND_URL
-  - LANGBOT_BACKEND_URL
-env_any:
-  - LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL|LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME
-automation: scripts/e2e/pipeline-debug-chat.mjs
-automation_env:
-  - LANGBOT_FRONTEND_URL
-  - LANGBOT_BACKEND_URL
-  - LANGBOT_BROWSER_PROFILE
-  - LANGBOT_CHROMIUM_EXECUTABLE
-  - LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL
-  - LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME
-  - LANGBOT_E2E_PROMPT
-  - LANGBOT_E2E_EXPECTED_TEXT
-  - LANGBOT_E2E_EXPECTED_RUNNER_ID
-  - LANGBOT_E2E_RESPONSE_TIMEOUT_MS
-automation_pipeline_url_env: LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL
-automation_pipeline_name_env: LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME
-automation_expected_runner_id: "plugin:langbot/acp-agent-runner/default"
-automation_prompt: "Use the injected LangBot MCP server tool langbot_get_current_event once. If the MCP call succeeds, reply with exactly ACP_AGENT_RUNNER_E2E_OK."
-automation_expected_text: "ACP_AGENT_RUNNER_E2E_OK"
-automation_response_timeout_ms: "300000"
-setup_automation:
-  - "node:scripts/e2e/ensure-acp-agent-runner-pipeline.mjs --write-env"
-setup_provides_env:
-  - LANGBOT_ACP_AGENT_RUNNER_PIPELINE_URL
-  - LANGBOT_ACP_AGENT_RUNNER_PIPELINE_NAME
-preconditions:
-  - "The remote machine has a working Claude Code login and can run npx -y @agentclientprotocol/claude-agent-acp."
-  - "LangBot can non-interactively SSH to the remote machine; the runner opens the MCP reverse tunnel automatically."
-steps:
-  - "Open LANGBOT_FRONTEND_URL."
-  - "Open the ACP AgentRunner QA pipeline."
-  - "Confirm the pipeline AI runner is plugin:langbot/acp-agent-runner/default."
-  - "Open Debug Chat."
-  - "Ask the real remote Claude ACP agent to call langbot_get_current_event and return ACP_AGENT_RUNNER_E2E_OK exactly."
-checks:
-  - "UI: Debug Chat shows the user prompt."
-  - "UI: Debug Chat shows a Bot response containing ACP_AGENT_RUNNER_E2E_OK."
-  - "Logs: Backend logs include Processing request from person_websocket and Streaming completed for this run."
-  - "Logs: No acp runner request error appears for this run."
-  - "Console: No unexpected frontend errors appear during Debug Chat."
-evidence_required:
-  - ui
-  - console
-  - backend_log
-diagnostics:
-  - "Use scripts/e2e/ensure-acp-agent-runner-pipeline.mjs --write-env to create/update the pipeline."
-  - "For remote Claude on 101, verify ssh yhh@101.34.71.12 can run without password prompts; no separate ssh -R process is required."
-success_patterns:
-  - "ACP_AGENT_RUNNER_E2E_OK"
-  - "Processing request from person_websocket"
-  - "Streaming completed"
-failure_patterns:
-  - "acp.command_not_found"
-  - "acp.process_exited"
-  - "Agent runner plugin:langbot/acp-agent-runner/default execution failed"
-troubleshooting:
-  - backend-not-listening
-  - plugin-runtime-timeout
-  - proxy-env-mismatch

skills/skills/langbot-testing/cases/agent-runner-async-db-readiness.yaml

@@ -1,34 +0,0 @@
-id: agent-runner-async-db-readiness
-title: "AgentRunner async DB readiness probe"
-mode: probe
-area: release
-type: smoke
-priority: p0
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - async-db
-  - aiosqlite
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-async-db-readiness.mjs
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-async-db-readiness --dry-run` first; remove `--dry-run` after checking the planned evidence directory."
-  - "Automation checks whether a direct aiosqlite in-memory connection can create a table within the readiness timeout."
-checks:
-  - "automation-result.json status is pass or env_issue."
-  - "pass means async SQLite tests are worth running."
-  - "env_issue means async SQLite-dependent Host pytest probes should be classified as environment-limited until fixed."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "If this probe returns env_issue, run agent-runner-ledger-invariants for fast ledger coverage and skip async ledger pytest as a release blocker in this environment."
-success_patterns:
-  - "AIOSQLITE_READY"
-failure_patterns:
-  - "aiosqlite readiness timed out"
-troubleshooting:
-  - aiosqlite-connect-hangs

skills/skills/langbot-testing/cases/agent-runner-behavior-matrix.yaml

@@ -1,34 +0,0 @@
-id: agent-runner-behavior-matrix
-title: "AgentRunner deterministic behavior matrix probe"
-mode: probe
-area: release
-type: regression
-priority: p0
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - deterministic-runner
-  - protocol
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-behavior-matrix.mjs
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-behavior-matrix --dry-run` first; remove `--dry-run` after checking the planned evidence directory."
-  - "Automation reads fixtures/agent-runner/qa-runner-behaviors.json and validates each result sequence through the Host AgentResultNormalizer."
-checks:
-  - "automation-result.json status is pass."
-  - "probe-stdout.log contains QA_RUNNER_BEHAVIOR_MATRIX_OK."
-  - "The matrix covers ok, stream_ok, empty_output, malformed_result, and controlled_failure."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "fail means the deterministic behavior fixture and Host result normalization disagree."
-success_patterns:
-  - "QA_RUNNER_BEHAVIOR_MATRIX_OK"
-failure_patterns:
-  - "AssertionError"
-  - "RunnerProtocolError"
-  - "behavior matrix exited"

skills/skills/langbot-testing/cases/agent-runner-fixture-contract.yaml

@@ -1,35 +0,0 @@
-id: agent-runner-fixture-contract
-title: "QA AgentRunner fixture contract probe"
-mode: probe
-area: release
-type: regression
-priority: p0
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - fixture
-  - deterministic-runner
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-fixture-contract.mjs
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-fixture-contract --dry-run` first; remove `--dry-run` after checking the planned evidence directory."
-  - "Automation imports the QA AgentRunner fixture source and executes normal, streaming, and controlled-failure paths with SDK entities."
-checks:
-  - "automation-result.json status is pass."
-  - "probe-stdout.log contains QA_AGENT_RUNNER_FIXTURE_CONTRACT_OK."
-  - "Normal input returns QA_AGENT_RUNNER_OK:<input>."
-  - "Streaming input emits message.delta chunks and completes."
-  - "Failure input returns QA_AGENT_RUNNER_CONTROLLED_FAILURE."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "This validates the deterministic fixture source contract. It does not prove the plugin package is installed in a live LangBot instance."
-success_patterns:
-  - "QA_AGENT_RUNNER_FIXTURE_CONTRACT_OK"
-failure_patterns:
-  - "AssertionError"
-  - "fixture contract exited"

skills/skills/langbot-testing/cases/agent-runner-ledger-concurrency.yaml

@@ -1,41 +0,0 @@
-id: agent-runner-ledger-concurrency
-title: "AgentRunner run ledger concurrency and auth pytest probe"
-mode: probe
-area: release
-type: regression
-priority: p0
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - pytest
-  - run-ledger
-  - concurrency
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-ledger-concurrency.mjs
-preconditions:
-  - "This Host pytest probe can be slow in the current multi-repo dev environment; keep it in the release gate, but do not treat a timeout as a browser E2E failure without checking pytest logs."
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-ledger-concurrency --dry-run` first; remove `--dry-run` only after `agent-runner-async-db-readiness` is pass."
-  - "Automation resolves LANGBOT_REPO, defaulting to ../LangBot when the env var is unset."
-  - "Automation runs selected high-value tests from test_run_ledger_store.py and test_run_ledger_api_auth.py."
-checks:
-  - "automation-result.json status is pass."
-  - "pytest exit status is 0 for selected run ledger claim, lease, status, token, ownership, and active-claim tests."
-  - "pytest-stdout.log and pytest-stderr.log are written under LBS_EVIDENCE_DIR."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "env_issue means LANGBOT_REPO/default ../LangBot did not resolve, rtk/uv was unavailable, or the expected test files are missing."
-  - "fail means one of the selected LangBot run ledger pytest targets failed or timed out."
-success_patterns:
-  - "pytest passed"
-failure_patterns:
-  - "pytest exited with status"
-  - "pytest timed out"
-  - "Failed to start pytest command"
-troubleshooting:
-  - aiosqlite-connect-hangs

skills/skills/langbot-testing/cases/agent-runner-ledger-contention.yaml

@@ -1,34 +0,0 @@
-id: agent-runner-ledger-contention
-title: "AgentRunner ledger SQLite contention probe"
-mode: probe
-area: release
-type: regression
-priority: p1
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - stress
-  - ledger
-  - concurrency
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-ledger-contention.mjs
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-ledger-contention --dry-run` first; remove `--dry-run` after checking the planned evidence directory."
-  - "Automation creates 120 queued runs in a file-backed SQLite database and uses eight worker threads to claim runs under write contention."
-checks:
-  - "automation-result.json status is pass."
-  - "probe-stdout.log contains LEDGER_CONTENTION_OK."
-  - "Every run is claimed once, reaches completed status, and has dispatch_attempts = 1."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "This probe catches obvious exactly-once claim regressions under local SQLite contention; it does not replace async Host pytest or PostgreSQL concurrency checks."
-success_patterns:
-  - "LEDGER_CONTENTION_OK"
-failure_patterns:
-  - "AssertionError"
-  - "ledger contention exited"

skills/skills/langbot-testing/cases/agent-runner-ledger-invariants.yaml

@@ -1,35 +0,0 @@
-id: agent-runner-ledger-invariants
-title: "AgentRunner ledger schema and status invariants probe"
-mode: probe
-area: release
-type: regression
-priority: p0
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - ledger
-  - invariant
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-ledger-invariants.mjs
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-ledger-invariants --dry-run` first; remove `--dry-run` after checking the planned evidence directory."
-  - "Automation resolves LANGBOT_REPO, defaulting to ../LangBot, and imports the sibling SDK from LANGBOT_PLUGIN_SDK_REPO or ../langbot-plugin-sdk/src."
-  - "Automation checks run status sets, terminal status validation, ledger table/index DDL, and a minimal synchronous insert/read path."
-checks:
-  - "automation-result.json status is pass."
-  - "probe-stdout.log contains LEDGER_INVARIANTS_OK."
-  - "The probe does not require aiosqlite or browser UI."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "env_issue means LANGBOT_REPO/default ../LangBot did not resolve or Python dependencies are unavailable."
-  - "fail means a ledger schema/status invariant changed and the release gate needs review."
-success_patterns:
-  - "LEDGER_INVARIANTS_OK"
-failure_patterns:
-  - "AssertionError"
-  - "ledger invariant probe exited"

skills/skills/langbot-testing/cases/agent-runner-ledger-stress.yaml

@@ -1,33 +0,0 @@
-id: agent-runner-ledger-stress
-title: "AgentRunner ledger lightweight stress probe"
-mode: probe
-area: release
-type: regression
-priority: p1
-risk: high
-ci_eligible: true
-tags:
-  - agent-runner
-  - probe
-  - stress
-  - ledger
-skills:
-  - langbot-testing
-env:
-automation: skills/langbot-testing/probes/agent-runner-ledger-stress.mjs
-steps:
-  - "Run `rtk bin/lbs test run agent-runner-ledger-stress --dry-run` first; remove `--dry-run` after checking the planned evidence directory."
-  - "Automation creates 100 queued runs in synchronous SQLite and simulates five runtimes claiming them in priority order."
-checks:
-  - "automation-result.json status is pass."
-  - "probe-stdout.log contains LEDGER_STRESS_OK."
-  - "Every run is claimed once and reaches a terminal completed status."
-evidence_required:
-  - filesystem
-diagnostics:
-  - "This probe is a fast deterministic stress baseline; it does not replace PostgreSQL/async concurrency tests."
-success_patterns:
-  - "LEDGER_STRESS_OK"
-failure_patterns:
-  - "AssertionError"
-  - "ledger stress exited"