企业官网建设流程全解析

简介：面向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 安装OpenCode：npm安装、官方脚本与手动二进制

OpenCode的安装方式有几种，我实际用下来推荐两条路：

# 方式一：npm 全局安装，需要 Node.js 18 及以上 npm install -g opencode-ai@latest # 方式二：官方安装脚本，自动下载当前平台二进制 curl -fsSL https://opencode.ai/install | bash # 验证安装结果 opencode --version

npm方式适合机器上已经有Node环境的开发者，安装路径由npm统一管理，升级时一条命令搞定。官方脚本会自动识别操作系统和CPU架构，下载对应二进制，适合Windows上不想碰Node的情况。

这里有个参数容易被忽略：OpenCode的npm包名是opencode-ai而不是opencode，后者是另一个同名工具，装错会得到一个完全不同的命令行程序。安装完成后执行opencode --version，能输出版本号才算装对。我在Windows环境遇到的“node_modules@opencode\cli\bin\opencode.exe与当前Windows版本不兼容”就是安装源搞混导致的，后面第5章会展开说。

2.3 账户初始化与provider选择

装好之后第一次运行opencode，它会要求登录并选择模型provider。执行：

opencode auth login

这个命令会列出所有可用的provider，包括Anthropic、OpenAI、Google Gemini，以及OpenCode官方的console免费层。选完之后，凭据会写入配置文件，后续每次启动自动读取。

这里把几个实际常用的provider列一下，方便按场景选：

选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内置终端直接调用OpenCode

TRAE 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.md

AGENTS.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”映射成触发词，“执行步骤”映射成指令正文。

转写时我一般只挑三个高频技能做转换：调试、代码审查、任务拆解，不贪多。转换之后的指令可以在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): opencode's 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，再重装OpenCode：

npm install -g npm@latest npm install -g opencode-ai@latest

如果还不行，就用官方安装脚本覆盖安装，脚本下载的二进制会适配当前系统。更保险的做法是在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 8080

0.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对账。这样的流程走顺之后，技能包基本不再出幺蛾子。希望帮到你。

本文还有配套的精品资源，点击获取