Skip to content
LiveNew tools this week
Submit
AIMarketly
oh-my-opencode-update logo

oh-my-opencode-update

Use when upgrading, reinstalling, or troubleshooting the oh-my-opencode plugin, especially when old caches, lockfiles, or permissions prevent the new version from taking effect.

NeverSight/skills_feed0installs213stars

SKILL.md

Full skill instructions

oh-my-opencode-update

面向唯一长期用户：凌贵旺（Guiwang Ling）。

核心目标

  • 默认升级到最新版本（latest），并支持 指定版本（pinned version）。
  • 先检查环境（npm/​node/权限），再备份，再温和卸载，再清理缓存（删除前二次确认），最后安装并验证。
  • 任何关键步骤失败：立刻停止（不自动扩大破坏范围）。

执行流程

脚本按以下顺序执行（共 7 步）：

步骤名称说明
[0/​7]Prerequisites check检查 npm、node 版本及配置目录权限
[1/​7]Baseline记录当前环境信息
[2/​7]Backup configs备份 opencode.json 和 oh-my-opencode.json
[3/​7]Uninstall (gentle)温和卸载旧版本
[4/​7]Cache cleanup可选的缓存清理（需确认）
[5/​7]Install/​Upgrade安装新版本（支持超时回退）
[6/​7]Verify验证安装结果

[5/​7] Install/​Upgrade 详解

安装过程采用双重策略：

  1. 首次尝试：正常 npm install --save-exact（带超时保护）
  2. 自动回退：若失败或超时，自动使用 --save-exact --ignore-scripts 重试

关键特性：

  • --save-exact：确保安装精确版本，避免 npm 自动添加 ^ 导致版本升级
  • 超时保护：防止 postinstall 脚本卡住

适用环境（可通过环境变量自定义）

默认路径

以下路径为默认值，可通过环境变量覆盖：

环境变量默认值说明
OPENCODE_CONFIG_DIR${HOME}/​.config/​opencodeopencode 配置目录（oh-my-opencode 安装位置）
OPENCODE_CACHE_DIR${HOME}/​.cache缓存目录根目录
OPENCODE_BIN${HOME}/​.opencode/​bin/​opencodeopencode 二进制文件路径
NPM_INSTALL_TIMEOUT120npm install 超时时间（秒），0 表示无超时

配置文件

  • opencode 配置：${OPENCODE_CONFIG_DIR}/​opencode.json
  • oh-my-opencode 配置：${OPENCODE_CONFIG_DIR}/​oh-my-opencode.json
  • 缓存目录：${OPENCODE_CACHE_DIR}/​oh-my-opencode

自定义路径（可选）

export OPENCODE_CONFIG_DIR="/​custom/​config/​opencode"
export OPENCODE_CACHE_DIR="/​custom/​cache"

更多配置说明请参见 references/​paths_config.md。

使用方式

脚本位置：${SKILL_ROOT}/​scripts/​oh_my_opencode_update.sh

其中 ${SKILL_ROOT} 为 skill 根目录（包含 SKILL.md 的目录）。

1) Dry-run（推荐先跑）

# 从 skill 根目录运行
bash scripts/​oh_my_opencode_update.sh --dry-run --latest

2) 实际执行：升级到 latest

bash scripts/​oh_my_opencode_update.sh --apply --latest

3) 实际执行：升级到指定版本

bash scripts/​oh_my_opencode_update.sh --apply --target-version 3.2.2

验收（必须做）

cd ${OPENCODE_CONFIG_DIR}
node node_modules/​.bin/​oh-my-opencode --version
node node_modules/​.bin/​oh-my-opencode doctor

常见问题

前置检查失败

  • npm 或 node 未安装
  • 配置目录无写权限
    • 检查权限：ls -ld "${OPENCODE_CONFIG_DIR}"
    • 修复权限：chmod u+w "${OPENCODE_CONFIG_DIR}"

npm 相关问题

  • npm install 失败
    • 脚本会自动输出诊断建议，常见原因：
      1. 网络问题 - 检查网络连接
      2. 权限问题 - 检查目录权限
      3. Registry 问题 - 尝试官方 registry
      4. 磁盘空间不足
  • npm uninstall 失败
    • 可能是包未安装（首次安装时正常）
    • 可能是权限或 lock 文件问题，按脚本提示修复
  • postinstall 脚本卡住
    • 脚本会自动处理：超时后使用 --ignore-scripts 重试
    • 可通过 NPM_INSTALL_TIMEOUT 调整超时时间
    • macOS 用户需安装 coreutils：brew install coreutils（提供 gtimeout）

历史说明

  • 本 skill 早期版本使用 bun 作为包管理器，现已切换到 npm 以提高兼容性和稳定性