xgj/setup-opencode/README.md

Setup OpenCode Action

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

功能特性

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

使用方法

基础用法

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

国内环境使用（推荐）

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

指定版本

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

使用最新版本

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

自定义 npm 包名

- name: 安装自定义包
  uses: actions/xgj/setup-opencode@v1
  with:
    package-name: 'opencode-ai'  # 默认就是 opencode-ai，这里仅作演示
    version: '1.2.3'

自定义 npm 镜像源

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

强制重新安装

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

使用输出

- 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-ai
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 流程

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：国内环境使用

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：多版本测试

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：带缓存状态检查

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）

故障排查

国内网络问题

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

自定义镜像源

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

安装失败

- 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 目录和全局安装，恢复快速

许可证

与主仓库保持一致。