95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
# 架构总览
|
||
|
||
## 目标
|
||
|
||
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)。
|
||
|
||
## 配置
|
||
|
||
Runtime 启动时读取全局和当前 Workspace 的可选配置，Workspace 配置按字段覆盖全局配置。产品装配向 Kernel 提供 Extension 工厂函数，每个工厂函数用自身的静态 `id` 表明身份：
|
||
|
||
```ts
|
||
createDeepSeekExtension.id = ExtensionId.DeepSeek;
|
||
```
|
||
|
||
`kernel.use(createDeepSeekExtension)` 根据这个 `id` 取得对应配置，调用 `createDeepSeekExtension(options)`，再保存创建出的 Extension 实例。配置文件位置、作用域和合并规则都不进入 Kernel。
|
||
|
||
Extension 负责解释和校验自己的片段。第一版配置只在启动时读取，不创建缺失文件、不写入默认值，也不支持热更新。
|
||
|
||
## 扩展点
|
||
|
||
多个实现向能力所有者登记，不再为扩展点增加新的架构层：
|
||
|
||
```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、事件溯源或分布式状态。
|