oh-pi

One-click setup for pi-coding-agent. Like oh-my-zsh for pi.

Package details

← Back

extensionskillthemeprompt

Install oh-pi from npm and Pi will load the resources declared by the package manifest.

npm report

$ pi install npm:oh-pi

Package: oh-pi
Version: 0.1.85
Published: Mar 2, 2026
Downloads: 1,127/mo · 166/wk
Author: telagod
License: MIT
Types: extension, skill, theme, prompt
Size: 345.7 KB
Dependencies: 2 dependencies · 0 peers

Pi manifest JSON

{
  "skills": [
    "./pi-package/skills"
  ],
  "themes": [
    "./pi-package/themes"
  ],
  "prompts": [
    "./pi-package/prompts"
  ],
  "extensions": [
    "./pi-package/extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

🐜 oh-pi

一条命令，增强 pi-coding-agent。

就像 oh-my-zsh 之于 pi —— 但带有自主蚁群系统。

English | 中文 | Français

npx oh-pi

30 秒上手

npx oh-pi    # 配置一切
pi           # 开始编码

就这样。oh-pi 会自动检测环境、引导配置，并写入 ~/.pi/agent/。

已有配置？会先备份，再覆盖。

2 分钟看懂价值

oh-pi 把原本分散且手工的配置流程（提供商、主题、扩展、技能、提示词模板）整合成一次引导，通常 1 分钟内完成。

当任务涉及多文件或可并行流程时，可启用蚁群系统，把 pi 升级为可协作的多智能体执行流。

docs/DEMO-SCRIPT.zh.md — 2 分钟演示脚本（价值与节奏）
ROADMAP.md — 定位、里程碑与衡量指标
DECISIONS.md — 阶段性关键决策与取舍依据

何时不该用蚁群

以下场景建议不要启用蚁群，直接单代理更快：

只改 1 个文件、改动范围明确
快速问答、解释代码、一次性小修复
你需要严格串行控制每一步修改

你会得到

~/.pi/agent/
├── auth.json            API 密钥（0600 权限）
├── settings.json        模型、主题、思维级别
├── keybindings.json     Vim/Emacs 快捷键（可选）
├── AGENTS.md            角色专属 AI 指南
├── extensions/          8 个扩展（7 个默认 + 蚁群）
│   ├── safe-guard       危险命令确认 + 路径保护
│   ├── git-guard        自动 stash 检查点 + 脏仓库警告
│   ├── auto-session     从首条消息自动命名会话
│   ├── custom-footer    增强状态栏（token/成本/时间/git/cwd）
│   ├── compact-header   精简启动信息
│   ├── auto-update      启动时检查更新
│   ├── bg-process       ⏳ **后台进程** — 自动后台化长时间运行的命令（开发服务器等）
│   └── ant-colony/      🐜 自主多智能体蚁群系统（可选）
├── prompts/             10 个模板（/review /fix /commit /test ...）
├── skills/              11 个技能（工具 + UI 设计 + 工作流）
└── themes/              6 个自定义主题

配置模式

模式	步骤	适合
🚀 快速	3	选提供商 → 输入密钥 → 完成
📦 预设	2	选角色方案 → 输入密钥
🎛️ 自定义	6	逐项自选

预设方案

	主题	思维	包含
🟢 全功能	oh-pi Dark	high	全部扩展含蚁群 + 后台进程
🔵 干净	Default	off	无扩展仅核心
🟣 仅蚁群	oh-pi Dark	medium	蚁群 + 最小配置

提供商

Anthropic · OpenAI · Google Gemini · Groq · OpenRouter · xAI · Mistral · FOXNIO（推荐的公益 Claude 提供商）

自动从环境变量检测 API 密钥。

🐜 蚁群系统

核心功能。模拟真实蚁群生态的多智能体系统 —— 深度整合 pi SDK。

你: "把认证从 session 重构为 JWT"

oh-pi:
  🔍 侦察蚁探索代码库（haiku — 快速、低成本）
  📋 根据发现生成任务池
  ⚒️  工蚁并行执行任务（sonnet — 能力强）
  🛡️ 兵蚁审查所有变更（sonnet — 严谨）
  ✅ 完成 — 报告自动注入对话

v0.1.75 更新亮点

Planning Recovery 回路：当 scout 产出非结构化情报时，进入 planning_recovery，而不是直接失败。
执行前计划校验：worker 启动前会校验任务字段完整性（title/description/caste/priority）。
复杂目标 Scout Quorum：多步骤目标默认至少 2 个 scout，提升规划可靠性。

生命周期（简化）

SCOUTING →（必要时）PLANNING_RECOVERY → WORKING → REVIEWING → DONE

架构

每只蚂蚁是进程内的 AgentSession（pi SDK），而非子进程：

pi（主进程）
  └─ ant_colony tool
       └─ queen.ts → runColony()
            └─ spawnAnt() → createAgentSession()
                 ├─ session.subscribe() → 实时 token 流
                 ├─ 零启动开销（共享进程）
                 └─ 共享认证和模型注册表

交互模式： 蚁群在后台运行 —— 你可以继续聊天。实时 widget 显示蚂蚁进度，完成后结果自动注入对话。

Print 模式（pi -p）： 蚁群同步运行，阻塞直到完成。

为什么是蚁群？

真实蚁群无需中央控制就能解决复杂问题。每只蚂蚁遵循简单规则，通过信息素通信，群体自组织。oh-pi 直接映射：

真实蚁群	oh-pi
侦察蚁发现食物	侦察蚁扫描代码库，识别目标
信息素路径	`.ant-colony/pheromone.jsonl` — 共享发现
工蚁搬运食物	工蚁在分配的文件上执行任务
兵蚁守卫巢穴	兵蚁审查变更，请求修复
食物越多蚂蚁越多	任务越多并发越高（自适应）
信息素蒸发	10 分钟半衰期 — 过时信息自动淡化

实时 UI

交互模式下，蚁群显示实时进度：

状态栏 — 紧凑 footer 显示真实指标：完成任务数、活跃蚂蚁、工具调用次数、输出 token 数、成本、耗时
Ctrl+Shift+A — 弹出详情面板，显示任务列表、活跃蚂蚁流、蚁群日志
通知 — 完成时显示汇总

使用 /colony-stop 中止运行中的蚁群。

信号协议

蚁群通过结构化信号与主对话通信，让模型无需猜测后台状态。更新采用被动推送（非阻塞），轮询仅在手动排障时需要：

信号	含义
`COLONY_SIGNAL:LAUNCHED`	蚁群已在后台启动
`COLONY_SIGNAL:SCOUTING`	侦察波次正在探索/规划
`COLONY_SIGNAL:PLANNING_RECOVERY`	计划恢复回路正在重组任务
`COLONY_SIGNAL:WORKING`	工蚁执行阶段进行中
`COLONY_SIGNAL:REVIEWING`	兵蚁审查阶段进行中
`COLONY_SIGNAL:TASK_DONE`	单个任务完成（进度检查点）
`COLONY_SIGNAL:COMPLETE`	蚁群完成并注入报告
`COLONY_SIGNAL:FAILED`	蚁群失败并附带诊断信息
`COLONY_SIGNAL:BUDGET_EXCEEDED`	达到预算上限

轮次控制

每只蚂蚁有严格的轮次预算，防止失控执行：

侦察蚁：8 轮 · 工蚁：15 轮 · 兵蚁：8 轮

模型选择

蚁群自动检测可用模型，让 LLM 按角色选择最优模型：

角色	策略	示例
侦察蚁	快速便宜 — 只读不改	`claude-haiku-4-5`, `gpt-4o-mini`
工蚁	能力强 — 执行代码修改	`claude-sonnet-4-0`, `gpt-4o`
兵蚁	与工蚁相同或稍便宜	`claude-sonnet-4-0`

不指定模型则默认使用当前会话模型。

成本报告

蚁群追踪每只蚂蚁和总花费，在最终报告中汇总。成本不会中断执行 —— 轮次限制和并发控制负责资源管理。

自动触发

LLM 自行决定何时部署蚁群，你不需要操心：

≥3 个文件需要修改 → 蚁群
可并行工作流 → 蚁群
单文件修改 → 直接执行（无蚁群开销）

自适应并发

蚁群自动找到你机器的最优并行度：

冷启动       →  ceil(max/2) 只蚂蚁（快速启动）
探索阶段     →  每波 +1，监控吞吐量
吞吐量下降   →  锁定最优值，稳定运行
CPU > 85%   →  立即降低
429 限流     →  并发 -1 + 退避（2s→5s→10s 上限）
任务完成     →  缩减到最小值

文件安全

一个文件只有一只蚂蚁。始终如此。冲突任务自动阻塞，锁释放后恢复。

技能

oh-pi 附带 11 个技能，分三类。

🔧 工具技能

零依赖 Node.js 脚本 —— 无需 API 密钥。

技能	功能
`context7`	通过 Context7 API 查询最新库文档
`web-search`	DuckDuckGo 搜索（免费，无需密钥）
`web-fetch`	提取网页内容为纯文本

# 示例
./skills/context7/search.js "react"
./skills/web-search/search.js "typescript generics" -n 5
./skills/web-fetch/fetch.js https://example.com

🎨 UI 设计规范技能

完整的设计规范，包含 CSS tokens、组件示例和设计原则。当你要求特定视觉风格时，agent 自动加载。

技能	风格	CSS 前缀
`liquid-glass`	Apple WWDC 2025 半透明玻璃	`--lg-`
`glassmorphism`	毛玻璃模糊 + 透明	`--glass-`
`claymorphism`	柔和 3D 粘土质感	`--clay-`
`neubrutalism`	粗边框、偏移阴影、高对比	`--nb-`

每个都包含 references/tokens.css，可直接使用的 CSS 自定义属性。

你: "用液态玻璃风格做一个仪表盘"
pi 加载 liquid-glass 技能 → 应用 --lg- tokens、玻璃效果、高光动画

🔄 工作流技能

技能	功能
`quick-setup`	检测项目类型，生成 .pi/ 配置
`debug-helper`	错误分析、日志解读、性能分析
`git-workflow`	分支、提交、PR、冲突解决
`ant-colony`	蚁群管理命令和策略

主题


🌙 oh-pi Dark	青色 + 紫色，高对比
🌙 Cyberpunk	霓虹洋红 + 电光青
🌙 Nord	北极蓝色调
🌙 Catppuccin Mocha	暗底柔和色
🌙 Tokyo Night	蓝紫暮色
🌙 Gruvbox Dark	暖色复古

提示词模板

/review    代码审查：bug、安全、性能
/fix       最小改动修复错误
/explain   代码解释，从简到详
/refactor  保持行为的重构
/test      生成测试
/commit    Conventional Commit 消息
/pr        Pull Request 描述
/security  OWASP 安全审计
/optimize  性能优化
/document  生成文档

AGENTS.md 模板

模板	方向
通用开发者	通用编码指南
全栈开发者	前端 + 后端 + 数据库
安全研究员	渗透测试 & 审计
数据 & AI 工程师	MLOps & 管道
🐜 蚁群操作员	多智能体编排

也是 Pi 包

跳过配置器，直接安装资源：

pi install npm:oh-pi

将所有主题、提示词、技能和扩展添加到你现有的 pi 配置中。

要求

Node.js ≥ 20
至少一个 LLM API 密钥
pi-coding-agent（缺失时自动安装）

许可证

MIT