# Enhanced API Gateway

简体中文 | [English](README.en.md)

这是 **Enhanced API Gateway** 的独立公开源码与发行仓库。它为嘉立创 EDA 专业版提供本地扩展、类型化 Protocol、共享运行时和配套 Bridge，使 MCP/AI 能通过官方公开扩展 API 读取状态并执行受保护的 PCB 操作。

当前发行版为 **1.2.0**。该版本精确锁定 `@jlceda/pro-api-types 0.4.25`，增加 V4 图层、物理叠层、多边形、详细 DRC、实时 DRC、能力证据缓存和同步/Promise 调用适配，同时保留精确目标、源码哈希、代次、执行账本与独立读回保护。

## 组件与版本

| 目录 | 当前版本 | 作用 |
| --- | ---: | --- |
| `gateway-enhanced/` | 1.2.0 | 嘉立创 EDA 专业版扩展，连接本机 Bridge 并执行类型化 RPC |
| `gateway-protocol/` | Protocol 2 / Contract 2.1.0 | 合约、Schema、操作注册表和类型入口 |
| `eda-runtime/` | 2.1.0 / Runtime Schema 2.3.0 | Gateway 共用的读取、计划校验、PCB 操作与约束运行时 |
| `bridge-server/` | 2.0.1 | 本机 WebSocket/HTTP Bridge、连接恢复与有界传输 |

四个目录共同构成可独立克隆、测试和构建的 Gateway 发行源。上层 `easyeda-api-plugin` 可以通过 Git submodule 固定本仓库版本；PCB MCP 与各 Skill 继续由各自仓库管理。

## 数据流

```text
AI / MCP client
      │ typed requests
      ▼
local Bridge server
      │ origin-filtered loopback connection
      ▼
Enhanced API Gateway extension
      │ official EasyEDA Pro extension APIs
      ▼
active EasyEDA project / document
```

Gateway 与 Bridge 会校验工程、窗口、文档和标签页身份。写操作还使用 generation、changeEpoch、sourceHash 和 executionId，避免断线重连、标签页切换或并发修改后把操作落到错误对象上。

## 开发与验证

需要 Node.js 20.17 或更高版本，CI 使用 Node.js 22。

```powershell
npm run bootstrap
npm run version:check
npm test
npm run package:extension
```

完整验证可直接运行：

```powershell
npm run verify
```

扩展安装包输出到 `gateway-enhanced/build/dist/run-api-gateway-enhanced_v<version>.eext`。安装、菜单、连接与故障排查见 `gateway-enhanced/README.md` 和 `gateway-enhanced/FAQ.md`。

## 版本管理

Gateway 使用语义化版本。正式版本标签统一为 `vX.Y.Z`，且必须与根目录 `package.json`、扩展 `package.json`、`extension.json` 和 `components.json` 中的 Gateway 版本完全一致。Protocol、Runtime 与 Bridge 保留独立版本号，并由 `components.json` 记录组合关系。

推送 `vX.Y.Z` 标签后，GitHub Actions 会重新执行版本检查、整栈测试和扩展打包，随后创建 GitHub Release，并附带 `.eext` 与 `SHA256SUMS.txt`。详细规则见 [VERSIONING.md](VERSIONING.md)，版本内容见 [CHANGELOG](gateway-enhanced/CHANGELOG.md)。

## 仓库规则

- 不提交 `.env`、令牌、私钥、用户目录、运行日志、`node_modules` 或构建产物。
- `gateway-protocol/operations.ts` 是操作元数据唯一来源；生成后必须执行完整漂移检查和测试。
- 只调用真实公开的 EasyEDA SDK API。缺失能力在协议和工具层显式报告，不通过任意脚本注入绕过。
- 构建成功只表示源码、协议和自动化测试通过，不等于已在所有嘉立创 EDA 客户端版本完成真实写入验收。

## 许可证与来源

Gateway 基于 EasyEDA 官方 Apache-2.0 扩展工程持续开发。原始许可证保存在 [LICENSE](LICENSE) 和 `gateway-enhanced/LICENSE`；公开发布不改变上游许可证、商标或第三方权利。