Agent 模块实施状态
最后更新：2026-03-22 关联里程碑：M1 Skills运行时
1. 模块概览
Agent 模块是消息处理的核心，负责： - LLM 流式调用与工具执行 - 会话管理与持久化 - 子 Agent 生命周期 - 记忆系统 - 技能注入
2. 核心组件状态
2.1 Agent 运行时
| 组件 | 文件 | 状态 | 完成度 | 功能说明 |
| Runner核心循环 | runner.py | ✅ 完成 | 100% | prompt → LLM stream → tool exec → loop |
| 流式接口统一 | stream.py | ✅ 完成 | 100% | 多Provider统一chunk格式 |
| 会话管理 | session.py | ✅ 完成 | 100% | JSONL DAG格式持久化 |
| 系统提示构建 | system_prompt.py | ✅ 完成 | 100% | AGENTS.md + Skills + 上下文 |
| Token计数 | tokens.py | ✅ 完成 | 100% | Token统计与限制 |
| 进度事件 | progress.py | ✅ 完成 | 100% | 执行进度推送 |
| 类型定义 | types.py | ✅ 完成 | 100% | 共享类型 |
2.2 LLM Provider 适配
| Provider | 状态 | 完成度 | 说明 |
| OpenAI | ✅ 完成 | 100% | GPT-4, GPT-3.5等 |
| Anthropic | ✅ 完成 | 100% | Claude系列 |
| Google Gemini | ✅ 完成 | 100% | Gemini Pro等 |
| Ollama | ✅ 完成 | 100% | 本地模型 |
| OpenAI兼容 | ✅ 完成 | 100% | 20+ 兼容提供商 |
Provider能力注册表：src/pyclaw/agents/providers/capability_registry.py
2.3 会话系统
| 功能 | 状态 | 完成度 | 说明 |
| 会话范围 | ✅ 完成 | 100% | global / per-sender / per-channel-peer |
| 定时重置 | ✅ 完成 | 100% | 指定时间创建新会话 |
| 空闲重置 | ✅ 完成 | 100% | 空闲超时自动新建 |
| 会话压缩 | ✅ 完成 | 100% | 自动压缩早期消息注入摘要 |
| 分支支持 | ✅ 完成 | 100% | JSONL DAG分支结构 |
2.4 思维模式
| 模式 | 状态 | 说明 |
disabled | ✅ 完成 | 直接生成 |
low | ✅ 完成 | 简短推理 |
high | ✅ 完成 | 深度推理（token消耗更大） |
3. 子 Agent 系统
3.1 生命周期管理
| 操作 | 文件 | 状态 | 说明 |
| spawn | subagents/ | ✅ 完成 | 创建子Agent |
| steer | subagents/ | ✅ 完成 | 重定向子Agent |
| kill | subagents/ | ✅ 完成 | 终止子Agent |
| 列表 | subagents/ | ✅ 完成 | 列出活跃子Agent |
3.2 约束
| 约束 | 值 | 说明 |
| MAX_DEPTH | 3 | 最大嵌套深度 |
| MAX_CONCURRENT | 5 | 最大并发数 |
4. 记忆系统
4.1 双引擎架构
| 引擎 | 文件 | 状态 | 功能 |
| SQLite FTS5 | memory/ | ✅ 完成 | 全文检索，关键词匹配 |
| LanceDB | memory/ | ✅ 完成 | 向量搜索，语义匹配 |
| 混合排序 | memory/ | ✅ 完成 | MMR + 时间衰减融合 |
4.2 记忆工具
| 工具 | 状态 | 说明 |
memory_search | ✅ 完成 | 搜索记忆 |
memory_store | ✅ 完成 | 存储记忆 |
5. 工具系统
5.1 内置工具（20+）
| 类别 | 工具 | 状态 |
| 文件操作 | read_file, write_file, list_dir | ✅ 完成 |
| 搜索 | grep, find, web_search | ✅ 完成 |
| 执行 | exec (shell命令) | ✅ 完成 |
| 浏览器 | navigate, click, screenshot | ✅ 完成 |
| 记忆 | memory_search, memory_store | ✅ 完成 |
| 网络 | web_fetch | ✅ 完成 |
| 系统 | cron (定时任务) | ✅ 完成 |
5.2 审批机制
| 机制 | 状态 | 说明 |
| allowlist | ✅ 完成 | 匹配命令直接执行 |
| denylist | ✅ 完成 | 匹配命令直接拒绝 |
| 审批请求 | ✅ 完成 | 推送到UI/CLI等待确认 |
5.3 沙箱
| 功能 | 状态 | 说明 |
| 工作区限制 | ✅ 完成 | tools.restrictToWorkspace |
| 路径规范化 | ✅ 完成 | 防止目录遍历 |
6. 运行时编排设计（进行中）
| 设计要素 | 状态 | 说明 |
| 三阶段模型 | 📋 设计中 | Orchestrate → Delegate → Reconcile |
| 编排制品 | 📋 设计中 | Manifest JSON持久化 |
| 动态增删 | 📋 设计中 | 运行中spawn/kill/steer |
| 工具注入 | 🚧 进行中 | 子Agent工具裁剪子集 |
详见：docs/plans/2026-03-21-runtime-agent-orchestration-design.md
7. 多 Agent 路由
7.1 路由优先级（7级）
| 优先级 | 绑定类型 | 状态 |
| 1 | 会话绑定 (session → agent) | ✅ 完成 |
| 2 | 线程绑定 (thread → agent) | ✅ 完成 |
| 3 | 通道绑定 (channel → agent) | ✅ 完成 |
| 4 | 群组绑定 (chat_id → agent) | ✅ 完成 |
| 5 | 用户绑定 (sender → agent) | ✅ 完成 |
| 6 | 全局绑定 (pattern match) | ✅ 完成 |
| 7 | 默认 Agent | ✅ 完成 |
8. 关键文件索引
| 文件 | 职责 |
src/pyclaw/agents/runner.py | Agent核心循环 |
src/pyclaw/agents/stream.py | 多Provider流式统一 |
src/pyclaw/agents/session.py | 会话持久化 |
src/pyclaw/agents/tools/ | 内置工具实现 |
src/pyclaw/agents/skills/ | 技能系统 |
src/pyclaw/agents/subagents/ | 子Agent管理 |
src/pyclaw/memory/ | 记忆系统 |
9. 待办事项
- [ ] 子Agent默认工具注入（当前
tools=[]） - [ ] 编排制品持久化实现
- [ ] steering_instructions消费确认
- [ ] 主会话与子会话上下文回灌机制