# 面向大模型生成网表的引脚与节点命名规范 v1

目的：让大模型生成的 `.cir` 网表更容易被人审阅，并为 schematic viewer 提供明确、简洁的布局提示。本文是生成约定；viewer 已接入八类前缀的基本角色识别、block 端口分边与布局提示。差分对的对称排布和全图电位分层尚未保证。普通 SPICE 节点仍可使用原名称，不符合本规范不代表网表无效。

## 1. 核心约定

只记住三件事：**用前缀表达角色，用主体表达功能，用 `_P` / `_N` 表达差分配对。**

节点名和子电路形式端口统一使用大写 ASCII 字母、数字及下划线，采用 `角色_功能` 格式，例如 `IN_AUDIO`、`OUT_AUDIO`。除全局参考地 `0` 外，名称以字母开头。不要依赖大小写区分节点，不在名称中使用空格、汉字、正负号、斜杠或层级路径分隔符。

这些限制是本规范的可移植命名子集，不是对 SPICE 全部合法名称的重新定义。不要批量重命名未经审计的既有网表或第三方模型库。

## 2. 八个角色前缀

| 前缀 | 含义 | 示例 | 默认布局提示 |
| --- | --- | --- | --- |
| `IN_` | 当前模块的信号输入、控制或测量输入 | `IN_AUDIO`、`IN_ENABLE` | 左侧 |
| `OUT_` | 当前模块的信号输出 | `OUT_AUDIO`、`OUT_SENSE` | 右侧 |
| `IO_` | 双向或无法赋予单一方向的接口 | `IO_BUS`、`IO_TANK` | 不强制方向 |
| `PWR_` | 供电网络 | `PWR_VDD`、`PWR_ANALOG` | 通常在上方，服从已知电位 |
| `RET_` | 电源回流、参考地或低侧供电网络 | `RET_GND`、`RET_VSS` | 通常在下方，服从已知电位 |
| `BIAS_` | 直流偏置或参考电压网络 | `BIAS_VCM`、`BIAS_VREF` | 靠近使用者；可确定时按电位排序 |
| `FB_` | 当前模块的内部反馈网络 | `FB_GAIN`、`FB_PHASE` | 靠近反馈路径，尽量绕开主链 |
| `N_` | 不属于以上角色的内部节点 | `N_COLLECTOR`、`N_FILTER` | 根据连接结构排布 |

每个名称只使用一个角色前缀。功能主体使用简短英文单词或常见缩写，可包含下划线。不要叠加成 `IN_OUT_AUDIO`，也不要为每个物理引脚增加新的角色前缀。

`PWR_` 不保证正电压，`RET_` 不保证零电压或负电压；它们表示设计者的供电与回流意图。节点电位必须由实际电路或显式说明确定。

## 3. 引脚角色与网络角色分开理解

`.SUBCKT` 形式端口的名称描述**该模块内部视角**。同一条实际网络可以连接某个模块的 `OUT_SIG` 和另一个模块的 `IN_SIG`，这是正常的级联关系。

实际网络名只描述其所属作用域中的角色。顶层连接两个处理级的网络可命名为 `N_STAGE1`，不能要求一条网同时改名为输入和输出。viewer 应优先使用每个实例的形式端口判断该 block 的左右方向，再用实际网络名补充全局排布线索。

`IN_` / `OUT_` 表示信号功能，不表示瞬时电流方向，也不改变器件在 SPICE 中的端口顺序。普通电阻、电感、电容的两端不需要强行命名为输入和输出。

## 4. 地、供电与偏置

- 顶层真正的全局参考地使用 `0`。不要用 `GND` 或 `RET_GND` 的名字代替与 `0` 的实际连接。
- 子电路需要可复用的接地接口时，形式端口使用 `RET_GND`，实例化时明确连接到 `0` 或指定的局部参考节点。
- 推荐正电源名 `PWR_VDD`，低侧或负电源名 `RET_VSS`。多电源域用功能区分，如 `PWR_ANALOG`、`PWR_DIGITAL`、`RET_ANALOG`。
- 偏置采用 `BIAS_VCM`、`BIAS_VREF` 等功能名，避免把 `1V8` 等数值写入名称。数值由源、参数或电路决定，修改电压时无需改名。
- 浮动电源、隔离回流和虚拟地不能仅因名字相似而连接到 `0`；默认不要通过 `.GLOBAL` 将局部网络变成全局网络。

若有必要，可用普通 SPICE 整行注释解释意图，例如 `* BIAS_VCM: nominal 1.65 V relative to 0`。该注释只供人审阅，不是已实现的机器指令，也不是工作点验证结果。

## 5. 差分、通道和重复结构

差分信号使用相同主体及末尾 `_P` / `_N`：`IN_AUDIO_P` 与 `IN_AUDIO_N`、`OUT_AUDIO_P` 与 `OUT_AUDIO_N`。`P/N` 表示成对信号的极性约定，不表示两个节点一定处于正/负直流电压。

多通道将通道号放在功能主体末尾、差分后缀之前，例如 `IN_AUDIO_CH1_P`、`IN_AUDIO_CH1_N`、`OUT_AUDIO_CH2`。同一项目保持一致，避免混用 `CH1`、`CHANNEL_1` 和 `A1` 表示同一个通道。

不要把 `_N` 同时用作低有效标记。低有效控制使用 `_ACTLOW`，如 `IN_ENABLE_ACTLOW`。差分配对必须同时存在 P、N 两个名称，不根据单独一个 `_N` 猜测配对关系。

## 6. 子电路与器件命名

新生成子电路推荐采用以下形式端口顺序：**IN → IO → OUT → PWR → RET**，同组内保持固定顺序，差分对 P 在前、N 在后。确需外部暴露的偏置端口可放在 PWR 之前；反馈输入若在模块边界上充当信号输入，命名为 `IN_FB`。

这是新定义的阅读约定。已有定义、第三方库和器件模型保持原顺序；实例的实参顺序必须严格匹配对应 `.SUBCKT` 定义，不能为了符合本规范而单独调整一端。

器件位号仍由真实 SPICE 类型前缀开头，例如 `R_BIAS1`、`C_FILTER1`、`Q_INPUT1`、`M_PULLDOWN1`、`V_SUPPLY1`、`X_STAGE1`。节点角色前缀不适用于器件位号，不能把电阻命名为 `BIAS_R1`。

同一子电路的局部节点可在不同实例中重复使用；不要手工给每个局部节点拼接完整实例路径。层级展开应由 viewer 根据真实实例作用域生成唯一身份。

## 7. 完整示例

以下网表展示两级 RC 网络的接口命名与位置对应；它是命名示例，不用名称宣称电路性能。

```spice
* Two-stage RC naming example
.SUBCKT RC_STAGE IN_SIG OUT_SIG RET_GND PARAMS: RVAL=1k CVAL=10n
R_SERIES IN_SIG OUT_SIG {RVAL}
C_SHUNT OUT_SIG RET_GND {CVAL}
.ENDS RC_STAGE

V_INPUT IN_SIG 0 DC 0 AC 1
X_STAGE1 IN_SIG N_STAGE1 0 RC_STAGE RVAL=1k CVAL=10n
X_STAGE2 N_STAGE1 OUT_SIG 0 RC_STAGE RVAL=2k CVAL=10n
R_LOAD OUT_SIG 0 100k
.AC DEC 20 10 1Meg
.END
```

在第一个实例中，形式端口 `OUT_SIG` 对应实际网络 `N_STAGE1`；在第二个实例中，形式端口 `IN_SIG` 也对应 `N_STAGE1`。因此，端口方向应按实例解释，不能用网络名替代实例引脚身份。

## 8. 可直接交给大模型的生成要求

> 生成标准 SPICE `.cir` 网表，节点和 `.SUBCKT` 端口使用大写 ASCII 字母、数字、下划线。以 IN_、OUT_、IO_、PWR_、RET_、BIAS_、FB_、N_ 表达当前作用域中的角色；不确定方向时使用 IO_ 或 N_，不要猜测。差分对使用相同主体和末尾 _P/_N，低有效控制用 _ACTLOW。顶层参考地使用 0，子电路地端口使用 RET_GND 并在实例中显式连接。新建子电路按 IN、IO、OUT、PWR、RET 排列端口；外露偏置端口放在 PWR 前。实例端口顺序严格匹配定义。器件位号保留真实 SPICE 类型前缀。局部节点交由子电路作用域隔离，不滥用 .GLOBAL。名称仅表达功能，不代替真实接线、电位分析或器件极性。第三方模型和已有接口保持原样。

## 9. 人工审阅与 viewer 接入边界

人工快速检查：输入输出是否从模块自身视角命名，X 实例是否逐项匹配定义，地是否实际接到 `0`，差分对是否齐全，供电/偏置是否有真实电路依据，器件位号是否保留类型前缀。

viewer 的前缀识别忽略大小写，仅匹配完整前缀边界（如 `IN_`），不把 `INPUT` 或 `OUTER` 等任意名称视为规范标签；形式端口角色按实例保留。后续差分配对识别应在同一作用域中按相同主体匹配。命名生成的语义来自命名约定，不能覆盖电气事实或用户显式设置。

兼容旧网表时，形式端口的确切名称 `in/input/out/output` 可作为弱方向提示，`vdd/vcc/vss/vee` 可作为弱供电角色提示；这些提示与规范前缀分开记录来源，不合并节点，也不改变 `.SUBCKT` 的端口顺序。未命名的形式端口若实际接到已确认的供电/参考网络，可继承该网络的布局角色。

对未采用本规范的名称正常解析和渲染，角色保持未知或使用可解释的弱提示。对不完整差分对、名称与确定电位矛盾等情况给出可审阅提示；不自动重命名、交换端口、合并网络或补造连接。

布局实现细节见 [circuit_schematic_layout_rules.md](circuit_schematic_layout_rules.md)。本规范只增加一份便于生成与审阅的契约，不改变 SPICE 电气语义。

## 10. 可选的布局描述注释 v1

在 `.cir` 标题之后、器件语句之前放置一个注释块。每行均以 SPICE 注释符 `*` 开头；普通 SPICE 软件会忽略整个块。它描述视觉包含和相对位置，不定义连接，不实例化子电路，不改变 `.SUBCKT` 端口顺序，也不代表时间顺序。

```spice
* @layout begin v1
* priority-cap 10
* group CHANNELS row {
*   group CHANNEL1 column { XOSC1 XFRONT1 XIQ1 }
*   group CHANNEL2 column { XOSC2 XFRONT2 XIQ2 }
*   group CHANNEL3 column { XOSC3 XFRONT3 XIQ3 }
* }
* group FEEDBACK row { XFB1 XFB2 XFB3 }
* place CHANNELS above FEEDBACK
* @layout end
```

以上实例名是语法示意，必须替换为网表中实际存在的位号。

| 语句 | 含义 |
| --- | --- |
| `group NAME row { MEMBERS }` | 命名视觉组，成员按书写顺序从左到右排列 |
| `group NAME column { MEMBERS }` | 命名视觉组，成员按书写顺序从上到下排列 |
| `group NAME classic { MEMBERS }` | 晶体管功能级，内部按连接及电流通路自动布局，不按成员书写顺序锁定位置 |
| `row { MEMBERS }` / `column { MEMBERS }` | 匿名视觉组，可嵌套在组中 |
| `place A left-of B` | A 位于 B 左侧 |
| `place A above B` | A 位于 B 上方 |
| `priority-cap N` | 有效端口优先级上限，默认 10，允许整数 3–64 |

`MEMBERS` 可以是实际器件名、实际子电路实例路径或视觉组名，以空白分隔；允许多行书写和大括号嵌套。关键字使用表中的小写形式，引用名称匹配忽略大小写。标识符以字母、`_` 或 `@` 开头，后续允许字母、数字、`_ . / % : @ -`；不支持带空格的名字、通配符、箭头、电气连线声明或 JavaScript 表达式。嵌套实例使用 viewer 的完整实例路径，如 `XAMP/XBIAS`；遇到特殊字符时采用 viewer 导出的路径编码。

每个作用域只允许一个 `@layout begin v1` / `@layout end` 块，最多 256 个视觉组。实例与器件只能属于一个叶级视觉组，视觉组只能有一个父组；组名应避免与器件/实例名重名。循环包含、重复归属、不存在的位号、未知语句和循环相对约束均报错，不静默忽略。`place` 用于互不包含的组或实例，不允许将祖先与后代互相定位；多个 `place` 应写成一致的排列链，优先用嵌套 row/column 表达复杂关系。

引用一个折叠实例时，排列其 block；在同一张顶层图中展开后，内部器件继续属于该实例的视觉区域。头部描述只约束顶层页面；进入实例独立内部页面时，不继承上层的 row/column、视觉组、相对位置或 priority-cap。内部页面重新采用自动器件骨架及适用的经典晶体管级规则；电气端口、网络和已确认电位仍保留。布局描述不是完整 ELKT，而是转换为 ELK 图约束的专用小语言；不暴露底层 ELK 参数。

大模型生成要求补充：先按真实电路理解功能链与反馈，再写视觉分组。重复通道通常放在同一个 row；每个通道内部可用 column 表达振荡器、缓冲、采样和处理的层级。反馈通路仍由真实器件语句连接，禁止为满足视觉排列改写节点或补造器件。

### 子电路定义内的局部布局

可在 `.subckt` 与 `.ends` 之间使用同一语法，约束该定义的独立内部页。成员采用定义内相对位号，如 `Q1`、`XBIAS/Q2`；也可用正式端口名引用本页接口标记，如 `IN_P`、`PWR_VCC`。局部组名按本作用域检查，不受顶层同名器件影响。

顶层与每个定义可各有一个描述块。打开实例时仅采用该定义自己的描述，不继承父级描述；定义没有描述时仍采用自动布局。当前图内选择性展开不会自动套用后代定义的局部描述，需进入其独立内部页查看。描述块仍不创建电气连接，SPICE 仿真器将其作为普通注释。

### 经典功能级的自动就近布局

例如 `group GAIN classic { Q16 Q17 Q18 Q22 R7 R8 R11 R12 C1 }`。外层仍可用 row/column 排列功能级；classic 内部不加成员顺序约束。普通器件与接口标记不会被包装成独立子电路。当前每级支持 1–12 个晶体管且不含折叠子电路；不适用或无法安全接线时显示自动布局回退原因，不能宣称经典模式已生效。

不要将所有电阻、电容再逐个用 row/column 固定位置，否则会覆盖自动就近意图。没有描述块的独立晶体管页面也会尝试经典模板（最多 32 个有源器件、80 个图元），仍须通过障碍与网络接触检查。该数量限制是实现边界，不是电气语义。

### 朝向及电源轨的自动决策

classic 成员的书写顺序不指定 B/G 朝向。viewer 可按真实同网邻居选择朝左或朝右，C/E、D/S 引脚身份不变；不需要额外镜像注释。含 classic 功能级的离散器件页优先共用按已确认电压高低排序的供电主干，供电不作为级间信号链排列。上层大型子电路的 row/column 关系仍有效；无法满足避障与连接检查时显示回退原因。


## 结构配对与控制极朝向（layout v13）

大模型生成管级网表时，应在当前 `.SUBCKT` 的 `@layout` 块中同时声明已知结构。顶层网表可使用自己的块。声明是普通 SPICE 注释，不改变器件、模型、引脚顺序及节点连接。

```spice
* @layout begin v1
* pair differential { Q1 Q2 Q3 Q4 }
* pair mirror { Q5 Q6 Q7 R1 R2 }
* pair mirror { Q8 Q9 }
* pair mirror { Q11 Q10 R4 }
* pair mirror { Q12 Q13 }
* pair vbe { Q18 R7 R8 }
* face Q14 right
* face Q20 left
* group CORE row {
*   group BIAS classic { Q10 Q11 Q12 R4 R5 }
*   group OUTPUT classic { Q13 Q14 Q15 Q20 R9 R10 OUT_SIG }
* }
* @layout end
```

上例展示语句形式，完整电路还需将其余器件列入适当的功能区域。规则如下：

| 语法 | 含义 |
| --- | --- |
| `pair mirror { QREF QOUT }` | 声明双管电流镜；按电气连接校验参考管与输出管，二者同排，B/G 相向 |
| `pair mirror { QREF QOUT QHELP R1 R2 }` | 带辅助管、退化电阻的电流镜；辅助器件全部列出，硬配对仍只覆盖参考管与输出管 |
| `pair differential { Q1 Q2 }` | 声明共尾差分对，须存在实际尾偏置连接 |
| `pair differential { Q1 Q2 Q3 Q4 }` | 声明互补复合差分输入级，两对分别并排 |
| `pair vbe { QBIAS RUP RDOWN }` | 声明 VBE 倍增器，校验 C–R–B–R–E；目前用于被动元件方向和邻近偏好，未固定三元件整体模板 |
| `face Q14 right` | BJT 的 B 或 FET 的 G 朝右；也可写 `left`。固定该朝向并跳过该管的镜像试排 |

- 配对使用当前作用域内的真实器件名称；不使用节点名或功能组名代替器件。子电路内部使用本地位号，进入实例时自动绑定路径。祖先的声明不继承到子页面。
- **当前页有 `pair` 声明时，只校验声明的小结构，不进行整图结构搜索。** 应列出希望使用的全部结构；未声明的结构不自动补全。没有 `pair` 时才启用整图识别回退。无效声明报错，不通过自动识别掩盖错误。
- 不存在的器件、重复成员、不匹配的连接或模型极性、`face` 与配对朝向冲突均报错。显式声明不允许修改电气连接。
- 同区域双管镜保持相邻；不同 classic 功能区域的电流镜允许隔着其他功能级，但要求 B/G 同一水平线，不要求两个区域合并。当前跨区域对齐由同一 row 容器下的经典区域实现；布局求解不收敛时明确报错。
- 仅有配对声明时仍采用自动经典布局，不必额外编造功能区域。可选 `face` 用于进一步减少方向搜索；省略时保留局部朝向试排。含声明的页面不进行多轮组合镜像搜索。
- 建议设计阶段生成顺序：先验证电气连接，再列配对，随后定义功能区域，最后指定必要的 B/G 朝向。不要为了让声明通过而改动原本电路连接。


## 更多经典双管结构（layout v14）

以下声明与现有 `pair mirror`、`pair differential` 共用一个 `@layout` 块。角色由实际连接确定，不依赖位号；支持 NPN / PNP 对偶结构。

```spice
* pair darlington { QDRIVER QOUTPUT }
* pair sziklai { QDRIVER QOUTPUT }
* pair cascode { QLOW QHIGH }
* pair push-pull { QUPPER QLOWER RUPPER RLOWER }
```

| 声明 | 保守拓扑校验 | 布局处理 |
| --- | --- | --- |
| `darlington` | 同极性、共集电极，驱动管 E 接输出管 B，驱动分支无多输出歧义 | 同区域内按信号级联紧凑错层放置 |
| `sziklai` | 互补极性，驱动管 C 接输出管 B，驱动管 E 接输出管 C，驱动节点无第三个有源端口 | 互补反馈双管，紧凑错层放置 |
| `cascode` | 同极性，下管 C 接上管 E，控制极不同，中间节点未接已知电源且无额外有源端口 | 按电流通路区分上下管，紧凑错层放置 |
| `push-pull` | 上 NPN、下 PNP，集电极供电电位顺序已确认，E 直接或经一个电阻汇到同一输出 | 保留方向与邻近软偏好，不强制把整个输出级包为刚性方块 |

直接共 E 的互补射随对可只写两管；存在退化/输出电阻时应把这些电阻列入声明。Sziklai 的带二极管变体、Wilson 镜和 folded cascode 不属于本版规则。规则证明的是局部连接形状，不证明静态工作点、增益或稳定性。

同区域的差分与电流镜优先保留，重叠器件不重复硬打包。复杂整图若新双管模板妨碍安全供电接入，会明确提示退回邻近布局；不会牺牲原有共用供电轨或静默丢器件。可通过分为合适的 `classic` 功能区域提高模板适用性。

定义参考：[ADI 的 Darlington / Cascode 术语](https://wiki.analog.com/university/courses/electronics/text/glossary)、[ADI 的 Sziklai 应用实例](https://www.analog.com/en/resources/design-notes/4096v-80ma-precision-reference.html)。


## 配对邻近优先级（layout v15）

无需增加新的注释语法。已声明或自动识别的高置信度 pair 会同时影响邻近评分；不再将“跨功能区域”作为豁免距离惩罚的理由。推挽对仍允许给输出电阻等留空间，邻近偏好不等同于强制全部同排。

`classic` 功能区域是视觉分组，不是电气隔离边界。同一 row 下、属于同一真实实例的两个 classic 区域，允许在布局适配层把配对输出管临时放到参考管/驱动管附近，以实现相邻模板。例如 Q12/Q13 可相邻放置，不必让 Q13 留在 OUTPUT 最右侧。原 `.cir`、Circuit IR、X 层级和用户注释不会被改写；实际布局调整记录在 report 的 `pairCompactions` 中。

真实子电路边界、折叠 block、实例包装、上下区域关系与每个 classic 区域最多 12 个有源器件的限制保持。如果尝试紧邻后无法保留全部配对、经典区域和公共供电轨，则明确提示回退原分区，不能声称已经完成紧邻布局。


## 子网朝向与输入标记（layout v16）

无需新语法。`pair` 声明继续决定结构身份，未固定 face 的同排 pair 可按外部端口邻近关系整体左右反射，电气参考/输出角色保持。若希望固定某个合法朝向，可保留已有 `face QNAME left/right`；与配对的固定引脚方向冲突仍报错。

`IN_*` 接口标记的左右朝向会自动适应唯一连接的 B/G 控制端，并尽量使用短水平线。这个规则只改图形，不改变 formal port 的输入角色或反馈网络。供电端口方向仍由电位和 PWR/RET 角色决定。接轨的 R/L/C/D 等二端器件在子网骨架后按就近端口接入，优先形成连续竖直回流线。

## 限流保护双管与共网提示（layout v17）

```spice
* pair current-limit { QOUTPUT QPROTECT RSENSE }
```

两管同极性，输出管 E 接保护管 B、输出管 B 接保护管 C，采样电阻跨接两管 E。三个成员必须符合实际连接，角色按拓扑判定；支持 NPN/PNP 对偶。不符合条件的声明报错。此结构是限流保护对，不是二极管连接、电流镜或共 C 达林顿对。

同区域内将两管及采样电阻保留在紧凑子网中；原有 `face` 约束继续有效。741 教学示例声明 `pair current-limit { Q14 Q15 R9 }`。与推挽结构重叠时只硬打包一次，推挽保持软偏好。

v18 起，打开实例内部时以独立 formal port 生成局部图。父电路把多个端口接到同一节点时，只在边界元数据和提示中记录，例如 Sallen–Key 的 `IN_N = OUT_SIG`；该外部反馈留在父级图，不画成内部短接。内部原本存在的连接仍保留。

## 独立子页面（layout v18，取代同图展开）

界面只保留子电路块和进入内部页面，不再提供展开、折叠、全部展开或全部折叠。鼠标点击块、键盘 Enter/Space、实例列表、面包屑和 URL 均用于独立页面导航。

子页面以 `.SUBCKT` 形式端口建立局部作用域，再按本地定义连接子级块。父级同网、接地或端口名称不能将子级形式端口短接、重命名或改变其布局。参数仍按实例传递，`.global` 和真实内部连接保留。边界映射列于 `interfaceBindings`，父级共网列于 `interfaceAliases`；这些数据用于审阅和重新绑定验证，不参与内部布线。

供电方向只取局部信息。内部理想 DC 源给出已知电位；仅有形式供电端口时，PWR 为上轨、RET_GND 为零参考顺序、RET_VEE/VSS 为下轨。局部排序值 +1/0/-1 只代表绘图等级，不是伏特数或电路约束，不能写回网表。