1. 从一次真实的 PCB 改板说起：EasyEDA AI Skill 到底解决了什么问题
你有没有遇到过这种场景：板子画到一半，DRC 报了一屏间距违规，你只能一个个点开、量距离、改坐标，改完再跑一遍，又冒出来新的。或者更烦的，原理图里 80 多个元件的位号要批量改前缀，手动改到怀疑人生。这类活儿不难，但极其消耗耐心，而且特别适合交给机器去做。
EasyEDA AI Skill 就是冲着这类需求来的。它做的事情可以一句话概括：让大模型通过一套统一的 Key/API 通道，直接调用运行中的嘉立创 EDA（EasyEDA）客户端能力，包括放置元件、读取图元、跑 DRC、创建差分对、拿网表等等。你不需要写插件、不需要学 EDA 的扩展开发，只要在 AI 编程工具里说一句「帮我检查 PCB 的 DRC 并修掉所有报错」，剩下的查文档、写代码、发请求、解析结果、迭代修复，全自动完成。
它适合谁？三类人最直接受益。第一类是想复刻这条链路的开发者——你手上可能有别的桌面软件（带 SDK 的那种），想照着 EasyEDA 这套桥接模型做一个自己的 Skill。第二类是日常画板的硬件工程师，想让 AI 帮忙做重复性的图元操作和规则检查。第三类是做 Agent 基础设施的人，想看看一个高质量的 AgentSkills 技能包内部到底长什么样。
这篇文章不打算停留在「用一下看看效果」。我会把整个链路拆开：从 SKILL.md 的技能定义、Bridge Server 的端口发现和协议设计、reference 目录的文档组织，到统一 Key/API 通道怎么接进来，最后给出一份可复制的 Skill 配置片段和一次端到端验证动作。读完你应该能自己动手把这条链路跑通，并且知道每一步为什么这么设计。
先看整体架构。EasyEDA AI Skill 是一个典型的三方桥接模型：AI Agent 在左边，EasyEDA 桌面客户端在右边，Bridge Server 在中间当翻译官。AI Agent 通过 HTTP REST API 把代码发到 Bridge Server，Bridge Server 再通过 WebSocket 转发给 EasyEDA 客户端执行，结果原路返回。整个通信跑在一个自动发现的端口范围 49620–49629 上，启动时不用手动指定端口，多个 Bridge 实例之间也不会冲突——这一点在实战里很关键，比如你一台机器上同时跑 Claude Code 和另一个 Agent 工具，两边各起一个 Bridge，互不干扰。
把 Bridge Server 比作翻译官不算夸张。AI Agent 说的是 JSON-RPC 风格的 execute 请求，EDA 客户端需要的是浏览器沙箱里的 JS 执行环境，Bridge Server 在这两者之间做了请求-响应匹配、超时控制、多窗口路由和心跳维护。理解了这层，后面所有的配置和排障都会顺很多。
2. 前置准备：用 TaoToken 统一 Key/API 通道接入大模型
在拆 Bridge Server 之前，得先把「大模型这一端」接好。因为整个链路里，AI Agent 是要真正去理解你的自然语言指令、查 API 文档、写 JS 代码的，这背后需要一个稳定可用的大模型调用通道。我这边用的是 TaoToken 作为统一入口，它把模型对话、Coding Plan、API Keys 这些能力收在一个地方，省得你在多个平台之间来回切。
TaoToken 是什么、能做什么、适合谁：它是一个面向开发者的模型调用与 Agent 能力平台，提供统一的 API 通道，你可以用它来驱动 Claude Code、Cline、Codex 这类编程工具，也可以直接调模型对话接口。适合想快速把大模型接进自己工作流、又不想折腾多套鉴权的开发者。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个不加 UTM）。
具体怎么接？分三步走。
第一步，拿到你的 API Key。进控制台创建：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面生成一个 Key：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。这个 Key 就是你后面所有工具的统一凭证，Base URL 填 https://taotoken.net/api ，Model ID 按你选的模型填（比如 claude 系列或 gpt 系列，具体以控制台展示为准）。
第二步，如果你用的是 Claude Code 这类工具，需要配置环境变量。这里有个坑：不同工具读的变量名不一样。Claude Code 读的是 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，而有些工具读 OPENAI_BASE_URL。我建议你先确认自己用的工具读哪套，再对应填。配置文档在这里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各工具的详细说明。
第三步，验证通道是否通。最直接的办法是发一个最小请求，看能不能拿到模型回复。如果你只是想先确认模型能用，可以直接在模型对话页面试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 。如果打算长期跑编码和 Agent 任务，建议直接上 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，额度更划算。
这里要强调一点：统一 Key/API 通道的价值在于「一处配置，多处复用」。你的 AI Agent、Bridge Server 的调试脚本、甚至后面写的小工具，都可以共用同一个 Base URL 和 Key。这样当你要换模型或者调额度时，只改一个地方。对于 EasyEDA Skill 这种需要 AI 频繁读文档、写代码的场景，通道的稳定性直接决定了体验——通道一断，AI 就卡在「正在思考」不动了。
配置好之后，你的 AI 工具就具备了「理解指令 + 生成代码」的能力。接下来要做的，是给它一个能真正操作 EDA 的「手」——也就是 Bridge Server 和 Skill 配置。
3. 可复制配置：Skill 片段、Bridge Server 与 settings 文件
这一节是全文最实操的部分。我会给出可以直接复制粘贴的配置片段，包括 Skill 的 SKILL.md 关键字段、Bridge Server 的启动方式、以及 AI 工具的 settings 配置。你照着填，就能把链路搭起来。
先说 Skill 的入口文件 SKILL.md。AgentSkills 规范里，AI 工具加载技能时读的就是这个文件。它的 YAML 前置元数据里，description 字段嵌入了触发词列表，比如「嘉立创EDA，启动！」「立创EDA，启动！」「EDA，启动！」，还有 EasyEDA、PCB、schematic、footprint 这些英文关键词。当你在对话里说到这些词，AI 工具会自动匹配并加载这个技能。下面是一个精简后的 SKILL.md 结构示例：
--- name: easyeda-api description: > 通过 Bridge Server 操控运行中的嘉立创 EDA（EasyEDA）客户端。 触发词：嘉立创EDA，启动！/ 立创EDA，启动！/ EDA，启动！/ EasyEDA / PCB / schematic / footprint。 注意：嘉立创EDA 的英文名是 EasyEDA，两者是同一个产品。 license: MIT compatibility: EasyEDA Pro 3.2.149+, Run API Gateway v1.0.5+ ---注意 description 里那句「嘉立创EDA 的英文名是 EasyEDA，两者是同一个产品」。这不是给人看的注释，是给 AI 的纠偏指令——有些模型会把这两者当成不同产品，或者在英文语境下用别的音译。直接写在 description 里，每次触发都会注入，确保不会歧义。这个技巧在你写自己的 Skill 时非常值得抄。
然后是 Bridge Server 的启动。它依赖 ws 库，启动命令很简单：
git clone <easyeda-api-skill 仓库地址> cd easyeda-api-skill npm install npm run server服务会自动在 49620–49629 范围内找到空闲端口启动。端口发现用了两层判断：第一层 isPortInUse() 发起 TCP 连接，300ms 超时，连上了就是被占用；第二层 isBridgeRunning() 对目标端口发 GET /health，解析 JSON 看 service 字段是不是 "easyeda-bridge"。两层都过了才绑定监听。如果发现已有实例在跑，直接 process.exit(0) 退出，防止重复启动。
接下来是 AI 工具的 settings 配置。以 Claude Code 为例，你需要把 Skill 放到它扫描的目录，并配置模型通道。下面是一个 settings 片段示例（路径按你的实际环境调整）：
{ "skillsDir": "~/.claude/skills", "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的 TaoToken API Key", "ANTHROPIC_MODEL": "你的 Model ID" } }如果你用的是 Cline 或类似的工具，配置项名可能不同，但核心三件套是一样的：Base URL + Key + Model ID。这三样缺一不可，而且必须和 TaoToken 控制台里展示的一致。我见过有人把 Base URL 末尾多写了一个斜杠，结果一直 404，排查了半天。
再补一个 Codex 的 auth.json 示例，因为 Codex 的鉴权文件格式比较特殊：
{ "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "你的 TaoToken API Key", "model": "你的 Model ID" }这里要提醒一句：不同工具读的环境变量名不一样，Claude Code 读 ANTHROPIC_，Codex 和很多 OpenAI 兼容工具读 OPENAI_。你填之前先确认工具文档，别一股脑全填上，有时候冲突了反而报错。
配置完成后，目录结构大概是这样：
easyeda-api-skill/ ├── SKILL.md ├── scripts/ │ └── bridge-server.mjs ├── references/ │ ├── classes/ # 120+ 个 API 类文档 │ ├── enums/ # 62 个枚举定义 │ ├── interfaces/ # 70+ 个接口类型 │ └── _quick-reference.md ├── guide/ └── format/references/ 目录是技能包的真正数据层。classes/ 下每个文件对应一个 API 类，格式统一：类名、描述、方法列表（含类型签名、参数说明、返回值类型、备注）。_quick-reference.md 是一个单文件速查表，把所有类的方法签名列在一起——当 AI 只需要确认方法名或参数顺序时，读这一个文件就够了，不需要逐个打开 120 个类文件。对于有 token 窗口限制的 AI 工具来说，这个设计直接影响了单轮对话能完成的复杂度。
这套配置的核心思路是离线优先：所有 API 文档打包在技能包内部，AI 查 API 时不需要访问在线文档站点。这解决了两个实际问题：一是在线文档站是 JS 渲染的，curl 或 AI 工具爬不到内容；二是离线环境下照样能工作。
4. 端到端验证：从 health 检查到一次真实的 DRC 触发
配置写完了，怎么确认大模型真的能触发 EasyEDA 操作？这一节给出一条完整的验证路径，从最底层的 health 检查，到一次真实的 DRC 触发，每一步都有预期结果。
第一步，验证 Bridge Server 活着。启动服务后，在终端跑：
curl http://localhost:49620/health预期返回类似：
{ "service": "easyeda-bridge", "edaConnected": true, "activeWindowId": "win-xxxx", "timestamp": 1730000000000 }如果 edaConnected 是 false，说明 EasyEDA 客户端还没连上来，先去装 Run API Gateway 扩展。如果连端口都连不上，说明 Bridge Server 没起来，回去看 npm run server 的输出。
第二步，验证 EDA 窗口连接。跑：
curl http://localhost:49620/eda-windows预期返回当前所有连接的 EDA 窗口列表。如果只有一个窗口，Bridge Server 会自动把它选为活跃窗口——这个「默认选中」的逻辑省掉了大量交互轮次。如果有多个窗口（比如原理图和 PCB 各开一个），你需要用 POST /eda-windows/select 指定 windowId。
第三步，发一个最小的 execute 请求，确认代码能在沙箱里跑。用 curl 发：
curl -X POST http://localhost:49620/execute \ -H "Content-Type: application/json" \ -d '{"code": "return eda.dmt_Project.getCurrentProjectInfo();"}'预期返回当前工程的信息对象。如果返回 result: null，八成是代码没写顶层 return，或者包在了 IIFE 里——这是最常见的坑之一，后面会细说。
第四步，让 AI 真正触发一次操作。在 AI 工具里说：「帮我检查当前 PCB 的 DRC 并列出所有报错」。AI 会先调 eda.dmt_Project.getCurrentProjectInfo() 确认工程开着，再调 eda.dmt_SelectControl.getCurrentDocumentInfo() 确认当前激活的是 PCB 文档，然后跑 eda.pcb_Drc.check(true, true, false) 拿到报错列表。
如果报的是间距违规，AI 会去 references/classes/PCB_Primitive.md 查 get() 方法的签名，然后调 eda.pcb_Primitive.get([id]) 取出图元，toAsync() 进入修改模式，setState 调整坐标或宽度，done() 提交变更。全部修完再跑一次 check()，反复迭代直到 passed 为 true。
如果报的是差分对阻抗不匹配，AI 不走图元修改的路子，而是去查 references/classes/PCB_Drc.md，发现 createDifferentialPair() 和 createNetClass() 可以直接用代码创建规则——USB_DP 和 USB_DM 配成一个 90Ω 差分对，不需要在 UI 里逐个点选。整段代码不到十行，从查文档到执行完毕不超过一分钟。
整个过程 AI 不需要离开对话界面，你只需要说一句自然语言指令。剩下的查 API、写代码、发 HTTP 请求、解析结果、迭代修复，全部由 AI 和 Bridge Server 自动完成。这就是「大模型操控 PCB 设计软件」的真实样子——不是模拟鼠标点击，而是语义级的 API 调用。
验证通过后，你可以再试几个更复杂的场景，比如批量改位号、跨页拿网表、自动放置去耦电容。每验证一个，你对这条链路的信任度就高一分。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
链路跑起来之后，真正花时间的往往是排障。这一节我把几个高频报错和对应的排查路径列出来，都是实测踩过的。
报错一：401 Unauthorized。这个基本都出在模型通道这一端。原因通常是 API Key 填错、过期，或者 Base URL 和 Key 不匹配。排查顺序：先确认 Key 是从 TaoToken 控制台复制的完整字符串，没有多余空格；再确认 Base URL 是 https://taotoken.net/api ，末尾没有多余斜杠；最后确认你用的工具读的环境变量名对不对——Claude Code 读 ANTHROPIC_AUTH_TOKEN，Codex 读 OPENAI_API_KEY，填错了就等于没填。如果三样都对还是 401，去控制台看这个 Key 的额度是不是用完了。
报错二：local proxy failed。这个报错通常出现在工具尝试走本地代理但代理没起来的时候。排查思路：先确认你的网络环境不需要额外代理配置（很多开发机是直连的，配了代理反而坏事）；再检查工具配置里有没有残留的 proxy 设置，有就清掉；最后确认 Bridge Server 和 AI 工具在同一台机器上，或者网络可达。如果是 Bridge Server 跑在虚拟机、EasyEDA 跑在宿主机这种跨机部署，要确认防火墙没挡住 49620–49629 这个端口段。
报错三：reading 'choices' 相关报错。这个报错一般意味着模型返回的响应格式和你工具预期的格式对不上。常见原因是 Model ID 填错了，或者你用的工具走的是 OpenAI 兼容格式但模型返回的是另一种格式。排查：确认 Model ID 和控制台展示的完全一致；确认工具的 API 格式设置（有些工具要显式选 OpenAI Compatible）；如果还不行，换一个模型试试，排除是单个模型的问题。
报错四：OAuth 相关报错。有些工具默认走 OAuth 登录流程，但你用的是 API Key 模式，两者会打架。排查：在工具设置里关掉 OAuth 登录选项，强制走 API Key；确认没有同时配置 OAuth token 和 API Key，有冲突就删掉 OAuth 那部分；如果工具支持多种鉴权模式，明确选 API Key 模式。
除了模型通道的报错，EasyEDA 这一端也有几个高频坑，一并列出来：
坑一：字段名写错。sch_PrimitiveComponent.getAll() 返回的元件对象里，位号字段叫 designator 而不是 designation。用错字段名，遍历 80 多个元件看起来全是空对象，第一反应会是「API 坏了」，实际是字段名写错了。正确姿势是先 var s = all.find(p => p.designator); return Object.keys(s) 探一下，而不是猜。
坑二：返回值捕获失败。execute 的代码必须顶层 return，不能包在 IIFE 里。写成 (async () => { ... })() 的话，Bridge 会收到 result: null，因为 IIFE 的返回值被吞掉了。正确写法就是直接 return await eda.xxx()。
坑三：跨页操作读错文档。dmt_EditorControl.openDocument(uuid) 返回成功，但后续的 getAll() 读的还是最初的页面——沙箱绑定在第一个打开的文档上。对于跨页的网络分析，用 sch_Netlist.getNetlist() 可以拿到整个工程的网表，不需要切换页面。
坑四：console.log 不可靠。沙箱里 console.log 的输出不会被 Bridge 捕获，调试要用 eda.sys_ToastMessage.showMessage() 或者直接 return。
坑五：await 漏写。getByLcscIds、search、getAll、DRC、netlist 这些全是异步的，必须 await。唯一的例外是 3.2.149 版本的 create() 方法是同步的。
这些坑在 SKILL.md 和 references/live-api-pitfalls.md 里都有记录，但真正遇到的时候还是得靠 AI 自己对照提示去排查——这也是为什么 SKILL.md 里要写这么详细的常见错误清单。一个高质量的 Skill，踩坑文档和代码模式同等重要。
6. 把这条链路复用到你自己的桌面软件上
拆完 EasyEDA 这套 Skill，最有价值的其实不是 EDA 本身，而是它背后的通用结构。一个 499 行的桥接服务器、一份 746 行的 SKILL.md、120+ 份 API 参考文档，组合在一起就是一个标准化的 AI Agent 技能包。这套结构对任何「让 AI 操控桌面软件」的场景都适用。
如果你想复刻，核心就四件事。第一，桥接层要薄但要稳。Bridge Server 只做三件事：端口发现、请求转发、超时保护。不解析代码语义、不做权限控制、不缓存结果。薄的好处是好维护、好调试；稳的要求是超时必有兜底、断连必有清理。第二，SKILL.md 是给 AI 的使用说明书，不是给人的 README。触发词列表、执行环境约束、常见错误清单、调试流程，这些要写成具体的判断逻辑（「如果窗口数为 0，告诉用户检查扩展安装」），而不是概览描述。第三，离线优先。所有 API 文档打包在技能包内部，AI 调用的每一步都不需要网络请求去取文档。第四，踩坑文档和代码模式同等重要。同样的坑每个新用户都会踩一遍，提前写出来省掉的是反复排查的时间。
具体到操作层面，把 eda 对象换成目标软件的 SDK 对象，把 API 文档按同样的 reference 格式组织，把 bridge-server 的端口发现和协议层直接复用——搞定。对于有 SDK 的桌面软件来说，这套桥接模型几乎可以原封不动地搬过去。
最后说一个实际部署的注意点。Run API Gateway 扩展的自动扫描只覆盖本机 localhost。如果 Bridge Server 跑在另一台机器上（比如 Ubuntu 虚拟机），需要在扩展的「配置」里手动填写 Bridge Server 的 IP 地址。我试过的一种部署是 Bridge Server 跑在 Ubuntu VM 的 0.0.0.0:49620，Windows 宿主机上的 EasyEDA 通过局域网 IP 连接——两台机器、两个 Bridge 实例互不干扰。这种跨机部署在团队协作场景里挺有用，一个人维护 Bridge，多个人连上来用。
如果你打算长期跑这类 Agent 任务，建议把模型通道也固定下来。统一用 TaoToken 的 Coding Plan 是个省心的选择：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，额度和稳定性都比按次调用更适合高频的 Agent 场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到配置问题先翻这里。想先验证模型能力的话，模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite ，API Keys 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。
整套链路跑通之后，你会发现真正的门槛不在代码，而在「把 AI 的决策路径写死在技能定义里，不给它瞎猜的空间」。这一点想明白了，你手上任何一个带 SDK 的桌面软件，都能变成 AI 能操控的工具。
