简介这份源码包面向使用 OpenCode 与 TRAE CN 进行 AI 辅助开发的工程师聚焦 Superpowers 插件与 ui-ux-pro-max 技能的配置落地解决插件路径不一致、代码生成规则松散等实际问题。包内共 3 个文件以 html 页面、inscode 配置与 gitignore 为主分别承担界面展示、项目环境描述与版本忽略规则压缩包整体约 6KB体量轻便、便于快速导入本地工程。目前已有 2102 人学习下载说明该配置方案在开发者社区中具备一定参考价值。读者可据此掌握克隆仓库、创建符号链接与目录结构的完整流程理解如何通过 AGENTS.md 或 opencode.json 设定严格代码生成规则并借助 ui-ux-pro-max 技能优化前端 UI/UX 输出。资源还针对 TRAE CN 的插件路径差异给出对应处理思路并附 Windows PowerShell 操作命令与常见问题排查方法适合希望提升代码生成可靠性与前端设计质量的开发者参考。1. OpenCode 与 TRAE CN 的 Superpowers 配置这套组合到底解决什么问题很多人第一次听到 OpenCode 和 TRAE CN 的 Superpowers 配置脑子里冒出来的问题是这俩不是竞品吗为什么要放一起配我一开始也这么想直到在一个真实项目里被逼着把两套工具串起来用。场景很具体团队里有人习惯在终端里用 OpenCode 跑 agent 任务有人习惯在 TRAE CN 的 IDE 里做可视化调试而 Superpowers 这套能力包一组预置的 agent 技能、工具调用约定和上下文注入规则如果只在一边配好另一边就完全用不上协作时上下文断裂同一个任务两边跑出来的结果对不上。这个标题讲的就是把 OpenCode 和 TRAE CN 两个环境下的 Superpowers 配置打通让同一套技能定义、同一套工具约定在两边都能生效。它解决的是「工具割裂导致 agent 行为不一致」的问题适合已经在用 OpenCode 或 TRAE CN 做日常开发、想让 agent 能力跨环境复用的工程师。如果你只是单环境用这篇里的跨环境同步思路也能帮你把配置结构理清楚少踩几个路径和权限的坑。2. Superpowers 在 OpenCode 与 TRAE CN 里的定位差异先搞清楚两边各管什么2.1 OpenCode 侧的 Superpowers 是命令行 agent 的能力扩展层OpenCode 本身是一个终端里的 AI 编程 agent它的工作方式是读你当前目录的上下文、调模型、执行工具、改文件。Superpowers 在 OpenCode 里的角色是给这个 agent 挂上一组预定义的技能skill和工具调用规则。你可以把它理解成给 agent 装了一套「标准作业程序」——遇到什么类型的任务该调哪个工具、该按什么格式输出、该在什么阶段向用户确认都由 Superpowers 里的配置决定。OpenCode 侧的配置核心是两样东西技能定义文件和工具注册表。技能定义文件描述「这个技能叫什么、什么时候触发、执行逻辑是什么」工具注册表描述「这个技能可以调用哪些外部命令或 API」。这两样东西的路径和加载顺序直接决定了 Superpowers 能不能被正确识别。常见做法是在项目根目录建一个配置目录把技能定义按类别拆成多个文件工具注册表用一个总入口引用它们。这里有个容易忽略的点OpenCode 加载 Superpowers 的时机是在 agent 初始化阶段如果你在 agent 已经跑起来之后才改配置文件不重启是不会生效的。我见过有人改完配置直接在当前会话里试怎么都不对重启一下就好了这种就是典型的加载时机问题。2.2 TRAE CN 侧的 Superpowers 走的是 IDE 插件与工作区配置双通道TRAE CN 是一个带 AI 能力的 IDE它的 Superpowers 配置分两层一层是 IDE 插件层面的全局配置决定这个 IDE 里所有工作区默认能用哪些 Superpowers 能力另一层是工作区层面的配置决定当前打开的这个项目能用哪些能力、技能定义从哪个路径读。这两层的优先级是工作区配置覆盖全局配置。也就是说你可以在全局配一套通用的 Superpowers 技能然后在具体项目的工作区配置里覆盖掉其中某几个换成这个项目专用的。这个机制很实用但也很容易配错——最常见的问题是工作区配置里只写了要覆盖的那几项没写继承全局的声明结果就是全局那套完全没生效只剩工作区里写的那几项在跑。TRAE CN 侧还有一个和 OpenCode 不一样的地方它有一个可视化的技能管理面板你可以在面板里看到当前生效的技能列表、每个技能的触发条件、最近一次调用的日志。这个面板在排查「为什么这个技能没触发」的时候非常有用比在 OpenCode 里翻日志快得多。所以我的习惯是跨环境调试 Superpowers 的时候先在 TRAE CN 的面板里确认技能定义本身没问题再去 OpenCode 侧排查加载和路径问题。2.3 两边配置能打通的前提是技能定义格式对齐OpenCode 和 TRAE CN 对 Superpowers 技能定义的格式要求不完全一样。OpenCode 侧更偏向纯文本加 YAML 前置元数据TRAE CN 侧对 JSON 结构的支持更完整。如果你想让同一套技能定义在两边都能用最省事的做法是选一个两边都支持的中间格式然后各写一个转换脚本。我一般会以 OpenCode 侧的格式为主格式因为它的结构更简单、更容易做版本管理。然后在 TRAE CN 侧写一个加载时转换的适配层把 OpenCode 格式的技能定义转成 TRAE CN 能识别的 JSON 结构。这个适配层不需要很复杂核心就是字段映射和默认值填充。下面这个转换脚本是我实际在用的简化版import yaml import json import os def convert_skill(opencode_skill_path): 把 OpenCode 格式的技能定义转成 TRAE CN 可识别的 JSON 结构 with open(opencode_skill_path, r, encodingutf-8) as f: content f.read() # OpenCode 技能定义是 YAML 前置元数据 正文 if content.startswith(---): parts content.split(---, 2) meta yaml.safe_load(parts[1]) body parts[2].strip() else: raise ValueError(f技能文件缺少 YAML 前置元数据: {opencode_skill_path}) # 字段映射OpenCode 的 trigger 对应 TRAE CN 的 activation trae_skill { name: meta.get(name, ), description: meta.get(description, ), activation: { patterns: meta.get(trigger, []), mode: meta.get(trigger_mode, auto) }, tools: meta.get(tools, []), instructions: body } return trae_skill def batch_convert(src_dir, dst_dir): 批量转换一个目录下所有技能定义 os.makedirs(dst_dir, exist_okTrue) converted [] for fname in os.listdir(src_dir): if not fname.endswith((.md, .yaml, .yml)): continue src_path os.path.join(src_dir, fname) skill convert_skill(src_path) dst_path os.path.join(dst_dir, f{skill[name]}.json) with open(dst_path, w, encodingutf-8) as f: json.dump(skill, f, ensure_asciiFalse, indent2) converted.append(skill[name]) return converted if __name__ __main__: result batch_convert(./skills, ./trae_skills) print(f已转换 {len(result)} 个技能: {result})这段脚本的逻辑很直白读 OpenCode 的技能文件拆出 YAML 前置元数据和正文把元数据里的字段按映射关系填到 TRAE CN 的结构里正文原样放进 instructions 字段。参数上需要注意两个地方trigger字段在 OpenCode 里可能是字符串也可能是列表脚本里统一按列表处理如果你的技能定义里写的是单个字符串YAML 解析出来会是 str 而不是 list需要在映射前做一次类型判断。另一个是trigger_modeOpenCode 默认是 autoTRAE CN 侧如果没显式指定会走它自己的默认值两边默认值可能不一样建议在技能定义里显式写清楚。3. 从零配一套跨环境可用的 Superpowers路径、权限与加载顺序3.1 目录结构怎么定才能两边都认跨环境配置最容易翻车的地方就是目录结构。OpenCode 默认从项目根目录的.opencode/skills/读技能定义TRAE CN 默认从工作区配置里指定的路径读如果你不显式指定它会去.trae/skills/找。两个默认路径不一样但内容需要保持一致。我的做法是在项目根目录建一个superpowers/目录作为唯一真实来源里面放技能定义和工具注册表。然后在.opencode/skills/和.trae/skills/各放一个软链接或者同步脚本指向superpowers/下的对应文件。这样你只需要维护一份配置两边都能读到。目录结构大概长这样project-root/ ├── superpowers/ │ ├── skills/ │ │ ├── code-review.md │ │ ├── test-gen.md │ │ └── refactor.md │ ├── tools/ │ │ └── registry.yaml │ └── trae-adapter/ │ └── convert.py ├── .opencode/ │ └── skills - ../superpowers/skills └── .trae/ └── skills - ../superpowers/skills软链接在 Linux 和 macOS 上没问题Windows 下需要管理员权限或者开发者模式才能创建。如果你在 Windows 上做这套配置建议用同步脚本代替软链接每次改完superpowers/下的文件跑一次同步。同步脚本很简单核心就是复制文件加时间戳比对这里不展开。3.2 工具注册表的字段含义与必填项工具注册表是 Superpowers 配置里最容易被低估的部分。很多人只配技能定义不配工具注册表结果技能触发之后调不到工具报一堆「tool not found」。工具注册表的核心字段有这几个字段含义是否必填常见值tool_name工具的唯一标识是shell_exec、file_read、http_callhandler实际执行入口是命令路径或模块函数名timeout超时秒数否默认 30长任务建议 120allowed_skills允许调用此工具的技能列表否不填表示所有技能可用env执行时注入的环境变量否按需allowed_skills这个字段值得单独说。如果你不填所有技能都能调这个工具这在开发阶段方便但在生产环境或者多人协作的项目里是隐患——一个不该有文件删除权限的技能如果工具注册表里没限制它就能调删除命令。我一般会在工具注册表里显式列出每个工具允许被哪些技能调用多花几分钟省掉后面排查权限问题的几个小时。timeout的默认值 30 秒在大多数场景下够用但如果你有跑测试、编译、拉依赖这类任务30 秒经常不够。我踩过的坑是一个跑集成测试的技能因为 timeout 没改测试跑到一半被掐断agent 拿到的是截断的输出然后基于截断输出做了错误的判断。这种问题不会报错只会让结果莫名其妙不对排查起来很费时间。建议凡是涉及外部命令执行的工具timeout 至少给到 120 秒。3.3 加载顺序与覆盖规则谁先谁后决定谁生效OpenCode 和 TRAE CN 在加载 Superpowers 配置时都是按「全局配置 → 项目配置 → 工作区配置」的顺序加载后面的覆盖前面的。但两边的「全局」定义不一样OpenCode 的全局配置在用户主目录下的.opencode/里TRAE CN 的全局配置在 IDE 的设置里。这个差异导致一个常见问题你在 OpenCode 全局配了一个技能在 TRAE CN 全局也配了同名技能但内容不同然后在项目里两边都读同一份项目配置。这时候 OpenCode 侧生效的是项目配置覆盖全局后的结果TRAE CN 侧也是但因为两边的全局配置本身就不一样覆盖后的结果可能还是不一样。解决办法是跨环境用的技能不要在全局配置里定义全部放在项目级的superpowers/目录里。全局配置只放那些跟具体项目无关的通用工具注册。这样两边的加载起点就是同一个项目配置覆盖规则再复杂也不会跑偏。加载顺序还有一个实操细节OpenCode 是在 agent 启动时一次性加载所有配置TRAE CN 是在工作区打开时加载之后如果你改了配置文件TRAE CN 会提示你重新加载工作区OpenCode 需要重启 agent。所以调试的时候改完配置先确认两边都重新加载了再去测技能触发不然你测的还是旧配置。4. 避坑与排查Superpowers 配置里最容易翻车的五个地方4.1 技能不触发日志里连尝试记录都没有现象在 OpenCode 里输入一个明显该触发某个技能的任务描述agent 完全没反应日志里也找不到任何跟这个技能相关的记录。原因最常见的是技能定义文件的路径不对OpenCode 根本没加载到这个文件。其次是 YAML 前置元数据格式错误比如trigger字段用了中文冒号、缩进用了 Tab 而不是空格导致解析失败但没报错文件被静默跳过。解决先用 OpenCode 的配置检查命令确认技能列表里有没有这个技能。如果没有检查文件路径是否在.opencode/skills/下、文件扩展名是否是.md或.yaml。如果路径对但还是没有把 YAML 前置元数据单独拿出来用python -c import yaml; yaml.safe_load(open(文件路径))验证一下能不能解析。解析报错的话重点看冒号和缩进。4.2 TRAE CN 侧技能触发了但工具调不到现象TRAE CN 的技能面板里能看到技能被触发但执行到调工具那一步就报「tool not found」或者「permission denied」。原因工具注册表里没有注册这个工具或者注册了但allowed_skills里没包含当前技能。另一个可能是工具的可执行文件路径是相对路径TRAE CN 的工作目录和 OpenCode 不一样相对路径解析出来的结果不同。解决先在工具注册表里确认工具有没有注册、allowed_skills有没有包含当前技能。如果都正常把工具的 handler 路径改成绝对路径或者用环境变量注入的方式指定路径。TRAE CN 的工作目录默认是工作区根目录OpenCode 默认是当前终端所在目录这两个可能不一样用绝对路径最稳。4.3 两边跑同一个技能输出格式对不上现象同一个技能在 OpenCode 里跑出来的结果是结构化 JSON在 TRAE CN 里跑出来是一段自然语言文本。原因技能定义里的输出格式约束在转换过程中丢了。OpenCode 的技能定义里输出格式通常写在正文的某个段落里转换脚本如果只搬了 YAML 元数据没搬正文或者搬了正文但 TRAE CN 侧不认这种格式约束就会导致输出格式不一致。解决把输出格式约束从正文里提出来放到 YAML 元数据的一个独立字段里比如output_format然后在转换脚本里把这个字段映射到 TRAE CN 的对应字段。如果 TRAE CN 不支持在技能定义里约束输出格式就在技能正文里用更明确的指令写清楚比如「必须返回 JSON字段包括 x、y、z」而不是「返回结构化结果」。4.4 改了配置但行为没变现象明明改了技能定义里的触发条件重新加载后行为还是跟改之前一样。原因加载缓存。OpenCode 和 TRAE CN 都会缓存已加载的技能定义重新加载的触发条件不一样。OpenCode 需要重启 agent 进程TRAE CN 需要关闭工作区再重新打开光点「重新加载」有时候不够。解决OpenCode 侧直接杀掉 agent 进程重新启动。TRAE CN 侧先关闭当前工作区再重新打开项目目录。如果还不行检查一下有没有多个同名技能定义文件在不同路径下加载顺序导致旧的那个覆盖了新的。4.5 Windows 下软链接创建失败导致配置读不到现象在 Windows 上按 Linux 的做法建了软链接OpenCode 和 TRAE CN 都读不到技能定义。原因Windows 创建软链接需要管理员权限或者开发者模式普通权限下mklink会失败但有些工具会静默失败你以为链接建好了其实没有。解决Windows 下不要用软链接改用同步脚本。写一个简单的 Python 脚本比对superpowers/skills/和.opencode/skills/、.trae/skills/下的文件修改时间把新的复制过去。每次改完配置跑一次脚本或者用文件监听工具自动触发。这个方案比软链接多一步操作但在 Windows 下稳定得多。5. 进阶用配置校验脚本把跨环境问题挡在提交之前跨环境配置最麻烦的不是配一次而是每次改完都要手动确认两边都正常。我的做法是写一个校验脚本在提交代码之前跑一遍把常见的配置问题自动查出来。这个脚本不复杂核心就是检查文件存在性、YAML 可解析性、工具注册表完整性、两边技能列表一致性。import os import yaml import json import sys def validate_superpowers(project_root): 校验 Superpowers 配置的完整性返回问题列表 issues [] skills_dir os.path.join(project_root, superpowers, skills) tools_file os.path.join(project_root, superpowers, tools, registry.yaml) # 1. 检查技能目录是否存在 if not os.path.isdir(skills_dir): issues.append(f技能目录不存在: {skills_dir}) return issues # 2. 逐个检查技能定义文件 skill_names [] for fname in os.listdir(skills_dir): if not fname.endswith((.md, .yaml, .yml)): continue fpath os.path.join(skills_dir, fname) with open(fpath, r, encodingutf-8) as f: content f.read() if not content.startswith(---): issues.append(f{fname}: 缺少 YAML 前置元数据) continue try: parts content.split(---, 2) meta yaml.safe_load(parts[1]) except yaml.YAMLError as e: issues.append(f{fname}: YAML 解析失败 - {e}) continue if name not in meta: issues.append(f{fname}: 缺少 name 字段) else: skill_names.append(meta[name]) if trigger not in meta: issues.append(f{fname}: 缺少 trigger 字段技能不会被自动触发) # 3. 检查工具注册表 if not os.path.isfile(tools_file): issues.append(f工具注册表不存在: {tools_file}) else: with open(tools_file, r, encodingutf-8) as f: registry yaml.safe_load(f) registered_tools {t[tool_name] for t in registry.get(tools, [])} # 检查技能里引用的工具是否都已注册 for fname in os.listdir(skills_dir): if not fname.endswith((.md, .yaml, .yml)): continue fpath os.path.join(skills_dir, fname) with open(fpath, r, encodingutf-8) as f: content f.read() parts content.split(---, 2) meta yaml.safe_load(parts[1]) for tool in meta.get(tools, []): if tool not in registered_tools: issues.append(f{fname}: 引用了未注册的工具 {tool}) # 4. 检查两边技能列表是否一致 opencode_skills set() trae_skills set() oc_dir os.path.join(project_root, .opencode, skills) trae_dir os.path.join(project_root, .trae, skills) if os.path.isdir(oc_dir): opencode_skills {f for f in os.listdir(oc_dir) if f.endswith((.md, .yaml, .yml))} if os.path.isdir(trae_dir): trae_skills {f for f in os.listdir(trae_dir) if f.endswith(.json)} # 文件名可能不同一边 md 一边 json这里只检查数量是否匹配 if len(opencode_skills) ! len(trae_skills): issues.append(f两边技能数量不一致: OpenCode {len(opencode_skills)} 个, TRAE CN {len(trae_skills)} 个) return issues if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else . problems validate_superpowers(root) if problems: print(f发现 {len(problems)} 个问题:) for p in problems: print(f - {p}) sys.exit(1) else: print(Superpowers 配置校验通过)这个脚本检查四类问题技能定义文件的存在性和格式、YAML 元数据的必填字段、技能引用的工具是否在注册表里、两边技能数量是否一致。参数上project_root传项目根目录脚本会自动去找superpowers/、.opencode/skills/、.trae/skills/这几个路径。如果你项目的目录结构不一样改脚本里的路径常量就行。把这个脚本挂到 git 的 pre-commit hook 里每次提交前自动跑一遍配置类的问题基本不会漏到协作环节。我用了大半年最明显的变化是以前跨环境配置出问题平均要花一两个小时排查现在大部分问题在提交前就被拦下来了真正需要人工介入的只剩那些跟具体运行环境相关的边界情况。最后一个习惯每次改完 Superpowers 配置不管校验脚本有没有报错我都会在 OpenCode 和 TRAE CN 里各跑一个最小任务验证一下。最小任务不需要复杂就是触发一个最简单的技能看它能不能正常调工具、正常返回结果。这个动作花不了两分钟但能挡住那些校验脚本覆盖不到的运行时问题。配置这东西静态检查再全也不如跑一遍来得实在。希望帮到你。本文还有配套的精品资源点击获取