UFO 配置架构深入解析模块化 YAML、类型安全访问与 Galaxy 多设备协同配置指南【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本篇技术指南以 UFO 开源仓库中的 配置架构总览文档 为核心系统讲解其现代模块化配置系统的设计哲学、加载算法、类型系统、环境覆盖机制以及 Galaxy 星座系统的配置模型。读完本文你将掌握从传统单体config.yaml平滑迁移到config/ufo/与config/galaxy/模块化结构的完整方法理解优先级链与深合并的具体行为并能在 IDE 中获得类型安全的配置访问体验。设计哲学为可维护性而生的现代配置系统UFO 的配置系统遵循专业软件工程的四个核心原则这些原则在 config/config_loader.py 的模块文档字符串中得到了逐一印证关注点分离Separation of Concerns配置按领域domain而非单体文件组织每个配置文件只负责一类关注点全部位于config/ufo/目录下Agent 配置agents.yaml所有 Agent 的 LLM 设置 → Agent Configuration 指南系统配置system.yaml执行与运行时设置 → System Configuration 指南RAG 配置rag.yaml知识检索设置 → RAG Configuration 指南MCP 配置mcp.yamlModel Context Protocol 服务器 → MCP Configuration 指南定价配置prices.yaml不同模型的成本追踪 → Pricing Configuration 指南第三方配置third_party.yaml外部 Agent 集成LinuxAgent、HardwareAgent→ Third-Party Configuration 指南类型安全 灵活性Type Safety Flexibility配置访问采用固定类型字段 动态 YAML 字段的混合方案两者兼顾# 类型安全访问推荐 config get_ufo_config() max_step config.system.max_step # IDE 自动补全 api_model config.app_agent.api_model # 动态访问用于自定义字段 custom_value config.CUSTOM_FEATURE_FLAG new_setting config[NEW_YAML_KEY] # 向后兼容旧代码仍然可用 max_step_old config[MAX_STEP]从 config/config_schemas.py 的SystemConfig、AgentConfig等 dataclass 可以看到固定字段被声明为带默认值的类型化属性如max_step: int 50、temperature: float 0.0而所有未识别的 YAML 键会被归入_extras字典通过__getattr__与__getitem__实现动态访问。向后兼容Backward Compatibility零破坏性变更现有代码无需任何修改即可继续工作旧的配置路径仍受支持ufo/config/旧的访问模式仍可用config[MAX_STEP]自动迁移警告引导用户迁移到新结构在ConfigLoader中LEGACY_PATH_MAP显式建立了新旧路径的映射关系config/ufo → ufo/config而 Galaxy 因为没有旧版路径被映射为None。加载时若新旧配置同时存在新路径优先旧值填充缺失键若只有旧路径则发出迁移警告。自动发现Auto-Discovery无需手工注册配置文件config/ufo/下所有*.yaml文件自动加载文件通过深合并deep merging智能合并支持环境特定覆盖*_dev.yaml、*_test.yaml、*_prod.yaml_discover_yaml_files方法会遍历目录下所有.yaml文件并排除以_dev、_test、_prod结尾的环境变体它们由UFO_ENV单独触发加载随后按排序顺序合并保证加载顺序一致、结果可复现。目录结构总览UFO/ ├── config/ ← 新配置根目录推荐 │ ├── ufo/ ← UFO² 配置 │ │ ├── agents.yaml # LLM Agent 设置 │ │ ├── agents.yaml.template # 安装用模板 │ │ ├── system.yaml # 系统与运行时设置 │ │ ├── rag.yaml # RAG 知识设置 │ │ ├── mcp.yaml # MCP 服务器配置 │ │ ├── prices.yaml # 模型定价 │ │ └── third_party.yaml # 第三方 Agent可选 │ │ │ ├── galaxy/ ← Galaxy 配置 │ │ ├── agent.yaml # 星座 Agent 设置 │ │ ├── agent.yaml.template # 安装用模板 │ │ ├── constellation.yaml # 星座运行时设置 │ │ └── devices.yaml # 设备/客户端配置 │ │ │ ├── config_loader.py # 现代配置加载器 │ └── config_schemas.py # 类型定义 │ └── ufo/config/ ← 旧路径仍受支持 └── config.yaml # 旧的单体配置Galaxy 星座系统的配置文件Galaxy 星座系统在config/galaxy/下拥有自己的一套配置文件文件用途模板文档constellation.yaml星座运行时设置心跳、并发、步数上限无Galaxy Constellation 配置devices.yaml设备 Agent 定义device_id、server_url、能力、元数据无Galaxy Devices 配置agent.yaml星座 Agent 的 LLM 配置API 设置、提示词有.templateGalaxy Agent 配置Galaxy 配置结构详解config/galaxy/ ├── constellation.yaml # Orchestrator 运行时设置 │ ├── CONSTELLATION_ID # 星座标识符 │ ├── HEARTBEAT_INTERVAL # 健康检查频率秒 │ ├── RECONNECT_DELAY # 重连延迟秒 │ ├── MAX_CONCURRENT_TASKS # 任务并发上限 │ ├── MAX_STEP # 每会话步数上限 │ ├── DEVICE_INFO # devices.yaml 的路径 │ └── LOG_TO_MARKDOWN # Markdown 日志标志 │ ├── devices.yaml # 设备定义 │ └── devices: [] # 设备配置数组 │ ├── device_id # 唯一设备标识符 │ ├── server_url # WebSocket 端点 │ ├── os # 操作系统 │ ├── capabilities # 设备能力 │ ├── metadata # 自定义元数据 │ ├── max_retries # 连接重试上限 │ └── auto_connect # 自动连接标志 │ └── agent.yaml # 星座 Agent LLM 配置 └── CONSTELLATION_AGENT: ├── REASONING_MODEL # 启用推理模式 ├── API_TYPE # API 提供商openai、aoai、azure_ad ├── API_BASE # API 基础 URL ├── API_KEY # API 认证密钥 ├── API_VERSION # API 版本 ├── API_MODEL # 模型名称/部署名 ├── AAD_* # Azure AD 认证设置 └── *_PROMPT # 提示词模板路径仓库中的实际文件 config/galaxy/constellation.yaml 给出了这些字段的默认值HEARTBEAT_INTERVAL: 30.0、RECONNECT_DELAY: 5.0、MAX_CONCURRENT_TASKS: 6、MAX_STEP: 15。而 config/galaxy/devices.yaml 则展示了设备定义的真实形态——每个设备通过server_url如ws://localhost:5001/ws建立 WebSocket 连接capabilities描述其能力如servermetadata可携带任意自定义键值日志路径、性能档位、运维工程师联系方式等max_retries与auto_connect控制连接行为。config/galaxy/agent.yaml.template 中CONSTELLATION_AGENT还额外声明了四个提示词路径字段分别指向星座创建/编辑的 share 提示词与 example 提示词。Galaxy 配置加载# 加载 Galaxy 配置 from config.config_loader import get_galaxy_config # 加载 Galaxy 配置包含 agent 与 constellation 设置 galaxy_config get_galaxy_config() # 访问 Agent 配置LLM 设置 agent_config galaxy_config.agent.constellation_agent # 访问星座运行时设置 constellation_settings galaxy_config.constellation # 或使用原始字典访问以保持向后兼容 constellation_id galaxy_config[CONSTELLATION_ID]Galaxy 与 UFO 配置的区别UFO 配置config/ufo/单 Agent 自动化设置Galaxy 配置config/galaxy/多设备星座设置两套系统可在同一项目中共存从 config/config_schemas.py 看GalaxyConfig内部由GalaxyAgentConfig包装CONSTELLATION_AGENT的类型化 AgentConfig与ConstellationRuntimeConfig星座运行时固定字段两个类型化模块加上_raw原始字典组成与 UFO 的UFOConfighost_agent、app_agent、backup_agent、evaluation_agent、operator、rag、system 七大类型化模块 _raw形成对称的设计。配置加载过程优先级链Priority Chain配置系统遵循明确的优先级链从高到低新模块化配置-config/{module}/*.yaml旧单体配置-{module}/config/config.yaml环境变量- 运行时覆盖当同一设置存在于多个位置时新模块化配置优先于旧配置。各来源按序合并后加载的来源覆盖先加载的来源。这里需要特别说明在load_ufo_config的实现中环境变量首先作为基础字典最低优先级随后 YAML 配置新路径优先、旧路径兜底通过update覆盖到其上因此 YAML 中的显式配置会覆盖同名环境变量但 YAML 中未设置的键仍可从环境中读取。加载算法ConfigLoader.load_ufo_config与load_galaxy_config的核心流程可概括如下load_galaxy_config无旧路径兜底其余一致def load_config(): # Step 1: 以环境变量为起点最低优先级 config_data dict(os.environ) # Step 2: 若旧配置存在则加载中间优先级 if exists(ufo/config/config.yaml): legacy_data load_yaml(ufo/config/config.yaml) merge(config_data, legacy_data) # Step 3: 加载新模块化配置最高优先级 for yaml_file in discover(config/ufo/*.yaml): new_data load_yaml(yaml_file) merge(config_data, new_data) # Step 4: 创建类型化配置对象 return UFOConfig.from_dict(config_data)此外_load_module_configs对mcp.yaml和agent_mcp.yaml有特殊处理它们会被整体嵌套到mcp键下便于统一访问。_load_with_fallback则完整实现了四分支逻辑新旧都存在时合并并警告CONFIG CONFLICT DETECTED只有新路径时静默使用理想情况只有旧路径时使用并警告LEGACY CONFIG PATH DETECTED两者都不存在时抛出FileNotFoundError并给出期望路径提示。深合并Deep Merging配置文件被递归合并允许将配置拆分到多个文件而无需重复# config/ufo/agents.yaml HOST_AGENT: API_TYPE: openai API_MODEL: gpt-4o # config/ufo/custom.yaml稍后添加 HOST_AGENT: TEMPERATURE: 0.5 # 追加到 HOST_AGENT # 结果HOST_AGENT 包含全部三个字段后加载文件中的字段被追加而非替换到先加载的配置中。_deep_merge的实现要点是当键在目标中已存在且两侧值均为字典时递归合并否则直接覆盖。这意味着顶层标量如API_TYPE会被覆盖而嵌套字典会被逐层合并。文件组织模式按领域拆分当前方案config/ufo/ ├── agents.yaml # 所有 Agent 的 LLM 配置 ├── system.yaml # 所有系统设置 ├── rag.yaml # 所有 RAG 设置 ├── mcp.yaml # 所有 MCP 服务器 └── prices.yaml # 模型定价优点相关设置易于查找关注点分离清晰便于撰写文档。备选方案按 Agent 拆分config/ufo/ ├── host_agent.yaml # HOST_AGENT 配置 ├── app_agent.yaml # APP_AGENT 配置 ├── system.yaml # 共享系统配置 └── rag.yaml # 共享 RAG 配置优点Agent 特定设置相互隔离便于按 Agent 定制适合多 Agent 场景。两种模式均可正常工作加载器会自动发现并合并所有 YAML 文件。这一保证建立在_discover_yaml_files对目录的全量扫描之上无论文件如何命名都会被合并进同一份配置。环境特定覆盖Environment-Specific Overrides支持开发、测试、生产环境# 基础配置 config/ufo/agents.yaml # 所有环境 # 环境特定覆盖 config/ufo/agents_dev.yaml # 仅开发环境 config/ufo/agents_test.yaml # 仅测试环境 config/ufo/agents_prod.yaml # 仅生产环境激活方式# 设置环境 export UFO_ENVdev # Linux/Mac $env:UFO_ENV dev # Windows PowerShell # 配置加载顺序 # 1. agents.yaml基础 # 2. agents_dev.yaml覆盖实现上ConfigLoader.__init__通过os.getenv(UFO_ENV, production)读取环境_load_module_configs在env非空且不等于production时为每个基础文件查找{stem}_{env}.yaml并深合并。也就是说production是默认环境只有显式设置其他环境值才会触发覆盖文件加载。类型系统固定类型推荐提供 IDE 自动补全与类型安全dataclass class SystemConfig: max_step: int 50 max_retry: int 20 temperature: float 0.0 # ... # 使用——IDE 知道类型 config.system.max_step # int config.system.temperature # float仓库中的 config/config_schemas.py 将该设计贯彻到底SystemConfig拥有从max_tokens、control_backend、safe_guard、log_level到use_mcp、output_presenter的数十个带默认值的固定字段RAGConfig则定义了离线文档、在线搜索、经验、演示四条 RAG 通道各自的开关与topk参数。这些默认值与 config/ufo/system.yaml、config/ufo/rag.yaml 中的实际配置一一对应。动态类型灵活用于自定义或实验性设置。关于添加自定义字段的更多内容见 Extending Configuration 指南。# 在 YAML 中 MY_CUSTOM_FEATURE: True NEW_EXPERIMENTAL_SETTING: value # 在代码中——动态访问 if config.MY_CUSTOM_FEATURE: setting config.NEW_EXPERIMENTAL_SETTING注意UFOConfig.from_dict会先把每个 YAML 键对照known_mappings映射为类型化字段未匹配的键全部落入_extrasUFOConfig与GalaxyConfig本身还保留_raw原始字典任何未建模的键都可经由config.KEY属性访问或config[KEY]字典访问字典值会被自动包装为DynamicConfig以支持嵌套访问。混合方案Hybrid Approach两者兼得class SystemConfig: # 固定字段 max_step: int 50 # 动态扩展 _extras: Dict[str, Any] def __getattr__(self, name): # 未知字段尝试从 extras 获取 return self._extras.get(name)迁移警告Migration Warnings使用旧路径时系统会给出明确警告⚠️ LEGACY CONFIG PATH DETECTED: UFO Using legacy config: ufo/config/ Please migrate to: config/ufo/ Quick migration: mkdir -p config/ufo cp ufo/config/*.yaml config/ufo/ Or use migration tool: python -m ufo.tools.migrate_config这些警告每个会话只出现一次_warnings_shown集合去重引导用户迁移到新结构。官方还提供自动化迁移工具python -m ufo.tools.migrate_config支持--backup --validate选项详见 Configuration Migration Guide。最佳实践推荐实践使用模块化文件- 按领域或按 Agent 拆分使用类型化访问- 优先config.system.max_step而非config[MAX_STEP]提供模板- 为敏感数据提供.template文件如 agents.yaml.template记录自定义字段- 在 YAML 中写注释使用环境覆盖- 区分开发/测试/生产差异应避免的反模式新旧混用- 完整迁移到新结构把密钥写进 YAML- 改用环境变量加载器支持${VAR}占位符展开见_expand_env_vars未设置的变量会原样保留重复设置- 善用深合并破坏向后兼容- 保持config[OLD_KEY]可用硬编码路径- 使用配置系统配置生命周期Configuration Lifecycle流程中的Apply Transformations对应_apply_legacy_transforms它为HOST_AGENT、APP_AGENT、BACKUP_AGENT、EVALUATION_AGENT、CONSTELLATION_AGENT按API_TYPE补全 API Base URLaoai自动拼接/openai/deployments/{deployment}/chat/completions?api-version...openai默认补为https://api.openai.com/v1/chat/completions并将字符串形式的CONTROL_BACKEND规范化为列表。缓存则通过get_ufo_config()/get_galaxy_config()的模块级全局变量与ConfigLoader单例共同实现调用clear_config_cache()可清空缓存便于测试或热重载。后续深入阅读UFO 配置指南Agent Configuration - 所有 Agent 的 LLM 与 API 设置System Configuration - 运行时与执行设置RAG Configuration - 知识检索与学习设置MCP Configuration - Model Context Protocol 服务器Pricing Configuration - LLM 成本追踪Third-Party Configuration - 外部 Agent 集成LinuxAgent、HardwareAgentMigration Guide - 从旧配置迁移到新配置Extending Configuration - 如何添加新配置项Galaxy 配置指南Galaxy Constellation Configuration - 星座编排器的运行时设置Galaxy Devices Configuration - 设备定义与能力Galaxy Agent Configuration - 星座 Agent 的 LLM 配置API 参考配置类与方法的详细 API 文档见以下核心实现config.config_loader.ConfigLoader- 配置加载与缓存单例 全局缓存config.config_schemas.UFOConfig- UFO 配置模式七大类类型化模块 动态访问config.config_schemas.GalaxyConfig- Galaxy 配置模式agent constellation 类型化模块 动态访问config.config_loader.get_ufo_config()- 获取 UFO 配置实例reloadTrue可强制重载config.config_loader.get_galaxy_config()- 获取 Galaxy 配置实例实际使用中UFO 的各 Agent如 ufo/agents/agent/host_agent.py、ufo/agents/agent/app_agent.py均通过get_ufo_config()获取配置再以config.system.max_step、config.app_agent.api_model等类型化方式读取参数Galaxy 星座侧则在 orchestrator 等模块中通过get_galaxy_config()读取运行时参数与设备清单。这套一份配置、三种访问方式类型化 / 动态 / 字典兼容的设计让 UFO 能够在保持向后兼容的同时为多 Agent、多设备的规模化编排提供可持续演进的配置基础设施。【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 UFO 配置架构深入解析：模块化 YAML、类型安全访问与 Galaxy 多设备协同配置指南
UFO 配置架构深入解析模块化 YAML、类型安全访问与 Galaxy 多设备协同配置指南【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本篇技术指南以 UFO 开源仓库中的 配置架构总览文档 为核心系统讲解其现代模块化配置系统的设计哲学、加载算法、类型系统、环境覆盖机制以及 Galaxy 星座系统的配置模型。读完本文你将掌握从传统单体config.yaml平滑迁移到config/ufo/与config/galaxy/模块化结构的完整方法理解优先级链与深合并的具体行为并能在 IDE 中获得类型安全的配置访问体验。设计哲学为可维护性而生的现代配置系统UFO 的配置系统遵循专业软件工程的四个核心原则这些原则在 config/config_loader.py 的模块文档字符串中得到了逐一印证关注点分离Separation of Concerns配置按领域domain而非单体文件组织每个配置文件只负责一类关注点全部位于config/ufo/目录下Agent 配置agents.yaml所有 Agent 的 LLM 设置 → Agent Configuration 指南系统配置system.yaml执行与运行时设置 → System Configuration 指南RAG 配置rag.yaml知识检索设置 → RAG Configuration 指南MCP 配置mcp.yamlModel Context Protocol 服务器 → MCP Configuration 指南定价配置prices.yaml不同模型的成本追踪 → Pricing Configuration 指南第三方配置third_party.yaml外部 Agent 集成LinuxAgent、HardwareAgent→ Third-Party Configuration 指南类型安全 灵活性Type Safety Flexibility配置访问采用固定类型字段 动态 YAML 字段的混合方案两者兼顾# 类型安全访问推荐 config get_ufo_config() max_step config.system.max_step # IDE 自动补全 api_model config.app_agent.api_model # 动态访问用于自定义字段 custom_value config.CUSTOM_FEATURE_FLAG new_setting config[NEW_YAML_KEY] # 向后兼容旧代码仍然可用 max_step_old config[MAX_STEP]从 config/config_schemas.py 的SystemConfig、AgentConfig等 dataclass 可以看到固定字段被声明为带默认值的类型化属性如max_step: int 50、temperature: float 0.0而所有未识别的 YAML 键会被归入_extras字典通过__getattr__与__getitem__实现动态访问。向后兼容Backward Compatibility零破坏性变更现有代码无需任何修改即可继续工作旧的配置路径仍受支持ufo/config/旧的访问模式仍可用config[MAX_STEP]自动迁移警告引导用户迁移到新结构在ConfigLoader中LEGACY_PATH_MAP显式建立了新旧路径的映射关系config/ufo → ufo/config而 Galaxy 因为没有旧版路径被映射为None。加载时若新旧配置同时存在新路径优先旧值填充缺失键若只有旧路径则发出迁移警告。自动发现Auto-Discovery无需手工注册配置文件config/ufo/下所有*.yaml文件自动加载文件通过深合并deep merging智能合并支持环境特定覆盖*_dev.yaml、*_test.yaml、*_prod.yaml_discover_yaml_files方法会遍历目录下所有.yaml文件并排除以_dev、_test、_prod结尾的环境变体它们由UFO_ENV单独触发加载随后按排序顺序合并保证加载顺序一致、结果可复现。目录结构总览UFO/ ├── config/ ← 新配置根目录推荐 │ ├── ufo/ ← UFO² 配置 │ │ ├── agents.yaml # LLM Agent 设置 │ │ ├── agents.yaml.template # 安装用模板 │ │ ├── system.yaml # 系统与运行时设置 │ │ ├── rag.yaml # RAG 知识设置 │ │ ├── mcp.yaml # MCP 服务器配置 │ │ ├── prices.yaml # 模型定价 │ │ └── third_party.yaml # 第三方 Agent可选 │ │ │ ├── galaxy/ ← Galaxy 配置 │ │ ├── agent.yaml # 星座 Agent 设置 │ │ ├── agent.yaml.template # 安装用模板 │ │ ├── constellation.yaml # 星座运行时设置 │ │ └── devices.yaml # 设备/客户端配置 │ │ │ ├── config_loader.py # 现代配置加载器 │ └── config_schemas.py # 类型定义 │ └── ufo/config/ ← 旧路径仍受支持 └── config.yaml # 旧的单体配置Galaxy 星座系统的配置文件Galaxy 星座系统在config/galaxy/下拥有自己的一套配置文件文件用途模板文档constellation.yaml星座运行时设置心跳、并发、步数上限无Galaxy Constellation 配置devices.yaml设备 Agent 定义device_id、server_url、能力、元数据无Galaxy Devices 配置agent.yaml星座 Agent 的 LLM 配置API 设置、提示词有.templateGalaxy Agent 配置Galaxy 配置结构详解config/galaxy/ ├── constellation.yaml # Orchestrator 运行时设置 │ ├── CONSTELLATION_ID # 星座标识符 │ ├── HEARTBEAT_INTERVAL # 健康检查频率秒 │ ├── RECONNECT_DELAY # 重连延迟秒 │ ├── MAX_CONCURRENT_TASKS # 任务并发上限 │ ├── MAX_STEP # 每会话步数上限 │ ├── DEVICE_INFO # devices.yaml 的路径 │ └── LOG_TO_MARKDOWN # Markdown 日志标志 │ ├── devices.yaml # 设备定义 │ └── devices: [] # 设备配置数组 │ ├── device_id # 唯一设备标识符 │ ├── server_url # WebSocket 端点 │ ├── os # 操作系统 │ ├── capabilities # 设备能力 │ ├── metadata # 自定义元数据 │ ├── max_retries # 连接重试上限 │ └── auto_connect # 自动连接标志 │ └── agent.yaml # 星座 Agent LLM 配置 └── CONSTELLATION_AGENT: ├── REASONING_MODEL # 启用推理模式 ├── API_TYPE # API 提供商openai、aoai、azure_ad ├── API_BASE # API 基础 URL ├── API_KEY # API 认证密钥 ├── API_VERSION # API 版本 ├── API_MODEL # 模型名称/部署名 ├── AAD_* # Azure AD 认证设置 └── *_PROMPT # 提示词模板路径仓库中的实际文件 config/galaxy/constellation.yaml 给出了这些字段的默认值HEARTBEAT_INTERVAL: 30.0、RECONNECT_DELAY: 5.0、MAX_CONCURRENT_TASKS: 6、MAX_STEP: 15。而 config/galaxy/devices.yaml 则展示了设备定义的真实形态——每个设备通过server_url如ws://localhost:5001/ws建立 WebSocket 连接capabilities描述其能力如servermetadata可携带任意自定义键值日志路径、性能档位、运维工程师联系方式等max_retries与auto_connect控制连接行为。config/galaxy/agent.yaml.template 中CONSTELLATION_AGENT还额外声明了四个提示词路径字段分别指向星座创建/编辑的 share 提示词与 example 提示词。Galaxy 配置加载# 加载 Galaxy 配置 from config.config_loader import get_galaxy_config # 加载 Galaxy 配置包含 agent 与 constellation 设置 galaxy_config get_galaxy_config() # 访问 Agent 配置LLM 设置 agent_config galaxy_config.agent.constellation_agent # 访问星座运行时设置 constellation_settings galaxy_config.constellation # 或使用原始字典访问以保持向后兼容 constellation_id galaxy_config[CONSTELLATION_ID]Galaxy 与 UFO 配置的区别UFO 配置config/ufo/单 Agent 自动化设置Galaxy 配置config/galaxy/多设备星座设置两套系统可在同一项目中共存从 config/config_schemas.py 看GalaxyConfig内部由GalaxyAgentConfig包装CONSTELLATION_AGENT的类型化 AgentConfig与ConstellationRuntimeConfig星座运行时固定字段两个类型化模块加上_raw原始字典组成与 UFO 的UFOConfighost_agent、app_agent、backup_agent、evaluation_agent、operator、rag、system 七大类型化模块 _raw形成对称的设计。配置加载过程优先级链Priority Chain配置系统遵循明确的优先级链从高到低新模块化配置-config/{module}/*.yaml旧单体配置-{module}/config/config.yaml环境变量- 运行时覆盖当同一设置存在于多个位置时新模块化配置优先于旧配置。各来源按序合并后加载的来源覆盖先加载的来源。这里需要特别说明在load_ufo_config的实现中环境变量首先作为基础字典最低优先级随后 YAML 配置新路径优先、旧路径兜底通过update覆盖到其上因此 YAML 中的显式配置会覆盖同名环境变量但 YAML 中未设置的键仍可从环境中读取。加载算法ConfigLoader.load_ufo_config与load_galaxy_config的核心流程可概括如下load_galaxy_config无旧路径兜底其余一致def load_config(): # Step 1: 以环境变量为起点最低优先级 config_data dict(os.environ) # Step 2: 若旧配置存在则加载中间优先级 if exists(ufo/config/config.yaml): legacy_data load_yaml(ufo/config/config.yaml) merge(config_data, legacy_data) # Step 3: 加载新模块化配置最高优先级 for yaml_file in discover(config/ufo/*.yaml): new_data load_yaml(yaml_file) merge(config_data, new_data) # Step 4: 创建类型化配置对象 return UFOConfig.from_dict(config_data)此外_load_module_configs对mcp.yaml和agent_mcp.yaml有特殊处理它们会被整体嵌套到mcp键下便于统一访问。_load_with_fallback则完整实现了四分支逻辑新旧都存在时合并并警告CONFIG CONFLICT DETECTED只有新路径时静默使用理想情况只有旧路径时使用并警告LEGACY CONFIG PATH DETECTED两者都不存在时抛出FileNotFoundError并给出期望路径提示。深合并Deep Merging配置文件被递归合并允许将配置拆分到多个文件而无需重复# config/ufo/agents.yaml HOST_AGENT: API_TYPE: openai API_MODEL: gpt-4o # config/ufo/custom.yaml稍后添加 HOST_AGENT: TEMPERATURE: 0.5 # 追加到 HOST_AGENT # 结果HOST_AGENT 包含全部三个字段后加载文件中的字段被追加而非替换到先加载的配置中。_deep_merge的实现要点是当键在目标中已存在且两侧值均为字典时递归合并否则直接覆盖。这意味着顶层标量如API_TYPE会被覆盖而嵌套字典会被逐层合并。文件组织模式按领域拆分当前方案config/ufo/ ├── agents.yaml # 所有 Agent 的 LLM 配置 ├── system.yaml # 所有系统设置 ├── rag.yaml # 所有 RAG 设置 ├── mcp.yaml # 所有 MCP 服务器 └── prices.yaml # 模型定价优点相关设置易于查找关注点分离清晰便于撰写文档。备选方案按 Agent 拆分config/ufo/ ├── host_agent.yaml # HOST_AGENT 配置 ├── app_agent.yaml # APP_AGENT 配置 ├── system.yaml # 共享系统配置 └── rag.yaml # 共享 RAG 配置优点Agent 特定设置相互隔离便于按 Agent 定制适合多 Agent 场景。两种模式均可正常工作加载器会自动发现并合并所有 YAML 文件。这一保证建立在_discover_yaml_files对目录的全量扫描之上无论文件如何命名都会被合并进同一份配置。环境特定覆盖Environment-Specific Overrides支持开发、测试、生产环境# 基础配置 config/ufo/agents.yaml # 所有环境 # 环境特定覆盖 config/ufo/agents_dev.yaml # 仅开发环境 config/ufo/agents_test.yaml # 仅测试环境 config/ufo/agents_prod.yaml # 仅生产环境激活方式# 设置环境 export UFO_ENVdev # Linux/Mac $env:UFO_ENV dev # Windows PowerShell # 配置加载顺序 # 1. agents.yaml基础 # 2. agents_dev.yaml覆盖实现上ConfigLoader.__init__通过os.getenv(UFO_ENV, production)读取环境_load_module_configs在env非空且不等于production时为每个基础文件查找{stem}_{env}.yaml并深合并。也就是说production是默认环境只有显式设置其他环境值才会触发覆盖文件加载。类型系统固定类型推荐提供 IDE 自动补全与类型安全dataclass class SystemConfig: max_step: int 50 max_retry: int 20 temperature: float 0.0 # ... # 使用——IDE 知道类型 config.system.max_step # int config.system.temperature # float仓库中的 config/config_schemas.py 将该设计贯彻到底SystemConfig拥有从max_tokens、control_backend、safe_guard、log_level到use_mcp、output_presenter的数十个带默认值的固定字段RAGConfig则定义了离线文档、在线搜索、经验、演示四条 RAG 通道各自的开关与topk参数。这些默认值与 config/ufo/system.yaml、config/ufo/rag.yaml 中的实际配置一一对应。动态类型灵活用于自定义或实验性设置。关于添加自定义字段的更多内容见 Extending Configuration 指南。# 在 YAML 中 MY_CUSTOM_FEATURE: True NEW_EXPERIMENTAL_SETTING: value # 在代码中——动态访问 if config.MY_CUSTOM_FEATURE: setting config.NEW_EXPERIMENTAL_SETTING注意UFOConfig.from_dict会先把每个 YAML 键对照known_mappings映射为类型化字段未匹配的键全部落入_extrasUFOConfig与GalaxyConfig本身还保留_raw原始字典任何未建模的键都可经由config.KEY属性访问或config[KEY]字典访问字典值会被自动包装为DynamicConfig以支持嵌套访问。混合方案Hybrid Approach两者兼得class SystemConfig: # 固定字段 max_step: int 50 # 动态扩展 _extras: Dict[str, Any] def __getattr__(self, name): # 未知字段尝试从 extras 获取 return self._extras.get(name)迁移警告Migration Warnings使用旧路径时系统会给出明确警告⚠️ LEGACY CONFIG PATH DETECTED: UFO Using legacy config: ufo/config/ Please migrate to: config/ufo/ Quick migration: mkdir -p config/ufo cp ufo/config/*.yaml config/ufo/ Or use migration tool: python -m ufo.tools.migrate_config这些警告每个会话只出现一次_warnings_shown集合去重引导用户迁移到新结构。官方还提供自动化迁移工具python -m ufo.tools.migrate_config支持--backup --validate选项详见 Configuration Migration Guide。最佳实践推荐实践使用模块化文件- 按领域或按 Agent 拆分使用类型化访问- 优先config.system.max_step而非config[MAX_STEP]提供模板- 为敏感数据提供.template文件如 agents.yaml.template记录自定义字段- 在 YAML 中写注释使用环境覆盖- 区分开发/测试/生产差异应避免的反模式新旧混用- 完整迁移到新结构把密钥写进 YAML- 改用环境变量加载器支持${VAR}占位符展开见_expand_env_vars未设置的变量会原样保留重复设置- 善用深合并破坏向后兼容- 保持config[OLD_KEY]可用硬编码路径- 使用配置系统配置生命周期Configuration Lifecycle流程中的Apply Transformations对应_apply_legacy_transforms它为HOST_AGENT、APP_AGENT、BACKUP_AGENT、EVALUATION_AGENT、CONSTELLATION_AGENT按API_TYPE补全 API Base URLaoai自动拼接/openai/deployments/{deployment}/chat/completions?api-version...openai默认补为https://api.openai.com/v1/chat/completions并将字符串形式的CONTROL_BACKEND规范化为列表。缓存则通过get_ufo_config()/get_galaxy_config()的模块级全局变量与ConfigLoader单例共同实现调用clear_config_cache()可清空缓存便于测试或热重载。后续深入阅读UFO 配置指南Agent Configuration - 所有 Agent 的 LLM 与 API 设置System Configuration - 运行时与执行设置RAG Configuration - 知识检索与学习设置MCP Configuration - Model Context Protocol 服务器Pricing Configuration - LLM 成本追踪Third-Party Configuration - 外部 Agent 集成LinuxAgent、HardwareAgentMigration Guide - 从旧配置迁移到新配置Extending Configuration - 如何添加新配置项Galaxy 配置指南Galaxy Constellation Configuration - 星座编排器的运行时设置Galaxy Devices Configuration - 设备定义与能力Galaxy Agent Configuration - 星座 Agent 的 LLM 配置API 参考配置类与方法的详细 API 文档见以下核心实现config.config_loader.ConfigLoader- 配置加载与缓存单例 全局缓存config.config_schemas.UFOConfig- UFO 配置模式七大类类型化模块 动态访问config.config_schemas.GalaxyConfig- Galaxy 配置模式agent constellation 类型化模块 动态访问config.config_loader.get_ufo_config()- 获取 UFO 配置实例reloadTrue可强制重载config.config_loader.get_galaxy_config()- 获取 Galaxy 配置实例实际使用中UFO 的各 Agent如 ufo/agents/agent/host_agent.py、ufo/agents/agent/app_agent.py均通过get_ufo_config()获取配置再以config.system.max_step、config.app_agent.api_model等类型化方式读取参数Galaxy 星座侧则在 orchestrator 等模块中通过get_galaxy_config()读取运行时参数与设备清单。这套一份配置、三种访问方式类型化 / 动态 / 字典兼容的设计让 UFO 能够在保持向后兼容的同时为多 Agent、多设备的规模化编排提供可持续演进的配置基础设施。【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考