# 🐜 Ant Colony — 蚁群多Agent协同扩展

> 真实蚁群生态映射的自组织多Agent系统。自适应并发，信息素通信，零中心化调度。

## 架构

```
蚁后 (Queen)                    主 pi 进程，接收目标，调度生命周期
  │
  ├─ 🔍 侦察蚁 (Scout)          轻量 haiku，探路，标记食物
  ├─ ⚒️  工蚁 (Worker)           sonnet，执行任务，可产生子任务
  └─ 🛡️ 兵蚁 (Soldier)          sonnet，审查质量，可要求返工
  
信息素 (Pheromone)              .ant-colony/ 文件系统，蚂蚁间间接通信
巢穴 (Nest)                    共享状态，原子文件操作，跨进程安全
```

## 生命周期

```
目标 → 侦察 → 任务池 → 工蚁并行执行 → 兵蚁审查 → 修复(如需) → 完成
         │                    │
         │  信息素挥发(10min半衰期)  │  子任务自动产生
         └────────────────────┘
```

## 自适应并发

模拟真实蚁群的动态招募机制：

- **冷启动**：1-2 只蚂蚁，逐步探索
- **探索期**：每次 +1，监测吞吐量拐点
- **稳态期**：围绕最优值微调
- **过载保护**：CPU > 85% 或内存 < 500MB 自动减少
- **弹性伸缩**：任务多→招募，任务少→收缩

## 使用方式

### 使用方式

LLM 在判断任务复杂度足够时会自动调用 `ant_colony` tool，无需手动触发。

### 命令

```
/colony-stop                中止运行中的蚁群
Ctrl+Shift+A                展开蚁群详情面板
```

### 示例

```
/colony 将整个项目从 CommonJS 迁移到 ESM，更新所有 import/export 和 tsconfig

/colony 为 src/ 下所有模块添加单元测试，覆盖率目标 80%

/colony 重构认证系统，从 session-based 迁移到 JWT，保持 API 兼容
```

## 信息素系统

蚂蚁通过信息素间接通信（stigmergy），不直接对话：

| 类型 | 释放者 | 含义 |
|------|--------|------|
| discovery | 侦察蚁 | 发现的代码结构、依赖关系 |
| progress | 工蚁 | 完成的变更、文件修改 |
| warning | 兵蚁 | 质量问题、冲突风险 |
| completion | 工蚁 | 任务完成标记 |
| dependency | 任意 | 文件间依赖关系 |

信息素按指数衰减（半衰期 10 分钟），避免过时信息误导后续蚂蚁。

## 文件锁定

每个任务声明操作的文件列表。女王保证：
- 同一文件同一时刻只有一只蚂蚁在修改
- 文件冲突的任务自动标记 `blocked`，等锁释放后恢复

## 巢穴结构

```
.ant-colony/{colony-id}/
├── state.json           蚁巢主状态
├── pheromone.jsonl      信息素追加日志
└── tasks/               每个任务一个文件（原子更新）
    ├── t-xxx.json
    └── t-yyy.json
```

## 安装

```bash
# 方式1：符号链接到 pi 扩展目录
mkdir -p ~/.pi/agent/extensions/ant-colony
ln -sf "$(pwd)/pi-package/extensions/ant-colony/index.ts" ~/.pi/agent/extensions/ant-colony/index.ts
ln -sf "$(pwd)/pi-package/extensions/ant-colony/types.ts" ~/.pi/agent/extensions/ant-colony/types.ts
ln -sf "$(pwd)/pi-package/extensions/ant-colony/nest.ts" ~/.pi/agent/extensions/ant-colony/nest.ts
ln -sf "$(pwd)/pi-package/extensions/ant-colony/spawner.ts" ~/.pi/agent/extensions/ant-colony/spawner.ts
ln -sf "$(pwd)/pi-package/extensions/ant-colony/queen.ts" ~/.pi/agent/extensions/ant-colony/queen.ts
ln -sf "$(pwd)/pi-package/extensions/ant-colony/concurrency.ts" ~/.pi/agent/extensions/ant-colony/concurrency.ts

# 方式2：通过 oh-pi 安装（待集成）
npx oh-pi  # 选择 Full Power 预设
```

## 模块说明

| 文件 | 行数 | 职责 |
|------|------|------|
| `types.ts` | 117 | 类型系统：蚂蚁、任务、信息素、巢穴状态 |
| `nest.ts` | 196 | 巢穴：文件系统共享状态，原子读写，信息素挥发 |
| `concurrency.ts` | 115 | 自适应并发：系统采样，探索/稳态双阶段调节 |
| `spawner.ts` | 316 | 蚂蚁孵化：进程管理，prompt 构建，输出解析 |
| `queen.ts` | 331 | 女王调度：生命周期，任务波次，多轮迭代 |
| `index.ts` | 324 | 扩展入口：tool/shortcut 注册，TUI 渲染 |