Agent/docs/project-structure.md

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 加载：按顺序加载配置，后加载的覆盖先加载的

---

使用方式

加载框架预设

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
)

扩展框架（可选）

# 加载项目特定的自定义 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

---

相关文档

• Sub-Agent 配置 - Sub-Agent 定义格式
• Skills - Skill 使用和编写
• 工具系统 - 工具注册和使用