For AI：扩展工程初始化指南 AI

本文档是面向 AI 编程助手（智能体） 的自动化初始化指南，例如 Claude Code、OpenCode、QwenCode、GitHub Copilot 等。当你被要求「初始化 / 创建 / 搭建一个新的嘉立创 EDA 专业版扩展工程」时，请严格遵循本文档执行。

如果你是人类开发者，请阅读面向人类的 如何开始 章节；本文档去除了图形界面操作步骤，并假设执行方可以运行终端命令、读写文件系统。

默认前置动作：安装 easyeda-api Skill

执行本文档的完整流程时，默认应当为当前 AI 编程工具安装 easyeda-api Skill（除非用户在确认环节明确拒绝）。该 Skill 内置完整的扩展开发文档、API 参考与用法示例，使 AI 可以直接在本地检索 API 而非联网抓取整站文档，能显著降低开发难度与 token 消耗。安装步骤见下文 3.5 节。

使用时机

当用户的指令与以下意图匹配时，你应该读取本文档并按流程执行：

• 「初始化一个嘉立创 EDA 专业版扩展工程 / 项目」
• 「使用 pro-api-sdk 创建一个新的扩展」
• 「搭建扩展开发环境并生成可导入的扩展包（.eext）」
• 其他需要从零生成一个可构建、可导入的扩展工程的请求

1. 核心背景与硬性约束

请先记住以下事实，它们决定了你的实现方式：

约束	说明
扩展的本质	每一个扩展都是一个独立的 JavaScript 脚本，运行在其独立的作用域链下
语言	遵循 ECMAScript Next 规范即可；推荐使用 TypeScript（默认入口为 /src/index.ts），类型定义来自 @jlceda/pro-api-types
浏览器 API 限制	扩展运行在主线程中，对 DOM、外部请求、本地文件系统等浏览器 API 的调用受到限制，此类需求应使用扩展 API 提供的预定义接口
Node.js 版本	必须不低于 20.17.0（以 SDK 的 package.json 中 engines.node 声明为准；若其它文档中的数值与其不一致，以 SDK 声明为准）
UUID	每个扩展需要一个 32 位字符串形式的唯一标识。使用 pro-api-sdk 时，首次执行 npm run build 会在 extension.json 的 uuid 为空或非法时自动生成并回填，无需手动生成
name 与 UUID 的关系	扩展未被扩展商店收录且未填写 uuid 时，name 会临时充当扩展标识。name 随时可变且可能重名，不要把它当作稳定、唯一的标识来依赖
产物	每次构建会在 build/dist/ 下生成 <name>_v<version>.eext 扩展包，供导入嘉立创 EDA 专业版使用

2. 执行前需要向用户确认的信息

在开始执行前，一次性向用户确认以下内容。不要臆造或擅自猜测这些值：

1. 工程所在目录（若用户未指定，默认使用当前目录；当前目录非空时，应新建一个子目录存放工程）
2. name：扩展名称，仅可包含小写英文字符 a-z、数字 0-9 与中划线 -，长度为 5-30 个字符
3. displayName：展示名称，可以为中文
4. description：一段描述扩展用途的文本
5. publisher：开发者信息
6. license：开源授权协议，未指定时默认 Apache-2.0
7. 工程用途 / 需要实现的初始功能（用于判断是否需要在入口文件中编写示例代码之外的内容）
8. 安装 easyeda-api Skill 的许可：默认会为你当前使用的 AI 编程工具安装 easyeda-api Skill（属于对你 AI 工具配置目录的改动），用于本地检索 API 文档、降低后续开发与调试的 token 消耗；如不希望安装，请在此明确说明。同时请告知你使用的 AI 编程工具类型（如 Claude Code / OpenCode / QwenCode / Codex 等），以便选择正确的安装方式。

用户确认后，再进入下面的执行流程。

3. 执行流程

3.1 检查 Node.js 环境

运行以下命令并核对版本：

node -v
npm -v

• 若 node -v 输出的版本低于 20.17.0，停止并提示用户先安装或切换 Node.js，不要尝试自行安装或升级（可能需要管理员权限）。
• 若命令不存在（command not found），提示用户安装 Node.js 后重试。

3.2 拉取 SDK 工程

在目标目录下执行，二者任选其一：

# 方式 A：git clone（推荐，结果可控）
git clone --depth=1 https://github.com/easyeda/pro-api-sdk.git my-extension

# 方式 A（中国大陆网络）：使用 Gitee 镜像
git clone --depth=1 https://gitee.com/jlceda/pro-api-sdk.git my-extension

# 方式 B：npx 初始化
npx github:easyeda/pro-api-sdk my-extension

注意事项：

• 工程目录名不要包含 空格 或 非 ASCII 字符，以免引发意外问题。
• 完成后必须验证：my-extension 目录下应存在 extension.json、package.json、src/index.ts 等关键文件，否则视为失败并排查。

3.3 安装依赖

cd my-extension
npm install

npm install 会安装依赖库并初始化运行时钩子等自动化配置。若失败，按下表排查：

现象	处理方式
网络超时 / 无法拉取软件包（常见于中国大陆网络）	编辑工程内的 .npmrc，取消注释 registry=https://registry.npmmirror.com 后重试。只允许修改工程内的 .npmrc，不得未经同意修改全局 npm 配置
Windows 下提示 无法加载文件 ...ps1，因为在此系统上禁止运行脚本	先尝试运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（仅对当前用户生效，无需管理员权限）；若仍失败，请用户自行以管理员身份在 PowerShell 中执行 Set-ExecutionPolicy RemoteSigned。AI 不得擅自尝试提权

3.4 配置 extension.json

打开工程根目录下的 extension.json，与用户确认后填写以下字段：

属性	类型	示例	描述
name	string	run-api-gateway	扩展名称，仅可包含小写英文字符 a-z、数字 0-9 与中划线 -，长度为 5-30 个字符
displayName	string	Run API Gateway	展示名称，可以为中文
description	string	为 AI 编程工具提供 WebSocket 网关桥接服务	描述
publisher	string	JLCEDA	开发者信息
license	string	Apache-2.0	开源授权协议
version	string	1.0.0	语义化版本号，格式为 major.minor.patch

关于 uuid 字段：

• 保持为空或非法值即可，首次 npm run build 会自动生成一个合法的 32 位 UUID 并回填到 extension.json。
• 若开发者计划将扩展上架到扩展商店，后续需要按商店流程申请并使用商店签发的官方 UUID 替换自动生成的本地 UUID。

3.5 安装 easyeda-api Skill（默认执行）

开始编写代码之前，默认先为当前 AI 编程工具安装 easyeda-api Skill（源码仓库）。除非用户在 §2 确认环节明确拒绝，否则不要跳过此步。

安装该 Skill 能带来以下收益：

• 内置嘉立创 EDA 专业版扩展开发的结构化 API 文档（含层级索引）、类型信息、用法示例与桥接调试能力，AI 可在本地直接检索；
• 未安装时，AI 只能联网抓取整站文档或凭记忆生成 API 调用代码，token 消耗高、正确率低、返工多；
• 安装后可实现「API 查找 → 代码生成 → 集成调试」一体化，显著降低开发难度与 token 消耗。

安装方式（按你当前所在工具执行；无法确定时直接询问用户）：

# OpenCode：装入 OpenCode 的全局技能目录
npx clawhub@latest install easyeda-api --workdir "$HOME/.config/opencode" --dir skills

对于 Claude Code / Codex / QwenCode 等其它支持 Agent Skills 的工具，请按 easyeda-api 官方说明 将 Skill 安装到对应工具的技能目录（Claude Code：~/.claude/skills/；OpenCode：~/.config/opencode/skills/）。

手动兜底：下载 https://image.lceda.cn/files/easyeda-api.zip 并解压到当前 AI 工具对应的技能目录（解压后应直接看到 SKILL.md，不要多套一层嵌套目录）。

安装后验证：

1. Skill 目录下存在 SKILL.md 等文件；
2. 若当前工具提供技能列表命令（如 OpenCode 的 /skills），确认 easyeda-api 已出现在列表中。

注意事项：

• 该安装会改动用户 AI 工具的用户级配置，须以 §2 中用户的许可为前提；用户拒绝时跳过，并告知不安装将导致后续 API 开发与调试消耗更多 token。
• 若当前环境根本不支持安装 Skill（如网页版对话），应向用户说明损失并建议改用支持 Agent Skills 的工具；无法安装时，再退化为「按需联网查阅官方 API 文档」。
• 若用户后续希望联动 EDA 进行联调（即让 AI 直接操作 / 调试正在运行的嘉立创 EDA 专业版），除本 Skill 外，还必须由用户在 EDA 侧安装 Run API Gateway 扩展。这是一步 GUI 操作，详见 3.9 联动 EDA 联调（可选）。

3.6 编写入口代码

SDK 的默认入口文件为 /src/index.ts。若用户要求实现具体功能，在此文件（或按需拆分的模块）中实现；若用户只是要一个可构建、可导入的骨架工程，保留 SDK 默认模板即可。

• 若用户明确希望使用原生 JavaScript，可将 /src/index.ts 重命名为 /src/index.js，并删除其中所有不符合 JavaScript 语法的内容（如类型标注）。

3.7 构建

npm run build

构建完成后逐项验证：

1. 命令以退出码 0 结束，无编译 / 类型 / ESLint 错误（如有报错，可执行 npm run lint 查看、npm run fix 自动修复）。
2. build/dist/ 下存在 <name>_v<version>.eext 产物文件。
3. extension.json 中的 uuid 已被回填为 32 位十六进制字符串。

构建时会读取工程根目录下的 .edaignore 文件，其语法与 .gitignore 一致，用于控制在构建时被排除在扩展包之外的内容。

3.8 导入扩展（必须由用户完成的 GUI 步骤）

AI 无法代替用户完成图形界面操作。请将 .eext 文件的绝对路径和以下导入指引转述给用户，并等待用户反馈导入结果：

Details

顶部菜单栏 -> 高级 -> 扩展管理器... -> 导入

选择上一步生成的 .eext 文件。

3.9 联动 EDA 联调（可选）

当用户后续提出「让 AI 直接操作 / 联调当前打开的 EDA 窗口」等需求时，需要打通以下链路：

AI 编程工具 → easyeda-api Skill → Bridge Server → Run API Gateway 扩展 → 嘉立创 EDA 专业版

其中 AI 侧组件已在 3.5 安装完毕（easyeda-api Skill，负责提供 API 文档、启动桥接服务并指导 AI 调用），EDA 侧组件 Run API Gateway 必须安装到嘉立创 EDA 专业版内（运行在 EDA 中，负责接收桥接请求并执行代码），此步只能由用户在 EDA 图形界面中完成，AI 负责给出指引并等待结果。

请将以下步骤转述给用户并等待反馈：

1. 获取扩展：Run API Gateway 是已发布的扩展，无需自行构建，从扩展商店获取即可：
   • 扩展广场：https://jlc-ext.com/item/oshwhub/run-api-gateway（或 https://ext.lceda.cn/item/oshwhub/run-api-gateway）
   • 源码仓库（仅供查看 / 二次开发）：https://github.com/easyeda/eext-run-api-gateway
2. 在 EDA 的扩展管理器中找到并安装 / 导入 Run API Gateway 扩展。
3. 在扩展管理器中勾选 允许外部交互 与 显示在顶部菜单。
4. 确认 EDA 顶部菜单出现 API Gateway（包含「重新连接」「停止连接」「切换自动连接状态」「关于...」等菜单项），即表示扩展已正确加载。

安装完成后，AI 依据 easyeda-api Skill 的工作流说明启动桥接、完成连接验证（如健康检查、握手），再开始执行联调任务；首次可让用户从打开 EDA 并保持扩展加载开始。连接失败时，依次检查：OpenCode 等 AI 工具与 Skill 是否可用（/skills）、EDA 扩展是否已加载、EDA 是否已启动，必要时点击 API Gateway 菜单中的「重新连接」。

4. 迭代开发流程

当用户后续提出修改需求时，遵循以下循环：

1. 修改源码（默认入口 /src/index.ts）。
2. 更新 extension.json 中的 version（每次递增 patch，重大变更递增 minor / major）。
3. 重新执行 npm run build。
4. 提示用户重新导入新生成的 .eext 文件（导入路径见 3.8）。

迭代调试期间同样建议保持 easyeda-api Skill 可用（见 3.5），以便本地检索 API、降低 token 消耗。

5. 行为边界（必须遵守）

• 不擅自提权：不得执行需要 sudo / 管理员权限的命令；确有必要时，把命令原样提供给用户，由用户自行执行。
• 不擅自改动全局配置：包括全局 npm registry、用户目录下的 .npmrc、系统环境变量等。
• 不臆造信息：name、displayName、description、publisher、license、版本号等需要用户决策的值，必须向用户确认后再写入。
• 不跳过验证：构建、安装依赖等关键命令执行后，必须检查退出码与产物是否存在，再继续下一步或宣告完成。
• 涉及网络与长时间命令时，先告知用户再执行。

6. 完成后必须向用户汇报

任务结束后，向用户输出以下内容：

1. 工程所在目录与关键文件（extension.json、src/index.ts）。
2. 构建产物 .eext 文件的绝对路径。
3. 导入嘉立创 EDA 专业版的菜单路径。
4. extension.json 中自动回填的 uuid（如已发生回填）。
5. easyeda-api Skill 的安装状态；若已安装，提示用户后续如需联动 EDA 联调，还须按 3.9 在 EDA 中安装 Run API Gateway 扩展（GUI 操作，AI 无法代办）。
6. 后续开发建议：如参考扩展案例（https://github.com/easyeda）、扩展广场（https://jlc-ext.com/）等。

7. 延伸阅读

初始化完成后，可根据用户需求推荐以下本指南内的章节：

• 如何开始：面向人类的完整图文初始化教程
• 扩展配置文件：extension.json 全字段说明
• 调用扩展 API：如何调用编辑器 API
• 多语言支持、内联框架支持、错误处理、接口稳定性
• 辅助项目：pro-api-sdk、pro-api-types、Run API Gateway、easyeda-api-skill 等