Agent/gateway/docs/core/lifecycle.md

Lifecycle（生命周期管理）

模块： gateway/core/lifecycle/

文档维护规范

1. 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
2. 文档分层，链接代码 - 关键实现需标注代码文件路径；格式：module/file.py:function_name
3. 简洁快照，日志分离 - 只记录已确认的设计

---

模块职责

Agent 生命周期管理，包括：

• Trace 注册：调用 Agent 框架创建 Trace
• Trace 查询：调用 Agent 框架查询 Trace 信息
• Workspace 管理：确保 Workspace 目录存在和清理
• 配置热重载：监听 Agent 技能配置变化并热重载

说明： Trace 元数据由 Agent 框架管理，Gateway 不维护副本

---

核心概念

Trace

基于 Agent Core 架构（详见 ../../../agent/docs/architecture.md）：

• Trace = Agent 的执行记录
• 每个 Trace 有独立的 Workspace
• Trace 数据结构由 Agent Core 定义

Workspace

• 每个 Trace 有独立的工作目录
• 包含 Agent 的配置、记忆、技能等
• 路径格式：~/.gateway/traces/{trace_id}/workspace/

---

模块结构

gateway/core/lifecycle/
├── trace_manager.py      # Trace 注册和元数据管理
├── workspace_manager.py  # Workspace 管理
└── config_watcher.py     # 配置热重载

---

关键功能

Trace 注册和元数据管理

实现位置： gateway/core/lifecycle/trace_manager.py

职责：

• 注册新的 Trace
• 查询 Trace 元数据
• 更新 Trace 状态

Workspace 管理

实现位置： gateway/core/lifecycle/workspace_manager.py

职责：

• 创建 Trace 的 Workspace
• 获取 Workspace 路径
• 清理 Workspace

配置热重载

实现位置： gateway/core/lifecycle/config_watcher.py

职责：

• 监听配置文件变化
• 热重载配置
• 不影响正在运行的 Trace

---

相关文档

• 需求规划：生命周期管理需求
• 架构设计：模块在整体架构中的位置
• Agent Core 架构：Trace 数据结构定义