企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 大模型
• 工具调用
• RAG
• 提示工程
• 强化学习

openjiuwen.agent_teams.schema.deep_agent_spec是 openJiuwen（agent-core）中负责团队角色（team role）可序列化声明式规格的模块：它定义了一张"冷构造"蓝图，把模型的连接信息、请求参数、工具、护栏（rail）、子智能体等全部折叠成 JSON 可序列化的 Pydantic 模型，再通过build()/resolve_parts()还原成可运行的DeepAgent。读完本文，你将掌握TeamModelConfig的字段语义与构造原理、DeepAgent 规格树的完整字段清单、能力提供者注册机制，以及它在TeamAgentSpec团队装配流程中的实际落地方式。

一、模块定位：为什么agent_teams.schema.deep_agent_spec是一个"薄再导出层"

从模块源码的模块注释可以确认，openjiuwen/agent_teams/schema/deep_agent_spec.py 是一个为保持团队侧既有导入路径兼容而保留的再导出（re-export）层：

• DeepAgentSpec、RailSpec、BuiltinToolSpec、SubAgentSpec以及它们的叶子类型（TeamModelConfig、WorkspaceSpec、VisionModelSpec、AudioModelSpec、ProgressiveToolSpec、SysOperationSpec等）的真源（source of truth）位于 harness 层：openjiuwen/harness/schema/deep_agent_spec.py。
• 再导出层保证from openjiuwen.agent_teams.schema.deep_agent_spec import DeepAgentSpec与from openjiuwen.harness.schema.deep_agent_spec import DeepAgentSpec拿到的是同一个类对象（is恒等），跨导入路径的恒等判断不受影响。
• 团队拓扑相关的规格（TeamSpec/TeamAgentSpec/ blueprint.py）则保留在agent_teams侧，不参与这次再导出。

openjiuwen/agent_teams/schema/__init__.py进一步汇总了两类规格的公开导出面：团队拓扑类（DeepAgentSpec、LeaderSpec、StorageSpec、TeamAgentSpec、TransportSpec、register_storage、register_transport等来自blueprint）以及本模块再导出的能力规格类（AudioModelSpec、ProgressiveToolSpec、RailSpec、SubAgentSpec、SysOperationSpec、VisionModelSpec、WorkspaceSpec）。

二、TeamModelConfig：团队角色的可序列化模型配置（本文档核心）

TeamModelConfig是本 API 文档页面的主体内容，它的定义与语义如下：

openjiuwen.agent_teams.TeamModelConfig—— 团队角色的可序列化模型配置（Serializable model configuration for a team role）。

属性：

• model_client_config（ModelClientConfig）：模型客户端配置，必填。
• model_request_config（ModelRequestConfig，可选）：模型请求配置，默认None。

在 harness 层源码中，它是这样一个 Pydantic 模型（openjiuwen/harness/schema/deep_agent_spec.py）：

class TeamModelConfig(BaseModel): """Serializable model configuration for a team role.""" model_client_config: ModelClientConfig model_request_config: Optional[ModelRequestConfig] = None def build(self) -> "Model": """Create a Model instance from this config.""" return Model( model_client_config=self.model_client_config, model_config=self.model_request_config, )

两个关键点：

1. build()是配置到运行时的分界线：TeamModelConfig本身是纯数据、可 JSON 序列化；调用build()后才会构造出openjiuwen.core.foundation.llm.Model实例，模型客户端（client_provider）的注册与选择发生在Model内部（详见下文第四节）。
2. ModelSpec是TeamModelConfig的别名：源码中ModelSpec = TeamModelConfig明确注释为"与 harness 命名约定对齐；ModelSpec是给希望使用模型层名称的调用方的规范导入"。两个名字指向同一个类对象，因此is恒等成立。

2.1 在 DeepAgentSpec / SubAgentSpec 中的使用方式

TeamModelConfig不是孤立存在的，它被挂在角色规格的model字段上：

• DeepAgentSpec.model: Optional[TeamModelConfig]，默认为None（此时由团队装配方注入成员级模型，见第六节agent_configurator的ctx.member_model or agent_spec.model回退逻辑）；
• SubAgentSpec.model: Optional[TeamModelConfig]，默认为None；子智能体构建时若self.model为None，则回退到父智能体的模型（build(parent_model=llm_model, ...)中的parent_model参数，openjiuwen/harness/schema/deep_agent_spec.py）。

这保证了"一个团队角色一套模型配置"的声明式表达：只需在规格里写清楚客户端与请求参数，构造流程会负责把它物化为可调用的Model。

三、配置底层的两个数据类：ModelClientConfig 与 ModelRequestConfig

TeamModelConfig的两个属性分别来自openjiuwen.core.foundation.llm。其完整字段定义见 API 文档 docs/en/2.Development Guide/API Docs/openjiuwen.core/foundation/llm/llm.md：

ModelClientConfig（客户端配置数据类）

ModelRequestConfig（单次请求参数配置数据类）

一个典型的TeamModelConfig构造示例（字段取值对齐上述文档）：

from openjiuwen.core.foundation.llm import ModelClientConfig, ModelRequestConfig from openjiuwen.agent_teams.schema.deep_agent_spec import TeamModelConfig team_model = TeamModelConfig( model_client_config=ModelClientConfig( client_id="team_llm", client_provider="OpenAI", api_key="your_api_key", api_base="https://api.openai.com/v1", timeout=60.0, max_retries=3, verify_ssl=True, ), model_request_config=ModelRequestConfig( model_name="your_model_name", temperature=0.7, max_tokens=1024, ), ) model = team_model.build() # -> openjiuwen.core.foundation.llm.Model

四、DeepAgent 规格树：从叶子类型到根规格

除TeamModelConfig外，本模块还再导出了一整套能力叶子类型。以下字段与默认值均取自 openjiuwen/harness/schema/deep_agent_spec.py 的类定义。

4.1 叶子规格（Leaf Spec）

VisionModelSpec（视觉模型配置，对应VisionModelConfigdataclass）：api_key=""、base_url=DEFAULT_OPENAI_BASE_URL、model=DEFAULT_OPENAI_VISION_MODEL、max_retries=3；build()返回VisionModelConfig。

AudioModelSpec（音频模型配置，对应AudioModelConfig）：api_key=""、base_url=DEFAULT_OPENAI_BASE_URL、transcription_model=DEFAULT_OPENAI_AUDIO_TRANSCRIPTION_MODEL、question_answering_model=DEFAULT_OPENAI_AUDIO_QA_MODEL、max_retries=3、http_timeout=DEFAULT_AUDIO_HTTP_TIMEOUT、max_audio_bytes=DEFAULT_MAX_AUDIO_BYTES、acr_access_key=""、acr_access_secret=""、acr_base_url=DEFAULT_ACR_BASE_URL；build()返回AudioModelConfig。

上述默认常量定义于 openjiuwen/harness/schema/config.py：

DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1" DEFAULT_OPENROUTER_VISION_MODEL = "google/gemini-2.5-pro" DEFAULT_OPENAI_VISION_MODEL = "gpt-4.1-mini" DEFAULT_OPENAI_AUDIO_TRANSCRIPTION_MODEL = "gpt-4o-transcribe" DEFAULT_OPENAI_AUDIO_QA_MODEL = "gpt-4o-audio-preview" DEFAULT_ACR_BASE_URL = "https://identify-ap-southeast-1.acrcloud.com/v1/identify" DEFAULT_AUDIO_HTTP_TIMEOUT = 20 DEFAULT_MAX_AUDIO_BYTES = 25 * 1024 * 1024

此外，VisionModelConfig与AudioModelConfig还各自提供from_env()工厂方法，支持从VISION_API_KEY/AUDIO_API_KEY/OPENAI_API_KEY等环境变量一键装配（见 openjiuwen/harness/schema/config.py 与 openjiuwen/harness/schema/config.py）。

WorkspaceSpec（工作区规格）：root_path="./"、language="cn"、stable_base=False。注释明确：stable_base=True（团队成员的默认情形）时工作区根被解析为{repo_root}/.agent_teams/workspaces/，从而在临时 worktree 清理后仍然存活；build()返回Workspace。

ProgressiveToolSpec（渐进式工具暴露配置）：enabled=True、search_limit=5。挂到DeepAgentSpec.progressive_tool上即启用渐进式工具加载；resolve_parts()会将其转换为progressive_tool_enabled与tool_search_limit两个配置（_progressive_tool_kwargs()）。

SysOperationSpec（系统操作规格）：id（必填）、mode=OperationMode.LOCAL、work_config=None、gateway_config=None。resolve()是幂等的 get-or-create：成员的系统操作 id 在会话生命周期内保持稳定，团队暂停后由新消息重建成员 harness 时会重新解析到同一资源（openjiuwen/harness/schema/deep_agent_spec.py）。

4.2 声明式能力引用：RailSpec 与 BuiltinToolSpec

RailSpec与BuiltinToolSpec都是"通过类型名 + 参数声明式引用能力"的规格，结构完全镜像：type: str（必填）+params: dict[str, Any] = {}。

• RailSpec.build()：从_RAIL_PROVIDER_REGISTRY按type取工厂并调用factory(dict(self.params), context)；未知类型（例如旧版本持久化的、当前版本已移除的 rail）只记 warning 并返回None，不影响其余 rail 构建（openjiuwen/harness/schema/deep_agent_spec.py）。
• BuiltinToolSpec.build()：从_TOOL_PROVIDER_REGISTRY取工厂；未知类型抛出ValueError并列出已注册类型清单（openjiuwen/harness/schema/deep_agent_spec.py）。tool_id参数保留给成员级工具 id 命名空间，实际按 agent 限定的 id 在AbilityManager.add_ability注册阶段完成：有状态工具拿到 agent 限定 id，无状态工具共享裸 id。

4.3 能力提供者注册机制

三个模块级注册表由三个注册函数驱动（openjiuwen/harness/schema/deep_agent_spec.py）：

• register_rail_provider(name, factory)：按RailSpec.type引用，工厂签名为factory(params, context)，可返回单个 rail 或 rail 列表；
• register_tool_provider(name, factory)：按BuiltinToolSpec.type引用，签名同上；
• register_subagent_provider(name, factory)：按SubAgentSpec.factory_name引用，工厂签名factory(factory_kwargs, context)，返回SubAgentConfig（或列表）；采用 opt-in 解析——只有factory_name命中注册表时才走工厂路径，既有的 factory 名称不受影响。

注释还强调：内置 rail / tool / sub-agent 同样通过 manifest 目录在这里注册，不再存在单独的类注册表；同一名称的重复注册以后者覆盖前者。构建结果由_as_built_list()归一化为扁平列表并丢弃None，空列表即视为"跳过该能力"。

4.4 SubAgentSpec：子智能体规格

字段清单（openjiuwen/harness/schema/deep_agent_spec.py）：

agent_card: AgentCard（必填）、system_prompt: str（必填）、tools: list[ToolCard | BuiltinToolSpec] = []、mcps: list[McpServerConfig] = []、model: Optional[TeamModelConfig] = None、rails: Optional[list[RailSpec]] = None、skills: Optional[list[str]] = None、workspace: Optional[WorkspaceSpec] = None、sys_operation: Optional[SysOperationSpec] = None、language: Optional[str] = None、prompt_mode: Optional[str] = None、enable_task_loop: bool = False、max_iterations: Optional[int] = None、factory_name: Optional[str] = None、factory_kwargs: dict[str, Any] = {}。

其build(parent_model, language, context)的解析顺序很有代表性（openjiuwen/harness/schema/deep_agent_spec.py）：

1. 若factory_name命中_SUBAGENT_PROVIDER_REGISTRY，直接由工厂构造；
2. 否则依次解析model（回退parent_model）、workspace、rails（逐个RailSpec.build并展平）；
3. sys_operation通过resolve()幂等解析；
4. 工具解析：BuiltinToolSpec以{agent_card.id 或 name}.{type}作为工具 id 前缀构造Tool，ToolCard直接透传；
5. 最后组装为运行时SubAgentConfig。

4.5 DeepAgentSpec：根规格与完整字段

DeepAgentSpec的类注释明确了它的核心契约（openjiuwen/harness/schema/deep_agent_spec.py）：

用于构造 DeepAgent 的完全 JSON 可序列化规格。使用model_dump_json()序列化以便网络分发；使用model_validate_json()反序列化后调用build()即可获得活的DeepAgent实例。

完整字段清单（默认值即源码默认值）：

五、构造流程：build() 与 resolve_parts() 的两段式装配

DeepAgentSpec的构造被拆成两段（openjiuwen/harness/schema/deep_agent_spec.py）：

resolve_parts(context)—— 只解析不实例化。它先解析model（self.model.build()）、语言、视觉/音频配置、工作区，再基于调用方传入（或冷启动时自举）的BuildContext派生一个 per-build 视图（浅拷贝 + 覆盖 workspace / member_card_id，避免污染调用方字段）。随后：

• 把父模型发布到build_ctx.extras["_parent_model"]；
• 提前解析sys_operation并发布到build_ctx.extras["_parent_sys_operation"]（键常量PARENT_SYS_OPERATION_EXTRAS_KEY，见 openjiuwen/harness/schema/build_context.py）——子智能体工厂若拿到父的系统操作，就不会让create_deep_agent新建一个绕过父沙箱的 LOCAL 操作；
• 依次构建 rails、subagents、tools；
• 最后委托给resolve_deep_agent_parts(...)返回DeepAgentParts。NativeHarness直接用这套 parts 做前向构造（不产生一次性模板）；build()则把它物化为全新的DeepAgent。

build(context)—— 物化为活的实例：parts = self.resolve_parts(context)后，agent = DeepAgent(parts.config.card)，再apply_deep_agent_parts(agent, parts)返回。

BuildContext是规格→运行时边界对象。它刻意不是 Pydantic 模型，与TeamRuntimeContext一样永不参与 JSON 序列化（openjiuwen/harness/schema/build_context.py）：字段含language、member_name、role、workspace、member_card_id、project_dir、team_outputs_dir、extras。平台可以子类化它添加类型化句柄，或通过extras逃生舱叠加多个平台。跨序列化边界（spawn 的子进程、分布式远端、冷恢复）时，接收方通过register_build_context_factory/build_context_from_seed从可序列化种子重建活的上下文。

六、在团队装配中的落地：TeamAgentSpec.agents 与 agent_configurator

规格的最终消费方是团队装配。从 blueprint.py 可以看到TeamAgentSpec用agents: dict[str, DeepAgentSpec]按角色键（"leader"/"teammate"，对应TeamRole枚举值）组织每个角色的 DeepAgent 规格，并叠加团队级配置（team_name、lifecycle、evolution_enabled、teammate_mode、spawn_mode、predefined_members、external_cli_agents、tiny_agents、model_pool等）。

装配阶段的关键逻辑在 openjiuwen/agent_teams/agent/agent_configurator.py：

• 模型回退：model_config = ctx.member_model or agent_spec.model——运行时上下文优先，规格兜底；
• 成员化改写：agent_spec.model_copy(update={...})以不可变方式注入card、model、workspace、cwd、project_root、sys_operation、tools、skills等成员级字段，再交给DeepAgentSpec.build(context)走第五节的两段式装配；
• 默认SysOperationSpec在成员侧按{card.id}.sys_operation兜底生成；
• 团队成员的技能读取统一走core.team.skill_use（按成员与团队的可见性声明收窄），因此规格里的skills只作为成员声明的种子 allow-list 进入SkillUseRail参数，而技能发现被刻意关闭。

从源码结构可以推断，这种"声明式规格 + 装配方注入运行上下文"的设计，正是为了让一个TeamAgentSpec可以穿越成员 spawn、进程重启与恢复边界：规格本体始终 JSON 可序列化，活的句柄全部由装配方在build()阶段补齐。

七、实践要点与序列化边界

1. 规格是纯数据，运行句柄留在 build 阶段：DeepAgentSpec/SubAgentSpec/TeamModelConfig以及各叶子类型都是 PydanticBaseModel，可直接model_dump_json()序列化、model_validate_json()反序列化；BuildContext、Model、Workspace等活句柄不应出现在序列化内容中。
2. 模型配置二选一：客户端配置model_client_config必填且api_base不会被自动填充；model_request_config可选，未显式给出时走各字段默认值（temperature=0.95、top_p=0.95）。
3. 能力引用用声明式名称而非类：rail / 内置工具 / 子智能体都通过type（或factory_name）从 provider 注册表解析，未知 rail 类型会被跳过并告警，未知工具类型则直接报错并列出可用类型——迁移升级时需注意旧规格里引用的名称是否仍被注册。
4. 团队成员的model可留空：agent_configurator的ctx.member_model or agent_spec.model回退链保证留空时由运行时上下文注入，适合"模型池统一调度、角色规格只描述能力"的团队编排场景。

八、相关资源

• 本模块再导出实现：openjiuwen/agent_teams/schema/deep_agent_spec.py
• 规格真源与构造逻辑：openjiuwen/harness/schema/deep_agent_spec.py
• 运行时配置数据类与默认常量：openjiuwen/harness/schema/config.py
• 运行时载体与跨边界重建：openjiuwen/harness/schema/build_context.py
• 团队级规格（TeamAgentSpec/LeaderSpec等）：openjiuwen/agent_teams/schema/blueprint.py
• 团队装配消费方：openjiuwen/agent_teams/agent/agent_configurator.py
• ModelClientConfig/ModelRequestConfig完整字段：docs/en/2.Development Guide/API Docs/openjiuwen.core/foundation/llm/llm.md

• 人工智能
• AI Agent
• Agent 框架
• 大模型
• 工具调用
• RAG
• 提示工程
• 强化学习