Open Notebook 发布门禁Release Gates解析人机协作的权限边界与 GO/NO-GO 判定机制【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook导读本文聚焦 Open Notebook开源 Notebook LM 实现在 v1.11.0 后确立、并在 v1.12.0~v1.14.0 持续打磨的发布门禁Gates契约——即一次发布过程中哪些操作可以由 Agent 自主完成、哪些必须经过 owner 明确授权、哪些永远不允许发生。该契约是.github/RELEASE_PROCESS.md置信度流程Confidence Process的配套护栏读者学完后将掌握一套可复用的三层权限模型 复测策略 GO/NO-GO 判据并理解它与 A/B/C 测试矩阵、镜像门Image Gate、CI 发布工作流之间的咬合关系。从 v1.11.0 沉淀下来的安全发布契约Gate 在软件工程中通常指卡点未通过就不放行。Open Notebook 的发布门禁则更进一步——它不只卡质量还卡权限。仓库中 .agents/skills/release/gates.md 开头就点明了这份文件的定位The contract that made v1.11.0 safe. When in doubt, ask — a blocked action is feedback, not an obstacle to route around.这是一份让 v1.11.0 安全落地的契约。拿不准就问——一次被拦下的操作是反馈而不是需要绕行的障碍。这段表述揭示了这个项目的两个核心理念发布是被编排出来的而不是点按钮。整套流程由.agents/skills/release/SKILL.md定义的 Release Orchestrator发布编排器技能驱动它把一个发布拆成 Phase 0 ~ Phase 9 十个阶段并在各阶段之间插入人工闸门human gate。挡路 ≠ 障碍。被门禁拦下的动作是对当前上下文如是否已拿到授权的反馈信号正确的做法是暂停并向 owner 询问而不是想方设法绕过门禁。这套门禁并不孤立存在它的上层是 .github/RELEASE_PROCESS.md流程的事实来源source of truth编排顺序与精确命令在 .agents/skills/release/SKILL.md 中而 SKILL.md 在每次发布开始时都会要求编排器先读 gates.md。也就是说gates.md 定义了整个编排过程中什么能碰、什么不能碰的底线。从源码结构看gates.md 属于.agents/skills/release/技能包的一部分与test-matrix.mdA/B/C 测试矩阵、runbook.md切版与发布阶段的精确命令、comms-templates.md发布公告模板并列共同构成一个完整的发布编排器知识包。门禁的三种授权层级gates.md 将发布期间的一切操作划分为三个层级从可自主执行到永不执行边界清晰且逐层收紧。第一层可自主执行一旦发布运行已在进行中在发布会话release run正式启动之后以下操作无需逐次询问即可执行可自主操作说明运行任意测试、构建、探测或分析包括uv run pytest tests/、ruff check .、uv run python -m mypy .、前端 lint/test/build 等启动/停止本地开发服务例如本地 dev 栈database → api → worker → frontend的启停创建分支、提交、打开 PR代码仓库中的所有变更都必须走 PRbranch → PR → CI → merge派生子代理subagents如 smoke-e2e、investigation问题调查、fixes修复等专项代理本地构建/拉取 Docker 镜像运行 release-test 测试框架和 RC stack以push_latestfalse派发Build and ReleaseCI 工作流只推版本标签不推v1-latest——这是约定好的预验证推送关键洞察最后一个动作是整套门禁设计的精髓——推版本镜像与推 latest 标签被拆成了两个不同级别的操作。CI 工作流 .github/workflows/build-and-release.yml 通过一个push_latest布尔入参控制是否追加v1-latest标签只有当push_latesttrue、或触发事件是非预发布non-prerelease的 GitHub Release published时v1-latest才会被加到 tag 列表里。于是发布方可以放心地先推送只带版本号的镜像做最终验证Phase 5.3等所有门禁通过后再触发真正的公开发布。第二层需要 owner 在会话内明确授权动作为什么需要授权合并你自己 authored 的 PR需要双人评审two-party review每次会话询问一次如merge when clean?并遵守答案发布 GitHub Release公开动作会触发v1-latest的推送——这是不归路point of no return任何会推送v1-latest的操作用户会立刻收到该版本影响所有存量部署创建 GitHub Issues外部可见的产物owner 未必想要批量给 issue 打released标签对共享状态的大规模修改触碰 owner 的开发数据只能在副本上工作export/import绝不挂载或改写原始数据值得展开的是最后一行——数据隔离原则。runbook 中给出了精确的操作路径在 Phase 6 的 RC stack 验证环节编排器需要从正在运行的SurrealDB 实例中导出数据副本docker exec container /surreal export ...然后通过make release-stack TAGver DUMP/tmp/dev-dump.surql启动带真实数据副本的可浏览栈。原点在于owner 的 dev 数据里可能包含加密凭证等敏感内容任何测试性操作都不得污染原件。这里有一个反复出现的经验教训在 .github/RELEASE_PROCESS.md 的 Known Gotchas 中有记载v1.12.0 曾因测试套件直接写入了真实开发数据库而泄漏 48 条Test前缀的凭证。为此Phase 2bucket A 执行专门加入了Dev-DB leak check在跑后端测试套件前后对每个表尤其是 credentials做记录数快照计数出现差异即说明有测试在污染在线数据库。第三层永远不允许Never以下行为没有例外不做任何灰度直接推送到 main——所有变更必须走 PR 流程用发布 prerelease/release 来绕过被卡住的步骤——把发布动作当作解围手段是绝对禁忌带着失败的检查标记阶段完成。gates.md 的原话值得引用GO with known issues is worse than a NO-GO that catches problems before users do带着已知问题放行比在问题到达用户之前就拦截下来更糟糕。每个修复合并后的复测策略Re-test Policy发布进入修复循环fix loopSKILL.md 的 Phase 4后每次合并一个修复 PR都要按影响面决定复测范围而不是无脑全量重跑复测对象触发条件廉价套件pytest lint 前端测试/构建总是always执行smoke-e2e / 镜像门仅当该修复触及它们所覆盖的代码区域时owner 的手动验证项仅当该修复触及 owner 已验证的功能时最终镜像门Phase 5.3始终在最终发布工件exact release artifact上运行这套策略的工程理性很直白廉价套件是回归底线必须无条件全跑而重型的 e2e、镜像构建与人工验证成本高昂若修复根本不涉及相应代码路径重复执行纯属浪费。但最后一条是硬性约束——无论中间复测了多少次最终的镜像门必须针对将要发布的那一个镜像来跑杜绝验证的是 A 镜像、发布的是 B 镜像这类时空错位。GO/NO-GO一次发布凭什么算合格gates.md 给出了简洁但完整的 GO 判据。一次发布只有在同时满足以下所有条件时才判定为 GObucket A 全绿——自动化测试桶后端全量、ruff、mypy 零错误、前端 lint/test/production build、smoke-e2e、定向探测全部通过镜像门绿色fresh upgrade——全新安装与升级两条路径都在真实容器上验证通过bucket C 由 owner 签字确认——涉及真实凭证、真实 TTS、视觉/UX 判断的人工验证桶得到 owner 放行无未关闭的发布回归发现no open release-regression findingsDependabot 高危告警已解决或被显式接受。这份判据的意义在于它把发布从主观感觉变成了可核验的清单。任何一项不满足就是 NO-GO而 NO-GO 不是失败——按 gates.md 的价值观它是一个在伤害用户之前捕获问题的机会。值得注意的是 bucket C 并不是补考而是提前并行启动的。SKILL.md 的 Phase 3 明确要求把 bucket C 清单交给 owner 并行测试别让 owner 在最后变成瓶颈。test-matrix.md 也强调 bucket C 要 deliver 成带预期结果的具体清单并且要根据实际变更内容和 owner 实际拥有的凭证来定制GET /api/credentials可以告诉你 owner 有哪些真实凭证可用。门禁背后的完整发布流程十个阶段的时间线为了说清 gates 在什么时机被触发有必要对照 .agents/skills/release/SKILL.md 勾勒一次发布的时间线。整个流程要求在单一会话内完成用 Task 工具跟踪各阶段状态以便 owner 看到进度所有仓库变更一律走 PR绝不直接推送 main。阶段内容相关门禁/产物Phase 0范围与 Changelog 审计git fetch --tags、对比git log last-tag..origin/main与 CHANGELOG 的[Unreleased]段、检查 Dependabot 高危告警Changelog 缺口一律补 PRPhase 1依据实际 diff 实例化风险测试矩阵test-matrix.md每个变更映射到 A/B/C 桶先与 owner 对齐矩阵再执行Phase 2执行 bucket A后端三件套、前端三件套、smoke-e2e、Dev-DB leak check、定向探测廉价套件全绿Phase 3镜像门启动 bucket C 交办make docker-build-local后make release-test TAGver OLD_TAGprevowner 并行跑 bucket CPhase 4修复循环复现 → 根因 → 带回归测试的聚焦 PR → CI → 按 gates.md 合并每次合并后按复测策略重测Phase 5切版Cutbumppyproject.toml 给 Changelog 段落标注日期 → merge →make tag→ 从最终 main 重建镜像并重跑镜像门 → CI 推版本镜像push_latestfalse版本镜像就位但v1-latest未动Phase 6推送镜像验证人工门make release-stack TAGver [DUMPdump]提供可浏览 RC 栈owner 用真实数据副本走核心流程无 owner GO 不得继续Phase 7发布人工门按 comms-templates.md 起草 release notesThanks 段落强制→ owner 审核 →明确 GO 后gh release create ... --latest→ 盯v1-latest推送并核验 manifests公开可见、不可撤销Phase 8清理make release-stack-down、移除临时 dump 与数据目录、确保 main 上git status干净、无残留测试容器环境归零Phase 9Retro永远执行问 owner 这个流程哪里该改进并当场把被采纳的改进写回文档与技能文件流程持续进化对照这张表gates.md 的三层授权就变得非常立体Phase 0~5 的绝大部分技术操作测试、分支、PR、本地镜像、触发 CI 预验证推送落在可自主执行层Phase 6 与 Phase 7是两个显式的人工门——前者是 owner 对 RC 栈的签字后者是对 GitHub Release 的最终放行而合并自己写的 PR给 issue 批量打标签这类贯穿全程但涉及共享状态或双人评审的动作单独拎出来要求授权。A/B/C 测试矩阵如何为门禁提供证据GO/NO-GO 判据中bucket A 全绿和bucket C owner 签字不是空洞的口号.agents/skills/release/test-matrix.md 把它们拆成了可执行的检查清单。Bucket A现在就跑的全自动化检查项命令/工具后端测试套件uv run pytest tests/代码风格 类型检查ruff check .·uv run python -m mypy .均为必需 CI 门禁mypy 必须零错误缺依赖时先uv sync --extra dev前端npm run lint·npm run test·npm run build依赖变更后先npm ci避免陈旧node_modules造成假构建失败全链路 happy pathsmoke-e2e 子代理跑本地 dev 栈API Playwright UI依赖审计Dependabot alerts npm audit定向探测probe依矩阵从 probe 库中挑选test-matrix.md 还沉淀了一个定向探测库probe library这些是 v1.11.0 验证过的合法使用回归探针直接服务于 GO/NO-GO 判据中的安全加固不得破坏合法使用原则上传体积恰好低于/高于 body 上限 → 应接受 / 返回 413源摄取一个localhostURL →应被接受自托管是合法场景link-local/metadata URL → 以清晰的 4xx 拒绝前端/config在干净与畸形Host下 → 返回正常 URL / 回退值绝不 5xxSSE 端点是否渐进式流式输出用curl -N -w观察首字节时间远小于总时长有无CORS_ORIGINS两种场景下的 CORS preflight每个枚举/白名单查询参数都需跑遍全部合法值 一个非法值v1.11.0 教训sort_bytitle单独 500 而兄弟参数全通过——必须测全整个表面不能只抽样一个超大数组输入和未知 provider 载荷 → 干净的 422而不是 500凡是 LLM 或 UI 会写入的数据都要在真实浏览器里验证完整链路而非只测 APImirror-bug 教训前端丢字段 后端忽略 null只有端到端才能抓到。test-matrix.md 中有一条 checklist 设计规则同样值得吸收v1.12.0 retro 结论在把X 未配置应报错这类错误路径项放进 bucket-C 人工清单前先到代码里确认它确实是一个错误——例如 transformation 和 tools 的默认配置会刻意回退到 chat 默认值参见 open_notebook/ai/models.py未配置并不等于该报错。Bucket B投入自动化与 owner 商定常驻候选包括本版本新特性的端到端场景、任何证明过两次价值的 probe 的 CI 化、任何 owner 总在手工重复的验证。决策规则很简单如果它能沉淀下来惠及未来多次发布、且成本低于它取代的人工验证就做否则这次先手工验证并在文档中记一笔。镜像门image gate本身就是从 bucket B 毕业的——它在演进为make release-test之前是需要投入的自动化候选。Bucket C发布 owner 专属尽早、并行用真实凭证做 provider 连接测试优先覆盖代码有变动的 provider每个主要 provider 至少一次 discover-models、一次 chat在密集笔记本上做一次带真实 TTS 的播客生成对发布涉及的每个 UI 变更做约 10 分钟的视觉/UX 巡览并抽样深色模式Phase 6用make release-stack验证推送镜像。镜像门Image Gate测工件而不是测仓库GO/NO-GO 判据第二条镜像门绿色fresh upgrade是整个置信度流程的核心创新.github/RELEASE_PROCESS.md 用一句话点题A green suite onmainis not a working imagemain 上全绿的套件不等于能跑的镜像。它的两条验证路径如下make docker-build-local # 构建 version local 标签 make release-test TAGnew OLD_TAGprevious在 scripts/release-test/ 的真实容器里跑两个场景全新安装Fresh install空数据库 → 启动时自动跑迁移 → 镜像内的 worker 进程处理一个 source → API/frontend/nginx 代理检查升级Upgrade先启动已发布的上一版本镜像、播种数据然后在同一数据卷上切换到新镜像 → 迁移生效、数据完好。RELEASE_PROCESS.md 特别标注了一个易错点docker-build-local用的是当前pyproject.toml的版本号打标所以跑升级测试前必须先docker pull真正的上一个版本标签否则会拿新构建去对比自己测试失效。镜像门的只测最终工件原则贯穿了整个流程Phase 5 的切版步骤要求从最终的 main重建镜像并重跑镜像门再经由 CI 推送版本镜像。SKILL.md 对此给出精确命令gh workflow run build-and-release.yml --ref main -f push_latestfalse gh run list --workflowbuild-and-release.yml --limit 1 # 获取 run id gh run watch run-id --exit-statuspush_latestfalse这个标志正是 gates.md可自主执行清单与需授权清单之间的技术分界线——它是版本镜像的预验证推送不触碰v1-latest因此编排器可以自主触发而任何会把v1-latest推出去的路径都被归入必须授权之列。推送完成后还需核验 manifests。runbook 给出了跨双 registry、双架构的校验脚本对每个镜像引用检查平台架构列表是否为[amd64, arm64]for ref in lfnovo/open_notebook:ver lfnovo/open_notebook:ver-single ghcr.io/lfnovo/open-notebook:ver; do docker manifest inspect $ref | python3 -c import json,sys; djson.load(sys.stdin); print(sorted(set(m[platform][architecture] for m in d.get(manifests,[]) if m[platform][architecture]!unknown))) done结合 .github/workflows/build-and-release.yml 可以看到完整的发布镜像拓扑两个 targetregular--target runtime与 single-container--target single同源于根目录 Dockerfile两个 registryDocker Hublfnovo/open_notebook与 GHCRghcr.io/lfnovo/open-notebookDocker Hub 仅在配置了对应 secrets 时推送两个平台linux/amd64、linux/arm64版本来源pyproject.toml当前仓库版本为1.14.0见 pyproject.tomlworkflow 通过grep提取latest 语义push_latesttrue或非 prerelease 的 GitHub Release published 事件都会追加v1-latest对应单容器为v1-latest-single标签。关于版本标签的完整语义RELEASE_PROCESS.md 提供了速查表命令/事件作用更新 latestmake docker-build-local仅为当前平台构建tagversionlocal无 registry 推送CIBuild and Releasepush_latestfalse用 CI 凭证推送版本标签❌ 否GitHub Release 发布非 prereleaseCI 推送版本 v1-latest✅ 是make docker-push/docker-push-latest本地等价操作需docker login❌ / ✅make tag创建并推送与pyproject.toml匹配的 git tag—这些 Makefile 目标均可从根目录 Makefile 中查到定义如release-test、release-stack、release-stack-down、docker-build-local、docker-push、docker-push-latest、tag等。人工验证阶段Phase 6RC 栈与真实数据副本Phase 6 是发布前的最后一道模拟验收。编排器为 owner 在本机提供一个可浏览的 RC 栈make release-stack TAGver [DUMPdump]runbook 给出了带 owner 开发数据副本的完整准备流程先确认开发环境实际使用的是哪个 SurrealDB 实例——读取.env中的SURREAL_URL本机可能跑着多个实例repo-compose 的:8000未必是它并记下SURREAL_DATABASE从正在运行的实例做一致性导出原件不受影响docker exec that-container /surreal export --conn http://localhost:8000 \ --user root --pass root --ns open_notebook --db that-db /dev/stdout /tmp/dev-dump.surql启动栈。注意rc-stack.sh默认会docker pull推送过的 tag——这是 v1.13.0 的血泪教训本地docker-build-local的lfnovo/open_notebook:ver标签会遮蔽推送镜像导致 Phase 6 实际验证的是本地构建而不是 registry 工件冒烟检查凭证可解密使用.env里的开发加密密钥curl -s http://localhost:15055/api/credentials | python3 -c import json,sys; cjson.load(sys.stdin); print(len(c), creds,, sum(1 for x in c if x.get(decryption_error)), decrypt errors)若要顺带验证 opt-in 重型运行时Docling Crawl4AI的安装路径可追加--with-runtimes标志首次启动安装耗时数分钟bash scripts/release-test/rc-stack.sh up ver /tmp/dev-dump.surql --with-runtimesrunbook 同时提醒容器内的凭证若指向宿主机服务Ollama、LM StudioURL 必须写成http://host.docker.internal:port。Phase 6 的 gate 语义在 SKILL.md 中写得斩钉截铁Do not proceed without their GO未获 owner 放行不得继续。这既是质量门也是 gates.md任何推送v1-latest的操作都需授权的前置防线——毕竟发布动作本身Phase 7就在下一步。历史上被门禁捕获的教训Known GotchasRELEASE_PROCESS.md 的 Known Gotchas 区记载了每个版本从门禁中沉淀出的经验是 gates 契约价值的直接证据版本号 bump 绝不能未提交地留在分支上v1.14.0 教训。编辑pyproject.toml/CHANGELOG.md后切换分支会把这些未暂存改动带走下一次git add -A会把 bump 扫进无关的 fix PR版本会悄无声息地搭上fix(...)提交发布。切版永远是最后一步、独立分支、立即提交若必须提前构建镜像需要已 bump 的版本在一次性分支上做并立即处理。切版后落地的修复需要完整 re-cut而不是挪一下 tagv1.14.0 教训。若已打 tag 但尚未发布无 GitHub Release、无v1-latestbucket C 发现 blocker 时tag 必须移到新提交且版本镜像必须重建——否则过期的 tag 或 registry 镜像会被发布动作提升为v1-latest。非默认端口的 RC 栈需要API_URL否则浏览器会连到host:5055——在开发机上那正是开发 API数据交叉污染。rc-stack.sh会设置它。SurrealDB import的OVERWRITE必须放在类型关键字之后DEFINE FIELD OVERWRITE ...且导出器可能向 dump 泄漏一行日志——rc-stack.sh两者都处理了。开发机端口可能属于其他项目3000/5055/8000动工前用lsof -nP -iTCP:port -sTCP:LISTEN加进程 cwd 确认归属绝不盲目 kill。前端可换端口冒烟PORT3001 npm run dev。opt-in 运行时门控必须在干净镜像上评判v1.13.0 教训。开发 venv 可能带外安装了crawl4ai/docling未走 opt-in 标志导致GET /api/capabilities报告可用、UI 开启引擎——这与精简默认镜像的真实行为不符。要在 RC 栈全新推送镜像上验证门控。如何在自己的项目中落地这套门禁模式gates.md 虽为 Open Notebook 的发布编排服务但其思想可以抽象成一套可迁移的工程实践把权限分成三层并写下来可自主 / 需授权 / 永不。特别要把触发公开发布的动作单列为最高风险项并在工具链层面提供预验证推送与公开发布的隔离开关对应这里的push_latest参数。用技术手段固化门禁边界让推版本标签可被 CI 参数控制、可被脚本自动触发而推 latest只绑定人工发布的显式事件——让权限模型不只停留在文档而是编码进工作流见 .github/workflows/build-and-release.yml。定义可核验的 GO 判据把可以发布了拆成自动化绿、镜像门绿fresh upgrade、owner 签字、无遗留回归、高危依赖已清五项任何一项不满足即 NO-GO。人工验证并行化owner 专属的验证项bucket C提前交办而不是放在流水线末尾串行等待。测试保护是否破坏合法使用每次安全加固都要反过来问一句——它会不会误伤自托管、大文件、反向代理等合法场景并沉淀成可复跑的定向 probe。测工件而非测源码无论 CI 多绿最终都要在真实容器里验证全新安装与升级两条路径fresh upgrade 镜像门且最终门必须跑在最终工件上。Retro 永不缺席每次发布后问这个流程哪里该改进并当场把改进写回流程文档与技能文件让门禁随版本一起进化。Open Notebook 把这个模式完整落地在 .agents/skills/release/ 技能包、.github/RELEASE_PROCESS.md 与 scripts/release-test/ 中其演进脉络记录在 ADR-005Release Confidence Process。对任何维护开源项目、需要让 AI Agent 深度参与发布流程的团队而言这套人工闸门 自动化证据 显式授权的组合都值得作为范本研读。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考