StaffML 贡献指南参与 ML 系统面试题库 Vault 的编写、审核与发布全流程【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book本篇指南系统讲解如何向 StaffML —— 面向 ML 系统工程师的面试题库与站点位于仓库interviews/目录提交贡献。内容涵盖从克隆仓库到第一道题可见的完整快速上手流程、可贡献的七类内容、PR 前的校验红线、provenance内容来源诚实性要求、以及 CC-BY-NC-4.0 许可下的合规边界。读完你就能使用vaultCLI 安全地新增、修改、重新分类题目并通过 CI 与维护者审核最终进入可被学术引用的版本化发布产物。快速开始从克隆到第一道题可见StaffML 的贡献目标包含两大部分题库 Vaultinterviews/vault/问题语料与站点interviews/staffml/Next.js 应用。官方设定的目标是在一台全新机器上从克隆到看到自己的第一道题耗时不超过 10 分钟。# 1. 克隆仓库并进入 interviews 工作区 git clone https://github.com/harvard-edge/cs249r_book.git cd cs249r_book/interviews # 2. 安装 vault-cli需要 Python 3.12 pip install -e vault-cli/[dev] vault --version pytest vault-cli/tests/ # 3. 分阶段探索先看当前可用的子命令 # 阶段不同可用的子命令不同详见文末分阶段范围 vault --help # 始终可用——列出当前阶段已启用的子命令 # 4. 运行本地 API 垫片需先执行 vault build 生成 vault.db # 它从本地 vault.db 提供与生产 Worker 一致的 API 面 # 无需 Cloudflare 账号即可开发站点Phase 1 起可用 vault build # 产出 interviews/vault/vault.db vault api --db interviews/vault/vault.db --port 8002 # 5. 让站点对接本地 API cd staffml/ cp .env.example .env.local # 编辑 .env.localNEXT_PUBLIC_VAULT_APIhttp://localhost:8002 pnpm install pnpm dev # 访问 http://localhost:3000其中第 4 步的vault api是 ARCHITECTURE.md 中 H-17 项决议的落地通过共享类型包staffml/vault-types约束本地垫片与生产 Worker 返回的 JSON schema 完全一致。如果整个流程超过 10 分钟官方要求提交一个标题为 CONTRIBUTING.md getting-started friction 的 issue 反馈摩擦点。从源码看vaultCLI 是一个基于 Typer 的 Python 包入口见 main.py当前注册了 22 个子命令模块包括build、check、authoringnew/edit/rm/restore/move/renumber/mark-exemplar、release、stats、codegen、doctor、diff、promote、dup、generate、lint、ls、show、chain、audit等。vault --version与--help通过is_eagerTrue的 eager 回调在任何阶段都保证可用。可以贡献什么七类贡献入口贡献类型位置方式新题目vault/questions/track/level/zone/vault new修改题目同上vault edit id重新分类题目同上vault move id --to track/level/zone新主题topicvault/taxonomy.yaml提交 PR并在 EVOLUTION.md 中附 §7 条目网站 UXinterviews/staffml/src/Next.js如 staffml 中存在 AGENTS.md 请先阅读Worker APIinterviews/staffml-vault-worker/Phase 3Wrangler 项目Schema 演进vault/schema/按 EVOLUTION.md 提交 RFC 式 PR新增vault-cli子命令vault-cli/src/vault_cli/commands/必须附带测试与文档更新注意实际仓库中题目的物理布局已按 v1.1 架构演进为interviews/vault/questions/track/area/id.yamlARCHITECTURE.md §3.6分类信息track/level/zone/competency_area 等记录在 YAML 正文而非路径中vault check --strict会强制校验路径分片与 YAML 正文中的track/competency_area字段一致。vault new幕后发生了什么从 authoring.py 的实现可以确认一条vault new会依次执行先执行git pull --rebase --autostash origin降低并发分配 ID 的碰撞率可用--skip-rebase跳过仅限离线开发生成内容寻址 ID当前实际方案为track-yyyymm-4hex其中4hex取自sha256(title \n topic)的前 4 位十六进制——把 topic 纳入哈希可防止两个不同主题的同名题目哈希相同ID 方案细节见 ID_SCHEMES.md追加id-registry.yaml{id, created_at, created_by}逐行追加绝不重写id-registry.yaml 是只增日志CI 会拒绝任何删除或重排自动填充authors从git config user.email读取提交者身份用 Jinja 模板脚手架出 YAMLcommon_mistake与napkin_math字段预置了规范的 Markdown 加粗标记模板Pitfall/Rationale/Consequence 与 Assumptions/Calculations/Conclusion作者只需填充 TODO 内容相关约定见 AUTHORING.md 的 Markup conventions 一节打开$EDITOR编辑保存时立即做 schema 校验。如果校验失败错误会以注释块的形式注入到 YAML 文件顶部并重新打开编辑器默认最多重试--retries3次而不是抛出终端 traceback——这是 David R3-H1 的作者体验修复避免了编写途中被异常打断。工作流规范分支与提交独立工作从dev分支拉出git checkout -b feat/short-description dev一个逻辑变更对应一个分支提交保持原子性对 vault 变更严禁使用git add -A应显式git add interviews/vault/questions/...提交信息不附加Co-Authored-By标签也不写 made with tool 之类脚注读起来就是常规工程提交。打开 PR 前必须通过的检查vault check --strict # 不变量检查 pytest vault-cli/tests/ # 单元 集成 契约测试 vault codegen --check # LinkML ↔ Pydantic/DDL/TS 漂移检查Phase 1CI 会重复执行上述全部检查红 CI 会阻塞合并。其中vault codegen --check对应 ARCHITECTURE.md §13 的契约要求PR 作者本地跑 codegenCI 只做验证绝不推 follow-up 提交。PR 审核门槛语料 PR至少 1 位维护者审核CI 全绿代码 PRvault-cli、worker1 位审核CI 全绿Schema 演进 PR外部贡献者接入Phase 7后要求 2 位审核破坏性 Schema 变更必须附带vault-cli/migrations/下的迁移脚本。Provenance 诚实性一条正确性红线每一道题的provenance字段必须如实反映其生成方式它是闭合枚举human—— 人类从零编写llm-draft—— 由vault generate产出尚未经过人工审核llm-then-human-edited—— LLM 草稿经人工大幅修订最常见情形generation_meta.human_reviewed_at记录修订时间imported—— 来自外部来源如书籍、已发表论文来源需写入tags。把 LLM 内容误标为human属于正确性缺陷correctness bug而非风格问题。这一要求与vault mark-exemplar的门禁相互呼应从 authoring.py 的mark_exemplar_cmd实现看只有provenance human或provenance llm-then-human-edited且已设置human_reviewed_at的题目才允许移入vault/exemplars/即vault generate的范例池纯 LLM 草稿会被直接拒绝。作者归属vault new通过vault/contributors.yaml邮箱 → 昵称映射从git config user.email自动填充authors字段。要加入该映射表提交一个更新vault/contributors.yaml的 PR 即可。对于外部 PR必须提供 GPG/SSH 提交签名或与 GitHub 验证邮箱一致的提交身份——CI 会拒绝authors:声明与提交者身份不匹配的内容。样式规范单概念聚焦与真实硬件参数一道题只聚焦一个概念。好的 napkin math通常是加分信号事实大杂烩通常是坏味道使用真实硬件参数——以mlsysbook/constants.py和vault/schema/models.yaml注册表中的规范值为准论文引用只接受 URL 格式https://mlsysbook.ai/book/chapters/slugscenario场景字段为纯文本solution 与 napkin math 允许受限 Markdown KaTeX。内容格式校验在 ARCHITECTURE.md §5 有严格规定scenario拒绝原始 HTML禁止、、script、javascript:、data:Markdown 字段需通过 CommonMark 解析 允许列表details.resources[].url的 scheme 必须匹配^https://且name非空YAML 解析器做了 DoS 加固仅yaml.safe_load、文件 ≤256 KB、最大深度 10、禁用 YAML 别名、单文件解析限时 500ms。阻塞外部 PR 合并的四件事Provenance 造假——vault mark-exemplar或vault promote --reviewed-by的字段与 git 提交者不符篡改注册表——任何删除id-registry.yaml中行的提交。该注册表只增不改Schema 混用——同一 PR 内出现不同schema_version的题目CI 会拒绝混合版本未签字的 Schema 演进 PR——schema 升级需要 2 位维护者批准。配合vault promote id --reviewed-by git-user--reviewed-by默认取git config user.emailCI 会拒绝该值与促进提交的提交者不匹配的情况——这是提交者身份约束在代码层面的落地。分阶段范围不同 checkout 下可用的命令截至 Phase 0vault 流水线仍是脚手架状态尚未端到端运转。当前可用vault --version、vault --helppip install -e vault-cli/[dev]与pytest文档ARCHITECTURE.md、REVIEWS.md、TESTING.md、EVOLUTION.md 及本文件。后续阶段规划完整路线图见 ARCHITECTURE.md §14Phase 1new、edit、move、rm、restore、build、check、serve、apiYAML 拆分落地Phase 2publish 原语命令、paper 导出器重写、回滚对称性 CIPhase 3D1 Worker staffml/vault-types FTS5 负载测试门禁Phase 4网站切换 service worker 回滚演练Phase 5chain 揭示前指示器 埋点Phase 6About 页论文显要位置。外部贡献者对vault/questions/的贡献自 Phase 1 退出起才可行。这一分阶段设计与 CLI 架构一致按暴露原语、组合成产品的原则publish是由check、build、snapshot、migrations emit、export paper、tag组合而成的产物命令用户既可一条命令走完常规路径也可按需单独调用任意原语。调试利器稳定的退出码语义vault全系命令遵循稳定的退出码分类法定义见 exit_codes.py文档见 EXIT_CODES.md脚本可以安全地依赖退出码含义0成功1校验 / 不变量失败2用法错误坏 flag、缺参数3文件系统 / I/O 错误4网络 / D1 / Worker 错误5用户中止确认许可证CC-BY-NC-4.0 与商业使用边界interviews/vault/下的语料以CC-BY-NC-4.0许可发布见 vault/questions/LICENSE非商业用途可自由共享与改编但须注明出处商业用途用该语料训练付费产品、出售访问权限、围绕它构建付费服务需要版权方另行书面许可联系邮箱vjreddig.harvard.edu向语料提交贡献即视为按同样的 CC-BY-NC-4.0 条款提供不要提交你无权以该方式许可的内容。interviews/vault-cli/工具链是独立构件其许可沿用仓库历史状态不受上述语料许可覆盖。寻求帮助的正确姿势架构问题→ 阅读 ARCHITECTURE.md为什么当初这么决定→ 查阅 REVIEWS.md大多数非显然决策都能对应到某条评审发现这是 bug 还是预期行为→ 开一个 issue附上你运行的命令与输出维护者即可快速定位。除此之外vault/README.md 提供了vault build/vault check --strict/vault stats/vault doctor/vault verify 0.9.0/vault api --port 8002的日常用法速查TESTING.md 与 CHANGELOG.md 记录了测试计划与演进历史可作为深入参与前的补充阅读。无论你是想贡献第一道题、修复现有题目、推动 schema 演进还是参与站点与 Worker 开发遵循本指南中的 provenance 诚实性、原子提交、显式git add与 CI 前置校验就能让每一次 PR 顺畅进入审核与发布流水线。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 StaffML 贡献指南：参与 ML 系统面试题库 Vault 的编写、审核与发布全流程
StaffML 贡献指南参与 ML 系统面试题库 Vault 的编写、审核与发布全流程【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book本篇指南系统讲解如何向 StaffML —— 面向 ML 系统工程师的面试题库与站点位于仓库interviews/目录提交贡献。内容涵盖从克隆仓库到第一道题可见的完整快速上手流程、可贡献的七类内容、PR 前的校验红线、provenance内容来源诚实性要求、以及 CC-BY-NC-4.0 许可下的合规边界。读完你就能使用vaultCLI 安全地新增、修改、重新分类题目并通过 CI 与维护者审核最终进入可被学术引用的版本化发布产物。快速开始从克隆到第一道题可见StaffML 的贡献目标包含两大部分题库 Vaultinterviews/vault/问题语料与站点interviews/staffml/Next.js 应用。官方设定的目标是在一台全新机器上从克隆到看到自己的第一道题耗时不超过 10 分钟。# 1. 克隆仓库并进入 interviews 工作区 git clone https://github.com/harvard-edge/cs249r_book.git cd cs249r_book/interviews # 2. 安装 vault-cli需要 Python 3.12 pip install -e vault-cli/[dev] vault --version pytest vault-cli/tests/ # 3. 分阶段探索先看当前可用的子命令 # 阶段不同可用的子命令不同详见文末分阶段范围 vault --help # 始终可用——列出当前阶段已启用的子命令 # 4. 运行本地 API 垫片需先执行 vault build 生成 vault.db # 它从本地 vault.db 提供与生产 Worker 一致的 API 面 # 无需 Cloudflare 账号即可开发站点Phase 1 起可用 vault build # 产出 interviews/vault/vault.db vault api --db interviews/vault/vault.db --port 8002 # 5. 让站点对接本地 API cd staffml/ cp .env.example .env.local # 编辑 .env.localNEXT_PUBLIC_VAULT_APIhttp://localhost:8002 pnpm install pnpm dev # 访问 http://localhost:3000其中第 4 步的vault api是 ARCHITECTURE.md 中 H-17 项决议的落地通过共享类型包staffml/vault-types约束本地垫片与生产 Worker 返回的 JSON schema 完全一致。如果整个流程超过 10 分钟官方要求提交一个标题为 CONTRIBUTING.md getting-started friction 的 issue 反馈摩擦点。从源码看vaultCLI 是一个基于 Typer 的 Python 包入口见 main.py当前注册了 22 个子命令模块包括build、check、authoringnew/edit/rm/restore/move/renumber/mark-exemplar、release、stats、codegen、doctor、diff、promote、dup、generate、lint、ls、show、chain、audit等。vault --version与--help通过is_eagerTrue的 eager 回调在任何阶段都保证可用。可以贡献什么七类贡献入口贡献类型位置方式新题目vault/questions/track/level/zone/vault new修改题目同上vault edit id重新分类题目同上vault move id --to track/level/zone新主题topicvault/taxonomy.yaml提交 PR并在 EVOLUTION.md 中附 §7 条目网站 UXinterviews/staffml/src/Next.js如 staffml 中存在 AGENTS.md 请先阅读Worker APIinterviews/staffml-vault-worker/Phase 3Wrangler 项目Schema 演进vault/schema/按 EVOLUTION.md 提交 RFC 式 PR新增vault-cli子命令vault-cli/src/vault_cli/commands/必须附带测试与文档更新注意实际仓库中题目的物理布局已按 v1.1 架构演进为interviews/vault/questions/track/area/id.yamlARCHITECTURE.md §3.6分类信息track/level/zone/competency_area 等记录在 YAML 正文而非路径中vault check --strict会强制校验路径分片与 YAML 正文中的track/competency_area字段一致。vault new幕后发生了什么从 authoring.py 的实现可以确认一条vault new会依次执行先执行git pull --rebase --autostash origin降低并发分配 ID 的碰撞率可用--skip-rebase跳过仅限离线开发生成内容寻址 ID当前实际方案为track-yyyymm-4hex其中4hex取自sha256(title \n topic)的前 4 位十六进制——把 topic 纳入哈希可防止两个不同主题的同名题目哈希相同ID 方案细节见 ID_SCHEMES.md追加id-registry.yaml{id, created_at, created_by}逐行追加绝不重写id-registry.yaml 是只增日志CI 会拒绝任何删除或重排自动填充authors从git config user.email读取提交者身份用 Jinja 模板脚手架出 YAMLcommon_mistake与napkin_math字段预置了规范的 Markdown 加粗标记模板Pitfall/Rationale/Consequence 与 Assumptions/Calculations/Conclusion作者只需填充 TODO 内容相关约定见 AUTHORING.md 的 Markup conventions 一节打开$EDITOR编辑保存时立即做 schema 校验。如果校验失败错误会以注释块的形式注入到 YAML 文件顶部并重新打开编辑器默认最多重试--retries3次而不是抛出终端 traceback——这是 David R3-H1 的作者体验修复避免了编写途中被异常打断。工作流规范分支与提交独立工作从dev分支拉出git checkout -b feat/short-description dev一个逻辑变更对应一个分支提交保持原子性对 vault 变更严禁使用git add -A应显式git add interviews/vault/questions/...提交信息不附加Co-Authored-By标签也不写 made with tool 之类脚注读起来就是常规工程提交。打开 PR 前必须通过的检查vault check --strict # 不变量检查 pytest vault-cli/tests/ # 单元 集成 契约测试 vault codegen --check # LinkML ↔ Pydantic/DDL/TS 漂移检查Phase 1CI 会重复执行上述全部检查红 CI 会阻塞合并。其中vault codegen --check对应 ARCHITECTURE.md §13 的契约要求PR 作者本地跑 codegenCI 只做验证绝不推 follow-up 提交。PR 审核门槛语料 PR至少 1 位维护者审核CI 全绿代码 PRvault-cli、worker1 位审核CI 全绿Schema 演进 PR外部贡献者接入Phase 7后要求 2 位审核破坏性 Schema 变更必须附带vault-cli/migrations/下的迁移脚本。Provenance 诚实性一条正确性红线每一道题的provenance字段必须如实反映其生成方式它是闭合枚举human—— 人类从零编写llm-draft—— 由vault generate产出尚未经过人工审核llm-then-human-edited—— LLM 草稿经人工大幅修订最常见情形generation_meta.human_reviewed_at记录修订时间imported—— 来自外部来源如书籍、已发表论文来源需写入tags。把 LLM 内容误标为human属于正确性缺陷correctness bug而非风格问题。这一要求与vault mark-exemplar的门禁相互呼应从 authoring.py 的mark_exemplar_cmd实现看只有provenance human或provenance llm-then-human-edited且已设置human_reviewed_at的题目才允许移入vault/exemplars/即vault generate的范例池纯 LLM 草稿会被直接拒绝。作者归属vault new通过vault/contributors.yaml邮箱 → 昵称映射从git config user.email自动填充authors字段。要加入该映射表提交一个更新vault/contributors.yaml的 PR 即可。对于外部 PR必须提供 GPG/SSH 提交签名或与 GitHub 验证邮箱一致的提交身份——CI 会拒绝authors:声明与提交者身份不匹配的内容。样式规范单概念聚焦与真实硬件参数一道题只聚焦一个概念。好的 napkin math通常是加分信号事实大杂烩通常是坏味道使用真实硬件参数——以mlsysbook/constants.py和vault/schema/models.yaml注册表中的规范值为准论文引用只接受 URL 格式https://mlsysbook.ai/book/chapters/slugscenario场景字段为纯文本solution 与 napkin math 允许受限 Markdown KaTeX。内容格式校验在 ARCHITECTURE.md §5 有严格规定scenario拒绝原始 HTML禁止、、script、javascript:、data:Markdown 字段需通过 CommonMark 解析 允许列表details.resources[].url的 scheme 必须匹配^https://且name非空YAML 解析器做了 DoS 加固仅yaml.safe_load、文件 ≤256 KB、最大深度 10、禁用 YAML 别名、单文件解析限时 500ms。阻塞外部 PR 合并的四件事Provenance 造假——vault mark-exemplar或vault promote --reviewed-by的字段与 git 提交者不符篡改注册表——任何删除id-registry.yaml中行的提交。该注册表只增不改Schema 混用——同一 PR 内出现不同schema_version的题目CI 会拒绝混合版本未签字的 Schema 演进 PR——schema 升级需要 2 位维护者批准。配合vault promote id --reviewed-by git-user--reviewed-by默认取git config user.emailCI 会拒绝该值与促进提交的提交者不匹配的情况——这是提交者身份约束在代码层面的落地。分阶段范围不同 checkout 下可用的命令截至 Phase 0vault 流水线仍是脚手架状态尚未端到端运转。当前可用vault --version、vault --helppip install -e vault-cli/[dev]与pytest文档ARCHITECTURE.md、REVIEWS.md、TESTING.md、EVOLUTION.md 及本文件。后续阶段规划完整路线图见 ARCHITECTURE.md §14Phase 1new、edit、move、rm、restore、build、check、serve、apiYAML 拆分落地Phase 2publish 原语命令、paper 导出器重写、回滚对称性 CIPhase 3D1 Worker staffml/vault-types FTS5 负载测试门禁Phase 4网站切换 service worker 回滚演练Phase 5chain 揭示前指示器 埋点Phase 6About 页论文显要位置。外部贡献者对vault/questions/的贡献自 Phase 1 退出起才可行。这一分阶段设计与 CLI 架构一致按暴露原语、组合成产品的原则publish是由check、build、snapshot、migrations emit、export paper、tag组合而成的产物命令用户既可一条命令走完常规路径也可按需单独调用任意原语。调试利器稳定的退出码语义vault全系命令遵循稳定的退出码分类法定义见 exit_codes.py文档见 EXIT_CODES.md脚本可以安全地依赖退出码含义0成功1校验 / 不变量失败2用法错误坏 flag、缺参数3文件系统 / I/O 错误4网络 / D1 / Worker 错误5用户中止确认许可证CC-BY-NC-4.0 与商业使用边界interviews/vault/下的语料以CC-BY-NC-4.0许可发布见 vault/questions/LICENSE非商业用途可自由共享与改编但须注明出处商业用途用该语料训练付费产品、出售访问权限、围绕它构建付费服务需要版权方另行书面许可联系邮箱vjreddig.harvard.edu向语料提交贡献即视为按同样的 CC-BY-NC-4.0 条款提供不要提交你无权以该方式许可的内容。interviews/vault-cli/工具链是独立构件其许可沿用仓库历史状态不受上述语料许可覆盖。寻求帮助的正确姿势架构问题→ 阅读 ARCHITECTURE.md为什么当初这么决定→ 查阅 REVIEWS.md大多数非显然决策都能对应到某条评审发现这是 bug 还是预期行为→ 开一个 issue附上你运行的命令与输出维护者即可快速定位。除此之外vault/README.md 提供了vault build/vault check --strict/vault stats/vault doctor/vault verify 0.9.0/vault api --port 8002的日常用法速查TESTING.md 与 CHANGELOG.md 记录了测试计划与演进历史可作为深入参与前的补充阅读。无论你是想贡献第一道题、修复现有题目、推动 schema 演进还是参与站点与 Worker 开发遵循本指南中的 provenance 诚实性、原子提交、显式git add与 CI 前置校验就能让每一次 PR 顺畅进入审核与发布流水线。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考