定退出碼與 --json 輸出腳本化 StaffML 題庫的構(gòu)建與校驗流程)
如何基于 vault 的穩(wěn)定退出碼與 --json 輸出腳本化 StaffML 題庫的構(gòu)建與校驗流程【免費下載鏈接】cs249r_bookMachine Learning Systems項目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book如果你的目標是把 StaffML 題庫question vault的「校驗 構(gòu)建」做成 CI 或本地可重復執(zhí)行的腳本核心難點是如何區(qū)分「題庫數(shù)據(jù)壞了」和「命令敲錯了」以及如何拿到結(jié)構(gòu)化的失敗明細而不是去解析終端彩色的 rich 輸出。cs249r_book 倉庫中的interviews/vault-cli包vault命令行正是為此設(shè)計的其退出碼分類跨版本穩(wěn)定永不重排編號所有子命令支持--json輸出統(tǒng)一信封envelope格式機器可以直接判斷成敗并提取錯誤列表。本文基于 interviews/vault-cli/docs/EXIT_CODES.md、interviews/vault-cli/docs/JSON_OUTPUT.md 和 interviews/vault-cli/README.md 的正文內(nèi)容給出一條「vault check把關(guān) →vault build出 SQLite → JSON 字段做斷言」的連續(xù)操作路徑。適用前提倉庫根目錄下存在interviews/vault/題庫目錄本倉庫已包含questions/下有數(shù)千個 YAML 題面文件Python 版本 ≥ 3.12pyproject.toml 中requires-python 3.12README 說明 CI 固定使用 3.12 以保證 hash 穩(wěn)定。退出碼契約腳本分支的依據(jù)vault的退出碼定義在 src/vault_cli/exit_codes.pyExitCodeIntEnum文檔明確「Codes are STABLE across releases. Never renumber. Scripts pin to these.」即可以安全地按編號寫腳本分支退出碼符號含義典型原因0SUCCESS命令成功完成正常路徑1VALIDATION_FAILURE數(shù)據(jù)不變量、schema 規(guī)則或完整性檢查失敗YAML 壞文件、內(nèi)容 hash 不匹配、registry 不一致2USAGE_ERROR命令調(diào)用本身非法缺參數(shù)、未知 flag、沖突 flag由 Typer/Click 觸發(fā)3IO_ERROR文件系統(tǒng)或本地 I/O 失敗權(quán)限不足、磁盤滿、預期文件缺失4NETWORK_ERROR對 D1、Cloudflare、LLM API 等外部服務的網(wǎng)絡調(diào)用失敗D1 不可達、超時、上游 5xx5USER_ABORTED交互式確認被拒絕或確認中 Ctrl-C用戶在vault rm --hard上輸入n64–78—預留sysexits.h標準碼僅在上述都不適用時使用文檔特別指出幾個區(qū)分點對腳本的意義1 與 2 的區(qū)分決定下一步動作1 表示「數(shù)據(jù)壞了去 git 里修」2 表示「命令寫錯了重讀 --help」5 單獨存在是為了腳本不把「用戶取消」誤判為 bug。對本文主路徑checkbuild純本地操作而言實際會遇到的就是 0、1、2、3 四類4 主要出現(xiàn)在deploy、ship等聯(lián)網(wǎng)命令。--json 信封統(tǒng)一的成功/失敗結(jié)構(gòu)所有支持--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內(nèi)新增字段屬于 minor 變更。也就是說腳本可以放心依賴這三個頂層字段不必假設(shè)data內(nèi)部結(jié)構(gòu)永不變。errors數(shù)組的具體形狀按命令而異。以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? } ] }上面的數(shù)字26 項檢查、2 項失敗只是文檔示例你的題庫實際數(shù)值會不同。從當前代碼 src/vault_cli/commands/check.py 可以確認errors每項至少包含uriYAML 文件路徑、severity1ErrorLSP 規(guī)范、code、source、message腳本只需遍歷這些字段即可打印可定位的錯誤清單。vault check --strict --json的data字段則由loaded成功加載的題目數(shù)、load_errorsYAML 加載/Schema 錯誤數(shù)、invariant_failures不變量失敗數(shù)組成全部為 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、跳過這些記錄繼續(xù)構(gòu)建只有「一個題目都沒加載出來」才以退出碼 1 中止。所以校驗必須在 build 之前由vault check獨立完成不能指望 build 替你把關(guān)。下面是把兩者串起來的完整腳本#!/usr/bin/env bash # 前提倉庫根目錄執(zhí)行依賴 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 — 數(shù)據(jù)問題YAML/schema/registry需在 git 中修復 echo $check_out | jq -r .errors[] | \(.uri)\t\(.code)\t\(.message) ;; 2) echo check: USAGE_ERROR — 命令參數(shù)寫錯重讀 vault check --help ;; 3) echo check: IO_ERROR — 檢查文件系統(tǒng)權(quán)限/磁盤/路徑 ;; 4) echo check: NETWORK_ERROR — 外部服務不可達check 本身通常不涉及網(wǎng)絡 ;; 5) echo check: USER_ABORTED — 交互確認被取消 ;; *) echo check: 未知退出碼 $rc ;; esac if [ $rc -ne 0 ]; then exit $rc fi # ---- 第 2 步構(gòu)建 vault.db ---- build_out$(vault build --release-id dev --json) rc$? case $rc in 0) echo build: PASS # 斷言ok 必須為 true并提取發(fā)布戳信息 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腳本里每一步的判斷依據(jù)case分支直接映射 EXIT_CODES.md 的表由于編號穩(wěn)定這段分支可以跨版本復用。jq -e .ok true是對信封契約而不是具體數(shù)值的斷言成功時ok必為 true 且errors為空。build成功路徑的data字段包含outputvault.db 路徑、release_id、release_hash64 位 hex、published_count、policy_versionJSON_OUTPUT.md 的vault build --json條目其中具體數(shù)字為文檔示例。如果只想在本地前端聯(lián)調(diào)讓interviews/staffml的 dev server 直接渲染本地題目可選分支是vault build --local它額外把corpus.json寫到interviews/staffml/src/data/corpus.json并鏡像到interviews/staffml/public/data/corpus.jsonNext.js 加載器實際取用的靜態(tài)路徑同時鏡像題目配圖到public/question-visuals/。這是 dev-only 產(chǎn)物生產(chǎn)構(gòu)建不讀這兩個文件build.py 的--local-json說明。副作用是會覆蓋這些前端目錄下的對應文件僅在跑本地開發(fā)時執(zhí)行。驗證結(jié)果確認構(gòu)建產(chǎn)物與題庫一致主路徑跑完check 退出 0、build 輸出oktrue后驗證方式分兩層直接斷言vault.db已寫到默認路徑interviews/vault/vault.db或你--output指定的路徑且 build 的 JSON 中data.output指向它。build 命令內(nèi)部還有一道自校驗寫入前端 manifestinterviews/staffml/src/data/vault-manifest.json前會核對生成數(shù)量與 release policy 過濾后的題量是否一致不一致即以退出碼 1 中止——所以oktrue意味著這道校驗也已通過。文檔聲明的發(fā)布期校驗可選屬于發(fā)布流水線見 READMEvault verify release-id [--git-ref tag]做「學術(shù)可引用性」round-trip其--json輸出含expected_hash、computed_hash、leaves_verified、match字段JSON_OUTPUT.md 示例為文檔示例值match: false時退出碼為 1且errors列出前 10 個不一致的葉子。vault stats --json則輸出題庫的題量、topic 數(shù)、chain 數(shù)、按 track/level 的分布適合寫進發(fā)布記錄。限制與排錯邊界--json-schema命令JSON_OUTPUT.md 提到vault sub --json-schema可打印某命令的完整 JSON schema但當前 src/vault_cli/ 源碼中尚未實現(xiàn)該參數(shù)全倉庫檢索不到。文檔與代碼存在版本差異本文主路徑不依賴它如需確認字段以 check.py / build.py 實際輸出的 JSON 為準。vault serve與vault api不支持--json前者啟動 Datasette、后者是常駐 HTTP 服務不是 JSON 輸出命令JSON_OUTPUT.md 明確標注 Not applicable腳本化流程里不要對它們做信封斷言。退出碼 5 的陷阱如果 CI 中某個帶交互確認的命令掛起等待確認后被超時殺掉會得到可區(qū)分的 5USER_ABORTED而非一般失敗腳本不應把它計入「數(shù)據(jù)壞了」。本文的 check/build 流程無交互不涉及此項。失敗時data可能只部分填充腳本對失敗分支只應讀errors不要假設(shè)data完整。--tier slow不要放進日常 CI它是 nightly 級別的 LSH 場景去重README成本與用途都不同于--strict。本地測試套件開發(fā) vault-cli 本身時才需要pip install -e interviews/vault-cli/[dev]后pytest interviews/vault-cli/tests/README「Run tests」節(jié)。下一步腳本化流程跑穩(wěn)之后倉庫文檔給出的延伸路徑是完整發(fā)布流水線vault snapshot ver→vault migrations-emit from to→vault publish ver→vault verify ver均支持--jsonschema 見 JSON_OUTPUT.md以及鏈式題序chains的構(gòu)建腳本 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 腳本即可作為它們的前置質(zhì)量門復用。【免費下載鏈接】cs249r_bookMachine Learning Systems項目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 如何基于 vault 的穩(wěn)定退出碼與 --json 輸出腳本化 StaffML 題庫的構(gòu)建與校驗流程
如何基于 vault 的穩(wěn)定退出碼與 --json 輸出腳本化 StaffML 題庫的構(gòu)建與校驗流程【免費下載鏈接】cs249r_bookMachine Learning Systems項目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book如果你的目標是把 StaffML 題庫question vault的「校驗 構(gòu)建」做成 CI 或本地可重復執(zhí)行的腳本核心難點是如何區(qū)分「題庫數(shù)據(jù)壞了」和「命令敲錯了」以及如何拿到結(jié)構(gòu)化的失敗明細而不是去解析終端彩色的 rich 輸出。cs249r_book 倉庫中的interviews/vault-cli包vault命令行正是為此設(shè)計的其退出碼分類跨版本穩(wěn)定永不重排編號所有子命令支持--json輸出統(tǒng)一信封envelope格式機器可以直接判斷成敗并提取錯誤列表。本文基于 interviews/vault-cli/docs/EXIT_CODES.md、interviews/vault-cli/docs/JSON_OUTPUT.md 和 interviews/vault-cli/README.md 的正文內(nèi)容給出一條「vault check把關(guān) →vault build出 SQLite → JSON 字段做斷言」的連續(xù)操作路徑。適用前提倉庫根目錄下存在interviews/vault/題庫目錄本倉庫已包含questions/下有數(shù)千個 YAML 題面文件Python 版本 ≥ 3.12pyproject.toml 中requires-python 3.12README 說明 CI 固定使用 3.12 以保證 hash 穩(wěn)定。退出碼契約腳本分支的依據(jù)vault的退出碼定義在 src/vault_cli/exit_codes.pyExitCodeIntEnum文檔明確「Codes are STABLE across releases. Never renumber. Scripts pin to these.」即可以安全地按編號寫腳本分支退出碼符號含義典型原因0SUCCESS命令成功完成正常路徑1VALIDATION_FAILURE數(shù)據(jù)不變量、schema 規(guī)則或完整性檢查失敗YAML 壞文件、內(nèi)容 hash 不匹配、registry 不一致2USAGE_ERROR命令調(diào)用本身非法缺參數(shù)、未知 flag、沖突 flag由 Typer/Click 觸發(fā)3IO_ERROR文件系統(tǒng)或本地 I/O 失敗權(quán)限不足、磁盤滿、預期文件缺失4NETWORK_ERROR對 D1、Cloudflare、LLM API 等外部服務的網(wǎng)絡調(diào)用失敗D1 不可達、超時、上游 5xx5USER_ABORTED交互式確認被拒絕或確認中 Ctrl-C用戶在vault rm --hard上輸入n64–78—預留sysexits.h標準碼僅在上述都不適用時使用文檔特別指出幾個區(qū)分點對腳本的意義1 與 2 的區(qū)分決定下一步動作1 表示「數(shù)據(jù)壞了去 git 里修」2 表示「命令寫錯了重讀 --help」5 單獨存在是為了腳本不把「用戶取消」誤判為 bug。對本文主路徑checkbuild純本地操作而言實際會遇到的就是 0、1、2、3 四類4 主要出現(xiàn)在deploy、ship等聯(lián)網(wǎng)命令。--json 信封統(tǒng)一的成功/失敗結(jié)構(gòu)所有支持--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內(nèi)新增字段屬于 minor 變更。也就是說腳本可以放心依賴這三個頂層字段不必假設(shè)data內(nèi)部結(jié)構(gòu)永不變。errors數(shù)組的具體形狀按命令而異。以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? } ] }上面的數(shù)字26 項檢查、2 項失敗只是文檔示例你的題庫實際數(shù)值會不同。從當前代碼 src/vault_cli/commands/check.py 可以確認errors每項至少包含uriYAML 文件路徑、severity1ErrorLSP 規(guī)范、code、source、message腳本只需遍歷這些字段即可打印可定位的錯誤清單。vault check --strict --json的data字段則由loaded成功加載的題目數(shù)、load_errorsYAML 加載/Schema 錯誤數(shù)、invariant_failures不變量失敗數(shù)組成全部為 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、跳過這些記錄繼續(xù)構(gòu)建只有「一個題目都沒加載出來」才以退出碼 1 中止。所以校驗必須在 build 之前由vault check獨立完成不能指望 build 替你把關(guān)。下面是把兩者串起來的完整腳本#!/usr/bin/env bash # 前提倉庫根目錄執(zhí)行依賴 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 — 數(shù)據(jù)問題YAML/schema/registry需在 git 中修復 echo $check_out | jq -r .errors[] | \(.uri)\t\(.code)\t\(.message) ;; 2) echo check: USAGE_ERROR — 命令參數(shù)寫錯重讀 vault check --help ;; 3) echo check: IO_ERROR — 檢查文件系統(tǒng)權(quán)限/磁盤/路徑 ;; 4) echo check: NETWORK_ERROR — 外部服務不可達check 本身通常不涉及網(wǎng)絡 ;; 5) echo check: USER_ABORTED — 交互確認被取消 ;; *) echo check: 未知退出碼 $rc ;; esac if [ $rc -ne 0 ]; then exit $rc fi # ---- 第 2 步構(gòu)建 vault.db ---- build_out$(vault build --release-id dev --json) rc$? case $rc in 0) echo build: PASS # 斷言ok 必須為 true并提取發(fā)布戳信息 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腳本里每一步的判斷依據(jù)case分支直接映射 EXIT_CODES.md 的表由于編號穩(wěn)定這段分支可以跨版本復用。jq -e .ok true是對信封契約而不是具體數(shù)值的斷言成功時ok必為 true 且errors為空。build成功路徑的data字段包含outputvault.db 路徑、release_id、release_hash64 位 hex、published_count、policy_versionJSON_OUTPUT.md 的vault build --json條目其中具體數(shù)字為文檔示例。如果只想在本地前端聯(lián)調(diào)讓interviews/staffml的 dev server 直接渲染本地題目可選分支是vault build --local它額外把corpus.json寫到interviews/staffml/src/data/corpus.json并鏡像到interviews/staffml/public/data/corpus.jsonNext.js 加載器實際取用的靜態(tài)路徑同時鏡像題目配圖到public/question-visuals/。這是 dev-only 產(chǎn)物生產(chǎn)構(gòu)建不讀這兩個文件build.py 的--local-json說明。副作用是會覆蓋這些前端目錄下的對應文件僅在跑本地開發(fā)時執(zhí)行。驗證結(jié)果確認構(gòu)建產(chǎn)物與題庫一致主路徑跑完check 退出 0、build 輸出oktrue后驗證方式分兩層直接斷言vault.db已寫到默認路徑interviews/vault/vault.db或你--output指定的路徑且 build 的 JSON 中data.output指向它。build 命令內(nèi)部還有一道自校驗寫入前端 manifestinterviews/staffml/src/data/vault-manifest.json前會核對生成數(shù)量與 release policy 過濾后的題量是否一致不一致即以退出碼 1 中止——所以oktrue意味著這道校驗也已通過。文檔聲明的發(fā)布期校驗可選屬于發(fā)布流水線見 READMEvault verify release-id [--git-ref tag]做「學術(shù)可引用性」round-trip其--json輸出含expected_hash、computed_hash、leaves_verified、match字段JSON_OUTPUT.md 示例為文檔示例值match: false時退出碼為 1且errors列出前 10 個不一致的葉子。vault stats --json則輸出題庫的題量、topic 數(shù)、chain 數(shù)、按 track/level 的分布適合寫進發(fā)布記錄。限制與排錯邊界--json-schema命令JSON_OUTPUT.md 提到vault sub --json-schema可打印某命令的完整 JSON schema但當前 src/vault_cli/ 源碼中尚未實現(xiàn)該參數(shù)全倉庫檢索不到。文檔與代碼存在版本差異本文主路徑不依賴它如需確認字段以 check.py / build.py 實際輸出的 JSON 為準。vault serve與vault api不支持--json前者啟動 Datasette、后者是常駐 HTTP 服務不是 JSON 輸出命令JSON_OUTPUT.md 明確標注 Not applicable腳本化流程里不要對它們做信封斷言。退出碼 5 的陷阱如果 CI 中某個帶交互確認的命令掛起等待確認后被超時殺掉會得到可區(qū)分的 5USER_ABORTED而非一般失敗腳本不應把它計入「數(shù)據(jù)壞了」。本文的 check/build 流程無交互不涉及此項。失敗時data可能只部分填充腳本對失敗分支只應讀errors不要假設(shè)data完整。--tier slow不要放進日常 CI它是 nightly 級別的 LSH 場景去重README成本與用途都不同于--strict。本地測試套件開發(fā) vault-cli 本身時才需要pip install -e interviews/vault-cli/[dev]后pytest interviews/vault-cli/tests/README「Run tests」節(jié)。下一步腳本化流程跑穩(wěn)之后倉庫文檔給出的延伸路徑是完整發(fā)布流水線vault snapshot ver→vault migrations-emit from to→vault publish ver→vault verify ver均支持--jsonschema 見 JSON_OUTPUT.md以及鏈式題序chains的構(gòu)建腳本 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 腳本即可作為它們的前置質(zhì)量門復用。【免費下載鏈接】cs249r_bookMachine Learning Systems項目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考