# 架构总览

## 目标

llm-to-agent 是个人使用、本地优先的 Agent。架构优先级是：

```text
简单易懂 > 容易扩展和修改 > 架构完整 > 通用性
```

Runtime 长期保持：

```text
Kernel + Extensions
```

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

## Kernel

Kernel 只提供所有 Extension 共用的运行机制：

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

Kernel 不认识 Workspace、Agent、模型、Tool 或其他业务概念。

## Extensions

Extension 是 Runtime 的独立装配单位，分为三类：

- 共享能力：拥有明确状态、资源或业务流程；
- Provider：接入可替换的模型、协议或外部系统；
- 产品入口：处理 CLI、Web、Desktop 的输入、输出和平台资源。

规划可以列出尚未实现的 Extension，源码、Catalog 和产品装配只包含已经开始实现的部分。Extension 内部文件和目录不设统一结构。

最终能力归属见 [Extension 规划](extensions.md)。

## 扩展点

多个实现向能力所有者登记，不再为扩展点增加新的架构层：

```text
models.providers
tools.providers
agent.contextContributors
automation.triggers
security.approvalChannels
health.checks
```

模型 Provider 由 `models` 选择，具体 Tool 由 `tools` 统一执行，上下文来源由 `agent` 组合。

## 协作

- 控制流程使用明确调用；
- 事件只表示已经发生的事实；
- Extension 只依赖其他 Extension 的公开契约；
- Provider 向扩展点注册实现，能力所有者不引用 Provider 实现；
- Tool 是能力 Extension 暴露给 Agent 的操作，不是新的 Extension；
- 高风险操作统一经过 `security`，凭据统一通过 `secrets` 的受控引用取得。

事件不能承担顺序、返回值、审批、事务或回滚。

## Runtime 与产品

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

版本切换、进程守护、离线恢复和失败回退由 Runtime 外的 Supervisor 负责。

## 长期约束

- 保持单用户、本地优先和单 Runtime；
- 保持一个 TypeScript package，直到出现独立构建、发布或进程边界；
- 使用静态装配，不提前建设插件平台、热加载或依赖图；
- 规划高风险边界，但不创建占位目录、文件、ID 或 Hook；
- 普通函数、页面、命令、Parser、Prompt 和单个 Tool 不拆成 Extension；
- 新增 Kernel 机制必须有多个具体使用者；
- 不提前建设 Command Bus、Middleware、事件溯源或分布式状态。