docs: 把「业务语义归插件、联动走事件总线」补进 OVERVIEW 与 PLUGIN_DEV

上一提交只在 ARCHITECTURE 里记了终端归属。本次把这条**通用原则**补到另外两份
文档,避免只读 OVERVIEW / 插件开发指南的人仍旧按旧直觉写代码。

## OVERVIEW(中英)

设计要点新增一条「业务语义留在插件层」:内核不定义业务对象(终端、命令历史、
设备状态、媒体库都是插件域)。以终端为例说明:PTY/生命周期/输出缓冲归
agentcli,WebUI/CLI 订阅总线自攒视图,内核只提供事件总线与注册面 —— 新增一类
能力不需要改内核,也不会在核心里堆出第二套业务真相。

## PLUGIN_DEV(中英)

PluginSDK 章节新增「与其它插件联动 — 走事件总线,不要依赖内核内部组件」:
- 代码示例:订阅 terminal_output + tool_call 自己攒视图
- 两条稳定事件表(谁发布、用途)
- ★ 外部插件只能订阅、不能发布(Publish 属 withheld 能力),所以「能力所有者
  需要广播状态」的插件必须内置(agentcli 即此例)
- 指向 internal/pluginview 作为参考实现,并写明「视图不是权威、晚启动会缺早期
  事件」

一个准确性修正:公开 SDK **没有** EventTerminalOutput 常量(属内核内部事件
类型),所以示例里外部插件用 sdk.EventType("terminal_output") 字符串订阅,
并注明内置插件可用 internal sdk 常量 —— 避免文档给出编不过的示例。

验证:四份文档代码围栏配对(74/74、0/0);仅文档改动,无代码影响。
This commit is contained in:
root
2026-10-20 09:41:07 +08:00
parent 3119d48625
commit f33ee3e396
4 changed files with 88 additions and 0 deletions

View File

@ -18,6 +18,12 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
这一划分的意义在于职责边界清晰:内核专注于编排与记忆管理,插件负责具体 IO 实现,二者互不耦合。
**业务语义留在插件层** — 内核不定义业务对象:终端、命令历史、设备状态、媒体库
都属于插件域。以终端为例,PTY、会话生命周期与输出缓冲全归 `agentcli`;WebUI 与
CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `EventToolCall`)
自己攒视图,而不是去读内核里的某个状态组件。内核只提供事件总线与插件注册面——
新增一类能力不需要改内核,也不会在核心里堆出第二套业务真相。
**三层记忆架构** — 通过分级存储策略管理 Agent 长周期运行中的信息留存:
- **Context 层**:内存中预训练词嵌入评分的事件窗口(StaticEmbedder 词向量 → CosineSimilarity,TF-IDF 回退),实时维护最近上下文,低相关性事件自动下沉到下一层
- **Document 层**:JSON 文件 + TF-IDF 向量索引的临时记忆,支持显式提交和隐式归档,冷数据蒸馏到 Graph