OpenCode + TRAE CN + Superpowers 项目源码配置实战指南

简介这份源码包面向需要在 OpenCode 与 TRAE CN 环境中配置 Superpowers 插件及 ui-ux-pro-max 技能的开发者聚焦 AI 工具链的高效搭建适合追求高质量可运行代码、强化前端界面体验的中高级开发者也可供团队统一代码生成规范参考。压缩包共 3 个文件以 inscode 配置为主辅以 HTML 说明页与 .gitignore 忽略规则分别用于项目配置、使用说明和版本忽略项整体仅 6KB轻量精简便于解压后直接对照或导入工作区。目前已有 2094 人学习下载。包内示例浓缩了插件仓库克隆、符号链接与目录结构设置、技能启用方法以及通过 AGENTS.md 或 opencode.json 写入严格代码生成规则的操作要点并针对 TRAE CN 插件路径不一致问题给出专门处理建议同时提供 PowerShell 常用命令与常见报错排查思路覆盖安装到验证的完整链路。开发者可将这套资源作为最小化配置模板复用已验证的插件、技能和规则组合快速搭建可运行环境、规避重复踩坑显著提升代码生成的一致性和开发效率。1. 为什么我要把 OpenCode、TRAE CN、Superpowers 三样东西拼在一起做 AI 编码实践的这几年我最常被问到的组合就是 OpenCode 与 TRAE CN 的 Superpowers 配置。原因很直接TRAE CN 的编辑器体验足够顺手但内置 Agent 在某些场景下不够可控OpenCode 作为终端里的编码 Agent能把模型、权限、技能都摊开给你调而 Superpowers 恰好是一套以技能为单位的配置源码包补上了“提示词工程”里最难攒的那部分。标题里挂着“项目源码”说明这东西不是看一篇教程就完事而是要落到本地的目录、配置文件和技能仓库里。这篇就把我自己的配置路径、参数选择和踩过的坑一次讲清楚适合那些已经在用 AI IDE、但对内置能力不够满意想保留编辑器、同时把命令行 Agent 真正用起来的人。2. 三件事先对齐OpenCode 是什么TRAE CN 是什么Superpowers 又是什么2.1 OpenCode在终端里跑的编码 Agent不是 IDEOpenCode 是一个面向终端的开源编码 Agent。它没有传统 IDE 的侧边栏和面板启动后就是一个交互式的命令行界面你输入需求它读项目文件、改代码、跑命令然后把改动写回磁盘。很多人第一次打开会不适应觉得“这不就是一个黑匣子终端吗”实际上它的核心优势恰恰在这里所有行为都受本地配置控制模型路由、工具权限、系统提示词都可以按项目拆开管理。安装上我一般用 npm 全局装命令很简单。装完之后在项目目录下执行opencode就能进入交互界面。它会读取当前目录下的配置文件把项目当作上下文。和直接在 IDE 里用 Agent 相比OpenCode 的差异在于它是独立的进程不绑架编辑器的运行方式也不依赖某个 IDE 版本的更新节奏。我平时会同时开两个窗口TRAE CN 负责浏览代码和写文档终端里跑 OpenCode 处理批量重构和跨文件改动。这样分工的好处是Editor 卡住的时候 Agent 还能干活Agent 改出问题的时候编辑器里还能直接看 diff 回滚。OpenCode 的对话历史、工具调用记录都落在本地目录里路径清晰查问题不需要翻 IDE 的日志。2.2 TRAE CN一个愿意把终端交出去的 IDE 宿主TRAE CN 是字节推出的 AI 原生 IDE 的国内版本内置了 Builder、Agent 这类功能能直接在编辑器里生成代码、改文件、执行命令。它本身的能力不弱但内置 Agent 的提示词、模型选择、工具范围基本是封装好的你想控制“它到底该先读哪个文件、用哪个模型、允不允许执行某条命令”能动的空间有限。把 OpenCode 放进 TRAE CN准确说法是把 OpenCode 跑在 TRAE CN 的内置终端里。TRAE CN 的内置终端就是普通的 shell你可以在里面启动 OpenCode两个工具共享同一个项目目录文件改动互相可见。这种组合的好处是你仍然用 TRAE CN 的界面看代码、看报错、做 diff但真正动手改大范围的代码时交给 OpenCode 去执行TRAE CN 只负责展示结果。值得提醒的是TRAE CN 在 Windows 下默认终端可能是 PowerShell 或 cmd而 OpenCode 的交互界面在 PowerShell 里偶尔会有渲染问题。我一般会在 TRAE CN 的终端设置里把默认 shell 切成 Git Bash 或 WSL 的 bash再启动 OpenCode。这一步不是必须的但能省掉不少 ANSI 转义、按键绑定之类的玄学问题。2.3 Superpowers把提示词工程变成可管理技能的源码包Superpowers 是一个以“技能skill”为单位的开源配置源码包。它不是一个插件也不是一个需要常驻的服务而是一套有固定目录结构的文本和脚本集合。每个技能一个目录里面通常有一个说明文件比如 SKILL.md和若干辅助脚本描述“这个技能在什么场景下用、需要读哪些文件、按什么步骤输出”。Agent 读到这些说明后就知道在对应场景下该怎么表现。我接触这套东西之后最大的感受是以前调 Agent 靠反复改提示词改到最后自己都忘了哪个版本有效Superpowers 把提示词拆成了一张张“技能卡片”按需加载。和新手说清楚一点它本身不绑定某个特定编码工具OpenCode 能用其它支持 AGENTS.md 或自定义命令的 Agent 也能用。标题里说“项目源码”指的就是这套技能仓库——你得把它 clone 到本地然后告诉 OpenCode 去哪儿找它。2.4 为什么会有人把它们三个拼起来一条请求的实际流转路径三个工具拼在一起实际跑通一条请求的路径是这样你在 TRAE CN 的内置终端里输入opencode并回车OpenCode 启动后读取当前目录下的opencode.json和AGENTS.md配置文件AGENTS.md里写着项目规范也可能写着加载哪些技能当你提出一个需求OpenCode 把需求连同相关技能说明一起发给配置好的模型模型如果想读文件或执行命令OpenCode 会按opencode.json里的权限规则决定放行还是询问你改动写回磁盘后TRAE CN 因为监听文件变化会自动在编辑器里刷新出来。这条链路里每个环节的配置点都是独立的所以排查问题也很方便模型不回复先看 provider 配置工具没生效先看 skills 目录路径TRAE CN 没刷新看文件是不是真的写到了当前工作区。把这条链路记在脑子里后面所有配置步骤都会变得有依据。3. 安装与初始化在 TRAE CN 里把 OpenCode 先跑起来3.1 安装方式与 Shell 选择先装 OpenCode。我常用的安装方式是通过 npm 全局安装Node.js 环境已经有的话直接执行下面这条命令# 全局安装 OpenCode CLI装完直接有 opencode 命令 npm install -g opencode/cli # 验证安装结果 opencode --version这段命令的作用是把 OpenCode 的 CLI 装到全局 node 目录下后续在任何项目目录里都能直接调用opencode命令。参数说明-g表示全局安装避免每个项目重复装如果你在公司内网有私有 npm 镜像安装前先确认镜像里的包版本和官方源一致。Windows 用户需要注意 shell 的选择。我见过最多的问题是 OpenCode 在 PowerShell 里渲染异常、按键失效表现就是方向键不能用、输出乱码。常见做法是给 TRAE CN 的终端配置 WSL2 或 Git Bash。如果你用的是 Win10 且没装 WSL2建议先补上再跑 OpenCode实在不想装 WSLGit Bash 也能凑合但个别交互按键还是会有差异。macOS 用户就简单很多直接换到 iTerm2 或系统自带 Terminal 都行。安装完成后进到你的项目目录先跑一次opencode看看能不能正常启动这一步能提前暴露 Node 版本、PATH 配置之类的基础问题。3.2 最小可用的 opencode.json 配置样例OpenCode 在项目目录下靠opencode.json决定模型和权限。我一般不会一上来就写满配置而是先用一个最小可用的版本把链路跑通再逐步加东西。下面这个是我常用的起点{ $schema: https://opencode.ai/schema.json, provider: { default: myprovider }, model: { default: myprovider/my-model }, permission: { allow: [ read, edit, command:run:node ], deny: [ command:run:rm -rf ] } }这段配置做了三件事把默认 provider 指到myprovider把默认模型指到该 provider 下的一个具体模型再定义工具权限。逻辑说明OpenCode 不会自动猜测你该用哪家模型所以 provider 和 model 必须显式写permission里allow表示放行的操作edit是文件编辑command:run:node表示允许执行 node 命令deny则用来拦截危险命令。参数说明$schema字段是为了让编辑器给你配置提示不是必须provider的名字如果是自定义的必须在配置里同时写清楚这个 provider 的 API 地址和 key 从哪里读command:run:node这种写法是“允许跑 node 命令但不允许跑其它 shell 命令”比直接全放行安全得多。每次改完配置重启 OpenCode 才会重新加载。3.3 第一次启动登录、验证与模型可用性配置写好后第一次启动 OpenCode 要确认模型能不能通。不同模型服务的登录方式不一样但流程基本是在 OpenCode 里执行登录命令粘贴 API key然后再启动对话。# 如果用的是需要登录的服务商先登录 opencode auth login # 以交互模式启动 OpenCode opencode # 在 OpenCode 交互界面里查看当前加载的模型列表 /modelsopencode auth login的作用是把你的 API key 写进 OpenCode 的本地认证存储里避免每次对话都手动传 key启动opencode后你就进入了交互界面/models是 OpenCode 内部命令用来列出当前配置下可用的模型。我第一次配置时在这里卡了很久折腾了十来分钟模型列表里就是看不到模型名后来发现是配置文件里 provider 名字大小写写错了。建议第一次跑通时不要急着追求最强模型先用最小的模型把链路验证完确认能收发消息再换成正式模型。社区里常说的“opencode go 套餐”本质就是把默认 provider 换成你付费的某个模型入口你在配置里把 API 地址和 key 换成那边的就行OpenCode 本身不限定模型来自哪家。3.4 免费额度报错error from provider (console): opencodes free tier can only be used from within opencode这个报错我在帮别人排查时见过太多次值得单独拧出来讲。它的完整报错是error from provider (console): opencodes free tier can only be used from within opencode这句话的意思是OpenCode 内置的免费档模型provider 名里带 console 的那一类只能从 OpenCode 自己的会话里发起请求。如果你把这个 provider 当作通用入口让别的客户端或脚本直接调用服务端会拒绝。这个报错最常见的发生场景有两种。第一种是你把 OpenCode 配置里默认模型设成了内置免费档但实际请求是从别的程序转发出来的——OpenCode 认为这不是它自己的会话于是拒绝。第二种是你在某个 IDE 插件或代理工具里填了 OpenCode 的免费档模型名想白嫖它的免费额度服务端直接拦了。解决办法也很直接要么把请求方改成 OpenCode 本身让对话都发生在opencode交互界面里要么在opencode.json里把 provider 换成自己的 API key不用内置免费档。不要试图绕过这个限制这是服务端做的校验客户端这边没有正经的后悔药。{ provider: { myprovider: { npm: ai-sdk/my-provider, options: { baseURL: https://your-api-endpoint.example.com, apiKey: {env:MY_API_KEY} } } } }这段配置的作用是让 OpenCode 使用你自己的模型服务入口。逻辑说明npm字段指定该 provider 对应的 SDK 包options里的baseURL是服务地址apiKey从环境变量MY_API_KEY里读取不硬编码在配置文件中。参数说明{env:变量名}这种写法是让 OpenCode 从运行环境里读敏感信息避免 key 泄露进版本库如果你的服务商不需要额外 SDK把整个 provider 指成 OpenCode 内置支持的类型即可写法要跟随你所用版本的 schema。4. 对接 TRAE CN 并挂上 Superpowers三种落地路径与一份验证清单4.1 路径一在 TRAE CN 内置终端里直接运行 opencode最直接的做法是在 TRAE CN 里打开内置终端切到项目目录直接输入opencode启动。这个方案配置成本最低但有一个前提TRAE CN 的内置终端要能找到opencode命令。Windows 下如果 npm 全局目录没有进 PATH终端里会提示找不到命令这时候需要手动把 npm 全局目录加进 PATH。# 查看 npm 全局安装目录 npm prefix -g # 把目录追加到 PATH以 Git Bash 为例 export PATH$PATH:$(npm prefix -g)第一段命令是查看 npm 全局安装目录在哪第二段是把该目录追加到当前 shell 的 PATH 里。逻辑说明OpenCode 装在 npm 全局目录下但 shell 启动时不一定加载这个目录所以要先找到它再手动加。参数说明npm prefix -g在 Windows 上通常输出C:\Users\你的用户名\AppData\Roaming\npm类似路径如果你用的 shell 是 PowerShell追加 PATH 的写法不一样要用$env:PATH ; (npm prefix -g)。跑起来之后OpenCode 的工作目录就是 TRAE CN 打开的项目目录文件改动会被 TRAE CN 自动感知。这个路径适合只想快速用起来、不想折腾复杂配置的人。缺点是没有把 Superpowers 挂进去OpenCode 只具备基础编码能力。要发挥技能包的价值看下一条路径。4.2 路径二把 Superpowers 的 skills 目录挂进 OpenCodeSuperpowers 这套技能源码包要真正生效核心是把它的 skills 目录暴露给 OpenCode。我一般先把项目 clone 到本地然后不直接改动原目录而是通过配置或软链接让 OpenCode 去读它。# 把 Superpowers 项目 clone 到本地固定目录 git clone https://github.com/superpowers/superpowers.git ~/superpowers # 在项目里创建 OpenCode 的技能入口目录 mkdir -p .opencode/skills # 将 Superpowers 的 skills 软链到项目里 ln -s ~/superpowers/skills .opencode/skills/superpowers这三段命令的作用分别是把技能源码下载到~/superpowers目录在当前项目里创建.opencode/skills目录作为 OpenCode 的技能加载点把 Superpowers 的技能目录软链接进去。逻辑说明OpenCode 在启动会话时会扫描.opencode下的技能目录技能目录里每个子目录对应一个技能技能内必须有说明文件才能被识别。参数说明软链接的好处是源码仓库可以单独更新git pull之后不需要重新复制如果你不想用软链接直接把~/superpowers/skills/*复制到.opencode/skills/下也可以代价是升级时要手动同步。挂完之后重启 OpenCode再问它有哪些技能可用。如果技能没出现先检查.opencode/skills目录下每个技能目录里是否真的有说明文件缺了它就相当于 Agent 拿到一个空壳。4.3 路径三通过 TRAE CN 的自定义规则共享同一份 AGENTS.md第三条路径解决的是“TRAE CN 的 Agent 和 OpenCode 能不能共享一套规范”的问题。TRAE CN 支持项目级自定义规则我通常把AGENTS.md放在项目根目录里面写项目技术栈、目录约定、编码规范再让 TRAE CN 和 OpenCode 都去读它。# 项目规范 ## 技术栈 - 前端Vue 3 TypeScript - 后端Node.js Express ## 编码约定 - 组件文件名使用 PascalCase - 所有接口返回值统一包装为 { code, data, message } - 修改公共类型时必须同步更新对应的测试文件 ## 关键目录 - src/api接口定义 - src/components组件 - src/utils工具函数这份AGENTS.md的作用是同时约束两个 Agent 的行为。逻辑说明OpenCode 默认会读取工作目录下的AGENTS.md作为项目上下文提示词TRAE CN 的自定义规则里可以引用同一个文件内容两边读到同样的规范生成风格才一致。参数说明文件里的内容要尽量写“必须做什么、不许做什么”少写空泛的“请保证代码质量”这类话模型对具体约束的遵从度远高于模糊要求。我现在的习惯是把这个文件也纳入版本库团队所有人都共用一份。改规范时只改这个文件两个 Agent 下次启动就会按新规范工作。4.4 验证一套技能是否生效配置完不能只看文件没报错就收工我一般会做一轮最小验证确认技能真的被加载、模型真的按技能输出。# 在 OpenCode 交互界面里列出当前已加载的技能 /skills # 直接触发一个技能看是否有预期输出 # 例如按代码审查技能的要求让 OpenCode 审查当前目录下最近改动的文件/skills命令会列出 OpenCode 当前加载到的全部技能名。逻辑说明如果这里看不到 Superpowers 里的技能名说明技能目录没挂对后面所有对话都不会按技能执行。参数说明如果你用的 OpenCode 版本较老可能没有/skills命令那就直接提问一个技能覆盖的场景观察回答是否按技能模板的结构输出。验证通过后我会再把第 4.1 到 4.3 的三个路径重新过一遍确认从 Tarek 的终端启动、技能目录加载、TRAE CN 自定义规则三个层面都对齐。这样即使后面改了 IDE 或换了模型这套配置也能平移。5. 配置避坑与常见问题排查这些坑我基本都踩过5.1 opencode.exe 与你运行的 Windows 版本不兼容现象在 Windows 上执行opencode时直接弹出错误提示“node_modulesopencode\cli\bin\opencode.exe 与你运行的 Windows 版本不兼容”命令完全无法启动。原因这个报错一般是 Windows 版本过旧或系统缺少必要的运行时组件也有可能是 npm 装到了错误的平台包。OpenCode 的二进制文件在旧版本 Windows 上跑不起来是常见原因。解决先确认系统是否开启了 WSL2 环境Windows 10 以下版本官方支持已经不友好然后卸载后用当前 LTS 版本的 Node 重新安装一次还是不行就直接在 WSL2 里跑opencode不要在原生 cmd 里死磕。我自己的处理方式就是直接在 WSL 里建项目目录TRAE CN 打开 WSL 路径终端切换成 WSL一次搞定。5.2 opencode web 只能本机访问局域网打不开现象OpenCode 的 Web 界面启动后地址显示localhost:xxxx同事在同一局域网里访问你的 IP 加端口却打不开浏览器提示连接超时或拒绝连接。原因OpenCode 的 Web 服务默认只绑定在127.0.0.1上这个地址只有本机能访问局域网里的其它机器当然进不来。这不是模型或配置的问题纯粹是网络监听地址限制。解决在启动参数或配置文件里把监听地址改成0.0.0.0让服务监听所有网卡同时注意操作系统防火墙是否放行了对应端口。我一般还会把访问加上一层简单的 token 校验毕竟监听所有网卡意味着同网段任何人都能访问。5.3 模型“只思考不回答”输出迟迟不落盘现象在 OpenCode 里提问后模型像是在长时间思考终端一直转圈最后只输出一段很短的内容或者干脆什么都不写文件也没有任何改动。原因我遇到过的情形有两种。第一种是模型输出超长超过了 OpenCode 或模型服务的最大 token 限制输出被截断。第二种是模型想执行某个工具命令但被昨天的permission配置拦住了OpenCode 在等你确认而你没有注意到终端底部的提示。解决把opencode.json里的最大输出 token 调大然后检查permission配置里是不是把某些命令拦得太死临时放行并观察如果配置没问题就用一个最简短的提问复现确认是否必现。5.4 技能加载了却不起作用目录名、大小写、说明文件缺失现象/skills里能看到技能名但实际对话里让它做对应事情它完全按普通聊天方式回答根本不走技能的模板和步骤。原因技能目录加载了但技能说明文件的格式没被正确解析常见问题是文件命名不对、技能描述太短或者说明文件里没有写清楚“何时该使用该技能”。OpenCode 按说明文件里的描述来决定是否触发技能描述写得像摆设它自然不认。解决打开技能目录里的说明文件检查文件命名是否为规范名称再看描述部分是否明确写了触发条件和执行步骤。我一般会把描述改成“当用户要求审查代码、重构函数、补充测试时必须使用本技能”这种带明确触发条件的写法效果立竿见影。5.5 token 消耗查不到、统计不准现象想确认一次大改到底烧了多少 token翻遍界面找不到入口或者 OpenCode 显示的数字和模型服务商控制台里的数据对不上。原因OpenCode 的统计界面和模型服务商的计费口径不完全一致。OpenCode 统计的是应用层看到的 token 数服务商统计的可能是包含缓存、输入重算在内的实际计费 token两者有差异很正常。解决在 OpenCode 里用统计命令查看本次会话的应用层消耗具体到某个模型服务商时以服务商后台为准。要准确定位还可以在配置里开启详细日志把每次请求的 token 明细记下来再和服务商账单比对。6. 进阶用法把 Superpowers 改造成自己的私有技能库6.1 用自己的 skill 固定团队规范Superpowers 提供的技能终究是通用能力团队真正需要的是把内部规范固化成技能。我会在.opencode/skills下新建一个私有技能目录里面只放一份说明文件。这个技能做一件事代码审查时严格按团队规范检查错误处理、日志输出、接口兼容性。说明文件里列出检查清单和不符合规范时的处理方式OpenCode 每次审查代码都会先读到这份清单输出格式稳定不会今天一个样子明天一个样子。如果你想给 OpenCode 加长期记忆常见做法是接 mem0 这类记忆服务在配置里多挂一个记忆 provider。我的习惯是不依赖记忆把所有规范写进技能说明因为记忆不可控而技能文件是版本库里可审查、可回滚的。6.2 三个命令看清配置是否真的生效改动配置后我不靠肉眼猜直接用三条命令验证。# 1. 查看 OpenCode 是否按预期配置启动 opencode --config # 2. 在交互界面里列出已加载的技能 /skills # 3. 检查权限规则是否生效 /permissionsopencode --config会输出当前生效的完整配置内容确认你改的字段真的被加载了/skills确认技能目录加载成功/permissions检查权限规则有没有按预期生效。这三条命令从上到下正好覆盖“配置、技能、权限”三个层面大多数配置问题靠它们就能定位。我已经把这种验证方式养成了习惯每次改完配置都先跑一遍再开始干活基本没再因为“改了没生效”回去翻黑匣子。Superpowers 的价值不在它自带的那些技能有多厉害而在于它给你搭好了一套把经验沉淀成技能的架子。按这个思路去维护自己的技能库OpenCode 和 TRAE CN 这套组合才真正值得长期投入。希望帮到你。本文还有配套的精品资源点击获取