trae-superpowers: Instructions file for Claude Code

AGENTS.md

本文件为在此仓库工作的 AI 编码代理提供指引。

项目概述

trae-superpowers 把上游 obra/superpowers 的 skills 装入 Trae IDE 的全局 skills 目录；若共享的 ~/.agents/skills 已有完整 Superpowers， 则直接复用且不接管。项目用 Trae 的 User Rules 替代上游原生的 SessionStart Hook， 使 skills 从第一条消息起即生效。

产物是三个自包含的 bash 脚本（install.sh / update.sh / uninstall.sh）加双语文档，没有构建产物、 没有运行时依赖。

常用命令

# 运行全部行为测试（离线、隔离 HOME，不触碰真实环境）
bash tests/run_all.sh

# 单独运行某个测试
bash tests/test_install.sh
bash tests/test_update.sh
bash tests/test_uninstall.sh

# 本地离线跑安装脚本（用假 skills 源和显式目标，避免 git clone 与写入真实目录）
HOME=/tmp/fakehome SUPERPOWERS_TARGET=trae-cn \
  SUPERPOWERS_SKILLS_SRC=/path/to/fake bash install.sh

关键环境变量：

• SUPERPOWERS_SKILLS_SRC：注入本地 skills 源（其下需有 skills/ 子目录），跳过 git clone， 测试与本地验证均依赖它。
• SUPERPOWERS_UPSTREAM_URL：覆盖上游仓库地址，默认 https://github.com/obra/superpowers.git。
• SUPERPOWERS_TARGET：非交互环境下指定唯一目标，取值为 trae-cn 或 trae。
• SUPERPOWERS_TTY：测试专用的终端设备覆盖项，默认 /dev/tty；生产使用无需设置。

架构与关键文件

• install.sh：通过方向键菜单或 SUPERPOWERS_TARGET 单选 Trae 目标 → 优先复用 完整的 .agents/skills，否则获取上游 skills 源 → cp -R 写入所选 skills 目录并写 manifest。核心函数 select_target / target_skills_dir / agents_superpowers_state / resolve_src / copy_skills / write_manifest。
• update.sh：普通模式下唯一 manifest 自动定位，两处都有或都没有时单选；完整 .agents 存在时改由唯一托管 Rule 自动定位，歧义时单选。选定目标后清理孤儿并逐 skill 清替（先删后拷），最后覆盖写 manifest。
• uninstall.sh：完整 .agents 存在时无需选择，保留外部安装并清理两个 Trae 目录中 manifest 管理的副本及托管 Rule；普通模式下唯一 manifest 自动定位，歧义时单选， 再优先按 manifest 逐名删除（离线可用），无 manifest 时回退到上游 skills 清单。
• tests/test_helpers.bash：断言与隔离环境辅助（make_temp_home、 make_fake_src、assert_*、finish_tests）。兼容 bash 3.2，不用关联数组。
• README.md / README.zh-CN.md：英文默认 + 中文，结构须保持一致。

支持的 Trae 变体目录

两个候选根目录（$HOME 下）：.trae-cn（CN）、.trae（intl）。每次安装只选择一个目标， 目录不存在时自动创建；再次选择另一目标不会迁移或清理旧目标。._agent-cn / ._agent 不再探测、迁移或清理。