openlogos smoke
openlogos smoke 用来验证部署后的健康状况:从 JSONL 文件读取 smoke 结果,与 logos/resources/test/smoke/ 中定义的 smoke 用例 ID 对比,并生成 smoke 报告。这是 Gate 3.8 质量检查。应在部署执行完成、并用 openlogos deploy-done(Gate 3.7)记录之后运行。
openlogos smoke [--env <name>] [--format json]在项目根目录下运行。
| 选项 | 说明 |
|---|---|
--env <name> | 本次验证的环境,例如 staging、production。没有登记表时只是本次运行与报告的自由标签;存在 logos/environments.yaml 时必须是已登记的 id 或别名,且必填(见环境证据)。 |
--format json | 输出机器可读的 JSON 信封(包含 sandbox 诊断信息)。 |
存在活跃变更提案时,smoke 会先检查提案的生命周期状态。检查按顺序进行,命中第一个即停止,并且发生在读取配置、执行 smoke.command、改动结果文件之前:
| 错误码 | 含义 | 处理 |
|---|---|---|
SMOKE_NOT_REQUIRED | 当前提案不需要 smoke | verify 通过后直接归档 |
SMOKE_DEPLOY_DECISION_CONFLICT | proposal.md 与 tasks.md 的部署决策不一致 | 先修正部署决策 |
SMOKE_DEPLOY_NOT_DONE | 缺少 DEPLOY_DONE | 完成部署后运行 openlogos deploy-done |
SMOKE_DEPLOY_TASKS_INCOMPLETE | [deploy] 仍有未勾选条目 | 补齐 [deploy] 任务后运行 openlogos deploy-done |
SMOKE_DEPLOY_MARKER_INVALID | DEPLOY_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、不写账本。
- 读取
logos/logos.config.json中的 smoke 配置(smoke.command、smoke.result_path、smoke.report_path)。未配置smoke.command但存在scripts/run-smoke.js时,使用node scripts/run-smoke.js。 - 有 smoke 命令时,先清空结果文件再执行命令(可选沙箱)。因此上一次部署留下的结果不会被当成本次的证据。命令非零退出时,smoke 给出告警,并按命令实际写出的结果继续判定。
- 从
logos/resources/verify/smoke-results.jsonl(或配置的路径)读取 smoke 结果。 - 扫描
logos/resources/test/smoke/*.md,从表格行首列读取已定义的 smoke 用例 ID(如SMOKE-releases-01)。 - 活跃提案新增或修改了
SMOKE-*用例时,执行 smoke 覆盖预检:runner 是否可达(smoke_runner_missing)、是否写出了结果(smoke_reporter_missing)、每个变更 ID 是否都有结果(smoke_cases_uncovered)。 - 计算 Gate 3.8、生成报告,并向活跃提案写入
SMOKE_PASS/SMOKE_FAIL。
smoke 配置
Section titled “smoke 配置”{ "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_path | logos/resources/verify/smoke-results.jsonl | smoke 结果 JSONL 路径 |
report_path | logos/resources/verify/smoke-report.md | 生成的报告路径 |
sandbox_mode | auto | 沙箱隔离模式(off / auto / always) |
沙箱执行器与 openlogos verify 共享:完整路径段严格等于 node_modules 的写入不参与写入审计,通过 sandbox.infos 输出说明,不影响 sandbox.status;白名单结果文件即使位于 node_modules 下也照常回收;symlink 隔离与 OS 级运行期写保护同样适用。写保护不可用时,always 失败,auto 告警。
Gate 3.8 通过标准
Section titled “Gate 3.8 通过标准”以下各项必须全部满足:
| 条件 | 说明 |
|---|---|
| 零失败用例 | 没有任何 smoke 结果的 status 为 "fail" |
| 100% 覆盖率 | 每个已定义的 smoke ID 都有结果 |
| 预检无诊断 | 本提案变更用例的 smoke 覆盖预检没有诊断项 |
| 必要用例未被 skip | 本提案新增或修改的 smoke 用例没有以 skip 结束(平台不可执行例外见下文) |
沙箱失败同样判 FAIL。任一条件不满足时,命令以退出码 1 退出。
必要用例的 skip
Section titled “必要用例的 skip”本提案新增或修改的 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。
smoke 结果格式(JSONL)
Section titled “smoke 结果格式(JSONL)”{"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 | 失败时的错误信息 |
detail | skip 时必填 | string | 跳过的原因 |
reason_code | 否 | platform-unavailable | 门禁唯一识别的原因码 |
duration_ms | 否 | number | 执行时长 |
timestamp | 否 | ISO 8601 | 运行时间 |
target_environment | 否 | 环境 id | runner 实际验证的环境(见下文)。既有字段 environment 仍是 runner 自定义的执行环境标签,不参与该判定 |
项目存在 logos/environments.yaml 登记表(见环境登记表)且传入 --env 时:
-
--env解析为环境 id(先匹配 id,再匹配别名,不区分大小写)。 -
以环境变量
OPENLOGOS_SMOKE_ENV=<id>运行smoke.command(沙箱内同样注入)。runner 应读取它,并在自己产生的每条结果行写回target_environment。 -
smoke 对计入门禁的结果行分类:
env_evidence条件 影响 declared每一行都有 target_environment且等于本次环境可以判为已验证 missing有行缺少 target_environment,或没有任何结果行门禁照旧计算(兼容旧 runner),但 verified=falsemismatch有行声明了其他环境 门禁 FAIL, gate.reason: "SMOKE_ENV_EVIDENCE_MISMATCH" -
向部署账本
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 行为与以前一致。
提案生命周期集成
Section titled “提案生命周期集成”存在活跃变更提案时,smoke 会写入标记:
| 门禁结果 | 标记 |
|---|---|
| PASS | 写 logos/changes/<slug>/SMOKE_PASS,删除 SMOKE_FAIL |
| FAIL | 写 logos/changes/<slug>/SMOKE_FAIL,删除 SMOKE_PASS |
SMOKE_PASS 后提案可以归档;SMOKE_FAIL 后修复部署问题再重跑 smoke。
输出示例(通过)
Section titled “输出示例(通过)”⚙️ 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输出示例(失败)
Section titled “输出示例(失败)”🔎 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.mdJSON 输出
Section titled “JSON 输出”使用 --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}],阻断门禁的必要用例 skipplatform_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) |