instance.py 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245
  1. """
  2. engine.instance — Agent Instance 管理
  3. Agent 是函数定义,Instance 是函数调用。
  4. 一份 agent 代码(模板)可以被不同领域的数据实例化多次。
  5. 目录结构:
  6. agentexample/qaagent67wiki/ ← agent 模板(版本控制)
  7. agent-config.yml
  8. agents/, skills/, scripts/
  9. /data/instances/maritime/ ← 实例数据(不版本控制)
  10. instance.yml ← 覆盖配置(指向 agent 模板 + 路径覆盖)
  11. wiki/ ← 累积知识
  12. knowledge/ ← 原始文件 + 索引
  13. workspace/ ← per-run 数据
  14. 用法:
  15. config = load_instance("/data/instances/maritime/instance.yml")
  16. # config = agent-config.yml 的内容,被 instance.yml 覆盖后的合并结果
  17. # 或从 agent_dir + instance_dir 分别指定:
  18. config = load_instance_from_dirs(
  19. agent_dir="agentexample/qaagent67wiki",
  20. instance_dir="/data/instances/maritime",
  21. )
  22. """
  23. from __future__ import annotations
  24. import copy
  25. import os
  26. import time
  27. from typing import Any, Dict, Optional
  28. import yaml
  29. def _deep_merge(base: dict, override: dict) -> dict:
  30. """
  31. 深度合并两个 dict。override 的值覆盖 base 的值。
  32. 嵌套 dict 递归合并,非 dict 值直接覆盖。
  33. """
  34. result = copy.deepcopy(base)
  35. for key, val in override.items():
  36. if key in result and isinstance(result[key], dict) and isinstance(val, dict):
  37. result[key] = _deep_merge(result[key], val)
  38. else:
  39. result[key] = copy.deepcopy(val)
  40. return result
  41. def load_instance(instance_path: str) -> Dict[str, Any]:
  42. """
  43. 从 instance.yml 加载合并后的配置。
  44. instance.yml 必须包含 `agent` 字段指向 agent 模板目录。
  45. 其余字段深度合并覆盖 agent-config.yml。
  46. Args:
  47. instance_path: instance.yml 的路径
  48. Returns:
  49. 合并后的完整配置 dict,额外包含:
  50. _agent_dir: agent 模板目录绝对路径
  51. _instance_dir: 实例数据目录绝对路径
  52. """
  53. instance_dir = os.path.dirname(os.path.abspath(instance_path))
  54. with open(instance_path, "r", encoding="utf-8") as f:
  55. instance_cfg = yaml.safe_load(f) or {}
  56. # agent 字段: 指向 agent 模板
  57. agent_ref = instance_cfg.pop("agent", None)
  58. if not agent_ref:
  59. raise ValueError(f"instance.yml must have 'agent' field: {instance_path}")
  60. # 解析 agent 模板目录
  61. agent_dir = _resolve_agent_dir(agent_ref, instance_dir)
  62. agent_config_path = os.path.join(agent_dir, "agent-config.yml")
  63. if not os.path.isfile(agent_config_path):
  64. raise FileNotFoundError(
  65. f"Agent template not found: {agent_config_path} "
  66. f"(referenced by agent: {agent_ref})"
  67. )
  68. with open(agent_config_path, "r", encoding="utf-8") as f:
  69. agent_cfg = yaml.safe_load(f) or {}
  70. # 从 instance_cfg 中剥离元数据字段
  71. instance_name = instance_cfg.pop("name", "")
  72. instance_cfg.pop("description", "")
  73. # 深度合并: agent_cfg 为 base, instance_cfg 为 override
  74. merged = _deep_merge(agent_cfg, instance_cfg)
  75. # 注入元数据
  76. merged["_agent_dir"] = agent_dir
  77. merged["_instance_dir"] = instance_dir
  78. if instance_name:
  79. merged["_instance_name"] = instance_name
  80. return merged
  81. def load_instance_from_dirs(
  82. agent_dir: str,
  83. instance_dir: str,
  84. ) -> Dict[str, Any]:
  85. """
  86. 从分别指定的 agent_dir 和 instance_dir 加载合并配置。
  87. 如果 instance_dir 下有 instance.yml,用它覆盖 agent-config.yml。
  88. 如果没有 instance.yml,直接使用 agent-config.yml。
  89. Args:
  90. agent_dir: agent 模板目录
  91. instance_dir: 实例数据目录
  92. Returns:
  93. 合并后的配置 dict
  94. """
  95. agent_dir = os.path.abspath(agent_dir)
  96. instance_dir = os.path.abspath(instance_dir)
  97. agent_config_path = os.path.join(agent_dir, "agent-config.yml")
  98. if not os.path.isfile(agent_config_path):
  99. raise FileNotFoundError(f"Agent config not found: {agent_config_path}")
  100. with open(agent_config_path, "r", encoding="utf-8") as f:
  101. agent_cfg = yaml.safe_load(f) or {}
  102. # 尝试加载 instance.yml
  103. instance_config_path = os.path.join(instance_dir, "instance.yml")
  104. if os.path.isfile(instance_config_path):
  105. with open(instance_config_path, "r", encoding="utf-8") as f:
  106. instance_cfg = yaml.safe_load(f) or {}
  107. # 剥离元数据
  108. instance_cfg.pop("agent", None)
  109. instance_name = instance_cfg.pop("name", "")
  110. instance_cfg.pop("description", "")
  111. merged = _deep_merge(agent_cfg, instance_cfg)
  112. if instance_name:
  113. merged["_instance_name"] = instance_name
  114. else:
  115. merged = agent_cfg
  116. merged["_agent_dir"] = agent_dir
  117. merged["_instance_dir"] = instance_dir
  118. return merged
  119. def create_instance(
  120. instance_dir: str,
  121. agent_ref: str,
  122. name: str = "",
  123. overrides: Dict[str, Any] | None = None,
  124. ) -> str:
  125. """
  126. 创建新的 agent 实例。
  127. 在 instance_dir 下创建:
  128. instance.yml
  129. wiki/
  130. knowledge/raw/
  131. knowledge/processed/
  132. workspace/
  133. Args:
  134. instance_dir: 实例目录路径
  135. agent_ref: agent 模板引用(目录名或路径)
  136. name: 实例名称
  137. overrides: 额外配置覆盖
  138. Returns:
  139. instance.yml 的路径
  140. """
  141. os.makedirs(instance_dir, exist_ok=True)
  142. os.makedirs(os.path.join(instance_dir, "wiki"), exist_ok=True)
  143. os.makedirs(os.path.join(instance_dir, "knowledge", "raw"), exist_ok=True)
  144. os.makedirs(os.path.join(instance_dir, "knowledge", "processed"), exist_ok=True)
  145. os.makedirs(os.path.join(instance_dir, "workspace"), exist_ok=True)
  146. instance_cfg = {
  147. "agent": agent_ref,
  148. "name": name or os.path.basename(instance_dir),
  149. }
  150. # 自动生成路径覆盖
  151. abs_dir = os.path.abspath(instance_dir)
  152. instance_cfg["knowledge"] = {
  153. "baseDir": os.path.join(abs_dir, "knowledge"),
  154. "rawDir": os.path.join(abs_dir, "knowledge", "raw"),
  155. "processedDir": os.path.join(abs_dir, "knowledge", "processed"),
  156. "indexFile": os.path.join(abs_dir, "knowledge", "rag_index.json"),
  157. "keywordFile": os.path.join(abs_dir, "knowledge", "rag_index.keywords.json"),
  158. }
  159. instance_cfg["wiki"] = {
  160. "dir": os.path.join(abs_dir, "wiki"),
  161. "relationsFile": os.path.join(abs_dir, "wiki", "relations.json"),
  162. }
  163. if overrides:
  164. instance_cfg = _deep_merge(instance_cfg, overrides)
  165. instance_path = os.path.join(instance_dir, "instance.yml")
  166. with open(instance_path, "w", encoding="utf-8") as f:
  167. yaml.dump(instance_cfg, f, allow_unicode=True, default_flow_style=False)
  168. return instance_path
  169. def _resolve_agent_dir(agent_ref: str, instance_dir: str) -> str:
  170. """
  171. 解析 agent 引用为绝对目录路径。
  172. 支持:
  173. "qaagent67wiki" → 在 agentexample/ 下查找
  174. "../agentexample/qaagent67wiki" → 相对于 instance_dir 解析
  175. "/abs/path/to/agent" → 绝对路径
  176. """
  177. # 绝对路径
  178. if os.path.isabs(agent_ref):
  179. return agent_ref
  180. # 相对于 instance_dir
  181. relative = os.path.join(instance_dir, agent_ref)
  182. if os.path.isdir(relative):
  183. return os.path.abspath(relative)
  184. # 在常见位置查找
  185. search_paths = [
  186. os.path.join(instance_dir, "..", "..", "agentexample", agent_ref),
  187. os.path.join(os.getcwd(), "agentexample", agent_ref),
  188. os.path.join(os.path.dirname(__file__), "..", "..", "agentexample", agent_ref),
  189. ]
  190. for path in search_paths:
  191. if os.path.isdir(path):
  192. return os.path.abspath(path)
  193. raise FileNotFoundError(
  194. f"Cannot resolve agent template '{agent_ref}'. "
  195. f"Searched: {instance_dir}, agentexample/"
  196. )