extension-dev-skill

name	extension-dev-skill
description	AI Skill for building EasyEDA Pro extension plugins. Used when users need to create, modify, or debug EasyEDA Pro plugins, including generating plugin code, querying API documentation, configuring extension.json, and handling i18n localization. Trigger words: "EasyEDA", "嘉立创EDA", "EDA plugin", "EDA extension", "extension.json", "pro-api-types", "原理图", "PCB设计"
tags	["EDA","EasyEDA","plugin","extension","PCB","schematic","嘉立创"]
license	MIT
compatibility	Build requires Node.js 18+; runtime is EasyEDA Pro browser sandbox
metadata	{"author":"JLCEDA","version":"2.0.0"}

extension-dev-skill

AI Skill for EasyEDA Pro extension plugin development. Provides scenario-driven recipes, complete API reference, code generation standards, and debugging toolchain.

Core Principles

1. Never guess APIs — Check resources/references/ first; no matching doc = does not exist
2. Verify mount path — Class name ≠ eda property name. Always confirm via the mapping table below
3. Verify return types — get() and getAll() on the same class may return different interface types
4. SCH modify ≠ PCB modify — SCH uses class-level modify() method; PCB uses setState_*().done() chain
5. Browser APIs forbidden in main process — No localStorage, window, document; allowed inside iframe only
6. Document type values — SCH=1, PCB=3, FOOTPRINT=4 (PCB is NOT 2)
7. console.log forbidden — Only console.warn and console.error are allowed in generated code

When to Use

Applicable:

• Creating or modifying EasyEDA Pro extension plugins
• Querying API method signatures via resources/ documentation
• Configuring extension.json, locales i18n files, or build processes
• Automating plugin import/debugging via eext-dev-mcp MCP tools

Not applicable:

• General TypeScript/JavaScript questions unrelated to EasyEDA Pro
• Non-EasyEDA Pro EDA tools
• Workspace has no extension.json and user did not request initialization

---

Scenario Quick Reference (Recipes)

When user intent matches a scenario below, read the corresponding recipe first — it contains the complete call chain, step-by-step instructions, common errors, and code examples.

Plugin Scaffolding & Document Info

recipe	scenario
recipes/create_menu_plugin.md	Create a new plugin with menu registration and basic structure
recipes/get_current_document.md	Get current document info (type, UUID, project) — the most common starting point

Document Tree Management (DMT)

recipe	scenario
recipes/dmt_board_management.md	Board management — create/delete/copy boards, get board info
recipes/dmt_editor_control.md	Editor control — open/close/activate documents, split screen, zoom, markers
recipes/dmt_project_management.md	Project/team/folder/workspace management
recipes/dmt_schematic_pcb_management.md	Schematic pages, PCB docs, panels — create/delete/copy/rename

Schematic Operations (SCH)

recipe	scenario
recipes/get_sch_components.md	Get all schematic components (designator, value, package)
recipes/modify_sch_component.md	Modify schematic component properties (designator, position, custom props)
recipes/export_sch_bom.md	Export BOM from schematic (all components with attributes)
recipes/sch_wire_bus_operations.md	Wire and bus operations — create/get/modify wires, get net info
recipes/sch_pin_operations.md	Get component pins — key pitfall: getAllPinsByPrimitiveId vs sch_PrimitivePin
recipes/sch_primitives_bindraw.md	Drawing primitives — arcs, circles, rectangles, polygons, text
recipes/sch_document_operations.md	Save, import changes from PCB, auto-layout, auto-routing
recipes/sch_netlist_operations.md	Netlist operations — get/update netlist
recipes/sch_drc_check.md	Schematic DRC (Design Rule Check)
recipes/sch_event_bindraw.md	Register schematic event callbacks (primitive/mouse events)
recipes/sch_select_control.md	Selection control — get/set selected, cross probe
recipes/sch_manufacture_data.md	Manufacturing data export — BOM file, netlist, PDF, component ordering
recipes/sch_simulation_engine.md	Simulation engine control and SCH utilities

PCB Operations (PCB)

recipe	scenario
recipes/get_pcb_components.md	Get all PCB components (designator, position, layer, rotation)
recipes/modify_pcb_primitive.md	Modify PCB primitives — modify() and setState_*().done() chain
recipes/pcb_net_query.md	Query PCB nets and net classes
recipes/pcb_primitives_bindraw.md	PCB drawing primitives — lines, arcs, vias, pads, fills, text, pour, etc.
recipes/pcb_document_operations.md	Save (needs UUID!), import changes, coordinate conversion, zoom
recipes/pcb_layer_operations.md	Layer operations — visibility, color, lock, copper layer count
recipes/pcb_select_control.md	PCB selection control — get/set selected, cross probe
recipes/pcb_drc_check.md	PCB DRC, net class, differential pair, equal-length group management
recipes/pcb_event_bindraw.md	Register PCB event callbacks (primitive/mouse/net/cross-probe events)
recipes/pcb_manufacture_data.md	Manufacturing data — Gerber, BOM, pick-and-place, PCB/SMT ordering
recipes/pcb_math_polygon.md	Polygon math — boolean operations, area, image-to-polygon

Library Operations (LIB)

recipe	scenario
recipes/lib_device_search.md	Search devices, get device info — canvas UUID ≠ library UUID pitfall
recipes/lib_symbol_footprint.md	Symbol and footprint search/get/preview
recipes/lib_libraries_management.md	Library list, classification, 3D models, CBB modules

System Operations (SYS)

recipe	scenario
recipes/iframe_custom_ui.md	Create custom UI with iframe (data exchange)
recipes/user_dialog_input.md	Get user input via built-in dialogs (input, select, confirm)
recipes/sys_storage_operations.md	Data storage — extension user config (key required!)
recipes/sys_http_request.md	External HTTP requests (cURL)
recipes/sys_file_operations.md	File system — save/read files
recipes/sys_menu_shortcut.md	Header menu and shortcut key management
recipes/sys_notification_message.md	Toast messages, message box, loading/progress bar
recipes/sys_environment_info.md	Runtime environment info — version, theme, language
recipes/sys_i18n_localization.md	Internationalization (i18n) — multi-language support
recipes/sys_window_operations.md	Window, right-click menu, panel control, message bus
recipes/sys_timer_websocket.md	Timer and WebSocket operations
recipes/sys_format_conversion.md	Format conversion — Altium Designer, KiCad import/export
recipes/sys_font_unit_tool.md	Font management, unit conversion (mil), utility tools, logging

---

eda Property Mapping Table

This is the authoritative mapping. Use eda.<property> to access the corresponding class.

DMT (Document Tree)

eda property	Class	Description
eda.dmt_Board	DMT_Board	Board management
eda.dmt_EditorControl	DMT_EditorControl	Editor tab/split-screen control
eda.dmt_Folder	DMT_Folder	Folder management
eda.dmt_Panel	DMT_Panel	Panel management
eda.dmt_Pcb	DMT_Pcb	PCB document management
eda.dmt_Project	DMT_Project	Project management
eda.dmt_Schematic	DMT_Schematic	Schematic document management
eda.dmt_SelectControl	DMT_SelectControl	Current document info (getCurrentDocumentInfo())
eda.dmt_Team	DMT_Team	Team management
eda.dmt_Workspace	DMT_Workspace	Workspace management

SCH (Schematic & Symbol)

eda property	Class	Description
eda.sch_Document	SCH_Document	Save, import changes, auto-layout
eda.sch_Drc	SCH_Drc	Schematic DRC
eda.sch_Event	SCH_Event	Schematic events
eda.sch_ManufactureData	SCH_ManufactureData	Manufacturing data export
eda.sch_Netlist	SCH_Netlist	Netlist operations
eda.sch_Primitive	SCH_Primitive	Unified primitive operations (abstract)
eda.sch_PrimitiveArc	SCH_PrimitiveArc	Arc primitives
eda.sch_PrimitiveAttribute	SCH_PrimitiveAttribute	Attribute primitives
eda.sch_PrimitiveBus	SCH_PrimitiveBus	Bus primitives
eda.sch_PrimitiveCircle	SCH_PrimitiveCircle	Circle primitives
eda.sch_PrimitiveComponent	SCH_PrimitiveComponent	Component primitives (get/create/modify/delete)
eda.sch_PrimitivePin	SCH_PrimitivePin	Pin primitives (symbol editor only)
eda.sch_PrimitivePolygon	SCH_PrimitivePolygon	Polygon primitives
eda.sch_PrimitiveRectangle	SCH_PrimitiveRectangle	Rectangle primitives
eda.sch_PrimitiveText	SCH_PrimitiveText	Text primitives
eda.sch_PrimitiveWire	SCH_PrimitiveWire	Wire primitives
eda.sch_SelectControl	SCH_SelectControl	Selection control
eda.sch_SimulationEngine	SCH_SimulationEngine	Simulation engine
eda.sch_Utils	SCH_Utils	Utilities

PCB (PCB & Footprint)

eda property	Class	Description
eda.pcb_Document	PCB_Document	Save, import changes, coordinate conversion
eda.pcb_Drc	PCB_Drc	PCB DRC
eda.pcb_Event	PCB_Event	PCB events
eda.pcb_Layer	PCB_Layer	Layer operations
eda.pcb_ManufactureData	PCB_ManufactureData	Manufacturing data / Gerber export
eda.pcb_MathPolygon	PCB_MathPolygon	Polygon math utilities
eda.pcb_Net	PCB_Net	Net operations
eda.pcb_Primitive	PCB_Primitive	Unified primitive operations (abstract)
eda.pcb_PrimitiveArc	PCB_PrimitiveArc	Arc primitives
eda.pcb_PrimitiveAttribute	PCB_PrimitiveAttribute	Attribute primitives
eda.pcb_PrimitiveComponent	PCB_PrimitiveComponent	Component primitives (get/create/modify/delete)
eda.pcb_PrimitiveDimension	PCB_PrimitiveDimension	Dimension primitives
eda.pcb_PrimitiveFill	PCB_PrimitiveFill	Fill primitives
eda.pcb_PrimitiveImage	PCB_PrimitiveImage	Image primitives
eda.pcb_PrimitiveLine	PCB_PrimitiveLine	Line primitives
eda.pcb_PrimitiveObject	PCB_PrimitiveObject	Binary embedded objects
eda.pcb_PrimitivePad	PCB_PrimitivePad	Pad primitives
eda.pcb_PrimitivePolyline	PCB_PrimitivePolyline	Polyline primitives
eda.pcb_PrimitivePour	PCB_PrimitivePour	Pour border primitives
eda.pcb_PrimitivePoured	PCB_PrimitivePoured	Pour fill primitives
eda.pcb_PrimitiveRegion	PCB_PrimitiveRegion	Region primitives
eda.pcb_PrimitiveString	PCB_PrimitiveString	Text primitives
eda.pcb_PrimitiveVia	PCB_PrimitiveVia	Via primitives
eda.pcb_SelectControl	PCB_SelectControl	Selection control

LIB (Library)

eda property	Class	Description
eda.lib_3DModel	LIB_3DModel	3D model library
eda.lib_Cbb	LIB_Cbb	Reuse module library
eda.lib_Classification	LIB_Classification	Library classification index
eda.lib_Device	LIB_Device	Device library (search/get devices)
eda.lib_Footprint	LIB_Footprint	Footprint library
eda.lib_LibrariesList	LIB_LibrariesList	Library list
eda.lib_PanelLibrary	LIB_PanelLibrary	Panel library
eda.lib_SelectControl	LIB_SelectControl	Library selection control
eda.lib_Symbol	LIB_Symbol	Symbol library

SYS (System)

eda property	Class	Description
eda.sys_ClientUrl	SYS_ClientUrl	External HTTP requests (cURL)
eda.sys_Dialog	SYS_Dialog	Dialogs (message, input, select, confirm)
eda.sys_Environment	SYS_Environment	Runtime environment info
eda.sys_FileManager	SYS_FileManager	File manager
eda.sys_FileSystem	SYS_FileSystem	File system interaction
eda.sys_FontManager	SYS_FontManager	Font management
eda.sys_FormatConversion	SYS_FormatConversion	Format conversion (Altium/KiCad)
eda.sys_HeaderMenu	SYS_HeaderMenu	Header menu control
eda.sys_I18n	SYS_I18n	Internationalization
eda.sys_IFrame	SYS_IFrame	IFrame windows (custom UI)
eda.sys_LoadingAndProgressBar	SYS_LoadingAndProgressBar	Loading / progress bar
eda.sys_Log	SYS_Log	Logging
eda.sys_Message	SYS_Message	Non-intrusive notifications
eda.sys_MessageBox	SYS_MessageBox	Message box
eda.sys_MessageBus	SYS_MessageBus	Message bus
eda.sys_PanelControl	SYS_PanelControl	Panel control
eda.sys_RightClickMenu	SYS_RightClickMenu	Right-click menu
eda.sys_Setting	SYS_Setting	Settings
eda.sys_ShortcutKey	SYS_ShortcutKey	Shortcut key registration
eda.sys_Storage	SYS_Storage	Storage (extension user config)
eda.sys_Timer	SYS_Timer	Timer
eda.sys_ToastMessage	SYS_ToastMessage	Toast notifications
eda.sys_Tool	SYS_Tool	Utility tools
eda.sys_Unit	SYS_Unit	Unit conversion (mil-based)
eda.sys_WebSocket	SYS_WebSocket	WebSocket
eda.sys_Window	SYS_Window	Window operations

PNL (Panel)

eda property	Class	Description
eda.pnl_Document	PNL_Document	Panel document operations

---

Critical Pitfalls (Must Read)

These are the most common errors. Violating any of these will produce broken code.

1. getCurrentDocumentInfo is on dmt_SelectControl, NOT sch_Document

// ❌ WRONG — does not exist
eda.sch_Document.getCurrentDocumentInfo();

// ✅ CORRECT
const docInfo = await eda.dmt_SelectControl.getCurrentDocumentInfo();

2. SCH modify() vs PCB setState_*().done()

// ❌ SCH: setState_* does NOT commit changes
component.setState_Designator("B2"); // no effect

// ✅ SCH: use class-level modify()
await eda.sch_PrimitiveComponent.modify(primitiveId, { designator: "B2" });

// ✅ PCB: setState_* chain + done() commits
line.setState_StartX(100).setState_StartY(200).done();

3. get() vs getAll() return different interface types

// get() returns ISCH_PrimitiveComponent — may NOT have getState_Designator()
// getAll() returns ISCH_PrimitiveComponent$1 — HAS getState_Designator()
const components = await eda.sch_PrimitiveComponent.getAll();
components[0].getState_Designator(); // ✓ works

4. SCH_Primitive / PCB_Primitive are abstract — no getAllPrimitiveId

// ❌ WRONG — abstract class, no getAllPrimitiveId
eda.sch_Primitive.getAllPrimitiveId();

// ✅ CORRECT — use concrete class
const ids = await eda.sch_PrimitiveComponent.getAllPrimitiveId();

5. openIFrame — no query parameters allowed

// ❌ WRONG
eda.sys_IFrame.openIFrame('/iframe/index.html?mode=add');

// ✅ CORRECT
eda.sys_IFrame.openIFrame('/iframe/index.html', 400, 500, 'my-id', { title: 'Title' });

6. IFrame data passing — window objects are isolated

// ❌ WRONG — main process and iframe window are isolated
(window as any).__data = data;
window.parent.eda; // unnecessary

// ✅ Option A (recommended): use storage
await eda.sys_Storage.setExtensionUserConfig('myKey', data);
// In iframe: const data = await eda.sys_Storage.getExtensionUserConfig('myKey');

// ✅ Option B: use eda directly in iframe (both contexts have access)
// In iframe: const doc = await eda.dmt_SelectControl.getCurrentDocumentInfo();

7. sys_Storage requires a key parameter

// ❌ WRONG — returns undefined
await eda.sys_Storage.getExtensionUserConfig();

// ✅ CORRECT
await eda.sys_Storage.getExtensionUserConfig('stats');

8. showInformationMessage does NOT render HTML

// ❌ WRONG — HTML tags shown as plain text
eda.sys_Dialog.showInformationMessage('<b>Hello</b>');

// ✅ CORRECT — use iframe for HTML content
eda.sys_IFrame.openIFrame('/iframe/result.html', 600, 400);

9. Pins/Pads do NOT have getState_Net

// ❌ WRONG — no getState_Net on pins
pin.getState_Net();

// ✅ SCH nets: get from wires
const wires = await eda.sch_PrimitiveWire.getAll();
wires[0].getState_Net();

// ✅ PCB nets: use pcb_Net
const nets = await eda.pcb_Net.getAll();

10. Canvas UUID ≠ Library UUID

// ❌ WRONG — canvas primitiveId is not a library device UUID
const comp = await eda.sch_PrimitiveComponent.get(id);
comp.getState_Component().uuid; // this is a primitiveId, NOT device UUID

// ✅ CORRECT — use lib_Device.search() to get library device UUID
const results = await eda.lib_Device.search({ keyword: 'STM32' });

11. Menu Title i18n Uses locales/extensionJson/, NOT locales/

// ❌ WRONG — menu titles are NOT translated via locales/en.json
// extension.json: "title": "%myplugin.menu.title%"  ← wrong syntax
// locales/en.json: { "myplugin.menu.title": "My Plugin" }  ← wrong location

// ✅ CORRECT — use plain text title, translate in locales/extensionJson/
// extension.json: "title": "My Plugin"
// locales/extensionJson/en.json: { "My Plugin": "My Plugin" }
// locales/extensionJson/zh-Hans.json: { "My Plugin": "我的插件" }

12. npm Packages Work in iframe, NOT in Main Process

// ❌ WRONG — npm packages that depend on DOM/Node.js APIs won't work in src/
import Chart from 'chart.js'; // fails in EDA sandbox

// ✅ CORRECT — use npm packages in iframe/ code (standard browser context)
// iframe/app.ts: import Chart from 'chart.js'; // works fine

---

API Documentation Structure

resources/
  experience.md                     # All pitfalls and lessons learned (15 items)
  guide/                            # Developer guide (concepts, best practices)
    index.md                        # What is the Extension API
    how-to-start.md                 # Environment setup and first extension
    invoke-apis.md                  # How to call APIs + debugging methods
    extension-json.md               # extension.json configuration reference
    i18n.md                         # Multi-language support
    inline-frame.md                 # IFrame custom UI windows
    error-handling.md               # Error handling and safety mode
    stability.md                    # API versioning and stability policy
    extensions-marketplace.md       # Extensions marketplace guide
    ancillary-projects.md           # Ancillary projects overview
    ancillary-projects/             # Ancillary project details
  references/                       # Complete API reference
    _index.md                       # Master index of all classes, enums, interfaces, types
    _quick-reference.md             # All method signatures for rapid lookup
    classes/                        # 120 class docs
    enums/                          # 62 enum docs
    interfaces/                     # 70 interface docs
    types/                          # 19 type alias docs

How to Look Up API

Recommended decision path:

1. User need is a multi-step scenario (e.g., "export BOM", "create plugin with UI") → find the matching recipes/ file
2. User need is a single API detail (e.g., "what params does modify() take") → read references/classes/<ClassName>.md
3. Need to find which class has a method → search in references/_quick-reference.md
4. Need enum values or interface properties → check references/enums/ or references/interfaces/
5. Need concepts or patterns → read guide/ files

---

Execution Workflow

1. Plan — Understand requirements, confirm target editor (home/sch/pcb) and core functionality
2. Init — If workspace has no extension.json, run project initialization; otherwise skip
3. Recipe — Check if a matching recipe exists in recipes/; if yes, follow its call chain
4. Query — For APIs not covered by recipes, query resources/references/ using the four-step method (find class → verify mount path → confirm signature → verify return interface)
5. Validate — Verify all type signatures are complete with no guesswork; if uncertain, return to Query
6. Confirm — Always present the implementation plan to the user before writing any code. The plan must include: API list, dependencies, data flow, and file changes. Then explicitly ask the user whether to proceed. Do not start code generation until the user confirms
7. Execute — After user confirmation, generate code; each API call corresponds to a verified signature, wrapped in try/catch with proper logging
8. Lint — Run node scripts/lint-eda-api.js src/ to verify EasyEDA Pro API usage; fix any errors before proceeding
9. Check — Check runtime environment constraints; confirm no forbidden operations; verify all headerMenus IDs in extension.json are globally unique across all editor pages; verify menu title translations are in locales/extensionJson/ (not locales/); if violations found, return to Execute to fix
10. Doc — Generate or update README.md and CHANGELOG.md
11. Deploy — Run npm run build; if eext-dev-mcp MCP tools are available, auto-import via dev_plugin; otherwise inform user to manually upload

API Verification Checklist

• Found class doc in resources/references/classes/; confirmed method exists
• Read full method signature; confirmed all parameter types and counts
• Confirmed eda.xxx_YYY property exists (use mapping table above)
• Verified return interface has required methods (checked in references/interfaces/)
• If using getAllPrimitiveId, using a concrete class (not abstract SCH_Primitive/PCB_Primitive)
• Document type checks use correct values: SCH=1, PCB=3, FOOTPRINT=4
• All headerMenus IDs are globally unique across every editor page
• Menu title translations are in locales/extensionJson/, code translations in locales/
• Ran node scripts/lint-eda-api.js src/ with no errors before building

---

Project Initialization

When extension.json does not exist:

git clone https://github.com/easyeda/pro-api-sdk.git <project-name>
cd <project-name>
npm install
npm run build

Runtime Environment Constraints

Requirement	❌ Forbidden	✅ Recommended
Get user input	-	eda.sys_Dialog.showInputDialog()
User selection	-	eda.sys_Dialog.showSelectDialog()
Show message	alert()	eda.sys_Dialog.showInformationMessage()
Confirm action	confirm()	eda.sys_Dialog.showConfirmationMessage()
Toast notification	DOM manipulation	eda.sys_Message.showToastMessage()
Store data	localStorage (main)	eda.sys_Storage.setExtensionUserConfig(key, value)
Custom UI	Manipulate host DOM	eda.sys_IFrame.openIFrame()
Show HTML	showInformationMessage(html)	Must use iframe
Open link	window.open()	eda.sys_Window.open()
IFrame data	window.__xxx / window.parent.eda	sys_Storage or use eda directly in iframe

---

Error Handling and Logging Standards

Logging Rules

Level	API	Usage	Allowed
Warning	console.warn('[PluginName]', ...)	Non-critical: fallback values, empty results, deprecated usage	✅ Yes
Error	console.error('[PluginName]', ...)	Failures: API call failed, data missing, operation aborted	✅ Yes
Debug	console.log(...)	—	❌ Forbidden

• Always prefix with plugin name: [MyPlugin]
• Only console.warn and console.error are allowed — console.log is strictly forbidden

try/catch Rules

1. Every eda.* API call must be wrapped in try/catch
2. Catch blocks must log with console.error and include the error object
3. Group related API calls in a single try/catch when they share a logical operation
4. Provide user-facing feedback on failure via eda.sys_Dialog.showInformationMessage() or eda.sys_Message.showToastMessage()

Standard Code Pattern

const PLUGIN_TAG = '[MyPlugin]';

export async function myFeature() {
  try {
    const docInfo = await eda.dmt_SelectControl.getCurrentDocumentInfo();
    if (!docInfo) {
      console.warn(PLUGIN_TAG, 'No active document found, aborting');
      return;
    }
    // ... business logic
  } catch (err) {
    console.error(PLUGIN_TAG, 'Failed to execute myFeature:', err);
    await eda.sys_Dialog.showInformationMessage('Operation failed. Check console for details.');
  }
}

Defensive Checks

const components = await eda.sch_PrimitiveComponent.getAll();
if (!components || components.length === 0) {
  console.warn(PLUGIN_TAG, 'No components found in current schematic');
  return;
}

---

Plugin Documentation Generation

README.md

After generating plugin code, always create or update README.md:

1. Plugin name and one-line description
2. Features list
3. Supported editors (home/sch/pcb/footprint)
4. Installation — build and import .eext file
5. Usage — menu access
6. Configuration — extension.json fields
7. Dependencies
8. Known limitations

CHANGELOG.md

Follow Keep a Changelog format:

# Changelog

## [1.0.0] - YYYY-MM-DD
### Added
- Initial release with xxx feature

• Record every user-visible change (Added / Changed / Fixed / Removed)
• Update on every code generation or modification session

---

Failure Strategies

Situation	Action
API does not exist	Stop immediately, inform user
Signature uncertain	Stop generation, return to Query step
Workspace not initialized	Prompt user to initialize first
Forbidden DOM API used	Auto-replace with eda.sys_* alternatives
Menu ID conflict	Add plugin-specific prefix; scan all IDs and reject duplicates

References

• Scenario recipes → recipes/ directory
• Quick method signatures → resources/references/_quick-reference.md
• Master API index → resources/references/_index.md
• Common pitfalls → resources/experience.md
• Developer guide → resources/guide/
• Full API reference → resources/references/