Update proj_man.

Author: Jiu-xiao

docs/basic_coding/core/core-rw.md

@@ -130,6 +130,8 @@ LibXR::STDIO::Printf("Hello, %d", 123);
 
 ## 用例示例
 
+对于数据大小为0的情况，Write会直接返回成功，Read会等待有任何数据可读再返回（阻塞模式下）。
+
 ```cpp
 // 阻塞写入串口，超时为 100ms （默认永远等待）
 WriteOperation op_block(sem, 100);

docs/code_gen/xrobot_inter.md

@@ -11,11 +11,11 @@ sidebar_position: 2
 ## 示例
 
 ```bash
-xr_gen_code_stm32 -i .\.config.yaml -o .\User\app_main.cpp --xrobot
+xr_gen_code_stm32 -i ./.config.yaml -o ./User/app_main.cpp --xrobot
 [INFO] Detected FreeRTOS configuration
 [INFO] FlashLayout is generated and injected, MCU: STM32G431KBU6
-[INFO] Flash layout map written to: .\User\flash_map.hpp
-[INFO] Successfully generated: .\User
+[INFO] Flash layout map written to: ./User/flash_map.hpp
+[INFO] Successfully generated: ./User
 [INFO] Generated header file: app_main.h
 ```
 

docs/proj_man/README.md

@@ -6,40 +6,206 @@ sidebar_position: 7
 
 # 项目管理（XRobot）
 
-本章简要介绍 XRobot 在嵌入式项目中的基本用法，包括模块拉取、配置和主函数生成等。详细的命令说明将在后续页面中分模块展开。
+XRobot 是一套面向嵌入式系统（如 STM32）的自动化代码生成工具，配合模块化硬件抽象层 LibXR 使用。它支持模块仓库管理、参数配置和主函数自动生成等工作，极大提高嵌入式项目的工程组织和开发效率。
 
-## 使用前提
+本章介绍 XRobot 的安装、目录结构、主要功能、命令行工具用法，以及完整的快速上手流程。
 
-确保已通过 pip 或 pipx 安装 `xrobot` 工具：
+---
 
-```bash
-pip install xrobot
-# 或使用 pipx
+## 安装
+
+推荐通过 pipx 安装（支持隔离环境）：
+
+**Windows：**
+```ps
+python -m pip install --user pipx
+python -m pipx ensurepath
 pipx install xrobot
+# 重启终端
 ```
 
-## 基本目录结构
+**Linux：**
+```bash
+sudo apt install pipx
+pipx install xrobot
+pipx ensurepath
+# 重启终端
+```
 
-XRobot 使用约定的目录布局进行模块管理和代码生成：
+**或者使用 pip 安装：**
+```bash
+pip install xrobot
+```
 
+**源码安装：**
 ```bash
+git clone https://github.com/xrobot-org/XRobot.git
+cd XRobot
+pip install .
+```
+
+---
+
+## 目录结构约定
+
+XRobot 推荐如下目录布局进行模块管理和代码生成：
+
+```text
 YourProject/
 ├── Modules/               # 存放模块仓库
 │   └── modules.yaml       # 仓库列表
+│   └── sources.yaml       # （可选）模块源索引
 ├── User/                  # 用户配置与生成输出
 │   ├── xrobot.yaml        # 构造参数配置
 │   └── xrobot_main.hpp    # 自动生成主函数
 ```
 
-## 工具说明
+---
+
+## 功能总览
+
+- **模块仓库拉取与同步**  
+  自动拉取、同步和递归解析模块仓库，保证依赖与版本一致性。
+- **参数自动提取与配置**  
+  自动解析模块头文件参数，生成和管理 YAML 配置文件。
+- **自动主函数生成**  
+  根据配置自动生成 C++ 入口函数 `XRobotMain()`，支持多模块、实例和嵌套结构。
+- **manifest 解析**  
+  解析并格式化模块头文件清单（manifest）。
+- **模块模板快速生成**  
+  一键生成包含 CI 的标准化模块目录。
+- **多源模块管理**  
+  支持本地/远程 YAML 配置和多模块源索引管理。
+
+---
+
+## 命令行工具一览
+
+| 命令 Command        | 说明                             | Description                                        |
+| ------------------- | -------------------------------- | -------------------------------------------------- |
+| `xrobot_gen_main`   | 自动生成 C++ 主函数              | Generate main C++ entry source file                |
+| `xrobot_mod_parser` | 解析模块并打印 manifest 信息     | Parse and show module manifest                     |
+| `xrobot_create_mod` | 快速创建标准化模块目录           | Create a new module folder & header                |
+| `xrobot_init_mod`   | 拉取并递归同步所有模块仓库       | Clone and recursively sync all module repos        |
+| `xrobot_setup`      | 一键初始化工作区和生成主函数     | One-click workspace setup & main function generate |
+| `xrobot_add_mod`    | 添加模块仓库或追加模块实例到配置 | Add repo or append module instance config          |
+| `xrobot_src_man`    | 多源模块仓库管理与索引工具       | Multi-source module repository management utility  |
+
+详细参数和用法见后续章节。
+
+---
+
+## 快速上手（推荐流程）
+
+```bash
+# 1. 一键初始化环境、拉取模块、生成主函数（推荐）
+# 1. One-click initialize workspace, fetch modules, and generate main function (recommended)
+$ xrobot_setup
+Starting XRobot auto-configuration...
+[INFO] Created default Modules/modules.yaml
+Please edit this file; each line should be a full module name like:
+  - xrobot-org/BlinkLED
+  - your-namespace/YourModule@dev
+[INFO] Created default Modules/sources.yaml
+Please configure sources index.yaml for official or custom/private mirrors.
+Default official source already included.
+
+$ xrobot_setup
+Starting XRobot auto-configuration...
+[EXEC] xrobot_init_mod --config Modules/modules.yaml --directory Modules --sources Modules/sources.yaml
+[INFO] Cloning new module: xrobot-org/BlinkLED
+Cloning into 'Modules/BlinkLED'...
+remote: Enumerating objects: 31, done.
+remote: Counting objects: 100% (31/31), done.
+remote: Compressing objects: 100% (21/21), done.
+remote: Total 31 (delta 10), reused 31 (delta 10), pack-reused 0 (from 0)
+Receiving objects: 100% (31/31), 4.43 KiB | 2.22 MiB/s, done.
+Resolving deltas: 100% (10/10), done.
+[SUCCESS] All modules and their dependencies processed.
+[INFO] Created default Modules/CMakeLists.txt: Modules/CMakeLists.txt
+[EXEC] xrobot_gen_main --output User/xrobot_main.hpp
+Discovered modules: BlinkLED
+[INFO] Successfully parsed manifest for BlinkLED
+[INFO] Writing configuration to User/xrobot.yaml
+[SUCCESS] Generated entry file: User/xrobot_main.hpp
+
+All done! Main function generated at: User/xrobot_main.hpp
+
+# 2. 单独拉取/同步模块仓库（可选）
+# 2. Pull or sync module repositories separately (optional)
+$ xrobot_init_mod --config Modules/modules.yaml --directory Modules
+[INFO] Updating module: xrobot-org/BlinkLED
+Already up to date.
+Already on 'master'
+Your branch is up to date with 'origin/master'.
+[SUCCESS] All modules and their dependencies processed.
 
-XRobot 工具集包括以下命令，具体用法见后续子页面：
+# 3. 创建模块
+# 3. Create a module
+$ xrobot_create_mod MySensor --desc "IMU interface module" --hw i2c1
+[OK] Module MySensor generated at Modules/MySensor
 
-- `xrobot_add_mod`：添加模块仓库或模块实例
-- `xrobot_init_mod`：拉取/更新模块仓库
-- `xrobot_gen_main`：生成主函数代码
-- `xrobot_create_mod`：创建模块模板
-- `xrobot_mod_parser`：解析模块头文件中的构造参数
-- `xrobot_setup`：一键生成入口文件和配置
+# 4. 查看模块信息
+# 4. View module information
+$ xrobot_mod_parser --path ./Modules/MySensor/
 
-后续页面将逐个介绍这些命令的详细用法与参数。
+=== Module: MySensor.hpp ===
+Description       : IMU interface module
+
+Constructor Args  :
+Required Hardware : i2c1
+Depends           : None
+
+# 5. 添加模块仓库（如需自定义来源）
+# 5. Add a module repository (custom source, optional)
+$ xrobot_add_mod your-namespace/YourModule@main
+[SUCCESS] Added repo module 'your-namespace/YourModule@main' to Modules/modules.yaml
+
+# 6. 添加模块实例
+# 6. Add a module instance
+$ xrobot_add_mod MySensor
+[SUCCESS] Appended module instance 'MySensor' as id 'MySensor_0' to User/xrobot.yaml
+
+# 7. 查看模块实例
+# 7. View module instances
+$ cat ./User/xrobot.yaml
+global_settings:
+  monitor_sleep_ms: 1000
+modules:
+- name: BlinkLED
+  constructor_args:
+    blink_cycle: 250
+- id: MySensor_0
+  name: MySensor
+  constructor_args: {}
+
+# 8. 重新生成主函数（支持自动扫描和配置）
+# 8. Regenerate main function (auto scan & config supported)
+$ xrobot_gen_main --output User/xrobot_main.hpp
+Discovered modules: BlinkLED, MySensor
+[SUCCESS] Generated entry file: User/xrobot_main.hpp
+
+# 9. 查看主函数
+# 9. View main function
+$ cat ./User/xrobot_main.hpp
+#include "app_framework.hpp"
+#include "libxr.hpp"
+
+// Module headers
+#include "BlinkLED.hpp"
+#include "MySensor.hpp"
+
+static void XRobotMain(LibXR::HardwareContainer &hw) {
+  using namespace LibXR;
+  ApplicationManager appmgr;
+
+  // Auto-generated module instantiations
+  static BlinkLED blinkled(hw, appmgr, 250);
+  static MySensor MySensor_0(hw, appmgr);
+
+  while (true) {
+    appmgr.MonitorAll();
+    Thread::Sleep(1000);
+  }
+}
+```

docs/proj_man/add_mod.md

@@ -6,41 +6,96 @@ sidebar_position: 4
 
 # 添加模块
 
-通过`xrobot_add_mod`工具可以快速添加一个新模块到仓库，或者从仓库中选择一个模块创建实例。
+XRobot 提供了 `xrobot_add_mod` 工具，用于：
 
-## 使用方法
+- **添加远程模块仓库**（添加到 `modules.yaml` 并拉取）
+- **添加模块实例**（添加到 `xrobot.yaml` 并生成代码）
 
-### 添加远程模块到仓库
+---
+
+## 1. 添加远程模块
 
---version可以省略，使用时要确保对应分支存在。
+你可以通过提供模块仓库地址快速添加模块：
 
 ```bash
-$ xrobot_add_mod https://github.com/yourorg/BlinkLED.git --version main
-[SUCCESS] Added repo module 'BlinkLED' to Modules/modules.yaml
+xrobot_add_mod xrobot-org/BlinkLED@master
 ```
 
-然后拉取模块：
+输出示例：
 
 ```bash
-$ xrobot_init_mod
-[INFO] Cloning new module: BlinkLED
+[SUCCESS] Added repo module 'xrobot-org/BlinkLED@master' to Modules/modules.yaml
+```
+
+然后运行初始化命令：
+
+```bash
+xrobot_init_mod
+```
+
+该命令会自动拉取所有模块：
+
+```bash
+[INFO] Cloning new module: xrobot-org/BlinkLED
 Cloning into 'Modules/BlinkLED'...
-remote: Enumerating objects: 22, done.
-remote: Counting objects: 100% (22/22), done.
-remote: Compressing objects: 100% (15/15), done.
-remote: Total 22 (delta 7), reused 22 (delta 7), pack-reused 0 (from 0)
-Receiving objects: 100% (22/22), done.
-Resolving deltas: 100% (7/7), done.
-[SUCCESS] All modules processed
+remote: Enumerating objects: 37, done.
+remote: Counting objects: 100% (37/37), done.
+remote: Compressing objects: 100% (25/25), done.
+remote: Total 37 (delta 11), reused 33 (delta 10), pack-reused 0 (from 0)
+Receiving objects: 100% (37/37), 7.48 KiB | 3.74 MiB/s, done.
+Resolving deltas: 100% (11/11), done.
+Already on 'master'
+Your branch is up to date with 'origin/master'.
+[SUCCESS] All modules and their dependencies processed.
+```
+
+---
+
+## 2. 添加模块实例（生成代码配置）
+
+假设你已拉取 BlinkLED 模块：
+
+```bash
+xrobot_add_mod BlinkLED
 ```
 
-### 创建模块实例
+输出如下：
 
 ```bash
-$ xrobot_add_mod BlinkLED
-[SUCCESS] Appended module instance 'BlinkLED' to User/xrobot.yaml
+[SUCCESS] Appended module instance 'BlinkLED' as id 'BlinkLED_0' to User/xrobot.yaml
+```
+
+此时 `xrobot.yaml` 配置文件中将新增：
 
-# 重新生成代码
-$ xrobot_gen_main
-...
+```yaml
+modules:
+- id: BlinkLED_0
+  name: BlinkLED
+  constructor_args:
+    blink_cycle: 250
 ```
+
+你可以直接运行 `xrobot_gen_main` 生成主函数：
+
+```bash
+xrobot_gen_main
+```
+
+---
+
+## 3. 自定义实例 ID
+
+默认实例 ID 为 `模块名_序号`，如 `BlinkLED_0`，可手动指定：
+
+```bash
+xrobot_add_mod BlinkLED --instance-id myled
+```
+
+---
+
+## 5. 配置文件位置说明
+
+| 配置类型     | 默认路径              | 内容                        |
+|--------------|-----------------------|-----------------------------|
+| 模块仓库列表 | `Modules/modules.yaml` | 存储模块地址/版本信息       |
+| 实例配置文件 | `User/xrobot.yaml`     | 存储模块实例参数和 ID 等信息 |