内容
# Telink SDK Builder
[English](README.en.md) | 简体中文
通用、SDK 无关的构建编排工具,让 AI 编程助手(Trae / Claude Desktop / Cursor / Cline 等)通过自然语言调用任意 SDK 仓库的构建脚本。
打包为 **TraeCLI plugin**(含 skill + slash command + MCP server),同时其 **MCP server 是标准协议**,任何支持 MCP 的客户端都能直接接入。也可纯命令行使用,不依赖任何 AI 工具。
## 一键安装
**Trae CLI:**
```bash
trae-cli plugin marketplace add git@github.com:JannLeo/telinksdk-builder-mcp.git
trae-cli plugin install telinksdk-builder
```
**其他 MCP 客户端(Claude Desktop / Cursor / Cline):** 见下方[给非 Trae 工具用](#给非-trae-工具用claude-desktop--cursor--cline--命令行)。
## Demo
在 Trae 里打开任意 Telink SDK 仓库,对话直接说:
```
> /build-init # 一键扫描仓库,自动生成 builder.json
> /build b80_dongle_flash # 编译 B80 dongle flash 固件
```
**`/build-init` 输出**(自动检测,生成配置):
```text
检测结果:Telink eclipse-only (C-type)
构建脚本:scripts/eclipse_headless_build.py
IDE 路径:C:\TelinkIoTStudio
预设(25 个,每个对应真实 Eclipse 配置):
- 8366_dongle -> 8366_dongle_for_8373_km/8366_dongle
- b80_dongle_flash -> B80_Driver_Demo/B80_dongle_flash
- b80_dongle_otp -> B80_Driver_Demo/B80_dongle_otp
- b80b_mouse_flash_sram -> B80B_Driver_Demo/B80b_mouse_flash_sram
- lark_dongle_demo -> TC_PLATFORM_SDK_1211/Lark_Dongle_Demo
... (全覆盖,无截断)
```
**`/build b80_dongle_flash` 输出**(真实编译,产物回传):
```text
✓ build: success (exit=0, 42s)
copied bin: build_variants/B80_Driver_Demo_b80_dongle_flash_20260717.bin (17400 bytes)
```
**`/build info` 输出**(查看配置):
```text
项目:telink_8373_kmd_2.4g_mode_sdk (eclipse)
配置文件:builder.json
参数(5):IdePath / ProjectPath / BuildTarget / WorkspaceDir / OutputDir
预设(25):8366_dongle, b80_dongle_flash, ... , lark_dongle_startup_from_boot
工具链:TelinkIoTStudio.exe, 默认目标 8366_dongle_for_8373_km/8366_dongle
```
## 组成
| 文件 | 作用 |
|------|------|
| `trae_build_runner.py` | 通用构建运行器。读取项目根的 `builder.json`(或旧名 `robin_builder.json`),按 preset / 参数调用配置中指定的构建脚本,收集产物。可独立命令行使用。 |
| `trae_build_mcp.py` | MCP stdio server(零依赖,纯 Python stdlib)。暴露 4 个工具,供任意 MCP 客户端调用。内部委托给 runner。 |
| `trae_builder_schema.json` | `builder.json` 的 JSON Schema,可用于校验/IDE 补全。 |
## 工作原理
1. 任意 SDK 仓库根放一个 `builder.json`,声明:构建脚本路径、参数列表、预设、产物目录。
2. `trae_build_mcp.py` 被 Trae 以 stdio 方式拉起,自动发现当前工作区的 `builder.json`。
3. 在 Trae 对话里说"用 rx_default 预设编译",agent 调用 `build_run` 工具,runner 据此生成命令并执行构建脚本,产物扫描后回传。
换仓库时只要新仓库自带 `builder.json`,同一份 `trae_builder` 工具链直接复用,无需改动。
## 暴露的 MCP 工具
| 工具 | 说明 |
|------|------|
| `build_info` | 显示当前项目的构建配置(参数、预设、产物配置、工具链)。不执行编译。 |
| `build_presets` | 列出 `builder.json` 里定义的预设。 |
| `build_run` | 执行一次构建。可传 `preset` 和/或 `params` 覆盖;`dry_run` 只打印命令不执行。 |
| `build_list` | 列出已收集的构建产物(按 `artifacts.scan_dirs` 和 `max_age_hours` 过滤)。 |
| `serial_list` | 列出本机可用串口(Windows COMx / Linux/macOS /dev/tty*)。需 pyserial。 |
| `serial_capture` | 抓取串口输出(默认 5 秒/200 行),用于烧录后验证固件行为。端口/波特率默认取 `builder.json` 的 `serial` 段;留空自动选第一个串口。agent 拿到日志原文自行判断"功能对不对"(如有没有 `boot ok`/版本号)。需 pyserial。 |
| `flash_info` | 显示 `builder.json` 的 `flash` 段(默认芯片、bdt.exe 路径、超时、是否自动复位)。不调用 bdt。 |
| `flash_run` | 调用 Telink `bdt.exe` 烧录/读写/复位芯片(wf 烧录、rf 读 flash、rst 复位等)。芯片名默认取 `flash.default_chip`;`wf` 不指定 input_file 时自动取 `build_variants` 下最新 `.bin` 产物,实现"编译→烧录"闭环;烧录成功后默认自动 `rst -f` 复位(可关)。 |
## 命令行直接使用(不经过 Trae)
```powershell
# 查看某项目的构建配置
python <BUILDER>/trae_build_runner.py --project <SDK路径> info
# 按预设编译(真实执行)
python <BUILDER>/trae_build_runner.py --project <SDK路径> build --preset rx_default
# 自定义参数 + 超时
python <BUILDER>/trae_build_runner.py --project <SDK路径> build --param Target=tx --param RomType=txrx --timeout 1200
# 仅打印命令不执行
python <BUILDER>/trae_build_runner.py --project <SDK路径> build --preset rx_default --dry-run
# 列出产物
python <BUILDER>/trae_build_runner.py --project <SDK路径> list
# 列出串口(需 pyserial)
python <BUILDER>/trae_build_runner.py --project <SDK路径> serial list
# 抓取串口输出 5 秒(端口/波特率默认取 builder.json 的 serial 段,留空自动选第一个)
python <BUILDER>/trae_build_runner.py --project <SDK路径> serial capture --port COM3 --baud 115200 --duration 5
# 烧录固件(芯片默认取 flash.default_chip;wf 不指定 --input 时自动取最新产物)
python <BUILDER>/trae_build_runner.py --project <SDK路径> flash --chip B80 --command wf --dry-run
python <BUILDER>/trae_build_runner.py --project <SDK路径> flash --chip B80 --command wf
# 读 flash 到文件 / 复位 / 擦除后写
python <BUILDER>/trae_build_runner.py --project <SDK路径> flash --chip B80 --command rf --output dump.bin --size 12k
python <BUILDER>/trae_build_runner.py --project <SDK路径> flash --chip B80 --command rst
python <BUILDER>/trae_build_runner.py --project <SDK路径> flash --chip B80 --command wf --erase --size 512k
```
## 完整闭环:编译 → 烧录 → 看串口
在 Trae 对话里一句话串起整个嵌入式开发流程:
```
> /build b80_dongle_flash # 1. 编译出 bin
> 烧录到 B80 # 2. agent 调 flash_run(wf),自动取最新 bin,烧完自动复位
> 抓 5 秒串口看看有没有 boot ok # 3. agent 调 serial_capture,读 UART 日志判断
```
## 依赖
- **Python 3.8+**
- **构建功能**:零第三方依赖(纯 stdlib)
- **串口抓取**:可选依赖 `pyserial`(`pip install pyserial`),未装时 serial_list/serial_capture 会给出友好提示
- **Eclipse headless 编译**:需对应平台的 Telink IoT Studio / Eclipse CDT
## 注册到 Trae CLI
在 `~/.trae/trae_cli.yaml`(用户级,对所有项目生效)添加:
```yaml
mcp_servers:
- name: trae_builder
type: stdio
command: python
args:
- "<BUILDER>/trae_build_mcp.py"
timeout: 30s
```
或在项目根放 `.mcp.json`(项目级):
```json
{
"mcpServers": {
"trae_builder": {
"type": "stdio",
"command": "python",
"args": ["D:\\work\\workspace\\trae_builder\\trae_build_mcp.py"],
"timeout": 30
}
}
}
```
注册后用 `trae-cli doctor` 检查连接状态;在交互模式用 `/mcp` 查看详情和工具列表。
> **关于 MCP 工具的可见性**:stdio MCP server 是异步加载,会话启动的 `init` 事件里 `mcp_servers` 可能为空(此时握手尚未完成),但通常 1 秒内握手完成,工具即可被 agent 调用。若首轮 prompt 调用 MCP 工具偶发失败,重试或等待片刻即可(详见 trae-cli 文档「首轮调用 MCP 工具失败/第二轮自动恢复」)。本工具链已在 `tc_ble_lite_sdk-1.2.2_allinone` 上实测 `build_info` 与 `build_run` 均可正常返回。
## 在 Trae 里直接编译: `/build` 自定义命令
除 MCP 外,还提供了 `/build` 自定义 prompt command(走 Bash 工具调 runner,不依赖 MCP),作为更直观的入口。
命令文件已放在 `~/.trae/commands/build.md`(用户级,对所有项目生效)。在任意含 `builder.json` 的仓库根目录打开 Trae,输入:
```
/build info # 查看该仓库的构建配置(参数/预设/产物)
/build list # 列出已收集的构建产物
/build rx_default # 按预设 rx_default 编译(真实执行)
/build rx_default --dry-run # 预演,只打印命令不编译
/build build --preset rx_default --param Target=tx # 显式 build 子命令 + 覆盖参数
```
`/build` 会自动用 `${workspaceFolder}` 定位当前仓库,调用 `trae_build_runner.py`,并把结果整理后汇报。
> Windows 终端注意:在 `cmd.exe` 里用 `trae-cli -p "/build ..."` 带空格参数可能被截断;推荐在 VSCode 集成终端( PowerShell )里直接输入 `/build ...`,或用 `trae-cli -p` 时整体加引号并在 PowerShell 下运行。
## 让旧仓库接入: `/build-init` 自动生成 builder.json
旧仓库没有 `builder.json` 时,用 `/build-init` 一键扫描并生成:
```
/build-init # 扫描当前仓库,自动生成 builder.json
/build-init --ide C:\TelinkIoTStudio # 指定 IDE 路径覆盖默认值
```
`/build-init` 调用 `trae_build_init.py`,自动识别常见构建模式:
| 模式 | 识别方式 | 生成内容 |
|------|---------|---------|
| **Telink A 型**(release_sdk_tool) | 找 `tools/release_sdk_tool/compile.bat` | IDE 路径、芯片列表(B80/B80B/tc122x 等)、每芯片一个预设 |
| **Telink B 型**(telink_ble 后处理) | 找 `rom_lib.bat`/`flash_on_rom_lib.bat` + `.cproject` | 从 `.cproject` 提取构建配置名、芯片 |
| **Telink C 型**(纯 Eclipse 工程) | 有 `.cproject` 但无上述脚本 | 从 `.project` 提取真实项目名、`.cproject` 提取所有配置,每工程×配置一个预设,用跨平台 `eclipse_headless_build.py` |
| **Makefile** | 找 `Makefile`/`makefile` | 解析出 target 列表,每个 target 一个预设 |
| **通用脚本** | 找根目录 `build.ps1`/`build.bat`/`build.sh` | 基础配置 |
| **fallback 模板** | 以上均未命中 | 提示用户手填 `build.script.path` |
## 跨平台支持(Windows / Linux / macOS)
- **runner / MCP server / 生成器**:纯 Python stdlib,三平台通用。
- **C 型构建脚本**:`scripts/eclipse_headless_build.py`(纯 Python)三平台通用;在 Windows 找 `TelinkIoTStudio.exe`/`eclipse.exe`,Linux/macOS 找 `eclipse`/`TelinkIoTStudio`。
- **A/B 型**:Windows 下用仓库自带的 `.bat`(保留 Telink 多阶段编排);Linux/macOS 下生成器会自动把构建脚本切换到跨平台的 `eclipse_headless_build.py`,并把 IDE 启动器名去掉 `.exe`。
- **runner 自动选解释器**:`.py`→python/python3,`.sh`→bash,`.ps1`→powershell/pwsh,`.bat`→cmd.exe。
- **依赖**:仅需 Python 3.8+;Eclipse headless 编译还需对应平台的 Telink IoT Studio / Eclipse CDT。
命令文件在 `~/.trae/commands/build-init.md`。也可命令行直接用:
```powershell
python <BUILDER>/trae_build_init.py <仓库路径> --dry-run # 预览不写
python <BUILDER>/trae_build_init.py <仓库路径> # 写入 builder.json
python <BUILDER>/trae_build_init.py <仓库路径> --ide C:\TelinkIoTStudio
```
生成后即可 `/build info` 查看、`/build <预设名>` 编译。若是 fallback 模板,按提示编辑 `builder.json` 补全 `build.script.path` 即可。
## 手动编写 builder.json
也可手写 `builder.json`,参考 `trae_builder_schema.json` 或现有 `tc_ble_lite_sdk-1.2.2_allinone/robin_builder.json`。最小示例:
```json
{
"schema_version": "1.0",
"sdk": { "name": "my-sdk", "type": "make" },
"build": {
"script": { "path": "build.ps1", "interpreter": "powershell.exe" },
"parameters": [
{ "name": "Target", "type": "enum", "enum": ["debug","release"], "default": "release" }
],
"presets": [
{ "name": "dbg", "params": { "Target": "debug" } }
],
"artifacts": { "scan_dirs": ["build"], "name_pattern": "*.bin", "max_age_hours": 168 },
"timeout_seconds": 600
}
}
```
## 给非 Trae 工具用(Claude Desktop / Cursor / Cline / 命令行)
本仓库的 MCP server(`trae_build_mcp.py`)是**标准 MCP stdio 协议**,不依赖 Trae。任何支持 MCP 的客户端都能接入,同样获得 `build_info` / `build_presets` / `build_run` / `build_list` 四个工具。
先 clone 仓库(或下载),记下路径(下面用 `<BUILDER>` 代指 clone 后的 `telinkbuildskill` 目录)。
### Claude Desktop
编辑配置文件:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"trae_builder": {
"command": "python",
"args": ["<BUILDER>/trae_build_mcp.py"]
}
}
}
```
重启 Claude Desktop,对话框会出现 `build_info` 等工具。
### Cursor
在项目根创建 `.cursor/mcp.json`:
```json
{
"mcpServers": {
"trae_builder": {
"command": "python",
"args": ["<BUILDER>/trae_build_mcp.py"]
}
}
}
```
### VSCode(Cline / Continue 等 MCP 扩展)
以 Cline 为例,在其 MCP 设置(通常 `~/.cline/mcp_settings.json` 或扩展设置)加:
```json
{
"mcpServers": {
"trae_builder": {
"command": "python",
"args": ["<BUILDER>/trae_build_mcp.py"]
}
}
}
```
### 任何 MCP 客户端(通用)
stdio 启动命令:`python <BUILDER>/trae_build_mcp.py`,无参数。server 自动发现当前工作区的 `builder.json`。
> 注意:非 Trae 客户端没有 `/build`、`/build-init` 命令和 build skill(那些是 Trae 专用格式),但 MCP 工具完全可用。首次为一个 SDK 仓库生成 `builder.json`,用下面的命令行方式。
### 纯命令行(不依赖任何 AI 客户端)
```bash
# 生成 builder.json(扫描仓库,自动检测构建模式)
python <BUILDER>/trae_build_init.py /path/to/sdk-repo
# 查看配置
python <BUILDER>/trae_build_runner.py --project /path/to/sdk-repo info
# 按预设编译
python <BUILDER>/trae_build_runner.py --project /path/to/sdk-repo build --preset rx_default
# 列出产物
python <BUILDER>/trae_build_runner.py --project /path/to/sdk-repo list
```
## 自测
```powershell
# 直接喂 JSON-RPC 测 MCP server(不依赖 Trae)
python <BUILDER>/trae_build_mcp.py < <BUILDER>/scripts/_mcp_probe_in.json
```
已验证:initialize / tools/list / build_info / build_presets / build_run(dry-run) / build_list / shutdown 全部正常返回。
## 贡献与推广
欢迎 issue / PR。如果你觉得有用,给个 ⭐ 让更多人看到。
**建议在 GitHub 仓库 Settings 里添加 Topics**(提升被搜索到的概率):
`mcp` `mcp-server` `trae-plugin` `embedded` `firmware` `eclipse-cdt` `telink` `sdk-builder` `cross-platform` `ai-coding`
**分享到社区时可用:**
- Trae / Claude / MCP 社区(Discord、GitHub Discussions)
- 嵌入式开发论坛(说明:让 AI 直接编译 Telink/嵌入式 SDK 固件)
- 掘金/知乎等技术博客(配 demo 截图/录屏效果最佳)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器