| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245 |
- """
- engine.instance — Agent Instance 管理
- Agent 是函数定义,Instance 是函数调用。
- 一份 agent 代码(模板)可以被不同领域的数据实例化多次。
- 目录结构:
- agentexample/qaagent67wiki/ ← agent 模板(版本控制)
- agent-config.yml
- agents/, skills/, scripts/
- /data/instances/maritime/ ← 实例数据(不版本控制)
- instance.yml ← 覆盖配置(指向 agent 模板 + 路径覆盖)
- wiki/ ← 累积知识
- knowledge/ ← 原始文件 + 索引
- workspace/ ← per-run 数据
- 用法:
- config = load_instance("/data/instances/maritime/instance.yml")
- # config = agent-config.yml 的内容,被 instance.yml 覆盖后的合并结果
- # 或从 agent_dir + instance_dir 分别指定:
- config = load_instance_from_dirs(
- agent_dir="agentexample/qaagent67wiki",
- instance_dir="/data/instances/maritime",
- )
- """
- from __future__ import annotations
- import copy
- import os
- import time
- from typing import Any, Dict, Optional
- import yaml
- def _deep_merge(base: dict, override: dict) -> dict:
- """
- 深度合并两个 dict。override 的值覆盖 base 的值。
- 嵌套 dict 递归合并,非 dict 值直接覆盖。
- """
- result = copy.deepcopy(base)
- for key, val in override.items():
- if key in result and isinstance(result[key], dict) and isinstance(val, dict):
- result[key] = _deep_merge(result[key], val)
- else:
- result[key] = copy.deepcopy(val)
- return result
- def load_instance(instance_path: str) -> Dict[str, Any]:
- """
- 从 instance.yml 加载合并后的配置。
- instance.yml 必须包含 `agent` 字段指向 agent 模板目录。
- 其余字段深度合并覆盖 agent-config.yml。
- Args:
- instance_path: instance.yml 的路径
- Returns:
- 合并后的完整配置 dict,额外包含:
- _agent_dir: agent 模板目录绝对路径
- _instance_dir: 实例数据目录绝对路径
- """
- instance_dir = os.path.dirname(os.path.abspath(instance_path))
- with open(instance_path, "r", encoding="utf-8") as f:
- instance_cfg = yaml.safe_load(f) or {}
- # agent 字段: 指向 agent 模板
- agent_ref = instance_cfg.pop("agent", None)
- if not agent_ref:
- raise ValueError(f"instance.yml must have 'agent' field: {instance_path}")
- # 解析 agent 模板目录
- agent_dir = _resolve_agent_dir(agent_ref, instance_dir)
- agent_config_path = os.path.join(agent_dir, "agent-config.yml")
- if not os.path.isfile(agent_config_path):
- raise FileNotFoundError(
- f"Agent template not found: {agent_config_path} "
- f"(referenced by agent: {agent_ref})"
- )
- with open(agent_config_path, "r", encoding="utf-8") as f:
- agent_cfg = yaml.safe_load(f) or {}
- # 从 instance_cfg 中剥离元数据字段
- instance_name = instance_cfg.pop("name", "")
- instance_cfg.pop("description", "")
- # 深度合并: agent_cfg 为 base, instance_cfg 为 override
- merged = _deep_merge(agent_cfg, instance_cfg)
- # 注入元数据
- merged["_agent_dir"] = agent_dir
- merged["_instance_dir"] = instance_dir
- if instance_name:
- merged["_instance_name"] = instance_name
- return merged
- def load_instance_from_dirs(
- agent_dir: str,
- instance_dir: str,
- ) -> Dict[str, Any]:
- """
- 从分别指定的 agent_dir 和 instance_dir 加载合并配置。
- 如果 instance_dir 下有 instance.yml,用它覆盖 agent-config.yml。
- 如果没有 instance.yml,直接使用 agent-config.yml。
- Args:
- agent_dir: agent 模板目录
- instance_dir: 实例数据目录
- Returns:
- 合并后的配置 dict
- """
- agent_dir = os.path.abspath(agent_dir)
- instance_dir = os.path.abspath(instance_dir)
- agent_config_path = os.path.join(agent_dir, "agent-config.yml")
- if not os.path.isfile(agent_config_path):
- raise FileNotFoundError(f"Agent config not found: {agent_config_path}")
- with open(agent_config_path, "r", encoding="utf-8") as f:
- agent_cfg = yaml.safe_load(f) or {}
- # 尝试加载 instance.yml
- instance_config_path = os.path.join(instance_dir, "instance.yml")
- if os.path.isfile(instance_config_path):
- with open(instance_config_path, "r", encoding="utf-8") as f:
- instance_cfg = yaml.safe_load(f) or {}
- # 剥离元数据
- instance_cfg.pop("agent", None)
- instance_name = instance_cfg.pop("name", "")
- instance_cfg.pop("description", "")
- merged = _deep_merge(agent_cfg, instance_cfg)
- if instance_name:
- merged["_instance_name"] = instance_name
- else:
- merged = agent_cfg
- merged["_agent_dir"] = agent_dir
- merged["_instance_dir"] = instance_dir
- return merged
- def create_instance(
- instance_dir: str,
- agent_ref: str,
- name: str = "",
- overrides: Dict[str, Any] | None = None,
- ) -> str:
- """
- 创建新的 agent 实例。
- 在 instance_dir 下创建:
- instance.yml
- wiki/
- knowledge/raw/
- knowledge/processed/
- workspace/
- Args:
- instance_dir: 实例目录路径
- agent_ref: agent 模板引用(目录名或路径)
- name: 实例名称
- overrides: 额外配置覆盖
- Returns:
- instance.yml 的路径
- """
- os.makedirs(instance_dir, exist_ok=True)
- os.makedirs(os.path.join(instance_dir, "wiki"), exist_ok=True)
- os.makedirs(os.path.join(instance_dir, "knowledge", "raw"), exist_ok=True)
- os.makedirs(os.path.join(instance_dir, "knowledge", "processed"), exist_ok=True)
- os.makedirs(os.path.join(instance_dir, "workspace"), exist_ok=True)
- instance_cfg = {
- "agent": agent_ref,
- "name": name or os.path.basename(instance_dir),
- }
- # 自动生成路径覆盖
- abs_dir = os.path.abspath(instance_dir)
- instance_cfg["knowledge"] = {
- "baseDir": os.path.join(abs_dir, "knowledge"),
- "rawDir": os.path.join(abs_dir, "knowledge", "raw"),
- "processedDir": os.path.join(abs_dir, "knowledge", "processed"),
- "indexFile": os.path.join(abs_dir, "knowledge", "rag_index.json"),
- "keywordFile": os.path.join(abs_dir, "knowledge", "rag_index.keywords.json"),
- }
- instance_cfg["wiki"] = {
- "dir": os.path.join(abs_dir, "wiki"),
- "relationsFile": os.path.join(abs_dir, "wiki", "relations.json"),
- }
- if overrides:
- instance_cfg = _deep_merge(instance_cfg, overrides)
- instance_path = os.path.join(instance_dir, "instance.yml")
- with open(instance_path, "w", encoding="utf-8") as f:
- yaml.dump(instance_cfg, f, allow_unicode=True, default_flow_style=False)
- return instance_path
- def _resolve_agent_dir(agent_ref: str, instance_dir: str) -> str:
- """
- 解析 agent 引用为绝对目录路径。
- 支持:
- "qaagent67wiki" → 在 agentexample/ 下查找
- "../agentexample/qaagent67wiki" → 相对于 instance_dir 解析
- "/abs/path/to/agent" → 绝对路径
- """
- # 绝对路径
- if os.path.isabs(agent_ref):
- return agent_ref
- # 相对于 instance_dir
- relative = os.path.join(instance_dir, agent_ref)
- if os.path.isdir(relative):
- return os.path.abspath(relative)
- # 在常见位置查找
- search_paths = [
- os.path.join(instance_dir, "..", "..", "agentexample", agent_ref),
- os.path.join(os.getcwd(), "agentexample", agent_ref),
- os.path.join(os.path.dirname(__file__), "..", "..", "agentexample", agent_ref),
- ]
- for path in search_paths:
- if os.path.isdir(path):
- return os.path.abspath(path)
- raise FileNotFoundError(
- f"Cannot resolve agent template '{agent_ref}'. "
- f"Searched: {instance_dir}, agentexample/"
- )
|