pythia-write

编写 PL/SQL

开始时宣布：“正在使用 pythia-write——先梳理代码库的约定。”

**阶段：**学习 → 执行 — 先梳理相邻代码，再起草；将其部署到位是 pythia-apply 的工作

**开始前：**如果项目有 .pythia/conventions.md，请先阅读 — 其中的项目规则优先于以下所有通用模式，并且 pythia conventions 会显示 apply 预览将检查的命名模式。如果项目没有该文件，而开发者 描述了项目风格，请提供 pythia conventions --init — 记录一次后， 它会应用于今后的每个会话，无需反复解释。

拥有数千个过程的代码库，早已确定过程应有的样子。你的工作是编写一个 让维护者看不出与现有过程有何不同的过程 — 而不是引入更好的风格。

工作流

1. 找到范例。 pythia similar <NEW_NAME> 会为名称标记相同的现有程序排序； MATCHED_TOKENS 列说明了匹配原因。用 pythia src 打开排名靠前的 两三个程序并模仿：命名、参数前缀、游标风格、错误处理、注释风格。
2. 核实签名。 对于你调用的每个程序： pythia args NAME — 获取实际参数名称、顺序、类型、默认值。绝不要 凭对相似代码的记忆猜测签名。
3. 核实类型。 对于你涉及的每张表：pythia cols TABLE — 然后根据这些列使用 %TYPE / %ROWTYPE 声明变量， 而不是手动照抄当前类型。这样列发生变化时，声明仍然有效。
4. 编写文件。 写入路径强制执行以下规则 — 请在此遵循：
   • 每个文件只包含一个对象。 包规范和包体是两个文件。
   • 文件以 PL/SQL 块的 ; 结尾，最后一行单独放置 /。
   • 对象名称不带限定符，或使用与连接目标完全一致的架构进行限定 — 不匹配会在应用时被拒绝。
   • 非 ASCII 字符串字面量（越南语消息、任何带重音符号的文本）： 绝不要直接粘贴 — 运行 pythia unistr "<text>" 并使用打印出的 unistr('...')，确保文本能在任何客户端/数据库字符集下准确保留。 （COMMENT ON ... IS 是例外：它只接受字面量。）
5. 交付前自行检查。 先运行 pythia lint <file> — 内置标准加上 LEAD 的规则；错误必须在预览前修复。然后对照 reference/patterns.md 再读一遍 — 检查游标和批量处理模式、异常处理规范、绑定变量、提交责任归属。你编写或修改的每条注释都必须经过 pythia-comment。

范围由开发者的描述决定，而不是你

只修改开发者指定的对象。如果影响分析显示有依赖对象会因此出错， 请列出这些对象并提出方案 — 修复它们属于单独的请求，需要单独获得明确批准。“我顺手改了”会让一个被要求修改的表，变成七个未经要求的过程重写。

约定优先于偏好

如果代码库使用显式游标，而你会写 FOR r IN， 那就使用显式游标。如果它的参数前缀看起来过时了，也照样使用。风格混杂的代码库比风格一贯但过时的代码库更糟 — 请另行向开发者提出风格修改建议，绝不要擅自更改。

何时不要使用此技能

• 新建包、API 或触发器的设计 → 先用 pythia-package 设计。
• 表、列、注释 → 用 pythia-table。
• 理解现有代码 → 用 pythia-explore。
• 衡量某项更改会造成什么影响 → 用 pythia-impact（必须已完成）。
• 将文件部署到数据库 → 始终使用 pythia-apply — 绝不要使用 run-sql，也不要使用 sqlplus。