> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见工作流

这页提供最常用的实战流程：项目初始化、硬件交互、固件开发、调试与会话管理。

## 新项目启动

<Steps>
  <Step title="创建或切换项目">
    ```txt embedder theme={"system"}
    /project
    ```

    <Frame caption="项目选择界面">
      <img src="https://mintcdn.com/embedder/4y2q1agcuRz3fRND/images/select-project.png?fit=max&auto=format&n=4y2q1agcuRz3fRND&q=85&s=a9be00239cea81ce0616f63c85ec8a36" alt="项目选择对话框，包含搜索框、新建按钮和历史项目" width="1992" height="1656" data-path="images/select-project.png" />
    </Frame>
  </Step>

  <Step title="选择平台">
    从官方目录选择平台，或手动新增。

    <Frame caption="平台选择界面">
      <img src="https://mintcdn.com/embedder/ujO4-sDifSwa2qo6/images/select-platform.png?fit=max&auto=format&n=ujO4-sDifSwa2qo6&q=85&s=a6c3fc150ba41632be86d7a8f4b7f876" alt="平台选择对话框，显示 Nordic nRF9xxx 平台" width="1980" height="1636" data-path="images/select-platform.png" />
    </Frame>

    如需新增平台，输入名称并点击 `+ Add "[platform name]"`，随后上传相关文档。
  </Step>

  <Step title="添加外设">
    选择你要用的外设（I2C/SPI/UART 等）。

    <Frame caption="外设选择界面">
      <img src="https://mintcdn.com/embedder/ujO4-sDifSwa2qo6/images/select-peripherals.png?fit=max&auto=format&n=ujO4-sDifSwa2qo6&q=85&s=5bf9421145a180e0648c9072b476478c" alt="外设选择对话框，显示多厂商组件列表" width="1990" height="1646" data-path="images/select-peripherals.png" />
    </Frame>

    后续可随时再次运行 `/peripheral` 调整配置。
  </Step>

  <Step title="生成项目上下文文件">
    ```txt embedder theme={"system"}
    /init
    ```

    生成 `EMBEDDER.md`，便于后续会话复用约束和命令。
  </Step>
</Steps>

## 硬件交互

### 串口监视器

打开串口侧边栏：

```txt Embedder theme={"system"}
/serial
```

或使用快捷键 `` Ctrl+` ``。

若不希望刷写后自动连接串口，可在提示中写：

```txt Embedder theme={"system"}
> don't auto-connect to serial after flashing
```

你还可以在串口工具栏中用 `[Filter]` 进行 regex 过滤。

<Frame>
  <img src="https://mintcdn.com/embedder/feqpp7Csqgb6FFzf/images/serial_filter.png?fit=max&auto=format&n=feqpp7Csqgb6FFzf&q=85&s=5e518da4c96ca100e44ea8ce95769018" alt="串口过滤器界面，使用正则表达式过滤日志" style={{ maxWidth:"200px" }} width="688" height="1254" data-path="images/serial_filter.png" />
</Frame>

## 固件开发

### 写驱动

```txt Embedder theme={"system"}
> write an I2C driver for the BME280 sensor on I2C1 (SDA=PB7, SCL=PB6).
> include functions for reading temperature, humidity, and pressure.
```

```txt Embedder theme={"system"}
> create a UART driver for GPS module on UART2 at 9600 baud.
> implement a ring buffer for RX and parse NMEA sentences.
```

```txt Embedder theme={"system"}
> implement SPI driver for the SD card module on SPI1.
> include initialization and single block read/write.
```

### 构建与刷写

<Steps>
  <Step title="安装依赖">
    ```txt Embedder theme={"system"}
    > help me install the dependencies for this project
    ```
  </Step>

  <Step title="构建项目">
    ```txt Embedder theme={"system"}
    > build the project
    ```
  </Step>

  <Step title="刷写固件">
    ```txt Embedder theme={"system"}
    > flash the firmware to the device
    ```
  </Step>

  <Step title="构建 + 刷写 + 监控">
    ```txt Embedder theme={"system"}
    > build and flash, then show me the serial output
    ```
  </Step>
</Steps>

## 串口调试

```txt Embedder theme={"system"}
> what's causing this error in the serial output?
```

```txt Embedder theme={"system"}
> the device keeps resetting, analyze the crash dump
```

```txt Embedder theme={"system"}
> add debug prints to trace the initialization sequence
```

## Plan 模式与 Act 模式

* **Act 模式**：可读写和执行命令，适合实现改动
* **Plan 模式**：只读分析，适合调研和方案设计

切换方式：`Shift+Tab`、`/plan`、`/act`

## 文档与上下文

你可以通过 `/console` 上传更多芯片手册、参考文档和外设资料。

<Frame caption="上传文档界面">
  <img src="https://mintcdn.com/embedder/4y2q1agcuRz3fRND/images/console-docs.png?fit=max&auto=format&n=4y2q1agcuRz3fRND&q=85&s=3e8e4a0ae841d2d936c8f3a2c5de982a" alt="Web 控制台中的文档上传区域" width="3016" height="2152" data-path="images/console-docs.png" />
</Frame>

示例：

```txt Embedder theme={"system"}
> what's the maximum I2C clock speed for this sensor?
```

```txt Embedder theme={"system"}
> show me the register map for the accelerometer
```

## Bash 模式

以 `!` 前缀直接执行命令，不经 AI 解释：

```bash theme={"system"}
!ls -la
!make clean
!git status
```

## 串口发送模式

以 `~` 前缀直接向设备串口发送：

```txt embedder theme={"system"}
~help
~reset
~get status
```

## 用 `@` 引用文件/目录

```txt Embedder theme={"system"}
> explain the logic in @src/main.c
```

```txt Embedder theme={"system"}
> what's in @src/drivers/?
```

## 会话管理

```txt Embedder theme={"system"}
/project
/history
/compress
```

## 快速参考

| 场景      | 命令 / 快捷键                               |
| ------- | -------------------------------------- |
| 新项目配置   | `/project` -> `/peripheral` -> `/init` |
| 打开串口    | `/serial` 或 `` Ctrl+` ``               |
| 切换模式    | `Shift+Tab` 或 `/plan` `/act`           |
| 引用文件    | 在提示中输入 `@filename`                     |
| Bash 直连 | `!command`                             |
| 串口发送    | `~message`                             |
| 撤销      | `/undo` 或 `Ctrl+Z`                     |
| 回退      | `/rewind` 或 `Ctrl+Z (2x)`              |
| 帮助      | `/help`                                |