StaffML Vault 共享类型包（@staffml/vault-types）技术指南：Schema v1.0 类型契约与跨端集成实践

StaffML Vault 共享类型包staffml/vault-types技术指南Schema v1.0 类型契约与跨端集成实践【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book导读staffml/vault-types是 StaffML 面试题仓库位于本仓库interviews/目录下中负责共享 TypeScript 类型契约的零依赖类型包其全部实体定义集中在 interviews/staffml-vault-types/index.ts。它把权威的 LinkML 题目 Schemaschema_version: 1.0与 Python 枚举翻译成纯类型供题库站点interviews/staffml/与 Cloudflare Workerinterviews/staffml-vault-worker/通过 pnpm workspace 协议统一消费。读完本文你将掌握该包的枚举域、Question/Manifest/Visual等核心类型结构、它与其他端点的镜像/消费关系以及它在 v1.0 中引入的人类审核Human Review等关键字段。包定位为什么需要一个零依赖的共享类型包interviews/staffml-vault-types/目录下没有任何package-lock.json。根据 README.md 的说明这是因为该包没有任何 npm 运行时依赖只包含类型定义只有当后续引入依赖或需要可复现安装的发布流程时才需要新增 lockfile。从 package.json 可以看到包的完整元信息namestaffml/vault-typesprivate: true不发布到公共 registryversion0.1.0main/types均指向index.ts——即入口即类型main与types指向同一文件type: module包内代码按 ESM 语义处理description明确指出包随每次 vault 发布进行版本管理Versioned with each vault release。这种纯类型、零依赖的设计使得两端站点与 Worker可以共享同一份类型契约而不引入任何运行时开销也不会造成依赖树的膨胀或版本冲突。权威 Schema 的来源与对齐关系index.ts文件头部的注释揭示了类型的权威来源interviews/staffml-vault-types/index.tsAligned with interviews/vault/schema/question_schema.yaml (LinkML, the authoritative schema) and interviews/vault/schema/enums.py.也就是说权威 Schema是 LinkML 格式的question_schema.yamlv1.0 约定Python 枚举定义在enums.pyTypeScript 中的各枚举联合类型与之对齐注释还提到CI drift checks against the Python enums计划在后续 PR 中落地即用 CI 校验 TS 枚举与 Python 枚举是否漂移drift。Worker 侧的镜像类型文件 interviews/staffml-vault-worker/src/types.ts 头部同样声明它是staffml/vault-types的Mirror镜像由 LinkML 代码生成并在 Phase 3 通过 pnpm workspace 协议改用共享包对应ARCHITECTURE.md§13 中针对问题 H-2 的修复。这一关系印证了共享类型包是单一事实来源的中间层Worker 镜像只是过渡期的产物。说明interviews/vault/schema/目录在当前仓库快照中并未直接列出index.ts头部注释指向该路径属于权威来源的声明本文以仓库内可确认的实体index.ts、worker 镜像、真实题目 YAML为准。枚举域Enums题目分类的受控词表index.ts用 TypeScript 联合类型union types定义了题目生命周期中所有的受控枚举域。这些枚举直接决定了题目的分类轴、状态机与来源标记。四轴分类相关枚举export type Track cloud | edge | mobile | tinyml | global; export type Level L1 | L2 | L3 | L4 | L5 | L6; export type Zone | recall | analyze | design | implement | fluency | diagnosis | specification | optimization | evaluation | realization | mastery; export type BloomLevel | remember | understand | apply | analyze | evaluate | create; export type Phase training | inference | both;Track题目所属的技术栈/部署域对应仓库中的interviews/vault/questions/track/目录划分cloud / edge / mobile / tinyml外加全局题globalLevel难度分级L1到L5另有最高档L6L6 及以上属于半开区间式表达Zone11 个取值的能力域/题型域从基础的recall、analyze到optimization、mastery覆盖回忆—分析—设计—实现—熟练—诊断—规格—优化—评估—落地—精通的完整能力谱系BloomLevel布鲁姆教育目标分类学修订版的六层动词remember / understand / apply / analyze / evaluate / create用于标注题目所考察的认知层级Phase机器学习生命周期阶段仅三个取值training训练、inference推理、both两者皆涉及。工作流与来源相关枚举export type Status draft | published | flagged | archived | deleted; export type Provenance | human | llm-draft | llm-then-human-edited | imported; export type HumanReviewStatus | not-reviewed | verified | flagged | needs-rework;Status题目的生命周期状态机——草稿 → 已发布 → 被标记 → 归档 → 删除Provenance题目的来源标记区分纯人工human、LLM 初稿llm-draft、LLM 初稿后人工编辑llm-then-human-edited以及批量导入imported。这是对生成式内容治理的关键元数据HumanReviewStatusv1.0 新引入的人类审核状态详见下文HumanReview接口。嵌套类型从资源到可视化附件的结构化设计在Question主接口之前index.ts定义了 5 个嵌套类型用于承载题目的组成部分ChainRef链式题目引用export interface ChainRef { id: string; position: number; }id指向题库中某道题如cloud-0231position表示该题在链chain中的顺序位置。题目通过chains数组可以同时属于多条链见Question接口中的chains?: ChainRef[]。Resource外部参考资料export interface Resource { name: string; url: string; }提供题目相关的参考资料条目名称 URL挂在QuestionDetails.resources下。HumanReviewv1.0 的人类审核记录export interface HumanReview { status: HumanReviewStatus; by?: string | null; date?: string | null; notes?: string | null; }这是 v1.0 引入的关键治理字段status使用受控枚举not-reviewed/verified/flagged/needs-reworkby/date/notes分别记录审核人、审核日期与备注均可为空null。在真实题目数据中该结构体现为human_reviewed: status: not-reviewed by: null date: null notes: null示例见 interviews/vault/questions/cloud/architecture/cloud-0231.yaml 第 42-46 行。Visual 与 VisualKind可视化附件v0.1.2 加固export type VisualKind svg; export interface Visual { kind: VisualKind; path: string; // 仅文件名位于 interviews/vault/visuals/track/ alt: string; // 无障碍描述≥10 字符≤400 字符 caption: string; // 面向作者的图注≥5 字符≤120 字符 }Visual在 v0.1.2 被加固hardenedkind是封闭枚举当前仅支持svgpath必须匹配^[a-z0-9-]\.svg$纯小写字母数字加连字符、以.svg结尾且只存裸文件名实际文件位于interviews/vault/visuals/track/目录下alt无障碍描述至少 10 字符、最多 400 字符caption图注至少 5 字符、最多 120 字符注释明确指出服务端由 Pydantic 强制校验这些约束该接口只是练习页practice page消费的形状shape。也就是说TS 类型只描述练习页该拿到什么真正的约束由服务端 Pydantic 模型兜底执行——类型契约与运行时校验各司其职。QuestionDetails解题细节容器export interface QuestionDetails { realistic_solution: string; // 正解/现实解法 common_mistake?: string; // 常见误区可选 napkin_math?: string; // 估算/纸上计算可选 resources?: Resource[]; // 参考资料可选 options?: string[]; // 选项用于选择题 correct_index?: number; // 正确选项下标 }从真实题目cloud-0231.yaml可以看到realistic_solution给出工程级正解如 KV-Cache 内存墙分析common_mistake以结构化 Markdown 记录陷阱—理由—后果napkin_math则以假设/约束 → 计算 → 结论三段式组织纸上估算。options/correct_index则支持单选题形态。Question 主接口v1.0 题目的完整形态export interface Question { schema_version: string; // 1.0 id: string; // 4-axis classification track: Track; level: Level; zone: Zone; topic: string; competency_area: string; bloom_level?: BloomLevel; phase?: Phase; // Content title: string; scenario: string; question?: string; visual?: Visual; details: QuestionDetails; // Workflow status: Status; provenance: Provenance; requires_explanation?: boolean; expected_time_minutes?: number; deletion_reason?: string; // Chain membership (plural — a question may belong to multiple chains) chains?: ChainRef[]; // LLM validation validated?: boolean; validation_status?: string; validation_date?: string; validation_model?: string; // Math validation (separate LLM pass) math_verified?: boolean; math_status?: string; math_date?: string; math_model?: string; // Human review (new in v1.0) human_reviewed?: HumanReview; // Free-form classification_review?: string; authors?: string[]; tags?: string[]; created_at?: string; updated_at?: string; last_modified?: string; }Question接口可以归纳为六个区块版本与标识schema_version约定为1.0与全局唯一id四轴分类4-axis classificationtrack、level、zone三个受控枚举轴加topic主题、competency_area能力域以及可选的bloom_level与phase内容title、scenario场景、可选的question问题正文、可选的visual可视化附件以及必填的details工作流状态status、provenance以及可选的requires_explanation、expected_time_minutes、deletion_reason质量验证三组并行的验证轨道——LLM 通用验证validated/validation_status/validation_date/validation_model、独立的数学验证 passmath_verified/math_status/math_date/math_model、以及 v1.0 新增的人类审核human_reviewed。这体现了LLM 初筛 数学复核 人工把关的三级质量体系自由元数据classification_review分类复核意见、authors、tags、created_at、updated_at、last_modified。与真实 YAML 数据的逐字段印证以 interviews/vault/questions/cloud/architecture/cloud-0231.yaml 为样本对照schema_version: 1.0 id: cloud-0231 track: cloud level: L4 zone: optimization topic: attention-scaling competency_area: architecture bloom_level: analyze phase: both title: The KV-Cache Context Explosion scenario: You are serving a Llama-3 8B model. ... status: published provenance: imported requires_explanation: false expected_time_minutes: 10 validated: true validation_status: OK validation_date: 2026-04-01 validation_model: gemini-2.5-flash math_verified: true math_status: CORRECT math_date: 2026-04-03 math_model: gemini-3.1-pro-preview human_reviewed: status: not-reviewed可见真实数据完整覆盖了类型契约中的分类轴、内容、工作流与三级验证字段index.ts中标注为可选的字段如question、visual在该样本中按需省略——这正是 TS 可选标记?对 YAML 稀疏结构的精确建模。Manifest 与 API 客户端选项发布清单与调用端配置Manifest发布清单export interface Manifest { release_id: string; release_hash: string; schema_version: string; // 1.0 policy_version: string; published_count: number; schema_fingerprint_ok: boolean; }Manifest描述一次 vault 发布的快照release_id发布号与release_hash内容哈希用于版本可追溯schema_version固定为1.0policy_version记录治理策略版本published_count为已发布题目数量schema_fingerprint_ok表示 schema 指纹校验是否通过。Worker 侧镜像 interviews/staffml-vault-worker/src/types.ts 中的Manifest接口与之逐字段一致并配套Env环境变量中的SCHEMA_FINGPRINT源码中拼写为SCHEMA_FINGERPRINT与缓存 TTL 配置CACHE_TTL_MANIFEST等。VaultApiClientOptions客户端容错配置export interface VaultApiClientOptions { release: string; retry?: { attempts: number; backoff: exponential | linear; jitter?: boolean }; circuitBreaker?: { failThreshold: number; resetMs: number }; headers?: Recordstring, string; }该接口为 vault API 客户端提供配置约定必填release目标发布可选retry支持指数/线性退避并可加 jitter抖动防惊群可选circuitBreaker支持熔断失败阈值 重置毫秒数headers用于注入自定义请求头。跨端集成pnpm workspace 协议与消费方式站点侧 interviews/staffml/tsconfig.json 中的 paths 映射展示了实际的消费方式staffml/vault-types: [ ../staffml-vault-types/index.ts ]即通过路径别名把staffml/vault-types直接指向共享包入口index.ts从而在 TypeScript 编译期共享类型。而index.ts头部注释与 Worker 镜像注释共同说明站点与 Worker 都通过 pnpm workspace 协议引入该包interviews/staffml-vault-worker/package.json中未重复声明该依赖符合 workspace 依赖提升/隐式解析的约定。关键设计要点与工程启示类型即契约Schema 单一事实来源index.ts是 LinkML 权威 Schemav1.0与 Python 枚举在 TS 侧的投影Worker 的types.ts仅是过渡期镜像最终方向是统一消费共享包并通过 CI drift check 防止枚举漂移。零依赖、纯类型、随发布版本化main/types均指向index.ts无 lockfile、无运行时依赖包版本当前 0.1.0与每次 vault 发布绑定保证站点与 Worker 拿到同一份契约。封闭枚举 服务端兜底校验VisualKind仅svg、path有正则约束、alt/caption有长度约束且由服务端 Pydantic 强制执行TS 类型负责形状契约运行时校验负责数据安全两者分层清晰。三级质量验证轨道LLM 通用验证、独立数学验证、人类审核并行存在v1.0 起并通过human_reviewed字段与 LLM 验证解耦——HumanReviewStatus与validated是两套独立的状态机。多链归属与稀疏可选字段一道题可同时属于多条链chains: ChainRef[]真实 YAML 中大量字段按需省略TS 的可选标记精确建模了这一稀疏结构。延伸阅读类型包入口interviews/staffml-vault-types/index.ts包元信息interviews/staffml-vault-types/package.jsonWorker 侧镜像类型interviews/staffml-vault-worker/src/types.ts站点消费配置interviews/staffml/tsconfig.json真实题目数据样本interviews/vault/questions/cloud/architecture/cloud-0231.yaml题库目录interviews/vault/questions/cloud / edge / mobile / tinyml / global 五个 track与Track枚举一一对应【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考