# Agent Framework 目录结构

> 框架与应用分层设计

---

## 核心架构

**框架层** (`agent/`): 核心代码、内置预设，可作为独立包发布

**应用层** (项目根目录): 项目特定配置，覆盖或扩展框架

---

## 框架层（`agent/`）

```
agent/
├── core/                       # 核心引擎
│   ├── runner.py               # AgentRunner
│   └── config.py               # AgentConfig, CallResult
├── execution/                  # 执行追踪
│   ├── models.py               # Trace, Step
│   ├── protocols.py            # TraceStore
│   ├── fs_store.py             # FileSystemTraceStore
│   └── tree_dump.py            # 可视化
├── memory/                     # 记忆系统
│   ├── models.py               # Experience, Skill
│   ├── protocols.py            # MemoryStore, StateStore
│   ├── stores.py               # 存储实现
│   └── skill_loader.py         # Skill 加载器（自动加载内置 skills）
├── tools/                      # 工具系统
│   ├── builtin/                # 内置基础工具
│   ├── advanced/               # 高级工具（第三方适配）
│   └── adapters/               # 外部集成
├── llm/                        # LLM 相关
│   ├── gemini.py
│   ├── openrouter.py
│   └── prompts/                # Prompt 工具
├── skills/                     # 框架内置 Skills（自动加载）
│   ├── core.md                 # 核心 skill，每次运行自动加载
│   └── browser_use/            # 浏览器自动化 skill
└── subagents/                  # 内置 Sub-Agent 定义
```

**实现**：
- 核心引擎：`agent/core/runner.py`
- 执行追踪：`agent/execution/`
- 记忆系统：`agent/memory/`（Skills 自动加载）
- 工具系统：`agent/tools/`
- LLM 集成：`agent/llm/`
- Skills：`agent/skills/core.md`（自动加载）+ `agent/skills/browser_use/`（按需加载）
- Sub-Agent 预设：`agent/subagents/`

---

## 应用层（项目根目录）

项目特定配置（可选）：

```
your-project/
├── skills/                     # 项目特定 Skills
├── subagents/                  # 项目特定 Sub-Agents
└── tools/                      # 项目特定工具
```

---

## 加载优先级

| 资源 | 框架预设 | 项目配置 | 优先级 |
|------|---------|---------|--------|
| Skills | `agent/skills/` | `./skills/` | 项目优先（`agent/skills/core.md` 总是自动加载） |
| Sub-Agents | `agent/subagents/` | `./subagents/` | 项目覆盖 |
| Tools | `agent/tools/builtin/` | `./tools/` | 手动注册 |

**实现**：
- Skills 自动加载：`agent/memory/skill_loader.py:load_skills_from_dir()`
  - 总是自动加载 `agent/skills/` 中的所有 skills（包括 `core.md`）
  - 可选加载 `skills_dir` 参数指定的额外自定义 skills
- Skills 工具动态加载：`agent/tools/builtin/skill.py` - 搜索路径 `./skills/` → `./agent/skills/`
- Sub-Agents 加载：按顺序加载配置，后加载的覆盖先加载的

---

## 使用方式

### 加载框架预设

```python
from agent import AgentRunner
from agent.llm import create_gemini_llm_call

# Skills 自动加载
# - agent/skills/core.md 总是自动加载
# - agent/skills/ 中的其他 skills 也会自动加载
runner = AgentRunner(
    llm_call=create_gemini_llm_call(),
    # skills_dir 可选：加载额外的自定义 skills
)
```

### 扩展框架（可选）

```python
# 加载项目特定的自定义 skills
runner = AgentRunner(
    llm_call=create_gemini_llm_call(),
    skills_dir="./skills",  # 额外加载项目自定义 skills
)

# 结果：agent/skills/ + ./skills/ 中的所有 skills 都会被加载
```

**Skills 加载机制**：
- **自动加载**：`agent/skills/` 中的所有 skills（包括 `core.md`）总是自动加载
- **可选加载**：通过 `skills_dir` 参数额外加载项目自定义 skills
- **动态加载**：通过 `skill` 工具运行时按需加载特定 skill

详见 [`SKILLS_SYSTEM.md`](../SKILLS_SYSTEM.md)

---

## 相关文档

- [Sub-Agent 配置](./sub-agents.md) - Sub-Agent 定义格式
- [Skills](./skills.md) - Skill 使用和编写
- [工具系统](./tools.md) - 工具注册和使用