planetscale-safe-orchestrator

PlanetScale 安全编排器（主技能）

目的

端到端运行完整的 PlanetScale 安全最佳实践技能包。按顺序加载并执行各子技能，累积证据，并生成一份统一的建议报告。第一轮仅进行评估。

不可妥协的安全约定

默认采用只读模式。

你可以检查配置、分支、查询遥测数据、建议、Webhook、角色、备份、流量预算和代码仓库代码。未经明确批准的指定变更集，不得修改 PlanetScale、数据库、代码仓库、网络安全态势、凭据、架构、生产流量控制或自动化端点。

C/D/E 类变更必须根据 ../planetscale-change-gates-and-approval-contract/SKILL.md 获得批准。如有疑问，请停止操作，并将其加入拟议变更集，而不是执行。

有一个例外：如果操作员明确确认风险并根据 ../planetscale-autonomous-execution-mode/SKILL.md 指定范围，则按该技能的状态和暂停规范自主执行，无需逐项变更审批。无论采用哪种方式，下面的评估阶段都相同。

子技能位于本技能旁边的同级文件夹中，并通过相对路径引用；如果引用的路径不存在，请查找 frontmatter 中 name 匹配的同级技能，并改用该技能。

所有 CLI 和 API 用法都必须以官方文档为依据，不得臆测：文档索引位于 https://planetscale.com/docs/llms.txt（在任意文档 URL 后添加 .md 可获取 Markdown 版本），API 参考位于 https://planetscale.com/docs/openapi.yaml。命令或端点失败时，请先查阅文档确认正确用法，再记录证据缺口。工具和访问故障应记录在内部运行日志中，绝不可写入客户报告。

开始之前

1. 完整阅读本文件。

2. 将下面的进度清单复制到工作笔记中，并随进度更新。

3. 收集输入（询问或从 AGENTS.md、MCP 上下文、环境和代码仓库中推断）：

   • 组织 slug
   • 数据库名称
   • 分支名称
   • 引擎：PlanetScale Vitess 或 PlanetScale Postgres
   • 生产分支（一个或多个）
   • 已连接的应用代码仓库路径（如有）
   • 应用语言、框架、ORM、查询构建器、连接池
   • 操作员的容忍级别：仅报告、生成 PR、仅在分支上迁移，或在监督下应用到生产环境

如果缺少输入，请继续探索。不要因信息不完整而停下。

进度清单

复制并跟踪：

Master assessment progress:
- [ ] Phase 0: Safety contract loaded
- [ ] Phase 1: Read-only inventory
- [ ] Phase 2: Engine safety review (Vitess OR Postgres)
- [ ] Phase 3: Query Insights and tags
- [ ] Phase 4: Traffic Control (Postgres only — skip for Vitess)
- [ ] Phase 5: Webhook automation
- [ ] Phase 6: Schema recommendations agent loop
- [ ] Phase 7: Codebase SQLCommenter instrumentation
- [ ] Phase 8: MCP agent operating model
- [ ] Phase 9: Best-practices matrix coverage check
- [ ] Phase 10: Unified customer report
- [ ] Phase 11: Change gates verified — stop, no mutations

接口优先顺序

1. PlanetScale MCP 仅提供洞察的服务 — 无需执行查询即可自主分析
2. 完整的 PlanetScale MCP，具有只读权限范围 — 架构或有限的只读查询
3. pscale CLI 和 pscale api — 结构化清单和精确 API 状态
4. 检查代码仓库 — 代码库分析和监测建议
5. 直接 SQL — 仅在操作员授予数据库读取权限时进行只读检查

操作员声明的接口限制优先于此顺序。如果运行限定为特定接口（例如仅 CLI），则使用这些接口；这不构成冲突，无需变通，也无需在客户报告中记录，范围部分的接口说明除外。

执行计划

每个阶段都要：阅读技能文件、遵循其中说明、记录所需输出，并在后续阶段沿用发现结果。除非清单指示跳过，否则不得跳过阶段。

阶段 0 — 安全约定

阅读：../planetscale-change-gates-and-approval-contract/SKILL.md

熟悉 A–E 类操作。除非操作员明确批准指定变更，否则后续所有阶段均按 A 类操作执行。

阶段 1 — 只读清查

读取并执行：../planetscale-readonly-inventory/SKILL.md

需保留并带入后续阶段的交付内容：

• 附带证据的清查表（来源、路径/命令、时间戳、置信度）
• 缺失证据表
• 风险标记
• 已确认的引擎（Vitess 或 Postgres）
• 分支拓扑和生产分支

如果清查后仍无法确定引擎，请在阶段 2 前先确定引擎。

阶段 2 — 引擎安全审查

准确运行以下其中一项：

引擎	技能文件
Vitess	../planetscale-vitess-safety-review/SKILL.md
Postgres	../planetscale-postgres-safety-review/SKILL.md

交付内容：引擎特定的安全缺口、工作流缺口，以及需要审批的拟议变更。

阶段 3 — Query Insights 和标签

读取并执行：../planetscale-query-insights-and-tags/SKILL.md

交付内容：查询风险表、标签覆盖表、不良/高基数标签、建议的标签架构、候选 Traffic Control 流量切片、候选架构和代码变更。

阶段 4 — Traffic Control（仅适用于 Postgres）

Vitess 跳过此阶段。 将清单项标记为已完成，并注明“ N/A — Vitess”。

对于 Postgres，读取并执行：../planetscale-traffic-control-recommendations/SKILL.md

交付内容：拟议预算（名称、模式、流量切片、规则类型、限制依据、测试/回滚计划）。

如果查询标签不完善，请按该技能的要求注明“先添加标签”，并暂缓推荐强制模式。

阶段 5 — Webhook 自动化

读取并执行：../planetscale-webhook-automation-recommendations/SKILL.md

交付内容：Webhook 清单、缺失的订阅、目标质量审查、自动化机会、不安全的自动化风险。

阶段 6 — 架构建议 Agent 循环

读取并执行：../planetscale-schema-recommendations-agent-loop/SKILL.md

交付内容：逐条建议的分类（类型、严重程度、证据、安全实施路径、验证/回滚计划）。

阶段 7 — 代码库 SQLCommenter 埋点

读取并执行：../planetscale-codebase-sqlcommenter-instrumentation/SKILL.md

仅在没有可用代码库时跳过。在最终报告中注明“未审查代码库”。

交付内容：检测到的技术栈、当前标签状态、建议的软件包/路径、拟议标签架构、可能需要变更的文件。

阶段 8 — MCP Agent 运作模式

读取并执行：../planetscale-mcp-agent-operating-model/SKILL.md

交付内容：建议的 MCP 服务选择、AGENTS.md 补充内容、自主操作的允许项/禁止项、拟议的 Agent 循环。

阶段 9 — 最佳实践矩阵覆盖检查

读取并执行：../planetscale-best-practices-matrix/SKILL.md

根据阶段 1–8 的发现，逐项核对矩阵中的所有条目。每项记录：

• 是否适用：是 / 否 / 未知
• 当前状态
• 缺口
• 建议 ID（见下方 ID 方案）
• 是否需要审批

补齐缺口：如果某项矩阵内容未在先前阶段覆盖，现在收集缺失证据（仅限只读）。

阶段 10 — 统一客户报告

读取并执行：../planetscale-customer-report-template/SKILL.md

将所有阶段的交付内容综合成一份报告。不要直接倾倒各阶段的原始输出——应合并、去重，并按影响排序。

建议 ID 方案

前缀	领域
OBS-*	Insights 和查询标签
VIT-*	Vitess 安全和部署工作流
PG-*	Postgres 角色、pg_strict、Traffic Control、PITR、网络
WEB-*	Webhook 和自动化
APP-*	仓库埋点
AGENT-*	MCP 和 Agent 工作流

在报告中分配稳定的 ID，并在拟议变更集中引用相同的 ID。

排序指引

建议按以下顺序排列：

1. 生产安全和可用性风险（优先级最高）
2. 阻碍问题诊断或 Traffic Control 的可观测性缺口
3. 可缩短平均检测/响应时间的自动化
4. 有明确证据支持的性能和架构改进

阶段 11 — 停止门槛

重新阅读：../planetscale-change-gates-and-approval-contract/SKILL.md

验证：

• 未执行任何 C/D/E 类操作
• 每项拟议变更都包含 ID、目标、接口、效果、风险、回滚方案和测试计划
• 报告以规定的最终句子结尾

**停止。**不要应用变更——除非请求中附有有效的自主模式确认（符合 ../planetscale-autonomous-execution-mode/SKILL.md 的规定）；在这种情况下，先提交报告和执行计划，然后依据该技能直接继续执行。

必需的最终报告结构

使用 ../planetscale-customer-report-template/SKILL.md 中的模板。至少包含以下章节：

1. 范围 — 组织、数据库、分支、引擎、仓库、接口、时间范围；已应用的变更：无

2. 执行摘要 — 用 3–7 条要点说明风险最高的差距和价值最高的改进

3. 当前状态 — 数据库拓扑、安全工作流、可观测性、自动化、仓库监控（附证据）

4. 建议 — 按优先级排列的表格，包含 ID、目标、收益、风险、是否需要审批、先行测试、证据

5. 需审批的拟议变更集 — 每项 C/D 类事项的具体变更、接口、回滚方案、生产影响

6. 有意未应用的变更 — 明确列出未更改的内容

7. 证据附录 — 来源、命令/路径、时间戳、值、备注

8. 规定的最终句子（原文）：

   未应用任何变更。请先批准具体的变更 ID，再执行任何修改。

部分运行的处理方式

如果无法访问 MCP、CLI、API 或仓库：

• 继续使用可用接口
• 在报告中记录缺失的证据
• 降低相关建议的可信度
• 不得臆造状态——标记为未知

报告之后

有两种执行方式：

**逐项审批。**操作员批准具体的变更 ID：

1. 重新阅读 ../planetscale-change-gates-and-approval-contract/SKILL.md
2. 仅执行指定的 ID
3. 生成该技能规定的执行后报告

**自主模式。**操作员明确确认风险并指定范围（“我接受风险——将报告中的所有建议应用到 storefront-demo，包括生产环境”）：

1. 阅读 ../planetscale-autonomous-execution-mode/SKILL.md，并根据其启用契约验证确认内容
2. 提交按依赖关系排序的执行计划，然后从头到尾执行，持续报告状态、逐步验证，并遵守该技能中的停止规则
3. 生成运行摘要和运行日志

切勿将“应用最佳实践”“修复所有问题”或“继续”解读为审批或风险确认。

快速调用

当用户说“运行完整评估”或“运行所有 PlanetScale 最佳实践技能”时：

1. 加载此技能
2. 按顺序运行阶段 0–11
3. 返回统一报告
4. 停止