# bsp-agent-demo

**Repository Path**: jackieling/bsp-agent-demo

## Basic Information

- **Project Name**: bsp-agent-demo
- **Description**: 公司的 Agent 项目 demo 摸索
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BSP Agent

基于 **Kimi CLI 二次开发**的 BSP（Board Support Package）智能助手 Web 平台。

AI Agent 作为核心，覆盖嵌入式 BSP 开发完整工作流：**SDK 分析 → 智能编译 → 镜像管理 → 烧录 → 自定义驱动**。

---

## 架构概览

```
浏览器（前端 SPA）
  SDK管理 │ 编译 │ 镜像/烧录 │ Web终端(xterm.js)
           │ REST API          │ WebSocket
后端（Web Server）
  BSP REST API ──── Agent Core（Kimi CLI 二开）
  SDK分析模块      编译执行模块      镜像识别模块      PTY伪终端
           │
    服务器 SDK 目录（/mnt/DATA1/APP）
           │
    PostgreSQL（分析结果 / 任务状态 / 镜像索引 / 烧录历史）
```

**技术栈：**
- 后端：Python 3.12 + FastAPI + Kimi CLI（uv 管理依赖）
- 数据库：PostgreSQL 16 + SQLAlchemy 2.0 (asyncpg) + Alembic
- 前端：React 19 + TypeScript + Vite + Tailwind CSS + xterm.js
- 部署：Docker Compose

---

## 快速开始

### 1. 环境准备

```bash
git clone <this-repo>
cd bsp-agent-new

# 复制并填写配置
cp .env.example .env
# 编辑 .env，填入：POSTGRES_PASSWORD、LLM_API_KEY 等
```

### 2. 一键部署

```bash
docker compose up -d
```

访问 `http://<服务器IP>:8080`

### 3. 验证部署

```bash
# 查看服务状态
docker compose ps

# 查看后端日志
docker compose logs -f backend

# 健康检查
curl http://localhost:8080/api/healthz
```

---

## 配置说明

### 必填项

| 变量 | 说明 |
|------|------|
| `POSTGRES_PASSWORD` | PostgreSQL 密码（自定义强密码） |
| `LLM_API_KEY` | LLM API Key（Moonshot / Kimi 平台申请） |

### 可选项

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `LLM_BASE_URL` | `https://api.moonshot.cn/v1` | LLM API 地址（兼容 OpenAI 格式） |
| `LLM_MODEL` | `moonshot-v1-128k` | 使用的模型名 |
| `MAX_CONCURRENT_BUILDS` | `2` | 最大并发编译数 |
| `LOG_LEVEL` | `INFO` | 日志级别 |

### SDK 路径

SDK 路径默认挂载为 `/mnt/DATA1/APP`（宿主机同路径挂载进容器）。  
如需挂载其他位置，修改 `docker-compose.yml` 中 `backend.volumes` 部分。

### 工具链挂载

如果交叉编译工具链安装在 SDK 目录之外，取消注释：
```yaml
# - /usr/local/toolchains:/usr/local/toolchains
# - /opt/gcc-arm-linux:/opt/gcc-arm-linux
```

### 烧录设备映射

如需 USB/串口烧录，取消注释：
```yaml
# devices:
#   - /dev/ttyUSB0:/dev/ttyUSB0
#   - /dev/bus/usb:/dev/bus/usb
```

---

## API 文档

后端 API 文档访问：`http://localhost:8080/bsp/docs`

### BSP API 端点

```
POST   /bsp/api/bsp/sdks/                    登记 SDK
GET    /bsp/api/bsp/sdks/                    SDK 列表
DELETE /bsp/api/bsp/sdks/{id}               删除 SDK
POST   /bsp/api/bsp/sdks/{id}/analyze       触发 SDK 分析（异步）
GET    /bsp/api/bsp/sdks/{id}/analysis      获取分析结果

POST   /bsp/api/bsp/builds/recommend         Agent 推荐编译命令
POST   /bsp/api/bsp/builds/                 确认并启动编译 → taskId
POST   /bsp/api/bsp/builds/{id}/cancel      取消编译
GET    /bsp/api/bsp/builds/                 编译任务列表
GET    /bsp/api/bsp/builds/{id}/images      本次编译产物列表

GET    /bsp/api/bsp/images/                 全部镜像列表

POST   /bsp/api/bsp/flash/recommend          Agent 推荐烧录方案
POST   /bsp/api/bsp/flash/                  确认并启动烧录
GET    /bsp/api/bsp/flash/                  烧录历史

WS     /bsp/api/bsp/ws/terminal/{sessionId}  PTY 终端双向流
```

### Kimi CLI API（继承）

```
GET/WS /api/sessions/...                     Kimi CLI 会话接口
```

---

## 本地开发

### 后端

```bash
cd backend

# 安装依赖（需要 uv）
uv sync

# 配置环境变量
export DATABASE_URL="postgresql+asyncpg://bsp:password@localhost:5432/bsp_agent"
export LLM_API_KEY="your-key"

# 运行数据库迁移
uv run alembic upgrade head

# 启动开发服务器
uv run python -m bsp_agent
```

### 前端

```bash
cd frontend

npm install
npm run dev
```

前端开发服务器默认代理 `/api`、`/ws`、`/bsp` 到后端 `localhost:8000`（需配置 `vite.config.ts`）。

---

## 项目结构

```
bsp-agent-new/
├── backend/
│   ├── src/bsp_agent/
│   │   ├── app.py              # FastAPI 应用（挂载到 Kimi CLI）
│   │   ├── config.py           # 配置管理
│   │   ├── api/                # REST + WebSocket 路由
│   │   │   ├── sdks.py         # SDK 管理 API
│   │   │   ├── builds.py       # 编译 API
│   │   │   ├── images.py       # 镜像 API
│   │   │   ├── flash.py        # 烧录 API
│   │   │   └── terminal.py     # PTY 终端 WebSocket
│   │   ├── core/
│   │   │   └── pty_manager.py  # PTY 会话管理
│   │   ├── db/                 # ORM 模型 + 会话
│   │   ├── models/             # Pydantic 接口模型
│   │   └── tools/              # BSP Agent 工具集
│   │       ├── analyze_sdk.py
│   │       ├── recommend_build_cmd.py
│   │       ├── run_build.py
│   │       ├── detect_images.py
│   │       ├── recommend_flash_cmd.py
│   │       ├── run_flash.py
│   │       └── gen_driver.py
│   ├── alembic/                # DB 迁移脚本
│   ├── pyproject.toml          # uv 依赖声明
│   └── Dockerfile
│
├── frontend/
│   ├── src/
│   │   ├── features/bsp/       # BSP 功能页面
│   │   │   ├── sdk/            # SDK 管理页
│   │   │   ├── build/          # 编译页
│   │   │   ├── images/         # 镜像页
│   │   │   ├── flash/          # 烧录页
│   │   │   └── terminal/       # xterm.js 终端组件
│   │   └── lib/bsp/api.ts      # BSP API 客户端
│   ├── nginx/default.conf      # Nginx 反代配置
│   └── Dockerfile
│
├── docker-compose.yml          # 一键部署
├── .env.example                # 配置模板
└── README.md
```

---

## 验收标准

1. `docker compose up -d` 一键部署，网络 172.28.0.0/16，数据持久化（重启不丢失）
2. 登记真实 SDK 路径并分析，展示构建系统、工具链、板级信息、DTS 清单
3. 选择 SDK 后 Agent 推荐可用编译命令，确认后编译，终端全程实时可见、可取消
4. 编译完成后产物页正确标注镜像文件
5. 选择镜像走完「推荐烧录命令 → 确认 → 终端执行」完整链路
6. Web 终端可直接输入命令与 Shell/Agent 交互

---

## 常见问题

**Q: SDK 分析超时？**  
A: 大型 SDK（如 Yocto）文件数量极多，可增加 `proxy_read_timeout` 或改为后台轮询模式。

**Q: 编译时找不到工具链？**  
A: 在 `docker-compose.yml` 中取消注释工具链挂载行，将工具链路径映射进容器。

**Q: WebSocket 终端连接失败？**  
A: 检查 Nginx 配置中 `Upgrade`/`Connection` 头是否正确透传，参见 `frontend/nginx/default.conf`。

**Q: 如何更换 LLM 模型？**  
A: 修改 `.env` 中的 `LLM_BASE_URL` 和 `LLM_MODEL`，支持任何 OpenAI API 兼容接口。