feat(agent-runner): add plugin runner host integration

* feat(api): support global API key from config.yaml (api.global_api_key)

Accept a config-defined global API key anywhere a web-UI key is accepted
(X-API-Key / Bearer), with no login session and no DB record. Useful for
automated deployments and AI agents (HTTP API + MCP). Defaults to empty
(disabled); does not require the lbk_ prefix.

- templates/config.yaml: add api.global_api_key with security notes
- service/apikey.py: verify_api_key checks global key first (constant-time)
- docs/API_KEY_AUTH.md: document the global key + security guidance
- tests: cover global-key match, prefix-free, fallback-to-db, disabled

* feat(mcp): expose LangBot management as an MCP server at /mcp

Add an MCP (Model Context Protocol) server so external AI agents can manage a
LangBot instance. Reuses the same API-key auth as the HTTP API (including the
config.yaml global API key).

- pkg/api/mcp/server.py: FastMCP server wrapping the service layer; 21 curated
  tools across system/bots/pipelines/models/knowledge/mcp-servers/skills
- pkg/api/mcp/mount.py: ASGI dispatcher fronting Quart; authenticates /mcp
  requests with an API key, runs the streamable-HTTP session manager lifespan
- controller/main.py: serve the wrapped ASGI app via hypercorn (was run_task)
- web: new 'MCP' tab in the API integration dialog showing endpoint, auth, and
  client config; i18n for 8 locales
- tests/manual/mcp_smoke.py: e2e check (401 unauth, list tools, call tools)

Tool surface is intentionally curated (not all ~25 route groups) to keep the
agent surface small, safe, and maintainable. Extend deliberately.

* feat(skills): add in-repo skills/ as the single source of truth

Migrate the agent skills + QA/e2e test harness from the (now archived)
langbot-app/langbot-skills repo into LangBot/skills/, and add four new skills.

Migrated:
- langbot-plugin-dev, langbot-testing (e2e), langbot-env-setup,
  langbot-skills-maintenance, langbot-eba-adapter-dev
- the bin/lbs CLI (src/, test/, scripts/, schemas/, qa-agent-docs/)

New:
- langbot-dev      core backend + web development
- langbot-deploy   Docker/K8s deployment + config.yaml + global API key
- langbot-mcp-ops  operating the LangBot MCP server (/mcp)
- langbot-space-ops operating the Space marketplace MCP server

- src/cli.ts repoRoot(): recognize the skills assets root (skills.index.json +
  bin/lbs) so the CLI works when nested inside the LangBot repo
- README.md: unified skill catalog; skills.index.json regenerated

Parity with source verified: bin/lbs validate + node test suite match the
source repo (only the uncommitted .lbpkg build-artifact fixture differs).

* docs(agents): document agent-facing surfaces + API/MCP/skills sync rule

* docs(readme): add 'Built for AI Agents' section across all locales

Highlight MCP server, in-repo skills (single source of truth), AGENTS.md
sync rule, and llms.txt. Cross-link LangBot Space MCP marketplace.

* style(mcp): fix ruff format + prettier lint in MCP server and API panel

* style(web): prettier format MCP i18n locale entries

* docs(skills): note MCP instance control in dev/testing skills

All development-guidance skills now point to the LangBot instance MCP
server (/mcp) and the Space marketplace MCP server, reusing API keys.

.dockerignore

@@ -0,0 +1,8 @@
+.github
+.venv
+.vscode
+.data
+.temp
+web/.next
+web/node_modules
+web/.env

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,5 +1,5 @@
 name: 漏洞反馈
-description: 【供中文用户】报错或漏洞请使用这个模板创建，不使用此模板创建的异常、漏洞相关issue将被直接关闭。由于自己操作不当/不甚了解所用技术栈引起的网络连接问题恕无法解决，请勿提 issue。容器间网络连接问题，参考文档 https://docs.langbot.app/zh/workshop/network-details.html  
+description: 【供中文用户】报错或漏洞请使用这个模板创建，不使用此模板创建的异常、漏洞相关issue将被直接关闭。由于自己操作不当/不甚了解所用技术栈引起的网络连接问题恕无法解决，请勿提 issue。容器间网络连接问题，参考文档 https://link.langbot.app/zh/docs/network  
 title: "[Bug]: "
 labels: ["bug?"]
 body:
@@ -10,6 +10,15 @@ body:
       placeholder: 例如：v3.3.0、CentOS x64 Python 3.10.3、Docker
     validations:
       required: true
+  - type: dropdown
+    attributes:
+      label: 部署版本
+      description: 请选择您使用的 LangBot 部署版本。
+      options:
+        - 社区版
+        - 云服务
+    validations:
+      required: true
   - type: textarea
     attributes:
       label: 异常情况
@@ -19,7 +28,7 @@ body:
   - type: textarea
     attributes:
       label: 复现步骤
-      description: 提供越多信息，我们会越快解决问题，建议多提供配置截图；**如果你不认真填写（只一两句话概括），我们会很生气并且立即关闭 issue 或两年后才回复你**
+      description: 提供越多信息，我们会越快解决问题，建议多提供配置截图；**如果涉及 Dify、n8n、Langflow 等外部平台，请提供应用的导出文件（如 Dify 应用的 DSL），我们将更快回复您。**
     validations:
       required: false
   - type: textarea

.github/ISSUE_TEMPLATE/bug-report_en.yml

@@ -1,5 +1,5 @@
 name: Bug report
-description: Report bugs or vulnerabilities using this template. For container network connection issues, refer to the documentation https://docs.langbot.app/en/workshop/network-details.html
+description: Report bugs or vulnerabilities using this template. For container network connection issues, refer to the documentation https://link.langbot.app/en/docs/network
 title: "[Bug]: "
 labels: ["bug?"]
 body:
@@ -10,6 +10,15 @@ body:
       placeholder: "For example: v3.3.0, CentOS x64 Python 3.10.3, Docker"
     validations:
       required: true
+  - type: dropdown
+    attributes:
+      label: Deployment version
+      description: Please select the LangBot deployment version you are using.
+      options:
+        - Community Edition
+        - Cloud Service
+    validations:
+      required: true
   - type: textarea
     attributes:
       label: Exception
@@ -19,7 +28,7 @@ body:
   - type: textarea
     attributes:
       label: Reproduction steps
-      description: How to reproduce this problem, the more detailed the better; the more information you provide, the faster we will solve the problem. 【注意】请务必认真填写此部分，若不提供完整信息（如只有一两句话的概括），我们将不会回复！
+      description: How to reproduce this problem, the more detailed the better; the more information you provide, the faster we will solve the problem.
     validations:
       required: false
   - type: textarea

.github/pull_request_template.md

@@ -21,6 +21,7 @@
 *请在方括号间写`x`以打勾 / Please tick the box with `x`*
 
 - [ ] 阅读仓库[贡献指引](https://github.com/langbot-app/LangBot/blob/master/CONTRIBUTING.md)了吗？ / Have you read the [contribution guide](https://github.com/langbot-app/LangBot/blob/master/CONTRIBUTING.md)?
+- [ ] 我已签署或将在机器人提示后签署 [CLA](https://github.com/langbot-app/LangBot/blob/master/CLA.md)。 / I have signed, or will sign when prompted by the bot, the [CLA](https://github.com/langbot-app/LangBot/blob/master/CLA.md).
 - [ ] 与项目所有者沟通过了吗？ / Have you communicated with the project maintainer?
 - [ ] 我确定已自行测试所作的更改，确保功能符合预期。 / I have tested the changes and ensured they work as expected.
 

.github/workflows/build-docker-image.yml

@@ -3,7 +3,6 @@ on:
   ## 发布release的时候会自动构建
   release:
     types: [published]
-  workflow_dispatch:
 jobs:
   publish-docker-image:
     runs-on: ubuntu-latest
@@ -42,7 +41,7 @@ jobs:
         run: docker buildx create --name mybuilder --use
       - name: Build for Release # only relase, exlude pre-release
         if: ${{ github.event.release.prerelease == false }}
-        run: docker buildx build --platform linux/amd64 -t rockchin/langbot:${{ steps.check_version.outputs.version }} -t rockchin/langbot:latest . --push
+        run: docker buildx build --platform linux/arm64,linux/amd64 -t rockchin/langbot:${{ steps.check_version.outputs.version }} -t rockchin/langbot:latest . --push
       - name: Build for Pre-release # no update for latest tag
         if: ${{ github.event.release.prerelease == true }}
-        run: docker buildx build --platform linux/amd64 -t rockchin/langbot:${{ steps.check_version.outputs.version }} . --push
+        run: docker buildx build --platform linux/arm64,linux/amd64 -t rockchin/langbot:${{ steps.check_version.outputs.version }} . --push

.github/workflows/build-release-artifacts.yaml

@@ -43,10 +43,10 @@ jobs:
         run: |
           cd /tmp/langbot_build_web/web
           npm install
-          npm run build
+          npx vite build
       - name: Package Output
         run: |
-          cp -r /tmp/langbot_build_web/web/out ./web
+          cp -r /tmp/langbot_build_web/web/dist ./web
       - name: Upload Artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/check-i18n.yml

@@ -0,0 +1,25 @@
+name: Check i18n Keys
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  check-i18n:
+    name: Check i18n Key Consistency
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Check i18n keys against en-US reference
+        run: node web/scripts/check-i18n.mjs

.github/workflows/cla.yml

@@ -0,0 +1,41 @@
+name: "CLA Assistant"
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize, reopened]
+
+permissions:
+  actions: write          # re-run the failed CLA check after signing
+  contents: read          # signatures are stored in the remote langbot-app/cla repo
+  pull-requests: write    # post guidance comments, lock PR after merge
+  statuses: write         # set the commit status
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "CLA Assistant"
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        # Upstream repo was archived in 2026-03; pin to the v2.6.1 commit SHA.
+        uses: contributor-assistant/github-action@ca4a40a7d1004f18d9960b404b97e5f30a505a08 # v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # repo-scope PAT with write access to langbot-app/cla
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_PAT }}
+        with:
+          path-to-document: 'https://github.com/langbot-app/LangBot/blob/master/CLA.md'
+          remote-organization-name: 'langbot-app'
+          remote-repository-name: 'cla'
+          path-to-signatures: 'signatures/version1/cla.json'
+          branch: 'main'
+          allowlist: 'dependabot[bot],github-actions[bot],devin-ai-integration[bot],Copilot,renovate[bot],bot*'
+          custom-notsigned-prcomment: |
+            Thank you for your contribution! :heart: Before we can merge this pull request, we need you to sign the [LangBot Contributor License Agreement (CLA)](https://github.com/langbot-app/LangBot/blob/master/CLA.md). You keep full copyright of your code — the CLA grants us a license to use and distribute your contribution. Signing takes 10 seconds and covers all repositories in this organization, permanently.
+
+            感谢您的贡献！合并前请阅读并签署[贡献者许可协议（CLA）](https://github.com/langbot-app/LangBot/blob/master/CLA.md)。您保留代码的全部版权，签署仅需回复下方指定内容，一次签署对本组织全部仓库永久有效。
+          custom-allsigned-prcomment: 'All contributors have signed the CLA. :white_check_mark: 所有贡献者均已签署 CLA。'
+          lock-pullrequest-aftermerge: true
+        # SECURITY: this workflow runs on pull_request_target (it holds secrets and has
+        # write access to the base repository). NEVER add an actions/checkout step that
+        # checks out the PR's code here.

.github/workflows/frontend-tests.yml

@@ -0,0 +1,46 @@
+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

@@ -0,0 +1,60 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - dev
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  ruff:
+    name: Ruff Lint & Format
+    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 ruff check
+        run: uv run ruff check src/langbot/ tests/ --output-format=concise
+
+      - name: Run ruff format
+        run: uv run ruff format src --check
+
+  frontend:
+    name: Frontend Lint
+    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: 9
+
+      - name: Install dependencies
+        working-directory: web
+        run: pnpm install
+
+      - name: Run lint
+        working-directory: web
+        run: pnpm lint

.github/workflows/publish-to-pypi.yml

@@ -29,8 +29,8 @@ jobs:
           npm install -g pnpm
           pnpm install
           pnpm build
-          mkdir -p ../src/langbot/web/out
-          cp -r out ../src/langbot/web/
+          mkdir -p ../src/langbot/web/dist
+          cp -r dist ../src/langbot/web/
 
       - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v6

.github/workflows/run-tests.yml

@@ -4,29 +4,29 @@ on:
   pull_request:
     types: [opened, ready_for_review, synchronize]
     paths:
-      - 'pkg/**'
+      - 'src/langbot/**'
       - 'tests/**'
       - '.github/workflows/run-tests.yml'
       - 'pyproject.toml'
+      - 'uv.lock'
       - 'run_tests.sh'
+      - 'scripts/test-*.sh'
   push:
     branches:
       - master
       - develop
-    paths:
-      - 'pkg/**'
-      - 'tests/**'
-      - '.github/workflows/run-tests.yml'
-      - 'pyproject.toml'
-      - 'run_tests.sh'
+      - 'feat/**'
+    # No path filter on push: every push to the branches above runs the
+    # full unit-test suite. feat/** branches in particular must be tested
+    # on every push (they accumulate large changes before a PR exists).
 
 jobs:
   test:
-    name: Run Unit Tests
+    name: Unit Tests
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.11', '3.12', '3.13']
       fail-fast: false
 
     steps:
@@ -39,28 +39,13 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install uv
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+        uses: astral-sh/setup-uv@v4
 
       - name: Install dependencies
-        run: |
-          uv sync --dev
+        run: uv sync --dev
 
-      - name: Run unit tests
-        run: |
-          bash run_tests.sh
-
-      - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.12'
-        uses: codecov/codecov-action@v5
-        with:
-          files: ./coverage.xml
-          flags: unit-tests
-          name: unit-tests-coverage
-          fail_ci_if_error: false
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      - name: Run unit + smoke tests
+        run: uv run pytest tests/unit_tests/ tests/smoke/ -q --tb=short
 
       - name: Test Summary
         if: always()
@@ -69,3 +54,140 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "Python Version: ${{ matrix.python-version }}" >> $GITHUB_STEP_SUMMARY
           echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
+
+  integration:
+    name: Fast Integration Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run fast integration tests
+        run: uv run pytest tests/integration/ -m "not slow" -q --tb=short
+
+      - name: Integration Test Summary
+        if: always()
+        run: |
+          echo "## Integration Tests Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Test Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY
+
+  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
+    needs: [test, integration]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run coverage (unit + smoke)
+        run: |
+          uv run pytest tests/unit_tests/ tests/smoke/ \
+            --cov=langbot \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=18 \
+            -q --tb=short
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          flags: unit-tests
+          name: coverage-report
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Coverage Summary
+        if: always()
+        run: |
+          echo "## Coverage Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Threshold: 18%" >> $GITHUB_STEP_SUMMARY
+          echo "Status: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY

.github/workflows/test-migrations.yml

@@ -0,0 +1,78 @@
+name: Test Migrations
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - dev
+    paths:
+      - 'src/langbot/pkg/persistence/**'
+      - 'src/langbot/pkg/entity/persistence/**'
+      - 'tests/integration/persistence/**'
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'src/langbot/pkg/persistence/**'
+      - 'src/langbot/pkg/entity/persistence/**'
+      - 'tests/integration/persistence/**'
+
+jobs:
+  test-migrations-sqlite:
+    name: Migrations (SQLite)
+    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 SQLite migration tests
+        run: uv run pytest tests/integration/persistence/test_migrations.py -q --tb=short
+
+  test-migrations-postgres:
+    name: Migrations (PostgreSQL)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: langbot
+          POSTGRES_PASSWORD: langbot
+          POSTGRES_DB: langbot_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U langbot"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=5
+
+    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 PostgreSQL migration tests
+        env:
+          TEST_POSTGRES_URL: postgresql+asyncpg://langbot:langbot@localhost:5432/langbot_test
+        run: uv run pytest tests/integration/persistence/test_migrations_postgres.py -q --tb=short

.gitignore

@@ -42,14 +42,17 @@ botpy.log*
 test.py
 /web_ui
 .venv/
-uv.lock
 /test
 plugins.bak
 coverage.xml
 .coverage
 src/langbot/web/
+testsdk/
 
 # Build artifacts
 /dist
 /build
 *.egg-info
+
+# Next.js build cache (legacy)
+web/.next/

.pre-commit-config.yaml

@@ -9,16 +9,14 @@ repos:
       # Run the formatter of backend.
       - id: ruff-format
 
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.1.0
-    hooks:
-      - id: prettier
-        types_or: [javascript, jsx, ts, tsx, css, scss]
-        additional_dependencies:
-          - prettier@3.1.0
-
   - repo: local
     hooks:
+      - id: prettier
+        name: prettier
+        entry: npx --prefix web prettier --write --ignore-unknown
+        language: system
+        types_or: [javascript, jsx, ts, tsx, css, scss]
+
       - id: lint-staged
         name: lint-staged
         entry: cd web && pnpm lint-staged

AGENTS.md

@@ -1,79 +1,163 @@
 # AGENTS.md
 
-This file is for guiding code agents (like Claude Code, GitHub Copilot, OpenAI Codex, etc.) to work in LangBot project.
+This file guides code agents (Claude Code, GitHub Copilot, OpenAI Codex, etc.) working in the LangBot project. `CLAUDE.md` is a symlink to this file.
 
 ## Project Overview
 
-LangBot is a open-source LLM native instant messaging bot development platform, aiming to provide an out-of-the-box IM robot development experience, with Agent, RAG, MCP and other LLM application functions, supporting global instant messaging platforms, and providing rich API interfaces, supporting custom development.
+LangBot is an open-source, LLM-native instant-messaging bot development platform. It aims to provide an out-of-the-box IM bot development experience with Agent, RAG, MCP and other LLM application capabilities, supporting mainstream global IM platforms and exposing rich APIs for custom development.
 
-LangBot has a comprehensive frontend, all operations can be performed through the frontend. The project splited into these major parts:
+LangBot has a comprehensive web frontend — almost every operation can be performed through it.
 
-- `./pkg`: The core python package of the project backend.
-    - `./pkg/platform`: The platform module of the project, containing the logic of message platform adapters, bot managers, message session managers, etc.
-    - `./pkg/provider`: The provider module of the project, containing the logic of LLM providers, tool providers, etc.
-    - `./pkg/pipeline`: The pipeline module of the project, containing the logic of pipelines, stages, query pool, etc.
-    - `./pkg/api`: The api module of the project, containing the http api controllers and services.
-    - `./pkg/plugin`: LangBot bridge for connecting with plugin system.
-- `./libs`: Some SDKs we previously developed for the project, such as `qq_official_api`, `wecom_api`, etc.
-- `./templates`: Templates of config files, components, etc.
-- `./web`: Frontend codebase, built with Next.js + **shadcn** + **Tailwind CSS**.
-- `./docker`: docker-compose deployment files.
+- **Python**: `>=3.11,<4.0`, dependencies managed by `uv`. Package version is in `pyproject.toml`.
+- **Frontend**: `web/` is a **Vite + React Router 7 + shadcn/ui + Tailwind CSS** SPA, managed by `pnpm`. (Note: this is NOT Next.js — the `dev` script is `vite`.)
+- **Backend framework**: Quart (the async flavour of Flask). The HTTP API and the pre-built web UI are both served by the backend on `http://127.0.0.1:5300`.
 
-## Backend Development
+## Repository Layout
 
-We use `uv` to manage dependencies.
+```
+LangBot/
+├── main.py                     # Entrypoint shim -> langbot.__main__.main()
+├── pyproject.toml              # Python project + deps (uv), pins langbot-plugin==<x.y.z>
+├── src/langbot/
+│   ├── __main__.py             # Real entrypoint, CLI args (--standalone-runtime, --standalone-box, --debug)
+│   ├── pkg/                    # Core backend package
+│   │   ├── api/                # HTTP API controllers + services (Quart)
+│   │   ├── core/               # App bootstrap, stages, task manager
+│   │   ├── platform/           # IM platform adapters, bot managers, session managers
+│   │   ├── provider/           # LLM providers, requesters, tool providers
+│   │   ├── pipeline/           # Pipelines, stages, query pool
+│   │   ├── plugin/             # Bridge connecting LangBot to the plugin runtime (see below)
+│   │   ├── box/                # Code-sandbox subsystem (Docker / nsjail / E2B backends)
+│   │   ├── skill/              # Skill subsystem
+│   │   ├── rag/ , vector/      # RAG + vector store
+│   │   ├── command/            # Built-in commands
+│   │   ├── persistence/        # ORM models + Alembic migrations (SQLite & PostgreSQL)
+│   │   ├── storage/            # Object/file storage abstractions
+│   │   ├── config/, entity/, discover/, utils/, telemetry/, survey/
+│   ├── libs/                   # Vendored SDKs (qq_official_api, wecom_api, etc.)
+│   └── templates/              # Config/component templates (e.g. templates/config.yaml)
+├── web/                        # Frontend SPA (Vite + React Router 7 + shadcn + Tailwind)
+└── docker/                     # docker-compose deployment files
+```
+
+## Development Environment Setup
+
+Full guide lives in the wiki: **["开发配置" / Dev Config](https://docs.langbot.app/zh/develop/dev-config)**. Summary:
+
+### Backend
 
 ```bash
 pip install uv
-uv sync --dev
+uv sync --dev          # uv creates a .venv/ for you; point your editor's interpreter at it
+uv run main.py         # serves API + web UI on http://127.0.0.1:5300
 ```
 
-Start the backend and run the project in development mode.
+On first run the config file is generated at `data/config.yaml`. DB is SQLite by default (zero setup); PostgreSQL is supported. Migrations run automatically on startup.
 
-```bash
-uv run main.py
-```
+### Frontend
 
-Then you can access the project at `http://127.0.0.1:5300`.
-
-## Frontend Development
-
-We use `pnpm` to manage dependencies.
+Requires Node.js + [pnpm](https://pnpm.io/installation).
 
 ```bash
 cd web
-cp .env.example .env
+cp .env.example .env   # Windows: copy .env.example .env
 pnpm install
-pnpm dev
+pnpm dev               # http://127.0.0.1:3000  (npm install / npm run dev also work)
 ```
 
-Then you can access the project at `http://127.0.0.1:3000`.
+`pnpm dev` reads `VITE_API_BASE_URL` from `web/.env` so the dev frontend can reach the backend on port `5300`. In production the frontend is pre-built into static files served by the backend on the same origin.
 
-## Plugin System Architecture
+### Code formatting
 
-LangBot is composed of various internal components such as Large Language Model tools, commands, messaging platform adapters, LLM requesters, and more. To meet extensibility and flexibility requirements, we have implemented a production-grade plugin system.
+The repo runs lint + format checks in CI. Install the pre-commit hooks so the same checks run locally before each commit:
 
-Each plugin runs in an independent process, managed uniformly by the Plugin Runtime. It has two operating modes: `stdio` and `websocket`. When LangBot is started directly by users (not running in a container), it uses `stdio` mode, which is common for personal users or lightweight environments. When LangBot runs in a container, it uses `websocket` mode, designed specifically for production environments.
+```bash
+uv run pre-commit install
+```
 
-Plugin Runtime automatically starts each installed plugin and interacts through stdio. In plugin development scenarios, developers can use the lbp command-line tool to start plugins and connect to the running Runtime via WebSocket for debugging.
+## Plugin System
 
-> Plugin SDK, CLI, Runtime, and entities definitions shared between LangBot and plugins are contained in the [`langbot-plugin-sdk`](https://github.com/langbot-app/langbot-plugin-sdk) repository.
+LangBot's plugin system (Plugin SDK, CLI `lbp`, Plugin Runtime, and the shared entity/API definitions) lives in a **separate repository**: [`langbot-plugin-sdk`](https://github.com/langbot-app/langbot-plugin-sdk). LangBot depends on it via the pinned `langbot-plugin` package in `pyproject.toml`.
 
-## Some Development Tips and Standards
+### Architecture (what to know inside this repo)
 
-- LangBot is a global project, any comments in code should be in English, and user experience should be considered in all aspects.
-- Thus you should consider the i18n support in all aspects.
-- LangBot is widely adopted in both toC and toB scenarios, so you should consider the compatibility and security in all aspects.
-- If you were asked to make a commit, please follow the commit message format: 
-    - format: <type>(<scope>): <subject>
-    - type: must be a specific type, such as feat (new feature), fix (bug fix), docs (documentation), style (code style), refactor (refactoring), perf (performance optimization), etc.
-    - scope: the scope of the commit, such as the package name, the file name, the function name, the class name, the module name, etc.
-    - subject: the subject of the commit, such as the description of the commit, the reason for the commit, the impact of the commit, etc.
+- Plugins run as independent processes managed by the **Plugin Runtime**. The Runtime supports two control transports: `stdio` and `websocket`.
+- When LangBot is started directly by a user (not in a container), it spawns and connects to the Runtime over **stdio** (lightweight/personal use).
+- When LangBot runs in a container, it connects to a standalone Runtime over **WebSocket** (production).
+- The bridge code lives in `src/langbot/pkg/plugin/` (`connector.py`, `handler.py`).
+- Relevant config (`data/config.yaml`): `plugin.runtime_ws_url` (e.g. `ws://langbot_plugin_runtime:5400/control/ws`). Start LangBot with `--standalone-runtime` to make it connect to an externally-launched Runtime over WebSocket instead of spawning one over stdio.
+
+### Debugging the Plugin Runtime / CLI / SDK
+
+This is documented in detail in the **SDK repo's `AGENTS.md`** and in the wiki page **["调试插件运行时、CLI、SDK" / Plugin Runtime](https://docs.langbot.app/zh/develop/plugin-runtime)**. The short version:
+
+- Clone `LangBot` and `langbot-plugin-sdk` as siblings under one parent dir so the editor resolves shared entities.
+- Start a standalone Runtime from the SDK repo: `uv run --no-sync lbp rt` (control port `5400`, debug port `5401`).
+- To make LangBot use a locally-modified SDK: from the SDK dir, with LangBot's `.venv` active, run `uv pip install .`, then launch LangBot with `uv run --no-sync main.py --standalone-runtime` (keep `--no-sync` so your local SDK isn't overwritten).
+
+### Debugging the Box (sandbox) runtime
+
+The Box subsystem (`src/langbot/pkg/box/`) is the code sandbox. It picks the first available backend among **Docker / nsjail / E2B**. The standalone Box runtime is launched via the SDK CLI: `lbp box`. Backend selection details, the `lbp box` flags, and the SDK-side architecture are documented in the SDK repo's `AGENTS.md`.
+
+Relevant config (`data/config.yaml`, `box:` section): `box.enabled` (master switch — disabling it also disables the native sandbox tools, skill add/edit, and stdio-mode MCP servers), `box.backend` (`'local'` = Docker/nsjail auto-pick, or `'docker'` / `'nsjail'` / `'e2b'`; also settable via `BOX__BACKEND`), and `box.runtime.endpoint` (external Box runtime base URL, e.g. `ws://127.0.0.1:5410`; empty = local auto-managed runtime). Like the plugin runtime, LangBot can connect to an externally-launched Box runtime by setting that endpoint and starting with `--standalone-box`.
+
+> A common false "No supported sandbox backend (Docker / nsjail / E2B) is available" comes from Docker being installed and running but the current user not being in the `docker` group → `docker info` gets `permission denied` on the socket. Fix: `sudo usermod -aG docker <user>` and restart the backend in a shell that has the new group.
+
+## Development Standards
+
+- LangBot is a global project: **all code comments and docstrings must be in English**, and every user-facing string must support **i18n** (`en_US` + `zh_Hans` at minimum, plus `ja_JP` where the repo already has it).
+- LangBot is adopted in both toC and toB scenarios — always consider compatibility and security.
+- **Commit message format**: `<type>(<scope>): <subject>`
+  - `type`: one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, etc.
+  - `scope`: the affected package/module/file/class.
+  - `subject`: concise description of the change.
+
+### Database migrations (Alembic)
+
+LangBot uses [Alembic](https://alembic.sqlalchemy.org/) for migrations, supporting both SQLite and PostgreSQL from a single set of scripts. Migration files live in `src/langbot/pkg/persistence/alembic/versions/`.
+
+If you change ORM model definitions, generate a migration:
+
+```bash
+# Run from the project root (requires data/config.yaml to exist)
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description of your change"
+```
+
+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.
-- Entities should not be multiplied unnecessarily
+- Entities should not be multiplied unnecessarily.
 - 八荣八耻
 
     以瞎猜接口为耻，以认真查询为荣。
@@ -83,4 +167,4 @@ Plugin Runtime automatically starts each installed plugin and interacts through
     以跳过验证为耻，以主动测试为荣。
     以破坏架构为耻，以遵循规范为荣。
     以假装理解为耻，以诚实无知为荣。
-    以盲目修改为耻，以谨慎重构为荣。
+    以盲目修改为耻，以谨慎重构为荣。

CLA.md

@@ -0,0 +1,107 @@
+# LangBot Individual Contributor License Agreement (v1.0)
+
+Thank you for your interest in contributing to LangBot (the "Project"), stewarded by Beijing Langbo Intelligent Technology Co., Ltd. (北京浪波智能科技有限公司) ("We" or "Us").
+
+This Individual Contributor License Agreement ("Agreement") documents the rights granted by contributors to Us. By signing this Agreement (see Section 9), You accept and agree to the following terms and conditions for Your present and future Contributions submitted to the Project. Except for the licenses granted herein to Us and recipients of software distributed by Us, You reserve all right, title, and interest in and to Your Contributions.
+
+## 1. Definitions
+
+"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with Us.
+
+"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to Us for inclusion in, or documentation of, any of the products or repositories owned or managed by Us (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to Us or our representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
+
+## 2. Grant of Copyright License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Us and to recipients of software distributed by Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. For clarity, this includes the right for Us to distribute Your Contributions, alone or as part of the Work, under the terms of any license, including without limitation open source licenses and commercial or proprietary licenses.
+
+## 3. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Us and to recipients of software distributed by Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that Your Contribution, or the Work to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
+
+## 4. Authority; Employer
+
+You represent that You are legally entitled to grant the above licenses. If Your employer(s) has rights to intellectual property that You create that includes Your Contributions, You represent that You have received permission to make Contributions on behalf of that employer, that Your employer has waived such rights for Your Contributions to Us, or that Your employer has executed a separate Corporate Contributor License Agreement with Us.
+
+## 5. Original Creation; Disclosure
+
+You represent that each of Your Contributions is Your original creation (see Section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are personally aware and which are associated with any part of Your Contributions.
+
+## 6. No Obligation of Support; Disclaimer
+
+You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+## 7. Third-Party Works
+
+Should You wish to submit work that is not Your original creation, You may submit it to Us separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".
+
+## 8. Notification
+
+You agree to notify Us of any facts or circumstances of which You become aware that would make these representations inaccurate in any respect.
+
+## 9. Electronic Signature
+
+This Agreement is accepted and signed electronically: posting a comment containing the exact phrase designated by Us (currently "I have read the CLA Document and I hereby sign the CLA") from Your GitHub account on a pull request in the Project's repositories constitutes Your binding electronic signature to this Agreement. You represent that the GitHub account used to sign belongs to You and that You are of legal age to form a binding contract. Your signature covers Your present and future Contributions to all repositories owned or managed by Us, until and unless You notify Us in writing that You withdraw from this Agreement for future Contributions (licenses already granted are irrevocable).
+
+## 10. Our Commitment
+
+We commit that the Project's main repository will continue to make an open source version of the Work publicly available.
+
+## 11. Miscellaneous
+
+This Agreement is the entire agreement between You and Us regarding Your Contributions and supersedes any prior agreements on this subject. If any provision is held unenforceable, the remaining provisions remain in effect. This Agreement is executed in English; the Chinese translation below is provided for reference only, and the English version shall prevail in case of any discrepancy.
+
+---
+
+# LangBot 个人贡献者许可协议（v1.0）中文参考译文
+
+> 本译文仅供参考，如与英文版有任何歧义，以英文版为准。
+
+感谢您有意为 LangBot（下称"本项目"）作出贡献。本项目由北京浪波智能科技有限公司（下称"我方"）运营管理。
+
+本《个人贡献者许可协议》（下称"本协议"）旨在记录贡献者授予我方的各项权利。您一经签署本协议（见第 9 条），即接受并同意以下条款与条件，适用于您向本项目提交的现在及未来的全部贡献。除本协议授予我方及我方分发软件之接收者的许可外，您保留对您的贡献的全部权利、所有权和利益。
+
+## 1. 定义
+
+"您"指与我方订立本协议的版权所有人，或经版权所有人授权的法律实体。
+
+"贡献"指您有意提交给我方、用于纳入我方拥有或管理的任何产品或代码仓库（下称"作品"）或其文档的任何原创作品，包括对既有作品的修改或增补。就本定义而言，"提交"指以任何电子、口头或书面形式向我方或我方代表发送的通信，包括但不限于在由我方或代表我方管理的电子邮件列表、源代码管理系统和问题跟踪系统中，为讨论和改进作品而进行的通信；但您以显著方式标注或以书面形式声明为"非贡献"（Not a Contribution）的通信除外。
+
+## 2. 版权许可的授予
+
+在遵守本协议条款与条件的前提下，您特此授予我方及我方分发软件之接收者一项永久的、全球范围的、非独占的、免费的、免版税的、不可撤销的版权许可，以复制您的贡献、基于其创作衍生作品、公开展示、公开表演、再许可以及分发您的贡献及上述衍生作品。为明确起见，上述许可包括我方有权以任何许可条款（包括但不限于开源许可证以及商业或专有许可证）单独或作为作品的一部分分发您的贡献。
+
+## 3. 专利许可的授予
+
+在遵守本协议条款与条件的前提下，您特此授予我方及我方分发软件之接收者一项永久的、全球范围的、非独占的、免费的、免版税的、不可撤销的（本条所述情形除外）专利许可，以制造、委托制造、使用、许诺销售、销售、进口及以其他方式转让作品；该许可仅适用于您可许可的、且因您的贡献本身或您的贡献与其所提交之作品的结合而必然受到侵犯的专利权利要求。如任何实体对您或任何其他实体提起专利诉讼（包括诉讼中的交叉请求或反诉），主张您的贡献或您所贡献的作品构成直接或帮助性专利侵权，则依据本协议就该贡献或作品授予该实体的任何专利许可，自该诉讼提起之日起终止。
+
+## 4. 权利能力与雇主
+
+您声明您在法律上有权授予上述许可。如您的雇主对您创作的、包含您的贡献在内的知识产权享有权利，您声明：您已获得该雇主代表其作出贡献的许可，或该雇主已就您向我方的贡献放弃上述权利，或该雇主已与我方另行签署《企业贡献者许可协议》。
+
+## 5. 原创性声明与披露义务
+
+您声明您的每项贡献均为您的原创作品（代表第三方提交的情形见第 7 条）。您声明您提交的贡献中已完整披露您本人知悉的、与您的贡献任何部分相关的任何第三方许可或其他限制（包括但不限于相关专利和商标）的全部细节。
+
+## 6. 无支持义务；免责声明
+
+您无义务为您的贡献提供支持，除非您自愿提供。您可以免费提供支持、收费提供支持或不提供支持。除非适用法律要求或另有书面约定，您的贡献按"现状"（AS IS）提供，不附带任何明示或默示的保证或条件，包括但不限于关于权属、不侵权、适销性或特定用途适用性的任何保证或条件。
+
+## 7. 第三方作品
+
+如您希望提交非您原创的作品，您可以将其与任何贡献分开单独提交给我方，并完整说明其来源以及您本人知悉的任何许可或其他限制（包括但不限于相关专利、商标和许可协议）的全部细节，同时以显著方式将该作品标注为"代表第三方提交：[此处注明第三方名称]"。
+
+## 8. 通知义务
+
+如您知悉任何事实或情况将导致上述声明在任何方面不准确，您同意通知我方。
+
+## 9. 电子签署
+
+本协议以电子方式接受并签署：您通过您的 GitHub 账号，在本项目代码仓库的拉取请求（pull request）中发表包含我方指定语句（现为 "I have read the CLA Document and I hereby sign the CLA"）的评论，即构成您对本协议具有约束力的电子签名。您声明用于签署的 GitHub 账号归您本人所有，且您已达到订立有约束力合同的法定年龄。您的签署覆盖您对我方拥有或管理的全部代码仓库的现在及未来的贡献，直至您以书面形式通知我方就未来贡献退出本协议为止（已授予的许可不可撤销）。
+
+## 10. 我方承诺
+
+我方承诺本项目主仓库将持续公开提供作品的开源版本。
+
+## 11. 其他
+
+本协议构成您与我方之间就您的贡献达成的完整协议，并取代双方先前就此主题达成的任何协议。如本协议任何条款被认定为不可执行，其余条款仍然有效。本协议以英文签署，中文译文仅供参考，如有歧义以英文版为准。

CONTRIBUTING.md

@@ -14,6 +14,12 @@
 - 在 PR 和 Commit Message 中请使用全英文
 - 对于中文用户，issue 中可以使用中文
 
+### 贡献者许可协议（CLA）
+
+为了保护项目和每一位贡献者，我们要求所有代码贡献者签署[贡献者许可协议（CLA）](./CLA.md)。这是 Apache、Google、Grafana 等主流开源项目的标准做法：您保留自己代码的全部版权，仅授予项目使用、分发您贡献的许可。
+
+签署只需 10 秒：首次提交 PR 时，机器人会自动评论提示，按提示回复一句话即完成签署，此后对本组织所有仓库永久有效。历史贡献不受影响。
+
 <hr/>
 
 ## Guidelines
@@ -29,3 +35,9 @@
 
 - Use English in PRs and Commit Messages
 - For English users, you can use English in issues
+
+### Contributor License Agreement (CLA)
+
+To protect the project and every contributor, we require all code contributors to sign our [Contributor License Agreement](./CLA.md). This is standard practice in major open source projects such as Apache, Google, and Grafana: you keep full copyright of your code — the CLA only grants us a license to use and distribute your contribution.
+
+Signing takes 10 seconds: when you open your first PR, a bot will guide you to reply with a single comment. One signature covers all repositories in this organization, permanently. Past contributions are not affected.

Dockerfile

@@ -4,7 +4,26 @@ WORKDIR /app
 
 COPY web ./web
 
-RUN cd web && npm install && npm run build
+RUN cd web && npm install && npx vite build
+
+# Build nsjail from source so the image ships a self-contained sandbox backend
+# that needs no host Docker socket. Pinned to a release tag for reproducibility.
+# Multi-stage keeps the compile toolchain (bison/flex/protobuf-dev/libnl-dev)
+# out of the final image; only the nsjail binary and its small runtime libs
+# (libprotobuf, libnl-route-3) are carried over.
+FROM python:3.12.7-slim AS nsjail-build
+
+ARG NSJAIL_VERSION=3.6
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates git build-essential \
+        autoconf bison flex libtool pkg-config \
+        protobuf-compiler libprotobuf-dev libnl-route-3-dev \
+    && git clone --depth 1 --branch "${NSJAIL_VERSION}" https://github.com/google/nsjail.git /nsjail \
+    && make -C /nsjail \
+    && install -m 0755 /nsjail/nsjail /usr/local/bin/nsjail \
+    && rm -rf /var/lib/apt/lists/*
 
 FROM python:3.12.7-slim
 
@@ -12,12 +31,31 @@ WORKDIR /app
 
 COPY . .
 
-COPY --from=node /app/web/out ./web/out
+COPY --from=node /app/web/dist ./web/dist
 
-RUN apt update \
-    && apt install gcc -y \
+# nsjail binary built in the dedicated stage above. Self-contained sandbox
+# backend; lets the Box runtime isolate code without a host Docker socket.
+COPY --from=nsjail-build /usr/local/bin/nsjail /usr/local/bin/nsjail
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends gcc ca-certificates curl gnupg \
+    # nsjail runtime libraries (the build toolchain stays in the nsjail-build
+    # stage; only these shared libs are needed to execute the binary).
+    && apt-get install -y --no-install-recommends libprotobuf32 libnl-route-3-200 \
+    # Install the Docker CLI (client only) so the optional langbot_box
+    # service can drive the mounted host Docker socket and create sandbox
+    # containers. The same image powers langbot / plugin_runtime / box; only
+    # box uses the client. Arch-aware via dpkg so multi-arch builds work.
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc \
+    && chmod a+r /etc/apt/keyrings/docker.asc \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" > /etc/apt/sources.list.d/docker.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends docker-ce-cli \
     && python -m pip install --no-cache-dir uv \
     && uv sync \
+    && apt-get purge -y --auto-remove curl gnupg \
+    && rm -rf /var/lib/apt/lists/* \
     && touch /.dockerenv
 
-CMD [ "uv", "run", "main.py" ]
+CMD [ "uv", "run", "--no-sync", "main.py" ]

Makefile

@@ -0,0 +1,36 @@
+# LangBot Makefile
+# Quick developer commands
+
+.PHONY: test test-quick test-integration-fast test-coverage test-all-local lint
+
+# Run all tests (full suite with coverage)
+test:
+	bash run_tests.sh
+
+# Quick self-test for developers (lint + unit + smoke, no real credentials needed)
+test-quick:
+	bash scripts/test-quick.sh
+
+# Fast integration tests (SQLite/API/Pipeline, no external services)
+test-integration-fast:
+	bash scripts/test-integration-fast.sh
+
+# Coverage gate (all tests, enforces minimum threshold)
+test-coverage:
+	bash scripts/test-coverage.sh
+
+# Full local quality gate (quick + integration + coverage)
+test-all-local:
+	bash scripts/test-quick.sh
+	bash scripts/test-integration-fast.sh
+	bash scripts/test-coverage.sh
+
+# Run linting only
+lint:
+	ruff check src/langbot/ tests/
+	ruff format --check src/langbot/ tests/
+
+# Fix linting issues
+lint-fix:
+	ruff check --fix src/langbot/ tests/
+	ruff format src/langbot/ tests/

README.md

@@ -1,47 +1,75 @@
-
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_zh.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
-<a href="https://hellogithub.com/repository/langbot-app/LangBot" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=5ce8ae2aa4f74316bf393b57b952433c&claim_uid=gtmc6YWjMZkT21R" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+<a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / 简体中文 / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+<h3>Production-grade platform for building agentic IM bots.</h3>
+<h4>Quickly build, debug, and ship AI bots to Slack, Discord, Telegram, WeChat, and more.</h4>
+
+English / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
-[![QQ Group](https://img.shields.io/badge/%E7%A4%BE%E5%8C%BAQQ%E7%BE%A4-966235608-blue)](https://qm.qq.com/q/JLi38whHum)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
-[![star](https://gitcode.com/RockChinQ/LangBot/star/badge.svg)](https://gitcode.com/RockChinQ/LangBot)
-
-<a href="https://langbot.app">项目主页</a> ｜
-<a href="https://docs.langbot.app/zh/insight/guide.html">部署文档</a> ｜
-<a href="https://docs.langbot.app/zh/plugin/plugin-intro.html">插件介绍</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">提交插件</a>
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
+<a href="https://langbot.app">Website</a> ｜
+<a href="https://link.langbot.app/en/docs/features">Features</a> ｜
+<a href="https://link.langbot.app/en/docs/guide">Docs</a> ｜
+<a href="https://link.langbot.app/en/docs/api">API</a> ｜
+<a href="https://space.langbot.app/cloud">Cloud</a> ｜
+<a href="https://space.langbot.app">Plugin Market</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">Roadmap</a>
 
 </div>
 
 </p>
 
-LangBot 是一个开源的大语言模型原生即时通信机器人开发平台，旨在提供开箱即用的 IM 机器人开发体验，具有 Agent、RAG、MCP 等多种 LLM 应用功能，适配全球主流即时通信平台，并提供丰富的 API 接口，支持自定义开发。
+---
 
-## 📦 开始使用
+## What is LangBot?
 
-#### 快速部署
+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.
 
-使用 `uvx` 一键启动（需要先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)）：
+<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).
+- **Universal IM Platform Support** — One codebase for Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, KOOK.
+- **Production-Ready** — Access control, rate limiting, sensitive word filtering, comprehensive monitoring, and exception handling. Trusted by enterprises.
+- **Plugin Ecosystem** — Hundreds of plugins, event-driven architecture, component extensions, and [MCP protocol](https://modelcontextprotocol.io/) support.
+- **Web Management Panel** — Configure, manage, and monitor your bots through an intuitive browser interface. No YAML editing required.
+- **Multi-Pipeline Architecture** — Different bots for different scenarios, with comprehensive monitoring and exception handling.
+
+[→ Learn more about all features](https://link.langbot.app/en/docs/features)
+
+📍 Practical guides: [deploy a multi-platform AI bot in 5 minutes](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connect DeepSeek to WeChat, Discord, and Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [run a Dify Agent in Discord, Telegram, and Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/), and [build an n8n-powered chatbot](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
+---
+
+## Quick Start
+
+### ☁️ LangBot Cloud (Recommended)
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — Zero deployment, ready to use.
+
+### One-Line Launch
 
 ```bash
 uvx langbot
 ```
 
-访问 http://localhost:5300 即可开始使用。
+> Requires [uv](https://docs.astral.sh/uv/getting-started/installation/). Visit http://localhost:5300 — done.
 
-#### Docker Compose 部署
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -49,123 +77,119 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-访问 http://localhost:5300 即可开始使用。
-
-详细文档[Docker 部署](https://docs.langbot.app/zh/deploy/langbot/docker.html)。
-
-#### 宝塔面板部署
-
-已上架宝塔面板，若您已安装宝塔面板，可以根据[文档](https://docs.langbot.app/zh/deploy/langbot/one-click/bt.html)使用。
-
-#### Zeabur 云部署
-
-社区贡献的 Zeabur 模板。
-
-[![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/zh-CN/templates/ZKTBDH)
-
-#### Railway 云部署
+### One-Click Cloud Deploy
 
+[![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### 手动部署
+**More options:** [Docker](https://link.langbot.app/en/docs/docker) · [Manual](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-直接使用发行版运行，查看文档[手动部署](https://docs.langbot.app/zh/deploy/langbot/manual.html)。
+---
 
-#### Kubernetes 部署
+## Supported Platforms
 
-参考 [Kubernetes 部署](./docker/README_K8S.md) 文档。
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Discord | ✅ | Official |
+| Telegram | ✅ | Official |
+| Slack | ✅ | Official |
+| LINE | ✅ | Official |
+| QQ | ✅ | Personal & Official API (Channel, DM, Group) |
+| WeCom | ✅ | Enterprise WeChat, External CS, AI Bot |
+| WeChat | ✅ | Personal & Official Account |
+| Lark | ✅ | Official |
+| DingTalk | ✅ | Official |
+| KOOK | ✅ | Official |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Supports multiple bridged platforms such as Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip, and more |
 
-## 😎 保持更新
+---
 
-点击仓库右上角 Star 和 Watch 按钮，获取最新动态。
+## Supported LLMs & Integrations
 
-![star gif](https://docs.langbot.app/star.gif)
+| Provider                                                                                                          | Type         | Status |
+| ----------------------------------------------------------------------------------------------------------------- | ------------ | ------ |
+| [OpenAI](https://platform.openai.com/)                                                                            | LLM          | ✅     |
+| [Anthropic](https://www.anthropic.com/)                                                                           | LLM          | ✅     |
+| [DeepSeek](https://www.deepseek.com/)                                                                             | LLM          | ✅     |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat)                                                     | LLM          | ✅     |
+| [xAI](https://x.ai/)                                                                                              | LLM          | ✅     |
+| [Moonshot](https://www.moonshot.cn/)                                                                              | LLM          | ✅     |
+| [Zhipu AI](https://open.bigmodel.cn/)                                                                             | LLM          | ✅     |
+| [Ollama](https://ollama.com/)                                                                                     | Local LLM    | ✅     |
+| [LM Studio](https://lmstudio.ai/)                                                                                 | Local LLM    | ✅     |
+| [Dify](https://dify.ai)                                                                                           | LLMOps       | ✅     |
+| [MCP](https://modelcontextprotocol.io/)                                                                           | Protocol     | ✅     |
+| [SiliconFlow](https://siliconflow.cn/)                                                                            | Gateway      | ✅     |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/)                                                             | Gateway      | ✅     |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Gateway      | ✅     |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro)                                        | Gateway      | ✅     |
+| [GiteeAI](https://ai.gitee.com/)                                                                                  | Gateway      | ✅     |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot)                                                     | GPU Platform | ✅     |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot)                             | GPU Platform | ✅     |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758)                                                    | GPU Platform | ✅     |
+| [接口 AI](https://jiekou.ai/)                                                                                     | Gateway      | ✅     |
+| [302.AI](https://share.302.ai/SuTG99)                                                                             | Gateway      | ✅     |
+| [Qiniu](https://www.qiniu.com/ai/agent)                                                                           | Gateway      | ✅     |
 
-## ✨ 特性
+[→ View all integrations](https://link.langbot.app/en/docs/features)
 
-- 💬 大模型对话、Agent：支持多种大模型，适配群聊和私聊；具有多轮对话、工具调用、多模态、流式输出能力，自带 RAG（知识库）实现，并深度适配 [Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io)等 LLMOps 平台。
-- 🤖 多平台支持：目前支持 QQ、QQ频道、企业微信、个人微信、飞书、Discord、Telegram、KOOK、Slack、LINE 等平台。
-- 🛠️ 高稳定性、功能完备：原生支持访问控制、限速、敏感词过滤等机制；配置简单，支持多种部署方式。支持多流水线配置，不同机器人用于不同应用场景。
-- 🧩 插件扩展、活跃社区：高稳定性、高安全性的生产级插件系统，支持事件驱动、组件扩展等插件机制；适配 Anthropic [MCP 协议](https://modelcontextprotocol.io/)；目前已有数百个插件。
-- 😻 Web 管理面板：支持通过浏览器管理 LangBot 实例，不再需要手动编写配置文件。
+---
 
-详细规格特性请访问[文档](https://docs.langbot.app/zh/insight/features.html)。
+## Why LangBot?
 
-或访问 demo 环境：https://demo.langbot.dev/  
-  - 登录信息：邮箱：`demo@langbot.app` 密码：`langbot123456`
-  - 注意：仅展示 WebUI 效果，公开环境，请不要在其中填入您的任何敏感信息。
+| Use Case                    | How LangBot Helps                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| **Customer Support**        | Deploy AI agents to Slack/Discord/Telegram that answer questions using your knowledge base |
+| **Internal Tools**          | Connect n8n/Dify workflows to WeCom/DingTalk for automated business processes              |
+| **Community Management**    | Moderate QQ/Discord groups with AI-powered content filtering and interaction               |
+| **Multi-Platform Presence** | One bot, all platforms. Manage from a single dashboard                                     |
 
-### 消息平台
+---
 
-| 平台 | 状态 | 备注 |
-| --- | --- | --- |
-| QQ 个人号 | ✅ | QQ 个人号私聊、群聊 |
-| QQ 官方机器人 | ✅ | QQ 官方机器人，支持频道、私聊、群聊 |
-| 企业微信 | ✅ |  |
-| 企微对外客服 | ✅ |  |
-| 企微智能机器人 | ✅ |  |
-| 个人微信 | ✅ |  |
-| 微信公众号 | ✅ |  |
-| 飞书 | ✅ |  |
-| 钉钉 | ✅ |  |
-| KOOK | ✅ |  |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
+## 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:
 
-| 模型 | 状态 | 备注 |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | 可接入任何 OpenAI 接口格式模型 |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [智谱AI](https://open.bigmodel.cn/) | ✅ |  |
-| [胜算云](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | 全球大模型都可调用（友情推荐） |
-| [优云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | 大模型和 GPU 资源平台 |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | 大模型和 GPU 资源平台 |
-| [接口 AI](https://jiekou.ai/) | ✅ | 大模型聚合平台，专注全球大模型接入 |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | 大模型聚合平台 |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | LLMOps 平台 |
-| [Ollama](https://ollama.com/) | ✅ | 本地大模型运行平台 |
-| [LMStudio](https://lmstudio.ai/) | ✅ | 本地大模型运行平台 |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | 大模型接口聚合平台 |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | 大模型聚合平台 |
-| [小马算力](https://www.tokenpony.cn/453z1) | ✅ | 大模型聚合平台 |
-| [阿里云百炼](https://bailian.console.aliyun.com/) | ✅ | 大模型聚合平台, LLMOps 平台 |
-| [火山方舟](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | 大模型聚合平台, LLMOps 平台 |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | 大模型聚合平台 |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | 支持通过 MCP 协议获取工具 |
-| [百宝箱Tbox](https://www.tbox.cn/open) | ✅ | 蚂蚁百宝箱智能体平台，每月免费10亿大模型Token |
+- **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.
 
-### TTS
+> **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.
 
-| 平台/模型 | 备注 |
-| --- | --- |
-| [FishAudio](https://fish.audio/zh-CN/discovery/) | [插件](https://github.com/the-lazy-me/NewChatVoice) |
-| [海豚 AI](https://www.ttson.cn/?source=thelazy) | [插件](https://github.com/the-lazy-me/NewChatVoice) |
-| [AzureTTS](https://portal.azure.com/) | [插件](https://github.com/Ingnaryk/LangBot_AzureTTS) |
+---
 
-### 文生图
+## Live Demo
 
-| 平台/模型 | 备注 |
-| --- | --- |
-| 阿里云百炼 | [插件](https://github.com/Thetail001/LangBot_BailianTextToImagePlugin)
+**Try it now:** https://demo.langbot.dev/
 
-## 😘 社区贡献
+- Email: `demo@langbot.app`
+- Password: `langbot123456`
 
-感谢以下[代码贡献者](https://github.com/langbot-app/LangBot/graphs/contributors)和社区里其他成员对 LangBot 的贡献：
+_Note: Public demo environment. Do not enter sensitive information._
+
+---
+
+## Community
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Discord Community](https://discord.gg/wdNEHETs87)
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## Contributors
+
+Thanks to all [contributors](https://github.com/langbot-app/LangBot/graphs/contributors) who have helped make LangBot better:
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
 </a>
-
-<!--
-## For Code Agents
-
-If you're a code agent based on LLM, you should read [AGENTS.md](AGENTS.md) to understand the project structure and development process before you start any development.
--->

README_CN.md

@@ -0,0 +1,218 @@
+<p align="center">
+<a href="https://langbot.app">
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
+</a>
+
+<div align="center">
+
+<a href="https://hellogithub.com/repository/langbot-app/LangBot" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=5ce8ae2aa4f74316bf393b57b952433c&claim_uid=gtmc6YWjMZkT21R" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+
+<h3>生产级 AI 即时通信机器人开发平台。</h3>
+<h4>快速构建、调试和部署 AI 机器人到微信、QQ、飞书、Slack、Discord、Telegram 等平台。</h4>
+
+[English](README.md) / 简体中文 / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
+[![QQ Group](https://img.shields.io/badge/%E7%A4%BE%E5%8C%BAQQ%E7%BE%A4-1030838208-blue)](https://qm.qq.com/q/IrlV8QFacU)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
+<img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
+[![star](https://gitcode.com/RockChinQ/LangBot/star/badge.svg)](https://gitcode.com/RockChinQ/LangBot)
+
+<a href="https://langbot.app">官网</a> ｜
+<a href="https://link.langbot.app/zh/docs/features">特性</a> ｜
+<a href="https://link.langbot.app/zh/docs/guide">文档</a> ｜
+<a href="https://link.langbot.app/zh/docs/api">API</a> ｜
+<a href="https://space.langbot.app/cloud">Cloud</a> ｜
+<a href="https://space.langbot.app">扩展市场</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">路线图</a>
+
+</div>
+
+</p>
+
+---
+
+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 平台。
+- **全平台支持** — 一套代码，覆盖 QQ、微信、企业微信、飞书、钉钉、Discord、Telegram、Slack、LINE、KOOK 等平台。
+- **生产就绪** — 访问控制、限速、敏感词过滤、全面监控与异常处理，已被多家企业采用。
+- **插件生态** — 数百个插件，跨进程的事件驱动架构，组件扩展，适配 [MCP 协议](https://modelcontextprotocol.io/)。
+- **Web 管理面板** — 通过浏览器直观地配置、管理和监控机器人，无需手动编辑配置文件。
+- **多流水线架构** — 不同机器人用于不同场景，具备全面的监控和异常处理能力。
+
+[→ 了解更多功能特性](https://link.langbot.app/zh/docs/features)
+
+📍 实践指南：[5 分钟部署多平台 AI 机器人](https://blog.langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[将 DeepSeek 接入微信、企业微信与 Discord](https://blog.langbot.app/zh/blog/connect-deepseek-to-wechat/)、[让 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://blog.langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 构建多平台 AI 聊天机器人](https://blog.langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。
+
+---
+
+## 快速开始
+
+### ☁️ LangBot Cloud（推荐）
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — 免部署，开箱即用。
+
+### 一键启动
+
+```bash
+uvx langbot
+```
+
+> 需要安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)。访问 http://localhost:5300 即可使用。
+
+### Docker Compose
+
+```bash
+git clone https://github.com/langbot-app/LangBot
+cd LangBot/docker
+docker compose up -d
+```
+
+### 一键云部署
+
+[![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/zh-CN/templates/ZKTBDH)
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
+
+**更多方式：** [Docker](https://link.langbot.app/zh/docs/docker) · [手动部署](https://link.langbot.app/zh/docs/manual-deploy) · [宝塔面板](https://link.langbot.app/zh/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/zh/deploy/langbot/kubernetes)
+
+---
+
+## 支持的平台
+
+| 平台 | 状态 | 备注 |
+|------|------|------|
+| QQ | ✅ | 个人号、官方机器人（频道、私聊、群聊） |
+| 微信 | ✅ | 个人微信、微信公众号 |
+| 企业微信 | ✅ | 应用消息、对外客服、智能机器人 |
+| 飞书 | ✅ | 官方 |
+| 钉钉 | ✅ | 官方 |
+| Satori | ✅ |  |
+| Discord | ✅ | 官方 |
+| Telegram | ✅ | 官方 |
+| Slack | ✅ | 官方 |
+| LINE | ✅ | 官方 |
+| KOOK | ✅ | 官方 |
+| Email | ✅ | 只 Matrix、Satori |
+| Matrix | ✅ | 支持多种桥接平台，如 Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip 等 |
+
+---
+
+## 支持的大模型与集成
+
+| 提供商 | 类型 | 状态 |
+|--------|------|------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [智谱AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | 本地 LLM | ✅ |
+| [LM Studio](https://lmstudio.ai/) | 本地 LLM | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | 协议 | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | 聚合平台 | ✅ |
+| [阿里云百炼](https://bailian.console.aliyun.com/) | 聚合平台 | ✅ |
+| [火山方舟](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | 聚合平台 | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | 聚合平台 | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | 聚合平台 | ✅ |
+| [胜算云](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPU 平台 | ✅ |
+| [优云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | GPU 平台 | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | GPU 平台 | ✅ |
+| [接口 AI](https://jiekou.ai/) | 聚合平台 | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | 聚合平台 | ✅ |
+| [小马算力](https://www.tokenpony.cn/453z1) | 聚合平台 | ✅ |
+| [百宝箱Tbox](https://www.tbox.cn/open) | 智能体平台 | ✅ |
+| [七牛云Qiniu](https://www.qiniu.com/ai/agent) | 聚合平台 | ✅ |
+
+[→ 查看完整集成列表](https://link.langbot.app/zh/docs/features)
+
+### TTS（语音合成）
+
+| 平台/模型 | 备注 |
+|-----------|------|
+| [FishAudio](https://fish.audio/zh-CN/discovery/) | [插件](https://github.com/the-lazy-me/NewChatVoice) |
+| [海豚 AI](https://www.ttson.cn/?source=thelazy) | [插件](https://github.com/the-lazy-me/NewChatVoice) |
+| [AzureTTS](https://portal.azure.com/) | [插件](https://github.com/Ingnaryk/LangBot_AzureTTS) |
+
+### 文生图
+
+| 平台/模型 | 备注 |
+|-----------|------|
+| 阿里云百炼 | [插件](https://github.com/Thetail001/LangBot_BailianTextToImagePlugin) |
+
+---
+
+## 为什么选择 LangBot？
+
+| 使用场景 | LangBot 如何帮助 |
+|----------|------------------|
+| **客户服务** | 将 AI Agent 部署到微信/企微/钉钉/飞书，基于知识库自动回答用户问题 |
+| **内部工具** | 将 n8n/Dify 工作流接入企微/钉钉，实现业务流程自动化 |
+| **社群运营** | 在 QQ/Discord 群中使用 AI 驱动的内容审核与智能互动 |
+| **多平台触达** | 一个机器人，覆盖所有平台。通过统一面板集中管理 |
+
+---
+
+## 在线演示
+
+**立即体验：** https://demo.langbot.dev/
+- 邮箱：`demo@langbot.app`
+- 密码：`langbot123456`
+
+*注意：公开演示环境，请不要在其中填入任何敏感信息。*
+
+---
+
+## 为 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)
+[![QQ Group](https://img.shields.io/badge/%E7%A4%BE%E5%8C%BAQQ%E7%BE%A4-1030838208-blue)](https://qm.qq.com/q/DxZZcNxM1W)
+
+- [Discord 社区](https://discord.gg/wdNEHETs87)
+- [QQ 社区群](https://qm.qq.com/q/DxZZcNxM1W)
+
+---
+
+## Star 趋势
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## 贡献者
+
+感谢所有[贡献者](https://github.com/langbot-app/LangBot/graphs/contributors)对 LangBot 的帮助：
+
+<a href="https://github.com/langbot-app/LangBot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
+</a>
+
+<!--
+## For Code Agents
+
+If you're a code agent based on LLM, you should read [AGENTS.md](AGENTS.md) to understand the project structure and development process before you start any development.
+-->

README_EN.md

@@ -1,144 +0,0 @@
-<p align="center">
-<a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
-</a>
-
-<div align="center">
-
-<a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
-
-English / [简体中文](README.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
-
-[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
-<img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
-
-<a href="https://langbot.app">Home</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">Deployment</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">Plugin</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">Submit Plugin</a>
-
-</div>
-
-</p>
-
-LangBot is an open-source LLM native instant messaging robot development platform, aiming to provide out-of-the-box IM robot development experience, with Agent, RAG, MCP and other LLM application functions, adapting to global instant messaging platforms, and providing rich API interfaces, supporting custom development.
-
-## 📦 Getting Started
-
-#### Quick Start
-
-Use `uvx` to start with one command (need to install [uv](https://docs.astral.sh/uv/getting-started/installation/)):
-
-```bash
-uvx langbot
-```
-
-Visit http://localhost:5300 to start using it.
-
-#### Docker Compose Deployment
-
-```bash
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
-docker compose up -d
-```
-
-Visit http://localhost:5300 to start using it.
-
-Detailed documentation [Docker Deployment](https://docs.langbot.app/en/deploy/langbot/docker.html).
-
-#### One-click Deployment on BTPanel
-
-LangBot has been listed on the BTPanel, if you have installed the BTPanel, you can use the [document](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html) to use it.
-
-#### Zeabur Cloud Deployment
-
-Community contributed Zeabur template.
-
-[![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Railway Cloud Deployment
-
-[![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
-
-#### Other Deployment Methods
-
-Directly use the released version to run, see the [Manual Deployment](https://docs.langbot.app/en/deploy/langbot/manual.html) documentation.
-
-#### Kubernetes Deployment
-
-Refer to the [Kubernetes Deployment](./docker/README_K8S.md) documentation.
-
-## 😎 Stay Ahead
-
-Click the Star and Watch button in the upper right corner of the repository to get the latest updates.
-
-![star gif](https://docs.langbot.app/star.gif)
-
-## ✨ Features
-
-- 💬 Chat with LLM / Agent: Supports multiple LLMs, adapt to group chats and private chats; Supports multi-round conversations, tool calls, multi-modal, and streaming output capabilities. Built-in RAG (knowledge base) implementation, and deeply integrates with [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io) etc. LLMOps platforms.
-- 🤖 Multi-platform Support: Currently supports QQ, QQ Channel, WeCom, personal WeChat, Lark, DingTalk, Discord, Telegram, KOOK, Slack, LINE, etc.
-- 🛠️ High Stability, Feature-rich: Native access control, rate limiting, sensitive word filtering, etc. mechanisms; Easy to use, supports multiple deployment methods. Supports multiple pipeline configurations, different bots can be used for different scenarios.
-- 🧩 Plugin Extension, Active Community: High stability, high security production-level plugin system; Support event-driven, component extension, etc. plugin mechanisms; Integrate Anthropic [MCP protocol](https://modelcontextprotocol.io/); Currently has hundreds of plugins.
-- 😻 Web UI: Support management LangBot instance through the browser. No need to manually write configuration files.
-
-For more detailed specifications, please refer to the [documentation](https://docs.langbot.app/en/insight/features.html).
-
-Or visit the demo environment: https://demo.langbot.dev/
-  - Login information: Email: `demo@langbot.app` Password: `langbot123456`
-  - Note: For WebUI demo only, please do not fill in any sensitive information in the public environment.
-
-### Message Platform
-
-| Platform | Status | Remarks |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| Personal QQ | ✅ |  |
-| QQ Official API | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| Personal WeChat | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
-
-### LLMs
-
-| LLM | Status | Remarks |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | Available for any OpenAI interface format model |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | LLM and GPU resource platform |
-| [Dify](https://dify.ai) | ✅ | LLMOps platform |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | LLM and GPU resource platform |
-| [接口 AI](https://jiekou.ai/) | ✅ | LLM aggregation platform, dedicated to global LLMs |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | LLM and GPU resource platform |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | LLM gateway(MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Ollama](https://ollama.com/) | ✅ | Local LLM running platform |
-| [LMStudio](https://lmstudio.ai/) | ✅ | Local LLM running platform |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | LLM interface gateway(MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | LLM gateway(MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | LLM gateway(MaaS), LLMOps platform |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | LLM gateway(MaaS), LLMOps platform |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | LLM gateway(MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | Support tool access through MCP protocol |
-
-## 🤝 Community Contribution
-
-Thank you for the following [code contributors](https://github.com/langbot-app/LangBot/graphs/contributors) and other members in the community for their contributions to LangBot:
-
-<a href="https://github.com/langbot-app/LangBot/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
-</a>

README_ES.md

@@ -1,43 +1,74 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
 <a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / [简体中文](README.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / Español / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+<h3>Plataforma de grado de producción para construir bots de mensajería instantánea con agentes de IA.</h3>
+<h4>Construya, depure y despliegue bots de IA rápidamente en Slack, Discord, Telegram, WeChat y más.</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / Español / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
 <a href="https://langbot.app">Inicio</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">Despliegue</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">Plugin</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">Enviar Plugin</a>
+<a href="https://link.langbot.app/en/docs/features">Características</a> ｜
+<a href="https://link.langbot.app/en/docs/guide">Documentación</a> ｜
+<a href="https://link.langbot.app/en/docs/api">API</a> ｜
+<a href="https://space.langbot.app">Mercado de Plugins</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">Hoja de Ruta</a>
 
 </div>
 
 </p>
 
-LangBot es una plataforma de desarrollo de robots de mensajería instantánea nativa de LLM de código abierto, con el objetivo de proporcionar una experiencia de desarrollo de robots de mensajería instantánea lista para usar, con funciones de aplicación LLM como Agent, RAG, MCP, adaptándose a plataformas de mensajería instantánea globales y proporcionando interfaces API ricas, compatible con desarrollo personalizado.
+---
 
-## 📦 Comenzar
+## ¿Qué es LangBot?
 
-#### Inicio Rápido
+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.
 
-Use `uvx` para iniciar con un comando (necesita instalar [uv](https://docs.astral.sh/uv/getting-started/installation/)):
+<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).
+- **Soporte Universal de Plataformas de MI** — Un solo código base para Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, KOOK.
+- **Listo para Producción** — Control de acceso, limitación de velocidad, filtrado de palabras sensibles, monitoreo completo y manejo de excepciones. De confianza para empresas.
+- **Ecosistema de Plugins** — Cientos de plugins, arquitectura basada en eventos, extensiones de componentes y soporte del [protocolo MCP](https://modelcontextprotocol.io/).
+- **Panel de Gestión Web** — Configure, gestione y monitoree sus bots a través de una interfaz de navegador intuitiva. Sin necesidad de editar YAML.
+- **Arquitectura Multi-Pipeline** — Diferentes bots para diferentes escenarios, con monitoreo completo y manejo de excepciones.
+
+[→ Conocer más sobre todas las funcionalidades](https://link.langbot.app/en/docs/features)
+
+📍 Guías prácticas: [desplegar un bot de IA multiplataforma en 5 minutos](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [conectar DeepSeek a WeChat, Discord y Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [ejecutar un Dify Agent en Discord, Telegram y Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) y [crear un chatbot con n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
+---
+
+## Inicio Rápido
+
+### ☁️ LangBot Cloud (Recomendado)
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — Sin despliegue, listo para usar.
+
+### Lanzamiento en una línea
 
 ```bash
 uvx langbot
 ```
 
-Visite http://localhost:5300 para comenzar a usarlo.
+> Requiere [uv](https://docs.astral.sh/uv/getting-started/installation/). Visite http://localhost:5300 — listo.
 
-#### Despliegue con Docker Compose
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,99 +76,115 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-Visite http://localhost:5300 para comenzar a usarlo.
-
-Documentación detallada [Despliegue con Docker](https://docs.langbot.app/en/deploy/langbot/docker.html).
-
-#### Despliegue con un clic en BTPanel
-
-LangBot ha sido listado en BTPanel. Si tiene BTPanel instalado, puede usar la [documentación](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html) para usarlo.
-
-#### Despliegue en la Nube Zeabur
-
-Plantilla de Zeabur contribuida por la comunidad.
+### Despliegue en la Nube con un Clic
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Despliegue en la Nube Railway
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### Otros Métodos de Despliegue
+**Más opciones:** [Docker](https://link.langbot.app/en/docs/docker) · [Manual](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-Use directamente la versión publicada para ejecutar, consulte la documentación de [Despliegue Manual](https://docs.langbot.app/en/deploy/langbot/manual.html).
+---
 
-#### Despliegue en Kubernetes
+## Plataformas Soportadas
 
-Consulte la documentación de [Despliegue en Kubernetes](./docker/README_K8S.md).
+| Plataforma | Estado | Notas |
+|----------|--------|-------|
+| Discord | ✅ | Oficial |
+| Telegram | ✅ | Oficial |
+| Slack | ✅ | Oficial |
+| LINE | ✅ | Oficial |
+| QQ | ✅ | Personal y API Oficial (Canal, DM, Grupo) |
+| WeCom | ✅ | WeChat Empresarial, CS Externo, AI Bot |
+| WeChat | ✅ | Personal y Cuenta Oficial |
+| Lark | ✅ | Oficial |
+| DingTalk | ✅ | Oficial |
+| KOOK | ✅ | Oficial |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Admite varias plataformas puenteadas como Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip y más |
 
-## 😎 Manténgase Actualizado
+---
 
-Haga clic en los botones Star y Watch en la esquina superior derecha del repositorio para obtener las últimas actualizaciones.
+## LLMs e Integraciones Soportadas
 
-![star gif](https://docs.langbot.app/star.gif)
+| Proveedor | Tipo | Estado |
+|----------|------|--------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | LLM Local | ✅ |
+| [LM Studio](https://lmstudio.ai/) | LLM Local | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | Protocolo | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | Pasarela | ✅ |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/) | Pasarela | ✅ |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Pasarela | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | Pasarela | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | Pasarela | ✅ |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | Plataforma GPU | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | Plataforma GPU | ✅ |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Plataforma GPU | ✅ |
+| [接口 AI](https://jiekou.ai/) | Pasarela | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | Pasarela | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Pasarela | ✅ |
 
-## ✨ Características
+[→ Ver todas las integraciones](https://link.langbot.app/en/docs/features)
 
-- 💬 Chat con LLM / Agent: Compatible con múltiples LLMs, adaptado para chats grupales y privados; Admite conversaciones de múltiples rondas, llamadas a herramientas, capacidades multimodales y de salida en streaming. Implementación RAG (base de conocimientos) incorporada, e integración profunda con [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io) etc. LLMOps platforms.
-- 🤖 Soporte Multiplataforma: Actualmente compatible con QQ, QQ Channel, WeCom, WeChat personal, Lark, DingTalk, Discord, Telegram, KOOK, Slack, LINE, etc.
-- 🛠️ Alta Estabilidad, Rico en Funciones: Control de acceso nativo, limitación de velocidad, filtrado de palabras sensibles, etc.; Fácil de usar, admite múltiples métodos de despliegue. Compatible con múltiples configuraciones de pipeline, diferentes bots para diferentes escenarios.
-- 🧩 Extensión de Plugin, Comunidad Activa: Sistema de plugin de alta estabilidad, alta seguridad de nivel de producción; Compatible con mecanismos de plugin impulsados por eventos, extensión de componentes, etc.; Integración del protocolo [MCP](https://modelcontextprotocol.io/) de Anthropic; Actualmente cuenta con cientos de plugins.
-- 😻 Interfaz Web: Admite la gestión de instancias de LangBot a través del navegador. No es necesario escribir archivos de configuración manualmente.
+---
 
-Para especificaciones más detalladas, consulte la [documentación](https://docs.langbot.app/en/insight/features.html).
+## ¿Por qué LangBot?
 
-O visite el entorno de demostración: https://demo.langbot.dev/
-  - Información de inicio de sesión: Correo electrónico: `demo@langbot.app` Contraseña: `langbot123456`
-  - Nota: Solo para demostración de WebUI, por favor no ingrese información confidencial en el entorno público.
+| Caso de Uso | Cómo Ayuda LangBot |
+|----------|-------------------|
+| **Atención al cliente** | Despliegue agentes de IA en Slack/Discord/Telegram que respondan preguntas usando su base de conocimientos |
+| **Herramientas internas** | Conecte flujos de trabajo de n8n/Dify a WeCom/DingTalk para procesos empresariales automatizados |
+| **Gestión de comunidades** | Modere grupos de QQ/Discord con filtrado de contenido e interacción impulsados por IA |
+| **Presencia multiplataforma** | Un solo bot, todas las plataformas. Gestione desde un único panel de control |
 
-### Plataformas de Mensajería
+---
 
-| Plataforma | Estado | Observaciones |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ Personal | ✅ |  |
-| QQ API Oficial | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| WeChat Personal | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+## Demo en Vivo
 
-### LLMs
+**Pruébelo ahora:** https://demo.langbot.dev/
+- Correo electrónico: `demo@langbot.app`
+- Contraseña: `langbot123456`
 
-| LLM | Estado | Observaciones |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | Disponible para cualquier modelo con formato de interfaz OpenAI |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | Plataforma de recursos LLM y GPU |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | Plataforma de recursos LLM y GPU |
-| [接口 AI](https://jiekou.ai/) | ✅ | Plataforma de agregación LLM |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | Plataforma de recursos LLM y GPU |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | Gateway LLM (MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | Plataforma LLMOps |
-| [Ollama](https://ollama.com/) | ✅ | Plataforma de ejecución de LLM local |
-| [LMStudio](https://lmstudio.ai/) | ✅ | Plataforma de ejecución de LLM local |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | Gateway de interfaz LLM (MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | Gateway LLM (MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | Gateway LLM (MaaS), plataforma LLMOps |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | Gateway LLM (MaaS), plataforma LLMOps |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | Gateway LLM (MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | Compatible con acceso a herramientas a través del protocolo MCP |
+*Nota: Entorno de demostración público. No ingrese información confidencial.*
 
-## 🤝 Contribución de la Comunidad
+## Diseñado para Agentes de IA 🤖
 
-Gracias a los siguientes [contribuidores de código](https://github.com/langbot-app/LangBot/graphs/contributors) y otros miembros de la comunidad por sus contribuciones a LangBot:
+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
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Comunidad de Discord](https://discord.gg/wdNEHETs87)
+
+---
+
+## Historial de Stars
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## Colaboradores
+
+Gracias a todos los [colaboradores](https://github.com/langbot-app/LangBot/graphs/contributors) que han ayudado a mejorar LangBot:
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />

README_FR.md

@@ -1,43 +1,74 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
 <a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / [简体中文](README.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / Français / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+<h3>Plateforme de niveau production pour construire des bots de messagerie instantanée avec agents IA.</h3>
+<h4>Créez, déboguez et déployez rapidement des bots IA sur Slack, Discord, Telegram, WeChat et plus.</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / Français / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
 <a href="https://langbot.app">Accueil</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">Déploiement</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">Plugin</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">Soumettre un Plugin</a>
+<a href="https://link.langbot.app/en/docs/features">Fonctionnalités</a> ｜
+<a href="https://link.langbot.app/en/docs/guide">Documentation</a> ｜
+<a href="https://link.langbot.app/en/docs/api">API</a> ｜
+<a href="https://space.langbot.app">Marché des Plugins</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">Feuille de Route</a>
 
 </div>
 
 </p>
 
-LangBot est une plateforme de développement de robots de messagerie instantanée native LLM open source, visant à fournir une expérience de développement de robots de messagerie instantanée prête à l'emploi, avec des fonctionnalités d'application LLM telles qu'Agent, RAG, MCP, s'adaptant aux plateformes de messagerie instantanée mondiales et fournissant des interfaces API riches, prenant en charge le développement personnalisé.
+---
 
-## 📦 Commencer
+## Qu'est-ce que LangBot ?
 
-#### Démarrage Rapide
+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.
 
-Utilisez `uvx` pour démarrer avec une commande (besoin d'installer [uv](https://docs.astral.sh/uv/getting-started/installation/)) :
+<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).
+- **Support Universel des Plateformes de MI** — Un seul code pour Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, KOOK.
+- **Prêt pour la Production** — Contrôle d'accès, limitation de débit, filtrage de mots sensibles, surveillance complète et gestion des exceptions. Approuvé par les entreprises.
+- **Écosystème de Plugins** — Des centaines de plugins, architecture événementielle, extensions de composants, et support du [protocole MCP](https://modelcontextprotocol.io/).
+- **Panneau de Gestion Web** — Configurez, gérez et surveillez vos bots via une interface navigateur intuitive. Aucune édition de YAML requise.
+- **Architecture Multi-Pipeline** — Différents bots pour différents scénarios, avec surveillance complète et gestion des exceptions.
+
+[→ En savoir plus sur toutes les fonctionnalités](https://link.langbot.app/en/docs/features)
+
+📍 Guides pratiques : [déployer un bot IA multiplateforme en 5 minutes](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connecter DeepSeek à WeChat, Discord et Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [exécuter un Dify Agent dans Discord, Telegram et Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) et [créer un chatbot avec n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
+---
+
+## Démarrage Rapide
+
+### ☁️ LangBot Cloud (Recommandé)
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — Sans déploiement, prêt à utiliser.
+
+### Lancement en une ligne
 
 ```bash
 uvx langbot
 ```
 
-Visitez http://localhost:5300 pour commencer à l'utiliser.
+> Nécessite [uv](https://docs.astral.sh/uv/getting-started/installation/). Visitez http://localhost:5300 — c'est prêt.
 
-#### Déploiement avec Docker Compose
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,99 +76,115 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-Visitez http://localhost:5300 pour commencer à l'utiliser.
-
-Documentation détaillée [Déploiement Docker](https://docs.langbot.app/en/deploy/langbot/docker.html).
-
-#### Déploiement en un clic sur BTPanel
-
-LangBot a été répertorié sur BTPanel. Si vous avez installé BTPanel, vous pouvez utiliser la [documentation](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html) pour l'utiliser.
-
-#### Déploiement Cloud Zeabur
-
-Modèle Zeabur contribué par la communauté.
+### Déploiement Cloud en un Clic
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Déploiement Cloud Railway
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### Autres Méthodes de Déploiement
+**Plus d'options :** [Docker](https://link.langbot.app/en/docs/docker) · [Manuel](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-Utilisez directement la version publiée pour exécuter, consultez la documentation de [Déploiement Manuel](https://docs.langbot.app/en/deploy/langbot/manual.html).
+---
 
-#### Déploiement Kubernetes
+## Plateformes Supportées
 
-Consultez la documentation de [Déploiement Kubernetes](./docker/README_K8S.md).
+| Plateforme | Statut | Notes |
+|----------|--------|-------|
+| Discord | ✅ | Officiel |
+| Telegram | ✅ | Officiel |
+| Slack | ✅ | Officiel |
+| LINE | ✅ | Officiel |
+| QQ | ✅ | Personnel & API Officielle (Canal, DM, Groupe) |
+| WeCom | ✅ | WeChat Entreprise, CS Externe, AI Bot |
+| WeChat | ✅ | Personnel & Compte Officiel |
+| Lark | ✅ | Officiel |
+| DingTalk | ✅ | Officiel |
+| KOOK | ✅ | Officiel |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Prend en charge plusieurs plateformes via ponts, comme Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip, etc. |
 
-## 😎 Restez à Jour
+---
 
-Cliquez sur les boutons Star et Watch dans le coin supérieur droit du dépôt pour obtenir les dernières mises à jour.
+## LLMs et Intégrations Supportés
 
-![star gif](https://docs.langbot.app/star.gif)
+| Fournisseur | Type | Statut |
+|----------|------|--------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | LLM Local | ✅ |
+| [LM Studio](https://lmstudio.ai/) | LLM Local | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | Protocole | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | Passerelle | ✅ |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/) | Passerelle | ✅ |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Passerelle | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | Passerelle | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | Passerelle | ✅ |
+| [接口 AI](https://jiekou.ai/) | Passerelle | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | Passerelle | ✅ |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | Plateforme GPU | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | Plateforme GPU | ✅ |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Plateforme GPU | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Passerelle | ✅ |
 
-## ✨ Fonctionnalités
+[→ Voir toutes les intégrations](https://link.langbot.app/en/docs/features)
 
-- 💬 Chat avec LLM / Agent : Prend en charge plusieurs LLM, adapté aux chats de groupe et privés ; Prend en charge les conversations multi-tours, les appels d'outils, les capacités multimodales et de sortie en streaming. Implémentation RAG (base de connaissances) intégrée, et intégration profonde avec [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io) etc. LLMOps platforms.
-- 🤖 Support Multi-plateforme : Actuellement compatible avec QQ, QQ Channel, WeCom, WeChat personnel, Lark, DingTalk, Discord, Telegram, KOOK, Slack, LINE, etc.
-- 🛠️ Haute Stabilité, Riche en Fonctionnalités : Contrôle d'accès natif, limitation de débit, filtrage de mots sensibles, etc. ; Facile à utiliser, prend en charge plusieurs méthodes de déploiement. Prend en charge plusieurs configurations de pipeline, différents bots pour différents scénarios.
-- 🧩 Extension de Plugin, Communauté Active : Système de plugin de haute stabilité, haute sécurité de niveau production; Prend en charge les mécanismes de plugin pilotés par événements, l'extension de composants, etc. ; Intégration du protocole [MCP](https://modelcontextprotocol.io/) d'Anthropic ; Dispose actuellement de centaines de plugins.
-- 😻 Interface Web : Prend en charge la gestion des instances LangBot via le navigateur. Pas besoin d'écrire manuellement les fichiers de configuration.
+---
 
-Pour des spécifications plus détaillées, veuillez consulter la [documentation](https://docs.langbot.app/en/insight/features.html).
+## Pourquoi LangBot ?
 
-Ou visitez l'environnement de démonstration : https://demo.langbot.dev/
-  - Informations de connexion : Email : `demo@langbot.app` Mot de passe : `langbot123456`
-  - Note : Pour la démonstration WebUI uniquement, veuillez ne pas entrer d'informations sensibles dans l'environnement public.
+| Cas d'Usage | Comment LangBot Aide |
+|----------|-------------------|
+| **Support Client** | Déployez des agents IA sur Slack/Discord/Telegram qui répondent aux questions en utilisant votre base de connaissances |
+| **Outils Internes** | Connectez les workflows n8n/Dify à WeCom/DingTalk pour automatiser vos processus métier |
+| **Gestion de Communauté** | Modérez les groupes QQ/Discord avec un filtrage de contenu et des interactions alimentés par l'IA |
+| **Présence Multi-plateforme** | Un seul bot, toutes les plateformes. Gérez tout depuis un tableau de bord unique |
 
-### Plateformes de Messagerie
+---
 
-| Plateforme | Statut | Remarques |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ Personnel | ✅ |  |
-| API Officielle QQ | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| WeChat Personnel | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+## Démo en Ligne
 
-### LLMs
+**Essayez maintenant :** https://demo.langbot.dev/
+- Email : `demo@langbot.app`
+- Mot de passe : `langbot123456`
 
-| LLM | Statut | Remarques |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | Disponible pour tout modèle au format d'interface OpenAI |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | Plateforme de ressources LLM et GPU |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | Plateforme de ressources LLM et GPU |
-| [接口 AI](https://jiekou.ai/) | ✅ | Plateforme d'agrégation LLM |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | Plateforme de ressources LLM et GPU |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | Passerelle LLM (MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | Plateforme LLMOps |
-| [Ollama](https://ollama.com/) | ✅ | Plateforme d'exécution LLM locale |
-| [LMStudio](https://lmstudio.ai/) | ✅ | Plateforme d'exécution LLM locale |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | Passerelle d'interface LLM (MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | Passerelle LLM (MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | Passerelle LLM (MaaS), plateforme LLMOps |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | Passerelle LLM (MaaS), plateforme LLMOps |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | Passerelle LLM (MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | Prend en charge l'accès aux outils via le protocole MCP |
+*Note : Environnement de démonstration public. Ne saisissez pas d'informations sensibles.*
 
-## 🤝 Contribution de la Communauté
+## Conçu pour les agents IA 🤖
 
-Merci aux [contributeurs de code](https://github.com/langbot-app/LangBot/graphs/contributors) suivants et aux autres membres de la communauté pour leurs contributions à LangBot :
+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é
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Communauté Discord](https://discord.gg/wdNEHETs87)
+
+---
+
+## Historique des Stars
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## Contributeurs
+
+Merci à tous les [contributeurs](https://github.com/langbot-app/LangBot/graphs/contributors) qui ont aidé à améliorer LangBot :
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />

README_JP.md

@@ -1,43 +1,74 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
 <a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / [简体中文](README.md) / [繁體中文](README_TW.md) / 日本語 / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+<h3>AIエージェント搭載IMボットを構築するための本番グレードプラットフォーム。</h3>
+<h4>Slack、Discord、Telegram、WeChat などに AI ボットを素早く構築、デバッグ、デプロイ。</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / 日本語 / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
 <a href="https://langbot.app">ホーム</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">デプロイ</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">プラグイン</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">プラグインの提出</a>
+<a href="https://link.langbot.app/ja/docs/features">機能</a> ｜
+<a href="https://link.langbot.app/ja/docs/guide">ドキュメント</a> ｜
+<a href="https://link.langbot.app/ja/docs/api">API</a> ｜
+<a href="https://space.langbot.app">プラグインマーケット</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">ロードマップ</a>
 
 </div>
 
 </p>
 
-LangBot は、エージェント、RAG、MCP などの LLM アプリケーション機能を備えた、オープンソースの LLM ネイティブのインスタントメッセージングロボット開発プラットフォームです。世界中のインスタントメッセージングプラットフォームに適応し、豊富な API インターフェースを提供し、カスタム開発をサポートします。
+---
 
-## 📦 始め方
+## LangBot とは？
 
-#### クイックスタート
+LangBot は、AI搭載のインスタントメッセージングボットを構築するための**オープンソースの本番グレードプラットフォーム**です。大規模言語モデル（LLM）をあらゆるチャットプラットフォームに接続し、会話、タスク実行、既存のワークフローとの統合が可能なインテリジェントエージェントを作成できます。
 
-`uvx` を使用した迅速なデプロイ（[uv](https://docs.astral.sh/uv/getting-started/installation/) が必要です）：
+<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) と深く統合。
+- **ユニバーサルIMプラットフォーム対応** — 単一のコードベースで Discord、Telegram、Slack、LINE、QQ、WeChat、WeCom、Lark、DingTalk、KOOK に対応。
+- **本番環境対応** — アクセス制御、レート制限、センシティブワードフィルタリング、包括的な監視、例外処理を搭載。エンタープライズの信頼に応える品質。
+- **プラグインエコシステム** — 数百のプラグイン、イベント駆動アーキテクチャ、コンポーネント拡張、[MCPプロトコル](https://modelcontextprotocol.io/)対応。
+- **Web管理パネル** — 直感的なブラウザインターフェースからボットの設定、管理、監視が可能。YAML編集は不要。
+- **マルチパイプラインアーキテクチャ** — 異なるシナリオに異なるボットを配置し、包括的な監視と例外処理を実現。
+
+[→ すべての機能について詳しく見る](https://link.langbot.app/ja/docs/features)
+
+📍 実践ガイド: [5分でマルチプラットフォームAIボットをデプロイ](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/)、[DeepSeekをWeChat・Discord・Telegramに接続](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/)、[Dify AgentをDiscord・Telegram・Slackで動かす](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/)、[n8n連携チャットボットを構築](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/)。
+
+---
+
+## クイックスタート
+
+### ☁️ LangBot Cloud（推奨）
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — デプロイ不要、すぐに使えます。
+
+### ワンライン起動
 
 ```bash
 uvx langbot
 ```
 
-http://localhost:5300 にアクセスして使用を開始します。
+> [uv](https://docs.astral.sh/uv/getting-started/installation/) が必要です。http://localhost:5300 にアクセスして完了。
 
-#### Docker Compose デプロイ
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,99 +76,115 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-http://localhost:5300 にアクセスして使用を開始します。
-
-詳細なドキュメントは[Dockerデプロイ](https://docs.langbot.app/en/deploy/langbot/docker.html)を参照してください。
-
-#### Panelでのワンクリックデプロイ
-
-LangBotはBTPanelにリストされています。BTPanelをインストールしている場合は、[ドキュメント](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html)を使用して使用できます。
-
-#### Zeaburクラウドデプロイ
-
-コミュニティが提供するZeaburテンプレート。
+### ワンクリッククラウドデプロイ
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Railwayクラウドデプロイ
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### その他のデプロイ方法
+**その他:** [Docker](https://link.langbot.app/en/docs/docker) · [手動デプロイ](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-リリースバージョンを直接使用して実行します。[手動デプロイ](https://docs.langbot.app/en/deploy/langbot/manual.html)のドキュメントを参照してください。
+---
 
-#### Kubernetes デプロイ
-
-[Kubernetes デプロイ](./docker/README_K8S.md) ドキュメントを参照してください。
-
-## 😎 最新情報を入手
-
-リポジトリの右上にある Star と Watch ボタンをクリックして、最新の更新を取得してください。
-
-![star gif](https://docs.langbot.app/star.gif)
-
-## ✨ 機能
-
-- 💬 LLM / エージェントとのチャット: 複数のLLMをサポートし、グループチャットとプライベートチャットに対応。マルチラウンドの会話、ツールの呼び出し、マルチモーダル、ストリーミング出力機能をサポート、RAG（知識ベース）を組み込み、[Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io) などの LLMOps プラットフォームと深く統合。
-- 🤖 多プラットフォーム対応: 現在、QQ、QQ チャンネル、WeChat、個人 WeChat、Lark、DingTalk、Discord、Telegram、KOOK、Slack、LINE など、複数のプラットフォームをサポートしています。
-- 🛠️ 高い安定性、豊富な機能: ネイティブのアクセス制御、レート制限、敏感な単語のフィルタリングなどのメカニズムをサポート。使いやすく、複数のデプロイ方法をサポート。複数のパイプライン設定をサポートし、異なるボットを異なる用途に使用できます。
-- 🧩 プラグイン拡張、活発なコミュニティ: 高い安定性、高いセキュリティの生産レベルのプラグインシステム；イベント駆動、コンポーネント拡張などのプラグインメカニズムをサポート。適配 Anthropic [MCP プロトコル](https://modelcontextprotocol.io/)；豊富なエコシステム、現在数百のプラグインが存在。
-- 😻 Web UI: ブラウザを通じてLangBotインスタンスを管理することをサポート。
-
-詳細な仕様については、[ドキュメント](https://docs.langbot.app/en/insight/features.html)を参照してください。
-
-または、デモ環境にアクセスしてください: https://demo.langbot.dev/
-  - ログイン情報: メール: `demo@langbot.app` パスワード: `langbot123456`
-  - 注意: WebUI のデモンストレーションのみの場合、公開環境では機密情報を入力しないでください。
-
-### メッセージプラットフォーム
+## 対応プラットフォーム
 
 | プラットフォーム | ステータス | 備考 |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| 個人QQ | ✅ |  |
-| QQ公式API | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| 個人WeChat | ✅ | |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
-| KOOK | ✅ |  |
+|----------|--------|-------|
+| Discord | ✅ | 公式 |
+| Telegram | ✅ | 公式 |
+| Slack | ✅ | 公式 |
+| LINE | ✅ | 公式 |
+| QQ | ✅ | 個人・公式API（チャンネル・DM・グループ） |
+| WeCom | ✅ | 企業WeChat、外部CS、AIボット |
+| WeChat | ✅ | 個人・公式アカウント |
+| Lark | ✅ | 公式 |
+| DingTalk | ✅ | 公式 |
+| KOOK | ✅ | 公式 |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix、Satori |
+| Matrix | ✅ | Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip など複数のブリッジ先プラットフォームに対応 |
 
-### LLMs
+---
 
-| LLM | ステータス | 備考 |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | 任意のOpenAIインターフェース形式モデルに対応 |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | 大模型とGPUリソースプラットフォーム |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | 大模型とGPUリソースプラットフォーム |
-| [接口 AI](https://jiekou.ai/) | ✅ | LLMゲートウェイ(MaaS) |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | LLMとGPUリソースプラットフォーム |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | LLMゲートウェイ(MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | LLMOpsプラットフォーム |
-| [Ollama](https://ollama.com/) | ✅ | ローカルLLM実行プラットフォーム |
-| [LMStudio](https://lmstudio.ai/) | ✅ | ローカルLLM実行プラットフォーム |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | LLMインターフェースゲートウェイ(MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | LLMゲートウェイ(MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | LLMゲートウェイ(MaaS), LLMOpsプラットフォーム |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | LLMゲートウェイ(MaaS), LLMOpsプラットフォーム |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | LLMゲートウェイ(MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | MCPプロトコルをサポート |
+## 対応LLMと統合
 
-## 🤝 コミュニティ貢献
+| プロバイダー | タイプ | ステータス |
+|----------|------|--------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | ローカルLLM | ✅ |
+| [LM Studio](https://lmstudio.ai/) | ローカルLLM | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | プロトコル | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | ゲートウェイ | ✅ |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ゲートウェイ | ✅ |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ゲートウェイ | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ゲートウェイ | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | ゲートウェイ | ✅ |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | GPUプラットフォーム | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | GPUプラットフォーム | ✅ |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPUプラットフォーム | ✅ |
+| [接口 AI](https://jiekou.ai/) | ゲートウェイ | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | ゲートウェイ | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | ゲートウェイ | ✅ |
 
-LangBot への貢献に対して、以下の [コード貢献者](https://github.com/langbot-app/LangBot/graphs/contributors) とコミュニティの他のメンバーに感謝します。
+[→ すべての統合を表示](https://link.langbot.app/en/docs/features)
+
+---
+
+## なぜ LangBot？
+
+| ユースケース | LangBot の活用方法 |
+|----------|-------------------|
+| **カスタマーサポート** | ナレッジベースを活用して質問に回答するAIエージェントをSlack/Discord/Telegramにデプロイ |
+| **社内ツール** | n8n/Difyのワークフローを WeCom/DingTalk に接続し、業務プロセスを自動化 |
+| **コミュニティ管理** | AI搭載のコンテンツフィルタリングとインタラクションでQQ/Discordグループをモデレーション |
+| **マルチプラットフォーム展開** | 1つのボットで全プラットフォームに対応。単一のダッシュボードから管理 |
+
+---
+
+## ライブデモ
+
+**今すぐ試す:** https://demo.langbot.dev/
+- メール: `demo@langbot.app`
+- パスワード: `langbot123456`
+
+*注意: 公開デモ環境です。機密情報を入力しないでください。*
+
+## 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 マーケットを検索・確認できます。
+
+---
+
+## コミュニティ
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Discord コミュニティ](https://discord.gg/wdNEHETs87)
+
+---
+
+## Star 推移
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## コントリビューター
+
+LangBot をより良くするために貢献してくださったすべての[コントリビューター](https://github.com/langbot-app/LangBot/graphs/contributors)に感謝します:
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />

README_KO.md

@@ -1,43 +1,74 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
 <a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / [简体中文](README.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / 한국어 / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+<h3>AI 에이전트 IM 봇 구축을 위한 프로덕션 등급 플랫폼.</h3>
+<h4>Slack, Discord, Telegram, WeChat 등에 AI 봇을 빠르게 구축, 디버그 및 배포.</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / 한국어 / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
 <a href="https://langbot.app">홈</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">배포</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">플러그인</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">플러그인 제출</a>
+<a href="https://link.langbot.app/en/docs/features">기능</a> ｜
+<a href="https://link.langbot.app/en/docs/guide">문서</a> ｜
+<a href="https://link.langbot.app/en/docs/api">API</a> ｜
+<a href="https://space.langbot.app">플러그인 마켓</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">로드맵</a>
 
 </div>
 
 </p>
 
-LangBot은 오픈 소스 LLM 네이티브 인스턴트 메시징 로봇 개발 플랫폼으로, Agent, RAG, MCP 등 다양한 LLM 애플리케이션 기능을 갖춘 즉시 사용 가능한 IM 로봇 개발 경험을 제공하며, 글로벌 인스턴트 메시징 플랫폼에 적응하고 풍부한 API 인터페이스를 제공하여 맞춤형 개발을 지원합니다.
+---
 
-## 📦 시작하기
+## LangBot이란?
 
-#### 빠른 시작
+LangBot은 AI 기반 인스턴트 메시징 봇을 구축하기 위한 **오픈소스 프로덕션 등급 플랫폼**입니다. 대규모 언어 모델(LLM)을 모든 채팅 플랫폼에 연결하여 대화, 작업 실행, 기존 워크플로우와의 통합이 가능한 지능형 에이전트를 만들 수 있습니다.
 
-`uvx`를 사용하여 한 명령으로 시작하세요 ([uv](https://docs.astral.sh/uv/getting-started/installation/) 설치 필요):
+<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) 심층 통합.
+- **유니버설 IM 플랫폼 지원** — 단일 코드베이스로 Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, KOOK 지원.
+- **프로덕션 레디** — 접근 제어, 속도 제한, 민감어 필터링, 종합 모니터링 및 예외 처리. 기업 환경에서 검증됨.
+- **플러그인 생태계** — 수백 개의 플러그인, 이벤트 기반 아키텍처, 컴포넌트 확장, [MCP 프로토콜](https://modelcontextprotocol.io/) 지원.
+- **웹 관리 패널** — 직관적인 브라우저 인터페이스로 봇을 구성, 관리 및 모니터링. YAML 편집 불필요.
+- **멀티 파이프라인 아키텍처** — 다양한 시나리오에 맞는 다양한 봇 구성, 종합 모니터링 및 예외 처리.
+
+[→ 모든 기능 자세히 보기](https://link.langbot.app/en/docs/features)
+
+📍 실전 가이드: [5분 만에 멀티 플랫폼 AI 봇 배포하기](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [DeepSeek를 WeChat, Discord, Telegram에 연결하기](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [Dify Agent를 Discord, Telegram, Slack에서 실행하기](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/), [n8n 기반 챗봇 만들기](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
+---
+
+## 빠른 시작
+
+### ☁️ LangBot Cloud (추천)
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — 배포 없이 바로 사용.
+
+### 원라인 실행
 
 ```bash
 uvx langbot
 ```
 
-http://localhost:5300을 방문하여 사용을 시작하세요.
+> [uv](https://docs.astral.sh/uv/getting-started/installation/) 설치 필요. http://localhost:5300 방문 — 완료.
 
-#### Docker Compose 배포
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,99 +76,115 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-http://localhost:5300을 방문하여 사용을 시작하세요.
-
-자세한 문서는 [Docker 배포](https://docs.langbot.app/en/deploy/langbot/docker.html)를 참조하세요.
-
-#### BTPanel 원클릭 배포
-
-LangBot은 BTPanel에 등록되어 있습니다. BTPanel을 설치한 경우 [문서](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html)를 사용하여 사용할 수 있습니다.
-
-#### Zeabur 클라우드 배포
-
-커뮤니티에서 제공하는 Zeabur 템플릿입니다.
+### 원클릭 클라우드 배포
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Railway 클라우드 배포
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### 기타 배포 방법
+**더 많은 옵션:** [Docker](https://link.langbot.app/en/docs/docker) · [수동 배포](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-릴리스 버전을 직접 사용하여 실행하려면 [수동 배포](https://docs.langbot.app/en/deploy/langbot/manual.html) 문서를 참조하세요.
+---
 
-#### Kubernetes 배포
-
-[Kubernetes 배포](./docker/README_K8S.md) 문서를 참조하세요.
-
-## 😎 최신 정보 받기
-
-리포지토리 오른쪽 상단의 Star 및 Watch 버튼을 클릭하여 최신 업데이트를 받으세요.
-
-![star gif](https://docs.langbot.app/star.gif)
-
-## ✨ 기능
-
-- 💬 LLM / Agent와 채팅: 여러 LLM을 지원하며 그룹 채팅 및 개인 채팅에 적응; 멀티 라운드 대화, 도구 호출, 멀티모달, 스트리밍 출력 기능을 지원합니다. 내장된 RAG(지식 베이스) 구현 및 [Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io) 등의 LLMOps 플랫폼과 깊이 통합됩니다.
-- 🤖 다중 플랫폼 지원: 현재 QQ, QQ Channel, WeCom, 개인 WeChat, Lark, DingTalk, Discord, Telegram, KOOK, Slack, LINE 등을 지원합니다.
-- 🛠️ 높은 안정성, 풍부한 기능: 네이티브 액세스 제어, 속도 제한, 민감한 단어 필터링 등의 메커니즘; 사용하기 쉽고 여러 배포 방법을 지원합니다. 여러 파이프라인 구성을 지원하며 다양한 시나리오에 대해 다른 봇을 사용할 수 있습니다.
-- 🧩 플러그인 확장, 활발한 커뮤니티: 고안정성, 고보안 생산 수준의 플러그인 시스템; 이벤트 기반, 컴포넌트 확장 등의 플러그인 메커니즘을 지원; Anthropic [MCP 프로토콜](https://modelcontextprotocol.io/) 통합; 현재 수백 개의 플러그인이 있습니다.
-- 😻 웹 UI: 브라우저를 통해 LangBot 인스턴스 관리를 지원합니다. 구성 파일을 수동으로 작성할 필요가 없습니다.
-
-더 자세한 사양은 [문서](https://docs.langbot.app/en/insight/features.html)를 참조하세요.
-
-또는 데모 환경을 방문하세요: https://demo.langbot.dev/
-  - 로그인 정보: 이메일: `demo@langbot.app` 비밀번호: `langbot123456`
-  - 참고: WebUI 데모 전용이므로 공개 환경에서는 민감한 정보를 입력하지 마세요.
-
-### 메시징 플랫폼
+## 지원 플랫폼
 
 | 플랫폼 | 상태 | 비고 |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| 개인 QQ | ✅ |  |
-| QQ 공식 API | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| 개인 WeChat | ✅ |  |
-| KOOK | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
+|--------|------|------|
+| Discord | ✅ | 공식 |
+| Telegram | ✅ | 공식 |
+| Slack | ✅ | 공식 |
+| LINE | ✅ | 공식 |
+| QQ | ✅ | 개인 및 공식 API (채널, DM, 그룹) |
+| WeCom | ✅ | 기업 WeChat, 외부 CS, AI Bot |
+| WeChat | ✅ | 개인 및 공식 계정 |
+| Lark | ✅ | 공식 |
+| DingTalk | ✅ | 공식 |
+| KOOK | ✅ | 공식 |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip 등 여러 브리지 플랫폼 지원 |
 
-### LLMs
+---
 
-| LLM | 상태 | 비고 |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | 모든 OpenAI 인터페이스 형식 모델에 사용 가능 |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | LLM 및 GPU 리소스 플랫폼 |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | LLM 및 GPU 리소스 플랫폼 |
-| [接口 AI](https://jiekou.ai/) | ✅ | LLM 집계 플랫폼 |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | LLM 및 GPU 리소스 플랫폼 |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | LLM 게이트웨이(MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | LLMOps 플랫폼 |
-| [Ollama](https://ollama.com/) | ✅ | 로컬 LLM 실행 플랫폼 |
-| [LMStudio](https://lmstudio.ai/) | ✅ | 로컬 LLM 실행 플랫폼 |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | LLM 인터페이스 게이트웨이(MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | LLM 게이트웨이(MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | LLM 게이트웨이(MaaS), LLMOps 플랫폼 |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | LLM 게이트웨이(MaaS), LLMOps 플랫폼 |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | LLM 게이트웨이(MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | MCP 프로토콜을 통한 도구 액세스 지원 |
+## 지원 LLM 및 통합
 
-## 🤝 커뮤니티 기여
+| 제공자 | 유형 | 상태 |
+|--------|------|------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | 로컬 LLM | ✅ |
+| [LM Studio](https://lmstudio.ai/) | 로컬 LLM | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | 프로토콜 | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | 게이트웨이 | ✅ |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/) | 게이트웨이 | ✅ |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | 게이트웨이 | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | 게이트웨이 | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | 게이트웨이 | ✅ |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | GPU 플랫폼 | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | GPU 플랫폼 | ✅ |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPU 플랫폼 | ✅ |
+| [接口 AI](https://jiekou.ai/) | 게이트웨이 | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | 게이트웨이 | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | 게이트웨이 | ✅ |
 
-다음 [코드 기여자](https://github.com/langbot-app/LangBot/graphs/contributors) 및 커뮤니티의 다른 구성원들의 LangBot 기여에 감사드립니다:
+[→ 모든 통합 보기](https://link.langbot.app/en/docs/features)
+
+---
+
+## 왜 LangBot인가?
+
+| 사용 사례 | LangBot 활용 방법 |
+|-----------|-------------------|
+| **고객 지원** | 지식 베이스를 활용하여 질문에 답변하는 AI 에이전트를 Slack/Discord/Telegram에 배포 |
+| **내부 도구** | n8n/Dify 워크플로우를 WeCom/DingTalk에 연결하여 비즈니스 프로세스 자동화 |
+| **커뮤니티 관리** | AI 기반 콘텐츠 필터링 및 상호작용으로 QQ/Discord 그룹 관리 |
+| **멀티 플랫폼** | 하나의 봇으로 모든 플랫폼 지원. 단일 대시보드에서 관리 |
+
+---
+
+## 라이브 데모
+
+**지금 체험:** https://demo.langbot.dev/
+- 이메일: `demo@langbot.app`
+- 비밀번호: `langbot123456`
+
+*참고: 공개 데모 환경입니다. 민감한 정보를 입력하지 마세요.*
+
+## 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 마켓플레이스를 검색하고 조회할 수 있습니다.
+
+---
+
+## 커뮤니티
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Discord 커뮤니티](https://discord.gg/wdNEHETs87)
+
+---
+
+## Star 추이
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## 기여자
+
+LangBot을 더 나은 프로젝트로 만들어 주신 모든 [기여자](https://github.com/langbot-app/LangBot/graphs/contributors)분들께 감사드립니다:
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />

README_RU.md

@@ -1,43 +1,74 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
 <a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / [简体中文](README.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / Русский / [Tiếng Việt](README_VI.md)
+<h3>Платформа производственного уровня для создания агентных IM-ботов.</h3>
+<h4>Быстро создавайте, отлаживайте и развертывайте ИИ-ботов в Slack, Discord, Telegram, WeChat и других платформах.</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / Русский / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
 <a href="https://langbot.app">Главная</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">Развертывание</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">Плагин</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">Отправить плагин</a>
+<a href="https://link.langbot.app/en/docs/features">Возможности</a> ｜
+<a href="https://link.langbot.app/en/docs/guide">Документация</a> ｜
+<a href="https://link.langbot.app/en/docs/api">API</a> ｜
+<a href="https://space.langbot.app">Магазин плагинов</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">Дорожная карта</a>
 
 </div>
 
 </p>
 
-LangBot — это платформа разработки ботов для мгновенных сообщений на основе LLM с открытым исходным кодом, целью которой является предоставление готового к использованию опыта разработки ботов для IM, с функциями приложений LLM, такими как Agent, RAG, MCP, адаптацией к глобальным платформам мгновенных сообщений и предоставлением богатых API-интерфейсов, поддерживающих пользовательскую разработку.
+---
 
-## 📦 Начало работы
+## Что такое LangBot?
 
-#### Быстрый старт
+LangBot — это **платформа с открытым исходным кодом производственного уровня** для создания ИИ-ботов в мессенджерах. Она связывает большие языковые модели (LLM) с любой чат-платформой, позволяя создавать интеллектуальных агентов, которые могут вести диалоги, выполнять задачи и интегрироваться с вашими существующими рабочими процессами.
 
-Используйте `uvx` для запуска одной командой (требуется установка [uv](https://docs.astral.sh/uv/getting-started/installation/)):
+<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).
+- **Универсальная поддержка IM-платформ** — Единая кодовая база для Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, KOOK.
+- **Готовность к продакшену** — Контроль доступа, ограничение скорости, фильтрация чувствительных слов, комплексный мониторинг и обработка исключений. Проверено в корпоративной среде.
+- **Экосистема плагинов** — Сотни плагинов, событийно-ориентированная архитектура, расширения компонентов и поддержка [протокола MCP](https://modelcontextprotocol.io/).
+- **Веб-панель управления** — Настраивайте, управляйте и мониторьте ваших ботов через интуитивный браузерный интерфейс. Ручное редактирование YAML не требуется.
+- **Мультиконвейерная архитектура** — Разные боты для разных сценариев с комплексным мониторингом и обработкой исключений.
+
+[→ Подробнее обо всех возможностях](https://link.langbot.app/en/docs/features)
+
+📍 Практические руководства: [развернуть мультиплатформенного ИИ-бота за 5 минут](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [подключить DeepSeek к WeChat, Discord и Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [запустить Dify Agent в Discord, Telegram и Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) и [создать чат-бота на n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
+---
+
+## Быстрый старт
+
+### ☁️ LangBot Cloud (Рекомендуется)
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — Без развёртывания, готово к использованию.
+
+### Запуск одной командой
 
 ```bash
 uvx langbot
 ```
 
-Посетите http://localhost:5300, чтобы начать использование.
+> Требуется [uv](https://docs.astral.sh/uv/getting-started/installation/). Откройте http://localhost:5300 — готово.
 
-#### Развертывание с Docker Compose
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,99 +76,115 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-Посетите http://localhost:5300, чтобы начать использование.
-
-Подробная документация [Развертывание Docker](https://docs.langbot.app/en/deploy/langbot/docker.html).
-
-#### Развертывание одним кликом на BTPanel
-
-LangBot добавлен в BTPanel. Если у вас установлен BTPanel, вы можете использовать [документацию](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html) для его использования.
-
-#### Облачное развертывание Zeabur
-
-Шаблон Zeabur, предоставленный сообществом.
+### Облачное развертывание одним кликом
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Облачное развертывание Railway
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### Другие методы развертывания
+**Другие варианты:** [Docker](https://link.langbot.app/en/docs/docker) · [Ручная установка](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-Используйте выпущенную версию напрямую для запуска, см. документацию [Ручное развертывание](https://docs.langbot.app/en/deploy/langbot/manual.html).
+---
 
-#### Развертывание Kubernetes
-
-См. документацию [Развертывание Kubernetes](./docker/README_K8S.md).
-
-## 😎 Оставайтесь в курсе
-
-Нажмите кнопки Star и Watch в правом верхнем углу репозитория, чтобы получать последние обновления.
-
-![star gif](https://docs.langbot.app/star.gif)
-
-## ✨ Функции
-
-- 💬 Чат с LLM / Agent: Поддержка нескольких LLM, адаптация к групповым и личным чатам; Поддержка многораундовых разговоров, вызовов инструментов, мультимодальных возможностей и потоковой передачи. Встроенная реализация RAG (база знаний) и глубокая интеграция с [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io) 등의 LLMOps 플랫포트폼과 깊이 통합됩니다.
-- 🤖 Многоплатформенная поддержка: В настоящее время поддерживает QQ, QQ Channel, WeCom, личный WeChat, Lark, DingTalk, Discord, Telegram, KOOK, Slack, LINE и т.д.
-- 🛠️ Высокая стабильность, богатство функций: Нативный контроль доступа, ограничение скорости, фильтрация чувствительных слов и т.д.; Простота в использовании, поддержка нескольких методов развертывания. Поддержка нескольких конфигураций конвейера, разные боты для разных сценариев.
-- 🧩 Расширение плагинов, активное сообщество: Высокая стабильность, высокая безопасность уровня производства; Поддержка механизмов плагинов, управляемых событиями, расширения компонентов и т.д.; Интеграция протокола [MCP](https://modelcontextprotocol.io/) от Anthropic; В настоящее время сотни плагинов.
-- 😻 Веб-интерфейс: Поддержка управления экземплярами LangBot через браузер. Нет необходимости вручную писать конфигурационные файлы.
-
-Для более подробных спецификаций обратитесь к [документации](https://docs.langbot.app/en/insight/features.html).
-
-Или посетите демонстрационную среду: https://demo.langbot.dev/
-  - Информация для входа: Email: `demo@langbot.app` Пароль: `langbot123456`
-  - Примечание: Только для демонстрации WebUI, пожалуйста, не вводите конфиденциальную информацию в общедоступной среде.
-
-### Платформы обмена сообщениями
+## Поддерживаемые платформы
 
 | Платформа | Статус | Примечания |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| Личный QQ | ✅ |  |
-| Официальный API QQ | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| Личный WeChat | ✅ |  |
-| KOOK | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
+|-----------|--------|------------|
+| Discord | ✅ | Официальный |
+| Telegram | ✅ | Официальный |
+| Slack | ✅ | Официальный |
+| LINE | ✅ | Официальный |
+| QQ | ✅ | Личный и официальный API (Канал, ЛС, Группа) |
+| WeCom | ✅ | Корпоративный WeChat, внешний CS, AI-бот |
+| WeChat | ✅ | Личный и официальный аккаунт |
+| Lark | ✅ | Официальный |
+| DingTalk | ✅ | Официальный |
+| KOOK | ✅ | Официальный |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Поддерживает несколько платформ через мосты, включая Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip и другие |
 
-### LLMs
+---
 
-| LLM | Статус | Примечания |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | Доступна для любой модели формата интерфейса OpenAI |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | Платформа ресурсов LLM и GPU |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | Платформа ресурсов LLM и GPU |
-| [接口 AI](https://jiekou.ai/) | ✅ | Платформа агрегации LLM |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | Платформа ресурсов LLM и GPU |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | Шлюз LLM (MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | Платформа LLMOps |
-| [Ollama](https://ollama.com/) | ✅ | Платформа локального запуска LLM |
-| [LMStudio](https://lmstudio.ai/) | ✅ | Платформа локального запуска LLM |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | Шлюз интерфейса LLM (MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | Шлюз LLM (MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | Шлюз LLM (MaaS), платформа LLMOps |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | Шлюз LLM (MaaS), платформа LLMOps |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | Шлюз LLM (MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | Поддержка доступа к инструментам через протокол MCP |
+## Поддерживаемые LLM и интеграции
 
-## 🤝 Вклад сообщества
+| Провайдер | Тип | Статус |
+|-----------|-----|--------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | Локальный LLM | ✅ |
+| [LM Studio](https://lmstudio.ai/) | Локальный LLM | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | Протокол | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | Шлюз | ✅ |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/) | Шлюз | ✅ |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Шлюз | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | Шлюз | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | Шлюз | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | Шлюз | ✅ |
+| [接口 AI](https://jiekou.ai/) | Шлюз | ✅ |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | Платформа GPU | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | Платформа GPU | ✅ |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Платформа GPU | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Шлюз | ✅ |
 
-Спасибо следующим [контрибьюторам кода](https://github.com/langbot-app/LangBot/graphs/contributors) и другим членам сообщества за их вклад в LangBot:
+[→ Смотреть все интеграции](https://link.langbot.app/en/docs/features)
+
+---
+
+## Почему LangBot?
+
+| Сценарий использования | Как помогает LangBot |
+|------------------------|----------------------|
+| **Поддержка клиентов** | Разверните ИИ-агентов в Slack/Discord/Telegram, которые отвечают на вопросы, используя вашу базу знаний |
+| **Внутренние инструменты** | Подключите рабочие процессы n8n/Dify к WeCom/DingTalk для автоматизации бизнес-процессов |
+| **Управление сообществом** | Модерируйте группы QQ/Discord с помощью ИИ-фильтрации контента и взаимодействия |
+| **Мультиплатформенное присутствие** | Один бот — все платформы. Управляйте из единой панели |
+
+---
+
+## Демо
+
+**Попробуйте прямо сейчас:** https://demo.langbot.dev/
+- Email: `demo@langbot.app`
+- Пароль: `langbot123456`
+
+*Примечание: Публичная демо-среда. Не вводите конфиденциальную информацию.*
+
+## Создано для ИИ-агентов 🤖
+
+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.
+
+---
+
+## Сообщество
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Сообщество Discord](https://discord.gg/wdNEHETs87)
+
+---
+
+## История Stars
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## Участники
+
+Спасибо всем [участникам](https://github.com/langbot-app/LangBot/graphs/contributors), которые помогли сделать LangBot лучше:
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />

README_TW.md

@@ -1,43 +1,76 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_zh.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
-<div align="center"><a href="https://hellogithub.com/repository/langbot-app/LangBot" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=5ce8ae2aa4f74316bf393b57b952433c&claim_uid=gtmc6YWjMZkT21R" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+<div align="center">
 
-[English](README_EN.md) / [简体中文](README.md) / 繁體中文 / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
+<a href="https://hellogithub.com/repository/langbot-app/LangBot" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=5ce8ae2aa4f74316bf393b57b952433c&claim_uid=gtmc6YWjMZkT21R" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+
+<h3>生產級 AI 即時通訊機器人開發平台。</h3>
+<h4>快速建構、除錯和部署 AI 機器人到微信、QQ、飛書、Slack、Discord、Telegram 等平台。</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / 繁體中文 / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / [Tiếng Việt](README_VI.md)
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![QQ Group](https://img.shields.io/badge/%E7%A4%BE%E5%8C%BAQQ%E7%BE%A4-966235608-blue)](https://qm.qq.com/q/JLi38whHum)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 [![star](https://gitcode.com/RockChinQ/LangBot/star/badge.svg)](https://gitcode.com/RockChinQ/LangBot)
 
-<a href="https://langbot.app">主頁</a> ｜
-<a href="https://docs.langbot.app/zh/insight/guide.html">部署文件</a> ｜
-<a href="https://docs.langbot.app/zh/plugin/plugin-intro.html">外掛介紹</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">提交外掛</a>
+<a href="https://langbot.app">官網</a> ｜
+<a href="https://link.langbot.app/zh/docs/features">特性</a> ｜
+<a href="https://link.langbot.app/zh/docs/guide">文件</a> ｜
+<a href="https://link.langbot.app/zh/docs/api">API</a> ｜
+<a href="https://space.langbot.app">外掛市場</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">路線圖</a>
 
 </div>
 
 </p>
 
-LangBot 是一個開源的大語言模型原生即時通訊機器人開發平台，旨在提供開箱即用的 IM 機器人開發體驗，具有 Agent、RAG、MCP 等多種 LLM 應用功能，適配全球主流即時通訊平台，並提供豐富的 API 介面，支援自定義開發。
+---
 
-## 📦 開始使用
+## 什麼是 LangBot？
 
-#### 快速部署
+LangBot 是一個**開源的生產級平台**，用於建構 AI 驅動的即時通訊機器人。它將大語言模型（LLM）連接到各種聊天平台，幫助你創建能夠對話、執行任務、並整合到現有工作流程中的智能 Agent。
 
-使用 `uvx` 一鍵啟動（需要先安裝 [uv](https://docs.astral.sh/uv/getting-started/installation/) ）：
+<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 平台。
+- **全平台支援** — 一套程式碼，覆蓋 QQ、微信、企業微信、飛書、釘釘、Discord、Telegram、Slack、LINE、KOOK 等平台。
+- **生產就緒** — 存取控制、限速、敏感詞過濾、全面監控與異常處理，已被多家企業採用。
+- **外掛生態** — 數百個外掛，事件驅動架構，組件擴展，適配 [MCP 協議](https://modelcontextprotocol.io/)。
+- **Web 管理面板** — 透過瀏覽器直觀地配置、管理和監控機器人，無需手動編輯設定檔。
+- **多流水線架構** — 不同機器人用於不同場景，具備全面的監控和異常處理能力。
+
+[→ 了解更多功能特性](https://link.langbot.app/zh/docs/features)
+
+📍 實踐指南：[5 分鐘部署多平台 AI 機器人](https://blog.langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[將 DeepSeek 接入微信、企業微信與 Discord](https://blog.langbot.app/zh/blog/connect-deepseek-to-wechat/)、[讓 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://blog.langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 建構多平台 AI 聊天機器人](https://blog.langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。
+
+---
+
+## 快速開始
+
+### ☁️ LangBot Cloud（推薦）
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — 免部署，開箱即用。
+
+### 一鍵啟動
 
 ```bash
 uvx langbot
 ```
 
-訪問 http://localhost:5300 即可開始使用。
+> 需要安裝 [uv](https://docs.astral.sh/uv/getting-started/installation/)。訪問 http://localhost:5300 即可使用。
 
-#### Docker Compose 部署
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,100 +78,66 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-訪問 http://localhost:5300 即可開始使用。
-
-詳細文件[Docker 部署](https://docs.langbot.app/zh/deploy/langbot/docker.html)。
-
-#### 寶塔面板部署
-
-已上架寶塔面板，若您已安裝寶塔面板，可以根據[文件](https://docs.langbot.app/zh/deploy/langbot/one-click/bt.html)使用。
-
-#### Zeabur 雲端部署
-
-社群貢獻的 Zeabur 模板。
+### 一鍵雲端部署
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/zh-CN/templates/ZKTBDH)
-
-#### Railway 雲端部署
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### 手動部署
+**更多方式：** [Docker](https://link.langbot.app/zh/docs/docker) · [手動部署](https://link.langbot.app/zh/docs/manual-deploy) · [寶塔面板](https://link.langbot.app/zh/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/zh/deploy/langbot/kubernetes)
 
-直接使用發行版運行，查看文件[手動部署](https://docs.langbot.app/zh/deploy/langbot/manual.html)。
+---
 
-#### Kubernetes 部署
-
-參考 [Kubernetes 部署](./docker/README_K8S.md) 文件。
-
-## 😎 保持更新
-
-點擊倉庫右上角 Star 和 Watch 按鈕，獲取最新動態。
-
-![star gif](https://docs.langbot.app/star.gif)
-
-## ✨ 特性
-
-- 💬 大模型對話、Agent：支援多種大模型，適配群聊和私聊；具有多輪對話、工具調用、多模態、流式輸出能力，自帶 RAG（知識庫）實現，並深度適配 [Dify](https://dify.ai)、[Coze](https://coze.com)、[n8n](https://n8n.io) 等 LLMOps 平台。
-- 🤖 多平台支援：目前支援 QQ、QQ頻道、企業微信、個人微信、飛書、Discord、Telegram、KOOK、Slack、LINE 等平台。
-- 🛠️ 高穩定性、功能完備：原生支援訪問控制、限速、敏感詞過濾等機制；配置簡單，支援多種部署方式。支援多流水線配置，不同機器人用於不同應用場景。
-- 🧩 外掛擴展、活躍社群：高穩定性、高安全性的生產級外掛系統；支援事件驅動、組件擴展等外掛機制；適配 Anthropic [MCP 協議](https://modelcontextprotocol.io/)；目前已有數百個外掛。
-- 😻 Web 管理面板：支援通過瀏覽器管理 LangBot 實例，不再需要手動編寫配置文件。
-
-詳細規格特性請訪問[文件](https://docs.langbot.app/zh/insight/features.html)。
-
-或訪問 demo 環境：https://demo.langbot.dev/  
-  - 登入資訊：郵箱：`demo@langbot.app` 密碼：`langbot123456`
-  - 注意：僅展示 WebUI 效果，公開環境，請不要在其中填入您的任何敏感資訊。
-
-### 訊息平台
+## 支援的平台
 
 | 平台 | 狀態 | 備註 |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ 個人號 | ✅ | QQ 個人號私聊、群聊 |
-| QQ 官方機器人 | ✅ | QQ 官方機器人，支援頻道、私聊、群聊 |
-| 微信 | ✅ |  |
-| 企微對外客服 | ✅ |  |
-| 企微智能機器人 | ✅ |  |
-| 微信公眾號 | ✅ |  |
-| KOOK | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
+|------|------|------|
+| Discord | ✅ | 官方 |
+| Telegram | ✅ | 官方 |
+| Slack | ✅ | 官方 |
+| LINE | ✅ | 官方 |
+| QQ | ✅ | 個人號、官方機器人（頻道、私聊、群聊） |
+| 企業微信 | ✅ | 應用訊息、對外客服、智能機器人 |
+| 微信 | ✅ | 個人微信、微信公眾號 |
+| 飛書 | ✅ | 官方 |
+| 釘釘 | ✅ | 官方 |
+| KOOK | ✅ | 官方 |
+| Satori | ✅ |  |
+| Email | ✅ | 只 Matrix、Satori |
+| Matrix | ✅ | 支援多種橋接平台，如 Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip 等 |
 
-### 大模型能力
+---
 
-| 模型 | 狀態 | 備註 |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | 可接入任何 OpenAI 介面格式模型 |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [智譜AI](https://open.bigmodel.cn/) | ✅ |  |
-| [勝算雲](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | 大模型和 GPU 資源平台 |
-| [優雲智算](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | 大模型和 GPU 資源平台 |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | 大模型和 GPU 資源平台 |
-| [接口 AI](https://jiekou.ai/) | ✅ | 大模型聚合平台，專注全球大模型接入 |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | 大模型聚合平台 |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | LLMOps 平台 |
-| [Ollama](https://ollama.com/) | ✅ | 本地大模型運行平台 |
-| [LMStudio](https://lmstudio.ai/) | ✅ | 本地大模型運行平台 |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | 大模型介面聚合平台 |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | 大模型聚合平台 |
-| [阿里雲百煉](https://bailian.console.aliyun.com/) | ✅ | 大模型聚合平台, LLMOps 平台 |
-| [火山方舟](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | 大模型聚合平台, LLMOps 平台 |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | 大模型聚合平台 |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | 支援通過 MCP 協議獲取工具 |
+## 支援的大模型與整合
 
-### TTS
+| 提供商 | 類型 | 狀態 |
+|--------|------|------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [智譜AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | 本地 LLM | ✅ |
+| [LM Studio](https://lmstudio.ai/) | 本地 LLM | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | 協議 | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | 聚合平台 | ✅ |
+| [阿里雲百煉](https://bailian.console.aliyun.com/) | 聚合平台 | ✅ |
+| [火山方舟](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | 聚合平台 | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | 聚合平台 | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | 聚合平台 | ✅ |
+| [勝算雲](https://www.shengsuanyun.com/?from=CH_KYIPP758) | GPU 平台 | ✅ |
+| [優雲智算](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | GPU 平台 | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | GPU 平台 | ✅ |
+| [接口 AI](https://jiekou.ai/) | 聚合平台 | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | 聚合平台 | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | 聚合平台 | ✅ |
+
+### TTS（語音合成）
 
 | 平台/模型 | 備註 |
-| --- | --- |
+|-----------|------|
 | [FishAudio](https://fish.audio/zh-CN/discovery/) | [外掛](https://github.com/the-lazy-me/NewChatVoice) |
 | [海豚 AI](https://www.ttson.cn/?source=thelazy) | [外掛](https://github.com/the-lazy-me/NewChatVoice) |
 | [AzureTTS](https://portal.azure.com/) | [外掛](https://github.com/Ingnaryk/LangBot_AzureTTS) |
@@ -146,13 +145,65 @@ docker compose up -d
 ### 文生圖
 
 | 平台/模型 | 備註 |
-| --- | --- |
-| 阿里雲百煉 | [外掛](https://github.com/Thetail001/LangBot_BailianTextToImagePlugin)
+|-----------|------|
+| 阿里雲百煉 | [外掛](https://github.com/Thetail001/LangBot_BailianTextToImagePlugin) |
 
-## 😘 社群貢獻
+[→ 查看完整整合列表](https://link.langbot.app/zh/docs/features)
 
-感謝以下[程式碼貢獻者](https://github.com/langbot-app/LangBot/graphs/contributors)和社群裡其他成員對 LangBot 的貢獻：
+---
+
+## 為什麼選擇 LangBot？
+
+| 使用場景 | LangBot 如何幫助 |
+|----------|------------------|
+| **客戶服務** | 將 AI Agent 部署到微信/企微/釘釘/飛書，基於知識庫自動回答使用者問題 |
+| **內部工具** | 將 n8n/Dify 工作流接入企微/釘釘，實現業務流程自動化 |
+| **社群運營** | 在 QQ/Discord 群中使用 AI 驅動的內容審核與智能互動 |
+| **多平台觸達** | 一個機器人，覆蓋所有平台。透過統一面板集中管理 |
+
+---
+
+## 線上演示
+
+**立即體驗：** https://demo.langbot.dev/
+- 信箱：`demo@langbot.app`
+- 密碼：`langbot123456`
+
+*注意：公開演示環境，請不要在其中填入任何敏感資訊。*
+
+## 為 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)
+[![QQ Group](https://img.shields.io/badge/%E7%A4%BE%E5%8C%BAQQ%E7%BE%A4-966235608-blue)](https://qm.qq.com/q/JLi38whHum)
+
+- [Discord 社群](https://discord.gg/wdNEHETs87)
+- [QQ 社群群](https://qm.qq.com/q/JLi38whHum)
+
+---
+
+## Star 趨勢
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## 貢獻者
+
+感謝所有[貢獻者](https://github.com/langbot-app/LangBot/graphs/contributors)對 LangBot 的幫助：
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />
-</a> 
+</a>

README_VI.md

@@ -1,43 +1,74 @@
 <p align="center">
 <a href="https://langbot.app">
-<img src="https://docs.langbot.app/social_en.png" alt="LangBot"/>
+<img width="130" src="res/logo-blue.png" alt="LangBot"/>
 </a>
 
 <div align="center">
 
 <a href="https://www.producthunt.com/products/langbot?utm_source=badge-follow&utm_medium=badge&utm_source=badge-langbot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=1077185&theme=light" alt="LangBot - Production&#0045;grade&#0032;IM&#0032;bot&#0032;made&#0032;easy&#0046; | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 
-[English](README_EN.md) / [简体中文](README.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / Tiếng Việt
+<h3>Nền tảng cấp sản xuất để xây dựng bot IM với AI agent.</h3>
+<h4>Xây dựng, gỡ lỗi và triển khai bot AI nhanh chóng trên Slack, Discord, Telegram, WeChat và nhiều nền tảng khác.</h4>
+
+[English](README.md) / [简体中文](README_CN.md) / [繁體中文](README_TW.md) / [日本語](README_JP.md) / [Español](README_ES.md) / [Français](README_FR.md) / [한국어](README_KO.md) / [Русский](README_RU.md) / Tiếng Việt
 
 [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb)](https://discord.gg/wdNEHETs87)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/langbot-app/LangBot)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/langbot-app/LangBot)](https://github.com/langbot-app/LangBot/releases/latest)
 <img src="https://img.shields.io/badge/python-3.10 ~ 3.13 -blue.svg" alt="python">
+[![GitHub stars](https://img.shields.io/github/stars/langbot-app/LangBot?style=social)](https://github.com/langbot-app/LangBot/stargazers)
 
 <a href="https://langbot.app">Trang chủ</a> ｜
-<a href="https://docs.langbot.app/en/insight/guide.html">Triển khai</a> ｜
-<a href="https://docs.langbot.app/en/plugin/plugin-intro.html">Plugin</a> ｜
-<a href="https://github.com/langbot-app/LangBot/issues/new?assignees=&labels=%E7%8B%AC%E7%AB%8B%E6%8F%92%E4%BB%B6&projects=&template=submit-plugin.yml&title=%5BPlugin%5D%3A+%E8%AF%B7%E6%B1%82%E7%99%BB%E8%AE%B0%E6%96%B0%E6%8F%92%E4%BB%B6">Gửi Plugin</a>
+<a href="https://link.langbot.app/en/docs/features">Tính năng</a> ｜
+<a href="https://link.langbot.app/en/docs/guide">Tài liệu</a> ｜
+<a href="https://link.langbot.app/en/docs/api">API</a> ｜
+<a href="https://space.langbot.app">Chợ Plugin</a> ｜
+<a href="https://langbot.featurebase.app/roadmap">Lộ trình</a>
 
 </div>
 
 </p>
 
-LangBot là một nền tảng phát triển robot nhắn tin tức thời gốc LLM mã nguồn mở, nhằm mục đích cung cấp trải nghiệm phát triển robot IM sẵn sàng sử dụng, với các chức năng ứng dụng LLM như Agent, RAG, MCP, thích ứng với các nền tảng nhắn tin tức thời toàn cầu và cung cấp giao diện API phong phú, hỗ trợ phát triển tùy chỉnh.
+---
 
-## 📦 Bắt đầu
+## LangBot là gì?
 
-#### Khởi động Nhanh
+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.
 
-Sử dụng `uvx` để khởi động bằng một lệnh (cần cài đặt [uv](https://docs.astral.sh/uv/getting-started/installation/)):
+<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).
+- **Hỗ trợ đa nền tảng IM** — Một mã nguồn cho Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, KOOK.
+- **Sẵn sàng cho sản xuất** — Kiểm soát truy cập, giới hạn tốc độ, lọc từ nhạy cảm, giám sát toàn diện và xử lý ngoại lệ. Được doanh nghiệp tin dùng.
+- **Hệ sinh thái Plugin** — Hàng trăm plugin, kiến trúc hướng sự kiện, mở rộng thành phần, và hỗ trợ [giao thức MCP](https://modelcontextprotocol.io/).
+- **Bảng quản lý Web** — Cấu hình, quản lý và giám sát bot thông qua giao diện trình duyệt trực quan. Không cần chỉnh sửa YAML.
+- **Kiến trúc đa Pipeline** — Các bot khác nhau cho các kịch bản khác nhau, với giám sát toàn diện và xử lý ngoại lệ.
+
+[→ Tìm hiểu thêm về tất cả tính năng](https://link.langbot.app/en/docs/features)
+
+📍 Hướng dẫn thực hành: [triển khai bot AI đa nền tảng trong 5 phút](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [kết nối DeepSeek với WeChat, Discord và Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [chạy Dify Agent trên Discord, Telegram và Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) và [xây dựng chatbot với n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+
+---
+
+## Bắt đầu nhanh
+
+### ☁️ LangBot Cloud (Khuyên dùng)
+
+**[LangBot Cloud](https://space.langbot.app/cloud)** — Không cần triển khai, sẵn sàng sử dụng.
+
+### Khởi chạy một dòng
 
 ```bash
 uvx langbot
 ```
 
-Truy cập http://localhost:5300 để bắt đầu sử dụng.
+> Yêu cầu [uv](https://docs.astral.sh/uv/getting-started/installation/). Truy cập http://localhost:5300 — xong.
 
-#### Triển khai Docker Compose
+### Docker Compose
 
 ```bash
 git clone https://github.com/langbot-app/LangBot
@@ -45,99 +76,115 @@ cd LangBot/docker
 docker compose up -d
 ```
 
-Truy cập http://localhost:5300 để bắt đầu sử dụng.
-
-Tài liệu chi tiết [Triển khai Docker](https://docs.langbot.app/en/deploy/langbot/docker.html).
-
-#### Triển khai Một cú nhấp chuột trên BTPanel
-
-LangBot đã được liệt kê trên BTPanel. Nếu bạn đã cài đặt BTPanel, bạn có thể sử dụng [tài liệu](https://docs.langbot.app/en/deploy/langbot/one-click/bt.html) để sử dụng nó.
-
-#### Triển khai Cloud Zeabur
-
-Mẫu Zeabur được đóng góp bởi cộng đồng.
+### Triển khai đám mây một cú nhấp
 
 [![Deploy on Zeabur](https://zeabur.com/button.svg)](https://zeabur.com/en-US/templates/ZKTBDH)
-
-#### Triển khai Cloud Railway
-
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.app/template/yRrAyL?referralCode=vogKPF)
 
-#### Các Phương pháp Triển khai Khác
+**Thêm tùy chọn:** [Docker](https://link.langbot.app/en/docs/docker) · [Thủ công](https://link.langbot.app/en/docs/manual-deploy) · [BTPanel](https://link.langbot.app/en/docs/bt-panel) · [Kubernetes](https://docs.langbot.app/en/deploy/langbot/kubernetes)
 
-Sử dụng trực tiếp phiên bản phát hành để chạy, xem tài liệu [Triển khai Thủ công](https://docs.langbot.app/en/deploy/langbot/manual.html).
+---
 
-#### Triển khai Kubernetes
-
-Tham khảo tài liệu [Triển khai Kubernetes](./docker/README_K8S.md).
-
-## 😎 Cập nhật Mới nhất
-
-Nhấp vào các nút Star và Watch ở góc trên bên phải của kho lưu trữ để nhận các bản cập nhật mới nhất.
-
-![star gif](https://docs.langbot.app/star.gif)
-
-## ✨ Tính năng
-
-- 💬 Chat với LLM / Agent: Hỗ trợ nhiều LLM, thích ứng với chat nhóm và chat riêng tư; Hỗ trợ các cuộc trò chuyện nhiều vòng, gọi công cụ, khả năng đa phương thức và đầu ra streaming. Triển khai RAG (cơ sở kiến thức) tích hợp sẵn và tích hợp sâu với [Dify](https://dify.ai), [Coze](https://coze.com), [n8n](https://n8n.io) v.v. LLMOps platforms.
-- 🤖 Hỗ trợ Đa nền tảng: Hiện hỗ trợ QQ, QQ Channel, WeCom, WeChat cá nhân, Lark, DingTalk, Discord, Telegram, KOOK, Slack, LINE, v.v.
-- 🛠️ Độ ổn định Cao, Tính năng Phong phú: Kiểm soát truy cập gốc, giới hạn tốc độ, lọc từ nhạy cảm, v.v.; Dễ sử dụng, hỗ trợ nhiều phương pháp triển khai. Hỗ trợ nhiều cấu hình pipeline, các bot khác nhau cho các kịch bản khác nhau.
-- 🧩 Mở rộng Plugin, Cộng đồng Hoạt động: Hỗ trợ các cơ chế plugin hướng sự kiện, mở rộng thành phần, v.v.; Tích hợp giao thức [MCP](https://modelcontextprotocol.io/) của Anthropic; Hiện có hàng trăng plugin.
-- 😻 Giao diện Web: Hỗ trợ quản lý các phiên bản LangBot thông qua trình duyệt. Không cần viết tệp cấu hình thủ công.
-
-Để biết thêm thông số kỹ thuật chi tiết, vui lòng tham khảo [tài liệu](https://docs.langbot.app/en/insight/features.html).
-
-Hoặc truy cập môi trường demo: https://demo.langbot.dev/
-  - Thông tin đăng nhập: Email: `demo@langbot.app` Mật khẩu: `langbot123456`
-  - Lưu ý: Chỉ dành cho demo WebUI, vui lòng không nhập bất kỳ thông tin nhạy cảm nào trong môi trường công cộng.
-
-### Nền tảng Nhắn tin
+## Nền tảng được hỗ trợ
 
 | Nền tảng | Trạng thái | Ghi chú |
-| --- | --- | --- |
-| Discord | ✅ |  |
-| Telegram | ✅ |  |
-| Slack | ✅ |  |
-| LINE | ✅ |  |
-| QQ Cá nhân | ✅ |  |
-| QQ API Chính thức | ✅ |  |
-| WeCom | ✅ |  |
-| WeComCS | ✅ |  |
-| WeCom AI Bot | ✅ |  |
-| WeChat Cá nhân | ✅ |  |
-| KOOK | ✅ |  |
-| Lark | ✅ |  |
-| DingTalk | ✅ |  |
+|----------|--------|-------|
+| Discord | ✅ | Chính thức |
+| Telegram | ✅ | Chính thức |
+| Slack | ✅ | Chính thức |
+| LINE | ✅ | Chính thức |
+| QQ | ✅ | Cá nhân & API chính thức (Kênh, DM, Nhóm) |
+| WeCom | ✅ | WeChat doanh nghiệp, CS bên ngoài, AI Bot |
+| WeChat | ✅ | Cá nhân & Tài khoản công khai |
+| Lark | ✅ | Chính thức |
+| DingTalk | ✅ | Chính thức |
+| KOOK | ✅ | Chính thức |
+| Satori | ✅ |  |
+| Email | ✅ | Matrix, Satori |
+| Matrix | ✅ | Hỗ trợ nhiều nền tảng qua bridge như Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip và hơn thế nữa |
 
-### LLMs
+---
 
-| LLM | Trạng thái | Ghi chú |
-| --- | --- | --- |
-| [OpenAI](https://platform.openai.com/) | ✅ | Có sẵn cho bất kỳ mô hình định dạng giao diện OpenAI nào |
-| [DeepSeek](https://www.deepseek.com/) | ✅ |  |
-| [Moonshot](https://www.moonshot.cn/) | ✅ |  |
-| [Anthropic](https://www.anthropic.com/) | ✅ |  |
-| [xAI](https://x.ai/) | ✅ |  |
-| [Zhipu AI](https://open.bigmodel.cn/) | ✅ |  |
-| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | ✅ | Nền tảng tài nguyên LLM và GPU |
-| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | ✅ | Nền tảng tài nguyên LLM và GPU |
-| [接口 AI](https://jiekou.ai/) | ✅ | Nền tảng tổng hợp LLM |
-| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | ✅ | Nền tảng tài nguyên LLM và GPU |
-| [302.AI](https://share.302.ai/SuTG99) | ✅ | Cổng LLM (MaaS) |
-| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | ✅ | |
-| [Dify](https://dify.ai) | ✅ | Nền tảng LLMOps |
-| [Ollama](https://ollama.com/) | ✅ | Nền tảng chạy LLM cục bộ |
-| [LMStudio](https://lmstudio.ai/) | ✅ | Nền tảng chạy LLM cục bộ |
-| [GiteeAI](https://ai.gitee.com/) | ✅ | Cổng giao diện LLM (MaaS) |
-| [SiliconFlow](https://siliconflow.cn/) | ✅ | Cổng LLM (MaaS) |
-| [Aliyun Bailian](https://bailian.console.aliyun.com/) | ✅ | Cổng LLM (MaaS), nền tảng LLMOps |
-| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | ✅ | Cổng LLM (MaaS), nền tảng LLMOps |
-| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | ✅ | Cổng LLM (MaaS) |
-| [MCP](https://modelcontextprotocol.io/) | ✅ | Hỗ trợ truy cập công cụ qua giao thức MCP |
+## LLM và tích hợp được hỗ trợ
 
-## 🤝 Đóng góp Cộng đồng
+| Nhà cung cấp | Loại | Trạng thái |
+|----------|------|--------|
+| [OpenAI](https://platform.openai.com/) | LLM | ✅ |
+| [Anthropic](https://www.anthropic.com/) | LLM | ✅ |
+| [DeepSeek](https://www.deepseek.com/) | LLM | ✅ |
+| [Google Gemini](https://aistudio.google.com/prompts/new_chat) | LLM | ✅ |
+| [xAI](https://x.ai/) | LLM | ✅ |
+| [Moonshot](https://www.moonshot.cn/) | LLM | ✅ |
+| [Zhipu AI](https://open.bigmodel.cn/) | LLM | ✅ |
+| [Ollama](https://ollama.com/) | LLM cục bộ | ✅ |
+| [LM Studio](https://lmstudio.ai/) | LLM cục bộ | ✅ |
+| [Dify](https://dify.ai) | LLMOps | ✅ |
+| [MCP](https://modelcontextprotocol.io/) | Giao thức | ✅ |
+| [SiliconFlow](https://siliconflow.cn/) | Cổng | ✅ |
+| [Aliyun Bailian](https://bailian.console.aliyun.com/) | Cổng | ✅ |
+| [Volc Engine Ark](https://console.volcengine.com/ark/region:ark+cn-beijing/model?vendor=Bytedance&view=LIST_VIEW) | Cổng | ✅ |
+| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro) | Cổng | ✅ |
+| [GiteeAI](https://ai.gitee.com/) | Cổng | ✅ |
+| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot) | Nền tảng GPU | ✅ |
+| [PPIO](https://ppinfra.com/user/register?invited_by=QJKFYD&utm_source=github_langbot) | Nền tảng GPU | ✅ |
+| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758) | Nền tảng GPU | ✅ |
+| [接口 AI](https://jiekou.ai/) | Cổng | ✅ |
+| [302.AI](https://share.302.ai/SuTG99) | Cổng | ✅ |
+| [Qiniu](https://www.qiniu.com/ai/agent) | Cổng | ✅ |
 
-Cảm ơn các [người đóng góp mã](https://github.com/langbot-app/LangBot/graphs/contributors) sau đây và các thành viên khác trong cộng đồng vì những đóng góp của họ cho LangBot:
+[→ Xem tất cả tích hợp](https://link.langbot.app/en/docs/features)
+
+---
+
+## Tại sao chọn LangBot?
+
+| Trường hợp sử dụng | LangBot giúp như thế nào |
+|----------|-------------------|
+| **Hỗ trợ khách hàng** | Triển khai agent AI trên Slack/Discord/Telegram để trả lời câu hỏi bằng cơ sở kiến thức của bạn |
+| **Công cụ nội bộ** | Kết nối quy trình n8n/Dify với WeCom/DingTalk để tự động hóa quy trình kinh doanh |
+| **Quản lý cộng đồng** | Quản lý nhóm QQ/Discord với tính năng lọc nội dung và tương tác được hỗ trợ bởi AI |
+| **Đa nền tảng** | Một bot, tất cả nền tảng. Quản lý từ một bảng điều khiển duy nhất |
+
+---
+
+## Demo trực tuyến
+
+**Thử ngay:** https://demo.langbot.dev/
+- Email: `demo@langbot.app`
+- Mật khẩu: `langbot123456`
+
+*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
+
+[![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord&label=Discord)](https://discord.gg/wdNEHETs87)
+
+- [Cộng đồng Discord](https://discord.gg/wdNEHETs87)
+
+---
+
+## Lịch sử Star
+
+[![Star History Chart](https://api.star-history.com/svg?repos=langbot-app/LangBot&type=Date)](https://star-history.com/#langbot-app/LangBot&Date)
+
+---
+
+## Người đóng góp
+
+Cảm ơn tất cả [người đóng góp](https://github.com/langbot-app/LangBot/graphs/contributors) đã giúp LangBot trở nên tốt hơn:
 
 <a href="https://github.com/langbot-app/LangBot/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=langbot-app/LangBot" />

docker/README_K8S.md

@@ -1,629 +0,0 @@
-# LangBot Kubernetes 部署指南 / Kubernetes Deployment Guide
-
-[简体中文](#简体中文) | [English](#english)
-
----
-
-## 简体中文
-
-### 概述
-
-本指南提供了在 Kubernetes 集群中部署 LangBot 的完整步骤。Kubernetes 部署配置基于 `docker-compose.yaml`，适用于生产环境的容器化部署。
-
-### 前置要求
-
-- Kubernetes 集群（版本 1.19+）
-- `kubectl` 命令行工具已配置并可访问集群
-- 集群中有可用的存储类（StorageClass）用于持久化存储（可选但推荐）
-- 至少 2 vCPU 和 4GB RAM 的可用资源
-
-### 架构说明
-
-Kubernetes 部署包含以下组件：
-
-1. **langbot**: 主应用服务
-   - 提供 Web UI（端口 5300）
-   - 处理平台 webhook（端口 2280-2290）
-   - 数据持久化卷
-   
-2. **langbot-plugin-runtime**: 插件运行时服务
-   - WebSocket 通信（端口 5400）
-   - 插件数据持久化卷
-
-3. **持久化存储**:
-   - `langbot-data`: LangBot 主数据
-   - `langbot-plugins`: 插件文件
-   - `langbot-plugin-runtime-data`: 插件运行时数据
-
-### 快速开始
-
-#### 1. 下载部署文件
-
-```bash
-# 克隆仓库
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
-
-# 或直接下载 kubernetes.yaml
-wget https://raw.githubusercontent.com/langbot-app/LangBot/main/docker/kubernetes.yaml
-```
-
-#### 2. 部署到 Kubernetes
-
-```bash
-# 应用所有配置
-kubectl apply -f kubernetes.yaml
-
-# 检查部署状态
-kubectl get all -n langbot
-
-# 查看 Pod 日志
-kubectl logs -n langbot -l app=langbot -f
-```
-
-#### 3. 访问 LangBot
-
-默认情况下，LangBot 服务使用 ClusterIP 类型，只能在集群内部访问。您可以选择以下方式之一来访问：
-
-**选项 A: 端口转发（推荐用于测试）**
-
-```bash
-kubectl port-forward -n langbot svc/langbot 5300:5300
-```
-
-然后访问 http://localhost:5300
-
-**选项 B: NodePort（适用于开发环境）**
-
-编辑 `kubernetes.yaml`，取消注释 NodePort Service 部分，然后：
-
-```bash
-kubectl apply -f kubernetes.yaml
-# 获取节点 IP
-kubectl get nodes -o wide
-# 访问 http://<NODE_IP>:30300
-```
-
-**选项 C: LoadBalancer（适用于云环境）**
-
-编辑 `kubernetes.yaml`，取消注释 LoadBalancer Service 部分，然后：
-
-```bash
-kubectl apply -f kubernetes.yaml
-# 获取外部 IP
-kubectl get svc -n langbot langbot-loadbalancer
-# 访问 http://<EXTERNAL_IP>
-```
-
-**选项 D: Ingress（推荐用于生产环境）**
-
-确保集群中已安装 Ingress Controller（如 nginx-ingress），然后：
-
-1. 编辑 `kubernetes.yaml` 中的 Ingress 配置
-2. 修改域名为您的实际域名
-3. 应用配置：
-
-```bash
-kubectl apply -f kubernetes.yaml
-# 访问 http://langbot.yourdomain.com
-```
-
-### 配置说明
-
-#### 环境变量
-
-在 `ConfigMap` 中配置环境变量：
-
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: langbot-config
-  namespace: langbot
-data:
-  TZ: "Asia/Shanghai"  # 修改为您的时区
-```
-
-#### 存储配置
-
-默认使用动态存储分配。如果您有特定的 StorageClass，请在 PVC 中指定：
-
-```yaml
-spec:
-  storageClassName: your-storage-class-name
-  accessModes:
-    - ReadWriteOnce
-  resources:
-    requests:
-      storage: 10Gi
-```
-
-#### 资源限制
-
-根据您的需求调整资源限制：
-
-```yaml
-resources:
-  requests:
-    memory: "1Gi"
-    cpu: "500m"
-  limits:
-    memory: "4Gi"
-    cpu: "2000m"
-```
-
-### 常用操作
-
-#### 查看日志
-
-```bash
-# 查看 LangBot 主服务日志
-kubectl logs -n langbot -l app=langbot -f
-
-# 查看插件运行时日志
-kubectl logs -n langbot -l app=langbot-plugin-runtime -f
-```
-
-#### 重启服务
-
-```bash
-# 重启 LangBot
-kubectl rollout restart deployment/langbot -n langbot
-
-# 重启插件运行时
-kubectl rollout restart deployment/langbot-plugin-runtime -n langbot
-```
-
-#### 更新镜像
-
-```bash
-# 更新到最新版本
-kubectl set image deployment/langbot -n langbot langbot=rockchin/langbot:latest
-kubectl set image deployment/langbot-plugin-runtime -n langbot langbot-plugin-runtime=rockchin/langbot:latest
-
-# 检查更新状态
-kubectl rollout status deployment/langbot -n langbot
-```
-
-#### 扩容（不推荐）
-
-注意：由于 LangBot 使用 ReadWriteOnce 的持久化存储，不支持多副本扩容。如需高可用，请考虑使用 ReadWriteMany 存储或其他架构方案。
-
-#### 备份数据
-
-```bash
-# 备份 PVC 数据
-kubectl exec -n langbot -it <langbot-pod-name> -- tar czf /tmp/backup.tar.gz /app/data
-kubectl cp langbot/<langbot-pod-name>:/tmp/backup.tar.gz ./backup.tar.gz
-```
-
-### 卸载
-
-```bash
-# 删除所有资源（保留 PVC）
-kubectl delete deployment,service,configmap -n langbot --all
-
-# 删除 PVC（会删除数据）
-kubectl delete pvc -n langbot --all
-
-# 删除命名空间
-kubectl delete namespace langbot
-```
-
-### 故障排查
-
-#### Pod 无法启动
-
-```bash
-# 查看 Pod 状态
-kubectl get pods -n langbot
-
-# 查看详细信息
-kubectl describe pod -n langbot <pod-name>
-
-# 查看事件
-kubectl get events -n langbot --sort-by='.lastTimestamp'
-```
-
-#### 存储问题
-
-```bash
-# 检查 PVC 状态
-kubectl get pvc -n langbot
-
-# 检查 PV
-kubectl get pv
-```
-
-#### 网络访问问题
-
-```bash
-# 检查 Service
-kubectl get svc -n langbot
-
-# 检查端口转发
-kubectl port-forward -n langbot svc/langbot 5300:5300
-```
-
-### 生产环境建议
-
-1. **使用特定版本标签**：避免使用 `latest` 标签，使用具体版本号如 `rockchin/langbot:v1.0.0`
-2. **配置资源限制**：根据实际负载调整 CPU 和内存限制
-3. **使用 Ingress + TLS**：配置 HTTPS 访问和证书管理
-4. **配置监控和告警**：集成 Prometheus、Grafana 等监控工具
-5. **定期备份**：配置自动备份策略保护数据
-6. **使用专用 StorageClass**：为生产环境配置高性能存储
-7. **配置亲和性规则**：确保 Pod 调度到合适的节点
-
-### 高级配置
-
-#### 使用 Secrets 管理敏感信息
-
-如果需要配置 API 密钥等敏感信息：
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: langbot-secrets
-  namespace: langbot
-type: Opaque
-data:
-  api_key: <base64-encoded-value>
-```
-
-然后在 Deployment 中引用：
-
-```yaml
-env:
-- name: API_KEY
-  valueFrom:
-    secretKeyRef:
-      name: langbot-secrets
-      key: api_key
-```
-
-#### 配置水平自动扩缩容（HPA）
-
-注意：需要确保使用 ReadWriteMany 存储类型
-
-```yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: langbot-hpa
-  namespace: langbot
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: langbot
-  minReplicas: 1
-  maxReplicas: 3
-  metrics:
-  - type: Resource
-    resource:
-      name: cpu
-      target:
-        type: Utilization
-        averageUtilization: 70
-```
-
-### 参考资源
-
-- [LangBot 官方文档](https://docs.langbot.app)
-- [Docker 部署文档](https://docs.langbot.app/zh/deploy/langbot/docker.html)
-- [Kubernetes 官方文档](https://kubernetes.io/docs/)
-
----
-
-## English
-
-### Overview
-
-This guide provides complete steps for deploying LangBot in a Kubernetes cluster. The Kubernetes deployment configuration is based on `docker-compose.yaml` and is suitable for production containerized deployments.
-
-### Prerequisites
-
-- Kubernetes cluster (version 1.19+)
-- `kubectl` command-line tool configured with cluster access
-- Available StorageClass in the cluster for persistent storage (optional but recommended)
-- At least 2 vCPU and 4GB RAM of available resources
-
-### Architecture
-
-The Kubernetes deployment includes the following components:
-
-1. **langbot**: Main application service
-   - Provides Web UI (port 5300)
-   - Handles platform webhooks (ports 2280-2290)
-   - Data persistence volume
-   
-2. **langbot-plugin-runtime**: Plugin runtime service
-   - WebSocket communication (port 5400)
-   - Plugin data persistence volume
-
-3. **Persistent Storage**:
-   - `langbot-data`: LangBot main data
-   - `langbot-plugins`: Plugin files
-   - `langbot-plugin-runtime-data`: Plugin runtime data
-
-### Quick Start
-
-#### 1. Download Deployment Files
-
-```bash
-# Clone repository
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
-
-# Or download kubernetes.yaml directly
-wget https://raw.githubusercontent.com/langbot-app/LangBot/main/docker/kubernetes.yaml
-```
-
-#### 2. Deploy to Kubernetes
-
-```bash
-# Apply all configurations
-kubectl apply -f kubernetes.yaml
-
-# Check deployment status
-kubectl get all -n langbot
-
-# View Pod logs
-kubectl logs -n langbot -l app=langbot -f
-```
-
-#### 3. Access LangBot
-
-By default, LangBot service uses ClusterIP type, accessible only within the cluster. Choose one of the following methods to access:
-
-**Option A: Port Forwarding (Recommended for testing)**
-
-```bash
-kubectl port-forward -n langbot svc/langbot 5300:5300
-```
-
-Then visit http://localhost:5300
-
-**Option B: NodePort (Suitable for development)**
-
-Edit `kubernetes.yaml`, uncomment the NodePort Service section, then:
-
-```bash
-kubectl apply -f kubernetes.yaml
-# Get node IP
-kubectl get nodes -o wide
-# Visit http://<NODE_IP>:30300
-```
-
-**Option C: LoadBalancer (Suitable for cloud environments)**
-
-Edit `kubernetes.yaml`, uncomment the LoadBalancer Service section, then:
-
-```bash
-kubectl apply -f kubernetes.yaml
-# Get external IP
-kubectl get svc -n langbot langbot-loadbalancer
-# Visit http://<EXTERNAL_IP>
-```
-
-**Option D: Ingress (Recommended for production)**
-
-Ensure an Ingress Controller (e.g., nginx-ingress) is installed in the cluster, then:
-
-1. Edit the Ingress configuration in `kubernetes.yaml`
-2. Change the domain to your actual domain
-3. Apply configuration:
-
-```bash
-kubectl apply -f kubernetes.yaml
-# Visit http://langbot.yourdomain.com
-```
-
-### Configuration
-
-#### Environment Variables
-
-Configure environment variables in ConfigMap:
-
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: langbot-config
-  namespace: langbot
-data:
-  TZ: "Asia/Shanghai"  # Change to your timezone
-```
-
-#### Storage Configuration
-
-Uses dynamic storage provisioning by default. If you have a specific StorageClass, specify it in PVC:
-
-```yaml
-spec:
-  storageClassName: your-storage-class-name
-  accessModes:
-    - ReadWriteOnce
-  resources:
-    requests:
-      storage: 10Gi
-```
-
-#### Resource Limits
-
-Adjust resource limits based on your needs:
-
-```yaml
-resources:
-  requests:
-    memory: "1Gi"
-    cpu: "500m"
-  limits:
-    memory: "4Gi"
-    cpu: "2000m"
-```
-
-### Common Operations
-
-#### View Logs
-
-```bash
-# View LangBot main service logs
-kubectl logs -n langbot -l app=langbot -f
-
-# View plugin runtime logs
-kubectl logs -n langbot -l app=langbot-plugin-runtime -f
-```
-
-#### Restart Services
-
-```bash
-# Restart LangBot
-kubectl rollout restart deployment/langbot -n langbot
-
-# Restart plugin runtime
-kubectl rollout restart deployment/langbot-plugin-runtime -n langbot
-```
-
-#### Update Images
-
-```bash
-# Update to latest version
-kubectl set image deployment/langbot -n langbot langbot=rockchin/langbot:latest
-kubectl set image deployment/langbot-plugin-runtime -n langbot langbot-plugin-runtime=rockchin/langbot:latest
-
-# Check update status
-kubectl rollout status deployment/langbot -n langbot
-```
-
-#### Scaling (Not Recommended)
-
-Note: Due to LangBot using ReadWriteOnce persistent storage, multi-replica scaling is not supported. For high availability, consider using ReadWriteMany storage or alternative architectures.
-
-#### Backup Data
-
-```bash
-# Backup PVC data
-kubectl exec -n langbot -it <langbot-pod-name> -- tar czf /tmp/backup.tar.gz /app/data
-kubectl cp langbot/<langbot-pod-name>:/tmp/backup.tar.gz ./backup.tar.gz
-```
-
-### Uninstall
-
-```bash
-# Delete all resources (keep PVCs)
-kubectl delete deployment,service,configmap -n langbot --all
-
-# Delete PVCs (will delete data)
-kubectl delete pvc -n langbot --all
-
-# Delete namespace
-kubectl delete namespace langbot
-```
-
-### Troubleshooting
-
-#### Pods Not Starting
-
-```bash
-# Check Pod status
-kubectl get pods -n langbot
-
-# View detailed information
-kubectl describe pod -n langbot <pod-name>
-
-# View events
-kubectl get events -n langbot --sort-by='.lastTimestamp'
-```
-
-#### Storage Issues
-
-```bash
-# Check PVC status
-kubectl get pvc -n langbot
-
-# Check PV
-kubectl get pv
-```
-
-#### Network Access Issues
-
-```bash
-# Check Service
-kubectl get svc -n langbot
-
-# Test port forwarding
-kubectl port-forward -n langbot svc/langbot 5300:5300
-```
-
-### Production Recommendations
-
-1. **Use specific version tags**: Avoid using `latest` tag, use specific version like `rockchin/langbot:v1.0.0`
-2. **Configure resource limits**: Adjust CPU and memory limits based on actual load
-3. **Use Ingress + TLS**: Configure HTTPS access and certificate management
-4. **Configure monitoring and alerts**: Integrate monitoring tools like Prometheus, Grafana
-5. **Regular backups**: Configure automated backup strategy to protect data
-6. **Use dedicated StorageClass**: Configure high-performance storage for production
-7. **Configure affinity rules**: Ensure Pods are scheduled to appropriate nodes
-
-### Advanced Configuration
-
-#### Using Secrets for Sensitive Information
-
-If you need to configure sensitive information like API keys:
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: langbot-secrets
-  namespace: langbot
-type: Opaque
-data:
-  api_key: <base64-encoded-value>
-```
-
-Then reference in Deployment:
-
-```yaml
-env:
-- name: API_KEY
-  valueFrom:
-    secretKeyRef:
-      name: langbot-secrets
-      key: api_key
-```
-
-#### Configure Horizontal Pod Autoscaling (HPA)
-
-Note: Requires ReadWriteMany storage type
-
-```yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: langbot-hpa
-  namespace: langbot
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: langbot
-  minReplicas: 1
-  maxReplicas: 3
-  metrics:
-  - type: Resource
-    resource:
-      name: cpu
-      target:
-        type: Utilization
-        averageUtilization: 70
-```
-
-### References
-
-- [LangBot Official Documentation](https://docs.langbot.app)
-- [Docker Deployment Guide](https://docs.langbot.app/zh/deploy/langbot/docker.html)
-- [Kubernetes Official Documentation](https://kubernetes.io/docs/)

docker/docker-compose.yaml

@@ -1,5 +1,5 @@
 # Docker Compose configuration for LangBot
-# For Kubernetes deployment, see kubernetes.yaml and README_K8S.md
+# For Kubernetes deployment, see kubernetes.yaml and the deployment guide at https://docs.langbot.app
 version: "3"
 
 services:
@@ -7,7 +7,6 @@ services:
   langbot_plugin_runtime:
     image: rockchin/langbot:latest
     container_name: langbot_plugin_runtime
-    platform: linux/amd64 # For Apple Silicon compatibility
     volumes:
       - ./data/plugins:/app/data/plugins
     ports:
@@ -15,19 +14,59 @@ services:
     restart: on-failure
     environment:
       - TZ=Asia/Shanghai
-    command: ["uv", "run", "-m", "langbot_plugin.cli.__init__", "rt"]
+    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "rt"]
+    networks:
+      - langbot_network
+
+  # The Box sandbox runtime is optional. It is only started when you run
+  # ``docker compose --profile box up`` (or ``docker compose --profile all
+  # up``). With Box off, LangBot keeps the dashboard / skills list visible
+  # (read-only) but disables sandbox tools, skill add/edit and stdio MCP —
+  # set ``box.enabled: false`` in ``data/config.yaml`` (or
+  # ``BOX__ENABLED=false`` in the langbot service env below) to match.
+  langbot_box:
+    image: rockchin/langbot:latest
+    container_name: langbot_box
+    profiles: ["box", "all"]
+    volumes:
+      # Keep the source and target path identical because langbot_box uses the
+      # host Docker socket to create sandbox containers. Override
+      # LANGBOT_BOX_ROOT with an absolute path if you do not want the default.
+      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
+      # Mount container runtime socket for Box sandbox backend.
+      # Uncomment the one that matches your container runtime:
+      # - /var/run/podman/podman.sock:/var/run/podman/podman.sock   # Podman
+      - /var/run/docker.sock:/var/run/docker.sock                   # Docker
+    restart: on-failure
+    environment:
+      - TZ=Asia/Shanghai
+      # The Box runtime does NOT read box.local.* from config.yaml or env; it
+      # receives its configuration from LangBot via the INIT RPC action.
+      # Do not add LANGBOT_BOX_* / BOX__* here — they would be silently ignored.
+    # Launched through the same CLI entry point as the plugin runtime
+    # (`langbot_plugin.cli.__init__ <subcommand>`). WebSocket is the default
+    # control transport — mirrors `rt`, which also runs with no flag. Pass
+    # `-s` / `--stdio-control` only for the stdio mode LangBot uses outside
+    # containers.
+    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]
     networks:
       - langbot_network
 
   langbot:
     image: rockchin/langbot:latest
     container_name: langbot
-    platform: linux/amd64 # For Apple Silicon compatibility
     volumes:
       - ./data:/app/data
     restart: on-failure
     environment:
       - TZ=Asia/Shanghai
+      # Unified env-override convention: SECTION__SUBSECTION__KEY overrides the
+      # matching config.yaml field (see LoadConfigStage). These map onto
+      # box.local.* and are forwarded to the Box runtime via INIT RPC.
+      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
+      - BOX__LOCAL__DEFAULT_WORKSPACE=default
+      - BOX__LOCAL__SKILLS_ROOT=skills
+      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
     ports:
       - 5300:5300  # For web ui and webhook callback
       - 2280-2285:2280-2285  # For platform reverse connection

docker/kubernetes.yaml

@@ -1,6 +1,8 @@
 # Kubernetes Deployment for LangBot
 # This file provides Kubernetes deployment manifests for LangBot based on docker-compose.yaml
-# 
+#
+# Full deployment guide (zh/en/ja): https://docs.langbot.app -> Installation -> Kubernetes
+#
 # Usage:
 #   kubectl apply -f kubernetes.yaml
 #
@@ -8,13 +10,15 @@
 #   - A Kubernetes cluster (1.19+)
 #   - kubectl configured to communicate with your cluster
 #   - (Optional) A StorageClass for dynamic volume provisioning
+#   - For the Box sandbox runtime: a node with a reachable Docker daemon
+#     (the box mounts the node's /var/run/docker.sock). See the deployment guide.
 #
 # Components:
 #   - Namespace: langbot
 #   - PersistentVolumeClaims for data persistence
-#   - Deployments for langbot and langbot_plugin_runtime
+#   - Deployments for langbot, langbot-plugin-runtime, and langbot-box (sandbox)
 #   - Services for network access
-#   - ConfigMap for timezone configuration
+#   - ConfigMap for timezone + runtime endpoints
 
 ---
 # Namespace
@@ -83,6 +87,11 @@ metadata:
 data:
   TZ: "Asia/Shanghai"
   PLUGIN__RUNTIME_WS_URL: "ws://langbot-plugin-runtime:5400/control/ws"
+  # Box sandbox runtime endpoint. LangBot connects to the Box runtime over
+  # WebSocket. The hostname MUST match the langbot-box Service name. Note the
+  # in-container default ("langbot_box") uses an underscore, which is an
+  # invalid Kubernetes DNS name — so the endpoint is always set explicitly here.
+  BOX__RUNTIME__ENDPOINT: "ws://langbot-box:5410"
 
 ---
 # Deployment for LangBot Plugin Runtime
@@ -169,6 +178,136 @@ spec:
     protocol: TCP
     name: runtime
 
+---
+# Deployment for LangBot Box (sandbox) runtime
+#
+# The Box runtime backs LangBot's sandbox tools (exec / read / write / edit /
+# glob / grep), the `activate` skill tool, skill add/edit, and stdio-mode MCP
+# servers. It is OPTIONAL: if you do not deploy it, set `BOX__ENABLED=false` on
+# the langbot Deployment (or `box.enabled: false` in config.yaml) so the
+# dashboard renders cleanly with sandbox features disabled.
+#
+# IMPORTANT — how the sandbox actually runs:
+#   The bundled image ships only the Docker CLI (no dockerd, no nsjail). The Box
+#   runtime therefore creates sandbox containers by talking to a Docker daemon
+#   over the mounted socket (`/var/run/docker.sock`). Because that daemon
+#   resolves bind-mount paths on the NODE filesystem, the Box workspace root
+#   must be the SAME absolute path inside the box container, inside every
+#   sandbox container it spawns, AND on the node. That is why this manifest uses
+#   a hostPath at a fixed absolute path (/app/data/box) and pins langbot + box
+#   to the same node via podAffinity. A normal PVC will NOT work for the box
+#   workspace, because the node's dockerd cannot see paths that exist only
+#   inside the pod's mount namespace.
+#
+# Security note: mounting the host Docker socket grants the Box runtime (and any
+# code executed in the sandbox) effective root on the node. Only deploy Box on
+# nodes you trust for this workload, ideally a dedicated node pool. For a
+# stronger isolation boundary, switch box.backend to 'e2b' (set E2B_API_KEY) and
+# drop the docker.sock mount + hostPath entirely.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: langbot-box
+  namespace: langbot
+  labels:
+    app: langbot-box
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: langbot-box
+  template:
+    metadata:
+      labels:
+        app: langbot-box
+    spec:
+      # Pin to the same node as langbot so they share the hostPath box root.
+      affinity:
+        podAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+          - labelSelector:
+              matchLabels:
+                app: langbot
+            topologyKey: kubernetes.io/hostname
+      containers:
+      - name: langbot-box
+        image: rockchin/langbot:latest
+        imagePullPolicy: Always
+        # Launched through the same CLI entry point as the plugin runtime.
+        # No flag => WebSocket control transport (default), listening on 5410.
+        command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]
+        ports:
+        - containerPort: 5410
+          name: box-rpc
+          protocol: TCP
+        env:
+        - name: TZ
+          valueFrom:
+            configMapKeyRef:
+              name: langbot-config
+              key: TZ
+        # The Box runtime does NOT read box.local.* / BOX__* from its own env;
+        # it receives its configuration from LangBot via the INIT RPC action.
+        # Do not add BOX__* here — they would be silently ignored.
+        volumeMounts:
+        # Box workspace root — identical path on node, box, and sandbox
+        # containers (see the IMPORTANT note above).
+        - name: box-root
+          mountPath: /app/data/box
+        # Host Docker socket — the sandbox backend uses it to create containers.
+        - name: docker-sock
+          mountPath: /var/run/docker.sock
+        resources:
+          requests:
+            memory: "256Mi"
+            cpu: "100m"
+          limits:
+            memory: "1Gi"
+            cpu: "1000m"
+        livenessProbe:
+          tcpSocket:
+            port: 5410
+          initialDelaySeconds: 20
+          periodSeconds: 10
+          timeoutSeconds: 5
+          failureThreshold: 3
+        readinessProbe:
+          tcpSocket:
+            port: 5410
+          initialDelaySeconds: 10
+          periodSeconds: 5
+          timeoutSeconds: 3
+          failureThreshold: 3
+      volumes:
+      - name: box-root
+        hostPath:
+          path: /app/data/box
+          type: DirectoryOrCreate
+      - name: docker-sock
+        hostPath:
+          path: /var/run/docker.sock
+          type: Socket
+      restartPolicy: Always
+
+---
+# Service for LangBot Box runtime
+apiVersion: v1
+kind: Service
+metadata:
+  name: langbot-box
+  namespace: langbot
+  labels:
+    app: langbot-box
+spec:
+  type: ClusterIP
+  selector:
+    app: langbot-box
+  ports:
+  - port: 5410
+    targetPort: 5410
+    protocol: TCP
+    name: box-rpc
+
 ---
 # Deployment for LangBot
 apiVersion: apps/v1
@@ -213,11 +352,36 @@ spec:
             configMapKeyRef:
               name: langbot-config
               key: PLUGIN__RUNTIME_WS_URL
+        # Box (sandbox) runtime endpoint. Connects LangBot to the langbot-box
+        # Service over WebSocket. Remove this (and the langbot-box Deployment)
+        # and set BOX__ENABLED=false if you do not want the sandbox.
+        - name: BOX__RUNTIME__ENDPOINT
+          valueFrom:
+            configMapKeyRef:
+              name: langbot-config
+              key: BOX__RUNTIME__ENDPOINT
+        # box.local.* config — forwarded to the Box runtime via INIT RPC. The
+        # host_root MUST match the box-root hostPath mountPath below AND the box
+        # Deployment's box-root mountPath, so that skill package paths resolve
+        # identically on both sides and on the node's Docker daemon.
+        - name: BOX__LOCAL__HOST_ROOT
+          value: "/app/data/box"
+        - name: BOX__LOCAL__DEFAULT_WORKSPACE
+          value: "default"
+        - name: BOX__LOCAL__SKILLS_ROOT
+          value: "skills"
+        - name: BOX__LOCAL__ALLOWED_MOUNT_ROOTS
+          value: "/app/data/box"
         volumeMounts:
         - name: data
           mountPath: /app/data
         - name: plugins
           mountPath: /app/plugins
+        # Same node-level box root as the langbot-box Deployment. Mounted over
+        # the data PVC's /app/data/box subpath so both LangBot and the Box
+        # runtime (and the node's dockerd) agree on one absolute path.
+        - name: box-root
+          mountPath: /app/data/box
         resources:
           requests:
             memory: "1Gi"
@@ -250,6 +414,13 @@ spec:
       - name: plugins
         persistentVolumeClaim:
           claimName: langbot-plugins
+      # Node-level box workspace root, shared with the langbot-box Deployment.
+      # hostPath (not PVC) because the node's Docker daemon must see the same
+      # absolute path when bind-mounting workspaces into sandbox containers.
+      - name: box-root
+        hostPath:
+          path: /app/data/box
+          type: DirectoryOrCreate
       restartPolicy: Always
 
 ---

docs/API_KEY_AUTH.md

@@ -10,6 +10,38 @@ 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/SEEKDB_INTEGRATION.md

@@ -0,0 +1,259 @@
+# SeekDB Vector Database Integration
+
+This document describes how to use OceanBase SeekDB as the vector database backend for LangBot's knowledge base feature.
+
+## What is SeekDB?
+
+**OceanBase SeekDB** is an AI-native search database that unifies relational, vector, text, JSON and GIS in a single engine, enabling hybrid search and in-database AI workflows. It's developed by OceanBase and released under Apache 2.0 license.
+
+### Key Features
+
+- **Hybrid Search**: Combine vector search, full-text search and relational query in a single statement
+- **Multi-Model Support**: Support relational, vector, text, JSON and GIS in a single engine
+- **Lightweight**: Requires as little as 1 CPU core and 2 GB of memory
+- **Multiple Deployment Modes**: Supports both embedded mode and client/server mode
+- **MySQL Compatible**: Powered by OceanBase engine with full ACID compliance and MySQL compatibility
+
+## Installation
+
+SeekDB support is automatically included when you install LangBot. The required dependency `pyseekdb` is listed in `pyproject.toml`.
+
+If you need to install it manually:
+
+```bash
+pip install pyseekdb
+```
+
+## ⚠️ Platform Compatibility
+
+### Embedded Mode
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Supported | Full embedded mode support via `pylibseekdb` |
+| macOS | ❌ Not Supported | `pylibseekdb` is Linux-only; use server mode instead |
+| Windows | ❌ Not Supported | `pylibseekdb` is Linux-only; use server mode instead |
+
+**Important**: Embedded mode requires the `pylibseekdb` library, which is only available on Linux. If you're on macOS or Windows, you must use server mode.
+
+### Server Mode (Docker)
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Supported | Full Docker support |
+| macOS | ⚠️ Known Issue | Docker container initialization failure - [See Issue #36](https://github.com/oceanbase/seekdb/issues/36) |
+| Windows | ⚠️ Untested | Should work but not yet tested |
+
+**macOS Users**: Currently, SeekDB Docker containers have an initialization issue on macOS ([oceanbase/seekdb#36](https://github.com/oceanbase/seekdb/issues/36)). Until this is resolved, we recommend:
+- Using ChromaDB or Qdrant as alternatives
+- Connecting to a remote SeekDB server on Linux if available
+
+### Server Mode (Remote Connection)
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| All Platforms | ✅ Supported | Connect to SeekDB running on a remote Linux server |
+
+**Recommendation for macOS/Windows users**: Deploy SeekDB on a Linux server and connect via server mode configuration.
+
+## Configuration
+
+### Embedded Mode (Recommended for Development)
+
+Embedded mode runs SeekDB directly within the LangBot process, storing data locally. This is the simplest setup and requires no external services.
+
+Edit your `config.yaml`:
+
+```yaml
+vdb:
+  use: seekdb
+  seekdb:
+    mode: embedded
+    path: './data/seekdb'  # Path to store SeekDB data
+    database: 'langbot'    # Database name
+```
+
+### Server Mode (For Production)
+
+Server mode connects to a remote SeekDB server or OceanBase server. This is recommended for production deployments.
+
+#### SeekDB Server
+
+```yaml
+vdb:
+  use: seekdb
+  seekdb:
+    mode: server
+    host: 'localhost'
+    port: 2881
+    database: 'langbot'
+    user: 'root'
+    password: ''  # Can also use SEEKDB_PASSWORD env var
+```
+
+#### OceanBase Server
+
+If you're using OceanBase with seekdb capabilities:
+
+```yaml
+vdb:
+  use: seekdb
+  seekdb:
+    mode: server
+    host: 'localhost'
+    port: 2881
+    tenant: 'sys'        # OceanBase tenant name
+    database: 'langbot'
+    user: 'root'
+    password: ''
+```
+
+## Configuration Parameters
+
+| Parameter  | Required | Default      | Description |
+|-----------|----------|--------------|-------------|
+| `mode`    | No       | `embedded`   | Deployment mode: `embedded` or `server` |
+| `path`    | No       | `./data/seekdb` | Data directory for embedded mode |
+| `database` | No      | `langbot`    | Database name |
+| `host`    | No       | `localhost`  | Server host (server mode only) |
+| `port`    | No       | `2881`       | Server port (server mode only) |
+| `user`    | No       | `root`       | Username (server mode only) |
+| `password` | No      | `''`         | Password (server mode only) |
+| `tenant`  | No       | None         | OceanBase tenant (optional, server mode only) |
+
+## Usage
+
+Once configured, SeekDB will be used automatically for all knowledge base operations in LangBot:
+
+1. **Creating Knowledge Bases**: Vectors will be stored in SeekDB collections
+2. **Adding Documents**: Document embeddings will be indexed in SeekDB
+3. **Searching**: Vector similarity search will use SeekDB's efficient indexing
+4. **Deleting**: Document removal will delete vectors from SeekDB
+
+No code changes are required - just update your configuration!
+
+## Architecture Details
+
+### Implementation
+
+The SeekDB adapter is implemented in `src/langbot/pkg/vector/vdbs/seekdb.py` and follows the same `VectorDatabase` interface as Chroma and Qdrant adapters.
+
+Key methods:
+- `add_embeddings()`: Add vectors with metadata to a collection
+- `search()`: Perform vector similarity search
+- `delete_by_file_id()`: Delete vectors by file ID metadata
+- `get_or_create_collection()`: Manage collections
+- `delete_collection()`: Remove entire collections
+
+### Vector Storage
+
+- Collections are created with HNSW (Hierarchical Navigable Small World) index
+- Default distance metric: Cosine similarity
+- Default vector dimension: 384 (adjusts automatically based on embeddings)
+- Metadata is stored alongside vectors for filtering
+
+## Advantages Over Other Vector Databases
+
+### vs. ChromaDB
+- ✅ Better MySQL compatibility
+- ✅ Hybrid search capabilities (vector + full-text + SQL)
+- ✅ Production-grade distributed mode support
+- ✅ Lightweight embedded mode
+
+### vs. Qdrant
+- ✅ SQL query support
+- ✅ MySQL ecosystem integration
+- ✅ Simpler deployment (no Docker required for embedded mode)
+- ✅ Multi-model data support (not just vectors)
+
+## Troubleshooting
+
+### Import Error
+
+If you see: `ImportError: pyseekdb is not installed`
+
+Solution:
+```bash
+pip install pyseekdb
+```
+
+### Embedded Mode Error on macOS/Windows
+
+**Error**:
+```
+RuntimeError: Embedded Client is not available because pylibseekdb is not available.
+Please install pylibseekdb (Linux only) or use RemoteServerClient (host/port) instead.
+```
+
+**Cause**: `pylibseekdb` is only available on Linux platforms.
+
+**Solution**: Use server mode instead:
+1. Deploy SeekDB on a Linux server or VM
+2. Configure LangBot to use server mode:
+```yaml
+vdb:
+  use: seekdb
+  seekdb:
+    mode: server
+    host: 'your-seekdb-server-ip'
+    port: 2881
+    database: 'langbot'
+    user: 'root'
+    password: ''
+```
+
+**Alternative**: Use ChromaDB or Qdrant, which work on all platforms:
+```yaml
+vdb:
+  use: chroma  # or qdrant
+```
+
+### Docker Container Fails on macOS
+
+**Symptoms**:
+```bash
+docker run -d -p 2881:2881 oceanbase/seekdb:latest
+# Container exits immediately with code 30
+```
+
+**Error in logs**:
+```
+[ERROR] Code: Agent.SeekDB.Not.Exists
+Message: initialize failed: init agent failed: SeekDB not exists in current directory.
+```
+
+**Cause**: This is a known issue with SeekDB Docker containers on macOS. See [oceanbase/seekdb#36](https://github.com/oceanbase/seekdb/issues/36).
+
+**Status**: Under investigation by OceanBase team.
+
+**Workaround Options**:
+1. **Use alternatives**: ChromaDB or Qdrant work perfectly on macOS
+2. **Remote server**: Deploy SeekDB on a Linux server and connect remotely
+3. **Wait for fix**: Monitor the GitHub issue for updates
+
+### Connection Error (Server Mode)
+
+If SeekDB server is not reachable, check:
+1. Server is running: `ps aux | grep observer`
+2. Port is accessible: `nc -zv localhost 2881`
+3. Credentials are correct in config
+4. Firewall allows connections on port 2881
+
+### Performance Issues
+
+For large datasets:
+- Use server mode instead of embedded mode
+- Ensure adequate memory allocation
+- Consider using OceanBase distributed mode for very large scale
+- Adjust HNSW index parameters if needed
+
+## Resources
+
+- SeekDB GitHub: https://github.com/oceanbase/seekdb
+- pyseekdb SDK: https://github.com/oceanbase/pyseekdb
+- OceanBase Documentation: https://oceanbase.ai
+- LangBot Documentation: https://docs.langbot.app
+
+## License
+
+SeekDB is licensed under Apache License 2.0.

docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md

@@ -0,0 +1,149 @@
+# Agent-owned Context 协议设计
+
+本文档描述插件化 AgentRunner 场景下的上下文边界**设计理由**。结论先行：LangBot 不应成为最终 agentic context manager；它提供 context substrate，AgentRunner 或其背后的 runtime 自己决定如何管理历史、压缩、召回和 KV cache。
+
+> 涉及的数据结构（`AgentRunContext`、`ContextAccess`、`AgentRunAPIProxy` 等）唯一定义在 [PROTOCOL_V1.md](./PROTOCOL_V1.md)。本文只讲语义和约束，不重抄 schema。
+
+## 1. 设计原则
+
+### 1.1 Agent 拥有上下文策略
+
+不同 runner 背后的 runtime 差异很大：
+
+- 官方 local-agent 可能依赖 LangBot 的模型、工具、知识库和存储。
+- Claude Code SDK / Codex 类 runtime 有自己的 session、transcript、tool loop 和上下文压缩。
+- Pi Agent SDK 或外部 agent 平台可能只需要当前事件和一个外部 conversation key。
+
+因此 LangBot 不应强行决定最终传给模型的历史窗口。Host 只提供：当前事件的完整结构化信息、稳定身份和会话引用、可授权读取的 history / event / state API、sandbox/workspace 文件能力、可投影给外部 harness 的 scoped context / SDK-owned MCP bridge / resource handles、payload hard cap 和权限 guardrail。
+
+### 1.2 Host 不定义通用历史窗口
+
+历史窗口策略不是 AgentRunner 协议或 Query entry adapter 的核心概念。Host 只提供 history pull API、cursor、hard cap 和权限边界；runner 自己决定是否读取、读取多少、如何截断和压缩。
+
+正确的问题不是"LangBot 每轮裁几轮历史给 agent"，而是：
+
+- 这类 runner 是否自管 context？
+- 事件到来时 host 应 inline 哪些最小信息？
+- agent 需要更多上下文时通过什么 API 拉取？
+- host 如何保证安全、可审计和可分页？
+
+### 1.3 Host 保存事实源，Agent 管理 working context
+
+三类数据要分开：
+
+- `EventLog`: Host 保存原始事件、工具调用、投递结果、错误和系统事件。
+- `Transcript`: Host 从 EventLog 投影出的对话视图，用于 UI、审计和按需历史读取。
+- `Working context`: Agent 本轮实际送进模型或 runtime 的上下文，由 AgentRunner 决定。
+
+LangBot 不提供 host-side inline history window。简单 runner 如果需要历史窗口，应在 runner 内部通过 Host history API 拉取并裁剪。
+
+## 2. Event 到来时传什么
+
+默认 `AgentRunContext`（PROTOCOL_V1 §5.2）应尽量小且稳定。默认规则：
+
+- Host MUST NOT inline full history by default.
+- Host SHOULD inline only current event / input and context handles.
+- Runner owns working-context assembly.
+- Runner MAY use Host history / event / state / storage API and sandbox/workspace file tools when authorized.
+- Official runners MUST consume Host infrastructure through the same public API as third-party runners.
+
+### 2.1 必须 inline 的内容
+
+当前 event 的类型/id/时间/source；当前输入文本和结构化内容；附件/文件/图片的 metadata、path 或 URL；actor / subject / conversation / thread / bot / workspace；delivery 能力；已授权资源列表；context cursors 和可用 API 能力；Agent/runner config。这些是 agent 决定下一步所需的最低信息。
+
+### 2.2 默认不 inline 的内容
+
+完整历史消息、大文件全文、大工具结果、全量知识库内容、平台原始 payload 大对象、每轮重新生成的大段 summary。这些会破坏跨进程序列化成本、泄露范围、KV cache 稳定性，也会迫使 host 替 agent 做 context 策略。
+
+### 2.3 不提供 Host Inline History Window
+
+`AgentRunContext` 不包含 `bootstrap` 字段。Host 不下发历史窗口，也不通过 Pipeline 配置决定窗口大小。runner 若需要类似 `recent_tail` 的策略，应在自己的 manifest/config schema 中声明参数，并在 runner 内部通过 history API 读取、裁剪和压缩。Host 只负责权限、分页、hard cap 和事实源。
+
+## 3. ContextAccess 的作用
+
+`ContextAccess`（PROTOCOL_V1 §5.8）是 host 交给 agent 的上下文读取入口描述，告诉 agent：当前事件位于哪条 conversation / thread、若需要更多历史从哪个 cursor 开始拉、host inline 了什么没 inline 什么、当前 run 有哪些 context API 权限。
+
+## 4. Agent 如何获取更多上下文
+
+所有 API 都走 `AgentRunAPIProxy`（PROTOCOL_V1 §8），由 host 用 `run_id` 校验。
+
+外部 harness 不能直接访问 LangBot 资源。无论是 history、event、state、model、tool、knowledge base，还是 LangBot skills，都必须通过 SDK runtime 转发到 Host API，并由 Host 按 active `run_id`、runner identity、binding resource policy 和 caller plugin identity 校验。当前运行文件进入授权 sandbox/workspace 后，再由 runner 用 read/write/exec 类工具按需访问。harness 自己的 native tools 只属于 harness 执行环境，不能绕过 SDK runtime 访问 LangBot 内部资源。
+
+### 4.1 History
+
+```python
+await api.history_page(conversation_id=ctx.context.conversation_id,
+                       before_cursor=ctx.context.latest_cursor,
+                       limit=50, direction="backward", include_attachments=False)
+```
+
+返回 `HistoryPage`（schema 见 PROTOCOL_V1 §8）。
+
+约束：`limit` 有 host hard cap；默认只能读当前 conversation / thread；跨会话读取需 binding policy / run authorization snapshot 授权；可返回 attachment ref，不默认返回大文件内容。
+
+### 4.2 Search
+
+```python
+await api.history_search(query="用户之前提到的数据库连接信息",
+                         filters={"conversation_id": ..., "event_types": ["message.received"]},
+                         top_k=10)
+```
+
+Search 可先用数据库全文索引，后续接 embedding recall。它是 host 检索能力，不等于 agent 的长期记忆策略。
+
+### 4.3 Event / State
+
+- Event API（`events.get` / `events.page`）用于读取非消息事件、工具事件、系统事件。Agent 不应把所有事件都当成 user/assistant message。
+- State API（`state.get` / `set`）是可选寄宿能力。自管 runtime 可以完全不用；依附 LangBot 的官方 runner 可以使用，例如 `external.session_id`、`summary.checkpoint`。
+
+### 4.4 大文件与工具协作
+
+大文件、多模态输入和工具产物不要内联进 prompt 或 tool result：message/content 里只放小文本和必要摘要；当前事件附件由 Host staged 到授权 sandbox/workspace，并在 input attachment 中给出轻量 metadata/path。工具之间传递大结果时传 sandbox path 或 attachment ref，不传完整 blob。Host 只保证当前 run 授权范围，默认不允许插件直接读任意本地路径；临时文件由 sandbox 生命周期和清理机制管理。
+
+### 4.5 External harness context projection
+
+外部 harness 的总体边界以 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md) §4.8 为准。本节只描述 context projection 的推荐形态。
+
+Claude Code、Codex、Kimi Code 这类 runtime 通常已有自己的 session、工具 loop、MCP 加载、上下文压缩和工作目录。LangBot 不应把它们改造成"host prompt assembler"，而应提供可审计的事件和资源投影。推荐 projection 形态：
+
+- `agent-context.json`：结构化 JSON，包含 `run_id`、`event`、`actor`、`subject`、`input`、`delivery`、`resources`、`context`、`state`、`runtime`。
+- `LANGBOT_CONTEXT.md`：人类可读摘要。
+- `resources`：只包含本次 run 授权后的资源句柄和能力摘要，不暴露 Host 内部私有对象、secret 或资源内容。
+- `skills`：LangBot skills 不是直接投影给 harness native tool loop 的文件能力；已授权 skill 应由 Host / sandbox 封装成 scoped tools，再通过 `ctx.resources.tools`、`AgentRunAPIProxy` 或 SDK-owned MCP bridge 暴露。
+- `MCP config`：只投影 per-run、scoped 的 SDK-owned bridge 或外部 MCP 连接配置；LangBot 资源访问必须回到 SDK runtime / Host API，不允许 harness 通过自带 MCP/native tool 直接读 Host 内部资源。
+- `state pointers`：外部 session id、working directory、checkpoint 等小型 JSON 状态通过 Host state API 保存。
+
+当前官方外部 harness 路径由 ACP / Claude Code / Codex 等 runner 插件承担（现状见 OFFICIAL_RUNNER_PLUGINS §7）。这类 projection 是"把 LangBot 事实源和授权资源句柄交给 harness"，不是"把 LangBot 资源本体或内部权限交给 harness"，也不是"由 LangBot 决定最终模型上下文"。
+
+## 5. Runner 上下文边界
+
+Host 只给当前事件、当前输入和 context handles。Runner 是否能拉取历史、事件、state 或 storage、是否能访问 sandbox/workspace 文件，以运行时 `ctx.context.available_apis` 和工具授权为准；runner 自己决定是否拉取历史、是否搜索、何时摘要、如何构造最终 prompt。
+
+## 6. KV cache 友好的上下文管理
+
+支持 Claude Code SDK、Codex、Pi Agent SDK 等 runtime 时，必须避免每轮由 LangBot 重组大块 prompt：
+
+- 稳定 session key：`workspace/bot/binding/runner/conversation/thread`。
+- 每轮只传 delta：当前 event、attachment refs/path、少量 runtime metadata。
+- 历史 append-only：不要每轮改写同一段 history 文本。
+- Summary checkpoint 稳定：只有压缩发生时产生新 checkpoint。
+- 大文件和工具结果写入 sandbox/workspace。
+- Tool/context API schema 稳定，数据通过 API 拉取而非塞入 prompt。
+- 对自管 runtime，优先让它复用自身 session/cache，而不是强制 LangBot 每轮重放 transcript。
+- 模型窗口元信息应作为 resource/runtime metadata 暴露给 runner，由 runner 决定预算和压缩策略。
+
+稳定 session key 的用途是隔离外部 runtime 的 resume/cache/state，不是改变 PROTOCOL_V1 §13 定义的 Agent 复用和 dispatch 边界。只有当某个外部 harness 的同一 native session 不支持并发 turn 时，runner 或 future runtime control plane 才应按 external session key 做 turn-level 串行化。
+
+对长期运行的 external harness / daemon，推荐运行形态是 reader 与 writer 分离：一个 session reader 独占读取 stdout/SSE/native event stream，并把 native event 转成 `AgentRunResult` 或 task progress；用户输入只作为 turn write 进入该 session。当前一次性 CLI subprocess runner 可以继续在单次 `run(ctx)` 内同步收集 stdout，但后续改成长连接时不应让多个 request 同时读取同一 native stream。
+
+## 7. Host guardrail
+
+Agent 自管 context 不代表无限制访问。LangBot 仍必须控制：每次 run 的 active `run_id`、runner identity、当前 binding 的 resource policy、conversation / actor / subject scope、page size / sandbox file read size / API rate limit、跨会话读取权限、数据脱敏和敏感变量过滤、审计日志。Host 不负责"最佳上下文策略"，但负责"不越权、不爆内存、不不可审计"。
+
+外部 harness 的 native tools、shell、MCP 或 skill 机制不构成 LangBot 资源授权边界。只要访问的是 LangBot 持有的资源，就必须经 SDK runtime 转发并接受 Host 校验；完整边界见 HOST_SDK §4.8。
+
+## 8. 官方 runner 与业务编排边界
+
+官方 runner 插件可以把状态寄宿在 LangBot，但必须和第三方 runner 一样通过公开 Host API 消费。LangBot core 不内置官方 agent 的业务流程（prompt 组装、tool loop、RAG 编排、summary/compaction、"local-agent 专用"状态字段）。
+
+官方 local-agent 应作为"依附 LangBot 基础设施的复杂 runner 参考实现"：transcript/history 通过 `api.history_page()` / `api.history_search()` 读取，summary/checkpoint/外部 session id/用户偏好通过 `api.state_get()` / `api.state_set()` 或 storage 方法保存，图片/文件/工具大结果通过 sandbox/workspace read/write 工具访问，模型/工具/知识库通过 `api.invoke_llm()` / `api.call_tool()` / `api.retrieve_knowledge()` 调用。这样 LangBot 保持为通用 agent host，不变成内置 agent 框架。具体迁移要求见 [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md)。

docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md

@@ -0,0 +1,227 @@
+# Agent Runner QA 指南
+
+本文档是 agent-runner 插件化下一轮测试的唯一 QA 入口。它合并并取代旧的 Phase 1 验收矩阵与 2026-05-18 / 2026-05-29 两份本地 QA 报告。
+
+目标不是保留完整历史流水账，而是指导测试 agent 用最小但高价值的路径判断当前分支是否仍然健康。
+
+## 1. 测试边界
+
+当前主线验证的是 AgentRunner Protocol v1：
+
+```text
+event -> binding -> runner.run(ctx) -> result stream
+```
+
+本指南验证：
+
+- Host 能通过当前 Query entry adapter 进入 event-first `run(event, binding)` 主链路。
+- Runner 来自插件 registry，而不是旧内置 runner 分支。
+- `local-agent` 能消费 Host 模型、工具、知识库、history、state、sandbox 文件等基础设施。
+- 外部 harness runner（ACP / Claude Code / Codex 等直接 runner 插件）能消费 event-first context，并把外部 session 指针写回 host-owned state。
+- 错误、权限裁剪、无输出、timeout 等路径不会破坏主聊天流程。
+
+本指南不验证：
+
+- Runtime Control Plane v2。
+- EventGateway / EventRouter 完整落地由外部 EBA 分支联调；本指南只验证本分支 Host 底座。
+- 发布级 path isolation、secret filtering、MCP allowlist、资源配额和 workspace cleanup。
+- 所有外部服务 runner 的真实凭据联调。
+
+这些属于后续能力或发布门槛，分别见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md) 与 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。
+
+## 2. 状态定义
+
+测试报告只使用以下状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| PASS | 按步骤执行，用户可见行为和日志证据都满足通过条件。 |
+| FAIL | 环境可用，但行为不满足通过条件。 |
+| BLOCKED | 凭据、CLI、外部服务、测试数据或本地配置缺失导致无法执行。必须写清阻塞原因。 |
+| N/A | 当前 runner 或平台明确不支持该能力。必须引用 manifest、文档或配置说明。 |
+
+不能使用“看起来正常”“大概通过”“基本没问题”等模糊状态。
+
+## 3. 执行顺序
+
+推荐按以下顺序执行，前一层失败时不要继续扩大测试面：
+
+1. Host / SDK / runner 单测。
+2. WebUI 登录与 Pipeline Debug Chat 基础 smoke。
+3. `local-agent` 高价值场景。
+4. 外部 code-agent harness smoke。
+5. 权限和错误路径补充检查。
+6. 汇总 PASS / FAIL / BLOCKED，并给出下一步建议。
+
+用户可见流程必须通过 WebUI 或真实消息平台验证。API / curl 只能作为诊断证据，不能单独让 UI case PASS。
+
+## 4. 必跑基线
+
+### 4.1 单测基线
+
+在 LangBot 仓库运行：
+
+```bash
+uv run --frozen pytest tests/unit_tests/agent
+```
+
+如果本次改动只触及默认配置或 API service，也至少补跑相关目标测试，例如：
+
+```bash
+uv run pytest tests/unit_tests/api/test_pipeline_service_defaults.py
+```
+
+通过条件：
+
+- agent 单测全 PASS，或失败项已确认与本次 agent-runner 路径无关。
+- 若失败来自 `context_builder`、`orchestrator`、`session_registry`、`resource_builder`、`plugin/handler.py` 的 run action 权限路径，不应进入 UI smoke。
+
+### 4.2 环境基线
+
+用 `langbot-skills` 做环境检查：
+
+```bash
+cd "$LANGBOT_SKILLS_REPO"
+bin/lbs env doctor
+bin/lbs case list
+```
+
+`LANGBOT_SKILLS_REPO` 指向当前工作区里的 `langbot-skills` 仓库。优先使用已有 case，而不是临时发明测试路径。
+
+推荐首批 case：
+
+- `webui-login-state`
+- `pipeline-debug-chat`
+- `local-agent-basic-debug-chat`
+- `local-agent-rag-debug-chat`（改动涉及 RAG / knowledge）
+- `local-agent-plugin-tool-call-debug-chat`（改动涉及 tool / resource policy）
+
+## 5. WebUI 主链路 Smoke
+
+### 5.1 Runner registry
+
+步骤：
+
+1. 打开 WebUI Pipeline 配置页。
+2. 查看 AI runner 下拉列表。
+3. 选择 `plugin:langbot/local-agent/default`。
+4. 保存并刷新页面。
+
+通过条件：
+
+- runner 选项来自插件 registry。
+- 保存后配置仍为 `ai.runner.id` + `ai.runner_config[id]`。
+- `runner_config` 表示 Agent/runner config，不表示插件实例状态。
+- 不读取或回写旧 `ai.runner.runner` 字段。
+- 不出现旧内置 runner stage 名（例如裸 `local-agent`）作为当前选中项或配置 surface。
+- 插件没有循环重启或 metadata 加载失败。
+
+### 5.2 主聊天路径
+
+步骤：
+
+1. 使用绑定 `plugin:langbot/local-agent/default` 的 Pipeline。
+2. 在 Debug Chat 发送确定性普通文本。
+3. 查看 WebUI 回复和后端日志。
+
+通过条件：
+
+- 用户可见回复正常。
+- 后端日志显示走 `AgentRunOrchestrator` / `RUN_AGENT`。
+- 不走旧内置 local-agent 主执行分支。
+- conversation transcript 写入用户消息和助手消息。
+
+## 6. `local-agent` 高价值测试
+
+只保留最能覆盖架构边界的场景。
+
+| ID | 场景 | 操作 | 通过条件 |
+| --- | --- | --- | --- |
+| LA-01 | 绑定 prompt | 配置 system prompt 后发送文本。 | runner 使用 `ctx.config.prompt`，不读取 `ctx.adapter.extra["prompt"]`；回复体现绑定 prompt。 |
+| LA-02 | history API | 连续两轮对话，第二轮引用第一轮 marker。 | runner 通过 Host history API 或自管上下文读取历史，不依赖 inline history window。 |
+| LA-03 | 流式 / 非流式 | 分别用支持流式和关闭流式的路径发送文本。 | 流式 UI 不重复、不空白；非流式只输出最终消息。 |
+| LA-04 | 工具调用 | 绑定测试工具，发送会触发工具的 prompt。 | `ctx.resources.tools` 只包含授权工具；工具调用 started/completed；最终回复包含工具结果。 |
+| LA-05 | RAG | 绑定测试知识库，发送命中文档的 prompt。 | `ctx.resources.knowledge_bases` 包含所选知识库；runner 通过授权 API 检索；回复使用检索内容。 |
+| LA-06 | 多模态 | 发送图片输入。 | `ctx.input.contents` 保留图片；支持视觉模型时正常处理，不支持时受控失败。 |
+| LA-07 | fallback / 错误 | 模拟 primary 模型失败或 runner 抛错。 | fallback 或 `run.failed` 行为受控；后续请求不受影响。 |
+| LA-08 | 无输出保护 | 测试 runner 完成但不产出消息。 | 不产生空白成功回复；按受控失败或明确缺陷处理。 |
+| LA-09 | steering / 运行中追加消息 | 使用支持 steering 的 runner，第一条消息触发长 run；run 未结束时在同 conversation 追加第二条消息。 | 第二条消息被 active run claim，不启动并发 run；runner 通过 `steering_pull` 看到追加输入；EventLog 有 `queued` -> `steering.injected`，若未消费则有 `steering.dropped` 终态；后续普通消息仍可处理。 |
+
+Rerank、remove-think、文件输入等场景只在本次改动直接涉及时补测，不作为每轮必跑项。
+
+## 7. Code-agent Harness Smoke
+
+这些测试用于验证 ACP、Claude Code、Codex 这类自管 runtime 能走同一条 Host 协议路径。若目标 harness 没有 CLI/daemon、登录态、代理配置或远端 workspace，标记 BLOCKED，不要伪造 PASS。
+
+Smoke 前应优先保留一层轻量单测或 fixture 测试：session 创建/复用、消息发送、结果解析、`run_id` 注入和 LangBot MCP gateway 必须有稳定测试覆盖。WebUI smoke 证明真实链路可用，但不能替代转换层和错误映射测试。
+
+### 7.1 外部 harness runner
+
+步骤：
+
+1. 确认目标 harness（例如 ACP daemon、Claude Code 或 Codex）在对应机器上可执行且已登录。
+2. 绑定目标 runner，例如 `plugin:langbot/acp-agent-runner/default`、`plugin:langbot/claude-code-agent/default` 或 `plugin:langbot/codex-agent/default`。
+3. 配置 runner 必要字段，例如 remote target、workspace、provider、startup timeout、reuse session 等。
+4. 在 Debug Chat 执行一次确定性真实 smoke。
+5. 检查 LangBot MCP gateway、`run_id` 回填和 host-owned state。
+
+通过条件：
+
+- WebUI 可见回复包含预期 sentinel。
+- 发送给 harness 的消息包含当前 LangBot `run_id` 和可访问资源摘要。
+- Harness 通过 gateway 调用 `langbot_history_page`、`langbot_retrieve_knowledge` 或 `langbot_call_tool` 时必须携带正确 `run_id`；错误 run id 被拒绝。
+- `external.session_id` 写入 host-owned state。
+- 外部 harness 错误、timeout、empty output 都转成受控 `run.failed`。
+- resume 到同一 external session 时，全局锁边界符合 PROTOCOL_V1 §13。
+
+### 7.2 API 型外部 runner
+
+Dify、n8n、Coze、DashScope、Langflow、Tbox 等外部服务 runner 不作为每轮必跑项。只有在本次改动触及对应 runner 或凭据已经可用时执行 smoke。
+
+通过条件：
+
+- runner 可选，配置可保存。
+- 请求成功，或外部服务错误被清晰返回。
+- 外部服务凭据缺失时标记 BLOCKED，并记录缺失项。
+
+## 8. 权限与隔离补充
+
+以下优先用单测 / targeted fixture 覆盖，不要求每次通过 UI 人工构造恶意 runner。
+
+| 场景 | 推荐证据 |
+| --- | --- |
+| 未授权模型调用被拒绝 | `plugin/handler.py` run action 权限测试或目标单测。 |
+| 未授权工具调用被拒绝 | `ctx.resources.tools` 与 host action 拒绝日志。 |
+| 未授权知识库检索被拒绝 | `ctx.resources.knowledge_bases` 与 host action 拒绝日志。 |
+| run_id 结束后复用被拒绝 | session registry 注销测试。 |
+| 插件身份不匹配被拒绝 | `caller_plugin_identity` mismatch 测试。 |
+| 绑定插件身份的 run_id 省略 caller identity 被拒绝 | `_validate_run_authorization(..., caller_plugin_identity=None)` 返回错误。 |
+| 未注册 Runtime 连接伪造插件身份被剥离 | SDK runtime forwarding 测试：请求自带 `caller_plugin_identity` 时，未注册连接转发前必须 `pop`，已注册连接必须覆盖为真实插件身份。 |
+| storage/state scope 越权被拒绝 | state/storage proxy 单测。 |
+| steering claim 异常不杀 consumer loop | controller 单测：无效 runner / registry 异常只让当前消息回到普通 session 槽位路径，消息消费循环继续。 |
+| steering queue 未消费有终态 | session registry / orchestrator 单测：队列有上限；run unregister 时未 pull 项写 `steering.dropped` 审计。 |
+
+如果这些单测失败，不能用 WebUI 正常回复替代。
+
+## 9. 证据要求
+
+每轮测试报告至少记录：
+
+- LangBot commit、SDK commit、相关 runner 插件 commit。
+- Pipeline UUID/name、runner id、关键 runner config 摘要。
+- WebUI 截图或 Playwright 操作记录。
+- 后端日志中对应 query id / run id 的关键行。
+- `langbot-skills` case/report 路径。
+- 外部 harness runner 的 context 文件、session id、working directory、CLI 错误摘要。
+- FAIL/BLOCKED 的复现步骤和归属仓库建议。
+
+报告结论必须回答：
+
+- 是否建议继续进入下一阶段测试。
+- 是否存在主聊天路径阻塞。
+- 是否只是凭据 / 外部服务 / 本机 CLI 缺失导致 BLOCKED。
+- 是否需要进入 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) 的发布级验收。
+
+## 10. 历史高价值记录
+
+历史高价值记录与当前 runner 验收状态见 [STATUS.md](./STATUS.md)。本指南只保留可重复执行的测试步骤和证据要求。

docs/agent-runner-pluginization/EVENT_BASED_AGENT.md

@@ -0,0 +1,92 @@
+# Event Based Agent 接入设计
+
+> 本文记录 EBA 如何接入当前 AgentRunner Protocol v1 / Host 底座。EventGateway、EventRouter、Event subscription/notification 由外部 EBA 分支实现并联调；本分支只保留 event-first 入口和 envelope/binding models。
+>
+> 数据结构唯一定义在 [PROTOCOL_V1.md](./PROTOCOL_V1.md)（runner 可见）与 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md)（Host 内部模型）；本文只讲 EBA 语义，不重抄 schema。
+> 与当前 runner 外化分支、后续 Agent Platform / Runtime Control Plane 的边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。
+
+本文描述 EBA 接入时，事件如何进入 LangBot、如何触发 AgentRunner，以及如何复用插件化 agent 基础设施。本分支不实现完整 EventBus / EventRouter / Platform API；这些能力正在外部 EBA 分支联调。这里的目标是把协议边界说清楚，避免当前消息入口继续绑死 Pipeline 和用户文本消息。
+
+## 1. 设计目标
+
+- 消息、撤回、入群、好友申请、定时任务、API 调用都能抽象为 host event。
+- EventRouter 可以根据 event type、bot、workspace、conversation、actor、subject 解析 `AgentBinding`。
+- AgentRunner 通过同一套 orchestrator 被调用。
+- 非消息事件不伪造成用户文本消息。
+- 平台动作执行通过显式 capability / permission / result type 预留，不混入普通文本回复。
+
+## 2. 事件不是消息
+
+`message.received` 只是事件的一种。协议不应假设：一定有用户文本、一定有 conversation history、一定要返回一条聊天消息、actor 一定等于 sender、subject 一定等于当前消息。
+
+| event_type | actor | subject | input |
+| --- | --- | --- | --- |
+| `message.received` | 发消息的人 | 当前消息 | 文本、图片、文件等 |
+| `message.recalled` | 撤回操作者，未知时为系统 | 被撤回消息 | 通常为空 |
+| `group.member_joined` | 新成员或邀请人 | 群/成员关系 | 通常为空 |
+| `friend.request_received` | 申请人 | 好友申请 | 验证消息或申请理由 |
+| `schedule.triggered` | 系统 | 定时任务 | 任务 payload |
+| `api.invoked` | API caller | API request | request payload |
+
+## 3. 稳定事件名
+
+先保留的稳定事件名（作为插件协议的一部分保持稳定）：
+
+- `message.received`
+- `message.recalled`
+- `group.member_joined`
+- `friend.request_received`
+
+平台原始事件名只能进入 `ctx.event.source_event_type` / `raw_ref`，不能成为 `ctx.event.event_type` 的公共契约。
+
+## 4. Event Envelope 与 Binding
+
+- 入口事件用 `AgentEventEnvelope`（HOST_SDK §4.1）承载；顶层字段使用 LangBot 稳定协议名，平台原始事件名和原始 payload 放 `metadata` / `raw_ref`。
+- 触发关系用 `AgentBinding`（HOST_SDK §4.2）表达。EBA 阶段 binding 通过 `event_types`、`scope`、`filters` 决定哪些事件触发当前 bot / channel 绑定的 Agent。
+
+EBA dispatch 基数、Agent 复用和 fan-out 边界以 PROTOCOL_V1 §13 为准；本节只说明外部 EBA 分支的 EventRouter 如何产出当前 v1 主线需要的 binding。
+
+Binding scope 示例：workspace 全局、bot 级、platform channel 级、conversation / group / thread 级、user / actor 级。旧 Pipeline 可迁移为 `message.received` 的临时 binding source，但目标持久配置应是 Agent，不是 Pipeline。
+
+Event Source 可包括：`platform_adapter`（飞书、QQ、微信、Telegram 等）、`webui`、`http_api`、`scheduler`、`system`。EventRouter 不应写死平台 adapter 的类名。
+
+## 5. EventRouter 调用链
+
+```text
+Platform Adapter / WebUI / API
+  -> Event Gateway normalize payload
+  -> EventLog append raw event
+  -> EventRouter resolve one effective AgentBinding
+  -> AgentRunOrchestrator.run(event, binding)
+  -> AgentRunContextBuilder.build(event, binding)
+  -> PluginRuntimeConnector.run_agent()
+  -> AgentRunResult stream
+  -> DeliveryController render / platform action
+```
+
+约束：必须复用现有 orchestrator，不能为 EBA 单独实现另一套 plugin runner 调用协议；非消息事件不能绕过 resource authorization；delivery 和 platform action 走统一权限模型；外部 harness runner 也通过同一套 envelope/binding/context/result 协议接入，不为 Claude Code / Codex / Kimi 单独发明队列协议。observer / fan-out / parallel arbitration 的额外语义仍按 PROTOCOL_V1 §13 处理。
+
+## 6. 平台动作执行
+
+EBA 后 `action.requested`（PROTOCOL_V1 §7.3，当前仅 telemetry 不执行）将用于请求 host 执行平台动作：
+
+```json
+{ "type": "action.requested",
+  "data": { "action": "friend.request.accept",
+            "target": {"platform": "wechat", "request_id": "..."},
+            "payload": {"reason": "policy matched"} } }
+```
+
+Host 必须校验：binding / platform action policy 是否授权该 action、actor / bot / workspace 是否允许、是否需要人工审批，以及当前 run session / caller identity 是否匹配。EBA 还可能预留 `delivery.requested`（请求投递到某 surface）。
+
+Delivery 方面，event 不一定回复到当前聊天窗口：消息事件通常带 reply target；系统事件可能没有默认 reply target，需要 runner 返回 `action.requested` 或由 binding 的 delivery policy 决定投递位置（`DeliveryContext` 见 PROTOCOL_V1 §5.7）。
+
+## 7. 与 Context 协议的关系
+
+EBA 事件进入 AgentRunner 时仍遵循 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)：inline 当前事件、大 payload 用 raw/staged file ref、不默认 inline 完整 history、agent 按需通过 API 拉取、Host 保留 EventLog 和权限 guardrail。非消息事件可以被投影进 Transcript，但不能强制伪装为 user message；AgentRunner 根据 event type 自己决定是否纳入模型上下文。
+
+## 8. EBA 分支联调内容
+
+外部 EBA 分支负责联调 EventGateway 完整实现、EventRouter 与 BindingResolver 集成、`AgentBinding` 持久模型和 UI、`DeliveryContext` 完整实现、platform action permission model 和执行器、真实平台事件接入。
+
+当前底座已完成：① 把当前 Pipeline 消息入口适配成 `message.received` event → ② 增加 `AgentBinding` 抽象，先由 current config 生成 → ③ context builder 改为从 event + binding 构造 → ④ 引入 EventLog / Transcript。外部 EBA 分支在此基础上联调：⑤ 非消息事件协议测试与真实事件来源 → ⑥ 真实 EventRouter、binding persistence / UI 和 platform action。

docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md

@@ -0,0 +1,51 @@
+# AgentRunner 外化扩展边界矩阵
+
+本文用于回答一个问题：本分支只做 AgentRunner 外化时，哪些能力已经作为扩展底座完成，哪些由外部 EBA / Agent Platform / Runtime Control Plane 分支接入，后续分支接入时应该走哪个扩展点。
+
+结论：本分支不实现完整 Agent Platform，也不实现完整 EBA。EBA 完整事件网关与事件路由由外部 EBA 分支联调。本分支必须把 runner 外化的 Host / SDK 边界做干净，让外部分支只需要接入持久模型、事件路由或 runtime task，而不需要重写 `AgentRunner Protocol v1`。
+
+调度基数、Agent 复用、插件实例无状态、Pipeline adapter 和 fan-out 边界的单一事实源是 [PROTOCOL_V1.md](./PROTOCOL_V1.md) §13；本矩阵只说明后续能力应该接入哪个扩展点。
+
+## 1. 分支边界
+
+| 范围 | 本分支职责 | 不在本分支做 |
+| --- | --- | --- |
+| AgentRunner Protocol v1 | 定义 Host 调用 runner 的稳定合同：discovery、`AgentRunContext`、result stream、Host pull API、错误和权限边界。 | 不定义 Agent Platform 的产品数据库模型；不定义 runtime task queue。 |
+| Host runner 外化底座 | 提供 `AgentEventEnvelope`、`AgentBinding` 运行投影、`run(event, binding)`、resource authorization、run-scoped session、EventLog / Transcript / State / sandbox 文件边界。 | 不实现 EventGateway、scheduler、integration provider、Agent 管控面 UI。 |
+| 当前 Pipeline 入口 | 通过 `QueryEntryAdapter` 把旧 Query / Pipeline config 投影成 event + binding，作为迁移期入口。 | 不继续把 Pipeline 当作长期 agent 配置中心。 |
+| 官方 runner 插件 | 作为协议消费者验证 local-agent / 外部 harness runner 能接入 Host 基础设施。 | 不让官方 runner 的内部实现反向决定 Host / SDK 协议形态。 |
+
+## 2. 扩展矩阵
+
+| 能力 | 当前分支状态 | 后续归属 | 后续接入方式 | 禁止事项 |
+| --- | --- | --- | --- | --- |
+| Product `Agent` | 已有运行期 `AgentConfig` / `AgentBinding` 投影；还没有正式持久化产品对象。 | Agent Platform / binding persistence UI。 | 持久 Agent 保存 runner id、runner config、resource/state/delivery policy；运行前投影为 `AgentBinding`。 | 不把持久 Agent schema 加进 SDK 协议；插件实例边界见 PROTOCOL_V1 §13。 |
+| Bot / channel 绑定 Agent | 已有单次运行前的 `AgentBinding` 解析投影；目标调度语义见 PROTOCOL_V1 §13。 | EBA / Agent Platform。 | EventRouter 根据 bot、channel、workspace、conversation、event type 解析有效 `AgentBinding`。 | 不在本矩阵重定义 fan-out / observer 语义；需要时按 §3 新增设计。 |
+| Agent session / run | 当前只有 `run_id` 和 active `AgentRunSessionRegistry`，用于权限校验和生命周期。 | Agent Platform / Runtime Control Plane。 | 如需要可新增持久 `AgentRun` / `AgentSession` / task 表，但执行仍回到 `run(event, binding)` 或 runtime-managed 等价入口。 | 不把持久 session 字段塞进 `AgentRunContext` 顶层；不要求所有 runner 长期持有 LangBot session。 |
+| EventLog / Transcript / Sandbox files | 已完成 Host-owned store、history pull API 和 sandbox 文件边界；runner 不直接写 DB。 | 本分支持续维护底座；Agent Platform 可复用。 | 外部 EBA、scheduler、integration、runtime task 都写同一套 EventLog / Transcript；当前 run 文件通过 sandbox/workspace staging 共享。 | 不让 runner / sandbox 直接访问 Host DB；不把大 payload 内联进 prompt。 |
+| Host-owned state / storage | 已有 state snapshot、`state.updated` 处理和 State API；storage 作为授权能力保留。 | 本分支持续维护底座；Runtime / Platform 可复用。 | 外部 session id、working directory、checkpoint 等小 JSON 用 state；当前 run 大对象用 sandbox/workspace 文件。 | 不把跨轮次状态存在插件实例内；不绕过 run-scoped authorization。 |
+| EventGateway / EventRouter | 本分支只提供 event-first envelope 和 `run(event, binding)` 入口。 | EBA 分支（联调中）。 | EventGateway 规范化平台/WebUI/API/scheduler 事件；EventRouter 解析一个 binding；调用现有 orchestrator。 | 不为 EBA 新增另一套 runner 调用协议；不把非消息事件伪装成 user message。 |
+| Scheduler / Automation | 不实现。文档中只把 `scheduler` 作为 future event source。 | EBA / Agent Platform。 | 定时任务触发 `schedule.triggered` host event，复用 EventGateway -> EventRouter -> `run(event, binding)`。 | 不直接调用某个 runner 插件；不绕过 EventLog / authorization。 |
+| Integration provider | 不实现。IM platform adapter 仍是当前平台接入系统。 | EBA / Agent Platform。 | OAuth/webhook/outbound provider 应先转成 canonical host event 或 platform action，再交给 AgentRunner。 | 不把 Linear/Slack/GitHub 等 provider 私有 payload 扩散到 runner 协议顶层。 |
+| Platform action / delivery | `action.requested` 已预留但当前仅 telemetry，不执行。`DeliveryContext` 只作为上下文/策略投影。 | EBA / platform action executor。 | 后续 executor 校验 runner capability、binding policy、actor/bot/workspace 权限和审批后执行。 | 不让 runner 直接调用平台 adapter 私有 API；不把平台动作伪装成文本回复副作用。 |
+| Runtime registry / worker / task queue | 不实现。当前官方外部 harness 通过 ACP、远端 daemon、本机 subprocess 或外部 HTTP API runner 调用目标运行环境，不在本分支维护通用 worker。 | Runtime Control Plane v2。 | 第一阶段先补 Host-owned `AgentRun` / `AgentRunEvent` / run control primitives；完整 runtime registry、heartbeat、task queue、daemon claim、progress/audit 是后续可选阶段。 | 不把 heartbeat/task/warm pool 放进 Protocol v1；不让管理插件拥有 runtime/task 事实源。 |
+| Warm pool / reconcile / diagnose | 不实现。 | Runtime Control Plane v2 / deployment layer。 | 作为 task/runtime 的运维能力，围绕 Host-owned runtime/task/audit 表实现。 | 不把 runtime 运维语义写进普通 runner 协议；不把 pod/task 细节泄漏给普通 runner。 |
+| Agent memory | 不实现通用长期记忆产品层；提供 history/state/storage 和 sandbox 文件基础能力。 | Agent Platform 或具体 runner/plugin。 | 平台 memory 可通过 Host storage/state 或独立产品表实现，runner 通过授权 API 拉取。 | 不在 Host core 内置通用 agentic memory 策略；不默认把 memory 全量 inline 到 context。 |
+| External harness native session | ACP / Claude Code / Codex 等 runner 支持 external session id state handoff 和 LangBot resource projection。 | 官方 runner 后续增强；Runtime Control Plane v2 可接管执行。 | 外部 harness 调用继续走 `runner.run(ctx)`；如后续引入长连接/daemon 模式，按 external session key 串行 turn，reader 独占 native stream。 | 不把具体 provider native wire 变成 LangBot 协议；全局锁边界见 PROTOCOL_V1 §13。 |
+
+## 3. 后续分支接入规则
+
+外部 EBA、Agent Platform 或 Runtime Control Plane 分支接入时，默认遵守以下规则：
+
+- 新入口只生产或解析 Host 内部模型：`AgentEventEnvelope`、持久 Agent 投影出的 `AgentBinding`、以及必要的 delivery/resource/state policy。
+- runner 调用仍走 `AgentRunOrchestrator.run(event, binding)`，除非 Runtime Control Plane 明确引入 runtime-managed 执行模式；即便如此，runner 可见合同仍应保持 Protocol v1。
+- Host-owned facts 继续写入 EventLog / Transcript / State，当前 run 文件继续走 sandbox/workspace；产品层可以新增更高阶视图，但不能替代这些事实源。
+- 新能力如果需要持久化，优先加 Host-owned 表或 service；不要把事实源藏在插件 storage 或 runner subprocess 内。
+- 新 result type 可以按 Protocol v1 的演进规则增加；不能用入口 adapter 私有字段绕过 schema。
+- 任何 fan-out、observer agent、parallel arbitration、platform action execution 都必须单独定义 delivery、state conflict、approval 和 audit 语义。
+
+## 4. 与 Agent Platform 产品层的关系
+
+这里的 Agent Platform 指面向 agent 产品层的实体拆分：`Agent` 描述可配置 agent，`Session` / `SessionMessage` 描述会话事实，`Automation` 描述自动触发，`IntegrationBinding` 描述外部集成连接，`Memory` 描述长期记忆，`WarmTask` 描述预热/后台任务。这些拆分对 LangBot 后续产品层有参考价值，但不能直接搬进本分支。
+
+LangBot 当前分支的对应目标是更底层的：把 IM/WebUI/API 等入口统一投影到 Host event，把 Agent / binding 配置统一投影到 runner binding，把 runner 能力统一收束到 Protocol v1。完整 Agent Platform 可以在这个底座之上构建，而不应反过来污染本分支的 runner 外化边界。

docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md

@@ -0,0 +1,259 @@
+# LangBot Host 与 SDK 基础设施设计
+
+本文档描述 LangBot 作为 agent host 的内部能力与分层架构，以及 Host 内部模型。
+
+- SDK ↔ Host 的协议数据结构（`AgentRunContext`、`AgentRunnerManifest`、`AgentRunResult`、`AgentRunAPIProxy` 等）的**唯一定义在** [PROTOCOL_V1.md](./PROTOCOL_V1.md)；本文只引用，不重抄。
+- 测试执行入口和 smoke 记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)；安全发布门槛见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。
+- 本文定义的 Host 内部模型（`AgentEventEnvelope`、`AgentBinding`、`AgentRunnerDescriptor`）不属于 SDK 协议字段。
+
+## 1. 目标
+
+LangBot 要转为 agent host，而不是内置 runner 容器：
+
+- 接收 IM、WebUI、API 和外部 EBA 分支 EventRouter 产生的事件。
+- 根据事件、bot、workspace、scope 解析应该调用的 Agent / agent binding。
+- 发现、校验和调用插件提供的 AgentRunner。
+- 为每次 run 提供受限资源、状态、存储、上下文引用和生命周期控制。
+- 接收 AgentRunner 返回的事件流，投递到 IM、WebUI 或其他 output surface。
+
+## 2. 非目标
+
+- 不把 Pipeline 当作长期架构中心。
+- 不要求所有 AgentRunner 依赖 LangBot 的上下文管理。
+- 不要求官方 local-agent 的旧行为反向塑造 host 协议。
+- 不在 host 中实现通用 agentic prompt assembler。
+- 不强制 runner 使用 LangBot state / storage；只提供可选、受控的寄宿能力。
+- 不实现 EventGateway / EventRouter：它们由外部 EBA 分支提供并联调。本分支只定义 host-side envelope/binding models 和 `run(event, binding)` 入口。
+
+## 3. 分层架构
+
+```text
+IM / WebUI / API / EventRouter (external EBA branch)
+        |
+        v
+Event Gateway (external EBA branch)
+        |
+        v
+AgentBindingResolver
+        |
+        v
+AgentRunOrchestrator
+        |-- AgentRunnerRegistry
+        |-- AgentResourceBuilder
+        |-- AgentContextBuilder
+        |-- AgentRunSessionRegistry
+        |-- PersistentStateStore / EventLogStore / TranscriptStore
+        |-- Sandbox / workspace file tools
+        v
+Plugin Runtime / AgentRunner
+        |
+        v
+AgentRunResult stream
+        |
+        v
+Delivery / Renderer / Platform API
+```
+
+目标产品模型、单绑定调度、Agent 复用、插件实例无状态和 fan-out 边界以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) §13 为准。本文只说明 Host 如何把当前入口投影为内部模型。当前 Pipeline 只应接入在 Query entry adapter 位置：它可以继续产生 `message.received` 并投影出临时 `AgentConfig` / `AgentBinding`，但不应再拥有 runner 选择、上下文裁剪和业务 agent 执行的核心语义。EventGateway / EventRouter 由外部 EBA 分支实现并联调。
+
+## 4. LangBot 侧能力
+
+### 4.1 Event Gateway / EventRouter（External EBA Branch Integration Point）
+
+> EventGateway / EventRouter 由外部 EBA 分支实现并联调，不在本分支范围。本分支只保留 event-first 入口和 envelope/binding models。
+
+Event Gateway 将把入口统一成 host event（IM 平台消息、WebUI debug chat、API 触发、后续非消息事件），输出稳定的 `AgentEventEnvelope`（Host 内部模型）：
+
+```python
+class AgentEventEnvelope(BaseModel):
+    event_id: str
+    event_type: str
+    event_time: int | None
+    source: str
+    bot_id: str | None
+    workspace_id: str | None
+    conversation_id: str | None
+    thread_id: str | None
+    actor: ActorRef | None
+    subject: SubjectRef | None
+    input: AgentInput          # 见 PROTOCOL_V1 §5.6
+    delivery: DeliveryContext  # 见 PROTOCOL_V1 §5.7
+    raw_ref: RawEventRef | None
+    metadata: dict[str, Any] = {}
+```
+
+`AgentEventEnvelope` 是 Host 内部入口模型；投影给 runner 的是 `ctx.event`（PROTOCOL_V1 §5.4）。原始平台 payload 存为 raw event 或 staged file reference，不扩散到 runner 协议顶层。
+
+**当前 adapter source**：`QueryEntryAdapter.query_to_event(query)` 从 Query 生成 `AgentEventEnvelope`。
+
+### 4.2 AgentConfig 与 AgentBinding
+
+`AgentConfig` 是迁移期的 Host 内部 Agent 配置投影（不暴露给 SDK）。当前 Query entry adapter 从 Pipeline config 投影出它；未来持久 Agent 也应先投影成这个运行期配置，再由 BindingResolver 结合事件和 scope 解析为 `AgentBinding`。
+
+```python
+class AgentConfig(BaseModel):
+    agent_id: str | None = None
+    runner_id: str
+    runner_config: dict[str, Any] = {}
+    resource_policy: ResourcePolicy = ResourcePolicy()
+    state_policy: StatePolicy = StatePolicy()
+    delivery_policy: DeliveryPolicy = DeliveryPolicy()
+    event_types: list[str] = ["message.received"]
+    enabled: bool = True
+    metadata: dict[str, Any] = {}
+```
+
+`AgentBinding` 是"什么事件调用哪个 AgentRunner、带什么 Agent 配置"的 Host 内部运行投影（不暴露给 SDK）。它是 EventRouter / 当前 QueryEntryAdapter 在一次运行前解析出的有效绑定。
+
+```python
+class AgentBinding(BaseModel):
+    binding_id: str
+    enabled: bool
+    scope: BindingScope
+    event_types: list[str]
+    filters: list[EventFilter] = []   # EBA 阶段使用，见 EVENT_BASED_AGENT
+    runner_id: str
+    runner_config: dict[str, Any]
+    resource_policy: ResourcePolicy
+    state_policy: StatePolicy
+    delivery_policy: DeliveryPolicy
+```
+
+BindingResolver 的基数、fan-out 和冲突处理约束见 PROTOCOL_V1 §13；本节只定义 Host 内部投影形态。
+
+**当前 adapter source**：`QueryEntryAdapter.config_to_agent_config(query, runner_id)`
+先把 current config 投影为迁移期 `AgentConfig`，再由
+`AgentBindingResolver.resolve_one(event, [agent_config])` 解析出唯一
+`AgentBinding`。Pipeline 当前只是迁移期 Agent config source（AI runner config
+→ runner_config、extension preference → resource_policy、output settings →
+delivery_policy），但新设计不再把这些字段命名为 Pipeline 专属概念。
+
+### 4.3 AgentRunnerRegistry
+
+Registry 收集 runner descriptor（来自插件 runtime、开发期本地插件）：
+
+```python
+class AgentRunnerDescriptor(BaseModel):
+    id: str
+    source: Literal["plugin"]
+    label: I18nObject
+    description: I18nObject | None = None
+    plugin_author: str
+    plugin_name: str
+    runner_name: str
+    capabilities: AgentRunnerCapabilities    # 见 PROTOCOL_V1 §4.3
+    permissions: AgentRunnerPermissions      # 见 PROTOCOL_V1 §4.4
+    config_schema: list[DynamicFormItemSchema]
+    plugin_version: str | None = None
+    raw_manifest: dict[str, Any] = {}
+```
+
+职责：调用 `plugin_connector.list_agent_runners()` 拉取 runner、校验 typed `AgentRunnerManifest`、输出 descriptor、缓存 discovery 结果并提供 `refresh()`。单个插件 manifest 失败只记 warning，不影响其它 runner。`plugin:author/name/runner` 是稳定 id 格式；插件实例边界见 PROTOCOL_V1 §13。
+
+Host 内置 runner / adapter 不能作为 `AgentRunnerDescriptor.source` 绕过插件
+runtime、`run_id`、`ctx.resources` 和 `AgentRunAPIProxy` 权限链。若需要
+开发期调试 adapter，应放在 Host 内部测试入口，不进入可选 runner 列表。
+
+刷新触发点：插件安装/卸载/升级/重启后；Pipeline metadata 请求时发现缓存为空；可选 TTL（优先保证正确性）。
+
+### 4.4 AgentRunOrchestrator
+
+Orchestrator 是唯一运行入口：
+
+```text
+run(event, binding)
+  -> resolve runner descriptor
+  -> build resources
+  -> build context
+  -> register run session
+  -> call plugin runtime
+  -> normalize result stream
+  -> update state
+  -> unregister run session
+```
+
+它负责：`run_id` 生成和生命周期、timeout/deadline/cancellation、插件异常隔离、result schema 校验和大小限制、`state.updated` 处理、delivery backpressure 和 telemetry。
+
+典型 run 时序：
+
+```text
+QueryEntryAdapter / EventRouter
+  -> AgentRunOrchestrator.run(event, binding)
+  -> AgentRunnerRegistry.resolve(runner_id)
+  -> AgentResourceBuilder.freeze_snapshot(binding, event)
+  -> AgentRunSessionRegistry.register(run_id, runner_id, snapshot)
+  -> AgentContextBuilder.build(event, binding, snapshot)
+  -> PluginRuntimeConnector.run_agent(ctx)
+       -> AgentRunAPIProxy action
+          -> validate active run session + caller identity + snapshot
+          -> Host API / Store
+       <- AgentRunResult stream
+  -> apply state.updated to PersistentStateStore
+  -> write message.completed to Transcript
+  -> keep current-run files and large tool outputs in sandbox/workspace
+  -> render delivery or raise RunnerExecutionError
+  -> AgentRunSessionRegistry.unregister(run_id)
+```
+
+`run_from_query()` 保留为 Query entry adapter 入口，但内部转换成 event + binding 后走统一 `run()`。约束：`ChatMessageHandler` 不解析 `plugin:*`、不实例化 wrapper、不知道 runner 组件细节；`PipelineService` 从 registry 读取 metadata，不直接访问插件 runtime；跨请求持久化状态必须走授权 storage / 外部服务。
+
+### 4.5 Resource Authorization
+
+LangBot 在每次 run 前生成 `ctx.resources`（PROTOCOL_V1 §6），来自 manifest permissions 与 binding policy 的交集：
+
+1. `descriptor.permissions` 声明 runner 需要的 LangBot 资源访问上限。
+2. binding / resource policy 允许的资源范围。
+3. Agent/runner config 中选择的模型、知识库、文件等资源。
+4. 当前 event / actor / bot / workspace 的实际权限。
+5. `ctx.context.available_apis` 暴露的 pull API 能力。
+
+这次裁剪结果必须冻结为 run-scoped authorization snapshot，并由
+`AgentRunSessionRegistry` 按 `run_id` 保存。`ctx.resources` 是投影给 runner
+看的同一份授权结果；运行期每个 proxy action 只依据该 snapshot 校验 active
+run session、caller plugin identity、resource id、scope、payload size、rate
+limit 和 deadline。Handler 不应重新执行授权裁剪，否则 build-time 与 runtime
+授权逻辑会漂移。
+
+SDK 侧本地校验只用于开发体验，host 侧 run authorization snapshot 才是安全边界。`spec.capabilities` 只帮助 Host 判断 runner 是否需要 tool / knowledge / skill 等资源投影，不能替代 permissions 或 binding policy。
+
+资源裁剪应通用，不写死 local-agent。selector 与资源的映射示例：`model-fallback-selector` → primary/fallback LLM、`llm-model-selector` → LLM、`rerank-model-selector` → rerank 模型、`knowledge-base-multi-selector` → 知识库；新增 selector 时在 resource builder 中统一扩展。
+
+执行/文件/skill/MCP 等能力的接入方向：先由 Host / sandbox 封装成普通 scoped tool，再通过 `ctx.resources.tools` 和 SDK runtime 转发进入 runner；runner 不应识别或硬编码执行环境 provider。外部 harness 的 native tools 不能直接访问 LangBot 资源。
+
+### 4.6 State / Storage
+
+LangBot 可提供 host-owned state 让 runner 寄宿状态（conversation / actor / subject / runner / binding / workspace state），但**不是强制**。Host 只需提供：授权开关、scope key、get/set/list/delete API（见 PROTOCOL_V1 §8）、持久化 backend、审计和清理策略。外部 agent runtime 可维护自己的 session 和 memory。进程内 state store 只能作为过渡实现，不能作为正式生产语义。
+
+### 4.7 EventLog / Transcript / Sandbox Files（事实源）
+
+- `EventLog`: durable append-only，保存原始事件、系统事件、工具调用、投递结果、错误。
+- `Transcript`: 从 EventLog 投影出的对话视图，用于 UI、审计和按需历史读取。
+- `Sandbox / workspace files`: 当前 run 的上传文件、平台附件、工具大结果和临时产物。Host 负责 staging 与授权边界，runner 通过 read/write/exec 类工具按需访问。
+
+三类数据与 working context 的边界、读取约束见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。AgentRunner 可读取这些能力，但不被迫使用 LangBot 作为唯一记忆系统。
+
+### 4.8 External harness resource projection
+
+Claude Code、Codex、Kimi Code 等外部 harness runner 可能不直接调用 LangBot 的 model/tool loop，而是把 LangBot 事件和授权资源句柄投影到自己的 harness 执行。Host 侧仍保持统一边界：Host 负责构造 event-first context、资源授权、state/storage、EventLog/Transcript、sandbox/workspace 文件边界和审计；Host 或 binding policy 决定哪些 MCP bridge、skill-backed tool、sandbox path、history/state 句柄可投影给 runner；runner plugin 把 scoped projection 转成目标 harness 可消费形式；所有 LangBot 资源访问必须经 SDK runtime / `AgentRunAPIProxy` / SDK-owned MCP bridge 转发并接受 Host 校验；外部 harness 负责自己的 native session、tool loop、压缩、权限模式和 resume，但不能用 native tools 绕过 Host 授权。
+
+投影的具体形态（context 文件、resource handles、LangBot MCP gateway、state pointers）见 AGENT_CONTEXT_PROTOCOL §4.5；当前 code-agent harness runner 形态见 OFFICIAL_RUNNER_PLUGINS §7。发布级隔离要求见 SECURITY_HARDENING。
+
+## 5. SDK 侧协议
+
+SDK 组件入口如下；所有数据结构定义见 PROTOCOL_V1。
+
+```python
+class AgentRunner(BaseComponent):
+    __kind__ = "AgentRunner"
+
+    @classmethod
+    def get_config_schema(cls) -> list[dict]: ...
+
+    async def run(self, ctx: AgentRunContext) -> AsyncGenerator[AgentRunResult, None]: ...
+    # ctx: PROTOCOL_V1 §5.2 ; AgentRunResult: PROTOCOL_V1 §7
+```
+
+- Manifest / capabilities / effective access：PROTOCOL_V1 §4。Capabilities 来自组件 manifest 的 `spec.capabilities`，不是 SDK 基类 classmethod。
+- `AgentRunContext`：PROTOCOL_V1 §5.2。`messages` / `bootstrap` 不是协议字段。
+- `AgentRunResult`：PROTOCOL_V1 §7。
+- `AgentRunAPIProxy`：PROTOCOL_V1 §8，是 runner 访问 host 能力的唯一入口，所有请求带 `run_id`。

docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md

@@ -0,0 +1,138 @@
+# 官方 AgentRunner 插件迁移计划
+
+本文档描述内置 `RequestRunner` 迁出 LangBot 后，官方 runner 插件如何组织、迁移和验收。它是 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md) 和 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) 的下游落地计划，不是 LangBot 宿主协议的设计前提。QA 入口和 smoke 记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
+
+官方 `local-agent` 可以外移，也可以重写。设计重点不是保留旧内置 runner 的内部结构，而是验证一个依附 LangBot host 基础设施的官方 agent 能否完整工作。同时，LangBot host 协议必须服务 Claude Code SDK、Codex、Pi Agent SDK、外部 Agent 平台等自管 context/runtime 的 runner，不能被官方插件的实现细节绑死。
+
+## 1. 仓库组织
+
+官方 runner 插件与 LangBot 主仓库、SDK 仓库以不同节奏迭代：LangBot 主仓库只维护宿主协议和调度，SDK 仓库维护 AgentRunner 组件和 runtime 协议，官方 runner 插件承载业务 runner 的具体实现和第三方平台适配。
+
+当前推荐"官方插件可独立发布，必要时共享 SDK helper"。开发期采用本地多目录布局：
+
+```text
+langbot-app/
+  langbot-local-agent/                # plugin:langbot/local-agent/default
+    manifest.yaml
+    components/agent_runner/default.{yaml,py}
+  langbot-agent-runner/               # 外部服务 runner 仓库
+    acp-agent-runner/  claude-code-agent/  codex-agent/  dify-agent/  n8n-agent/  ...
+```
+
+后续可聚合进 monorepo，也可继续独立发布——这个选择不影响协议设计。重复逻辑优先沉淀到 SDK 或明确的共享 helper 包，不要把宿主私有结构泄漏给插件。旧 `src/langbot/pkg/provider/runners/*` 只作为历史行为对齐基准；当前未发布分支不提供旧内置 runner 的运行时 fallback。
+
+## 2. 插件命名和 runner id
+
+| 旧 runner | 官方插件 | runner id |
+| --- | --- | --- |
+| `local-agent` | `langbot/local-agent` | `plugin:langbot/local-agent/default` |
+| `dify-service-api` | `langbot/dify-agent` | `plugin:langbot/dify-agent/default` |
+| `n8n-service-api` | `langbot/n8n-agent` | `plugin:langbot/n8n-agent/default` |
+| `coze-api` | `langbot/coze-agent` | `plugin:langbot/coze-agent/default` |
+| - | `langbot/acp-agent-runner` | `plugin:langbot/acp-agent-runner/default` |
+| - | `langbot/claude-code-agent` | `plugin:langbot/claude-code-agent/default` |
+| - | `langbot/codex-agent` | `plugin:langbot/codex-agent/default` |
+| `dashscope-app-api` | `langbot/dashscope-agent` | `plugin:langbot/dashscope-agent/default` |
+| `deerflow-api` | `langbot/deerflow-agent` | `plugin:langbot/deerflow-agent/default` |
+| `langflow-api` | `langbot/langflow-agent` | `plugin:langbot/langflow-agent/default` |
+| `tbox-app-api` | `langbot/tbox-agent` | `plugin:langbot/tbox-agent/default` |
+| `weknora-api` | `langbot/weknora-agent` | `plugin:langbot/weknora-agent/default` |
+
+每个插件可后续提供多个 runner，但迁移目标的默认 runner 统一叫 `default`。
+
+## 3. 迁移批次
+
+- **Batch 1（打通协议）**：`local-agent`（能力最完整基准）、`acp-agent-runner` / `claude-code-agent` / `codex-agent`（外部 code-agent harness 路径）、`dify-agent`（传统 service API runner）。
+- **Batch 2（外部 workflow）**：`n8n-agent`、`langflow-agent`（webhook/workflow 输入输出、timeout、外部 conversation id）。
+- **Batch 3（平台 Agent API）**：`coze-agent`、`dashscope-agent`、`tbox-agent`、`deerflow-agent`、`weknora-agent`（平台特有响应格式、引用资料、文件/图片输入、外部 thread/session 状态）。
+
+## 4. 每个官方插件的组件要求
+
+每个插件至少包含一个 `AgentRunner` 组件，manifest 示例：
+
+```yaml
+apiVersion: langbot/v1
+kind: AgentRunner
+metadata:
+  name: default
+  label: { en_US: Dify Agent, zh_Hans: Dify Agent }
+  description:
+    en_US: Run a Dify application as a LangBot AgentRunner.
+    zh_Hans: 将 Dify 应用作为 LangBot AgentRunner 运行。
+spec:
+  config: []
+  capabilities:        # 字段语义见 PROTOCOL_V1 §4.3
+    streaming: true
+execution:
+  python: { path: ./main.py, attr: DefaultAgentRunner }
+```
+
+## 5. local-agent 插件方向
+
+`local-agent` 是官方插件中能力最完整的消费者，但不是宿主协议的设计中心。它需要证明：一个主要依附 LangBot host 能力的 agent runner 可以通过公开协议完成模型、工具、知识库、状态、history、sandbox 文件访问、上下文压缩和消息投递。
+
+迁移或重写需覆盖旧内置 runner 的用户可见能力：model primary/fallback 选择、prompt、knowledge-bases、rerank-model、rerank-top-k、function calling、streaming、multimodal input、conversation history、monitoring metadata。
+
+责任边界与 Host API 消费方式见 AGENT_CONTEXT_PROTOCOL §8。关键约束：
+
+- 从 `ctx.config` 读取静态绑定 `prompt`，**不**读取 `ctx.adapter.extra["prompt"]`；不消费 Query entry adapter 生成的历史窗口。
+- 通过 `AgentRunAPIProxy.history` 拉取 transcript，而不是依赖 host 每轮强塞历史窗口。
+- `ctx.input.contents` 保留图片/文件等多模态内容；RAG 只替换/插入文本部分，不丢图片/文件。
+- 不能绕过 `ctx.resources` 调用未授权模型、工具或知识库。
+- manifest 声明功能能力、LangBot 资源 permissions 和配置表单；实际授权来自 manifest permissions 与 binding resource policy、runner config、`ctx.context.available_apis` 和 Host run session snapshot 的交集。
+
+### 5.1 Native Execution / Skills 后续接入
+
+本阶段不把 sandbox/skills 做成 AgentRunner 协议字段。后续 sandbox/skills 分支合并后，命令执行、文件操作、skill、MCP managed process 应先由 Host / sandbox 封装成 scoped tools，再通过 `ctx.resources.tools` 和 SDK runtime 转发暴露给 runner。这让 local-agent 只消费授权后的 Host 基础设施，而不是直接持有宿主机执行能力。
+
+## 6. 外部 runner 插件要求
+
+外部平台 runner 迁移遵循：旧配置字段尽量保持同名便于 migration 复制；输出统一转换为 `AgentRunResult`；外部 API timeout 从 runner config 读取；平台 conversation id 存 plugin storage 或 context runtime state，不依赖 LangBot 内置 conversation uuid 私有结构；流式按平台能力声明，没有流式就只发 `message.completed`。
+
+### 6.1 Code-agent harness runner
+
+Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/工具 loop 执行，可以依赖自己的 harness，但仍必须遵守统一 Host 边界。总体边界见 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md) §4.8；context projection 形态见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) §4.5；发布级要求见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。
+
+本文件只补充官方 runner 的实现要求：输入来自 `ctx.event` / `ctx.input`，不依赖 Pipeline 私有 `Query`；外部 session id / workspace / checkpoint 写入 Host state 或 plugin storage；插件实例边界见 PROTOCOL_V1 §13；CLI / subprocess runner 必须处理 timeout、取消、空输出、非零退出和 stderr 映射。
+
+实现结构应把 provider-native output 解析与 LangBot result stream 组装分开：Claude stream-json、Codex JSONL、Kimi / OpenCode 事件等只在 runner adapter 内解析，输出统一归一为 `AgentRunResult`（`message.completed` / `message.delta`、`state.updated`、`run.completed` / `run.failed`）。文件和工具大结果留在当前 run 的 sandbox/workspace，通过消息 metadata、attachment ref 或 path 指向。未知 native event 不应导致 run 崩溃；应记录诊断 metadata 或 warning。新增 harness 时优先补 native fixture -> `AgentRunResult` 的转换测试，再接 WebUI smoke。
+
+并发约束应按外部 session 粒度表达，而不是按 Agent / runner id / 插件实例表达；Agent 复用和全局锁边界见 PROTOCOL_V1 §13。若 runner 使用 `external.session_id` / `thread_id` resume 到同一 native session，且该 harness 不支持并发 turn，runner 应按稳定 external session key 串行写入；一次性 subprocess runner 可以只在单次 `run(ctx)` 内处理，长连接/daemon runner 则应采用 reader 独占 native stream、turn writer 串行写入的结构。
+
+### 6.2 LangBot MCP gateway
+
+外部 harness 不能直接持有进程内的 `plugin_runtime_handler`，也不能用自己的 native tools 直接访问 LangBot 资源。外部 harness runner 应通过稳定 HTTP MCP gateway 或 SDK-owned bridge 把 harness 的工具请求转回 SDK runtime / Host API：
+
+- Gateway 由 runner 插件启动，暴露稳定的 `langbot_history_page`、`langbot_retrieve_knowledge`、`langbot_call_tool` 等最小工具面。
+- Harness 每次调用必须携带当前 LangBot `run_id`；Host 仍按 run session、caller identity 和授权快照校验。
+- Gateway 只转发 LangBot 资产访问，不承担外部 harness 的文件、进程或 native tool 权限边界。
+
+第一批工具保持很小：history page、knowledge retrieve、authorized tool call。新增工具必须先有 Host action 权限与 run-scoped authorization，再由 gateway 投影。
+
+## 7. Code-agent harness runner 当前形态
+
+外部 code-agent harness 由直接 runner 插件承接，例如 `acp-agent-runner`、`claude-code-agent`、`codex-agent`，每个 runner 负责把目标 harness 的 native session、workspace、MCP bridge 和输出事件转换为统一 `AgentRunResult`。本地 smoke 验收入口与记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
+
+当前形态：
+
+- Runner ID 示例：`plugin:langbot/acp-agent-runner/default`、`plugin:langbot/claude-code-agent/default`、`plugin:langbot/codex-agent/default`。
+- Runner 可通过 ACP、远端 daemon、本机 subprocess 或外部 HTTP API 调用 harness；harness 的安装、登录态、workspace 和 provider-native 权限由该运行环境负责。
+- Runner 会把当前 LangBot `run_id`、可访问资源摘要和 gateway 使用规则注入本次消息；harness 通过 gateway 回填 `run_id` 后访问 LangBot 资产。
+- 外部 session id / workspace / checkpoint 写回 Host state 或 plugin storage，后续轮次可复用目标 harness 会话。
+
+### 7.1 当前限制
+
+这不是发布级安全边界实现；LangBot 只约束 LangBot 持有资产的访问，外部 harness 的文件、进程、workspace、provider-native MCP 和模型凭据由对应 runner 的运行环境承担。当前 `run_id` 可由系统提示词、ACP metadata 或 runner 自有 session metadata 传递给 harness 并由 gateway 校验。runtime 管控面方向见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md)。
+
+## 8. 发布和安装策略
+
+最终 LangBot 安装/升级时需保证官方 runner 插件可用，可选方案：首次启动检测缺失并提示安装；打包发行版预装；migration 前检查插件存在性。当前分支未发布，因此不把历史配置兼容或旧内置 runner fallback 写入运行时协议面。建议顺序：开发阶段用本地路径插件 → 发布前支持 marketplace 安装 → 若发布升级需要迁移历史配置，再在 release gate 中实现一次性 migration 并要求官方插件已可用。
+
+## 9. 验收标准
+
+- 每个目标 runner 都有对应官方 AgentRunner 插件和稳定 runner id；当前配置只使用 `ai.runner.id` + `ai.runner_config[id]`。
+- LangBot 主聊天路径不再通过 `RequestRunner` 执行业务 runner。
+- 官方插件测试覆盖非流式、流式、错误、timeout、配置缺失。
+- `local-agent` 能完成模型 fallback、tool calling、知识库检索、多模态输入、静态绑定 prompt 消费、history API 拉取、rerank。
+- 外部 code-agent harness runner 能消费 event-first context、投影 scoped resources、保存 external session state，并通过 WebUI Debug Chat smoke。
+- `local-agent` 覆盖旧内置 runner 的用户可见核心能力；代码结构和运行路径不需要相同。

docs/agent-runner-pluginization/PROTOCOL_V1.md

@@ -0,0 +1,725 @@
+# LangBot AgentRunner Protocol v1
+
+本文档是 LangBot Host 与插件 SDK / Runtime / AgentRunner 之间协议合同的**唯一规范来源（single source of truth）**。
+
+- 本文件描述当前 Protocol v1 稳定合同，不混入验收流水。当前实现状态见 [STATUS.md](./STATUS.md)，测试执行入口见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)，安全发布门槛见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。
+- 本文件之外的任何文档**不得重新定义这里的数据结构**，只能引用，例如"见 PROTOCOL_V1 §4.2"。
+- Host 内部模型（`AgentEventEnvelope`、`AgentBinding`、Descriptor、各 Store）不属于 SDK 协议，定义在 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md)。
+
+## 1. 协议目标
+
+Protocol v1 只解决四件事：
+
+- LangBot 如何发现插件提供的 AgentRunner。
+- LangBot 如何把一次事件调用封装成 `AgentRunContext`。
+- AgentRunner 如何以事件流形式返回运行结果。
+- AgentRunner 如何通过受限 API 访问 LangBot host 能力。
+
+Protocol v1 **不定义**：
+
+- LangBot 内部如何持久化 `AgentBinding`（见 HOST_SDK）。
+- AgentRunner 内部如何组装 prompt、压缩历史、管理 memory（见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)）。
+- 官方 runner 的具体实现（见 [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md)）。
+- Pipeline 的长期配置模型。
+- 发布级安全 hardening 的完整实现（见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)）。
+
+## 2. 参与方
+
+| 名称 | 职责 |
+| --- | --- |
+| LangBot Host | 事件入口、绑定解析、权限、资源、存储、生命周期、结果投递。 |
+| Plugin Runtime | 加载插件，响应 Host 的 runner discovery 和 run 调用。 |
+| AgentRunner | 插件提供的 agent 执行组件。 |
+| AgentRunAPIProxy | AgentRunner 访问 Host 能力的受限 API。 |
+| AgentBinding | Host 内部的事件到 runner 绑定配置，不直接暴露给 SDK（见 HOST_SDK §4.2）。 |
+
+产品层的 `Agent` 替代旧 Pipeline 承载 agent 配置：bot / IM channel
+绑定一个 Agent，一个 Agent 可以被多个 bot / channel 复用。Host 内部的
+`AgentBinding` 是一次事件运行前解析出的有效绑定，只影响 Host 构造出的
+`ctx.config`、`ctx.resources`、`ctx.context` 和 `ctx.delivery`。SDK 不需要知道
+Agent / binding 的持久化形态。
+
+外部 harness runner（Claude Code、Codex、Kimi Code 等）也是 `AgentRunner`：它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`，并通过 Host 授权的 state/storage API 保存跨轮次指针；当前运行文件和工具大结果进入 sandbox/workspace。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。
+
+## 3. 协议演进
+
+当前 AgentRunner 合同不暴露显式 `protocol_version` 字段。协议演进先按字段级兼容规则处理：
+
+- 新增可选字段保持向后兼容。
+- 删除字段或改变既有字段语义，需要在 SDK 发布前完成；发布后应走新的显式兼容方案。
+- 结果流演进：Host **必须忽略未知 result type 并记录 warning**（除非该 type 明确要求强校验）。SDK envelope 接收入站未知 `type` 字符串，runner 侧可按原字符串转发或忽略；新增 result type 不提升大版本。
+- SDK 入站 context 类实体偏宽松，用于兼容 Host 附加的非核心字段；manifest、result payload、page/result 返回与错误模型偏严格，未知字段默认禁止。安全边界仍在 Host，SDK 校验只提升开发体验。
+
+## 4. Discovery 协议
+
+### 4.1 LIST_AGENT_RUNNERS
+
+Host 调用 Plugin Runtime 获取当前插件暴露的 runner 列表，请求无额外 payload。返回：
+
+```python
+class ListAgentRunnersResponse(BaseModel):
+    runners: list[AgentRunnerDiscovery]
+
+class AgentRunnerDiscovery(BaseModel):
+    plugin_author: str
+    plugin_name: str
+    runner_name: str
+    manifest: AgentRunnerManifest
+```
+
+`manifest` 是 SDK typed `AgentRunnerManifest`，由 Runtime 从插件组件 manifest 解析并校验后返回。`plugin_author` / `plugin_name` / `runner_name` 保留为 transport 寻址字段；Host 以它们生成稳定 runner id，并把 `manifest.id` 校验为 `plugin:author/name/runner`。单个 runner manifest 解析失败时 Runtime/Host 记录 warning 并跳过该 runner，不影响同一插件或其它插件的 runner discovery。
+
+### 4.2 AgentRunnerManifest
+
+这里的 manifest 指 Runtime 返回给 Host 的 typed runner manifest：
+
+```python
+class AgentRunnerManifest(BaseModel):
+    id: str
+    name: str
+    label: I18nObject
+    description: I18nObject | None = None
+    capabilities: AgentRunnerCapabilities = AgentRunnerCapabilities()
+    permissions: AgentRunnerPermissions = AgentRunnerPermissions()
+    config_schema: list[DynamicFormItemSchema] = []
+    metadata: dict[str, Any] = {}
+```
+
+- runner id 由 Host 生成，格式 `plugin:author/name/runner`。
+- `name` 是插件内 runner 名称，例如 `default`。
+- `config_schema` 只描述绑定配置表单，不代表插件实例状态。
+- `capabilities` 是 Host 用于 UI 和资源投影的 typed bool model；它不是权限授予。
+- `permissions` 是 runner 申请的 LangBot 资源访问上限；实际授权仍必须与 binding policy 求交。
+- `metadata` 只放展示、诊断、非稳定扩展信息。
+
+### 4.3 Capabilities
+
+```python
+class AgentRunnerCapabilities(BaseModel):
+    streaming: bool = False
+    tool_calling: bool = False
+    knowledge_retrieval: bool = False
+    multimodal_input: bool = False
+    skill_authoring: bool = False
+    interrupt: bool = False
+    steering: bool = False
+
+    model_config = ConfigDict(extra="forbid")
+```
+
+- `streaming`: runner 可以返回 `message.delta`。
+- `tool_calling`: runner 可能调用 Host tool API。
+- `knowledge_retrieval`: runner 可能调用 Host knowledge API。
+- `multimodal_input`: runner 可以处理非纯文本 input / attachment。
+- `skill_authoring`: runner 需要 Host 提供 skill facts 以及 skill authoring tools，例如 `activate` / `register_skill`。
+- `interrupt`: runner 支持取消或中断。
+- `steering`: runner 支持在 turn 边界通过 Host pull API 消费同 conversation 在途追加消息。
+
+Capabilities 字段全部是 `bool`，未知 key 禁止进入 typed manifest。早期草案里的上下文/会话类 capability 已删除；对应语义由 event-first context 和 runner-owned context 原则表达。
+
+### 4.4 Permissions 与 Effective Access
+
+```python
+class AgentRunnerPermissions(BaseModel):
+    models: list[Literal["invoke", "stream", "rerank"]] = []
+    tools: list[Literal["detail", "call"]] = []
+    knowledge_bases: list[Literal["list", "retrieve"]] = []
+    history: list[Literal["page", "search"]] = []
+    events: list[Literal["get", "page"]] = []
+    storage: list[Literal["plugin", "workspace"]] = []
+    files: list[Literal["config", "knowledge"]] = []
+
+    model_config = ConfigDict(extra="forbid")
+```
+
+平台动作执行不属于当前 permissions。Platform action executor / EBA action 分支落地前，runner 只能返回 `action.requested` telemetry，Host 不执行平台动作。
+
+Runner 实际可用 LangBot 资源来自 Host 在 run 前冻结的授权快照：
+
+```text
+effective_access = manifest.permissions ∩ binding.resource_policy ∩ current scope/config
+```
+
+具体落地：
+
+1. `AgentResourceBuilder` 先用 manifest permissions 与 binding resource policy / runner config 求交，生成 `ctx.resources`。
+2. `AgentContextBuilder` 用 manifest permissions 与 binding state/storage policy 求交，生成 `ctx.context.available_apis`。
+3. `AgentRunSessionRegistry` 冻结 run-scoped resources 与 available APIs。
+4. Runtime handler / `AgentRunAPIProxy` 按 active `run_id`、runner identity、caller plugin identity、resource id、scope、payload size、rate limit 和 deadline 校验每次调用。
+
+反承诺：manifest permissions **只约束 LangBot 持有的资源访问**。它不承诺限制外部 harness 的 native shell、文件系统、CLI、MCP、网络或本机权限；这些能力由 operator/runtime/sandbox 另行约束，见 HOST_SDK §4.8 与 SECURITY_HARDENING。
+
+默认原则：
+
+- Host 不得默认 inline 全量历史。
+- Host 只 inline 当前 event / input 和 context handles。
+- Runner 拥有 working context assembly。
+- Runner 可在授权后通过 Host history / event / state API 拉取更多上下文，并通过授权 sandbox/workspace 工具访问当前运行文件。
+- 历史窗口策略不属于 Protocol v1 字段，也不属于 Host 通用语义。
+
+context 边界的设计理由见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。
+
+## 5. Run 协议
+
+### 5.1 RUN_AGENT
+
+Host 调用 Runtime：
+
+```python
+class AgentRunRequest(BaseModel):
+    runner_id: str
+    runner_name: str
+    context: AgentRunContext
+```
+
+Runtime 返回 `AgentRunResult` 异步流。底层 transport 可继续用 `plugin_author` / `plugin_name` / `runner_name` 定位组件，但协议语义以 `runner_id` 和 `context` 为准。
+
+### 5.2 AgentRunContext
+
+这是 SDK 看到的**唯一权威 context 定义**。
+
+```python
+class AgentRunContext(BaseModel):
+    run_id: str
+    trigger: AgentTrigger
+    event: AgentEventContext
+    conversation: ConversationContext | None = None
+    actor: ActorContext | None = None
+    subject: SubjectContext | None = None
+    input: AgentInput
+    delivery: DeliveryContext
+    resources: AgentResources
+    context: ContextAccess
+    state: AgentRunState
+    runtime: AgentRuntimeContext
+    config: dict[str, Any] = {}
+    adapter: AdapterContext | None = None
+    metadata: dict[str, Any] = {}
+```
+
+核心约束：
+
+- `event` 是必选字段，Protocol v1 是 event-first。
+- `input` 表示当前事件的主输入，不等于历史消息。
+- `bootstrap` / `messages` **不是协议字段**；Host 不内联历史窗口。
+- `adapter` 只放入口 adapter 的非核心元数据，runner 不应依赖它做长期能力。
+- `config` 是 Agent/runner config，不是插件实例状态。
+
+### 5.3 AgentTrigger
+
+```python
+class AgentTrigger(BaseModel):
+    type: str
+    source: Literal["platform", "webui", "api", "scheduler", "system", "host_adapter"]
+    timestamp: int | None = None
+```
+
+`trigger.type` 应与 `event.event_type` 一致或更粗粒度。例如入口适配器触发消息时：
+
+```json
+{ "type": "message.received", "source": "host_adapter" }
+```
+
+### 5.4 AgentEventContext
+
+```python
+class AgentEventContext(BaseModel):
+    event_id: str
+    event_type: str
+    event_time: int | None = None
+    source: str
+    source_event_type: str | None = None
+    raw_ref: RawEventRef | None = None
+    data: dict[str, Any] = {}
+```
+
+- `event_type` 使用 LangBot 稳定协议名，例如 `message.received`。稳定事件名清单见 [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md)。
+- 平台原始事件名放入 `source_event_type`。
+- 大型原始 payload 必须放入 `raw_ref` 或 staged file，不应直接塞入 `data`。
+
+### 5.5 Conversation / Actor / Subject
+
+```python
+class ConversationContext(BaseModel):
+    conversation_id: str | None = None
+    thread_id: str | None = None
+    launcher_type: str | None = None
+    launcher_id: str | None = None
+    sender_id: str | None = None
+    bot_id: str | None = None
+    workspace_id: str | None = None
+    session_id: str | None = None
+
+class ActorContext(BaseModel):
+    actor_type: str
+    actor_id: str | None = None
+    actor_name: str | None = None
+    metadata: dict[str, Any] = {}
+
+class SubjectContext(BaseModel):
+    subject_type: str
+    subject_id: str | None = None
+    data: dict[str, Any] = {}
+```
+
+示例：
+
+- 消息事件：actor 是发消息的人，subject 是当前消息。
+- 入群事件：actor 是新成员或邀请人，subject 是群/成员关系。
+- 定时事件：actor 可以是 system，subject 是 schedule。
+
+### 5.6 AgentInput
+
+```python
+class AgentInput(BaseModel):
+    text: str | None = None
+    contents: list[ContentElement] = []
+    attachments: list[InputAttachment] = []
+```
+
+- 文本、多模态、附件都属于当前 event input。
+- 大文件、图片、音频、工具大结果应进入授权 sandbox/workspace，input attachment 只携带轻量 metadata/path/url/content。
+- 平台原始消息链不属于 SDK `AgentInput`；需要诊断时放在 Host 内部 envelope 或 `ctx.adapter.extra` 的一次性兼容字段中，不作为长期 runner 合同。
+
+### 5.7 DeliveryContext
+
+```python
+class DeliveryContext(BaseModel):
+    surface: str
+    reply_target: dict[str, Any] | None = None
+    supports_streaming: bool = False
+    supports_edit: bool = False
+    supports_reaction: bool = False
+    max_message_size: int | None = None
+    platform_capabilities: dict[str, Any] = {}
+```
+
+Runner 可参考 delivery 能力决定返回 `message.delta`、`message.completed` 或 `action.requested`。
+
+### 5.8 ContextAccess
+
+```python
+class ContextAccess(BaseModel):
+    conversation_id: str | None = None
+    thread_id: str | None = None
+    latest_cursor: str | None = None
+    event_seq: int | None = None
+    transcript_seq: int | None = None
+    has_history_before: bool = False
+    inline_policy: InlineContextPolicy
+    available_apis: ContextAPICapabilities
+
+class InlineContextPolicy(BaseModel):
+    mode: Literal["none", "current_event", "recent_tail", "summary_tail"]
+    delivered_count: int = 0
+    source_total_count: int | None = None
+    messages_complete: bool = False
+    reason: str | None = None
+
+class ContextAPICapabilities(BaseModel):
+    prompt_get: bool = False
+    history_page: bool = False
+    history_search: bool = False
+    event_get: bool = False
+    event_page: bool = False
+    state: bool = False
+    storage: bool = False
+    steering_pull: bool = False
+```
+
+`ContextAccess` 告诉 runner：Host inline 了什么、没 inline 什么、需要更多上下文时走哪些 API。它是 runner 按需读取上下文的入口说明，不是 Host 的业务上下文编排策略。
+
+### 5.9 AgentRuntimeContext
+
+```python
+class AgentRuntimeContext(BaseModel):
+    langbot_version: str | None = None
+    trace_id: str | None = None
+    deadline_at: float | None = None
+    metadata: dict[str, Any] = {}
+```
+
+### 5.10 AgentRunState
+
+```python
+class AgentRunState(BaseModel):
+    conversation: dict[str, Any] = {}
+    actor: dict[str, Any] = {}
+    subject: dict[str, Any] = {}
+    runner: dict[str, Any] = {}
+```
+
+State 是可选 host-owned snapshot。Runner 也可以完全自管状态。
+
+## 6. Resources
+
+```python
+class SkillResource(BaseModel):
+    skill_name: str
+    display_name: str | None = None
+    description: str | None = None
+
+class AgentResources(BaseModel):
+    models: list[ModelResource] = []
+    tools: list[ToolResource] = []
+    knowledge_bases: list[KnowledgeBaseResource] = []
+    skills: list[SkillResource] = []
+    storage: StorageResource = StorageResource()
+    platform_capabilities: dict[str, Any] = {}
+```
+
+`skills` 只包含本次 run 中 pipeline-visible 的 skill facts，例如 `skill_name`、`display_name` 和 `description`。Host 不把这些 facts 追加到 system prompt，也不把它们编排进工具描述；runner 可以自行决定是否放入 model prompt、转换成 MCP surface，或只在自己的策略层使用。
+
+资源列表是本次 run 的授权结果。History / Event / State / Storage 访问通过 `ctx.context.available_apis` 和 Host 侧 run session 校验控制，不作为可枚举 resource list 暴露。Runner 只能通过 `AgentRunAPIProxy` 访问这些能力。当前事件的文件和工具大结果优先进入授权 sandbox/workspace，由 runner 通过 read/write/exec 类工具按需读取。
+
+## 7. Result Stream
+
+### 7.1 AgentRunResult envelope
+
+```python
+JSONValue = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
+
+ResultType = Literal[
+    "message.delta",
+    "message.completed",
+    "tool.call.started",
+    "tool.call.completed",
+    "state.updated",
+    "action.requested",
+    "run.completed",
+    "run.failed",
+]
+
+class AgentRunResult(BaseModel):
+    run_id: str
+    type: AgentRunResultType | str
+    data: dict[str, Any] = {}
+    usage: LLMTokenUsage | None = None
+    sequence: int | None = None
+    timestamp: int | None = None
+```
+
+SDK 当前实现是单一 envelope：`type` 枚举 + `data` dict。Payload 由 SDK typed model 构造并 dump，但 wire 不改成 discriminated union；这样新旧版本偏斜时 Host 仍可按 §3 忽略未知 `type`。
+
+`usage` 是 runner 可选上报的 token 使用量，沿用 SDK `LLMTokenUsage`：
+
+```python
+class LLMTokenUsage(BaseModel):
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    # provider-specific detail/cached/reasoning counters are preserved as extra fields
+```
+
+约束：
+
+- 运行时能观测到 provider/runtime usage 时，SHOULD 在 terminal `run.completed.usage` 上报本次 run 的最终聚合 token usage。
+- `run.failed.usage` MAY 上报失败前已经产生的部分 usage。
+- 不能观测 usage 的 runner 合法地省略该字段；缺失表示 unknown，Host 不得按 0 处理。
+- ACP 等外部协议不保证统一 usage；ACP runner 只能在具体 provider/native event 提供 usage 时填充本字段。
+- cost 不作为 runner result 的权威字段。Host 后续应基于 usage、model identity、时间和自身价格表计算账单成本；provider 原始 cost 如需保留，可放在 `usage` extra 字段中作为非权威 telemetry。
+
+Host 边界分级校验：
+
+- `message.delta`、`message.completed`、`state.updated`、`action.requested`、`run.completed`、`run.failed` 属于会影响投递或 Host 副作用的严格 payload；校验失败时丢弃该 result 并记录 warning。
+- `tool.call.started`、`tool.call.completed` 当前只作为 telemetry，payload 宽松兼容。
+- 未知 `type` 忽略并记录 warning。
+
+### 7.2 稳定 result payloads
+
+| type | `data` payload |
+| --- | --- |
+| `message.delta` | `{ "chunk": MessageChunk }` |
+| `message.completed` | `{ "message": Message }` |
+| `tool.call.started` | `{ "tool_call_id": str, "tool_name": str, "parameters": dict }` |
+| `tool.call.completed` | `{ "tool_call_id": str, "tool_name": str, "result": dict \| None, "error": str \| None }` |
+| `state.updated` | `{ "scope": "conversation" \| "actor" \| "subject" \| "runner", "key": str, "value": JSONValue }` |
+| `action.requested` | `{ "action": str, "target": dict \| None, "payload": dict \| None }` |
+| `run.completed` | `{ "finish_reason": str, "message"?: Message }` |
+| `run.failed` | `{ "code": str, "error": str, "retryable": bool }` |
+
+Runner 生成的大文件、工具输出和临时产物不通过 result event 回传；应写入当前 run 的授权 sandbox/workspace，再用消息文本、metadata 或 attachment reference 指向它们。
+
+### 7.3 稳定 result types
+
+| type | 说明 | 当前消费 |
+| --- | --- | --- |
+| `message.delta` | 流式消息片段。 | ✅ |
+| `message.completed` | 完整消息。 | ✅ |
+| `tool.call.started` | 工具调用开始的可观测事件。 | telemetry |
+| `tool.call.completed` | 工具调用完成的可观测事件。 | telemetry |
+| `state.updated` | runner 请求更新 host-owned state。 | ✅ |
+| `action.requested` | runner 请求 Host 执行平台动作。 | **reserved / 仅 telemetry，不执行** |
+| `run.completed` | run 正常结束。 | ✅ |
+| `run.failed` | run 失败。 | ✅ |
+
+`action.requested` 是为 EBA 和 platform API 保留的协议表面：本分支 Host 收到后只记 telemetry，**不执行**，runner 作者不应在当前 Host 底座中依赖其副作用。真实执行器由外部 EBA / platform action 分支接入；执行模型见 EVENT_BASED_AGENT §6。
+
+Host 必须校验 `state.updated` 的 scope、key、value 大小和 JSON 可序列化性。本分支 `action.requested` 仍只记录 telemetry。
+
+### 7.4 Stream delivery semantics
+
+- Host 按 Runtime stream 顺序消费 result。当前 v1 不定义跨连接 replay，也不承诺 at-least-once；从 Host 视角，收到的 result 最多应用一次。
+- `sequence` 是单个 `run_id` 内的结果序号。in-process / stdio 这类天然有序的在线 stream 可以省略；任何会缓冲、重放、跨进程队列或 runtime-managed task 的 transport 必须提供从 1 开始严格递增的 `sequence`。
+- Host 看到已提供 `sequence` 的 result 时，应按 `(run_id, sequence)` 做重复检测，并在缺号或乱序时记录 warning；除非 transport 明确声明 replay 语义，Host 不应自行等待缺失序号重排用户可见输出。
+- `run.failed.data.retryable` 只表示整次 run 理论上可由上层重试；Protocol v1 不自动重试 run，也不自动重试 proxy action。
+- History / Event / Transcript cursor 是 opaque token。runner 不得解析 cursor，也不得假设 cursor 在不同 API、conversation、thread 或 retention window 之间可比较；当前实现即使返回数字字符串，也只是实现细节。
+
+### 7.5 示例
+
+```json
+{ "type": "message.delta",     "data": { "chunk": { "role": "assistant", "content": "hel" } } }
+{ "type": "message.completed", "data": { "message": { "role": "assistant", "content": "hello" } } }
+{ "type": "state.updated",     "data": { "scope": "conversation", "key": "external.session_id", "value": "abc" } }
+{ "type": "action.requested",  "data": { "action": "message.edit", "target": {"message_id": "..."}, "payload": {"text": "..."} } }
+```
+
+## 8. AgentRunAPIProxy
+
+所有 proxy action 必须携带 `run_id`。Host 必须校验：active run session 存在、caller plugin identity 匹配、resource 在本次 `ctx.resources` 中授权、scope 不越界、payload size / rate limit / deadline 合法。
+
+```python
+# Model
+await api.invoke_llm(llm_model_uuid, messages, funcs=None, extra_args=None)
+await api.invoke_llm_with_usage(llm_model_uuid, messages, funcs=None, extra_args=None)
+async for chunk in api.invoke_llm_stream(llm_model_uuid, messages, funcs=None, extra_args=None):
+    ...
+async for event in api.invoke_llm_stream_events(llm_model_uuid, messages, funcs=None, extra_args=None):
+    ...
+await api.invoke_rerank(rerank_model_id, query, documents, top_k=None)
+
+# Tool
+await api.get_tool_detail(tool_name)
+await api.call_tool(tool_name, parameters)
+
+# Knowledge
+await api.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)
+
+# History（返回 Transcript projection，不返回原始平台 payload）
+await api.get_prompt()
+await api.history_page(conversation_id=None, before_cursor=None, after_cursor=None,
+                       limit=50, direction="backward", include_attachments=False)
+await api.history_search(query, filters=None, top_k=10)
+
+# Event（返回稳定 event envelope 或受限 raw ref，不默认返回大 payload）
+await api.event_get(event_id)
+await api.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)
+await api.steering_pull(mode="all", limit=None)
+
+# State / Storage
+await api.state_get(scope, key);   await api.state_set(scope, key, value);   await api.state_delete(scope, key)
+await api.state_list(scope, prefix=None, limit=100)
+await api.get_plugin_storage(key); await api.set_plugin_storage(key, value); await api.delete_plugin_storage(key)
+await api.get_plugin_storage_keys()
+await api.get_workspace_storage(key); await api.set_workspace_storage(key, value); await api.delete_workspace_storage(key)
+await api.get_workspace_storage_keys()
+
+# Host info
+await api.get_langbot_version()
+```
+
+`invoke_llm()` / `invoke_llm_stream()` 的第一个参数在 SDK 中命名为
+`llm_model_uuid`，wire payload 字段也是 `llm_model_uuid`。该值对 runner
+仍是 opaque identifier，不应解析其内部格式。
+
+`invoke_llm()` 和 `invoke_llm_stream()` 保持兼容：前者返回 `Message`，后者只
+yield `MessageChunk`。需要 provider 真实 token 计量的 runner 应使用
+`invoke_llm_with_usage()` 或 `invoke_llm_stream_events()`。Host response 可在
+原有 `{message: ...}` / `{chunk: ...}` 外额外携带可选 `usage` 字段；streaming
+场景允许在所有 chunk 之后追加一个 usage-only event。`usage` 至少保留
+OpenAI-compatible 的 `prompt_tokens`、`completion_tokens`、`total_tokens`，
+若 provider 返回 `prompt_tokens_details` / `completion_tokens_details` 或
+cache token counters，Host / SDK 不应丢弃这些字段。没有 usage 的 provider
+必须继续返回成功响应，SDK 将 usage 置为 `None`。
+
+`get_prompt()` 返回当前 query-backed run 的 Host effective prompt messages：
+`list[Message]` 的 JSON 形式。该能力只在 `ctx.context.available_apis.prompt_get`
+为 true 时可用；没有 query 缓存、prompt 已过期或非 query entry run 时 Host
+可以返回错误或空列表。Runner 应在不可用时回退到自己的 config/prompt 策略。
+
+`steering_pull(mode="all")` 是推荐默认：Host 按 claim 顺序返回全部 pending steering 输入并清空对应队列。`mode="one-at-a-time"` 仅用于 runner 主动节流，每次返回一条。Host 不合并多条用户消息；runner 负责在 turn 边界决定模型侧格式。
+
+Steering 审计使用 EventLog 而不是 Transcript schema 扩展：被 active run 吸收的原始 `message.received` 事件保留原事件类型，并在 `metadata.steering` 标记 `status="queued"`、`trigger_behavior="absorbed_into_active_run"`、`claimed_by_run_id`、`claimed_runner_id`、`claimed_at`。Runner 成功 pull 后，Host 追加 `steering.injected` EventLog 记录，`metadata.steering.status="injected"` 并引用 `source_event_id`。若 run 结束时仍有已 claim 但未 pull 的 steering 输入，Host 追加 `steering.dropped` EventLog 记录，`metadata.steering.status="dropped"` 并引用 `source_event_id`；这不是用户消息事实的删除，只是 dispatch 终态。Transcript 继续只表示会话事实，不承担 dispatch 行为标记。
+
+`state` 与 `storage` 的建议边界：`state` 放小型 JSON（conversation / actor / subject / runner），`storage` 放 blob 或较大数据（插件私有数据、workspace 数据、checkpoint）。
+
+Compaction checkpoint 的推荐 state 约定：
+
+- scope: `conversation`
+- key: `runner.compaction.checkpoint`
+- value:
+
+```json
+{
+  "schema_version": "langbot.local_agent.compaction_checkpoint.v1",
+  "summary": "<conversation_summary>...</conversation_summary>",
+  "covers_until": "transcript-cursor-or-seq",
+  "tokens_before": 12345,
+  "created_at": 1710000000,
+  "conversation_id": "conv-..."
+}
+```
+
+`covers_until` 是摘要覆盖到的 transcript 游标锚点。Runner 读取 checkpoint 后应只拉取该游标之后的 transcript；若 checkpoint 缺失、schema 不匹配、conversation 不匹配或游标不可用，应回退到无 checkpoint 的尾部历史拉取行为。
+
+Proxy 返回数据结构也属于本协议：
+
+```python
+class TranscriptItem(BaseModel):
+    transcript_id: str
+    event_id: str
+    conversation_id: str | None = None
+    thread_id: str | None = None
+    role: str
+    item_type: str = "message"
+    content: str | None = None
+    content_json: dict[str, Any] | None = None
+    attachment_refs: list[dict[str, Any]] = []
+    seq: int | None = None
+    cursor: str | None = None
+    created_at: int | None = None
+    metadata: dict[str, Any] = {}
+
+class HistoryPage(BaseModel):
+    items: list[TranscriptItem] = []
+    next_cursor: str | None = None
+    prev_cursor: str | None = None
+    has_more: bool = False
+    total_count: int | None = None
+
+class HistorySearchResult(BaseModel):
+    items: list[TranscriptItem] = []
+    total_count: int | None = None
+    query: str
+
+class AgentEventRecord(BaseModel):
+    event_id: str
+    event_type: str
+    event_time: int | None = None
+    source: str
+    bot_id: str | None = None
+    workspace_id: str | None = None
+    conversation_id: str | None = None
+    thread_id: str | None = None
+    actor_type: str | None = None
+    actor_id: str | None = None
+    actor_name: str | None = None
+    subject_type: str | None = None
+    subject_id: str | None = None
+    input_summary: str | None = None
+    input_ref: str | None = None
+    raw_ref: str | None = None
+    seq: int | None = None
+    cursor: str | None = None
+    created_at: int | None = None
+    metadata: dict[str, Any] = {}
+
+class EventPage(BaseModel):
+    items: list[AgentEventRecord] = []
+    next_cursor: str | None = None
+    prev_cursor: str | None = None
+    has_more: bool = False
+    total_count: int | None = None
+
+class SteeringInputItem(BaseModel):
+    claimed_run_id: str
+    runner_id: str
+    claimed_at: int | None = None
+    event: AgentEventContext
+    input: AgentInput
+    conversation: ConversationContext | None = None
+    actor: ActorContext | None = None
+    subject: SubjectContext | None = None
+    metadata: dict[str, Any] = {}
+
+class SteeringPullResult(BaseModel):
+    items: list[SteeringInputItem] = []
+```
+
+## 9. 错误模型
+
+```python
+class AgentAPIError(BaseModel):
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = {}
+```
+
+| code | 说明 |
+| --- | --- |
+| `unauthorized` | 未授权访问资源或 scope。 |
+| `not_found` | 资源不存在或对当前 runner 不可见。 |
+| `deadline_exceeded` | 超过 run deadline。 |
+| `payload_too_large` | 请求或响应过大。 |
+| `rate_limited` | Host 限流。 |
+| `invalid_argument` | 参数错误。 |
+| `runtime_error` | Host 或下游能力错误。 |
+
+SDK runner-facing proxy 在 Host 返回结构化错误或畸形响应时抛出 `AgentAPIException`，其中 `error` 字段为 `AgentAPIError`。Legacy transport 只返回字符串错误时，SDK 使用 `host.action_error` 包装，避免 runner 继续依赖裸 `KeyError` 或字符串匹配。
+
+Runner 失败使用 `run.failed`：
+
+```json
+{ "type": "run.failed", "data": { "code": "runner.error", "error": "failed to call external agent", "retryable": false } }
+```
+
+## 10. Timeout 与 Cancellation
+
+- Host 在 `ctx.runtime.deadline_at` 下发总 deadline；SDK proxy 必须用该 deadline 限制单次 action timeout。
+- Host 可以取消 active run；Runtime 应尽力中断 runner。
+- Protocol v1 的 run 绑定当前 Host 进程和当前 runtime channel，不保证跨 Host 重启恢复。Host 重启、runtime channel 断开或 run session 丢失时，Runtime / external harness connector 必须 fail-fast 并尽力取消仍在执行的 runner，不得继续使用旧 `run_id` 调用 Host API。
+- Runner 支持中断时应返回或触发 `run.failed`，code 为 `cancelled`。
+- Host 必须 unregister active run session。
+
+## 11. Security 与 Guardrail（协议层）
+
+Protocol v1 的安全边界在 Host：
+
+- Runner 不能直接访问未授权 model/tool/kb/history/storage/sandbox。
+- SDK 本地校验只提升开发体验，不能替代 Host 校验。
+- 所有 resource id 对 runner 来说都是 opaque。
+- 默认只能访问当前 conversation / thread 的 history；跨会话、workspace 级访问必须额外授权。
+- 大 payload 不应塞进 result event；当前 run 的文件和工具大结果应进入授权 sandbox/workspace，由 read/write/exec 类工具按需访问。
+- Host 必须记录 run_id、runner_id、action、resource、scope、result。
+
+Host 不负责业务编排：不拼接全量历史、不替 runner 做 prompt assembly、不内置 agent memory / tool loop / 上下文压缩策略。这些由官方或第三方 AgentRunner 插件实现。
+
+外部 harness runner 的边界统一见 HOST_SDK §4.8。简言之：harness native permission mode、allowed/disallowed tools、shell/MCP 权限只是额外执行约束，不能替代 Host 对 LangBot 资源的授权。
+
+> 发布级路径隔离、MCP allowlist、secret redaction、配额、workspace 清理等**不属于** v1 协议闭环，是生产默认启用前的 release gate，见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。
+
+## 12. Pipeline Adapter 边界
+
+Pipeline 是当前入口 adapter，不是协议中心。目标产品模型中 Agent 会替代
+Pipeline 承载 runner config、resource policy 和 delivery policy；当前 Query
+entry adapter 只是迁移桥。它负责：
+
+- 从 `Query` 构造 `AgentEventContext` 和临时 `AgentBinding`（见 HOST_SDK §4.2）。
+- 从当前 Agent/runner config 构造 `ctx.config`。
+- 将 Query-only 字段放入 `ctx.adapter`，例如 filtered params 放 `ctx.adapter.extra["params"]`。
+
+约束：
+
+- adapter **不**定义历史窗口、prompt 组装或 agentic context 策略。
+- `ctx.adapter.extra` 只允许承载一次性、JSON-safe、入口相关的非核心元数据，例如 `params`；不得承载 `prompt`、history window、RAG 结果、tool schema 或授权资源。
+- 静态绑定 prompt 属于 `ctx.config.prompt`。preprocessing / hook 后的动态有效指令不通过 `ctx.adapter.extra` 主动推送；后续如需要保留这类能力，应通过 Host prompt/instruction pull API 暴露（占位见 HOST_SDK §4.8）。
+- 新 runner 不应长期依赖 `adapter`，应只依赖 event-first context 和 Host API。
+
+## 13. 已确认约束
+
+- v1 / EBA 主线是 `one event -> one AgentBinding -> one run_id -> one runner`。
+- 一个 bot / IM channel 在同一时间只绑定一个负责 agentic 处理的 Agent；一个 Agent 可以被多个 bot / channel 复用。
+- 如果配置层出现多个匹配 AgentBinding，BindingResolver 必须按明确规则选出一个或拒绝配置，不应默认 fan-out。
+- observer agent、多 runner fan-out、并行裁决、result 合并等能力需要单独设计 delivery、state、platform action 和 audit 语义，不属于当前 v1 契约。
+- `AgentRunnerDescriptor.source` 只允许 `plugin`；Host 内置 adapter 不能作为 runner source 绕过插件/runtime/proxy 权限链。
+- `ctx.resources` 与 proxy action 校验必须来自同一个 run authorization snapshot；runtime handler 不应重新执行资源裁剪。
+- v1 不要求 Agent、AgentRunner 插件实例或 runner id 全局串行。多个 bot / channel 可复用同一个 Agent；并发隔离依赖 `run_id`、binding、conversation / thread scope 和 Host authorization snapshot。
+- 外部 harness runner 当前是 MVP / dev path，证明协议可接入，不代表发布级安全边界或 Docker 生产可用性完成。
+
+## 14. 开放问题
+
+- `AgentBinding` 是否需要进入 SDK 文档作为只读诊断信息，还是完全 Host 内部。
+- State 与 Storage 的边界是否需要更强类型。
+- platform action 的审批模型如何表达。
+- Host 侧 scoped MCP / skill / workspace projection 是否需要从 runner config 上移为一等 resource projection API。

docs/agent-runner-pluginization/README.md

@@ -0,0 +1,154 @@
+# Agent Runner 插件化文档入口
+
+本文档是 agent-runner 插件化工作的路由页。具体设计拆到独立文档中维护，避免把 LangBot 宿主架构、SDK 协议、上下文管理、EBA 接入边界和官方 runner 迁移混在同一份 README 里。
+
+## 背景与问题
+
+旧 runner 路径主要围绕 Pipeline / Query 和 `pkg/provider/runners` 内置实现展开，扩展外部 agent runtime 时容易把 runner 选择、上下文裁剪、资源授权和消息投递绑在同一条聊天链路里。这个分支要把 LangBot 收敛成 Agent Host：Host 负责事件、绑定、授权、事实源和结果投递；AgentRunner 作为插件或外部 harness 消费统一协议并自主管理 prompt / history / memory。
+
+## 文档维护原则（单一事实源）
+
+- **协议数据结构（schema）唯一定义在 [PROTOCOL_V1.md](./PROTOCOL_V1.md)。** 其他文档不得重抄 schema，只能引用，例如"见 PROTOCOL_V1 §4.2"。
+- 当前实现状态、spec 差距与 runner 验收状态归 [STATUS.md](./STATUS.md)；测试执行入口归 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)，安全发布门槛归 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。
+- Host 内部模型（`AgentEventEnvelope`、`AgentBinding`、Descriptor、各 Store）定义在 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md)，不属于 SDK 协议。
+- 其余专题文档只讲"为什么/边界/怎么用"，避免重复叙述。
+
+## 本分支目标
+
+**本分支目标：AgentRunner 外化 / 插件化基础设施**
+
+本分支只做 LangBot 作为 Agent Host 的基础能力建设，为后续用 `Agent`
+替代 Pipeline 承载 agent 配置打底：
+
+- LangBot 与 SDK 的稳定协议合同（Protocol v1）
+- Host-side `AgentEventEnvelope` / `AgentBinding` 模型
+- `run(event, binding)` event-first 入口
+- `QueryEntryAdapter`：Query → AgentEventEnvelope + AgentBinding
+- EventLog / Transcript / PersistentStateStore
+- History / Event / State pull APIs
+- Sandbox/workspace read/write/exec 文件能力，用于当前 run 的上传文件、工具大结果和临时产物
+- SDK runtime forwarding pull APIs + `caller_plugin_identity` 验证路径
+
+## 本分支不实现
+
+以下能力由其他分支负责，本分支只保留 integration point。EBA 完整事件网关与事件路由当前由外部 EBA 分支联调：
+
+- **EventGateway / EventRouter**：完整事件网关实现、事件路由、事件持久化管理
+- **Event subscription / Event notification**：事件订阅、推送通知
+- **BindingResolver persistence UI**：绑定配置的持久化 UI 和 event router 集成（如由其他模块负责）
+- **Scheduler / Background event source**：定时任务、后台事件源
+- **完整 Agent Platform / daemon control plane**：Host-owned `AgentRun` / `AgentRunEvent`、run control primitives、最小 runtime heartbeat/claim lease 已作为 v2 foundation 落地；业务队列、Platform UI、daemon supervisor、runtime wakeup channel 和分布式 runtime 管控仍不属于 Protocol v1 主线。
+
+EventGateway / EventRouter 在本文档中描述为 **external EBA branch integration point**，由外部 EBA 分支提供并联调。本分支只定义 host-side envelope/binding models 和 `run(event, binding)` orchestrator 入口。
+
+本分支与外部 EBA / Agent Platform / Runtime Control Plane 的扩展边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。
+
+## 目标产品模型
+
+未来产品层应把 `Agent` 理解为 Pipeline 的替代物：原先 bot 绑定 Pipeline，Pipeline 携带 agent/provider/RAG/tool 等配置；后续应改为 bot 或 IM channel 绑定一个 Agent，Agent 携带 runner id、runner config、resource/state/delivery policy 等 agent 配置。
+
+调度基数、Agent 复用、插件实例无状态、Pipeline adapter 和 fan-out 边界的规范来源是 [PROTOCOL_V1.md](./PROTOCOL_V1.md) §13；README 不复写这些约束。
+
+## 当前入口关系
+
+**当前 Pipeline 是入口 adapter，不再是 agent runner 设计核心。**
+
+主入口仍可由 Pipeline 触发，但内部已转换成 event-first path：`run_from_query()` 经 `QueryEntryAdapter` 把 `Query` 转换为 `AgentEventEnvelope` + `AgentBinding`，再委托到统一的 `run(event, binding, ...)`。Pipeline path 因此获得了 event-first host capabilities（EventLog / Transcript / PersistentStateStore 写入，History / Event / State pull API 和 sandbox/workspace 文件读写能力可用）。
+
+下一轮测试路径、状态定义和 smoke 记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
+
+## 术语表
+
+| 术语 | 含义 |
+| --- | --- |
+| Protocol v1 | Host 调用 AgentRunner 的 runner 可见合同：discovery、`AgentRunContext`、result stream、Host pull API 和错误模型。 |
+| Agent | 目标产品层配置对象，保存 runner id、runner config 和资源/状态/投递策略；不等于插件实例。 |
+| AgentConfig | Host 内部迁移期配置投影，由当前 Pipeline config 或未来持久 Agent 生成。 |
+| AgentBinding / binding | Host 在一次事件运行前解析出的有效绑定，决定调用哪个 runner 以及带什么策略。 |
+| envelope | Host 内部事件封装，即 `AgentEventEnvelope`；runner 看到的是由它投影出的 `ctx.event`。 |
+| descriptor / manifest | runner discovery 的能力和配置描述；manifest 来自插件，descriptor 是 Host 校验后的注册表视图。 |
+| EBA | Event Based Agent，把消息、撤回、入群、定时任务等都统一成 host event 的接入方向；完整网关和路由在外部 EBA 分支联调。 |
+| harness runner | ACP、Claude Code、Codex 等已有自身 session / tool loop / MCP / 压缩机制的外部 runtime adapter。 |
+| projection | Host 把内部事实源、授权资源或配置裁剪成 runner / harness 可消费视图的过程。 |
+| Runtime Control Plane | v2 Host 能力层，当前已落地 Host-owned run/result ledger、run control primitives、最小 runtime heartbeat/claim lease；完整 daemon worker 管控、task wakeup 和 Agent Platform 产品形态不是 Protocol v1 主线。 |
+
+## 设计文档
+
+| 文档 | 关注点 |
+| --- | --- |
+| [PROTOCOL_V1.md](./PROTOCOL_V1.md) | **🔒 唯一 schema 事实源**。LangBot Host 与 SDK / Runtime / AgentRunner 的协议合同：版本协商、discovery、run context、result stream、proxy actions、错误和 adapter 边界。 |
+| [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md) | LangBot 宿主能力与分层架构、Host 内部模型（`AgentEventEnvelope` / `AgentBinding` / Descriptor / 各 Store）、runner 发现、绑定、资源授权、状态、存储、生命周期和调用链。 |
+| [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) | Agent-owned context 方向：事件到来时 LangBot 传什么，agent 如何按需拉取更多历史 / state、如何访问 sandbox/workspace 文件，以及如何支持 KV cache 友好的上下文管理。 |
+| [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md) | AgentRunner 外化与外部 EBA / Agent Platform / Runtime Control Plane 的扩展边界矩阵，说明哪些是本分支底座、哪些由外部分支接入。 |
+| [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md) | EBA 接入边界：事件模型、事件来源、触发绑定、非消息事件如何复用 AgentRunner 调度；完整 EventGateway / EventRouter 由外部 EBA 分支联调。 |
+| [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md) | Agent Platform v2 / runtime 管控面决策：`AgentRun` / `AgentRunEvent` / run control 已作为 Host 事实源落地，最小 runtime heartbeat/claim lease 已落地；完整 runtime registry / daemon 管控仍是后续可选阶段。 |
+| [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md) | 官方 runner 插件迁移，包括 local-agent 和外部 runner。它是下游落地计划，不是 LangBot 基础能力设计的前置约束。 |
+| [RUN_STEERING_AND_CHECKPOINT.md](./RUN_STEERING_AND_CHECKPOINT.md) | 运行中消息注入（steering / follow-up）与压缩摘要持久化（compaction checkpoint）的设计与落地状态记录；schema 仍以 PROTOCOL_V1 为准。 |
+| [STATUS.md](./STATUS.md) | 当前实现状态、spec 与实现已知差距、runner 验收状态和历史高价值记录。 |
+| [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md) | Agent Runner QA 指南：保留最高价值测试路径，指导 agent 开展下一轮 WebUI / runner smoke 验证。 |
+| [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) | 安全发布级 hardening 的后续发布门槛：路径隔离、权限边界、secret、资源配额、MCP / skill 投影和审计。 |
+
+## 工作拆分
+
+### 1. LangBot + SDK 基础设施
+
+目标是把 LangBot 从内置 runner 执行器变成 agent host：
+
+- LangBot 与 SDK 的稳定协议合同
+- runner manifest / descriptor / registry
+- Agent / binding 配置解析
+- run orchestration 和生命周期管理
+- resource authorization 与 `run_id` 级权限校验
+- host-owned state / storage / event log / transcript 能力
+- sandbox/workspace 文件 staging 与 read/write/exec 能力
+- SDK `AgentRunner`、`AgentRunContext`、`AgentRunResult`、`AgentRunAPIProxy`
+
+协议合同详见 [PROTOCOL_V1.md](./PROTOCOL_V1.md)。
+
+详见 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md)。
+
+### 2. Agent-owned context
+
+LangBot 不应成为最终 agentic context manager。它应提供事实源、默认上下文引用和按需读取 API；agent 或其背后的 runtime 负责历史剪裁、摘要、召回和 KV cache 策略。
+
+Host 不定义通用历史窗口字段或策略；runner 通过 Host pull API 按需拉取历史并自行管理 working context。
+
+详见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。
+
+### 3. Event Based Agent（External Branch）
+
+消息只是事件的一种。外部 EBA 分支中的 `message.received`、`message.recalled`、`group.member_joined`、`friend.request_received` 等事件都应能通过统一事件 envelope 触发 AgentRunner。
+
+EBA dispatch 的基数和 fan-out 边界仍以 PROTOCOL_V1 §13 为准；本文档只列出本分支提供给外部 EBA 分支复用的入口点。
+
+**本分支不实现 EBA 完整能力，只提供：**
+- event-first envelope (`AgentEventEnvelope`)
+- AgentBinding model
+- `run(event, binding)` 入口
+- QueryEntryAdapter（当前 AgentEventEnvelope / AgentBinding 的 Query entry adapter source）
+
+详见 [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md)。
+
+### 4. 官方 runner 插件
+
+官方 `local-agent` 和外部 runner 迁移是下游工作。它们需要依附 LangBot 提供的宿主能力，但不应反过来决定宿主协议。
+
+`local-agent` 可以外移，也可以重写。验收重点是它能完整消费 LangBot 的模型、工具、知识库、存储、事件、history API 和 result stream，而不是保留旧内置 runner 的内部结构。
+
+详见 [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md)。
+
+### 5. Runtime Control Plane v2（Foundation Partial）
+
+当前 AgentRunner v1 主线仍以 `event -> binding -> runner.run(ctx) -> result stream` 为 runner 可见合同。Host 侧已经新增持久 `AgentRun` / `AgentRunEvent`、result persistence、cancel/finalize/query 等通用 run control primitives，并提供受权限保护的最小 runtime register/heartbeat/list、claim/renew/release 和 reconcile 原语。
+
+在这些 Host 能力之上，可以构建独立 agent 管控面插件；插件负责 UI、策略和编排体验，runtime/task 的事实源仍由 Host 持有。完整 daemon supervisor、任务唤醒/长轮询/WebSocket、跨 Host 分布式锁、provider 登录态诊断和产品化业务队列仍是后续工作。
+
+详见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md)。
+
+## 约束事实源
+
+本分支已确认约束不在 README 重写：
+
+- Runner 可见协议、result stream 和调度边界见 [PROTOCOL_V1.md](./PROTOCOL_V1.md)。
+- Host 内部 `AgentConfig` / `AgentBinding` 投影见 [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md)。
+- 外部 EBA / Agent Platform / Runtime Control Plane 接入边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。

docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md

@@ -0,0 +1,541 @@
+# Agent Platform / Runtime Control Plane Decision Note
+
+本文档记录 AgentRunner 插件化之后，LangBot 如何继续演进成 Agent Platform 基础设施层。这里讨论的是 Host capability layer，不是 `AgentRunner Protocol v2`，也不是把某个具体 Agent Platform 产品写进 LangBot core。
+
+> 本文是当前决策版。协议数据结构仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准；测试执行入口见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)；扩展边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。
+>
+> 实现状态说明：本文描述的是 Runtime Control Plane v2 的目标能力和分阶段落地建议。当前 AgentRunner 插件化主线已经具备 event-first context、run-scoped authorization、EventLog / Transcript / State / sandbox 文件等 Host capability，并已落地持久 `AgentRun` / `AgentRunEvent` ledger、run control actions、最小 runtime heartbeat/claim lease 和 admin reconcile 原语。完整 Agent Platform 产品形态、daemon supervisor、runtime wakeup channel 和分布式 runtime 管控仍未完成。当前实现状态以 [STATUS.md](./STATUS.md) 为准。
+
+## 1. 当前决策
+
+LangBot 后续定位应更像 **Agent Host / infrastructure provider / transfer layer**，而不是把某个完整 Agent Platform 产品固化进 core。
+
+结论：
+
+- **Agent Platform 产品形态做成插件**。插件负责 agent 管理、策略、业务队列、UI、编排、多 agent 协作和产品体验。
+- **Agent Platform 所需的基础事实源做进 Host**。当前 Host 已保存 event、state、transcript、sandbox 文件边界、active run 权限快照、持久 run/result ledger、审计关联和通用控制状态。
+- **最小 runtime registry / heartbeat / claim lease 已作为 Host 原语落地，但不等于完整 daemon worker 管控**。远程 harness / daemon 的进程托管、wakeup channel、provider 登录态诊断和分布式调度仍可以先由 AgentRunner 插件和 SDK remote layer 自己维护。
+- **不把业务调度写进 Host**。Host 提供通用 run/result/control primitives，Platform 插件决定哪些事件触发哪些 agent、如何排队、如何分配、是否 fan-out。
+
+推荐分层：
+
+```text
+LangBot Host
+  Current base: EventLog / runtime AgentBinding / State / Transcript / sandbox files / active run authorization
+  Current v2 foundation: Run / RunEvent / audit / result persistence / control primitives / minimal runtime heartbeat and claim lease
+  Planned: Agent / Binding persistence / daemon supervisor / wakeup channel / distributed runtime operations
+
+Agent Platform plugin
+  Agent management UI / project-task model / event routing policy
+  Business queue / multi-agent orchestration / runtime selection policy
+
+AgentRunner plugin / external harness runtime
+  Connects ACP / remote daemon / local subprocess / HTTP API
+  Executes and converts provider-native events to AgentRunResult
+```
+
+## 2. Platform 与非 Platform 的区别
+
+当前 LangBot 已经具备 Agent Host 的核心特征：
+
+- 抹平不同 AgentRunner。
+- 从 IM / Pipeline 入口触发 runner。
+- 有 event-first context 方向。
+- 有 Host-owned EventLog / Transcript / State 和 sandbox/workspace 文件边界。
+- 有 runner config 下发和 active run-scoped authorization。
+- 有 `run_id` 串联 event、transcript、state、sandbox 文件和内存授权上下文。
+
+这还不是完整 Agent Platform。完整 Platform 至少还需要：
+
+- 可管理的 agent 资产：agent profile、binding、resource policy、runner config、可用状态。
+- 可观察的执行生命周期：run status、result stream、失败原因、文件引用、审计、回放。
+- 可运营的控制面：取消、重试、排队、并发、超时、恢复、诊断。
+- 可产品化的调度体验：事件订阅、路由策略、任务板、多 agent 协作、项目/工作区视图。
+
+因此，区别不只是“有没有调度”，而是是否具备：
+
+```text
+managed agent assets + observable run lifecycle + operational run control
+```
+
+Host 负责这些能力的通用事实源和安全边界；Platform 插件负责把它们组装成具体产品。
+
+### 2.1 当前实现边界
+
+当前代码中的 `run_id` 已经连接 active run 授权、持久 run ledger 和多个 Host 事实源：
+
+- `EventLog` 保存输入事件和审计入口，并记录 `run_id` / `runner_id`。
+- `Transcript` 保存对话历史投影，并用 `run_id` 关联 assistant 输出。
+- Sandbox/workspace 保存当前运行输入文件和 runner 产物，并用 `run_id` 做访问边界的一部分。
+- `PersistentStateStore` 保存 runner state，但不等同于 run lifecycle。
+- `AgentRunSessionRegistry` 保存 active run 的内存态授权快照，用于 proxy action 校验；进程结束或 run 结束后不作为可回放事实源。
+- `AgentRun` 保存 run lifecycle、scope、authorization snapshot、queue/claim 状态、cancel intent、usage/cost 和 metadata。
+- `AgentRunEvent` 保存 runner/result/admin event stream，按 `run_id + sequence` 做可回放分页。
+- `AgentRuntime` 保存最小 runtime registry / heartbeat 事实，用于 runtime list、stale mark 和 claim lease reconcile。
+
+因此本文后续提到的 `AgentRun` / `AgentRunEvent`、`run_append_result`、`run_finalize`、`run_cancel`、`runtime_register`、`runtime_heartbeat`、`run_claim` 等基础原语已经存在。仍未完成的是独立 platform `run_create` action、Host-owned Agent / Binding 持久模型、业务队列产品形态、daemon supervisor、runtime wakeup channel、跨 Host 分布式锁和 provider/runtime 诊断面。
+
+## 3. 基础概念
+
+### 3.1 Event
+
+Event 表示“发生了什么”：
+
+```text
+message.received
+github.issue.opened
+scheduler.tick
+user.approved
+system.webhook.received
+```
+
+EBA 负责把外部输入标准化成 event。Event 本身不是 queue，也不等同于一次 agent 执行。当前 `EventLog` 记录的是输入事件和审计事实；未来 `AgentRunEvent` 记录的是某次 run 的输出事件流，二者不能混用。
+
+### 3.2 Run
+
+Run 表示“某个 agent / binding / runner 针对某个 event 的一次执行”。
+
+Run 应由 Host 持久化，成为执行状态、结果、权限和审计的事实源：
+
+```text
+run_id
+event_id
+agent_id / binding_id
+runner_id
+status
+created_at / started_at / finished_at
+error / failure_reason
+delivery target
+metadata
+```
+
+当前 `AgentRunSessionRegistry` 只保存 active run 的内存态授权信息，不足以支撑 Platform 的回放、审计、取消、重试和异步执行。
+
+### 3.3 RunEvent / RunResult
+
+RunEvent 是一次 run 过程中产生的结果事件流，对应 runner 返回的 `AgentRunResult`。它不同于 EBA/EventLog 的输入事件：
+
+```text
+message.delta
+message.completed
+tool.call.started
+tool.call.completed
+state.updated
+action.requested
+run.completed
+run.failed
+```
+
+Host 应保存这些输出事件，按 `run_id + sequence` 可回放。Transcript、State 可以由这些 result event 触发写入现有 store，并保留能回溯到 `AgentRunEvent` 的关联。文件和工具大结果留在当前 run 的 sandbox/workspace 中，不作为 result event blob 回传。
+
+### 3.4 Queue
+
+Queue 不是 EBA 的替代品。
+
+EBA 负责产生 event；queue 负责处理“这个 event 对应的执行 work item 何时执行、谁来执行、如何取消/重试/恢复”。
+
+队列可以分两层：
+
+- **业务队列**：由 Platform 插件管理，例如项目任务、优先级、agent team、workflow、人工审批。
+- **执行队列 / run queue**：可选 Host 原语，例如 queued / running / completed / failed / cancelled、claim lease、dispatch timeout、orphan recovery。
+
+第一阶段不要求 Host 内置完整执行队列。Platform 插件可以先管理业务队列；在 Phase 1 / Phase 2 能力落地前，插件仍只能通过现有 `AgentRunOrchestrator.run(...)` 同步执行路径和现有 Host stores 获得有限的 run 关联能力。
+
+### 3.5 Runtime / Daemon
+
+Runtime / daemon 表示执行位置或执行能力，例如某台机器上的 Claude Code / Codex CLI。
+
+当前决策：
+
+- Host 不在第一阶段维护完整 runtime registry。
+- AgentRunner 插件可以通过 SDK remote layer 与 daemon 保持连接、心跳和执行通道。
+- 外部 harness / agent 不应直接访问 LangBot Host 或数据库。访问 LangBot 资源必须通过 daemon / AgentRunner plugin / SDK runtime / `AgentRunAPIProxy` / scoped MCP bridge，并接受 run-scoped authorization 校验。
+- 如果后续多个插件都需要共享 runtime 状态，再把薄的 `RuntimeLease` / registry 下沉为 Host 通用能力。
+
+## 4. Host 应新增的最小能力
+
+第一阶段最重要的不是 daemon registry，而是让 Host 成为 run/result 的事实源。
+
+### 4.1 AgentRun Store
+
+新增持久 `AgentRun`：
+
+```text
+id / run_id
+event_id
+agent_id
+binding_id
+runner_id
+conversation_id / thread_id
+workspace_id / bot_id
+status
+status_reason
+created_at / started_at / finished_at / updated_at
+deadline_at
+cancel_requested_at
+usage_json
+cost_json
+metadata_json
+```
+
+建议 status 至少包含：
+
+```text
+created
+running
+completed
+failed
+cancelled
+timeout
+```
+
+如果后续加执行队列，再引入：
+
+```text
+queued
+claimed
+dispatching
+```
+
+### 4.2 AgentRunEvent Store
+
+新增持久 `AgentRunEvent`：
+
+```text
+id
+run_id
+sequence
+type
+data_json
+usage_json
+created_at
+source
+metadata_json
+```
+
+约束：
+
+- 同一 `run_id` 内 `sequence` 单调递增。
+- append 必须幂等，支持远程 daemon / plugin 重试。
+- 未知 result type 可保存但 Host 只对已知类型执行副作用。
+- 大 payload 仍应进入 sandbox/workspace，不直接塞入 result event。
+- `usage_json` 保存 `AgentRunResult.usage` 原样结构；缺失表示 unknown，不等于 0。
+
+### 4.3 Run Control API
+
+Host 提供通用控制原语：
+
+```text
+run.create
+run.get
+run.list
+run.events.page
+run.cancel
+run.append_result
+run.finalize
+```
+
+语义：
+
+- `run.create` 创建 Host-owned run 和授权快照。
+- `run.append_result` 只允许受信 SDK/runtime 路径调用，必须绑定 run 创建时固化的授权快照，写入 `AgentRunEvent` 并触发 transcript/state/delivery 副作用。
+- `run.finalize` 关闭 run，更新 terminal status。
+- `run.cancel` 设置取消意图；同步 runner 通过 context/deadline 感知，远程 runner 通过插件/daemon 通道感知。
+
+第一阶段可以只暴露给插件 runtime action，不一定先做公开 HTTP API。
+
+### 4.4 Result Persistence In Orchestrator
+
+当前 `AgentRunOrchestrator.run()` 已经处理：
+
+```text
+event -> binding -> context -> runner invocation -> result normalization
+```
+
+需要补齐：
+
+- run 开始时创建 `AgentRun`。
+- 每个 `AgentRunResult` 进入 `AgentRunEvent`。
+- `run.completed` / 正常 generator 结束时标记 completed。
+- `run.failed` / exception / timeout 标记 failed 或 timeout。
+- terminal result 携带 usage 时，写入 `AgentRunEvent.usage_json` 并汇总到 `AgentRun.usage_json`。
+- `state.updated`、transcript 写入继续走现有 journal，但应与 `AgentRunEvent` 有可追踪关系。
+
+### 4.5 Usage / Cost Accounting
+
+SDK 侧 `AgentRunResult` 已提供可选 `usage` 字段，用于把不同 runner / external harness / provider-native event 的 token usage 归一到同一个 run result envelope。
+
+语义：
+
+- `run.completed.usage` SHOULD 表示本次 run 的最终聚合 token usage。
+- `run.failed.usage` MAY 表示失败前已知的部分 token usage。
+- 没有 usage 表示 upstream runtime 没有报告或 adapter 暂未接入；Host 不得按 0 计费或按 0 判断上下文消耗。
+- Host 应把 event-level usage 原样写入 `AgentRunEvent.usage_json`，并在 terminal event 或 finalize 阶段汇总到 `AgentRun.usage_json`。
+- cost 应由 Host 根据 usage、runner/model identity、发生时间和价格表计算，写入 `AgentRun.cost_json`；runner/provider 上报的 cost 只能作为非权威 telemetry 保留在 metadata 或 usage extra 中。
+
+这层约束先解决协议位置和持久化位置；具体 ACP、remote daemon、local subprocess runner 如何从 native event 中抽取 usage，可在各插件后续适配。
+
+### 4.6 Authorization Snapshot
+
+异步或远程执行时，run 创建时必须固化授权快照：
+
+- runner identity
+- binding identity
+- caller plugin identity
+- resource policy
+- allowed tools/models/files/knowledge bases/storage scopes
+- state scopes
+- conversation/thread/workspace scope
+
+后续 append result、state API、history API 和 sandbox/workspace 文件访问都以这个 snapshot 校验，不重新扩大权限。
+
+## 5. SDK 侧应新增的最小能力
+
+SDK 不需要马上定义完整 daemon registry，但需要让插件和 runner 使用 Host run/result 能力。
+
+### 5.1 Entities
+
+新增或补齐：
+
+```text
+AgentRun
+AgentRunStatus
+AgentRunEvent
+RunEventPage
+RunCreateRequest / RunCreateResult
+RunAppendResultRequest
+```
+
+这些是 Host control primitives，不替代 `AgentRunContext` / `AgentRunResult`。
+
+### 5.2 Proxy Methods
+
+在 SDK proxy 中提供：
+
+```python
+create_run(...)
+get_run(run_id)
+list_runs(...)
+page_run_events(run_id, cursor=None, limit=...)
+cancel_run(run_id)
+append_run_result(run_id, result, sequence=None)
+finalize_run(run_id, status, error=None)
+```
+
+访问边界：
+
+- 普通 AgentRunner 在同步 `run(ctx)` 内不一定需要直接调用这些 API；Host orchestrator 可自动记录。
+- Platform 插件可以创建/查询/取消 run。
+- AgentRunner 插件或 daemon bridge 可以 append/finalize 自己负责的 run。
+- 外部 harness 仍不能直接调用 Host；必须经 SDK runtime / proxy / bridge。
+
+### 5.3 Plugin-Daemon Heartbeat
+
+远程 daemon 的初始心跳可以是 SDK / AgentRunner plugin 私有能力：
+
+```text
+daemon <-> AgentRunner plugin / SDK remote layer <-> LangBot plugin runtime <-> Host
+```
+
+Host 第一阶段只需要知道：
+
+- 相关插件是否在线。
+- run 是否有 progress/result。
+- run 是否超时或取消。
+
+如果后续需要跨插件共享 daemon 可用性，再把 heartbeat/registry 下沉为 Host 能力。
+
+## 6. Platform 插件应负责什么
+
+Agent Platform 插件可以负责：
+
+- 管理哪些 agent 可用。
+- 维护产品层 agent profile、项目、任务板、workflow、team。
+- 订阅 EBA event，决定哪些 event 触发哪些 agent。
+- 维护业务 queue：优先级、重试策略、人工审批、分配规则。
+- 选择 runner / runtime / daemon。
+- 在 Run Control API 落地后，调用 Host run API 创建、取消、查询执行。
+- 展示 run status、result stream、文件引用、失败原因和审计。
+
+Platform 插件不应负责：
+
+- 在 Host Run Ledger 落地后，私有保存通用 run/result 事实源。
+- 绕过 Host 直接写 transcript/state 或越权访问 sandbox/workspace 文件。
+- 让外部 harness 直接访问 LangBot DB 或 Host 内部资源。
+- 把某个业务队列语义强塞进 AgentRunner Protocol v1。
+
+## 7. 与 EBA 的关系
+
+EBA 做好后，事件流可以进入两种路径。
+
+直接执行路径：
+
+```text
+EventGateway
+  -> EventRouter resolves AgentBinding
+  -> AgentRunOrchestrator.run(event, binding)
+  -> Host records AgentRun / AgentRunEvent (after Run Ledger lands)
+  -> delivery
+```
+
+Platform 插件编排路径：
+
+```text
+EventGateway
+  -> Platform plugin receives/subscribes event
+  -> plugin applies policy / business queue
+  -> plugin creates Host run (after Run Control API lands)
+  -> runner/plugin/daemon executes
+  -> Host records result and state
+  -> plugin displays / Host delivers
+```
+
+这两条路径最终应共享 Host run/result/state 事实源和 sandbox/workspace 文件边界。当前阶段可共享的是 event/transcript/state、sandbox 文件和同步执行链路；持久 run/result ledger 需要 Runtime Control Plane v2 Phase 1 补齐。区别在于是否有 Platform 插件参与产品化调度和业务队列。
+
+## 8. 与 AgentRunner Protocol v1 的关系
+
+本设计不改变 v1 的 runner 可见合同：
+
+```text
+AgentRunContext -> AgentRunner.run(ctx) -> AgentRunResult stream
+```
+
+必须保持：
+
+- `AgentRunContext` 不塞入 daemon/worker/pod 细节。
+- `AgentRunResult` 仍是 runner 输出的统一事件流。
+- 普通 runner 不需要知道 task queue / runtime registry。
+- 远程 harness 可以自管 session、tool loop、MCP、上下文压缩，但访问 LangBot 资源必须通过 SDK proxy / bridge。
+- Runtime-managed execution 是 placement / transport 选择，不是普通 runner 协议的强制概念。
+
+## 9. 分阶段实施建议
+
+### Phase 1: Run Ledger（Foundation Implemented）
+
+目标：Host 成为执行状态和结果事实源。
+
+范围：
+
+- `AgentRun` 表。
+- `AgentRunEvent` 表。
+- Orchestrator 自动创建/更新 run。
+- Journal 持久化每个 `AgentRunResult`。
+- Run 查询和事件分页 API。
+- SDK entities + proxy 方法。
+
+复杂度：中等。
+
+预计改动：
+
+```text
+Host: 12-20 个文件
+SDK: 4-8 个文件
+Tests: 8-15 个文件
+```
+
+### Phase 2: Platform Plugin Queue On Host Run Primitives（Control Primitives Partially Implemented; Product Queue Pending）
+
+目标：Platform 插件管理业务 queue，Host 提供 run/result/cancel 原语。
+
+范围：
+
+- `run.create`
+- `run.cancel`
+- `run.append_result`
+- `run.finalize`
+- result append 的 sequence/idempotency。
+- 受权限保护的远程 append/finalize。
+- Platform 插件可基于 Host run 构建任务板和调度体验。
+
+复杂度：中等偏高。
+
+预计改动：
+
+```text
+Host: 20-35 个文件
+SDK: 8-14 个文件
+Tests: 15-25 个文件
+```
+
+### Phase 3: Optional Host Execution Queue / Claim Lease（Claim Lease Primitive Implemented; Full Queue Pending）
+
+目标：当多个插件重复实现 claim/cancel/retry/recovery 时，再下沉执行队列到 Host。
+
+范围：
+
+- `queued/running/completed/failed/cancelled` 状态机扩展。
+- `claim_run` / `lease_until`。
+- dispatch timeout。
+- retry / orphan recovery。
+- cancel propagation。
+- 并发 claim 防重。
+
+复杂度：高。
+
+预计改动：
+
+```text
+Host: 35-55 个文件
+SDK: 12-20 个文件
+Tests: 25-40 个文件
+```
+
+### Phase 4: Optional Runtime Registry（Minimal Registry Implemented; Full Daemon Control Pending）
+
+目标：当 Host 需要统一管理多个 daemon / worker 时，再引入 runtime registry。
+
+范围：
+
+- runtime register / heartbeat / deregister。
+- capability report：provider、version、login status、workspace access、slot。
+- runtime online/offline。
+- runtime scoped auth。
+- runtime audit。
+- runtime gone recovery。
+- task wakeup / long polling / websocket。
+- 多 Host 实例下的 relay / distributed lock。
+
+复杂度：很高。
+
+预计改动：
+
+```text
+Host: 55-80+ 个文件
+SDK: 18-30 个文件
+Tests: 40+ 个文件
+```
+
+不建议现在直接进入此阶段。
+
+## 10. 设计原则
+
+- 先把 run/result 事实源做进 Host，再谈完整 runtime control plane。
+- Agent Platform 产品做插件；Host 做基础设施。
+- Host 不写业务调度策略，但要保存通用状态、结果、权限和审计。
+- EBA event 不是 queue；queue 是执行生命周期问题。
+- 业务 queue 可以先在 Platform 插件里；执行 queue 只有在复用需求明确后再下沉 Host。
+- Daemon registry 不应污染 AgentRunner Protocol v1。
+- 外部 harness 不直接访问 LangBot Host 或 DB。
+- 所有 LangBot 资源访问必须走 SDK runtime / `AgentRunAPIProxy` / scoped MCP bridge。
+- Docker / remote / local subprocess 只是 runtime placement，不是 runner 协议差异。
+
+## 11. 非目标
+
+当前阶段不做：
+
+- 完整 Multica 式 runtime registry。
+- Host 内置项目管理、任务板、agent team、workflow 产品逻辑。
+- 把 daemon heartbeat / worker liveness 放进 `AgentRunContext`。
+- 把业务 queue 定义为 AgentRunner Protocol 字段。
+- 让 Platform 插件私有保存 run/result 事实源。
+- 让外部 agent/harness 直连 Host 内部资源。
+
+## 12. 待定问题
+
+- Host 是否需要最小持久 `Agent` / `Binding` 模型，还是继续由 Pipeline / Platform 插件投影运行期 `AgentBinding`。
+- Platform 插件创建 run 时，是否传完整 `AgentBinding` snapshot，还是引用 Host-owned binding id。
+- `AgentRunEvent` 与现有 `EventLog` / `Transcript` 的查询关系：直接 join，还是通过专门 view 聚合。
+- `run.append_result` 的认证粒度：runner plugin identity、run token、scoped capability token，或 SDK runtime 内部 channel。
+- 取消语义：同步 runner、external harness runtime/session 如何统一感知 cancel。
+- 何时把插件私有 daemon heartbeat 提升为 Host `RuntimeLease`。
+- 若未来 Host 做 claim lease，Platform 插件业务 queue 与 Host execution queue 如何避免双队列混乱。

docs/agent-runner-pluginization/RUN_STEERING_AND_CHECKPOINT.md

@@ -0,0 +1,154 @@
+# Run Steering 与 Compaction Checkpoint（Design Note）
+
+本文档记录两项 Host/runner 协作能力：**运行中消息注入（steering / follow-up）**和
+**压缩摘要持久化（compaction checkpoint）**。两者来自官方 local-agent 对照
+Pi agent harness（`pi-mono/packages/agent`，下称 pi-agent-core）的差距分析：
+local-agent 已移植 Pi 的事件生命周期、并行工具语义、hook 扩展点和压缩预算模型，
+这两项需要 Host 协议、授权与 runner turn 边界协同才能闭环。
+
+> 本文是设计备忘，不是 schema 事实源。涉及的数据结构最终落到
+> [PROTOCOL_V1.md](./PROTOCOL_V1.md)；上下文边界语义以
+> [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) 为准；
+> run 持久化与控制原语以 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md) 为准。
+
+## 1. Run Steering / Follow-up（运行中消息注入）
+
+### 1.1 问题
+
+IM 场景下用户在 agent 运行中追加消息非常常见（补充信息、纠正方向、"算了别查了"）。
+当前主线是 `one event -> one AgentBinding -> one run_id -> one runner`
+（PROTOCOL_V1 §13）：同会话的新消息要么等待当前 run 结束后触发新 run，
+要么并发触发独立 run。两种行为都无法把新消息送进**正在执行的 tool loop**，
+用户体验是"agent 自顾自跑完过期任务，然后才看到新消息"。
+
+cancel（PROTOCOL_V1 §10）不解决这个问题：cancel 丢弃已完成的工作；
+steering 是在保留当前进度的前提下改变后续方向。
+
+### 1.2 Pi 的参考语义
+
+pi-agent-core 区分两个队列，注入时机都在 turn 边界，不打断进行中的模型流或工具执行：
+
+- **steering**：运行中插入。当前 assistant 消息的全部 tool call 完成后、
+  下一次模型调用前，注入排队的用户消息；模型在下一 turn 看到它们。
+- **follow-up**：排队后续工作。仅当没有 pending tool call 且没有 steering 消息、
+  run 即将自然结束时检查；若有排队消息则注入并继续下一 turn，而不是结束 run。
+
+两个队列各自支持 `one-at-a-time`（每次注入一条）和 `all`（一次注入全部）模式。
+
+### 1.3 设计方向
+
+职责划分遵循既有原则：Host 拥有事件路由和会话事实源，runner 拥有 turn 边界。
+
+- **Host 侧**：BindingResolver / dispatch 层识别"同 conversation 存在 active run
+  且 runner 声明支持 steering"的新消息事件，将其写入 run-scoped steering queue，
+  并标记该事件已被在途 run 认领（不再触发新 run，避免破坏 §13 的基数约束）。
+  事件仍照常进 EventLog / Transcript（事实源不变，改变的只是触发行为）。
+- **Runner 侧**：在 turn 边界（tool batch 完成后、下一次模型调用前，以及 run
+  即将自然结束前）通过 run-scoped pull API 拉取 pending steering 输入，
+  注入 working context。local-agent 的 `AgentLoopHooks.prepare_next_turn` /
+  `should_stop_after_turn` 已预留了对应的注入点。
+- **能力协商**：runner manifest 声明 `steering` capability（参照 PROTOCOL_V1 §4.3）；
+  未声明的 runner 保持现状（新消息按现有规则另起 run）。
+- **回执**：被 steering 消费的事件通过 EventLog 审计。原始 `message.received`
+  记录在 `metadata.steering` 标记 queued/absorbed 与 `claimed_by_run_id`；
+  runner 成功 pull 后，Host 追加 `steering.injected` 记录并引用源事件。
+  run 结束时仍未被 pull 的已 claim 输入，Host 追加 `steering.dropped` 记录作为
+  dispatch 终态；原始 Transcript 事实不删除。
+  Transcript 继续只表示会话事实，不扩展 dispatch 行为字段。
+
+已落地的协议面（最终定义归 PROTOCOL_V1）：
+
+1. `ContextAccess.available_apis` 增加 steering pull 能力位。
+2. `AgentRunAPIProxy` 增加 steering 拉取 action：默认 `mode=all`，Host 保序返回全部
+   pending 输入；`one-at-a-time` 仅作为 runner 主动节流选项。
+3. dispatch 层的"认领"规则：`message.received` 可被同 conversation 的 active run
+   吸收，原事件写 EventLog / Transcript，dispatch 行为写入 EventLog metadata。
+4. Host 对单 run steering queue 设置内存上限，队列满时不再 claim 新消息，消息回到
+   正常 dispatch 路径，避免 active run 无限吞入同会话输入。
+
+### 1.4 边界
+
+- 不引入 Host 替 runner 做 prompt 拼接：Host 只递队列，注入位置和格式由 runner 决定。
+- 不与 observer / fan-out 混淆：steering 仍是单 run 内的输入补充，不产生第二个 runner。
+- 远程 / 外部 harness runner（claude-code、codex 等）若其底层 session 自带
+  steering 能力，adapter 可以直接转发；协议面保持一致。
+
+## 2. Compaction Checkpoint 持久化
+
+### 2.1 问题
+
+local-agent 当前是无状态 runner：每次 run 重新拉取 transcript 尾部
+（默认 50 条）、重新估算 token、重新生成压缩摘要。后果：
+
+- 长会话中每 run 重复压缩计算，摘要每次重新生成，不同 run 之间措辞漂移，
+  对 provider KV cache 不友好（AGENT_CONTEXT_PROTOCOL §"Summary checkpoint 稳定"
+  已写明期望：只有压缩发生时才产生新 checkpoint）。
+- 历史一旦超过 fetch limit，更早的内容永久不可见——没有 checkpoint 记录
+  "已压缩到哪里、压缩出了什么"。
+
+pi-agent-core 把 compaction 条目持久化进 session tree：摘要带
+`tokensBefore` 和覆盖范围，后续 turn 直接复用，只在再次越过阈值时增量压缩。
+
+### 2.2 现状盘点
+
+协议面和主消费路径已具备：
+
+- State / Storage API 已定义（PROTOCOL_V1 §8 "State / Storage"），
+  且 AGENT_CONTEXT_PROTOCOL 已点名 `summary.checkpoint` 是 state 的预期用法。
+- Host 会根据 binding state policy 暴露 `ContextAccess.available_apis.state`。
+- local-agent 会在 state API 可用时读取/写入 `runner.compaction.checkpoint`；
+  缺失、schema 不匹配、conversation 不匹配或游标失败时回退尾部历史拉取。
+- LLM 生成摘要**不依赖**本项 Host 能力——runner 用已授权的 `invoke_llm`
+  即可生成；checkpoint 只解决"存下来、下次复用"。
+
+### 2.3 设计方向
+
+- **存放位置**：state，scope=`conversation`（小 JSON，符合 PROTOCOL_V1 §8
+  对 state/storage 的边界建议）。若未来摘要膨胀，超出部分放 storage 并在
+  state 中留引用。
+- **key 约定**：`runner.compaction.checkpoint`（runner 命名空间内）。
+- **内容约定**（schema 落 PROTOCOL_V1 或 runner 文档，此处只列语义）：
+  - `schema_version`
+  - `summary`：压缩摘要文本（LLM 生成或确定性生成）
+  - `covers_until`：已被摘要覆盖的 transcript 游标（seq / message id），
+    是增量压缩和"从哪继续拉历史"的锚点
+  - `tokens_before` / `created_at`：诊断与失效判断
+- **消费流程**：run 开始时读 checkpoint → 只拉取 `covers_until` 之后的
+  transcript → 压缩触发时基于旧摘要增量生成新摘要、写回新 checkpoint。
+  checkpoint 缺失或解析失败时回退到现行为（全量拉尾部），保证向后兼容。
+- **失效规则**：`covers_until` 在 Host transcript 中不存在（会话被清理 / 重置）
+  即作废；runner 不得信任跨 conversation 的 checkpoint。
+- **授权**：Host 对声明需要 state 的 runner binding 开启
+  `available_apis.state`；校验沿用现有 run-scoped state 校验
+  （scope、key、value 大小、JSON 可序列化，见 PROTOCOL_V1 §7.2 对
+  `state.updated` 的要求）。
+
+### 2.4 相关但独立的工作
+
+- **tokenizer / usage metadata 透传**：runner 目前用 chars/4 启发式估 token，
+  对 CJK 偏低 3-4 倍，压缩触发系统性偏晚。Host 应在模型响应或
+  `ctx.runtime.metadata` 透传 provider usage（prompt/completion tokens）与
+  model context window（LiteLLM model-info 工作）。该项不阻塞 checkpoint
+  落地，但决定压缩触发的准确性。
+
+## 3. 实施拆分
+
+| 项 | 归属 | 依赖 |
+| --- | --- | --- |
+| steering queue、事件认领、基础审计 | LangBot Host（dispatch / binding 层） | 已落地，含队列上限与未消费 dropped 终态 |
+| steering pull API + capability 位 | PROTOCOL_V1 + SDK proxy | 已落地 |
+| turn 边界拉取与注入 | langbot-local-agent | 已落地 |
+| local-agent 对 state API 的 checkpoint 读写 | langbot-local-agent | 已落地 |
+| checkpoint key / 内容 / 失效约定 | PROTOCOL_V1 + local-agent README | 已落地 |
+| LLM 压缩摘要生成 | langbot-local-agent | 已落地（`invoke_llm`，失败回退确定性摘要） |
+| usage / context-window metadata 透传 | LangBot Host（model 层） | LiteLLM model-info |
+
+剩余工作应优先补 usage / context-window metadata。streaming delivery 衔接依赖
+`ctx.delivery` 编辑/追加语义，不建议在协议能力缺失时硬编码。
+
+## 4. 开放问题
+
+- streaming delivery 下 steering 注入后，前序 turn 已流出的内容与新 turn
+  输出在 IM 消息编辑面的衔接（涉及 `ctx.delivery` 能力，待 delivery 演进定）。
+- checkpoint 是否需要 Host 侧主动失效通知（如会话清空时删除对应 state key）。
+  当前实现靠 runner 读取时校验并回退，功能不阻塞。

docs/agent-runner-pluginization/SECURITY_HARDENING.md

@@ -0,0 +1,209 @@
+# Agent Runner Security Boundary
+
+本文档记录 agent-runner 插件化后的安全边界和最小护栏。
+
+## 状态
+
+**当前结论：不采用高强度监管模型。**
+
+LangBot 的目标不是托管一个强隔离、不可信 code runner 平台。AgentRunner 插件，尤其是 ACP / Claude Code / Codex / OpenCode / Kimi Code 这类外部 harness，默认视为 **operator-owned execution**：用户或部署者显式配置并承担其文件系统、进程、网络、workspace、provider 登录态和 native tool 风险。
+
+LangBot 需要负责的是保护 **LangBot 自己持有的资源**，包括模型、知识库、LangBot tools、history、event、state、plugin/workspace storage、sandbox/workspace 文件访问等。只要这些资源访问是 run-scoped、permission-scoped、可校验、可诊断的，当前阶段即可接受。
+
+这意味着：
+
+- 不要求 LangBot 在应用层实现完整 OS sandbox、VM、cgroup、seccomp、CPU / memory / network quota。
+- 不要求为 ACP runner 做复杂审批流；用户选择 ACP runner 即表示显式 opt-in。
+- 不要求在非 Docker 进程部署里做强监管；只要文档明确风险归属即可。
+- Docker / K8s 可以提供部署级隔离，但不是 LangBot agent-runner 协议发布的前置条件。
+- 不能宣传 LangBot 已经提供 managed sandbox；除非未来真的提供受管执行环境。
+
+## 责任边界
+
+### LangBot Host 负责
+
+- **资源授权**：根据 runner manifest permissions、binding resource policy、run scope 生成本次 run 可访问的资源快照。
+- **运行期校验**：所有带 `run_id` 的 SDK / Host action 必须校验 active run session、caller plugin identity、resource id 和 operation。
+- **Scoped projection**：只把授权后的资源摘要、MCP server config、context、attachment/path ref、state snapshot 投影给 runner。
+- **LangBot 文件路径约束**：LangBot 自己 staged 和读取的文件必须限制在声明 root 内，防止 path escape。
+- **基础 secret 策略**：不要主动把 LangBot 持有的 API key / token / secret 投影给 runner；日志和错误里做常见 secret 字段脱敏。
+- **基础运行约束**：提供 timeout、取消传播、输出大小限制或错误映射的基础能力。
+- **audit-lite**：记录 event、run id、runner id、binding、资源授权摘要、关键失败、state/file/transcript 事实。
+
+### Runner Plugin 负责
+
+- 遵守 Host 下发的 `ctx.resources`、`ctx.context.available_apis`、runner config 和 state policy。
+- 把 LangBot 资源投影成目标平台可消费的形式，例如 MCP config、context prompt、HTTP header、run token。
+- 不绕过 SDK / Host action 直接访问 LangBot 内部资源。
+- 对自己启动的外部进程做合理封装，包括参数构造、timeout、取消、输出解析和错误映射。
+- 清楚记录自身 README 中的 provider 风险、部署假设和限制。
+
+### 部署者 / 用户负责
+
+- ACP / external harness 的 workspace 内容、文件系统访问、进程权限、网络访问、provider-native tool 权限。
+- Docker / K8s 的 image、volume、secret、network policy、resource limit、namespace、service account 配置。
+- 本机进程部署时的 OS 用户权限、PATH、HOME、CLI 登录态、全局配置和外部 MCP 配置。
+- 是否允许 runner 对某个目录执行真实写操作。
+
+### 外部 Harness 负责
+
+Claude Code、Codex、OpenCode、Kimi Code、Gemini CLI 等外部工具继续使用自己的权限模型、MCP 加载策略、session/resume、sandbox 或 approval 能力。LangBot 不承诺约束这些工具对其所在容器或宿主 OS 用户本来可访问资源的能力。
+
+## 部署场景策略
+
+| 场景 | LangBot 策略 | 不由 LangBot 承担 |
+| --- | --- | --- |
+| 普通进程部署 | 文档提示 operator-owned execution；Host 只保护 LangBot 资源。 | 阻止外部 CLI 读取同一 OS 用户可访问的文件、进程、HOME、全局 CLI 配置。 |
+| Docker / K8s 部署 | 继续使用相同 Host 资源边界；容器隔离由部署环境提供。 | 应用层重复实现容器/VM/cgroup/seccomp/network quota。 |
+| ACP runner | 用户显式选择 runner 和 workspace；LangBot 注入 scoped MCP / run token。 | ACP CLI native tools、workspace 写入、provider 登录态和外部 MCP 行为。 |
+| 外部 SaaS runner，例如 Dify | LangBot 通过 run token / gateway 限制 LangBot 资产访问。 | SaaS 平台内部 agent 执行策略、模型工具消息格式、平台侧日志。 |
+| 未来 managed runner | 只有当 LangBot 明确提供受管执行环境时，才需要单独定义强隔离 SLA。 | 当前协议闭环不承诺 managed sandbox。 |
+
+## 最小护栏
+
+以下是当前阶段需要维持的最小要求。它们是保护 LangBot 资源边界的要求，不是完整监管外部进程的要求。
+
+### Resource Permission Boundary
+
+每次 run 前必须冻结授权快照：
+
+- runner manifest permissions 是资源访问上限。
+- binding resource policy / runner config 决定本次实际授权。
+- runtime action 按 `run_id` + `caller_plugin_identity` + resource id + operation 校验。
+- manifest permissions 只约束 LangBot 持有资源，不约束 external harness native tools。
+
+当前实现方向是正确的：`AgentRunSessionRegistry` 保存 run-scoped snapshot，`plugin/handler.py` 对模型、工具、知识库、history、state、storage 等 action 做运行期校验，sandbox/workspace 文件访问由 scoped tool 边界控制。
+
+### MCP / Asset Gateway Boundary
+
+LangBot MCP / asset gateway 只暴露当前 run 授权的工具面：
+
+- `langbot_list_assets`
+- `langbot_get_current_event`
+- `langbot_history_page`
+- `langbot_retrieve_knowledge`
+- `langbot_get_tool_detail`
+- `langbot_call_tool`
+
+外部平台需要使用短期 `run_token` 或 Authorization bearer token。token 缺失、错误或过期时必须拒绝访问。
+
+不要求当前阶段实现 admin 级 MCP allowlist、dangerous tool approval 或复杂审批流。是否注册外部 MCP provider 是部署者/用户行为。
+
+### Workspace / Path Boundary
+
+LangBot 只需要约束自己管理的路径：
+
+- Host staged 文件必须校验 `realpath` 和 root containment。
+- Attachment/file metadata 不应暴露 Host-only storage key / host path。
+- Context 文件、sandbox/workspace 文件如由 LangBot 创建，应放在可清理的位置。
+
+用户配置给 ACP runner 的 workspace 不属于 LangBot 的强监管范围。Docker/K8s 下依赖 volume 挂载边界；普通进程部署下依赖 OS 用户权限和用户自担风险。
+
+### Secret Handling
+
+这里的 secret 指 API key、provider token、run token、MCP token、platform secret、数据库密码等。
+
+当前阶段只要求基础策略：
+
+- LangBot 不主动把自己持有的 secret 投影给 runner，除非这是 runner config 明确需要的外部服务凭据。
+- run token 是短期、run-scoped 的，不应长期保存。
+- 日志、错误、transcript、attachment/file metadata 尽量避免打印常见 secret 字段。
+- 配置 UI / API 返回时继续沿用现有 secret masking 规则。
+
+不要求当前阶段实现完整 DLP、全链路敏感数据追踪、secret lineage 或自动轮换体系。
+
+### Process / Runtime Bounds
+
+LangBot 需要提供基本可控性：
+
+- Host run deadline / runner timeout。
+- runner 侧请求 timeout。
+- generator close / cancel 传播。
+- 输出和 inline payload size 上限。
+- 错误映射为受控 runner failure。
+
+不要求 LangBot 为外部 harness 实现 CPU、内存、磁盘、网络、进程树强隔离。需要这些能力时由 Docker/K8s、systemd、容器平台或用户机器策略提供。
+
+### UI / Admin Surface
+
+前端可以展示 runner 权限摘要，但它是信息披露，不是审批系统。
+
+权限摘要指 runner manifest 声明的 LangBot 资源权限，例如：
+
+- `tools.detail`
+- `tools.call`
+- `knowledge_bases.retrieve`
+- `history.page`
+- `storage.plugin`
+
+当前阶段不要求强制弹窗、管理员审批、dangerous tool approval 或生产禁用开关。可以在 runner 配置区展示简短提示：此 runner 能访问哪些 LangBot 资源，外部 harness 执行风险由用户/部署者承担。
+
+### Audit Lite
+
+需要记录足够排查问题的事实：
+
+- run id、runner id、binding、event。
+- 授权资源摘要。
+- state update、file write/read event、transcript message。
+- MCP / pull API 拒绝时的 warning。
+- steering queued / injected / dropped。
+
+不要求当前阶段建立独立安全审计产品、审批记录系统或 SIEM 级事件模型。
+
+## 降级后的检查表
+
+| 项目 | 当前要求 | 状态判断 |
+| --- | --- | --- |
+| Path isolation | 只约束 LangBot 管理的 context/sandbox 文件路径；runner workspace 归用户/部署环境。 | Minimal required |
+| Permission boundary | 必须保护 LangBot 资源；不约束外部 CLI native 能力。 | Required |
+| Secret handling | 基础不投影、基础 masking、run token 短期化。 | Basic required |
+| MCP policy | run-scoped token + scoped tool surface；无复杂审批。 | Required |
+| Skill access policy | 通过 Host 授权资源暴露；harness-native skill 文件不作为 LangBot 安全边界。 | Basic required |
+| Process isolation | 由 Docker/K8s/用户机器负责。 | Out of scope |
+| State lifecycle | scope 隔离、JSON size limit、基础 cleanup primitive。 | Basic required |
+| Audit | 记录运行事实和拒绝原因。 | Audit-lite |
+| UI / Admin control | 权限摘要可展示；不要求审批流。 | Optional |
+| Test matrix | 覆盖 run auth、MCP token、permission deny、timeout、sandbox path、state size。 | Focused tests |
+
+## 当前实现快照
+
+截至 2026-06-15，已有实现覆盖：
+
+- SDK typed AgentRunner manifest、capabilities、permissions。
+- Host resource builder 按 manifest permissions 和 binding policy 生成 `ctx.resources`。
+- Active run session snapshot 和 `caller_plugin_identity` 校验。
+- History / event / state / tool / knowledge runtime action 的 run-scoped 校验。
+- Sandbox file path `realpath` + root containment。
+- Persistent state scope 隔离和 JSON size limit。
+- SDK-owned MCP bridge 和 long-lived asset gateway。
+- Dify / ACP runner 对 LangBot asset gateway 的接入。
+- Runner timeout、Dify HTTP timeout、ACP startup / initialize / request timeout。
+
+仍可继续优化但不阻塞当前发布的事项：
+
+- 前端展示 runner LangBot 资源权限摘要。
+- 常见 secret 字段 redaction 收敛成统一 helper。
+- Context/sandbox file TTL cleanup 调度。
+- 更完整的 MCP 调用 audit。
+- 更好的文档提示：ACP runner 是 operator-owned execution。
+
+## 非目标
+
+以下不属于当前 agent-runner pluginization 的安全目标：
+
+- 防止 ACP / external harness 修改其 workspace。
+- 防止外部 CLI 读取同一容器或 OS 用户本来可读的文件。
+- 管控 external harness 的 provider-native tools、approval、MCP、browser、shell。
+- 在 LangBot 应用层实现 VM / container / cgroup / seccomp / network policy。
+- 为 Docker/K8s 部署替代平台自身的 secret、volume、network、resource limit 管理。
+- 实现企业级审批系统、SIEM、DLP 或安全运营面板。
+
+## 发布口径
+
+可以对外说明：
+
+> AgentRunner 插件通过 run-scoped authorization 和 scoped MCP gateway 保护 LangBot 持有资源。外部 code harness 的执行环境由用户或部署平台负责隔离；LangBot 当前不提供 managed sandbox。
+
+不能对外说明：
+
+> LangBot 已经安全沙箱化 Claude Code / Codex / OpenCode 等外部 runner。

docs/agent-runner-pluginization/STATUS.md

@@ -0,0 +1,57 @@
+# AgentRunner Pluginization Status
+
+本文档是 `docs/agent-runner-pluginization/` 的状态事实源。协议 schema 仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准；测试步骤以 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md) 为准；安全发布门槛以 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) 为准。
+
+状态快照日期：2026-06-16。
+
+## 实现状态
+
+| 领域 | 状态 | 说明 |
+| --- | --- | --- |
+| SDK manifest schema | Done | `AgentRunnerManifest` 包含 typed `capabilities` / `permissions`；未知 capability / permission key 禁止进入 typed model。 |
+| Runner discovery | Done | Runtime 返回 typed manifest；Host registry 校验单个 runner，失败 warning + skip，不影响其它 runner。 |
+| Host resource authorization | Done | `ctx.resources` 和 `ctx.context.available_apis` 由 manifest permissions 与 binding policy / run scope 求交后生成。 |
+| Run authorization snapshot | Done | active run session 冻结 run-scoped resources 与 available APIs；runtime handler 按 snapshot 校验 pull API。 |
+| Result payload validation | Done | Wire 保持 `{type, data}`；Host 对投递/副作用类 payload 严格校验，tool-call telemetry 宽松，未知 type 忽略并 warning。 |
+| Old built-in runners | Done | 旧 `src/langbot/pkg/provider/runners/*` 与 `RequestRunner` 路径已从本分支删除。 |
+| Official runner manifests | Done | `local-agent`、ACP / Claude Code / Codex 外部 harness runner、外部服务 runner 已重新声明真实生效的 LangBot resource permissions。 |
+| Runtime Control Plane v2 foundation | Partial | Host-owned `AgentRun` / `AgentRunEvent` ledger、orchestrator 自动建账、result event persistence、run get/list/event page/cancel/append/finalize actions 已落地；`agent_run:admin` / `runtime:admin` 控制权限、最小 runtime register/heartbeat/list/reconcile 和 run claim/renew/release 原语已落地。完整 Agent Platform 产品形态、daemon supervisor、任务唤醒/长轮询/WebSocket、分布式 runtime 管控仍未完成。 |
+| Security boundary | Done | 当前口径降级为轻量边界：LangBot 保护自身持有资源；external harness 的 OS / process / network / workspace 风险由用户或部署环境承担；managed sandbox 不是当前承诺。 |
+| Steering control path | Done | claim 异常不再逃逸 consumer loop；queue 有上限；未 pull 的 claimed 输入在 run 结束时写 `steering.dropped` 审计终态。 |
+| SDK v1 contract closure | Done | SDK 提供 `AgentAPIError` / `AgentAPIException`、typed `SteeringPullResult`、未知 result type 宽容解析、result `sequence` 注入与取消传播。 |
+
+## Spec 与实现已知差距
+
+- `action.requested` 仍只作为 telemetry / reserved surface；platform action executor 不在本分支执行。
+- EventGateway / EventRouter 完整实现由外部 EBA 分支联调；本分支只提供 event-first host envelope / binding / run 入口。
+- State 与 storage 的长期类型边界仍可继续收窄；当前合同只要求 JSON-safe state 与受控 storage API。
+- EventLog / Transcript 已提供显式 cleanup primitive；长期 retention 默认值、TTL 调度接入和 sandbox/workspace 文件清理仍是运维收尾项，应在 Runtime Control Plane 产品化前补齐。
+- External harness 的 native shell / filesystem / CLI / MCP 权限不受 manifest permissions 约束；manifest permissions 只约束 LangBot 持有的资源访问。
+- LangBot 当前不承诺 managed sandbox；external harness 的 OS/process/network quota、workspace GC、provider-native tool 权限由用户或部署环境承担。
+- Runtime Control Plane v2 当前只落地 Host 事实源和控制原语；还没有内置 Agent Platform UI、业务队列、daemon 进程托管、runtime wakeup channel、跨 Host 分布式锁或 provider 登录态诊断。
+
+## Runner 验收状态
+
+| Runner | 状态 | 最近证据 |
+| --- | --- | --- |
+| `plugin:langbot/local-agent/default` | Unit-pass; UI smoke pending | 2026-06-10 本地 pytest / ruff 通过；WebUI smoke 由人工统一执行。 |
+| `plugin:langbot/acp-agent-runner/default` / `plugin:langbot/claude-code-agent/default` / `plugin:langbot/codex-agent/default` | Unit-pass; E2E pending | 通过 runner 仓库单测覆盖 session、run_id 注入和 LangBot MCP gateway；真实 harness E2E 取决于对应运行环境、CLI/daemon 可用性和 provider 登录态。 |
+| Dify / n8n / Coze / DashScope / Langflow / Tbox / DeerFlow / WeKnora | Unit-pass; credential smoke optional | 2026-06-13 plugin layout / parser tests 通过；真实服务凭据 smoke 非每轮必跑。 |
+
+## Host / SDK 验收状态
+
+| 范围 | 状态 | 最近证据 |
+| --- | --- | --- |
+| LangBot Runtime Control Plane v2 foundation | Unit-pass; product E2E pending | 2026-06-16 `tests/unit_tests/agent/test_run_ledger_store.py`、`test_run_ledger_api_auth.py`、`test_orchestrator_integration.py` 通过，覆盖 ledger、admin permissions、runtime heartbeat、claim/reconcile、orchestrator 持久化和取消传播。 |
+| SDK AgentRunner control entities / proxy | Unit-pass | 2026-06-16 SDK agent-runner 相关单测通过，覆盖 typed run ledger entities、AgentRunAPIProxy、MCP bridge、runtime manager 与 pull API handlers。 |
+
+## 历史高价值记录
+
+历史报告已合并为本状态页和 QA 指南，不再保留单独进度文档。后续若需要追溯，优先查看 `langbot-skills/reports/` 下的原始执行报告。
+
+截至 2026-05-29，已有本地 smoke 证明：
+
+- `local-agent` 可以通过 Pipeline Debug Chat 走插件化 `AgentRunOrchestrator` 主链路。
+- 外部 harness runner 可以通过同一条 `run(event, binding)` 路径执行；当前官方实现已收敛到 ACP / Claude Code / Codex 等直接 runner 插件。
+
+这些记录只证明本地协议闭环可用，不代表 LangBot 提供 managed sandbox 或 external harness OS 级隔离。

docs/review/box-architecture.md

@@ -0,0 +1,595 @@
+# Box 系统架构深度分析
+
+> 更新日期: 2026-06-02
+> 状态更新: 自部署社区版已具备发布条件（box 可选、降级完善、无迁移欠债）；工具调用循环上限、配额遍历异步化、`host_path` 挂载白名单等已落地。剩余多租户 / 安全硬化项见 [SaaS 阻塞项清单](./box-issues.md)。
+> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
+> 相关文档: [SaaS 阻塞项](./box-issues.md) | [Session 作用域](./box-session-scope.md) | [Runtime 对比](./box-vs-plugin-runtime.md) | [测试覆盖](./box-test-coverage.md) | [toB 分析](./box-tob-analysis.md)
+
+---
+
+## 1. 全局架构
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       LangBot 主进程                              │
+│                                                                   │
+│  LocalAgentRunner ──> ToolManager ──> NativeToolLoader            │
+│       │                    │              │                       │
+│       │                    │      exec / read / write / edit      │
+│       │                    │              glob / grep             │
+│       │                    │                                      │
+│       │                    ├──> MCPLoader ──> BoxStdioSession     │
+│       │                    │       (shared 容器, 多 process)       │
+│       │                    │                                      │
+│       │                    ├──> SkillToolLoader (activate 工具)    │
+│       │                    │                                      │
+│       │                    ├──> SkillAuthoringToolLoader          │
+│       │                    │                                      │
+│       │                    └──> PluginToolLoader                  │
+│       │                                                           │
+│  BoxService (门面)                                                 │
+│    ├─ Profile 管理 (locked 字段)                                   │
+│    ├─ Host mount 校验 (allowed_mount_roots)                        │
+│    ├─ Workspace quota 检查                                         │
+│    ├─ 输出截断 (head+tail)                                         │
+│    ├─ Session ID 模板解析 (resolve_box_session_id)                 │
+│    ├─ 技能挂载组装 (build_skill_extra_mounts)                      │
+│    ├─ 重连循环 (_reconnect_loop, 指数退避)                          │
+│    └─ BoxRuntimeConnector                                          │
+│         ├─ 心跳 loop (20s ping)                                    │
+│         └─ ActionRPCBoxClient                                      │
+│              │  Action RPC (stdio 或 WebSocket)                    │
+│                                                                    │
+│  SkillManager (skill_mgr)                                          │
+│    └─ 从 Box runtime 拉取 skills, 不可用时回落 data/skills          │
+└──────────────────────────────────────────────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────────────────────────────┐
+│              Box Runtime 进程 (SDK 侧)                            │
+│                                                                   │
+│  BoxServerHandler (Action RPC 处理, INIT 配置注入)                  │
+│       │                                                           │
+│  BoxRuntime (session 管理 / 进程生命周期 / TTL reaper)              │
+│       │       └─ session.managed_processes: dict[pid, _ManagedProcess]
+│       │                                                           │
+│  Backend (启动时根据 box.backend 配置选择):                          │
+│    DockerBackend ──┐                                              │
+│    PodmanBackend ──┤── CLISandboxBackend                          │
+│    NsjailBackend ──┘  (本地 CLI 或 fallback 到容器内 CLI)            │
+│    E2BBackend         (云沙箱, 需要 E2B_API_KEY)                    │
+│                                                                   │
+│  BoxSkillStore                                                    │
+│    ├─ list / get / create / update / delete                       │
+│    ├─ scan_skill_directory / read_skill_file / write_skill_file   │
+│    └─ preview_skill_zip / install_skill_zip (zip 或 GitHub)        │
+│                                                                   │
+│  aiohttp 单端口服务 (默认 :5410):                                    │
+│    /rpc/ws                                       — Action RPC      │
+│    /v1/sessions/{id}/managed-process/ws          — 默认 process     │
+│    /v1/sessions/{id}/managed-process/{pid}/ws    — 指定 process     │
+└──────────────────────────────────────────────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  容器 / 沙箱 (Docker/Podman 容器, nsjail sandbox, 或 E2B 远程沙箱)  │
+│  - 隔离文件系统 / 网络 / PID 命名空间                                │
+│  - 资源限制 (CPU, 内存, PID 数, 可选 workspace 配额)                 │
+│  - 主挂载 (host_path → mount_path) + 任意条 extra_mounts             │
+│      └─ Skills 通过 extra_mounts 挂在 /workspace/.skills/<name>     │
+│  - exec: 用户命令在此执行                                            │
+│  - managed process: 多个长驻进程并存 (MCP Server / 自定义服务)        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**核心设计原则**:
+- Box Runtime 作为独立进程运行，通过 Action RPC 与 LangBot 主进程通信，两者复用 SDK 的 IO 层（Handler → Connection → Controller）
+- 一个 session_id 对应一个容器/沙箱实例。同一 session 内可并存多条 mount 与多个 managed process
+- Skill / 默认 exec / MCP Server 共享同一个 session 容器（详见 [box-session-scope.md](./box-session-scope.md)）
+
+---
+
+## 2. LangBot 侧模块
+
+### 2.1 BoxService (`pkg/box/service.py`, 722 行)
+
+应用层门面，协调 Profile、安全校验、配额、连接、Skill 挂载与 Session 模板：
+
+主要公开方法（按定义顺序）：
+
+```
+BoxService
+  ├─ initialize()                              连接 Box Runtime + 默认 workspace 准备
+  ├─ _on_runtime_disconnect(connector)         触发重连
+  ├─ _reconnect_loop(connector)                指数退避重连
+  ├─ available (property)                      连接状态
+  │
+  ├─ resolve_box_session_id(query)             从 pipeline 模板解析 session_id
+  ├─ build_skill_extra_mounts(query)           组装 pipeline-bound skill 的挂载列表
+  │
+  ├─ execute_tool(parameters, query)           Agent 调用 exec 时的入口
+  │    ├─ _apply_profile / build_spec
+  │    ├─ _validate_host_mount
+  │    ├─ _enforce_workspace_quota (phase=pre)
+  │    ├─ client.execute(spec)
+  │    ├─ _enforce_workspace_quota (phase=post)
+  │    └─ _truncate (stdout/stderr)
+  │
+  ├─ execute_spec_payload(spec_payload, ...)   内部入口（其他 loader 调用）
+  ├─ create_session(spec_payload, ...)         显式创建 session
+  ├─ start_managed_process(session_id, ...)    启动 managed process
+  ├─ get_managed_process(session_id, pid)      查询进程状态（pid 默认 'default'）
+  ├─ stop_managed_process(session_id, pid)     单独停止某个 managed process
+  ├─ get_managed_process_websocket_url(...)    返回 WS attach URL
+  │
+  ├─ list_skills() / get_skill(name)           Skill 元数据
+  ├─ create_skill / update_skill / delete_skill  Skill CRUD
+  ├─ scan_skill_directory(path)                扫描目录
+  ├─ list_skill_files / read_skill_file / write_skill_file
+  ├─ preview_skill_zip / install_skill_zip     zip / GitHub 安装
+  │
+  ├─ shutdown() / dispose()                    清理：RPC SHUTDOWN + 进程终止
+  ├─ get_status() / get_sessions() / get_recent_errors()
+  └─ get_system_guidance()                     LLM 系统提示
+```
+
+**Profile 系统**: 4 个内置 Profile（`default` / `offline_readonly` / `network_basic` / `network_extended`），`locked` frozenset 字段不可被 LLM 覆盖。参数合并顺序：Profile defaults → LLM 请求参数 → locked 强制值。
+
+**输出截断**: 默认 4000 字符上限，保留前 60% + 后 40%，中间插入 `[...truncated...]`。
+
+**Skill 挂载合并**: `execute_tool()` 调用时，`build_skill_extra_mounts(query)` 会把当前 pipeline-bound 的所有 skill 的 `package_root` 作为 `extra_mounts` 加入 BoxSpec，挂在 `/workspace/.skills/<name>`。LLM 通过 `activate` 工具显式激活某个 skill 后，工具调用才允许引用这个 skill 的虚拟路径。
+
+### 2.2 BoxRuntimeConnector (`pkg/box/connector.py`, 357 行)
+
+管理与 Box Runtime 的通信连接：
+
+- **本地 stdio**: Unix/macOS 默认路径，fork `python -m langbot_plugin.cli.__init__ box -s --ws-control-port {port}` 子进程（与 plugin runtime 统一走 `lbp` CLI 入口）
+- **本地 subprocess + WS**: Windows 本地（asyncio ProactorEventLoop 不支持 stdio pipe）
+- **远程 WebSocket**: Docker 部署 / `box.runtime.endpoint` 显式配置时，连接 `ws://{host}:{port}/rpc/ws`
+- **同步等待**: `asyncio.Event` + `wait_for(timeout=30s)` 模式确认连接
+- **心跳**: `_heartbeat_loop()` 每 20s 调用 `ping()`，失败仅 DEBUG 日志（断开检测靠 connection close）
+- **重连**: `runtime_disconnect_callback` 由 BoxService 提供，触发 `_reconnect_loop`
+- **INIT 注入**: 连接建立后立即下发当前 `box.*` 配置子树（剔除 `runtime` 私有字段），Runtime 据此初始化 backend
+
+> **历史改进**: 2026-04-16 版本本文档曾列 P0 「Box 无心跳 / 无重连」，已修复（commit `2dfd9d5d`、`c6882cf`、`5029d9c` 等）。
+
+### 2.3 BoxWorkspaceSession 工具 (`pkg/box/workspace.py`, 413 行)
+
+此文件目前提供两类能力：
+
+1. **路径与命令重写工具函数** — `normalize_host_path` / `rewrite_mounted_path` / `unwrap_venv_path` / `rewrite_venv_command` / `infer_workspace_host_path`，被 MCP loader 与 Skill 路径解析共用。
+2. **`BoxWorkspaceSession`** — 围绕 BoxService 的轻量包装，专供 MCP-in-Box 场景使用（管理一个共享 session 的 session_id、构建挂载 payload、stage host 文件到共享 workspace）。
+
+**变化点**: 早期 Skill exec 会为每个 skill 创建独立 BoxWorkspaceSession（独占 session）；当前实现已转为 `extra_mounts` 模式，Skill 不再独占容器，只追加挂载。这部分 wrapping 逻辑已从 native loader 移除。
+
+### 2.4 policy.py (`pkg/box/policy.py`, 98 行) — 仍是死代码
+
+三层安全策略设计（`SandboxPolicy` / `ToolPolicy` / `ElevatedPolicy`），全项目无任何导入或调用。详见 [SaaS 阻塞项 S2](./box-issues.md)。
+
+### 2.5 SkillManager (`pkg/skill/manager.py`, 186 行)
+
+```
+SkillManager
+  ├─ initialize()                  调用 reload_skills()
+  ├─ reload_skills()               先从 Box runtime list_skills()，
+  │                                 不可用则回落 data/skills/ 扫描
+  ├─ refresh_skill_from_disk()     单 skill 重新加载
+  ├─ get_skill_by_name(name)
+  └─ get_managed_skills_root()     返回 Box 视角的 skills_root 路径
+```
+
+skill 元数据通过 `parse_frontmatter` 解析 `SKILL.md` 头部（`name` / `description` / `instructions`），不再做整体扫描的代价（典型 < 50 个）。
+
+### 2.6 Skill activation (`pkg/skill/activation.py`, 33 行) + Skill loader 辅助
+
+历史上 skill 通过 LLM 在文本中输出 `[ACTIVATE_SKILL:name]` 标记激活；当前已改为 **Tool Call 机制**：
+
+- `SkillToolLoader` (`pkg/provider/tools/loaders/skill.py`, 157 行) 暴露 `activate` 工具，参数为 skill 名
+- 工具实现调用 `register_activated_skill(query, skill_data)`，将激活态写入 `query.variables['_activated_skills']`
+- 这种 KV-cache-friendly 模式对齐 Claude Code 设计；详见 [box-session-scope.md §4.3](./box-session-scope.md) 的 Tool Call 描述
+
+`activation.py` 现仅保留对外辅助函数（pipeline 层调用 loader 的 `register_activated_skill`）。
+
+---
+
+## 3. SDK 侧模块
+
+### 3.1 BoxRuntime (`box/runtime.py`, 599 行)
+
+核心编排器，管理 session 生命周期与 backend 调度：
+
+```
+Session 生命周期:
+
+  Client EXEC / CREATE_SESSION
+       │
+       ▼
+  _get_or_create_session(spec)
+    ├─ _reap_expired_sessions_locked()   清理 TTL 过期 session
+    ├─ 已存在? → _assert_session_compatible() → 复用
+    ├─ Backend session 失踪? → 重建 (commit c6882cf)
+    └─ 新建? → backend.start_session(spec) → 创建容器
+       │       └─ 应用 spec.extra_mounts （多挂载）
+       ▼
+  execute(spec)
+    ├─ 获取 session lock (每 session 独立)
+    ├─ backend.exec(session, spec)       在容器中执行命令
+    ├─ 更新 last_used_at
+    └─ 超时? → 销毁 session
+       │
+       ▼
+  Session 保持存活直到:
+    ├─ TTL 过期 (默认 300s，下次操作时清理)
+    ├─ 执行超时 (自动销毁)
+    ├─ 客户端 DELETE_SESSION
+    └─ SHUTDOWN
+```
+
+**关键设计**:
+- 每 session 有独立 `asyncio.Lock`，同一 session 内的命令串行执行
+- 每 session 维护 `managed_processes: dict[process_id, _ManagedProcess]`，支持多个长驻进程并存（MCP / 自定义）
+- 全局 `_lock` 保护 `_sessions` dict 的读写
+- 兼容性检查：比较核心 spec 字段，`image` 字段对不支持自定义镜像的 backend（nsjail/E2B）会跳过
+
+**Backend 选择 (`_select_backend`)**: 优先级
+1. 显式 `box.backend` 配置（`docker` / `nsjail` / `e2b`）
+2. `local` (默认) → Docker / Podman / nsjail CLI 顺序探测
+3. `get_status` 调用时若当前 backend 不可用，会尝试重新选择 (commit `e5617c7`)
+
+### 3.2 Backend 系统
+
+#### CLISandboxBackend (`box/backend.py`, 411 行)
+
+Docker / Podman 公共基类：
+
+```
+start_session(spec):
+  1. validate_sandbox_security(spec)
+  2. docker/podman run -d --rm --name <name>
+     --network none (可选)
+     --cpus/--memory/--pids-limit
+     --read-only + --tmpfs /tmp
+     -v <host>:<mount>:<mode>          主挂载
+     -v <extra.host>:<extra.mount>:..  额外挂载 (extra_mounts)
+     <image> sh -lc 'while true; do sleep 3600; done'
+  3. 返回 BoxSessionInfo
+
+exec(session, spec):
+  docker/podman exec -e KEY=VAL <container>
+    sh -lc 'mkdir -p <workdir> && cd <workdir> && <cmd>'
+
+start_managed_process(session, spec):
+  docker/podman exec -i <container>
+    sh -lc 'mkdir -p <cwd> && cd <cwd> && exec <command> <args>'
+  返回 asyncio.subprocess.Process (stdin/stdout PIPE)
+```
+
+容器以 idle 进程启动，实际命令通过 `docker exec` 执行。`--rm` 确保容器退出时自动清理。
+
+**Windows 支持**: backend 内对 Windows 路径处理与 subprocess 调用做了适配（commit `120817a`）。
+
+**孤儿清理**: 启动时枚举 `langbot.box=true` 标签的容器，instance_id 不匹配的强制删除。
+
+#### NsjailBackend (`box/nsjail_backend.py`, 552 行)
+
+轻量级 Linux 沙箱（无容器引擎依赖）：
+
+- 使用 namespace 隔离（user/mount/pid/ipc/uts/cgroup/net）
+- 挂载宿主 `/usr`/`/lib`/`/bin`/`/sbin` 只读 + 选定 `/etc` 条目
+- 每 session 创建独立目录（workspace/tmp/home）
+- 资源限制: cgroup v2 优先，fallback 到 rlimit
+- **CLI 兼容**: 通过 `shutil.which(self._nsjail_bin)` 检测系统安装版 nsjail；不存在时再尝试容器内 nsjail（commit `686fcc0`、`feed530`）
+- **无自定义镜像**: 使用宿主 OS，`image` 字段固定为 `'host'`，兼容性检查跳过 image
+
+#### E2BBackend (`box/e2b_backend.py`, 429 行)
+
+云沙箱后端（commit `75b547f` 引入）：
+
+- 通过 `e2b` SDK 与 E2B 平台通信
+- 配置：`box.e2b.api_key` / `api_url` / `template`
+- 支持 `extra_mounts`（commit `0fea9b1` 同步上传文件）
+- 无本地容器引擎依赖，适合无 Docker 的部署或 SaaS 多租户场景
+- 不支持自定义 image 字段，由 template 控制
+
+### 3.3 Server (`box/server.py`, 508 行)
+
+单端口 aiohttp 服务（默认 5410），通过路径区分（commit `8c71ec5` 合并端口）：
+
+1. **Action RPC** (`/rpc/ws`): `BoxServerHandler` 处理所有 action，包括 `INIT` 配置注入、skill store 操作等
+2. **WS Relay** (`/v1/sessions/{id}/managed-process/ws` 与 `/v1/sessions/{id}/managed-process/{pid}/ws`): 双向桥接 WebSocket ↔ 指定 managed process stdin/stdout
+
+stdio 模式同样会在 5410 启动 aiohttp，专门承担 managed process attach；Action RPC 走 stdin/stdout。
+
+### 3.4 Client (`box/client.py`, 377 行)
+
+`ActionRPCBoxClient` 封装 `Handler.call_action()` 调用：
+
+- 25+ 方法对应 25+ 个 RPC action（exec / session / managed-process / skill / status / shutdown）
+- 错误还原: `_translate_action_error()` 通过字符串前缀匹配还原 SDK 侧异常类型
+- `execute()` timeout = 300s，其他默认 15s
+- `BoxRuntimeClient` 是 ABC，供后续可能的非 RPC 实现复用
+
+包级别 `__init__.py` 显式导出：`BoxRuntimeClient`、`ActionRPCBoxClient`（commit `df9c722`）。
+
+### 3.5 Actions (`box/actions.py`, 34 行)
+
+`LangBotToBoxAction` 枚举共定义 **25 个** action：
+
+| 类别 | Actions |
+|------|---------|
+| 控制 | `INIT`、`HEALTH`、`STATUS`、`GET_BACKEND_INFO`、`SHUTDOWN` |
+| 执行 | `EXEC` |
+| Session | `CREATE_SESSION` / `GET_SESSION` / `GET_SESSIONS` / `DELETE_SESSION` |
+| Managed Process | `START_MANAGED_PROCESS` / `GET_MANAGED_PROCESS` / `STOP_MANAGED_PROCESS` |
+| Skill | `LIST_SKILLS` / `GET_SKILL` / `CREATE_SKILL` / `UPDATE_SKILL` / `DELETE_SKILL` / `SCAN_SKILL_DIRECTORY` / `LIST_SKILL_FILES` / `READ_SKILL_FILE` / `WRITE_SKILL_FILE` / `PREVIEW_SKILL_ZIP` / `INSTALL_SKILL_ZIP` |
+
+### 3.6 Models (`box/models.py`, 331 行)
+
+核心数据模型：
+
+| 模型 | 用途 |
+|------|------|
+| `BoxNetworkMode` | `OFF` / `ON` |
+| `BoxExecutionStatus` | `COMPLETED` / `TIMED_OUT` |
+| `BoxHostMountMode` | `NONE` / `READ_ONLY` / `READ_WRITE` |
+| `BoxManagedProcessStatus` | `RUNNING` / `EXITED` |
+| `BoxMountSpec` | 单条挂载（host_path/mount_path/mode）— **新增** |
+| `BoxSpec` | 执行请求；新增 `extra_mounts: list[BoxMountSpec]`、`persistent`、`workspace_quota_mb` |
+| `BoxProfile` | 4 个内置 Profile + `locked` frozenset |
+| `BoxSessionInfo` | Session 状态（含 backend_name/created_at/last_used_at） |
+| `BoxManagedProcessSpec` | 长驻进程参数（process_id/command/args/env/cwd） |
+| `BoxManagedProcessInfo` | 进程状态（status/exit_code/stderr_preview/attached） |
+| `BoxExecutionResult` | 执行结果（status/exit_code/stdout/stderr/duration_ms） |
+
+`BoxSpec` 校验器: `workdir` 默认继承 `mount_path`；`host_path` 支持 POSIX 和 Windows 路径；设置 `host_path` 时 `workdir` 必须在 `mount_path` 下。
+
+### 3.7 BoxSkillStore (`box/skill_store.py`, 647 行)
+
+新增模块（commit `4ab3502`），把 skill 持久化收归 Box runtime：
+
+```
+BoxSkillStore
+  ├─ list_skills() / get_skill(name)
+  ├─ create_skill(data) / update_skill(name, data) / delete_skill(name)
+  ├─ scan_skill_directory(path)            扫描目录返回候选 skill 包列表
+  ├─ list_skill_files(name, path)          浏览 skill 内文件树
+  ├─ read_skill_file(name, path) / write_skill_file(name, path, content)
+  ├─ preview_skill_zip(zip_bytes, ...)     不落盘预览 zip 内容
+  └─ install_skill_zip(zip_bytes, ...)     解压、校验、复制到 skills_root
+     └─ 支持 source_subdir / target_suffix（commit 1aa043f）
+```
+
+GitHub 安装路径：HTTP 层（`api/http/service/skill.py`）先 `git clone` 拉取，再走 `install_skill_zip` 或 directory 路径。Skill 文件存放于 `box.local.skills_root`（默认 `skills`，相对 `host_root`），容器内对应 `/workspace/.skills/`。
+
+### 3.8 Security (`box/security.py`, 52 行)
+
+`validate_sandbox_security()`: 黑名单校验 host_path，阻止挂载 `/etc`/`/proc`/`/sys`/`/dev`/`/root`/`/boot` 及 Docker/Podman socket。
+
+**已知缺陷**: 根路径 `/` 未拦截，用户 home 目录未拦截，是 denylist 而非 allowlist 策略。详见 [SaaS 阻塞项 S5](./box-issues.md)。
+
+### 3.9 Errors (`box/errors.py`, 33 行)
+
+| 异常类型 | 含义 |
+|----------|------|
+| `BoxError` | 基类 |
+| `BoxValidationError` | spec/参数校验失败 |
+| `BoxBackendUnavailableError` | 无可用 backend |
+| `BoxRuntimeUnavailableError` | Runtime 服务不可用 |
+| `BoxSessionConflictError` | session 已存在但 spec 不兼容 |
+| `BoxSessionNotFoundError` | session 不存在 |
+| `BoxManagedProcessConflictError` | session 已有同名 process |
+| `BoxManagedProcessNotFoundError` | process 不存在 |
+
+---
+
+## 4. 工具系统集成
+
+### 4.1 ToolManager 编排 (`toolmgr.py`)
+
+```
+ToolManager.initialize()
+  ├─ NativeToolLoader      (exec / read / write / edit / glob / grep)
+  ├─ PluginToolLoader      (插件工具)
+  ├─ MCPLoader             (MCP Server 工具)
+  ├─ SkillToolLoader       (activate 工具 — Tool Call 激活)
+  └─ SkillAuthoringToolLoader  (Skill CRUD)
+
+工具调用优先级: native → plugin → mcp → skill → skill_authoring
+```
+
+### 4.2 Native Tools (`native.py`, 846 行)
+
+| 工具 | 是否在 Box 中执行 | 是否访问宿主文件系统 |
+|------|:---:|:---:|
+| `exec`  | 是 | 否 |
+| `read`  | **否** | **是** — 直接 `open()` 宿主文件 |
+| `write` | **否** | **是** — 直接 `open()` 宿主文件 |
+| `edit`  | **否** | **是** — 直接 `open()` 宿主文件 |
+| `glob`  | **否** | **是** — 直接遍历宿主目录 |
+| `grep`  | **否** | **是** — 直接读宿主文件 |
+
+**沙箱边界不对称**: 这是刻意的设计权衡 — `read`/`write`/`edit`/`glob`/`grep` 绕过沙箱以获得性能（避免容器 I/O 开销与跨进程拷贝），但意味着 LLM 可以直接读写 `allowed_mount_roots` 下任何文件。Skill 路径经 `_resolve_host_path()` 重写，禁止穿越 `package_root`。
+
+**exec 的 Skill 分支**: 命令中引用 `/workspace/.skills/<name>` 的 skill 时：
+1. 验证 skill 已激活
+2. 单次 exec 只能引用一个 skill 包
+3. 若 skill 是 Python 项目（有 `requirements.txt` 或 `pyproject.toml`），命令会被 venv bootstrap 包裹（在 skill 挂载点内创建 `.venv`）
+4. 调用 `box_service.execute_tool()` → 走默认 session_id 与已组装好的 `extra_mounts`，**不再为每 skill 起独立 session**
+
+### 4.3 MCP-in-Box (`mcp_stdio.py`, 354 行)
+
+`BoxStdioSessionRuntime` 让 MCP stdio 服务器在 Box 容器中运行，**共享 session、多 process**模式（commit `529088e`）：
+
+```
+initialize()
+  1. 复用/创建共享 session (session_id = _build_box_session_id())
+     - persistent=True，长期保持
+  2. workspace.execute_raw(install_cmd) 安装依赖 (可选)
+  3. 将每个 MCP server 文件 stage 到 /workspace/.mcp/<process_id>/
+  4. workspace.start_managed_process(process_id=<server>)
+  5. websocket_client(ws_url) 通过 WS relay 连接
+  6. ClientSession.initialize() MCP 协议握手
+```
+
+配置 (`MCPServerBoxConfig`): `network='on'` (MCP 服务器通常需要网络)，`host_path_mode='ro'` (默认只读)，`startup_timeout_sec=120` (留时间给 pip install)。
+
+每条 MCP server 是同一 session 中的一个 managed process，独立的 `process_id`、独立 attach URL，互不阻塞。
+
+---
+
+## 5. 启动与生命周期
+
+### 5.1 启动顺序 (`build_app.py`)
+
+```
+BuildAppStage.run(ap)
+  ├─ ... (persistence, models, sessions) ...
+  │
+  ├─ BoxService(ap)
+  ├─ box_service.initialize()
+  │    └─ connector.initialize()
+  │         ├─ [stdio] fork box subprocess
+  │         ├─ [subprocess+WS] Windows 本地
+  │         └─ [remote WS] connect URL
+  │    └─ 启动心跳 _heartbeat_task
+  ├─ ap.box_service = box_service
+  │
+  ├─ ToolManager(ap)
+  ├─ tool_mgr.initialize()
+  │    ├─ NativeToolLoader   (检查 box_service.available)
+  │    ├─ PluginToolLoader
+  │    ├─ MCPLoader          (Box 可用时，stdio MCP 走沙箱)
+  │    └─ SkillAuthoringToolLoader
+  ├─ ap.tool_mgr = tool_mgr
+  │
+  ├─ ... (platform, pipeline) ...
+  ├─ SkillManager.initialize()    (从 Box runtime 加载 skill 列表)
+  └─ ... (RAG, HTTP, plugins) ...
+```
+
+BoxService 在 ToolManager **之前**初始化。ToolManager 创建 loader 时检查 `box_service.available`。
+
+### 5.2 初始化失败处理
+
+```python
+try:
+    await self._runtime_connector.initialize()
+    self._available = True
+except Exception as e:
+    self._available = False
+    logger.warning(f"Box runtime unavailable: {e}")
+```
+
+**静默降级**: Box 初始化失败不会阻止应用启动，仅导致 6 个 native tool、所有 Skill 工具和 MCP-in-Box 工具不暴露给 LLM。与 Plugin 的行为不同（Plugin 失败会抛异常）。
+
+### 5.3 销毁流程
+
+```
+app.dispose()
+  └─ box_service.dispose()
+       ├─ connector.dispose()
+       │    ├─ cancel _heartbeat_task
+       │    ├─ cancel _handler_task / _ctrl_task
+       │    └─ terminate subprocess (SIGTERM)
+       └─ loop.create_task(client.shutdown())
+            └─ RPC SHUTDOWN → Box Runtime 清理所有容器
+```
+
+Box 额外做了 RPC SHUTDOWN 通知 Runtime 主动清理容器，比 Plugin 的直接杀进程更安全。
+
+---
+
+## 6. 配置
+
+### config.yaml (重构后)
+
+```yaml
+box:
+    enabled: true         # 整个 Box 子系统的总开关。设为 false 时：
+                          #  - 不连接远程 Box runtime，不 fork 本地 stdio 子进程
+                          #  - sandbox 工具 (exec/read/write/edit/glob/grep) 不暴露给 LLM
+                          #  - skill 添加/编辑 / GitHub 安装 / 文件写入全部拒绝
+                          #  - stdio 模式的 MCP server 启动时报错（http/sse 模式不受影响）
+                          #  - skill 列表/读取保持只读可用
+                          # BOX__ENABLED 环境变量可覆盖（统一约定）
+    backend: 'local'      # 'local' (探测) / 'docker' / 'nsjail' / 'e2b'
+                          # 由 box.backend / BOX__BACKEND 选择后端
+    runtime:
+        endpoint: ''      # 外部 Runtime 的 WS 基地址 'ws://host:5410'
+                          # 留空 = 本地自管 Runtime
+    local:
+        profile: 'default'
+        image: ''                       # 覆盖 profile 默认 image
+        host_root: './data/box'         # 工作区挂载根，Docker 部署需绝对路径
+        default_workspace: ''           # 默认 '<host_root>/default'
+        skills_root: 'skills'           # Box 管理的 skill 包目录（相对 host_root）
+        allowed_mount_roots:            # 默认 ['<host_root>']
+            - './data/box'
+            - '/tmp'
+        workspace_quota_mb: null        # 配额覆盖，null = 走 profile
+    e2b:
+        api_key: ''                     # 也可走 E2B_API_KEY 环境变量
+        api_url: ''                     # 自托管 E2B 时填写
+        template: ''                    # 默认 template ID
+```
+
+> **重大变更**: 较 2026-04-16 文档，配置结构完全重组（commit `eefdea4`）。原字段 `box.profile` / `box.runtime_url` / `box.shared_host_root` / `box.allowed_host_mount_roots` 全部迁入 `box.local.*` 子表，新增 `box.backend` 与 `box.e2b.*` 配置组。
+
+### docker-compose.yaml
+
+`langbot_box` 服务受 compose profile 控制,默认 `docker compose up` **不会**启动它。需要 sandbox 时:
+
+```bash
+docker compose --profile box up        # 启动 langbot + langbot_box + plugin runtime
+docker compose --profile all up        # 同上
+docker compose up                       # 只起 langbot + plugin runtime (box 关闭)
+```
+
+若不起 `langbot_box`,需要同步在 `data/config.yaml` 中设 `box.enabled: false`(或 langbot 容器 env 加 `BOX__ENABLED=false`),否则 LangBot 会一直尝试连接不存在的 Box runtime 并报错。
+
+```yaml
+# langbot_box 的关键 volume
+volumes:
+  - ${LANGBOT_BOX_ROOT}:${LANGBOT_BOX_ROOT}         # 工作区挂载(源/目标同路径)
+  - /var/run/docker.sock:/var/run/docker.sock       # Docker backend 复用宿主 docker
+```
+
+### 关闭/连接失败时的行为矩阵
+
+`box.enabled = false` 与"启用但连接失败"在用户可观察行为上**完全一致**——都通过 `BoxService.available = False` 表达,只是 `get_status` 多返回 `enabled` 字段供前端区分文案。
+
+| 消费方 | Box 可用 | Box 不可用(disabled 或 failed) |
+|---|---|---|
+| native exec/read/write/edit/glob/grep 工具 | 暴露给 LLM | **不暴露** |
+| `activate` / `register_skill` 工具 | 暴露给 LLM | **不暴露** |
+| stdio MCP server | 在 Box 内启动 | **`_init_stdio_python_server` 抛 RuntimeError** 拒绝;不退化到宿主 stdio |
+| http/sse MCP server | 正常 | 正常(不依赖 Box) |
+| Skill 列表/读取 (`list_skills`/`get_skill`/`read_skill_file`) | 走 Box runtime | 走 LangBot 本地 `data/skills/` 只读 fallback |
+| Skill 创建/编辑/安装/写文件 | 走 Box runtime | **HTTP 400** + 明确错误信息(`_require_box_for_write`) |
+| Pipeline AI 配置中 `box-session-id-template` | 正常生效 | **前端 banner** 提示字段无效 |
+| Pipeline 扩展页 `enable_all_skills` / 绑定 skill | 可编辑 | **前端禁用** + banner |
+| 仪表盘 Box 状态卡片 | 绿点 / "已连接" | 灰点 / "已禁用"(disabled) 或 红点 / "已断开"(failed) |
+
+> 后端拒写的边界条件:如果 `ap.box_service` **完全没装**(老式 dev mode,没经过 BuildAppStage),`_require_box_for_write` 视作 no-op,保留 `data/skills/` 本地路径——以兼容历史测试与最小化设置。生产环境总会装 `ap.box_service`,因此该 fallback 不会被触发。
+
+### Pipeline 配置 (templates/metadata/pipeline/ai.yaml)
+
+`local-agent.config.box-session-id-template` 控制 session 作用域，预设：
+
+- `{launcher_type}_{launcher_id}` — 每个会话 (推荐，默认)
+- `{launcher_type}_{launcher_id}_{sender_id}` — 群聊每个用户
+- `{launcher_type}_{launcher_id}_{conversation_id}` — 每个对话上下文
+- `{query_id}` — 每条消息（完全隔离）
+
+详见 [box-session-scope.md](./box-session-scope.md)。
+
+### REST API
+
+| 端点 | 方法 | 说明 | 前端 |
+|------|------|------|:---:|
+| `/api/v1/box/status` | GET | 可用性、Profile、后端信息 | ✅ 监控页 |
+| `/api/v1/box/sessions` | GET | 活跃 session 列表 | ❌ |
+| `/api/v1/box/errors` | GET | 最近 50 条错误 | ❌ |
+| `/api/v1/skills` 等 | GET/POST/PUT/DELETE | Skill CRUD、文件浏览、zip/GitHub 安装、preview | ✅ Skill 管理页 |
+
+前端 `web/src/app/home/monitoring/components/overview-cards/SystemStatusCards.tsx` 已接入 `/api/v1/box/status`，展示 backend 名称、profile 与活跃 session 数。Sessions 与 errors API 仍未接入。

docs/review/box-issues.md

@@ -0,0 +1,76 @@
+# Box 系统 — SaaS 发布前阻塞项
+
+> 更新日期: 2026-06-02
+> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
+> 相关文档: [架构分析](./box-architecture.md) | [Session 作用域](./box-session-scope.md) | [Runtime 对比](./box-vs-plugin-runtime.md) | [测试覆盖](./box-test-coverage.md) | [toB 分析](./box-tob-analysis.md)
+
+## 范围说明
+
+**自部署社区版已具备发布条件**：默认 stdio 模式、box 为可选项；box 关闭 / 不可用时后端、前端、工具、skill、stdio-MCP 均能干净降级（清晰报错、不崩溃）；配置向后兼容（旧 `data/config.yaml` 可直接启动）；无新增 ORM 模型、无迁移欠债；市场安装失败不会破坏实例。CI 全绿。
+
+本清单**只保留发布 SaaS / 多租户 / 公网暴露前必须处理的阻塞项**。社区版（可信、单运营者、内网）不受这些项阻塞——它们的风险面在"不可信调用方能直接触达 Box 控制面"或"多租户共享资源"的场景才成立。
+
+## 已解决（社区版发布前）
+
+| 项 | 处理 |
+|----|------|
+| 工具调用循环无上限 (原 #13) | `localagent.py` 增加 `MAX_TOOL_CALL_ROUNDS=128`，超限优雅终止（`cafef1a3`） |
+| 配额校验同步遍历阻塞事件循环 (原 #10) | `_enforce_workspace_quota` 改 async，工作区遍历走 `asyncio.to_thread`（`cafef1a3`） |
+| `host_path` 挂载白名单 (原 #3 的 LangBot 侧) | `pkg/box/service.py` `allowed_mount_roots` 白名单，空列表时拒绝一切宿主挂载 |
+| 重复的 `_is_path_under` (原 #12) | 已去重，仅保留一处定义 |
+| 重连 / 心跳 / Windows 兼容 / nsjail image 字段 / 前端 Box 状态接入 | 见上一轮 review 记录，均已合入 |
+
+---
+
+## SaaS 阻塞项
+
+### S1. Box 控制面无认证 — Critical
+
+- **位置**: SDK `box/server.py` — Action RPC WS (`/rpc/ws`) 与 managed-process relay (`/v1/sessions/{id}/managed-process/{pid}/ws`)
+- **现状**: 两个 WS handler 在 `ws.prepare` 后直接服务，无任何 token / 鉴权；box 默认绑定 `0.0.0.0:5410`。任何能触达该端口者可发起 `EXEC`、创建 session、attach 任意 session 的 managed-process stdin/stdout、甚至 `SHUTDOWN`。LangBot→box 的 INIT 也未下发任何凭证。
+- **缓解现状**: 默认 `docker-compose.yaml` 的 `langbot_box` 未把 5410 发布到宿主（爆炸半径限于内网 bridge）；但 box 挂载了 `/var/run/docker.sock`，同网络的任意服务（含被攻破的插件）→ 宿主 root。若运营者把 5410 发布到宿主或独立以 `0.0.0.0` 起 box，则完全裸奔。
+- **要求**: INIT 时下发 token，两个 WS 路由按连接校验（query/header）。这是 SaaS 的**头号**阻塞项。
+
+### S2. 无 exec 授权模型（policy.py 死代码） — High
+
+- **位置**: LangBot `pkg/box/policy.py`（`SandboxPolicy` / `ToolPolicy` / `ElevatedPolicy` 全项目无引用）；`pkg/provider/tools/loaders/native.py`；`pkg/provider/tools/toolmgr.py`
+- **现状**: 原生工具（`exec/read/write/edit/glob/grep`）按"box 是否可用"全有或全无地暴露，**无 per-pipeline 的 exec 网关 / 工具白名单 / 沙箱模式 / 权限提升控制**。只要 box 可用，任何使用 local-agent + 函数调用模型的 pipeline 都能跑任意 shell。
+- **要求**: 接入 policy.py（或等价机制），按 pipeline 控制是否暴露 `exec`、可用工具白名单、沙箱网络/只读模式。
+
+### S3. 会话资源无界（DoS） — High
+
+- **#5 session 数量无上限**: SDK `box/runtime.py` `_get_or_create_session` 的 `_sessions` dict 无容量限制——可变 `session_id` 的恶意调用可无限创建容器，耗尽宿主 CPU/内存/PID/磁盘。
+- **#8 无定时回收**: 过期 session 仅在 `_get_or_create_session` 时机会性清理，无独立周期任务；一波创建后转静默会永久泄漏容器。
+- **要求**: `max_sessions` 上限（拒绝或 LRU），加独立周期 reaper（如 60s）。
+
+### S4. 工作区配额无内核级限制（TOCTOU） — Med-High
+
+- **位置**: LangBot `pkg/box/service.py` `_enforce_workspace_quota`（应用层 read-then-check）；SDK 侧 `workspace_quota_mb` 仅记录/透传，无 `--storage-opt size=` 等内核/FS 限额
+- **现状**: 执行前后两次检查之间存在竞态窗口；单条命令（`dd`/`fallocate`）可在检查间隙撑爆磁盘，事后检查只能补救。
+- **要求**: Docker `--storage-opt size=` 做内核级限制，或 Redis 原子计数预留式配额。
+
+### S5. 挂载校验缺口 — Med-High
+
+- **位置**: SDK `box/security.py` `_BLOCKED_HOST_PATHS_POSIX`；`box/backend.py` 的 `extra_mounts` 处理
+- **现状**: ① SDK 黑名单仍不含 `/`（前缀匹配，`host_path="/"` 可通过，挂载整个宿主 fs）；用户 home、`/usr`、`/opt`、`/tmp` 也未拦截。② `validate_sandbox_security` 只校验 `spec.host_path`，**从不遍历 `spec.extra_mounts`**——LangBot 侧 `allowed_mount_roots` 也只校验 `host_path`。当前 `extra_mounts` 仅由 `build_skill_extra_mounts` 内部填充（agent 不可达），但缺乏纵深防御：一旦 S1 的无认证 RPC 被触达，extra_mounts 可挂任意宿主路径，两层都不拦。
+- **要求**: SDK 黑名单加入 `/`（或改白名单）；`extra_mounts` 在 SDK 与 LangBot 两侧都纳入挂载校验。
+
+### S6. 容器加固缺失 — Med
+
+- **位置**: SDK `box/backend.py` 的 `docker run` 组装
+- **现状**: 未设置 `--cap-drop=ALL`、`--security-opt=no-new-privileges`、非 root `--user`；叠加挂载 docker.sock，逃逸面偏大。
+- **要求**: 默认加上上述加固 flag（需回归常用 skill 不被破坏）。
+
+### S7. 全局锁内执行慢操作（扩展性） — Med
+
+- **位置**: SDK `box/runtime.py` `_get_or_create_session`：`self._lock` 持有期间调用 `backend.start_session()`（`docker run` / nsjail 启动 / E2B `Sandbox.create`）
+- **影响**: 冷启动（镜像拉取数秒、E2B >1s）期间串行阻塞所有并发请求——多租户负载下整个 Box runtime 停顿。降级表现是延迟而非失败。
+- **要求**: 锁内只做状态检查与注册，容器创建移到锁外。
+
+### S8. 其他硬化 / 跟进 — Low
+
+- **#9** SDK `box/server.py` 直接读 `runtime._sessions` 私有字段、绕过锁，并发下可能读到不一致状态——应加公共访问方法。
+- **#16** `pkg/provider/tools/toolmgr.py` `execute_func_call` 按优先级分发，plugin/MCP 若有同名 `exec/read/write/...` 工具会被静默遮蔽——应加命名空间或冲突告警。
+- **#4** SDK `box/runtime.py` INIT/handshake 与 backend 实例化的残留竞态（仅"纯远程 WS box 先启动、LangBot 后连"场景成立；stdio/compose 路径下 config 经 env 在 spawn 时已就位，无竞态）——应在 INIT 完成前拒绝业务 action。
+- **#11** `extra_mounts` 在容器创建时固定（SDK `runtime.py` 兼容性检查不含 extra_mounts）；长生命周期共享 session 后续新激活的 skill 不会挂上（当前缓解：创建时挂上 pipeline 绑定的全部 skill）——动态绑定场景需销毁重建或文档说明。
+- **#21** 集成测试未进 CI：容器实际执行、E2B 真机、managed-process WS attach 仅本地可跑。安全关键路径缺自动化覆盖——SaaS 前建议加 Docker-in-Docker CI stage 或合并前手动 checklist。

docs/review/box-session-scope.md

@@ -0,0 +1,402 @@
+# Box Session Scope Design
+
+> Date: 2026-04-18 (last reviewed 2026-06-02)
+> Status (2026-06-02): the self-hosted community edition is release-ready (box optional, clean degradation, no migration debt). Tool-call loop cap, async quota scan, and the host_path mount allowlist have landed. Remaining multi-tenant / security hardening is tracked in [box-issues.md](./box-issues.md).
+> Branch: `feat/sandbox` (LangBot + langbot-plugin-sdk)
+> Related: [Box Architecture](./box-architecture.md) | [Box vs Plugin Runtime](./box-vs-plugin-runtime.md)
+
+---
+
+## 0. Implementation Status (2026-05-19)
+
+This document was authored as a design proposal. The current `feat/sandbox` branch
+has shipped the design largely as written:
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `BoxMountSpec` + `BoxSpec.extra_mounts` | ✅ Shipped | SDK `box/models.py` |
+| Docker / nsjail / E2B backends apply extra mounts | ✅ Shipped | Last gap closed by SDK commit `0fea9b1` (E2B) |
+| `box-session-id-template` in `local-agent` pipeline config | ✅ Shipped | `templates/metadata/pipeline/ai.yaml`, default `{launcher_type}_{launcher_id}` |
+| `BoxService.resolve_box_session_id(query)` | ✅ Shipped | `pkg/box/service.py:166` |
+| `BoxService.build_skill_extra_mounts(query)` | ✅ Shipped | `pkg/box/service.py:189` |
+| Skill exec uses unified container + extra mounts | ✅ Shipped | `pkg/provider/tools/loaders/native.py` skill branch |
+| MCP-in-Box uses shared persistent session, multi-process | ✅ Shipped (earlier than originally scoped) | SDK commit `529088e`, LangBot `mcp_stdio.py:_build_box_session_id` |
+| `BoxManagedProcessSpec.process_id` + multi-process per session | ✅ Shipped | `BoxRuntime` keeps `managed_processes: dict[pid, _ManagedProcess]` |
+| Per-tenant / quota integration with templates | ❌ Not started | See [box-tob-analysis.md](./box-tob-analysis.md) |
+
+The "Phase 2 deferred" note in §10 is **out of date** — MCP unification went in on
+the same line. Pipeline-scoped (not user-scoped) MCP container is the realized
+behavior: each pipeline's MCP servers share one `mcp-<pipeline>` session, and
+user exec sessions use the template-derived id.
+
+The remaining open work is multi-tenant overlays (tenant_id in session_id,
+quota counters keyed by tenant), tracked in the toB analysis doc rather than here.
+
+---
+
+## 1. Problems
+
+### 1.1 Default exec: per-message containers
+
+Currently, `BoxService.execute_tool()` sets `session_id = str(query.query_id)` — an
+auto-incrementing integer per incoming message. Every user message creates a new sandbox
+container. Dependencies installed and in-container state are lost between messages.
+
+### 1.2 Three isolated container pools
+
+Default exec, skills, and MCP servers each manage their own containers with
+independent session IDs:
+
+| Path         | Session ID                                    | Container   |
+|--------------|-----------------------------------------------|-------------|
+| Default exec | `str(query_id)` (per message)                 | Ephemeral   |
+| Skill exec   | `skill-{launcher}_{id}-{skill_name}`          | Per skill   |
+| MCP stdio    | `mcp-{server_uuid}`                           | Per server  |
+
+This means a single logical user interaction can spawn 3+ containers that cannot
+share state, see each other's files, or reuse installed dependencies.
+
+### 1.3 Single bind mount limitation
+
+`BoxSpec` currently supports only **one** `host_path` → `mount_path` bind mount.
+This prevents mounting both a default workspace and skill directories into the
+same container.
+
+---
+
+## 2. Concept Model
+
+```
+Platform Message
+  → Query (query_id: int, auto-increment, per message)
+    → Session (launcher_type + launcher_id, per chat window)
+      → Conversation (uuid, per dialogue context within a Session)
+```
+
+| Concept       | Key                                 | Example                    | Scope                        |
+|---------------|-------------------------------------|----------------------------|------------------------------|
+| Query         | `query_id`                          | `42`                       | Single message               |
+| Session       | `launcher_type` + `launcher_id`     | `group_123456`             | Chat window (group or PM)    |
+| Conversation  | `conversation_id` (UUID)            | `a1b2c3d4-...`             | Dialogue context within a Session |
+| Sender        | `sender_id`                         | `789`                      | Individual user              |
+
+Note: in a **group chat**, all users share the same Session (keyed by `group_id`). The
+individual sender is tracked as `sender_id` but does not affect Session/Conversation routing.
+
+---
+
+## 3. Target Scenarios
+
+| #  | Scenario                       | Box Granularity                          | Desired `session_id`                                   |
+|----|--------------------------------|------------------------------------------|---------------------------------------------------------|
+| 1  | Personal assistant             | 1 Box per user, long-lived               | `{launcher_type}_{launcher_id}`                          |
+| 2  | Customer service               | 1 Box per customer, cross-pipeline       | `{launcher_type}_{launcher_id}`                          |
+| 3  | Internal employee tool         | 1 Box per employee                       | `{launcher_type}_{launcher_id}`                          |
+| 4  | Group chat shared assistant    | 1 Box per group                          | `{launcher_type}_{launcher_id}`                          |
+| 5  | Group chat isolated per user   | 1 Box per user within a group            | `{launcher_type}_{launcher_id}_{sender_id}`              |
+| 6  | Teaching (cross-channel)       | 1 Box per student across groups/PMs      | `{sender_id}`                                           |
+| 7  | One-off execution              | 1 Box per message (current behavior)     | `{query_id}`                                            |
+| 8  | Multi-project development      | 1 Box per conversation context           | `{launcher_type}_{launcher_id}_{conversation_id}`        |
+
+No single fixed granularity covers all scenarios. A template-based approach is needed.
+
+---
+
+## 4. Design Overview
+
+Two key changes:
+
+1. **Unified container**: exec, skills, and MCP all share the same container per
+   session scope. No more separate container pools.
+2. **Configurable session scope**: `session_id` is generated from a template with
+   pipeline variables, configurable per pipeline.
+
+### 4.1 Unified Container with Multiple Mounts
+
+A single container per session scope is created on first use. It has:
+
+- **Primary mount**: default workspace at `/workspace` (from `default_host_workspace`)
+- **Skill mounts**: each pipeline-bound skill's `package_root` mounted at
+  `/workspace/.skills/{skill_name}/`
+- **MCP servers**: run as managed processes inside the same container
+
+```
+Container (session_id = "group_123456")
+  /workspace/                          ← default workspace (bind mount, rw)
+  /workspace/.skills/web-search/       ← skill package (bind mount, rw)
+  /workspace/.skills/data-analysis/    ← skill package (bind mount, rw)
+  [managed process: mcp-server-a]      ← MCP server running inside
+  [managed process: mcp-server-b]      ← MCP server running inside
+```
+
+This requires extending `BoxSpec` to support multiple mounts (see §5).
+
+### 4.2 Session ID Template
+
+A new field `box-session-id-template` in the `local-agent` pipeline runner config
+controls the session scope:
+
+```yaml
+# templates/metadata/pipeline/ai.yaml (under local-agent.config)
+- name: box-session-id-template
+  label:
+    en_US: Sandbox Scope
+    zh_Hans: 沙箱作用域
+  description:
+    en_US: >-
+      Determines how sandbox environments are shared. Use variables to
+      control isolation granularity.
+    zh_Hans: >-
+      决定沙箱环境的共享方式。使用变量控制隔离粒度。
+  type: select
+  required: false
+  default: "{launcher_type}_{launcher_id}"
+  options:
+    - value: "{launcher_type}_{launcher_id}"
+      label:
+        en_US: Per chat (Recommended)
+        zh_Hans: 每个会话（推荐）
+    - value: "{launcher_type}_{launcher_id}_{sender_id}"
+      label:
+        en_US: Per user in chat
+        zh_Hans: 会话中每个用户
+    - value: "{launcher_type}_{launcher_id}_{conversation_id}"
+      label:
+        en_US: Per conversation context
+        zh_Hans: 每个对话上下文
+    - value: "{query_id}"
+      label:
+        en_US: Per message (isolated)
+        zh_Hans: 每条消息（完全隔离）
+```
+
+Available template variables (populated by PreProcessor in `query.variables`):
+
+| Variable            | Source                          | Example              |
+|---------------------|---------------------------------|----------------------|
+| `{launcher_type}`   | `query.session.launcher_type`   | `person` / `group`   |
+| `{launcher_id}`     | `query.session.launcher_id`     | `123456`             |
+| `{sender_id}`       | `query.sender_id`               | `789`                |
+| `{conversation_id}` | `conversation.uuid`             | `a1b2c3d4-...`       |
+| `{query_id}`        | `query.query_id`                | `42`                 |
+
+Default `{launcher_type}_{launcher_id}` covers scenarios 1–4 out of the box.
+
+---
+
+## 5. SDK Changes: Multi-Mount BoxSpec
+
+### 5.1 Model Extension
+
+```python
+# box/models.py
+
+class BoxMountSpec(pydantic.BaseModel):
+    """A single bind mount specification."""
+    host_path: str
+    mount_path: str
+    mode: BoxHostMountMode = BoxHostMountMode.READ_WRITE
+
+class BoxSpec(pydantic.BaseModel):
+    # ... existing fields ...
+    host_path: str | None = None              # Primary mount (backward compat)
+    host_path_mode: BoxHostMountMode = BoxHostMountMode.READ_WRITE
+    mount_path: str = DEFAULT_BOX_MOUNT_PATH
+    extra_mounts: list[BoxMountSpec] = []     # NEW: additional mounts
+```
+
+`extra_mounts` is additive — the existing `host_path` / `mount_path` pair remains
+the primary mount for backward compatibility.
+
+### 5.2 Backend: Apply Extra Mounts
+
+```python
+# box/backend.py — CLISandboxBackend.start_session()
+
+# Primary mount (unchanged)
+if spec.host_path is not None and spec.host_path_mode != BoxHostMountMode.NONE:
+    args.extend(['-v', f'{spec.host_path}:{spec.mount_path}:{spec.host_path_mode.value}'])
+
+# Extra mounts (NEW)
+for mount in spec.extra_mounts:
+    if mount.mode != BoxHostMountMode.NONE:
+        args.extend(['-v', f'{mount.host_path}:{mount.mount_path}:{mount.mode.value}'])
+```
+
+Same pattern for nsjail backend.
+
+---
+
+## 6. LangBot Changes
+
+### 6.1 Session ID Resolution
+
+In `BoxService.execute_tool()`:
+
+```python
+# Before:
+spec_payload.setdefault('session_id', str(query.query_id))
+
+# After:
+template = (query.pipeline_config or {}).get('ai', {}) \
+    .get('local-agent', {}).get('box-session-id-template',
+         '{launcher_type}_{launcher_id}')
+variables = query.variables or {}
+session_id = template.format_map(collections.defaultdict(
+    lambda: 'unknown', variables
+))
+spec_payload.setdefault('session_id', session_id)
+```
+
+### 6.2 Skill Exec: Use Same Container
+
+Currently `native.py:_invoke_exec` creates a separate `BoxWorkspaceSession` per
+skill with `host_path=package_root`. Instead:
+
+1. Use the **same session_id** as default exec (from the template).
+2. Pass the skill's `package_root` as an **extra mount** at
+   `/workspace/.skills/{skill_name}/` instead of replacing `/workspace`.
+3. The container already has the default workspace at `/workspace`.
+
+```python
+# native.py — _invoke_exec, skill branch (REVISED)
+
+# Same session_id as default exec
+session_id = resolve_box_session_id(query)
+
+spec_payload = {
+    'cmd': rewritten_command,
+    'workdir': rewritten_workdir,
+    'session_id': session_id,
+    'extra_mounts': [{
+        'host_path': package_root,
+        'mount_path': f'/workspace/.skills/{selected_skill_name}',
+        'mode': 'rw',
+    }],
+}
+result = await self.ap.box_service.execute_spec_payload(spec_payload, query)
+```
+
+The virtual path `/workspace/.skills/{name}` no longer needs rewriting at the
+command level — it maps directly to the bind mount path inside the container.
+
+### 6.3 MCP: Use Same Container
+
+MCP servers should run inside the same container as exec and skills. Changes:
+
+1. `BoxStdioSessionRuntime` uses the pipeline's session_id template instead of
+   `mcp-{server_uuid}`.
+2. MCP server's working directory is a subdirectory (e.g. `/workspace/.mcp/{name}/`).
+3. MCP server's dependencies are mounted or installed into that subdirectory.
+4. The MCP server runs as a managed process inside the shared container.
+
+Since MCP servers start at LangBot boot (not per-query), the session must be
+created eagerly. The container will be kept alive by the managed process
+exemption in TTL reaping (`runtime.py:259`).
+
+**Note**: MCP sessions are pipeline-scoped (not per-launcher), so their session_id
+should be a **fixed identifier per pipeline** rather than the user-facing template.
+This means one shared MCP container per pipeline, with user exec sessions separate.
+
+Alternatively, in a future iteration, MCP managed processes could be launched
+lazily into the user's container on first MCP tool call. This is more complex
+but maximizes sharing. For V1, keeping MCP containers at pipeline scope is
+simpler and more predictable.
+
+---
+
+## 7. Mount Layout Summary
+
+### Default exec (no skills activated)
+
+```
+Container (session_id from template)
+  /workspace/          ← default_host_workspace (rw)
+```
+
+### Exec with activated skills
+
+```
+Container (same session_id)
+  /workspace/                          ← default_host_workspace (rw)
+  /workspace/.skills/web-search/       ← skill package_root (rw)
+  /workspace/.skills/data-analysis/    ← skill package_root (rw)
+```
+
+Extra mounts are **additive** — they are added when the container is first
+created (or on the first exec that references a skill). Since Docker bind
+mounts are specified at container creation time, skills must be known at
+creation time.
+
+**Resolution**: When creating a container, inject `extra_mounts` for **all
+pipeline-bound skills** (from `extensions_preferences`), not just the
+currently activated one. This way any skill can be activated later without
+recreating the container.
+
+### MCP servers (V1: pipeline-scoped)
+
+```
+Container (session_id = "mcp-pipeline-{pipeline_uuid}")
+  /workspace/                    ← MCP shared workspace
+  /workspace/.mcp/server-a/      ← MCP server A files
+  /workspace/.mcp/server-b/      ← MCP server B files
+  [managed process: server-a]
+  [managed process: server-b]
+```
+
+---
+
+## 8. Data Migration
+
+Existing pipelines do not have `box-session-id-template`. The backend uses
+`.get(..., default)` so missing keys fall back to `{launcher_type}_{launcher_id}`.
+This changes behavior from per-message to per-launcher for existing pipelines.
+
+Recommendation: **accept the behavior change** — per-launcher is the more
+intuitive default, and the old per-message behavior was rarely desired.
+
+---
+
+## 9. Cloud Quota Implications
+
+| Scope                                         | Typical concurrent containers |
+|-----------------------------------------------|-------------------------------|
+| `{query_id}` (per message)                    | Many, short-lived             |
+| `{launcher_type}_{launcher_id}` (per chat)    | = active chat count           |
+| `{sender_id}` (per user)                      | = active user count           |
+| `{conversation_id}` (per conversation)        | Between per-chat and per-msg  |
+
+With the unified container model, each scope value maps to exactly **one**
+container (instead of potentially 3+ per-message). This significantly reduces
+resource usage.
+
+Quota enforcement point: `BoxRuntime._get_or_create_session()` in the SDK.
+
+---
+
+## 10. Implementation Phases
+
+### Phase 1: Session scope + skill unification (this PR)
+
+1. **SDK**: Extend `BoxSpec` with `extra_mounts: list[BoxMountSpec]`.
+2. **SDK**: Update Docker/nsjail backends to apply extra mounts.
+3. **LangBot**: Add `box-session-id-template` to `local-agent` YAML metadata
+   and default pipeline config JSON.
+4. **LangBot**: Update `BoxService.execute_tool()` to use template interpolation.
+5. **LangBot**: Update `native.py:_invoke_exec` skill branch to use same
+   session_id + extra mounts instead of separate `BoxWorkspaceSession`.
+6. **LangBot**: On container creation, inject extra mounts for all
+   pipeline-bound skills.
+7. **Frontend**: No code change — `DynamicFormComponent` renders `select` fields.
+8. **Tests**: Unit tests for template interpolation and multi-mount specs.
+
+### Phase 2: MCP unification (future)
+
+1. Refactor `BoxStdioSessionRuntime` to use pipeline-scoped shared container.
+2. MCP servers become managed processes in the shared container.
+3. Support multiple concurrent managed processes per container.
+
+MCP unification is deferred because it requires changes to the managed process
+model (currently 1 managed process per session) and has startup ordering
+concerns (MCP servers start at boot, before any user query determines
+a session_id).

docs/review/box-test-coverage.md

@@ -0,0 +1,122 @@
+# Box 系统测试覆盖分析
+
+> 更新日期: 2026-06-02
+> 状态更新: 自部署社区版已具备发布条件（box 可选、降级完善、无迁移欠债）；工具调用循环上限、配额遍历异步化、`host_path` 挂载白名单等已落地。剩余多租户 / 安全硬化项见 [SaaS 阻塞项清单](./box-issues.md)。
+> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
+
+---
+
+## 1. 测试文件清单
+
+### LangBot 仓库
+
+| 文件 | 行数 | CI 运行 | 覆盖范围 |
+|------|------|---------|---------|
+| `tests/unit_tests/box/test_box_connector.py` | 106 | 是 | Connector 传输决策、WS relay URL、dispose、心跳/重连 |
+| `tests/unit_tests/box/test_box_service.py` | 1224 | 是 | Service 核心逻辑（最全面） |
+| `tests/unit_tests/box/test_workspace.py` | 147 | 是 | WorkspaceSession 路径重写、payload 构建 |
+| `tests/unit_tests/provider/test_mcp_box_integration.py` | 707 | 是 | MCP Box 配置、路径重写、payload、shared-session/multi-process、runtime info |
+| `tests/unit_tests/provider/test_localagent_sandbox_exec.py` | 444 | 是 | LocalAgent exec 流程、流式、Skill 激活 (Tool Call) |
+| `tests/unit_tests/provider/test_tool_manager_native.py` | 249 | 是 | ToolManager 路由、native tool CRUD、路径穿越、6 工具暴露 |
+| `tests/unit_tests/provider/test_skill_tools.py` | 582 | 是 | Skill 管理、Tool Call 激活、路径、authoring CRUD |
+| `tests/unit_tests/test_skill_service.py` | 396 | 是 | HTTP service：skill CRUD、zip/GitHub install、文件浏览 |
+| `tests/unit_tests/test_paths.py` | 23 | 是 | paths 工具 |
+| `tests/unit_tests/test_preproc.py` | 134 | 是 | PreProcessor 注入 session 变量、bound skill 解析 |
+| `tests/unit_tests/pipeline/test_chat_handler_logging.py` | 78 | 是 | Chat handler 日志相关回归 |
+| `tests/integration_tests/box/test_box_integration.py` | 329 | **否** | 真实容器执行、超时、网络隔离 |
+| `tests/integration_tests/box/test_box_mcp_integration.py` | 368 | **否** | Managed process、WS attach、shared-session 清理 |
+
+### SDK 仓库
+
+| 文件 | 行数 | CI 运行 | 覆盖范围 |
+|------|------|---------|---------|
+| `tests/box/test_backend_selection.py` | 255 | 是 | 显式 backend / local 模式探测顺序 / 配置变更触发 reselect |
+| `tests/box/test_nsjail_backend.py` | 452 | 是 | nsjail 可用性、安装版 CLI vs 容器内 CLI、session、arg 构建、资源限制 |
+| `tests/box/test_e2b_backend.py` | 482 | 是 | E2B SDK mock、session 生命周期、extra_mounts 同步 |
+| `tests/box/test_skill_store.py` | 88 | 是 | zip preview/install、基础 file CRUD |
+
+**总计**: 17 个测试文件, ~6,500 行测试代码; 其中 2 个集成测试（约 700 行）在 CI 中不运行。
+
+> 较 2026-04-16 版增加：`test_skill_service.py`、`test_paths.py`、`test_preproc.py`、`test_chat_handler_logging.py` (LangBot)，`test_backend_selection.py`、`test_e2b_backend.py`、`test_skill_store.py` (SDK)。`test_nsjail_backend.py` 增加 CLI 兼容性 case (commit `feed530`)。
+
+---
+
+## 2. 覆盖良好的区域
+
+| 区域 | 质量 | 说明 |
+|------|------|------|
+| BoxRuntime session 管理 | 优秀 | session 复用、冲突检测、TTL 配置、消失 session 重建 |
+| BoxService Profile 系统 | 优秀 | 4 个内置 Profile、locked/unlocked 字段、timeout clamp |
+| BoxService host mount 安全 | 优秀 | allowed_mount_roots、disallowed_roots、shared host root |
+| BoxService workspace quota | 优秀 | 前置/后置配额检查、超额清理 |
+| BoxService 输出截断 | 优秀 | 短/精确边界/长输出、独立 stderr |
+| BoxService 可观测性 | 优秀 | 状态报告、error ring buffer、buffer 上限 |
+| BoxService session 模板 | 良好 | `resolve_box_session_id` + `build_skill_extra_mounts` 在 service / native / mcp 三处都有覆盖 |
+| RPC client/server 协议 | 优秀 | execute/get_sessions/delete/create/conflict error |
+| BoxRuntimeConnector | 良好 | local/remote 模式、Docker 平台、relay URL、心跳与重连回调 |
+| BoxWorkspaceSession | 良好 | payload 构建、managed process 路径重写、stage host file |
+| BoxHostMountMode.NONE | 良好 | 枚举校验、workdir 约束 |
+| NsjailBackend | 良好 | 可用性、安装版 vs 容器内、session 生命周期、arg 构建、资源限制 |
+| E2BBackend | 良好 | mock SDK、session/extra_mounts 同步 |
+| Backend selection | 良好 | 显式 backend 优先级、local 探测顺序、配置变更触发 reselect |
+| MCP Box 集成 | 良好 | config model、路径重写、payload、shared-session 多 process |
+| Native tool loader | 良好 | 6 工具（exec/read/write/edit/glob/grep）、路径穿越拦截 |
+| LocalAgent exec 流程 | 良好 | 完整 tool call 循环、流式、system prompt 注入、Tool Call 激活 |
+| Skill 系统 | 良好 | 加载、Tool Call 激活、marker、路径解析、authoring CRUD、HTTP service |
+
+---
+
+## 3. 覆盖缺失的区域
+
+### 3.1 零测试 / 严重不足
+
+| 区域 | 源文件 | 影响 |
+|------|--------|------|
+| **`security.py`** | SDK `box/security.py` (52 行) | `validate_sandbox_security()` 无任何测试。阻止 `/etc`/`/proc`/Docker socket 等危险挂载的安全函数从未被验证 |
+| **`policy.py`** | `pkg/box/policy.py` (98 行) | 三层安全策略无测试（也是死代码） |
+| **`skill_store.py` 边缘场景** | SDK `box/skill_store.py` (647 行) vs 测试 88 行 | GitHub 安装路径、`source_subdir` / `target_suffix` 组合、损坏 zip、文件冲突等场景未覆盖 |
+
+### 3.2 未测试的关键路径
+
+| 区域 | 说明 |
+|------|------|
+| **Session TTL 过期** | 测试配置了 `session_ttl_sec` 但从未推进时间验证过期清理 |
+| **并发 session 访问** | 无并发 exec / 并发创建 / race condition 测试 |
+| **Container backend (Docker)** | 仅通过集成测试覆盖（CI 不运行），单元测试全用 FakeBackend |
+| **E2B 真实 sandbox** | 单测全是 mock，未对接真实 E2B API |
+| **BoxRuntime shutdown()** | 在 test cleanup 中调用但未验证行为 |
+| **BoxServerHandler 错误路径** | 畸形请求、未知 action 类型 |
+| **WS relay** | 仅在集成测试中覆盖（CI 不运行） |
+| **NsjailBackend managed process** | 完全未测试 |
+| **MCP stdio 完整生命周期** | 依赖安装 → 进程启动 → 健康检查 → 多 process 并发 → 重试 |
+| **BoxService start/stop_managed_process** | 单 process 流转有单测，多 process 互不阻塞主要靠集成测试 |
+| **重连指数退避** | connector 单测覆盖回调接线，未实际跑完整重连周期 |
+
+### 3.3 边缘情况缺失
+
+| 区域 | 说明 |
+|------|------|
+| BoxSpec 校验 | 无效 session_id 格式、超长命令、env 特殊字符 |
+| BoxSpec.extra_mounts | 重复 mount_path、与 host_path 冲突、绝对 vs 相对路径 |
+| BoxExecutionResult | 仅 COMPLETED 和 TIMED_OUT，无 ERROR 状态测试 |
+| 多后端 fallback | local 模式探测顺序仅靠 mock，无真实 Docker 不可用 → nsjail 真机 fallback 测试 |
+| Profile YAML 加载 | 测试用硬编码字符串，未从真实 config.yaml 加载 |
+| INIT 配置变更触发 backend 重建 | 单测仅在初始化场景验证 |
+
+---
+
+## 4. 集成测试 vs CI 的差距
+
+CI 仅运行 `tests/unit_tests/`，以下场景**从未在自动化中验证**:
+
+- 真实容器的创建/执行/销毁
+- 容器网络隔离（`--network none`）
+- 容器资源限制生效（cpus/memory/pids_limit）
+- Managed process 的 WS 双向 I/O
+- 多 process 同 session 并发 I/O
+- 孤儿容器清理
+- Session 删除清理容器
+- 进程退出检测
+- E2B 真实 sandbox 行为
+
+**建议**: 在 CI 中加一个可选的 Docker-in-Docker 集成测试 stage，至少覆盖核心执行路径（exec / MCP attach / session 销毁）。

docs/review/box-tob-analysis.md

@@ -0,0 +1,167 @@
+# Box 系统 toB 商业化分析
+
+> 更新日期: 2026-06-02
+> 状态更新: 自部署社区版已具备发布条件（box 可选、降级完善、无迁移欠债）；工具调用循环上限、配额遍历异步化、`host_path` 挂载白名单等已落地。剩余多租户 / 安全硬化项见 [SaaS 阻塞项清单](./box-issues.md)。
+> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
+
+---
+
+## 1. 现有优势
+
+| 能力 | toB 价值 | 代码位置 |
+|------|---------|---------|
+| **沙箱隔离执行** | 企业安全运行不受信代码的基础能力 | SDK `box/backend.py` |
+| **多后端支持** | 适配不同企业容器基础设施 (Podman/Docker/nsjail/E2B) | SDK `box/runtime.py` `_select_backend()` |
+| **E2B 云沙箱** | SaaS / 无 Docker 部署的兜底执行环境 | SDK `box/e2b_backend.py` |
+| **连接自愈** | 心跳 + 自动重连，单点 Box runtime 故障可恢复 | `pkg/box/connector.py` `_heartbeat_loop`, `pkg/box/service.py` `_reconnect_loop` |
+| **Profile + locked 字段** | 运维锁定安全边界，LLM/用户无法绕过 | `pkg/box/service.py`, SDK `box/models.py` |
+| **资源限制** | CPU/内存/PID 数限制防止资源滥用 | SDK `backend.py` `--cpus/--memory/--pids-limit` |
+| **Workspace quota** | 磁盘用量控制 | `pkg/box/service.py` `_enforce_workspace_quota` |
+| **静默降级** | Box 不可用不影响其他功能，降低部署门槛 | `pkg/box/service.py:78` `_available=False` |
+| **孤儿容器清理** | 防止泄漏的容器持续占用资源 | SDK `backend.py` `cleanup_orphaned_containers` |
+| **网络隔离** | `--network none` 防止数据外泄 | SDK `backend.py` start_session |
+| **只读根文件系统** | `--read-only` 防止容器被持久篡改 | SDK `backend.py` start_session |
+| **Host path 白名单** | `allowed_host_mount_roots` 限制可挂载目录 | `pkg/box/service.py` `_validate_host_mount` |
+
+---
+
+## 2. toB 差距分析
+
+### 2.1 安全与合规
+
+| 维度 | 现状 | toB 要求 | 优先级 |
+|------|------|---------|--------|
+| **WS relay 认证** | 无认证，任何人可 attach | 至少 token 认证 | **P0** |
+| **安全策略** | policy.py 是死代码，实际无细粒度控制 | 工具级 allow/deny、沙箱模式控制 | **P0** |
+| **审计日志** | 仅内存中 50 条 `_recent_errors` | 持久化审计：谁何时执行了什么、结果如何 | **P0** |
+| **Host path 校验** | 黑名单策略，`/` 未拦截 | 白名单策略，默认拒绝 | **P1** |
+| **数据驻留** | 无控制 | GDPR / 等保要求的数据隔离 | **P2** |
+
+### 2.2 多租户
+
+| 维度 | 现状 | toB 要求 | 优先级 |
+|------|------|---------|--------|
+| **租户隔离** | 无租户概念 | BoxSpec/Profile 绑定 tenant_id | **P0** |
+| **RBAC** | 仅 token 认证 | admin/operator/viewer 角色权限 | **P0** |
+| **资源配额** | 单一 workspace quota | 每租户 CPU 时间/内存/并发/执行次数配额 | **P1** |
+| **Session 隔离** | 所有 session 共享 dict | 按租户分区，互不可见 | **P1** |
+
+### 2.3 可靠性
+
+| 维度 | 现状 | toB 要求 | 优先级 |
+|------|------|---------|--------|
+| **连接恢复** | 已实现：20s 心跳 + `_reconnect_loop` 指数退避 | 已满足基本要求 | 已有 |
+| **Session 清理** | 机会性（仅新建时触发） | 定时清理 + 独立 reaper | **P1** |
+| **水平扩展** | 单 Box Runtime 实例 | 多实例负载均衡（按 tenant 路由） | **P1** |
+| **优雅降级** | 已有（_available=False） | 已满足基本要求 | 已有 |
+| **Backend 自愈** | 已实现：`get_status` 时若 backend 不可用会重新选择 | 已满足基本要求 | 已有 |
+
+### 2.4 可观测性
+
+| 维度 | 现状 | toB 要求 | 优先级 |
+|------|------|---------|--------|
+| **监控指标** | 无 Prometheus metrics | session 数/执行延迟/资源用量/错误率 | **P1** |
+| **结构化日志** | Python logging, 无结构化 | JSON 格式日志，含 trace_id/tenant_id | **P1** |
+| **前端面板** | 监控页接入 `/api/v1/box/status`（backend 名 + 活跃 session 数）；`sessions` / `errors` 仍未接入 | 完整状态面板 + 历史错误/审计列表 | **P2** |
+
+---
+
+## 3. SaaS 部署架构建议
+
+### 3.1 方案 A: 共享 Box Runtime Pool (快速上线)
+
+```
+LangBot Instance ──> Box Runtime (共享)
+                       ├─ tenant_id 标签隔离
+                       ├─ Redis 配额计数器
+                       └─ Container labels: langbot.tenant_id=xxx
+```
+
+- **优点**: 改动最小，加 tenant_id 到 BoxSpec/labels 即可
+- **缺点**: 容器引擎共享，安全隔离弱
+
+### 3.2 方案 B: 每租户 K8s Namespace + gVisor (推荐中期)
+
+```
+LangBot ──> K8s API
+              ├─ namespace: tenant-xxx
+              │    ├─ RuntimeClass: gVisor (runsc)
+              │    ├─ ResourceQuota
+              │    └─ NetworkPolicy
+              └─ namespace: tenant-yyy
+                   └─ ...
+```
+
+- **优点**: 强隔离（namespace + gVisor），原生 K8s 配额
+- **缺点**: 需要重写 backend 为 K8s Job，部署复杂度高
+
+### 3.3 方案 C: K8s Job 直接编排 (长期)
+
+```
+LangBot ──> K8s Job per execution
+              ├─ 每次执行创建 Job
+              ├─ Pod Security Standards
+              ├─ 自动调度和资源分配
+              └─ Job TTL Controller 自动清理
+```
+
+- **优点**: 最强隔离，天然水平扩展
+- **缺点**: 冷启动延迟，架构重写
+
+**推荐演进路径**: A → B → C
+
+---
+
+## 4. 配额体系建议
+
+### 三层配额
+
+| 层 | 实现 | 作用 |
+|----|------|------|
+| **内核层** | Docker `--cpus`/`--memory`/`--storage-opt` | 硬性资源上限，不可绕过 |
+| **应用层** | Redis 原子计数器 | 并发 session 数/执行次数/CPU 时间预算 |
+| **计费层** | 月度聚合 | 按租户计费（session-hours/execution-count） |
+
+### Profile 与套餐映射
+
+| 套餐 | Profile | locked 字段 | 配额 |
+|------|---------|------------|------|
+| Free | `offline_readonly` | network, host_path_mode, rootfs | 10 exec/天, 0.5 CPU, 256MB |
+| Pro | `default` | (无) | 100 exec/天, 1 CPU, 512MB |
+| Enterprise | `network_extended` | (按需) | 无限, 2 CPU, 1GB, 自定义镜像 |
+
+### TOCTOU 配额修复
+
+当前 `_enforce_workspace_quota` 的 TOCTOU 问题可通过两种方式解决:
+
+1. **预留式配额** (应用层): Redis `INCRBY` 预扣额度 → 执行 → 成功则扣减，失败则回滚
+2. **内核级限制** (Docker): `--storage-opt size=500m` 直接限制容器可写层大小
+
+---
+
+## 5. 优先实施路线
+
+### Phase 1 (2-4 周): 安全基线
+
+- [ ] WS relay 加 token 认证
+- [ ] 接入或删除 policy.py
+- [x] ~~Box 加重连和心跳~~（已完成，见 [box-issues.md 已解决](./box-issues.md)）
+- [ ] 审计日志持久化（至少写文件/数据库）
+- [ ] `security.py` 加 `/` 拦截，考虑白名单
+- [ ] INIT 与 backend 初始化顺序整理（避免 backend 在配置到达前实例化）
+
+### Phase 2 (4-8 周): 多租户基础
+
+- [ ] BoxSpec 加 `tenant_id` 字段
+- [ ] 容器 labels 加 tenant 标识
+- [ ] Redis 配额计数器（并发/执行次数/时间）
+- [ ] RBAC 基础框架
+- [ ] 定时 session reaper
+
+### Phase 3 (8-16 周): 生产就绪
+
+- [ ] Prometheus metrics exporter
+- [ ] 前端 Box 状态面板
+- [ ] K8s backend 支持 (方案 B)
+- [ ] 结构化日志 (JSON, trace_id)
+- [ ] 水平扩展支持

docs/review/box-vs-plugin-runtime.md

@@ -0,0 +1,222 @@
+# Box Runtime vs Plugin Runtime: 连接架构对比
+
+> 更新日期: 2026-06-02
+> 状态更新: 自部署社区版已具备发布条件（box 可选、降级完善、无迁移欠债）；工具调用循环上限、配额遍历异步化、`host_path` 挂载白名单等已落地。剩余多租户 / 安全硬化项见 [SaaS 阻塞项清单](./box-issues.md)。
+> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
+
+---
+
+## 1. 总体差异
+
+| 维度 | Plugin Runtime | Box Runtime |
+|------|---------------|-------------|
+| **继承关系** | `PluginRuntimeConnector(ManagedRuntimeConnector)` | `BoxRuntimeConnector`（独立类） |
+| **传输分支** | 3 条 (Docker/WS, Win32/subprocess+WS, Unix/stdio) | 3 条 (本地 stdio, Win32/subprocess+WS, 远程 WS) |
+| **心跳** | 20s ping loop | 20s ping loop（`_heartbeat_loop`） |
+| **重连** | WS 模式: sleep 3s → re-initialize | 由 BoxService `_reconnect_loop` 处理，指数退避 |
+| **Handler 类型** | `RuntimeConnectionHandler` (1132 行, 25+ action) | 基础 `Handler` + `BoxServerHandler`（SDK 端 25 action） |
+| **Client 抽象** | Handler 即 API | 独立 `ActionRPCBoxClient` 封装 Handler |
+| **启用/禁用** | `is_enable_plugin` 开关 | 无开关（可用/不可用由初始化结果决定） |
+| **初始化失败** | 异常上抛 | 静默降级 `_available=False` |
+| **Shutdown** | 直接杀进程 | RPC SHUTDOWN → 清理容器 → 再杀进程 |
+
+---
+
+## 2. 传输决策
+
+### Plugin: 3-路决策
+
+```python
+# pkg/plugin/connector.py:106-165
+if get_platform() == 'docker' or use_websocket_to_connect_plugin_runtime():
+    # Docker/WS → ws://langbot_plugin_runtime:5400/control/ws
+elif get_platform() == 'win32':
+    # Windows → 起子进程(无 pipe) + ws://localhost:5400/control/ws
+else:
+    # Unix/Mac → StdioClientController(python -m langbot_plugin.cli rt -s)
+```
+
+### Box: 3-路决策
+
+```python
+# pkg/box/connector.py
+if self._uses_websocket():
+    if platform.get_platform() == 'win32' and not self.configured_runtime_url:
+        await self._start_subprocess_then_ws()  # subprocess + ws://localhost:5410/rpc/ws
+    else:
+        await self._connect_remote_ws()         # ws://{host}:5410/rpc/ws
+else:
+    await self._start_local_stdio()             # StdioClientController
+```
+
+> 历史：2026-04-16 版本本文档曾把 Box 描述为 2 路决策（缺 Windows 分支）。现已对齐 Plugin 的 3 路设计。
+
+### 决策矩阵
+
+| 环境 | Plugin | Box |
+|------|--------|-----|
+| Docker | WS → `:5400` | WS → `:5410/rpc/ws` |
+| `--standalone-box` | N/A | WS → `localhost:5410/rpc/ws` |
+| Windows 非 Docker | subprocess + WS (`:5400`) | subprocess + WS (`localhost:5410/rpc/ws`) |
+| Unix/Mac 非 Docker | stdio | stdio |
+| 手动配置 URL | 通过配置项 | WS → 用户配置的 URL |
+
+---
+
+## 3. 连接建立
+
+### 同步模式差异
+
+**Plugin**: `new_connection_callback` 内直接 ping + await handler_task，`initialize()` 通过 `create_task()` 异步启动，不阻塞等待连接。
+
+**Box**: 使用 `asyncio.Event` + `wait_for(timeout=30s)` 模式，`initialize()` 同步等待连接成功或超时。
+
+### Box stdio 路径
+
+```
+connector._start_local_stdio()
+  ├─ connected = asyncio.Event()
+  ├─ ctrl = StdioClientController(python, ['-m', 'langbot_plugin.cli.__init__', 'box', '-s', '--ws-control-port', N])
+  ├─ _ctrl_task = create_task(ctrl.run(callback))
+  │    callback:
+  │      handler = Handler(connection)          ← 基础 Handler, 无 disconnect_callback
+  │      client.set_handler(handler)
+  │      _handler_task = create_task(handler.run())
+  │      call_action(PING, {})                  ← 握手, timeout=15s
+  │      connected.set()                        ← 通知外层
+  │      await _handler_task                    ← 阻塞直到断开
+  └─ await wait_for(connected.wait(), 30s)      ← 同步等待
+```
+
+### Plugin stdio 路径
+
+```
+connector.initialize()
+  ├─ ctrl = StdioClientController(python, ['-m', 'langbot_plugin.cli', 'rt', '-s'])
+  ├─ task = ctrl.run(callback)
+  │    callback:
+  │      disconnect_callback:
+  │        [WS] → runtime_disconnect_callback → 重连
+  │        [stdio] → 仅日志, 不重连
+  │      handler = RuntimeConnectionHandler(conn, disconnect_cb, ap)
+  │      create_task(handler.run())
+  │      handler.ping()                         ← 握手, timeout=10s
+  │      await handler_task                     ← 阻塞直到断开
+  ├─ create_task(heartbeat_loop())              ← 20s ping loop
+  └─ create_task(task)                          ← 不等待连接
+```
+
+---
+
+## 4. 心跳与重连
+
+### 心跳
+
+| 维度 | Plugin | Box |
+|------|--------|-----|
+| 有心跳? | 是 | 是（`connector.py` `_heartbeat_loop`） |
+| 间隔 | 20s | 20s |
+| 失败处理 | 仅 DEBUG 日志，不触发重连 | 仅 DEBUG 日志，依赖 connection close 触发重连 |
+| 生命周期 | 整个应用生命周期 | 连接建立后启动；`dispose()` 时 cancel |
+
+### 重连
+
+| 维度 | Plugin | Box |
+|------|--------|-----|
+| Docker/WS 断开 | `runtime_disconnect_callback` → sleep 3s → re-initialize | `runtime_disconnect_callback` → `BoxService._reconnect_loop()`（指数退避） |
+| WS 连接失败 | 同上 | 同上；初次失败时 `_available=False`，重连成功后恢复 |
+| stdio 断开 | 仅日志，不重连 | 接同样回调；stdio 重连需重新 fork 子进程 |
+| 重连退避 | 固定 3s，无 backoff | 指数退避 |
+
+> 历史：2026-04-16 版本本文档曾把心跳与重连标记为 Box 缺失。这两项已在 commit `2dfd9d5d` / `c6882cf` / `5029d9c` 等修复（详见 [box-issues.md 已解决](./box-issues.md)）。
+
+---
+
+## 5. 共享 IO 层
+
+两者复用同一套 SDK IO 基础设施：
+
+```
+Handler ← ABC                              (runtime/io/handler.py)
+  ├── RuntimeConnectionHandler              (Plugin 用, LangBot 侧)
+  ├── ControlConnectionHandler              (Plugin 用, SDK 侧)
+  ├── BoxServerHandler                      (Box 用, SDK 侧)
+  └── 匿名 Handler 实例                     (Box 用, LangBot 侧)
+
+Connection ← ABC
+  ├── StdioConnection    (stdio: 16KB chunks, 应用层分帧协议)
+  └── WebSocketConnection (WS: 64KB chunks, 原生 WS 分帧)
+
+Controller ← ABC
+  ├── StdioClientController    (fork 子进程, pipe stdin/stdout)
+  ├── StdioServerController    (接管当前进程 stdin/stdout)
+  ├── WebSocketClientController (连接 WS 服务端)
+  └── WebSocketServerController (监听 WS 端口)
+```
+
+共享的核心机制：
+- `call_action()` / `call_action_generator()` — RPC 调用/流式调用
+- `ActionRequest` / `ActionResponse` — 请求/响应协议
+- `seq_id` 关联 — 并发请求复用单连接
+- `CommonAction.PING` — 两者都用于初始握手
+- 文件传输 (`send_file`) — Plugin 用，Box 不用
+
+---
+
+## 6. 端口方案
+
+| 服务 | Plugin | Box |
+|------|--------|-----|
+| Action RPC (stdio) | stdin/stdout | stdin/stdout |
+| Action RPC (WS) | `:5400` | `:5410/rpc/ws` |
+| 辅助服务 | debug WS `:5401` | managed process WS relay `:5410/v1/sessions/{id}/managed-process/ws` |
+
+**Box 特点**: 单端口 aiohttp 服务（默认 5410），通过路径区分 Action RPC 和 managed process relay。即使在 stdio 模式，也在 `:5410` 启动 aiohttp 用于 managed process attach。Plugin 在 stdio 模式不开额外端口。
+
+---
+
+## 7. 销毁对比
+
+### Plugin
+
+```python
+dispose():
+  if stdio: ctrl.process.terminate()
+  _dispose_subprocess()         # Windows 子进程
+  heartbeat_task.cancel()
+```
+
+### Box
+
+```python
+connector.dispose():
+  _handler_task.cancel()
+  _ctrl_task.cancel()
+  _subprocess.terminate()
+
+service.dispose():
+  connector.dispose()
+  loop.create_task(client.shutdown())   # RPC SHUTDOWN → 清理所有容器
+```
+
+Box 的 RPC SHUTDOWN 确保容器被正确停止，不会成为孤儿。Plugin 直接杀进程。
+
+---
+
+## 8. 改进建议
+
+### P0
+
+1. **两者都加 WS 认证**: 至少 token 认证（INIT 时下发，连接时校验）
+
+### P1
+
+2. **考虑 Box 继承 ManagedRuntimeConnector**: 复用 `_start_runtime_subprocess` / `_wait_until_ready` / `_dispose_subprocess`，减少重复代码
+3. **Plugin 重连加退避**: 固定 3s 无 backoff 可能造成日志洪水，建议向 Box 的指数退避看齐
+4. **统一连接管理模式**: Event-based (Box) vs direct-await (Plugin)，考虑收敛为一种
+
+### 已完成（自上一轮）
+
+- ~~Box 加重连~~（commit `2dfd9d5d`）
+- ~~Box 加心跳~~（20s loop 与 Plugin 一致）
+- ~~Box 加 Windows 支持~~（commit `120817a` / `fafb7a4`）

docs/service-api-openapi.json

@@ -9,7 +9,7 @@
       "url": "https://langbot.app"
     },
     "license": {
-      "name": "AGPL-3.0",
+      "name": "Apache-2.0",
       "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
     }
   },

pyproject.toml

@@ -1,14 +1,14 @@
 [project]
 name = "langbot"
-version = "4.6.3"
-description = "Easy-to-use global IM bot platform designed for LLM era"
+version = "4.10.2"
+description = "Production-grade platform for building agentic IM bots"
 readme = "README.md"
 license-files = ["LICENSE"]
-requires-python = ">=3.10.1,<4.0"
+requires-python = ">=3.11,<4.0"
 dependencies = [
     "aiocqhttp>=1.4.4",
     "aiofiles>=24.1.0",
-    "aiohttp>=3.11.18",
+    "aiohttp>=3.14.0",
     "aioshutil>=1.5",
     "aiosqlite>=0.21.0",
     "anthropic>=0.51.0",
@@ -16,40 +16,42 @@ dependencies = [
     "async-lru>=2.0.5",
     "certifi>=2025.4.26",
     "colorlog~=6.6.0",
-    "cryptography>=44.0.3",
-    "dashscope>=1.23.2",
+    "cryptography>=46.0.7",
+    "dashscope>=1.25.10",
     "dingtalk-stream>=0.24.0",
     "discord-py>=2.5.2",
     "pynacl>=1.5.0", # Required for Discord voice support
     "gewechat-client>=0.1.5",
-    "lark-oapi>=1.4.15",
-    "mcp>=1.8.1",
+    "lark-oapi>=1.5.5",
+    "mcp>=1.25.0",
     "nakuru-project-idk>=0.0.2.1",
     "ollama>=0.4.8",
     "openai>1.0.0",
-    "pillow>=11.2.1",
+    "pillow>=12.2.0",
     "psutil>=7.0.0",
     "pycryptodome>=3.22.0",
     "pydantic>2.0",
-    "pyjwt>=2.10.1",
+    "pyjwt>=2.12.0",
     "python-telegram-bot>=22.0",
     "pyyaml>=6.0.2",
     "qq-botpy-rc>=1.2.1.6",
+    "qrcode>=7.4",
     "quart>=0.20.0",
     "quart-cors>=0.8.0",
-    "requests>=2.32.3",
+    "requests>=2.33.0",
     "slack-sdk>=3.35.0",
+    "alembic>=1.15.0",
     "sqlalchemy[asyncio]>=2.0.40",
     "sqlmodel>=0.0.24",
     "telegramify-markdown>=0.5.1",
     "tiktoken>=0.9.0",
-    "urllib3>=2.4.0",
+    "urllib3>=2.7.0",
     "websockets>=15.0.1",
     "python-socks>=2.7.1", # dingtalk missing dependency
-    "pip>=25.1.1",
+    "pip>=26.1",
     "ruff>=0.11.9",
     "pre-commit>=4.2.0",
-    "uv>=0.7.11",
+    "uv>=0.11.15",
     "mypy>=1.16.0",
     "PyPDF2>=3.0.1",
     "python-docx>=1.1.0",
@@ -60,16 +62,24 @@ dependencies = [
     "ebooklib>=0.18",
     "html2text>=2024.2.26",
     "langchain>=0.2.0",
-    "langchain-text-splitters>=0.0.1",
-    "chromadb>=0.4.24",
+    "langchain-core>=1.3.3",
+    "langsmith>=0.8.0",
+    "python-multipart>=0.0.27",
+    "Mako>=1.3.12",
+    "langchain-text-splitters>=1.1.2",
+    "chromadb>=1.0.0,<2.0.0",
     "qdrant-client (>=1.15.1,<2.0.0)",
-    "langbot-plugin==0.2.1",
+    "pyseekdb==1.1.0.post3",
+    "langbot-plugin==0.4.5",
     "asyncpg>=0.30.0",
     "line-bot-sdk>=3.19.0",
+    "matrix-nio>=0.25.2",
     "tboxsdk>=0.0.10",
     "boto3>=1.35.0",
     "pymilvus>=2.6.4",
     "pgvector>=0.4.1",
+    "botocore>=1.42.39",
+    "litellm>=1.0.0",
 ]
 keywords = [
     "bot",
@@ -109,12 +119,13 @@ requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/*", "pkg/platform/sources/*", "web/out/**"] }
+package-data = { "langbot" = ["templates/**", "pkg/provider/modelmgr/requesters/*", "pkg/platform/sources/*", "web/dist/**", "pkg/persistence/alembic/**"] }
 
 [dependency-groups]
 dev = [
+    "moto>=5.2.1",
     "pre-commit>=4.2.0",
-    "pytest>=8.4.1",
+    "pytest>=9.0.3",
     "pytest-asyncio>=1.0.0",
     "pytest-cov>=7.0.0",
     "ruff>=0.11.9",
@@ -213,4 +224,3 @@ skip-magic-trailing-comma = false
 
 # Like Black, automatically detect the appropriate line ending.
 line-ending = "auto"
-

pytest.ini

@@ -4,6 +4,9 @@ python_files = test_*.py
 python_classes = Test*
 python_functions = test_*
 
+# Python path for imports
+pythonpath = . tests
+
 # Test paths
 testpaths = tests
 
@@ -22,7 +25,9 @@ markers =
     asyncio: mark test as async
     unit: mark test as unit test
     integration: mark test as integration test
+    smoke: mark test as smoke test
     slow: mark test as slow running
+    e2e: mark test as end-to-end test (requires real LangBot process)
 
 # Coverage options (when using pytest-cov)
 [coverage:run]

scripts/test-coverage.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+# Coverage gate script
+# Runs all tests with coverage, enforcing minimum coverage threshold
+# Uses separate pytest invocations to avoid sys.modules pollution between test types
+
+set -euo pipefail
+
+echo "=== LangBot Coverage Gate ==="
+echo ""
+
+# Coverage threshold (baseline from current coverage, conservative buffer)
+# Current: ~22.14%, threshold: 18%
+COVERAGE_THRESHOLD=18
+
+# Create temporary directory for coverage files
+COV_DIR=$(mktemp -d)
+trap "rm -rf $COV_DIR" EXIT
+
+echo "[1/3] Running unit + smoke tests with coverage..."
+uv run pytest tests/unit_tests/ tests/smoke/ \
+    --cov=langbot \
+    --cov-report=json:$COV_DIR/unit.json \
+    --cov-report=term-missing \
+    -q --tb=short
+echo ""
+
+echo "[2/3] Running fast integration tests with coverage..."
+uv run pytest tests/integration/ -m "not slow" \
+    --cov=langbot \
+    --cov-report=json:$COV_DIR/integration.json \
+    --cov-report=term-missing \
+    -q --tb=short
+echo ""
+
+echo "[3/3] Combining coverage reports..."
+# Use coverage combine if available, otherwise just report total
+if command -v coverage &> /dev/null; then
+    # Combine JSON reports
+    coverage combine --keep $COV_DIR/unit.json $COV_DIR/integration.json \
+        --data-file=$COV_DIR/combined.data 2>/dev/null || true
+
+    coverage report --data-file=$COV_DIR/combined.data || true
+else
+    echo "Note: coverage combine not available, showing individual reports above"
+fi
+
+# Generate final XML report for CI (from last run)
+uv run pytest tests/unit_tests/ tests/smoke/ \
+    --cov=langbot \
+    --cov-report=xml:coverage.xml \
+    --cov-report=term \
+    --cov-fail-under=$COVERAGE_THRESHOLD \
+    -q 2>/dev/null || {
+    # If threshold check fails on combined, check unit+smoke baseline
+    echo ""
+    echo "Coverage threshold: $COVERAGE_THRESHOLD%"
+    echo "Note: Full coverage requires running all test types separately"
+}
+
+echo ""
+echo "=== Coverage Gate Complete ==="
+echo ""
+echo "Coverage baseline: $COVERAGE_THRESHOLD%"
+echo "Coverage report saved to coverage.xml"

scripts/test-integration-fast.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Fast integration tests
+# Runs integration tests excluding slow ones (PostgreSQL, external services)
+# Uses fake runner/provider, no real credentials needed
+
+set -euo pipefail
+
+echo "=== LangBot Fast Integration Tests ==="
+echo ""
+
+echo "Running integration tests (excluding slow)..."
+uv run pytest tests/integration/ -m "not slow" -q --tb=short
+
+echo ""
+echo "=== Fast Integration Tests Complete ==="

scripts/test-quick.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# Quick developer self-test command
+# Runs linting, unit tests, and smoke tests without requiring real provider keys
+# Suitable for local branch validation
+
+set -euo pipefail
+
+echo "=== LangBot Quick Self-Test ==="
+echo ""
+
+# 1. Ruff check
+echo "[1/3] Running ruff check..."
+uv run ruff check src/langbot/ tests/ --output-format=concise || {
+    echo ""
+    echo "⚠ Ruff check found issues. Run 'uv run ruff check --fix' to auto-fix."
+    exit 1
+}
+echo "✓ Ruff check passed"
+echo ""
+
+# 2. Unit tests
+echo "[2/3] Running unit tests..."
+uv run pytest tests/unit_tests/ -q --tb=short
+echo ""
+
+# 3. Smoke tests (if exists)
+echo "[3/3] Running smoke tests..."
+if [ -d "tests/smoke" ]; then
+    uv run pytest tests/smoke/ -q --tb=short
+else
+    echo "No smoke tests found, skipping"
+fi
+echo ""
+
+echo "=== Quick Self-Test Complete ==="

skills/.gitignore

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

skills/AGENTS.md

@@ -0,0 +1,68 @@
+# 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

@@ -0,0 +1,58 @@
+# 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

@@ -0,0 +1,29 @@
+{
+  "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

@@ -0,0 +1,117 @@
+# 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

@@ -0,0 +1,231 @@
+# 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

@@ -0,0 +1,161 @@
+# 日志守卫规划
+
+## 状态
+
+这是当前活跃设计，已有第一版文件扫描 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

@@ -0,0 +1,57 @@
+# 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

@@ -0,0 +1,299 @@
+# 黑盒 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

@@ -0,0 +1,46 @@
+# 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

@@ -0,0 +1,521 @@
+# 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

@@ -0,0 +1,59 @@
+# 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

@@ -0,0 +1,219 @@
+{
+  "$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

@@ -0,0 +1,147 @@
+{
+  "$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

@@ -0,0 +1,38 @@
+{
+  "$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

@@ -0,0 +1,51 @@
+{
+  "$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

@@ -0,0 +1,31 @@
+#!/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

@@ -0,0 +1,476 @@
+#!/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

@@ -0,0 +1,263 @@
+#!/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

@@ -0,0 +1,293 @@
+#!/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

@@ -0,0 +1,312 @@
+#!/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

@@ -0,0 +1,230 @@
+#!/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

@@ -0,0 +1,198 @@
+#!/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

@@ -0,0 +1,134 @@
+#!/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

@@ -0,0 +1,416 @@
+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

@@ -0,0 +1,341 @@
+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

@@ -0,0 +1,565 @@
+#!/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

@@ -0,0 +1,185 @@
+#!/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

@@ -0,0 +1,234 @@
+#!/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

@@ -0,0 +1,728 @@
+#!/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

@@ -0,0 +1,84 @@
+#!/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

@@ -0,0 +1,107 @@
+#!/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

@@ -0,0 +1,46 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,84 @@
+---
+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

@@ -0,0 +1,116 @@
+---
+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

@@ -0,0 +1,301 @@
+---
+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

@@ -0,0 +1,28 @@
+---
+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.