llm-to-agent/docs/architecture.md

架构总览

目标

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

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

Runtime 长期保持：

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 规划。

配置

Runtime 启动时读取全局和当前 Workspace 的可选配置，Workspace 配置按字段覆盖全局配置。产品装配向 Kernel 提供 Extension 工厂函数，每个工厂函数用自身的静态 id 表明身份：

createDeepSeekExtension.id = ExtensionId.DeepSeek;

kernel.use(createDeepSeekExtension) 根据这个 id 取得对应配置，调用 createDeepSeekExtension(options)，再保存创建出的 Extension 实例。配置文件位置、作用域和合并规则都不进入 Kernel。

Extension 负责解释和校验自己的片段。第一版配置只在启动时读取，不创建缺失文件、不写入默认值，也不支持热更新。

扩展点

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

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、事件溯源或分布式状态。