planetscale-mcp-agent-operating-model

MCP Agent 运行模式

目的

定义 Agent 应如何安全地使用 PlanetScale MCP。Agent 应利用生产遥测数据生成有用的工作，同时避免自主更改生产环境。

默认 MCP 选择

如果任务只需要 Insights 和 Schema Recommendations，请使用 PlanetScale MCP 只读分析服务器。

只有在任务明确要求访问 Insights 以外的数据库或架构时，才使用完整的 PlanetScale MCP 服务。优先选择只读范围。

完整的 MCP 服务提供查询执行工具。除非操作人员明确批准某项特定的非生产操作，或经过仔细审核的生产操作，否则应将写入查询工具视为禁用。

AGENTS.md 指南

两个用途不同的文档都名为 AGENTS.md：

1. CLI Agent 指南 — 随 pscale 一同提供（位于 planetscale/cli 仓库中的 AGENTS.md，或通过 pscale agent-guide --format json 获取）。涵盖身份验证、--format json、标志 的位置以及 pscale sql。在此技能包中加载技能 planetscale-pscale-cli-automation， 可遵循相同的约定。

2. 项目 Agent 指南 — 应用仓库中的 AGENTS.md（或 同等文件）。涵盖此应用的数据库目标及审批政策。

在仓库中工作时，建议在 AGENTS.md 或同等项目说明中添加项目数据库 目标配置部分，内容包括：

• PlanetScale 组织。
• 数据库。
• 分支。
• 引擎：Vitess 或 Postgres。
• 生产分支名称。
• Agent 是否可以使用 MCP 只读分析模式或完整 MCP。
• 是否禁止写入查询。
• 架构、Traffic Control、Webhook、角色和网络更改所需的审批流程。

未经批准，不要编辑 AGENTS.md。

默认允许的自主任务

• 读取 Insights。
• 读取架构建议。
• 读取架构元数据。
• 读取现有 Webhook 和 Traffic Control 配置。
• 读取分支元数据。
• 检查仓库代码。
• 将查询模式与代码关联起来。
• 创建问题。
• 发起拉取请求。
• 创建开发分支。
• 在非生产开发分支上应用 DDL 和迁移。
• 向受审核工作流保护的分支发起部署请求。
• 起草 Traffic Control 预算提案。
• 起草 Webhook 接收端需求。

如果存在 PR + 部署请求工作流，架构建议的默认交付物应是完整、可审核的工作单元：已应用 DDL 的开发分支、附有证据（指纹、指标、预期效果）的 PR，以及已发起的部署请求。人工负责作出合并/部署决定，而不是推动提案从无到有。

默认不允许（需审核门控的操作及不可审核的变更）：

• 对生产环境执行写入 SQL。
• 直接在生产分支上执行 DDL。
• 部署部署请求／将架构应用到生产环境。
• 合并拉取请求。
• 创建 Webhook。
• 创建或启用 Traffic Control 预算。
• 轮换凭据。
• 更改角色。
• 更改 IP 限制或专用连接。
• 恢复或提升分支。

Agent 工作循环

每日建议循环

1. 读取未解决的架构建议。
2. 读取排名靠前的 Insights 回归问题。
3. 将问题与仓库代码关联起来。
4. 生成按优先级排序的问题或 PR。
5. 由人工审核。
6. 任何影响数据库的操作均由人工批准。

异常处理循环

1. 接收或检查异常。
2. 收集受影响的查询模式和标签。
3. 找出源路由／作业／部署。
4. 撰写事件说明和拟议的修复方案。
5. 如果代码修复方案明确，则发起 PR。
6. 如果需要更改数据库，则仅创建拟议的变更集。

Traffic Control 循环

1. 根据 Insights／标签识别不安全的流量切片。
2. 起草 warn 预算提案。
3. 由人工批准创建。
4. 观察警告。
5. 仅在验证后由人工批准启用 enforce 模式。

定时循环（cron / Automations）

上述循环以交互方式运行。它们也可以按计划运行，无需人工介入，分为两个层级。Tier 2 需要根据 ../planetscale-autonomous-execution-mode/SKILL.md 获得长期授权；Tier 1 无需授权。

两个层级的所有定时循环都必须：在运行开始时重新读取授权，将状态流式传输到已配置的交付渠道，持久化运行日志，并避免重复提交（对于指纹/建议 ID 相同且已处于打开状态的问题，不要再次提交）。

Tier 1 — 通过审核工作流提出建议（无需授权）

• 建议到 PR 循环（每天）：通过 MCP 列出待处理的架构建议；对于每个符合工作流的新建议（增量或破坏性——PR 审核是把关环节），创建开发分支、应用 DDL、提交包含指纹、指标和预期效果的 PR，并创建部署请求。当人工可以通过一次合并/部署操作发布时，可审核单元即告完成。输出：每条建议对应一个分支、PR 和部署请求。
• 回归监控（每小时或每次部署后）：将主要模式与已存储的基线进行比较（p50/p99、读取行数、执行次数）；出现重大回归时，从查询标签中识别部署 SHA，并提交一份将模式与提交范围关联起来的报告。输出：报告。
• 标签覆盖率审计（每周）：衡量带有标签的查询时间占比；列出未标记但成本较高的模式及可能涉及的代码路径；创建或更新一条跟踪问题。输出：问题。
• 异常分诊（由 webhook 触发，不轮询）：收到 branch.anomaly 时，收集受影响的模式，判断可能原因，并向事件频道发布分诊说明。输出：分诊说明。
• 安全态势漂移检查（每天）：将当前的安全迁移标志、webhook 配置、角色列表和备份计划与上一份评估报告进行差异比较；报告任何漂移。输出：报告。

Tier 2 — 执行审核把关后的操作（需要长期授权）

• 建议部署器（每天，在 PR 循环之后）：部署符合白名单条件的待处理部署请求——通常是“增量 DDL、PR 已获批准或基于待处理建议创建、部署时设有回滚窗口、每次运行最多 N 个”——然后通过架构读取验证，并针对目标指纹进行后续 Insights 检查。只有当授权规定了可在运行时验证的界限时，才能自主部署破坏性 DDL（例如：“仅删除过去 30 天内读取次数为零的索引，并在运行时通过 Insights 确认”）。如果组织要求部署前必须获得 PR 批准，则已批准的 PR 即满足审核把关要求，授权仅涵盖机械式部署。
• 分支清理（每周）：删除超过授权时限且没有待处理部署请求的开发分支；绝不操作生产分支或受保护分支。
• 警告预算维护器（每周）：为符合白名单条件、近期发现的高成本切片创建警告模式 Traffic Control 预算；报告现有预算的警告计数。除非授权指定了具体预算，否则绝不自主进入强制模式。
• 凭据过期强制处理（每天）：仅在授权列明受影响角色且已有轮换运行手册的情况下，删除或标记超过授权最大有效期限的密码。

循环反模式

• 使用 cron 轮询 MCP 来获取 webhook 已经传送的事件——应使用 webhook 作为触发器；cron 应用于基线、扫描和审计。
• Tier 2 循环的白名单描述的是“保持系统健康”之类的意图，而不是有界操作。
• 执行变更却没有用于发送状态的交付渠道的循环。
• 无界扇出：一次运行应用所有待处理建议，且没有每次运行的数量上限。

查询执行安全措施

对于读取查询：

• 如果有副本，优先使用副本。
• 当分支配置了副本时，planetscale_execute_read_query 默认会将读取路由到副本（use_replica: true）。只有在任务需要主库读取语义时，才设置 use_replica: false，例如检查写入后立即的状态或仅主库具备的行为。
• 为 Agent 工作添加来源标签/注释。
• 避免不受限制的扫描。
• 除非获得明确批准，否则不要在生产环境中使用 EXPLAIN ANALYZE。
• 限制结果大小。
• 除非必要且已获批准，否则不要查询敏感列。
• 对于启用了行级安全策略的 Postgres 表，请记住，MCP 读取角色使用 pg_read_all_data，且不会绕过 RLS。如果读取查询返回零行或计数为零，且 MCP 响应警告 RLS 可能正在过滤结果，则在通过批准的路径确认前，应将结果视为经策略过滤或未知；不要断定表为空。
• 调试 Postgres 高 CPU 使用率时，请使用按 CPU 使用率排序的 Insights 数据（通过 MCP（如可用），或在 Insights API 上使用 sort=cpuTime）。CPU 时间指标仅适用于 Postgres；不要在 Vitess 上请求相同的按 CPU 排序视图。

对于写入查询：

• 默认禁止。
• 如果获得批准，优先使用非生产分支。
• 必须审查确切的 SQL。
• 必须制定回滚计划。
• 必须确认分支和数据库名称。

输出

返回：

• 推荐的 MCP 服务选择。
• 所需权限范围。
• 要添加的 AGENTS.md 指令。
• 允许自主执行的工作。
• 禁止的工作。
• 提议的 Agent 工作循环。
• 审批关卡。

最后写上：

“未使用任何 MCP 写入工具或数据库变更操作。”