# 架构总览

## 目标

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

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

Runtime 内部长期只有：

```text
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 目录](extensions.md)。

## Runtime 与产品

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

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

## 长期约束

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