企业官网建设流程全解析

简介：这份源码包面向使用 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', encoding='utf-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_ok=True) 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', encoding='utf-8') as f: json.dump(skill, f, ensure_ascii=False, indent=2) 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_mode，OpenCode 默认是 auto，TRAE 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」。工具注册表的核心字段有这几个：

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', encoding='utf-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', encoding='utf-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', encoding='utf-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 里各跑一个最小任务验证一下。最小任务不需要复杂，就是触发一个最简单的技能，看它能不能正常调工具、正常返回结果。这个动作花不了两分钟，但能挡住那些校验脚本覆盖不到的运行时问题。配置这东西，静态检查再全，也不如跑一遍来得实在。希望帮到你。

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