mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-08-29 05:37:14 +00:00
feat: MCP server + in-repo skills (agent-friendly platform) (#2269)
* 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.
This commit is contained in:
Junyan Chin
@@ -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` 是诊断工具，不是主要测试路径。
|
||||
Reference in New Issue
Block a user