企业官网建设流程全解析

1. 项目概述：Superpowers 不是超能力，而是开发者工具链的“认知增强层”

你搜“superpowers”时，第一反应可能是漫威电影里的变种人，或者某个科幻游戏的技能树。但最近半年，在开发者社区、技术论坛和 GitHub Trending 榜单上反复刷屏的Superpowers，根本不是虚构设定——它是一套正在悄然重构本地开发工作流的智能辅助协议层，本质是让 IDE（比如 Cursor、VS Code）与后端 AI 编程服务（如 Claude Code、Codex CLI、Antigravity）之间建立稳定、可配置、带上下文感知的通信管道。它不直接写代码，也不训练模型，而是像一个“翻译官+调度员+缓存代理”的三合一中间件，把开发者在编辑器里敲下的每一行提示词、选中的代码块、甚至光标停留位置，精准地打包、路由、增强后，发给最适合的 AI 引擎处理，再把结果结构化地回传、高亮、可编辑地呈现出来。

核心关键词Superpowers在这里不是品牌名，而是一个功能抽象概念：它代表的是“让现有开发工具瞬间获得超出原生能力的智能响应能力”。你不需要换掉熟悉的 Cursor 或 VS Code，也不用硬着头皮去配 Docker、改环境变量、手动拉取二进制；Superpowers 的设计哲学就是“零侵入式增强”——它通过标准 LSP（Language Server Protocol）扩展、轻量级 CLI 注入、以及 IDE 插件桥接这三层，把 Claude Code 的长上下文理解、Codex CLI 的本地代码索引能力、Antigravity 的实时沙盒执行，全部变成你编辑器里 Ctrl+Enter 就能调用的快捷操作。我去年在团队内部做技术选型时，对比过 7 种类似方案，最后锁定 Superpowers 的关键原因就一条：它不强制你用它的 UI，也不要求你迁移到它的云平台，而是真正尊重你已有的技术栈和工作习惯。你用 Java 写 Spring Boot？Superpowers 能自动识别@RestController注解，把请求路径和参数结构注入到提示词里；你用 Python 调 pandas？它会主动抓取.head()输出样本，帮你生成后续分析逻辑。这种“懂你正在写的代码”的能力，才是它被称作“superpowers”的真实原因。

它解决的不是“有没有 AI”的问题，而是“AI 怎么才不添乱”的问题。太多开发者装完 Claude Code 插件，发现它要么卡在 loading，要么返回一堆无关的伪代码，要么把整个文件当上下文塞给模型导致 token 爆仓。Superpowers 的价值恰恰在于它内置了一套“AI 使用守则”：自动截断非相关代码段、识别并保留类型定义、对敏感字段（如 API Key、密码字段）做模糊化脱敏、甚至能根据当前文件后缀动态切换后端引擎——Java 文件优先走 Codex CLI 做静态分析，Markdown 文档则直连 Claude Code 做内容润色。这不是炫技，而是把 AI 从“不可控的黑箱”变成了“可预期的协作者”。适合谁？不是只给算法工程师，而是给所有每天要写 CRUD、修 Bug、读祖传代码的中阶开发者——你不需要懂 transformer 架构，但你需要一个能听懂你“帮我把这段 for 循环改成 stream API”的工具。它不替代你思考，但让你的思考更少被环境打断。

2. 核心架构拆解：为什么 Superpowers 不是另一个插件，而是一套协议

2.1 它不是独立应用，而是“协议层 + 运行时 + 配置中心”三位一体

很多初学者第一次接触 Superpowers，会下意识去官网找 .exe 或 .dmg 下载包，结果发现根本没有。这是因为 Superpowers 本身不提供 GUI，也不打包任何大模型权重。它的核心是一个开源协议规范（GitHub 上叫superpowers-spec），定义了 IDE、本地运行时、远程 AI 服务三者之间如何交换数据。你可以把它理解成 HTTP 协议之于浏览器——Chrome 和 Firefox 都遵循 HTTP，但它们自己并不实现 TCP/IP 栈；同样，Cursor 和 VS Code 只需集成 Superpowers 兼容的插件（比如cursor-superpowers-bridge），就能调用任何符合该协议的后端服务，无论它是跑在你本机的 Codex CLI，还是公司内网的 Antigravity 实例，甚至是自建的 Claude Code 代理节点。

这个协议最关键的三个字段是context、intent和constraints。context不是简单地把当前文件全文发过去，而是由 Superpowers 运行时动态提取的结构化信息：AST 节点路径（告诉你光标在哪个方法体内）、最近的 import 语句（推断你可能要用的库）、Git 差异标记（只传 dirty lines）、甚至是你最近 5 分钟内搜索过的 symbol（暗示你当前关注的模块）。intent是用户操作的语义归类，比如 Ctrl+Enter 在函数内触发的是refactor，在注释行触发的是explain，在空行触发的是generate——它不依赖用户输入的提示词文字，而是结合编辑器状态自动判断。constraints则是硬性规则：最大 token 数、是否允许联网、是否启用代码执行、输出格式必须是 Markdown 还是纯文本。我实测过，当constraints.execution = true且当前文件是 Python 时，Superpowers 会自动启动一个隔离的临时 venv，把生成的代码片段丢进去跑pytest，只有通过才返回结果；否则直接报错“执行失败”，而不是返回一串看似合理实则无法运行的代码。这种“意图驱动 + 约束执行”的设计，才是它区别于普通 Copilot 类插件的根本。

2.2 为什么必须搭配 Codex CLI、Antigravity、Claude Code？它们各自承担什么角色

Superpowers 协议本身不包含 AI 模型，它需要后端引擎来执行具体任务。目前生态中最主流的三个组合是：

• Codex CLI：定位是“本地代码理解专家”。它不联网，不调用 API，而是基于你项目根目录下的codex.yaml配置，用 Rust 编写的轻量解析器扫描整个代码库，构建符号表、调用图、依赖关系图。当你在 Controller 层按 Ctrl+Enter 请求“生成对应 Service 方法”，Codex CLI 能精准定位到UserService类，找出它已有的findUserById方法签名，并生成参数匹配、异常处理完备的新方法体。它的优势是快（毫秒级响应）、稳（不依赖网络）、准（完全基于你的真实代码结构）。但短板也很明显：无法处理自然语言描述的模糊需求，比如“让这个接口支持分页”，它需要你明确说“在listUsers方法里加Pageable参数”。

• Antigravity：定位是“安全沙盒执行器”。它解决的是“AI 生成的代码到底能不能跑”的终极信任问题。当你勾选“执行并验证”选项，Antigravity 会在内存隔离的容器里启动一个极简运行时（Java 用 GraalVM Substrate VM，Python 用 Pyodide WebAssembly），加载你当前项目的最小依赖集，然后执行生成的代码片段。它甚至能捕获NullPointerException并反向定位到源码第几行——不是简单地告诉你“运行出错”，而是指出“你在第 42 行调用了 null 对象的getName()方法”。我遇到过最典型的场景：AI 建议用Optional.orElseThrow()，但项目 JDK 是 8，Antigravity 直接报错并推荐降级为Guava的Optional。这种“编译器级”的反馈，是纯语言模型永远给不了的。

• Claude Code：定位是“高级语义协作者”。它负责处理 Codex CLI 和 Antigravity 都搞不定的开放性问题：重构建议、文档补全、跨文件逻辑串联、技术选型咨询。比如你选中一段 Kafka 消费者代码，问“怎么改成批量消费模式”，Claude Code 会结合你项目里已有的spring-kafka版本、application.yml中的配置项，给出带BatchListener示例、ConcurrentKafkaListenerContainerFactory配置、以及性能调优参数的完整方案。但它有个硬性前提：必须通过 Superpowers 的constraints严格限制其作用域，否则容易陷入“百科全书式回答”。我们团队的约定是：Claude Code 只响应带明确文件路径和行号的请求，比如“/src/main/java/com/example/OrderService.java:87”，绝不处理“帮我设计一个订单系统”这种宽泛问题。

这三者不是互斥的，而是按需协同。一次典型的 Superpowers 调用流程是：用户触发快捷键 → Superpowers 运行时收集context→ 判断intent为refactor→ 查constraints发现execution = true→ 先调 Codex CLI 生成候选代码 → 再交 Antigravity 执行验证 → 若失败则用 Claude Code 分析错误日志并重写 → 最终把通过验证的代码注入编辑器。整个过程对用户透明，你只看到一个“正在优化…”的状态条，背后却是三套引擎的精密配合。

2.3 为什么 Cursor 成为事实上的首选前端？VS Code 用户怎么办

从热词搜索数据看，“cursor superpowers”、“cursor 中文设置”、“cursor 下载插件”的搜索量远超 VS Code 相关词，这不是偶然。Cursor 原生深度集成了 Superpowers 协议栈：它的编辑器内核直接暴露了superpowers.contextProviderAPI，允许插件直接读取 AST、Git 状态、甚至调试器变量快照。更重要的是，Cursor 的 Settings UI 里有一个专门的 “Superpowers” 页签，可以图形化配置每个后端引擎的路径、超时时间、默认constraints，连codex.yaml的 schema 校验都是实时的。我试过在 Cursor 里修改codex.yaml的exclude_patterns，保存后立刻生效，无需重启。

VS Code 用户并非不能用，只是多一层适配。官方维护的vscode-superpowers插件本质是个“协议翻译器”：它监听 VS Code 的textDocument/didChange事件，用 TypeScript 重实现了一套简易版的 context 提取逻辑（基于 Monaco Editor 的 model API），再把结果序列化成 Superpowers 协议要求的 JSON 格式。问题在于，VS Code 的 API 对 AST 解析支持有限，它无法像 Cursor 那样获取完整的语法树节点，只能靠正则和行号粗略定位。比如你在 Java 的switch语句里请求“添加 default 分支”，VS Code 版本可能把整个类文件当上下文发过去，导致 Codex CLI 处理变慢；而 Cursor 能精确到switch语句块的起始和结束行号。这不是插件作者偷懒，而是底层编辑器能力的客观差异。所以如果你重度使用 Java/TypeScript 且依赖精准重构，Cursor 是更省心的选择；如果主要写脚本、Markdown 或前端，VS Code 加上vscode-superpowers插件完全够用，甚至更轻量。

提示：不要试图在 VS Code 里强行安装 Cursor 的专属插件（如cursor-codex-bridge），它们依赖 Cursor 私有 API，会直接报Cannot find module 'cursor-core'错误。正确做法是只装vscode-superpowers，然后手动配置codex.cliPath指向你本地安装的 Codex CLI 二进制文件。

3. 实操部署全流程：从零开始搭建属于你的 Superpowers 工作流

3.1 环境准备与基础依赖安装（以 macOS 为例，Windows/Linux 同理）

Superpowers 的部署不是“一键安装”，而是“分层配置”。我建议按“运行时 → 后端引擎 → 前端 IDE”顺序推进，每一步都验证通过再继续，避免问题叠加。以下是我在线上团队落地时验证过的最小可行配置（macOS Sonoma, Apple Silicon）：

第一步：安装 Superpowers 运行时（CLI）
Superpowers 官方不提供预编译二进制，必须从源码构建。这不是为了增加门槛，而是确保它能精确匹配你本地的 Node.js 版本和架构。打开终端，执行：

# 1. 克隆官方仓库（注意：必须用 --recursive 获取子模块） git clone --recursive https://github.com/superpowers/superpowers-cli.git cd superpowers-cli # 2. 检查 Node.js 版本（必须 >= 18.17.0，< 20.x） node -v # 如果低于要求，请用 nvm 安装：nvm install 18.17.0 && nvm use 18.17.0 # 3. 安装依赖并构建 npm ci # 用 ci 而不是 install，确保 lockfile 一致 npm run build # 4. 全局链接（让其他工具能找到它） npm link

构建成功后，运行superpowers --version应该输出类似v0.9.4-alpha.3的版本号。注意：npm link会把superpowers命令软链接到/usr/local/bin，如果你用 zsh，可能需要执行hash -r刷新命令缓存。这一步最容易出错的是 Node.js 版本不匹配——我见过最多的问题是开发者用 nvm 切换了版本，但终端新开窗口后又回到系统默认的 16.x，导致npm ci报ERR_OSSL_PEM_NO_START_LINE错误。解决方案：在~/.zshrc里固定一行nvm use 18.17.0，然后source ~/.zshrc。

第二步：安装 Codex CLI（本地代码理解引擎）
Codex CLI 是 Rust 编写的，所以先装 Rust 工具链：

# 1. 安装 rustup（Rust 官方安装器） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env # 2. 验证安装 rustc --version # 应输出 rustc 1.78.0 (9b12b1234 2024-05-01) # 3. 从 GitHub Releases 下载预编译二进制（推荐，比源码编译快） # 访问 https://github.com/codex-cli/codex-cli/releases 找最新版，例如 v0.12.0 curl -L https://github.com/codex-cli/codex-cli/releases/download/v0.12.0/codex-cli-macos-arm64 -o /usr/local/bin/codex chmod +x /usr/local/bin/codex # 4. 验证 codex --version # 应输出 codex-cli 0.12.0

注意：不要用cargo install codex-cli，因为官方 crate registry 上的版本滞后于 GitHub Releases，且缺少针对 Apple Silicon 的优化。下载二进制时务必选择macos-arm64（M1/M2/M3）或macos-x86_64（Intel），选错会导致Bad CPU type in executable错误。

第三步：配置 Antigravity（安全执行沙盒）
Antigravity 的安装最简单，因为它本质是一个 Docker Compose 项目：

# 1. 确保 Docker Desktop 已安装并运行 docker --version # 应输出 Docker version 24.0.0+ # 2. 克隆仓库并启动 git clone https://github.com/antigravity/antigravity.git cd antigravity docker compose up -d # 3. 验证服务是否就绪（等待约 30 秒） curl http://localhost:8080/health # 应返回 {"status":"ok"}

Antigravity 默认监听http://localhost:8080，这是 Superpowers 运行时调用它的地址。如果你的 Docker 绑定到了其他端口（比如公司 IT 锁死了 8080），需要修改antigravity/docker-compose.yml里的ports配置，并同步更新 Superpowers 的config.yaml。另外，Antigravity 启动时会下载 GraalVM 和 Pyodide 的镜像，首次运行可能较慢，耐心等待docker compose logs -f显示Started Antigravity server即可。

3.2 Superpowers 核心配置文件详解（config.yaml）

Superpowers 的行为完全由~/.superpowers/config.yaml控制。这个文件不是自动生成的，必须手动创建。以下是我在生产环境使用的精简版配置，每一行都附带真实场景解释：

# 全局超时设置（单位：毫秒） timeout: 15000 # 后端引擎配置 engines: # Codex CLI 配置 codex: enabled: true # 必须指向你安装的 codex 二进制路径 binary: "/usr/local/bin/codex" # 指向项目根目录下的 codex.yaml（见下一节） config: "codex.yaml" # 当 Codex CLI 响应超时时，是否降级到 Claude Code fallback: "claude" # Antigravity 配置 antigravity: enabled: true # 必须和 docker compose 的端口一致 endpoint: "http://localhost:8080" # 执行超时，太短会误判，太长影响体验 timeout: 8000 # Claude Code 配置（以官方桌面版为例） claude: enabled: true # 桌面版安装后，会注册一个自定义协议 handler # macOS 路径通常是 ~/Applications/Claude\ Code.app/Contents/MacOS/Claude\ Code binary: "/Users/yourname/Applications/Claude Code.app/Contents/MacOS/Claude Code" # 如果用网页版，这里填 https://claude.ai # endpoint: "https://claude.ai" # 默认约束（全局生效，可被单次请求覆盖） defaults: # 是否允许 AI 执行代码（仅 Antigravity 支持） execution: false # 是否允许联网（影响 Claude Code 的搜索能力） internet: true # 输出格式：markdown（带语法高亮）或 plain（纯文本） format: "markdown" # 最大 token 数，防止大文件拖垮模型 maxTokens: 4096 # 语言特定规则（覆盖 defaults） languageRules: java: # Java 项目默认开启执行验证，因为编译错误太常见 execution: true # 强制使用 Codex CLI 作为主引擎，Claude 仅作 fallback primaryEngine: "codex" python: # Python 默认允许联网，方便查 pip 包文档 internet: true markdown: # Markdown 文档默认用 Claude Code，擅长润色和结构化 primaryEngine: "claude"

这个配置的关键在于languageRules—— 它让 Superpowers 真正“懂语言”。比如你打开一个.java文件，即使没手动开启execution，Superpowers 也会自动把constraints.execution设为true，调用 Antigravity 去验证生成的代码；而打开.md文件，它会忽略 Codex CLI，直连 Claude Code。我曾经因为忘了配languageRules.java.primaryEngine，导致在 Java 文件里 Ctrl+Enter 总是调用 Claude Code，返回一堆不贴合 Spring Boot 规范的伪代码，浪费了整整一天排查时间。所以这条配置不是可选项，而是必选项。

3.3 项目级配置：codex.yaml如何让 AI 真正理解你的代码

codex.yaml是 Codex CLI 的灵魂，它告诉引擎“你的代码库长什么样”。这个文件必须放在你 Git 仓库的根目录，Superpowers 运行时会自动找到它。以下是我们电商项目的真实codex.yaml（已脱敏）：

# 项目元信息 project: name: "ecommerce-backend" language: "java" # 指向 Maven 的 pom.xml，Codex CLI 会解析它来获取依赖 buildFile: "pom.xml" # 代码扫描规则 scan: # 包含哪些源码目录（必须是相对路径） include: - "src/main/java" - "src/main/resources" # 排除哪些目录（提高扫描速度） exclude: - "**/test/**" - "**/generated/**" - "src/main/resources/application-dev.yml" # 敏感配置不纳入上下文 # 符号映射（关键！让 AI 知道缩写代表什么） symbols: # 自定义注解映射 "@RestController": "Spring MVC REST controller" "@Service": "Spring service layer bean" "@Repository": "Spring data access layer" # 常用类映射 "Pageable": "Spring Data pagination interface" "ResponseEntity": "Spring HTTP response wrapper" # 模板片段（AI 生成时自动插入的代码块） templates: # 生成 Controller 方法时的默认模板 controllerMethod: - "public ResponseEntity<?> {{methodName}}({{params}}) {" - " try {" - " // TODO: implement business logic" - " return ResponseEntity.ok().build();" - " } catch (Exception e) {" - " log.error(\"Error in {{methodName}}\", e);" - " return ResponseEntity.status(500).build();" - " }" - "}" # 自定义指令（AI 能理解的特殊命令） instructions: - "当用户请求 '生成 Service 方法' 时，必须检查对应的 Repository 接口是否存在，并在 Service 方法中调用它。" - "当用户请求 '添加日志' 时，必须使用 SLF4J 的 log.error() 或 log.info()，禁止使用 System.out.println。"

这个配置的价值在于“把团队规范编码化”。比如symbols里定义@RestController的含义，Codex CLI 就能在生成代码时，自动为你加上@RequestMapping("/api")和@ResponseBody；templates里的controllerMethod模板，确保所有新生成的 Controller 方法都包含统一的异常处理结构；而instructions则是硬性规则，Codex CLI 的 Rust 解析器会把这些指令编译成 AST 匹配规则，违反规则的生成结果会被直接拒绝。我亲眼见过一个新人提交的 PR，因为codex.yaml里写了“禁止 System.out.println”，Superpowers 在他本地生成代码时就直接报错，逼着他去学 SLF4J——这比 Code Review 时打回去高效十倍。

3.4 Cursor 前端集成与中文设置（避坑指南）

Cursor 的 Superpowers 集成是开箱即用的，但有几个隐藏设置必须手动调整，否则你会觉得“这玩意儿不如 Copilot”：

第一步：启用 Superpowers 插件
打开 Cursor → Command Palette (Cmd+Shift+P) → 输入Extensions: Install Extensions→ 搜索Superpowers→ 安装Superpowers for Cursor。安装后重启 Cursor。

第二步：配置 Superpowers 路径
Cursor 默认找不到你本地的superpowersCLI，必须手动指定：

• 打开 Settings (Cmd+,) → 搜索superpowers→ 找到Superpowers: Cli Path
• 点击Edit in settings.json→ 在settings.json里添加：

{ "superpowers.cliPath": "/usr/local/bin/superpowers" }

注意：路径必须是绝对路径，且指向superpowers可执行文件，不是目录。如果填错，Cursor 启动时会报Failed to launch superpowers CLI，但错误日志藏在Help → Toggle Developer Tools → Console里，很多人找不到。

第三步：设置中文界面（Cursor 1.5+ 版本）
Cursor 的中文支持是渐进式的，不是简单改语言：

• 打开 Settings → 搜索locale→ 找到Locale设置项
• 从下拉菜单选择zh-CN（不是Chinese，那个是旧版）
• 关键一步：关闭 Cursor，重新打开。很多用户卡在这里，以为设置了就生效，其实必须重启。

第四步：配置快捷键与默认行为
Cursor 的默认快捷键Cmd+K是聚焦命令面板，和 Superpowers 冲突。我推荐改成Cmd+Shift+K：

• Settings →Keyboard Shortcuts→ 搜索superpowers
• 找到Superpowers: Trigger Action→ 点击左侧图标 → 输入Cmd+Shift+K
• 同时，禁用Cmd+K的默认行为（右键 →Remove Keybinding）

第五步：验证集成是否成功
新建一个 Java 文件，写一个空的public class Test {，把光标放在{后面，按Cmd+Shift+K，输入生成 main 方法。如果看到右下角出现Superpowers: Generating...，几秒后插入标准的public static void main(String[] args)，说明集成成功。如果卡住，打开Help → Toggle Developer Tools → Console，看是否有HTTP 403或Connection refused错误——前者是 Antigravity 的 endpoint 配错了，后者是 Docker 没启动。

4. 实战技巧与高频问题排查：那些文档里不会写的真相

4.1 “Unable to locate the codex cli binary” 错误的 3 种真实原因与解法

这个错误在热词搜索里排前三（unable to locate the codex cli binary or required runtime components. check），但官方文档只说“检查路径”，根本没提具体怎么查。根据我帮 12 个团队排查的经验，90% 的情况是以下三种之一：

原因一：路径权限问题（macOS/Linux 最常见）
你用curl下载的codex二进制默认没有执行权限。ls -l /usr/local/bin/codex会显示-rw-r--r--，而不是-rwxr-xr-x。解决方案很简单：

sudo chmod +x /usr/local/bin/codex

但要注意：如果codex文件在~/Downloads里，你sudo chmod之后再mv到/usr/local/bin，权限会丢失！正确做法是mv之后再chmod。

原因二：PATH 环境变量未生效（VS Code 用户专属）
VS Code 启动时会继承系统 shell 的 PATH，但如果你用nvm管理 Node.js，nvm的 PATH 是在~/.zshrc里设置的，而 VS Code 可能从~/.bash_profile启动，导致找不到codex。验证方法：在 VS Code 的 Terminal 里运行which codex，如果返回空，说明 PATH 有问题。解决方案：

• 打开 VS Code →Cmd+Shift+P→Developer: Reload Window with Extensions Disabled
• 然后Cmd+Shift+P→Shell Command: Install 'code' command in PATH
• 重启 VS Code

原因三：Codex CLI 版本与 Superpowers 协议不兼容（隐蔽陷阱）
Superpowers 协议是演进的，v0.9.x 要求 Codex CLI v0.12.0+，但如果你用brew install codex-cli，Homebrew 目前只提供 v0.10.0。codex --version显示0.10.0，但 Superpowers 运行时发了一个 v0.12.0 才支持的scanContext字段，Codex CLI 直接忽略，返回空响应，Superpowers 就判定为“binary not found”。解决方案：必须用 GitHub Releases 下载，别信包管理器。

实操心得：每次升级 Superpowers 或 Codex CLI 后，务必运行superpowers validate --engine codex。这个命令会模拟一次完整调用，输出详细的协议握手日志。如果看到Received invalid response from codex: missing field 'symbols'，就是版本不匹配的铁证。

4.2 “Antigravity 403” 和 “Agent execution terminated due to error” 的根源与修复

这两个错误看似是 Antigravity 的问题，实则是 Superpowers 的constraints配置不当：

“Antigravity 403” 的真相
HTTP 403 不是权限问题，而是 Antigravity 的安全策略触发。它默认只允许执行来自localhost的请求，且要求Originheader 为http://localhost:5328（Cursor 的默认端口）。如果你在config.yaml里把antigravity.endpoint配成了https://my-antigravity.company.com，但没在 Antigravity 的docker-compose.yml里配置CORS_ORIGINS环境变量，就会 403。修复方法：

• 修改antigravity/docker-compose.yml，在antigravity服务下添加：

environment: - CORS_ORIGINS=http://localhost:5328,https://my-antigravity.company.com

• docker compose down && docker compose up -d

“Agent execution terminated due to error” 的典型场景
这不是 Antigravity 崩溃，而是它检测到危险操作主动终止。最常见的两种情况：

• Java 项目里生成了System.exit(0)：Antigravity 的沙盒会拦截Runtime.getRuntime().exit()调用，并返回此错误。解决方案：在codex.yaml的instructions里加一条"禁止生成 System.exit() 调用"。
• Python 项目里用了os.system('rm -rf /')类命令：Antigravity 的 WebAssembly 运行时没有os模块，但会捕获ImportError并终止。解决方案：在config.yaml的languageRules.python下加constraints.sandbox: "strict"，强制启用更严格的沙盒。

注意：Antigravity 的日志非常详细。当出现执行错误时，不要只看 Superpowers 的报错，一定要运行docker compose logs antigravity | tail -20，里面会有类似Blocked call to os.system with args: ['rm', '-rf', '/']的原始记录，这才是根因。

4.3 Claude Code “Not available in your country” 的合规绕过方案

热词里频繁出现note: claude code might not be available in your country. check supported co，这不是网络问题，而是 Claude Code 桌面版的地理围栏（Geofencing）策略。它通过设备 IP 和系统语言双重校验，只要你的 macOS 语言设为en-US且 IP 在支持列表外，就会弹窗。但 Superpowers 协议允许你用endpoint指向自建代理，前提是代理符合协议：

合法方案：用公司内网的 Claude Code 代理节点
我们团队的做法是，在 AWS EC2 上部署一个 Nginx 反向代理：

# /etc/nginx/sites-available/clauder-proxy upstream claude_upstream { server api.anthropic.com:443; } server { listen 8081 ssl; server_name claude-proxy.internal; ssl_certificate /etc/letsencrypt/live/clauder-proxy.internal/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/clauder-proxy.internal/privkey.pem; location / { proxy_pass https://claude_upstream; proxy_set_header Host api.anthropic.com; proxy_set_header X-Real-IP $remote_addr; # 关键：伪造地理位置头，必须是支持国家的 ISO 代码 proxy_set_header X-Forwarded-For "203.0.113.1"; proxy_set_header X-Country-Code "US"; } }

然后在config.yaml里把claude.endpoint改成http://claude-proxy.internal:8081。注意：X-Country-Code必须是 Anthropic 官方支持的国家代码（US、GB、CA、AU 等），且X-Forwarded-For的 IP 必须是真实存在的、位于该国的 IP（我们用 AWS us-east-1 的弹性 IP）。这个方案完全合规，因为流量最终还是走 Anthropic 官方 API，只是代理层做了地理头欺骗。

不推荐方案：修改系统语言或 hosts 文件
网上流传的“把系统语言改成 English (United States)”或“hosts 绑定 api.anthropic.com 到美国服务器”已被 Anthropic 识别并封禁。2024 年 6 月后，Claude Code 桌面版增加了 TLS 指纹校验，这些方法全部失效。

4.4 Superpowers Java 开发专项调优：让 AI 真正懂 Spring Boot

Java 开发者最常抱怨“Superpowers 生成的代码不符合 Spring 规范”，根本原因是 Codex CLI 默认的 Java 解析器不理解 Spring 的约定。解决方案是深度定制codex.yaml：

第一步：启用 Spring Boot 专用解析器
在codex.yaml的project下添加：

frameworks: - spring-boot: "3.2.0" # 必须和你 pom.xml 里的版本一致

这会让 Codex CLI 加载spring-boot-parser插件，自动识别@SpringBootApplication、@ConfigurationProperties等注解。

第二步：定义 Spring 特有符号
在symbols下补充：

"@Autowired": "Spring dependency injection annotation" "@Value": "Spring property injection annotation" "RestTemplate": "Spring HTTP client (legacy)" "WebClient": "Spring reactive HTTP client (modern)"

第三步：配置 Controller 生成模板
在templates下重写controllerMethod：

controllerMethod: - "public ResponseEntity<{{returnType}}> {{methodName}}({{params}}) {" - " {{businessLogic}}" - " return ResponseEntity.ok(result);" - "}"

关键是{{businessLogic}}占位符，Codex CLI