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

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. 检查本地默认变量：

bin/lbs env show

默认变量在：

skills/.env

本机专用覆盖写到：

skills/.env.local

它会覆盖 skills/.env 中的同名变量，并且不应该提交。 skills/.env 是共享默认值，不应写入本机绝对路径、浏览器 profile、provider key 或其他凭据。 新机器建议从模板开始：

cp skills/.env.example skills/.env.local

常用变量：

LANGBOT_FRONTEND_URL
LANGBOT_BACKEND_URL
LANGBOT_DEV_FRONTEND_URL
LANGBOT_REPO
LANGBOT_WEB_REPO
LANGBOT_BROWSER_PROFILE

3. 检查环境是否就绪：

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：

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 执行计划：

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 说：

帮我跑一下 LangBot 新前端 smoke test。

agent 应该：

• 读 skills/.env
• 优先查看 bin/lbs suite plan core-smoke，或查找 type: smoke 的 cases
• 生成 test plan
• 用浏览器执行 UI 操作
• 检查 console、截图、后端日志
• 输出简短 QA 报告

Runner Externalization 发布门禁

你可以直接对 agent 说：

按 agent-runner release gate 跑完整矩阵，先做 preflight，再跑浏览器 case，并把 blocked/env_issue/fail 分开。

agent 应该先查看 skills/langbot-testing/references/agent-runner-release-gate.md， 再执行：

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 后，用：

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 测试

你可以说：

我改了 provider 页面，帮我测一下 DeepSeek provider 添加、测试、绑定 pipeline 是否正常。

agent 应该：

• 查找相关 case 和 reference
• 如果没有稳定路径，先探索 UI
• 用浏览器执行真实交互
• 失败时用日志/API 辅助定位
• 稳定后新增或更新 case/reference
• 新故障沉淀为 troubleshooting

定点排错

你可以说：

Debug Chat 点了没回复，帮我查是前端问题还是后端问题。

agent 应该：

• 先通过 UI 复现
• 看 console/network
• 看后端日志
• 必要时用 API/curl 做诊断
• 匹配 troubleshooting
• 给出修复建议或直接修复

重要原则

这些原则固定在：

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 值。

规划文档

如果要判断下一步建设什么，先看：

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

01-qa-agent-harness-plan.md 是早期规划，部分内容已经被当前实现和路线图替代。

常用命令

环境

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 和索引

bin/lbs list
bin/lbs validate
bin/lbs index --check
bin/lbs index

Case

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

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

bin/lbs test plan pipeline-debug-chat
bin/lbs test plan pipeline-debug-chat --json

Test Start

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

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：

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 后才能真正执行：

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 和日志守卫

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。

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：

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：

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

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

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 "..."

目录说明

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：

bin/lbs case new provider-xxx --title "Provider XXX can be configured" --area provider --type provider

3. 编辑生成的 cases/*.yaml，补充真实步骤、检查点和 troubleshooting。

4. 校验：

bin/lbs validate
bin/lbs index --check
bin/lbs index

添加一个新故障

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 是诊断工具，不是主要测试路径。