OpenCode 安装配置指南（Windows）

一、前置依赖

依赖	版本要求	安装方式
Node.js	18+	官网下载，LTS版本即可
Git	最新	官网下载
VS Code	最新	官网下载
讯飞Coding Plan	-	官网注册，获取以下参数

讯飞CodingPlan参数（注册后在控制台获取）：

apiKey: <你的apiKey>
modelId: astron-code-latest
baseURL: https://maas-coding-api.cn-huabei-1.xf-yun.com/v2

⚠️ apiKey是敏感信息，切勿泄露或提交到Git仓库。

二、安装OpenCode CLI

打开PowerShell（推荐）或CMD，执行：

npm install -g opencode

验证安装：

opencode --version

全局安装路径通常在 C:\Users\<用户名>\AppData\Roaming\npm\

三、安装VSCode扩展

打开VSCode
进入扩展商店（Ctrl+Shift+X）
搜索 OpenCode
安装官方扩展

四、配置目录说明

OpenCode的配置目录位于 C:\Users\<用户名>\.config\opencode\。

4.1 哪些是自动生成的

首次启动OpenCode后，以下文件会自动生成，无需手动创建：

文件	生成时机	说明
`opencode.json`	首次启动OpenCode	主配置文件，但内容为空或默认值，需要手动编辑填入provider和plugin配置
`oh-my-openagent.json`	安装oh-my-openagent插件	需要手动编辑填入模型和prompt配置

这两个文件虽然会自动创建，但内容需要你手动填写。直接用第七节、第八节的完整JSON内容覆盖即可。

4.2 哪些需要手动创建

skills/ 目录不会自动生成，需要手动创建：

mkdir $env:USERPROFILE\.config\opencode\skills

后续所有自建Skill的.md文件都放在这个目录下。

4.3 完整操作流程

有两种方式完成配置，选择其一即可：

方式A：交互式配置（推荐新手）

# 1. 启动 OpenCode，按提示选择 provider 并填入 API Key
opencode

# 2. 退出 OpenCode（输入 /exit 或 Ctrl+C）

# 3. 创建 skills 目录
mkdir $env:USERPROFILE\.config\opencode\skills

# 4. 手动补充 opencode.json 中的 plugin 字段（交互式配置不会自动添加）
#    以及手动创建 oh-my-openagent.json（见第七节、第八节）
cd $env:USERPROFILE\.config\opencode
# 用 VS Code 或记事本编辑 opencode.json 和 oh-my-openagent.json

方式B：手动配置（推荐有经验者）

# 1. 创建skills目录
mkdir $env:USERPROFILE\.config\opencode\skills

# 2. 直接用第七节、第八节的完整JSON内容创建opencode.json和oh-my-openagent.json
cd $env:USERPROFILE\.config\opencode
# 用VS Code或记事本创建这两个文件

# 3. 启动OpenCode，配置已就绪
opencode

后续所有操作都在 C:\Users\<用户名>\.config\opencode\ 目录下进行。

五、安装oh-my-openagent插件

oh-my-openagent是OpenCode的Agent编排插件，负责管理各Agent的模型、prompt和行为配置。

npm install -g oh-my-openagent

验证：

npm list -g oh-my-openagent

安装后无需手动操作，OpenCode启动时通过opencode.json中的plugin字段自动加载。

六、安装Superpowers技能库

Superpowers是一个开源的通用工作流技能库，提供调试、TDD、计划编写等标准化工作流。

cd $env:USERPROFILE\.config\opencode
git clone https://github.com/obra/superpowers.git

验证目录结构：

ls .\superpowers\skills\

应看到 brainstorming/、systematic-debugging/、test-driven-development/ 等目录。

安装后无需手动注册，OpenCode启动时通过opencode.json中的plugin路径自动加载。

七、配置opencode.json

文件路径：C:\Users\<用户名>\.config\opencode\opencode.json

{
  "schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-openagent",
    "superpowers/.opencode/plugins/superpowers.js"
  ],
  "provider": {
    "astroncodingplan": {
      "name": "科大讯飞",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
        "astron-code-latest": {
          "name": "Astron Coding Plan",
          "limit": {
            "context": 200000,
            "output": 64000
          }
        }
      },
      "options": {
        "baseURL": "https://maas-coding-api.cn-huabei-1.xf-yun.com/v2",
        "apiKey": "<你的apiKey>"
      }
    }
  }
}

字段说明：

字段	作用
`plugin`	加载插件：`oh-my-openagent`（Agent编排）+ `superpowers`（技能库）
`provider`	配置AI模型提供商的API连接信息
`provider.astroncodingplan`	提供商名称（小写，与`oh-my-openagent.json`中的model前缀对应）
`npm`	SDK包名，讯飞用`@ai-sdk/openai-compatible`
`models.astron-code-latest`	模型ID和上下文/输出长度限制
`options.apiKey`	敏感信息，勿泄露

八、配置oh-my-openagent.json

文件路径：C:\Users\<用户名>\.config\opencode\oh-my-openagent.json

此文件控制各Agent使用的模型和追加提示词。

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": {
      "enabled": true,
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n## 用户偏好\n\n**重要：始终使用中文回复。**"
    },
    "build": {
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    },
    "explore": {
      "enabled": true,
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    },
    "librarian": {
      "enabled": true,
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    },
    "oracle": {
      "enabled": true,
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    },
    "prometheus": {
      "enabled": true,
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    },
    "metis": {
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    },
    "momus": {
      "model": "astroncodingplan/astron-code-latest",
      "prompt_append": "\n\n**重要：始终使用中文回复。**"
    }
  }
}

字段说明：

字段	作用
`agents.<name>.model`	格式 `<provider>/<model_id>`，对应`opencode.json`中的配置
`agents.<name>.prompt_append`	追加到Agent系统提示词末尾（如语言偏好）
`agents.<name>.enabled`	是否启用该Agent（默认`true`）

⚠️ 不需要配置categories。平台内置分类会自动使用对应Agent的模型，手动覆盖是冗余的。

九、核心概念：Agent vs Skill

理解这个区分，才能正确使用和扩展OpenCode。

Agent（平台内置，不可新建）

OpenCode内置了一组Agent，用户不能创建新Agent类型，只能通过oh-my-openagent.json配置其模型和prompt：

Agent	角色	调用方式
`sisyphus`	主Agent（对话入口）	自动
`build`	通用任务执行	`task(category=...)`
`explore`	探索/搜索	-
`librarian`	知识库/文档	-
`oracle`	深度分析	-
`prometheus`	性能/监控	-
`metis`	架构/设计	-
`momus`	测试/质量	-

Skill（用户可创建，自由扩展）

Skill是存储在skills/目录下的Markdown文件，定义特定领域的专业知识、工作流或规范。通过斜杠命令或task(load_skills=[...])加载给Agent使用。

十、Skill编写指南

10.1 Skill文件结构

每个Skill是一个.md文件，建议包含以下章节：

# Skill名称

## 角色定义
你是一个...专家

## 核心能力
- 能力1
- 能力2

## 工作流程
1. 步骤1
2. 步骤2

## 约束
- 约束1
- 约束2

10.2 基础Skill（4个，必建）

覆盖嵌入式软件开发的核心工作流：编码、审查调试、测试、文档。

Skill文件	是否必要	理由
`coder.md`	☑ 必要	编码是最高频操作，没有coder则主Agent只能按通用方式写代码，无法贴合项目风格和约束
`reviewer-debugger.md`	☑ 必要	嵌入式代码的时序、内存、并发问题远比Web开发复杂，通用审查无法覆盖
`tester.md`	☑ 必要	嵌入式测试需关注硬件边界、中断时序、资源竞争，通用测试Skill不会考虑这些
`tech-writer.md`	☑ 必要	嵌入式文档需包含寄存器描述、时序图、内存布局，通用文档Skill不会生成这些

10.3 进阶Skill（6个，按需新建）

Skill文件	是否必要	解决的痛点	什么时候该建
`architect.md`	按需	架构设计缺乏系统性，线程模型/内存池/模块边界靠经验拍板	项目启动阶段，或重构时需要系统性架构决策
`builder.md`	强烈推荐	构建排障是嵌入式开发最耗时的日常操作，环境变量/依赖链/交叉编译问题频发	几乎任何嵌入式项目都会遇到构建问题，建议尽早创建
`optimizer.md`	按需	性能问题（时延/吞吐/Cache）难以定位，需要CPU绑核、NUMA、无锁等专业优化知识	项目进入性能调优阶段
`log-analyzer.md`	按需	运行时日志/抓包分析门槛高，perf/内核日志/协议报文解读需要专业知识	需要分析运行时行为、定位偶发问题
`protocol.md`	按需	协议规范与代码实现对不上，报文格式/帧结构/信道流程需要对照协议文档	项目涉及协议实现（如前传接口、串口协议、网络协议栈）
`sysadmin.md`	按需	系统部署配置繁琐，大页/核隔离/中断/网卡绑定等需要专业知识	需要配置目标运行环境（Linux实时系统、DPDK等）

建议策略：先建4个基础Skill → 遇到构建问题就加builder → 遇到性能问题就加optimizer → 依此类推。每个Skill的.md内容根据你的项目技术栈定制。

十一、Skill使用方法与实操举例

方式1：斜杠命令（直接对话，加载到当前会话）

在OpenCode对话框中输入/技能名，Skill内容会注入当前会话上下文，后续对话都会遵循该Skill的规范。

/coder 优化现有C代码逻辑，简化冗余判断
/tech-writer 绘制模块分层Mermaid架构图
/reviewer-debugger 分析该函数执行时序与卡顿风险
/tester 为当前函数生成完整单元测试用例

适用场景：简单任务，你自己直接指挥，不需要子Agent介入。

方式2：task委托（主Agent指派子Agent+Skill执行）

主Agent（sisyphus）通过task()将工作委托给子Agent，同时加载Skill注入专业知识。这是最常用的方式，主Agent负责拆解和编排，子Agent负责执行。

示例1：简单编码任务

task(category="quick", load_skills=["coder"], prompt="重构内存分配函数，添加错误日志")

→ 主Agent委派一个quick类子Agent，加载coder Skill，执行重构。

示例2：深度分析任务，组合多个Skill

task(category="deep", load_skills=["tech-writer","protocol"], prompt="分析上行随机接入数据流，生成时序图")

→ 子Agent同时具备文档写作能力（tech-writer）和协议知识（protocol），输出带时序图的协议分析文档。

示例3：构建排障

task(category="quick", load_skills=["builder"], prompt="编译报错undefined reference to dma_init，排查原因")

→ 子Agent加载builder Skill，知道如何排查链接错误、依赖链、环境变量。

示例4：性能优化

task(category="deep", load_skills=["optimizer","coder"], prompt="分析下行处理器径时延，优化内存池锁竞争")

→ 子Agent同时具备性能分析能力和编码能力，能定位问题并给出代码修改方案。

参数说明：

参数	作用	常用值
`category`	任务复杂度，决定子Agent的模型和工具集	`quick`（单文件改动）、`deep`（需要深度研究）、`ultrabrain`（高难度逻辑）
`load_skills`	要加载的Skill列表，对应`skills/`下的文件名（不含`.md`）	`["coder"]`、`["tech-writer","protocol"]`
`prompt`	具体任务描述	越具体越好

方式3：主Agent自动匹配

当你在对话中描述一个任务时，主Agent会根据任务性质自动选择合适的子Agent和Skill：

你：帮我排查编译报错 "undefined reference to dma_buffer_init" → 主Agent自动调用 task(category="quick", load_skills=["builder"], prompt="...")
你：写一份内存管理架构文档，要有时序图 → 主Agent自动调用 task(category="deep", load_skills=["tech-writer"], prompt="...")

你不需要手动指定category和load_skills，主Agent会判断。但如果你发现它选错了Skill，可以明确指定。

十二、Superpowers内置技能

Superpowers仓库提供通用工作流技能，与自建Skill互补。每个技能是一个目录，内含SKILL.md定义文件：

技能目录	用途
`brainstorming/`	创意探索、需求分析（实施前必用）
`test-driven-development/`	TDD工作流
`systematic-debugging/`	系统化调试
`writing-plans/`	实施计划编写
`executing-plans/`	计划执行
`verification-before-completion/`	完成前验证
`requesting-code-review/`	请求代码审查
`receiving-code-review/`	接收代码审查
`dispatching-parallel-agents/`	并行任务分发
`using-git-worktrees/`	Git worktree隔离开发
`writing-skills/`	编写新Skill的规范

调用方式：通过task(load_skills=[...])加载，或由主Agent根据任务自动匹配。

十三、完整目录结构

安装完成后的目录结构：

C:\Users\<用户名>\.config\opencode\
├── opencode.json                 # 全局配置
├── oh-my-openagent.json          # Agent配置
├── skills/                       # 自建Skill目录
│   ├── coder.md
│   ├── reviewer-debugger.md
│   ├── tester.md
│   ├── tech-writer.md
│   ├── architect.md
│   ├── builder.md
│   ├── optimizer.md
│   ├── log-analyzer.md
│   ├── protocol.md
│   └── sysadmin.md
└── superpowers/                  # 克隆的Superpowers技能库
    └── skills/                   # 内置技能
        ├── brainstorming/
        ├── systematic-debugging/
        ├── test-driven-development/
        └── ...

十四、工程初始化

VSCode打开项目根目录
打开OpenCode对话面板
执行命令：

/init

自动生成AGENTS.md（项目级知识库，主Agent自动读取）→ 完成全局工程索引加载

十五、OpenCode CLI常用命令

在OpenCode对话框中输入斜杠命令（/开头），可以执行各种操作。输入/后会自动弹出命令列表。

15.1 会话管理（最高频）

命令	作用	说明
`/new`	新建对话	清空当前会话上下文，释放Token占用。长时间对话后Token耗尽时使用
`/compact`	压缩当前对话	将历史对话压缩为摘要，降低Token占用但保留关键上下文
`/exit`	退出OpenCode	关闭当前OpenCode会话
`/undo`	撤销上一条消息	撤销AI最近一次回复及其产生的代码修改，回退到上一轮对话状态
`/fork`	分叉会话	从当前对话分叉出一个新会话，两个会话独立发展，互不影响
`/timeline`	显示对话时间线	可选择跳回历史某条消息继续对话

Token管理策略：

想保留当前工作进度 → /compact
想完全重新开始 → /new
AI刚改坏了代码 → /undo
想同时试两个方向 → /fork

15.2 模型与连接

命令	作用	说明
`/models`	切换模型	在对话中切换当前使用的AI模型（如从Flash切到Pro）
`/agents`	切换Agent	切换当前对话的Agent类型（如从sisyphus切到build）
`/connect`	连接Provider	连接或重新连接AI模型提供商，配置新API时使用
`/mcps`	切换MCP服务	启用/禁用MCP工具服务器

15.3 导出与分享

命令	作用	说明
`/copy`	复制对话记录	将当前会话的完整对话内容复制到剪贴板
`/export`	导出对话记录	将当前会话导出为文件（JSON/Markdown），保存到本地
`/timestamps`	显示时间戳	在对话消息旁显示每条消息的发送时间

15.4 Skill与工具命令

命令	作用	说明
`/coder`	加载编码Skill	注入编码规范和项目风格约束到当前会话
`/reviewer-debugger`	加载审查调试Skill	注入代码审查和问题排查规范
`/tester`	加载测试Skill	注入测试用例生成规范
`/tech-writer`	加载文档Skill	注入技术文档写作规范
`/init`	初始化工程	生成`AGENTS.md`项目知识库，加载工程索引
`/init-deep`	深度初始化	生成层级化的`AGENTS.md`知识库（比`/init`更详细）
`/websearch`	网页搜索	通过Exa搜索引擎查询网络信息

15.5 工作流命令

命令	作用	说明
`/ralph-loop`	启动自动驱动开发循环	Agent自动迭代工作直到任务完成
`/ulw-loop`	启动超工作模式循环	类似ralph-loop但使用ultrawork模式，更激进
`/cancel-ralph`	取消活动循环	停止当前运行的ralph-loop或ulw-loop
`/stop-continuation`	停止所有续行机制	停止ralph loop、todo续行、boulder等所有自动续行

15.6 代码质量命令

命令	作用	说明
`/ai-slop-remover`	清理AI代码异味	移除单个文件中的AI生成代码坏味道
`/remove-ai-slops`	批量清理AI代码异味	清理整个分支变更中的AI代码异味
`/refactor`	智能重构	基于LSP、AST-grep、架构分析的智能重构，带TDD验证

15.7 Git与协作命令

命令	作用	说明
`/git-master`	Git专家模式	原子提交、rebase/squash、历史搜索
`/review-work`	完成后审查	启动5个并行审查Agent
`/handoff`	交接摘要	生成详细的上下文摘要，用于在新会话中继续工作

15.8 浏览器命令

命令	作用	说明
`/playwright`	浏览器自动化	通过Playwright MCP进行浏览器操作、截图、测试
`/dev-browser`	持久化浏览器	带持久页面状态的浏览器自动化

15.9 编辑器

命令	作用	说明
`/editor`	打开编辑器	在外部编辑器（VS Code）中打开当前项目

15.10 命令速查

# 会话管理（最常用）
/new → 清Token，新对话
/compact → 压缩对话，降Token
/exit → 退出
/undo → 撤销上一条AI回复
/fork → 分叉会话，试不同方案

# 模型切换
/models → 切换AI模型（Flash/Pro）
/agents → 切换Agent类型

# Skill加载
/coder → 编码模式
/reviewer-debugger → 审查调试模式
/tester → 测试模式
/tech-writer → 文档模式

# 工程
/init → 初始化工程
/websearch → 联网搜索

# 导出
/copy → 复制对话到剪贴板
/export → 导出对话为文件
/handoff → 生成交接摘要

15.11 终端子命令（在PowerShell中使用）

除了对话内的斜杠命令，OpenCode还有一组终端子命令，在PowerShell中直接执行（不在对话框内）：

子命令	作用	说明
`opencode`	启动TUI	默认启动交互式终端界面
`opencode run "你的问题"`	单次执行	不进入交互界面，直接执行一条指令后退出
`opencode -c`	继续上次会话	恢复最近一次对话，继续之前的工作
`opencode -s <sessionID>`	恢复指定会话	恢复某个历史会话继续对话
`opencode -m provider/model`	指定模型启动	启动时直接指定模型
`opencode models`	列出可用模型	查看当前配置下所有可用的AI模型
`opencode providers`	管理Provider	添加/删除/配置AI模型提供商
`opencode stats`	查看Token统计	显示Token使用量和费用统计
`opencode export <sessionID>`	导出会话	将指定会话导出为JSON文件
`opencode import <file>`	导入会话	从JSON文件或URL导入会话数据
`opencode plugin <module>`	安装插件	安装插件并自动更新配置
`opencode upgrade`	升级OpenCode	升级到最新版本
`opencode pr <number>`	拉取GitHub PR	拉取指定PR的分支并自动启动OpenCode
`opencode session`	管理会话	查看/恢复/删除历史会话

高频用法：

opencode -c — 每天早上恢复昨天的对话继续工作
opencode run "帮我检查这个文件的编译错误" — CI/CD脚本中自动执行
opencode stats — 查看今天的Token消耗情况
opencode models — 确认当前有哪些模型可用

十六、Token与费用

OpenCode界面展示当前会话上下文Token占用，界面金额为虚拟参考价。

真实计费/消耗/余额：登录讯飞星辰CodingPlan控制台查看。

十七、环境生效要求

修改以下文件后，重启VSCode或重启OpenCode扩展即可生效：

opencode.json
oh-my-openagent.json
skills/目录下的.md文件

十八、最简安装：AI辅助一键配置

核心思路：人工只做3件事（装Node.js、装OpenCode、填APIKey），其余全部交给OpenCode自己完成。

18.1 人工步骤（约5分钟）

步骤1：安装Node.js (18+)（如果还没装）从 nodejs.org 下载安装，一路Next。

步骤2：安装OpenCode CLI + oh-my-openagent

npm install -g opencode
npm install -g oh-my-openagent

步骤3：启动OpenCode，填入API Key

opencode

首次启动会进入交互式配置，按提示选择provider并填入API Key。完成后OpenCode就能用了。

如果交互式配置不支持讯飞CodingPlan，则手动编辑 C:\Users\<用户名>\.config\opencode\opencode.json，只需填入第七节中provider部分（apiKey替换为你的真实Key）。

步骤4：把以下提示词复制粘贴给OpenCode

18.2 AI自动完成的提示词

在OpenCode对话框中粘贴以下内容（一次性粘贴，然后回车，让AI自动执行）：

帮我完成以下OpenCode配置，全部自动执行，不需要我确认：

1. 创建skills目录：C:\Users\<你的用户名>\.config\opencode\skills\

2. 在skills目录下创建以下4个基础Skill文件（.md），每个文件内容包含角色定义、核心能力、工作流程、约束四个章节，面向嵌入式C/C++系统软件开发（如实时系统、高速数据面、Linux内核模块）：
   - coder.md：代码编写、模块梳理、调用链分析、代码重构，严格贴合工程现有风格
   - reviewer-debugger.md：代码审查、问题排查、时序分析、日志分析、性能瓶颈定位
   - tester.md：单元测试、边界条件、异常分支、功能校验用例生成
   - tech-writer.md：流程图、时序图、模块说明、接口文档、技术总结

3. 在skills目录下创建以下6个进阶Skill文件（.md），同样面向嵌入式系统开发：
   - architect.md：架构设计、线程模型、内存池规划、模块边界定义、状态机设计
   - builder.md：编译错误、链接失败、环境变量缺失、依赖链断裂、交叉编译配置
   - optimizer.md：CPU绑核、NUMA亲和、Cache优化、时延分析、无锁改造、SIMD利用率
   - log-analyzer.md：运行时日志解读、协议报文解析、perf热点定位、内核消息分析
   - protocol.md：协议报文格式验证、帧结构映射、信道处理流程、压缩算法实现
   - sysadmin.md：大页内存、CPU核隔离、中断亲和、网卡绑定、DPDK EAL参数、内核调优

4. 用以下内容覆盖 C:\Users\<你的用户名>\.config\opencode\oh-my-openagent.json:
   {
     "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
     "agents": {
       "sisyphus": { "enabled": true, "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n## 用户偏好\n\n**重要：始终使用中文回复。**" },
       "build": { "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" },
       "explore": { "enabled": true, "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" },
       "librarian": { "enabled": true, "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" },
       "oracle": { "enabled": true, "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" },
       "prometheus": { "enabled": true, "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" },
       "metis": { "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" },
       "momus": { "model": "astroncodingplan/astron-code-latest", "prompt_append": "\n\n**重要：始终使用中文回复。**" }
     }
   }

5. 在 C:\Users\<你的用户名>\.config\opencode\ 目录下 clone Superpowers 技能库：
   git clone https://github.com/obra/superpowers.git

6. 确认 opencode.json 中 plugin 字段包含以下两项（如果没有则添加）：
   "plugin": ["oh-my-openagent", "./superpowers/.opencode/plugins/superpowers.js"]

7. 完成后输出所有创建/修改的文件清单，让我确认。

提示词中需要替换的内容：

C:\Users\<你的用户名>\ → 替换为你的实际用户目录
如果你用的不是讯飞CodingPlan，把 astroncodingplan/astron-code-latest 替换为你的provider/model（如 google/gemini-2.5-flash）

18.3 执行后验证

AI执行完毕后，检查以下内容：

# 1. 检查skills目录
ls $env:USERPROFILE\.config\opencode\skills\
# 应看到coder.md, reviewer-debugger.md, tester.md, tech-writer.md等10个文件

# 2. 检查superpowers目录
ls $env:USERPROFILE\.config\opencode\superpowers\skills\
# 应看到brainstorming/, systematic-debugging/等目录

# 3. 检查oh-my-openagent.json
cat $env:USERPROFILE\.config\opencode\oh-my-openagent.json
# 应看到8个agent配置，model都是astroncodingplan/astron-code-latest

验证通过后，重启OpenCode（/exit后重新opencode），所有配置即生效。

18.4 人工介入量对比

步骤	完整安装（手动）	最简安装（AI辅助）
安装Node.js	人工	人工（无法替代）
`npm install opencode`	人工	人工（无法替代）
`npm install oh-my-openagent`	人工	人工（无法替代）
填入API Key	人工	人工（敏感信息）
创建skills目录	人工	AI自动
编写10个Skill文件	人工（耗时最长）	AI自动
编辑oh-my-openagent.json	人工	AI自动
`git clone superpowers`	人工	AI自动
配置opencode.json plugin	人工	AI自动
人工操作次数	9步	3步
预计耗时	30-60分钟	5分钟 + AI执行时间

关键洞察：AI能帮你的前提是OpenCode已经能跑起来（有APIKey）。所以人工的3步都是“让AI活过来”的必要条件，之后就可以让AI自己干活了。

十九、免费模型方案（无付费API也可使用）

如果公司未购买CodingPlan或其他付费API，以下方案可以零成本使用OpenCode进行学习和实践。

方案1：Google Gemini API免费额度（推荐）

Google AI Studio提供业界最慷慨的免费额度，无需信用卡，永久有效：

项目	免费额度
Gemini 2.5 Flash	1,500 请求/天，1M tokens/分钟
Gemini 2.5 Pro	50 请求/天
注册要求	Google账号，无需信用卡
有效期	永久（不会过期）

⚠️ 免费额度下，Google可能使用你的请求数据训练模型。生产环境慎用。

配置方法：

访问 Google AI Studio，用Google账号登录
点击“Get API Key”，生成免费API Key
修改opencode.json：

{
  "schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-openagent",
    "./superpowers/.opencode/plugins/superpowers.js"
  ],
  "provider": {
    "google": {
      "npm": "@ai-sdk/google",
      "name": "Google Gemini",
      "options": {
        "apiKey": "<你的Google API Key>"
      },
      "models": {
        "gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash",
          "limit": { "context": 1000000, "output": 65536 }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro",
          "limit": { "context": 1000000, "output": 65536 }
        }
      }
    }
  }
}

修改oh-my-openagent.json，将所有Agent的model改为： "model": "google/gemini-2.5-flash"
重启OpenCode扩展

Gemini 2.5 Flash速度快、额度大，适合日常编码。Gemini 2.5 Pro推理更强但每天只有50次，留给复杂任务。

方案2：本地模型 Ollama（完全离线）

如果有GPU机器，可以运行本地模型，完全免费，无需网络。

安装Ollama
拉取模型：ollama pull codellama:34b 或 ollama pull deepseek-coder-v2
修改opencode.json：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/ollama",
      "name": "ollama Local",
      "options": {
        "baseURL": "http://localhost:11434"
      },
      "models": {
        "codellama:34b": {
          "name": "Code Llama 34B"
        }
      }
    }
  }
}

本地模型质量取决于模型大小和GPU算力。34B参数的Code Llama在代码补全上可用，但复杂推理不如云端大模型。

方案3：OpenRouter免费模型聚合

OpenRouter聚合多家模型提供商，部分模型提供免费额度。

注册OpenRouter账号
获取API Key
配置为OpenAI兼容provider：

{
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "<你的OpenRouter API Key>"
      },
      "models": {
        "deepseek/deepseek-chat:free": {
          "name": "DeepSeek Chat Free"
        }
      }
    }
  }
}

免费方案对比

方案	成本	模型质量	速度	离线可用	适合场景
Gemini API免费额度	0	★★★★★	快	×	首选，日常编码学习
Ollama本地模型	0（需GPU）	★★★★	中	✓	内网环境、数据敏感
OpenRouter免费模型	0	★★★★	慢	×	尝试不同模型

二十、常见问题

Q: 为什么不需要新建Agent？

OpenCode平台的Agent是内置的（sisyphus/build/explore/oracle等），用户不能创建新Agent类型。扩展系统能力的方式是创建Skill（.md文件），通过/命令或task(load_skills=[...])加载给已有Agent使用。

Q: Skill和Superpowers内置技能的关系？

自建Skill（skills/目录）：定义你的项目/领域专业知识（如嵌入式开发规范、协议知识）
Superpowers技能（superpowers/skills/目录）：定义通用工作流（如TDD、调试流程、计划编写）
两者互补：Superpowers告诉Agent怎么做（流程），自建Skill告诉Agent做什么（领域知识）

Q: oh-my-openagent.json和opencode.json的区别？

文件	职责	内容
`opencode.json`	全局配置	provider（API连接）、plugin（插件加载）
`oh-my-openagent.json`	Agent配置	各Agent的模型、prompt、启用状态

Q: 为什么不需要配置categories？

categories是平台内置的任务分类（quick/deep/ultrabrain等），其模型会自动跟随oh-my-openagent.json中对应Agent的model设置。手动覆盖是冗余的，反而可能影响平台升级。

Q: PowerShell和CMD有区别吗？

npm命令在两者中通用。本文推荐PowerShell，因为mkdir -p和环境变量语法（$env:USERPROFILE）更方便。CMD中需用mkdir和%USERPROFILE%。

Q: 免费模型够用吗？

对于学习和日常编码，Gemini 2.5 Flash的免费额度（1,500次/天）完全够用。对于复杂架构设计、长代码生成等需要强推理的场景，付费模型（如讯飞Coding Plan、Claude）效果更好。建议先用免费方案上手，确认有价值后再考虑付费。

基于 Windows 环境实践整理，OpenCode + 讯⻜ Coding Plan 验证通过