# OpenCode Windows ARM64 架构问题分析报告

## 问题描述

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

## 根本原因

经过详细分析，发现了以下关键问题：

### 1. **opencode-ai 不支持 Windows ARM64**

`opencode-ai` 包的可选依赖列表中**不包含** `opencode-windows-arm64`：

```json
{
  "optionalDependencies": {
    "opencode-linux-x64": "1.1.19",
    "opencode-darwin-x64": "1.1.19",
    "opencode-linux-arm64": "1.1.19",
    "opencode-windows-x64": "1.1.19",        // ✅ Windows x64
    "opencode-darwin-arm64": "1.1.19",        // ✅ macOS ARM64
    "opencode-linux-x64-musl": "1.1.19",
    "opencode-linux-arm64-musl": "1.1.19",
    "opencode-linux-x64-baseline": "1.1.19",
    "opencode-darwin-x64-baseline": "1.1.19",
    "opencode-windows-x64-baseline": "1.1.19",// ✅ Windows x64 baseline
    "opencode-linux-x64-baseline-musl": "1.1.19"
    // ❌ 没有 opencode-windows-arm64！
  }
}
```

### 2. **支持的架构列表**

根据 npm registry 搜索结果，`opencode-ai` 目前只支持以下二进制包：

- ✅ `opencode-linux-x64`
- ✅ `opencode-linux-arm64`
- ✅ `opencode-darwin-x64` (macOS Intel)
- ✅ `opencode-darwin-arm64` (macOS Apple Silicon)
- ✅ `opencode-windows-x64`
- ✅ `opencode-linux-x64-musl`
- ✅ `opencode-linux-arm64-musl`
- ✅ `opencode-linux-x64-baseline`
- ✅ `opencode-darwin-x64-baseline`
- ✅ `opencode-windows-x64-baseline`
- ✅ `opencode-linux-x64-baseline-musl`

**缺失的架构：**
- ❌ `opencode-windows-arm64` (Windows on ARM)

### 3. **问题触发条件**

以下情况会导致安装失败：

1. **真实的 Windows ARM64 设备**：
   - Surface Pro X
   - Surface Pro 9 5G
   - 其他 ARM 架构的 Windows 设备
   - Node.js `process.arch` 返回 `'arm64'`

2. **错误的环境变量设置**：
   ```bash
   npm_config_arch=arm64
   ```

3. **npm 架构检测错误**（极少见）

## 解决方案

### 方案 1：检测并跳过 OpenCode 安装（推荐）

在 `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();

    // Windows ARM64 不受支持
    if (platform === 'win32' && arch === 'arm64') {
      this.log('⚠️  OpenCode 不支持 Windows ARM64 架构', 'warning');
      this.log('   跳过 OpenCode 安装', 'info');
      this.log('   如需使用 OpenCode，请在 x64 环境或 WSL 中安装', 'info');
      return false;
    }

    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');
    throw error;
  }
}
```

### 方案 2：提供详细的错误信息

如果检测到不支持的架构，提供清晰的错误信息和替代方案：

```javascript
if (platform === 'win32' && arch === 'arm64') {
  this.log('❌ OpenCode 暂不支持 Windows ARM64 架构', 'error');
  this.log('', 'info');
  this.log('可能的解决方案：', 'info');
  this.log('  1. 使用 WSL (Windows Subsystem for Linux) 安装 x64 版本', 'info');
  this.log('  2. 等待 OpenCode 官方发布 Windows ARM64 版本', 'info');
  this.log('  3. 使用其他 AI CLI 工具（CodeBuddy、iFlow、Qoder 等）', 'info');
  this.log('', 'info');
  this.log('跳过 OpenCode 安装，继续安装其他工具...', 'info');
  return false;
}
```

### 方案 3：添加用户配置选项

允许用户明确跳过 OpenCode：

```bash
stigmergylite --no-opencode
```

这已经是现有功能，可以在文档中强调此选项。

## 影响范围

- **受影响用户**：使用 Windows ARM64 设备的用户
- **其他工具**：不受影响
  - ✅ CodeBuddy 支持多架构
  - ✅ iFlow CLI 支持多架构
  - ✅ Qoder CLI 支持多架构
  - ✅ Qwen CLI 支持多架构
  - ✅ Bun 支持多架构

## 测试验证

可以在非 ARM64 设备上模拟 ARM64 环境测试：

```bash
# 设置环境变量模拟 ARM64（仅用于测试）
export npm_config_arch=arm64

# 运行安装
npm install -g opencode-ai

# 预期结果：安装失败，提示找不到 opencode-windows-arm64
```

## 建议

1. **立即实施**：添加架构检测，优雅地处理不支持的架构
2. **文档更新**：在 README 和安装说明中明确列出系统要求
3. **用户反馈**：向 OpenCode 项目报告缺乏 Windows ARM64 支持的问题
4. **替代方案**：文档中说明 Windows ARM64 用户可以使用 WSL 或其他 CLI 工具

## 相关资源

- opencode-ai 包：https://www.npmjs.com/package/opencode-ai
- OpenCode GitHub：需要查找项目仓库
- Windows on ARM 文档：https://learn.microsoft.com/en-us/windows/arm/