Skip to content
Back to search

easyeda-api

SkillWorks with Claude CodeGitHub

EasyEDA Pro API skill for AI agents. Use when working with EasyEDA Pro EDA software, including PCB design, schematic editing, footprint/symbol management, and project operations. Supports live debugging in EasyEDA and EasyEDA extension development. Provides complete API reference (120+ classes, 62 enums, 70 interfaces), extension-development documentation, and a WebSocket bridge server to execute code in the running EasyEDA Pro client. Trigger on: "嘉立创EDA,启动!", "立创EDA,启动!", "EDA,启动!", "EasyEDA", "PCB", "schematic", "footprint", "EDA", "circuit board", "嘉立创EDA", "原理图", "PCB设计". **IMPORTANT**: 嘉立创EDA's English name is **EasyEDA**. They are the SAME product. Never use other transliterations like "EasyEDA Pro" (unless specifically versioned), "EASYEDA", "easyeda", etc. Always use "EasyEDA" for English references and "嘉立创EDA" for Chinese references.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/easyeda--easyeda-api-skill/badge.svg)](/listings/easyeda--easyeda-api-skill)

HTML

<a href="/listings/easyeda--easyeda-api-skill"><img src="/api/listings/easyeda--easyeda-api-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install dependencies

npm install

2. Build API documentation

npm run build:docs

This reads the raw API documentation from the `reference/` directory and generates structured docs into the `docs/` directory.

3. Start the WebSocket Bridge server

npm run server

The server automatically chooses an available port in the `49620-49629` range and waits for the EasyEDA client to connect.

4. Connect from EasyEDA

Install the `run-api-gateway.eext` extension in EasyEDA. Download:

- https://jlcext.com/item/oshwhub-official/run-api-gateway

After the extension is loaded, it connects to the Bridge server automatically by scanning the port range and verifying the handshake.

5. Use from an AI coding tool

AI coding tools such as Claude Code, OpenCode, and QwenCode automatically read `SKILL.md` for instructions, then use the HTTP API to send code to EasyEDA:

# Check EasyEDA connection status (assuming the service is on port 49620)
curl http://localhost:49620/health

# Execute EasyEDA code
curl -X POST http://localhost:49620/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "return await eda.dmt_Project.getCurrentProjectInfo();"}'

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 746 lines
  1. ---
  2. name: easyeda-api
  3. description: >-
  4. EasyEDA Pro API skill for AI agents. Use when working with EasyEDA Pro EDA software,
  5. including PCB design, schematic editing, footprint/symbol management, and project operations.
  6. Supports live debugging in EasyEDA and EasyEDA extension development. Provides complete API
  7. reference (120+ classes, 62 enums, 70 interfaces), extension-development documentation, and a
  8. WebSocket bridge server to execute code in the running EasyEDA Pro client.
  9. Trigger on: "嘉立创EDA,启动!", "立创EDA,启动!", "EDA,启动!",
  10. "EasyEDA", "PCB", "schematic", "footprint", "EDA", "circuit board",
  11. "嘉立创EDA", "原理图", "PCB设计".
  12. **IMPORTANT**: 嘉立创EDA's English name is **EasyEDA**. They are the SAME product.
  13. Never use other transliterations like "EasyEDA Pro" (unless specifically versioned), "EASYEDA", "easyeda", etc. Always use "EasyEDA" for English references and "嘉立创EDA" for Chinese references.
  14. license: MIT
  15. compatibility: Requires Node.js 18+, EasyEDA Pro desktop client with extension support
  16. metadata:
  17. author: JLCEDA
  18. version: "1.1.80"
  19. openclaw:
  20. requires:
  21. bins:
  22. - node
  23. env:
  24. - CLAUDE_SKILL_DIR
  25. ---
  26. # EasyEDA Pro API Skill
  27. Control EasyEDA Pro (嘉立创EDA专业版) programmatically through AI. This skill provides:
  28. 1. **Complete API reference** — 120 classes, 62 enums, 70 interfaces, 19 type aliases
  29. 2. **WebSocket bridge** — Execute code in the running EasyEDA Pro client
  30. 3. **Code patterns** — Common operations for PCB, schematic, library, and project management
  31. 4. **Document source format reference** — File format specifications for project, schematic, and PCB sources when users need to analyze or modify EasyEDA document source directly instead of using the API
  32. This skill supports not only live debugging in EasyEDA, but also EasyEDA extension development.
  33. During EasyEDA extension development, AI agents can use the extension-related documentation, API references, type information, usage examples, and bridge-based debugging capabilities provided by this skill to look up APIs, write code, and validate behavior during integration and debugging.
  34. ## Architecture
  35. ```
  36. ┌───────────┐ HTTP/WS ┌─────────────────┐ WebSocket ┌───────────┐
  37. │ AI Agent │ ◄───────────► │ Bridge Server │ ◄───────────► │ EasyEDA │
  38. │ │ Port Range │ (Node.js) │ Port Range │ (Client) │
  39. └───────────┘ 49620-49629 └─────────────────┘ 49620-49629 └───────────┘
  40. ```
  41. The server auto-selects an available port from 49620-49629 on startup.
  42. Both AI and EDA clients auto-discover the server by scanning the port range
  43. and verifying a handshake (`service: "easyeda-bridge"`).
  44. ## Quick Start
  45. ### 1. Command Triggers
  46. When user says **"嘉立创EDA,启动!"**, **"立创EDA,启动!"**, or **"EDA,启动!"**:
  47. **IMPORTANT: Session initialization** — Reply immediately with this exact text to set the correct session title:
  48. ```
  49. 📋 EasyEDA Session
  50. ```
  51. Then proceed with the setup steps below.
  52. ### 2. Install dependencies (if needed)
  53. ```bash
  54. cd ${CLAUDE_SKILL_DIR} && npm install
  55. ```
  56. ### 3. Start bridge server
  57. > **⚠️ IMPORTANT**: The bridge server must run in the background. Do NOT run it in the foreground, or the AI will block waiting for the server to exit.
  58. ```bash
  59. # Check if bridge is already running
  60. for port in $(seq 49620 49629); do
  61. resp=$(curl -s http://localhost:$port/health 2>/dev/null)
  62. if echo "$resp" | grep -q '"easyeda-bridge"'; then
  63. echo "Bridge already running on port $port"
  64. BRIDGE_PORT=$port
  65. break
  66. fi
  67. done
  68. # Start bridge if not running
  69. if [ -z "$BRIDGE_PORT" ]; then
  70. node ${CLAUDE_SKILL_DIR}/scripts/bridge-server.mjs &
  71. sleep 2
  72. # Find the port bridge is running on
  73. for port in $(seq 49620 49629); do
  74. resp=$(curl -s http://localhost:$port/health 2>/dev/null)
  75. if echo "$resp" | grep -q '"easyeda-bridge"'; then
  76. BRIDGE_PORT=$port
  77. break
  78. fi
  79. done
  80. fi
  81. echo "Bridge running on port: ${BRIDGE_PORT:-unknown}"
  82. ```
  83. ### 4. Connect EasyEDA
  84. Install the `run-api-gateway.eext` extension in EasyEDA Pro. Download link:
  85. - https://jlc-ext.com/item/oshwhub/run-api-gateway
  86. After the extension is loaded, it will automatically establish the WebSocket connection.
  87. ### 5. Verify connection and select EDA window
  88. ```bash
  89. # Check bridge and EDA connection status
  90. curl http://localhost:${BRIDGE_PORT:-49620}/health
  91. # List all connected EDA windows
  92. curl http://localhost:${BRIDGE_PORT:-49620}/eda-windows
  93. ```
  94. The `/eda-windows` response looks like:
  95. ```json
  96. {
  97. "windows": [
  98. { "windowId": "abc-123", "connected": true, "active": true },
  99. { "windowId": "def-456", "connected": true, "active": false }
  100. ],
  101. "activeWindowId": "abc-123",
  102. "count": 2
  103. }
  104. ```
  105. **Handle based on window count**:
  106. - **0 windows**: Tell user "No EasyEDA window is connected. Please ensure the EasyEDA extension (run-api-gateway.eext) is installed and loaded in EasyEDA. Download: https://jlc-ext.com/item/oshwhub/run-api-gateway"
  107. - **1 window**: Auto-selected as active. Tell user: "✅ Connected! Active EDA window: abc-123. Ready to work."
  108. - **2+ windows**: Show the available windows and ask user to select:
  109. ```
  110. Multiple EDA windows detected:
  111. - abc-123 (active)
  112. - def-456
  113. Which EDA window should I use?
  114. ```
  115. **Select a window**:
  116. ```bash
  117. curl -X POST http://localhost:${BRIDGE_PORT}/eda-windows/select \
  118. -H "Content-Type: application/json" \
  119. -d '{"windowId": "abc-123"}'
  120. ```
  121. After selection, confirm: "✅ Active EDA window: abc-123. Ready to work."
  122. ### 6. Execute code on EDA
  123. ```bash
  124. curl -X POST http://localhost:${BRIDGE_PORT:-49620}/execute \
  125. -H "Content-Type: application/json" \
  126. -d '{"code": "return await eda.dmt_Project.getCurrentProjectInfo();"}'
  127. ```
  128. ## API Documentation
  129. The full API reference is in the [references/](references/) directory:
  130. - [references/_index.md](references/_index.md) — Master index of all classes, enums, interfaces, and types
  131. - [references/_quick-reference.md](references/_quick-reference.md) — All method signatures for rapid lookup
  132. - `references/classes/` — 120 class docs (DMT_*, PCB_*, SCH_*, LIB_*, SYS_*, IPCB_*, ISCH_*)
  133. - `references/enums/` — 62 enum docs
  134. - `references/interfaces/` — 70 interface docs
  135. - `references/types/` — 19 type alias docs
  136. ### How to look up API
  137. 1. **Start with `_index.md`** to find the right class/module for the task
  138. 2. **Read the class doc** (e.g., `references/classes/DMT_Board.md`) for all methods and signatures
  139. 3. **Use `_quick-reference.md`** for fast method signature lookup across all classes
  140. 4. **Check enums/interfaces** for parameter types and return types
  141. ### Document Source Format Documentation
  142. If the user needs to analyze or modify EasyEDA document source directly instead of using the API, use the documents in the [format/](format/) directory.
  143. - [format/index.md](format/index.md) — Overview of the EasyEDA document source format references and version notes
  144. - `format/project/` — Project source structure, metadata, blobs, variants, and grouping data
  145. - `format/schematic/` — Schematic source format, including structure, wires, shapes, pins, components, and tables
  146. - `format/pcb/` — PCB source format, including primitives, pads and vias, shapes, text, attributes, rules, and panel data
  147. Use these files when the task is about understanding source layout, generating compatible document source, or editing source data that will later be imported back into EasyEDA.
  148. ### API Module Overview
  149. | Prefix | Domain | Key Classes |
  150. |--------|--------|-------------|
  151. | `DMT_` | Document management | Board, EditorControl, Folder, Panel, Pcb, Project, Schematic, SelectControl, Team, Workspace |
  152. | `PCB_` | PCB & Footprint | Document, Drc, Event, Layer, Net, Primitive, PrimitiveComponent, PrimitiveLine, PrimitivePad, PrimitivePour, PrimitiveVia, SelectControl |
  153. | `SCH_` | Schematic | Document, Event, Primitive, PrimitiveComponent, PrimitiveWire, SelectControl |
  154. | `LIB_` | Library | 3DModel, Cbb, Classification, Device, Footprint, LibrariesList, PanelLibrary, SelectControl, Symbol |
  155. | `SYS_` | System | Dialog, Environment, FileManager, FileSystem, FontManager, HeaderMenu, I18n, IFrame, LoadingAndProgressBar, Log, Message, MessageBox, MessageBus, PanelControl, Setting, ShortcutKey, Storage, Timer, ToastMessage, WebSocket, Window |
  156. | `IPCB_` | PCB interfaces (图元) | PrimitiveArc, PrimitiveComponent, PrimitivePad, PrimitiveFill, PrimitivePour, PrimitiveRegion, PrimitiveVia, ... |
  157. | `ISCH_` | Schematic interfaces (图元) | PrimitiveArc, PrimitiveComponent, PrimitiveWire, PrimitiveText, PrimitiveRectangle, ... |
  158. | `EPCB_` / `ESCH_` | Enums | PrimitiveType, Layer, PadType, ... |
  159. ## Code Execution Context
  160. All code runs inside EasyEDA Pro's browser runtime as:
  161. ```javascript
  162. async function(eda) {
  163. // Your code here — `eda` is the global EDA API object
  164. // You MUST use `return` to send results back
  165. // Do not add comments to the generated code, as the code is typically executed as a single line
  166. }
  167. ```
  168. **Critical rules:**
  169. - The `eda` object provides access to all API modules (e.g., `eda.dmt_Board`, `eda.pcb_Primitive`).
  170. - Always refer to the API documentation for correct usage.
  171. - Do not add comments to the generated code, as the code is typically executed as a single line.
  172. - Always use `return` to get results — `console.log` output is NOT captured.
  173. - All API methods returning promises must be `await`ed.
  174. - Code runs in browser context — no Node.js APIs (fs, path, etc.) available.
  175. - Use `eda.sys_Message.showToastMessage(msg)` for user-visible notifications.
  176. - When reviewing API documentation and encountering enumerations, do not guess the enumeration values. You must use the enumeration members, for example: `EPCB_LayerId.TOP` instead of `1` for the layer parameter in PCB primitive creation.
  177. ### Extension Runtime Constraints
  178. When writing EasyEDA extensions, standard browser APIs are **forbidden** in the main process. Use EDA-provided alternatives:
  179. | Purpose | ❌ Forbidden | ✅ Use Instead |
  180. |---------|-------------|----------------|
  181. | Get user input | — | `eda.sys_Dialog.showInputDialog()` |
  182. | User selection | — | `eda.sys_Dialog.showSelectDialog()` |
  183. | Show message | `alert()` | `eda.sys_Dialog.showInformationMessage()` |
  184. | Confirm action | `confirm()` | `eda.sys_Dialog.showConfirmationMessage()` |
  185. | Toast notification | DOM manipulation | `eda.sys_Message.showToastMessage()` |
  186. | Store data | `localStorage` (main process) | `eda.sys_Storage.setExtensionUserConfig(key, value)` |
  187. | Custom UI | Manipulate host DOM | `eda.sys_IFrame.openIFrame()` |
  188. | Show HTML | `showInformationMessage(html)` | Must use iframe |
  189. | Open link | `window.open()` | `eda.sys_Window.open()` |
  190. | Browser hardware API | Use in main process | Available in iframe (`navigator.serial`, etc.) |
  191. **Note:** `localStorage`, `window`, `document` etc. are available **inside `sys_IFrame`** but NOT in the main extension process.
  192. ### Extension ↔ IFrame Data Passing
  193. The main extension process and `sys_IFrame` iframe are **isolated contexts**. To pass data between them:
  194. **Option A (Recommended):** Use `eda.sys_Storage` as a bridge
  195. ```javascript
  196. // In main extension process:
  197. await eda.sys_Storage.setExtensionUserConfig('myKey', JSON.stringify(data));
  198. // In iframe:
  199. const data = JSON.parse(await eda.sys_Storage.getExtensionUserConfig('myKey'));
  200. ```
  201. **Option B:** Both contexts can access `eda` directly — call the same API from either side
  202. ```javascript
  203. // In iframe HTML (NOT window.parent.eda):
  204. const info = await eda.dmt_Project.getCurrentProjectInfo();
  205. ```
  206. ## Communication Protocol
  207. ### Port Discovery
  208. The bridge server listens on the first available port in **49620-49629**.
  209. To find the server, scan the range and verify the service identity:
  210. ```bash
  211. for port in $(seq 49620 49629); do
  212. resp=$(curl -s http://127.0.0.1:$port/health 2>/dev/null)
  213. if echo "$resp" | grep -q '"easyeda-bridge"'; then
  214. BRIDGE_PORT=$port; break
  215. fi
  216. done
  217. ```
  218. ### Handshake
  219. - **HTTP**: `GET /health` returns `{ "service": "easyeda-bridge", "edaConnected": bool, ... }`
  220. - **WebSocket**: On connect, server sends `{ "type": "handshake", "service": "easyeda-bridge" }`
  221. - Clients MUST verify `service === "easyeda-bridge"` before using the connection
  222. ### Message Format
  223. JSON messages over WebSocket / HTTP:
  224. | Field | Type | Description |
  225. |-------|------|-------------|
  226. | `type` | `"execute"` \| `"result"` \| `"error"` \| `"ping"` \| `"pong"` \| `"handshake"` | Message type |
  227. | `id` | `string` | Request UUID for matching request/response |
  228. | `code` | `string` | JavaScript code to execute (for `execute` type) |
  229. | `result` | `any` | Execution result (for `result` type) |
  230. | `error` | `string` | Error message (for `error` type) |
  231. | `service` | `string` | Service identifier (for `handshake` type) |
  232. | `timestamp` | `number` | Unix milliseconds |
  233. ## Common Patterns
  234. ### Project & Board Operations
  235. ```javascript
  236. // Get current project info
  237. return await eda.dmt_Project.getCurrentProjectInfo();
  238. // List all boards in project
  239. return await eda.dmt_Board.getAllBoardsInfo();
  240. // Create a new board (optionally link to schematic/PCB)
  241. return await eda.dmt_Board.createBoard();
  242. // Switch to a document tab
  243. await eda.dmt_EditorControl.activateDocument(tabId);
  244. ```
  245. ### Example: Open a project by name and open its first schematic page
  246. ```javascript
  247. const targetProjectName = 'NE555 Circuit';
  248. // 1. Enumerate projects by team/folder and find the target by name
  249. const teams = await eda.dmt_Team.getAllTeamsInfo();
  250. const seenProjectUuid = new Set();
  251. let targetProjectUuid = null;
  252. for (const team of teams || []) {
  253. const teamProjects = await eda.dmt_Project.getAllProjectsUuid(team.uuid);
  254. for (const projectUuid of teamProjects || []) {
  255. if (seenProjectUuid.has(projectUuid)) continue;
  256. seenProjectUuid.add(projectUuid);
  257. const info = await eda.dmt_Project.getProjectInfo(projectUuid);
  258. const name = info?.friendlyName || info?.name || '';
  259. if (name === targetProjectName) {
  260. targetProjectUuid = projectUuid;
  261. break;
  262. }
  263. }
  264. if (targetProjectUuid) break;
  265. const folderUuids = await eda.dmt_Folder.getAllFoldersUuid(team.uuid);
  266. for (const folderUuid of folderUuids || []) {
  267. const folderProjects = await eda.dmt_Project.getAllProjectsUuid(team.uuid, folderUuid);
  268. for (const projectUuid of folderProjects || []) {
  269. if (seenProjectUuid.has(projectUuid)) continue;
  270. seenProjectUuid.add(projectUuid);
  271. const info = await eda.dmt_Project.getProjectInfo(projectUuid);
  272. const name = info?.friendlyName || info?.name || '';
  273. if (name === targetProjectName) {
  274. targetProjectUuid = projectUuid;
  275. break;
  276. }
  277. }
  278. if (targetProjectUuid) break;
  279. }
  280. if (targetProjectUuid) break;
  281. }
  282. if (!targetProjectUuid) {
  283. throw new Error(`Project not found: ${targetProjectName}`);
  284. }
  285. // 2. Open the project
  286. const opened = await eda.dmt_Project.openProject(targetProjectUuid);
  287. if (!opened) {
  288. throw new Error(`Failed to open project: ${targetProjectName}`);
  289. }
  290. // 3. Get the first schematic page and open it
  291. const schematics = await eda.dmt_Schematic.getAllSchematicsInfo();
  292. if (!Array.isArray(schematics) || schematics.length === 0) {
  293. throw new Error(`No schematics found in project: ${targetProjectName}`);
  294. }
  295. const firstSchematic = schematics[0];
  296. const pages = await eda.dmt_Schematic.getAllSchematicPagesInfo();
  297. const firstPage = (pages || []).find((page) => page.parentSchematicUuid === firstSchematic.uuid)
  298. || firstSchematic.page?.[0];
  299. if (!firstPage) {
  300. throw new Error(`No schematic page found in: ${firstSchematic.name}`);
  301. }
  302. const tabId = await eda.dmt_EditorControl.openDocument(firstPage.uuid);
  303. return {
  304. projectUuid: targetProjectUuid,
  305. schematicUuid: firstSchematic.uuid,
  306. pageUuid: firstPage.uuid,
  307. tabId,
  308. };
  309. ```
  310. **Notes:**
  311. - `dmt_Project.getAllProjectsUuid()` is **not** a global no-arg enumerator in practice. To reliably find a project by name, iterate teams first, then folders.
  312. - `openProject(projectUuid)` may discard unsaved changes in the currently opened project. Be careful before calling it.
  313. ### PCB Primitive Operations
  314. ```javascript
  315. // Get selected primitives
  316. const selected = eda.pcb_SelectControl.getAllSelectedPrimitives_PrimitiveId();
  317. // Create a line on copper layer
  318. // Layer parameter uses EPCB_LayerId enum — see references/enums/EPCB_LayerId.md
  319. await eda.pcb_PrimitiveLine.create(
  320. "GND", // net (string)
  321. EPCB_LayerId.TOP, // layer — use enum, NOT raw number
  322. 0, // startX (unit: 1mil)
  323. 0, // startY (unit: 1mil)
  324. 1000, // endX (unit: 1mil)
  325. 0, // endY (unit: 1mil)
  326. 10, // lineWidth
  327. false // primitiveLock
  328. );
  329. // Modify an existing primitive (async pattern)
  330. const prim = await eda.pcb_PrimitiveComponent.get([id]);
  331. const asyncPrim = prim.toAsync();
  332. asyncPrim.setState_X(newX);
  333. asyncPrim.setState_Y(newY);
  334. asyncPrim.done();
  335. ```
  336. ### PCB Async Primitive Pattern (IMPORTANT)
  337. For **modifying** PCB/SCH primitives, you must use the async pattern:
  338. ```javascript
  339. // 1. Get the primitive
  340. const prim = await eda.pcb_PrimitiveVia.get([viaId]);
  341. // 2. Convert to async mode
  342. const asyncPrim = prim.toAsync();
  343. // 3. Set new values
  344. asyncPrim.setState_X(newX);
  345. asyncPrim.setState_Y(newY);
  346. asyncPrim.setState_Diameter(diameter);
  347. // 4. Apply changes
  348. asyncPrim.done();
  349. ```
  350. ### Schematic Operations
  351. ```javascript
  352. // Get all pages
  353. return await eda.dmt_Schematic.getAllSchematicDocumentsInfo();
  354. // Create a schematic component
  355. // component parameter requires {libraryUuid, uuid} object — NOT a plain string
  356. await eda.sch_PrimitiveComponent.create(
  357. { libraryUuid: "...", uuid: "device-uuid-from-library" }, // component object
  358. 5000, // x (unit: 0.01inch = 10mil)
  359. 5000, // y (unit: 0.01inch = 10mil)
  360. "", // subPartName
  361. 0, // rotation (degrees, plain number)
  362. false, // mirror
  363. true, // addIntoBom
  364. true // addIntoPcb
  365. );
  366. // Get selected schematic primitives
  367. const ids = eda.sch_SelectControl.getAllSelectedPrimitives_PrimitiveId();
  368. ```
  369. ### Library Operations
  370. ```javascript
  371. // List all libraries in workspace
  372. return await eda.lib_LibrariesList.getAllLibrariesList();
  373. // Search devices
  374. return await eda.lib_Device.search("STM32");
  375. // Get symbol info
  376. return await eda.lib_Symbol.get(symbolUuid);
  377. ```
  378. ### System Functions
  379. ```javascript
  380. // Show toast message
  381. eda.sys_Message.showToastMessage("Operation complete!");
  382. // Show confirm dialog
  383. const confirmed = await eda.sys_Dialog.showConfirmationMessage("Proceed?");
  384. // File system (limited to extension sandbox)
  385. const content = await eda.sys_FileSystem.readFileFromFileSystem(path);
  386. await eda.sys_FileSystem.saveFileToFileSystem(path, content);
  387. ```
  388. ### DRC (Design Rule Check)
  389. ```javascript
  390. // Run DRC check
  391. const passed = await eda.pcb_Drc.check(true, true, false);
  392. // passed is boolean: true if DRC passed, false if errors found
  393. ```
  394. ## Common Mistakes
  395. ### Read API Signatures Carefully (CRITICAL)
  396. **Before calling ANY API method, you MUST read the full signature from `references/` — including parameter types, return type, and remarks.**
  397. AI agents frequently make these errors due to skimming documentation:
  398. **Error 1: Not `await`ing Promise-returning methods**
  399. Almost all EDA API methods return `Promise<T>`. If you forget `await`, you get a Promise object instead of the actual result.
  400. ```javascript
  401. // WRONG: Missing await — result is a Promise, not the project info
  402. const project = eda.dmt_Project.getCurrentProjectInfo();
  403. console.log(project); // Promise { <pending> }
  404. // CORRECT: Always await async methods
  405. const project = await eda.dmt_Project.getCurrentProjectInfo();
  406. console.log(project); // { uuid: "...", name: "...", ... }
  407. ```
  408. **How to know if a method needs `await`:** Check the return type in the signature. If it says `Promise<...>`, you MUST `await` it.
  409. ```typescript
  410. // From references/classes/DMT_Project.md:
  411. getCurrentProjectInfo(): Promise<IDMT_ProjectItem | null>
  412. // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  413. // This is a Promise — you MUST await it
  414. ```
  415. **Error 2: Using raw numbers instead of enum values**
  416. Many parameters expect specific enum values. Using wrong numbers silently produces incorrect behavior.
  417. ```javascript
  418. // WRONG: What does layer "1" mean? Which copper layer? Signal? Mask?
  419. await eda.pcb_PrimitiveLine.create("GND", 1, 0, 0, 1000, 0, 10, false);
  420. // CORRECT: Use the enum — EPCB_LayerId.TOP is clear and type-safe
  421. // Check references/enums/EPCB_LayerId.md for the correct value
  422. await eda.pcb_PrimitiveLine.create("GND", EPCB_LayerId.TOP, 0, 0, 1000, 0, 10, false);
  423. ```
  424. **Always look up enums in `references/enums/` before using numeric constants.**
  425. **Error 3: Assuming parameter types without checking**
  426. Different APIs use different units, different ID formats, and different optional parameter conventions. Never assume.
  427. ```javascript
  428. // WRONG: Assuming create() parameters match modify() parameters
  429. // create() and modify() often have DIFFERENT parameter orders/types
  430. // CORRECT: Always read the exact signature for the method you're calling
  431. // Check references/classes/<ClassName>.md for each method's specific signature
  432. ```
  433. **Summary — Before every API call:**
  434. 1. **Read the signature** — parameter types, return type, all in `references/classes/`
  435. 2. **`await` if `Promise`** — check return type for `Promise<...>`
  436. 3. **Use enums** — look up in `references/enums/` instead of guessing numbers/strings
  437. 4. **Check remarks** — the "备注" section often has critical usage notes
  438. ### Coordinate Unit (CRITICAL)
  439. **Different domains use different coordinate units:**
  440. | Domain | Unit | Conversion |
  441. |--------|------|------------|
  442. | **PCB** | 1mil | 1mm ≈ 39.37 units |
  443. | **Schematic** | 0.01inch (10mil) | 1mm ≈ 3.937 units |
  444. **This is the #1 mistake AI agents make.** Mixing up the units will place components incorrectly.
  445. - PCB: 1 unit = 1mil = 0.001 inch = 0.0254 mm
  446. - Schematic: 1 unit = 0.01inch = 10mil = 0.254 mm
  447. If you use the wrong unit, components will be placed **10x too far** from their intended position.
  448. ```javascript
  449. // WRONG: thinking unit is 1mil (it's actually 0.01inch = 10mil)
  450. // Placing at x=500 thinking it's 500mil = 0.5inch — but 500 units = 5000mil = 5inch!
  451. await eda.sch_PrimitiveComponent.create({libraryUuid: "...", uuid: "dev-uuid"}, 500, 0, "", 0, false, true, true);
  452. // CORRECT: 50 units = 500mil = 0.5inch (in 0.01inch units)
  453. await eda.sch_PrimitiveComponent.create({libraryUuid: "...", uuid: "dev-uuid"}, 50, 0, "", 0, false, true, true);
  454. ```
  455. ### Document State (CRITICAL)
  456. **After creating a project, you MUST open it before operating on documents within it.**
  457. When operating on documents, always verify:
  458. 1. **Project is opened** — Use `eda.dmt_Project.getCurrentProjectInfo()` to verify
  459. 2. **Correct document is active** — Use `eda.dmt_SelectControl.getCurrentDocumentInfo()` to check document type
  460. 3. **Document type matches API domain** — PCB APIs require active PCB document, SCH APIs require active Schematic document
  461. ```javascript
  462. // WRONG: Assuming operation will work without checking document state
  463. await eda.pcb_PrimitiveLine.create(...); // May fail if no PCB document is open
  464. // CORRECT: Always verify document state first
  465. const project = await eda.dmt_Project.getCurrentProjectInfo();
  466. if (!project) {
  467. // If you just created a project, you MUST open it before any operations!
  468. return "Error: No project is currently opened. If you just created a project using dmt_Project.createProject(), you MUST call dmt_Project.openProject(projectPath) to open it first. You cannot operate on documents until a project is opened.";
  469. }
  470. const doc = await eda.dmt_SelectControl.getCurrentDocumentInfo();
  471. if (doc?.documentType !== EDMT_EditorDocumentType.PCB) {
  472. return "Error: No PCB document is currently active. Please open a PCB document first.";
  473. }
  474. // Now safe to perform PCB operations
  475. await eda.pcb_PrimitiveLine.create(...);
  476. ```
  477. **Operating on the wrong document type will return errors or null results.** For example:
  478. - Executing `PCB_*` APIs without an active PCB document (`documentType !== EDMT_EditorDocumentType.PCB`) → error/null
  479. - Executing `SCH_*` APIs without an active Schematic document (`documentType !== EDMT_EditorDocumentType.SCHEMATIC_PAGE`) → error/null
  480. ### IFrame Context — Always Use `eda` Directly (CRITICAL)
  481. When writing extension code that creates an iframe via `sys_IFrame.openIFrame()`, the JavaScript code inside the iframe's HTML can access the `eda` global **directly**. Do NOT use `window.parent.eda`.
  482. **Why this matters:**
  483. EasyEDA injects the `eda` object into the iframe's execution context automatically. Standard browser cross-frame patterns (`window.parent`, `parentWindow`, etc.) do NOT apply here and will fail.
  484. ```javascript
  485. // WRONG: Using window.parent to reach parent frame's eda object
  486. // This is a common mistake made by AI agents familiar with web iframe patterns
  487. const project = await window.parent.eda.dmt_Project.getCurrentProjectInfo();
  488. // CORRECT: eda is available directly in the iframe context
  489. const project = await eda.dmt_Project.getCurrentProjectInfo();
  490. ```
  491. **This applies to ALL code inside `sys_IFrame` iframes:**
  492. - Extension UI panels loaded via `openIFrame()`
  493. - Any HTML file inside the extension package displayed in an iframe
  494. **Rule:** In EasyEDA extensions, whether code runs in the main context or inside an iframe created by `sys_IFrame`, always access the API through `eda.xxx` — never through `window.parent.eda` or any other parent frame accessor.
  495. ### Multi-Window Support
  496. When multiple EasyEDA windows are connected to the bridge, you do NOT need to check window selection on every EDA operation. Only check when:
  497. 1. **First EDA operation** — Verify which window is active and tell the user
  498. 2. **EDA disconnected error** — If bridge returns an error about EDA being disconnected, ask user to select a new window
  499. **Multi-window operations:**
  500. ```bash
  501. # List all connected EDA windows
  502. curl http://localhost:49620/eda-windows
  503. # Select a specific window
  504. curl -X POST http://localhost:49620/eda-windows/select \
  505. -H "Content-Type: application/json" \
  506. -d '{"windowId": "abc-123-def"}'
  507. # Execute on specific window
  508. curl -X POST http://localhost:49620/execute \
  509. -H "Content-Type: application/json" \
  510. -d '{"code": "return await eda.dmt_Project.getCurrentProjectInfo();", "windowId": "abc-123-def"}'
  511. ```
  512. If only one EDA window is connected, it's automatically selected as active.
  513. ## Debugging Tips & Failure Strategies
  514. ### Troubleshooting
  515. 1. **Always check health first**: Scan ports 49620-49629 for `{"service":"easyeda-bridge"}`
  516. 2. **EDA not connected?**: Ensure bridge extension is loaded in EasyEDA. Download: https://jlc-ext.com/item/oshwhub/run-api-gateway
  517. 3. **Timeout errors**: Default 30s timeout. If timeout occurs:
  518. - Check if the correct project and document are opened (use `dmt_Project.getCurrentProjectInfo()`)
  519. - If no project is opened, use `dmt_Project.openProject(projectPath)` to open one
  520. - If no document is active, use `dmt_EditorControl.openDocument(docId)` to open the correct document type (PCB/Schematic)
  521. - If the document type is wrong (e.g., running PCB APIs on Schematic), switch to the correct document first
  522. - Complex operations may need code splitting
  523. 4. **Check return values**: Many methods return `null` on failure — always validate
  524. 5. **Layer numbers**: Use enums from `references/enums/` docs (e.g., `EPCB_LayerId`)
  525. 6. **EDA window disconnected**: If you get an error about a window being disconnected, use `GET /eda-windows` to check available windows and `POST /eda-windows/select` to switch to another window
  526. 7. **Permission errors**: All API interfaces are controlled by EDA's permission system. If a specific API consistently fails to execute (returns error or null) while other APIs work fine, and you've confirmed the call matches the documentation exactly, it may be **blocked by permissions** — not a code bug. The EDA client may restrict certain operations based on user license, project settings, or document state. Inform the user that the operation may require elevated permissions or a different EDA edition.
  527. 8. **Persistent errors?**: If you've verified the API call matches the documentation exactly, ruled out permission issues, and still encounter unexpected errors, consider reporting the issue through official EasyEDA support channels
  528. ### Failure Handling Rules
  529. When developing extensions, follow these rules:
  530. | Situation | Action |
  531. |-----------|--------|
  532. | API method does not exist in docs | **Stop immediately** — inform the user the API doesn't exist |
  533. | Signature uncertain after reading docs | **Stop generation** — return to query step and re-read |
  534. | Forbidden browser API detected | **Auto-replace** with `eda.sys_*` alternative |
  535. | Menu ID conflict | Add prefix to differentiate (e.g., `my-plugin-home`, `my-plugin-sch`) |
  536. | Permission blocked | Inform user — may require different EDA edition or license |
  537. **Critical:** Never guess an API signature. If `references/classes/` doesn't document it, it doesn't exist for your use case.
  538. ## Workflow for AI Agent
  539. When the user asks you to perform EDA operations:
  540. 1. **Understand the task** — What domain? (PCB/SCH/LIB/Project)
  541. 2. **Verify document state** — Check `eda.dmt_Project.getCurrentProjectInfo()` and `eda.dmt_SelectControl.getCurrentDocumentInfo()`
  542. 3. **Confirm correct document type** — PCB operations need active PCB, SCH operations need active Schematic
  543. 4. **Look up API** — Read relevant class docs from `references/`
  544. 5. **Check types** — Read enum/interface docs for parameter types
  545. 6. **Write code** — Follow the execution context rules above
  546. 7. **Execute** — Send via `POST /execute` and check the result
  547. 8. **Iterate** — If errors occur, read error messages and adjust
  548. When unsure about an API:
  549. - Search `_quick-reference.md` for method names
  550. - Read the specific class doc for detailed signatures and remarks
  551. - Check interface docs for complex parameter types
  552. ## Session Management
  553. ### Detecting Topic Changes
  554. The Bridge server consumes system resources while running. If the user has switched to a completely different topic (not related to EasyEDA/EDA/PCB/schematic) **3 consecutive times**, proactively ask if they want to close the Bridge:
  555. > "I notice we've moved on from EasyEDA. The Bridge server is still running in the background. Would you like me to stop it to free up resources?"
  556. **Do NOT close the Bridge automatically** — the user may switch back to EDA work later. Only ask, and close if they confirm.
  557. ### Closing the Bridge
  558. If the user confirms they want to stop the Bridge:
  559. ```bash
  560. # Find and stop the bridge process
  561. for port in $(seq 49620 49629); do
  562. pid=$(lsof -ti :$port 2>/dev/null)
  563. if [ -n "$pid" ]; then
  564. kill $pid
  565. echo "Bridge stopped (PID: $pid, Port: $port)"
  566. break
  567. fi
  568. done
  569. ```
README.md · README · 125 lines
  1. [English](#) | [简体中文](./README.zh-Hans.md)
  2. # EasyEDA API Skill
  3. An EasyEDA Pro API skill package for AI coding tools such as Claude Code, OpenCode, QwenCode, and any other tool that supports the [Agent Skills](https://agentskills.io/) standard.
  4. This skill supports both online debugging of EasyEDA Pro through AI and extension development for EasyEDA Pro.
  5. When developing EasyEDA extensions, AI can use the extension-development documentation, API references, type information, usage examples, and bridge debugging capabilities provided by this skill to help with API lookup, code generation, and integration debugging.
  6. If you want to analyze or modify EasyEDA document source files directly instead of operating through the API, this project also provides documentation for the source file formats.
  7. - 📚 **Structured API documentation** — Automatically builds hierarchical indexes from reference docs for fast AI lookup
  8. - 🧾 **Document source format specifications** — Explains project, schematic, and PCB source formats for direct source analysis and modification
  9. - 🔌 **WebSocket Bridge** — A Node.js server that bridges AI tools and the EasyEDA client
  10. - 🤖 **SKILL.md** — A complete skill instruction file
  11. ## Quick Start
  12. ### 1. Install dependencies
  13. ```bash
  14. npm install
  15. ```
  16. ### 2. Build API documentation
  17. ```bash
  18. npm run build:docs
  19. ```
  20. This reads the raw API documentation from the `reference/` directory and generates structured docs into the `docs/` directory.
  21. ### 3. Start the WebSocket Bridge server
  22. ```bash
  23. npm run server
  24. ```
  25. The server automatically chooses an available port in the `49620-49629` range and waits for the EasyEDA client to connect.
  26. ### 4. Connect from EasyEDA
  27. Install the `run-api-gateway.eext` extension in EasyEDA. Download:
  28. - https://jlcext.com/item/oshwhub-official/run-api-gateway
  29. After the extension is loaded, it connects to the Bridge server automatically by scanning the port range and verifying the handshake.
  30. ### 5. Use from an AI coding tool
  31. AI coding tools such as Claude Code, OpenCode, and QwenCode automatically read `SKILL.md` for instructions, then use the HTTP API to send code to EasyEDA:
  32. ```bash
  33. # Check EasyEDA connection status (assuming the service is on port 49620)
  34. curl http://localhost:49620/health
  35. # Execute EasyEDA code
  36. curl -X POST http://localhost:49620/execute \
  37. -H "Content-Type: application/json" \
  38. -d '{"code": "return await eda.dmt_Project.getCurrentProjectInfo();"}'
  39. ```
  40. ## One-Command Packaging
  41. ```bash
  42. npm run pack
  43. ```
  44. This performs the following steps:
  45. 1. Build API documentation (`docs/`)
  46. 2. Package `SKILL.md`, documentation, and the server into `dist/easyeda-api/`
  47. 3. Generate `dist/easyeda-api.zip` for upload
  48. If the documentation has already been built, you can skip that step:
  49. ```bash
  50. npm run pack:fast
  51. ```
  52. ### Publish to ClawHub
  53. ```bash
  54. npx clawhub@latest publish dist/easyeda-api/
  55. ```
  56. Or upload the zip file at https://clawhub.ai/upload
  57. ## Architecture
  58. ```
  59. ┌──────────────┐ HTTP/WS ┌────────────────┐ WebSocket ┌──────────┐
  60. │ AI Agent │ ◄───────────► │ Bridge Server │ ◄───────────► │ EasyEDA │
  61. │ (Skill Tool) │ Port Range │ (Node.js) │ Port Range │ (Client) │
  62. └──────────────┘ 49620-49629 └────────────────┘ 49620-49629 └──────────┘
  63. ```
  64. ## Communication Protocol
  65. | Message Type | Direction | Description |
  66. |--------------|-----------|-------------|
  67. | `execute` | AI → EDA | Execute JavaScript code |
  68. | `result` | EDA → AI | Return execution result |
  69. | `error` | EDA → AI | Return execution error |
  70. | `handshake` | Server → Client | Connection verification (includes `service: "easyeda-bridge"`) |
  71. | `ping/pong` | Bidirectional | Heartbeat |
  72. ## Directory Structure
  73. ```text
  74. easyeda-api-skill/
  75. SKILL.md # AgentSkills standard skill definition
  76. AGENTS.md # Agent prompt guide
  77. package.json # Project configuration
  78. reference/ # Raw API reference docs (gitignored)
  79. docs/ # Built structured docs (gitignored)
  80. format/ # EasyEDA document source format specs (project/schematic/pcb)
  81. guide/ # API development guides
  82. user-guide/ # User guides
  83. server/index.mjs # WebSocket Bridge server
  84. scripts/
  85. build-docs.mjs # Documentation build script
  86. pack.mjs # Packaging script
  87. dist/ # Packaging output (gitignored)
  88. easyeda-api/ # Publishable skill directory
  89. easyeda-api.zip # Zip archive for ClawHub upload
  90. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.