pythia-write

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing PL/SQL

编写PL/SQL

Announce at start: "Using pythia-write — mining the codebase's conventions first."

Before anything: if the project has

.pythia/conventions.md

, read it — house rules there outrank every generic pattern below, and

pythia conventions

shows the naming patterns the apply preview will check.

A codebase with thousands of procedures has already decided how procedures look. Your job is to write one that a maintainer cannot tell from the existing ones — not to introduce a better style.

开始前声明： "正在使用pythia-write工具——优先参考代码库的现有约定规范。"

操作前须知： 如果项目存在

.pythia/conventions.md

文件，请先阅读其中内容——文件内的内部规则优先级高于以下所有通用模式，且

pythia conventions

命令会显示应用预览时将检查的命名模式。

拥有数千个存储过程的代码库早已确定了存储过程的编写风格。你的任务是写出让维护者无法区分新代码与现有代码的程序——而非引入所谓"更优"的风格。

The Workflow

工作流程

Find the models.
```
pythia similar <NEW_NAME>
```
ranks existing programs sharing name tokens; the
```
MATCHED_TOKENS
```
column says why. Open the top two or three with
```
pythia src
```
and imitate: naming, parameter prefixes, cursor style, error handling, comment style.
Anchor the signatures. For every program you call:
```
pythia args NAME
```
— real parameter names, order, types, defaults. Never guess a signature from memory of similar code.
Anchor the types. For every table you touch:
```
pythia cols TABLE
```
— then declare variables with
```
%TYPE
```
/
```
%ROWTYPE
```
against those columns instead of copying the current type by hand. The declaration then survives column changes.
Write the file. Rules the write path enforces — follow them here:
- One object per file. Package spec and body are two files.
- End the file with the PL/SQL block's
```
;
```
  and a final line holding
```
/
```
  .
- Name the object unqualified, or qualified with the exact schema the connection targets — a mismatch is refused at apply time.
- Non-ASCII string literals (Vietnamese messages, any accented text): never paste raw — run
```
pythia unistr "<text>"
```
  and use the printed
```
unistr('...')
```
  , so the text survives every client/DB charset exactly.
Check yourself before handing off. Reread against
```
reference/patterns.md
```
— cursor and bulk patterns, exception discipline, bind variables, commit ownership.

查找参考模板。
```
pythia similar <NEW_NAME>
```
命令会对包含相同名称标识的现有程序进行排序；
```
MATCHED_TOKENS
```
列会说明匹配原因。使用
```
pythia src
```
命令打开排名靠前的2到3个程序并进行模仿：包括命名方式、参数前缀、游标风格、错误处理和注释风格。
锚定签名信息。 对于你调用的每个程序，执行
```
pythia args NAME
```
命令——获取真实的参数名称、顺序、类型及默认值。绝不要凭借对相似代码的记忆来猜测签名。
锚定数据类型。 对于你操作的每个表，执行
```
pythia cols TABLE
```
命令——然后使用
```
%TYPE
```
/
```
%ROWTYPE
```
来声明变量，而非手动复制当前类型。这样变量声明能在表列变更时自动适配。
编写文件。 编写过程需遵循以下规则：
- 每个文件仅包含一个对象。 包规范和包体分别为两个文件。
- 文件末尾需以PL/SQL块的
```
;
```
  结尾，并在最后一行添加
```
/
```
  。
- 对象名称可以不带限定符，或使用连接目标的准确模式名进行限定——若名称不匹配，应用时会被拒绝。
- 非ASCII字符串字面量（如越南语消息、带重音的文本）：绝不要直接粘贴原始文本——执行
```
pythia unistr "<text>"
```
  命令，并使用输出的
```
unistr('...')
```
  格式，确保文本在所有客户端/数据库字符集下都能准确保留。
交付前自查。 对照
```
reference/patterns.md
```
文件重新检查代码——包括游标和批量处理模式、异常处理规范、绑定变量、提交权限。

Scope is the developer's sentence, not yours

修改范围由开发者指定，而非自行扩展

Change ONLY the objects the developer named. When impact shows dependents that will break, you REPORT them with the list and a proposal — fixing them is a separate request that needs its own explicit approval. "While I was there" is how an asked-for table edit becomes seven unasked procedure rewrites.

只修改开发者指定的对象。当影响分析显示有依赖对象会被破坏时，你需列出这些对象并提交修复建议——修复它们是单独的请求，需要获得明确批准。"顺手修改"往往会导致原本只要求修改一张表，最后却变成了七个未被要求的存储过程重写。

Conventions outrank preferences

约定规范优先于个人偏好

If the codebase writes explicit cursors where you would write

FOR r IN

, write explicit cursors. If its parameter prefixes look dated, use them anyway. A mixed-style codebase is worse than a consistently dated one — propose style changes to the developer separately, never silently.

如果代码库中使用显式游标，而你习惯使用

FOR r IN

语法，那么请使用显式游标。如果其参数前缀看起来过时，仍需遵循。风格混杂的代码库比风格统一但过时的代码库更糟糕——请单独向开发者提出风格变更建议，绝不要擅自修改。

When NOT to use this skill

何时不使用此技能

Understanding existing code →
```
pythia-explore
```
.
Measuring what a change breaks →
```
pythia-impact
```
(must already be done).
Landing the file on the database →
```
pythia-apply
```
, always — never
```
run-sql
```
, never
```
sqlplus
```
.

理解现有代码 → 使用
```
pythia-explore
```
工具。
评估变更影响范围 → 使用
```
pythia-impact
```
工具（必须已完成此步骤）。
将文件部署到数据库 → 始终使用
```
pythia-apply
```
工具——绝不要使用
```
run-sql
```
或
```
sqlplus
```
。