ChatDev 配置 Schema API 契约深度解析:基于 Breadcrumb 的动态配置元数据接口
ChatDev 配置 Schema API 契约深度解析:基于 Breadcrumb 的动态配置元数据接口
导读
本文围绕 ChatDev(DevAll)中 /api/config/schema 与 /api/config/schema/validate 两个动态配置 Schema 接口展开,系统讲解它们如何通过 breadcrumbs(路径面包屑)按需暴露 DesignConfig → GraphConfig → NodeConfig 等配置树的字段定义、约束与校验结果。读完本文,你将掌握该契约的请求/响应结构、Breadcrumb 导航规则、CLI 调试命令以及前端"无硬编码"表单渲染的完整调用范式,并理解其底层由 FIELD_SPECS、CHILD_ROUTES 与 Schema 注册表驱动的实现原理。
1. 契约要解决什么问题
ChatDev 的工作流配置采用树形分层结构:根节点 DesignConfig 下挂 graph,graph 下挂 nodes/edges/memory,节点又按 type 判别字段(如 model、python、agent)下钻到不同子类。如果前端表单或 IDE/CLI 把每一层的字段定义都硬编码,配置结构一旦扩展(新增节点类型、工具类型),客户端就要同步发版。
该契约的核心思路是:Schema 由服务端根据当前所处的配置节点动态生成,客户端只描述"我现在在哪一层、要下钻哪个字段"(即 breadcrumbs),服务端据此返回对应的字段元数据。正如文档末尾所言,搭配 FIELD_SPECS 使用,可在前端/IDE 构建无需硬编码的配置体验。其实现分布在 配置 Schema 路由、Schema 导出器、配置基类与字段规格 以及 Schema 注册表 等模块中。
2. 接口总览
| 方法 | 作用 |
|---|---|
POST /api/config/schema |
根据 breadcrumbs 返回对应配置节点的字段定义。 |
POST /api/config/schema/validate |
校验一份 YAML/JSON 文档,并可回传局部 Schema。 |
两个端点定义在 server/config_schema_router.py 中,路由前缀为 /api/config。服务端使用 Pydantic 模型约束请求体:SchemaRequest 仅包含可选的 breadcrumbs 字段,SchemaValidateRequest 在此基础上增加必填的 document 字符串字段。
class SchemaRequest(BaseModel):
breadcrumbs: List[Mapping[str, Any]] | None = Field(
default=None,
description="Breadcrumb path starting from DesignConfig, e.g. [{\"node\":\"DesignConfig\",\"field\":\"graph\"}]",
)
class SchemaValidateRequest(SchemaRequest):
document: str = Field(..., description="Full YAML/JSON content")
3. 请求体:Breadcrumb 公共字段
3.1 请求体示例
{
"breadcrumbs": [
{"node": "DesignConfig", "field": "graph"},
{"node": "GraphConfig", "field": "nodes"},
{"node": "NodeConfig", "value": "model"}
]
}
字段语义如下:
node(必填):当前所处的类名(如DesignConfig、GraphConfig、NodeConfig)。field(可选):要下钻的子字段名;缺省表示仅断言仍在该node。value(可选):当子类由判别字段决定时填写(如节点type)。值与 YAML 中保持一致。index(可选 int):预留用于列表遍历,当前以field/value为主。
3.2 服务端解析:Breadcrumb 数据类
在 Schema 导出器 中,每个 breadcrumb 会被转换为冻结的 Breadcrumb 数据类:
@dataclass(frozen=True)
class Breadcrumb:
node: str
field: str | None = None
value: Any | None = None
@classmethod
def from_mapping(cls, data):
node = str(data.get("node")) if data.get("node") else ""
if not node:
raise SchemaResolutionError("breadcrumb entry missing 'node'")
...
index = data.get("index")
if index is not None and not isinstance(index, int):
raise SchemaResolutionError("breadcrumb 'index' must be integer when provided")
可见服务端对请求体有严格校验:缺少 node 会直接抛出 SchemaResolutionError(最终映射为 HTTP 422);index 若提供则必须是整数。to_json() 方法只在存在 field/value 时才序列化对应键,保证回显的 breadcrumbs 紧凑一致。
4. /api/config/schema:按需获取字段定义
4.1 响应示例
{
"schemaVersion": "0.1.0",
"node": "NodeConfig",
"fields": [
{"name": "id", "typeHint": "str", "required": true, "description": "Unique node identifier"},
{"name": "type", "typeHint": "str", "required": true,
"enum": ["model","python","agent"],
"enumOptions": [{"value":"model","label":"LLM Node","description":"Runs provider-backed models"}]
}
],
"constraints": [...],
"breadcrumbs": [...],
"cacheKey": "f90d..."
}
fields:序列化的ConfigFieldSpec;若有子配置,会包含childRoutes。constraints:由collect_schema()生成的互斥/组合约束。cacheKey:基于{node, breadcrumbs}的 SHA-1,可用于客户端缓存。
4.2 字段元数据的真实形状
ConfigFieldSpec 定义于 entity/configs/base.py,其 to_json() 序列化输出比文档示例更完整,实际响应中每个字段可能包含:
| 键 | 含义 | 说明 |
|---|---|---|
name |
字段名 | 如 id、log_level |
displayName |
展示名 | 缺省回退为 name |
type |
类型提示 | 如 str、bool、enum:LogLevel、list[Node]、dict[str, Any] |
required |
是否必填 | 布尔值 |
advance |
是否高级字段 | 前端可据此决定是否折叠显示 |
default |
默认值 | 存在时才序列化 |
enum / enumOptions |
枚举值与富元数据 | EnumOption 含 value、label、description |
description |
字段说明 | 供 UI 展示与提示 |
childNode |
子配置类名 | 字段存在 child 时输出 |
以 GraphDefinition 的 FIELD_SPECS 为例,log_level 字段实际声明了 type_hint="enum:LogLevel"、默认值 DEBUG、完整枚举列表以及通过 enum_options_for(LogLevel) 生成的富元数据;nodes 字段声明 type_hint="list[Node]" 且 child=Node。这些声明就是 Schema API 输出的数据来源。
4.3 childRoutes:下钻的路由提示
当某个字段能导航到子配置时,导出器会扫描 CHILD_ROUTES 并附加 childRoutes:
routes = [
{
"childKey": key.to_json(),
"childNode": target.__name__,
}
for key, target in config_cls.child_routes().items()
if key.field == name
]
childRoutes 中的 childKey(字段 + 可选判别值)与 childNode(子配置类名)共同告诉前端"下钻这个字段后我会进入哪个配置节点"。前端 formUtils.js 与 DynamicFormField.vue 正是依据 field.childRoutes 是否非空来决定是否渲染"展开子配置"的入口。
4.4 字段排序与 cacheKey
导出器会先输出必填字段、再输出可选字段(保持各自相对顺序),保证表单把必填项放在前面:
def _ordered_field_names(specs):
required_names = [name for name, spec in items if getattr(spec, "required", False)]
optional_names = [name for name, spec in items if not getattr(spec, "required", False)]
return required_names + optional_names
cacheKey 由 _hash_payload 计算:对 {"node": ..., "breadcrumbs": [...]} 做排序键 JSON 序列化后取 SHA-1 摘要(utils/schema_exporter.py)。客户端可用它做精确缓存:只要 node 与 breadcrumbs 未变,schema 响应必然一致。
5. /api/config/schema/validate:文档校验与局部 Schema 回传
5.1 请求体
请求体在 breadcrumbs 旁加入 document:
{
"breadcrumbs": [{"node": "DesignConfig"}],
"document": "name: demo\nversion: 0.4.0\nworkflow:\n nodes: []\n edges: []\n"
}
5.2 三种响应形态
校验通过:
{ "valid": true, "schema": { ... } }
配置错误(后端 ConfigError):
{
"valid": false,
"error": "field 'nodes' must not be empty",
"path": ["workflow","nodes"],
"schema": { ... }
}
YAML 解析失败:HTTP 400,payload { "message": "invalid_yaml", "error": "..." }。
5.3 服务端实现原理
路由处理器 validate_document 的执行链路清晰可循(server/config_schema_router.py):
- 先用
yaml.safe_load解析document,捕获yaml.YAMLError并返回 HTTP 400 +invalid_yaml; - 校验解析结果必须是 Mapping,否则返回 HTTP 422
document_root_not_mapping; - 调用
load_design_from_mapping(parsed)走完整配置加载管线,捕获ConfigError后返回valid=false,同时带上exc.path(配置错误路径)与回传的局部 Schema; - 全部通过则返回
valid=true与schema。
其中 error 中的 path 由配置解析层的 extend_path 与 ConfigError 联动产生(entity/configs/base.py),例如 workflow.nodes[2].type 这样的点路径,前端可直接据此把错误定位到具体表单字段。需要说明的是,示例中的错误文案 field 'nodes' must not be empty 属于该端点的通用错误形态演示,实际错误消息由各配置类的 from_dict / validate 抛出的 ConfigError 决定(如重复节点 id、边引用了未知节点等,见 GraphDefinition.validate)。
6. Breadcrumb 导航原理与使用提示
6.1 使用提示(文档要点)
- 起点:
{ "node": "DesignConfig" }。 - 每一步的
node必须与当前位置的类匹配,否则返回 422。 - 用
field进入子配置(graph → nodes → config 等)。 - 判别式子类(如节点
type、toolingtype)需填写value。 - 不可导航的字段会返回
field '<name>' on <node> is not navigable。
6.2 底层解析逻辑
_resolve_config_class 是 breadcrumbs 导航的核心(utils/schema_exporter.py):
for crumb in breadcrumbs:
if crumb.node != current_cls.__name__:
raise SchemaResolutionError(
f"breadcrumb node '{crumb.node}' does not match current config '{current_cls.__name__}'"
)
if crumb.field is None:
continue
child_cls = current_cls.resolve_child(crumb.field, crumb.value)
if child_cls is None:
spec = current_cls.field_specs().get(crumb.field)
if not spec or spec.child is None:
raise SchemaResolutionError(
f"field '{crumb.field}' on {current_cls.__name__} is not navigable"
)
child_cls = spec.child
current_cls = child_cls
每一步先断言 crumb.node 与当前配置类的 __name__ 完全一致(这是 422 的主要来源),然后优先通过 resolve_child(field, value) 匹配判别式路由——该方法遍历 CHILD_ROUTES 并用 ChildKey.matches 判断字段名与判别值(entity/configs/base.py),value 为 None 的 ChildKey 视为通配;若没有判别式路由,则回退到 FIELD_SPECS 中该字段声明的 child 类型。两处都找不到时抛出 field '<name>' on <node> is not navigable。
7. CLI 辅助:--inspect-schema
在导出模板或调试注册表前,可先用命令行直接查看 Schema:
python run.py --inspect-schema --schema-breadcrumbs '[{"node":"DesignConfig","field":"graph"}]'
输出与 /schema 相同。实现位于 run.py:--inspect-schema 触发 schema 输出后立即退出;--schema-breadcrumbs 先经 json.loads 解析(JSON 非法时直接 SystemExit),随后调用 build_schema_response(breadcrumbs),解析失败则打印 Failed to resolve schema: ...。
注意:run.py 模块加载时会调用 ensure_schema_registry_populated(),它一次性导入 runtime.node.builtin_nodes、builtin_stores、builtin_thinking、builtin_types、builtin_providers 等注册模块(runtime/bootstrap/schema.py),确保内置节点、内存存储、思考策略、边条件与模型提供商的 Schema 均已写入 Schema 注册表。这正是 CLI 与 HTTP 接口行为一致的前提——Schema 元数据来自同一份 FIELD_SPECS 与注册表。
8. 前端调用范式(附真实代码)
文档给出的前端四步调用范式:
- 以
[{node:'DesignConfig', field:'graph'}]拉取基础表单。 - 用户展开子配置(节点、tooling 等)时,附加相应 breadcrumbs 再取一次 Schema。
- 用
cacheKey + breadcrumbs做客户端缓存。 - 保存前调用
/schema/validate,将error+path显示在表单中。
前端已有对应的封装函数 fetchConfigSchema,它向 /api/config/schema 发起 POST 并携带 { breadcrumbs },非 2xx 时抛出带状态码的异常;表单组件 DynamicFormField.vue 则依据响应中的 childRoutes 决定是否递归渲染子配置。这意味着文档描述的"按需拉取 + 递归下钻 + cacheKey 缓存 + 保存前校验"的范式在仓库中已有落地实现,可视为接入参考。
9. 错误参考
| HTTP | 场景 | Payload |
|---|---|---|
| 400 | YAML 解析失败 | { "message": "invalid_yaml", "error": "..." } |
| 422 | Breadcrumb 解析失败 | { "message": "breadcrumb node 'X'..." } |
200 + valid=false |
后端 ConfigError |
{ "error": "...", "path": ["workflow", ...] } |
200 + valid=true |
文档有效 | 返回所请求的 Schema,便于表单渲染。 |
从源码看,422 的触发点有两类:breadcrumb 解析失败(SchemaResolutionError 被路由层捕获并转 422)与文档根节点非 Mapping(document_root_not_mapping);400 专属于 YAML 语法错误;而业务配置错误一律以 200 + valid=false 返回并携带 path,与文档表格完全对应。
10. 与 FIELD_SPECS / 注册表协同的完整链路
整个契约的运行闭环可以概括为:
- 声明:各配置数据类(如
DesignConfig、GraphDefinition、Node、各工具/内存/思考子类)通过类级FIELD_SPECS(字段)、CONSTRAINTS(运行时约束)、CHILD_ROUTES(判别式路由)声明元数据; - 注册:内置节点、边条件、内存存储、思考策略、模型提供商通过
register_node_schema等函数登记到 schema_registry/registry.py,重复注册同名但不同类的行为会抛出SchemaRegistrationError以保证一致性; - 导出:
build_schema_response按 breadcrumbs 解析目标类 →collect_schema()汇总字段与约束 → 序列化并附加childRoutes→ 计算cacheKey; - 消费:前端按
childRoutes递归下钻渲染表单,保存前经/schema/validate校验;CLI 与 IDE 通过--inspect-schema或同一 HTTP 端点获得一致的 Schema。
由此,新增一种节点类型或工具时,只需在其配置类中声明 FIELD_SPECS/CHILD_ROUTES 并完成注册,前端与 CLI 无需改动即可获得全新的表单与校验能力——这正是该 API 契约的价值所在。可结合 设计模板 与 真实工作流示例 进一步对照 FIELD_SPECS 与 YAML 字段的对应关系。