mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-27 12:53:35 +00:00
3e3c6a24d2
- SDK PluginAPI (internal/plugin/sdk/): RegisterTool/RegisterStage/Subscribe/Publish - EventBus (internal/events/): system-level pub/sub with wildcard support - StageHost (internal/agent/core/stages.go): 7-stage message pipeline - Agent core: on_input/pre_action/post_action/before_toolcall/after_toolcall/before_output/after_output - Plugin Registry: SDK plugin registration and tool routing - GraphDB.MergeEntities: entity consolidation with relation redirection - memory_merge tool: allows LLM to merge similar entities - Consolidation task: heartbeat detects conflicts, enqueues via IO for LLM decision - _consolidation_ internal channel for system-level memory maintenance - Comprehensive documentation: ARCHITECTURE.md, PLAN.md, DESIGN.md, README.md - 54 tests across all packages, all passing
133 lines
5.9 KiB
Markdown
133 lines
5.9 KiB
Markdown
# HomeAgent 实施计划
|
||
|
||
## 已完成
|
||
|
||
### Phase 0 — 核心基础设施 ✅
|
||
|
||
| 任务 | 文件 | 状态 |
|
||
|------|------|------|
|
||
| SDK 接口定义 | `internal/plugin/sdk/api.go` | ✅ |
|
||
| PluginAPI（RegisterTool/RegisterStage/Subscribe/Publish） | `internal/plugin/sdk/api.go` | ✅ |
|
||
| 插件内部 EventBus | `internal/plugin/sdk/bus.go` | ✅ |
|
||
| 系统 EventBus | `internal/events/bus.go` | ✅ |
|
||
| StageHost 编排器 | `internal/agent/core/stages.go` | ✅ |
|
||
| Agent 阶段注入（7 个 hook 点） | `internal/agent/core/agent.go` | ✅ |
|
||
| 插件注册表 SDK 支持 | `internal/plugin/plugin.go` | ✅ |
|
||
| main.go 接入 EventBus + StageHost | `cmd/homed/main.go` | ✅ |
|
||
| 架构文档 v4 | `docs/ARCHITECTURE.md` | ✅ |
|
||
|
||
---
|
||
|
||
## 待实施
|
||
|
||
### Phase 1 — 插件 SDK 迁移（当前）
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 1.1 | SDK 添加 `ToolDef` 参数描述支持 | `RegisterTool` 接受 `ToolDef` 结构体（含 parameters）而非纯 handler | high |
|
||
| 1.2 | StageHost 收集完整 ToolDef | 目前只传 name，需传完整 description + parameters 给 LLM | high |
|
||
| 1.3 | Registry.AddPluginAPI 自动构建 StageHost | 替代手动 `syncFromRegistry` | high |
|
||
| 1.4 | 添加 `before_toolcall` deny 机制的测试 | 确保 `StageContext.Response` 在工具级别生效 | medium |
|
||
| 1.5 | 添加 `on_input` 改写消息的测试 | `stageCtx.RawMessage` 在阶段后被正确使用 | medium |
|
||
|
||
### Phase 2 — 迁移 WebUI 到 SDK 模式
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 2.1 | WebUI 改为通过 `PluginAPI` 注册 | 不再依赖 `Device` 接口 | high |
|
||
| 2.2 | WebUI 通过 `Subscribe(EventAll)` 获取所有事件 | 取代 OutputChan 监听 | high |
|
||
| 2.3 | WebUI 注册 `output_send` 工具 | 通过 `RegisterTool` 暴露给 LLM | high |
|
||
| 2.4 | 删除 `internal/api/plugin.go` 的 Device 包装 | 不再需要 `Device` 适配器 | medium |
|
||
| 2.5 | Handler 改为通过 EventBus 获取 IOManager 引用 | 减少直接依赖 | low |
|
||
|
||
### Phase 3 — 迁移 QQ/OneBot 到 SDK 模式
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 3.1 | OneBot 插件改为 `PluginAPI.RegisterTool` | 注册 `qq_send_private_msg` 等工具 | high |
|
||
| 3.2 | OneBot 接管后通过 `Publish(raw_input)` 发布事件 | 取代 IOManager.InjectInput | high |
|
||
| 3.3 | OneBot 注册阶段钩子 | 可接入群聊特定的 `pre_action` 逻辑 | medium |
|
||
| 3.4 | 删除 `internal/onebot/device.go` 的 Device 包装 | SDK 模式原生支持 | medium |
|
||
|
||
### Phase 4 — 迁移 OutputBus 到 SDK
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 4.1 | 创建 `internal/outputbus/` 插件 | 管理 `output_send`/`output_list_channels` | high |
|
||
| 4.2 | 通过 `RegisterTool` 注册输出工具 | LLM 可直接调用 | high |
|
||
| 4.3 | 通过 `RegisterStage(before_output)` 拦截最终文本 | 渠道适配 | medium |
|
||
| 4.4 | Agent 内置的 output_* 工具改为委托给 outputbus | 解耦核心 | medium |
|
||
|
||
### Phase 5 — 清理旧组件
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 5.1 | 删除 `Device` 接口定义 | 全部迁移后移除 | high |
|
||
| 5.2 | 删除 `IOManager.ExecuteTool` | 工具路由走 StageHost | high |
|
||
| 5.3 | 删除 `IOManager.EmitOutput`/`EmitOutputTo` | 走 EventBus | medium |
|
||
| 5.4 | 删除 `IOManager.AtomicSwapDevices` | 不再需要设备热替换 | medium |
|
||
| 5.5 | 删除 `PluginDevice` 包装器 | SDK 模式替代 | medium |
|
||
| 5.6 | 删除 `internal/onebot/device.go` | 已迁移到 SDK | high |
|
||
| 5.7 | 删除 `internal/api/plugin.go` | 已迁移到 SDK | medium |
|
||
| 5.8 | 精简 `cmd/homed/main.go` | 移除设备相关初始化 | medium |
|
||
|
||
### Phase 6 — 进程隔离
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 6.1 | 实现 Unix Socket JSON-RPC 传输层 | 进程隔离模式 | low |
|
||
| 6.2 | `sdk.Run()` 自动检测 in-process/external | 开发 vs 生产 | low |
|
||
| 6.3 | 插件进程管理（启动/停止/健康检查） | Supervisor 扩展 | low |
|
||
|
||
### Phase 7 — 增强功能
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 7.1 | WebUI D3.js 力导向图记忆星图 | 已有 API `GET /api/v1/memory/star` | low |
|
||
| 7.2 | Model Context Protocol (MCP) 支持 | 标准工具协议 | low |
|
||
| 7.3 | 多 Agent 支持 | 每个 Agent 独立上下文 | low |
|
||
| 7.4 | Python 插件 SDK | 扩展生态 | low |
|
||
|
||
---
|
||
|
||
## 文件最终结构（Phase 5 完成后）
|
||
|
||
```
|
||
HomeAgent/
|
||
├── cmd/homed/main.go — 入口
|
||
├── internal/
|
||
│ ├── agent/
|
||
│ │ ├── core/
|
||
│ │ │ ├── agent.go — Agent 核心
|
||
│ │ │ ├── context.go — 相关性上下文
|
||
│ │ │ └── stages.go — StageHost
|
||
│ │ └── api/
|
||
│ │ └── provider.go — LLM Provider
|
||
│ ├── events/
|
||
│ │ └── bus.go — 系统事件总线
|
||
│ ├── plugin/
|
||
│ │ └── sdk/
|
||
│ │ ├── api.go — PluginAPI
|
||
│ │ └── bus.go — 插件 EventBus
|
||
│ ├── memory/ — 三层记忆
|
||
│ ├── knowledge/ — 知识库
|
||
│ ├── tracker/ — 变更追踪
|
||
│ ├── supervisor/ — 守护进程
|
||
│ └── plugins/ — 插件实现
|
||
│ ├── webui/ — HTTP API + 仪表盘
|
||
│ ├── onebot/ — QQ 通道
|
||
│ └── outputbus/ — 输出通道管理
|
||
├── docs/
|
||
│ └── ARCHITECTURE.md — 架构文档
|
||
├── DESIGN.md
|
||
├── PLAN.md
|
||
└── README.md
|
||
```
|
||
|
||
## 设计原则
|
||
|
||
1. **核心零 IO** — Core 不依赖任何插件、设备、通道实现
|
||
2. **三通道标准** — 所有插件通过 Tool/Stage/Event 与核心交互
|
||
3. **增量迁移** — 每阶段保持向后兼容，旧组件与新 SDK 并行运行
|
||
4. **测试覆盖** — 每阶段提交前确保全部测试通过
|