# OpenCode Windows ARM64 架构问题修复总结

## 问题描述

用户报告在某些机器上安装 `stigmergylite` 时，OpenCode 安装失败并提示"必须安装 Windows ARM64 版本"。

## 根本原因分析

### 1. OpenCode 包架构支持情况

通过分析 `opencode-ai@1.1.19` 包的可选依赖，发现以下情况：

**支持的架构：**
- ✅ `opencode-linux-x64`
- ✅ `opencode-linux-arm64`
- ✅ `opencode-darwin-x64` (macOS Intel)
- ✅ `opencode-darwin-arm64` (macOS Apple Silicon)
- ✅ `opencode-windows-x64`
- ✅ 各种 `-musl` 和 `-baseline` 变体

**不支持的架构：**
- ❌ `opencode-windows-arm64` （完全缺失）

### 2. 问题触发场景

- **真实的 Windows ARM64 设备**：Surface Pro X、Surface Pro 9 5G 等
- **环境变量错误配置**：`npm_config_arch=arm64`
- **架构检测错误**（极少见）

## 修复方案

### 代码修改

在 `index.js` 的 `installOpenCode()` 方法中添加了平台和架构检测逻辑：

```javascript
async installOpenCode() {
  this.log('开始安装 OpenCode...', 'info');

  try {
    // 检查是否已安装
    if (this.commandExists('opencode')) {
      this.log('OpenCode 已安装', 'success');
      return true;
    }

    // 检测操作系统和架构
    const platform = os.platform();
    const arch = os.arch();

    // OpenCode 支持的平台和架构组合
    const supportedPlatforms = [
      { platform: 'win32', arch: 'x64', package: 'opencode-windows-x64' },
      { platform: 'darwin', arch: 'x64', package: 'opencode-darwin-x64' },
      { platform: 'darwin', arch: 'arm64', package: 'opencode-darwin-arm64' },
      { platform: 'linux', arch: 'x64', package: 'opencode-linux-x64' },
      { platform: 'linux', arch: 'arm64', package: 'opencode-linux-arm64' },
    ];

    // 检查当前平台是否支持
    const isSupported = supportedPlatforms.some(
      p => p.platform === platform && p.arch === arch
    );

    // Windows ARM64 特殊处理
    if (platform === 'win32' && arch === 'arm64') {
      this.log('⚠️  检测到 Windows ARM64 架构', 'warning');
      this.log('❌ OpenCode 目前不支持 Windows ARM64 架构', 'error');
      this.log('', 'info');
      this.log('可能的解决方案：', 'info');
      this.log('  1. 使用 WSL2 (Windows Subsystem for Linux) 安装 Linux 版本', 'info');
      this.log('     在 WSL2 中运行: npm install -g opencode-ai', 'info');
      this.log('  2. 等待 OpenCode 官方发布 Windows ARM64 版本', 'info');
      this.log('  3. 使用其他 AI CLI 工具（CodeBuddy、iFlow、Qoder、Qwen 均支持 ARM64）', 'info');
      this.log('', 'info');
      this.log('跳过 OpenCode 安装，继续安装其他工具...', 'info');
      return false; // 返回 false 而不是抛出异常
    }

    // 其他不受支持的平台警告
    if (!isSupported) {
      this.log(`⚠️  当前平台 ${platform} ${arch} 可能不受 OpenCode 官方支持`, 'warning');
      this.log('尝试安装 opencode-ai（可能使用通用或模拟版本）...', 'info');
    }

    // 正常安装
    this.log(`检测到平台: ${platform} ${arch}`, 'info');
    this.log('执行: npm install -g opencode-ai', 'info');

    execSync('npm install -g opencode-ai', {
      stdio: this.options.silent ? 'pipe' : 'inherit',
      timeout: 300000
    });

    // 验证安装
    const version = execSync('opencode --version', { encoding: 'utf-8' });
    this.log(`OpenCode 安装成功: ${version.trim()}`, 'success');
    return true;
  } catch (error) {
    this.log(`OpenCode 安装失败: ${error.message}`, 'error');

    // 架构不支持错误的额外提示
    if (error.message.includes('EBADPLATFORM') || error.message.includes('not found')) {
      this.log('', 'info');
      this.log('这可能是由于当前架构不受支持导致的', 'warning');
      this.log('请访问 https://www.npmjs.com/package/opencode-ai 查看支持的平台', 'info');
    }

    throw error;
  }
}
```

### 关键改进点

1. **平台检测**：明确检测操作系统和架构
2. **Windows ARM64 特殊处理**：提前识别并跳过，不中断整个安装流程
3. **友好的错误信息**：提供清晰的说明和替代方案
4. **非破坏性**：返回 `false` 而不是抛出异常，允许其他工具继续安装
5. **警告而非错误**：对不常见的架构给出警告但仍尝试安装

## 测试验证

### 测试脚本

创建了三个测试脚本：

1. **test-arm64-detection.js**：测试平台检测逻辑（已通过 ✅）
2. **test-opencode-platform.js**：模拟不同平台行为（已通过 ✅）
3. **test-opencode-install.js**：测试实际安装流程（已通过 ✅）

### 测试结果

```
================================================================================
测试总结
================================================================================
通过: 6/6
失败: 0/6

✅ 所有测试通过！

测试场景覆盖：
- ✅ Windows x64 (Intel/AMD) - 正常安装
- ✅ Windows ARM64 (Surface Pro X) - 正确跳过
- ✅ macOS Intel - 正常安装
- ✅ macOS Apple Silicon - 正常安装
- ✅ Linux x64 - 正常安装
- ✅ Linux ARM64 - 正常安装
```

## 用户影响

### Windows ARM64 用户

**之前的行为：**
```
❌ 安装失败，抛出异常
❌ 整个 stigmergylite 安装流程中断
```

**现在的行为：**
```
⚠️  检测到 Windows ARM64 架构
❌ OpenCode 目前不支持 Windows ARM64 架构

可能的解决方案：
  1. 使用 WSL2 (Windows Subsystem for Linux) 安装 Linux 版本
  2. 等待 OpenCode 官方发布 Windows ARM64 版本
  3. 使用其他 AI CLI 工具（CodeBuddy、iFlow、Qoder、Qwen 均支持 ARM64）

跳过 OpenCode 安装，继续安装其他工具...
✅ Git、Bun、CodeBuddy、iFlow、Qoder、Qwen 等工具正常安装
```

### 其他平台用户

- ✅ 无影响，正常安装流程

## 相关文件

### 修改的文件
- `index.js` - 添加了平台检测和 Windows ARM64 处理逻辑

### 新增的文件
- `OPENCODE_ARCHITECTURE_ISSUE.md` - 详细的问题分析报告
- `diagnose-opencode.js` - 诊断脚本，用于排查架构问题
- `test-arm64-detection.js` - 平台检测逻辑测试
- `test-opencode-platform.js` - 多平台行为模拟测试
- `test-opencode-install.js` - 实际安装测试
- `FIX_OPENCODE_ARM64.md` - 本文档

## 使用建议

### Windows ARM64 用户

**选项 1：使用 WSL2（推荐）**
```bash
# 在 WSL2 中安装 OpenCode
wsl
npm install -g opencode-ai
```

**选项 2：跳过 OpenCode**
```bash
# 安装时跳过 OpenCode
stigmergylite --no-opencode

# 或使用环境变量
npm_config_opencode=false stigmergylite
```

**选项 3：使用替代工具**
所有其他 AI CLI 工具都支持 ARM64：
- ✅ CodeBuddy (`@tencent-ai/codebuddy-code`)
- ✅ iFlow CLI (`@iflow-ai/iflow-cli`)
- ✅ Qoder CLI (`@qoder-ai/qodercli`)
- ✅ Qwen CLI (`@qwen-code/qwen-code`)

### 所有用户

如果遇到架构相关问题，可以运行诊断脚本：
```bash
node diagnose-opencode.js
```

## 未来改进

1. **持续关注**：监控 OpenCode 项目是否发布 Windows ARM64 版本
2. **自动重试**：如果 OpenCode 发布 ARM64 版本，建议用户重新运行安装
3. **文档更新**：在 README 中明确列出系统要求和已知限制
4. **用户反馈**：向 OpenCode 项目报告缺乏 Windows ARM64 支持的问题

## 版本更新

建议更新版本号并发布：
- 当前版本：`1.1.0`
- 建议版本：`1.1.1`（bug 修复）
- 更新日志：`fix: 正确处理 OpenCode 在 Windows ARM64 上的安装问题`

## 参考资料

- opencode-ai 包：https://www.npmjs.com/package/opencode-ai
- Node.js os.platform()：https://nodejs.org/api/os.html#osplatform
- Node.js os.arch()：https://nodejs.org/api/os.html#osarch
- Windows on ARM：https://learn.microsoft.com/en-us/windows/arm/