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 类内：

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. 编写流程

实现 from_dict 校验：在解析 YAML 时确保类型正确、提供清晰错误（抛 ConfigError，见 entity/configs/python_runner.py）。
定义 FIELD_SPECS：覆盖所有公开字段，提供类型、描述、默认值等信息。
动态字段处理：若字段依赖注册表或目录扫描结果，重写 field_specs() 并使用 replace() 注入实时 enum/description（示例：FunctionToolEntryConfig.field_specs() 自动列出函数目录）。
导出设计模板：完成修改后运行：
```
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 配置的实现。

3.9 KiB Executable File Raw Blame History Unescape Escape