# Android ADB Proxy Manager - Cross-Platform Refactoring Plan

## 项目概述

将现有的 `proxy.sh` 脚本重构为支持 Windows、macOS、Linux 多操作系统的跨平台工具，并大幅改进多设备 ADB 支持。

## 当前实现分析

### 发现的问题
- **仅支持macOS**: 使用 `/sbin/ifconfig` 和 macOS 特定命令
- **多设备支持有限**: 基础正则匹配，无交互式设备选择
- **单IP处理**: `proxyhelper()` 在多IP时退出而非处理
- **无Windows/Linux兼容性**: 命令依赖不跨平台

### 核心函数
- `adb:shell:proxy()` - 设备选择逻辑 (11-48行)
- `proxyhelper()` - 基础代理管理 (119-179行)  
- `proxyhelper_multi_devices()` - 增强版本带IP选择 (50-117行)
- 便捷包装函数 - 快速代理控制 (184-198行)

## 实施计划 (6周)

### 阶段1: 跨平台基础 (第1周)

#### 任务1.1: 操作系统检测
- [ ] 实现 `detect_os()` 函数
- [ ] 支持 Linux、macOS、Windows 检测
- [ ] 设置平台特定变量

```bash
# 检测操作系统并设置平台特定命令
detect_os() {
    case "$(uname -s)" in
        Linux*)   OS="linux";;
        Darwin*)  OS="macos";;
        CYGWIN*|MINGW*|MSYS*) OS="windows";;
        *) echo "Unsupported OS"; exit 1;;
    esac
}
```

#### 任务1.2: 跨平台网络接口检测
- [ ] Linux: 使用 `ip route` 或 `hostname -I`
- [ ] macOS: 保持现有 `ifconfig` 方式
- [ ] Windows: 使用 PowerShell `Get-NetIPAddress`

```bash
# 平台特定IP检测
get_local_ips() {
    case "$OS" in
        "linux")
            ip route get 1.1.1.1 | awk '{print $7}' | head -1
            # 或者: hostname -I | tr ' ' '\n' | grep -v '^$'
            ;;
        "macos")  
            ifconfig | sed -En 's/127.0.0.1//;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p'
            ;;
        "windows")
            powershell.exe -Command "Get-NetIPAddress -AddressFamily IPv4 | Where-Object {\$_.IPAddress -ne '127.0.0.1'} | Select-Object -ExpandProperty IPAddress"
            ;;
    esac
}
```

#### 任务1.3: 跨平台命令包装器
- [ ] 实现统一的命令执行接口
- [ ] 处理 Windows PowerShell 命令
- [ ] 统一行计数、文本处理等工具

```bash
# 平台无关命令执行
execute_platform_command() {
    local cmd_type=$1
    shift
    
    case "$cmd_type" in
        "count_lines")
            case "$OS" in
                "windows") powershell.exe -Command "(\$input | Measure-Object -Line).Lines" ;;
                *) wc -l ;;
            esac
            ;;
        "head")
            case "$OS" in
                "windows") powershell.exe -Command "Select-Object -First $1" ;;
                *) head -n "$1" ;;
            esac
            ;;
    esac
}
```

### 阶段2: 增强多设备支持 (第2周)

#### 任务2.1: 交互式设备选择菜单
- [ ] 实现设备列表显示
- [ ] 添加序号选择功能
- [ ] 支持"all"选项执行所有设备
- [ ] 优雅的错误处理

```bash
# 增强设备选择与交互菜单
select_device_interactive() {
    local devices
    devices=$(adb devices | grep -v 'List of devices' | grep 'device$')
    
    if [ -z "$devices" ]; then
        echo "❌ 没有检测到已连接的设备"
        return 1
    fi
    
    local device_count
    device_count=$(echo "$devices" | wc -l | tr -d ' ')
    
    if [ "$device_count" -eq 1 ]; then
        echo "✅ 检测到单个设备，自动选择"
        echo "$devices" | awk '{print $1}'
        return 0
    fi
    
    echo "📱 检测到 $device_count 个设备："
    echo "$devices" | nl -w2 -s') '
    echo
    echo "请选择设备 (1-$device_count), 或输入 'all' 对所有设备执行:"
    read -r choice
    
    if [ "$choice" = "all" ]; then
        echo "all"
    elif [ "$choice" -ge 1 ] 2>/dev/null && [ "$choice" -le "$device_count" ]; then
        echo "$devices" | sed -n "${choice}p" | awk '{print $1}'
    else
        echo "❌ 无效选择"
        return 1
    fi
}
```

#### 任务2.2: 批量设备操作
- [ ] 支持对所有设备执行命令
- [ ] 实现进度指示器
- [ ] 添加设备操作日志

```bash
# 在多个设备上执行命令
execute_on_devices() {
    local command=$1
    local target_devices=$2
    
    if [ "$target_devices" = "all" ]; then
        local devices
        devices=$(adb devices | grep -v 'List of devices' | grep 'device$' | awk '{print $1}')
        
        echo "$devices" | while read -r device; do
            echo "🔄 执行于设备 $device: $command"
            adb -s "$device" shell "$command"
            echo "---"
        done
    else
        echo "🔄 执行于设备 $target_devices: $command"
        adb -s "$target_devices" shell "$command"
    fi
}
```

#### 任务2.3: 设备过滤和搜索
- [ ] 按设备型号过滤
- [ ] 按产品名称过滤  
- [ ] 正则表达式匹配
- [ ] 设备详细信息显示

```bash
# 高级设备过滤
filter_devices() {
    local filter_type=$1
    local filter_value=$2
    
    case "$filter_type" in
        "model")
            adb devices -l | grep "model:$filter_value" | awk '{print $1}'
            ;;
        "product") 
            adb devices -l | grep "product:$filter_value" | awk '{print $1}'
            ;;
        "regex")
            adb devices | grep -v 'List of devices' | grep 'device$' | grep "$filter_value" | awk '{print $1}'
            ;;
        *)
            adb devices | grep -v 'List of devices' | grep 'device$' | awk '{print $1}'
            ;;
    esac
}
```

### 阶段3: 增强代理管理 (第3周)

#### 任务3.1: 智能IP选择与验证
- [ ] 实现IP地址验证
- [ ] 自动网络接口检测
- [ ] 交互式IP选择界面
- [ ] 记住用户选择

```bash
# 增强IP选择与验证
select_proxy_ip() {
    local port=${1:-$CHARLES_PROXY_PORT}
    local ips
    ips=$(get_local_ips)
    
    if [ -z "$ips" ]; then
        echo "❌ 无法获取本机IP地址"
        return 1
    fi
    
    local ip_count
    ip_count=$(echo "$ips" | wc -l | tr -d ' ')
    
    if [ "$ip_count" -eq 1 ]; then
        echo "$ips:$port"
        return 0
    fi
    
    echo "🌐 检测到多个网络接口："
    echo "$ips" | nl -w2 -s') '
    echo
    echo "请选择要使用的IP地址 (1-$ip_count):"
    read -r choice
    
    if [ "$choice" -ge 1 ] 2>/dev/null && [ "$choice" -le "$ip_count" ]; then
        local selected_ip
        selected_ip=$(echo "$ips" | sed -n "${choice}p")
        echo "$selected_ip:$port"
    else
        echo "❌ 无效选择"
        return 1
    fi
}
```

#### 任务3.2: 代理验证和测试
- [ ] 代理连接测试
- [ ] 网络可达性检查
- [ ] 代理状态验证
- [ ] 错误诊断

```bash
# 验证代理连接
validate_proxy() {
    local proxy_address=$1
    local device=$2
    
    echo "🔍 验证代理连接: $proxy_address"
    
    # 测试代理连接
    if command -v curl >/dev/null 2>&1; then
        if curl -x "$proxy_address" --connect-timeout 5 -s http://httpbin.org/ip >/dev/null 2>&1; then
            echo "✅ 代理连接测试成功"
            return 0
        else
            echo "⚠️  代理连接测试失败，但仍将设置"
        fi
    fi
    
    return 0
}
```

### 阶段4: 现代CLI界面 (第4周)

#### 任务4.1: 改进帮助系统
- [ ] 全面的使用说明
- [ ] 示例命令
- [ ] 参数说明
- [ ] 故障排除指南

```bash
# 增强帮助系统
show_help() {
    cat << EOF
🚀 Android ADB Proxy Manager v2.0

用法:
  proxy <command> [options]

设备选择:
  -d, --device <id>      指定设备ID
  -a, --all              对所有设备执行
  -f, --filter <type:value> 按条件过滤设备
      类型: model, product, regex

代理命令:
  set [ip] [port]        设置代理 (默认: 自动IP:8888)
  get                    获取当前代理设置
  clear                  清除代理设置
  status                 显示代理状态和连接测试
  
预设代理:
  charles                启用Charles代理 (端口8888)
  proxyman               启用Proxyman代理 (端口9090)
  
设备管理:
  devices                列出所有连接的设备
  device-info            显示设备详细信息
  
示例:
  proxy set                          # 交互式设置代理
  proxy set 192.168.1.100 8080      # 指定IP和端口
  proxy get --all                   # 获取所有设备的代理设置
  proxy charles --device emulator-5554  # 为指定设备设置Charles代理
  
支持的操作系统: Windows, macOS, Linux
EOF
}
```

#### 任务4.2: 配置管理
- [ ] 配置文件支持
- [ ] 用户偏好设置
- [ ] 默认值管理
- [ ] 配置导入导出

```bash
# 配置文件支持
PROXY_CONFIG_FILE="$HOME/.android_proxy_config"

save_config() {
    local key=$1
    local value=$2
    
    # 如果配置文件不存在则创建
    touch "$PROXY_CONFIG_FILE"
    
    # 更新或添加配置
    if grep -q "^$key=" "$PROXY_CONFIG_FILE"; then
        case "$OS" in
            "macos") sed -i '' "s/^$key=.*/$key=$value/" "$PROXY_CONFIG_FILE" ;;
            *) sed -i "s/^$key=.*/$key=$value/" "$PROXY_CONFIG_FILE" ;;
        esac
    else
        echo "$key=$value" >> "$PROXY_CONFIG_FILE"
    fi
}

load_config() {
    local key=$1
    
    if [ -f "$PROXY_CONFIG_FILE" ]; then
        grep "^$key=" "$PROXY_CONFIG_FILE" | cut -d'=' -f2
    fi
}
```

### 阶段5: 高级功能 (第5周)

#### 任务5.1: 代理配置文件
- [ ] 代理配置文件创建
- [ ] 配置文件管理
- [ ] 快速切换代理
- [ ] 配置文件列表

```bash
# 代理配置文件管理
create_proxy_profile() {
    local profile_name=$1
    local ip=$2
    local port=$3
    
    save_config "profile_${profile_name}_ip" "$ip"
    save_config "profile_${profile_name}_port" "$port"
    echo "✅ 代理配置文件 '$profile_name' 已保存"
}

use_proxy_profile() {
    local profile_name=$1
    local device=$2
    
    local ip
    local port
    ip=$(load_config "profile_${profile_name}_ip")
    port=$(load_config "profile_${profile_name}_port")
    
    if [ -n "$ip" ] && [ -n "$port" ]; then
        set_proxy "$ip" "$port" "$device"
    else
        echo "❌ 代理配置文件 '$profile_name' 不存在"
        return 1
    fi
}
```

#### 任务5.2: 日志记录和历史
- [ ] 操作日志记录
- [ ] 历史命令查看
- [ ] 错误日志管理
- [ ] 日志清理

```bash
# 操作日志记录
PROXY_LOG_FILE="$HOME/.android_proxy.log"

log_operation() {
    local operation=$1
    local device=$2
    local details=$3
    local timestamp
    timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    
    echo "[$timestamp] $operation - Device: $device - $details" >> "$PROXY_LOG_FILE"
}
```

### 阶段6: 测试和文档 (第6周)

#### 任务6.1: 自动化测试
- [ ] 跨平台兼容性测试
- [ ] 功能测试套件
- [ ] 错误处理测试
- [ ] 性能测试

```bash
# 跨平台测试套件
run_tests() {
    echo "🧪 运行跨平台测试套件..."
    
    # 测试操作系统检测
    detect_os
    echo "✅ OS检测: $OS"
    
    # 测试IP检测  
    local ips
    ips=$(get_local_ips)
    if [ -n "$ips" ]; then
        echo "✅ IP检测: 成功"
    else
        echo "❌ IP检测: 失败"
    fi
    
    # 测试ADB连接
    if command -v adb >/dev/null 2>&1; then
        echo "✅ ADB: 已安装"
        local device_count
        device_count=$(adb devices | grep -v 'List of devices' | grep 'device$' | wc -l)
        echo "📱 检测到 $device_count 个设备"
    else
        echo "❌ ADB: 未安装"
    fi
}
```

#### 任务6.2: 文档完善
- [ ] 用户手册编写
- [ ] 安装指南
- [ ] 故障排除指南
- [ ] 示例和最佳实践

## 实施优先级矩阵

| 功能 | 优先级 | 复杂度 | 影响力 |
|------|-------|--------|--------|
| 操作系统检测 | 高 | 低 | 高 |
| 跨平台IP检测 | 高 | 中 | 高 |
| 交互式设备选择 | 高 | 中 | 高 |
| 批量设备操作 | 中 | 中 | 高 |
| 代理验证 | 中 | 低 | 中 |
| 配置文件 | 低 | 低 | 中 |
| 增强帮助系统 | 低 | 低 | 低 |

## 成功标准

### ✅ 跨平台兼容性
- [ ] Windows、macOS、Linux支持
- [ ] 原生命令集成
- [ ] 无外部依赖

### ✅ 卓越的多设备支持
- [ ] 交互式设备选择菜单
- [ ] 批量操作支持  
- [ ] 设备过滤和搜索

### ✅ 增强的用户体验
- [ ] 清晰的错误消息
- [ ] 进度指示器
- [ ] 配置持久化

### ✅ 健壮的代理管理
- [ ] 连接验证
- [ ] 配置文件管理
- [ ] 操作日志记录

## 技术债务和改进机会

### 当前技术债务
- [ ] 硬编码的macOS命令路径
- [ ] 缺乏错误处理
- [ ] 重复代码
- [ ] 无配置管理

### 改进机会
- [ ] 添加单元测试
- [ ] 实现配置验证
- [ ] 增加性能监控
- [ ] 支持代理链

## 风险评估

### 技术风险
- **Windows兼容性**: PowerShell命令执行可能有差异
- **ADB版本差异**: 不同版本ADB输出格式可能不同
- **网络接口检测**: 不同系统网络配置复杂性

### 缓解策略
- **广泛测试**: 在所有目标平台上测试
- **兼容性层**: 创建统一的命令抽象层
- **渐进式发布**: 分阶段发布功能

## 下一步行动

1. **立即开始**: 阶段1的操作系统检测
2. **并行开发**: 可以同时进行UI设计和核心功能开发
3. **早期测试**: 每个阶段完成后立即测试
4. **用户反馈**: 在阶段4后收集用户反馈

## 项目时间线

```
Week 1: [████████████████████████████████] 跨平台基础
Week 2: [████████████████████████████████] 多设备支持
Week 3: [████████████████████████████████] 代理管理
Week 4: [████████████████████████████████] CLI界面
Week 5: [████████████████████████████████] 高级功能
Week 6: [████████████████████████████████] 测试文档
```

## 资源需求

- **开发时间**: 6周 (约120小时)
- **测试环境**: Windows 10+, macOS 10.14+, Ubuntu 18.04+
- **测试设备**: 至少2-3个Android设备或模拟器
- **工具依赖**: ADB, Bash/PowerShell, 基本网络工具