企业官网建设流程全解析

简介：这份源码包面向使用 OpenCode 与 TRAE CN 进行开发的工程师，聚焦 Superpowers 插件与 ui-ux-pro-max 技能的配置落地，解决插件路径不一致、代码生成规则松散等实际问题。包内共 3 个文件，以 inscode 配置、html 页面与 gitignore 忽略规则为主，压缩包约 6KB，体量轻巧，便于直接嵌入现有工程目录结构。已有 2106 人学习下载，说明该配置方案在开发者社区中具备一定参考价值。读者可从中获取插件安装与符号链接设置的完整思路、前端 UI/UX 优化技能的启用方法，以及通过 AGENTS.md 或 opencode.json 约束代码输出的规则模板；针对 TRAE CN 的路径差异问题，也给出了可对照的排错方向。整体适合希望提升代码生成可靠性、减少手工调试成本的开发者作为配置参考。

1. 当 AI 编程助手开始“拼装技能”：OpenCode 与 TRAE CN 的 Superpowers 配置到底在解决什么

很多人第一次听到 OpenCode 与 TRAE CN 的 Superpowers 配置，会以为这又是一个“装完就变强”的插件合集。实际恰恰相反：它更像一套把 AI 编程助手从“单轮问答机器”改造成“可编排技能体”的接线方案。你手里可能已经有 OpenCode 这个终端里的编码代理，也可能在用 TRAE CN 这类带中文交互的 AI IDE，但默认状态下它们各自为战——OpenCode 擅长在命令行里读写文件、跑测试，TRAE CN 擅长在编辑器里做上下文补全和对话式重构，而 Superpowers 这一层配置的作用，就是把两者的能力通过统一的技能描述和调用约定串起来，让“让 AI 帮我改这个模块”从一句模糊指令，变成一条可追踪、可复现、可回滚的执行链。

这套配置适合谁？如果你只是偶尔让 AI 补个函数，那确实用不上；但如果你已经在用 AI 代理批量处理重构、跨文件迁移、测试补齐，并且被“它改到一半停了”“它不知道项目里还有另一个同名工具函数”这类问题折磨过，那 Superpowers 配置就是你需要认真看的东西。它解决的不是模型智商问题，而是模型在工程环境里的“手脚协调”问题。接下来的内容会从最小可跑通的配置讲起，一路讲到参数边界和翻车现场，尽量让你照着做就能复现。

2. Superpowers 配置的骨架：技能描述、调用约定与 OpenCode 侧接入

2.1 为什么不能直接把 TRAE CN 的对话能力塞进 OpenCode

先讲清楚一个容易翻车的认知：OpenCode 和 TRAE CN 虽然都叫“AI 编程助手”，但它们的执行模型不一样。OpenCode 更接近一个带工具调用能力的终端代理，它的核心循环是“读上下文 → 决定调哪个工具 → 执行 → 看结果 → 继续”，工具包括读文件、写文件、跑 shell、搜索仓库等。TRAE CN 则更偏向编辑器内的交互层，它的强项是理解当前打开文件的语义、给出中文注释和重构建议，但它的工具边界通常被限制在编辑器 API 范围内。

Superpowers 配置要做的，不是把两者合并成一个进程，而是定义一套双方都能识别的“技能描述文件”。这个文件用自然语言加结构化字段描述一个技能：技能名、触发条件、需要的工具权限、输入输出约定、失败回退策略。OpenCode 侧读取这个描述后，把它注册成自己可调用的一个工具；TRAE CN 侧则通过配置项把这个技能挂到对应的命令或快捷键上。两边不直接通信，而是通过共享的技能描述和同一套项目上下文来对齐行为。

常见做法是：在项目根目录建一个.superpowers/目录，里面放skills.yaml和context.md。skills.yaml定义技能，context.md写项目级的约定，比如“所有数据库操作必须走 repository 层”“测试文件放在__tests__下”。OpenCode 启动时会读这两个文件，TRAE CN 的配置项里也会指向同一个目录。这样无论你从终端还是从编辑器触发，AI 看到的约束是一致的。

2.2 最小可跑通的 skills.yaml 与 OpenCode 注册命令

下面是一个能跑通的最小技能描述。它定义了一个“安全重命名符号”的技能：当用户要求重命名某个函数或变量时，AI 不能直接全局替换，而是要先搜索引用、列出影响范围、等确认后再改。

# .superpowers/skills.yaml version: 1 skills: - name: safe_rename_symbol description: > 在项目中安全重命名一个符号。必须先搜索所有引用， 列出文件与行号，生成影响报告，确认后再执行替换。 triggers: - "重命名" - "rename symbol" tools: - search_references - read_file - write_file - run_tests input_schema: symbol: string new_name: string scope: string # 可选，限定目录 output_schema: report_path: string changed_files: array fallback: abort_and_report

这个文件里几个字段值得展开。triggers是给 TRAE CN 侧用的，当对话里出现“重命名”时，编辑器会把请求路由到这个技能，而不是直接让模型自由发挥。tools是给 OpenCode 侧用的，它决定了这个技能执行时能调用哪些底层工具；如果你没写run_tests，那 AI 改完就不会自动跑测试，这在重构场景里很危险。fallback: abort_and_report表示一旦搜索引用失败或测试不通过，就停止并输出报告，而不是继续硬改。

注册到 OpenCode 的方式通常是在它的配置文件里加一段：

# opencode.config.yaml superpowers: enabled: true skills_dir: .superpowers auto_load: true max_skill_depth: 3

max_skill_depth控制技能嵌套层数。比如“安全重命名”内部可能调用“生成影响报告”这个子技能，子技能再调用“格式化输出”。层数太深会导致调试困难，一般设 2 到 3 就够。设成 1 则禁止嵌套，适合刚上手时排查问题。

2.3 TRAE CN 侧如何挂载同一套技能描述

TRAE CN 的配置入口通常在设置里的“AI 助手”或“扩展配置”区域，不同版本叫法可能不同，但核心是找到一个能指定“外部技能目录”的字段。把路径指向项目根目录的.superpowers/，然后开启“优先使用项目技能”选项。这样当你在编辑器里选中一个函数名说“重命名这个”，TRAE CN 不会直接把请求发给模型，而是先查skills.yaml里有没有匹配的 trigger，有就走技能流程。

这里有个容易忽略的点：TRAE CN 和 OpenCode 对“项目根目录”的判定可能不一致。OpenCode 通常以它启动时的当前工作目录为准，TRAE CN 则以编辑器打开的工作区根目录为准。如果你在 monorepo 里，子包目录下也有.superpowers/，两边可能读到不同的文件。稳妥做法是在项目最外层放一份主配置，子包用extends字段继承：

# packages/some-module/.superpowers/skills.yaml version: 1 extends: ../../.superpowers/skills.yaml skills: - name: module_specific_lint description: 该模块特有的 lint 规则检查 triggers: ["lint 这个模块"] tools: [run_shell]

extends的路径解析规则一般是相对于当前文件，但不同工具实现可能有差异，建议用绝对路径或从根目录算起的路径，避免玄学问题。

3. 把技能跑起来：从单技能验证到多技能编排的实操步骤

3.1 用一条命令验证技能是否被正确加载

配置写完不要急着上复杂任务，先验证 OpenCode 能不能识别到技能。常见做法是跑一个自检命令：

opencode superpowers list --dir .superpowers

如果输出里能看到safe_rename_symbol及其工具列表，说明加载成功。如果报“skills_dir not found”，先检查路径是相对还是绝对；如果报“yaml parse error”，多半是缩进问题，YAML 对空格敏感，tab 会直接翻车。还有一个隐蔽情况：技能名重复。如果extends的父配置和子配置里有同名技能，不同工具的处理策略不同，有的后者覆盖前者，有的直接报冲突。稳妥做法是子配置里只写新增技能，不要重复定义。

验证 TRAE CN 侧是否挂载成功，可以在编辑器里触发一个 trigger 词，然后看输出里有没有出现技能名。比如输入“重命名 getUserInfo 为 fetchUserProfile”，如果返回的第一行是[skill: safe_rename_symbol]之类的标记，说明路由生效；如果直接开始改代码，说明技能没被识别，请求走了默认模型通道。

3.2 单技能执行：安全重命名的完整流程与参数说明

假设验证通过，现在实际跑一次重命名。在 OpenCode 里可以这样调用：

opencode run "重命名 getUserInfo 为 fetchUserProfile，范围限定在 src/services"

技能执行时会按skills.yaml里定义的流程走。第一步是search_references，它会在指定 scope 内搜索getUserInfo的所有出现位置，包括定义、调用、类型引用、字符串里的硬编码。这里有个参数边界：搜索是否包含测试文件和文档文件。默认通常包含，但如果你的测试里有 mock 数据也叫这个名字，可能会被误报。可以在skills.yaml的input_schema里加一个include_tests: boolean，默认 false，需要时再开。

第二步是生成影响报告，通常写到.superpowers/reports/rename_<timestamp>.md。报告里会列出每个文件的路径、行号、上下文片段。这一步是给你后悔药用的——如果报告里出现了你不想改的地方，可以中断，手动调整 scope 后重跑。

第三步是执行替换。替换不是简单的字符串替换，而是按符号边界匹配，避免把getUserInfoCache里的getUserInfo也改掉。这一步依赖语言解析能力，如果项目里混用了多种语言，解析器可能对某些文件失效，导致漏改或错改。常见做法是在skills.yaml里指定language_hint，比如typescript，让工具优先用对应解析器。

第四步是run_tests。如果测试不通过，技能会按fallback策略中止，并保留改动现场供你排查。这里建议把测试命令也写进配置，而不是让工具猜：

# .superpowers/skills.yaml 片段 - name: safe_rename_symbol # ... 其他字段 test_command: "npm run test -- --testPathPattern={{changed_dir}}"

{{changed_dir}}是模板变量，会被替换成实际改动的目录，这样只跑相关测试，避免全量测试拖慢反馈。参数说明：test_command支持模板变量，常见的有{{changed_files}}、{{changed_dir}}、{{symbol}}。如果测试命令里有空格或特殊字符，用引号包住整个值。

3.3 多技能编排：让“重构 + 补测试 + 更新文档”串成一条链

单技能跑通后，真正的效率提升来自编排。比如一个常见需求：“把这个模块里的回调风格改成 async/await，补上缺失的单元测试，并更新 README 里的示例”。这涉及三个技能：convert_callback_to_async、generate_missing_tests、update_readme_examples。在 Superpowers 配置里可以用pipeline字段把它们串起来：

# .superpowers/pipelines.yaml pipelines: - name: modernize_module steps: - skill: convert_callback_to_async input: target_dir: "{{user.target_dir}}" - skill: generate_missing_tests input: coverage_threshold: 80 depends_on: convert_callback_to_async - skill: update_readme_examples input: readme_path: "README.md" depends_on: generate_missing_tests on_failure: stop_and_report

depends_on保证执行顺序，前一步失败则后续不执行。on_failure除了stop_and_report，还可以设continue_with_warning，适合文档更新这类非关键步骤。coverage_threshold是生成测试的触发阈值，低于这个值才补测试，避免重复生成。

编排的坑在于上下文传递。第一步改了文件，第二步生成测试时需要知道改了哪些文件，这依赖第一步的输出被正确传递。如果output_schema里没定义changed_files，第二步就拿不到。所以每个技能的output_schema要写清楚，尤其是会被下游依赖的字段。另一个坑是超时：多技能链跑起来可能几分钟，OpenCode 默认超时可能不够，需要在配置里调skill_timeout_seconds，一般设 300 到 600。

4. 避坑与排查：Superpowers 配置里最容易翻车的五个地方

4.1 技能触发了但工具没权限，报“tool not permitted”

现象：TRAE CN 里输入 trigger 词后，技能名出现了，但紧接着报工具权限错误，比如write_file not permitted in current context。原因通常是skills.yaml里声明了write_file，但 OpenCode 的全局权限配置里没放开写操作，或者当前会话处于只读模式。解决：检查 OpenCode 配置里的permissions段，确保write_file和run_shell在允许列表里；如果是 TRAE CN 侧触发，还要看编辑器的“安全模式”是否开启，开启时会拦截所有写操作。

4.2 重命名漏改：字符串里的符号没被替换

现象：代码里的函数调用都改了，但某个配置文件或模板字符串里的旧名字还在，导致运行时找不到符号。原因：搜索引用时默认只解析代码文件，不解析.json、.yaml、.md里的文本。解决：在skills.yaml的search_references工具参数里加include_patterns，显式包含这些文件类型；或者单独跑一个“文本替换”技能，但要注意文本替换没有符号边界保护，容易误伤，建议先出报告再执行。

4.3 多技能链在第二步卡住，日志只显示“waiting for dependency”

现象：pipeline 执行到第二步就不动了，日志里反复出现等待依赖。原因：第一步技能虽然执行了，但output_schema里定义的字段没实际产出，导致依赖解析失败。常见于技能内部出错但没抛异常，而是返回了空结果。解决：在skills.yaml里给每个技能加validate_output: true，让工具在技能返回后校验输出字段是否存在，缺失则直接报错，而不是静默等待。同时检查第一步的日志，看是否有被忽略的警告。

4.4 TRAE CN 和 OpenCode 读到的配置不一致

现象：在终端里跑 OpenCode 技能正常，但在 TRAE CN 里触发同样的技能却行为不同，比如 scope 没生效。原因：两边的工作目录不同，或者 TRAE CN 缓存了旧版skills.yaml。解决：在skills.yaml里用绝对路径或环境变量定义关键路径；TRAE CN 侧修改配置后重启编辑器或手动清除技能缓存；在技能描述里加一个config_hash字段，执行时打印出来，方便对比两边读到的是不是同一份。

4.5 技能嵌套过深导致调试困难

现象：一个简单重命名跑了很久，日志里出现多层技能调用，出错时不知道是哪一层的问题。原因：max_skill_depth设得太大，或者技能之间互相调用形成了隐式循环。解决：初期把max_skill_depth设为 1 或 2，等稳定后再放开；在skills.yaml里禁止技能调用自身或形成环，可以用forbidden_calls字段显式声明；日志里给每个技能调用加唯一 ID，方便追踪。

5. 进阶技巧：用技能版本化与灰度验证让配置可回滚

5.1 给技能加版本号，避免“改配置把线上流程搞崩”

Superpowers 配置一旦被团队多人使用，最怕的是有人改了skills.yaml导致别人的流程失效。一个实用习惯是给每个技能加version字段，并在 pipeline 里锁定版本：

skills: - name: safe_rename_symbol version: 2 # ... pipelines: - name: modernize_module steps: - skill: safe_rename_symbol@2

这样即使有人把技能升到 v3，已有 pipeline 仍然用 v2，不会突然行为变化。版本升级时，先在新 pipeline 里试 v3，验证通过再逐步迁移。这个做法在多人协作的项目里能省下大量“昨天还好好的”类排查时间。

5.2 灰度验证：先用 dry-run 模式跑一遍影响报告

很多技能支持dry_run参数，开启后只生成报告不实际改文件。在正式执行前，先跑一次 dry-run，把报告发给相关人确认，再关掉 dry-run 执行。可以在 pipeline 里加一个preflight步骤：

pipelines: - name: modernize_module preflight: - skill: safe_rename_symbol@2 input: dry_run: true steps: - skill: safe_rename_symbol@2 input: dry_run: false

preflight的结果会作为执行步骤的输入之一，如果 preflight 报告里标记了高风险改动（比如涉及公共 API），可以配置require_approval: true，让流程暂停等人确认。这个机制在跨模块重构时特别有用，避免 AI 一口气改了几十个文件才发现方向错了。

5.3 一个我常用的验证习惯：改完先看 diff 统计，再看测试

不管技能描述写得多严谨，我最后都会做两步人工检查。第一步是看 diff 统计：

git diff --stat

如果改动文件数远超预期，比如只想改一个模块却动了二十个文件，大概率是 scope 没生效或搜索范围太宽，直接回滚重来。第二步是跑一次全量测试，而不是只跑技能里配置的增量测试。增量测试快，但可能漏掉跨模块影响；全量测试慢，但能兜住底。这个习惯帮我拦下过好几次“技能报告说没问题但实际破坏了公共接口”的情况。

配置这套东西的初衷不是让 AI 替你做决定，而是让它的每一步都留下痕迹、可验证、可回退。技能描述写得越具体，翻车概率越低；但也不要为了追求完美配置而迟迟不跑第一次，先让一个最小技能在真实项目里跑通，比读十篇配置指南都有用。希望帮到你。

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