企业官网建设流程全解析

• 人工智能
• AI 技能
• 提示工程

本篇技术指南聚焦 agency-agents-zh 仓库中面向 Trae 的集成方案：如何把仓库内的 276 个 AI 智能体角色转换为 Trae 项目级 rule 文件并安装到<your-project>/.trae/rules/，同时彻底讲清楚"装了但几乎不自动触发"这一常见困惑的成因，并给出精选安装、显式@调用、alwaysApply三种真正可落地的激活方案。读完本文，你将掌握 Trae rule 的完整生命周期——从生成、安装到按需激活与故障排查，并能结合 scripts/convert.sh 与 scripts/install.sh 的源码理解其底层机制。

Trae rule 与 Cursor.mdc：同源的两种落地格式

agency-agents-zh 是一个以"即插即用 AI 专家角色"为核心的仓库，全部角色以带 YAML frontmatter 的.md文件组织在 engineering/、marketing/、design/、finance/ 等 20 个部门目录中。要让这些角色在 Trae 中生效，需要先经过一次格式转换：将仓库内 276 个智能体转换为 Trae 项目级 rule 文件，安装到<your-project>/.trae/rules/。

Trae rule 与 Cursor.mdc同源，差异仅在于两点：

两个工具共用同一套 frontmatter 语义（description/globs/alwaysApply），所以仓库内 Cursor 集成说明 中关于激活方式的思路同样适用于 Trae。正因同源，转换脚本中对两者的处理几乎一致——从 convert.sh 源码 可以看到convert_cursor与convert_trae两个函数生成的 frontmatter 结构完全相同，唯一区别是输出扩展名（.mdcvs.md）与输出目录（cursor/rules/vstrae/rules/）。

标准安装流程：两步完成转换与部署

Trae 属于**项目级（project-scoped）**工具，因此安装必须在目标项目根目录执行，而不是在 home 目录或仓库目录执行。完整流程分两步：

# 1. 在仓库目录生成 rule 文件 ./scripts/convert.sh --tool trae # 2. 切到目标项目根目录再安装（项目级，不要在 home 跑） cd /your/project /path/to/agency-agents-zh/scripts/install.sh --tool trae

执行后会得到<your-project>/.trae/rules/<agent-slug>.md一批文件。

第一步：convert.sh 做了什么

scripts/convert.sh 是一个纯 bash 转换器，通过--tool trae只跑 Trae 转换分支。其核心流程在run_conversions主循环中：遍历AGENT_DIRS声明的 20 个部门目录（academic、company、design、engineering……见 scripts/convert.sh），用find递归收集每个目录下的.md文件，跳过首行不是---（无 frontmatter）的文件，再用get_field提取源文件的name与description字段。

关键转换函数是convert_trae（scripts/convert.sh）：

convert_trae() { local file="$1" local name description slug outfile body name="$(get_field "name" "$file")" description="$(get_field "description" "$file")" slug="$(slugify_from_file "$file")" # 文件名去 .md → kebab-case slug body="$(get_body "$file")" # 去掉 frontmatter 保留正文 outfile="$OUT_DIR/trae/rules/${slug}.md" mkdir -p "$OUT_DIR/trae/rules" cat > "$outfile" <<HEREDOC --- description: ${description} globs: alwaysApply: false --- ${body} HEREDOC }

三个值得注意的机制：

• slug 直接取文件名：slugify_from_file就是basename "$file" .md，所以engineering-code-reviewer.md生成engineering-code-reviewer.md。这意味着 rule 文件名与仓库内角色文件一一对应，也决定了后文@调用的命名规则。
• 正文原样保留：源角色的完整身份、规则、工作流全部透传，只有 frontmatter 被重写为标准 rule 三字段。
• 输出目录：产物落在仓库的integrations/trae/rules/（该目录由 convert.sh 生成，已被仓库.gitignore排除，属于运行时产物而非版本库内容）。

转换数量以当前仓库实际角色数为准。原集成文档撰写时约为 215 条，而当前仓库经 scripts/check-counts.mjs 校验的角色总数是276 个（AGENT-LIST.md 同步记录），每次convert.sh --tool trae都会按当下仓库内容全量重新生成。

第二步：install.sh 如何部署

scripts/install.sh 的install_trae函数（scripts/install.sh）做的工作非常直接：

install_trae() { local src="$INTEGRATIONS/trae/rules" local dest="${PWD}/.trae/rules" ... mkdir -p "$dest" while IFS= read -r -d '' f; do cp "$f" "$dest/"; (( count++ )) || true done < <(find "$src" -maxdepth 1 -name "*.md" -print0) ok "Trae: $count 个规则 -> $dest" warn "Trae: 项目级安装。请在项目根目录运行。" }

注意dest="${PWD}/.trae/rules"—— 目标目录是当前工作目录下的.trae/rules，这正是文档强调"切到目标项目根目录再安装"的原因。如果误在 home 目录运行，规则会被装到 home 下的.trae/rules/，Trae 项目将完全看不到。这也是 integrations/README.md 中"For project-scoped tools such as OpenCode, Cursor, Aider, and Windsurf, run the installer from your target project root"所描述的项目级工具通用约束。

为什么"几乎不自动触发"是预期行为，不是 bug

这是使用 Trae 集成时最容易踩的认知坑，仓库已在 issue #59 中专门讨论过。问题的根源在于convert_trae生成的默认 frontmatter：

--- description: <角色一句话描述> globs: alwaysApply: false ---

这是 Cursor / Trae 共同约定的"agent-requested rule"——模型读完description后自己判断要不要把这条 rule 拉进当前上下文，而不是无条件常驻。一旦你install --tool trae把全部 276 条 rule 一次性装进项目，就会出现三重问题：

1. description 相互稀释：276 条描述同时存在于候选集里，模型很难判断"当前任务应该命中哪一条"；
2. 命中不等于常驻：即便某条被命中，也只是"读一下这条 rule"，不会变成长期生效的 system prompt；
3. 上下文预算被挤占：全量装载会消耗大量上下文预算，IDE 通常会挑选性截断，反而影响模型表现。

结论：默认全装 = 几乎不会自动触发。这是设计决定，不是安装失败。理解了这一点，下面的三种正确姿势才有意义。

三种正确的使用姿势

姿势一：精选安装（强烈推荐）

只装你真正会用的 10–20 条，让自动匹配真正生效。两种做法任选：

# 先生成 ./scripts/convert.sh --tool trae # 再按需复制（rule 文件生成于仓库 integrations/trae/rules/ 下） mkdir -p /your/project/.trae/rules cp integrations/trae/rules/engineering-frontend-developer.md /your/project/.trae/rules/ cp integrations/trae/rules/engineering-code-reviewer.md /your/project/.trae/rules/ cp integrations/trae/rules/engineering-backend-architect.md /your/project/.trae/rules/ cp integrations/trae/rules/engineering-git-workflow-master.md /your/project/.trae/rules/ # ... 按当前项目的语言/框架/职责挑

或者更直接：先全装，再到.trae/rules/把用不上的删掉。筛选时可以参考 AGENT-LIST.md 中每个角色的 ID 与描述，例如前端项目挑engineering-frontend-developer、需要代码审查挑engineering-code-reviewer、重视质量门禁挑engineering-git-workflow-master。每挑一条，description的稀释程度就低一分，自动命中的概率就高一分。

姿势二：在对话里显式 @ 调用

即使全装，你也可以在 Trae Chat / Builder 里手动指定，强制加载某条 rule：

@engineering-pc-host-engineer 帮我审查这段 QSerialPort 的粘包处理 @engineering-code-reviewer 看下这次提交的安全风险

@后输入rule 文件名（去掉.md）即可定向加载。这条路径永远生效，不依赖模型的自动判断，是处理"低频但重要"的垂直角色的最可靠方式。

姿势三：把高频 rule 改为 alwaysApply

挑 1–3 条绝大多数对话都需要的规则（如代码审查标准、git 工作流），手动改其 frontmatter：

--- description: ... globs: "**/*.ts,**/*.tsx" # 也可按文件类型自动挂载 alwaysApply: true # 始终生效 ---

globs支持按文件类型自动挂载——例如只对 TypeScript 文件生效时写"**/*.ts,**/*.tsx"，相当于把这条 rule 变成特定场景下的常驻专家。但务必遵守一条红线：

⚠️ 不要把所有 rule 都改成alwaysApply: true——会爆上下文，且角色之间互相打架。

对照表：什么时候用哪种

故障排查

• .trae/rules/里有文件但 Trae 看不到：确认在项目根目录而不是 home 目录；重启 Trae 一次；扩展名必须是.md，不是.mdc。
• @<rule-name>补全列表里看不到刚装的 rule：Trae 启动时扫描一次目录，新装后需要重启窗口。
• 装了一堆但模型还是答得很泛：参见上文"几乎不自动触发"——把.trae/rules/里的文件砍到 10–20 条以内再试。
• 想看每条 rule 的 description：直接head -5rule 文件即可，frontmatter 一目了然。

重新生成与同步

修改了源 agent（engineering/、marketing/等目录下的.md）后，需要重新生成并重新安装才能生效：

./scripts/convert.sh --tool trae # 已经 install 过的项目需要重新跑一次 install --tool trae 才会同步

这背后的逻辑与安装步骤完全对称：convert.sh负责把源角色重新渲染为integrations/trae/rules/下的新产物，install.sh负责把新产物重新复制到项目的.trae/rules/。如果源角色文件本身有变动而忘记重跑两步，项目里跑的还是旧版 rule——这也是 scripts/check-counts.mjs 这类自检脚本存在的意义：它会在发布前校验文档中声明的角色数与仓库实际角色数一致，防止计数悄悄滞后。

小结

Trae 集成是 agency-agents-zh 多工具适配中的一环，其核心心智模型可以浓缩为三句话：rule 是 agent-requested 而非常驻的（所以默认全装不触发）；项目级工具必须在项目根目录安装（所以cd /your/project是关键步骤）；10–20 条精选 + 1–2 条 alwaysApply + 按需 @ 是黄金组合（所以别贪多）。掌握了这三条，再配合 convert.sh 与 install.sh 的源码理解，你就能在这 276 个专家角色中按需取用，让 Trae 的自动匹配真正为你工作。

• 人工智能
• AI 技能
• 提示工程