Back to Details

planetscale-safe-orchestrator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PlanetScale safe orchestrator (master skill)

PlanetScale 安全编排器（核心Skill）

Purpose

用途

Run the complete PlanetScale safe best-practices skill pack end to end. Load and execute each sub-skill in order, accumulate evidence, and produce one unified recommendations report. The first pass is assessment-only.
端到端运行完整的PlanetScale安全最佳实践Skill包。按顺序加载并执行每个子Skill，收集证据，生成一份统一的建议报告。首次执行仅为评估环节。

Non-negotiable safety contract

不可妥协的安全协议

Default to read-only.
You may inspect configuration, branches, query telemetry, recommendations, webhooks, roles, backups, traffic budgets, and repository code. You must not mutate PlanetScale, the database, the repository, the network posture, credentials, schema, production traffic controls, or automation endpoints without explicit approval of a named change set.
Class C/D/E mutations require approval per 
../11-change-gates-and-approval-contract/SKILL.md
. When in doubt, stop and add to the proposed change set instead of executing.
One exception exists: if the operator explicitly acknowledges the risk and names a scope per 
../13-autonomous-execution-mode/SKILL.md
, execution proceeds autonomously under that skill's status and halt discipline instead of stopping for per-change approval. The assessment phases below are identical either way.
Sub-skills are sibling folders next to this skill (for example 
../01-readonly-inventory/SKILL.md
). Some installers rename skill folders to their frontmatter 
name
(for example 
planetscale-readonly-inventory
instead of 
01-readonly-inventory
); if a referenced numbered path does not exist, locate the sibling skill whose frontmatter 
name
matches and use it instead.
Ground all CLI and API usage in the official documentation rather than guessing: the docs index is at https://planetscale.com/docs/llms.txt (append 
.md
to any docs URL for the markdown version) and the API reference is https://planetscale.com/docs/openapi.yaml. When a command or endpoint fails, check the docs for the correct form before recording an evidence gap. Tooling and access failures belong in the internal run log, never in the customer report.
默认采用只读模式。
您可以检查配置、分支、查询遥测数据、建议、Webhooks、角色、备份、流量预算以及代码库代码。未经明确批准的变更集，不得修改PlanetScale、数据库、代码库、网络态势、凭据、架构、生产流量控制或自动化端点。
C/D/E类变更需遵循
../11-change-gates-and-approval-contract/SKILL.md
的要求获得批准。如有疑问，请停止操作并将内容添加到拟议变更集中，而非直接执行。
存在一个例外情况：若操作人员明确确认风险，并根据
../13-autonomous-execution-mode/SKILL.md
指定范围，则将根据该Skill的状态和暂停规则自主执行，而非针对每项变更单独请求批准。无论哪种情况，以下评估阶段均保持一致。
子Skill位于本Skill的同级文件夹中（例如
../01-readonly-inventory/SKILL.md
）。部分安装程序会将Skill文件夹重命名为其前置元数据
name
（例如
planetscale-readonly-inventory
而非
01-readonly-inventory
）；若引用的编号路径不存在，请找到前置元数据
name
匹配的同级Skill并使用它。
所有CLI和API操作均需基于官方文档，而非猜测：文档索引位于https://planetscale.com/docs/llms.txt（任何文档URL后追加`.md`即可获取markdown版本），API参考位于https://planetscale.com/docs/openapi.yaml。当命令或端点执行失败时，请先查阅文档确认正确格式，再记录证据缺口。工具和访问失败需记录在内部运行日志中，不得出现在客户报告中。

Before you start

开始前准备

  1. Read this file completely.
  2. Copy the progress checklist below into your working notes and update it as you go.
  3. Collect inputs (ask or infer from 
    AGENTS.md
    , MCP context, environment, repository):
    • Organization slug
    • Database name
    • Branch name
    • Engine: PlanetScale Vitess or PlanetScale Postgres
    • Production branch or branches
    • Connected application repository path, if available
    • Application language, framework, ORM, query builder, connection pooling
    • Operator tolerance: report-only, PR-generation, branch-only migrations, or supervised production apply
If inputs are missing, continue with discovery. Do not block on completeness.
  1. 完整阅读本文档。
  2. 将下方的进度检查表复制到工作笔记中，并随时更新。
  3. 收集输入信息（可通过询问或从
    AGENTS.md
    、MCP上下文、环境、代码库中推断）：
    • 组织slug
    • 数据库名称
    • 分支名称
    • 引擎：PlanetScale Vitess 或 PlanetScale Postgres
    • 生产分支
    • 已连接的应用代码库路径（若可用）
    • 应用语言、框架、ORM、查询构建器、连接池
    • 操作人员容忍度：仅报告、生成PR、仅分支迁移、或受监督的生产环境应用
若输入信息缺失，继续进行发现环节，无需因信息不全而停滞。

Progress checklist

进度检查表

Copy and track:
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
复制并跟踪：
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

Interface preference order

接口偏好顺序

  1. PlanetScale MCP insights-only server — autonomous analysis without query execution
  2. Full PlanetScale MCP with read-only scope — schema or limited read queries
  3. pscale
    CLI and 
    pscale api
    — structured inventory and exact API state
  4. Repository inspection — codebase analysis and instrumentation recommendations
  5. Direct SQL — read-only introspection only when operator grants database read access
The operator's stated interface constraint overrides this order. If the run is restricted to specific interfaces (for example CLI-only), use those interfaces; this is not a conflict and needs no workaround or note in the customer report beyond the Scope section's interfaces line.
  1. PlanetScale MCP仅洞察服务器——无需执行查询即可自主分析
  2. 具有只读范围的完整PlanetScale MCP——架构或有限只读查询
  3. pscale
    CLI和
    pscale api
    ——结构化资产盘点和精确API状态
  4. 代码库检查——代码库分析和埋点建议
  5. 直接SQL——仅当操作人员授予数据库只读权限时，才可进行只读自省
操作人员指定的接口约束优先于此顺序。若运行限制为特定接口（例如仅CLI），则使用这些接口；这不属于冲突情况，除了在报告的范围部分注明接口信息外，无需在客户报告中添加其他说明。

Execution plan

执行计划

For each phase: read the skill file, follow its instructions, capture its required output, and carry findings forward. Do not skip phases unless the checklist says to skip.
对于每个阶段：阅读Skill文档，遵循其说明，捕获所需输出，并将发现结果带入下一阶段。除非检查表明确说明跳过，否则不得跳过任何阶段。

Phase 0 — Safety contract

阶段0——安全协议

Read: 
../11-change-gates-and-approval-contract/SKILL.md
Internalize operation classes A–E. All later phases operate under Class A unless the operator explicitly approves a named change.
阅读：
../11-change-gates-and-approval-contract/SKILL.md
理解A-E类操作。所有后续阶段均默认采用A类操作，除非操作人员明确批准特定变更。

Phase 1 — Read-only inventory

阶段1——只读资产盘点

Read and execute: 
../01-readonly-inventory/SKILL.md
Deliverables to carry forward:
  • Inventory table with evidence (source, path/command, timestamp, confidence)
  • Missing evidence table
  • Risk flags
  • Confirmed engine (Vitess or Postgres)
  • Branch topology and production branch
If engine is still unknown after inventory, determine it before Phase 2.
阅读并执行：
../01-readonly-inventory/SKILL.md
需带入下一阶段的交付物：
  • 带证据的资产盘点表（来源、路径/命令、时间戳、可信度）
  • 缺失证据表
  • 风险标记
  • 确认的引擎（Vitess或Postgres）
  • 分支拓扑和生产分支
若资产盘点后仍未知引擎类型，需在阶段2前确定。

Phase 2 — Engine safety review

阶段2——引擎安全审查

Run exactly one:
EngineSkill file
Vitess
../02-vitess-safety-review/SKILL.md
Postgres
../03-postgres-safety-review/SKILL.md
Deliverables: engine-specific safety gaps, workflow gaps, and proposed changes requiring approval.
仅运行以下其中一项：
引擎Skill文档
Vitess
../02-vitess-safety-review/SKILL.md
Postgres
../03-postgres-safety-review/SKILL.md
交付物：引擎特定的安全缺口、工作流缺口，以及需要批准的拟议变更。

Phase 3 — Query Insights and tags

阶段3——查询Insights和标签

Read and execute: 
../04-query-insights-and-tags/SKILL.md
Deliverables: query risk table, tag coverage table, bad/high-cardinality tags, recommended tag schema, candidate Traffic Control slices, candidate schema and code changes.
阅读并执行：
../04-query-insights-and-tags/SKILL.md
交付物：查询风险表、标签覆盖表、不良/高基数标签、推荐标签架构、候选流量控制切片、候选架构和代码变更。

Phase 4 — Traffic Control (Postgres only)

阶段4——流量控制（仅Postgres）

Skip this phase for Vitess. Mark checklist item complete with note "N/A — Vitess".
For Postgres, read and execute: 
../05-traffic-control-recommendations/SKILL.md
Deliverables: proposed budgets (name, mode, traffic slice, rule type, limits rationale, test/rollback plan).
If query tags are weak, note "tagging first" per that skill and defer enforce-mode recommendations.
Vitess引擎跳过此阶段。在检查表中标记该项为完成，并注明"N/A — Vitess"。
对于Postgres引擎，阅读并执行：
../05-traffic-control-recommendations/SKILL.md
交付物：拟议预算（名称、模式、流量切片、规则类型、限制依据、测试/回滚计划）。
若查询标签不完善，需根据该Skill的要求注明"先标记"，并推迟强制模式建议。

Phase 5 — Webhook automation

阶段5——Webhook自动化

Read and execute: 
../06-webhook-automation-recommendations/SKILL.md
Deliverables: webhook inventory, missing subscriptions, destination quality review, automation opportunities, unsafe automation risks.
阅读并执行：
../06-webhook-automation-recommendations/SKILL.md
交付物：Webhook资产盘点、缺失的订阅、目标质量审查、自动化机会、不安全自动化风险。

Phase 6 — Schema recommendations agent loop

阶段6——架构建议Agent循环

Read and execute: 
../07-schema-recommendations-agent-loop/SKILL.md
Deliverables: per-recommendation triage (type, severity, evidence, safe implementation path, validation/rollback plan).
阅读并执行：
../07-schema-recommendations-agent-loop/SKILL.md
交付物：每条建议的分类（类型、严重性、证据、安全实施路径、验证/回滚计划）。

Phase 7 — Codebase SQLCommenter instrumentation

阶段7——代码库SQLCommenter埋点

Read and execute: 
../08-codebase-sqlcommenter-instrumentation/SKILL.md
Skip only if no repository is available. Note "no repository reviewed" in the final report.
Deliverables: detected stack, current tagging state, recommended package/path, proposed tag schema, files likely to change.
阅读并执行：
../08-codebase-sqlcommenter-instrumentation/SKILL.md
仅在无代码库可用时跳过。在最终报告中注明"未审查代码库"。
交付物：检测到的技术栈、当前标记状态、推荐包/路径、拟议标签架构、可能需要修改的文件。

Phase 8 — MCP agent operating model

阶段8——MCP Agent运行模式

Read and execute: 
../09-mcp-agent-operating-model/SKILL.md
Deliverables: recommended MCP server choice, AGENTS.md additions, allowed/disallowed autonomous work, proposed agent loops.
阅读并执行：
../09-mcp-agent-operating-model/SKILL.md
交付物：推荐的MCP服务器选择、AGENTS.md补充内容、允许/禁止的自主工作、拟议Agent循环。

Phase 9 — Best-practices matrix coverage check

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

Read and execute: 
../12-best-practices-matrix/SKILL.md
Cross-check every matrix item against Phases 1–8 findings. For each item record:
  • Applies: yes / no / unknown
  • Current state
  • Gap
  • Recommendation ID (see ID scheme below)
  • Approval requirement
Fill gaps: if a matrix item was not covered by earlier phases, gather missing evidence now (read-only only).
阅读并执行：
../12-best-practices-matrix/SKILL.md
将矩阵中的每个条目与阶段1-8的发现结果进行交叉核对。为每个条目记录：
  • 是否适用：是/否/未知
  • 当前状态
  • 缺口
  • 建议ID（见下方ID规则）
  • 批准要求
填补缺口：若某个矩阵条目未被早期阶段覆盖，立即收集缺失证据（仅只读操作）。

Phase 10 — Unified customer report

阶段10——统一客户报告

Read and execute: 
../10-customer-report-template/SKILL.md
Synthesize all phase deliverables into one report. Do not dump raw phase outputs — merge, deduplicate, and rank by impact.
阅读并执行：
../10-customer-report-template/SKILL.md
将所有阶段的交付物整合为一份报告。不得直接输出原始阶段结果——需合并、去重，并按影响程度排序。

Recommendation ID scheme

建议ID规则

PrefixDomain
OBS-*
Insights and query tags
VIT-*
Vitess safety and deploy workflow
PG-*
Postgres roles, pg_strict, Traffic Control, PITR, network
WEB-*
Webhooks and automation
APP-*
Repository instrumentation
AGENT-*
MCP and agent workflows
Assign stable IDs across the report. Reference the same IDs in the proposed change set.
前缀领域
OBS-*
洞察和查询标签
VIT-*
Vitess安全和部署工作流
PG-*
Postgres角色、pg_strict、流量控制、PITR、网络
WEB-*
Webhooks和自动化
APP-*
代码库埋点
AGENT-*
MCP和Agent工作流
在报告中分配稳定的ID。在拟议变更集中引用相同的ID。

Ranking guidance

排序指南

Order recommendations by:
  1. Production safety and availability risk (highest first)
  2. Observability gaps blocking diagnosis or Traffic Control
  3. Automation that reduces mean time to detect/respond
  4. Performance and schema improvements with clear evidence
建议按以下顺序排序：
  1. 生产环境安全和可用性风险（优先级最高）
  2. 阻碍诊断或流量控制的可观测性缺口
  3. 缩短检测/响应时间的自动化措施
  4. 有明确证据的性能和架构改进

Phase 11 — Stop gate

阶段11——停止闸门

Re-read: 
../11-change-gates-and-approval-contract/SKILL.md
Verify:
  • No Class C/D/E actions were taken
  • Every proposed mutation has an ID, target, interface, effect, risk, rollback, and test plan
  • Report ends with the required final sentence
Stop. Do not apply changes — unless a valid autonomous-mode acknowledgment (per 
../13-autonomous-execution-mode/SKILL.md
) accompanied the request, in which case present the report and the execution plan, then continue directly into execution under that skill.
重新阅读：
../11-change-gates-and-approval-contract/SKILL.md
验证：
  • 未执行任何C/D/E类操作
  • 每项拟议变更均包含ID、目标、接口、影响、风险、回滚和测试计划
  • 报告以要求的最终语句结尾
停止操作。不得应用任何变更——除非请求附带有效的自主模式确认（根据
../13-autonomous-execution-mode/SKILL.md
），在此情况下，需提交报告和执行计划，然后根据该Skill的规则直接进入执行环节。

Required final report structure

最终报告必填结构

Use the template in 
../10-customer-report-template/SKILL.md
. Minimum sections:
  1. Scope — org, database, branches, engine, repository, interfaces, time window; changes applied: none
  2. Executive summary — 3–7 bullets on highest-risk gaps and highest-value improvements
  3. Current state — database topology, safety workflow, observability, automation, repository instrumentation (with evidence)
  4. Recommendations — ranked table with IDs, target, benefit, risk, approval needed, test first, evidence
  5. Proposed change set requiring approval — every Class C/D item with exact change, interface, rollback, production impact
  6. Changes intentionally not applied — explicit list of what was not changed
  7. Evidence appendix — source, command/path, timestamp, value, notes
  8. Final required sentence (verbatim):
    No changes have been applied. Approve specific change IDs before any mutation.
使用
../10-customer-report-template/SKILL.md
中的模板。至少包含以下部分：
  1. 范围——组织、数据库、分支、引擎、代码库、接口、时间窗口；已应用变更：无
  2. 执行摘要——3-7条关于最高风险缺口和最高价值改进的要点
  3. 当前状态——数据库拓扑、安全工作流、可观测性、自动化、代码库埋点（附证据）
  4. 建议——按优先级排序的表格，包含ID、目标、收益、风险、是否需要批准、是否先测试、证据
  5. 需批准的拟议变更集——所有C/D类项目，包含具体变更、接口、回滚方案、生产环境影响
  6. 有意未应用的变更——明确列出未执行的变更
  7. 证据附录——来源、命令/路径、时间戳、值、备注
  8. 必填最终语句（原文照搬）：
    No changes have been applied. Approve specific change IDs before any mutation.

Handling partial runs

部分运行的处理

If MCP, CLI, API, or repository access is unavailable:
  • Continue with available interfaces
  • Record missing evidence in the report
  • Lower confidence on affected recommendations
  • Do not invent state — mark unknown
若MCP、CLI、API或代码库访问不可用：
  • 使用可用接口继续操作
  • 在报告中记录缺失的证据
  • 降低相关建议的可信度
  • 不得虚构状态——标记为未知

After the report

报告完成后的流程

Two paths into execution:
Per-change approval. The operator approves specific change IDs:
  1. Re-read 
    ../11-change-gates-and-approval-contract/SKILL.md
  2. Execute only the named IDs
  3. Produce the post-execution report defined in that skill
Autonomous mode. The operator explicitly acknowledges the risk with a named scope ("I accept the risk — apply all report recommendations to storefront-demo, production included"):
  1. Read 
    ../13-autonomous-execution-mode/SKILL.md
    and validate the acknowledgment against its activation contract
  2. Present the dependency-ordered execution plan, then execute end to end with continuous status, per-step verification, and the halt rules from that skill
  3. Produce the run summary and run log
Never interpret "apply best practices", "fix everything", or "go ahead" as either approval or risk acknowledgment.
有两种执行路径：
逐项变更批准。操作人员批准特定变更ID：
  1. 重新阅读
    ../11-change-gates-and-approval-contract/SKILL.md
  2. 仅执行指定ID的变更
  3. 生成该Skill中定义的执行后报告
自主模式。操作人员明确确认风险并指定范围（例如"我接受风险——将所有报告建议应用到storefront-demo，包括生产环境"）：
  1. 阅读
    ../13-autonomous-execution-mode/SKILL.md
    ，并根据其激活协议验证确认信息
  2. 提交按依赖顺序排列的执行计划，然后端到端执行，持续更新状态，每步验证，并遵循该Skill的暂停规则
  3. 生成运行摘要和运行日志
不得将"应用最佳实践"、"修复所有问题"或"继续执行"解释为批准或风险确认。

Quick invocation

快速调用

When the user says "run the full assessment" or "run all PlanetScale best-practices skills":
  1. Load this skill
  2. Run Phases 0–11 in order
  3. Return the unified report
  4. Stop
当用户说"运行完整评估"或"运行所有PlanetScale最佳实践Skill"时：
  1. 加载本Skill
  2. 按顺序运行阶段0-11
  3. 返回统一报告
  4. 停止操作