规划目录

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

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

源码仓库

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 开发、自举发布和版本回退。

运行数据目录

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

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

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

允许调整的判断标准

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

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

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

4.7 KiB Raw Blame History Unescape Escape