mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
4909388f35
issue #44：Pi 像 opencode 一样开放，skill:// 能直接用，已验证可手动使用， 希望原生支持。上游 obra/superpowers 在 v6.0.0 已用扩展模型原生集成 Pi， 本提交把同样的集成方式落到本 fork。 Pi 走扩展模型，通过 package.json 的 pi 字段声明，直接指向仓库现有 skills/，不复制 skill、无运行时依赖。扩展内容中立——读取 fork 现有的 中文 using-superpowers/SKILL.md 自动注入，故扩展代码逐字节照搬上游。 - .pi/extensions/superpowers.ts：注册 resources_discover / session_start / session_compact / agent_end / context 生命周期钩子，在会话注入 using-superpowers bootstrap + Pi 工具映射（带去重标记、插在 compaction summary 之后） - package.json：加 pi.skills=["./skills"] + pi.extensions + pi-package keyword；.pi/extensions/ 加入 files（npm 发布需含扩展） - skills/using-superpowers/references/pi-tools.md：Pi 工具映射参考 - docs/README.pi.md：中文安装/原理/工具映射/验证指南；README.md 工具列表加链接 - tests/pi/：上游扩展行为测试（适配 fork：name=superpowers-zh）+ 运行包装 验证：bash tests/pi/run-tests.sh 6/6 通过 exit 0（校验 pi 包配置、生命周期 钩子无 pre-compaction 注入、resources_discover 贡献 skills 目录、session_start 注入 You-have-superpowers + Pi-tool-mapping、pi-tools 参考存在）；package.json 合法；scripts/audit.sh 静态 0 FAIL；README→docs/README.pi.md 链接可解析。 注：扩展是 TS（仅 import type，运行时无类型依赖），Node 22.6–23.5 需 --experimental-strip-types（run-tests.sh 已带），23.6+ 默认支持。 Pi 内实际 skill 触发需在 Pi 内验证（与本 fork 其它 harness 同样限制）。
55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
# 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+ 默认支持。
|