🐜 Ant Colony for Pi

把 pi-coding-agent 从单代理，升级为可协作的蚁群式编码系统。

当前仓库正从「pi 配置增强包」收敛为「面向复杂任务的 pi 蚁群插件」。 Ant Colony for Pi 现在是对外的主产品名称。 oh-pi 作为现阶段的分发/引导包名保留，ant-colony 是主能力、主叙事、主产品方向。

English | 中文 | Français

npx oh-pi

命名说明

本项目不是另一个同名 oh-pi 项目的 fork，也不隶属于那个项目。

对当前仓库来说：

• Ant Colony for Pi = 标准产品名
• oh-pi = 当前 bootstrap / 包名 / 过渡名称

正式改名迁移方案见：

• 品牌方向：Agent Colony
• canonical repo/package：pi-agent-colony
• docs/RENAMING-PLAN.md
• docs/RENAME-EXECUTION-CHECKLIST.md
• docs/MIGRATION-MATRIX.md
• docs/RELEASE-SEQUENCING.md
• docs/MIGRATION-ANNOUNCEMENT.md

新定位

这不是一个“配置大礼包”

我们不再把产品核心定义为：

• 主题、预设、技能、快捷配置的集合
• “oh-my-zsh for pi” 式 convenience layer

我们现在把产品核心定义为：

• Ant Colony for Pi
• 一个为复杂编码任务设计的多智能体协作插件
• 让 pi 具备侦察、拆解、并行执行、审查与恢复能力

它解决什么问题

当任务具备这些特征时，单 agent 往往开始吃力：

• 涉及 3 个以上文件
• 需要 跨模块理解与重构
• 可以拆成 多个并行子任务
• 需要 执行后统一审查与修复闭环

Ant Colony 的目标不是替代 pi，而是让 pi 在这类任务上拥有一个更强的执行层。

30 秒开始

npx oh-pi             # 兼容期内的 legacy/bootstrap 安装路径
npx pi-agent-colony   # canonical 安装路径
pi                    # 在 pi 中使用蚁群能力

当前阶段，oh-pi 仍作为兼容桥接名称保留，并继续负责把能力写入 ~/.pi/agent/。 后续默认名称会逐步切到 pi-agent-colony，产品公开名称则保持 Agent Colony / Agent Colony for Pi。

迁移公告

Canonical 安装路径：

npx pi-agent-colony
pi install npm:pi-agent-colony

兼容安装路径：

npx oh-pi
pi install npm:oh-pi

详情见：

• docs/MIGRATION-ANNOUNCEMENT.md

先看蚁群价值，再看安装细节

当你这样说

“把认证从 session 重构为 JWT，并补齐测试与回归检查”

Ant Colony 会这样工作

1. scout 侦察代码库，定位边界与依赖
2. planner 生成任务池与执行顺序
3. workers 并行修改不同文件/模块
4. reviewer 统一审查变更，必要时退回复修
5. 汇总最终结果并注入主对话

这才是本项目真正的差异化：复杂任务吞吐、任务分解能力、以及执行可靠性。

• docs/DEMO-SCRIPT.zh.md — 2 分钟演示脚本
• ROADMAP.md — 新定位下的里程碑
• DECISIONS.md — 定位调整与架构取舍
• docs/PRODUCT.md — 产品边界、适用场景与非目标
• docs/ARCHITECTURE-REFACTOR.md — 插件边界与重构方向（英文）

何时应该用蚁群

优先用于：

• 多文件修改
• 跨模块重构
• 新 feature 拆解执行
• 测试补全、修复与回归检查
• 可并行的工程任务

何时不该用蚁群

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

• 只改 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/              10 个技能（工具 + 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 附带 10 个技能，分三类。

🔧 工具技能

零依赖 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