【嵌入式软件AI编程】（1）面向 AI 协同开发的硬件设计资源分析
【嵌入式软件AI编程】（2）使用 altium-monkey-mcp 提取硬件设计信息
【嵌入式软件AI编程】（3）面向 AI 协同开发的 STM32 硬件信息标准化
【嵌入式软件AI编程】（4）提取 STM32 硬件信息工作流的建立与使用

1. 引言

在 STM32 嵌入式软件开发中，MCU 引脚分配、外设信号映射及板载器件连接关系等硬件信息，通常分散在原理图、PCB 设计文件和用户手册等资料中。如何从这些硬件设计资料中提取软件开发所需的信息，是实现 AI 协同开发的重要基础。

使用 altium-monkey-mcp 提取 STM32 硬件设计信息，可以在不安装 Altium Designer 的情况下，直接读取 Altium 原生设计文件，查询元器件、引脚和网络连接信息，并导出结构化 JSON 网表。本文使用 Windows/Codex 环境进行安装和验证，介绍工具的安装配置、主要功能及实际验证过程，为后续构建标准化硬件信息资源、支持 AI 辅助 STM32 软件开发提供实践参考。

2. altium-monkey-mcp 项目介绍

## 2.1 Altium 设计文件简介

Altium Designer 是常用的电子电路设计软件，其工程文件包含原理图、PCB 设计及工程组织等信息。本文使用的 NUCLEO-G431RB 开发板资料中，BoardDesignPack/Altium_Designer/ 目录包含 mb1367.PrjPcb、MB1367.PcbDoc 以及多个 *.SchDoc 文件。

其中：

• *.PrjPcb 用于组织 Altium 工程及其设计文档；
• *.SchDoc 保存原理图页面中的元器件、引脚、网络标识和电气连接等信息；
• *.PcbDoc 保存 PCB 的器件布局、焊盘、板层及布线等设计信息。
  此外，工程中的 *.OutJob 用于配置设计输出任务。

这些文件保存了丰富的硬件设计信息，但不同文件的内部格式和用途存在差异，不能简单地作为普通文本文件统一读取。对于嵌入式软件开发而言，重点是从这些原始资料中提取 MCU 引脚、网络连接、板载器件和扩展接口等信息。

2.2 altium-monkey-mcp 项目简介

altium-monkey-mcp 是一个开源的 MCP 服务项目，旨在使 AI 助手能够读取和分析 Altium Designer 工程。
altium-monkey-mcp 是对 altium-monkey 的轻量封装，后者直接解析二进制 .SchDoc / .PcbDoc / .PrjPcb 格式的 Altium 原生设计文件，为 AI 提供工程查询、元器件检索、网络连接分析、BOM 获取及设计图形渲染等能力。

该项目不需要安装 Altium Designer，即可对支持的原生设计文件进行读取和分析。服务采用只读方式，不修改原始设计文件，适合用于硬件设计资料提取和辅助分析。

项目支持 Windows、Linux 和 macOS，支持 Claude Code、Claude Desktop、VS Code 等AI 助手，运行环境要求 Python 3.12～3.14。

• 核心文件类型：

  • .SchDoc
  • .SchLib
  • .PcbDoc
  • .PcbLib
  • .PrjPcb
  • .OutJob
  • .IntLib 提取
  • .PCBDwf Draftsman 文件（目前为实验性）

• 常见工作流：

  1. 创建和修改原理图文档
  2. 创建原理图符号和 PCB 封装
  3. 插入 SchLib 符号和 PcbLib 封装
  4. 从项目中提取 SchLib 和 PcbLib 数据
  5. 渲染逻辑原理图 SVG、编译后的物理原理图 SVG 和 PCB SVG
  6. 检查 PCB 层、钻孔、板轮廓、网络和网络类
  7. 编写和修改 PCB 过孔，包括 IPC-4761 保护元数据
  8. 提取嵌入字体和 3D 模型
  9. 生成项目容器，并在安装了 Altium Designer 的 Windows 上运行关联的 OutJob
  10. 创建实验性 Draftsman 页面，包含注释、文本、图片和生成的板组装视图高亮图稿

2.3 altium-monkey-mcp 主要功能

工具	描述
list_projects	在目录下查找 .PrjPcb 项目
project_info	图纸层级、变体、项目参数、计数、编译诊断
search_components	对位号、值、封装、描述、参数进行正则搜索
get_component	参数、每个引脚及其网络以及该网络上的其他内容、PCB 布局
search_nets	对网络名称进行正则搜索
get_net	网络上的所有引脚 + PCB 布线统计（每层走线长度/宽度、过孔）
get_bom	物料清单，可选按设计变体、分组
pcb_info	板尺寸、层叠结构、网络类、差分对、设计规则
pcb_placement	拾放坐标（X/Y、旋转、面）
components_near	给定元件半径范围内的元件
render_schematic	将图纸渲染为 SVG + PNG
render_pcb	将选定的 PCB 层渲染为 SVG + PNG（裁剪至板边界）
export_netlist_json	将完整编译网表写入 JSON 文件

project 接受 .PrjPcb（推荐）、.SchDoc、.PcbDoc 或包含项目的目录。
已解析的设计缓存在内存中，当任何设计文件发生变化时重新加载。

工程结构与设计文件识别

工程结构与设计文件识别功能可以帮助我们了解原始硬件资料的组织结构，为后续选择需要提取的设计文档提供依据。

• list_projects 用于搜索指定目录下的 Altium 工程，识别项目文件及其关联的原理图和 PCB 文件；
• project_info 用于获取工程概况，包括原理图层级、工程参数、设计变体以及元器件和网络数量等信息。

元器件与引脚信息查询

• search_components 支持按元器件位号、型号、描述等信息检索器件；
• get_component 可以进一步查询指定元器件的属性、引脚及其所属网络，并获取可用的 PCB 布局信息。

对于 STM32 嵌入式软件开发，这类功能尤其重要。例如，可以查询 MCU 的各个引脚连接了哪些网络，并据此整理 GPIO、UART、SPI、I2C 等外设的板级连接信息。

网络连接关系查询

• search_nets 用于按照网络名称进行检索；
• get_net 用于查询指定网络连接的引脚及相关 PCB 布线统计信息。

网络查询能够进一步揭示元器件之间的电气连接关系。例如，通过查询某个网络，可以确定 MCU 引脚与 LED、按键、连接器或其他板载器件之间的连接情况。

需要注意，网络名称不一定直接包含外设名称。查询结果还需要结合原理图和器件信息进行解释，才能确定其具体功能。

网表 JSON 导出

网表 JSON 导出是后续硬件信息整理关系最密切的功能。

• export_netlist_json 可以将解析后的工程连接信息导出为 JSON 文件。

JSON 网表以结构化形式记录元器件和网络信息，能够通过程序进一步读取、筛选和转换。例如，可以从网络记录中整理元器件引脚与网络之间的对应关系，并将其转换为后续标准化硬件信息所需的 CSV 文件。

PCB 信息查询与原理图渲染

本项目还提供 PCB 相关查询和图形渲染功能。

• pcb_info 可以查询 PCB 尺寸、层叠结构、网络类别及设计规则等信息；
• pcb_placement 用于获取器件的贴装位置、所在层面和旋转角度；
• components_near 可以查询指定器件附近的其他器件。
• render_schematic 和 render_pcb 分别用于将原理图和 PCB 渲染为 SVG 或 PNG 图像。

这些功能既可以补充结构化查询结果，也可以为后续分析器件布局、理解电路功能提供图形参考。PNG 输出还需要满足项目说明中关于 Inkscape 的可选依赖要求。

2.4 MCP 与 Codex 的集成

MCP（Model Context Protocol）是一种用于连接 AI 应用与外部工具的协议。通过 MCP，AI 助手可以发现工具的名称、参数和功能，并在任务执行过程中按需调用相应工具。

在本文的方案中，altium-monkey-mcp 负责解析 Altium 设计文件并提供查询接口，Codex 负责根据开发需求选择工具、组织查询任务并处理返回结果。两者通过 MCP 协议协作，不需要为每次查询单独编写文件解析程序。

本文在 Windows 环境中，将项目安装到独立的 Python 虚拟环境，并将 MCP 服务注册到 Codex。注册后，Codex 能够识别该服务提供的 13 个工具，涵盖工程查询、元器件检索、网络分析、JSON 网表导出、PCB 信息查询及图形渲染等功能。

至此，便建立了从 Altium 原生设计文件到 AI 可调用的硬件信息提取工具的基本通路。下一章将介绍 altium-monkey-mcp 的具体安装与配置过程。

3. altium-monkey-mcp 的安装与配置

3.1 获取项目源码

首先从 GitHub 获取 altium-monkey-mcp 项目的源代码。项目仓库地址为：https://github.com/wjakiela/altium-monkey-mcp。

本文使用 Git 将项目克隆到 Windows 本地目录 C:\tools\altium-monkey-mcp，以便后续安装依赖、配置运行环境和注册 MCP 服务。

打开 PowerShell，执行以下命令：

# 创建工具存放目录
New-Item -ItemType Directory -Force C:\tools

# 切换到工具存放目录
Set-Location C:\tools

# 克隆项目源码
git clone https://github.com/wjakiela/altium-monkey-mcp.git

# 进入项目目录
Set-Location C:\tools\altium-monkey-mcp

执行完成后，可以使用以下命令查看项目文件：

Set-Location C:\tools\altium-monkey-mcp

Get-ChildItem -Force

项目根目录包含 README.md、pyproject.toml 等文件。其中，README.md 介绍项目的安装和使用方法，pyproject.toml 则声明了项目名称、Python 版本要求、依赖包及启动入口等配置信息，是后续准备运行环境和安装项目的重要依据。

至此，项目源码已准备就绪。下一步将安装 Python 运行环境及项目依赖，为启动 MCP 服务做好准备。

3.2 项目安装与环境配置

altium-monkey-mcp 基于 Python 开发，需要准备 Python 运行环境并安装项目依赖。为避免影响系统 Python 和其他开发项目，本文使用 uv 管理 Python 版本、创建独立虚拟环境并安装项目。

项目的 pyproject.toml 声明要求 Python 版本为 >=3.12,<3.15，并依赖 altium-monkey 和 mcp 两个主要软件包。本文使用 Python 3.12.16 进行安装。

安装 uv

uv 是 Python 项目的环境与依赖管理工具，可以下载和管理 Python 版本、创建虚拟环境并安装项目依赖。

在 Windows PowerShell 中执行以下命令：

Set-Location C:\tools\altium-monkey-mcp

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，关闭当前 PowerShell 窗口并重新打开，然后检查安装结果：

Set-Location C:\tools\altium-monkey-mcp

uv --version

如果能够显示 uv 的版本号，说明安装成功。本文使用的版本为 0.13.6。

安装 Python 3.12

uv 可以自行下载并管理 Python 运行环境，无须预先安装独立的 Python 发行版。执行以下命令：

Set-Location C:\tools\altium-monkey-mcp

uv python install 3.12

安装完成后，可以查看 uv 管理的 Python 版本：

Set-Location C:\tools\altium-monkey-mcp

uv python list --only-installed

本文安装的版本为 Python 3.12.16。

创建 Python 虚拟环境

进入项目目录，执行：

Set-Location C:\tools\altium-monkey-mcp

uv venv --python 3.12

默认情况下，uv 会在项目目录下创建 .venv 虚拟环境，用于隔离本项目的 Python 解释器和依赖包。

可以使用以下命令检查虚拟环境是否创建成功：

Set-Location C:\tools\altium-monkey-mcp

Test-Path .\.venv\Scripts\python.exe

如果返回 True，说明虚拟环境中的 Python 解释器已经存在。

安装项目及其依赖

在项目根目录执行：

Set-Location C:\tools\altium-monkey-mcp

uv pip install -e .

uv 会根据 pyproject.toml 安装项目及其声明的依赖，并在虚拟环境中注册相应的命令入口。

本文安装的主要依赖包括：

• altium-monkey：用于解析 Altium 原生设计文件的底层库。
• mcp：用于实现 MCP 服务接口。

安装完成后，可以检查项目的安装信息：

Set-Location C:\tools\altium-monkey-mcp

uv pip show altium-monkey-mcp

还可以检查 MCP 服务的启动程序是否生成：

Set-Location C:\tools\altium-monkey-mcp

Test-Path .\.venv\Scripts\altium-monkey-mcp.exe

如果返回 True，说明项目的命令行启动入口已经生成。

至此，altium-monkey-mcp 的运行环境和项目依赖安装完成。整个过程使用独立虚拟环境管理依赖，不需要安装 Altium Designer。下一步将把该服务注册到 Codex，使 AI 能够通过 MCP 调用其硬件信息提取工具。

3.3 将 MCP 服务注册到 Codex

完成项目安装后，需要将 altium-monkey-mcp 注册到 Codex，使 AI 能够通过 MCP 协议调用其提供的硬件信息提取工具。本文使用 Codex CLI 完成服务注册。

（1）检查 Codex CLI

打开 PowerShell，执行以下命令：

Set-Location C:\tools\altium-monkey-mcp

codex --version
codex mcp --help

本文使用的 Codex CLI 版本为 0.157.0。第二条命令用于查看 MCP 服务管理功能及其支持的操作。

（2）注册 MCP 服务

altium-monkey-mcp 安装在项目的 Python 虚拟环境中，其启动程序位于：

C:\tools\altium-monkey-mcp\.venv\Scripts\altium-monkey-mcp.exe

使用以下命令将其注册到 Codex：

Set-Location C:\tools\altium-monkey-mcp

codex mcp add altium-monkey -- "C:\tools\altium-monkey-mcp\.venv\Scripts\altium-monkey-mcp.exe"

其中，altium-monkey 是注册到 Codex 的服务名称，后面的完整路径指定了 MCP 服务的启动程序。使用虚拟环境中的可执行文件，可以避免依赖系统中其他 Python 环境的配置。

注册成功后，终端会显示类似以下信息：

Added global MCP server 'altium-monkey'.

这表示服务配置已成功添加到 Codex 的全局 MCP 配置中。

（3）检查注册结果

执行以下命令查看已注册的 MCP 服务：

Set-Location C:\tools\altium-monkey-mcp

codex mcp list

如果输出列表中出现 altium-monkey，且状态为 enabled，说明该服务已启用。

至此，altium-monkey-mcp 已注册到 Codex。下一节将进一步检查 Codex 是否能够识别该服务及其提供的工具。

3.4 验证 MCP 服务与工具列表

完成注册后，重新启动 Codex 会话，使其加载最新的 MCP 配置。在新会话中输入以下提示词：

请检查当前可用的 MCP 服务，确认是否能够识别 altium-monkey，并列出该服务提供的全部工具名称及其功能。暂时不要读取或修改任何工程文件。

如果 Codex 能够识别该服务并列出工具名称和功能，说明 MCP 服务已成功接入，工具发现正常。

本文实际验证中，Codex 成功识别了 altium-monkey 服务及其提供的 13 个工具，涵盖工程查询、元器件与网络检索、JSON 网表导出、PCB 信息查询及图形渲染等功能。

至此，MCP 服务的安装、注册与工具发现验证完成。下一章将通过实际的 STM32G4 Nucleo-64 硬件设计工程，进一步验证这些工具的使用效果。

4. altium-monkey-mcp 的使用

完成安装与配置后，可以通过 Codex 调用 altium-monkey-mcp 提供的工具，读取 Altium 原生设计文件并提取硬件信息。
本文以 STM32G4 Nucleo-64 系列开发板的 MB1367 参考设计为测试对象，使用其 Altium Designer 工程文件验证 altium-monkey-mcp 的硬件信息提取能力。原始资料位于 D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer 目录，包含 Altium 工程文件、原理图文件和 PCB 设计文件。

4.1 测试对象与原始资料

首先，调用 list_projects 工具扫描该目录，识别工程文件及其关联的设计文档。

在 Codex 中输入以下提示词：

请调用 mcp__altium_monkey__list_projects，扫描目录：
"D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer"
列出找到的 .PrjPcb、.SchDoc 和 .PcbDoc 文件。
只返回结果，不做分析。

工具返回结果如下：

扫描结果：

.PrjPcb：
- mb1367.PrjPcb

.SchDoc：
- Arduino_extension_connectors.SchDoc
- Mechanical.SchDoc
- Power.SchDoc
- Project_overview.SchDoc
- STM32_microcontroller_IOs.SchDoc
- STM32_microcontroller_power.SchDoc
- ST_LINK_V3E.SchDoc
- Top.SchDoc

.PcbDoc：
- MB1367.PcbDoc

扫描结果识别出 1 个 Altium 工程文件、8 个原理图文件和 1 个 PCB 设计文件，与原始资料目录中的文件组织情况相符。

其中，mb1367.PrjPcb 用于组织整个设计工程；8 个 *.SchDoc 文件分别描述工程概况、MCU 引脚与接口、供电电路、ST-LINK 调试器及其他电路；MB1367.PcbDoc 则记录 PCB 设计信息。

该步骤验证了 altium-monkey-mcp 能够识别指定目录下的 Altium 工程及相关设计文件，为后续查询工程概况、提取 MCU 引脚连接关系和导出 JSON 网表提供了基础。

4.2 工程识别与项目概况查询

识别工程文件后，可以进一步调用 project_info 工具读取工程概况，获取原理图层级、元器件数量、网络数量、工程参数及设计变体等信息。

在 Codex 中输入以下提示词：

请调用 mcp__altium_monkey__project_info，
读取项目文件：
"D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer\mb1367.PrjPcb"
返回项目概况，包括图纸层级、参数、元件数量、网络数量等。

工具返回的主要结果如下：

（1）工程概况

项目	返回结果
原理图数量	8 张
PCB 文件数量	1 个
元器件数量	202 个
网络数量	143 个
项目变体	G474RE、G431RB、G491RE、WS
编译诊断	空

（2）原理图层级与元器件分布

图纸	元器件数量
Project_overview.SchDoc	0
Top.SchDoc	0
STM32_microcontroller_IOs.SchDoc	45
STM32_microcontroller_power.SchDoc	19
Arduino_extension_connectors.SchDoc	23
Power.SchDoc	24
ST_LINK_V3E.SchDoc	81
Mechanical.SchDoc	10
合计	202

（3）工程参数

参数	返回值
Board_Name	NUCLEO64 STM32G4
Board_Reference	MB1367
Board_PCB_Revision	C
Board_Assembly_Revision	05
Board_Document_Date	07-FEB-22
WS	with_socket

这些结果表明，project_info 不仅能够读取工程的基本结构，还可以提取板卡标识、版本信息及设计变体等参数，为后续硬件信息整理提供依据。

需要注意，项目变体中的 G474RE、G431RB 和 G491RE 对应不同的目标 MCU 型号，而 WS 表示 with_socket 配置。该工程以 STM32G474RET6 为原理图基准器件，因此不能仅根据原理图中的 MCU 型号判断工程是否适用于 NUCLEO-G431RB。

通过该步骤，可以在查询具体元器件和网络之前，先掌握整个工程的组织结构、规模及关键参数，为后续提取 MCU 引脚连接信息和导出 JSON 网表做好准备。

4.3 MCU 元器件与引脚连接查询

在了解工程整体结构后，可以进一步查询 MCU 元器件的详细信息，包括器件型号、封装、引脚列表、网络名称及各网络连接的其他器件。这些信息是后续提取 MCU 引脚映射和板载器件连接关系的重要基础。

（1）搜索 MCU 相关元器件

首先，调用 search_components 搜索工程中的 STM32 器件。在 Codex 中输入以下提示词：

请调用 mcp__altium_monkey__search_components，
在项目
"D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer\mb1367.PrjPcb"
中搜索 STM32 相关元件，
列出匹配到的元件位号、名称、描述。

返回结果如下：

位号	名称	描述
U13	STM32G474	STM32G474，LQFP64 封装
U5	STM32F723IEK	STM32F723IEK（STM32F7），BGA176

搜索结果共匹配到 2 个元器件。其中，U13 是原理图中的 STM32G4 MCU 器件，U5 则是另一个 STM32 器件。搜索结果没有提供独立的名称字段，表中的名称根据器件描述整理。

（2）查询 MCU 的详细信息

确定 MCU 元器件位号后，调用 get_component 查询 U13 的详细信息，包括器件参数、全部引脚、各引脚所属网络，以及同一网络上的其他连接端。

提示词如下：

请调用 mcp__altium_monkey__get_component，
读取项目
"D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer\mb1367.PrjPcb"
中 MCU 对应元件的详细信息，
返回其参数、所有引脚、每个引脚所属网络，
以及这些网络上还连接了哪些器件。

返回的主要信息如下。

① 元器件参数

参数	返回值
元件位号	U13
所在原理图	STM32_microcontroller_IOs.SchDoc
Value	STM32G474RET6
Manufacturer	STMICROELECTRONICS
Package	LQFP64
PCB 所在层	顶层
PCB 中心坐标	(32.46, 24.09) mm
旋转角度	0°

这些信息不仅包含 MCU 型号和封装，还包括器件在原理图中的位置及 PCB 布局信息，可用于后续硬件资源整理和器件定位。

② MCU 引脚与网络连接

返回了 U13 的全部 64 个引脚，并为每个引脚提供引脚编号、引脚名称、网络名称及其他连接端。以下列出部分记录作为示例：

引脚编号	引脚名称	网络名称	其他连接端
1	VBAT	VBAT	C53.2、CN7.33、SB38.2
2	PC13	PC13	CN7.23、SB16.2
3	PC14 - OSC32_IN	NetSB31_2	SB31.2、SB32.2
4	PC15 - OSC32_OUT	NetSB29_2	SB29.2、SB30.2
13	PA1	PA1	CN7.30、CN8.2
14	PA2	PA2	SB17.2、SB18.1
15	VSS	GND	见下方 GND 汇总
16	VDD	VDD	见下方 VDD 汇总
17	PA3	PA3	SB22.1、SB23.2
18	PA4	PA4	CN7.32、CN8.3
19	PA5	PA5	CN10.11、CN5.6、SB6.1
61	PB8-BOOT0	PB8	JP7.1、SB2.2、SB4.1
62	PB9	PB9	CN10.5、CN5.9、SB34.2
63	VSS	GND	见下方 GND 汇总
64	VDD	VDD	见下方 VDD 汇总

• VDD 汇总：U13 的 16、32、48、64 脚共同连接 B1.1、B1.2、C42.2、C45.2、C52.2、C54.2、C55.2、CN7.5、JP6.2、JP8.3、L1.1、SB38.1、SB8.1。
• GND 汇总：U13 的 15、31、47、63 脚所在网络还有 144 个其他连接端，涉及 90 个器件。器件位号为：B2；C1–C42、C45、C52–C59；CN1、CN2、CN4–CN7、CN10–CN12；JP1；LD1、LD3；Q1；R5、R8、R11、R15–R17、R21、R26、R28、R31；SB11；U1–U12；X1、X3。】

例如，PA5 引脚连接到名为 PA5 的网络，该网络还连接到 CN10.11、CN5.6 和 SB6.1。这表明工具能够将 MCU 引脚与板上的连接器、焊桥等器件关联起来，为后续分析扩展接口和板载电路提供数据。

对于电源引脚，工具也能够识别 VDD、GND 等网络。由于多个 MCU 电源引脚连接到同一网络，返回结果对部分共用连接进行了汇总，而不是在每一行重复列出全部连接端。

通过本次查询，验证了 altium-monkey-mcp 能够从原生 Altium 工程中获取 MCU 元器件参数、完整引脚列表及其网络连接关系。这些结构化结果可以作为后续生成标准化 MCU 引脚映射表和板载器件连接表的基础数据。

4.4 网络搜索与连接关系验证

在获取 MCU 引脚连接信息后，可以进一步使用 search_nets 搜索指定名称的网络，了解网络命名方式及其检索效果。与上一节从 MCU 引脚出发查询连接关系不同，本节从网络名称出发进行检索，为后续按网络整理硬件连接信息提供参考。

在 Codex 中输入以下提示词：

请调用 mcp__altium_monkey__search_nets，
在项目
"D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer\mb1367.PrjPcb"
中搜索包含 LED、USART、I2C、SPI 的网络名称。

工具返回结果如下：

匹配的网络名称	引脚数
LED_STLK	3

工具没有找到名称包含 USART、I2C 或 SPI 的网络。

本次查询表明，search_nets 能够按照指定的网络名称进行检索，并返回匹配网络及其连接端数量。例如，LED_STLK 网络包含 3 个连接端。

但未搜索到包含 USART、I2C 或 SPI 的网络，并不意味着原理图中不存在这些外设相关连接。网络名称可能采用 MCU 引脚名称、板级信号名称或其他命名方式，而不一定直接包含外设名称。

因此，使用网络名称搜索硬件信息时，需要注意以下两点：

• 搜索结果取决于网络命名方式。 如果网络名称不包含指定关键词，即使它与目标外设有关，也可能无法通过该关键词检索到。
• 网络名称不能直接等同于外设功能。 判断某个网络是否用于 USART、I²C 或 SPI，还需要结合 MCU 引脚复用功能、原理图连接关系及其他硬件资料进行分析。

本次测试验证了网络名称检索功能的基本可用性，同时也说明，仅依靠关键词搜索不足以完整识别板载外设。后续整理标准化硬件信息时，应将 MCU 引脚映射、网络连接关系和外设功能定义结合起来，而不能只根据网络名称进行判断。

4.5 导出并检查 JSON 网表

除了通过工具逐项查询元器件和网络信息，altium-monkey-mcp 还提供 export_netlist_json 工具，可以将工程中的网表导出为 JSON 文件。与单次查询返回局部信息不同，完整网表能够为后续批量处理和标准化硬件信息整理提供统一的数据来源。

导出 JSON 网表

在 Codex 中输入以下提示词：

请调用 mcp__altium_monkey__export_netlist_json，
对项目
"D:\STM32Ref\NucleoG431\MB1367C_BoardDesignPack\Altium_Designer\mb1367.PrjPcb"
导出完整网表 JSON，
并说明导出的文件路径。

返回结果如下：

完整网表 JSON 已导出并确认文件存在：

文件路径：
C:\Users\Administrator\Documents\Codex\2026-10-28\this-requires-inspecting-the-local-codex\outputs\mb1367_netlist.json

导出成功后，可以在指定路径找到 mb1367_netlist.json 文件。该文件保存了从 Altium 工程中提取的结构化元器件与网络数据。

检查 JSON 网表的基本结构

打开导出的 JSON 文件，可以看到其顶层结构包含以下主要字段：

{
  "schema": "altium_monkey.netlist.b0",
  "generator": "altium_monkey",
  "components": [],
  "nets": []
}

其中，schema 用于标识数据结构版本，generator 标识生成工具，components 保存元器件信息，nets 保存网络及其连接信息。实际文件中的 components 和 nets 包含完整的设计数据，上述示例仅展示其基本结构。

检查数据内容与一致性

对导出的 mb1367_netlist.json 进行检查，得到以下结果：

检查项目	检查结果
元器件记录数	202
网络记录数	143
元器件位号	均唯一
网络连接引用的元器件位号	均能匹配到已有元器件
MCU U13 的引脚网络记录	64 个引脚均有对应记录

元器件数量和网络数量与前面 project_info 工具返回的工程概况一致，说明导出文件与前面的查询结果在这些统计项上保持一致。网络连接记录也能够引用已有的元器件位号，表明 JSON 数据具有较好的内部一致性。

需要注意，这些检查主要验证 JSON 的结构和数据之间的对应关系，并不能单独证明每一条电气连接都与原始原理图完全一致。实际用于软件开发前，建议抽取部分引脚和网络，与原理图进行核对。

JSON 网表的用途

本次导出的 JSON 网表是整个硬件信息提取流程的重要中间数据。它以结构化方式保存元器件、引脚和网络连接关系，能够供后续脚本读取和处理。

例如，可以根据 components 和 nets 中的记录，整理 MCU 引脚映射表、板载器件连接表等标准化硬件信息。需要注意，JSON 网表主要描述设计中的器件属性和电气连接关系，通常不能独立完整说明 GPIO 有效电平、上下拉要求或外设的具体使用方式，这些内容仍需要结合原理图、用户手册及其他资料补充。

通过本次测试，验证了 altium-monkey-mcp 能够将 Altium 原生工程中的设计信息导出为结构化 JSON 网表，为下一阶段实现“信息提取与整理 → 标准化硬件信息”提供了可用的数据基础。

5. 提取的硬件设计信息

通过前述测试，altium-monkey-mcp 已经从 MB1367 Altium 工程中提取了工程组成、板卡参数、元器件属性、MCU 引脚分配及网络连接关系等信息，并成功导出了 JSON 网表。本章对实际获得的硬件设计信息进行归纳，明确本次实践的具体成果。

5.1 工程组成与板卡基本信息

通过 list_projects 和 project_info，获得了工程文件清单、原理图组织关系、板卡参数及设计统计信息。

信息类别	实际提取的内容
工程文件	mb1367.PrjPcb
原理图文件	8 个 *.SchDoc 文件及其名称
PCB 文件	MB1367.PcbDoc
板卡名称	NUCLEO64 STM32G4
板卡参考编号	MB1367
PCB 版本	C
装配版本	05
设计日期	07-FEB-22
元器件数量	202 个
网络数量	143 个
工程变体	G474RE、G431RB、G491RE、WS
原理图组织关系	图纸层级、各图纸的元器件数量

这些信息可以帮助我们快速了解硬件设计的整体组成，确定设计文件之间的关系，并获取板卡标识、版本和工程规模等基本信息。

5.2 元器件及其属性信息

通过 search_components、get_component 以及 JSON 网表中的 components，获得了工程内元器件的标识、型号、封装和相关属性。

实际提取的信息包括：

• 器件标识： 元器件位号，例如 U13、U5、C49、CN10。
• 器件基本属性： 器件值、型号、描述及器件类型。
• 封装信息： PCB 封装名称，例如 LQFP64。
• 器件库信息： 元器件库引用名称。
• 物料属性： 制造商、制造商料号、内部物料编号等参数。
• 设计来源： 元器件所在的原理图文件。

以 MCU 元器件 U13 为例，实际提取结果如下。

属性	提取结果
元件位号	U13
器件型号	STM32G474RET6
制造商	STMICROELECTRONICS
封装	LQFP64
器件类型	IC
所在原理图	STM32_microcontroller_IOs.SchDoc
制造商料号	STM32G474RET6

这些信息不仅能够识别 MCU，还可以用于整理板载连接器、阻容器件、调试器及其他外围元器件的清单，为后续分析器件连接关系提供基础。

5.3 MCU 引脚分配与电气连接关系

本次实践最重要的成果之一，是获得了 MCU 引脚与网络之间的对应关系，以及这些网络连接的其他器件引脚。

通过 get_component 查询 U13，工具返回了全部 64 个 MCU 引脚的信息，包括引脚编号、引脚名称、所属网络及其他连接端。导出的 JSON 网表也包含了 U13 的 64 个引脚网络记录。

实际获得的信息包括：

• MCU 引脚编号及引脚名称。
• 每个引脚所属的电气网络名称。
• 与同一网络相连的其他元器件及其引脚编号。
• MCU 引脚与板载连接器、焊桥和外围器件之间的连接关系。
• 电源引脚与 VDD、GND 等网络之间的连接关系。

部分实际提取结果如下。

MCU 引脚	网络名称	其他连接端
PC13（引脚 2）	PC13	CN7.23、SB16.2
PA5（引脚 19）	PA5	CN10.11、CN5.6、SB6.1
PA9（引脚 43）	PA9	CN10.21、CN5.1
PA10（引脚 44）	PA10	CN10.33、CN9.3
PB3（引脚 56）	PB3	CN10.31、CN9.4、SB15.1
PB8（引脚 61）	PB8	JP7.1、SB2.2、SB4.1

例如，MCU 的 PA5 引脚连接到 PA5 网络，该网络还连接到 CN10.11、CN5.6 和 SB6.1。由此可以建立从 MCU 引脚到网络、再到其他器件引脚的连接关系。

这些信息能够直接支持后续的软件开发工作。例如，在编写 GPIO 驱动或使用扩展接口时，可以根据实际连接关系查询目标 MCU 引脚与板载器件、连接器之间的对应关系，而不必完全依赖人工阅读原理图。

需要注意，以上信息描述的是原始设计中的引脚和电气连接关系，并不直接说明每个引脚在软件中应该配置成何种外设功能。实际使用时，仍需结合目标 MCU 的引脚复用功能及其他硬件资料进行确认。

5.4 网络信息与其他可提取数据

除了 MCU 引脚映射，本次实践还获得了整个工程的网络记录，以及部分 PCB 布局信息。

（1）网络连接信息

导出的 mb1367_netlist.json 包含 143 个网络，主要记录以下内容：

信息类别	实际获得的内容
网络标识	网络名称及内部标识
网络连接端	元器件位号、引脚编号、引脚名称和引脚类型
网络来源	相关原理图文件及来源页面信息
图形对象	与网络有关的导线、网络标签、端口、电源端口等记录
层级信息	部分网络的图纸层级连接信息及相关端点
别名信息	网络别名记录

JSON 网表共包含 202 个元器件记录、143 个网络记录和 653 条网络端子连接记录。对导出数据进行初步检查后，元器件位号均唯一，网络连接引用的元器件位号均能匹配到已有元器件。

这些数据可以从网络角度描述元器件之间的连接关系，与上一节从 MCU 引脚出发查询连接的方式相互补充。

（2）网络名称检索

通过 search_nets，还验证了按网络名称查询的能力。例如，本次搜索包含 LED、USART、I2C 和 SPI 的网络名称时，工具返回了 LED_STLK，其连接端数量为 3；未找到包含其他三个关键词的网络名称。

这说明工具能够提供网络名称检索结果，但检索效果受到原始网络命名方式的影响。没有搜索到包含某个外设名称的网络，并不意味着工程中不存在该外设相关的连接。

（3）PCB 器件布局信息

在调用 get_component 查询 U13 时，工具还返回了该器件的 PCB 布局信息：

属性	提取结果
所在层	顶层
中心坐标	(32.46, 24.09) mm
旋转角度	0°

这表明，除了原理图中的器件属性与电气连接，MCP 工具还能够在元器件查询结果中提供相应的 PCB 布局信息。本次仅对 U13 的布局信息进行了实际查询，尚未对整个 PCB 的布局、布线和设计规则开展完整验证。

综上，本次实践实际获得了四类主要成果：工程组成与板卡参数、元器件属性、MCU 引脚与电气连接关系，以及网络连接和部分 PCB 布局信息。 这些都是从现有 Altium 设计资料中提取的具体硬件信息，而非仅仅完成了工具安装或文件格式转换。

同时，这些结果仍属于原始信息提取阶段的产物。要使其能够直接服务于 AI 协同开发 STM32 嵌入式软件，还需要进一步结合原理图、用户手册等资料，补充器件功能、外设用途等信息，并整理为标准化硬件信息资源。

6. 总结与展望

本次实践验证了使用 altium-monkey-mcp 提取 STM32 硬件设计信息的技术路线。在不安装 Altium Designer 的情况下，通过 Codex 调用 MCP 工具，成功识别 Altium 工程及其设计文件，查询了工程概况、MCU 元器件参数、引脚与网络连接关系，并导出了 JSON 网表。导出数据中的元器件数量和网络数量与工程概况一致，初步检查结果表明数据具有较好的结构完整性和内部一致性。

下一步，将以导出的 JSON 网表为基础，结合 PDF 原理图、用户手册及 BOM 等资料，建立从原始硬件资料到标准化硬件信息的处理流程，将提取和整理后的数据保存为 board_info.md、pin_mapping.csv、peripheral_connections.csv 等文件，为 AI 协同开发 STM32 嵌入式软件提供结构清晰、可追溯的硬件信息资源。

版权声明：

欢迎关注 youcans@xidian【嵌入式软件AI编程】专栏
转发必须注明原文链接：
【嵌入式软件AI编程】（2）使用 altium-monkey-mcp 提取硬件设计信息
Copyright by ai4mcu@qq.com
Crated：2026-10