# Lifecycle（生命周期管理）

**模块：** `gateway/core/lifecycle/`

## 文档维护规范

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

---

## 模块职责

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 可以共享一个 Workspace（主 Agent 和子 Agent）
- 包含 Agent 的配置、记忆、技能等
- 路径格式：`~/.gateway/workspaces/{workspace_id}/`
- 需要引用计数机制，确保清理时无活跃 Trace

---

## 模块结构

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

---

## 关键功能

### TraceManager

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

**职责：**
- 调用 Agent 框架创建 Trace
- 查询 Trace 信息
- 管理 Trace 和 Workspace 的关联关系

**核心接口：**

```python
class TraceManager:
    def create_trace(
        self,
        workspace_id: str,
        agent_type: str,  # "personal_assistant" | "digital_employee"
        metadata: dict = None
    ) -> str:
        """创建新 Trace，返回 trace_id"""
        pass

    def get_trace(self, trace_id: str) -> dict:
        """查询 Trace 信息（调用 Agent 框架）"""
        pass

    def list_traces(
        self,
        workspace_id: str = None,
        agent_type: str = None
    ) -> list[dict]:
        """查询 Trace 列表"""
        pass

    def get_workspace_id(self, trace_id: str) -> str:
        """获取 Trace 对应的 workspace_id"""
        pass
```

### WorkspaceManager

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

**职责：**
- 创建和初始化 Workspace 目录
- 管理 Workspace 引用计数
- 清理无活跃 Trace 的 Workspace

**核心接口：**

```python
class WorkspaceManager:
    def create_workspace(self, workspace_id: str) -> str:
        """创建 Workspace 目录，返回路径"""
        pass

    def get_workspace_path(self, workspace_id: str) -> str:
        """获取 Workspace 路径"""
        pass

    def add_trace_ref(self, workspace_id: str, trace_id: str):
        """增加 Trace 引用"""
        pass

    def remove_trace_ref(self, workspace_id: str, trace_id: str):
        """移除 Trace 引用"""
        pass

    def cleanup_workspace(self, workspace_id: str, force: bool = False):
        """清理 Workspace（检查引用计数，force=True 强制清理）"""
        pass

    def list_workspaces(self) -> list[dict]:
        """列出所有 Workspace 及其引用计数"""
        pass
```

### ConfigWatcher

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

**职责：**
- 监听 Agent 技能配置文件变化
- 触发热重载回调
- 不影响正在运行的 Trace

**核心接口：**

```python
class ConfigWatcher:
    def watch(self, workspace_id: str, callback: callable):
        """监听指定 Workspace 的配置变化"""
        pass

    def stop_watch(self, workspace_id: str):
        """停止监听"""
        pass
```

---

## 典型流程

### 个人助理型 Agent 首次对话

1. 用户通过飞书发送消息
2. Routing 模块收到消息，查询是否有对应 Trace
3. 无 Trace → 调用 `TraceManager.create_trace(workspace_id=user_id, agent_type="personal_assistant")`
4. TraceManager 调用 Agent 框架创建 Trace，返回 trace_id
5. 调用 `WorkspaceManager.create_workspace(workspace_id=user_id)`（如果不存在）
6. 调用 `WorkspaceManager.add_trace_ref(workspace_id=user_id, trace_id=trace_id)`
7. 开始对话

### 数字员工型 Agent 串行处理

1. 用户 A 发送消息
2. Routing 模块查询数字员工的 Trace（共享 workspace_id）
3. 如果无 Trace → 创建（同上）
4. 如果有 Trace 且正在处理 → 消息进入队列
5. 当前对话结束 → 从队列取下一条消息

### 主 Agent 调用子 Agent

1. 主 Agent 执行过程中需要调用子 Agent
2. 调用 `TraceManager.create_trace(workspace_id=主Agent的workspace_id, agent_type=...)`
3. 子 Trace 共享主 Trace 的 Workspace
4. 调用 `WorkspaceManager.add_trace_ref(workspace_id, 子trace_id)`
5. 子 Agent 执行完成 → `WorkspaceManager.remove_trace_ref(...)`

### Workspace 清理

1. Trace 结束时调用 `WorkspaceManager.remove_trace_ref(...)`
2. WorkspaceManager 检查引用计数
3. 引用计数为 0 → 可以清理（可选延迟清理策略）
4. 删除 Workspace 目录

---

## 错误处理

### Trace 创建失败

- Agent 框架返回错误 → 向用户返回友好错误信息
- Workspace 创建失败 → 清理已创建的 Trace，返回错误

### Workspace 引用计数不一致

- 定期检查 Workspace 引用计数和实际 Trace 状态
- 发现不一致 → 记录日志，修正引用计数

### 配置热重载失败

- 配置文件格式错误 → 记录日志，保持旧配置
- 不影响正在运行的 Trace

### 并发安全

- TraceManager 和 WorkspaceManager 的关键操作需要加锁
- 避免多个请求同时创建相同 workspace_id 的 Workspace

---

## 相关文档

- [需求规划](../requirements.md)：生命周期管理需求
- [架构设计](../architecture.md)：模块在整体架构中的位置
- [Agent Core 架构](../../../agent/docs/architecture.md)：Trace 数据结构定义