altium-schematic-reader

Altium 原理图读取器

使用此技能，根据可靠的电路事实回答有关 Altium 原理图设计的问题，而不是根据文件名或截图猜测。

随附脚本通过 altium-monkey 读取 Altium 文件，并返回精简的 JSON 数据片段，供 AI 推理使用。

前置条件

Python 环境中必须能够导入 altium-monkey。

推荐的安装方式：

pip install altium-monkey

在 altium_monkey 源代码检出目录中操作时，运行脚本前将 PYTHONPATH 设置为其 src/py 目录。

$env:PYTHONPATH="path\to\altium_monkey\src\py"

定位设计

如果用户没有指定项目，请查找候选 Altium 项目：

Get-ChildItem -Recurse -Filter *.PrjPcb

如果有多个可能的项目，请询问用户要检查哪一个。对于单个 .SchDoc，请使用 sheet 命令。

命令模式

可从任意工作目录运行：

python <skill_dir>\scripts\read_schematic.py <command> [args]

所有命令都会将 JSON 输出到 stdout。错误会将 JSON 输出到 stderr。

工作流

对于本次会话中尚未检查的项目，始终先运行 summary。

python <skill_dir>\scripts\read_schematic.py summary path\to\Project.PrjPcb

然后选择有针对性的后续查询：

• 使用 components --brief 了解工作表上的内容。
• 使用 nets 列出命名网络，或搜索电源轨／信号名称。
• 使用 nets --name NET_NAME 检查某个网络上的所有端子。
• 使用 connections --designator U1 检查元件的所有连接引脚。
• 使用 connections --designator U1 --pin 5 检查单个引脚。
• 使用 bom 查询物料清单和变体相关问题。
• 仅在没有 .PrjPcb 时使用 sheet。
• 仅在最后不得已时使用 raw design 或 raw netlist，因为输出可能很大。

对于 MCU、处理器、连接器和排针表格，不要只依赖网表连接。网表会省略未连接的引脚。请检查元件符号引脚（通过 altium-monkey 检查 component.pins，或使用 altium-circuit-investigator 的 port_inventory.py），并将这些引脚与网表端点合并，确保列出所有引脚，包括 NC/未连接 引脚。

命令

项目摘要：

python <skill_dir>\scripts\read_schematic.py summary path\to\Project.PrjPcb

元件：

python <skill_dir>\scripts\read_schematic.py components path\to\Project.PrjPcb --brief
python <skill_dir>\scripts\read_schematic.py components path\to\Project.PrjPcb --sheet Power.SchDoc --brief
python <skill_dir>\scripts\read_schematic.py components path\to\Project.PrjPcb --designator U7

网络：

python <skill_dir>\scripts\read_schematic.py nets path\to\Project.PrjPcb
python <skill_dir>\scripts\read_schematic.py nets path\to\Project.PrjPcb --contains P3V3
python <skill_dir>\scripts\read_schematic.py nets path\to\Project.PrjPcb --name GND

引脚级连通性：

python <skill_dir>\scripts\read_schematic.py connections path\to\Project.PrjPcb --designator U7
python <skill_dir>\scripts\read_schematic.py connections path\to\Project.PrjPcb --designator U7 --pin C9

物料清单：

python <skill_dir>\scripts\read_schematic.py bom path\to\Project.PrjPcb
python <skill_dir>\scripts\read_schematic.py bom path\to\Project.PrjPcb --variant PCBA_Build

单张工作表：

python <skill_dir>\scripts\read_schematic.py sheet path\to\Sheet.SchDoc

原始数据备用命令：

python <skill_dir>\scripts\read_schematic.py raw path\to\Project.PrjPcb design
python <skill_dir>\scripts\read_schematic.py raw path\to\Project.PrjPcb netlist

推理规则

• 在回答中注明位号、引脚编号、网络名称和工作表文件名。
• 优先使用项目级命令，而不是检查单张工作表，因为项目级命令会解析位号和层级结构。
• 有网表查询可用时，不要根据符号图形或元件名称推断连通性。
• 区分“网表中不存在”和“符号上不存在”：需要覆盖所有引脚时，仍必须将符号上未连接的引脚报告为 NC。
• 对于 CTRL、OUT、IN、FB、AD、QD 或 AUX 等含义不明确的信号名称，请检查局部原理图标签，或在命名其功能前使用 altium-circuit-investigator。
• 对于“这段电路有什么作用”之类的问题，先检查 summary，再检查工作表级元件简表，最后检查主要 IC 的连接。
• 对于电源问题，请检查 summary.power_and_ground_nets、类似电源轨的网络名称，以及目标 IC 上的 POWER 引脚。
• 对于审查类问题，先查找证据，再分别说明已确认的问题与假设。

已知限制

• 复杂的层级通道和由 .Annotation 驱动的映射可能需要人工验证。
• 变体支持取决于 altium-monkey，对不常见的变体配置可能有限。
• 解析失败时，应报告出错文件的路径和完整的 JSON 错误。
• altium-monkey 使用 AGPL-3.0-or-later 许可证；将其嵌入分发式或网络服务前，请先审查相关许可义务。

参考资料

围绕此技能设计后端、API、缓存、UI 或 AI 工作流时，请阅读 references/software_design.md。