mirror of
https://github.com/OpenBMB/ChatDev.git
synced 2026-04-25 11:18:06 +00:00
96 lines
3.7 KiB
Markdown
Executable File
96 lines
3.7 KiB
Markdown
Executable File
# 配置 Schema API 契约
|
||
|
||
本参考说明 `/api/config/schema` 与 `/api/config/schema/validate` 如何暴露 DevAll 的动态配置元数据，便于前端表单、IDE/CLI 通过 breadcrumbs（路径面包屑）按需获取局部 Schema。
|
||
|
||
## 1. 接口
|
||
| 方法 | 作用 |
|
||
| --- | --- |
|
||
| `POST /api/config/schema` | 根据 breadcrumbs 返回对应配置节点的字段定义。 |
|
||
| `POST /api/config/schema/validate` | 校验一份 YAML/JSON 文档，并可回传局部 Schema。 |
|
||
|
||
### 1.1 请求体（公共字段）
|
||
```json
|
||
{
|
||
"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` 为主。
|
||
|
||
### 1.2 `/schema` 响应示例
|
||
```json
|
||
{
|
||
"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，可用于客户端缓存。
|
||
|
||
### 1.3 `/schema/validate` 额外字段
|
||
请求体在 breadcrumbs 旁加入 `document`：
|
||
```json
|
||
{
|
||
"breadcrumbs": [{"node": "DesignConfig"}],
|
||
"document": "name: demo\nversion: 0.4.0\nworkflow:\n nodes: []\n edges: []\n"
|
||
}
|
||
```
|
||
响应：
|
||
- 通过：`{ "valid": true, "schema": { ... } }`
|
||
- 配置错误：
|
||
```json
|
||
{
|
||
"valid": false,
|
||
"error": "field 'nodes' must not be empty",
|
||
"path": ["workflow","nodes"],
|
||
"schema": { ... }
|
||
}
|
||
```
|
||
- YAML 解析失败：HTTP 400，payload `{ "message": "invalid_yaml", "error": "..." }`
|
||
|
||
## 2. Breadcrumb 使用提示
|
||
- 起点：`{ "node": "DesignConfig" }`。
|
||
- 每一步的 `node` 必须与当前位置的类匹配，否则返回 422。
|
||
- 用 `field` 进入子配置（graph → nodes → config 等）。
|
||
- 判别式子类（如节点 `type`、tooling `type`）需填写 `value`。
|
||
- 不可导航的字段会返回 `field '<name>' on <node> is not navigable`。
|
||
|
||
## 3. CLI 辅助
|
||
```bash
|
||
python run.py --inspect-schema --schema-breadcrumbs '[{"node":"DesignConfig","field":"graph"}]'
|
||
```
|
||
输出与 `/schema` 相同，便于在导出模板前调试 `FIELD_SPECS` 或注册表。
|
||
|
||
## 4. 前端调用范式
|
||
1. 以 `[{node:'DesignConfig', field:'graph'}]` 拉取基础表单。
|
||
2. 用户展开子配置（节点、tooling 等）时，附加相应 breadcrumbs 再取一次 Schema。
|
||
3. 用 `cacheKey + breadcrumbs` 做客户端缓存。
|
||
4. 保存前调用 `/schema/validate`，将 `error` + `path` 显示在表单中。
|
||
|
||
## 5. 错误参考
|
||
| 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，便于表单渲染。 |
|
||
|
||
搭配 `FIELD_SPECS` 使用，可在前端/IDE 构建无需硬编码的配置体验。
|