163 lines
7.6 KiB
Markdown
163 lines
7.6 KiB
Markdown
# 架构总览
|
||
|
||
## 定位
|
||
|
||
本项目是纯个人使用、本地优先的开发助手与电脑管家。完整功能范围保持不变，但源码只围绕两个长期边界演化：`Kernel` 撑起系统，`Extensions` 增加能力。
|
||
|
||
架构不追求套用通用框架的模块名。一个概念是否进入 Kernel，只看它是不是所有能力都必须遵守的稳定运行规则；其余需求默认通过 Extension 实现。
|
||
|
||
## 系统拓扑与源码架构
|
||
|
||
系统拓扑描述进程如何连接：
|
||
|
||
```text
|
||
Supervisor ──启动/切换/回退──▶ Runtime
|
||
▲
|
||
│
|
||
CLI / Web / Desktop
|
||
```
|
||
|
||
Runtime 内部的源码架构只有：
|
||
|
||
```text
|
||
Kernel ◀──── Extensions
|
||
```
|
||
|
||
Supervisor、Runtime 入口和三个产品入口是部署位置，不是叠在 Kernel 上方的业务架构层。
|
||
|
||
## Kernel
|
||
|
||
Kernel 负责让系统可靠地运行：
|
||
|
||
- 启动、停止以及 Extension 生命周期；
|
||
- Extension 注册、能力查找和运行事件；
|
||
- Space、Conversation、Message 与 Run 的稳定语义；
|
||
- Agent 主执行循环、流式输出、取消和错误边界；
|
||
- 本地状态、持久化一致性和资源所有权；
|
||
- Tool 等副作用能力不可绕过的权限与记录边界；
|
||
- 产品输入提交和 Run 事件订阅的统一运行接口。
|
||
|
||
Kernel 可以认识本项目真正不可缺少的概念，不为了保持“微内核纯度”拆出 Application、Host 或 Client 等中间层。
|
||
|
||
正常增加产品能力时不修改 Kernel。只有多个 Extension 都缺少同一种通用机制，或某项规则必须由系统统一强制执行时，才扩展 Kernel 的公共接口。
|
||
|
||
## Extensions
|
||
|
||
Extension 负责让系统具备具体能力，例如模型、Workspace、Shell、Git、计划、多 Agent、记忆、浏览器、自动化、界面和系统控制。
|
||
|
||
Extension 不需要声明自己属于 Adapter、Tool、Hook、Behavior 或 Profile。一个完整能力可以同时注册可调用实现、订阅事件、维护数据并管理资源。
|
||
|
||
最小契约只有生命周期：
|
||
|
||
```ts
|
||
interface Extension {
|
||
readonly id: string;
|
||
setup(context: ExtensionSetupContext): void | Promise<void>;
|
||
start?(context: ExtensionRuntimeContext): void | Promise<void>;
|
||
stop?(context: ExtensionRuntimeContext): void | Promise<void>;
|
||
}
|
||
```
|
||
|
||
- `setup` 只注册能力和事件处理器，不开启外部资源；所有 Extension 完成 `setup` 后才进入 `start`。
|
||
- `start` 开启终端、网络连接、后台任务等运行资源。
|
||
- `stop` 按安装的逆序关闭资源。
|
||
|
||
Extension 对象只是安装入口。Kernel 在运行时真正调用的是 Extension 注册的能力；只需响应过程的 Extension 则订阅 Kernel 事件。事实事件只能由拥有该事实的 Kernel 流程发布，ExtensionContext 不提供发布 Kernel 事件的权限。
|
||
|
||
## 公共扩展与产品线私有扩展
|
||
|
||
Extensions 按使用范围组织：
|
||
|
||
```text
|
||
extensions/
|
||
├── shared/ # 三条产品线可复用的能力
|
||
├── cli/ # CLI 私有输入、展示和终端交互
|
||
├── web/ # Web 私有协议、路由和页面
|
||
└── desktop/ # Desktop 私有原生集成
|
||
```
|
||
|
||
公共扩展不认识具体产品界面。产品线私有扩展可以使用 Kernel 和公共能力，但 CLI、Web、Desktop 私有扩展之间不能直接依赖；不再只属于一条产品线的代码应提升到 `shared/`，不要求三个产品全部使用。
|
||
|
||
“公共”与“私有”只是源码归属和装配规则。Kernel 不认识这些分类，也不包含 `cli | web | desktop` 分支。
|
||
|
||
## 产品装配
|
||
|
||
每条产品线只有一份扩展清单：
|
||
|
||
```text
|
||
products/
|
||
├── shared.ts
|
||
├── cli.ts
|
||
├── web.ts
|
||
└── desktop.ts
|
||
```
|
||
|
||
启动入口先安装公共扩展，再安装当前启用产品的私有扩展。装配清单不承载业务逻辑，也不形成新的架构层。
|
||
|
||
单个 Runtime 可以同时装配三条产品线的接入扩展；也可以在某种安装形态中只启用其中一部分。无论启用哪些产品，Kernel 和公共数据始终只有一套。
|
||
|
||
系统拓扑图中的 CLI、Web、Desktop 表示用户实际接触的产品入口。产品私有 Extension 运行在适合自己的位置：Web Extension 可以直接在 Runtime 中开启服务；CLI 与 Desktop 可以包含 Runtime 侧接入能力和进程外的轻量启动器。启动器只负责拉起或连接 Runtime、转发输入输出，不保存 Agent 状态，也不复制 Kernel。CLI 启动器退出时，Runtime 中的 Kernel 与已提交 Run 继续运行。
|
||
|
||
产品入口需要使用的 Kernel 接口不只包含聊天 Run，还包括三类基础操作：
|
||
|
||
- 创建、读取和修改 Space、Conversation、配置、扩展及审批等产品状态；
|
||
- 提交、查询、取消和继续 Run；
|
||
- 按连接或 Run 重新订阅实时事件。
|
||
|
||
这些是同一套运行接口，不要求再建立独立 Client 架构层。具体采用本地 IPC、HTTP、SSE 或其他传输方式，由相应产品 Extension 决定。
|
||
|
||
## 首版工作流
|
||
|
||
第一版先跑通同一条端到端主链路：
|
||
|
||
```text
|
||
产品私有扩展接收输入
|
||
↓
|
||
Kernel 创建 Run 并保存用户消息
|
||
↓
|
||
Kernel 调用模型 Extension
|
||
↓
|
||
模型返回文本增量或 Tool 请求
|
||
↓
|
||
Kernel 按需调用 Tool Extension，并将结果继续交给模型
|
||
↓
|
||
Kernel 保存最终消息和 Run 状态
|
||
↓
|
||
产品私有扩展订阅 Run Event 并展示
|
||
```
|
||
|
||
CLI 私有 Extension 与轻量启动器把 Run Event 渲染到终端；Web 转换为网络响应和事件流；Desktop 转换为 IPC、窗口或原生通知。产品差异只存在于链路两端，中间的 Run、模型、Tool、记忆和计划能力全部复用。
|
||
|
||
## 能力与事件
|
||
|
||
- **能力**是 Kernel 或其他 Extension 需要主动调用并取得结果的实现，例如模型生成、Tool 执行或记忆检索。
|
||
- **事件**是已经发生的运行事实，例如 Run 开始、文本增量、Tool 完成和 Run 结束。所有监听器相互隔离；监听失败进入诊断记录，不反向改变已经发生的事实或主流程结果。
|
||
|
||
需要阻止、修改或返回结果的逻辑不能伪装成普通事件监听；真实需求出现时，由 Kernel 提供明确的调用能力或受控执行点。
|
||
|
||
Extension 的持久化数据统一通过 Kernel Store 写入各自命名空间。Extension 可以拥有自己的数据结构和外部资源，但不能绕过 Kernel 的数据目录、生命周期、权限和清理规则；模型连接、浏览器进程等运行资源在 `start/stop` 中管理。
|
||
|
||
## 依赖规则
|
||
|
||
```text
|
||
main → products → extensions → kernel
|
||
|
||
shared extensions → kernel
|
||
CLI extensions → kernel + shared capabilities
|
||
Web extensions → kernel + shared capabilities
|
||
Desktop extensions → kernel + shared capabilities
|
||
|
||
Kernel ✕ 具体 Extension
|
||
CLI ✕ Web ✕ Desktop 私有实现
|
||
```
|
||
|
||
图中的依赖表示源码 import。Extension 之间需要协作时，通过 Kernel 注册和取得公开能力，不直接反向引用另一个 Extension 的内部实现。
|
||
|
||
目录不是边界本身。判断架构是否成立的标准是：新增具体能力通常只需增加或修改 Extension，而 Kernel 不需要知道它的名字和产品归属。
|
||
|
||
## Supervisor 与自进化
|
||
|
||
Supervisor 位于当前 Runtime 版本之外，只负责启动、版本切换、健康检查和失败回退。它在 System Evolution 发布闭环出现时实现；此前可由普通启动脚本承担。
|
||
|
||
Agent 可以在隔离 worktree 中修改 Kernel 或 Extensions、运行测试并展示 Diff。具体功能优先通过 Extension 生长，但 Kernel 并非不可修改；涉及新的全局运行规则时，仍可在验证和回退保护下演化 Kernel。
|