# eai-adapters

**Repository Path**: eai-code/eai-adapters

## Basic Information

- **Project Name**: eai-adapters
- **Description**: 工具链适配层 | GCC · EIDE · ARMCC · SDCC · RISC-V · LLVM
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# eai-adapters

> Toolchain adapters layer — 把 YML 项目描述翻译成各嵌入式工具链能直接打开的可编译工程

## 中心思想

**eai-adapters 是一个独立工具**（CLI / MCP server），接收 YML 项目描述 + 工具链选择，输出该工具链能直接打开/编译的工程文件。

**解决的核心问题**：嵌入式工具链碎片化（GCC / EIDE / Keil / SDCC / RISC-V / LLVM 各家工程格式互不兼容），开发者用一份 YML 描述项目，eai-adapters 翻译成任意工具链的工程。

**类比**：编译器后端 —— 同一份 IR（YML）生成不同目标（工具链工程）。

---

## 设计哲学

### 1. FP 纯函数本质

eai-adapters 整体是一个纯函数：`(yml, params) → 工程文件`。相同输入永远产出相同工程，唯一副作用是写磁盘。

### 2. 数据驱动，禁代码耦合

eai-adapters 是**独立工具**，不 import 任何兄弟组件代码（eai-coder / eai-exporters / eai-spec）。组件间靠 **YML schema 契约**（由 eai-spec 定义）连接，不靠 import。

调用方（eai-coder）通过 subprocess 调用 eai-adapters CLI，绝不依赖其代码。

### 3. 单一职责：只生不养

- **生出工程** = eai-adapters
- **养大工程**（编译 / 烧录 / 调试 / 代码生成）= eai-coder

### 4. 工具平等

gcc / eide / armcc / sdcc / riscv / llvm / stm32cubemx 是平行 adapter，CLI 签名统一，无主次之分。

### 5. 黑盒独立

单独 CLI 跑得起来，eai-coder 不启动也能用。不暴露代码 API，只暴露 CLI / MCP 接口。

### 6. 错误显式不吞

YML 字段缺、工具未装、模板缺失等，明确报告 + 非零退出码，绝不静默失败。

---

## 模块架构

eai-adapters 自身分三个**一等公民**模块，靠 IR（内部表示）解耦：

```
                 ┌──────────────────────────────────────┐
YML 输入 ──────▶ │  Parser（解调器）                    │  ← 可变，YML 结构大变只改这里
                 │  - 当前：eai-code 自定义 YML          │
                 │  - 未来：可能接入 Kconfig / Device Tree│
                 └──────────────────────────────────────┘
                              │ IR（内部标准化表示）
                              ▼
                 ┌──────────────────────────────────────┐
                 │  CLI Gateway（对外接口）             │  ← 稳定契约
                 │  - 统一 CLI / MCP 入口               │
                 │  - 参数路由                          │
                 └──────────────────────────────────────┘
                              │ 调度指令
                              ▼
       ┌───────────────────────────────────────────────────┐
       │  Toolchain Adapter（下游工具链创建器，一等公民）   │
       ├───────────────┬───────────────┬───────────────────┤
       │  eide         │ stm32cubemx   │  gcc              │
       │  armcc        │ sdcc          │  riscv / llvm     │
       └───────────────┴───────────────┴───────────────────┘
                              │
                              ▼
                         工程文件（磁盘）
```

### 三模块解耦的好处

- **YML 演化隔离**：YML 结构大变 → 只改 Parser，下游不动
- **工具升级隔离**：CubeMX 从 v6.18 升到 v7 改了 CLI → 只动 stm32cubemx adapter
- **新增工具链**：加一个 adapter 模块，其他不动

### Adapter 的本质：调度器，不是生成器

除少数 adapter（如 gcc 可能直接写 Makefile），大多数 adapter 是**调度外部 CLI 工具**生成工程：

| Adapter | 调度的外部工具 | META 经验沉淀 |
|---|---|---|
| `stm32cubemx` | STM32CubeMX `-q` 无头脚本 | META-053~057（版本号清洗、ASCII 路径、三行脚本、日志覆盖） |
| `eide` | EIDE CLI / EIDE MCP server | TODO |
| `gcc` | 直接生成 Makefile（无需外部工具） | TODO |
| `armcc` | 生成 `.uvprojx`（Keil MDK） | TODO |
| `sdcc` | SDCC 工程文件 | TODO |
| `riscv` / `llvm` | 各自工具链 | TODO |

---

## 输入 / 输出契约

### CLI 调用

```bash
# 标准调用
eai-adapters create \
  --yml project.yml \
  --toolchain eide \
  --out ./out

# dry-run（只看计划不写盘）
eai-adapters create --yml project.yml --toolchain eide --out ./out --dry-run

# 列出支持的 toolchain
eai-adapters list

# 查看 YML 解析结果（调试用）
eai-adapters parse --yml project.yml
```

### 输入

**YML 文件**（必填）：来自 eai-exporters 的项目描述，结构由 eai-spec 定义。
- 当前 schema：`YmlInput` v0.1
- 核心字段：`schema_version` / `project` / `chip` / `peripherals` / `nets` / `code_layout?`
- 注意：YML **不包含 toolchain 选择**，工具链由调用方 CLI 参数传入

**CLI 参数**：
- `--toolchain`（必填）：`gcc | eide | armcc | sdcc | riscv | llvm | stm32cubemx`
- `--out`（必填）：输出目录
- `--dry-run`（可选）：只打印计划
- `--template`（可选）：覆盖默认模板选择
- `--verbose`（可选）：详细日志

### 输出

**磁盘**：完整的可编译工程

| Toolchain | 产物 |
|---|---|
| gcc | `Makefile` + `main.c` + GCC 工程结构 |
| eide | `.eide/eide.yml` + `.vscode/` + EIDE 工程结构 |
| armcc | `.uvprojx`（MDK-ARM Keil 工程） |
| stm32cubemx | 调用 CubeMX 生成完整 HAL 工程（`Core/Inc+Src/` + `Drivers/`） |

**stdout**（JSON 状态，机器可读）：

```json
{
  "status": "ok",
  "path": "./out/myproj",
  "toolchain": "eide",
  "warnings": [],
  "next": "用 VSCode + EIDE 插件打开该目录"
}
```

---

## 与生态其他组件的关系

```
eai-exporters  ──YML──▶  eai-coder  ──YML+params──▶  eai-adapters  ──工程文件──▶ 磁盘
(EDA 导出插件)        (传话 + 描述)                 (翻译 + 调度 CLI 工具)
       │                  │                            │
       └──── eai-spec ────┴────────────────────────────┘
            (定义 YML schema 数据契约)
```

| 组件 | 与 eai-adapters 的关系 |
|---|---|
| **eai-spec** | 提供 YML schema（数据契约，只读引用，不 import 代码） |
| **eai-exporters** | 上游，产出 YML |
| **eai-coder** | 调用方，通过 subprocess 调用 eai-adapters CLI |
| **eai-templates** | 提供 variant 模板素材（如 adapter 需要） |
| **eai-frontend** | 给人类用户提供 UI（包装 eai-adapters CLI） |

---

## 非目标（明确不做什么）

- ❌ 不编译 / 烧录 / 调试（→ eai-coder）
- ❌ 不定义 YML schema（→ eai-spec）
- ❌ 不提供 variant 代码片段库（→ eai-templates）
- ❌ 不 import 兄弟组件代码（保持黑盒）
- ❌ 不做 IDE 集成 UI（→ eai-frontend）

---

## Roadmap

- [x] **v0.1**：中心思想 + 模块架构对齐（本 README）
- [ ] **v0.2**：仓库骨架（三模块目录 + TS 配置）
- [ ] **v0.3**：IR schema 定义 + Parser（eai-code YML → IR）
- [ ] **v0.4**：CLI Gateway 基础（`create` / `list` / `parse` 命令）
- [ ] **v0.5**：第一个 adapter — **stm32cubemx**（已有 META-053~057 兜底踩坑）
- [ ] **v0.6**：eide adapter
- [ ] **v0.7**：gcc adapter
- [ ] **v0.8**：armcc / sdcc / riscv / llvm adapter
- [ ] **v1.0**：全工具链覆盖 + 测试覆盖率 >80%

---

## 关联文档

- 设计哲学总览：本仓库根目录
- eai-coder 调研结论：https://gitee.com/eai-code/eai-coder/blob/main/docs/08-依赖调研结论.md
- 生态蓝图：https://gitee.com/eai-code/eai-coder/blob/main/docs/11-生态蓝图与项目计划.md
- 架构原则：https://gitee.com/eai-code/eai-coder/blob/main/docs/09-架构原则.md
- YML 接口设计：https://gitee.com/eai-code/eai-coder/blob/main/docs/15-代码布局与YML接口设计.md
- 全局 META 规则库：https://gitee.com/eai-code/ai-meta

## Status

Work in progress (设计重启 2026-07-27)

Part of eai-code ecosystem: https://gitee.com/eai-code

## License

Apache-2.0（与 eai-code 生态一致）