xgj/setup-opencode/README.md

# Setup OpenCode Action

使用 npm 全局安装 OpenCode 并缓存，支持版本检测和自动更新。

## 功能特性

- ✅ **npm 安装**：使用 npm 全局安装，简单快速
- 🚀 **智能缓存**：缓存 npm 包和全局安装，加速后续构建
- 🔄 **自动更新**：版本变化时自动更新
- 🇨🇳 **国内镜像**：支持淘宝镜像源，国内环境友好
- ⚡ **快速恢复**：缓存命中时跳过安装，秒级完成

## 使用方法

### 基础用法

```yaml
- name: 安装 OpenCode
  uses: actions/xgj/setup-opencode@v1
```

### 国内环境使用（推荐）

```yaml
- name: 安装 OpenCode（淘宝镜像）
  uses: actions/xgj/setup-opencode@v1
  with:
    version: 'latest'
    use-taobao-registry: 'true'
```

### 指定版本

```yaml
- name: 安装 OpenCode 1.2.3
  uses: ./.gitea/actions/setup-opencode
  with:
    version: '1.2.3'
```

### 使用最新版本

```yaml
- name: 安装最新版 OpenCode
  uses: actions/xgj/setup-opencode@v1
  with:
    version: 'latest'
```

### 自定义 npm 包名

```yaml
- name: 安装自定义包
  uses: actions/xgj/setup-opencode@v1
  with:
    package-name: '@myorg/opencode'
    version: '1.2.3'
```

### 自定义 npm 镜像源

```yaml
- name: 使用自定义镜像源
  uses: actions/xgj/setup-opencode@v1
  with:
    version: 'latest'
    npm-registry: 'https://registry.npmmirror.com'
```

### 强制重新安装

```yaml
- name: 强制重新安装 OpenCode
  uses: actions/xgj/setup-opencode@v1
  with:
    version: '1.2.3'
    skip-cache: 'true'
```

### 使用输出

```yaml
- name: 安装 OpenCode
  id: setup-opencode
  uses: actions/xgj/setup-opencode@v1
  with:
    version: 'latest'

- name: 显示版本信息
  run: |
    echo "安装版本: ${{ steps.setup-opencode.outputs.version }}"
    echo "缓存命中: ${{ steps.setup-opencode.outputs.cache-hit }}"
    echo "执行更新: ${{ steps.setup-opencode.outputs.updated }}"

- name: 使用 OpenCode
  run: |
    opencode --version
    opencode build
```

## 输入参数

| 参数 | 描述 | 必填 | 默认值 |
| ---- | ---- | ---- | ------ |
| `version` | OpenCode 版本号（例如: 1.0.0, latest） | 否 | `latest` |
| `package-name` | npm 包名 | 否 | `opencode` |
| `use-taobao-registry` | 使用淘宝 npm 镜像源 (true/false) | 否 | `false` |
| `npm-registry` | 自定义 npm 镜像源地址 | 否 | `` |
| `cache-prefix` | 缓存前缀名称 | 否 | `opencode-npm` |
| `skip-cache` | 跳过缓存，强制重新安装 (true/false) | 否 | `false` |

## 输出

| 输出 | 描述 |
| ---- | ---- |
| `version` | 安装的 OpenCode 版本 |
| `cache-hit` | 缓存是否命中 (true/false) |
| `updated` | 是否执行了更新 (true/false) |

## 工作原理

1. **参数验证**：验证输入参数的有效性
2. **配置镜像源**：根据配置设置 npm 镜像源（支持淘宝镜像）
3. **缓存检查**：根据包名和版本生成缓存键，尝试恢复缓存
4. **版本比对**：
   - 检查已安装版本是否与请求版本一致
   - 版本一致：跳过安装
   - 版本不一致或未安装：执行 npm 安装
5. **npm 安装**：使用 `npm install -g` 全局安装指定版本
6. **保存缓存**：缓存 npm 包和全局安装目录

## 缓存策略

- **缓存内容**：
  - `~/.npm` - npm 缓存目录
  - `/usr/local/lib/node_modules/{package}` - 全局安装的包
  - `/usr/local/bin/{package}` - 全局命令
- **缓存键格式**：`{OS}-{cache-prefix}-{package-name}-{version}`
- **缓存更新**：版本号变化时自动更新缓存
- **缓存生命周期**：遵循 GitHub Actions 缓存默认生命周期（最多 7 天未使用）

## 完整示例

### 示例 1：基础 CI/CD 流程

```yaml
name: Build with OpenCode

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 安装 OpenCode
        uses: actions/xgj/setup-opencode@v1
        with:
          version: '1.2.3'

      - name: 构建项目
        run: |
          opencode build --release

      - name: 运行测试
        run: |
          opencode test
```

### 示例 2：国内环境使用

```yaml
name: Build in China

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 安装 OpenCode（淘宝镜像）
        uses: actions/xgj/setup-opencode@v1
        with:
          version: 'latest'
          use-taobao-registry: 'true'

      - name: 构建
        run: opencode build
```

### 示例 3：多版本测试

```yaml
name: Test Multiple Versions

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        opencode-version: ['1.0.0', '1.1.0', '1.2.0', 'latest']
    steps:
      - uses: actions/checkout@v4

      - name: 安装 OpenCode ${{ matrix.opencode-version }}
        uses: actions/xgj/setup-opencode@v1
        with:
          version: ${{ matrix.opencode-version }}

      - name: 运行测试
        run: |
          echo "Testing with OpenCode ${{ matrix.opencode-version }}"
          opencode --version
          opencode test
```

### 示例 4：带缓存状态检查

```yaml
name: Build with Cache Info

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 安装 OpenCode
        id: opencode
        uses: actions/xgj/setup-opencode@v1
        with:
          version: 'latest'
          use-taobao-registry: 'true'

      - name: 显示缓存状态
        run: |
          if [[ "${{ steps.opencode.outputs.cache-hit }}" == "true" ]]; then
            echo "✅ 使用缓存，节省时间！"
          else
            echo "📥 首次安装或版本更新"
          fi
          
          if [[ "${{ steps.opencode.outputs.updated }}" == "true" ]]; then
            echo "🔄 OpenCode 已更新到 ${{ steps.opencode.outputs.version }}"
          fi

      - name: 构建
        run: opencode build
```

## 注意事项

1. **国内环境**：🇨🇳 在国内使用时，强烈建议设置 `use-taobao-registry: 'true'` 使用淘宝镜像源
2. **版本格式**：版本号应遵循语义化版本规范（如 1.2.3）
3. **npm 环境**：需要 Node.js 和 npm 已安装（GitHub Actions 默认已安装）
4. **全局安装**：使用 `npm install -g` 全局安装，命令自动添加到 PATH
5. **缓存限制**：GitHub Actions 缓存有大小限制（10GB）

## 故障排查

### 国内网络问题

```yaml
- name: 使用淘宝镜像源
  uses: actions/xgj/setup-opencode@v1
  with:
    version: '1.2.3'
    use-taobao-registry: 'true'
```

### 自定义镜像源

```yaml
- name: 使用自定义镜像
  uses: actions/xgj/setup-opencode@v1
  with:
    version: '1.2.3'
    npm-registry: 'https://registry.npmmirror.com'
```

### 安装失败

```yaml
- name: 清除缓存重新安装
  uses: actions/xgj/setup-opencode@v1
  with:
    version: '1.2.3'
    skip-cache: 'true'
```

### 版本不匹配

检查 `updated` 输出，如果为 `true` 表示已更新到新版本。

## 优势

相比二进制安装方式，npm 安装具有以下优势：

- ✅ **简单直接**：一条 `npm install -g` 命令搞定
- ✅ **依赖管理**：npm 自动处理依赖关系
- ✅ **版本管理**：npm 原生支持版本管理
- ✅ **跨平台**：npm 包通常支持多平台
- ✅ **更新方便**：版本更新只需修改版本号
- ✅ **缓存高效**：缓存 npm 目录和全局安装，恢复快速

## 许可证

与主仓库保持一致。