OpenCode V2安装到第一次受控代码修改

开始改代码前先核对 OpenCode 的结束事件

OpenCode 1.3.13；本地请求回放。请求轨迹和退出码见回执。

在隔离项目设置自定义 provider，执行 opencode run --format json --model qrfixture/qwen3.8-flash。

检查 JSON 事件中的文本与 step_finish，不把进程退出码当唯一证据。

连接通过后再运行原教程的代码样例，并用 git diff 与原测试核对实际改动。

本次补测没有让模型编辑仓库；原教程中的代码改动仍需单独验收。

• 通过：有 step_finish 事件
• 通过：有可验收结果

python3 lab.py --output ./result o03

• 查看脱敏执行回执
• 返回 OpenCode 专题
• 查看相关官方说明

1. 先确认要用V2，不把V1命令当成另一套软件

V1和V2默认都提供opencode命令，不能按默认方式并装。V1文档的opencode-ai与V2文档的@opencode/cli是不同安装入口；先记录已有命令的来源和版本，再按官方迁移说明选择。

已有V1配置不等于必须重写：当前V2仍支持受支持的V1配置，原生V2格式是可选。先保留原配置副本；不要把下面原生V2字段逐项混入一个V1 Provider条目。

• 官方V1迁移到V2：兼容范围与例外

2. 从当前V2渠道选择一种安装方式

以下是当前官方给macOS/Linux列出的一种npm安装入口，供读者在自己的环境选择；本页没有执行它。也可使用官方V2的Homebrew渠道或单独二进制。不要连续执行多种安装方式来覆盖同名命令。

安装后新开终端，核对命令路径和完整版本；若仍显示V1，先查PATH与原安装来源。Windows当前V2文档提供原生二进制，不能直接把本段包管理器步骤泛化到所有Windows环境。

npm install -g @opencode/cli
command -v opencode
opencode --version

• 核对当前平台的V2安装入口

3. 在全新练习目录保存待修实现

新建一个空文件夹，只放下面两份原创文本。任务不是金额精度或日期排序：它只给用户输入加“任务：”前缀，要求去掉首尾空白，并对纯空白拒绝生成标签。

先保留label.py原件。这段是刻意不完整的作者输入。本站只在本地内存中核对过它与手工参考的测试表现，不是OpenCode或模型输出。

def task_label(text):
    return "任务：" + text

4. 保存不允许模型修改的三项原测试

把测试保存为同目录的test_label.py。读者先在该目录运行python3 -m unittest -v，保存真实失败和退出码；按输入合同，修复后应满足这三项检查。

作者在本地内存中运行这三项测试：原始实现有两项失败，手工参考实现三项通过；没有安装或调用OpenCode。读者仍需在自己的工作目录保存真实失败与修复日志，不能把作者参考结果当成自己的会话结果。

import unittest
from label import task_label

class LabelTest(unittest.TestCase):
    def test_trim(self):
        self.assertEqual(task_label("  上线检查  "), "任务：上线检查")

    def test_plain(self):
        self.assertEqual(task_label("复查"), "任务：复查")

    def test_blank(self):
        with self.assertRaises(ValueError):
            task_label("   ")

if __name__ == "__main__":
    unittest.main(verbosity=2)

5. 核对原生V2 Provider、执行宿主和权限

已有可用模型可以继续使用。需要自定义OpenAI兼容Provider时，当前官方V2示例使用providers、package、settings与env；将下面模型占位键换成自己令牌实际可用、且支持所需工具协议的准确ID。

下例是按官方结构编写的apizt填写参考，未在V2连接验证。密钥由自己的安全启动环境提供，不放进文件。V2默认使用共享后台服务；先确认实际进程读取的配置和凭据，不能只看当前终端变量存在。

• V2原生权限为有序permissions数组；后匹配规则、其他配置和Agent规则会影响有效行为。上述片段不是系统沙箱，也不替你检查全部既有配置。
• 每次看清编辑路径、工作目录与命令再决定授权。提示词限定只改label.py，但仍须用最终文件检查确认。
• 官方支持opencode --standalone运行私有服务；只在自己的练习环境选用，不随意重启其他正在进行的会话。

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "apizt": {
      "name": "apizt",
      "env": [
        "tokenba_API_KEY"
      ],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.apizt.com/v1"
      },
      "models": {
        "MODEL_ID_FROM_CONSOLE": {
          "name": "填写自己的准确型号"
        }
      }
    }
  },
  "permissions": [
    {
      "action": "edit",
      "resource": "*",
      "effect": "ask"
    },
    {
      "action": "shell",
      "resource": "*",
      "effect": "ask"
    },
    {
      "action": "external_directory",
      "resource": "*",
      "effect": "ask"
    }
  ]
}

• V2原生Provider字段与协议
• V2权限的匹配与范围
• V2客户端与后台服务

6. 先读文件和方案，再批准一个实现改动

在这份练习目录启动V2。用/models选择目标模型，/agents选择Agent，或按V2文档用Shift+Tab切换。显式附上@label.py与@test_label.py，先让Plan说明合同。

Plan限制普通项目编辑，但shell仍受权限控制，不能当作所有命令绝不执行的保证。确认方案后选择Build，审阅每次文件/命令请求，只接受当前实现文件所需的改动。

读取@label.py和@test_label.py。
先说明实现为何不符合三个原测试，再给出最小方案。
确认后只修改label.py：去掉输入首尾空白，纯空白抛ValueError，其余返回“任务：”加处理后的文本。
不要改测试、添加依赖、处理其他目录或发布任何内容。
返回实际文件diff和运行原测试的工具输出；没有执行就明确说明。

• V2的文件附件、模型与Agent入口

7. 自己回读文件并独立运行原测试

确认label.py确实在当前工作目录落盘，test_label.py与原件一致。再独立运行相同测试，核对首尾空格、普通文本、纯空白三项结果；只有模型的文字承诺或一段贴出的补丁，都不算完成。

如果建立过Git基线，再检查git diff --name-only和逐文件diff。Python运行产生的缓存与允许改动的源码分开看。遇到误改可先审差异，再按官方/undo操作确认回退范围；此处没有演示已执行的回退。

python3 -m unittest -v
# 仅当你已经保存Git基线时，再检查：
git diff --name-only
git diff -- label.py test_label.py

• 下一步：用原测试修复金额精度问题
• 也在用Cline？看文件与会话恢复的区别

8. Cline、OpenCode、Continue：先按当前任务选入口

这是一张操作入口表，不是同任务性能评测。Cline和Continue也有其他客户端，OpenCode也不只终端；下面只比较本批文章涉及的具体用法。

• Cline恢复练习
• Continue本地文档上下文
• Continue YAML与模型角色

9. 失败与费用按实际阶段记录

安装或命令路径问题发生在模型调用之前，先查版本和来源；认证、模型或协议错误看脱敏HTTP状态与最终端点；文字成功但工具失败，再看模型能力、权限和真实工具响应。不要把这些都归因于余额。

Plan、Build、失败与重试都可能产生请求。先按一次完整任务保留模型、请求ID、usage和结果，再对照实际账单；本页没有V2在线运行或真实任务价格，不承诺比官方、订阅或其他服务便宜。

V2当前不运行语言服务器或生成LSP诊断，不能把旧V1的LSP记录当成V2通过。本题直接用原始unittest结果验收。

实际V2版本 / 安装来源：
执行宿主与配置来源：
Provider / 准确模型 / 协议：
原测试基线 / 修改后结果：
实际变更文件 / 工具结果：
失败与重试：
全部usage / 控制台实扣：未核对时留空
未完成或未验证项：

怎样确认已经完成

• 版本、安装来源和执行宿主清楚，未把V1单轮记录套用到V2。
• 自己的label.py满足trim、普通文本和blank三个原测试，test_label.py未被改动。
• 实际文件改动、工具执行和独立复跑结果分别保存；作者输入、预期结果与用户会话不混淆。
• 全部请求、失败和费用未知项保留；本地作者fixture核验不等于原生任务，本文未安装V2或付费调用模型。

常见问题

资料来源

• OpenCode V2官方安装（2026-10-23核对，未锁补丁版）
• OpenCode V1→V2：兼容配置、命令冲突与不支持项
• OpenCode V2：原生Provider、env与settings
• OpenCode V2 TUI：附件、模型、Agent与undo
• OpenCode V2：共享服务与standalone入口
• OpenCode V2：Build与Plan的范围
• OpenCode V2：有序权限与实际资源
• Cline当前IDE操作入口，用于任务选择对照
• Continue当前模型角色与YAML参考
• OpenCode 官方参考