IronClaw Live Canary 回归矩阵：本地运行、账号体系与 CI 集成完全指南

• 人工智能
• AI 应用
• 交互助手
• AI Agent

IronClaw 的 live canary 是一套面向真实第三方服务（真实 LLM、真实 OAuth 登录页、真实 provider API）的持续回归系统，与只回放提交过的 fixture 的确定性 CI 互补，专门捕捉 mock 无法暴露的 provider 漂移、token 刷新失败、升级兼容性和鉴权回归。本文以 scripts/live-canary/README.md 为骨架，结合 scripts/live-canary/run.sh、scripts/live-canary/scrub-artifacts.sh、scripts/live-canary/ACCOUNTS.md 与共享 Python 框架，完整讲解 lane 体系、本地命令、构件与密钥清洗策略、账号材料管理及 CI 集成，读完后你可以独立拉起任意一条 live canary lane 并正确解读产物。

目录结构与命名约定

scripts/live-canary/（带连字符）是面向操作者的统一入口目录，包含三个核心 shell 入口点：

• run.sh —— 统一 lane 分发器：根据LANE环境变量分发到对应 lane，并负责写构件（summary、env 摘要、日志、results.json 等）；
• scrub-artifacts.sh —— 上传前的构件扫描与清洗守卫；
• upgrade-canary.sh —— 检查"上一发布版本创建的数据库能否被当前 checkout 打开并使用"。

而鉴权相关 Python 执行器位于两个兄弟目录：

• scripts/auth_canary/run_canary.py —— mock 支撑的 pytest 矩阵（fresh-machine，对应auth-smoke/auth-full/auth-channels）；
• scripts/auth_live_canary/run_live_canary.py —— 真实 provider 执行器，两种模式：--mode seeded（token 持久化与刷新）与--mode browser（Playwright 驱动 OAuth consent）。

两者共享的鉴权 canary 框架位于scripts/live_canary/（下划线，Python 包）：

• common.py —— 环境变量/密钥读取、Python venv 引导、Playwright 安装、网关栈启动等通用运行时；
• auth_registry.py —— 各 provider 的 case 注册表（seeded 与 browser 两套 case 定义）；
• auth_runtime.py —— 扩展安装、OAuth setup 流程、/v1/responses探针等 API 驱动逻辑。

命名约定值得注意：live-canary/（连字符）是 shell 分发器与操作者入口；live_canary/（下划线）是 Python 包。这种连字符/下划线拆分遵循 Python 的包命名约定——Python import 不允许出现连字符。未来新增鉴权 provider 应当通过共享注册表和账号指南扩展，而不是另起一套独立 runner 形态。所有命令都要求从仓库根目录执行。

Lane 家族全景

README 将 lane 划分为三类：

上游 live LLM lanes

• deterministic-replay—— 确定性回放（在run.sh中以IRONCLAW_LIVE_TEST=0运行e2e_live测试）；
• public-smoke—— 真实 LLM 加公开工具，每日定时与手动触发；
• persona-rotating—— 真实 LLM 多轮 persona 工作流，每天轮换一个 persona。run.sh中的select_rotating_persona()按星期几（date -u +%u）选择：周一/周六ceo_full_workflow，周二/周日content_creator_full_workflow，周三trader_full_workflow，周四/周五developer_full_workflow；也可通过SCENARIO显式覆盖；
• private-oauth—— Google Drive 鉴权门与透明刷新，针对专用测试账号。run.sh中drive_auth_gate_roundtrip目前被跳过（等待非 HTTP 预检鉴权门落地），实际运行drive_transparent_oauth_refresh；
• release-public-full—— 发布候选的完整公开 live 套件（e2e_live_mission+e2e_live_personas全量）；
• upgrade-canary—— 上一版本数据库升级兼容性检查。

本分支新增的 Auth lanes

• auth-smoke—— mock 支撑的鉴权冒烟（hosted OAuth、MCP OAuth、多用户 MCP 隔离），每小时与手动；
• auth-full—— 更大的 mock 鉴权矩阵（含失败与刷新 case），手动；
• auth-channels—— WASM 频道鉴权诊断 lane，手动；
• auth-live-seeded—— 向干净数据库播种已知良好凭据后做真实 provider 运行时检查，每小时与手动；
• auth-browser-consent—— Playwright 打开真实 provider OAuth 流程完成浏览器 consent，每晚与手动。

Reborn WebUI v2 QA lane

• reborn-webui-v2-live-qa—— 以 QA 表格 case 为支撑、驱动 Reborn CLIserve与 WebUI v2 的完整 live QA 矩阵，每 3 小时与手动。

run.sh的分发逻辑（见 run.sh）中，cargo 类 lane 统一走run_cargo_test（cargo test --test <target> <filter> -- --ignored --nocapture --test-threads=1），Python 类 lane 统一走run_python_lane（把--skip-build/--skip-python-bootstrap与--case/--all-cases/--non-telegram-qa-cases等参数转发给 Python runner）。未识别的LANE会打印已知 lane 列表并以状态码 2 退出。

PR 定向运行的门禁：PR 定向运行使用被评审的 PR 二进制加真实集成密钥执行。它们必须通过reborn-live-canary-prGitHub environment gate（见 .github/workflows/live-canary.yml 中environment: reborn-live-canary-pr），并且对精确的 PR head commit 需要有来自具写权限协作者的 approving review。定时与手动触发的默认分支运行不要求该 PR gate。

本地命令速查

从仓库根目录执行以下命令：

# 运行公开 live smoke lane LANE=public-smoke scripts/live-canary/run.sh # 运行 auth smoke lane LANE=auth-smoke scripts/live-canary/run.sh # 运行 seeded auth live lane LANE=auth-live-seeded scripts/live-canary/run.sh # 运行 browser-consent auth lane LANE=auth-browser-consent scripts/live-canary/run.sh

只运行选定的 provider case（逗号分隔，run.sh的build_case_args会解析成多个--case参数）：

LANE=auth-live-seeded CASES=gmail,github scripts/live-canary/run.sh LANE=auth-browser-consent CASES=google,notion scripts/live-canary/run.sh # Browser cases: google, notion only。github 是 PAT-only（非 OAuth）， # 所以它留在 auth-live-seeded 中——见 scripts/live_canary/auth_registry.py。

运行 Reborn WebUI v2 live QA lane，复用本地拷贝的 Reborn home：

LANE=reborn-webui-v2-live-qa \ REBORN_WEBUI_V2_LIVE_QA_HOME=/tmp/ironclaw-reborn-real-slack \ scripts/live-canary/run.sh

运行完整 QA 表支撑的 Reborn 套件（CASES=all在 reborn lane 下会展开为--non-telegram-qa-cases）：

LANE=reborn-webui-v2-live-qa CASES=all scripts/live-canary/run.sh

使用 CI 风格浏览器安装（含系统依赖）：

LANE=auth-browser-consent PLAYWRIGHT_INSTALL=with-deps scripts/live-canary/run.sh

复用已有构建与 Python 环境（跳过重新构建与 venv 引导）：

LANE=auth-smoke SKIP_BUILD=1 SKIP_PYTHON_BOOTSTRAP=1 scripts/live-canary/run.sh

运行升级 canary（用 tag 指代上一版本）：

LANE=upgrade-canary \ PREVIOUS_REF=v0.1.2 \ CURRENT_REF=HEAD \ scripts/live-canary/run.sh

关键环境变量

从 run.sh 可以看到分发器的可调参数及默认值：

run.sh开头的set +x是刻意的安全护栏：显式关闭命令追踪，防止未来某次编辑加入set -x（或调用方继承的-x）把环境派生出的命令参数里的任务级密钥插值进 workflow 日志。

构件输出与摘要

所有构件写入：

artifacts/live-canary/<lane>/<provider>/<timestamp>/

每次运行固定产出的文件（由 run.sh 定义）：

• test-output.log—— 全量日志；
• summary.md—— 汇总表（lane、scenario、provider、status、started/finished、commit 与构件清单）；
• env-summary.txt—— 环境摘要（sha、branch、rustc、cargo、LLM_BACKEND、LLM_MODEL、DATABASE_BACKEND、LIBSQL_PATH、cases、skip_build等）；
• trace-fixture-status.txt——tests/fixtures/llm_traces/live目录的 git 状态（live 运行是否改变了 trace fixture）；
• results.json—— 结构化结果（cargo lane 由 emit_results_json.py 从日志解析生成）。

另外 reborn lane 还产出case-manifest.json（含retry_policy）、preflight.json（预检结果）等。

Reborn WebUI v2 lane 的重试语义与隐私安全指标

该 lane 的 runner 会保留每个 case 的每次尝试到results.json。一个先失败后成功的 case 会被报告为retry_outcome: "flake"，并在 green-run-explanation.json 中单独计数，不会当作普通首次通过呈现。从 run_live_qa.py 可以看到：创建 routine、触发或验证外部投递、断言 exactly-once 行为、或守卫安全敏感输出的 case 在 case_matrix.py 中声明retry_policy: "never"，重试不会复制副作用或掩盖确定性失败。

模型驱动的 case 还会在results.json中发布隐私安全的标量details.metrics：模型/工具调用次数、模型发出的工具调用批次数量与宽度分布、输入/输出/缓存读/未缓存输入 token 数，以及提供商定价可用时的 USD 成本。计数来自该 case 的完整 LLM trace（在原始 trace 从上传构件中排除之前提取）；prompt、response、工具参数与工具输出内容永远不会被复制进 metrics。旧版或中断的 trace 将 batch/cache/cost 值报告为null而非 0（见_unavailable_case_metrics与_zero_case_metrics的区分，run_live_qa.py）。

上传前的构件清洗策略

scrub-artifacts.sh 是防止把明显 token 形态的字符串从日志或结果文件上传上去的守卫。默认（非严格）模式是 report-only：扫描并输出scrub-matches.txt匹配清单，但不裁剪；STRICT_ARTIFACT_SCRUB=true时启用严格清洗。

严格模式下的三类裁剪

1. 受管系统技能快照：只删除"受管标记 + 稳定内容哈希 + 文件集合 + 字节内容"四项全部与测试提交的源控制 bundle 匹配的副本。脚本用内嵌 Python 实现 FNV-64 内容哈希（初始值0xCBF29CE484222325、乘数0x100000001B3）对源 bundle 计算，并与运行时标记.ironclaw-reborn-bundled.json中记录的content_hash（16 位十六进制）比对；同时校验标记owner必须等于运行时铸币方ironclaw_composition_bundled_skill（Rust 侧定义见crates/extensions/ironclaw_extension_host/src/bundled_skills.rs）、format == 1，并逐文件比对文件集与字节。对不带标记的 backend-generic 技能挂载树，退化为"文件集与字节与源 bundle 完全一致"的源码等价校验。未验证/不受管/发散的系统技能与所有其他运行特有构件保持原样并纳入密钥扫描。
2. 第一方扩展 manifest：源码逐字节验证的第一方扩展 manifest 也会被删除，因为其静态凭据 schema 字段看起来像 live 密钥。NEAR AI 的动态渲染 manifest 则先在只规范化仓库所有的cloud-api.near.ai与private.near.aiMCP 端点后，与可信运行时模板 scripts/live-canary/fixtures/nearai-runtime-manifest.toml 比对。改动或无法识别的 manifest 仍受 fail-closed 扫描约束。
3. 密钥形态内容：对全部文件跑一组保守正则（bearer后跟 16+ token 字母表字符、api_key/access_token/refresh_token/secret/password赋值、JSON 引号 token 形态、gh[pousr]_/github_pat_/ya29./xox[baprs]-/sk-/sk-ant-/AKIA[0-9A-Z]{16}等）。严格模式下，可清洗构件（*.log、*.jsonl、summary.md、env-summary.txt、results.json、case-manifest.json、preflight.json、auth-canary-junit.xml、browser 摘要、llm-traces/*.json等）被就地替换为<REDACTED>变体（并校验 JSON 合法性）；不可清洗构件直接删除；若删除后仍有未脱敏命中，退出码非 0 使 lane 失败。二进制文件（png/jpg/sqlite/db/wasm/zip）跳过扫描。

此外，emit_results_json.py 在把 panic 消息写入results.json之前也做一次防御性脱敏（REDACT_PATTERNS与 shell 脚本规则对齐），防止断言输出意外携带真实 token 进入构件仓库。该脚本只解析test result:行存在的 cargo lane 日志，并强制要求--test-threads=1——若发现并行输出交错会以状态码 2 失败关闭（InterleavedOutputError）。

密钥与账号材料

• 公开 live LLM lane 的密钥与变量（LIVE_ANTHROPIC_API_KEY、LIVE_OPENAI_COMPATIBLE_API_KEY、LIVE_OPENAI_COMPATIBLE_BASE_URL及 model 变量等）详见 docs/internal/live-canary.md，其中还给出了各 lane 的触发频率与阻塞性对照表；
• seeded auth live provider 凭据：见 scripts/live-canary/ACCOUNTS.md。

两种 live-provider 运行模型

• auth-live-seeded：启动全新本地 IronClaw 实例并把已知良好凭据播种进干净数据库。适合每小时或频繁 live 检查、refresh-token 覆盖、稳定 provider 运行时探针。Google 的 access token 会在网关启动前由 runner 侧先刷新（_preflight_refresh_google_token），保证 CI 存储的旧 token 播种时是新鲜的；
• auth-browser-consent：以零 provider token 启动，在 Playwright 中打开真实 provider OAuth 流程、完成浏览器 consent，然后同时验证浏览器聊天与/v1/responses。适合每晚或发布前检查、redirect URI 与 consent UI 校验、provider 登录/consent 漂移检测。

操作规则

• 仅使用专用测试账号，绝不复用个人或生产账号；
• 每个集成尽量只保留一个 provider 账号/workspace；
• 保持 scope 狭窄、fixture 可丢弃、偏好只读或低风险探针；
• 每个 provider 保持一个稳定 fixture，便于失败归类（Gmail 一个含可读消息的收件箱、Calendar 一个含即将到来事件的日历、GitHub 一个含稳定 issue 的专用仓库、Notion 一个含可搜索页面的测试 workspace）。

关键 secrets 一览

Seeded lane（由scripts/auth_live_canary/run_live_canary.py读取）：

注意：Notion 声明 OAuth/DCR 设置，不能通过通用 setup API 接受 seeded token（auth_registry.py 会直接报错），必须走--mode browser --case notion。

Browser-consent lane：

• 首选 Playwright storage-state JSON 文件（更稳定）：AUTH_BROWSER_GOOGLE_STORAGE_STATE_PATH、AUTH_BROWSER_GITHUB_STORAGE_STATE_PATH、AUTH_BROWSER_NOTION_STORAGE_STATE_PATH；
• 回退用户名/密码 env（最后手段）：AUTH_BROWSER_GOOGLE_USERNAME/PASSWORD等；
• Google 还需要GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET；Notion 依赖 provider 侧 OAuth 元数据，无需单独 client env。

GitHub 不支持浏览器 consent：github WASM 工具注册为auth_summary.method = "manual"（PAT 粘贴，而非 OAuth），browser 探针无事可驱动，因此 GitHub 覆盖放在auth-live-seeded（直接播种AUTH_LIVE_GITHUB_TOKEN）。仅当 github 工具上线 OAuth 流程后才应重新加入 browser 段。

捕获 Playwright storage state

从仓库根目录执行（以 Google 为例）：

cd tests/e2e . .venv/bin/activate python - <<'PY' import asyncio from pathlib import Path from playwright.async_api import async_playwright TARGET_URL = "https://accounts.google.com/" OUTPUT = Path("google-storage-state.json").resolve() async def main(): async with async_playwright() as p: browser = await p.chromium.launch(headless=False) context = await browser.new_context() page = await context.new_page() await page.goto(TARGET_URL) print(f"Log in manually, then press Enter to save {OUTPUT}") input() await context.storage_state(path=str(OUTPUT)) await browser.close() asyncio.run(main()) PY

provider 登录 URL：Googlehttps://accounts.google.com/、Notionhttps://www.notion.so/login。CI 中把 storage-state 文件 base64 编码后存入 secret：

# Linux base64 -w0 tests/e2e/google-storage-state.json # macOS base64 < tests/e2e/google-storage-state.json | tr -d '\n'

对应 secret 名AUTH_BROWSER_GOOGLE_STORAGE_STATE_B64、AUTH_BROWSER_NOTION_STORAGE_STATE_B64；workflow 解码为临时文件并导出*_STORAGE_STATE_PATH后调用 runner。

Reborn WebUI v2 lane 的特殊账号要求

• 本地拷贝 home 必须包含根config.toml或local-dev/reborn-local-dev.db；若拷贝 DB 存有加密 provider 密钥，还需一并拷贝local-dev/.reborn-local-dev-secrets-master-key，否则能看 metadata 却无法解密 Slack token 或 Google product-auth refresh 密钥；
• 无拷贝 home 时可由 CI 密钥生成临时 home，Google product-auth 可从GOOGLE_OAUTH_CLIENT_ID/SECRET与AUTH_LIVE_GOOGLE_ACCESS/REFRESH_TOKEN播种。CI 在 Reborn shard fan-out 前先校验一次 refresh token，每个含 Google case 的 shard 再自行兑换并写入私有 runner 临时目录；AUTH_LIVE_GOOGLE_ACCESS_TOKEN仅作本地回退，access token 永不经过 job outputs 或上传构件；
• 预检失败形态可从preflight.json读取：reborn_secret_master_key_missing（缺 master key）、invalid_client/unauthorized_client（client secret 与存储 client ID 不匹配）、Google OAuth refresh probe failed: invalid_grant（refresh token 对当前 OAuth client 无效，需重新授权并成对轮换AUTH_LIVE_GOOGLE_ACCESS_TOKEN/AUTH_LIVE_GOOGLE_REFRESH_TOKEN）；
• Slack 工作流 case 需要 bot 级凭据：IRONCLAW_REBORN_SLACK_SIGNING_SECRET、IRONCLAW_REBORN_SLACK_BOT_TOKEN、REBORN_WEBUI_V2_LIVE_QA_SLACK_ROUTE_USER_ID（个人 DM 投递目标）；SLACK_WEBHOOK_URL仅用于 canary 上报，不足以覆盖 WebUI Slack 工作流；
• Telegram 工作流 case 需要真实测试 bot token：TELEGRAM_BOT_TOKEN或LIVE_CANARY_TELEGRAM_BOT_TOKEN（必要时还有TELEGRAM_WEBHOOK_SECRET与REBORN_WEBUI_V2_LIVE_QA_TELEGRAM_CHAT_ID）；
• 只有 Slack、Google、Telegram 凭据全部就位后才应使用CASES=all，否则 runner 会把受影响 case 记为凭据门并非零退出。

本地设置与失败分类

seeded 与 browser-consent lane 共用一份配置文件与同一个 runner，仅以--mode区分：

cd scripts/auth_live_canary cp config.example.env config.env set -a && source config.env && set +a cd ../.. # 列出 seeded cases: python3 scripts/auth_live_canary/run_live_canary.py --mode seeded --list-cases # 列出 browser cases: python3 scripts/auth_live_canary/run_live_canary.py --mode browser --list-cases

失败先分类：credential failure（token 被吊销、scope 缺失、账号禁用）→provider failure（配额、限流、consent UI 变更、策略变更）→IronClaw failure（密钥持久化、刷新、扩展激活、鉴权注入、回调处理）。首先检查artifacts/live-canary/<lane>/<provider>/<timestamp>/results.json、workflow 日志、browser-consent 失败的截图，并确认测试账号还能直接执行小型 fixture 操作。

轮换凭据的标准流程：为专用测试账号铸造/捕获替换凭据 → 更新对应 GitHub Actions secrets → 手动只跑受影响的 lane 与 provider → 确认浏览器与/v1/responses验证再次通过。

GitHub Workflow 集成

GitHub Actions 使用 .github/workflows/live-canary.yml 作为唯一的定时与手动入口，同时包含上游 live LLM jobs 与 auth 专属 canary jobs。run.sh的finish钩子会在每次运行结束统一记录 trace 状态、写 summary、生成 results.json 并退出；PR 定向运行需通过reborn-live-canary-prenvironment gate 与 head commit 的 approving review。

从 docs/internal/live-canary.md 的 lane 对照表看：public-smoke、persona-rotating、reborn-webui-v2-live-qa定时失败会开 issue；release-public-full与upgrade-canary是发布清单 gate；auth-*lanes 均为非阻塞（每小时/每晚/手动）。上传前所有 lane 都经过 scrub-artifacts.sh 清洗，private OAuth lane 应继续避免上传原始 OAuth 日志。

升级 canary 的原理

upgrade-canary.sh 验证"上一发布版本创建的数据库能否被当前 checkout 打开并使用"：它用git worktree add --detach分别检出PREVIOUS_REF（默认取最近 tag）与CURRENT_REF（默认HEAD），两个 worktree 各自cargo build，然后用统一环境（DATABASE_BACKEND=libsql、LIBSQL_PATH=<db>、LLM_BACKEND=openai_compatible、占位模型与密钥）跑config_round_trip集成测试；当前 checkout 额外跑workspace_integration。这是发布前/手动 lane，不是 PR gate。注意该脚本内部使用rm -f "${DB_PATH}"与git worktree remove --force做清理，仅服务于其自身临时工作区。

扩展新 provider 的标准路径

在新增鉴权 provider 时，遵循共享框架而不是新起 runner：

1. 在 auth_registry.py 的SEEDED_CASES或BROWSER_CASES注册表中添加 case 条目（含扩展安装名、期望显示名、探针 prompt、期望工具名、期望文本、shared secret 名、是否requires_refresh_seed等）；
2. 复用 common.py 与 auth_runtime.py 的共享 setup/runtime helpers（扩展生命周期等待、OAuth start/callback、账号选择、/v1/responses探针）；
3. 在 ACCOUNTS.md 中记录所需账号材料，并把密钥加入 live-canary.yml 的 repo-scope secrets。

生命周期类 case（gmail_roundtrip、google_calendar_lifecycle、notion_search_lifecycle）会执行真实 provider 写操作（发邮件、建日历事件等），虽是自清理（create → verify → delete），但反复每小时跑并不符合"低风险/只读"定位，因此被排除在定时 lane 默认选择之外，必须显式CASES=gmail_roundtrip或--case指定才执行（见 auth_registry.py 的LIFECYCLE_CASE_NAMES与configured_seeded_cases）。

这套体系的价值在于：它让"真实 LLM + 真实 provider + 真实浏览器"的回归具备可重复、可审计、密钥安全的运行形态——任何一次 provider 侧改动（OAuth 页面改版、scope 策略收紧、token 生命周期变化）都会在 lane 结果中留下可分类的失败痕迹，而不会把凭据泄漏进构件仓库。

• 人工智能
• AI 应用
• 交互助手
• AI Agent