From 9a30445ad7fe384cd6aaf14c1a26432e405f0e88 Mon Sep 17 00:00:00 2001
From: xueben <mr_xueben@foxmail.com>
Date: Sun, 18 Jan 2026 23:12:01 +0800
Subject: [PATCH] =?UTF-8?q?New:=20=E4=BC=98=E5=8C=96=E6=A8=A1=E6=8B=9F?=
 =?UTF-8?q?=E5=99=A8=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Why: 当前模拟器文档中对于软硬件模式描述不恰当;
---
 README.md                    |  3 ++-
 docs/simulator.md            | 34 +++++++++++++++++++---------------
 docs/testing.md              |  4 ++--
 simulator/ButtonSimulator.md |  6 +++---
 test/README.md               | 11 ++++++-----
 5 files changed, 32 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 380b774..fb76f4e 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,8 @@ git clone https://github.com/530china/BitsButton.git
 cd BitsButton
 
 # 运行自动化测试用例
-./run_tests.bat  # Windows
+./run_tests.bat              # Windows
+./test/scripts/run_tests.sh  # Linux/macOS
 ```
 
 
diff --git a/docs/simulator.md b/docs/simulator.md
index e847c13..42b04ed 100644
--- a/docs/simulator.md
+++ b/docs/simulator.md
@@ -2,7 +2,7 @@
 
 模拟器是一个用于在PC端模拟硬件按键行为的工具，无需实际硬件即可验证按键检测逻辑，特别适合开发和测试阶段。
 
-> 🔍 **了解更多**：如需深入了解模拟器的技术实现细节，请参阅 [模拟器技术实现文档](../simulator/ButtonSimulator.md)。
+> 🔍 **技术详情**：如需了解模拟器的技术实现细节，请参阅 [模拟器技术实现文档](../simulator/ButtonSimulator.md)。
 
 
 
@@ -105,11 +105,15 @@ python run.py  # 默认以软件模式运行GUI界面
 
 ## 工作原理
 
-模拟器通过适配层与BitsButton库交互，实现Python界面与C库之间的数据交换。
+模拟器通过适配层与BitsButton库交互，实现Python界面与C库之间的数据交换。根据运行模式的不同，交互方式有所区别：
 
-### 数据流向
+### 软件模式数据流向
 
-- 用户界面操作 → 按键状态变化 → 传递给BitsButton库 → 生成事件 → 返回显示
+- 用户界面操作 → 按键状态变化 → 内部模拟处理 → 生成事件 → 返回显示
+
+### 硬件模式数据流向
+
+- 用户界面操作 → 按键状态变化 → 通过动态库 → 传递给BitsButton库 → 生成事件 → 返回显示
 
 适配层主要负责：
 - 将界面的按键操作转换为BitsButton库可识别的格式
@@ -156,7 +160,7 @@ controller.release_button(1)
 
 ## 双模式运行
 
-模拟器支持两种运行模式，以适应不同的开发和测试需求：
+模拟器支持两种运行模式，以满足不同的验证需求：
 
 ### 软件模式
 
@@ -165,13 +169,13 @@ python run.py                 # 默认软件模式
 python run.py --mode software # 显式指定软件模式
 ```
 
-软件模式是一种纯Python实现的模拟方案，具有以下特点：
+软件模式用于验证按键模拟器自身的功能，它完全在Python环境中运行，具有以下特点：
 
 - **无需编译**：直接运行Python代码，无需安装任何编译工具
 - **跨平台兼容**：基于Python和tkinter，可在所有支持Python的平台上运行
 - **快速启动**：无需编译时间，启动速度更快
 - **易于调试**：纯Python代码便于调试和修改
-- **适用场景**：适合算法验证、快速原型开发、功能测试等
+- **适用场景**：适合验证模拟器界面、按键映射、事件显示等模拟器本身的各项功能
 
 ### 硬件模式
 
@@ -179,18 +183,18 @@ python run.py --mode software # 显式指定软件模式
 python run.py --mode hardware # 硬件模式
 ```
 
-硬件模式通过动态库与底层BitsButton库交互，具有以下特点：
+硬件模式用于验证BitsButton库的功能，通过动态库与底层的BitsButton库交互，具有以下特点：
 
-- **真实交互**：与实际的C库进行交互，更接近真实硬件行为
-- **编译要求**：需要安装适当的编译工具链（如GCC、MinGW或Xcode）
-- **性能优势**：底层库的性能表现更接近实际硬件环境
-- **完整功能**：能够测试完整的适配层功能
-- **适用场景**：适合性能测试、完整功能验证、与底层库的集成测试等
+- **库功能验证**：与实际的BitsButton C库进行交互，验证库的各项功能
+- **编译要求**：需要安装适当的编译工具链（如GCC、MinGW或Xcode）来构建动态库
+- **真实交互**：模拟器通过动态库调用BitsButton库的函数，更接近实际硬件环境
+- **PC验证能力**：让开发者可以在PC上验证库的功能，而无需使用实际的嵌入式开发板
+- **适用场景**：适合验证BitsButton库的各种功能、性能测试、功能验证等
 
 ### 模式选择建议
 
-- **初学者或快速验证**：使用软件模式
-- **完整功能测试或性能评估**：使用硬件模式
+- **验证模拟器功能**：使用软件模式
+- **验证BitsButton库功能**：使用硬件模式
 - **CI/自动化测试**：推荐使用软件模式以减少环境依赖
 
 ## 故障排除
diff --git a/docs/testing.md b/docs/testing.md
index 029d90d..349a4c8 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -2,7 +2,7 @@
 
 了解如何使用BitsButton的测试框架来验证您的项目是否正常工作，以及如何添加新的测试用例。
 
-> 🔍 **了解更多**：如需深入了解测试框架的技术实现细节，请参阅 [测试框架技术实现文档](../test/README.md)。
+> 🔍 **技术详情**：如需了解测试框架的技术实现细节，请参阅 [测试框架技术实现文档](../test/README.md)。
 
 
 
@@ -24,7 +24,7 @@
 
 ```bash
 ./run_tests.bat clean  # Windows
-./test/scripts/run_tests.sh clean  # Linux/macOS
+# Linux/macOS不支持clean参数，直接重新运行即可
 ```
 
 ## 测试覆盖范围
diff --git a/simulator/ButtonSimulator.md b/simulator/ButtonSimulator.md
index f66b03a..2a2b092 100644
--- a/simulator/ButtonSimulator.md
+++ b/simulator/ButtonSimulator.md
@@ -67,7 +67,7 @@ python run.py --help            # 查看命令行选项
 
 ### 组件交互
 
-软件模式下，Python模拟器通过适配层与C库交互，实现按键状态模拟和事件回调。硬件模式下，通过动态库与底层硬件通信。
+软件模式下，Python模拟器在纯Python环境中运行，用于验证模拟器自身的界面和功能。硬件模式下，通过动态库与BitsButton库交互，用于验证库的功能。
 
 ## 常见问题解决
 
@@ -173,12 +173,12 @@ python run.py --fix-env
 
 > 提示：修改配置文件后需重启应用生效
 
-## 用户指南参考
+## 用户使用参考
 
 如需了解模拟器的基本使用方法和应用场景，请参阅主项目的用户文档：
 
 - [使用指南](../docs/usage_guide.md)
-- [模拟器使用文档](../docs/simulator.md)
+- [模拟器用户文档](../docs/simulator.md)
 
 ---
 
diff --git a/test/README.md b/test/README.md
index 859c612..d9c45f6 100644
--- a/test/README.md
+++ b/test/README.md
@@ -131,7 +131,7 @@ void exit_low_power_mode(void) {
 
 BitsButton库使用位模式编码按键值：
 - **单击**: `0b010` (0x2)
-- **双击**: `0b01010` (0xA) 
+- **双击**: `0b01010` (0xA)
 - **三连击**: `0b101010` (0x2A)
 - **四连击**: `0b10101010` (0xAA)
 - **五连击**: `0b1010101010` (0x2AA)
@@ -146,13 +146,14 @@ BitsButton库使用位模式编码按键值：
 # Windows
 .\run_tests.bat
 
-# Linux/macOS  
+# Linux/macOS
 ./test/scripts/run_tests.sh
 ```
 
 ### 清理重建
-```bash
-.\run_tests.bat clean
+```
+.\run_tests.bat clean        # Windows
+# Linux/macOS不支持clean参数，直接重新运行即可
 ```
 
 ### 手动构建
@@ -214,7 +215,7 @@ make
 - 检查事件缓冲区状态
 - 验证时序参数设置
 
-## 用户指南参考
+## 用户使用参考
 
 如需了解测试框架的基本使用方法和应用场景，请参阅主项目的用户文档：