superpowers-zh 1.5.0 → 1.6.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-zh",
       "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 18 款工具",
-      "version": "1.5.0",
+      "version": "1.6.0",
       "source": "./",
       "author": {
         "name": "jnMetaCode",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-zh",
   "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 18 款工具",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "AI 编程超能力中文增强版：头脑风暴、subagent 驱动开发、规划、TDD、调试、代码审查、收尾工作流，附 4 个中文 skills 沉淀。",
   "author": {
     "name": "jnMetaCode",

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers-zh",
   "displayName": "Superpowers 中文版",
   "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Cursor / Claude Code / Hermes Agent / Claw Code / Qoder 等 18 款工具",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/.pi/extensions/superpowers.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const EXTREMELY_IMPORTANT_MARKER = "<EXTREMELY_IMPORTANT>";
+const BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for pi";
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(extensionDir, "../..");
+const skillsDir = resolve(packageRoot, "skills");
+const bootstrapSkillPath = resolve(skillsDir, "using-superpowers", "SKILL.md");
+
+let cachedBootstrap: string | null | undefined;
+
+export default function superpowersPiExtension(pi: ExtensionAPI) {
+	let injectBootstrap = true;
+
+	pi.on("resources_discover", async () => ({
+		skillPaths: [skillsDir],
+	}));
+
+	pi.on("session_start", async () => {
+		injectBootstrap = true;
+	});
+
+	pi.on("session_compact", async () => {
+		injectBootstrap = true;
+	});
+
+	pi.on("agent_end", async () => {
+		injectBootstrap = false;
+	});
+
+	pi.on("context", async (event) => {
+		if (!injectBootstrap) return;
+		if (event.messages.some(messageContainsBootstrap)) return;
+
+		const bootstrap = getBootstrapContent();
+		if (!bootstrap) return;
+
+		const bootstrapMessage = {
+			role: "user" as const,
+			content: [{ type: "text" as const, text: bootstrap }],
+			timestamp: Date.now(),
+		};
+
+		const insertAt = firstNonCompactionSummaryIndex(event.messages);
+		return {
+			messages: [
+				...event.messages.slice(0, insertAt),
+				bootstrapMessage,
+				...event.messages.slice(insertAt),
+			],
+		};
+	});
+}
+
+function getBootstrapContent(): string | null {
+	if (cachedBootstrap !== undefined) return cachedBootstrap;
+
+	try {
+		const skillContent = readFileSync(bootstrapSkillPath, "utf8");
+		const body = stripFrontmatter(skillContent);
+		cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}
+${BOOTSTRAP_MARKER}
+
+You have superpowers.
+
+The using-superpowers skill content is included below and is already loaded for this Pi session. Follow it now. Do not try to load using-superpowers again.
+
+${body}
+
+${piToolMapping()}
+</EXTREMELY_IMPORTANT>`;
+		return cachedBootstrap;
+	} catch {
+		cachedBootstrap = null;
+		return null;
+	}
+}
+
+function stripFrontmatter(content: string): string {
+	const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+	return (match ? match[1] : content).trim();
+}
+
+function piToolMapping(): string {
+	return `## Pi tool mapping
+
+Pi has native skills but does not expose Claude Code's \`Skill\` tool. When a Superpowers instruction says to invoke a skill, use Pi's native skill system instead: load the relevant \`SKILL.md\` with \`read\` when the skill applies, or let a human invoke \`/skill:name\` explicitly.
+
+Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for the corresponding actions: read a file, create or edit files, run shell commands, search file contents, find files by name, and list directories.
+
+Pi does not ship a standard subagent tool. If a subagent tool such as \`subagent\` from \`pi-subagents\` is available, use it for Superpowers subagent workflows. If no subagent tool is available, do the work in this session or explain the missing capability instead of inventing \`Task\` calls.
+
+Pi does not ship a standard task-list tool. If an installed todo/task tool is available, use it. Otherwise track work in plan files or a repo-local \`TODO.md\` when task tracking is needed. Treat older \`TodoWrite\` references as this task-tracking action.`;
+}
+
+function messageContainsBootstrap(message: unknown): boolean {
+	const content = (message as { content?: unknown }).content;
+	if (typeof content === "string") return content.includes(BOOTSTRAP_MARKER);
+	if (!Array.isArray(content)) return false;
+	return content.some((part) => {
+		return (
+			part &&
+			typeof part === "object" &&
+			(part as { type?: unknown }).type === "text" &&
+			typeof (part as { text?: unknown }).text === "string" &&
+			(part as { text: string }).text.includes(BOOTSTRAP_MARKER)
+		);
+	});
+}
+
+function firstNonCompactionSummaryIndex(messages: unknown[]): number {
+	let index = 0;
+	while ((messages[index] as { role?: unknown } | undefined)?.role === "compactionSummary") {
+		index += 1;
+	}
+	return index;
+}

package/README.md

@@ -2,10 +2,47 @@
 
 🌐 **简体中文** | [English (upstream)](https://github.com/obra/superpowers)
 
-> 🦸 **superpowers（159k+ ⭐）完整汉化 + 4 个中国原创 skills** — 让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 **18 款 AI 编程工具**真正会干活。从头脑风暴到代码审查，从 TDD 到调试，每个 skill 都是经过实战验证的工作方法论。
+> 🦸 **superpowers（233k+ ⭐）完整汉化 + 4 个中国原创 skills** — 让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 **18 款 AI 编程工具**真正会干活。从头脑风暴到代码审查，从 TDD 到调试，每个 skill 都是经过实战验证的工作方法论。
 
 Chinese community edition of [superpowers](https://github.com/obra/superpowers) — 20 skills across 18 AI coding tools, including full translations and China-specific development skills.
 
+[![官网 sp.aiolaola.com](https://img.shields.io/badge/🌐_官网-sp.aiolaola.com-F59E0B)](https://sp.aiolaola.com)
+[![GitHub stars](https://img.shields.io/github/stars/jnMetaCode/superpowers-zh?style=social)](https://github.com/jnMetaCode/superpowers-zh)
+[![npm version](https://img.shields.io/npm/v/superpowers-zh)](https://www.npmjs.com/package/superpowers-zh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com)
+
+> 📖 **免费配套学习** → [从零学会 AI 编程](https://aiolaola.com/?utm_source=github&utm_campaign=superpowers)：180 节免费实操课 + 《AI 编程实战三卷书》在线阅读 + 实战社区 · superpowers 装好后配上方法论效率翻倍 · 永久免费
+
+### 📊 项目规模
+
+| 📦 翻译 Skills | 🇨🇳 中国特色 Skills | 🤖 支持工具 |
+|:---:|:---:|:---:|
+| **14** | **6** | **Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Codex / Aider / Trae / VS Code (Copilot) / DeerFlow / OpenCode / OpenClaw / Qwen Code / Antigravity / Claw Code / Qoder** |
+
+---
+
+## ❤️ 赞助商 &nbsp;<sub>🙏 想出现在这里？联系 **jnMetaCode@qq.com** 赞助</sub>
+
+<table>
+<tr>
+<td width="200" align="center">
+<a href="https://www.5cookie.cc/sign-up?aff=Pj7u"><img src="assets/sponsors/5cookie-code.png" width="180" alt="5Cookie Code"></a>
+</td>
+<td>
+<a href="https://www.5cookie.cc/sign-up?aff=Pj7u"><b>5Cookie Code</b></a> 是一家稳定高速的 API 中继服务提供商，为 Claude Code、Codex 等平台或模型提供 API 中继服务。面向个人、团队和企业用户提供 AI 编码服务和 AI 生图服务。
+</td>
+</tr>
+</table>
+
+---
+
+## 这是什么？
+
+[superpowers](https://github.com/obra/superpowers) 是目前最火的 AI 编程 skills 框架（233k+ stars），为 AI 编程工具提供**系统化的工作方法论**。
+
+**superpowers-zh** 在完整翻译的基础上，新增了面向中国开发者的特色 skills。
+
 <!-- 效果对比 -->
 <table>
 <tr><td>
@@ -33,32 +70,11 @@ AI：在开始实现之前，我需要了解几个关键问题：
 </td></tr>
 </table>
 
-[![GitHub stars](https://img.shields.io/github/stars/jnMetaCode/superpowers-zh?style=social)](https://github.com/jnMetaCode/superpowers-zh)
-[![npm version](https://img.shields.io/npm/v/superpowers-zh)](https://www.npmjs.com/package/superpowers-zh)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com)
-
-> 📖 **配套阅读**：[《AI 编程实战 · 方法论三卷书》](https://book.aibuzhiyu.com/) — 10 个 AI 编程工具完整教程 + 真实踩坑 · superpowers 装好之后，配上方法论效率翻倍 · 在线书 + PDF · 永久免费
-
-### 📊 项目规模
-
-| 📦 翻译 Skills | 🇨🇳 中国特色 Skills | 🤖 支持工具 |
-|:---:|:---:|:---:|
-| **14** | **6** | **Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Codex / Aider / Trae / VS Code (Copilot) / DeerFlow / OpenCode / OpenClaw / Qwen Code / Antigravity / Claw Code / Qoder** |
-
----
-
-## 这是什么？
-
-[superpowers](https://github.com/obra/superpowers) 是目前最火的 AI 编程 skills 框架（159k+ stars），为 AI 编程工具提供**系统化的工作方法论**。
-
-**superpowers-zh** 在完整翻译的基础上，新增了面向中国开发者的特色 skills。
-
 ### 🆚 与英文上游的区别（老被问，一次说清）
 
 | 维度 | superpowers（英文上游） | superpowers-zh（中文增强版） |
 |------|----------------------|---------------------------|
-| ⭐ Star 数 | 159k+ | — |
+| ⭐ Star 数 | 233k+ | — |
 | 📦 Skills 总数 | 14 | **20**（14 翻译 + 4 国产原创 + 2 上游历史保留） |
 | 🌐 语言 | 英文 | 中文（技术术语保留英文） |
 | 🤖 **支持工具** | **6 款**：Claude Code / Cursor / Codex / OpenCode / Copilot CLI / Gemini CLI | **18 款**：上述 6 款 + Hermes Agent / Trae / Kiro / Qwen Code（通义灵码）/ OpenClaw / Claw Code / Antigravity / DeerFlow / VS Code / Windsurf / Aider / Qoder |
@@ -96,7 +112,7 @@ AI：在开始实现之前，我需要了解几个关键问题：
 | [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
 | [OpenClaw](https://github.com/anthropics/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
 | [Qwen Code](https://tongyi.aliyun.com/lingma) (通义灵码) | IDE 插件 | `npx superpowers-zh` | `.qwen/skills/` |
-| [Antigravity](https://github.com/anthropics/antigravity) | CLI | `npx superpowers-zh` | `.antigravity/skills/` |
+| [Antigravity](https://github.com/anthropics/antigravity) | CLI | `npx superpowers-zh` | `.agents/skills/` |
 | [Claw Code](https://github.com/ultraworkers/claw-code) | CLI (Rust) | `npx superpowers-zh` | `.claw/skills/` |
 | [Qoder](https://qoder.com) (阿里 AI IDE) | IDE | `npx superpowers-zh` | `.qoder/skills/` + `.qoder/rules/` |
 
@@ -170,7 +186,7 @@ cp -r superpowers-zh/skills /your/project/.codex/skills       # Codex CLI
 cp -r superpowers-zh/skills /your/project/.kiro/steering      # Kiro
 cp -r superpowers-zh/skills /your/project/skills/custom       # DeerFlow 2.0
 cp -r superpowers-zh/skills /your/project/.trae/rules         # Trae
-cp -r superpowers-zh/skills /your/project/.antigravity        # Antigravity
+cp -r superpowers-zh/skills /your/project/.agents        # Antigravity
 cp -r superpowers-zh/skills /your/project/.github/superpowers # VS Code (Copilot)
 cp -r superpowers-zh/skills /your/project/skills              # OpenClaw
 cp -r superpowers-zh/skills /your/project/.windsurf/skills   # Windsurf
@@ -207,7 +223,7 @@ cp -r superpowers-zh/skills /your/project/.qoder/skills      # Qoder（阿里 AI
 | Claw Code | `.claw/skills/*/SKILL.md` | Rust 版 CLI agent，兼容 Claude Code 的 SKILL.md 格式 |
 | Qoder | `.qoder/skills/*/SKILL.md` + `.qoder/rules/superpowers-zh.md` | 阿里 AI IDE，自动生成 `trigger: always_on` 的 bootstrap rule |
 
-> **详细安装指南**：[Kiro](docs/README.kiro.md) · [DeerFlow](docs/README.deerflow.md) · [Trae](docs/README.trae.md) · [Antigravity](docs/README.antigravity.md) · [VS Code](docs/README.vscode.md) · [Codex](docs/README.codex.md) · [OpenCode](docs/README.opencode.md) · [OpenClaw](docs/README.openclaw.md) · [Windsurf](docs/README.windsurf.md) · [Gemini CLI](docs/README.gemini-cli.md) · [Aider](docs/README.aider.md) · [Qwen Code](docs/README.qwen.md) · [Hermes Agent](docs/README.hermes.md) · [Qoder](docs/README.qoder.md)
+> **详细安装指南**：[Kiro](docs/README.kiro.md) · [DeerFlow](docs/README.deerflow.md) · [Trae](docs/README.trae.md) · [Antigravity](docs/README.antigravity.md) · [VS Code](docs/README.vscode.md) · [Codex](docs/README.codex.md) · [OpenCode](docs/README.opencode.md) · [OpenClaw](docs/README.openclaw.md) · [Windsurf](docs/README.windsurf.md) · [Gemini CLI](docs/README.gemini-cli.md) · [Aider](docs/README.aider.md) · [Qwen Code](docs/README.qwen.md) · [Hermes Agent](docs/README.hermes.md) · [Qoder](docs/README.qoder.md) · [Kimi Code](docs/README.kimi.md) · [Pi](docs/README.pi.md)
 
 ### 卸载 / 误装清理（v1.2.1+）
 
@@ -219,7 +235,7 @@ npx superpowers-zh@latest --uninstall
 会做这些：
 
 - 删除所有装过的 skill 目录（`.claude/skills/`、`.trae/skills/` 等）
-- 删除独立 bootstrap 文件（`.trae/rules/superpowers-zh.md`、`.qoder/rules/superpowers-zh.md`、`.antigravity/rules.md`）
+- 删除独立 bootstrap 文件（`.trae/rules/superpowers-zh.md`、`.qoder/rules/superpowers-zh.md`、`.agents/rules.md`）
 - 清理追加到 `CLAUDE.md` / `HERMES.md` / `GEMINI.md` / `CONVENTIONS.md` 里的 superpowers-zh 段，**保留你自己写的内容**
 
 数据安全说明：v1.2.1 起，安装会把追加内容包在 `<!-- superpowers-zh:begin/end -->` 哨兵注释之间，卸载按哨兵精确切除。识别不可靠时跳过 + 警告，**绝不会误删用户内容**。
@@ -253,6 +269,14 @@ npx superpowers-zh@latest --uninstall
 
 ## 交流 · Community
 
+<table>
+<tr>
+<td width="170" align="center">
+<img src="assets/qr-wechat.jpg" width="150" alt="微信公众号 AI不止语 二维码"><br>
+<sub>微信扫码关注</sub>
+</td>
+<td>
+
 微信公众号 **「AI不止语」**（微信搜索 `AI_BuZhiYu`）— 技术问答 · 项目更新 · 实战文章
 
 | 渠道 | 加入方式 |
@@ -260,11 +284,15 @@ npx superpowers-zh@latest --uninstall
 | QQ 2群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
 | 微信群 | 关注公众号后回复「群」获取入群方式 |
 
+</td>
+</tr>
+</table>
+
 ---
 
 ## 🌟 相关项目生态
 
-**六个项目组合使用，覆盖 AI 编程 + AI 视频创作的完整链路。**
+**八个项目组合使用，覆盖 AI 编程 + AI 视频创作 + 桌面陪伴的完整链路。**
 
 | 项目 | 定位 | 一句话 |
 |------|------|-------|
@@ -274,6 +302,8 @@ npx superpowers-zh@latest --uninstall
 | **[ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide)** | 📖 实战教程 | 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 配置模板 |
 | **[shellward](https://github.com/jnMetaCode/shellward)** | 🛡️ 安全中间件 | 8 层防御 + DLP 数据流 + 注入检测，**零依赖**（含 MCP Server） |
 | 🆕 **[ai-shortfilm-prompts](https://github.com/jnMetaCode/ai-shortfilm-prompts)** | 🎬 视频提示词 | Mx-Shell《丧尸清道夫》5 段式方法论 + Skill，Seedance / 小云雀 / Sora / 可灵 / 即梦通用 |
+| 🆕 **[local-agent-toolkit](https://github.com/jnMetaCode/local-agent-toolkit)** | 🛠️ Agent 本地三件套 | 给 agent 配上**记忆 / 技能管理 / 运行追踪**，零依赖、数据不出本机；本仓库 skills 可用 `npx @jnmetacode/skillet add jnMetaCode/superpowers-zh/skills/<名称>` 一键安装 |
+| 🆕 **[codepet](https://github.com/jnMetaCode/codepet)** | 🐾 桌面养成桌宠 | 码宠 CodePet —— 你写代码 / 用 Claude Code，它就涨经验、升级、换状态、跳舞。**全本地、隐私优先、开源** |
 
 ---
 

package/RELEASE-NOTES.zh.md

@@ -6,6 +6,27 @@
 
 ---
 
+## v1.6.0 (2026-06-20)
+
+本版本对齐上游 **v6.0.0** 的实质性 skill / 基础设施变更，并新增两款 harness 支持。
+
+### 🆕 新增 harness 支持
+
+- **Kimi Code**（#59，关 #37）—— 插件清单模型 `.kimi-plugin/plugin.json`：指向现有 `skills/`、`sessionStart` 会话开始自动加载 `using-superpowers`、`skillInstructions` 提供 Kimi 工具映射。安装：Kimi 插件管理器 `/plugins install https://github.com/jnMetaCode/superpowers-zh`。文档见 `docs/README.kimi.md`。
+- **Pi (oh-my-pi)**（#60，关 #44）—— 扩展模型：`package.json` 的 `pi` 字段 + `.pi/extensions/superpowers.ts`（注册生命周期钩子，注入 `using-superpowers` bootstrap + Pi 工具映射）。文档见 `docs/README.pi.md`。
+
+### 🔒 brainstorm 可视化伴侣安全模型（#58，同步上游 v6.0.0）
+
+伴侣服务器重写为**每会话密钥**鉴权（`?key=` 或会话 cookie 门禁所有端点）+ 安全响应头（`X-Frame-Options: DENY`、CSP `frame-ancestors 'none'`、`Cross-Origin-Resource-Policy: same-origin` 等），修复旧版无鉴权时本地浏览器可读取屏幕/注入事件的缺口。Token 用 `crypto.randomBytes(32)`、`timingSafeEqual` 比较、token 文件 `0o600`。
+
+### 🔧 其它 v6 同步
+
+- **using-git-worktrees / finishing-a-development-branch**（#57）—— 移除已废弃的全局 worktree 目录 `~/.config/superpowers/worktrees/`，对齐 v6.0.0。
+- **hooks/session-start**（#58）—— 移除 legacy `~/.config/superpowers/skills` 迁移警告，输出补 `| cat`。
+- **opencode 测试**（#72）—— 修复 `setup.sh` 拷贝不存在的 `lib/` 导致的测试飘红。
+
+> SDD（subagent-driven-development）的 v6 重写为性能/成本优化，需专门 eval 验证，故本版本暂未纳入（详见 #19）。
+
 ## v1.5.0 (2026-05-21)
 
 ### 🆕 Qoder 适配（第 18 款工具，#26、#34）

package/bin/superpowers-zh.js

@@ -53,7 +53,7 @@ const TARGETS = [
   { name: 'Kiro',          dir: '.kiro/steering',            detect: '.kiro' },
   { name: 'DeerFlow',      dir: 'skills/custom',             detect: 'deer_flow' },
   { name: 'Trae',          dir: '.trae/skills',              detect: '.trae' },
-  { name: 'Antigravity',   dir: '.antigravity/skills',       detect: '.antigravity' },
+  { name: 'Antigravity',   dir: '.agents/skills',            detect: '.agents' },
   { name: 'VS Code',       dir: '.github/superpowers',       detect: '.github/copilot-instructions.md' },
   { name: 'OpenClaw',      dir: 'skills',                     detect: '.openclaw' },
   { name: 'Windsurf',      dir: '.windsurf/skills',          detect: '.windsurf' },
@@ -204,17 +204,17 @@ function generateAntigravityBootstrap(projectDir) {
 
 ## 可用 Skills
 
-Skills 位于 \`.antigravity/skills/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
+Skills 位于 \`.agents/skills/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
 
 ${skillList}
 
 ## 如何使用
 
-当任务匹配某个 skill 时，读取对应的 \`.antigravity/skills/<skill-name>/SKILL.md\` 并严格遵循其流程。
+当任务匹配某个 skill 时，读取对应的 \`.agents/skills/<skill-name>/SKILL.md\` 并严格遵循其流程。
 `;
 
-  // 写入 .antigravity/rules.md（不覆盖用户已有的 GEMINI.md / AGENTS.md）
-  const rulePath = resolve(projectDir, '.antigravity', 'rules.md');
+  // 写入 .agents/rules.md（不覆盖用户已有的 GEMINI.md / AGENTS.md）
+  const rulePath = resolve(projectDir, '.agents', 'rules.md');
   writeFileSync(rulePath, content, 'utf8');
   console.log(`  ✅ Antigravity: bootstrap rule -> ${rulePath}`);
 }
@@ -521,7 +521,7 @@ function isHomeDir(p) {
 const BOOTSTRAP_DELETE = [
   '.trae/rules/superpowers-zh.md',
   '.qoder/rules/superpowers-zh.md',
-  '.antigravity/rules.md',
+  '.agents/rules.md',
 ];
 const BOOTSTRAP_CLEAN_SECTION = [
   'CLAUDE.md',
@@ -748,18 +748,17 @@ function install(forceToolName, force) {
   }
 
   if (installed === 0) {
-    console.log('  ⚠️  未检测到任何已知的 AI 编程工具。\n');
-    console.log('  如果你使用的是 Cursor、Trae 等工具，请用 --tool 指定：');
-    console.log('    npx superpowers-zh --tool cursor');
-    console.log('    npx superpowers-zh --tool trae\n');
-    console.log('  现在将默认安装到 .claude/skills/（兼容 Claude Code / OpenClaw）\n');
-
-    const dest = resolve(PROJECT_DIR, '.claude', 'skills');
-    mkdirSync(dest, { recursive: true });
-    copyDirSync(SKILLS_SRC, dest);
-    console.log(`  ✅ 默认安装: ${countDirs(dest)} 个 skills -> ${dest}`);
-
-    generateClaudeCodeBootstrap(PROJECT_DIR);
+    // 检测落空时不再静默装 Claude Code —— 否则 Antigravity / Trae 等
+    // 不会在项目里留下检测目录的工具，会被误装成 Claude（见 issue #33）。
+    // 改为明确报错并教用户用 --tool 显式指定。
+    console.log('  ⚠️  未在当前目录检测到任何已知 AI 编程工具的项目标记。\n');
+    console.log('  为避免装错工具，未做任何安装。请用 --tool 显式指定你的工具，例如：\n');
+    console.log('    npx superpowers-zh --tool claude        # Claude Code / Copilot CLI');
+    console.log('    npx superpowers-zh --tool antigravity   # Google Antigravity');
+    console.log('    npx superpowers-zh --tool trae          # Trae');
+    console.log('    npx superpowers-zh --tool cursor        # Cursor\n');
+    console.log(`  全部可用别名：${Object.keys(TOOL_ALIASES).join(', ')}\n`);
+    process.exit(1);
   }
 
   console.log('\n  安装完成！重启你的 AI 编程工具即可生效。\n');

package/docs/README.antigravity.md

@@ -9,14 +9,14 @@ cd /your/project
 npx superpowers-zh
 ```
 
-安装脚本会自动检测 `.antigravity/` 目录并将 skills 复制到该目录。
+安装脚本会自动检测 `.agents/` 目录并将 skills 复制到该目录。
 
 ## 手动安装
 
 ```bash
 git clone https://github.com/jnMetaCode/superpowers-zh.git
-mkdir -p /your/project/.antigravity/skills
-cp -r superpowers-zh/skills/* /your/project/.antigravity/skills/
+mkdir -p /your/project/.agents/skills
+cp -r superpowers-zh/skills/* /your/project/.agents/skills/
 ```
 
 ## 工作原理
@@ -27,7 +27,7 @@ Antigravity 支持多种规则文件格式：
 |------|--------|------|
 | `GEMINI.md` | 最高 | Antigravity 专属规则 |
 | `AGENTS.md` | 中 | 通用规则（Antigravity、Cursor、Claude Code 共享） |
-| `.antigravity/rules.md` | 中 | 项目级规则目录 |
+| `.agents/rules.md` | 中 | 项目级规则目录 |
 | `CLAUDE.md` | 低 | 也会被自动读取 |
 
 ### 推荐配置方式
@@ -37,10 +37,10 @@ Antigravity 支持多种规则文件格式：
 ```markdown
 # GEMINI.md
 
-使用 .antigravity/ 目录下的 superpowers skills 来指导工作流程。
+使用 .agents/ 目录下的 superpowers skills 来指导工作流程。
 优先使用 brainstorming（头脑风暴）开始新任务。
 
-Skills 列表参见 .antigravity/ 目录。
+Skills 列表参见 .agents/ 目录。
 ```
 
 **方式二**：在 `AGENTS.md` 中引用（多工具共享）：
@@ -49,7 +49,7 @@ Skills 列表参见 .antigravity/ 目录。
 # AGENTS.md
 
 本项目使用 superpowers-zh skills 框架。
-Skills 位于 .antigravity/（Antigravity）或 .claude/skills/（Claude Code）目录下。
+Skills 位于 .agents/（Antigravity）或 .claude/skills/（Claude Code）目录下。
 ```
 
 ### 工具映射

package/docs/README.kimi.md

@@ -0,0 +1,86 @@
+# Superpowers 中文版 · Kimi Code 指南
+
+在 [Kimi Code](https://github.com/MoonshotAI/kimi-code) 上使用 superpowers-zh 的完整说明。
+
+## 安装
+
+superpowers-zh 通过 Kimi Code 的插件清单 `.kimi-plugin/plugin.json` 集成，**直接指向仓库现有的 `skills/` 目录**——不复制 skill、不建 symlink、不装 hook、无任何运行时依赖。
+
+打开插件管理器：
+
+```text
+/plugins
+```
+
+如果 Kimi 插件市场已收录，进入 `Marketplace` > `Superpowers 中文版` 安装即可。
+
+也可以直接从本仓库安装：
+
+```text
+/plugins install https://github.com/jnMetaCode/superpowers-zh
+```
+
+如需验证尚未发布的改动，显式指定分支：
+
+```text
+/plugins install https://github.com/jnMetaCode/superpowers-zh/tree/main
+```
+
+Kimi Code 在**新会话**才会应用插件变更。安装、更新、启用、禁用或重载插件后，用 `/new` 开一个新会话。
+
+## 工作原理
+
+Kimi 插件清单位于 `.kimi-plugin/plugin.json`，做三件事：
+
+1. 把 Kimi Code 指向仓库现有的 `skills/` 目录；
+2. 通过 `sessionStart.skill` 在会话开始时加载 `using-superpowers`（这是让 skill 在恰当时机自动触发的关键）；
+3. 通过 `skillInstructions` 提供 Kimi 专属的工具映射。
+
+## 工具映射
+
+skill 内容描述的是「动作」而非写死某个运行时的工具名。在 Kimi Code 上它们对应到：
+
+- 「向用户提问」/「问澄清问题」/「给出多选项」→ `AskUserQuestion`
+- 「创建待办」/「在待办清单中标记完成」→ `TodoList`
+- 「分派子智能体」/「Task tool (general-purpose)」→ `Agent`（用 Kimi 的 subagent 类型，如 `coder`/`explore`/`plan`，**不要**传 `general-purpose`）
+- 「调用某个 skill」→ Kimi Code 原生 `Skill` 工具
+- 「读文件」/「写文件」/「改文件」→ `Read` / `Write` / `Edit`
+- 「跑 shell 命令」→ `Bash`
+- 「搜索文件内容」→ `Grep`
+- 「按路径/模式找文件」→ `Glob`
+- 「抓取 URL」→ `FetchURL`
+- 「联网搜索」→ `WebSearch`
+
+完整映射写在清单的 `skillInstructions` 字段里，由 Kimi 在运行时读取。
+
+## 更新
+
+用 Kimi Code 的插件管理器：
+
+```text
+/plugins
+```
+
+选中 Superpowers 中文版更新，更新后用 `/new` 开新会话。
+
+## 排错
+
+### 插件没加载
+
+1. 跑 `/plugins info superpowers-zh` 看诊断信息；
+2. 确认插件已启用；
+3. 安装或更新后用 `/new` 开新会话。
+
+### 直接 GitHub 安装装到了旧版本
+
+对于裸仓库 URL，Kimi Code 会装最新的 GitHub release（若存在）。要在下一个 release 前测试未发布的改动，显式指定分支：
+
+```text
+/plugins install https://github.com/jnMetaCode/superpowers-zh/tree/main
+```
+
+### skill 不触发
+
+1. 用 `/plugins info superpowers-zh` 确认插件已启用；
+2. 用 `/new` 开新会话；
+3. 试验收提示词：`我们来做个 react todo list`。集成正常的话，会在写任何代码之前先加载 `brainstorming`。

package/docs/README.pi.md

@@ -0,0 +1,54 @@
+# Superpowers 中文版 · Pi 指南
+
+在 [Pi](https://github.com/earendil-works/pi)（oh-my-pi）上使用 superpowers-zh 的完整说明。
+
+## 安装
+
+superpowers-zh 通过 Pi 的扩展机制集成，**直接指向仓库现有的 `skills/` 目录**——不复制 skill、不建 symlink、无额外运行时依赖。
+
+集成由 `package.json` 里的 `pi` 字段声明：
+
+```json
+"pi": {
+  "skills": ["./skills"],
+  "extensions": ["./.pi/extensions/superpowers.ts"]
+}
+```
+
+并带 `pi-package` keyword，便于 Pi 发现这是一个 Pi 包。
+
+按 Pi 的包安装方式安装 `superpowers-zh`（参考 Pi 文档的包管理命令），Pi 会读取上述 `pi` 配置，挂载 `skills/` 并加载 `.pi/extensions/superpowers.ts` 扩展。
+
+## 工作原理
+
+`.pi/extensions/superpowers.ts` 注册了 Pi 的生命周期钩子：
+
+1. **`resources_discover`** — 把仓库的 `skills/` 目录贡献给 Pi 的技能系统；
+2. **`session_start` / `session_compact`** — 标记需要重新注入 bootstrap；
+3. **`context`** — 在会话上下文中注入 `using-superpowers` 的内容（去除 frontmatter）+ Pi 工具映射，作为「You have superpowers」bootstrap，让 skill 在恰当时机被遵循；
+4. **`agent_end`** — 一轮结束后停止重复注入。
+
+注入带有唯一标记，已存在时不会重复注入；并且会插入到 compaction summary 之后，避免被压缩流程吞掉。
+
+## 工具映射
+
+Pi 有原生技能系统，但**不暴露** `Skill` 工具。skill 内容描述「动作」，在 Pi 上对应到小写工具：
+
+- 「调用某个 skill」→ Pi 原生技能：用 `read` 加载对应 `SKILL.md`，或由人类显式 `/skill:name`
+- 「读/写/改文件」→ `read` / `write` / `edit`
+- 「跑 shell 命令」→ `bash`
+- 「搜索文件内容」→ `grep`，「按名找文件」→ `find`，「列目录」→ `ls`
+- 「分派子智能体」→ 若装了 `pi-subagents` 的 `subagent` 工具则用之；没有则在本会话内完成或说明能力缺失，**不要**臆造 `Task` 调用
+- 「待办清单」→ 若装了 todo/task 工具则用之；否则用 plan 文件或仓库内 `TODO.md` 跟踪；旧的 `TodoWrite` 引用按此处理
+
+完整映射见 [`skills/using-superpowers/references/pi-tools.md`](../skills/using-superpowers/references/pi-tools.md)，扩展也会把同样的映射注入会话。
+
+## 验证
+
+```bash
+bash tests/pi/run-tests.sh
+```
+
+该测试动态加载扩展并校验：声明了 `pi` 包配置、注册了正确的生命周期钩子（且无 pre-compaction 注入）、`resources_discover` 贡献了 `skills/` 目录、`session_start` 注入了「You have superpowers」+「Pi tool mapping」、pi-tools 参考文档存在。
+
+> 注：扩展是 TypeScript（仅 `import type`，运行时无类型依赖）。Node 22.6–23.5 需 `--experimental-strip-types`（run-tests.sh 已带），23.6+ 默认支持。

package/docs/README.trae.md

@@ -9,16 +9,18 @@ cd /your/project
 npx superpowers-zh
 ```
 
-安装脚本会自动检测 `.trae/` 目录并将 skills 复制到 `.trae/rules/`。
+安装脚本会自动检测 `.trae/` 目录，将各 skill 完整复制到 `.trae/skills/`（含 `SKILL.md` 及其 `scripts/` 等附属文件），并在 `.trae/rules/superpowers-zh.md` 生成一份 bootstrap 规则用于自动触发。
 
 ## 手动安装
 
 ```bash
 git clone https://github.com/jnMetaCode/superpowers-zh.git
-mkdir -p /your/project/.trae/rules
-cp -r superpowers-zh/skills/* /your/project/.trae/rules/
+mkdir -p /your/project/.trae/skills
+cp -r superpowers-zh/skills/* /your/project/.trae/skills/
 ```
 
+> 手动复制只会放好 skill 文件，不会生成 `.trae/rules/` 下的 bootstrap 自动触发规则。建议优先用上面的 `npx superpowers-zh`，否则需要在对话里手动点名 skill 才会激活。
+
 ## 工作原理
 
 Trae 使用 `.rules` 机制管理 AI 行为：
@@ -32,7 +34,7 @@ Trae 使用 `.rules` 机制管理 AI 行为：
 
 ### Skills 适配
 
-superpowers-zh 的 SKILL.md 文件可以直接作为 Trae 的 rules 使用。Trae 会在初始化时加载 `.trae/rules/` 下的所有规则文件。
+安装器把各 skill 放在 `.trae/skills/<skill-name>/`，并在 `.trae/rules/superpowers-zh.md` 写入一份 bootstrap 规则。Trae 初始化时加载 `.trae/rules/` 下的规则，bootstrap 规则会引导 AI 在任务匹配时读取对应的 `.trae/skills/<skill-name>/SKILL.md` 并遵循其流程。
 
 ### 推荐配置