HomeAgent/PLAN.md

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. 测试覆盖 — 每阶段提交前确保全部测试通过