# 规划目录

本文描述 `Kernel + Extensions` 架构下的源码与运行数据目录。目录服务于依赖关系和可理解性，不要求为尚未实现的能力预建空 package。

## 源码仓库

当前采用一个 TypeScript package：

```text
llm-to-agent/
├── src/
│   ├── kernel/
│   │   ├── kernel.ts          # 生命周期与总入口
│   │   ├── extension.ts       # Extension 契约与扩展点
│   │   ├── registry.ts        # Extension 注册的能力
│   │   ├── events.ts          # 运行事件
│   │   └── ...                # 后续 Space、Conversation、Run、Store、权限等稳定机制
│   │
│   ├── extensions/
│   │   ├── shared/            # 跨产品公共能力
│   │   ├── cli/               # CLI 私有能力
│   │   ├── web/               # Web 私有能力
│   │   └── desktop/           # Desktop 私有能力
│   │
│   ├── products/
│   │   ├── product.ts         # 产品定义
│   │   ├── index.ts           # 产品查找
│   │   ├── shared.ts          # 公共 Extension 装配清单
│   │   ├── cli.ts             # CLI 私有装配清单
│   │   ├── web.ts             # Web 私有装配清单
│   │   └── desktop.ts         # Desktop 私有装配清单
│   │
│   └── main.ts                # 创建 Kernel 并执行装配
│
├── docs/
├── tests/                     # 跨进程或跨版本测试
├── tooling/                   # 构建和开发辅助
├── package.json
└── tsconfig.json
```

单元测试与所属源码放在一起。

## Kernel 目录

`src/kernel/` 只保存所有能力共同依赖的稳定运行机制。首批内容是 Extension 生命周期、能力注册和事件；Space、Conversation、Run、Store、取消、权限等在对应功能实际实现时进入。

Kernel 不导入 `src/extensions/` 或 `src/products/`。具体能力流入 Kernel 的唯一方式是安装 Extension 后注册公开抓手。

## Extensions 目录

Extension 按完整能力纵向组织，不按 Adapter、Tool、Hook、Behavior 等技术名词横向切分。

例如未来的 `shared/browser/` 可以同时包含浏览器连接、可调用能力、运行事件处理和自己的测试；无需把同一能力拆散到四种模块目录。

只有真实能力开始开发时才创建目录和源码。README 可以说明边界，但不再使用空 `index.ts`、空 package 或预留导出伪造进度。

## 公共与产品私有边界

- `shared/`：不认识单一产品界面，并可被至少两条产品线或后台 Runtime 能力复用；不要求三条产品全部启用。
- `cli/`：终端输入、ANSI 渲染、REPL、斜杠命令和 TUI。
- `web/`：HTTP 接入、事件流、路由、页面与受控远程访问。
- `desktop/`：窗口、原生桥接、托盘、快捷键、通知、安装与更新。

产品私有目录不能互相依赖。Web 和 Desktop 共用的聊天界面、状态或组件应进入 `shared/` 下的合适能力目录，Desktop 不直接引用 `web/` 私有实现。

CLI 与 Desktop 需要进程外启动器时，启动器源码可以与该产品的私有 Extension 放在同一能力目录中，但必须保持轻量：只负责 Runtime 拉起、连接和输入输出转发，不能复制状态与 Agent 执行逻辑。

这里的“私有”表示产品归属，不自动构成权限边界。若未来需要限制某项能力只对特定产品可见，再由 Kernel 提供通用作用域机制，而不是硬编码三个产品名。

## Products 目录

`src/products/` 只负责选择 Extension Factory，并允许 Runtime 同时启用一个或多个产品入口：

```ts
const factories = [
  ...sharedExtensions,
  ...product.extensions,
];
```

清单使用 Factory 而不是复用 Extension 实例，避免多个 Kernel 或测试之间共享可变生命周期状态。产品逻辑一律留在对应 Extension 中。

## Package 调整原则

当前单包能够提供最短依赖链和最低维护成本。满足以下真实需求之一时，才将目录提升为独立 package：

- Web 或 Desktop 构建工具无法与 Runtime 共用配置；
- 原生依赖或平台依赖需要单独安装；
- 能力需要独立测试、版本、分发或进程隔离；
- 单包依赖导致实际构建或启动成本无法接受。

拆包只改变物理构建边界，不改变 `products → extensions → kernel` 的依赖方向。

## Supervisor 目录

Supervisor 到 P3 自进化发布闭环时再建立。它必须位于当前 Runtime 发布物之外，才能在新 Kernel 启动失败时切回旧版本，但它不是 Runtime 内部的第三种架构模块。

## 运行数据目录

运行数据不进入源码仓库：

```text
~/.agent/
├── tasks/
├── registry.json
├── extensions/       # 本地安装的扩展
├── releases/         # Installed Releases
├── runtime/
└── config/
```

Project 专属 Agent 数据位于项目根目录的 `.agent/`。候选 worktree 和 Installed Release 由 `~/.agent/` 下的运行数据管理。

## 调整判断

- 新功能默认进入某个 Extension；
- 多个 Extension 需要同一种不可绕过的机制时，才调整 Kernel；
- 两个产品线复用私有代码时，将复用部分提升到 `shared/`；
- 目录需要独立构建或发布时再拆 package；
- 调整后同步文档，但不保留没有实际价值的兼容层。