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,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 未稳定时拖慢迭代。
|
||||
@@ -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 检查。
|
||||
@@ -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 样例。
|
||||
@@ -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?"
|
||||
@@ -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 的空间。
|
||||
@@ -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` 为准。
|
||||
@@ -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