# 架构总览

## 定位

`llm-to-agent` 是纯个人使用、本地优先的开发助手与电脑管家。它以一个常驻 Runtime 作为唯一运行宿主，并通过 CLI、Web、Desktop 三个客户端共享数据和执行状态。

系统采用四层结构：

```text
Launcher / Supervisor
        ↓
Runtime Host
        ↓
Application Runtime
        ↓
Microkernel + Extensions
```

这四层表达职责和依赖方向，不要求第一版拆成四个独立进程。

## Launcher / Supervisor

Supervisor 位于 Agent 运行版本之外，只负责启动、版本切换、健康检查和失败回退。它不理解 Space、Conversation、Tool 或 Agent 推理。

Supervisor 在 P3 的 System Evolution 发布闭环中实现，P1/P2 开发阶段可以先由普通启动脚本承担进程拉起。

## Runtime Host

Runtime Host 是 Node.js 进程的组合入口，负责：

- 创建并启动 Application Runtime 与 Microkernel；
- 装配当前启用的扩展；
- 开启本地客户端连接；
- 处理进程信号、单实例和退出；
- 将配置与基础设施交给内部模块。

Host 不包含 Project、Conversation、Agent 工作流等业务规则。

## Application Runtime

Application Runtime 负责这个产品不可缺少的应用能力：

- Project / Task Space；
- Conversation 与持久化 Run Record；
- 本地数据 Repository 和唯一写入；
- 客户端 Command、Query 与 Event Stream；
- 当前 Space/Conversation 上下文；
- Profile 选择和基础并发策略。

它不包含 DeepSeek 请求、Shell、Git、浏览器驱动、提示词或具体 Agent 协作策略。

## Microkernel

Microkernel 负责一次 Agent 执行的通用机制：

- 创建内存中的 Run Context；
- 调用 Agent Behavior；
- 注册并调用 Tool；
- 执行 Hook Pipeline；
- 发出流式输出和运行事件；
- 传播取消信号并隔离执行错误。

Microkernel 不认识 Project、Task 或具体存储，也不依赖任何具体扩展。

## Extensions

扩展只放真正可替换、可按需增加的能力：

- **Adapter**：DeepSeek、未来模型提供商、浏览器或检索驱动；
- **Tool**：文件、Shell、Git、浏览器、桌面控制；
- **Hook**：围绕 Tool/Run 生命周期观察、限制或响应；
- **Behavior**：DefaultAgent、CodingAgent、Planner、Reviewer。

Space、Conversation 和持久化 Run Record 是 Application Runtime 的产品领域，不作为可卸载插件。

## Profile

Profile 是 Application Runtime 管理的声明式能力组合，不是独立运行层：

```text
Profile
├── 默认 Behavior
├── 可用 Tools
├── 启用 Hooks
├── 模型设置
└── 上下文/记忆策略
```

Project 和 Task 是 Space 类型；System Evolution 是应用于 Project 的特殊 Profile。

## 依赖规则

```text
Supervisor → Runtime Host
Runtime Host → Application Runtime / Microkernel / Extensions
Application Runtime → Microkernel 公共接口
Extensions → Microkernel 扩展接口
Microkernel ✕ Application Runtime / 具体 Extensions
Clients → Runtime Interface
```

目录隔离只是表现，以上依赖方向才是边界是否真实成立的判断依据。

## 客户端接口

CLI、Web、Desktop 逻辑上只使用三类交互：

- **Command**：创建 Space、发送消息、取消 Run 等状态变更；
- **Query**：读取 Space、Conversation、Run 和日志；
- **Event Stream**：接收模型增量、Tool 过程和 Run 状态。

具体采用 HTTP/SSE、Unix Socket 或其他本地协议在实现时确定，不提前冻结字段。

## Event 与 Hook

- **Run Event** 是发生过的事实，用于日志和客户端实时展示。
- **Hook** 是事件前后实际执行的扩展代码。

两者不能混为同一个事件总线：记录了一个事件，不代表必须触发可修改流程的 Hook。

## 演化原则

任何一层都允许由 Agent 修改，包括 Application Runtime 和 Microkernel。Agent 在 System Evolution Project 的隔离 worktree 中修改源码、运行测试并展示 Diff；Git 写操作由用户确认，Supervisor 负责切换构建版本和失败回退。

自进化依赖的是源码可修改、候选版本隔离、测试、发布和回退，不要求把所有产品能力插件化。