StaffML 问题库 CLI 完全指南vault-cli的安装、22 个命令、校验层级与发布流水线【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book本文以 interviews/vault-cli/README.md 为主体系统讲解 StaffML 问题库question vault的官方命令行工具vault-cli从本地可编辑安装、四类共 22 个子命令的实战用法到内容寻址 ID 方案、三级校验、稳定退出码、--json机器输出契约再到 v1.1 引入的 chain 构建流水线与测试工程实践。读完本文你将掌握用vault完成题目增删改查、构建编译、检查校验、快照发布、回滚上线的完整操作链路并理解其背后的源码级实现原理。项目定位vault-cli 与问题库的关系vault-cliPython 包名staffml-vault入口命令vault是 StaffML 面试问题库的作者—构建—发布一体化命令行工具。它并不直接存储数据而是围绕interviews/vault/目录下的 YAML 语料数千道按 track/level/zone 分类的题目提供作者侧新建、编辑、软删/硬删、移动、恢复、重编号、标记 exemplar构建与校验侧YAML → SQLite 编译、快速/结构/慢速三档校验、统计、代码生成一致性守护、8 项诊断发布侧快照、迁移 SQL 生成、论文导出、git 打 tag、原子发布、学术引用级校验、版本 diff、D1 部署、回滚、正式上线、草稿晋升本地开发侧本地构建并镜像 corpus.json 给 StaffML 前端、本地 API 服务、Datasette 浏览。设计基线文档是interviews/vault/ARCHITECTURE.md其 §3.6 记录了 v1.1 的增量变化对抗性评审记录见interviews/vault/REVIEWS.md测试计划见interviews/vault/TESTING.md。安装与运行环境vault-cli采用 hatchling 构建通过本地可编辑安装接入项目。在仓库根目录执行# from the monorepo root pip install -e interviews/vault-cli/ vault --version安装后入口脚本在pyproject.toml中声明为vault vault_cli.main:app。环境要求如下Python ≥ 3.12 是硬性要求requires-python 3.12CI 精确锁定 3.12原因是为了哈希稳定性——语料与产物的内容哈希必须跨机器、跨 CI 可复现Python 版本不一致会改变哈希结果。详见docs/EXIT_CODES.md与 ARCHITECTURE.md §3.5。运行时依赖typer0.12命令行框架、rich13终端美化、pydantic2.7数据模型校验、pyyaml6、click8。开发依赖可选 extra[dev]pytest8、pytest-cov5、pytest-timeout2、mypy1.10strict 模式、ruff0.5。pyproject.toml中还内置了质量门槛配置ruff 启用E/F/W/I/B/UP/N/SIM规则集并对 Typer 惯用法typer.Option(...)出现在函数参数默认位置与(str, Enum)混用做了针对性豁免mypy 以strict true运行。安装时若需要开发工具使用带 extra 的方式pip install -e interviews/vault-cli/[dev]命令总览今天存活的 22 个子命令vault是基于 Typer 的聚合应用顶层入口在src/vault_cli/main.py。app以no_args_is_helpTrue创建直接敲vault会打印帮助面板通过register(app)将各命令模块挂载为子命令涵盖 authoring、build、check、serve_api、release、stats、codegen、doctor、diff、promote、dup、generate、lint、ls、show、chain、audit 等模块。全局提供--version/-V快速查看版本_version_callback打印后以ExitCode.SUCCESS退出。命令按用途可分为四组1. 作者Authoring命令vault new --track cloud --level l4 --zone diagnosis \ --topic kv-cache --title ... # content-addressed ID registry append authors vault edit id # $EDITOR; failure injects comment block, re-opens vault move id --to track/level/zone # dirty-tree / chain / applicability refusals vault rm id [--hard] # soft (deprecate) by default; --hard needs typed confirm vault restore id # undo soft-delete vault renumber id # recover from post-rebase dedup-seq collision vault mark-exemplar id # promote to human-only exemplar poolvault new会用内容寻址方式生成 ID、追加注册表条目并从git config user.email自动填充authors字段vault edit打开$EDITOR若校验失败会把错误以注释块注入文件顶部并自动重开而不是直接报错中断vault rm默认软删除status: deprecated--hard需要键入完整标题确认vault move会做脏工作树、chain 完整性、applicability 矩阵三重拒绝检查vault mark-exemplar只允许human或已人工评审的llm-then-human-edited来源的题目进入 exemplar 池。2. 构建与检查命令vault build # YAML → vault.db vault check --strict # fast structural tiers vault check --tier slow # nightly LSH scenario-dedup vault stats [--format-prometheus|--exemplar-coverage] vault codegen --check # shared-types drift guard vault doctor [--check name] # 8 diagnostic subchecksvault build把 YAML 语料编译为 SQLite 数据库vault.db产出release_id、release_hash等元信息vault check是 CI 的主要守门人--strict等价于跑 fast structural 两档README 标注 60s--tier slow则是夜间任务含基于 LSH 的场景去重vault codegen --check守护前端共享类型定义与实际语料之间不漂移vault doctor提供 8 项诊断子检查git 状态、schema 版本、注册表完整性、发布完整性、D1 连通性、内容哈希抽样、LLM 花费账本等可用--check name单独执行。3. 发布流水线命令vault snapshot 1.0.0 # stage to releases/.pending-1.0.0/ vault migrations-emit 0.9.0 1.0.0 # forward inverse SQL (all 4 tables) vault export-paper 1.0.0 # SQL → macros.tex corpus_stats.json vault tag 1.0.0 # git commit tag vault publish 1.0.0 [--resume|--sign] # composed product; atomic POSIX rename vault verify 1.0.0 [--git-ref v1.0.0] # academic-citability round-trip vault diff 0.9.0 1.0.0 --classify # cosmetic|semantic|structural vault deploy 1.0.0 --env staging # D1 migration snapshot POP probe vault rollback v --env production [--method snapshot|sql] vault ship 1.0.0 --env production [--resume] [--skip-legs paper] vault promote id | --all-drafts # drafts → published with provenance bump发布链路的每一步都是可断点续传、可验证的publish采用原子 POSIX rename先落地releases/.pending-v/成功后才切换为正式目录verify做学术可引用级别的哈希往返校验expected_hashvscomputed_hash逐叶验证deploy组合了 D1 迁移、快照与 POP点存在性探测rollback支持snapshot/sql两种恢复方法ship是生产全流程编排失败时自动回滚。4. 本地开发命令vault build --local # YAML → vault.db AND mirror corpus.json into staffml/public/data/ # so cd interviews/staffml npm run dev renders local edits # instead of fetching the production worker. Also writes the # legacy src/data/corpus.json for build tooling. The StaffML # predev hook calls this automatically; see # interviews/staffml/README.md for the full dev workflow. vault api --db path.db --port 8002 # mirror Worker endpoint surface from local vault.db vault serve # Datasette over vault.db (127.0.0.1 only)vault build --local除了编译vault.db还会把corpus.json镜像到interviews/staffml/public/data/并写出旧版src/data/corpus.json这样前端npm run dev渲染的是本地编辑而不是线上 Worker 数据。vault api在本地复刻 Cloudflare Worker 的接口面vault serve启动仅绑定 127.0.0.1 的 Datasette 用于人工浏览。所有命令都支持--json输出机器可读结果schema 见docs/JSON_OUTPUT.md退出码契约稳定见docs/EXIT_CODES.md。内容寻址 ID 与作者命令的源码实现作者命令的实现集中在src/vault_cli/commands/authoring.py几个关键机制值得展开v2 ID 方案_new_question_id()生成qid track-yyyymm-4hex。其中 4 位十六进制来自_id_hash(title, topic)——即sha256(title \n topic)的前 4 个字符在topic参与哈希防止两个标题相同但主题无关的题目撞出同一 ID。若同(track, yyyymm)桶内碰撞则按十六进制递增直到找到空位每桶 65,536 个槽位碰撞概率极低。这解释了为何同样的题目内容在任意机器上都会得到一致的 ID。注册表追加append-only_append_registry()向interviews/vault/id-registry.yaml追加一行{id, created_at, created_by}。该文件是只追加日志CI 会拒绝删除行的提交。注册表先git pull --rebase --autostash origin再分配降低并发碰撞率§3.3 并发契约。vault new脚手架新题 YAML 以schema_version: 1.0、status: draft、provenance: human起步正文骨架预填两个带规范加粗标记的模板块——common_mistakeThe Pitfall / The Rationale / The Consequence与napkin_mathAssumptions Constraints / Calculations / Conclusion。模板是模块级常量tests/test_authoring_scaffold.py专门断言这些标记必须齐全。vault edit的自愈循环编辑后立即用 Pydantic 的Question.model_validate()校验失败则调用_inject_validation_error_comment()把错误以# ─── VALIDATION FAILURE ───注释块注入文件头部并剥离旧错误块防止堆积然后重新打开编辑器最多重试--retries默认 3次。若编辑器以非零码退出则按USER_ABORTED中止。vault rm的双重安全软删只需改写status: deprecated--hard会先拒绝删除仍在 chain 中的题目除非--force随后要求键入完整题目标题才真正 unlink 文件键入不匹配按USER_ABORTED退出。test_commands.py中有对应回归测试test_rm_hard_without_confirm_aborts。vault move的三重拒绝① 工作树脏则拒绝除非--allow-dirty② 题目在 chain 中则拒绝除非--i-understand-chain-breakage③ 目标(track, topic)落在interviews/vault/data/applicable_cells.json的 excluded 集合则拒绝。通过后优先走git mv保留历史非 git 仓库时回退到普通移动。vault renumber针对 rebase 后序号碰撞的恢复命令。解析旧文件名topic-hash-seq.yaml从当前 seq 开始向上找下一个空闲槽改写 YAML 的id字段、重命名文件、追加新注册表条目旧 ID 永不复用。校验分层fast / structural / slowvault check的实现位于src/vault_cli/commands/check.py校验逻辑在src/vault_cli/validator.py中按 tier 组织fast tier加载期基础不变量任何坏 YAML、schema 违规在此暴露structural tier跨文件的完整性检查注册表一致性、引用解析、链约束等--strict下与 fast 一起跑面向 CIslow tier昂贵的全库检查如 LSH 场景去重面向夜间任务。check_cmd还接受--tier {fast|structural|all}精细控制加载错误load_errors始终计入失败。--json模式下错误被序列化为 LSP 诊断形状urirangeseveritycodemessage编辑器可直接渲染内联波浪线。校验器内部使用 WHITE/GRAY/BLACK 经典三色做环检测ruff 配置对其N806做了豁免。稳定退出码契约docs/EXIT_CODES.md是退出码分类学的权威文档其单一事实来源是src/vault_cli/exit_codes.py中的ExitCode枚举。核心契约代码跨版本稳定、永不重编号、脚本可安全 pin 住。CodeSymbol含义典型触发场景0SUCCESS命令成功完成正常路径1VALIDATION_FAILURE数据不变量 / schema / 完整性检查失败坏 YAML、内容哈希不匹配、注册表不一致、回滚对称性破坏2USAGE_ERROR命令调用本身格式错误缺必需参数、未知 flag、冲突 flag由 Typer/Click 抛出3IO_ERROR文件系统或本地 I/O 失败权限不足、磁盘满、缺文件、符号链接切换失败4NETWORK_ERROR对 D1 / Cloudflare / LLM API 等外部服务的网络调用失败D1 不可达、超时、上游 5xx、DNS 故障5USER_ABORTED交互确认被拒绝或确认中途 Ctrl-C键入n或vault rm --hard标题不匹配64–78—保留给sysexits.h标准码仅当前述类别都不适用时使用这套分类的工程动机在文档中写得很明确0 vs 1让 CI 能用if vault check; then deploy; fi的惯用法区分可以放行与语料有毛病1 vs 2让运维能区分数据坏了去改 git与命令敲错了重读 --help3 vs 4让可观测性区分本地 IO 几乎可复现与网络错误值得重试并上报 Cloudflare 日志5单独设码避免脚本把用户取消误判为 bug。代码中严禁使用裸整数一律raise typer.Exit(codeExitCode.VALIDATION_FAILURE)式地引用枚举由 mypy 捕获拼写错误。新增码值的流程在[6..63]或[79..127]取下一个未用值 → 在此文档登记符号与含义 → 更新回归测试test_exit_code_taxonomy_is_stable→ 永不重编号。--json 机器输出契约所有支持--json的子命令共享统一信封envelope{ ok: true | false, exit_code: 0.., exit_symbol: SUCCESS | VALIDATION_FAILURE | ..., command: vault subcommand, cli_version: 0.1.0, data: command-specific, errors: [error, ...], warnings: [warning, ...] }成功时oktrue、errors[]、data填充完整失败时okfalse、errors填充、data可能部分。任意命令的vault cmd --json-schema会打印该命令的完整 JSON schema例如vault check --json-schema | jq .。各命令的 schema 细节check/stats/verify/doctor/diff/build/publish/ship/new/rm/move/renumber/restore/promote/mark-exemplar/snapshot/migrations-emit/export-paper/tag/deploy/rollback 等均在docs/JSON_OUTPUT.md中逐一文档化serve与api是长驻服务不适用--json。信封契约随 CLI 版本化改动信封字段重命名ok/exit_code/data属于 CLI 主版本升级仅在data内加可选字段属于次版本。vault check --json的错误条目采用 LSP 诊断形状severity1Error、2Warning、3Info、4Hint例如{ 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, range: { start: { line: 6, character: 0 }, end: { line: 6, character: 24 } }, 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? }] }Chain 构建流水线v1.1Chain 是同一(track, topic)桶内、沿 Bloom 层级L1→L6递进的教学序列。设计要点interviews/vault/chains.json是唯一权威注册表YAML 题目不再携带chains:字段所有中间产物chains.proposed*.json、gaps.proposed*.json、审计轨迹等统一落在interviews/vault/_pipeline/该目录整体 gitignore只有持久化注册表chains.json入库——约定详见interviews/vault/README.md的 Pipeline artifacts 一节LLM 驱动工具的中间输出是可复现生成的噪音不应污染 git 历史构建工具位于scripts/目录。标准五步流水线# 1. Surface (track, topic) buckets that need chains. Writes # interviews/vault/chain-coverage.json (gitignored — regeneratable). python3 scripts/diagnose_chain_coverage.py # 2. Strict pass: Δ ∈ {1, 2}, primary chains. Default mode. # Defaults write to _pipeline/chains.proposed.json. python3 scripts/build_chains_with_gemini.py --all # 3. Lenient pass: Δ ∈ {1, 2, 3}, secondary chains. # Use --buckets-from to scope the run to uncovered buckets only. python3 scripts/build_chains_with_gemini.py --mode lenient \ --buckets-from ../vault/chain-coverage.json \ --output ../vault/_pipeline/chains.proposed.lenient.json # 4. Apply a single proposed file (replaces chains.json after validation). python3 scripts/apply_proposed_chains.py \ --proposed ../vault/_pipeline/chains.proposed.json # 5. Merge primary secondary into chains.json with cap enforcement # (each qid in ≤ 2 chains; non-L1/L2 qids capped at 1 membership). python3 scripts/merge_chain_passes.py关键规则由tests/test_chain_validation.py完整覆盖strict 模式接受 Δ∈{1,2} 的递进、拒绝同级对与三级跳lenient 模式放宽到 Δ∈{1,2,3}但仍然拒绝向后递减与四级跳链长 2 或 6、跨 topic、引用未知 qid 均被拒。apply_proposed_chains.py与校验器都容忍 chain 条目缺失tier字段默认视为primary--mode lenient产出的链会被标记tier: secondary。任何修改之后都要重跑vault check --strict vault build --local-jsonchain 语料增长进度记录在docs/CHAIN_ROADMAP.md可恢复的覆盖工作流chain 的审计、embedding、救援工具分置于src/vault_cli/chains/{audit,embeddings,rescue}.py。运行测试pip install -e interviews/vault-cli/[dev] pytest interviews/vault-cli/tests/测试套件位于interviews/vault-cli/tests/README 标注当前 74 个测试pytest 配置于pyproject.tomladdopts -x --strict-markers --timeout60。覆盖面包括test_commands.pyCLI 命令级行为与退出码含rm --hard确认中止test_authoring_scaffold.py新题脚手架模板的标记完整性test_chain_validation.pychain 校验的 strict/lenient 边界矩阵test_hashing.py内容哈希与 ID 方案test_release.py/test_ship.py/test_policy.py发布策略过滤、快照、ship 编排test_legacy_export.pycorpus.json 与 chain_tiers 导出test_book_refs.py书引用book refs解析与链接检查test_audit_batching.pyLLM 审计批处理的分批逻辑空输入、最大条数、最大字符、顺序保持、超大单条。此外Makefile提供了便捷目标make install带 dev extras 安装、make test、make lintruff 检查 非阻塞 mypy、make hooks/make hooks-uninstall把scripts/pre_commit_corpus_guard.py软链进.git/hooks/pre-commit作为语料守护钩子。目录布局interviews/vault-cli/ ├── pyproject.toml ├── README.md # 本文档主体 ├── docs/ │ ├── CHAIN_ROADMAP.md # resumable chain-coverage workstream │ ├── EXIT_CODES.md # stable exit-code taxonomy │ ├── JSON_OUTPUT.md # per-command --json schemas │ └── CUTOVER_QA.md # manual cutover QA checklist ├── src/vault_cli/ # Typer app library │ ├── __init__.py │ ├── compiler.py / loader.py / yaml_io.py │ ├── legacy_export.py # corpus.json chain_tiers emitter │ ├── policy.py # release-policy filter │ ├── validator.py # fast / structural / slow tiers │ ├── chains/ # audit / embeddings / rescue │ ├── commands/ # 18 个命令模块authoring、check、release、ship… │ └── main.py # Typer app entry ├── scripts/ # ops Gemini-powered tools │ ├── diagnose_chain_coverage.py # surface uncovered buckets │ ├── build_chains_with_gemini.py # --mode {strict,lenient} │ ├── apply_proposed_chains.py # gate proposed chains.json │ ├── merge_chain_passes.py # primary secondary, cap-enforced │ ├── summarize_proposed_chains.py # quick-read review │ └── ... # auditing, calibration, D1 emit, etc. └── tests/ # pytest suite (74 tests today)注scripts/*.py因需独立运行而在导入vault_cli前插入sys.pathruff 对其E402做了豁免docs/下还包含 AUDIT_FINDINGS、CORPUS_HARDENING_PLAN、PHASE_3_REVIEW_GUIDE、PHASE_5_UNRESOLVED、RELEASE_AUDIT_PLAN 等审计与演进文档。架构与贡献完整的架构设计请阅读兄弟目录interviews/vault/下的文档ARCHITECTURE.md——完整设计文档REVIEWS.md——对抗性评审台账TESTING.md——测试计划schema 版本演进规则见 vault 目录内 schema 相关文档。贡献规范见仓库根目录的CONTRIBUTING.md项目采用 MIT 许可详见仓库根目录LICENSE.md。本工具由vault命令 库代码src/vault_cli/ 运维脚本scripts/ 测试tests/四部分构成任何对语料结构、发布流程或校验规则的改动都建议先对照 ARCHITECTURE.md 的设计意图再以vault check --strict与完整 pytest 套件作为回归防线。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
StaffML 问题库 CLI 完全指南：`vault-cli` 的安装、22 个命令、校验层级与发布流水线
StaffML 问题库 CLI 完全指南vault-cli的安装、22 个命令、校验层级与发布流水线【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book本文以 interviews/vault-cli/README.md 为主体系统讲解 StaffML 问题库question vault的官方命令行工具vault-cli从本地可编辑安装、四类共 22 个子命令的实战用法到内容寻址 ID 方案、三级校验、稳定退出码、--json机器输出契约再到 v1.1 引入的 chain 构建流水线与测试工程实践。读完本文你将掌握用vault完成题目增删改查、构建编译、检查校验、快照发布、回滚上线的完整操作链路并理解其背后的源码级实现原理。项目定位vault-cli 与问题库的关系vault-cliPython 包名staffml-vault入口命令vault是 StaffML 面试问题库的作者—构建—发布一体化命令行工具。它并不直接存储数据而是围绕interviews/vault/目录下的 YAML 语料数千道按 track/level/zone 分类的题目提供作者侧新建、编辑、软删/硬删、移动、恢复、重编号、标记 exemplar构建与校验侧YAML → SQLite 编译、快速/结构/慢速三档校验、统计、代码生成一致性守护、8 项诊断发布侧快照、迁移 SQL 生成、论文导出、git 打 tag、原子发布、学术引用级校验、版本 diff、D1 部署、回滚、正式上线、草稿晋升本地开发侧本地构建并镜像 corpus.json 给 StaffML 前端、本地 API 服务、Datasette 浏览。设计基线文档是interviews/vault/ARCHITECTURE.md其 §3.6 记录了 v1.1 的增量变化对抗性评审记录见interviews/vault/REVIEWS.md测试计划见interviews/vault/TESTING.md。安装与运行环境vault-cli采用 hatchling 构建通过本地可编辑安装接入项目。在仓库根目录执行# from the monorepo root pip install -e interviews/vault-cli/ vault --version安装后入口脚本在pyproject.toml中声明为vault vault_cli.main:app。环境要求如下Python ≥ 3.12 是硬性要求requires-python 3.12CI 精确锁定 3.12原因是为了哈希稳定性——语料与产物的内容哈希必须跨机器、跨 CI 可复现Python 版本不一致会改变哈希结果。详见docs/EXIT_CODES.md与 ARCHITECTURE.md §3.5。运行时依赖typer0.12命令行框架、rich13终端美化、pydantic2.7数据模型校验、pyyaml6、click8。开发依赖可选 extra[dev]pytest8、pytest-cov5、pytest-timeout2、mypy1.10strict 模式、ruff0.5。pyproject.toml中还内置了质量门槛配置ruff 启用E/F/W/I/B/UP/N/SIM规则集并对 Typer 惯用法typer.Option(...)出现在函数参数默认位置与(str, Enum)混用做了针对性豁免mypy 以strict true运行。安装时若需要开发工具使用带 extra 的方式pip install -e interviews/vault-cli/[dev]命令总览今天存活的 22 个子命令vault是基于 Typer 的聚合应用顶层入口在src/vault_cli/main.py。app以no_args_is_helpTrue创建直接敲vault会打印帮助面板通过register(app)将各命令模块挂载为子命令涵盖 authoring、build、check、serve_api、release、stats、codegen、doctor、diff、promote、dup、generate、lint、ls、show、chain、audit 等模块。全局提供--version/-V快速查看版本_version_callback打印后以ExitCode.SUCCESS退出。命令按用途可分为四组1. 作者Authoring命令vault new --track cloud --level l4 --zone diagnosis \ --topic kv-cache --title ... # content-addressed ID registry append authors vault edit id # $EDITOR; failure injects comment block, re-opens vault move id --to track/level/zone # dirty-tree / chain / applicability refusals vault rm id [--hard] # soft (deprecate) by default; --hard needs typed confirm vault restore id # undo soft-delete vault renumber id # recover from post-rebase dedup-seq collision vault mark-exemplar id # promote to human-only exemplar poolvault new会用内容寻址方式生成 ID、追加注册表条目并从git config user.email自动填充authors字段vault edit打开$EDITOR若校验失败会把错误以注释块注入文件顶部并自动重开而不是直接报错中断vault rm默认软删除status: deprecated--hard需要键入完整标题确认vault move会做脏工作树、chain 完整性、applicability 矩阵三重拒绝检查vault mark-exemplar只允许human或已人工评审的llm-then-human-edited来源的题目进入 exemplar 池。2. 构建与检查命令vault build # YAML → vault.db vault check --strict # fast structural tiers vault check --tier slow # nightly LSH scenario-dedup vault stats [--format-prometheus|--exemplar-coverage] vault codegen --check # shared-types drift guard vault doctor [--check name] # 8 diagnostic subchecksvault build把 YAML 语料编译为 SQLite 数据库vault.db产出release_id、release_hash等元信息vault check是 CI 的主要守门人--strict等价于跑 fast structural 两档README 标注 60s--tier slow则是夜间任务含基于 LSH 的场景去重vault codegen --check守护前端共享类型定义与实际语料之间不漂移vault doctor提供 8 项诊断子检查git 状态、schema 版本、注册表完整性、发布完整性、D1 连通性、内容哈希抽样、LLM 花费账本等可用--check name单独执行。3. 发布流水线命令vault snapshot 1.0.0 # stage to releases/.pending-1.0.0/ vault migrations-emit 0.9.0 1.0.0 # forward inverse SQL (all 4 tables) vault export-paper 1.0.0 # SQL → macros.tex corpus_stats.json vault tag 1.0.0 # git commit tag vault publish 1.0.0 [--resume|--sign] # composed product; atomic POSIX rename vault verify 1.0.0 [--git-ref v1.0.0] # academic-citability round-trip vault diff 0.9.0 1.0.0 --classify # cosmetic|semantic|structural vault deploy 1.0.0 --env staging # D1 migration snapshot POP probe vault rollback v --env production [--method snapshot|sql] vault ship 1.0.0 --env production [--resume] [--skip-legs paper] vault promote id | --all-drafts # drafts → published with provenance bump发布链路的每一步都是可断点续传、可验证的publish采用原子 POSIX rename先落地releases/.pending-v/成功后才切换为正式目录verify做学术可引用级别的哈希往返校验expected_hashvscomputed_hash逐叶验证deploy组合了 D1 迁移、快照与 POP点存在性探测rollback支持snapshot/sql两种恢复方法ship是生产全流程编排失败时自动回滚。4. 本地开发命令vault build --local # YAML → vault.db AND mirror corpus.json into staffml/public/data/ # so cd interviews/staffml npm run dev renders local edits # instead of fetching the production worker. Also writes the # legacy src/data/corpus.json for build tooling. The StaffML # predev hook calls this automatically; see # interviews/staffml/README.md for the full dev workflow. vault api --db path.db --port 8002 # mirror Worker endpoint surface from local vault.db vault serve # Datasette over vault.db (127.0.0.1 only)vault build --local除了编译vault.db还会把corpus.json镜像到interviews/staffml/public/data/并写出旧版src/data/corpus.json这样前端npm run dev渲染的是本地编辑而不是线上 Worker 数据。vault api在本地复刻 Cloudflare Worker 的接口面vault serve启动仅绑定 127.0.0.1 的 Datasette 用于人工浏览。所有命令都支持--json输出机器可读结果schema 见docs/JSON_OUTPUT.md退出码契约稳定见docs/EXIT_CODES.md。内容寻址 ID 与作者命令的源码实现作者命令的实现集中在src/vault_cli/commands/authoring.py几个关键机制值得展开v2 ID 方案_new_question_id()生成qid track-yyyymm-4hex。其中 4 位十六进制来自_id_hash(title, topic)——即sha256(title \n topic)的前 4 个字符在topic参与哈希防止两个标题相同但主题无关的题目撞出同一 ID。若同(track, yyyymm)桶内碰撞则按十六进制递增直到找到空位每桶 65,536 个槽位碰撞概率极低。这解释了为何同样的题目内容在任意机器上都会得到一致的 ID。注册表追加append-only_append_registry()向interviews/vault/id-registry.yaml追加一行{id, created_at, created_by}。该文件是只追加日志CI 会拒绝删除行的提交。注册表先git pull --rebase --autostash origin再分配降低并发碰撞率§3.3 并发契约。vault new脚手架新题 YAML 以schema_version: 1.0、status: draft、provenance: human起步正文骨架预填两个带规范加粗标记的模板块——common_mistakeThe Pitfall / The Rationale / The Consequence与napkin_mathAssumptions Constraints / Calculations / Conclusion。模板是模块级常量tests/test_authoring_scaffold.py专门断言这些标记必须齐全。vault edit的自愈循环编辑后立即用 Pydantic 的Question.model_validate()校验失败则调用_inject_validation_error_comment()把错误以# ─── VALIDATION FAILURE ───注释块注入文件头部并剥离旧错误块防止堆积然后重新打开编辑器最多重试--retries默认 3次。若编辑器以非零码退出则按USER_ABORTED中止。vault rm的双重安全软删只需改写status: deprecated--hard会先拒绝删除仍在 chain 中的题目除非--force随后要求键入完整题目标题才真正 unlink 文件键入不匹配按USER_ABORTED退出。test_commands.py中有对应回归测试test_rm_hard_without_confirm_aborts。vault move的三重拒绝① 工作树脏则拒绝除非--allow-dirty② 题目在 chain 中则拒绝除非--i-understand-chain-breakage③ 目标(track, topic)落在interviews/vault/data/applicable_cells.json的 excluded 集合则拒绝。通过后优先走git mv保留历史非 git 仓库时回退到普通移动。vault renumber针对 rebase 后序号碰撞的恢复命令。解析旧文件名topic-hash-seq.yaml从当前 seq 开始向上找下一个空闲槽改写 YAML 的id字段、重命名文件、追加新注册表条目旧 ID 永不复用。校验分层fast / structural / slowvault check的实现位于src/vault_cli/commands/check.py校验逻辑在src/vault_cli/validator.py中按 tier 组织fast tier加载期基础不变量任何坏 YAML、schema 违规在此暴露structural tier跨文件的完整性检查注册表一致性、引用解析、链约束等--strict下与 fast 一起跑面向 CIslow tier昂贵的全库检查如 LSH 场景去重面向夜间任务。check_cmd还接受--tier {fast|structural|all}精细控制加载错误load_errors始终计入失败。--json模式下错误被序列化为 LSP 诊断形状urirangeseveritycodemessage编辑器可直接渲染内联波浪线。校验器内部使用 WHITE/GRAY/BLACK 经典三色做环检测ruff 配置对其N806做了豁免。稳定退出码契约docs/EXIT_CODES.md是退出码分类学的权威文档其单一事实来源是src/vault_cli/exit_codes.py中的ExitCode枚举。核心契约代码跨版本稳定、永不重编号、脚本可安全 pin 住。CodeSymbol含义典型触发场景0SUCCESS命令成功完成正常路径1VALIDATION_FAILURE数据不变量 / schema / 完整性检查失败坏 YAML、内容哈希不匹配、注册表不一致、回滚对称性破坏2USAGE_ERROR命令调用本身格式错误缺必需参数、未知 flag、冲突 flag由 Typer/Click 抛出3IO_ERROR文件系统或本地 I/O 失败权限不足、磁盘满、缺文件、符号链接切换失败4NETWORK_ERROR对 D1 / Cloudflare / LLM API 等外部服务的网络调用失败D1 不可达、超时、上游 5xx、DNS 故障5USER_ABORTED交互确认被拒绝或确认中途 Ctrl-C键入n或vault rm --hard标题不匹配64–78—保留给sysexits.h标准码仅当前述类别都不适用时使用这套分类的工程动机在文档中写得很明确0 vs 1让 CI 能用if vault check; then deploy; fi的惯用法区分可以放行与语料有毛病1 vs 2让运维能区分数据坏了去改 git与命令敲错了重读 --help3 vs 4让可观测性区分本地 IO 几乎可复现与网络错误值得重试并上报 Cloudflare 日志5单独设码避免脚本把用户取消误判为 bug。代码中严禁使用裸整数一律raise typer.Exit(codeExitCode.VALIDATION_FAILURE)式地引用枚举由 mypy 捕获拼写错误。新增码值的流程在[6..63]或[79..127]取下一个未用值 → 在此文档登记符号与含义 → 更新回归测试test_exit_code_taxonomy_is_stable→ 永不重编号。--json 机器输出契约所有支持--json的子命令共享统一信封envelope{ ok: true | false, exit_code: 0.., exit_symbol: SUCCESS | VALIDATION_FAILURE | ..., command: vault subcommand, cli_version: 0.1.0, data: command-specific, errors: [error, ...], warnings: [warning, ...] }成功时oktrue、errors[]、data填充完整失败时okfalse、errors填充、data可能部分。任意命令的vault cmd --json-schema会打印该命令的完整 JSON schema例如vault check --json-schema | jq .。各命令的 schema 细节check/stats/verify/doctor/diff/build/publish/ship/new/rm/move/renumber/restore/promote/mark-exemplar/snapshot/migrations-emit/export-paper/tag/deploy/rollback 等均在docs/JSON_OUTPUT.md中逐一文档化serve与api是长驻服务不适用--json。信封契约随 CLI 版本化改动信封字段重命名ok/exit_code/data属于 CLI 主版本升级仅在data内加可选字段属于次版本。vault check --json的错误条目采用 LSP 诊断形状severity1Error、2Warning、3Info、4Hint例如{ 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, range: { start: { line: 6, character: 0 }, end: { line: 6, character: 24 } }, 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? }] }Chain 构建流水线v1.1Chain 是同一(track, topic)桶内、沿 Bloom 层级L1→L6递进的教学序列。设计要点interviews/vault/chains.json是唯一权威注册表YAML 题目不再携带chains:字段所有中间产物chains.proposed*.json、gaps.proposed*.json、审计轨迹等统一落在interviews/vault/_pipeline/该目录整体 gitignore只有持久化注册表chains.json入库——约定详见interviews/vault/README.md的 Pipeline artifacts 一节LLM 驱动工具的中间输出是可复现生成的噪音不应污染 git 历史构建工具位于scripts/目录。标准五步流水线# 1. Surface (track, topic) buckets that need chains. Writes # interviews/vault/chain-coverage.json (gitignored — regeneratable). python3 scripts/diagnose_chain_coverage.py # 2. Strict pass: Δ ∈ {1, 2}, primary chains. Default mode. # Defaults write to _pipeline/chains.proposed.json. python3 scripts/build_chains_with_gemini.py --all # 3. Lenient pass: Δ ∈ {1, 2, 3}, secondary chains. # Use --buckets-from to scope the run to uncovered buckets only. python3 scripts/build_chains_with_gemini.py --mode lenient \ --buckets-from ../vault/chain-coverage.json \ --output ../vault/_pipeline/chains.proposed.lenient.json # 4. Apply a single proposed file (replaces chains.json after validation). python3 scripts/apply_proposed_chains.py \ --proposed ../vault/_pipeline/chains.proposed.json # 5. Merge primary secondary into chains.json with cap enforcement # (each qid in ≤ 2 chains; non-L1/L2 qids capped at 1 membership). python3 scripts/merge_chain_passes.py关键规则由tests/test_chain_validation.py完整覆盖strict 模式接受 Δ∈{1,2} 的递进、拒绝同级对与三级跳lenient 模式放宽到 Δ∈{1,2,3}但仍然拒绝向后递减与四级跳链长 2 或 6、跨 topic、引用未知 qid 均被拒。apply_proposed_chains.py与校验器都容忍 chain 条目缺失tier字段默认视为primary--mode lenient产出的链会被标记tier: secondary。任何修改之后都要重跑vault check --strict vault build --local-jsonchain 语料增长进度记录在docs/CHAIN_ROADMAP.md可恢复的覆盖工作流chain 的审计、embedding、救援工具分置于src/vault_cli/chains/{audit,embeddings,rescue}.py。运行测试pip install -e interviews/vault-cli/[dev] pytest interviews/vault-cli/tests/测试套件位于interviews/vault-cli/tests/README 标注当前 74 个测试pytest 配置于pyproject.tomladdopts -x --strict-markers --timeout60。覆盖面包括test_commands.pyCLI 命令级行为与退出码含rm --hard确认中止test_authoring_scaffold.py新题脚手架模板的标记完整性test_chain_validation.pychain 校验的 strict/lenient 边界矩阵test_hashing.py内容哈希与 ID 方案test_release.py/test_ship.py/test_policy.py发布策略过滤、快照、ship 编排test_legacy_export.pycorpus.json 与 chain_tiers 导出test_book_refs.py书引用book refs解析与链接检查test_audit_batching.pyLLM 审计批处理的分批逻辑空输入、最大条数、最大字符、顺序保持、超大单条。此外Makefile提供了便捷目标make install带 dev extras 安装、make test、make lintruff 检查 非阻塞 mypy、make hooks/make hooks-uninstall把scripts/pre_commit_corpus_guard.py软链进.git/hooks/pre-commit作为语料守护钩子。目录布局interviews/vault-cli/ ├── pyproject.toml ├── README.md # 本文档主体 ├── docs/ │ ├── CHAIN_ROADMAP.md # resumable chain-coverage workstream │ ├── EXIT_CODES.md # stable exit-code taxonomy │ ├── JSON_OUTPUT.md # per-command --json schemas │ └── CUTOVER_QA.md # manual cutover QA checklist ├── src/vault_cli/ # Typer app library │ ├── __init__.py │ ├── compiler.py / loader.py / yaml_io.py │ ├── legacy_export.py # corpus.json chain_tiers emitter │ ├── policy.py # release-policy filter │ ├── validator.py # fast / structural / slow tiers │ ├── chains/ # audit / embeddings / rescue │ ├── commands/ # 18 个命令模块authoring、check、release、ship… │ └── main.py # Typer app entry ├── scripts/ # ops Gemini-powered tools │ ├── diagnose_chain_coverage.py # surface uncovered buckets │ ├── build_chains_with_gemini.py # --mode {strict,lenient} │ ├── apply_proposed_chains.py # gate proposed chains.json │ ├── merge_chain_passes.py # primary secondary, cap-enforced │ ├── summarize_proposed_chains.py # quick-read review │ └── ... # auditing, calibration, D1 emit, etc. └── tests/ # pytest suite (74 tests today)注scripts/*.py因需独立运行而在导入vault_cli前插入sys.pathruff 对其E402做了豁免docs/下还包含 AUDIT_FINDINGS、CORPUS_HARDENING_PLAN、PHASE_3_REVIEW_GUIDE、PHASE_5_UNRESOLVED、RELEASE_AUDIT_PLAN 等审计与演进文档。架构与贡献完整的架构设计请阅读兄弟目录interviews/vault/下的文档ARCHITECTURE.md——完整设计文档REVIEWS.md——对抗性评审台账TESTING.md——测试计划schema 版本演进规则见 vault 目录内 schema 相关文档。贡献规范见仓库根目录的CONTRIBUTING.md项目采用 MIT 许可详见仓库根目录LICENSE.md。本工具由vault命令 库代码src/vault_cli/ 运维脚本scripts/ 测试tests/四部分构成任何对语料结构、发布流程或校验规则的改动都建议先对照 ARCHITECTURE.md 的设计意图再以vault check --strict与完整 pytest 套件作为回归防线。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考