117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# 规划目录
|
||
|
||
本文描述当前架构下建议采用的源码与运行数据目录。它用于指导项目起步，不是不可修改的目录规范。
|
||
|
||
后续实现或 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 的真实开发过程证明当前结构降低了可理解性或修改效率。
|
||
|
||
目录调整后应同步更新本文，但不需要为保持旧规划而保留无价值的兼容层。
|