StaffML Vault 语料库 Schema 与文件夹结构审计为什么扁平目录与track-NNNN标识是正确选择【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book本篇技术指南基于 interviews/vault/audit/2026-04-25-schema-folder-audit.md 展开围绕 StaffML 面试题库近万份逐题 YAML 语料的文件夹布局、ID 格式与 LinkML Schema 展开系统审计。你将理解为何团队在 v0.1 尝试过分层目录后仍回归扁平结构为何 48% 的语料带有 cohort 标签却不应批量重命名以及三项低风险 schema 清理ID 软正则、删除死字段、promotion 时清理 tags如何落地。读完可掌握结构化语料库在「分类即数据、文件系统仅作寻址」设计原则下的审计方法与迁移决策框架。一、审计背景与评估范围该审计于2026-04-25在分支audit/vault-schema-folder上执行针对的是 StaffML 面试题库的「Schema 与文件夹」两个正交维度。审计时的语料快照为9,982 份 YAML其中9,224 份为已发布published458 份为已删除deleted300 份为草稿draft审计的出发点是一个常见的工程直觉「语料规模已经近万是否应该像track/topic/或track/level/zone/那样引入子目录来组织」审计的结论恰恰相反保持现有 schema 与文件夹结构不变仅做三项小清理。这一结论建立在完整的语料统计、历史教训回溯与性能实测之上而非拍脑袋。二、TL;DR三条结论与理由领域建议理由文件夹布局track/id.yaml保持扁平不增加 topic/level/zone 子目录团队在 v0.1 明确尝试过更深的分层并在 v1.0 回退且有文档化原因当前规模下文件系统操作很快分类是数据而非寻址YAML SchemaLinkML Pydantic 代码生成保持仅做两处小编辑见第四节必填字段集合正确血缘lineage字段填充干净只有边缘情况需要注意ID 格式新内容track-NNNN旧 ID 保留保持在验证器中加一条软正则检查语料中 52% 已使用干净格式ID_SCHEMES.md 的迁移策略合理不做批量重命名审计文档的原话是「这个结构比我之前『加track/topic/子目录』的条件反射被思考得更仔细。审计确认了团队现有决策是正确的。」——这是一份典型的、以数据推翻直觉的工程审计。三、文件夹布局扁平结构的正确性论证3.1 当前形态interviews/vault/questions/ ├── cloud/ 4,302 files ├── edge/ 2,147 ├── global/ 418 ├── mobile/ 1,779 └── tinyml/ 1,336 ──── 9,982 total扁平track → 文件没有 level / zone / topic 子文件夹。仓库当前的实际目录结构与之一致见 interviews/vault/questions/。3.2 历史教训v0.1 分层设计的失败2026-04-21 回退这一决策并非没有试错。interviews/vault/ARCHITECTURE.md的 §3.3 记录了 v0.1 → v1.0 的逆转v0.1 曾采用track/level/zone/topic-hash.yaml的路径即分类设计最终被放弃原因有三路径承载不了完整分类体系论文的 11-zone × 6-level 分类法只有 4/11 个 zone 和 6/6 个 level 有对应目录L6 层级完全缺失迁移脚本静默丢数据v0.1 迁移脚本把无法表达的(level, zone)组合静默折叠进l1/recall/并丢弃了 86 道目标 cell 不存在的问题重分类需要移动文件这客观上抑制了修正意愿——改一个分类要动文件路径成本远高于改 YAML 字段。v1.0 的逆转让「分类成为 YAML 数据的属性」文件系统只携带track用于导航。这正是审计文档强调的核心设计原则「文件系统是浅层寻址方案」the filesystem as a shallow addressing scheme每一次重分类都只是一次 YAML 编辑而不是一次git mv。从源码侧看这一原则被 interviews/vault-cli/src/vault_cli/loader.py 落实为一条结构不变量questions/下的目录必须匹配 YAML 中的track字段而文件名仅要求id.yaml——因为历史上有合法问题的 ID 前缀已与当前 track 不再一致。3.3 扁平结构能撑住规模吗实测数据审计对 4,302 文件的cloud/目录做了基准测试操作耗时ls cloud/21 msgrep -l topic: kv-cache-management cloud/*.yaml194 ms跨 4,302 文件Python 加载全部 9,982 份 YAML 做审计约 6 s结论现代笔记本轻松容纳 1 万 小文件目录在约 5 万文件之前任何操作都不会明显变慢。当前规模下没有任何文件系统压力。3.4 中间方案track/topic/的权衡审计作者此前曾主张引入 topic 子目录87 topics × 5 tracks 435 个潜在子目录但权衡表显示该方案得不偿失优点缺点ls cloud/kv-cache-management/可列出同主题问题大多数 cell 稀疏会出现大量空目录文件系统自带文档性topic 是可变的Phase 2 审计曾把 25 道题移出边界按主题的 git diff 更干净每次重分类都要git mv浏览层可发现性跨主题搜索仍然要 grep并不受益决定性论据来自 ARCHITECTURE.md §3.3文件系统作为浅层寻址方案把每次重分类的成本模型设定为一次 YAML 编辑——这是正确的成本模型。加上 topic 子目录等于重新引入团队已明确移除的摩擦。结论保持扁平。分类浏览已由 CLI 的vault ls --topic kv-cache-management --track cloud提供见 interviews/vault/docs/ID_SCHEMES.md 的配套工具表前端练习页的过滤器则为终端用户提供同样的能力。文件系统层级不是可查询内容的正确抽象。四、ID 格式52% 干净 vs 48% 带 cohort 标签的现实4.1 语料中的真实分布模式数量占比track-NNNN干净格式5,22852%track-cohort-NNNN过程产物4,75448%其他0—当前 ID 中的 cohort 标签共有50 个不同的值顶部 cohort 及含义Cohort 标签数量含义-fill-1,300补缺口生成批次gap-filling generation-cell-789覆盖 cell 定向生成批次-r2-259第二轮生成-sus-232「可疑」评审批次-exp-anal-119探索/分析批次-crit-、-top-、-new-各约 100各类评审队列-exp2-anal-…-exp2-opti-各约 95Bloom 区域编码的第二轮批次-portfolio-、-balance-、-scale-各 50本周的组合平衡循环4.2 为什么这些 ID 能混进来schema 约束缺失question_schema.yaml将id声明为自由格式string没有任何正则约束。凡是匹配track-...的 ID 都能通过校验——这就是 cohort 标签 ID 得以存在的机制。4.3 审计建议不重命名只加软验证关键决策是不重命名现有 ID。依据 interviews/vault/docs/ID_SCHEMES.md 的迁移策略重命名会破坏3,100 条 chain 引用链内问题引用外部书签与 URL论文附录审计 JSONL 记录git blame历史重命名的成本约为清理价值的 10 倍。取而代之的是对新 ID 仅加软正则形成两级验证硬规则校验失败^[a-z]-[a-z0-9-]$—— 阻止非结构化 ID软警告^(cloud|edge|mobile|tinyml|global)-\d{4,}$—— 面向新内容存量 ID 豁免grandfathered。vault new已经会铸造干净 ID见 ID_SCHEMES.md 中「碰撞-freevault new命令锁定id-registry.yaml分配下一个空闲track-NNNN」的机制正则只是把这一行为强制到直接手写 YAML 的场景上。4.4 ID 方案的设计原则只编码不可变轴ID_SCHEMES.md 给出了更深的背景一个好的 ID 满足三条性质——稳定分配后永不改变、规模化无碰撞任何贡献者/工具铸造的新 ID 都经过检查、可读可引用出现在聊天、PR 描述、控制台日志中时人能猜出大概。其设计结论是ID 只编码不可变轴track不编码 level/zone/topic因为内容分类是可变的Phase 2 审计曾移动 25 道题的 level 边界。分类查询交给vault.db或grep ^level:即可「工具化比重命名便宜」。配套工具需求命令带过滤浏览全部问题vault ls [--track --level --zone --topic --status --in-chains]查看单题及链上下文vault show question-id端到端走一条链vault chain show chain-id确认无孤儿链引用vault check --strict铸造下一个空闲 IDvault new --track t五、Schema 字段填充现实schema 与语料高度匹配审计对 schema 允许的50 个字段逐一做了填充率统计核心结论是schema 非常贴合现实——必填字段 100% 填充可选字段在合理处填充。5.1 必填核心全部状态 100% 填充schema_version, id, track, level, zone, topic, competency_area, bloom_level, phase, title, scenario, question, status, provenance, requires_explanation, expected_time_minutes, validated, details (with realistic_solution common_mistake napkin_math)每个问题都携带这些字段。schema 的必填集合与现实完全一致。5.2 验证血缘字段published 100% / draft 0-2% —— 设计使然validation_status, validation_date, validation_model 97% overall math_status, math_date, math_model 85-93% overall math_verified 96%草稿为空是因为它们尚未经过验证。这个缺口是生命周期问题不是 schema 问题——与 interviews/vault/audit/README.md 描述的「语义评审用于验证已发布问题的质量」流程相印证。5.3 确实稀疏——但这是合理设计字段覆盖率稀疏原因chains25%仅 879 条链约 3 题/链——语料设计如此details.options/correct_index17%大多数题目是开放问答非选择题validation_issues16%仅当验证器发现问题时才出现tags5%主要是草稿语义不一致——见下visual0.3%视觉原型是刻意策展的validation_status_pro/validation_issues_pro4-5%仅 Claude-Opus-Pro 评审过的条目classification_review0.3%仅 31 条做过分类复核5.4 值得修复的异常tags语义混用状态tags填充率Published1.6%Draft99.7%草稿用tags做cohort 追踪如portfolio-loop-iteration-001、gemini-generated、target-specification-L5已发布条目几乎没有 tags。两条出路promotion 时剥离 cohort tags最干净——tags成为真正的面向用户字段把tags文档化为审计/cohort 面包屑字段当前现实——语义混杂但诚实。审计倾向方案 1。从源码看promotion 脚本 interviews/vault-cli/src/vault_cli/commands/promote.py 正是天然落点——它已负责status: published置位、provenance: llm-draft → llm-then-human-edited转换、authors追加等发布期变更。该脚本将草稿从vault/drafts/移动至vault/questions/并重写元数据字段剥离 cohort tags 只需在此处追加五行逻辑。六、三项低风险 Schema 改进6.1 收紧id正则新增软验证器现状id: range: string——什么都能过。提议id: range: string identifier: true required: true pattern: ^(cloud|edge|mobile|tinyml|global)(-[a-z][a-z0-9]*)?-[0-9]$ description: | track-NNNN for new content; track-cohort-NNNN tolerated for legacy items predating ID_SCHEMES.md v2.该模式拒绝未来的畸形 ID 而不破坏存量。审计指出当前约120 条违反此正则——即-anal-、-real-、-mast-、-desi-、-spec-、-impl-、-flue-、-opti-等 Bloom 区域 cohort例如cloud-exp2-anal-005模式接受-exp2-anal-005因为 cohort 允许含数字与连字符审计作者明确表示容忍。6.2 从 schema 中删除details.questionPydantic 调查显示零条使用details.question——顶层question字段已取代它。这个未使用的嵌套字段是死 schema。从源码印证在 interviews/vault-cli/src/vault_cli/models.py 的Details模型中question: str | None None仍作为可选字段存在约第 249 行而真正承载题干的是realistic_solution、common_mistake、napkin_math等字段该模型第 213-215 行——审计建议删除的正是这个从未被填充的question可选项。6.3 promotion 时清理tags在promote_validated.py即上述 promote.py中追加# Drop cohort breadcrumbs; preserve user-facing tags. COHORT_TAG_PREFIXES (portfolio-loop-, target-, gemini-, visual-archetype-, matplotlib-rendered, dot-rendered, gap-) d[tags] [t for t in d.get(tags, []) if not any(t.startswith(p) for p in COHORT_TAG_PREFIXES)]五行代码审计痕迹保留在提交历史中语料则被清理干净。七、明确不推荐的事项为了让建议边界清晰审计列出了考虑过但否决的方案❌添加track/topic/子目录——分类可变文件系统层级不可变ARCHITECTURE.md §3.3 有据❌添加track/level/或track/zone/子目录——同前且 v0.1 的尝试是有文档的灾难86 题丢失、cell 静默折叠❌把遗留 ID 重命名为干净格式——破坏 3,100 链引用、外部书签、论文、审计 JSONL❌放弃 LinkML——它是可靠选择一次代码生成即可产出 Pydantic SQL TS❌放弃逐题 YAML 改用 SQLite 作为源——v1.0 已因 diff 性、git blame、贡献者体验等原因否决❌添加topic_path派生字段——查询时计算即可无需 schema 变更。八、留给未来审计的保留项以下问题真实存在但不阻塞Cohort tags 漏过 promotion§6.3 可修复tags字段过载用户分类与审计 cohort 面包屑混用。可拆分为tagscohort但仅当 cohort 在 promotion 后仍需存续才值得做缺少顶层chains不变量schema 目前不约束一条链必须单 track。大概率没问题pre-commit 的vault check可以补充验证last_modified字段存在于 schema 但无处填充添加一个 pre-commit 钩子自动递增或直接删除该字段。这些都可以在 interviews/vault/TESTING.md、interviews/vault/REVIEWS.md 与 interviews/vault/CHANGELOG.md 的迭代体系中跟踪解决。九、净结论schema 与文件夹结构是良好的。它们体现了一次深思熟虑的 v0.1 → v1.0 重构这次重构从一次有文档的失败中学习。正确的动作不是重新设计而是应用三项定向清理为id加软正则硬规则^[a-z]-[a-z0-9-]$阻止非结构化 ID软警告^(cloud|edge|mobile|tinyml|global)-\d{4,}$面向新内容存量豁免删除details.question死字段promotion 时清理 cohort tags在promote.py中剥离 cohort 前缀保留用户可见 tags。其余保持原样。对于任何维护近万份结构化 YAML 语料的团队这份审计的决策框架都值得借鉴分类是可变的、应作为数据存在文件系统是不可变的、只承担寻址ID 一旦分配永不变更用验证器而非重命名来维护格式纪律。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
