llm-to-agent/docs/architecture.md

架构总览

目标

llm-to-agent 是个人项目，架构优先级是：

简单易懂 > 容易修改 > 容易扩展 > 通用性

Runtime 内部长期只有：

Kernel + Extensions

Kernel 管“Extension 怎样连接和运行”，Extension 管“系统具体能做什么”。

Kernel

第一版 Kernel 只保留几件直观的事：

• 按顺序装入 Extension；
• 依次执行 setup 和 start，停止时倒序执行 stop；
• 通过命名抓手提供和取得能力；
• 通过命名事件发布和监听事实。

抓手和事件暂时使用带命名空间的字符串，不为它们建立复杂的 TypeScript 类型系统。Setup Context 负责注册，Runtime Context 负责使用；Kernel 信任 Extension 遵守生命周期，不增加 Context 失效检查和不可变包装。

Kernel 不认识 Workspace、Conversation、Run、Agent、模型或 Tool。只有所有 Extension 都必须遵守的运行规则才进入 Kernel。

Extensions

Extension 可以提供能力、调用其他能力、添加同类实现、发布或监听事实，并管理自己的数据与资源。

控制流程必须使用明确调用；事件只表示已经发生的事实，不能承担顺序、返回值、审批或回滚。

Extension 之间只依赖公开契约，不引用彼此的实现。

具体能力归属见 Extension 目录。

Runtime 与产品

Runtime 持有唯一一套 Kernel、Extension 实例和本地数据。CLI、Web、Desktop 是不同产品入口，使用同一套能力和状态。

自进化阶段再增加 Runtime 外的 Supervisor，用于版本切换、健康检查和失败回退。

长期约束

• 默认在现有 Extension 内增加普通代码，出现真实独立边界后再拆。
• 第一版静态装配，不建设插件平台、热加载或依赖图。
• 保持单进程、单用户和本地优先，直到真实需求要求改变。
• 不提前建设 Command Bus、Middleware、事件溯源或分布式状态。
• 新增 Kernel 机制必须有多个具体使用者。