OpenCode 入门教程：开源终端 AI 编程助手的完整实战

node --version

npm install -g opencode-ai@latest

bun add -g opencode-ai@latest
pnpm add -g opencode-ai@latest
yarn global add opencode-ai@latest

brew install anomalyco/tap/opencode

curl -fsSL https://opencode.ai/install | bash

# Scoop
scoop install opencode

# Chocolatey
choco install opencode

# 稳定版
sudo pacman -S opencode

# 最新版（AUR）
paru -S opencode-bin

mise use -g opencode
nix run nixpkgs#opencode

opencode --version

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "sk-ant-xxxxxxxxxxxxx"
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-5-20250929"
}

cd /你的项目路径

opencode

opencode run "帮我找出 src/ 下所有未被引用的函数"

opencode session

# 启动时自动续接最近一次会话
opencode --continue

# 续接指定 ID 的会话
opencode --session <会话ID>

opencode export

// opencode.json — 接入云间 API 中转站
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    // OpenAI 兼容组：GPT 系列、DeepSeek V4、GLM、Kimi 等
    // 走标准 OpenAI API 格式，baseURL 指向云间 API 的 OpenAI 兼容端点
    "openai": {
      "options": {
        "apiKey": "sk-你的云间API-Key",
        "baseURL": "https://cloudzone-api.cyou/v1"
      },
      "models": {
        "gpt-5.4":       { "name": "GPT 5.4" },
        "gpt-5.1-codex": { "name": "GPT 5.1 Codex" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    },
    // Anthropic 兼容组（CC MAX）：Claude 全系列
    // 走原生 Anthropic API 格式，baseURL 指向云间 API 的 Anthropic 兼容端点
    "anthropic": {
      "options": {
        "apiKey": "sk-你的云间API-Key",
        "baseURL": "https://cloudzone-api.cyou/v1"
      },
      "models": {
        "claude-sonnet-4-5-20250929": { "name": "Claude Sonnet 4.5" },
        "claude-opus-4-5":            { "name": "Claude Opus 4.5" }
      }
    }
  },
  // 默认模型：写代码推荐 GPT 5.1 Codex，性价比高
  "model": "openai/gpt-5.1-codex"
}

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "sk-xxx",
        "baseURL": "https://cloudzone-api.cyou/v1"
      },
      // 白名单：只显示这三个模型
      "whitelist": ["gpt-5.4", "gpt-5.1-codex", "deepseek-v4-flash"]
    }
  }
}

// tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",           // 主题名
  "leader_timeout": 2000,        // 快捷键前缀的超时时间（毫秒）
  "scroll_speed": 3,             // 滚动速度
  "mouse": true,                 // 是否启用鼠标
  "cursor": {
    "style": "block",            // 光标样式：block / underline / bar
    "blinking": true             // 光标是否闪烁
  },
  "diff_style": "auto",          // 代码差异展示风格
  "attention": {
    "enabled": true,             // 任务完成时是否提醒
    "notifications": true,       // 是否发送系统通知
    "sound": true,               // 是否播放提示音
    "volume": 0.4
  }
}

opencode agent create

opencode agent create \
  --path .opencode/agent/code-reviewer.md \
  --description "只读代码审查，不修改文件" \
  --mode primary \
  --permissions "read,glob,grep,lsp"

chmod +x install-opencode.sh
./install-opencode.sh

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
.\install-opencode.ps1

#!/usr/bin/env bash
# ============================================================
#  OpenCode 入门教程 一键脚本（macOS / Linux / WSL）
#  公开源码，欢迎审查 —— 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
# ============================================================

set -u

CLOUDZONE_URL="https://cloudzone-api.cyou"
CLOUDZONE_API_BASE="https://cloudzone-api.cyou/v1"

GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; CYAN='\033[0;36m'; NC='\033[0m'
info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }
step()  { echo -e "${CYAN}[STEP]${NC} $1"; }

# ---------- 第 0 步：检测网络环境（国内 / 国外）----------
detect_network() {
  step "检测网络环境（国内 / 国外）..."
  if curl -fsI --max-time 5 "https://claude.ai" >/dev/null 2>&1; then
    info "可直连 claude.ai，判定为海外网络"
    echo "overseas"
  else
    warn "无法直连 claude.ai，判定为国内网络环境"
    echo "domestic"
  fi
}

# ---------- 第 1 步：安装 Node.js 18+ ----------
install_nodejs() {
  local net="$1"
  step "检查 Node.js 环境..."

  if command -v node >/dev/null 2>&1; then
    local NODE_MAJOR
    NODE_MAJOR=$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)
    if [ "$NODE_MAJOR" -ge 18 ]; then
      info "Node.js $(node --version) 已就绪"
      return 0
    fi
    warn "Node.js $(node --version) 版本过低（需要 18+），将尝试安装新版本..."
  fi

  # 尝试 Homebrew（macOS / Linux）
  if command -v brew >/dev/null 2>&1; then
    info "通过 Homebrew 安装 Node.js..."
    if brew install node 2>/dev/null; then
      info "Homebrew 安装 Node.js 成功"
      return 0
    fi
    warn "Homebrew 安装失败，尝试其他方式"
  fi

  # 尝试 apt（Debian / Ubuntu）
  if command -v apt-get >/dev/null 2>&1; then
    info "通过 apt 安装 Node.js..."
    curl -fsSL --max-time 30 "https://deb.nodesource.com/setup_20.x" 2>/dev/null | sudo -E bash - 2>/dev/null
    if sudo apt-get install -y nodejs 2>/dev/null; then
      info "apt 安装 Node.js 成功"
      return 0
    fi
    warn "apt 安装失败，尝试其他方式"
  fi

  # 尝试 dnf（Fedora）
  if command -v dnf >/dev/null 2>&1; then
    info "通过 dnf 安装 Node.js..."
    if sudo dnf install -y nodejs 2>/dev/null; then
      info "dnf 安装 Node.js 成功"
      return 0
    fi
    warn "dnf 安装失败，尝试其他方式"
  fi

  # 尝试 yum（RHEL / CentOS）
  if command -v yum >/dev/null 2>&1; then
    info "通过 yum 安装 Node.js..."
    curl -fsSL --max-time 30 "https://rpm.nodesource.com/setup_20.x" 2>/dev/null | sudo -E bash - 2>/dev/null
    if sudo yum install -y nodejs 2>/dev/null; then
      info "yum 安装 Node.js 成功"
      return 0
    fi
    warn "yum 安装失败，尝试其他方式"
  fi

  # 尝试 pacman（Arch Linux）
  if command -v pacman >/dev/null 2>&1; then
    info "通过 pacman 安装 Node.js..."
    if sudo pacman -S --noconfirm nodejs 2>/dev/null; then
      info "pacman 安装 Node.js 成功"
      return 0
    fi
    warn "pacman 安装失败，尝试其他方式"
  fi

  # 回退：手动下载二进制包
  local NODE_VER="v20.18.0"
  local OS
  OS="$(uname -s)"
  local ARCH
  ARCH="$(uname -m)"
  local NODE_ARCHIVE=""
  local NODE_DIRNAME=""

  case "$OS" in
    Linux)
      case "$ARCH" in
        x86_64)  NODE_ARCHIVE="node-${NODE_VER}-linux-x64.tar.xz"; NODE_DIRNAME="node-${NODE_VER}-linux-x64" ;;
        aarch64) NODE_ARCHIVE="node-${NODE_VER}-linux-arm64.tar.xz"; NODE_DIRNAME="node-${NODE_VER}-linux-arm64" ;;
        armv7l)  NODE_ARCHIVE="node-${NODE_VER}-linux-armv7l.tar.xz"; NODE_DIRNAME="node-${NODE_VER}-linux-armv7l" ;;
        *) error "不支持的 Linux 架构：$ARCH"; return 1 ;;
      esac
      ;;
    Darwin)
      case "$ARCH" in
        x86_64) NODE_ARCHIVE="node-${NODE_VER}-darwin-x64.tar.gz"; NODE_DIRNAME="node-${NODE_VER}-darwin-x64" ;;
        arm64)  NODE_ARCHIVE="node-${NODE_VER}-darwin-arm64.tar.gz"; NODE_DIRNAME="node-${NODE_VER}-darwin-arm64" ;;
        *) error "不支持的 macOS 架构：$ARCH"; return 1 ;;
      esac
      ;;
    *) error "不支持的操作系统：$OS"; return 1 ;;
  esac

  local NODE_URL
  if [ "$net" = "domestic" ]; then
    NODE_URL="https://npmmirror.com/mirrors/node/${NODE_VER}/${NODE_ARCHIVE}"
  else
    NODE_URL="https://nodejs.org/dist/${NODE_VER}/${NODE_ARCHIVE}"
  fi

  step "下载 Node.js ${NODE_VER} (${OS} ${ARCH})..."
  local TMP_FILE="/tmp/${NODE_ARCHIVE}"
  if ! curl -fsSL --max-time 120 "$NODE_URL" -o "$TMP_FILE"; then
    warn "主源下载失败，尝试备用源..."
    local FALLBACK_URL
    if [ "$net" = "domestic" ]; then
      FALLBACK_URL="https://nodejs.org/dist/${NODE_VER}/${NODE_ARCHIVE}"
    else
      FALLBACK_URL="https://npmmirror.com/mirrors/node/${NODE_VER}/${NODE_ARCHIVE}"
    fi
    if ! curl -fsSL --max-time 120 "$FALLBACK_URL" -o "$TMP_FILE"; then
      error "所有源均无法下载 Node.js。请手动安装：https://nodejs.org/ （海外）或 https://npmmirror.com/mirrors/node/ （国内镜像）"
      return 1
    fi
  fi

  info "解压 Node.js 到 /usr/local..."
  cd /tmp || return 1
  rm -rf "/tmp/${NODE_DIRNAME}"
  if [[ "$NODE_ARCHIVE" == *.tar.xz ]]; then
    tar -xJf "$TMP_FILE"
  else
    tar -xzf "$TMP_FILE"
  fi

  if sudo cp -r "/tmp/${NODE_DIRNAME}/"* /usr/local/ 2>/dev/null; then
    info "已安装到 /usr/local（需要 sudo 权限）"
  else
    # 无 sudo 权限：安装到用户目录
    warn "无 sudo 权限，安装到 $HOME/.local/node"
    mkdir -p "$HOME/.local/node"
    cp -r "/tmp/${NODE_DIRNAME}/"* "$HOME/.local/node/"
    export PATH="$HOME/.local/node/bin:$PATH"
    # 写入 shell 配置文件（永久生效）
    local SHELL_RC="${HOME}/.bashrc"
    case "${SHELL:-/bin/bash}" in */zsh) SHELL_RC="$HOME/.zshrc" ;; esac
    if ! grep -q '.local/node/bin' "$SHELL_RC" 2>/dev/null; then
      echo 'export PATH="$HOME/.local/node/bin:$PATH"' >> "$SHELL_RC"
      info "PATH 已写入 $SHELL_RC，新开终端窗口后生效"
    fi
  fi

  rm -f "$TMP_FILE"; rm -rf "/tmp/${NODE_DIRNAME}"
  if command -v node >/dev/null 2>&1; then
    info "Node.js $(node --version) 安装完成"
    return 0
  else
    error "Node.js 安装后仍无法使用，请手动安装：https://nodejs.org/ （海外）或 https://npmmirror.com/mirrors/node/ （国内镜像）"
    return 1
  fi
}

# ---------- 第 2 步：安装 OpenCode ----------
install_opencode() {
  local net="$1"
  step "安装 OpenCode..."

  if command -v opencode >/dev/null 2>&1; then
    info "已检测到 OpenCode：$(opencode --version 2>/dev/null || echo '已安装')"
    return 0
  fi

  # 国内：使用 npmmirror 镜像加速
  if [ "$net" = "domestic" ]; then
    info "国内网络，通过 npm + 国内镜像（npmmirror.com）安装..."
    if npm install -g opencode-ai@latest --registry="https://registry.npmmirror.com" 2>/dev/null; then
      info "npm（国内镜像）安装成功"
      return 0
    fi
    warn "国内镜像失败，尝试官方 npm registry..."
  fi

  # 海外／回退：使用官方 npm registry
  info "通过 npm（官方源）安装..."
  if npm install -g opencode-ai@latest 2>/dev/null; then
    info "npm 安装成功"
    return 0
  fi

  error "所有安装方式均失败。请参考官方文档手动安装：https://github.com/anomalyco/opencode"
  return 1
}

# ---------- 第 3 步：配置 API Key ----------
configure_api() {
  step "配置 API Key..."
  echo ""
  echo "OpenCode 需要 API Key 才能调用 AI 模型。默认配置云间 API 中转站："
  echo "  · 价格不足官方两折，国内直连无需翻墙"
  echo "  · 支持 90+ 模型，按量计费无月租"
  echo ""
  echo "是否现在跳转注册并获取 API Key？"
  echo "  Y - 立即跳转至 ${CLOUDZONE_URL}"
  echo "  N - 我已有 Key，自行输入"
  read -r -p "请选择 [Y/N]: " choice

  local API_KEY=""
  if [ "${choice:-N}" = "Y" ] || [ "${choice:-N}" = "y" ]; then
    info "正在打开浏览器..."
    if command -v xdg-open >/dev/null 2>&1; then
      xdg-open "$CLOUDZONE_URL" >/dev/null 2>&1
    elif command -v open >/dev/null 2>&1; then
      open "$CLOUDZONE_URL" >/dev/null 2>&1          # macOS
    else
      warn "无法自动打开浏览器，请手动访问：$CLOUDZONE_URL"
    fi
    echo "注册后在「我的 API Key」页面复制 Key（以 sk- 开头）。"
    read -r -p "粘贴你的 API Key: " API_KEY
  else
    # 关闭回显，避免 Key 明文留在终端滚动区
    read -r -s -p "请输入你的 API Key (sk-...): " API_KEY
    echo
  fi

  if [ -z "${API_KEY:-}" ]; then
    error "未输入 API Key，跳过配置。可稍后手动设置。"
    return 1
  fi

  # 写入 OpenCode 全局配置文件
  local OPCONF_DIR="$HOME/.local/share/opencode"
  mkdir -p "$OPCONF_DIR"
  local OPCONF="$OPCONF_DIR/opencode.json"

  if [ -f "$OPCONF" ]; then
    warn "已有配置文件 $OPCONF，将备份为 opencode.json.bak"
    cp "$OPCONF" "$OPCONF_DIR/opencode.json.bak"
  fi

  # 使用占位符 + sed 替换，避免 API Key 中的特殊字符破坏 JSON
  cat > "$OPCONF" << 'OPCONFEOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "__API_KEY__",
        "baseURL": "__BASE_URL__"
      }
    },
    "anthropic": {
      "options": {
        "apiKey": "__API_KEY__",
        "baseURL": "__BASE_URL__"
      }
    }
  },
  "model": "openai/gpt-5.1-codex"
}
OPCONFEOF

  # macOS 和 Linux 的 sed -i 语法不同，分别处理
  if [[ "$(uname -s)" == "Darwin" ]]; then
    sed -i '' "s|__API_KEY__|${API_KEY}|g; s|__BASE_URL__|${CLOUDZONE_API_BASE}|g" "$OPCONF"
  else
    sed -i "s|__API_KEY__|${API_KEY}|g; s|__BASE_URL__|${CLOUDZONE_API_BASE}|g" "$OPCONF"
  fi

  info "配置完成！"
  echo "  配置文件: $OPCONF"
  echo "  API Key : ${API_KEY:0:10}********"
  echo "  Base URL: $CLOUDZONE_API_BASE"
  echo ""
  info "启动 OpenCode 后输入 /models 即可看到可用模型列表"
}

# ---------- 第 4 步：验证安装 ----------
verify_installation() {
  step "验证安装..."
  if command -v opencode >/dev/null 2>&1; then
    info "OpenCode 安装成功：$(opencode --version 2>/dev/null || echo '版本检测完成')"
    return 0
  else
    warn "opencode 命令未在 PATH 中找到。请尝试关闭终端重新打开，或执行："
    warn "  export PATH=\"\$(npm config get prefix)/bin:\$PATH\""
    return 0
  fi
}

# ---------- 主流程 ----------
main() {
  echo "============================================"
  echo "  OpenCode 入门教程 一键脚本"
  echo "  适用于 macOS / Linux / WSL"
  echo "  默认接入：云间 API 中转站"
  echo "============================================"
  echo ""

  local NET
  NET=$(detect_network)

  if ! install_nodejs "$NET"; then
    error "Node.js 安装失败，脚本终止。请按上方提示手动处理。"
    exit 1
  fi

  if ! install_opencode "$NET"; then
    error "OpenCode 安装失败，脚本终止。请按上方提示手动处理。"
    exit 1
  fi

  configure_api

  verify_installation

  echo ""
  echo "============================================"
  info "全部完成！"
  echo ""
  echo "  启动方式：在终端输入 opencode 回车"
  echo "  首次使用：在 TUI 中输入 /init 分析项目，生成 AGENTS.md"
  echo "  切换模型：输入 /models 查看可用模型列表"
  echo "  获取帮助：输入 /help 或见博客正文"
  echo "============================================"
}

main "$@"

# ============================================================
#  OpenCode 入门教程 一键脚本（Windows PowerShell）
#  公开源码，欢迎审查 —— 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
# ============================================================

$ErrorActionPreference = "Stop"
$CLOUDZONE_URL = "https://cloudzone-api.cyou"
$CLOUDZONE_API_BASE = "https://cloudzone-api.cyou/v1"

function Write-Info  { Write-Host "[INFO] $args" -ForegroundColor Green }
function Write-Warn  { Write-Host "[WARN] $args" -ForegroundColor Yellow }
function Write-Err   { Write-Host "[ERROR] $args" -ForegroundColor Red }
function Write-Step  { Write-Host "[STEP] $args" -ForegroundColor Cyan }

# ---------- 第 0 步：检测网络环境（国内 / 国外）----------
function Detect-Network {
    Write-Step "检测网络环境（国内 / 国外）..."
    try {
        $null = Invoke-WebRequest -Uri "https://claude.ai" -Method Head -TimeoutSec 5 -UseBasicParsing
        Write-Info "可直连 claude.ai，判定为海外网络"
        return "overseas"
    } catch {
        Write-Warn "无法直连 claude.ai，判定为国内网络环境"
        return "domestic"
    }
}

# ---------- 第 1 步：安装 Node.js 18+ ----------
function Install-NodeJS {
    param([string]$Net)
    Write-Step "检查 Node.js 环境..."

    if (Get-Command node -ErrorAction SilentlyContinue) {
        try {
            $major = [int](node -p 'process.versions.node.split(".")[0]' 2>$null)
            if ($major -ge 18) {
                $nodeVer = node --version 2>$null
                Write-Info "Node.js $nodeVer 已就绪"
                return $true
            }
        } catch {}
        $nodeVer = node --version 2>$null
        Write-Warn "Node.js $nodeVer 版本过低（需要 18+），将尝试安装新版本..."
    }

    $nodeVer = "v20.18.0"
    $msiName = "node-$nodeVer-x64.msi"
    $nodeUrl = if ($Net -eq "domestic") {
        "https://npmmirror.com/mirrors/node/$nodeVer/$msiName"
    } else {
        "https://nodejs.org/dist/$nodeVer/$msiName"
    }

    Write-Step "下载 Node.js $nodeVer..."
    $msiPath = "$env:TEMP\$msiName"
    try {
        Invoke-WebRequest -Uri $nodeUrl -OutFile $msiPath -TimeoutSec 120 -UseBasicParsing
        Write-Info "主源下载成功"
    } catch {
        Write-Warn "主源下载失败：$_"
        $altUrl = if ($Net -eq "domestic") {
            "https://nodejs.org/dist/$nodeVer/$msiName"
        } else {
            "https://npmmirror.com/mirrors/node/$nodeVer/$msiName"
        }
        Write-Warn "尝试备用源：$altUrl"
        try {
            Invoke-WebRequest -Uri $altUrl -OutFile $msiPath -TimeoutSec 120 -UseBasicParsing
            Write-Info "备用源下载成功"
        } catch {
            Write-Err "所有源均无法下载 Node.js。请手动安装：https://nodejs.org/ （海外）或 https://npmmirror.com/mirrors/node/ （国内镜像）"
            return $false
        }
    }

    Write-Info "安装 Node.js（静默安装，需要管理员权限）..."
    Write-Warn "即将弹出用户账户控制（UAC）窗口，请点击「是」允许。"
    Write-Warn "（UAC 是 Windows 的安全机制，安装系统级软件必须经过你的确认——这不是恶意行为，是正常流程。）"
    $proc = Start-Process msiexec.exe -ArgumentList "/i `"$msiPath`" /quiet /norestart" -Wait -PassThru -Verb RunAs
    if ($proc.ExitCode -ne 0) {
        Write-Err "Node.js 安装失败（退出码: $($proc.ExitCode)）。请手动安装：https://nodejs.org/ （海外）或 https://npmmirror.com/mirrors/node/ （国内镜像）"
        return $false
    }

    # 刷新 PATH 环境变量（当前会话生效）
    $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
    # （PATH 写入"用户级"是由 Node.js 安装程序自动完成的，脚本只刷新当前会话读取新 PATH）
    Write-Info "Node.js 安装完成"
    return $true
}

# ---------- 第 2 步：安装 OpenCode ----------
function Install-OpenCode {
    param([string]$Net)
    Write-Step "安装 OpenCode..."

    if (Get-Command opencode -ErrorAction SilentlyContinue) {
        try {
            $ver = opencode --version 2>$null
            Write-Info "已检测到 OpenCode：$ver"
            return $true
        } catch {
            Write-Info "已检测到 OpenCode（已安装）"
            return $true
        }
    }

    # 国内：使用 npmmirror 镜像加速
    if ($Net -eq "domestic") {
        Write-Info "国内网络，通过 npm + 国内镜像（npmmirror.com）安装..."
        try {
            npm install -g opencode-ai@latest --registry="https://registry.npmmirror.com"
            Write-Info "npm（国内镜像）安装成功"
            return $true
        } catch {
            Write-Warn "国内镜像失败：$_"
        }
    }

    # 海外／回退：使用官方 npm registry
    Write-Info "通过 npm（官方源）安装..."
    try {
        npm install -g opencode-ai@latest
        Write-Info "npm 安装成功"
        return $true
    } catch {
        Write-Err "所有安装方式均失败：$_"
        Write-Err "请参考官方文档手动安装：https://github.com/anomalyco/opencode"
        return $false
    }
}

# ---------- 第 3 步：配置 API Key ----------
function Configure-Api {
    Write-Step "配置 API Key..."
    Write-Host ""
    Write-Host "OpenCode 需要 API Key 才能调用 AI 模型。默认配置云间 API 中转站："
    Write-Host "  · 价格不足官方两折，国内直连无需翻墙"
    Write-Host "  · 支持 90+ 模型，按量计费无月租"
    Write-Host ""
    Write-Host "是否现在跳转注册并获取 API Key？"
    Write-Host "  Y - 立即跳转至 $CLOUDZONE_URL"
    Write-Host "  N - 我已有 Key，自行输入"
    $choice = Read-Host "请选择 [Y/N]"

    $apiKey = ""
    if ($choice -eq "Y" -or $choice -eq "y") {
        Write-Info "正在打开浏览器..."
        try {
            Start-Process "$CLOUDZONE_URL"        # Windows 默认浏览器打开
        } catch {
            Write-Warn "无法自动打开浏览器，请手动访问：$CLOUDZONE_URL"
        }
        Write-Host "注册后在「我的 API Key」页面复制 Key（以 sk- 开头）。"
        # Read-Host -AsSecureString 不回显，但返回 SecureString 需转明文用于写入配置文件
        $sec = Read-Host "粘贴你的 API Key" -AsSecureString
        $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)
        $apiKey = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
        [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
    } else {
        $sec = Read-Host "请输入你的 API Key (sk-...)" -AsSecureString
        $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)
        $apiKey = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
        [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
    }

    if ([string]::IsNullOrWhiteSpace($apiKey)) {
        Write-Err "未输入 API Key，跳过配置。可稍后手动设置。"
        return $false
    }

    # 写入 OpenCode 全局配置文件
    $opConfDir = "$env:USERPROFILE\.local\share\opencode"
    if (-not (Test-Path $opConfDir)) {
        New-Item -ItemType Directory -Path $opConfDir -Force | Out-Null
    }
    $opConf = "$opConfDir\opencode.json"

    if (Test-Path $opConf) {
        Write-Warn "已有配置文件 $opConf，将备份为 opencode.json.bak"
        Copy-Item $opConf "$opConfDir\opencode.json.bak" -Force
    }

    # 使用 PowerShell 哈希表构建 JSON（安全，不会因 Key 中的特殊字符破坏 JSON 结构）
    $config = [ordered]@{
        '$schema' = 'https://opencode.ai/config.json'
        provider  = [ordered]@{
            openai = [ordered]@{
                options = [ordered]@{
                    apiKey  = $apiKey
                    baseURL = $CLOUDZONE_API_BASE
                }
            }
            anthropic = [ordered]@{
                options = [ordered]@{
                    apiKey  = $apiKey
                    baseURL = $CLOUDZONE_API_BASE
                }
            }
        }
        model = 'openai/gpt-5.1-codex'
    }
    $config | ConvertTo-Json -Depth 5 | Set-Content -Path $opConf -Encoding UTF8

    $masked = if ($apiKey.Length -gt 10) { $apiKey.Substring(0, 10) + "********" } else { "********" }
    Write-Info "配置完成！"
    Write-Host "  配置文件: $opConf"
    Write-Host "  API Key : $masked"
    Write-Host "  Base URL: $CLOUDZONE_API_BASE"
    Write-Host ""
    Write-Info "启动 OpenCode 后输入 /models 即可看到可用模型列表"
    return $true
}

# ---------- 第 4 步：验证安装 ----------
function Verify-Installation {
    Write-Step "验证安装..."
    if (Get-Command opencode -ErrorAction SilentlyContinue) {
        try {
            $ver = opencode --version 2>$null
            if ($ver) { Write-Info "OpenCode 安装成功：$ver" }
        } catch {
            Write-Info "OpenCode 安装成功"
        }
        return $true
    } else {
        # npm 全局安装的 bin 目录可能不在 PATH 中
        try {
            $npmPrefix = npm config get prefix 2>$null
            if ($npmPrefix) {
                Write-Warn "opencode 命令未在 PATH 中找到。请尝试："
                Write-Warn "  关闭 PowerShell 窗口重新打开，或手动将以下路径添加到 PATH："
                Write-Warn "  $npmPrefix"
            }
        } catch {}
        return $true
    }
}

# ---------- 主流程 ----------
Write-Host "============================================"
Write-Host "  OpenCode 入门教程 一键脚本"
Write-Host "  适用于 Windows"
Write-Host "  默认接入：云间 API 中转站"
Write-Host "============================================"
Write-Host ""

$net = Detect-Network

if (-not (Install-NodeJS -Net $net)) {
    Write-Err "Node.js 安装失败，脚本终止。请按上方提示手动处理。"
    exit 1
}

if (-not (Install-OpenCode -Net $net)) {
    Write-Err "OpenCode 安装失败，脚本终止。请按上方提示手动处理。"
    exit 1
}

Configure-Api | Out-Null

Verify-Installation | Out-Null

Write-Host ""
Write-Host "============================================"
Write-Info "全部完成！"
Write-Host ""
Write-Host "  启动方式：在终端输入 opencode 回车"
Write-Host "  首次使用：在 TUI 中输入 /init 分析项目，生成 AGENTS.md"
Write-Host "  切换模型：输入 /models 查看可用模型列表"
Write-Host "  获取帮助：输入 /help 或见博客正文"
Write-Host "============================================"