pythia-deploy

发布版本

开始时宣布：“正在使用 pythia-deploy — 先预览发布版本中的每条语句。”

**阶段：**询问 → 执行 — 按顺序排列的整组语句会先统一预览并获批，然后逐步运行

使用 sqlplus @release.sql 运行的发布脚本没有快照、没有预览、没有验证，也不会记录第 212 行失败前已执行的内容。 pythia deploy 会通过写入路径逐条运行同一个文件，因此发生故障时会安全停止，并准确列出已执行的内容以及如何撤销。

铁律

A RELEASE RUNS IN ORDER, AS PREVIEWED, AND STOPS AT THE FIRST BROKEN STEP

如何读取脚本

• SQL 中每个 ; 代表一条语句；PL/SQL 单元（CREATE ... PROCEDURE / FUNCTION / PACKAGE / TRIGGER / TYPE）在仅包含 / 的行结束。 字面值或注释中的 ; 或 / 都属于文本。
• SQL*Plus 指令（SET、PROMPT、SPOOL、SHOW ERRORS、WHENEVER、 DEFINE、…）不会在数据库上运行任何内容：它们会被跳过并列出。
• @file / @@file 包含项会被拒绝——请改为列出这些文件； deploy 绝不会运行无人检查过的路径。
• 以下内容会被拒绝，而非跳过：匿名 BEGIN ... END; 块（与 apply 一样）、 EXEC / HOST / CONNECT，以及 ALTER SESSION — 它会悄然改变后续每条语句的运行方式，任何预览都无法呈现这一点。
• 文件按给定顺序运行。如果目录中的每个文件都带有编号（1_、02_、10_、Flyway 的 V3__），则按自然名称顺序运行；否则按每个文件创建的对象排序——表、索引、注释、类型、视图、规范、过程、程序体、触发器、授权、数据。预览会说明采用了哪种顺序。

工作流

1. 整理需要按顺序运行的文件；对发布版本会更改的每个现有对象执行影响分析 （pythia-impact）。
2. 检查这组文件：pythia lint <files> — 必须在预览前修复错误，而非之后修复。
3. 预览：pythia deploy <files>。不会写入任何内容。原样转达预览：每条语句的组、对象、更改行数、影响、! DESTRUCTIVE 和 lint 行，以及差异。策略拒绝会在任何内容运行之前显示 — 转达给开发者，由开发者决定。
4. 询问一次 — 预览会打印 deploy token（10 位十六进制）。开发者通过第一个可用渠道批准 — 使用文本原样为 pythia approve --card <token> 的 AskUserQuestion（Claude Code）、pythia_approve 工具（Codex 启动时所在的环境）、或在其终端中运行 pythia approve <token>；若某个渠道失败，则尝试下一个尚未询问的渠道。
5. 运行：pythia deploy <files> --confirm <token> — 使用相同的文件列表。每条语句都会经过快照 → 应用 → 验证，并拥有独立的日志条目。读取未经过管道处理的退出代码：0 全部完成 · 1 被拒绝（之后的内容均未运行）· 3 已写入但存在问题（在此处停止）。
6. 报告每条语句的结果。若停止：已完成的内容会保留在数据库中（DDL 会自行提交）；其余审批会被撤回；输出会按从最新到最早的顺序列出撤销命令、说明哪些已完成的语句没有撤销操作，以及给出用于恢复执行的 --from N。是继续修复还是还原，由开发者决定。

在覆盖每条语句的自动驾驶租约（pythia-autopilot）下，第 3 步会直接执行发布版本；如果有任何语句未被覆盖，则整个发布版本会退回预览模式，输出会说明具体是哪条语句及原因。

停止后重新运行

停止前的语句已写入数据库；CREATE TABLE、ALTER TABLE ADD 和插入操作不能运行两次。修复失败的语句，然后运行 pythia deploy <files> --from <N> — 为剩余部分重新预览并重新审批。若回填需要先前在同一发布版本中添加的列，则在 DDL 存在之前无法进行评估：先部署 DDL，再使用 --from 部署数据部分。

危险信号 — 如果发现自己有以下想法，请停下

想法	实际情况
“在 sqlplus 里运行更快”	没有快照、没有验证，也没有记录执行停在何处。钩子也会拒绝这种做法。
“第 7 条语句失败了，跳过它继续执行”	后续内容都是基于它编排的。停下并报告，让开发者决定。
“这些包含项没问题，都是我写的”	部署会运行列出并预览过的内容。请列出它们。
“一次审批就涵盖了整个发布，所以我可以编辑文件后重新运行”	令牌与预览过的内容绑定。编辑后 → 重新预览。
“最后一条语句退出码为 3，其他都没问题”	已写入，但存在问题。请报告为有问题，并附上撤销列表。

何时不应使用此技能

• 单个文件中的一条语句 → pythia-apply。
• 设计发布内容中的表或包 → pythia-table、 pythia-package；此技能只负责部署它们。