首先：请使用父技能 neon 了解 Neon 概览、入门指南、最佳开发实践等更多信息。
如果 neon 技能尚未安装，请从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或通过以下命令安装：
npx skills add neondatabase/agent-skills --skill neon
Lakebase Postgres 分支管理
目标： 创建一个 Neon 分支，或者在创建无法进行时，给出清晰、可操作的后续步骤。选择正确的分支类型，然后通过 CLI（或在 CLI 不可用时使用 MCP）执行分支创建。
- 标准分支：适用于使用真实数据进行迁移和查询测试。
- 仅模式分支（Beta）：适用于敏感数据处理工作流，只需要结构而不复制数据行。
分支类型决策
请首先使用以下决策规则：
- 如果用户想要测试复杂的迁移、性能或针对类似于生产环境的数据的行为，请选择标准分支。
- 如果用户需要避免复制敏感数据，请选择仅模式分支。
如果需求不明确，请提出一个澄清性问题： “您是需要真实数据进行测试，还是因为数据敏感只需要模式结构？”
工具选择：CLI 或 MCP
支持 Neon CLI 和 Neon MCP 服务器，但默认使用 CLI。仅当 CLI 在您的环境中不可用、被阻止、无法认证，或者用户明确要求 MCP 时，才使用 MCP。
选择顺序
- 首先检查 CLI：
- 运行
neon --version确认 CLI 已安装。 - 运行
neon projects list确认认证/上下文。
- 运行
- 如果 CLI 缺失，请通过快速入门指导安装。
- 如果 CLI 已安装但未认证，请引导用户通过
neon auth（或 API 密钥认证），然后继续。 - 当无法使用 CLI 时（环境中无 CLI 访问、执行被阻止、认证不可行），或用户明确要求 MCP 时，切换到 MCP。确认 Neon MCP 工具可用且已认证（例如，列举项目正常工作），然后按照下面的 MCP 分支流程操作。
- 如果以上路径均不成功，请使用 Neon REST API：
MCP 分支流程
- 根据数据敏感性和迁移测试目标，选择标准分支还是仅模式分支。
- 使用分支工具（例如
create_branch）创建分支。 - 使用读取工具（例如
describe_branch）进行验证。 - 对于迁移工作流，优先在分支上执行迁移流程，之后再应用于主分支。
创建标准分支（推荐用于真实数据的迁移测试）
当用户需要真实的测试条件时使用此模式。 真实的生产类数据可以暴露您的种子数据或数据迁移脚本可能会遗漏的边缘情况，这有助于在实际上线前发现迁移问题。
链接：https://neon.com/docs/introduction/branching.md
步骤
-
首先确定工具路径（参见选择顺序）：使用
neon --version验证 CLI，仅在 CLI 不可用时才回退到 MCP。 -
确保项目上下文已设置（
neon set-context --project-id <您的项目ID>）或在命令中包含--project-id。 -
创建分支：
neon branches create \ --name <分支名称> \ --parent <父分支ID或名称> \ --expires-at 2026-12-15T18:02:16Z -
可选：获取新分支的连接字符串：
neon connection-string <分支名称>
创建仅模式分支（Beta，敏感数据）
当用户必须避免将生产数据行复制到测试分支时使用此模式。
链接：https://neon.com/docs/guides/branching-schema-only.md
步骤
-
首先确定工具路径（参见选择顺序）：使用
neon --version验证 CLI，仅在 CLI 不可用时才回退到 MCP。 -
创建仅模式分支：
neon branches create \ --name <仅模式分支名称> \ --parent <父分支ID或名称> \ --schema-only \ --expires-at 2026-12-15T18:02:16Z如果存在多个项目，请包含
--project-id：neon branches create \ --name <仅模式分支名称> \ --parent <父分支ID或名称> \ --schema-only \ --project-id <您的项目ID> \ --expires-at 2026-12-15T18:02:16Z
Beta 支持指导（必读）
仅模式分支仍处于 Beta 阶段。如果用户报告意外行为、错误或缺少功能：
- 请他们在 Neon 控制台中分享反馈：
- 建议在 Neon Discord 中开启支持对话：
从父分支重置
当子分支已偏离，并且用户希望从父分支的最新模式和数据进行干净刷新时使用此模式。
链接：https://neon.com/docs/guides/reset-from-parent.md
功能说明
- 完全使用父分支的最新状态替换子分支的模式和数据。
- 不会合并；子分支上的本地更改将丢失。
- 保持相同的连接详情，但活动连接在重置期间会短暂中断。
何时推荐使用
- 开发或暂存分支远远落后于生产分支。
- 用户希望从与父分支对齐的干净状态开始新功能。
- 团队希望从生产分支刷新暂存分支以获得一致的测试基线。
硬约束和阻塞因素
- 只有子分支可以重置（根分支和仅模式根分支无法从父分支重置）。
- 如果目标分支有子分支，则重置被阻塞，直到那些子分支被移除。
- 父分支从快照恢复后，从父分支重置功能可能在 24 小时内不可用。
- 从父分支重置始终使用当前的父分支状态；如果需要时间点恢复，请使用 Instant restore。
CLI 用法
neon branches reset <id|名称> --parent --preserve-under-name <备份分支名称>
如果项目上下文尚未设置，请包含项目 ID：
neon branches reset <id|名称> --parent --preserve-under-name <备份分支名称> --project-id <项目ID>
--preserve-under-name 会将重置前的状态保留为一个备份分支，用于回滚，但会额外增加一个需要稍后清理的分支。
可选：设置上下文以避免重复 --project-id：
neon set-context --project-id <项目ID>
控制台和 API 用法
- 控制台： 打开目标子分支，然后从操作菜单中选择从父分支重置。
- API： 使用分支的恢复端点，并将
source_branch_id设置为父分支 ID。
注意事项与说明
- 仅模式分支仅用于结构克隆和敏感/合规数据控制。
- 仅模式分支是独立的根分支（没有父分支和共享历史），因此从父分支重置不适用。
- 对于依赖于真实行形状、数据量和边缘情况的迁移测试，请优先使用标准分支。
- 根分支配额和每分支存储限制可能会限制用户创建的仅模式分支数量。
- 如果用户不确定，默认建议如下：
- 迁移验证使用标准分支。
- 合规和隐私约束使用仅模式分支。
有用的工作流模式
如果用户询问流程建议（而不仅仅是单个命令），请推荐以下模式：
- 每个 PR 一个分支： 在 PR 打开时创建分支，合并/关闭时删除，保持迁移测试隔离。
- 每次测试运行一个分支： 在流水线启动时创建分支，运行迁移/测试，结束时删除，确保确定性的 CI。
- 每个开发者一个分支： 提供具有生产类形状的隔离开发环境，避免团队在共享测试数据上发生冲突。
- PII 感知分支： 如果生产数据包含敏感信息，则从匿名分支派生开发/PR 分支，或使用仅模式分支。
- 临时生命周期卫生： 设置分支过期时间并自动化清理，以避免旧分支累积不必要的存储/历史成本。
创建后环境更新提示
创建分支后，询问用户是否要更新本地环境凭证以指向新分支。
- 询问：“您是否希望我将您的
.env中的DATABASE_URL更新为此新分支的连接字符串？” - 如果是，则将新的分支连接字符串写入所请求的环境变量文件/键。
- 如果否，则保持凭证不变，并提供连接字符串供用户手动使用。
- 在没有明确确认的情况下，切勿覆盖现有的环境变量键。
Neon 基础设施即代码 (neon.ts)
除了以命令式方式（CLI / MCP / API 上述方法）创建分支外，您还可以在 neon.ts（Neon 的基础设施即代码文件，完整参考请参见 neon 技能）中以声明方式编程定义新分支应接收的配置。branch 属性是一个函数，它接收被评估的分支并返回其设置，从而使项目中创建的所有分支获得一致的生命周期和计算配置，无需为每个分支指定单独的标志。
npm i @neon/config
// neon.ts
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
branch: (branch) => {
if (branch.exists) return {}; // 从不协调已存在的分支
if (branch.isDefault) return { protected: true };
if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
return {
parent: "main",
ttl: "7d", // 临时性：创建后 7 天自动过期（最长 30 天）
postgres: {
computeSettings: {
autoscalingLimitMinCu: 0.25, // 自动缩容到零
autoscalingLimitMaxCu: 1, // 保持一次性分支成本低廉
suspendTimeout: "5m",
},
},
};
}
return {};
},
});
该闭包接收目标分支的只读描述符——name、exists、isDefault、parentId 等——并返回要应用的调整：parent、ttl（自动过期）、protected 和 postgres.computeSettings。这是对上述临时生命周期卫生以及每个 PR / 每次测试模式的声明式补充：无需在每次 neon branches create 时记住 --expires-at，TTL 和计算配置将保存在版本控制中，并应用于每个匹配的分支。
因为 neon checkout 在创建分支时会应用此策略，所以一个新的 preview/* 或 dev-* 分支在创建时就已经设置了过期时间和自动缩容。检出_已存在_的分支不会重新协调它——运行 neon deploy（即 neon config apply 的别名）以将更改应用于已存在的分支。
CI/CD 中的分支管理
Neon 分支在 CI/CD 中的常见用例：
- 每 PR 预览部署： 在 PR 打开时分支，将预览部署到该分支上，PR 关闭时删除。每个 PR 获得一个隔离的数据库分支。将分支的
DATABASE_URL注入到已部署的应用中是特定于托管提供商的——请参见 preview-branches-with-cloudflare、preview-branches-with-vercel 或 preview-branches-with-fly 以获取经过测试的模式。 - CI 中的迁移测试： 在合并前，针对包含生产类数据的分支运行有风险的 Schema 更改。
- Schema 差异可见性： 使用 schema-diff GitHub Action 自动在 PR 上评论数据库层的差异。
示例
示例 1：使用真实数据进行迁移测试
用户输入： “我需要针对生产类数据测试一个有风险的迁移。”
Agent 输出格式：
- 推荐标准分支并解释原因。
- 分享文档链接：https://neon.com/docs/introduction/branching
- 首先检查工具路径（使用
neon --version检查 CLI；仅在 CLI 不可用时才使用 MCP）。 - 提供命令：
neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Zneon connection-string migration-test
示例 2：敏感数据开发工作流
用户输入： “由于合规要求，我们无法复制生产数据。”
Agent 输出格式：
- 推荐仅模式分支并解释原因。
- 分享文档链接：https://neon.com/docs/guides/branching-schema-only
- 首先检查工具路径（使用
neon --version检查 CLI；仅在 CLI 不可用时才使用 MCP）。 - 提供命令：
neon branches create --name compliance-dev --parent main --schema-only --project-id <您的项目ID> --expires-at 2026-12-15T18:02:16Z
- 提及 Beta 支持路径：