# AGENTS.md — KiCad PCB + ZWCAD 项目操作指南

> 其他 Agent 在操作本项目前**必须阅读此文件**。

## 环境概况

- **KiCad**: 10.0.6，安装于 `C:\Program Files\KiCad\10.0\bin`
- **IPC API**: 已启用（`kicad_common.json` 中 `enable_server: true`）
- **kipy**: v0.8.0，KiCad Python 环境中
- **项目路径**: `K:\PCB-KiCad\test\test.kicad_pro`
- **ZWCAD**: 2020，安装于 `C:\Program Files\ZWSOFT\ZWCAD 2020\`
- **ZWCAD COM**: ProgID `ZWCAD.Application.2020`，CLSID `{EC92313D-5A17-11E7-B72E-BC5FF42AC839}`

## 快速连接

```powershell
# 一键检测连接状态
& "C:\Program Files\KiCad\10.0\bin\python.exe" "K:\PCB-KiCad\kicad_connect.py"
```

连接前提：KiCad 已运行且通过 GUI 打开了 PCB 文件。

## 快速连接（ZWCAD）

```powershell
# 附加到已运行的 ZWCAD 实例
$app = [Runtime.InteropServices.Marshal]::GetActiveObject("ZWCAD.Application.2020")

# 或启动新实例
$app = New-Object -ComObject "ZWCAD.Application.2020"
$app.Visible = $true
```

连接前提：ZWCAD 已安装。附加模式需 ZWCAD 已运行；新建模式会自动启动。

## 关键规则

1. **Python 环境**：必须用 `C:\Program Files\KiCad\10.0\bin\python.exe`，不可用系统 Python
2. **kipy 导入**：`from kipy.kicad import KiCad`（不是 `kicad` 或 `kicad_python`）
3. **IPC 服务器**：修改配置后必须重启 KiCad
4. **文档访问**：PCB 必须通过 KiCad GUI 打开（双击文件树），不可独立启动 pcbnew
5. **视觉验证**：由用户手动执行，Agent 不调用 computer_use
6. **PCB 旋转**：90° 旋转矩阵为 (x,y)→(y,-x)，非标准数学 CCW
7. **坐标系统**：原理图和 PCB 均为 Y 轴向下
8. **ZWCAD COM 数组封送**：PS5 原生 COM 调用无法传递 double[] 数组，必须用 C# `Type.InvokeMember`，详见 `ZWCAD_COM_Guide.md`
9. **ZWCAD 坐标系**：Y 轴向上（标准数学方向，与 KiCad 相反）

## 文件说明

| 文件 | 用途 |
|------|------|
| `kicad_ipc_guide.md` | KiCad 完整连接指南 + 失败案例 + API 速查 |
| `kicad_connect.py` | KiCad 即插即用连接检测脚本 |
| `kicad_setup.ps1` | KiCad 一次性环境配置脚本 |
| `generate_design.py` | PCB 设计生成脚本（原理图 + PCB） |
| `ZWCAD_COM_Guide.md` | ZWCAD COM 自动化完整指南（必读） |
| `zwcad_final.ps1` | ZWCAD 画图脚本模板（C# InvokeMember 方案） |
| `zwcad_array.ps1` | ZWCAD 打开 DWG + 绘制正方形矩阵 |
| `zwcad_marshal_diag.ps1` | ZWCAD COM 数组封送诊断脚本 |

## DRC/ERC 检查

```powershell
# PCB 设计规则检查
& "C:\Program Files\KiCad\10.0\bin\kicad-cli.exe" pcb drc -o "K:\PCB-KiCad\test\drc.txt" "K:\PCB-KiCad\test\test.kicad_pcb"

# 原理图电气规则检查
& "C:\Program Files\KiCad\10.0\bin\kicad-cli.exe" sch erc -o "K:\PCB-KiCad\test\erc.txt" "K:\PCB-KiCad\test\test.kicad_sch"
```

## 常见错误速查

| 症状 | 解决 |
|------|------|
| `ModuleNotFoundError: kicad` | `from kipy.kicad import KiCad` |
| `ConnectionError` | 检查 `enable_server: true`，重启 KiCad |
| `no handler available` | 在 KiCad GUI 中双击打开 PCB 文件 |
| `board.filepath` 不存在 | 用 `get_open_documents()` 获取文件信息 |
| DRC 焊盘位置与计算不符 | PCB 旋转: (x,y)→(y,-x) |
| ZWCAD AddLine 坐标全 (0,0) | PS5 数组封送 bug，用 C# `Type.InvokeMember` |
| `Value does not fall within expected range` | double[] 直传 COM，改用 InvokeMember |
| `CreateTypedArray` 返回 null | PS5 限制，不使用，改用 `[Zw]::P(x,y)` |
| `SendCommand` 无效果 | 附加实例不执行，用 `PostCommand` 或 COM API |
| 窗口不显示新内容 | ZoomExtents 也需 InvokeMember，或用 ZoomCenter |
| Add-Type 编译报"视为错误的警告" | C# 有未使用变量，删除或用 `catch (Exception)` |