kicad-schematic

KiCad 原理图 Agent

通过编写使用计算所得引脚位置的 Python 脚本，生成通过 ERC 检查的 KiCad 8/9 原理图——绝不猜测坐标。还可修复现有原理图中的 ERC 错误，并处理 KiCad 8→9 迁移。

关键原则

原理图出错的首要原因是猜测引脚位置。 将标签连接到 IC 引脚时，必须根据符号定义中的引脚位置和坐标变换公式计算出精确坐标。scripts/kicad_sch_helpers.py 中的辅助库会自动完成此操作。

Y 轴陷阱（最常见的错误）

符号库（.kicad_sym）使用 Y 轴向上（数学坐标系）。原理图（.kicad_sch）使用 Y 轴向下（屏幕坐标系）。这意味着从库坐标变换到原理图坐标时，必须将 Y 坐标取反。忘记这一步会导致标签偏离引脚 10-50 mm，造成大量 pin_not_connected 和 label_dangling 错误。

变换公式——库坐标为 (px, py) 的引脚，符号放置在原理图坐标 (sx, sy)，旋转角度为 R：

• 旋转 0： 原理图位置 = (sx + px, sy - py)
• 旋转 90： 原理图位置 = (sx + py, sy + px)
• 旋转 180：原理图位置 = (sx - px, sy + py)
• 旋转 270：原理图位置 = (sx - py, sy - px)

始终使用辅助库中的 pin_abs()——绝不要手动计算这些坐标。

架构

User describes circuit
        |
Read symbol libraries (.kicad_sym) to get pin positions
        |
Build pin position dictionaries for every multi-pin IC
        |
Write Python script using SchematicBuilder (from helper library)
  - Use connect_pin() for IC pins (computes positions automatically)
  - Use place_2pin_vertical() for passives (knows pin 1/2 positions)
        |
Generate .kicad_sch file
        |
Post-process with fix_subsymbol_names()
        |
Run ERC validation: kicad-cli sch erc --format json
        |
Parse errors -> fix script -> regenerate -> repeat (max 5 iterations)

分步工作流

0. 确认 kicad-cli 可用

运行任何 ERC 验证之前，请确认系统 PATH 中包含 kicad-cli。运行：

which kicad-cli 2>/dev/null || where kicad-cli 2>/dev/null

如果未找到，请检查本地是否安装了 KiCad，并提出创建符号链接：

macOS：

# Check if KiCad is installed as an app
KICAD_CLI="/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
if [ -f "$KICAD_CLI" ]; then
    echo "Found kicad-cli inside KiCad.app. Creating symlink..."
    sudo ln -sf "$KICAD_CLI" /usr/local/bin/kicad-cli
    echo "Done! kicad-cli is now available on PATH."
else
    echo "KiCad not found. Install from https://www.kicad.org/download/macos/"
fi

Linux：

# kicad-cli is typically installed alongside KiCad via package manager
# Check common locations
for p in /usr/bin/kicad-cli /usr/local/bin/kicad-cli /snap/kicad/current/bin/kicad-cli; do
    if [ -f "$p" ]; then
        echo "Found kicad-cli at $p"
        # If not on PATH, symlink it
        if ! command -v kicad-cli &>/dev/null; then
            sudo ln -sf "$p" /usr/local/bin/kicad-cli
        fi
        break
    fi
done
# If still not found:
# Ubuntu/Debian: sudo apt install kicad
# Fedora: sudo dnf install kicad
# Arch: sudo pacman -S kicad
# Or install from https://www.kicad.org/download/linux/

Windows：

# Check standard install path
$kicadCli = "C:\Program Files\KiCad\8.0\bin\kicad-cli.exe"
if (Test-Path $kicadCli) {
    Write-Host "Found kicad-cli. Add to PATH:"
    Write-Host '  [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Program Files\KiCad\8.0\bin", "User")'
} else {
    Write-Host "KiCad not found. Install from https://www.kicad.org/download/windows/"
}

告知用户检查结果，并在创建任何符号链接之前征求确认。如果确实未安装 kicad-cli，请提供对应操作系统的下载链接并停止——ERC 验证需要它。

1. 了解电路

编写任何代码之前，请收集：

• 包含具体料号的元件清单
• 电源架构（电压轨、稳压器）
• 信号连接关系（哪些引脚彼此相连）
• 所需符号库（KiCad 标准库及任何自定义 .kicad_sym 文件）

2. 读取符号库（不可妥协）

对于每个 IC 和多引脚元件，读取其 .kicad_sym 定义，以获取精确的引脚名称、编号、位置和类型。没有这些数据，就无法正确连接引脚。

from kicad_sch_helpers import SymbolLibrary

lib = SymbolLibrary()
lib.load_from_kicad_sym("path/to/library.kicad_sym")

# Now you know exact pin positions
ad9363 = lib.get("AD9363ABCZ")
for pin in ad9363.pins:
    print(f"{pin.name} ({pin.number}): at ({pin.x}, {pin.y}), type={pin.pin_type}")

对于手动/内联方案，根据库构建引脚字典：

# Extract from .kicad_sym file — these are LIBRARY coordinates (Y-up)
AD_PINS = {
    'TX1A_P': (-17.78, 25.40),
    'TX1A_N': (-17.78, 22.86),
    'SPI_CLK': (-17.78, -10.16),
    # ... all pins
}

# SOT-23-5 packages (common for LDOs like AP2112K, ME6211):
SOT5_PINS = {
    'VIN':  (-7.62,  2.54),   # Pin 1 - top left
    'GND':  ( 0.00, -7.62),   # Pin 2 - bottom center
    'EN':   (-7.62, -2.54),   # Pin 3 - bottom left
    'NC':   ( 7.62, -2.54),   # Pin 4 - bottom right  <- NOT VOUT!
    'VOUT': ( 7.62,  2.54),   # Pin 5 - top right     <- THIS is VOUT!
}

警告——SOT-23-5 引脚陷阱： VOUT 位于 (7.62, +2.54)，NC 位于 (7.62, -2.54)。两者仅相距 5.08 mm。混淆它们会导致 LDO 输出悬空。始终根据实际库文件进行确认。

3. 编写生成器脚本

使用 SchematicBuilder 构建所有原理图。关键方法是 connect_pin()，它会自动计算精确的引脚位置：

from kicad_sch_helpers import SchematicBuilder, SymbolLibrary, snap

lib = SymbolLibrary()
lib.load_from_kicad_sym("custom_symbols.kicad_sym")

sch = SchematicBuilder(symbol_lib=lib, project_name="my_project")
sch.set_lib_symbols(lib_symbols_content)  # Raw S-expression for embedded symbols

# Place an IC
sch.place("CubeSat_SDR:AD9363ABCZ", "U1", "AD9363ABCZ",
          x=320, y=200, footprint="CubeSat_SDR:AD9363_BGA144")

# Connect pins by NAME — coordinates computed automatically
sch.connect_pin("U1", "TX1A_P", "TX1A_P", wire_dx=-5.08)
sch.connect_pin("U1", "SPI_CLK", "SPI_CLK", wire_dy=-5.08)
sch.connect_pin("U1", "GND", "GND", wire_dy=5.08)

# For unused pins, add no-connect flags
sch.connect_pin_noconnect("U1", "AUXDAC1")

# For 2-pin passives, use convenience helpers
from kicad_sch_helpers import place_2pin_vertical
place_2pin_vertical(sch, "Device:C", "C1", "100nF",
                    x=snap(230), y=snap(155),
                    top_net="VCC_3V3", bottom_net="GND",
                    footprint="Capacitor_SMD:C_0402_1005Metric")

如果使用内联引脚字典（不使用 SymbolLibrary），请使用 pin_abs()：

from kicad_sch_helpers import pin_abs, snap

GRID = 1.27

def wl(sch, sx, sy, pin_name, pins_dict, net, dx=0, dy=0, rot=0, label_angle=0):
    """Wire + Label: connect an IC pin to a net label."""
    px, py = pin_abs(sx, sy, pins_dict[pin_name][0], pins_dict[pin_name][1], rot)
    ex, ey = snap(px + dx), snap(py + dy)
    if dx != 0 or dy != 0:
        sch.w(px, py, ex, ey)
    sch.label(net, ex, ey, label_angle)

# Usage:
wl(sch, 320, 200, 'TX1A_P', AD_PINS, "TX1A_P", dx=-7.62)

4. 处理 lib_symbols 部分

原理图中必须嵌入所有引用符号的定义。三条关键规则：

1. 父符号使用完整的 lib_id：(symbol "Device:R" ...)
2. 子符号不得包含库前缀：(symbol "R_0_1" ...)，而不是 (symbol "Device:R_0_1" ...)
3. 始终进行后处理，使用 fix_subsymbol_names() 捕获任何错误

将 fix_subsymbol_names() 用作后处理步骤：

from kicad_sch_helpers import fix_subsymbol_names

content = sch.build(title="My Schematic")
content = fix_subsymbol_names(content)

基于正则表达式的修复器可以处理任意嵌套深度和任意库前缀格式的子符号。

5. 网格对齐（可避免 90% 的警告）

原理图中的每个坐标都必须是 1.27 mm 的倍数。使用 snap()：

from kicad_sch_helpers import snap

# snap() rounds to nearest 1.27mm grid point
x = snap(123.45)  # -> 124.46 (nearest multiple of 1.27)

对以下位置应用 snap()：元件位置、导线端点、标签位置、无连接位置和 PWR_FLAG 位置。connect_pin() 和 pin_abs() 函数会自动完成此操作。

6. 添加 PWR_FLAG 符号

对于每个由稳压器（而非电源符号）提供电压的电源网络，都添加一个 PWR_FLAG，以防止出现 “power_pin_not_driven” 错误：

# Define PWR_FLAG in lib_symbols (see references/kicad_sexpression_format.md)
# Then place on each power net:
sch.place_pwr_flag(x=70, y=78, net_name="VCC_3V3A")

经验法则：如果某个网络由输出引脚类型为 passive（而非 power_out）的元件驱动，则该网络需要 PWR_FLAG。这包括大多数 LDO 稳压器。

对于没有专用 GND 电源符号驱动的 GND 网络，也添加 PWR_FLAG。

7. 未连接标记

每个 IC 上所有未使用的引脚都必须添加未连接标记。缺少未连接标记会导致 pin_not_connected 错误。

# Using SchematicBuilder:
sch.connect_pin_noconnect("U1", "AUXDAC1")

# Or manually with pin_abs:
px, py = pin_abs(sx, sy, pin_x, pin_y, rotation)
sch.nc(px, py)

8. 使用 kicad-cli 验证

from kicad_sch_helpers import run_erc

result = run_erc("output/schematic.kicad_sch")
print(f"Errors: {result['errors']}, Warnings: {result['warnings']}")

if result['errors'] > 0:
    for detail in result['details']:
        if detail.get('severity') == 'error':
            print(f"  {detail['type']}: {detail.get('description', '')}")

9. 自动修复循环

对于复杂的原理图，请使用以下验证循环：

from kicad_sch_helpers import validate_and_fix_loop

def my_fixer(erc_result, iteration):
    """Analyze ERC errors and apply fixes. Return True if fixes applied."""
    error_types = erc_result.get('error_types', {})

    if 'pin_not_connected' in error_types:
        # Read the schematic, find unconnected pins, add connections
        # ... fix logic ...
        return True

    if 'label_dangling' in error_types:
        # Move labels to correct pin positions
        # ... fix logic ...
        return True

    return False  # No fixable errors found

final = validate_and_fix_loop("output/schematic.kicad_sch", my_fixer)

修复现有原理图中的 ERC 错误

如果用户已有包含 ERC 错误的 .kicad_sch 文件（而非要生成新原理图），请使用以下工作流。

步骤 1：以 JSON 格式运行 ERC

始终使用 --format json -o file.json --severity-all。切勿将 kicad-cli 输出通过管道传到标准输出——它会将 JSON 写入 -o 指定的文件。

在 macOS 上，kicad-cli 需要环境变量才能找到标准库：

KICAD9_SYMBOL_DIR="/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols" \
KICAD9_FOOTPRINT_DIR="/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints" \
/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli sch erc \
  --format json --severity-all -o /tmp/erc_result.json schematic.kicad_sch

或者使用辅助工具：

from kicad_sch_helpers import run_erc
result = run_erc("schematic.kicad_sch", env_vars={
    "KICAD9_SYMBOL_DIR": "/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols",
    "KICAD9_FOOTPRINT_DIR": "/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints",
})

步骤 2：解析并分类违规项

import json
with open("/tmp/erc_result.json") as f:
    report = json.load(f)

violations = []
for sheet in report.get("sheets", []):
    violations.extend(sheet.get("violations", []))

# Categorize by severity and type
errors = [v for v in violations if v.get("severity") == "error"]
warnings = [v for v in violations if v.get("severity") == "warning"]
by_type = {}
for v in violations:
    t = v.get("type", "unknown")
    by_type.setdefault(t, []).append(v)

print(f"Errors: {len(errors)}, Warnings: {len(warnings)}")
for t, items in sorted(by_type.items()):
    print(f"  {t}: {len(items)}")

注意： JSON 格式会将违规项嵌套在 sheets[].violations[] 中，而不是放在顶层。

步骤 3：编写针对性的 Python 修复脚本

切勿手动编辑 .kicad_sch 文件——始终编写 Python 脚本。S 表达式格式对空白字符和括号配对十分敏感。

关键实用函数（均位于 scripts/kicad_sch_helpers.py 中）：

from kicad_sch_helpers import (
    find_block,                    # Find balanced parenthesized block
    remove_block_with_whitespace,  # Clean removal preserving formatting
    extract_embedded_symbol,       # Extract from lib_symbols section
    convert_embedded_to_library,   # Embedded → standalone library format
    find_by_uuid,                  # Locate element by UUID
    remove_by_uuid,                # Remove element by UUID
    replace_lib_id,                # Bulk lib_id replacement
    replace_footprint,             # Bulk footprint replacement
    fix_annotation_suffixes,       # Add numeric suffixes to bare refs
    create_pwr_flag_block,         # Generate PWR_FLAG s-expression
)

步骤 4：常见修复模式

按 UUID 移除符号：

content = remove_by_uuid(content, "uuid-string", "symbol")

替换所有实例中的 lib_id：

content = replace_lib_id(content, "Connector:Conn_01x04", "CubeSat_SDR:Conn_01x04")

添加 PWR_FLAG 以修复 power_pin_not_driven：

pwr_block = create_pwr_flag_block(
    x=34.29, y=77.47, ref_num=7,
    project_name="my_project",
    root_uuid="5fb33c66-7637-43ae-9eef-34b4f23f6cfb"
)
# Insert before the final closing paren
last_close = content.rstrip().rfind(')')
content = content[:last_close] + '\n' + pwr_block + '\n' + content[last_close:]

在 .kicad_pro 中抑制警告：

import json
with open("project.kicad_pro") as f:
    pro = json.load(f)
pro["erc"]["rule_severities"]["lib_symbol_mismatch"] = "ignore"
with open("project.kicad_pro", "w") as f:
    json.dump(pro, f, indent=2)
    f.write('\n')

步骤 5：迭代修复与验证

每批修复后都要运行 ERC。有些修复会暴露新的问题：

1. 运行 ERC → 解析结果 → 分类
2. 优先修复优先级最高的错误（参见参考资料中的错误优先级）
3. 再次运行 ERC → 确认错误数量减少
4. 重复以上步骤，直到错误数为 0（如有合理理由，可抑制警告）

**运行修复脚本前，请先备份原理图。**使用 shutil.copy2()。

---

KiCad 8→9 迁移

使用 KiCad 9 验证 KiCad 8 原理图时，预计会遇到以下类别的问题：

符号重命名（lib_symbol_issues）

KiCad 8 名称	KiCad 9 名称	备注
Connector:Conn_01x04	Connector:Conn_01x04_Pin	所有单排连接器均已重命名
Connector:Conn_01x06	Connector:Conn_01x06_Pin	同样的模式
Connector:Conn_02x20	Connector:Conn_02x20_Pin	所有双排连接器也已重命名
Connector:SMA	已移除	使用自定义库或 Connector:Coaxial
Connector:TestPoint	Connector:TestPoint（已移动）	引脚布局可能不同
Regulator_Linear:AMS1117	有 4 个引脚（新增 ADJ）	3 引脚原理图将无法匹配

**修复策略：**创建一个包含 KiCad 8 符号版本的项目级自定义库。将 lib_id 更改为指向自定义库。不要尝试更新为 KiCad 9 版本——引脚位置不同，会破坏导线连接。

引脚位置变化（lib_symbol_mismatch）

重要：不要将嵌入的 Device:C/R/L 符号替换为 KiCad 9 版本。

KiCad 9 更改了无源元件的引脚位置：

• KiCad 8：Device:C 引脚位于 (0, ±2.54)
• KiCad 9：Device:C 引脚位于 (0, ±3.81)

替换嵌入的符号会破坏连接到每个电容、电阻和电感的所有导线。应在 .kicad_pro 中抑制 lib_symbol_mismatch——嵌入的 KiCad 8 符号仍可正常使用。

封装重命名（footprint_link_issues）

KiCad 8 封装	KiCad 9 封装
SW_Push_1P1T_NO_6x3.5mm	SW_Push_1P1T_NO_CK_PTS125Sx43SMTR
SMA_Amphenol_901-143_Vertical	SMA_Amphenol_901-144_Vertical

可使用 replace_footprint() 批量更新。

注释要求

KiCad 9 要求所有位号都以数字结尾。 像 C_RX1B_N 或 J_PWR 这样的位号会在 GUI 中导致“未注释项目”错误（但在 CLI ERC 中不会）。

from kicad_sch_helpers import fix_annotation_suffixes
content = fix_annotation_suffixes(content)  # Adds "1" suffix to bare refs

迁移工作流

1. 运行 ERC → 对违规项分类
2. 创建自定义库，使用 KiCad 8 版本的符号（从嵌入的 lib_symbols 中提取）
3. 将 lib_ids 从标准库更新为自定义库
4. 更新已重命名的封装
5. 修复位号后缀
6. 为任何新增的 power_pin_not_driven 错误添加 PWR_FLAG
7. 在 .kicad_pro 中抑制 lib_symbol_mismatch（安全——嵌入的符号仍可正常工作）
8. 如果存在有意的双重命名，则抑制 multiple_net_names
9. 再次运行 ERC → 确认错误数为 0

---

自定义库管理

当不同版本的标准 KiCad 库发生变化时，创建项目级库以保持兼容性。

创建项目库表

sym-lib-table（位于项目根目录）：

(sym_lib_table
  (version 7)
  (lib (name "CubeSat_SDR")(type "KiCad")(uri "${KIPRJMOD}/libraries/cubesat_sdr.kicad_sym")(options "")(descr "Project custom symbols"))
)

fp-lib-table（位于项目根目录）：

(fp_lib_table
  (version 7)
  (lib (name "CubeSat_SDR")(type "KiCad")(uri "${KIPRJMOD}/libraries/cubesat_sdr.pretty")(options "")(descr "Project custom footprints"))
)

使用 ${KIPRJMOD} 指定可移植路径——它会解析为项目目录。

将嵌入的符号提取到库中

从标准库符号迁移到自定义符号时：

from kicad_sch_helpers import extract_embedded_symbol, convert_embedded_to_library

# Read schematic
with open("schematic.kicad_sch") as f:
    sch = f.read()

# Extract a symbol from the embedded lib_symbols section
block = extract_embedded_symbol(sch, "Connector:Conn_01x04")

# Convert from embedded format (prefix:Name) to library format (Name)
lib_block = convert_embedded_to_library(block, "Connector", "Conn_01x04")

# Append to custom library file (before the final closing paren)
with open("libraries/custom.kicad_sym") as f:
    lib = f.read()
close_pos = lib.rstrip().rfind(')')
lib = lib[:close_pos] + '\t' + lib_block + '\n' + lib[close_pos:]
with open("libraries/custom.kicad_sym", "w") as f:
    f.write(lib)

嵌入格式与库格式

在 .kicad_sch 中，嵌入的 lib_symbols 顶层格式为 (symbol "Library:Name" ...)，子符号使用 (symbol "Name_0_1" ...)。

在 .kicad_sym 库文件中，顶层格式为 (symbol "Name" ...)，子符号使用 (symbol "Name_0_1" ...)。

唯一的区别是顶层名称不再包含库前缀。

---

常见模式

去耦电容阵列

for i, (ref, val) in enumerate(zip(refs, values)):
    place_2pin_vertical(sch, "Device:C", ref, val,
                        x=snap(start_x + i * 8), y=snap(cap_y),
                        top_net=power_net, bottom_net="GND",
                        footprint=f"Capacitor_SMD:{fp}")

2 引脚无源元件（R、C、L）

标准 KiCad 2 引脚无源元件符号具有以下特征：

• 引脚 1 位于库坐标 (0, 2.54)——垂直放置时在上方
• 引脚 2 位于库坐标 (0, -2.54)——垂直放置时在下方

原理图中旋转角度为 0、位置为 (sx, sy) 时：

• 引脚 1 的原理图位置：(sx, sy - 2.54)
• 引脚 2 的原理图位置：(sx, sy + 2.54)

place_2pin_vertical(sch, "Device:C", "C1", "100nF",
                    x=snap(100), y=snap(150),
                    top_net="VCC_3V3", bottom_net="GND",
                    footprint="Capacitor_SMD:C_0402_1005Metric")

多引脚 IC 连接

# Always use connect_pin — never compute positions manually
signal_map = {
    "TX1A_P": "TX1A_P",
    "TX1A_N": "TX1A_N",
    "SPI_CLK": "SPI_CLK",
    # ... all signal pins
}
for pin_name, net_name in signal_map.items():
    sch.connect_pin("U1", pin_name, net_name, wire_dx=-7.62)

# Power pins
for pin_name in ["VDDD1P3", "VDDA1P3", "VDDD1P8"]:
    sch.connect_pin("U1", pin_name, f"VCC_{pin_name}", wire_dy=5.08)

# Unused pins — EVERY unused pin needs this
for pin_name in ["AUXDAC1", "AUXDAC2", "AUXADC", "TEMP_SENS"]:
    sch.connect_pin_noconnect("U1", pin_name)

带 PWR_FLAG 的电源稳压器

sch.place("CubeSat_SDR:AP2112K", "U4", "AP2112K-3.3",
          x=snap(100), y=snap(180),
          footprint="Package_TO_SOT_SMD:SOT-23-5")
wl(sch, 100, 180, 'VIN',  SOT5_PINS, "VCC_5V",  dx=-7.62)
wl(sch, 100, 180, 'EN',   SOT5_PINS, "VCC_5V",  dx=-7.62)
wl(sch, 100, 180, 'GND',  SOT5_PINS, "GND",     dy=5.08)
wl(sch, 100, 180, 'VOUT', SOT5_PINS, "VCC_3V3", dx=7.62)
# NC pin — no-connect flag, NOT a label
nc_x, nc_y = pin_abs(100, 180, *SOT5_PINS['NC'])
sch.nc(nc_x, nc_y)
# PWR_FLAG on output net
sch.place_pwr_flag(x=snap(115), y=snap(178), net_name="VCC_3V3")

经验总结（实战验证）

这些经验来自对真实的 119 个组件 CubeSat SDR 原理图进行调试：

1. 绝不要猜测引脚位置。 即使偏差 1.27mm（一个网格单位）也会导致 ERC 错误。务必读取 .kicad_sym 文件并使用计算后的位置。

2. Y 轴翻转是最常见的错误来源。 符号库的 Y 轴向上，而原理图的 Y 轴向下，因此必须对 Y 值取反。符号库中位于 (0, 25.4) 的引脚，在原理图中的位置是 (sx, sy - 25.4)——而不是 (sx, sy + 25.4)。弄错会导致标签与引脚相距 50mm。

3. SOT-23-5 的 VOUT 与 NC 容易混淆，且会导致 LDO 电路无声地失效。 VOUT=(7.62, 2.54)，NC=(7.62, -2.54)。两者的区别仅在 Y 值的符号。Y 轴翻转后，VOUT 在原理图中位于 NC 上方。务必对照符号库进行确认。

4. 子符号命名错误会导致 KiCad 静默出错。 如果写成 (symbol "Device:R_0_1" ...) 而不是 (symbol "R_0_1" ...)，KiCad 可能可以打开文件，但所有符号都会显示为损坏。务必运行 fix_subsymbol_names()。

5. PWR_FLAG 的必要性比你想象的更高。 任何由稳压器驱动、且输出引脚类型为 passive 的网络都需要 PWR_FLAG。GND 上也要添加一个。缺少 PWR_FLAG 会导致该网络上的每个组件都出现 power_pin_not_driven 错误。

6. 吸附到网格可以避免数百条警告。 单个组件偏离网格，就会导致所有连接的导线和标签都出现偏离网格警告。从一开始就让所有对象吸附到网格。

7. 逐一检查所有引脚。 按引脚列表逐项检查。每个引脚必须满足以下其中一项：通过导线和标签连接、连接到电源符号，或标记为 no_connect。即使漏掉一个引脚也会产生错误。

8. 检查括号是否配对。 KiCad S 表达式中的括号必须完全配对。在生成流程的末尾添加检查：

   depth = sum(1 if c == '(' else -1 if c == ')' else 0 for c in content)
   assert depth == 0, f"Parenthesis imbalance: depth={depth}"
   

9. 不要用 KiCad 9 版本替换内嵌的 Device:C/R/L。 KiCad 9 将无源引脚位置从 ±2.54 改为 ±3.81。替换内嵌符号会破坏所有导线连接。改为忽略 lib_symbol_mismatch。

10. kicad-cli 的 JSON 输出到文件，而非 stdout。 务必使用 -o /tmp/result.json。通过管道传给 python 会得到空的 stdin。JSON 嵌套在 sheets[].violations[] 中，而不是顶层。

11. CLI ERC 不会检查注释。 对于引用末尾不是数字的对象（例如 C_RX1B_N），GUI 会提示“Item not annotated”，但 CLI ERC 会静默通过。迁移时务必运行 fix_annotation_suffixes()。

12. macOS 上的 kicad-cli 需要环境变量。 如果未设置 KICAD9_SYMBOL_DIR 和 KICAD9_FOOTPRINT_DIR，kicad-cli 就无法找到全局库，并会产生误报的 lib_symbol_issues 警告。

13. 不要在 macOS 上使用 grep -P。 系统不支持 PCRE 模式。处理原理图文件的所有模式匹配都应使用 Python 正则表达式。

14. 为自定义符号创建项目级库表。 使用 ${KIPRJMOD} 设置可移植路径。提取内嵌符号来填充库，不要从头重写。

15. 运行修复脚本前先备份。 括号配对错误会导致原理图无法加载。进行任何修改前，先使用 shutil.copy2()。

16. 不要忽略 ERC 错误，只忽略警告。 在 KiCad 8→9 迁移中，忽略 lib_symbol_mismatch（警告）是安全的。绝不要忽略 pin_not_connected 或 power_pin_not_driven 等实际错误。

参考文件

• scripts/kicad_sch_helpers.py — Python 辅助库（务必使用）
• references/kicad_sexpression_format.md — KiCad S 表达式格式规范、坐标系、常见 ERC 错误及修复方法

生成任何原理图前，请先阅读 references/kicad_sexpression_format.md，了解坐标系、子符号命名规则和 PWR_FLAG 要求。

交付前检查清单

新建原理图

1. 所有坐标都通过 snap() 对齐到 1.27 mm 网格
2. 每个 IC 引脚都通过 connect_pin() / wl() 连接，或通过 connect_pin_noconnect() / nc() 标记
3. 使用 fix_subsymbol_names() 修正子符号名称
4. 在每个电压稳压器输出网络和 GND 上都放置 PWR_FLAG
5. 运行 ERC 验证（目标为 0 个错误，可接受警告）
6. 验证括号配对（文件末尾深度为 0）
7. 根据 .kicad_sym 库验证引脚位置（不要猜测）
8. 仔细核对所有 LDO 的 SOT-23-5 封装中 VOUT 与 NC 的位置

修复现有原理图 / 迁移到 KiCad 9

9. 所有参考标号均以数字结尾（fix_annotation_suffixes()）
10. 通过项目级自定义库处理已重命名或缺失的符号
11. 不替换嵌入的 Device:C/R/L 符号（改为抑制 lib_symbol_mismatch）
12. 更新已重命名的封装（replace_footprint()）
13. 在所有电源输入网络（包括外部电源，如桶形插孔、USB VBUS）上添加 PWR_FLAG
14. 运行任何修复脚本前先备份原理图
15. 在 macOS 上为 kicad-cli 设置环境变量（KICAD9_SYMBOL_DIR、KICAD9_FOOTPRINT_DIR）
16. 使用 --severity-all 运行 ERC，以检查所有警告类型