MCP Toolbox 开源维护者手册Issue 全生命周期与版本发布运维实战【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读本文完整解析 MCP Toolbox 开源项目一个面向数据库的 MCP Server的《Open Source Maintainer Playbook》维护者手册它定义了从 Issue 报告、Bug 分诊、PR 评审、版本发布到仓库自动化的端到端维护流程。读完本文你将掌握该项目 SLO 目标与标签体系、可直接套用的分诊与 PR 评审清单、版本化/持续/ GitHub Release 三种发布机制的实操步骤以及 npm 与 PyPI 多平台制品的完整发布链路并了解这些流程在仓库中对应的真实配置文件与源码位置。手册定位为多仓库维护团队建立一致流程MCP Toolbox 并非单一仓库而是由googleapis组织下的一组开源仓库组成的家族核心的 MCP Toolbox 主仓库以及 Python SDK、JS SDK、Go SDK 三个语言 SDK 仓库。维护者团队同时面对多个仓库的 Issue 与 PR因此本手册的目标是统一维护流程在保证代码质量的同时为贡献者提供可预期的积极体验让开源运营变得清晰、高效、可预测。从仓库现状看这套流程并非纸上谈兵标签体系在 .github/labels.yaml 中完整定义自动分派规则在 .github/blunderbuss.yml 中配置发布流水线则在 .ci/versioned.release.cloudbuild.yaml 等文件中落实。下文将逐一展开。Issue 生命周期从报告到发布一个 Bug 或功能需求从被提出到最终随版本发布需要经过五个环节每个环节都在手册中有对应的细化章节识别问题Identify Issue社区成员或团队成员在仓库中打开 Issue。分诊Triage团队成员确认 Issue、打上分类与优先级标签并验证报告。解决ResolutionIssue 被指派修复或实现工作开始。评审与合并Review MergePR 经过团队评审全部检查通过后由维护者合并进主干分支。发布Release合并的变更被打包进下一个版本化发布。这条链路的关键在于每一步都有明确的负责人与完成标准避免谁都能看一眼、却没人负责到底的开放源码协作困境。Issue 工作流详解识别问题与 SLO 响应目标维护者需要跨所有仓库跟踪开放的 Issue 与 PR以保证对入站工作的可见性。每个团队应持续监控三类工作并按其优先级顺序处理超出 SLO已超过目标响应/关闭时间必须立即补救接近 SLO即将达到目标理想情况下问题不应拖到超期未分诊Untriaged。手册要求每位维护者每周至少检查一次自己名下的 Issue/PR。当前 SLO 目标如下类型优先级指标目标功能需求Feature RequestP0响应5 天流程ProcessP0响应5 天Bug / 客户问题P0响应2 天关闭14 天P1响应7 天关闭90 天P2响应30 天注响应至少需要评审者给出一次答复关闭要求 Issue/PR 被实际关闭。注意该表的一个细节响应与关闭是两套时钟且 P0 的 Bug 关闭时限14 天远严于响应时限2 天这体现了对严重问题快速接住、限期了结的双重约束。Bug 分诊工作流与检查清单识别到 Bug 后第一步是给出初始确认initial acknowledgement然后按以下清单逐项执行检查重复是否为已知问题若是链接到原始 Issue、感谢用户并以重复duplicate为由关闭。验证可复现性能否依据现有信息复现若不能请求补充信息。打标签按需添加Priority 、Type 、Product 若适用标签——SLO 基于优先级标签计算如适用再添加Status 标签。指派/解除指派如需深入调查指派一名团队成员若你计划处理该问题保持指派状态并纳入你的迭代若不计划处理解除指派让贡献者清楚该问题目前无人认领。标签体系分类、优先级、产品与状态标签是分诊的核心语言具体规则在手册中定义、在 .github/labels.yaml 中落地。从该配置文件可以确认仓库实际注册了以下类别的标签类型Type标签含义Bug错误或代码缺陷产生非预期结果或不理想的使用模式Feature requestFR功能需求或行为/设计上的改进Questions信息或澄清请求Docs需要补充文档Process常规工作流相关可能包含测试、发布等Cleanup系统改进或内部清理/卫生问题优先级Priority优先级适用场景示例P0Bug主要功能损坏导致特性不可用数据库连接问题、工具持续报错、扩展加载失败导致无法访问其全部工具、关键数据面工具持续返回错误结果导致数据损坏P0FR减少摩擦、扩展主要功能的高优先级特性例如 Prompt 支持P1Bug影响下一个版本的关键特性损坏工具或扩展不稳定如新建实例的工具偶发超时需要手动重试、关键特性文档过时造成困惑P1FR面向下一版本的重要特性改进或新增例如新增一种认证方式P2BugBug 不应标为 P2—P2FR锦上添花如工具微调、常见权限问题报错信息更可操作、工具输出可精简以提升可读性P3BugBug 不应标为 P3—P3开放贡献的功能请求例如给现有扩展添加非关键新特性产品Product每个产品都应有独立标签。若缺标签在 .github/labels.yaml 中补充。从仓库配置文件看当前已注册product:系列标签覆盖 AlloyDB、BigQuery、Bigtable、Cassandra、ClickHouse、MSSQL、MySQL、PostgreSQL、Couchbase、Dataplex、Dgraph、Elasticsearch、Firebird、Firestore、Looker、MindsDB、MongoDB、Neo4j、OceanBase、Oracle、Redis、Serverless Spark、SingleStore、Spanner、SQLite、TiDB、Trino、Valkey、YugabyteDB 等数据库产品——这与仓库internal/sources/下对应的数据库连接器源码一一对应产品标签本质上承担着路由到数据库专项维护团队的作用。状态Status标签含义help wanted未计划的工作开放给社区贡献feedback wanted等待社区或 Issue 作者反馈若贡献者超 60 天未响应应直接关闭 PRwaiting for response评审者在等待作者反馈或响应同样适用 60 天关闭规则仓库中还注册了tests: run触发 GitHub Actions 测试、docs: deploy-preview触发文档预览、evals: run触发 Cloud Build 上的 prebuilt config 评测等动作型标签它们是下文 PR 处理环节的开关。可直接套用的分诊回复模板确认功能需求Thanks for suggesting this feature! We appreciate you taking the time to provide this feedback. Weve added this to our backlog for consideration. We cant provide a specific timeline for implementation right now, but we will update this issue with any progress. In the meantime, we welcome pull requests from the community if you are interested in contributing this feature yourself.请求更多信息Thanks for opening this issue! We are having trouble reproducing your problem with the information provided. To help us investigate further, could you please provide: - A minimal, reproducible code sample that demonstrates the issue. - The full error message and stack trace. We will close this issue in 14 days if we dont hear back. Thanks!模板中14 天无回复即关闭的预告与 SLO 表中 P0 Bug 的 14 天关闭目标相互呼应也与 stale-sweep 技能中60 天沉默即建议关闭的规则共同构成一条递进的时间线详见文末衔接小节。Resolution解决阶段的协作规则Bug 的解决是写代码修复功能需求是落地实现PR 则是评估与评审新增特性。分诊完成后Issue 应指派给团队成员若外部贡献者表示有意处理应指派给对方以避免重复劳动。几个值得注意的工程决策自己不拥有的 flaky 测试不做优先处理优先处理团队自有的测试尽量把工作推回上游产品团队若第三方测试持续不稳定考虑将其移出测试套件并上报对应的联系人。为 FR 或 Bug 开 PR 时必须在描述中链接对应 Issue保证可追溯性。自动生成的 PR如依赖更新、发布自动化只要测试与 PR 检查通过就合并走快速通道。Handling Pull RequestsPR 处理与评审评审者检查清单手册为评审者提供了覆盖变更正确性、合规性、可维护性的完整清单该 PR 是否有对应 Issue若有是否已链接PR 标题与描述是否清晰说明了做什么与为什么是否存在未考虑的逻辑错误或边界情况该变更是否引入破坏性变更若有是否已文档化且确有必要PR 标题是否符合团队规范代码是否符合代码风格指南运行 linter是否包含针对新功能或 Bug 修复的测试测试是否覆盖了 happy path 与边界情况若改变了用户与代码的交互方式是否更新了README.md或相关文档复杂逻辑是否有清晰的代码注释若处理用户输入是否做了适当的清理sanitize是否新增了依赖若是是否经过审查vet若需要进入下一个版本打上release candidate标签。所有提交前测试必须通过文档变更须经评审后才可批准。文档预览的部署规则文档预览链接对于主仓库内部分支的 PR 自动生成出于安全考虑外部 fork 的 PR 禁用预览必须由维护者手动部署检查变更审查 PR 中的改动确认安全、无恶意代码特别注意 .github/workflows/ 目录下的改动。部署预览给 PR 打上docs: deploy-preview标签以触发文档预览。运行 Prebuilt Config 评测EvalsEvals 不在 PR 强制门禁gate之内——它们会调用真实模型访问真实数据库因此按计划运行、其他时候按需运行。若 PR 改动了 prebuilt config、其 evalset 或评测 CI给 PR 打上evals: run标签并评论/gcbrun触发构建只评测该 PR 涉及的配置。该标签会保持生效后续推送会自动重跑完成后移除标签即可。与文档预览不同一次评测运行会编译并执行 PR 代码、对接真实测试基础设施因此来自 fork 的 PR 必须先人工评审 diff对 fork PR 使用/gcbrun还会放行等待中的集成测试触发器。评测集覆盖范围参见 DEVELOPER.md 中的 Adding Prebuilt Config Evals 一节。发布沟通与跟踪PR 合并后应在原 Issue 上留言让外部贡献者知道修复会随下一个版本发布例如This has been resolved in PR #[PR number]. The fix will be available in our next release (vX.Y.Z). Thanks again to [contributor-username] for the contribution! Closing this issue now.发布 PR 由发布自动化创建并指派给团队成员需要留意这些 PR 或视情况改派。发布节奏上MCP Toolbox 主仓库一般每月两次版本化发布SDK 则按需发布。维护者团队与代码所有权团队googleapis/senseai-eco被设置为 .github/CODEOWNERS 中的代码所有者由 GitHub TeamSync 工具从 MDB 组senseai-eco创建。此外各数据库专项团队如googleapis/toolbox-alloydb也从 MDB 组创建用于管理具体数据库产品的代码所有权与评审。这一按产品分权的设计在 .github/blunderbuss.yml 中体现得最直观该配置把product:标签映射到对应团队——例如product: alloydb路由到googleapis/toolbox-alloydb-team、product: postgres路由到googleapis/toolbox-cloud-sql-postgres-team——同时为 Issue 与 PR 各维护一套默认指派名单。这意味着一个 AlloyDB 相关的 Issue 从被打上产品标签起就自动进入对应数据库团队的指派队列SLO 时钟也随之启动。Releasing版本发布机制与完整操作三种发布类型Toolbox 依托 Google Cloud 项目database-toolbox存在两种核心发布流加一个自动化环节版本化发布Versioned Release官方、受支持的发行版标记为latest。流水线定义在 .ci/versioned.release.cloudbuild.yaml。持续发布Continuous Release用于官方版本之间提前测试新特性及端到端测试。流水线定义在 .ci/continuous.release.cloudbuild.yaml。GitHub Release.github/release-please.yml 自动创建 GitHub Releases 与发布 PR。从 .ci/versioned.release.cloudbuild.yaml 的实现可以看到发布构建的实际形态通过docker buildx构建并推送多架构镜像版本号直接读取cmd/version.txt并支持_PUSH_LATEST开关控制是否额外打latest标签。而 .github/release-please.yml 声明releaseType: simple、versionFile: cmd/version.txt并列出 README、文档、npm/server/package.json各平台包版本、server.json的 version 字段等一大批 extraFiles——这些正是发布 PR 会自动同步版本号的版本来源清单。如何发布一个新版本【可选】如需覆盖版本号向仓库发送一个触发 release-please 的 PR。也可通过生成含如下提交信息的 commit 实现git commit -m chore: release 0.1.0 -m Release-As: 0.1.0 --allow-empty。【可选】如需编辑变更日志向发布 PR 发送 commit。合并发布 PR 前更新版本下拉框让版本化文档构建感知新版本在hugo.toml与hugo.cloudflare.toml中为新版本添加[[params.versions]]块从hugo.cloudflare.toml移除最旧版本的[[params.versions]]块并删除cloudflare-pages分支中该版本的目录Cloudflare 每次部署仅允许 20,000 个文件必须裁剪历史版本。批准并合并标题为 chore(main): release x.x.x 的 PR。新 tag 被推送后Cloud Build 触发器会自动运行可查看触发构建的状态。更新 GitHub 发布说明追加制品清单表格export VERSIONv0.0.0 .ci/generate_release_table.sh复制表格输出 → GitHub 的 Releases 页面点击edit→ 将表格粘贴到发布说明底部 → 点击Update release。在内部聊天群和 Discord 上发布版本消息。支持的发布制品二进制发布的平台/架构组合linux/amd64darwin/arm64darwin/amd64windows/amd64windows/arm64容器镜像基础镜像distrolessnpm 与 PyPI 包的发布自动化主路径OSS Exit Gate手册强调当前 npm 与 PyPI 的发布已由自动化接管走 Google 的OSS Exit Gate通道npmpublish-npm-to-ar与trigger-exit-gate两步见 .ci/versioned.release.cloudbuild.yaml将全部六个包推送到 Exit Gate Artifact Registry并上传publish_all: true清单触发 Exit Gate 向 npmjs.org 外部发布。若 npm 部分在 Go 二进制已上传 GCS 后失败可用 .ci/npm_retry.cloudbuild.yaml 只重试 npm 步骤幂等已发布的包会跳过。PyPI同样通过publish-pypi-to-ar与trigger-exit-gate-pypi步骤自动化。每次发布通过 pypi/setup.py 以TOOLBOX_PLATFORM环境变量构建五个平台标签 wheel每个 OS/arch 一个上传到 Exit Gate 仓库后由 Exit Gate 通过 trusted publishing 发布到 pypi.org。PyPI 单独的重试流水线在 .ci/pypi_retry.cloudbuild.yaml幂等性由twine upload --skip-existing保证。以下手动流程仅作为自动化故障时的回退方案。手动发布 npm前置条件与准备前置条件在 npmjs.com 注册账号开启 npm 账号的两步验证2FA发布必需联系当前维护者申请toolbox-sdk/组织的 Editor 权限。准备需要发布以下 5 个平台组合对应的包darwin/arm64→server-darwin-arm64darwin/x64→server-darwin-x64linux/x64→server-linux-x64win32/arm64→server-win32-arm64win32/x64→server-win32-x64仓库中npm/目录下的server与server-{os}-{arch}五个平台包目录正好对应这一矩阵而cmd/version.txt当前内容为1.11.0正是 release-please 的versionFiledownloadBinary.js会在prepack阶段从该文件读取版本。Phase A发布平台专属包对上述 5 个组合逐一执行进入包目录cd npm/server-os-arch校验版本确认二进制版本由仓库根目录cmd/version.txt提供与package.json的version字段一致。同步锁文件npm install --force清理制品删除既有二进制保证打包干净。rm -rf bin/打包并发布npm pack . npm publish --access public验证发布下一个包前先在 npm registry 确认当前版本已生效。Phase B发布主包toolbox-sdk/server进入主目录cd ../server。校验版本确认package.json的version字段为目标版本且optionalDependencies中 5 个平台包的版本均与新版本一致。同步锁文件需先等 5 个依赖包全部发布npm install --package-lock-only确认package-lock.json中每个包都有对应条目且 integrity 哈希已更新若不一致删除锁文件重新生成。打包并发布npm pack .与npm publish --access public。验证确认主包以正确版本上线。发布后提交全部包发布成功后创建包含npm/所有子目录更新后package-lock.json的 PR标题设为chore(main): release npm vX.Y.Z。切勿将二进制提交进仓库。npm 发布故障排查访问令牌过期或需要认证执行npm login若 registry 不是https://registry.npmjs.org/用npm config set registry https://registry.npmjs.org/或修改.npmrc。版本不匹配不要重新发布同一版本递增 patch 版本后按上述流程发布新版本。弃用推荐某版本损坏时标记弃用npm deprecate package_nameversion critical bug fixed in vX.Y.Z。取消发布核选项仅发布后 72 小时内可执行npm unpublish package-nameversion注意这会永久烧毁该版本号。测试与自动化自动化测试策略单元测试与集成测试由 Cloud Build 在每个 PR上自动触发集成测试在**合并时与每夜nightly**运行。失败通知由 Cloud Build Failure Reporter 对应的 GitHub Actions 工作流 schedule_reporter.yml 负责——这正是手册中发现失败后有人跟进的落地机制。仓库 .github/workflows/ 下还有tests.yaml、lint.yaml、conformance.yml、docs_lint.yaml、link_checker.yaml等一整套检查共同构成 PR 质量门禁。Cloud Build 触发器配置触发器可经 UI 或gcloud配置关键设置如下事件EventPull request区域Regionglobal默认 worker poolsSourceGeneration1st genRepogoogleapis/mcp-toolboxGitHub App基础分支^main$评论控制Comment controlRequired except for owners and collaborators除所有者与协作者外必须评论触发过滤器Filters添加目录过滤器ConfigCloud Build 配置文件位置选 Repository 并填写文件路径Service account为 demo service 设置以启用认证服务的 ID token 创建仓库自动化设施一览手册列出的仓库自动化组件多数在当前仓库中均有实体文件可直接对照学习组件作用.github/blunderbuss.yml从 GitHub 团队自动指派 Issue 与 PR用产品标签把任务路由到对应产品团队.github/renovate.json5依赖更新工具GitHub 内置的 Dependabot 负责安全警告go/github-issue-mirrorGitHub Issue 自动镜像到 Buganizer已暂停.github/labels.yaml 配套的 sync-repo-settings仓库设置同步.github/release-please.yml创建 GitHub Releases.github/ISSUE_TEMPLATEGitHub Issue 模板与 stale-sweep 技能的衔接手册是判断的权威依据值得一提的联系是本手册是仓库中 stale-sweep 维护技能同目录下的 SKILL.md引用的权威规则来源。该技能在执行过期清扫时明确读取本手册并据此作出三类判断60 天沉默即关闭规则来自手册中status: waiting for response/status: feedback wanted的状态定义若贡献者超 60 天未响应直接关闭 PRSLO 响应与关闭目标来自前文的 SLO 表格用于识别卡在我们这边的 SLO 超期项关闭/催促的措辞模板改编自手册中的社区沟通模板保证话术统一。同时该技能也强调仓库没有 stale bot.github/下无 stale 工作流关闭动作始终是维护者的有意识行为——这与手册每个关闭都应给出理由与引用的精神完全一致。维护者用gh拉取候选、按谁在沉默分桶、给出可粘贴的 nudge 与 close 评论正是把本文这套 SLO 与标签体系应用到日常积压清理中的最佳实践。结语MCP Toolbox 的维护者手册展示了一个多仓库、多数据库产品矩阵下开源维护的完整范式用 SLO 约束响应、用标签体系支撑路由、用检查清单保证评审质量、用多级自动化降低发布风险。无论是想了解开源维护的业界实践还是希望为项目贡献代码阅读本手册即可理解维护者期望的 Issue 与 PR 形态本文梳理的流程与仓库中的配置文件都是最直接的起点。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP Toolbox 开源维护者手册：Issue 全生命周期与版本发布运维实战
MCP Toolbox 开源维护者手册Issue 全生命周期与版本发布运维实战【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读本文完整解析 MCP Toolbox 开源项目一个面向数据库的 MCP Server的《Open Source Maintainer Playbook》维护者手册它定义了从 Issue 报告、Bug 分诊、PR 评审、版本发布到仓库自动化的端到端维护流程。读完本文你将掌握该项目 SLO 目标与标签体系、可直接套用的分诊与 PR 评审清单、版本化/持续/ GitHub Release 三种发布机制的实操步骤以及 npm 与 PyPI 多平台制品的完整发布链路并了解这些流程在仓库中对应的真实配置文件与源码位置。手册定位为多仓库维护团队建立一致流程MCP Toolbox 并非单一仓库而是由googleapis组织下的一组开源仓库组成的家族核心的 MCP Toolbox 主仓库以及 Python SDK、JS SDK、Go SDK 三个语言 SDK 仓库。维护者团队同时面对多个仓库的 Issue 与 PR因此本手册的目标是统一维护流程在保证代码质量的同时为贡献者提供可预期的积极体验让开源运营变得清晰、高效、可预测。从仓库现状看这套流程并非纸上谈兵标签体系在 .github/labels.yaml 中完整定义自动分派规则在 .github/blunderbuss.yml 中配置发布流水线则在 .ci/versioned.release.cloudbuild.yaml 等文件中落实。下文将逐一展开。Issue 生命周期从报告到发布一个 Bug 或功能需求从被提出到最终随版本发布需要经过五个环节每个环节都在手册中有对应的细化章节识别问题Identify Issue社区成员或团队成员在仓库中打开 Issue。分诊Triage团队成员确认 Issue、打上分类与优先级标签并验证报告。解决ResolutionIssue 被指派修复或实现工作开始。评审与合并Review MergePR 经过团队评审全部检查通过后由维护者合并进主干分支。发布Release合并的变更被打包进下一个版本化发布。这条链路的关键在于每一步都有明确的负责人与完成标准避免谁都能看一眼、却没人负责到底的开放源码协作困境。Issue 工作流详解识别问题与 SLO 响应目标维护者需要跨所有仓库跟踪开放的 Issue 与 PR以保证对入站工作的可见性。每个团队应持续监控三类工作并按其优先级顺序处理超出 SLO已超过目标响应/关闭时间必须立即补救接近 SLO即将达到目标理想情况下问题不应拖到超期未分诊Untriaged。手册要求每位维护者每周至少检查一次自己名下的 Issue/PR。当前 SLO 目标如下类型优先级指标目标功能需求Feature RequestP0响应5 天流程ProcessP0响应5 天Bug / 客户问题P0响应2 天关闭14 天P1响应7 天关闭90 天P2响应30 天注响应至少需要评审者给出一次答复关闭要求 Issue/PR 被实际关闭。注意该表的一个细节响应与关闭是两套时钟且 P0 的 Bug 关闭时限14 天远严于响应时限2 天这体现了对严重问题快速接住、限期了结的双重约束。Bug 分诊工作流与检查清单识别到 Bug 后第一步是给出初始确认initial acknowledgement然后按以下清单逐项执行检查重复是否为已知问题若是链接到原始 Issue、感谢用户并以重复duplicate为由关闭。验证可复现性能否依据现有信息复现若不能请求补充信息。打标签按需添加Priority 、Type 、Product 若适用标签——SLO 基于优先级标签计算如适用再添加Status 标签。指派/解除指派如需深入调查指派一名团队成员若你计划处理该问题保持指派状态并纳入你的迭代若不计划处理解除指派让贡献者清楚该问题目前无人认领。标签体系分类、优先级、产品与状态标签是分诊的核心语言具体规则在手册中定义、在 .github/labels.yaml 中落地。从该配置文件可以确认仓库实际注册了以下类别的标签类型Type标签含义Bug错误或代码缺陷产生非预期结果或不理想的使用模式Feature requestFR功能需求或行为/设计上的改进Questions信息或澄清请求Docs需要补充文档Process常规工作流相关可能包含测试、发布等Cleanup系统改进或内部清理/卫生问题优先级Priority优先级适用场景示例P0Bug主要功能损坏导致特性不可用数据库连接问题、工具持续报错、扩展加载失败导致无法访问其全部工具、关键数据面工具持续返回错误结果导致数据损坏P0FR减少摩擦、扩展主要功能的高优先级特性例如 Prompt 支持P1Bug影响下一个版本的关键特性损坏工具或扩展不稳定如新建实例的工具偶发超时需要手动重试、关键特性文档过时造成困惑P1FR面向下一版本的重要特性改进或新增例如新增一种认证方式P2BugBug 不应标为 P2—P2FR锦上添花如工具微调、常见权限问题报错信息更可操作、工具输出可精简以提升可读性P3BugBug 不应标为 P3—P3开放贡献的功能请求例如给现有扩展添加非关键新特性产品Product每个产品都应有独立标签。若缺标签在 .github/labels.yaml 中补充。从仓库配置文件看当前已注册product:系列标签覆盖 AlloyDB、BigQuery、Bigtable、Cassandra、ClickHouse、MSSQL、MySQL、PostgreSQL、Couchbase、Dataplex、Dgraph、Elasticsearch、Firebird、Firestore、Looker、MindsDB、MongoDB、Neo4j、OceanBase、Oracle、Redis、Serverless Spark、SingleStore、Spanner、SQLite、TiDB、Trino、Valkey、YugabyteDB 等数据库产品——这与仓库internal/sources/下对应的数据库连接器源码一一对应产品标签本质上承担着路由到数据库专项维护团队的作用。状态Status标签含义help wanted未计划的工作开放给社区贡献feedback wanted等待社区或 Issue 作者反馈若贡献者超 60 天未响应应直接关闭 PRwaiting for response评审者在等待作者反馈或响应同样适用 60 天关闭规则仓库中还注册了tests: run触发 GitHub Actions 测试、docs: deploy-preview触发文档预览、evals: run触发 Cloud Build 上的 prebuilt config 评测等动作型标签它们是下文 PR 处理环节的开关。可直接套用的分诊回复模板确认功能需求Thanks for suggesting this feature! We appreciate you taking the time to provide this feedback. Weve added this to our backlog for consideration. We cant provide a specific timeline for implementation right now, but we will update this issue with any progress. In the meantime, we welcome pull requests from the community if you are interested in contributing this feature yourself.请求更多信息Thanks for opening this issue! We are having trouble reproducing your problem with the information provided. To help us investigate further, could you please provide: - A minimal, reproducible code sample that demonstrates the issue. - The full error message and stack trace. We will close this issue in 14 days if we dont hear back. Thanks!模板中14 天无回复即关闭的预告与 SLO 表中 P0 Bug 的 14 天关闭目标相互呼应也与 stale-sweep 技能中60 天沉默即建议关闭的规则共同构成一条递进的时间线详见文末衔接小节。Resolution解决阶段的协作规则Bug 的解决是写代码修复功能需求是落地实现PR 则是评估与评审新增特性。分诊完成后Issue 应指派给团队成员若外部贡献者表示有意处理应指派给对方以避免重复劳动。几个值得注意的工程决策自己不拥有的 flaky 测试不做优先处理优先处理团队自有的测试尽量把工作推回上游产品团队若第三方测试持续不稳定考虑将其移出测试套件并上报对应的联系人。为 FR 或 Bug 开 PR 时必须在描述中链接对应 Issue保证可追溯性。自动生成的 PR如依赖更新、发布自动化只要测试与 PR 检查通过就合并走快速通道。Handling Pull RequestsPR 处理与评审评审者检查清单手册为评审者提供了覆盖变更正确性、合规性、可维护性的完整清单该 PR 是否有对应 Issue若有是否已链接PR 标题与描述是否清晰说明了做什么与为什么是否存在未考虑的逻辑错误或边界情况该变更是否引入破坏性变更若有是否已文档化且确有必要PR 标题是否符合团队规范代码是否符合代码风格指南运行 linter是否包含针对新功能或 Bug 修复的测试测试是否覆盖了 happy path 与边界情况若改变了用户与代码的交互方式是否更新了README.md或相关文档复杂逻辑是否有清晰的代码注释若处理用户输入是否做了适当的清理sanitize是否新增了依赖若是是否经过审查vet若需要进入下一个版本打上release candidate标签。所有提交前测试必须通过文档变更须经评审后才可批准。文档预览的部署规则文档预览链接对于主仓库内部分支的 PR 自动生成出于安全考虑外部 fork 的 PR 禁用预览必须由维护者手动部署检查变更审查 PR 中的改动确认安全、无恶意代码特别注意 .github/workflows/ 目录下的改动。部署预览给 PR 打上docs: deploy-preview标签以触发文档预览。运行 Prebuilt Config 评测EvalsEvals 不在 PR 强制门禁gate之内——它们会调用真实模型访问真实数据库因此按计划运行、其他时候按需运行。若 PR 改动了 prebuilt config、其 evalset 或评测 CI给 PR 打上evals: run标签并评论/gcbrun触发构建只评测该 PR 涉及的配置。该标签会保持生效后续推送会自动重跑完成后移除标签即可。与文档预览不同一次评测运行会编译并执行 PR 代码、对接真实测试基础设施因此来自 fork 的 PR 必须先人工评审 diff对 fork PR 使用/gcbrun还会放行等待中的集成测试触发器。评测集覆盖范围参见 DEVELOPER.md 中的 Adding Prebuilt Config Evals 一节。发布沟通与跟踪PR 合并后应在原 Issue 上留言让外部贡献者知道修复会随下一个版本发布例如This has been resolved in PR #[PR number]. The fix will be available in our next release (vX.Y.Z). Thanks again to [contributor-username] for the contribution! Closing this issue now.发布 PR 由发布自动化创建并指派给团队成员需要留意这些 PR 或视情况改派。发布节奏上MCP Toolbox 主仓库一般每月两次版本化发布SDK 则按需发布。维护者团队与代码所有权团队googleapis/senseai-eco被设置为 .github/CODEOWNERS 中的代码所有者由 GitHub TeamSync 工具从 MDB 组senseai-eco创建。此外各数据库专项团队如googleapis/toolbox-alloydb也从 MDB 组创建用于管理具体数据库产品的代码所有权与评审。这一按产品分权的设计在 .github/blunderbuss.yml 中体现得最直观该配置把product:标签映射到对应团队——例如product: alloydb路由到googleapis/toolbox-alloydb-team、product: postgres路由到googleapis/toolbox-cloud-sql-postgres-team——同时为 Issue 与 PR 各维护一套默认指派名单。这意味着一个 AlloyDB 相关的 Issue 从被打上产品标签起就自动进入对应数据库团队的指派队列SLO 时钟也随之启动。Releasing版本发布机制与完整操作三种发布类型Toolbox 依托 Google Cloud 项目database-toolbox存在两种核心发布流加一个自动化环节版本化发布Versioned Release官方、受支持的发行版标记为latest。流水线定义在 .ci/versioned.release.cloudbuild.yaml。持续发布Continuous Release用于官方版本之间提前测试新特性及端到端测试。流水线定义在 .ci/continuous.release.cloudbuild.yaml。GitHub Release.github/release-please.yml 自动创建 GitHub Releases 与发布 PR。从 .ci/versioned.release.cloudbuild.yaml 的实现可以看到发布构建的实际形态通过docker buildx构建并推送多架构镜像版本号直接读取cmd/version.txt并支持_PUSH_LATEST开关控制是否额外打latest标签。而 .github/release-please.yml 声明releaseType: simple、versionFile: cmd/version.txt并列出 README、文档、npm/server/package.json各平台包版本、server.json的 version 字段等一大批 extraFiles——这些正是发布 PR 会自动同步版本号的版本来源清单。如何发布一个新版本【可选】如需覆盖版本号向仓库发送一个触发 release-please 的 PR。也可通过生成含如下提交信息的 commit 实现git commit -m chore: release 0.1.0 -m Release-As: 0.1.0 --allow-empty。【可选】如需编辑变更日志向发布 PR 发送 commit。合并发布 PR 前更新版本下拉框让版本化文档构建感知新版本在hugo.toml与hugo.cloudflare.toml中为新版本添加[[params.versions]]块从hugo.cloudflare.toml移除最旧版本的[[params.versions]]块并删除cloudflare-pages分支中该版本的目录Cloudflare 每次部署仅允许 20,000 个文件必须裁剪历史版本。批准并合并标题为 chore(main): release x.x.x 的 PR。新 tag 被推送后Cloud Build 触发器会自动运行可查看触发构建的状态。更新 GitHub 发布说明追加制品清单表格export VERSIONv0.0.0 .ci/generate_release_table.sh复制表格输出 → GitHub 的 Releases 页面点击edit→ 将表格粘贴到发布说明底部 → 点击Update release。在内部聊天群和 Discord 上发布版本消息。支持的发布制品二进制发布的平台/架构组合linux/amd64darwin/arm64darwin/amd64windows/amd64windows/arm64容器镜像基础镜像distrolessnpm 与 PyPI 包的发布自动化主路径OSS Exit Gate手册强调当前 npm 与 PyPI 的发布已由自动化接管走 Google 的OSS Exit Gate通道npmpublish-npm-to-ar与trigger-exit-gate两步见 .ci/versioned.release.cloudbuild.yaml将全部六个包推送到 Exit Gate Artifact Registry并上传publish_all: true清单触发 Exit Gate 向 npmjs.org 外部发布。若 npm 部分在 Go 二进制已上传 GCS 后失败可用 .ci/npm_retry.cloudbuild.yaml 只重试 npm 步骤幂等已发布的包会跳过。PyPI同样通过publish-pypi-to-ar与trigger-exit-gate-pypi步骤自动化。每次发布通过 pypi/setup.py 以TOOLBOX_PLATFORM环境变量构建五个平台标签 wheel每个 OS/arch 一个上传到 Exit Gate 仓库后由 Exit Gate 通过 trusted publishing 发布到 pypi.org。PyPI 单独的重试流水线在 .ci/pypi_retry.cloudbuild.yaml幂等性由twine upload --skip-existing保证。以下手动流程仅作为自动化故障时的回退方案。手动发布 npm前置条件与准备前置条件在 npmjs.com 注册账号开启 npm 账号的两步验证2FA发布必需联系当前维护者申请toolbox-sdk/组织的 Editor 权限。准备需要发布以下 5 个平台组合对应的包darwin/arm64→server-darwin-arm64darwin/x64→server-darwin-x64linux/x64→server-linux-x64win32/arm64→server-win32-arm64win32/x64→server-win32-x64仓库中npm/目录下的server与server-{os}-{arch}五个平台包目录正好对应这一矩阵而cmd/version.txt当前内容为1.11.0正是 release-please 的versionFiledownloadBinary.js会在prepack阶段从该文件读取版本。Phase A发布平台专属包对上述 5 个组合逐一执行进入包目录cd npm/server-os-arch校验版本确认二进制版本由仓库根目录cmd/version.txt提供与package.json的version字段一致。同步锁文件npm install --force清理制品删除既有二进制保证打包干净。rm -rf bin/打包并发布npm pack . npm publish --access public验证发布下一个包前先在 npm registry 确认当前版本已生效。Phase B发布主包toolbox-sdk/server进入主目录cd ../server。校验版本确认package.json的version字段为目标版本且optionalDependencies中 5 个平台包的版本均与新版本一致。同步锁文件需先等 5 个依赖包全部发布npm install --package-lock-only确认package-lock.json中每个包都有对应条目且 integrity 哈希已更新若不一致删除锁文件重新生成。打包并发布npm pack .与npm publish --access public。验证确认主包以正确版本上线。发布后提交全部包发布成功后创建包含npm/所有子目录更新后package-lock.json的 PR标题设为chore(main): release npm vX.Y.Z。切勿将二进制提交进仓库。npm 发布故障排查访问令牌过期或需要认证执行npm login若 registry 不是https://registry.npmjs.org/用npm config set registry https://registry.npmjs.org/或修改.npmrc。版本不匹配不要重新发布同一版本递增 patch 版本后按上述流程发布新版本。弃用推荐某版本损坏时标记弃用npm deprecate package_nameversion critical bug fixed in vX.Y.Z。取消发布核选项仅发布后 72 小时内可执行npm unpublish package-nameversion注意这会永久烧毁该版本号。测试与自动化自动化测试策略单元测试与集成测试由 Cloud Build 在每个 PR上自动触发集成测试在**合并时与每夜nightly**运行。失败通知由 Cloud Build Failure Reporter 对应的 GitHub Actions 工作流 schedule_reporter.yml 负责——这正是手册中发现失败后有人跟进的落地机制。仓库 .github/workflows/ 下还有tests.yaml、lint.yaml、conformance.yml、docs_lint.yaml、link_checker.yaml等一整套检查共同构成 PR 质量门禁。Cloud Build 触发器配置触发器可经 UI 或gcloud配置关键设置如下事件EventPull request区域Regionglobal默认 worker poolsSourceGeneration1st genRepogoogleapis/mcp-toolboxGitHub App基础分支^main$评论控制Comment controlRequired except for owners and collaborators除所有者与协作者外必须评论触发过滤器Filters添加目录过滤器ConfigCloud Build 配置文件位置选 Repository 并填写文件路径Service account为 demo service 设置以启用认证服务的 ID token 创建仓库自动化设施一览手册列出的仓库自动化组件多数在当前仓库中均有实体文件可直接对照学习组件作用.github/blunderbuss.yml从 GitHub 团队自动指派 Issue 与 PR用产品标签把任务路由到对应产品团队.github/renovate.json5依赖更新工具GitHub 内置的 Dependabot 负责安全警告go/github-issue-mirrorGitHub Issue 自动镜像到 Buganizer已暂停.github/labels.yaml 配套的 sync-repo-settings仓库设置同步.github/release-please.yml创建 GitHub Releases.github/ISSUE_TEMPLATEGitHub Issue 模板与 stale-sweep 技能的衔接手册是判断的权威依据值得一提的联系是本手册是仓库中 stale-sweep 维护技能同目录下的 SKILL.md引用的权威规则来源。该技能在执行过期清扫时明确读取本手册并据此作出三类判断60 天沉默即关闭规则来自手册中status: waiting for response/status: feedback wanted的状态定义若贡献者超 60 天未响应直接关闭 PRSLO 响应与关闭目标来自前文的 SLO 表格用于识别卡在我们这边的 SLO 超期项关闭/催促的措辞模板改编自手册中的社区沟通模板保证话术统一。同时该技能也强调仓库没有 stale bot.github/下无 stale 工作流关闭动作始终是维护者的有意识行为——这与手册每个关闭都应给出理由与引用的精神完全一致。维护者用gh拉取候选、按谁在沉默分桶、给出可粘贴的 nudge 与 close 评论正是把本文这套 SLO 与标签体系应用到日常积压清理中的最佳实践。结语MCP Toolbox 的维护者手册展示了一个多仓库、多数据库产品矩阵下开源维护的完整范式用 SLO 约束响应、用标签体系支撑路由、用检查清单保证评审质量、用多级自动化降低发布风险。无论是想了解开源维护的业界实践还是希望为项目贡献代码阅读本手册即可理解维护者期望的 Issue 与 PR 形态本文梳理的流程与仓库中的配置文件都是最直接的起点。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考