跳转到内容

openlogos smoke

openlogos smoke 用来验证部署后的健康状况:从 JSONL 文件读取 smoke 结果,与 logos/resources/test/smoke/ 中定义的 smoke 用例 ID 对比,并生成 smoke 报告。这是 Gate 3.8 质量检查。应在部署执行完成、并用 openlogos deploy-done(Gate 3.7)记录之后运行。

Terminal window
openlogos smoke [--env <name>] [--format json]

在项目根目录下运行。

选项说明
--env <name>本次验证的环境,例如 staging、production。没有登记表时只是本次运行与报告的自由标签;存在 logos/environments.yaml 时必须是已登记的 id 或别名,且必填(见环境证据)。
--format json输出机器可读的 JSON 信封(包含 sandbox 诊断信息)。

存在活跃变更提案时,smoke 会先检查提案的生命周期状态。检查按顺序进行,命中第一个即停止,并且发生在读取配置、执行 smoke.command、改动结果文件之前:

错误码含义处理
SMOKE_NOT_REQUIRED当前提案不需要 smokeverify 通过后直接归档
SMOKE_DEPLOY_DECISION_CONFLICTproposal.md 与 tasks.md 的部署决策不一致先修正部署决策
SMOKE_DEPLOY_NOT_DONE缺少 DEPLOY_DONE完成部署后运行 openlogos deploy-done
SMOKE_DEPLOY_TASKS_INCOMPLETE[deploy] 仍有未勾选条目补齐 [deploy] 任务后运行 openlogos deploy-done
SMOKE_DEPLOY_MARKER_INVALIDDEPLOY_DONE 非空但不是合法记录,或无法读取(error.details.problems 点名问题字段)重新执行 openlogos deploy-done --env <id> [--ref <revision>] 重写
SMOKE_ENV_MISMATCH有登记表,且 DEPLOY_DONE 记录的环境与 --env 不一致对实际部署的环境执行 smoke
SMOKE_DEPLOY_SUPERSEDED有登记表,且提案落标之后该环境又被部署过(账本中该环境最近一次部署不是 DEPLOY_DONE 记录的那一次)在提案通道重新部署后再 smoke

有登记表时还会先检查 ENV_REGISTRY_INVALID、ENV_REQUIRED、ENV_UNKNOWN。以上拒绝都不运行 smoke.command、不写 smoke marker、不写账本。

  1. 读取 logos/logos.config.json 中的 smoke 配置(smoke.command、smoke.result_path、smoke.report_path)。未配置 smoke.command 但存在 scripts/run-smoke.js 时,使用 node scripts/run-smoke.js。
  2. 有 smoke 命令时,先清空结果文件再执行命令(可选沙箱)。因此上一次部署留下的结果不会被当成本次的证据。命令非零退出时,smoke 给出告警,并按命令实际写出的结果继续判定。
  3. 从 logos/resources/verify/smoke-results.jsonl(或配置的路径)读取 smoke 结果。
  4. 扫描 logos/resources/test/smoke/*.md,从表格行首列读取已定义的 smoke 用例 ID(如 SMOKE-releases-01)。
  5. 活跃提案新增或修改了 SMOKE-* 用例时,执行 smoke 覆盖预检:runner 是否可达(smoke_runner_missing)、是否写出了结果(smoke_reporter_missing)、每个变更 ID 是否都有结果(smoke_cases_uncovered)。
  6. 计算 Gate 3.8、生成报告,并向活跃提案写入 SMOKE_PASS / SMOKE_FAIL。
{
"smoke": {
"command": "node scripts/run-smoke.js",
"result_path": "logos/resources/verify/smoke-results.jsonl",
"report_path": "logos/resources/verify/smoke-report.md",
"sandbox_mode": "auto",
"sandbox_root": "/private/tmp",
"sandbox_deny_workspace_write": true
}
}
字段默认值说明
command存在 scripts/run-smoke.js 时为 node scripts/run-smoke.js,否则无运行 smoke 测试并把结果写入 result_path 的 shell 命令
result_pathlogos/resources/verify/smoke-results.jsonlsmoke 结果 JSONL 路径
report_pathlogos/resources/verify/smoke-report.md生成的报告路径
sandbox_modeauto沙箱隔离模式(off / auto / always)

沙箱执行器与 openlogos verify 共享:完整路径段严格等于 node_modules 的写入不参与写入审计,通过 sandbox.infos 输出说明,不影响 sandbox.status;白名单结果文件即使位于 node_modules 下也照常回收;symlink 隔离与 OS 级运行期写保护同样适用。写保护不可用时,always 失败,auto 告警。

以下各项必须全部满足:

条件说明
零失败用例没有任何 smoke 结果的 status 为 "fail"
100% 覆盖率每个已定义的 smoke ID 都有结果
预检无诊断本提案变更用例的 smoke 覆盖预检没有诊断项
必要用例未被 skip本提案新增或修改的 smoke 用例没有以 skip 结束(平台不可执行例外见下文)

沙箱失败同样判 FAIL。任一条件不满足时,命令以退出码 1 退出。

本提案新增或修改的 smoke 用例,是这次部署的必要证据。skip 只说明没有取得证据,因此这类 skip 默认拦截(gate.reason: "required_cases_skipped"),报告中列在「Required Cases Without Evidence」一节。

例外只有一种:用例在当前平台上确实无法执行。这时 runner 以 reason_code: "platform-unavailable" 写 skip,并在 detail 中写明原因(不能为空),这类 skip 会被放行。它在报告中单独列为「Platform-Unavailable Skips」,在 JSON 中列入 platform_skipped_cases,以便审计。缺原因码、使用其他原因码或 detail 为空的 skip,仍按缺少必要证据处理。

不属于本提案变更范围的 smoke 用例,其 skip 口径不变(计入已执行,不计入失败或未覆盖),单独不会导致 FAIL。

{"id":"SMOKE-releases-01","status":"pass","duration_ms":1200,"timestamp":"2026-05-28T10:00:00Z"}
{"id":"SMOKE-releases-02","status":"fail","error":"Expected 200, got 404","duration_ms":500}
{"id":"SMOKE-cli-install-03","status":"skip","reason_code":"platform-unavailable","detail":"Windows-only installer check; current runner is Linux"}
字段必填取值说明
id是SMOKE-<领域>-<序号>与规格中定义一致的 smoke 用例 ID
status是pass、fail、skip结果
error否string失败时的错误信息
detailskip 时必填string跳过的原因
reason_code否platform-unavailable门禁唯一识别的原因码
duration_ms否number执行时长
timestamp否ISO 8601运行时间
target_environment否环境 idrunner 实际验证的环境(见下文)。既有字段 environment 仍是 runner 自定义的执行环境标签,不参与该判定

项目存在 logos/environments.yaml 登记表(见环境登记表)且传入 --env 时:

  1. --env 解析为环境 id(先匹配 id,再匹配别名,不区分大小写)。

  2. 以环境变量 OPENLOGOS_SMOKE_ENV=<id> 运行 smoke.command(沙箱内同样注入)。runner 应读取它,并在自己产生的每条结果行写回 target_environment。

  3. smoke 对计入门禁的结果行分类:

    env_evidence条件影响
    declared每一行都有 target_environment 且等于本次环境可以判为已验证
    missing有行缺少 target_environment,或没有任何结果行门禁照旧计算(兼容旧 runner),但 verified=false
    mismatch有行声明了其他环境门禁 FAIL,gate.reason: "SMOKE_ENV_EVIDENCE_MISMATCH"
  4. 向部署账本 logos/.openlogos-runtime/deployments.jsonl 追加一条 smoke 记录。只有同时满足门禁通过、env_evidence 为 declared、结果由本次运行产生(fresh_results)、部署环境已确认、部署版本已知时,记录才是已验证(verified=true)。晋级检查(promote_from)与 env 中的「最近 smoke」只认已验证的记录。

先写账本、后写 smoke marker;任一步失败时两者一起恢复,并以 SMOKE_LEDGER_WRITE_FAILED 结束。

部署执行已启用(有环境配置了 deploy)时,smoke 还会核对部署身份:有活跃提案时,DEPLOY_DONE 必须是账本中该环境最近一次部署(否则 SMOKE_DEPLOY_SUPERSEDED);没有活跃提案时,部署身份取自账本,smoke 结果照常记入账本。

没有登记表时,--env 仍只是普通标签,smoke 行为与以前一致。

存在活跃变更提案时,smoke 会写入标记:

门禁结果标记
PASS写 logos/changes/<slug>/SMOKE_PASS,删除 SMOKE_FAIL
FAIL写 logos/changes/<slug>/SMOKE_FAIL,删除 SMOKE_PASS

SMOKE_PASS 后提案可以归档;SMOKE_FAIL 后修复部署问题再重跑 smoke。

⚙️ Running smoke.command: node scripts/run-smoke.js
🔎 OpenLogos Smoke Verification
Environment: staging
Defined: 5
Executed: 5
Passed: 4
Failed: 0
Skipped: 1
Coverage: 100%
Pass rate: 100%
smoke 沙箱:mode=auto,status=pass,isolated=true,write_denied=true
Platform-unavailable smoke cases (skip accepted):
SMOKE-cli-install-03: Windows-only installer check; current runner is Linux
✅ Gate 3.8: PASS
📄 报告:logos/resources/verify/smoke-report.md
🔎 OpenLogos Smoke Verification
Defined: 5
Executed: 4
Passed: 2
Failed: 1
Skipped: 1
Coverage: 80%
Pass rate: 75%
Failed smoke cases:
SMOKE-releases-03 Expected 200, got 404
Uncovered smoke cases:
SMOKE-cli-install-02
Required smoke cases without evidence (skip):
SMOKE-releases-04: staging token not configured
❌ Gate 3.8: FAIL
📄 报告:logos/resources/verify/smoke-report.md

使用 --format json 时,data 包含 environment、summary、gate(result、reason)、failed_cases、uncovered_cases、skipped_cases、changed_cases、diagnostics、runners、sandbox、report_path、result_path。以下两个列表仅在非空时出现:

  • required_skipped_cases:[{id, detail}],阻断门禁的必要用例 skip
  • platform_skipped_cases:[{id, detail}],已放行的平台不可执行 skip

gate.reason 优先级:failed_cases → 预检诊断码 → required_cases_skipped → incomplete_coverage。详见 CLI JSON 输出。

有登记表时,data 还包含 environment_evidence:target、deploy_id、ref、deploy_env_confirmed、env_evidence、mismatched_case_ids、missing_case_ids、fresh_results、verified 与 ledger_written。

错误原因解决方法
logos/logos.config.json not found不在项目根目录cd 到项目根目录
SMOKE_* 前置错误码见 前置检查按该表处理
No smoke results found at ...(NO_SMOKE_RESULTS)结果文件不存在配置 smoke.command,或先运行 smoke runner
No smoke case specs found(NO_SMOKE_CASES)logos/resources/test/smoke/ 中没有 smoke ID先编写 smoke 用例规格(deployment-designer / test-writer)
  • verify:测试验收(Gate 3.6,部署前运行)
  • deploy-done:记录部署完成(Gate 3.7)
  • deploy / env:执行部署,查看各环境最近的部署与 smoke
  • status:在提案生命周期中显示 smoke 门状态
  • archive:smoke 通过后归档提案