precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/manifest/types_parts/manifest.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview Manifest 主类型定义模块
+
+功能概述:
+- 定义项目清单 (ProjectManifest) 的核心数据结构
+- 整合项目信息、设置、Schema/Constraint/Regex 引用、数据源配置
+
+架构设计:
+- 主入口模型: ProjectManifest 是 manifest.yaml 解析后的根对象
+- ID 唯一性校验: 自动检测并处理重复的 ID
+- 默认值处理: schemas/constraints/regex_nodes/data_sources 默认为空列表
+
+输入示例 (manifest.yaml):
+    version: 2
+
+    project:
+      name: 我的数据项目
+      description: 这是一个测试项目
+
+    settings:
+      file_processing:
+        default_encoding: utf-8
+        csv_delimiter: ","
+      validation:
+        parallel_workers: 4
+
+    schemas:
+      - id: users
+        path: schemas/users.yaml
+      - id: orders
+        path: schemas/orders.yaml
+
+    constraints:
+      - id: users_not_null
+        path: constraints/users_not_null.yaml
+
+    regex_nodes:
+      - id: email_pattern
+        path: regex/email.yaml
+
+    data_sources:
+      - id: primary
+        path: data
+        mode: relative
+        description: 主数据目录
+
+    patterns_dir: patterns
+
+输出示例 (Python 对象):
+    ProjectManifest(
+        version=2,
+        project=ProjectInfo(name="我的数据项目", description="这是一个测试项目"),
+        settings=ProjectSettings(...),
+        schemas=[SchemaRef(...), ...],
+        constraints=[ConstraintRef(...), ...],
+        regex_nodes=[RegexRef(...), ...],
+        data_sources=[DataSourceRef(id="primary", path="data", mode="relative")],
+        patterns_dir="patterns",
+        warnings=[]
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from app.shared.core.project.manifest.types_parts.constants import V2_VERSION
+from app.shared.core.project.manifest.types_parts.data_source import DataSourceRef
+from app.shared.core.project.manifest.types_parts.info import ProjectInfo
+from app.shared.core.project.manifest.types_parts.refs import (
+    ConstraintRef,
+    ManualDataRef,
+    RegexRef,
+    SchemaRef,
+    TransformRef,
+)
+from app.shared.core.project.manifest.types_parts.settings import ProjectSettings
+from app.shared.core.project.manifest.types_parts.template import TemplateInstanceRef, TemplateRef
+
+
+class ProjectManifest(BaseModel):
+    """@classdesc 项目清单主类型
+
+    这是 manifest.yaml 文件解析后的根对象，包含了项目的所有配置引用。
+
+    字段说明:
+        - version: 配置版本号，当前固定为 2
+        - project: 项目基本信息 (名称、描述等)
+        - settings: 项目设置 (文件处理、验证规则等)
+        - schemas: Schema 文件引用列表
+        - constraints: Constraint 文件引用列表
+        - regex_nodes: Regex 节点文件引用列表
+        - data_sources: 数据源目录引用列表（用于全量校验）
+        - patterns_dir: patterns 目录路径
+        - warnings: 加载过程中产生的警告信息
+
+    数据校验:
+        - ID 唯一性: 自动检测重复的 schema/constraint/regex/data_source ID，保留第一个
+        - None 转换: schemas/constraints/regex_nodes/data_sources 如果为 None，自动转为空列表
+
+    示例:
+        # YAML 文件内容
+        version: 2
+        project:
+          name: 用户管理系统
+        schemas:
+          - id: users
+            path: schemas/users.yaml
+          - id: users  # 重复 ID
+            path: schemas/users_dup.yaml
+        data_sources:
+          - id: primary
+            path: data
+            mode: relative
+
+        # 解析后的对象 (重复的会被自动处理)
+        ProjectManifest(
+            version=2,
+            project=ProjectInfo(name="用户管理系统", ...),
+            schemas=[SchemaRef(id="users", path="schemas/users.yaml")],
+            data_sources=[DataSourceRef(id="primary", path="data", mode="relative")],
+            warnings=["Schema ID 'users' 重复，已跳过 'schemas/users_dup.yaml'"]
+        )
+    """
+
+    version: int = Field(V2_VERSION, description="配置版本号（固定为 2）")
+    project: ProjectInfo
+    settings: ProjectSettings = Field(default_factory=ProjectSettings, description="项目设置")
+    schemas: list[SchemaRef] = Field(default_factory=list, description="Schema 文件索引")
+    constraints: list[ConstraintRef] = Field(default_factory=list, description="Constraint 文件索引")
+    regex_nodes: list[RegexRef] = Field(default_factory=list, description="Regex 节点文件索引")
+    transforms: list[TransformRef] = Field(default_factory=list, description="Transform 功能节点文件索引")
+    manual_data: list[ManualDataRef] = Field(default_factory=list, description="ManualData 内联数据节点文件索引")
+    data_sources: list[DataSourceRef] = Field(default_factory=list, description="数据源目录索引")
+    templates: list[TemplateRef] = Field(default_factory=list, description="模板定义文件索引")
+    template_instances: list[TemplateInstanceRef] = Field(default_factory=list, description="模板实例索引")
+    patterns_dir: str = Field("patterns", description="patterns 目录（相对路径）")
+    warnings: list[str] = Field(default_factory=list, description="加载时的警告信息")
+
+    @field_validator(
+        "schemas",
+        "constraints",
+        "regex_nodes",
+        "transforms",
+        "manual_data",
+        "data_sources",
+        "templates",
+        "template_instances",
+        mode="before",
+    )
+    @classmethod
+    def _coerce_none_to_list(cls, v: Any) -> Any:
+        if v is None:
+            return []
+        return v
+
+    @model_validator(mode="after")
+    def _validate_unique_ids(self) -> ProjectManifest:
+        warnings: list[str] = []
+
+        seen_schema_ids: dict[str, SchemaRef] = {}
+        unique_schemas: list[SchemaRef] = []
+        for schema in self.schemas:
+            if schema.id in seen_schema_ids:
+                existing_schema: SchemaRef = seen_schema_ids[schema.id]
+                warnings.append(
+                    f"两个表结构定义使用了相同的 ID「{schema.id}」：已跳过 {schema.path}，保留 {existing_schema.path}"
+                )
+            else:
+                seen_schema_ids[schema.id] = schema
+                unique_schemas.append(schema)
+        # 就地重赋值用 object.__setattr__ 绕开 fields_set 标记（回归: 普通赋值会把
+        # 字段加入 model_fields_set，令 PUT /config/full 的"未显式设置则保留磁盘值"
+        # 合并防线对全部列表字段失效——见 full_config_writer._should_merge 与
+        # test_full_config_reliability 的 fields_set 纯净性守卫）
+        object.__setattr__(self, "schemas", unique_schemas)
+
+        seen_constraint_ids: dict[str, ConstraintRef] = {}
+        unique_constraints: list[ConstraintRef] = []
+        for constraint in self.constraints:
+            if constraint.id in seen_constraint_ids:
+                existing_constraint: ConstraintRef = seen_constraint_ids[constraint.id]
+                warnings.append(
+                    f"两条约束使用了相同的 ID「{constraint.id}」：已跳过 {constraint.path}，保留 {existing_constraint.path}"
+                )
+            else:
+                seen_constraint_ids[constraint.id] = constraint
+                unique_constraints.append(constraint)
+        object.__setattr__(self, "constraints", unique_constraints)
+
+        seen_regex_ids: dict[str, RegexRef] = {}
+        unique_regex_nodes: list[RegexRef] = []
+        for regex in self.regex_nodes:
+            if regex.id in seen_regex_ids:
+                existing_regex: RegexRef = seen_regex_ids[regex.id]
+                warnings.append(
+                    f"两个正则定义使用了相同的 ID「{regex.id}」：已跳过 {regex.path}，保留 {existing_regex.path}"
+                )
+            else:
+                seen_regex_ids[regex.id] = regex
+                unique_regex_nodes.append(regex)
+        object.__setattr__(self, "regex_nodes", unique_regex_nodes)
+
+        seen_transform_ids: dict[str, TransformRef] = {}
+        unique_transforms: list[TransformRef] = []
+        for transform in self.transforms:
+            if transform.id in seen_transform_ids:
+                existing_transform: TransformRef = seen_transform_ids[transform.id]
+                warnings.append(
+                    f"两个数据转换使用了相同的 ID「{transform.id}」：已跳过 {transform.path}，保留 {existing_transform.path}"
+                )
+            else:
+                seen_transform_ids[transform.id] = transform
+                unique_transforms.append(transform)
+        object.__setattr__(self, "transforms", unique_transforms)
+
+        # ManualData ID 去重
+        seen_manual_data_ids: dict[str, ManualDataRef] = {}
+        unique_manual_data: list[ManualDataRef] = []
+        for md in self.manual_data:
+            if md.id in seen_manual_data_ids:
+                existing_manual_data: ManualDataRef = seen_manual_data_ids[md.id]
+                warnings.append(
+                    f"两个手动数据定义使用了相同的 ID「{md.id}」：已跳过 {md.path}，保留 {existing_manual_data.path}"
+                )
+            else:
+                seen_manual_data_ids[md.id] = md
+                unique_manual_data.append(md)
+        object.__setattr__(self, "manual_data", unique_manual_data)
+
+        seen_data_source_ids: dict[str, DataSourceRef] = {}
+        unique_data_sources: list[DataSourceRef] = []
+        for ds in self.data_sources:
+            if ds.id in seen_data_source_ids:
+                existing_data_source: DataSourceRef = seen_data_source_ids[ds.id]
+                warnings.append(
+                    f"两个数据源目录使用了相同的 ID「{ds.id}」：已跳过 {ds.path}，保留 {existing_data_source.path}"
+                )
+            else:
+                seen_data_source_ids[ds.id] = ds
+                unique_data_sources.append(ds)
+        object.__setattr__(self, "data_sources", unique_data_sources)
+
+        # 模板定义 ID 去重
+        seen_template_ids: dict[str, TemplateRef] = {}
+        unique_templates: list[TemplateRef] = []
+        for tmpl in self.templates:
+            if tmpl.id in seen_template_ids:
+                existing_template: TemplateRef = seen_template_ids[tmpl.id]
+                warnings.append(f"Template ID '{tmpl.id}' 重复，已跳过 '{tmpl.path}'，保留 '{existing_template.path}'")
+            else:
+                seen_template_ids[tmpl.id] = tmpl
+                unique_templates.append(tmpl)
+        object.__setattr__(self, "templates", unique_templates)
+
+        # 模板实例 ID 去重
+        seen_instance_ids: dict[str, TemplateInstanceRef] = {}
+        unique_instances: list[TemplateInstanceRef] = []
+        for inst in self.template_instances:
+            if inst.id in seen_instance_ids:
+                existing_instance: TemplateInstanceRef = seen_instance_ids[inst.id]
+                warnings.append(
+                    f"TemplateInstance ID '{inst.id}' 重复，"
+                    f"已跳过 (template_id={inst.template_id})，"
+                    f"保留 (template_id={existing_instance.template_id})"
+                )
+            else:
+                seen_instance_ids[inst.id] = inst
+                unique_instances.append(inst)
+        object.__setattr__(self, "template_instances", unique_instances)
+
+        # 回归: 追加而非整体覆盖——文件里手写的 warnings 是用户的磁盘内容，
+        # 覆盖赋值会在加载→保存 roundtrip 中把它从磁盘上抹掉。
+        # 去重校验每次加载只在确有重复时产生新告警（重复引用已在上方被剔除，
+        # 下次加载不再触发），因此追加不会随 roundtrip 无限增长。
+        object.__setattr__(self, "warnings", list(self.warnings or []) + warnings)
+        return self

app/shared/core/project/manifest/types_parts/refs.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview Manifest 引用类型定义模块
+
+功能概述:
+- 定义 manifest 文件中对其他配置文件的引用结构
+- 包括 Schema、Constraint、Regex 三种引用类型
+
+架构设计:
+- 轻量级引用: 仅包含 ID 和路径，不包含完整内容
+- 延迟加载: 实际内容在后续步骤加载
+
+输入示例 (manifest.yaml):
+    version: 2
+    schemas:
+      - id: users           # SchemaRef.id
+        path: schemas/users.yaml  # SchemaRef.path
+      - id: orders
+        path: schemas/orders.yaml
+    constraints:
+      - id: users_not_null
+        path: constraints/users_not_null.yaml
+    regex_nodes:
+      - id: email_pattern
+        path: regex/email.yaml
+
+输出示例 (Python 对象):
+    # SchemaRef 对象
+    SchemaRef(id="users", path="schemas/users.yaml")
+
+    # ConstraintRef 对象
+    ConstraintRef(id="users_not_null", path="constraints/users_not_null.yaml")
+
+    # RegexRef 对象
+    RegexRef(id="email_pattern", path="regex/email.yaml")
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SchemaRef(BaseModel):
+    """@classdesc Schema 文件引用
+
+    用于在 manifest.yaml 中引用一个 Schema 配置文件。
+
+    字段说明:
+        - id: Schema 的唯一标识符，应与 schema 文件内部的 id 字段一致
+        - path: 相对于 manifest.yaml 所在目录的路径
+
+    示例:
+        # manifest.yaml 中的定义
+        schemas:
+          - id: users
+            path: schemas/users.yaml
+
+        # 对应的 Python 对象
+        SchemaRef(id="users", path="schemas/users.yaml")
+    """
+
+    id: str = Field(..., description="表 ID（与 schema 文件内 id 一致）")
+    path: str = Field(..., description="schema 文件相对路径（相对于 manifest 所在目录）")
+
+
+class ConstraintRef(BaseModel):
+    """@classdesc Constraint 文件引用
+
+    用于在 manifest.yaml 中引用一个 Constraint 配置文件。
+
+    示例:
+        # manifest.yaml 中的定义
+        constraints:
+          - id: users_not_null
+            path: constraints/users_not_null.yaml
+
+        # 对应的 Python 对象
+        ConstraintRef(id="users_not_null", path="constraints/users_not_null.yaml")
+    """
+
+    id: str = Field(..., description="约束 ID（与 constraint 文件内 id 一致）")
+    path: str = Field(..., description="constraint 文件相对路径（相对于 manifest 所在目录）")
+
+
+class RegexRef(BaseModel):
+    """@classdesc Regex 节点文件引用
+
+    用于在 manifest.yaml 中引用一个 Regex 节点配置文件。
+
+    示例:
+        # manifest.yaml 中的定义
+        regex_nodes:
+          - id: email_pattern
+            path: regex/email.yaml
+
+        # 对应的 Python 对象
+        RegexRef(id="email_pattern", path="regex/email.yaml")
+    """
+
+    id: str = Field(..., description="Regex 节点 ID（与 regex 文件内 id 一致）")
+    path: str = Field(..., description="regex 文件相对路径（相对于 manifest 所在目录）")
+
+
+class TransformRef(BaseModel):
+    """@classdesc Transform 节点文件引用
+
+    用于在 manifest.yaml 中引用一个 Transform 功能节点配置文件。
+
+    示例:
+        # manifest.yaml 中的定义
+        transforms:
+          - id: split_id_card
+            path: transforms/split_id_card.transform.yaml
+
+        # 对应的 Python 对象
+        TransformRef(id="split_id_card", path="transforms/split_id_card.transform.yaml")
+    """
+
+    id: str = Field(..., description="Transform 节点 ID（与 transform 文件内 id 一致）")
+    path: str = Field(..., description="transform 文件相对路径（相对于 manifest 所在目录）")
+
+
+class ManualDataRef(BaseModel):
+    """@classdesc ManualData 节点文件引用
+
+    用于在 manifest.yaml 中引用一个 ManualData 内联数据节点配置文件。
+
+    示例:
+        # manifest.yaml 中的定义
+        manual_data:
+          - id: ti1__md1
+            path: manual_data/ti1__md1.yaml
+
+        # 对应的 Python 对象
+        ManualDataRef(id="ti1__md1", path="manual_data/ti1__md1.yaml")
+    """
+
+    id: str = Field(..., description="ManualData 节点 ID（与 manual_data 文件内 id 一致）")
+    path: str = Field(..., description="manual_data 文件相对路径（相对于 manifest 所在目录）")

app/shared/core/project/manifest/types_parts/settings.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 项目设置类型定义模块
+
+功能概述:
+- 整合项目各类设置的结构
+- 包括验证设置、文件处理设置、脚本安全设置
+
+架构设计:
+- 组合模式: ProjectSettings 组合多个子设置
+- 默认工厂: 每个子设置都有默认值
+
+输入示例 (manifest.yaml):
+    settings:
+      validation:
+        parallel_workers: 4
+        strict_mode: true
+      file_processing:
+        default_encoding: utf-8
+        csv_delimiter: ","
+      script_security:
+        allowed_imports:
+          - math
+          - datetime
+        max_execution_time: 30
+
+输出示例:
+    ProjectSettings(
+        validation=ValidationSettings(parallel_workers=4, strict_mode=True),
+        file_processing=FileProcessingSettings(
+            default_encoding="utf-8",
+            csv_delimiter=","
+        ),
+        script_security=ScriptSecuritySettings(
+            allowed_imports=["math", "datetime"],
+            max_execution_time=30
+        )
+    )
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from app.shared.core.project.manifest.types_parts.settings_file_processing import FileProcessingSettings
+from app.shared.core.project.manifest.types_parts.settings_script_security import ScriptSecuritySettings
+from app.shared.core.project.manifest.types_parts.settings_validation import ValidationSettings
+
+
+class ProjectSettings(BaseModel):
+    """
+    @classdesc 项目设置
+
+    包含项目运行时的各类配置选项。
+
+    字段说明:
+        - validation: 验证行为设置 (并行数、严格模式等)
+        - file_processing: 文件处理设置 (编码、日期格式、分隔符等)
+        - script_security: 脚本安全设置 (允许的导入、最大执行时间等)
+
+    默认值:
+        所有子设置都有默认值，可以不填写使用默认配置
+
+    示例:
+        # 最小配置 (使用默认值)
+        settings: {}
+
+        # 自定义配置
+        settings:
+          validation:
+            parallel_workers: 8
+          file_processing:
+            encoding: gbk
+    """
+
+    validation: ValidationSettings = Field(default_factory=ValidationSettings, description="校验行为设置")
+    file_processing: FileProcessingSettings = Field(default_factory=FileProcessingSettings, description="文件处理设置")
+    script_security: ScriptSecuritySettings = Field(default_factory=ScriptSecuritySettings, description="脚本安全设置")

app/shared/core/project/manifest/types_parts/settings_file_processing.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 文件处理设置类型定义模块
+
+功能概述:
+- 定义文件处理相关的配置选项
+- 包括编码、分隔符
+
+架构设计:
+- 类型安全: 使用 Literal 限制可选值
+- 默认值: 提供合理的默认配置
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class FileProcessingSettings(BaseModel):
+    """@classdesc 文件处理设置
+
+    定义如何读取数据文件。
+
+    字段说明:
+        - default_encoding: 文件字符编码，auto 表示自动检测
+        - csv_delimiter: CSV 文件字段分隔符
+
+    输入示例 (manifest.yaml):
+        settings:
+          file_processing:
+            default_encoding: utf-8
+            csv_delimiter: ";"
+
+    输出示例:
+        FileProcessingSettings(
+            default_encoding="utf-8",
+            csv_delimiter=";",
+        )
+
+    默认值:
+        FileProcessingSettings(
+            default_encoding="utf-8",
+            csv_delimiter=",",
+        )
+    """
+
+    default_encoding: Literal["utf-8", "gbk", "auto"] = Field("utf-8", description="读取文件时使用的字符编码")
+    csv_delimiter: str = Field(",", description="CSV文件的字段分隔符")

app/shared/core/project/manifest/types_parts/settings_script_security.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 脚本安全设置类型定义模块
+
+功能概述:
+- 定义脚本执行的安全策略
+- 控制 eval/exec 的使用、沙箱模式、超时等
+
+架构设计:
+- 安全优先: 默认禁用危险函数
+- 范围限制: timeout_seconds 有取值范围
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ScriptSecuritySettings(BaseModel):
+    """@classdesc 脚本安全设置
+
+    定义脚本执行的权限和安全策略。
+
+    字段说明:
+        - allow_eval: 是否允许使用 eval() 函数 (危险! 可能执行任意代码)
+        - allow_exec: 是否允许使用 exec() 函数 (危险! 可能执行任意代码)
+        - sandbox_mode: 是否在沙箱环境中执行 (限制文件系统访问等)
+        - timeout_seconds: 脚本最大执行时间 (1-60秒)
+
+    原理说明:
+        为什么默认禁用 eval/exec?
+        - eval() 和 exec() 可以执行任意 Python 代码
+        - 如果用户输入被拼接到这些函数中，可能导致代码注入攻击
+        - 建议使用安全的表达式解析器代替
+
+    输入示例 (manifest.yaml):
+        settings:
+          script_security:
+            allow_eval: false
+            allow_exec: false
+            sandbox_mode: true
+            timeout_seconds: 30
+
+    输出示例:
+        ScriptSecuritySettings(
+            allow_eval=False,
+            allow_exec=False,
+            sandbox_mode=True,
+            timeout_seconds=30
+        )
+
+    默认值 (最安全配置):
+        ScriptSecuritySettings(
+            allow_eval=False,
+            allow_exec=False,
+            sandbox_mode=True,
+            timeout_seconds=10
+        )
+    """
+
+    allow_eval: bool = Field(False, description="是否允许执行 Python eval() 函数")
+    allow_exec: bool = Field(False, description="是否允许执行 Python exec() 函数")
+    sandbox_mode: bool = Field(True, description="是否在受限环境中执行脚本")
+    timeout_seconds: int = Field(10, ge=1, le=60, description="脚本单次执行的最大时间（秒）")