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

---

模块结构

gateway/core/lifecycle/
├── __init__.py           # 聚合导出（TraceManager、WorkspaceManager 等）
├── errors.py             # LifecycleError、WorkspaceDockerError
├── config_watcher.py     # 配置热重载
├── workspace/
│   ├── manager.py        # WorkspaceManager（目录、引用计数）
│   └── docker_runner.py  # WorkspaceDockerRunner（沙箱容器）
└── trace/
    ├── manager.py        # TraceManager（Agent API 代理与本地登记）
    └── backend.py        # LifecycleTraceBackend（channels.TraceBackend）

---

关键功能

TraceManager

实现位置： gateway/core/lifecycle/trace/manager.py

职责：

• 调用 Agent 框架创建 Trace
• 查询 Trace 信息
• 管理 Trace 和 Workspace 的关联关系

核心接口：

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（Docker 编排见同目录 docker_runner.py）

职责：

• 创建和初始化 Workspace 目录
• 管理 Workspace 引用计数
• 清理无活跃 Trace 的 Workspace

核心接口：

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

核心接口：

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

---

相关文档

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