# think-light

**Repository Path**: osheyx/think-light

## Basic Information

- **Project Name**: think-light
- **Description**: ThinkLight（思灯）编排仓：多 LLM 编码 Agent 感知信号灯系统的技术方案总纲、ADR、安装脚本与统一命令入口
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/osheyx/think-light
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThinkLight（思灯）完整技术实现方案

> 以嵌入式开发板为终端的**多 LLM 编码 Agent 感知信号灯系统**：板端采集传感器作为现实上下文注入 Agent，板载 RGB 灯 + LCD 实时展示多任务并行状态，主机网关统一接入 Claude Code / Codex / Trae / MiniMax Code / OpenCode / Pi。

## 〇、多仓导航

本项目按「一板 + 多端」拆成独立仓库，各端语言不同、发布节奏不同、依赖不同，一个端坏了不影响其它端：

| 仓库 | 职责 | 状态 |
| --- | --- | --- |
| **[think-light](https://gitee.com/osheyx/think-light)**（本仓） | 编排仓：方案总纲、ADR、硬件文档、安装脚本、统一命令入口 | ✅ |
| [think-light-firmware](https://gitee.com/osheyx/think-light-firmware) | 板端 C 固件：`core/` 跨板通用 + `bsp/` 各板适配 | 🚧 接口契约已定 |
| [think-light-protocol](https://gitee.com/osheyx/think-light-protocol) | 报文**唯一契约来源**：JSON Schema + Rust crate + Python 包 | ✅ |
| [think-light-gateway-rs](https://gitee.com/osheyx/think-light-gateway-rs) | Rust 网关（生产版） | 🚧 结构已定 |
| [think-light-gateway-py](https://gitee.com/osheyx/think-light-gateway-py) | Python 网关（调试版） | 🚧 结构已定 |
| [think-light-dashboard](https://gitee.com/osheyx/think-light-dashboard) | Web 仪表盘前端 | 🚧 结构已定 |
| [think-light-plugins](https://gitee.com/osheyx/think-light-plugins) | 官方插件样例与插件接口说明 | 🚧 接口约定中 |

### 克隆

```bash
# 编排仓 + 全部子仓（子仓以 git submodule 形式挂在 vendor/ 下）
git clone --recursive https://gitee.com/osheyx/think-light.git

# 只克隆编排仓
git clone https://gitee.com/osheyx/think-light.git
cd think-light && git submodule update --init --recursive
```

### 目录约定

```
think-project/
├── think-light/            ① 编排仓（本仓）
├── think-light-firmware/   ② 板端固件
├── think-light-protocol/   ③ 共享协议
├── think-light-gateway-rs/ ④ Rust 网关（生产）
├── think-light-gateway-py/ ⑤ Python 网关（调试）
├── think-light-dashboard/  ⑥ Web 仪表盘
├── think-light-plugins/    ⑦ 插件
├── alios-things/           ⑧ 上游 SDK（第三方，只读）
└── toolchain/              本地工具链缓存（ARM GCC，不进 Git）
```

结构规范全文见 [`docs/architecture/repo-layout.md`](docs/architecture/repo-layout.md)。

### 当前可用命令

`justfile` 定义了完整的命令入口，但**各端实现尚未全部落地**，下表是当前真实可用性：

| 命令 | 状态 | 说明 |
| --- | --- | --- |
| `just` | ✅ | 列出全部命令 |
| `just sync` | ✅ | 拉起子仓（git submodule） |
| `just check-protocol` | ✅ | 校验协议 schema / Rust / Python 三方自洽 |
| `just clean` | ✅ | 清理构建产物 |
| `just doctor` | 🚧 | 待补 `scripts/doctor.sh` |
| `just list-boards` | 🚧 | 待补 `scripts/list-boards.sh` |
| `just build-firmware a10` | 🚧 | 待补 `firmware/build.sh` |
| `just flash a10` | 🚧 | 待补 `firmware/flash.sh` |
| `just run-py` / `just run-rs` | 🚧 | 待网关实现落地 |
| `just test-py` / `just test-rs` | 🚧 | 待测试落地 |
| `just test-firmware` | 🚧 | 待 `tests/run.sh` 落地 |
| `just dashboard` | 🚧 | 待补 `scripts/open-dashboard.sh` |
| `just build-plugins` | 🚧 | 待插件样例落地 |

## 一、方案总览

### 1.1 项目定位

跨硬件可移植的**多LLM编码Agent感知信号灯系统**：以嵌入式开发板为终端，采集板载传感器作为现实上下文，通过WiFi/有线双链路对接主机网关，统一接入Claude Code、Codex、Trae、MiniMaxCode、OpenCode、Pi等多款编码Agent；板载RGB灯+LCD屏实时展示多任务并行状态，支持一键部署、插件化扩展、标准化排障。

### 1.2 核心能力

- 多编码Agent统一接入，一套协议兼容所有工具
- 多任务并行调度，全局状态灯+任务详情屏两级展示
- WiFi MQTT + USB串口双链路主备切换，断连自动降级
- 板载传感器（加速度/光感/接近/麦克风）实时注入Agent上下文
- 硬件抽象层（BSP）隔离，跨开发板移植零业务代码改动
- 一键式部署：固件编译、烧录、网关部署、配置引导全流程自动化
- 插件化扩展，支持自定义规则、新增Agent、新增传输通道

### 1.3 技术栈总表

| 模块 | 技术选型 | 说明 |
| --- | --- | --- |
| 嵌入式MCU固件 | C语言 + AliOS Things/FreeRTOS | 贴近硬件、最小资源占用，跨RTOS可移植 |
| 主机网关（高性能版） | Rust + Tokio + rumqtt + tokio-serial | 零GC、低延迟、高并发，生产环境主力 |
| 主机网关（轻量调试版） | Python + Asyncio + paho-mqtt + pyserial | 快速迭代、调试友好，新Agent优先验证 |
| Web仪表盘 | Rust Leptos + 原生JS | 网关内置一体化部署，实时可视化 |
| 通信协议 | JSON over MQTT / 串口 | 双链路格式完全一致 |
| 构建与交付 | Just + Cargo + arm-none-eabi-gcc | 跨平台统一命令入口 |
| 扩展插件 | WASM（Wasmtime） / Python子进程 | 热加载、沙箱隔离，不修改网关本体 |

---

## 二、分层详细技术设计

### 2.1 嵌入式固件层（ThinkLight Firmware）

#### 2.1.1 分层架构

严格遵循**核心业务与硬件完全解耦**原则，Core层代码跨平台通用，新增硬件仅新增BSP适配。

```
┌───────────────────────────────────────────┐
│  App业务层（Core，只读，跨板通用）          │
│  ├─ 任务池 + Agent调度器                   │
│  ├─ 状态机 + 指示灯聚合逻辑                │
│  ├─ 屏幕渲染管理器（概览/详情）             │
│  ├─ 传感器管理器 + 数据滤波                 │
│  └─ 传输管理器（双链路主备）                │
├───────────────────────────────────────────┤
│  抽象服务层（Core，接口契约永久稳定）        │
│  ├─ tl_sensor_dev.h    传感器抽象          │
│  ├─ tl_indicator.h     指示灯抽象          │
│  ├─ tl_screen_dev.h    屏幕抽象            │
│  ├─ tl_transport.h     传输通道抽象        │
│  └─ tl_sys_hal.h       系统RTOS抽象        │
├───────────────────────────────────────────┤
│  BSP硬件适配层（换板仅修改/新增本层）        │
│  ├─ 板载传感器驱动（I2C/SPI）              │
│  ├─ RGB指示灯PWM/GPIO实现                 │
│  ├─ LCD屏幕驱动                           │
│  ├─ WiFi/USB串口/以太网传输实现            │
│  └─ RTOS系统接口封装（时间/互斥/队列）      │
└───────────────────────────────────────────┘
```

#### 2.1.2 核心抽象接口（稳定契约）

所有接口以C结构体+函数指针实现，业务层仅面向接口编程。

1. **传感器抽象**

```
typedef enum { SENSOR_LIGHT, SENSOR_PROXIMITY, SENSOR_ACCEL, SENSOR_MIC } sensor_type_e;

typedef struct {
    uint64_t ts_ms;
    sensor_type_e type;
    union {
        uint16_t light;
        uint16_t proximity;
        float accel[3];
        int16_t mic_level;
    } val;
} sensor_data_t;

typedef struct {
    const char *name;
    sensor_type_e type;
    int  (*init)(void);
    int  (*read)(sensor_data_t *out);
    int  (*deinit)(void);
    bool is_ready;
} sensor_dev_t;
```

2. **指示灯抽象**

```
typedef enum {
    IND_IDLE, IND_SAMPLING, IND_SEND,
    IND_THINKING, IND_RECV_CMD, IND_ERROR
} indicator_state_e;

typedef struct {
    int (*init)(void);
    int (*set_state)(indicator_state_e state);
    int (*deinit)(void);
} indicator_dev_t;
```

3. **屏幕抽象**

```
typedef struct {
    int (*init)(void);
    int (*render_task_list)(tl_task_t *tasks, uint8_t count, sensor_data_t *sens);
    int (*render_task_detail)(tl_task_t *task, sensor_data_t *sens);
    int (*render_error)(uint8_t error_code);
    int (*clear)(void);
} screen_dev_t;
```

4. **传输通道抽象**

```
typedef void (*recv_cb_t)(const char *payload, size_t len);

typedef struct {
    transport_type_e type;
    int  (*init)(void);
    int  (*send)(const char *payload, size_t len);
    void (*set_recv_cb)(recv_cb_t cb);
    int  (*deinit)(void);
    bool is_online;
} transport_dev_t;
```

#### 2.1.3 核心业务模块

1. **任务池（tl_task_pool）**
   - 固定大小环形队列（默认最大8个并发任务），避免动态内存
   - 任务结构体：`task_id`、`agent_type`、`state`、`progress`、`brief`、`start_ts`
   - 接口：新增、更新、删除、按ID查询、遍历
2. **Agent调度器（tl_agent_scheduler）**
   - 事件驱动：收到下行`task_update`报文即更新任务池
   - 200ms周期调度：
     1. 扫描所有任务，计算全局聚合状态
     2. 调用指示灯接口更新RGB
     3. 调用屏幕管理器刷新当前页面
   - 超时回收：超过30s无更新的任务自动标记为IDLE
3. **全局指示灯聚合算法**（优先级从高到低）
   1. 任意任务ERROR → 红色闪烁
   2. 任意任务THINKING → 黄色慢闪
   3. 任意任务SEND/RECV_CMD → 蓝色闪烁
   4. 全部任务IDLE → 绿色常亮
4. **屏幕管理器**
   - 两种显示模式，按键切换：
     - 概览模式：多行列表展示所有活跃任务+底部常驻传感器数据
     - 详情模式：聚焦单个任务完整信息（Agent类型、状态、进度、摘要）
   - 按键交互：A键切换任务/进入详情，B键返回概览，长按A清空任务池
5. **传输管理器**
   - 双链路并行上报、主备接收
   - WiFi优先策略：WiFi在线则下行仅走MQTT；WiFi断开自动切USB串口；WiFi恢复自动回切
   - 报文去重：通过`msg_id`过滤重复下行指令
   - 心跳保活：每5s上行一次板子状态心跳
6. **传感器管理器**
   - 500ms周期轮询所有板载传感器
   - 简单滑动均值滤波，剔除异常值
   - 维护最新一帧传感器上下文，任务上报时自动携带

#### 2.1.4 资源约束设计

- 静态内存分配，禁止运行时malloc
- JSON报文最大长度256字节，精简字段
- 调度周期200ms，平衡响应速度与功耗
- 固件镜像目标控制在256KB Flash / 64KB RAM以内，适配主流MCU

---

### 2.2 主机网关层（ThinkLight Gateway）

#### 2.2.1 核心定位

终端硬件与LLM Agent之间的中间枢纽：对上统一适配各编码Agent，对下统一管理多块开发板，承担协议转换、任务调度、流量控制、插件托管职责。

提供两个实现版本，**对外协议完全一致，固件端无感切换**：

- Rust高性能版：正式运行、多任务高并发场景
- Python轻量版：新Agent快速验证、调试开发场景

#### 2.2.2 Rust高性能网关（生产版）

基于Tokio异步运行时，零GC、毫秒级延迟，支持数十个任务并发流式输出。

1. **核心模块**

| 模块 | 职责 | 技术依赖 |
| --- | --- | --- |
| 事件总线 EventBus | 全局发布订阅，所有事件统一流 | tokio::sync::broadcast |
| 任务调度器 | 并发控制、队列管理、超时重试、全局限流 | tokio::spawn + 令牌桶 |
| Agent适配器层 | 各编码Agent的API封装，统一接口 | 各官方SDK/HTTP客户端 |
| 传输层 | 串口通信、MQTT客户端、链路健康检测 | tokio-serial、rumqttc |
| 插件引擎 | WASM插件加载、沙箱执行、事件订阅 | wasmtime |
| 配置管理 | TOML配置加载、热重载、校验 | serde、toml |
| 可观测层 | 结构化日志、指标采集、健康检查 | tracing、metrics |
2. **Agent统一标准接口（Trait）**

```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AgentType {
    ClaudeCode, Codex, Trae, MiniMaxCode, OpenCode, Pi, Custom
}

#[async_trait]
pub trait CodeAgentAdapter: Send + Sync {
    fn agent_type(&self) -> AgentType;
    async fn submit_task(&self, prompt: &str, sensor_ctx: Option<&SensorCtx>) -> Result<u32, AgentError>;
    async fn poll_task(&self, task_id: u32) -> Result<TaskUpdate, AgentError>;
    async fn cancel_task(&self, task_id: u32) -> Result<(), AgentError>;
}
```

新增Agent仅需实现该Trait并注册到适配器工厂，核心调度代码零改动。

3. **插件系统**
   - 基于Wasmtime的WebAssembly沙箱，支持Rust/Go/AssemblyScript编译为插件
   - 可订阅总线事件、自定义触发规则、扩展自定义Agent
   - 热加载，无需重启网关

#### 2.2.3 Python轻量网关（调试版）

功能与Rust版1:1对齐，开发效率优先，适合快速验证新Agent原型。

- 基于asyncio异步框架，paho-mqtt + pyserial实现双链路
- 适配器基类统一接口，新增Agent仅需继承基类实现三个方法
- 与Rust版共享完全相同的JSON报文协议，可无缝替换

---

### 2.3 通信协议规范

双链路（WiFi MQTT / USB串口）采用**完全一致的JSON报文格式**，保证传输层切换业务无感。

#### 2.3.1 通用报文头

```
{
  "msg_id": 1001,
  "type": "task_update",
  "ts": 1728000000
}
```

#### 2.3.2 上行报文（板→网关）

| 报文类型 | 触发场景 | 核心字段 |
| --- | --- | --- |
| `sensor_report` | 周期上报传感器数据 | `light`、`proximity`、`accel` |
| `board_heartbeat` | 5s一次保活 | `fw_version`、`heap_free`、`link_status` |
| `key_event` | 按键按下/长按 | `key`、`action` |
| `cmd_ack` | 下行命令执行确认 | `msg_id`、`code`、`msg` |

#### 2.3.3 下行报文（网关→板）

| 报文类型 | 触发场景 | 核心字段 |
| --- | --- | --- |
| `task_update` | Agent任务状态变化 | `task_id`、`agent_type`、`state`、`progress`、`brief` |
| `task_add` | 新增任务 | `task_id`、`agent_type`、`brief` |
| `task_cancel` | 取消任务 | `task_id` |
| `sys_cmd` | 系统控制 | `cmd`（reboot/calibrate/set_brightness等） |

#### 2.3.4 MQTT主题规范

```
thinklight/{board_id}/up/sensor      # 传感器上报
thinklight/{board_id}/up/heartbeat   # 心跳
thinklight/{board_id}/up/event       # 事件
thinklight/{board_id}/down/task      # 任务指令
thinklight/{board_id}/down/sys       # 系统指令
```

---

### 2.4 Web仪表盘层

- 网关内置HTTP服务，无需额外部署
- 核心功能：实时任务列表、全局状态展示、传感器历史曲线、任务提交入口、日志查看、配置管理
- 技术实现：Rust网关采用Leptos服务端渲染 + WebSocket实时推送；Python网关采用FastAPI + 原生JS

---

## 三、一键部署与发布体系

### 3.1 统一工程目录

```
think-light/
├── justfile                    # 跨平台统一命令入口
├── install.sh / install.bat    # 一键安装入口
├── firmware/
│   ├── core/                   # 通用核心代码（只读）
│   ├── bsp/
│   │   ├── a10/                # 当前A10板适配
│   │   ├── esp32/              # 后续移植
│   │   └── template/           # 移植模板
│   └── builder/                # 编译+烧录脚本封装
├── host_gateway/
│   ├── rust_gateway/           # 高性能版
│   └── py_gateway/             # 轻量调试版
├── dashboard/                  # 前端静态资源
├── plugins/                    # 插件目录
├── config/
│   └── config_default.toml     # 默认配置模板
├── scripts/                    # 环境检测、烧录、配置引导脚本
└── docs/                       # 协议、移植、排障文档
```

### 3.2 一键安装流程

`install.sh / install.bat` 全自动化执行以下步骤：

1. 系统检测：识别Windows/macOS/Linux，架构匹配
2. 依赖检查：自动安装缺失工具链（Rust/Python、arm-gcc、烧录工具、MQTT broker）
3. 固件编译：根据选择的目标板子编译对应固件
4. 固件烧录：引导插入USB，一键烧录到开发板
5. 网关编译：编译Rust版或安装Python版依赖
6. 配置引导：交互式生成`config.toml`，配置API密钥、串口、WiFi、并发数
7. 启动验证：输出启动命令，自动验证链路连通性

### 3.3 统一命令入口（Just）

```
just list-boards          # 列出支持的开发板
just build-firmware a10   # 编译指定板子固件
just flash a10            # 烧录固件
just run-rust             # 启动Rust网关
just run-py               # 启动Python网关
just dashboard            # 打开Web仪表盘
just doctor               # 一键健康检查排障
```

### 3.4 版本与升级

- 三版本独立管理：固件版本、网关版本、协议版本
- 协议向后兼容：高版本网关兼容低版本固件
- 固件OTA：支持WiFi无线升级，无需插线
- 网关升级：单二进制文件替换，配置自动迁移

---

## 四、运维排障体系

### 4.1 故障域分层（从下到上）

```
硬件层 → 固件层 → 传输层 → 网关层 → Agent层
```

排障遵循**从下到上定位**原则，逐层排除。

### 4.2 板端可观测设计（无需接电脑也可初判）

1. **红色LED闪烁错误码**
   - 1闪：传感器初始化失败
   - 2闪：WiFi连接失败
   - 3闪：所有传输链路均断开
   - 4闪：内存不足/任务池溢出
   - 5闪：固件异常重启
2. **屏幕错误页**：故障时自动跳转，显示错误码与建议
3. **串口日志**：USB串口输出分级日志（ERROR/WARN/INFO/DEBUG）

### 4.3 网关可观测设计

- 结构化日志：所有事件带trace_id，可串联整条链路
- 核心指标：任务并发数、平均响应延迟、链路在线状态、Agent错误率
- 健康检查接口：`/health` 返回各组件健康状态
- `just doctor` 一键诊断：自动检测串口、MQTT、各Agent连通性、配置合法性

### 4.4 标准排查流程

1. **看板子指示灯**：红灯闪烁按错误码定位硬件/固件/链路问题
2. **看串口日志**：确认报文收发、任务更新是否正常
3. **看网关日志**：确认是否收到上报、是否成功调用Agent
4. **直连测试**：单独调用Agent API，排除服务商侧问题
5. **链路替换**：切换WiFi/串口，排除单链路故障

### 4.5 常见故障速查表

| 现象 | 可能原因 | 排查点 |
| --- | --- | --- |
| 板子红灯常亮不启动 | 供电不足、固件损坏 | 换USB线、重新烧录固件 |
| WiFi连不上 | SSID密码错、信号弱、2.4G/5G不兼容 | 配置重配、靠近路由器 |
| 任务不更新 | 网关未启动、MQTT断开、API密钥错 | 网关日志、Agent连通性测试 |
| 屏幕乱码 | 屏幕驱动不匹配、SPI时序错误 | BSP屏幕驱动配置 |
| 传感器数值为0 | 传感器未初始化、I2C引脚错 | 传感器驱动、硬件接线 |

---

## 五、扩展规范与演进路线

### 5.1 扩展标准范式

| 扩展类型 | 操作路径 | 是否修改核心代码 |
| --- | --- | --- |
| 新增编码Agent | 网关新增适配器文件 + 注册 + 配置 | 否 |
| 新增开发板 | firmware/bsp新增目录 + 实现抽象接口 | 否 |
| 新增传输通道 | 新增transport实现 + 注册到管理器 | 否 |
| 自定义业务规则 | 编写WASM/Python插件 | 否 |
| 新增板载外设 | BSP新增驱动 + 注册到传感器管理器 | 否 |

### 5.2 版本演进路线

- **v1.0 基础版**：单任务单Agent、RGB红绿灯、双链路通信、传感器上报、一键部署
- **v1.1 多任务版**：任务池、多Agent接入、LCD屏幕双模式展示、按键交互
- **v1.2 插件版**：WASM插件系统、自定义规则、多板管理
- **v2.0 分布式版**：多板级联、边缘协同、云端网关部署

---

## 六、开源许可与参与

### License

本仓与全部子仓统一采用 **[MIT](LICENSE)** 协议，© 2026 heyongxian。

### 贡献

改动前请先读 [`AGENTS.md`](AGENTS.md)（项目硬性约定）与 [`docs/architecture/repo-layout.md`](docs/architecture/repo-layout.md)（多仓结构规范）。三条最关键的：

1. **固件 core 层跨板通用**，板子特有代码一律进 `firmware/bsp/<board>/`。
2. **报文格式唯一来源**是 [`think-light-protocol`](https://gitee.com/osheyx/think-light-protocol) 的 `protocol/schema/*.json` —— 改报文先改 schema、再升协议版本、最后改各端实现。
3. **网关新增 Agent = 新增适配器 + 注册 + 配置**，不改调度核心。

提交信息遵循 Conventional Commits（`feat:` `fix:` `docs:` `refactor:` `chore:` `test:`），分支用 `main` / `feat/<scope>` / `fix/<scope>`。

### 相关仓库

| 仓库 | 职责 |
| --- | --- |
| [think-light](https://gitee.com/osheyx/think-light) | 编排仓（本仓） |
| [think-light-firmware](https://gitee.com/osheyx/think-light-firmware) | 板端 C 固件 |
| [think-light-protocol](https://gitee.com/osheyx/think-light-protocol) | 报文契约唯一来源 |
| [think-light-gateway-rs](https://gitee.com/osheyx/think-light-gateway-rs) | Rust 网关（生产版） |
| [think-light-gateway-py](https://gitee.com/osheyx/think-light-gateway-py) | Python 网关（调试版） |
| [think-light-dashboard](https://gitee.com/osheyx/think-light-dashboard) | Web 仪表盘 |
| [think-light-plugins](https://gitee.com/osheyx/think-light-plugins) | 官方插件样例 |