@huaqiu/dsh-tool-pcb-autoplacement

在 KiCad 中通过 DSH 对话生成 PCB 初始布局候选、检查布局约束并评估布局质量。

本插件与 @huaqiu/dsh-kicad 配合使用：dsh-kicad 提供初始布局 Skill，本插件提供布局检查、评分和工程审查。

安装 · 配置 · 使用 · 常见问题 · 更新记录

当前为 alpha 内测版。DSH 宿主必须满足本包的 peerDependencies；本版尚未适配 DSH 0.2.1-alpha.4。

功能

• 读取当前 PCB 的器件、板框、连接关系及原生 Lock 状态。
• 检查候选布局的重叠、出板、固定条件和适用的工程约束。
• 提供布局质量分项及检查覆盖情况，辅助比较候选方案。
• 结合工程知识审查功能分组、机械位置和布线空间，说明问题依据及未验证项。

本包包含 pcb-layout-engineering 和 pcb-layout-review 两套业务 Skills。初始布局直接使用 dsh-kicad 的 pcb-initial-placement，无需单独安装 Skill 文件。

环境要求

| 项目 | 要求 | | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | KiCad | 当前验证环境为 10.0.7；启用官方 API 服务，并在 PCB 编辑器中打开板文件 | | DSH | 使用与本包 peerDependencies 匹配的宿主版本，并配置可用的模型 | | Node.js | ^22.19.0 \|\| >=24.0.0 | | dsh-kicad | 安装并启用包含 pcb-initial-placement 的版本；已核对 0.6.1 包含此 Skill | | Python | 使用 KiCad 自带的 Python 和匹配的 kipy/pcbnew；插件包附带 protobuf 缺失时的纯 Python 回退。原生文件检查还需同版 kicad-cli |

安装

使用 KiCad 所连接的 DSH 运行环境，在同一个 profile 中安装两个插件。以下以 web profile 为例；实际名称不同时，请替换 web。

dsh plugin --profile web add @huaqiu/[email protected]
dsh plugin --profile web add @huaqiu/dsh-tool-pcb-autoplacement@alpha

若宿主已经安装并启用了 dsh-kicad，确认其包含 pcb-initial-placement 后，无需重复安装。

安装完成后：

1. 在 DSH 插件设置中确认两个插件均已启用。
2. 确认插件使用 KiCad 内置的 Python；宿主已提供解释器路径时无需另行配置。
3. 重载 DSH，在 KiCad 中打开测试 PCB 后开始对话。

不要同时启用旧包 dsh-plugin-pcb-autoplacement，以免重复注册工具。仅在普通 Node.js 项目中执行 npm install，不会自动把插件启用到 KiCad 正在使用的 DSH 中。

Python 运行环境

插件调用 KiCad 内置的 Python，业务脚本随 npm 包提供，无需另行安装 Python 或手动安装 SDK。KiCad 托管环境已提供 DSH_KICAD_PYTHON 时直接沿用；仅在未提供路径时，将 pythonPath 指向 KiCad 安装目录中的解释器，不使用系统中另一套 Python。

出现导入或连接错误时，先通过 dsh-kicad 核对解释器路径与当前 KiCad 连接，不要求用户自行搭建 Python 环境。

配置

在 DSH 插件设置中，为 @huaqiu/dsh-tool-pcb-autoplacement 设置以下选项：

插件通过随包的 cordis.patch.yml 注册，安装管理器依据 package.json 中的 dsh.bundle.patch 自动加载该文件。

| 选项 | 默认值 | 说明 | | ------------------- | ---------------------------------------- | ------------------------------------------------------ | | pythonPath | DSH_KICAD_PYTHON，未设置时为 python3 | 能导入 kipy 的 Python 可执行文件路径 | | automaticBudgetMs | 3200000 | 一轮自动工作的总预算，单位为毫秒，即 3200 秒 | | captureTimeoutMs | 30000 | PCB 状态采集超时，单位为毫秒 | | artifactsRoot | 系统本地任务目录 | 候选与检查文件的保存位置；自定义时须使用可写的绝对路径 |

Windows 配置示例，请将路径替换为实际安装位置：

pythonPath: 'C:/path/to/KiCad/bin/python.exe'
automaticBudgetMs: 3200000
captureTimeoutMs: 30000

KiCad 托管环境若已设置 DSH_KICAD_PYTHON，可直接沿用。dsh-kicad 自身的连接与配置方式见其 npm 文档。更改配置后，重载 DSH。

使用

在 KiCad 的 DSH 对话中说明布局目标及固定条件，例如：

请对当前 PCB 进行初始布局，保留所有已锁定器件的位置、旋转和板面，
检查器件重叠、出板和固定条件，并说明布局质量与未验证项。

也可以补充本轮要求：

本轮保持 U2 和 J1 不动，其余器件可以重新布局。
请说明候选方案的改善、取舍，以及仍需人工确认的问题。

对话中的固定要求是本轮执行条件，不会自动改写器件的原生 Lock 属性。候选需要完成布局硬检查和业务工程复核；资料不足的项目会标为未验证，评分不能抵消已证实的硬错误。

当前限制

• 当前内测版默认提供文件候选和只读复核。活动板预览、采用和恢复仅对显式授权的隔离测试副本开放，安装插件不会自动启用这些操作。
• 插件不会自动保存工程。
• 本阶段面向布线前布局，不提供布线、信号完整性、热或制造合格结论。

数据与模型

PCB 操作通过本地官方 KiCad IPC 执行。DSH 会将任务所需的上下文交给所配置的模型，是否向远程模型提供方发送板级信息取决于 DSH 的模型配置；本插件不应被理解为完全离线的模型方案。

常见问题

安装后找不到初始布局能力

确认插件安装在 KiCad 实际使用的 DSH profile 中，两个插件均已启用，且 dsh-kicad 包含 pcb-initial-placement。随后重载 DSH。

提示 Python 无法导入 kipy 或 pcbnew

检查 pythonPath 是否指向 KiCad 使用的解释器，而非系统中另一套 Python。kipy 用于官方 IPC；pcbnew 和 kicad-cli 用于需要它们的原生文件检查。

提示无法连接 KiCad

确认 PCB 编辑器已打开板文件、官方 API 服务已启用，并在该 KiCad 托管的 DSH 中重试。连接失败时先恢复连接，再继续布局。

提示 DSH 版本不兼容

核对宿主版本与本包 peerDependencies。当前 alpha 尚未适配 0.2.1-alpha.4；版本豁免不能证明接口兼容。

问题反馈

向维护者反馈时，请提供插件、DSH、KiCad 和 dsh-kicad 的版本，复现步骤、预期结果及实际错误。附上最小复现板和脱敏日志有助于定位问题；不要公开 API Key 或未经授权的工程资料。

版本变更见 CHANGELOG。

许可证

本包当前声明为 UNLICENSED，尚未采用开源许可证。npm 包公开可下载不代表已授予开源使用、修改或再分发许可。

第三方软件依赖遵循各自的许可证，版权与许可声明随对应依赖分发。