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 通过标准。

快速开始

Clone 仓库。
检查本地默认变量：

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

检查环境是否就绪：

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 的入口文件未漂移。

查看已有测试 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。

生成 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 通过。

重要原则

这些原则固定在：

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 维护协议

添加一个新测试路径

先让 agent 通过浏览器探索并执行路径。
稳定后创建 case：

bash

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

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

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

LangBot Skills 用户使用手册

LangBot Skills 用户使用手册

这个仓库解决什么

快速开始

推荐使用方式

冒烟测试

Runner Externalization 发布门禁

新 Feature 测试

定点排错

重要原则

规划文档

常用命令

环境

Skill 和索引

Case

Suite

Test Plan

Test Start

Test Automation

Test Report 和日志守卫

Runtime Log Guard

Test Result

Troubleshooting

目录说明

添加一个新测试路径

添加一个新故障

当前边界