mi-task/README_INTEGRATION.md

机器狗控制系统集成方案

📋 概述

本文档描述了如何将 single-test 测试模块优雅地集成到 main.py 中，同时保留原本的任务点模式。

🎯 集成目标

1. 保持兼容性：完全保留原有的任务1-5执行流程
2. 增加测试功能：集成子运动函数测试能力
3. 用户友好：提供直观的模式选择界面
4. 灵活启动：支持多种启动方式

🏗️ 架构设计

文件结构

task/
├── main.py                 # 主程序（已修改）
├── start.py                # 启动脚本（新增）
├── config.py               # 配置文件（新增）
├── README_INTEGRATION.md   # 集成说明（本文件）
├── single-test/            # 测试模块目录
│   ├── __init__.py
│   ├── test_main.py
│   ├── test_basic_movements.py
│   ├── test_arc_movements.py
│   ├── test_custom_gait.py
│   ├── test_vision_functions.py
│   ├── test_complex_movements.py
│   └── README.md
└── [其他原有文件...]

核心组件

1. 主程序 (main.py)

• 新增模式选择功能：支持3种运行模式
• 保留原有逻辑：legacy_main() 函数保持原始功能
• 智能导入：自动检测 single-test 模块可用性
• 配置驱动：使用 config.py 管理参数

2. 启动脚本 (start.py)

• 命令行接口：支持参数化启动
• 快速启动：直接启动指定模式
• 帮助系统：提供详细的使用说明

3. 配置文件 (config.py)

• 集中配置：统一管理所有参数
• 分类管理：按功能模块组织配置
• 动态修改：支持运行时配置更新

🚀 使用方法

方法1：交互式菜单（推荐）

# 启动主菜单，选择运行模式
python main.py

显示菜单：

======================================================================
                        机器狗控制系统
======================================================================
🎯 运行模式选择:
  1. 完整任务模式     - 运行完整的任务1-5流程
  2. 测试模式        - 进入子运动函数测试
  3. 交互式测试      - 快速测试单个功能
  0. 退出程序
======================================================================

方法2：命令行启动

# 直接运行完整任务
python start.py -m task

# 直接进入测试模式
python start.py -m test

# 直接进入交互式测试
python start.py -m interactive

# 使用原始模式（兼容旧版）
python start.py -l

# 查看帮助
python start.py -h

方法3：程序调用

# 在其他Python脚本中调用
from main import run_complete_task_mode, run_test_mode, run_interactive_test_mode

# 运行完整任务
run_complete_task_mode()

# 运行测试模式
run_test_mode()

# 运行交互式测试
run_interactive_test_mode()

🔧 三种运行模式

1. 完整任务模式

• 功能：执行完整的任务1-5流程
• 适用场景：正式比赛、完整测试
• 特点：与原始 main.py 行为完全一致

2. 测试模式

• 功能：进入 single-test 主菜单
• 适用场景：功能调试、分模块测试
• 特点：提供完整的测试套件选择

3. 交互式测试模式

• 功能：快速命令行测试界面
• 适用场景：快速验证、单个功能测试
• 特点：输入编号即可执行测试

⚙️ 配置管理

系统配置

SYSTEM_CONFIG = {
    'TIME_SLEEP': 5000,          # 默认等待时间
    'ENABLE_SINGLE_TEST': True,   # 启用测试功能
    'DEFAULT_TEST_OBSERVE': True, # 测试详细输出
    'SAFETY_CHECK': True,         # 安全检查
    'AUTO_STAND_UP': True,        # 自动站立
}

测试配置

TEST_CONFIG = {
    'BASIC_MOVEMENT': {
        'turn_speed': 0.5,        # 转弯速度
        'move_speed': 0.3,        # 移动速度
        'default_distance': 1.0,  # 默认距离
    },
    # ... 其他测试配置
}

使用配置

from config import get_config, update_config

# 获取配置
time_sleep = get_config('SYSTEM', 'TIME_SLEEP', 5000)

# 更新配置
update_config('SYSTEM', 'TIME_SLEEP', 3000)

🛡️ 安全特性

1. 模块检测

• 自动检测 single-test 模块是否可用
• 模块不存在时优雅降级
• 提供明确的错误提示

2. 异常处理

• 每个模式都有独立的异常处理
• 资源清理保证
• 用户友好的错误信息

3. 兼容性保证

• 保留原始 legacy_main() 函数
• 配置文件向后兼容
• 渐进式升级支持

📊 集成优势

1. 无缝集成

• ✅ 保留所有原有功能
• ✅ 新增功能不影响原有逻辑
• ✅ 支持渐进式迁移

2. 用户体验

• ✅ 直观的模式选择界面
• ✅ 多种启动方式
• ✅ 详细的帮助信息

3. 开发友好

• ✅ 模块化设计
• ✅ 配置化管理
• ✅ 易于扩展

4. 运维便利

• ✅ 命令行支持
• ✅ 批处理友好
• ✅ 自动化集成

🔄 迁移指南

从原始版本迁移

1. 备份原始文件

   cp main.py main.py.backup
   

2. 更新文件

   • 替换 main.py 为新版本
   • 添加 start.py 和 config.py
   • 确保 single-test/ 目录存在

3. 验证功能

   # 测试原始功能
   python start.py -l
   
   # 测试新功能
   python start.py -m test
   

自定义配置

1. 修改配置文件

   # config.py
   SYSTEM_CONFIG['TIME_SLEEP'] = 3000  # 修改默认等待时间
   

2. 添加新的测试配置

   TEST_CONFIG['CUSTOM_TEST'] = {
       'param1': 'value1',
       'param2': 'value2',
   }
   

🐛 故障排除

常见问题

1. single-test模块未找到

   警告：single-test模块未找到，测试功能将不可用
   

   • 检查 single-test/ 目录是否存在
   • 确认 single-test/__init__.py 文件存在

2. 配置文件错误

   ModuleNotFoundError: No module named 'config'
   

   • 确认 config.py 文件存在
   • 检查文件语法是否正确

3. 权限问题

   # 给启动脚本添加执行权限
   chmod +x start.py
   

调试模式

启用详细日志：

# 在config.py中修改
SYSTEM_CONFIG['LOG_LEVEL'] = 'DEBUG'
SYSTEM_CONFIG['LOG_TO_FILE'] = True

📈 未来扩展

1. 新增运行模式

• 可以轻松添加新的运行模式
• 修改 print_main_menu() 和 main() 函数

2. 更多测试功能

• 在 single-test/ 目录添加新的测试模块
• 更新 test_main.py 的菜单

3. 高级配置

• 支持配置文件热重载
• 添加配置验证功能
• 支持环境变量配置

📞 技术支持

如果在集成过程中遇到问题，请：

1. 检查本文档的故障排除部分
2. 查看相关模块的README文件
3. 检查日志文件（如果启用）
4. 联系技术支持团队

---

版本: 1.0
更新日期: 2024年12月
维护者: 机器狗控制系统开发团队