Update.

Author: Jiu-xiao

docs/about.md

@@ -1,7 +1,7 @@
 ---
 id: about
 title: 关于
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # 关于本项目

docs/basic_coding/README.md

@@ -1,7 +1,7 @@
 ---
 id: basic-coding
 title: 基础编程（libxr）
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # 基础编程（libxr）

docs/code_gen/README.md

@@ -1,7 +1,7 @@
 ---
 id: code-gen
 title: 代码生成（CodeGenerator）
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # 代码生成（CodeGenerator）

docs/code_gen/stm32/can.md

@@ -10,11 +10,11 @@ LibXR 支持标准 CAN 和 CAN FD。在 STM32CubeMX 中需要启用相应的外
 
 ## 示例
 
-第三个参数表示发送队列大小，用于缓冲待发送的数据帧。
+第二个参数表示发送队列大小，用于缓冲待发送的数据帧。
 
 ```cpp
-STM32CAN can1(&hcan1, "can1", 5);
-STM32CANFD fdcan1(&hfdcan1, "fdcan1", 5);
+STM32CAN can1(&hcan1, 5);
+STM32CANFD fdcan1(&hfdcan1, 5);
 ```
 
 ## 配置文件

docs/code_gen/stm32/uart.md

@@ -15,13 +15,13 @@ LibXR 支持两种串口类型：**硬件串口** 和 **USB CDC**。它们均可
 
 ```cpp
 // 硬件串口
-STM32UART usart1(&huart1, usart1_rx_buf, usart1_tx_buf, 5, 5);
+STM32UART usart1(&huart1, usart1_rx_buf, usart1_tx_buf, 5);
 
 // USB CDC（FreeRTOS 或裸机下）
-STM32VirtualUART uart_cdc(hUsbDeviceFS, UserTxBufferFS, UserRxBufferFS, 5, 5);
+STM32VirtualUART uart_cdc(hUsbDeviceFS, UserTxBufferFS, UserRxBufferFS, 5);
 
 // USB CDC（ThreadX + USBX）
-STM32VirtualUART uart_cdc(&hpcd_USB_FS, 2048, 2, 2048, 2, 5, 12, 256);
+STM32VirtualUART uart_cdc(&hpcd_USB_FS, 2048, 2, 2048, 2, 12, 256);
 ```
 
 > 注意：在 **ThreadX 系统** 中，使用 USBX 替代 ST 官方 USB 库，构造函数参数也不同，使用 USB PCD 句柄（如 `&hpcd_USB_FS`）初始化。
@@ -30,12 +30,12 @@ STM32VirtualUART uart_cdc(&hpcd_USB_FS, 2048, 2, 2048, 2, 5, 12, 256);
 
 ```cpp
 // 如果使用硬件串口
-STDIO::read_ = &usart1.read_port_;
-STDIO::write_ = &usart1.write_port_;
+STDIO::read_ = usart1.read_port_;
+STDIO::write_ = usart1.write_port_;
 
 // 如果使用 USB CDC
-STDIO::read_ = &uart_cdc.read_port_;
-STDIO::write_ = &uart_cdc.write_port_;
+STDIO::read_ = uart_cdc.read_port_;
+STDIO::write_ = uart_cdc.write_port_;
 
 // 创建虚拟文件系统
 RamFS ramfs("XRobot");
@@ -63,23 +63,25 @@ terminal_thread.Create(&terminal, terminal.ThreadFun, "terminal", 512,
 terminal_source: usb
 
 # 终端相关配置（可选）
-terminal:
-  RunAsThread: true       # 是否作为线程运行（ThreadX 推荐）
-  ThreadStackDepth: 512   # 线程栈深度
-  ThreadPriority: 3       # 线程优先级（对应 LibXR::Thread::Priority）
+Terminal:
+  READ_BUFF_SIZE: 32      # 终端读取缓冲区大小
+  MAX_LINE_SIZE: 32       # 每行最大字符数
+  MAX_ARG_NUMBER: 5       # 每行最大参数个数
+  MAX_HISTORY_NUMBER: 5   # 历史命令个数
+  RunAsThread: true       # 是否作为线程运行
+  ThreadStackDepth: 1024  # 线程栈深度（仅在线程下有效）
+  ThreadPriority: 3       # 线程优先级（仅在线程下有效）
 
 # 硬件串口配置
 USART:
   usart1:
     tx_buffer_size: 128
     rx_buffer_size: 128
     tx_queue_size: 5
-    rx_queue_size: 5
 
 # USB CDC 配置（FreeRTOS 下有效）
 USB:
   tx_queue_size: 12
-  rx_queue_size: 12
 ```
 
 > USB 的 `UserTxBufferFS` 与 `UserRxBufferFS` 缓冲区仅在使用 **官方 USB 库**（FreeRTOS）时有效。ThreadX + USBX 模式不需要配置这些缓冲。

docs/concept.md

@@ -0,0 +1,86 @@
+---
+id: concept
+title: 设计思想
+sidebar_position: 2
+---
+
+# 设计思想
+
+## `嵌入式系统中，运行时的内存分配是设计缺陷`
+
+在嵌入式系统中，运行时的内存分配应被视为设计缺陷。系统的所有资源应尽可能在构造或初始化阶段就完成分配和配置。这不仅有助于提高系统的可预测性和稳定性，也更容易进行内存使用分析和资源规划。
+
+需要注意的是，这一原则并不意味着禁止使用动态内存分配（如 `malloc`、`new`），而是强调**动态内存分配的时间点**必须在系统的初始化阶段完成。在系统进入主循环或开始任务调度之后，不应再进行新的内存分配操作。否则将引入：
+
+- 未知的延迟（如碎片整理等）
+- 难以追踪的内存泄漏或越界错误
+- 潜在的内存分配失败
+
+换句话说，**“动态分配可以用，但必须在静态时机使用”**。在这种前提下，你甚至可以用一个只出不进的栈来实现内存分配，并非常方便的监视内存使用情况。
+
+## `一切回调/中断都必须是无阻塞的`
+
+回调是跨上下文的执行点，无论来自中断、调度器还是线程之间的异步触发，其职责都应当极度克制。**回调的设计目的不是“处理”，而是“转交”。**
+
+在 LibXR 中，所有回调仅允许执行以下两类操作：
+
+1. **通知线程**：设置状态、释放信号量、发布事件；
+2. **推送数据**：写入无锁队列、缓存结构等预分配数据区。
+
+除此之外的行为一律禁止：
+
+- 阻塞等待（如信号量、锁、睡眠）  
+- 业务逻辑处理或调用上层接口  
+- 动态内存分配  
+- 调用任何不确定时延的函数
+
+## `上下文（thread/isr）必须在回调中显式传递`
+
+- 所有回调统一传入 `bool in_isr` 参数
+- 操作系统封装 API 明确分为 `Api()` / `ApiFromCallback(in_isr)`
+- 用户无需判断当前上下文，只需将 `in_isr` 向上传递
+- 保证所有回调、任务切换、信号交互在 ISR / Thread 两种模式下都能安全运行
+- 永远不需要猜当前是不是在中断运行
+
+## `任何 I/O 操作都必须绑定确定的完成行为`
+
+I/O 操作的重点不是“发出请求”，而是**如何得知它完成了，以及之后如何处理结果**。
+
+LibXR 通过 `Operation` 类型对 I/O 行为进行建模，在操作发起时就绑定好完成后的响应机制：
+
+| 行为模式 | 类型       | 描述                             |
+| -------- | ---------- | -------------------------------- |
+| 回调     | `CALLBACK` | 操作完成后自动触发回调函数       |
+| 阻塞     | `BLOCK`    | 当前任务等待，直到操作完成或超时 |
+| 轮询     | `POLLING`  | 用户主动检查操作是否完成         |
+| 忽略     | `NONE`     | 发起即忘，不等待任何反馈         |
+
+```cpp
+WriteOperation op_cb(callback);     // 异步回调
+WriteOperation op_block(sem, 100);  // 阻塞等待
+WriteOperation op_poll(status);     // 轮询状态
+WriteOperation op_none;             // 忽略结果
+
+uart1.Write("Hello, world!", op_block);
+```
+
+一个没有绑定完成行为的操作，是不可控的。
+
+## `接口中不应出现任何平台相关类型`
+
+使用者不应在任何接口中看到平台相关的结构体或依赖。例如：
+
+- STM32 的 `UART_HandleTypeDef*`
+- ESP-IDF 的 `uart_port_t`
+- Linux 的 `termios`
+- FreeRTOS 的 `TaskHandle_t`、`SemaphoreHandle_t`
+
+这类类型只能存在于平台实现内部，绝不应出现在接口声明、参数或返回值中。
+
+接口必须保持平台无关性，以确保：
+
+- 不同平台间可替换
+- 行为可测试、可模拟
+- 未使用平台代码可裁剪
+
+若平台类型出现在接口中，则该接口不能复用、不可维护，且会导致上层逻辑依赖具体实现。

docs/env_setup/README.md

@@ -1,7 +1,7 @@
 ---
 id: env-setup
 title: 环境配置
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # 环境配置

docs/proj_man/README.md

@@ -1,7 +1,7 @@
 ---
 id: proj-man
 title: 项目管理（XRobot）
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # 项目管理（XRobot）

i18n/en/docusaurus-plugin-content-docs/current/about.md

@@ -1,7 +1,7 @@
 ---
 id: about
 title: About
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # About This Project

i18n/en/docusaurus-plugin-content-docs/current/basic_coding/README.md

@@ -1,7 +1,7 @@
 ---
 id: basic-coding
 title: Basic Programming (libxr)
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Basic Programming (libxr)