# agent67v2 — 多智能体协作版个人助手

> Lambda: `Memory(Loop(Coordinator >> Handoff(SkillRegistry)))`

## 1. 动机

agent67 (v1) 是单体 ReAct agent，42 个工具全量注入 system prompt：

| 问题 | 原因 | 影响 |
|------|------|------|
| 响应慢 | 42 工具描述 ~2000 tokens 注入 prompt | LLM 推理 token 多，首响延迟高 |
| 无法协同 | 单一 ReAct 循环，不暴露为可调用 Skill | 其他编排器无法复用 agent67 的能力 |
| 不可拆分 | 所有工具平铺在一个 agent 中 | 调试困难，职责不清 |

## 2. 架构

```
agent67v2 协调者 (6 个元工具, ~500 tokens prompt)
├── code-agent    (13工具: 文件/代码/Git)
├── shell-agent   (1工具: Bash)
├── web-agent     (10工具: 搜索/知识库/文档)
├── memory-agent  (17工具: 记忆/任务/调度/画像)
├── system-agent  (4工具: 浏览器/应用/系统/截图)
└── researcher    (17工具: 读论文→复现→实验→记录)
```

### Lambda 表达式对比

```
v1: λ = Memory(Loop(Brain >> Route(42 tools)))           # 单体
v2: λ = Memory(Loop(Coordinator >> Handoff(Registry)))    # 多智能体
         ├─ code-agent  = Loop(CodeBrain >> Route(13))
         ├─ shell-agent = Guard(Loop(ShellBrain >> Bash))
         ├─ web-agent   = Loop(WebBrain >> Route(10))
         ├─ memory-agent = Memory(Loop(MemBrain >> Route(17)))
         ├─ system-agent = Guard(Loop(SysBrain >> Route(4)))
         └─ researcher  = Loop(ResBrain >> Route(17))
```

## 3. 三大改进

### 3.1 拆分微代理

42 个工具按职责拆分为 6 个专业微代理。协调者只持有 7 个元工具 (`call_code`, `call_shell`, `call_web`, `call_memory`, `call_system`, `call_research`, `ToolSearch`)。

**效果**: system prompt 从 ~2000 tokens 缩减到 ~500 tokens，首次响应快 2-3x。

### 3.2 Skill 复用 (SkillRegistry)

每个微代理注册为 `Skill`，通过全局 `SkillRegistry` 可被任何编排器发现和调用：

```python
from lambdagent.skills import SkillRegistry
registry = SkillRegistry()
code_agent = registry.get("code-agent")
result = code_agent.apply("读取 main.py")
```

**复用场景**:
- research67 编排器可复用 `code-agent` 做代码实验
- agentbuilder67 可复用 `web-agent` 搜索参考配置
- 新编排器只需 `registry.get("code-agent")` 即可使用

### 3.3 工具懒加载 (ToolSearch)

参考 Claude Code 的 deferred tools 模式，协调者不在 prompt 中注入全部工具描述，而是通过 `ToolSearch` 元工具按需查找：

```json
{"action": "ToolSearch", "input": {"query": "文件操作"}}
```

返回匹配的工具列表，协调者再决定委派给哪个代理。

## 4. 配置与启动

### 统一配置文件

`agent-config.yml` 包含协调者 + 子代理定义。子代理通过 `subAgents` 节声明，支持两种模式：

```yaml
subAgents:
  code-agent:
    config: agents/code-agent.yml   # 文件引用 (本地开发)
    inline: {type: react, ...}      # 内联配置 (PaaS 部署)
    tool: call_code
```

### 启动方式

```bash
# PaaS CLI (与 agent67 一致)
python3 -m agentpaas agent create --name lambda2 \
  --config agentexample/agent67v2/agent-config.yml
python3 -m agentpaas chat lambda2

# 直接运行
cd agentexample/agent67v2 && python run.py
```

### 编译器扩展

`from_config()` 编译器新增 `subAgents` 支持：
- `build_agent()` 检测 `subAgents` 节 → 编译子代理 → 注入为 `call_*` 工具
- 子代理使用**懒编译** — 首次调用时才 `from_config()`
- `inline` 模式通过 `build_agent(dict)` 直接编译，不依赖文件路径
- 自动注册为 `Skill` 到全局 `SkillRegistry`

## 5. Research Skill Pack

独立的可复用技能包，封装 "读论文→复现→实验→记录" 研究流程：

```
lambdagent/skillpacks/research/
├── __init__.py
├── skills.py              # 4 个独立 Skill + 1 个 Pipeline
└── agent-config.yml       # PaaS 可部署的编排器
```

| Skill | 职责 | 工具 |
|-------|------|------|
| `paper-reader` | 搜索→阅读→提取关键信息 | WebSearch, WebFetch |
| `code-reproducer` | 克隆→理解→运行→对比 | Bash, ReadFile, CodeSearch |
| `experimenter` | 设计实验→执行→分析 | Bash, WriteFile, RunTests |
| `lab-notebook` | 整理笔记→报告→知识库 | WriteFile, KBAdd, MemoryStore |
| `research-pipeline` | 完整流程 (组合以上) | reader >> reproducer >> experimenter >> notebook |

agent67 (v1) 通过 `ResearchWorkflow` 工具也能调用此流程。

## 6. 文件清单

```
agent67v2/
├── agent-config.yml          # 统一配置 (协调者 + 6个子代理 inline)
├── orchestrator.yml          # 协调者配置 (独立版)
├── DESIGN.md                 # 本文件
├── run.py                    # 交互式运行入口
├── launch_paas.py            # PaaS 部署入口
├── agents/
│   ├── code-agent.yml
│   ├── shell-agent.yml
│   ├── web-agent.yml
│   ├── memory-agent.yml
│   └── system-agent.yml
├── core/
│   ├── coordinator.py        # 协调者 ReAct 循环
│   └── bootstrap.py          # 从 agent-config.yml 构建完整 Term
├── skills/
│   └── registry.py           # 微代理 Skill 注册
└── tools/
    └── tool_search.py        # ToolSearch 懒加载元工具
```