mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-08-31 14:47:13 +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` 为准。
|
||||
Reference in New Issue
Block a user