# 规划目录

本文描述当前架构下建议采用的源码与运行数据目录。它用于指导项目起步，不是不可修改的目录规范。

后续实现或 System Evolution 过程中，如果真实依赖、代码规模或开发体验证明某个划分不合理，可以移动、合并或拆分目录；调整时应优先保持职责和依赖方向，而不是机械维持路径兼容。

## 源码仓库

```text
llm-to-agent/
├── apps/
│   ├── runtime/          # Runtime Host / composition root
│   ├── supervisor/       # 启动、版本切换、健康检查、回退
│   ├── cli/              # REPL、非交互 CLI、TUI
│   ├── web/              # Web 客户端
│   └── desktop/          # Desktop Host 与原生桥接
│
├── packages/
│   ├── kernel/           # Microkernel
│   ├── application/      # Application Runtime
│   └── client/           # 客户端共享的 Runtime Client
│
├── extensions/           # 第一方扩展，按完整能力纵向划分
│   ├── deepseek/
│   ├── workspace/
│   ├── shell/
│   ├── git/
│   └── .../
│
├── docs/
│   ├── architecture.md
│   ├── directory-plan.md
│   ├── roadmap.md
│   └── features/
│
├── tests/
│   └── e2e/              # 跨包、自举和版本切换测试
│
├── tooling/              # 构建、发布、开发辅助
│
├── package.json
├── tsconfig.json
└── workspace.yaml
```

## 架构对应关系

| 架构职责 | 规划目录 |
| --- | --- |
| Launcher / Supervisor | `apps/supervisor/` |
| Runtime Host | `apps/runtime/` |
| Application Runtime | `packages/application/` |
| Microkernel | `packages/kernel/` |
| Extensions | `extensions/` |
| Runtime Client | `packages/client/` |
| CLI / Web / Desktop | `apps/cli/`、`apps/web/`、`apps/desktop/` |

## 目录原则

### Apps 是进程和产品入口

`apps/runtime/` 负责创建组件、安装扩展并开启本地连接，不承载 Space、Conversation、Tool 或 Agent Behavior 的具体实现。

CLI、Web、Desktop 通过同一个 Runtime Client 工作，不各自复制 Agent、存储和执行逻辑。

### Packages 固定核心依赖边界

- `kernel/` 只包含 Run Context、Behavior 调度、Tool Gateway、Hook Pipeline、Run Event、流式输出、取消和错误边界。
- `application/` 承载 Project/Task、Conversation、Message、Run Record、Repository、Profile 以及 Command/Query 等产品领域。
- `client/` 承载三个客户端共用的 Command、Query、Event Stream 和连接逻辑。

不建立泛化的 `shared/` 或 `types/` 大杂烩。类型应尽量由拥有该概念的模块导出，只有真正跨客户端传输的协议进入 `client/`。

### Extensions 按完整能力纵向划分

扩展不按 Adapter、Tool、Hook、Behavior 等技术类型横向拆目录，而是按能力组织。例如 `browser/` 可以同时包含浏览器 Adapter、相关 Tools、操作 Hook 和 Browser Behavior。

第一版不要求每个扩展都是独立 package。只有在依赖、测试、复用、版本或独立发布需求出现后，才将它提升为单独 workspace package。

### 功能文档不映射源码目录

`docs/features/` 按产品大功能组织，源码按职责和依赖组织，两者不要求一一对应。

例如 System Evolution 会同时涉及 Application Runtime、Git 扩展、Runtime Host、Supervisor 和 CLI，不应为了与功能文档对齐而把所有代码放入单个目录。

### 测试就近放置

单元测试和模块测试与所属源码放在一起。顶层 `tests/e2e/` 只保存真正跨包、跨进程或跨版本的场景，例如 CLI 到 Runtime、Project 开发、自举发布和版本回退。

## 运行数据目录

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

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

Project 专属 Agent 数据位于项目根目录的 `.agent/`。候选 worktree 和 Installed Release 由 `~/.agent/` 下的运行数据管理，不作为源码仓库中的固定目录。

## 允许调整的判断标准

满足以下任一情况时，可以调整目录：

- 一个目录长期承载了多个不相关职责；
- 一项完整能力被迫跨越过多技术分类目录；
- 模块需要独立测试、复用、加载、版本或发布；
- 现有依赖方向导致循环依赖或核心反向依赖具体功能；
- System Evolution 的真实开发过程证明当前结构降低了可理解性或修改效率。

目录调整后应同步更新本文，但不需要为保持旧规划而保留无价值的兼容层。