如何基于 vault 的稳定退出码与 --json 输出脚本化 StaffML 题库的构建与校验流程【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book如果你的目标是把 StaffML 题库question vault的「校验 构建」做成 CI 或本地可重复执行的脚本核心难点是如何区分「题库数据坏了」和「命令敲错了」以及如何拿到结构化的失败明细而不是去解析终端彩色的 rich 输出。cs249r_book 仓库中的interviews/vault-cli包vault命令行正是为此设计的其退出码分类跨版本稳定永不重排编号所有子命令支持--json输出统一信封envelope格式机器可以直接判断成败并提取错误列表。本文基于 interviews/vault-cli/docs/EXIT_CODES.md、interviews/vault-cli/docs/JSON_OUTPUT.md 和 interviews/vault-cli/README.md 的正文内容给出一条「vault check把关 →vault build出 SQLite → JSON 字段做断言」的连续操作路径。适用前提仓库根目录下存在interviews/vault/题库目录本仓库已包含questions/下有数千个 YAML 题面文件Python 版本 ≥ 3.12pyproject.toml 中requires-python 3.12README 说明 CI 固定使用 3.12 以保证 hash 稳定。退出码契约脚本分支的依据vault的退出码定义在 src/vault_cli/exit_codes.pyExitCodeIntEnum文档明确「Codes are STABLE across releases. Never renumber. Scripts pin to these.」即可以安全地按编号写脚本分支退出码符号含义典型原因0SUCCESS命令成功完成正常路径1VALIDATION_FAILURE数据不变量、schema 规则或完整性检查失败YAML 坏文件、内容 hash 不匹配、registry 不一致2USAGE_ERROR命令调用本身非法缺参数、未知 flag、冲突 flag由 Typer/Click 触发3IO_ERROR文件系统或本地 I/O 失败权限不足、磁盘满、预期文件缺失4NETWORK_ERROR对 D1、Cloudflare、LLM API 等外部服务的网络调用失败D1 不可达、超时、上游 5xx5USER_ABORTED交互式确认被拒绝或确认中 Ctrl-C用户在vault rm --hard上输入n64–78—预留sysexits.h标准码仅在上述都不适用时使用文档特别指出几个区分点对脚本的意义1 与 2 的区分决定下一步动作1 表示「数据坏了去 git 里修」2 表示「命令写错了重读 --help」5 单独存在是为了脚本不把「用户取消」误判为 bug。对本文主路径checkbuild纯本地操作而言实际会遇到的就是 0、1、2、3 四类4 主要出现在deploy、ship等联网命令。--json 信封统一的成功/失败结构所有支持--json的子命令共用同一外层信封见 JSON_OUTPUT.md{ ok: true, exit_code: 0, exit_symbol: SUCCESS, command: vault subcommand, cli_version: 0.1.0, data: { }, errors: [], warnings: [] }成功时oktrue、errors[]、data有值失败时okfalse、errors有值、data可能只部分填充即使失败stderr 退出码仍然正确同时 stdout 输出上面的 JSON例如失败时{ok: false, exit_code: 1, exit_symbol: VALIDATION_FAILURE, errors: [...]}。信封的字段契约是版本化的重命名ok/exit_code/data属于 CLI major 版本变更data内新增字段属于 minor 变更。也就是说脚本可以放心依赖这三个顶层字段不必假设data内部结构永不变。errors数组的具体形状按命令而异。以vault check --json为例JSON_OUTPUT.md 给出的是LSP 诊断形状文档示例{ ok: false, exit_code: 1, exit_symbol: VALIDATION_FAILURE, command: vault check, data: { checks_run: 26, checks_passed: 24, checks_failed: 2, tier: structural }, errors: [ { uri: file:///.../questions/cloud/l4/diagnosis/foo-7f3a9c-0001.yaml, severity: 1, code: topic-not-in-taxonomy, source: vault-check, message: topic kv-cachee not found in taxonomy.yaml; did you mean kv-cache-management? } ] }上面的数字26 项检查、2 项失败只是文档示例你的题库实际数值会不同。从当前代码 src/vault_cli/commands/check.py 可以确认errors每项至少包含uriYAML 文件路径、severity1ErrorLSP 规范、code、source、message脚本只需遍历这些字段即可打印可定位的错误清单。vault check --strict --json的data字段则由loaded成功加载的题目数、load_errorsYAML 加载/Schema 错误数、invariant_failures不变量失败数组成全部为 0 时退出码为 0。主路径check 把门、build 出库的脚本两个命令的签名来自 README 与 check.py、build.py 源码vault check [--vault-dir PATH] [--strict] [--tier fast|structural|all] [--json]默认--vault-dir为interviews/vault--strict同时跑 fast structural 两个 tierCI 默认通过时退出 0、任何失败退出 1。--tier slow是 nightly 用的 LSH 场景去重本文主路径不涉及。vault build [--vault-dir PATH] [--output|-o PATH] [--release-id ID] [--json]把vault/questions/下的 YAML 编译为 SQLite默认输出interviews/vault/vault.db默认--release-id为dev。注意一个边界vault build对加载错误是容忍式的——有坏 YAML 时只打 warning、跳过这些记录继续构建只有「一个题目都没加载出来」才以退出码 1 中止。所以校验必须在 build 之前由vault check独立完成不能指望 build 替你把关。下面是把两者串起来的完整脚本#!/usr/bin/env bash # 前提仓库根目录执行依赖 jq自行安装。 set -uo pipefail # ---- 第 1 步校验题库CI 默认 strict 档---- check_out$(vault check --strict --json 21) rc$? case $rc in 0) echo check: PASS ;; 1) echo check: FAIL — 数据问题YAML/schema/registry需在 git 中修复 echo $check_out | jq -r .errors[] | \(.uri)\t\(.code)\t\(.message) ;; 2) echo check: USAGE_ERROR — 命令参数写错重读 vault check --help ;; 3) echo check: IO_ERROR — 检查文件系统权限/磁盘/路径 ;; 4) echo check: NETWORK_ERROR — 外部服务不可达check 本身通常不涉及网络 ;; 5) echo check: USER_ABORTED — 交互确认被取消 ;; *) echo check: 未知退出码 $rc ;; esac if [ $rc -ne 0 ]; then exit $rc fi # ---- 第 2 步构建 vault.db ---- build_out$(vault build --release-id dev --json) rc$? case $rc in 0) echo build: PASS # 断言ok 必须为 true并提取发布戳信息 echo $build_out | jq -e .ok true /dev/null || { echo build: ok 字段异常; exit 1; } echo $build_out | jq -r release_id\(.data.release_id) release_hash\(.data.release_hash) published\(.data.published_count) ;; 1) echo build: VALIDATION_FAILURE如一道题都没加载出来 ;; *) echo build: 退出码 $rc ;; esac exit $rc脚本里每一步的判断依据case分支直接映射 EXIT_CODES.md 的表由于编号稳定这段分支可以跨版本复用。jq -e .ok true是对信封契约而不是具体数值的断言成功时ok必为 true 且errors为空。build成功路径的data字段包含outputvault.db 路径、release_id、release_hash64 位 hex、published_count、policy_versionJSON_OUTPUT.md 的vault build --json条目其中具体数字为文档示例。如果只想在本地前端联调让interviews/staffml的 dev server 直接渲染本地题目可选分支是vault build --local它额外把corpus.json写到interviews/staffml/src/data/corpus.json并镜像到interviews/staffml/public/data/corpus.jsonNext.js 加载器实际取用的静态路径同时镜像题目配图到public/question-visuals/。这是 dev-only 产物生产构建不读这两个文件build.py 的--local-json说明。副作用是会覆盖这些前端目录下的对应文件仅在跑本地开发时执行。验证结果确认构建产物与题库一致主路径跑完check 退出 0、build 输出oktrue后验证方式分两层直接断言vault.db已写到默认路径interviews/vault/vault.db或你--output指定的路径且 build 的 JSON 中data.output指向它。build 命令内部还有一道自校验写入前端 manifestinterviews/staffml/src/data/vault-manifest.json前会核对生成数量与 release policy 过滤后的题量是否一致不一致即以退出码 1 中止——所以oktrue意味着这道校验也已通过。文档声明的发布期校验可选属于发布流水线见 READMEvault verify release-id [--git-ref tag]做「学术可引用性」round-trip其--json输出含expected_hash、computed_hash、leaves_verified、match字段JSON_OUTPUT.md 示例为文档示例值match: false时退出码为 1且errors列出前 10 个不一致的叶子。vault stats --json则输出题库的题量、topic 数、chain 数、按 track/level 的分布适合写进发布记录。限制与排错边界--json-schema命令JSON_OUTPUT.md 提到vault sub --json-schema可打印某命令的完整 JSON schema但当前 src/vault_cli/ 源码中尚未实现该参数全仓库检索不到。文档与代码存在版本差异本文主路径不依赖它如需确认字段以 check.py / build.py 实际输出的 JSON 为准。vault serve与vault api不支持--json前者启动 Datasette、后者是常驻 HTTP 服务不是 JSON 输出命令JSON_OUTPUT.md 明确标注 Not applicable脚本化流程里不要对它们做信封断言。退出码 5 的陷阱如果 CI 中某个带交互确认的命令挂起等待确认后被超时杀掉会得到可区分的 5USER_ABORTED而非一般失败脚本不应把它计入「数据坏了」。本文的 check/build 流程无交互不涉及此项。失败时data可能只部分填充脚本对失败分支只应读errors不要假设data完整。--tier slow不要放进日常 CI它是 nightly 级别的 LSH 场景去重README成本与用途都不同于--strict。本地测试套件开发 vault-cli 本身时才需要pip install -e interviews/vault-cli/[dev]后pytest interviews/vault-cli/tests/README「Run tests」节。下一步脚本化流程跑稳之后仓库文档给出的延伸路径是完整发布流水线vault snapshot ver→vault migrations-emit from to→vault publish ver→vault verify ver均支持--jsonschema 见 JSON_OUTPUT.md以及链式题序chains的构建脚本 scripts/ 五步流程diagnose_chain_coverage.py→build_chains_with_gemini.py→apply_proposed_chains.py→merge_chain_passes.py改动后需重跑vault check --strict与vault build --local-json。这些属于独立任务本文不展开本文的 check→build 脚本即可作为它们的前置质量门复用。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
