简介面向OpenCode与TRAE CN开发者的Superpowers配置指南项目源码重点演示如何集成Superpowers插件与ui-ux-pro-max技能以生成稳定、可直接运行的高质量代码尤其适合需要精细化控制输出质量的中初级开发者与前端团队。压缩包共3个文件其中inscode为核心配置html为说明文档gitignore用于版本管理整体仅6KB可快速下载即用。目前已有2094人学习实用性已获一定验证。指南内容覆盖插件仓库克隆、符号链接创建、目录结构设置、ui-ux-pro-max技能启用以及通过AGENTS.md或opencode.json配置严格生成规则等核心步骤同时针对TRAE CN环境插件路径不一致的常见问题给出专门处理方案并提供Windows PowerShell操作命令与故障排查思路。所有案例均基于Windows环境演示便于读者照做并理解各文件作用从而在本地快速搭建可靠、高效的编码环境。1. Superpowers不是插件一套“会主动挑活干”的技能包很多人第一次看到“Superpowers”这个名字会以为它是一个点上就能让AI变强的插件装上才发现它连安装包都没有有的只是一批markdown文件。这套技能包的运行机制很简单把编码、调试、计划、子代理拆成一簇簇带规则说明的skill文件塞进OpenCode的技能目录模型行动之前先扫描这些规则的description自己判断“现在该调用哪个技能”而不是每次都从零开始瞎猜。下面把OpenCode与TRAE CN挂载Superpowers的全过程拆开讲适合已经用过AI编程工具、但觉得默认行为不够“懂行”的开发者也适合想搞懂技能命中逻辑的新手。2. 先把宿主装到位OpenCode安装、Node版本与账户初始化2.1 OpenCode是什么为什么它适合挂技能包OpenCode是一个跑在终端里的本地AI编程agent核心代码开源配置和会话都存成普通文件不像有些IDE把技能封装成不可见的黑匣子。选择它挂载Superpowers不是因为模型能力最强而是因为它的skills机制最直接把技能文件放进指定目录运行时就会把技能说明注入给模型整个流程可审计出问题时能打开文件看是哪条规则没生效。与TRAE CN这类IDE内置Agent相比OpenCode更贴近“命令行工具”的定位不绑定编辑器可以被TRAE CN、VS Code、甚至只是一个纯终端调用。技能包这种静态文件结构和OpenCode的适配成本最低。2.2 安装OpenCodenpm安装、官方脚本与手动二进制OpenCode的安装方式有几种我实际用下来推荐两条路# 方式一npm 全局安装需要 Node.js 18 及以上 npm install -g opencode-ailatest # 方式二官方安装脚本自动下载当前平台二进制 curl -fsSL https://opencode.ai/install | bash # 验证安装结果 opencode --versionnpm方式适合机器上已经有Node环境的开发者安装路径由npm统一管理升级时一条命令搞定。官方脚本会自动识别操作系统和CPU架构下载对应二进制适合Windows上不想碰Node的情况。这里有个参数容易被忽略OpenCode的npm包名是opencode-ai而不是opencode后者是另一个同名工具装错会得到一个完全不同的命令行程序。安装完成后执行opencode --version能输出版本号才算装对。我在Windows环境遇到的“node_modulesopencode\cli\bin\opencode.exe与当前Windows版本不兼容”就是安装源搞混导致的后面第5章会展开说。2.3 账户初始化与provider选择装好之后第一次运行opencode它会要求登录并选择模型provider。执行opencode auth login这个命令会列出所有可用的provider包括Anthropic、OpenAI、Google Gemini以及OpenCode官方的console免费层。选完之后凭据会写入配置文件后续每次启动自动读取。这里把几个实际常用的provider列一下方便按场景选provider用途注意点consoleOpenCode官方免费层额度较小只能在opencode内部使用外接会报错anthropicClaude系列编码能力强需要API key按token计费openaiGPT系列通用性好需要API keygemini免费层额度较大适合做预算紧张时的日常补充选provider以前我总贪图省事直接选默认结果在console免费层上跑大任务几下就把额度打光。后面养成的习惯是先用opencode models看一眼当前provider支持的模型列表再根据任务类型决定用哪个而不是每次都让agent自己挑。3. 挂载Superpowers技能包目录结构、命中规则与验证方法3.1 Superpowers里到底有什么Superpowers不是单个文件而是一整个仓库里面按技能维度拆成子目录。每个技能的核心是SKILL.md文件头部是YAML格式的frontmatter声明技能名称和触发条件--- name: debugging description: 调试代码时使用当测试失败、报错或行为不符合预期时触发 ---真正干活的规则写在frontmatter下面先做什么、再做什么、什么时候停下来问用户、什么情况下必须子代理介入。OpenCode的机制是扫描这些规则文件把它们作为上下文的一部分注入模型相当于每次对话开头就告诉模型“你有一本调试手册遇到对应场景先翻手册再动手”。仓库里常见的技能还包括编码规范、代码审查、任务规划、子代理管理、浏览器操作等。安装之后你不需要全部用上技能是否参与决策由模型根据description判断和实际场景不匹配的技能不会占用太多上下文。3.2 安装步骤git clone与符号链接安装的本质是把这堆markdown文件放进OpenCode指定的技能目录。执行# 克隆Superpowers仓库到OpenCode技能目录 git clone https://github.com/obra/superpowers.git ~/.config/opencode/skills/superpowers # 如果想保留仓库原始位置也可以做符号链接 ln -s ~/projects/superpowers ~/.config/opencode/skills/superpowers~/.config/opencode/skills是OpenCode的技能根目录递归扫描时每个子目录就是一个技能。用符号链接的好处是仓库更新时直接git pull原始目录就能生效不用反复复制。装完后看一下目录结构是否完整ls -la ~/.config/opencode/skills/superpowers正常情况下能看到SKILL.md和若干子技能目录。如果这里目录结构不完整运行OpenCode时技能就不会被加载而且界面没有任何错误提示——这是最容易踩的静默失败点。3.3 技能命中规则description写得好Agent才“知道什么时候用”技能命中逻辑是Superpowers机制里最玄学也最关键的部分。模型的决策依据主要是description字段同一时刻可能有多个技能的description都和当前任务沾边模型会按相关性排序选它认为最匹配的那个加载。常见的翻车是技能装了但description写得太泛比如“编码时使用”。模型面对一个具体bug时可能选通用编码技能而非调试技能结果行为模式和没装技能包几乎一样。验证技能是否命中可以这样操作# 在OpenCode交互界面里查看当前会话加载的技能 /typing /skills或者直接开启调试输出观察模型在每一步读取了哪些文件。如果看不到技能文件被读取优先检查description描述是否具体到“什么场景用什么工具”。Superpowers仓库里每个技能的description都经历过反复打磨自己扩展技能时最该抄的也是这套写法。4. TRAE CN接入OpenCode内置终端与自定义指令两条路线4.1 TRAE CN和OpenCode的定位差异TRAE CN是带图形界面的AI IDE内置Agent适合日常写代码、看diff、做重构。OpenCode是纯命令行的agent优势是技能包机制灵活。两者不冲突实际工程里我常见两种组合方式要么在TRAE CN内置终端里直接跑OpenCode要么把Superpowers的规则转写成TRAE CN自己的指令体系。前者适合临时调模型、跑技能包后者适合想把技能固化成团队规范的人。4.2 路线一TRAE CN内置终端直接调用OpenCodeTRAE CN自带的终端是一个完整shell可以直接执行外部命令。把OpenCode装好后在终端里运行# 在TRAE CN内置终端启动OpenCode项目根目录打开 cd /path/to/your/project opencode启动后OpenCode会读取当前目录下的.opencode配置和技能文件项目上下文从TRAE CN里继承。这个方式的好处是配置零成本Superpowers技能直接在OpenCode里生效代价是TRAE CN内置Agent本身用不上这些技能两边是割裂的。为了让TRAE CN的项目上下文和OpenCode保持一致我会在项目根目录放一个AGENTS.md内容包含项目技术栈、目录结构、约定规范。OpenCode和TRAE CN都支持读取这个文件一份配置两边生效# 项目根目录创建AGENTS.md touch AGENTS.mdAGENTS.md本质是给agent看的说明文档不需要特定语法写成自然语言即可比如“本项目的构建命令是npm run build”“数据库迁移脚本在db/migrations目录下”。两个工具都能解析它等于给技能包加了一层项目专属上下文。4.3 路线二把Superpowers转写为TRAE CN自定义指令TRAE CN没有OpenCode那种skills目录机制不支持直接把SKILL.md丢进去就让Agent自动加载。但TRAE CN支持自定义指令可以把Superpowers里的核心规则转成指令文本。转换思路很简单把SKILL.md里的“name”映射成指令名称“description”映射成触发词“执行步骤”映射成指令正文。Superpowers技能字段TRAE CN自定义指令对应位置name指令名称description指令描述用于匹配场景执行步骤指令正文注意事项指令里单独一段强调转写时我一般只挑三个高频技能做转换调试、代码审查、任务拆解不贪多。转换之后的指令可以在TRAE CN的Agent配置里导入效果是输入描述场景时Agent会优先按指令流程走。这套做法的局限也很明显技能是静态文本没有Superpowers那种动态、多技能协作的感觉但对于团队统一规范已经够用。4.4 会话上下文与项目级配置组合无论走哪条路线项目级配置都是技能包能不能落地的关键。OpenCode的读取顺序是先读全局配置再读项目根目录的.opencode配置最后读AGENTS.md。TRAE CN则是读取工作区设置。开启OpenCode时手动指定配置文件可以避免项目环境串了opencode --config ~/projects/your-project/.opencode--config参数指定配置文件路径适合同时维护多个项目、各项目技能侧重不同的情况。如果AGENTS.md写在项目根目录启动命令不要加--no-agent否则项目规则不会被加载。5. 避坑排查免费层报错、Windows兼容与局域网访问的五条记录5.1 “free tier can only be used from within opencode”报错现象在TRAE CN终端或IDE插件里调用OpenCode选console provider运行时报错error from provider (console): opencodes free tier can only be used from within opencode。原因console免费层是OpenCode官方提供给自家CLI的额度OpenCode在发起请求时会携带一个内部标识第三方工具伪装不了。只要不是在OpenCode自己的交互界面里发请求就会被拒绝。解决免费层只在opencode原生命令行里用。要接入TRAE CN就给TRAE侧配置Anthropic或OpenAI的API key把console免费层只当成本地试用渠道。从那以后我养成了习惯凡是接IDE一律先问自己“这个provider能不能外接”查清楚再配不再白折腾。5.2 “opencode.exe与当前Windows版本不兼容”现象Windows上运行opencode提示node_modules\opencode\cli\bin\opencode.exe 与你运行的 Windows 版本不兼容。原因典型的安装源混用。npm包opencode-ai在不同Node版本下会编译或拉取不同版本的二进制如果Node版本过低拉到的旧版exe和当前Windows版本不兼容。解决先把npm和Node升级到最新LTS再重装OpenCodenpm install -g npmlatest npm install -g opencode-ailatest如果还不行就用官方安装脚本覆盖安装脚本下载的二进制会适配当前系统。更保险的做法是在WSL2里运行Linux二进制基本没有这个兼容问题。5.3 OpenCode只思考不回答现象让OpenCode处理一个编码任务模型输出了一堆分析、计划、拆解步骤就是不写代码会话里“思考”过程占了大部分。原因两种情况。一是当前模型本身是推理型模型比如带有extended thinking的Claude模型默认先输出思考再输出结果二是技能包里的计划技能被触发了模型认为当前任务需要先规划。解决换一个非推理型模型或者在prompt里明确要求“直接输出代码不要思考过程”。如果确定是技能触发手动在对话里输入/skills关闭当前技能或者指定只启用编码技能/use coding这个命令让OpenCode只加载coding技能屏蔽计划类技能的干扰。5.4 OpenCode Web只能本地访问局域网打不开现象启动OpenCode Web界面后手机或其他电脑访问http://127.0.0.1:端口打不开。原因默认绑定的是loopback地址只允许本机访问。这是出于安全考虑的默认值不是bug。解决启动时显式指定监听地址opencode --host 0.0.0.0 --port 80800.0.0.0表示监听所有网卡之后局域网内其他设备就能通过http://本机IP:8080访问。注意这个模式下任何人都能连上你的OpenCode建议只在可信内网使用用完立即关闭。5.5 免费模型额度消耗对不上账现象App或web端显示的token消耗和OpenCode里看到的用量数字对不上。原因OpenCode的用量统计按provider分开记录console免费层和自费API key的计费体系不同另外如果同一个API key被多个工具复用服务商后台统计的是总消耗而OpenCode只记自己那部分。解决在OpenCode里查看实时用量/usage这个命令会列出当前会话和各provider累计的token消耗和provider后台对比时两边的统计口径要对齐。排查时先确认当前会话用的哪个provider、哪个模型再对照服务商后台的API Key使用记录。6. 进阶自己写技能、用量对账与桌面版使用习惯6.1 照着Superpowers格式写一个自己的SKILL.md技能包的价值不只是装现成的OpenCode的skills机制支持自定义技能。以“changelog生成”为例在技能目录下新建子目录和SKILL.md--- name: changelog-generator description: 生成或更新CHANGELOG.md时使用当git log有新增提交、用户要求整理变更记录时触发 --- # Changelog生成流程 1. 运行 git log --oneline -20 查看最近提交 2. 按 feat/fix/docs/refactor 分组整理 3. 输出到 CHANGELOG.md 的 Unreleased 区块 4. 不要修改历史版本区块关键还是description的写法要写明“什么时候触发”模型才能准确命中。写完保存重启OpenCode即可加载不需要额外注册。技能内容要具体到步骤避免“提取提交信息”这种泛化描述。6.2 用量对账与桌面版习惯每次会话结束前用/usage看一眼消耗养成这个习惯以后预算失控的情况少了很多。桌面版比终端版多了图形界面启动后同样用/usage查看配置目录一致不用担心数据不同步。如果用Web模式加局域网访问注意内网环境和监听地址的配合不要在不安全网络里开放监听。从那以后我每次配置新环境的Superpowers都强制走一遍先确认skills目录权限和结构再确认provider能否外接最后用/usage对账。这样的流程走顺之后技能包基本不再出幺蛾子。希望帮到你。本文还有配套的精品资源点击获取