mirror of
https://github.com/OpenBMB/ChatDev.git
synced 2026-04-25 19:28:09 +00:00
62 lines
3.9 KiB
Markdown
Executable File
62 lines
3.9 KiB
Markdown
Executable File
# FIELD_SPECS 定义指南
|
||
|
||
本文档解释如何在新增配置（Config）时正确编写 `FIELD_SPECS`，以便 Web UI 表单和 `python -m tools.export_design_template` 命令自动生成可视化表单与 YAML 模板。本指南适用于所有继承 `BaseConfig` 的配置类，例如节点、Memory、Thinking、Tooling 等。
|
||
|
||
## 1. 为什么需要 FIELD_SPECS
|
||
- UI 表单依赖 `FIELD_SPECS` 生成输入控件、默认值、提示文案。
|
||
- 设计模板导出脚本会读取 `FIELD_SPECS`，将字段元数据写入 `yaml_template/design*.yaml` 以及 `frontend/public/` 镜像文件。
|
||
- 没有 `FIELD_SPECS` 的字段在前端无法展示，也不会出现在导出的模板中。
|
||
|
||
## 2. 基本结构
|
||
`FIELD_SPECS` 是一个 `{字段名: ConfigFieldSpec}` 的字典，通常定义在 Config 类内：
|
||
|
||
```python
|
||
FIELD_SPECS = {
|
||
"interpreter": ConfigFieldSpec(
|
||
name="interpreter",
|
||
display_name="解释器",
|
||
type_hint="str",
|
||
required=False,
|
||
default="python3",
|
||
description="Python 可执行文件路径",
|
||
),
|
||
...
|
||
}
|
||
```
|
||
|
||
核心字段说明：
|
||
- `name`：与 YAML 字段一致。
|
||
- `display_name`：可选的用户展示名称，前端表单优先显示；缺省时自动回退到 `name`。
|
||
- `type_hint`：供 UI/文档展示的类型描述，例如 `str`、`list[str]`、`dict[str, Any]`。
|
||
- `required`：是否必填；若有默认值通常设为 False。
|
||
- `default`：默认值（标量或 JSON 可序列化对象）。
|
||
- `description`：表单提示与文档说明。
|
||
- `enum`：可选值列表（字符串数组）。
|
||
- `enumOptions`：为枚举提供 label/description 等附加提示，推荐搭配 `enum` 一起返回，提升表单友好度。
|
||
- `child`：嵌套子配置类（引用另一个 `BaseConfig` 子类）。
|
||
|
||
## 3. 编写流程
|
||
1. **实现 `from_dict` 校验**：在解析 YAML 时确保类型正确、提供清晰错误（抛 `ConfigError`，见 `entity/configs/python_runner.py`）。
|
||
2. **定义 `FIELD_SPECS`**：覆盖所有公开字段，提供类型、描述、默认值等信息。
|
||
3. **动态字段处理**：若字段依赖注册表或目录扫描结果，重写 `field_specs()` 并使用 `replace()` 注入实时 `enum`/`description`（示例：`FunctionToolEntryConfig.field_specs()` 自动列出函数目录）。
|
||
4. **导出设计模板**：完成修改后运行：
|
||
```bash
|
||
python -m tools.export_design_template --output yaml_template/design.yaml --mirror frontend/public/design.yaml
|
||
```
|
||
该命令会根据最新的 `FIELD_SPECS` 生成 YAML 模板和前端镜像文件，无需手动编辑。
|
||
|
||
## 4. 常见模式示例
|
||
- **简单标量字段**：`entity/configs/python_runner.py` 中的 `timeout_seconds`，展示如何设置整数默认值和校验。
|
||
- **嵌套列表字段**：`entity/configs/memory.py` 的 `file_sources` 使用 `child=FileSourceConfig`，UI 自动渲染可重复子表单。
|
||
- **动态枚举**：`entity/configs/node.py:304` 的 `Node.field_specs()` 使用节点注册表填充 `type` 选项并附带 `enumOptions` 描述；`FunctionToolEntryConfig.field_specs()` 从函数目录生成带说明的枚举列表。
|
||
- **注册驱动描述**：调用 `register_node_type`/`register_memory_store`/`register_thinking_mode`/`register_tooling_type` 时提供的 `summary/description` 会自动写入 `enumOptions`，务必填写，避免前端看到没有含义的值。
|
||
- **可选区块**：通过 `required=False` + `default=...` 表示可选配置，`from_dict` 中需妥善处理。
|
||
|
||
## 5. 最佳实践
|
||
- 描述保持用户友好，明确单位（例如“超时时间（秒）”）。
|
||
- 默认值应与 `from_dict` 行为一致，避免 UI 默认与后端解析不符。
|
||
- 对嵌套配置提供精简示例或引用，以免 UI 难以理解字段含义。
|
||
- 修改或新增 `FIELD_SPECS` 后，记得同步导出设计模板。
|
||
|
||
如需更多例子，可查阅 `entity/configs/model.py`、`entity/configs/tooling.py` 等文件，或参考已有节点/Memory/Thinking 配置的实现。
|