Merge branch 'feat/snippet-fe' into deploy/dev

Co-authored-by: krishkantiuj-ren <hiccup.cc.3@gmail.com>
Co-authored-by: Asuka Minato <i@asukaminato.eu.org>

.github/CODEOWNERS

@@ -166,6 +166,7 @@
 
 # Frontend - App - API Documentation
 /web/app/components/develop/ @JzoNgKVO @iamjoel
+/web/app/components/develop/template/*.mdx @JzoNgKVO @iamjoel @RiskeyL
 
 # Frontend - App - Logs and Annotations
 /web/app/components/app/workflow-log/ @JzoNgKVO @iamjoel

.github/workflows/deploy-saas.yml

@@ -1,4 +1,4 @@
-name: Deploy Agent Dev
+name: Deploy SaaS
 
 permissions:
   contents: read
@@ -7,7 +7,7 @@ on:
   workflow_run:
     workflows: ["Build and Push API & Web"]
     branches:
-      - "deploy/agent-dev"
+      - "deploy/saas"
     types:
       - completed
 
@@ -16,13 +16,13 @@ jobs:
     runs-on: depot-ubuntu-24.04
     if: |
       github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.head_branch == 'deploy/agent-dev'
+      github.event.workflow_run.head_branch == 'deploy/saas'
     steps:
       - name: Deploy to server
         uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
         with:
-          host: ${{ secrets.AGENT_DEV_SSH_HOST }}
+          host: ${{ secrets.SAAS_DEV_SSH_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_PRIVATE_KEY }}
           script: |
-            ${{ vars.SSH_SCRIPT || secrets.SSH_SCRIPT }}
+            ${{ vars.SSH_SCRIPT_SAAS_DEV || secrets.SSH_SCRIPT_SAAS_DEV }}

.github/workflows/style.yml

@@ -95,6 +95,51 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
+      - name: Web tsslint
+        if: steps.changed-files.outputs.any_changed == 'true'
+        env:
+          NODE_OPTIONS: --max-old-space-size=4096
+        run: vp run lint:tss
+
+      - name: Web dead code check
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: vp run knip
+
+  ts-common-style:
+    name: TS Common
+    runs-on: depot-ubuntu-24.04
+    permissions:
+      checks: write
+      pull-requests: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Check changed files
+        id: changed-files
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
+        with:
+          files: |
+            web/**
+            cli/**
+            e2e/**
+            sdks/nodejs-client/**
+            packages/**
+            package.json
+            pnpm-lock.yaml
+            pnpm-workspace.yaml
+            .nvmrc
+            eslint.config.mjs
+            .github/workflows/style.yml
+            .github/actions/setup-web/**
+
+      - name: Setup web environment
+        if: steps.changed-files.outputs.any_changed == 'true'
+        uses: ./.github/actions/setup-web
+
       - name: Restore ESLint cache
         if: steps.changed-files.outputs.any_changed == 'true'
         id: eslint-cache-restore
@@ -105,28 +150,14 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'web/eslint.config.mjs', 'web/eslint.constants.mjs', 'web/plugins/eslint/**') }}-
 
-      - name: Web style check
+      - name: Style check
         if: steps.changed-files.outputs.any_changed == 'true'
-        working-directory: .
         run: vp run lint:ci
 
-      - name: Web tsslint
+      - name: Type check
         if: steps.changed-files.outputs.any_changed == 'true'
-        working-directory: ./web
-        env:
-          NODE_OPTIONS: --max-old-space-size=4096
-        run: vp run lint:tss
-
-      - name: Web type check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        working-directory: .
         run: vp run type-check
 
-      - name: Web dead code check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        working-directory: ./web
-        run: vp run knip
-
       - name: Save ESLint cache
         if: steps.changed-files.outputs.any_changed == 'true' && success() && steps.eslint-cache-restore.outputs.cache-hit != 'true'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5

SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in Dify, please report it privately through GitHub Security Advisories:
+
+https://github.com/langgenius/dify/security/advisories/new
+
+Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
+
+When submitting a report, include as much relevant information as you can safely provide, such as:
+
+- A description of the vulnerability
+- Steps to reproduce, if safe to share privately
+- Affected components, versions, or configurations
+- Potential impact
+- Any suggested mitigation or fix, if available
+
+The maintainers will review reports submitted through GitHub Security Advisories and coordinate follow-up there.
+
+## Public Disclosure
+
+Please avoid publicly disclosing details of a vulnerability until it has been reviewed and, where appropriate, a fix or mitigation has been made available.
+
+## Security Updates
+
+Security fixes may be released through normal project releases or other appropriate channels. Users are encouraged to keep Dify deployments up to date.

api/Dockerfile

@@ -27,7 +27,7 @@ COPY api/providers ./providers
 COPY dify-agent/pyproject.toml dify-agent/README.md /app/dify-agent/
 COPY dify-agent/src /app/dify-agent/src
 # Trust the checked-in lock during image builds; local path sources are copied from the repository context.
-RUN uv sync --frozen --no-dev
+RUN uv sync --frozen --no-dev --no-editable
 
 # production stage
 FROM base AS production
@@ -97,6 +97,7 @@ RUN \
 # Copy Python environment and packages
 ENV VIRTUAL_ENV=/app/api/.venv
 COPY --from=packages --chown=dify:dify ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+COPY --from=packages --chown=dify:dify /app/dify-agent /app/dify-agent
 ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
 
 # Download nltk data

api/commands/__init__.py

@@ -4,6 +4,12 @@ CLI command modules extracted from `commands.py`.
 
 from .account import create_tenant, reset_email, reset_password
 from .data_migrate import data_migrate, legacy_model_types
+from .data_migration import (
+    export_migration_data,
+    export_migration_data_template,
+    import_migration_data,
+    migration_data_wizard,
+)
 from .plugin import (
     extract_plugins,
     extract_unique_plugins,
@@ -26,7 +32,12 @@ from .retention import (
     restore_workflow_runs,
 )
 from .storage import clear_orphaned_file_records, file_usage, migrate_oss, remove_orphaned_files_on_storage
-from .system import convert_to_agent_apps, fix_app_site_missing, reset_encrypt_key_pair, upgrade_db
+from .system import (
+    convert_to_agent_apps,
+    fix_app_site_missing,
+    reset_encrypt_key_pair,
+    upgrade_db,
+)
 from .vector import (
     add_qdrant_index,
     migrate_annotation_vector_database,
@@ -48,10 +59,13 @@ __all__ = [
     "data_migrate",
     "delete_archived_workflow_runs",
     "export_app_messages",
+    "export_migration_data",
+    "export_migration_data_template",
     "extract_plugins",
     "extract_unique_plugins",
     "file_usage",
     "fix_app_site_missing",
+    "import_migration_data",
     "install_plugins",
     "install_rag_pipeline_plugins",
     "legacy_model_types",
@@ -59,6 +73,7 @@ __all__ = [
     "migrate_data_for_plugin",
     "migrate_knowledge_vector_database",
     "migrate_oss",
+    "migration_data_wizard",
     "old_metadata_migration",
     "remove_orphaned_files_on_storage",
     "reset_email",

api/commands/data_migration.py

@@ -0,0 +1,754 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any, cast
+from uuid import UUID
+
+import click
+import sqlalchemy as sa
+import yaml
+
+from extensions.ext_database import db
+from models import Tenant
+from models.model import App
+from models.tools import ApiToolProvider, MCPToolProvider, WorkflowToolProvider
+from services.app_dsl_service import AppDslService
+from services.data_migration.dependency_discovery_service import DependencyDiscoveryService
+from services.data_migration.entities import (
+    DependencyKind,
+    ImportOptions,
+    MigrationDataError,
+    ReportContext,
+    ResourceReportItem,
+)
+from services.data_migration.export_service import ExportConfigParser, MigrationExportService
+from services.data_migration.import_service import ImportRequest, MigrationImportService
+from services.data_migration.package_service import MigrationPackageService
+from services.data_migration.report_service import MigrationReportService
+
+ID_STRATEGY_CHOICES = ["preserve-id", "generate-new-id"]
+CONFLICT_STRATEGY_CHOICES = ["fail", "skip", "update"]
+SUPPORTED_WIZARD_APP_MODES = ["workflow", "advanced-chat"]
+WizardToolMap = dict[str, dict[str, str | None]]
+WizardToolSelection = dict[str, list[str]]
+
+
+def _scripted_export_template() -> dict[str, Any]:
+    return {
+        "source_tenant": {
+            "mode": "single",
+            "id": "",
+            "name": "admin's Workspace",
+        },
+        "apps": {
+            "modes": ["workflow", "advanced-chat"],
+            "ids": [],
+            "all": True,
+        },
+        "include_referenced_tools": True,
+        "additional_tools": {
+            "api_tools": [],
+            "workflow_tools": [],
+            "mcp_tools": [],
+        },
+        "include_secrets": False,
+        "import_options": {
+            "create_app_api_token_on_import": False,
+            "id_strategy": "preserve-id",
+            "conflict_strategy": "fail",
+        },
+    }
+
+
+@click.command("app-migration-template", help="Print or write a scripted export config JSON template.")
+@click.option(
+    "--output",
+    "output_file",
+    required=False,
+    type=click.Path(dir_okay=False),
+    help="Path to write the export config JSON template. Prints to stdout when omitted.",
+)
+@click.option("--overwrite", is_flag=True, default=False, help="Overwrite output if it already exists.")
+def export_migration_data_template(output_file: str | None, overwrite: bool) -> None:
+    template_json = json.dumps(_scripted_export_template(), indent=2, ensure_ascii=False) + "\n"
+    if output_file is None:
+        click.echo(template_json, nl=False)
+        return
+    path = Path(output_file)
+    if path.exists() and not overwrite:
+        raise click.ClickException(f"Output file already exists: {output_file}")
+    path.write_text(template_json)
+    click.echo(click.style(f"Output written to {output_file}", fg="green"))
+
+
+@click.command("export-app-migration", help="Export workflow migration data to a versioned JSON package.")
+@click.option(
+    "--input",
+    "input_file",
+    required=False,
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to export config JSON.",
+)
+@click.option(
+    "--output",
+    "output_file",
+    required=False,
+    type=click.Path(dir_okay=False),
+    help="Path to migration package JSON.",
+)
+@click.option("--overwrite", is_flag=True, default=False, help="Overwrite output if it already exists.")
+def export_migration_data(input_file: str | None, output_file: str | None, overwrite: bool) -> None:
+    try:
+        _require_options(("--input", input_file), ("--output", output_file))
+        assert input_file is not None
+        assert output_file is not None
+        raw_config = _load_json_object(input_file, "Export config")
+        selection = ExportConfigParser().parse(raw_config)
+        result = MigrationExportService().export(selection)
+        MigrationPackageService().save_package(result.package, output_file, overwrite=overwrite)
+        click.echo(click.style(f"Output written to {output_file}", fg="green"))
+        _render_report(result.report_items, context=_with_output_path(result.report_context, output_file))
+    except MigrationDataError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@click.command("import-app-migration", help="Import a versioned migration data package.")
+@click.option(
+    "--input",
+    "input_file",
+    required=False,
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to migration package JSON.",
+)
+@click.option("--target-tenant", default=None, help="Target tenant/workspace name. Overrides package metadata.")
+@click.option("--operator-email", default=None, help="Operator account email in the target tenant.")
+@click.option(
+    "--id-strategy",
+    default=None,
+    type=click.Choice(ID_STRATEGY_CHOICES),
+    help="Override package ID strategy.",
+)
+@click.option(
+    "--conflict-strategy",
+    default=None,
+    type=click.Choice(CONFLICT_STRATEGY_CHOICES),
+    help="Override package conflict strategy.",
+)
+@click.option(
+    "--create-app-api-token-on-import/--no-create-app-api-token-on-import",
+    default=None,
+    help="Override package app API token creation behavior.",
+)
+def import_migration_data(
+    input_file: str | None,
+    target_tenant: str | None,
+    operator_email: str | None,
+    id_strategy: str | None,
+    conflict_strategy: str | None,
+    create_app_api_token_on_import: bool | None,
+) -> None:
+    try:
+        _require_options(("--input", input_file))
+        assert input_file is not None
+        package = MigrationPackageService().load_package(input_file)
+        result = MigrationImportService().import_package(
+            ImportRequest(
+                package=package,
+                cli_target_tenant=target_tenant,
+                operator_email=operator_email,
+                options_override=_build_options_override(
+                    package.metadata.import_options,
+                    id_strategy=id_strategy,
+                    conflict_strategy=conflict_strategy,
+                    create_app_api_token_on_import=create_app_api_token_on_import,
+                ),
+            )
+        )
+        _render_report(result.report_items, context=result.report_context)
+    except MigrationDataError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def parse_index_selection(raw: str, values: list[str]) -> list[str]:
+    normalized = raw.strip().lower()
+    if normalized == "all":
+        return values
+
+    selected: list[str] = []
+    for part in raw.split(","):
+        stripped = part.strip()
+        if not stripped:
+            continue
+        try:
+            index = int(stripped)
+        except ValueError as exc:
+            raise click.ClickException(f"Selection must be 'all' or comma-separated numbers: {raw}") from exc
+        if index < 1 or index > len(values):
+            raise click.ClickException(f"Selection index out of range: {index}")
+        selected.append(values[index - 1])
+    return list(dict.fromkeys(selected))
+
+
+def _print_wizard_step(title: str) -> None:
+    click.echo("")
+    click.echo(f"==== {title} ====")
+
+
+def _print_wizard_substep(title: str) -> None:
+    click.echo("")
+    click.echo(f"-- {title} --")
+
+
+@click.command("app-migration-wizard", help="Interactively export workflow migration data.")
+def migration_data_wizard() -> None:
+    try:
+        tenant = _prompt_source_tenant()
+        apps = _eligible_apps_for_tenant(tenant.id)
+        app_ids = _prompt_app_ids(apps)
+        _print_wizard_step("Referenced Tools")
+        include_referenced_tools = click.confirm(
+            "Automatically export tools referenced by selected apps? [y/n, default: y]",
+            default=True,
+            show_default=False,
+        )
+        auto_tools = _discover_auto_tools([app for app in apps if app.id in set(app_ids)], include_referenced_tools)
+        auto_tools = _resolve_auto_tool_names(tenant.id, auto_tools)
+        _print_auto_tools(auto_tools)
+        additional_tools = _prompt_additional_tools(tenant.id, auto_tools)
+        include_secrets, create_tokens, id_strategy, conflict_strategy = _prompt_import_options()
+        _print_wizard_step("Output")
+        output_file, overwrite = _prompt_output_file()
+
+        selection = ExportConfigParser().parse(
+            {
+                "source_tenant": {"mode": "single", "id": tenant.id, "name": tenant.name},
+                "apps": {"ids": app_ids, "all": False},
+                "include_referenced_tools": include_referenced_tools,
+                "additional_tools": additional_tools,
+                "include_secrets": include_secrets,
+                "import_options": {
+                    "create_app_api_token_on_import": create_tokens,
+                    "id_strategy": id_strategy,
+                    "conflict_strategy": conflict_strategy,
+                },
+            }
+        )
+        _confirm_wizard_summary(
+            tenant_name=tenant.name,
+            app_names=[app.name for app in apps if app.id in set(app_ids)],
+            auto_tools=auto_tools,
+            additional_tools=additional_tools,
+            manual_labels=_selected_tool_labels_for_tenant(tenant.id, additional_tools),
+            include_referenced_tools=include_referenced_tools,
+            include_secrets=include_secrets,
+            create_tokens=create_tokens,
+            id_strategy=id_strategy,
+            conflict_strategy=conflict_strategy,
+            output_file=output_file,
+        )
+        result = MigrationExportService().export(selection)
+        MigrationPackageService().save_package(result.package, output_file, overwrite=overwrite)
+        click.echo(click.style(f"Output written to {output_file}", fg="green"))
+        _print_wizard_step("Report")
+        _render_report(result.report_items, context=_with_output_path(result.report_context, output_file))
+    except MigrationDataError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _load_json_object(path: str, label: str) -> dict[str, Any]:
+    try:
+        with Path(path).open(encoding="utf-8") as file:
+            raw = json.load(file)
+    except json.JSONDecodeError as exc:
+        raise MigrationDataError(f"{label} JSON is invalid: {exc.msg}") from exc
+    if not isinstance(raw, dict):
+        raise MigrationDataError(f"{label} JSON must be an object.")
+    return raw
+
+
+def _require_options(*options: tuple[str, object | None]) -> None:
+    missing_options = [name for name, value in options if value is None]
+    if missing_options:
+        raise click.UsageError(f"Missing option(s): {', '.join(missing_options)}.")
+
+
+def _build_options_override(
+    package_options: ImportOptions,
+    *,
+    id_strategy: str | None,
+    conflict_strategy: str | None,
+    create_app_api_token_on_import: bool | None,
+) -> ImportOptions | None:
+    if id_strategy is None and conflict_strategy is None and create_app_api_token_on_import is None:
+        return None
+    return ImportOptions.from_mapping(
+        {
+            "id_strategy": id_strategy or package_options.id_strategy,
+            "conflict_strategy": conflict_strategy or package_options.conflict_strategy,
+            "create_app_api_token_on_import": (
+                create_app_api_token_on_import
+                if create_app_api_token_on_import is not None
+                else package_options.create_app_api_token_on_import
+            ),
+        }
+    )
+
+
+def _prompt_source_tenant() -> Tenant:
+    tenants = list(db.session.scalars(sa.select(Tenant).order_by(Tenant.name.asc())).all())
+    if not tenants:
+        raise MigrationDataError("No tenants found.")
+
+    _print_wizard_step("Source Tenant")
+    click.echo("Source tenants:")
+    for index, tenant in enumerate(tenants, 1):
+        click.echo(f"{index}. {tenant.name} ({tenant.id})")
+
+    tenant_index = click.prompt("Select one source tenant by number", type=int, default=1, show_default=True)
+    if tenant_index < 1 or tenant_index > len(tenants):
+        raise click.ClickException(f"Selection index out of range: {tenant_index}")
+    return tenants[tenant_index - 1]
+
+
+def _eligible_apps_for_tenant(tenant_id: str) -> list[App]:
+    return list(
+        db.session.scalars(
+            sa.select(App)
+            .where(App.tenant_id == tenant_id, App.mode.in_(SUPPORTED_WIZARD_APP_MODES))
+            .order_by(App.name.asc())
+        ).all()
+    )
+
+
+def _prompt_app_ids(apps: list[App]) -> list[str]:
+    if not apps:
+        raise MigrationDataError("No workflow or advanced-chat apps found for the selected tenant.")
+
+    _print_wizard_step("App Selection")
+    click.echo("Currently supported app types: workflow and chatflow.")
+    click.echo("Workflow/chatflow apps:")
+    for index, app in enumerate(apps, 1):
+        mode = app.mode.value if hasattr(app.mode, "value") else app.mode
+        click.echo(f"{index}. {app.name} [{mode}] ({app.id})")
+    app_ids = parse_index_selection(
+        click.prompt("Select apps by number, comma-separated numbers, or all", default="all"),
+        [app.id for app in apps],
+    )
+    selected_apps = [app for app in apps if app.id in set(app_ids)]
+    click.echo("Selected apps:")
+    for app in selected_apps:
+        click.echo(f"- {app.name} ({app.id})")
+    return app_ids
+
+
+def _prompt_import_options() -> tuple[bool, bool, str, str]:
+    _print_wizard_step("Import Options")
+    _print_wizard_substep("Secrets")
+    click.echo("Secrets include workflow/app DSL secret values, custom API tool credentials,")
+    click.echo("and full MCP provider connection data such as server URL, headers, authentication, and tool list.")
+    click.echo("If you choose no, credentials are omitted or masked,")
+    click.echo("and MCP providers are exported as dependency metadata only.")
+    click.echo("Treat the output JSON as sensitive if you choose yes.")
+    include_secrets = click.confirm(
+        "Include secrets in output JSON? [y/n, default: n]",
+        default=False,
+        show_default=False,
+    )
+    _print_wizard_substep("App API Tokens")
+    click.echo("When enabled, import will create an app API token if the imported app has none,")
+    click.echo("or reuse an existing app API token if one already exists.")
+    create_tokens = click.confirm(
+        "Create or reuse app API tokens during import? [y/n, default: n]",
+        default=False,
+        show_default=False,
+    )
+    _print_wizard_substep("ID Strategy")
+    click.echo("ID strategy controls whether imported app and tool IDs preserve source IDs")
+    click.echo("or use target-generated IDs.")
+    click.echo("preserve-id: keep source IDs where the target service supports it.")
+    click.echo("generate-new-id: let the target environment generate new IDs and rewrite references via mapping.")
+    id_strategy = click.prompt(
+        "Import ID strategy. Enter one of: preserve-id, generate-new-id",
+        type=click.Choice(ID_STRATEGY_CHOICES),
+        default="preserve-id",
+        show_default=True,
+    )
+    _print_wizard_substep("Conflict Strategy")
+    click.echo("Conflict strategy controls what import does when a target resource already exists.")
+    click.echo("fail: stop at the first conflict; previously committed resources are not rolled back.")
+    click.echo("skip: keep the existing target resource and skip importing that resource.")
+    click.echo("update: update the existing target resource in place.")
+    conflict_strategy = click.prompt(
+        "Import conflict strategy. Enter one of: fail, skip, update",
+        type=click.Choice(CONFLICT_STRATEGY_CHOICES),
+        default="update",
+        show_default=True,
+    )
+    return include_secrets, create_tokens, id_strategy, conflict_strategy
+
+
+def _discover_auto_tools(apps: list[App], include_referenced_tools: bool) -> WizardToolMap:
+    auto_tools: WizardToolMap = {"api_tools": {}, "workflow_tools": {}, "mcp_tools": {}}
+    if not include_referenced_tools:
+        return auto_tools
+    discovery_service = DependencyDiscoveryService()
+    for app in apps:
+        dsl_content = AppDslService.export_dsl(app_model=app, include_secret=False)
+        raw_dsl = yaml.safe_load(dsl_content) if dsl_content else {}
+        dsl = raw_dsl if isinstance(raw_dsl, dict) else {}
+        for dependency in discovery_service.discover_from_dsl(dsl):
+            if dependency.kind == DependencyKind.API_TOOL:
+                auto_tools["api_tools"][dependency.provider_name or dependency.provider_id] = dependency.provider_id
+            elif dependency.kind == DependencyKind.WORKFLOW_TOOL:
+                auto_tools["workflow_tools"][dependency.provider_name or dependency.provider_id] = (
+                    dependency.provider_id
+                )
+            elif dependency.kind == DependencyKind.MCP_TOOL:
+                auto_tools["mcp_tools"][dependency.provider_name or dependency.provider_id] = dependency.provider_id
+    return auto_tools
+
+
+def _resolve_auto_tool_names(tenant_id: str, auto_tools: WizardToolMap) -> WizardToolMap:
+    return {
+        "api_tools": _resolve_api_tool_names(tenant_id, auto_tools["api_tools"]),
+        "workflow_tools": _resolve_workflow_tool_names(tenant_id, auto_tools["workflow_tools"]),
+        "mcp_tools": _resolve_mcp_tool_names(tenant_id, auto_tools["mcp_tools"]),
+    }
+
+
+def _resolve_api_tool_names(tenant_id: str, tools: dict[str, str | None]) -> dict[str, str | None]:
+    resolved: dict[str, str | None] = {}
+    for name, identifier in tools.items():
+        predicates = [ApiToolProvider.name == name]
+        if _is_uuid_string(identifier):
+            predicates.append(ApiToolProvider.id == identifier)
+        provider = db.session.scalar(
+            sa.select(ApiToolProvider).where(
+                ApiToolProvider.tenant_id == tenant_id,
+                sa.or_(*predicates),
+            )
+        )
+        resolved[provider.name if provider else name] = provider.id if provider else identifier
+    return resolved
+
+
+def _resolve_workflow_tool_names(tenant_id: str, tools: dict[str, str | None]) -> dict[str, str | None]:
+    resolved: dict[str, str | None] = {}
+    for name, identifier in tools.items():
+        predicates = [WorkflowToolProvider.name == name]
+        if _is_uuid_string(identifier):
+            predicates.append(WorkflowToolProvider.id == identifier)
+        provider = db.session.scalar(
+            sa.select(WorkflowToolProvider).where(
+                WorkflowToolProvider.tenant_id == tenant_id,
+                sa.or_(*predicates),
+            )
+        )
+        resolved[provider.name if provider else name] = provider.id if provider else identifier
+    return resolved
+
+
+def _resolve_mcp_tool_names(tenant_id: str, tools: dict[str, str | None]) -> dict[str, str | None]:
+    resolved: dict[str, str | None] = {}
+    for name, identifier in tools.items():
+        predicates = [MCPToolProvider.name == name]
+        if identifier:
+            predicates.append(MCPToolProvider.server_identifier == identifier)
+        if _is_uuid_string(identifier):
+            predicates.append(MCPToolProvider.id == identifier)
+        provider = db.session.scalar(
+            sa.select(MCPToolProvider).where(
+                MCPToolProvider.tenant_id == tenant_id,
+                sa.or_(*predicates),
+            )
+        )
+        resolved[provider.name if provider else name] = provider.id if provider else identifier
+    return resolved
+
+
+def _is_uuid_string(value: str | None) -> bool:
+    if not value:
+        return False
+    try:
+        UUID(value)
+    except ValueError:
+        return False
+    return True
+
+
+def _print_auto_tools(auto_tools: WizardToolMap) -> None:
+    _print_wizard_step("Automatically Discovered Tools")
+    click.echo("Automatically discovered tools:")
+    _print_auto_tool_category("Custom API tools", auto_tools["api_tools"])
+    _print_auto_tool_category("Workflow tools", auto_tools["workflow_tools"])
+    _print_auto_tool_category("MCP tools", auto_tools["mcp_tools"])
+
+
+def _print_auto_tool_category(label: str, values: dict[str, str | None]) -> None:
+    click.echo(label)
+    if not values:
+        click.echo("- none")
+        return
+    for name, identifier in sorted(values.items()):
+        click.echo(f"- {_format_tool_name_id(name, identifier)}")
+
+
+def _prompt_additional_tools(tenant_id: str, auto_tools: WizardToolMap) -> WizardToolSelection:
+    selections: WizardToolSelection = {"api_tools": [], "workflow_tools": [], "mcp_tools": []}
+    _print_wizard_step("Additional Tools")
+    if not click.confirm(
+        "Export additional tools manually? [y/n, default: n]",
+        default=False,
+        show_default=False,
+    ):
+        _print_final_tool_selection(auto_tools, selections, {})
+        return selections
+    manual_labels: dict[str, str] = {}
+    api_tool_options = [
+        (tool.name, tool.name, tool.id)
+        for tool in db.session.scalars(
+            sa.select(ApiToolProvider).where(ApiToolProvider.tenant_id == tenant_id).order_by(ApiToolProvider.name)
+        ).all()
+    ]
+    selections["api_tools"] = _prompt_tool_category(
+        "Custom API tools",
+        api_tool_options,
+        auto_tools=auto_tools["api_tools"],
+    )
+    manual_labels.update(_selected_tool_labels(api_tool_options, selections["api_tools"]))
+    workflow_tool_options = [
+        (tool.id, tool.name, tool.id)
+        for tool in db.session.scalars(
+            sa.select(WorkflowToolProvider)
+            .where(WorkflowToolProvider.tenant_id == tenant_id)
+            .order_by(WorkflowToolProvider.name)
+        ).all()
+    ]
+    selections["workflow_tools"] = _prompt_tool_category(
+        "Workflow tools",
+        workflow_tool_options,
+        auto_tools=auto_tools["workflow_tools"],
+    )
+    manual_labels.update(_selected_tool_labels(workflow_tool_options, selections["workflow_tools"]))
+    mcp_tool_options = [
+        (tool.id, tool.name, tool.server_identifier)
+        for tool in db.session.scalars(
+            sa.select(MCPToolProvider).where(MCPToolProvider.tenant_id == tenant_id).order_by(MCPToolProvider.name)
+        ).all()
+    ]
+    selections["mcp_tools"] = _prompt_tool_category(
+        "MCP tools",
+        mcp_tool_options,
+        auto_tools=auto_tools["mcp_tools"],
+    )
+    manual_labels.update(_selected_tool_labels(mcp_tool_options, selections["mcp_tools"]))
+    _print_final_tool_selection(auto_tools, selections, manual_labels)
+    return selections
+
+
+def _selected_tool_labels_for_tenant(tenant_id: str, selected_tools: WizardToolSelection) -> dict[str, str]:
+    labels: dict[str, str] = {}
+    if selected_tools["api_tools"]:
+        labels.update(
+            _selected_tool_labels(
+                [
+                    (tool.name, tool.name, tool.id)
+                    for tool in db.session.scalars(
+                        sa.select(ApiToolProvider)
+                        .where(ApiToolProvider.tenant_id == tenant_id)
+                        .order_by(ApiToolProvider.name)
+                    ).all()
+                ],
+                selected_tools["api_tools"],
+            )
+        )
+    if selected_tools["workflow_tools"]:
+        labels.update(
+            _selected_tool_labels(
+                [
+                    (tool.id, tool.name, tool.id)
+                    for tool in db.session.scalars(
+                        sa.select(WorkflowToolProvider)
+                        .where(WorkflowToolProvider.tenant_id == tenant_id)
+                        .order_by(WorkflowToolProvider.name)
+                    ).all()
+                ],
+                selected_tools["workflow_tools"],
+            )
+        )
+    if selected_tools["mcp_tools"]:
+        labels.update(
+            _selected_tool_labels(
+                [
+                    (tool.id, tool.name, tool.server_identifier)
+                    for tool in db.session.scalars(
+                        sa.select(MCPToolProvider)
+                        .where(MCPToolProvider.tenant_id == tenant_id)
+                        .order_by(MCPToolProvider.name)
+                    ).all()
+                ],
+                selected_tools["mcp_tools"],
+            )
+        )
+    return labels
+
+
+def _selected_tool_labels(options: list[tuple[str, str, str]], selected_values: list[str]) -> dict[str, str]:
+    selected = set(selected_values)
+    return {value: _format_tool_name_id(name, detail) for value, name, detail in options if value in selected}
+
+
+def _prompt_tool_category(
+    label: str,
+    options: list[tuple[str, str, str]],
+    *,
+    auto_tools: dict[str, str | None],
+) -> list[str]:
+    if not options:
+        click.echo(f"{label}: none")
+        return []
+    _print_wizard_step(label)
+    for index, (value, name, detail) in enumerate(options, 1):
+        marker = "[auto]" if _is_auto_tool(value, name, detail, auto_tools) else "[ ]"
+        click.echo(f"{index}. {marker} {name} ({detail})")
+    raw = click.prompt(
+        f"Select {label.lower()} by number, comma-separated numbers, all, or empty",
+        default="",
+        show_default=cast(Any, "empty"),
+    )
+    if not raw.strip():
+        return []
+    return parse_index_selection(raw, [value for value, _, _ in options])
+
+
+def _is_auto_tool(value: str, name: str, detail: str, auto_tools: dict[str, str | None]) -> bool:
+    return name in auto_tools or value in auto_tools or value in auto_tools.values() or detail in auto_tools.values()
+
+
+def _print_final_tool_selection(
+    auto_tools: WizardToolMap,
+    additional_tools: WizardToolSelection,
+    manual_labels: dict[str, str],
+) -> None:
+    _print_wizard_step("Final Tool Selection")
+    _print_tool_selection_body(auto_tools, additional_tools, manual_labels)
+
+
+def _print_tool_selection_body(
+    auto_tools: WizardToolMap,
+    additional_tools: WizardToolSelection,
+    manual_labels: dict[str, str],
+) -> None:
+    click.echo("Final tools to export:")
+    _print_final_tool_category(
+        "Custom API tools",
+        auto_tools["api_tools"],
+        additional_tools["api_tools"],
+        manual_labels,
+    )
+    _print_final_tool_category(
+        "Workflow tools",
+        auto_tools["workflow_tools"],
+        additional_tools["workflow_tools"],
+        manual_labels,
+    )
+    _print_final_tool_category("MCP tools", auto_tools["mcp_tools"], additional_tools["mcp_tools"], manual_labels)
+
+
+def _print_final_tool_category(
+    label: str,
+    auto_tools: dict[str, str | None],
+    manual_values: list[str],
+    manual_labels: dict[str, str],
+) -> None:
+    click.echo(label)
+    lines = [f"- [auto] {_format_tool_name_id(name, identifier)}" for name, identifier in sorted(auto_tools.items())]
+    auto_identifiers = {identifier for identifier in auto_tools.values() if identifier}
+    lines.extend(
+        f"- [manual] {manual_labels.get(value, value)}"
+        for value in manual_values
+        if value not in auto_tools and value not in auto_identifiers
+    )
+    if not lines:
+        click.echo("- none")
+        return
+    for line in lines:
+        click.echo(line)
+
+
+def _format_tool_name_id(name: str, identifier: str | None) -> str:
+    if identifier and identifier != name:
+        return f"{name}: {identifier}"
+    return name
+
+
+def _confirm_wizard_summary(
+    *,
+    tenant_name: str,
+    app_names: list[str],
+    auto_tools: WizardToolMap,
+    additional_tools: WizardToolSelection,
+    manual_labels: dict[str, str],
+    include_referenced_tools: bool,
+    include_secrets: bool,
+    create_tokens: bool,
+    id_strategy: str,
+    conflict_strategy: str,
+    output_file: str,
+) -> None:
+    _print_wizard_step("Summary")
+    click.echo("Migration export summary:")
+    click.echo(f"source tenant: {tenant_name}")
+    click.echo(f"selected apps: {len(app_names)}")
+    for app_name in app_names:
+        click.echo(f"- {app_name}")
+    click.echo(f"auto referenced tools: {str(include_referenced_tools).lower()}")
+    _print_tool_selection_body(auto_tools, additional_tools, manual_labels)
+    click.echo(f"include secrets: {str(include_secrets).lower()}")
+    click.echo(f"create app api token on import: {str(create_tokens).lower()}")
+    click.echo(f"id strategy: {id_strategy}")
+    click.echo(f"conflict strategy: {conflict_strategy}")
+    click.echo(f"output path: {output_file}")
+    if not click.confirm("Write migration package? [y/n, default: y]", default=True, show_default=False):
+        raise click.Abort()
+
+
+def _prompt_output_file() -> tuple[str, bool]:
+    default_output = f"migration-data-{datetime.now().strftime('%Y%m%d-%H%M%S')}.json"
+    output_file = click.prompt("Output path", default=default_output, show_default=True)
+    if output_file.lower() in {"y", "yes", "n", "no"}:
+        raise click.ClickException("Output path must be a file path. Press Enter to use the default path.")
+    overwrite = False
+    if Path(output_file).exists():
+        overwrite = click.confirm(
+            "Output file exists. Overwrite? [y/n, default: n]",
+            default=False,
+            show_default=False,
+        )
+        if not overwrite:
+            raise click.ClickException(f"Output file already exists: {output_file}")
+    return output_file, overwrite
+
+
+def _with_output_path(context: ReportContext | None, output_path: str) -> ReportContext:
+    if context is None:
+        return ReportContext(output_path=output_path)
+    return ReportContext(
+        output_path=output_path,
+        source_scope=context.source_scope,
+        selected_app_count=context.selected_app_count,
+        include_secrets=context.include_secrets,
+        target_tenant=context.target_tenant,
+        operator_email=context.operator_email,
+        app_api_tokens_created=context.app_api_tokens_created,
+        app_api_tokens_reused=context.app_api_tokens_reused,
+        id_mapping_count=context.id_mapping_count,
+        id_mappings=context.id_mappings,
+    )
+
+
+def _render_report(report_items: list[ResourceReportItem], *, context: ReportContext | None = None) -> None:
+    for line in MigrationReportService().render(report_items, context=context):
+        click.echo(line)

api/commands/vector.py

@@ -30,7 +30,7 @@ def vdb_migrate(scope: str):
 
 def migrate_annotation_vector_database():
     """
-    Migrate annotation datas to target vector database .
+    Migrate annotation data to target vector database.
     """
     click.echo(click.style("Starting annotation data migration.", fg="green"))
     create_count = 0
@@ -140,7 +140,7 @@ def migrate_annotation_vector_database():
 
 def migrate_knowledge_vector_database():
     """
-    Migrate vector database datas to target vector database .
+    Migrate vector database data to target vector database.
     """
     click.echo(click.style("Starting vector database migration.", fg="green"))
     create_count = 0

api/controllers/common/schema.py

@@ -6,10 +6,11 @@ These helpers keep that translation centralized so models registered through
 `register_schema_models` emit resolvable Swagger 2.0 references.
 """
 
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
 from enum import StrEnum
-from typing import Any, Literal, NotRequired, TypedDict
+from typing import Any, Literal, NotRequired, Protocol, TypedDict
 
+from flask import request
 from flask_restx import Namespace
 from pydantic import BaseModel, TypeAdapter
 
@@ -36,6 +37,12 @@ QueryParamDoc = TypedDict(
 )
 
 
+class QueryArgs(Protocol):
+    def to_dict(self, flat: bool = True) -> dict[str, str]: ...
+
+    def getlist(self, key: str) -> list[str]: ...
+
+
 def _register_json_schema(namespace: Namespace, name: str, schema: dict) -> None:
     """Register a JSON schema and promote any nested Pydantic `$defs`."""
 
@@ -167,6 +174,58 @@ def query_params_from_model(model: type[BaseModel]) -> dict[str, QueryParamDoc]:
     return params
 
 
+def query_params_from_request[ModelT: BaseModel](
+    model: type[ModelT],
+    *,
+    list_fields: Iterable[str] = (),
+    args: QueryArgs | None = None,
+    use_defaults_for_malformed_ints: bool = False,
+) -> ModelT:
+    """Validate query args with Pydantic while preserving Flask query parsing behavior.
+
+    Repeated params need explicit ``getlist()`` handling because Werkzeug's
+    ``to_dict()`` keeps only one value. For malformed scalar integers, Flask's
+    For endpoints migrated from ``request.args.get(..., type=int, default=...)``,
+    set ``use_defaults_for_malformed_ints`` to preserve Flask's fallback to
+    defaults for malformed optional integer params.
+    """
+
+    query_args = args or request.args
+    params: dict[str, Any] = query_args.to_dict()
+    for field_name in list_fields:
+        params[field_name] = query_args.getlist(field_name)
+
+    if use_defaults_for_malformed_ints:
+        _drop_malformed_defaulted_integer_params(model, params)
+    return model.model_validate(params)
+
+
+def _drop_malformed_defaulted_integer_params(model: type[BaseModel], params: dict[str, Any]) -> None:
+    properties = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0).get("properties", {})
+    if not isinstance(properties, Mapping):
+        return
+
+    for name, value in list(params.items()):
+        if not isinstance(value, str):
+            continue
+
+        field = model.model_fields.get(name)
+        if field is None or field.is_required():
+            continue
+
+        property_schema = properties.get(name)
+        if not isinstance(property_schema, Mapping):
+            continue
+
+        if _nullable_property_schema(property_schema).get("type") != "integer":
+            continue
+
+        try:
+            int(value)
+        except ValueError:
+            params.pop(name)
+
+
 def _query_param_from_property(property_schema: Mapping[str, Any], *, required: bool) -> QueryParamDoc:
     param_schema = _nullable_property_schema(property_schema)
     param_doc: QueryParamDoc = {"in": "query", "required": required}
@@ -239,6 +298,7 @@ __all__ = [
     "DEFAULT_REF_TEMPLATE_SWAGGER_2_0",
     "get_or_create_model",
     "query_params_from_model",
+    "query_params_from_request",
     "register_enum_models",
     "register_response_schema_model",
     "register_response_schema_models",

api/controllers/console/__init__.py

@@ -119,6 +119,7 @@ from .explore import (
     saved_message,
     trial,
 )
+from .snippets import snippet_workflow, snippet_workflow_draft_variable
 from .socketio import workflow as socketio_workflow
 
 # Import tag controllers
@@ -134,6 +135,7 @@ from .workspace import (
     model_providers,
     models,
     plugin,
+    snippets,
     tool_providers,
     trigger_providers,
     workspace,
@@ -206,6 +208,9 @@ __all__ = [
     "saved_message",
     "setup",
     "site",
+    "snippet_workflow",
+    "snippet_workflow_draft_variable",
+    "snippets",
     "socketio_workflow",
     "spec",
     "statistic",

api/controllers/console/agent/composer.py

@@ -1,9 +1,17 @@
 from flask_restx import Resource
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from fields.agent_fields import (
+    AgentAppComposerResponse,
+    AgentComposerCandidatesResponse,
+    AgentComposerImpactResponse,
+    AgentComposerValidateResponse,
+    WorkflowAgentComposerResponse,
+)
+from libs.helper import dump_response
 from libs.login import current_account_with_tenant, login_required
 from models.model import App, AppMode
 from services.agent.composer_service import AgentComposerService
@@ -11,23 +19,40 @@ from services.agent.composer_validator import ComposerConfigValidator
 from services.entities.agent_entities import ComposerSavePayload
 
 register_schema_models(console_ns, ComposerSavePayload)
+register_response_schema_models(
+    console_ns,
+    AgentAppComposerResponse,
+    AgentComposerCandidatesResponse,
+    AgentComposerImpactResponse,
+    AgentComposerValidateResponse,
+    WorkflowAgentComposerResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer")
 class WorkflowAgentComposerApi(Resource):
+    @console_ns.response(
+        200, "Workflow agent composer state", console_ns.models[WorkflowAgentComposerResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     def get(self, app_model: App, node_id: str):
         _, tenant_id = current_account_with_tenant()
-        return AgentComposerService.load_workflow_composer(
-            tenant_id=tenant_id,
-            app_id=app_model.id,
-            node_id=node_id,
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.load_workflow_composer(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                node_id=node_id,
+            ),
         )
 
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(
+        200, "Workflow agent composer saved", console_ns.models[WorkflowAgentComposerResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -36,18 +61,24 @@ class WorkflowAgentComposerApi(Resource):
     def put(self, app_model: App, node_id: str):
         account, tenant_id = current_account_with_tenant()
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
-        return AgentComposerService.save_workflow_composer(
-            tenant_id=tenant_id,
-            app_id=app_model.id,
-            node_id=node_id,
-            account_id=account.id,
-            payload=payload,
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.save_workflow_composer(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                node_id=node_id,
+                account_id=account.id,
+                payload=payload,
+            ),
         )
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/validate")
 class WorkflowAgentComposerValidateApi(Resource):
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(
+        200, "Workflow agent composer validation result", console_ns.models[AgentComposerValidateResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -55,21 +86,29 @@ class WorkflowAgentComposerValidateApi(Resource):
     def post(self, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
-        return {"result": "success", "errors": []}
+        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": []})
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/candidates")
 class WorkflowAgentComposerCandidatesApi(Resource):
+    @console_ns.response(
+        200, "Workflow agent composer candidates", console_ns.models[AgentComposerCandidatesResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     def get(self, app_model: App, node_id: str):
-        return AgentComposerService.get_workflow_candidates(app_id=app_model.id)
+        return dump_response(
+            AgentComposerCandidatesResponse,
+            AgentComposerService.get_workflow_candidates(app_id=app_model.id),
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/impact")
 class WorkflowAgentComposerImpactApi(Resource):
+    @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(200, "Workflow agent composer impact", console_ns.models[AgentComposerImpactResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -79,13 +118,21 @@ class WorkflowAgentComposerImpactApi(Resource):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         current_snapshot_id = payload.binding.current_snapshot_id if payload.binding else None
         if not current_snapshot_id:
-            return {"current_snapshot_id": None, "workflow_node_count": 0, "bindings": []}
-        return AgentComposerService.calculate_impact(tenant_id=tenant_id, current_snapshot_id=current_snapshot_id)
+            return dump_response(
+                AgentComposerImpactResponse, {"current_snapshot_id": None, "workflow_node_count": 0, "bindings": []}
+            )
+        return dump_response(
+            AgentComposerImpactResponse,
+            AgentComposerService.calculate_impact(tenant_id=tenant_id, current_snapshot_id=current_snapshot_id),
+        )
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/save-to-roster")
 class WorkflowAgentComposerSaveToRosterApi(Resource):
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(
+        200, "Workflow agent composer saved to roster", console_ns.models[WorkflowAgentComposerResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -94,26 +141,34 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
     def post(self, app_model: App, node_id: str):
         account, tenant_id = current_account_with_tenant()
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
-        return AgentComposerService.save_workflow_composer(
-            tenant_id=tenant_id,
-            app_id=app_model.id,
-            node_id=node_id,
-            account_id=account.id,
-            payload=payload,
+        return dump_response(
+            WorkflowAgentComposerResponse,
+            AgentComposerService.save_workflow_composer(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                node_id=node_id,
+                account_id=account.id,
+                payload=payload,
+            ),
         )
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent-composer")
 class AgentAppComposerApi(Resource):
+    @console_ns.response(200, "Agent app composer state", console_ns.models[AgentAppComposerResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model()
     def get(self, app_model: App):
         _, tenant_id = current_account_with_tenant()
-        return AgentComposerService.load_agent_app_composer(tenant_id=tenant_id, app_id=app_model.id)
+        return dump_response(
+            AgentAppComposerResponse,
+            AgentComposerService.load_agent_app_composer(tenant_id=tenant_id, app_id=app_model.id),
+        )
 
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(200, "Agent app composer saved", console_ns.models[AgentAppComposerResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -122,17 +177,23 @@ class AgentAppComposerApi(Resource):
     def put(self, app_model: App):
         account, tenant_id = current_account_with_tenant()
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
-        return AgentComposerService.save_agent_app_composer(
-            tenant_id=tenant_id,
-            app_id=app_model.id,
-            account_id=account.id,
-            payload=payload,
+        return dump_response(
+            AgentAppComposerResponse,
+            AgentComposerService.save_agent_app_composer(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                account_id=account.id,
+                payload=payload,
+            ),
         )
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent-composer/validate")
 class AgentAppComposerValidateApi(Resource):
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
+    @console_ns.response(
+        200, "Agent app composer validation result", console_ns.models[AgentComposerValidateResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -140,14 +201,20 @@ class AgentAppComposerValidateApi(Resource):
     def post(self, app_model: App):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
-        return {"result": "success", "errors": []}
+        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": []})
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent-composer/candidates")
 class AgentAppComposerCandidatesApi(Resource):
+    @console_ns.response(
+        200, "Agent app composer candidates", console_ns.models[AgentComposerCandidatesResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model()
     def get(self, app_model: App):
-        return AgentComposerService.get_agent_app_candidates(app_id=app_model.id)
+        return dump_response(
+            AgentComposerCandidatesResponse,
+            AgentComposerService.get_agent_app_candidates(app_id=app_model.id),
+        )

api/controllers/console/agent/roster.py

@@ -4,10 +4,18 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
 from extensions.ext_database import db
+from fields.agent_fields import (
+    AgentConfigSnapshotDetailResponse,
+    AgentConfigSnapshotListResponse,
+    AgentInviteOptionsResponse,
+    AgentRosterListResponse,
+    AgentRosterResponse,
+)
+from libs.helper import dump_response
 from libs.login import current_account_with_tenant, login_required
 from services.agent.roster_service import AgentRosterService
 from services.entities.agent_entities import RosterAgentCreatePayload, RosterAgentUpdatePayload, RosterListQuery
@@ -29,6 +37,14 @@ register_schema_models(
     RosterAgentUpdatePayload,
     RosterListQuery,
 )
+register_response_schema_models(
+    console_ns,
+    AgentConfigSnapshotDetailResponse,
+    AgentConfigSnapshotListResponse,
+    AgentInviteOptionsResponse,
+    AgentRosterListResponse,
+    AgentRosterResponse,
+)
 
 
 def _agent_roster_service() -> AgentRosterService:
@@ -37,17 +53,23 @@ def _agent_roster_service() -> AgentRosterService:
 
 @console_ns.route("/agents")
 class AgentRosterListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(RosterListQuery))
+    @console_ns.response(200, "Agent roster list", console_ns.models[AgentRosterListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     def get(self):
         _, tenant_id = current_account_with_tenant()
         query = RosterListQuery.model_validate(request.args.to_dict(flat=True))
-        return _agent_roster_service().list_roster_agents(
-            tenant_id=tenant_id, page=query.page, limit=query.limit, keyword=query.keyword
+        return dump_response(
+            AgentRosterListResponse,
+            _agent_roster_service().list_roster_agents(
+                tenant_id=tenant_id, page=query.page, limit=query.limit, keyword=query.keyword
+            ),
         )
 
     @console_ns.expect(console_ns.models[RosterAgentCreatePayload.__name__])
+    @console_ns.response(201, "Agent created", console_ns.models[AgentRosterResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -57,36 +79,49 @@ class AgentRosterListApi(Resource):
         payload = RosterAgentCreatePayload.model_validate(console_ns.payload or {})
         service = _agent_roster_service()
         agent = service.create_roster_agent(tenant_id=tenant_id, account_id=account.id, payload=payload)
-        return service.get_roster_agent_detail(tenant_id=tenant_id, agent_id=agent.id), 201
+        return dump_response(
+            AgentRosterResponse,
+            service.get_roster_agent_detail(tenant_id=tenant_id, agent_id=agent.id),
+        ), 201
 
 
 @console_ns.route("/agents/invite-options")
 class AgentInviteOptionsApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentInviteOptionsQuery))
+    @console_ns.response(200, "Agent invite options", console_ns.models[AgentInviteOptionsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     def get(self):
         _, tenant_id = current_account_with_tenant()
         query = AgentInviteOptionsQuery.model_validate(request.args.to_dict(flat=True))
-        return _agent_roster_service().list_invite_options(
-            tenant_id=tenant_id,
-            page=query.page,
-            limit=query.limit,
-            keyword=query.keyword,
-            app_id=query.app_id,
+        return dump_response(
+            AgentInviteOptionsResponse,
+            _agent_roster_service().list_invite_options(
+                tenant_id=tenant_id,
+                page=query.page,
+                limit=query.limit,
+                keyword=query.keyword,
+                app_id=query.app_id,
+            ),
         )
 
 
 @console_ns.route("/agents/<uuid:agent_id>")
 class AgentRosterDetailApi(Resource):
+    @console_ns.response(200, "Agent detail", console_ns.models[AgentRosterResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     def get(self, agent_id: UUID):
         _, tenant_id = current_account_with_tenant()
-        return _agent_roster_service().get_roster_agent_detail(tenant_id=tenant_id, agent_id=str(agent_id))
+        return dump_response(
+            AgentRosterResponse,
+            _agent_roster_service().get_roster_agent_detail(tenant_id=tenant_id, agent_id=str(agent_id)),
+        )
 
     @console_ns.expect(console_ns.models[RosterAgentUpdatePayload.__name__])
+    @console_ns.response(200, "Agent updated", console_ns.models[AgentRosterResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -94,10 +129,14 @@ class AgentRosterDetailApi(Resource):
     def patch(self, agent_id: UUID):
         account, tenant_id = current_account_with_tenant()
         payload = RosterAgentUpdatePayload.model_validate(console_ns.payload or {})
-        return _agent_roster_service().update_roster_agent(
-            tenant_id=tenant_id, agent_id=str(agent_id), account_id=account.id, payload=payload
+        return dump_response(
+            AgentRosterResponse,
+            _agent_roster_service().update_roster_agent(
+                tenant_id=tenant_id, agent_id=str(agent_id), account_id=account.id, payload=payload
+            ),
         )
 
+    @console_ns.response(204, "Agent archived")
     @setup_required
     @login_required
     @account_initialization_required
@@ -110,23 +149,31 @@ class AgentRosterDetailApi(Resource):
 
 @console_ns.route("/agents/<uuid:agent_id>/versions")
 class AgentRosterVersionsApi(Resource):
+    @console_ns.response(200, "Agent versions", console_ns.models[AgentConfigSnapshotListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     def get(self, agent_id: UUID):
         _, tenant_id = current_account_with_tenant()
-        return {"data": _agent_roster_service().list_agent_versions(tenant_id=tenant_id, agent_id=str(agent_id))}
+        return dump_response(
+            AgentConfigSnapshotListResponse,
+            {"data": _agent_roster_service().list_agent_versions(tenant_id=tenant_id, agent_id=str(agent_id))},
+        )
 
 
 @console_ns.route("/agents/<uuid:agent_id>/versions/<uuid:version_id>")
 class AgentRosterVersionDetailApi(Resource):
+    @console_ns.response(200, "Agent version detail", console_ns.models[AgentConfigSnapshotDetailResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     def get(self, agent_id: UUID, version_id: UUID):
         _, tenant_id = current_account_with_tenant()
-        return _agent_roster_service().get_agent_version_detail(
-            tenant_id=tenant_id,
-            agent_id=str(agent_id),
-            version_id=str(version_id),
+        return dump_response(
+            AgentConfigSnapshotDetailResponse,
+            _agent_roster_service().get_agent_version_detail(
+                tenant_id=tenant_id,
+                agent_id=str(agent_id),
+                version_id=str(version_id),
+            ),
         )

api/controllers/console/app/app.py

@@ -467,7 +467,8 @@ class AppListApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def get(self):
+    @with_session(write=False)
+    def get(self, session: Session):
         """Get app list"""
         current_user, current_tenant_id = current_account_with_tenant()
 
@@ -504,7 +505,7 @@ class AppListApi(Resource):
         draft_trigger_app_ids: set[str] = set()
         if workflow_capable_app_ids:
             draft_workflows = (
-                db.session.execute(
+                session.execute(
                     select(Workflow).where(
                         Workflow.version == Workflow.VERSION_DRAFT,
                         Workflow.app_id.in_(workflow_capable_app_ids),

api/controllers/console/app/app_import.py

@@ -9,9 +9,11 @@ from controllers.console.wraps import (
     cloud_edition_billing_resource_check,
     edit_permission_required,
     setup_required,
+    with_current_user,
 )
 from extensions.ext_database import db
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models.account import Account
 from models.model import App
 from services.app_dsl_service import AppDslService, Import
 from services.enterprise.enterprise_service import EnterpriseService
@@ -48,9 +50,9 @@ class AppImportApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
-    def post(self):
+    @with_current_user
+    def post(self, current_user: Account):
         # Check user role first
-        current_user, _ = current_account_with_tenant()
         args = AppImportPayload.model_validate(console_ns.payload)
 
         # AppDslService performs internal commits for some creation paths, so use a plain
@@ -97,10 +99,9 @@ class AppImportConfirmApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self, import_id: str):
+    @with_current_user
+    def post(self, current_user: Account, import_id: str):
         # Check user role first
-        current_user, _ = current_account_with_tenant()
-
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)
             # Confirm import

api/controllers/console/app/conversation.py

@@ -12,7 +12,12 @@ from werkzeug.exceptions import NotFound
 from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+    with_current_user,
+)
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
 from fields.conversation_fields import (
@@ -31,8 +36,9 @@ from fields.conversation_fields import (
     ConversationWithSummaryPagination as ConversationWithSummaryPaginationResponse,
 )
 from libs.datetime_utils import naive_utc_now, parse_time_range
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
 from models import Conversation, EndUser, Message, MessageAnnotation
+from models.account import Account
 from models.model import App, AppMode
 from services.conversation_service import ConversationService
 from services.errors.conversation import ConversationNotExistsError
@@ -93,8 +99,8 @@ class CompletionConversationApi(Resource):
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
-    def get(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, app_model: App):
         args = CompletionConversationQuery.model_validate(request.args.to_dict(flat=True))
 
         query = sa.select(Conversation).where(
@@ -165,10 +171,11 @@ class CompletionConversationDetailApi(Resource):
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
-    def get(self, app_model: App, conversation_id: UUID):
+    @with_current_user
+    def get(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return ConversationMessageDetailResponse.model_validate(
-            _get_conversation(app_model, conversation_id_str), from_attributes=True
+            _get_conversation(current_user, app_model, conversation_id_str), from_attributes=True
         ).model_dump(mode="json")
 
     @console_ns.doc("delete_completion_conversation")
@@ -182,8 +189,8 @@ class CompletionConversationDetailApi(Resource):
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
-    def delete(self, app_model: App, conversation_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 
         try:
@@ -207,8 +214,8 @@ class ChatConversationApi(Resource):
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
     @edit_permission_required
-    def get(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, app_model: App):
         args = ChatConversationQuery.model_validate(request.args.to_dict(flat=True))
 
         subquery = (
@@ -318,10 +325,11 @@ class ChatConversationDetailApi(Resource):
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
     @edit_permission_required
-    def get(self, app_model: App, conversation_id: UUID):
+    @with_current_user
+    def get(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return ConversationDetailResponse.model_validate(
-            _get_conversation(app_model, conversation_id_str), from_attributes=True
+            _get_conversation(current_user, app_model, conversation_id_str), from_attributes=True
         ).model_dump(mode="json")
 
     @console_ns.doc("delete_chat_conversation")
@@ -335,8 +343,8 @@ class ChatConversationDetailApi(Resource):
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
     @account_initialization_required
     @edit_permission_required
-    def delete(self, app_model: App, conversation_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 
         try:
@@ -347,8 +355,7 @@ class ChatConversationDetailApi(Resource):
         return "", 204
 
 
-def _get_conversation(app_model, conversation_id):
-    current_user, _ = current_account_with_tenant()
+def _get_conversation(current_user: Account, app_model, conversation_id):
     conversation = db.session.scalar(
         sa.select(Conversation).where(Conversation.id == conversation_id, Conversation.app_id == app_model.id).limit(1)
     )

api/controllers/console/app/generator.py

@@ -2,6 +2,7 @@ from collections.abc import Sequence
 
 from flask_restx import Resource
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import register_enum_models, register_schema_models
 from controllers.console import console_ns
@@ -11,6 +12,7 @@ from controllers.console.app.error import (
     ProviderNotInitializeError,
     ProviderQuotaExceededError,
 )
+from controllers.console.app.wraps import with_session
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_tenant_id
 from core.app.app_config.entities import ModelConfig
 from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
@@ -19,7 +21,6 @@ from core.helper.code_executor.javascript.javascript_code_provider import Javasc
 from core.helper.code_executor.python3.python3_code_provider import Python3CodeProvider
 from core.llm_generator.entities import RuleCodeGeneratePayload, RuleGeneratePayload, RuleStructuredOutputPayload
 from core.llm_generator.llm_generator import LLMGenerator
-from extensions.ext_database import db
 from graphon.model_runtime.entities.llm_entities import LLMMode
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.login import login_required
@@ -158,7 +159,8 @@ class InstructionGenerateApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    def post(self, current_tenant_id: str):
+    @with_session(write=False)
+    def post(self, session: Session, current_tenant_id: str):
         args = InstructionGeneratePayload.model_validate(console_ns.payload)
         providers: list[type[CodeNodeProvider]] = [Python3CodeProvider, JavascriptCodeProvider]
         code_provider: type[CodeNodeProvider] | None = next(
@@ -168,10 +170,10 @@ class InstructionGenerateApi(Resource):
         try:
             # Generate from nothing for a workflow node
             if (args.current in (code_template, "")) and args.node_id != "":
-                app = db.session.get(App, args.flow_id)
+                app = session.get(App, args.flow_id)
                 if not app:
                     return {"error": f"app {args.flow_id} not found"}, 400
-                workflow = WorkflowService().get_draft_workflow(app_model=app)
+                workflow = WorkflowService().get_draft_workflow(app_model=app, session=session)
                 if not workflow:
                     return {"error": f"workflow {args.flow_id} not found"}, 400
                 nodes: Sequence = workflow.graph_dict["nodes"]

api/controllers/console/app/message.py

@@ -25,6 +25,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_user,
 )
 from core.app.entities.app_invoke_entities import InvokeFrom
 from core.entities.execution_extra_content import ExecutionExtraContentDomainModel
@@ -43,7 +44,8 @@ from fields.conversation_fields import (
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.helper import to_timestamp, uuid_value
 from libs.infinite_scroll_pagination import InfiniteScrollPagination
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models.account import Account
 from models.enums import FeedbackFromSource, FeedbackRating
 from models.model import App, AppMode, Conversation, Message, MessageAnnotation, MessageFeedback
 from services.errors.conversation import ConversationNotExistsError
@@ -257,9 +259,8 @@ class MessageFeedbackApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
-
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
         args = MessageFeedbackPayload.model_validate(console_ns.payload)
 
         message_id = str(args.message_id)
@@ -337,8 +338,8 @@ class MessageSuggestedQuestionApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
-    def get(self, app_model: App, message_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, app_model: App, message_id: UUID):
         message_id_str = str(message_id)
 
         try:

api/controllers/console/app/site.py

@@ -14,12 +14,14 @@ from controllers.console.wraps import (
     edit_permission_required,
     is_admin_or_owner_required,
     setup_required,
+    with_current_user,
 )
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.datetime_utils import naive_utc_now
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
 from models import Site
+from models.account import Account
 from models.model import App
 
 
@@ -85,9 +87,9 @@ class AppSite(Resource):
     @edit_permission_required
     @account_initialization_required
     @get_app_model
-    def post(self, app_model: App):
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
         args = AppSiteUpdatePayload.model_validate(console_ns.payload or {})
-        current_user, _ = current_account_with_tenant()
         site = db.session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
         if not site:
             raise NotFound
@@ -134,8 +136,8 @@ class AppSiteAccessTokenReset(Resource):
     @is_admin_or_owner_required
     @account_initialization_required
     @get_app_model
-    def post(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
         site = db.session.scalar(select(Site).where(Site.app_id == app_model.id).limit(1))
 
         if not site:

api/controllers/console/app/statistic.py

@@ -8,13 +8,14 @@ from pydantic import BaseModel, Field, field_validator
 from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
 from libs.datetime_utils import parse_time_range
 from libs.helper import convert_datetime_to_date
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
 from models import AppMode
+from models.account import Account
 from models.model import App
 
 
@@ -48,9 +49,8 @@ class DailyMessageStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("created_at")
@@ -109,9 +109,8 @@ class DailyConversationStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("created_at")
@@ -169,9 +168,8 @@ class DailyTerminalsStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("created_at")
@@ -230,9 +228,8 @@ class DailyTokenCostStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("created_at")
@@ -294,9 +291,8 @@ class AverageSessionInteractionStatistic(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("c.created_at")
@@ -374,9 +370,8 @@ class UserSatisfactionRateStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("m.created_at")
@@ -444,9 +439,8 @@ class AverageResponseTimeStatistic(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("created_at")
@@ -505,8 +499,8 @@ class TokensPerSecondStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = StatisticTimeRangeQuery.model_validate(request.args.to_dict(flat=True))
 
         converted_created_at = convert_datetime_to_date("created_at")

api/controllers/console/app/workflow_statistic.py

@@ -6,10 +6,11 @@ from sqlalchemy.orm import sessionmaker
 from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from extensions.ext_database import db
 from libs.datetime_utils import parse_time_range
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models.account import Account
 from models.enums import WorkflowRunTriggeredFrom
 from models.model import App, AppMode
 from repositories.factory import DifyAPIRepositoryFactory
@@ -46,9 +47,8 @@ class WorkflowDailyRunsStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = WorkflowStatisticQuery.model_validate(request.args.to_dict(flat=True))
 
         assert account.timezone is not None
@@ -86,9 +86,8 @@ class WorkflowDailyTerminalsStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = WorkflowStatisticQuery.model_validate(request.args.to_dict(flat=True))
 
         assert account.timezone is not None
@@ -126,9 +125,8 @@ class WorkflowDailyTokenCostStatistic(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = WorkflowStatisticQuery.model_validate(request.args.to_dict(flat=True))
 
         assert account.timezone is not None
@@ -166,9 +164,8 @@ class WorkflowAverageAppInteractionStatistic(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
-    def get(self, app_model: App):
-        account, _ = current_account_with_tenant()
-
+    @with_current_user
+    def get(self, account: Account, app_model: App):
         args = WorkflowStatisticQuery.model_validate(request.args.to_dict(flat=True))
 
         assert account.timezone is not None

api/controllers/console/auth/login.py

@@ -32,11 +32,11 @@ from controllers.console.wraps import (
     decrypt_password_field,
     email_password_login_enabled,
     setup_required,
+    with_current_user,
 )
 from events.tenant_event import tenant_was_created
 from libs.helper import EmailStr, extract_remote_ip
 from libs.helper import timezone as validate_timezone_string
-from libs.login import current_account_with_tenant
 from libs.token import (
     clear_access_token_from_cookie,
     clear_csrf_token_from_cookie,
@@ -46,6 +46,7 @@ from libs.token import (
     set_csrf_token_to_cookie,
     set_refresh_token_to_cookie,
 )
+from models.account import Account
 from services.account_service import AccountService, InvitationDetailDict, RegisterService, TenantService
 from services.billing_service import BillingService
 from services.entities.auth_entities import LoginFailureReason, LoginPayloadBase
@@ -172,9 +173,8 @@ class LoginApi(Resource):
 class LogoutApi(Resource):
     @setup_required
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self):
-        current_user, _ = current_account_with_tenant()
-        account = current_user
+    @with_current_user
+    def post(self, account: Account):
         if isinstance(account, flask_login.AnonymousUserMixin):
             response = make_response({"result": "success"})
         else:

api/controllers/console/datasets/datasets_document.py

@@ -9,7 +9,7 @@ from uuid import UUID
 
 import sqlalchemy as sa
 from flask import request, send_file
-from flask_restx import Resource, marshal
+from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import asc, desc, func, select
 from werkzeug.exceptions import Forbidden, NotFound
@@ -34,14 +34,16 @@ from core.rag.index_processor.constant.index_type import IndexTechniqueType
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from fields.document_fields import (
-    document_fields,
-    document_status_fields,
-    document_with_segments_fields,
+    DocumentMetadataResponse,
+    DocumentResponse,
+    DocumentStatusListResponse,
+    DocumentStatusResponse,
+    normalize_enum,
 )
 from graphon.model_runtime.entities.model_entities import ModelType
 from graphon.model_runtime.errors.invoke import InvokeAuthorizationError
 from libs.datetime_utils import naive_utc_now
-from libs.helper import to_timestamp
+from libs.helper import dump_response, to_timestamp
 from libs.login import current_account_with_tenant, login_required
 from models import DatasetProcessRule, Document, DocumentSegment, UploadFile
 from models.dataset import DocumentPipelineExecutionLog
@@ -74,12 +76,6 @@ from ..wraps import (
 logger = logging.getLogger(__name__)
 
 
-def _normalize_enum(value: Any) -> Any:
-    if isinstance(value, str) or value is None:
-        return value
-    return getattr(value, "value", value)
-
-
 class DatasetResponse(ResponseModel):
     id: str
     name: str
@@ -93,7 +89,7 @@ class DatasetResponse(ResponseModel):
     @field_validator("data_source_type", "indexing_technique", mode="before")
     @classmethod
     def _normalize_enum_fields(cls, value: Any) -> Any:
-        return _normalize_enum(value)
+        return normalize_enum(value)
 
     @field_validator("created_at", mode="before")
     @classmethod
@@ -101,61 +97,10 @@ class DatasetResponse(ResponseModel):
         return to_timestamp(value)
 
 
-class DocumentMetadataResponse(ResponseModel):
-    id: str
-    name: str
-    type: str
-    value: str | None = None
-
-
-class DocumentResponse(ResponseModel):
-    id: str
-    position: int | None = None
-    data_source_type: str | None = None
-    data_source_info: Any = Field(default=None, validation_alias="data_source_info_dict")
-    data_source_detail_dict: Any = None
-    dataset_process_rule_id: str | None = None
-    name: str
-    created_from: str | None = None
-    created_by: str | None = None
-    created_at: int | None = None
-    tokens: int | None = None
-    indexing_status: str | None = None
-    error: str | None = None
-    enabled: bool | None = None
-    disabled_at: int | None = None
-    disabled_by: str | None = None
-    archived: bool | None = None
-    display_status: str | None = None
-    word_count: int | None = None
-    hit_count: int | None = None
-    doc_form: str | None = None
-    doc_metadata: list[DocumentMetadataResponse] = Field(default_factory=list, validation_alias="doc_metadata_details")
-    summary_index_status: str | None = None
-    need_summary: bool | None = None
-
-    @field_validator("data_source_type", "indexing_status", "display_status", "doc_form", mode="before")
-    @classmethod
-    def _normalize_enum_fields(cls, value: Any) -> Any:
-        return _normalize_enum(value)
-
-    @field_validator("doc_metadata", mode="before")
-    @classmethod
-    def _normalize_doc_metadata(cls, value: Any) -> list[Any]:
-        if value is None:
-            return []
-        return value
-
-    @field_validator("created_at", "disabled_at", mode="before")
-    @classmethod
-    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
-        return to_timestamp(value)
-
-
 class DocumentWithSegmentsResponse(DocumentResponse):
     process_rule_dict: Any = None
-    completed_segments: int | None = None
-    total_segments: int | None = None
+    completed_segments: int | None = Field(default=None, exclude_if=lambda value: value is None)
+    total_segments: int | None = Field(default=None, exclude_if=lambda value: value is None)
 
 
 class DatasetAndDocumentResponse(ResponseModel):
@@ -190,6 +135,14 @@ class DocumentDatasetListParam(BaseModel):
     fetch_val: str = Field("false", alias="fetch")
 
 
+class DocumentWithSegmentsListResponse(ResponseModel):
+    data: list[DocumentWithSegmentsResponse]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
 register_schema_models(
     console_ns,
     KnowledgeConfig,
@@ -200,13 +153,19 @@ register_schema_models(
     GenerateSummaryPayload,
     DocumentMetadataUpdatePayload,
     DocumentBatchDownloadZipPayload,
+)
+register_response_schema_models(
+    console_ns,
+    SimpleResultMessageResponse,
+    SimpleResultResponse,
+    UrlResponse,
     DatasetResponse,
     DocumentMetadataResponse,
     DocumentResponse,
     DocumentWithSegmentsResponse,
     DatasetAndDocumentResponse,
+    DocumentWithSegmentsListResponse,
 )
-register_response_schema_models(console_ns, SimpleResultMessageResponse, SimpleResultResponse, UrlResponse)
 
 
 class DocumentResource(Resource):
@@ -312,7 +271,11 @@ class DatasetDocumentListApi(Resource):
             "status": "Filter documents by display status",
         }
     )
-    @console_ns.response(200, "Documents retrieved successfully")
+    @console_ns.response(
+        200,
+        "Documents retrieved successfully",
+        console_ns.models[DocumentWithSegmentsListResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -425,18 +388,15 @@ class DatasetDocumentListApi(Resource):
                 )
                 document.completed_segments = completed_segments
                 document.total_segments = total_segments
-            data = marshal(documents, document_with_segments_fields)
-        else:
-            data = marshal(documents, document_fields)
         response = {
-            "data": data,
+            "data": documents,
             "has_more": len(documents) == limit,
             "limit": limit,
             "total": paginated_documents.total,
             "page": page,
         }
 
-        return response
+        return dump_response(DocumentWithSegmentsListResponse, response)
 
     @setup_required
     @login_required
@@ -482,9 +442,7 @@ class DatasetDocumentListApi(Resource):
         except ModelCurrentlyNotSupportError:
             raise ProviderModelCurrentlyNotSupportError()
 
-        return DatasetAndDocumentResponse.model_validate(
-            {"dataset": dataset, "documents": documents, "batch": batch}, from_attributes=True
-        ).model_dump(mode="json")
+        return dump_response(DatasetAndDocumentResponse, {"dataset": dataset, "documents": documents, "batch": batch})
 
     @setup_required
     @login_required
@@ -567,9 +525,7 @@ class DatasetInitApi(Resource):
         except ModelCurrentlyNotSupportError:
             raise ProviderModelCurrentlyNotSupportError()
 
-        return DatasetAndDocumentResponse.model_validate(
-            {"dataset": dataset, "documents": documents, "batch": batch}, from_attributes=True
-        ).model_dump(mode="json")
+        return dump_response(DatasetAndDocumentResponse, {"dataset": dataset, "documents": documents, "batch": batch})
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/indexing-estimate")
@@ -742,6 +698,9 @@ class DocumentBatchIndexingEstimateApi(DocumentResource):
 
 @console_ns.route("/datasets/<uuid:dataset_id>/batch/<string:batch>/indexing-status")
 class DocumentBatchIndexingStatusApi(DocumentResource):
+    @console_ns.response(
+        200, "Indexing status retrieved successfully", console_ns.models[DocumentStatusListResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -784,9 +743,8 @@ class DocumentBatchIndexingStatusApi(DocumentResource):
                 "completed_segments": completed_segments,
                 "total_segments": total_segments,
             }
-            documents_status.append(marshal(document_dict, document_status_fields))
-        data = {"data": documents_status}
-        return data
+            documents_status.append(document_dict)
+        return dump_response(DocumentStatusListResponse, {"data": documents_status})
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/indexing-status")
@@ -794,7 +752,9 @@ class DocumentIndexingStatusApi(DocumentResource):
     @console_ns.doc("get_document_indexing_status")
     @console_ns.doc(description="Get document indexing status")
     @console_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
-    @console_ns.response(200, "Indexing status retrieved successfully")
+    @console_ns.response(
+        200, "Indexing status retrieved successfully", console_ns.models[DocumentStatusResponse.__name__]
+    )
     @console_ns.response(404, "Document not found")
     @setup_required
     @login_required
@@ -839,7 +799,7 @@ class DocumentIndexingStatusApi(DocumentResource):
             "completed_segments": completed_segments,
             "total_segments": total_segments,
         }
-        return marshal(document_dict, document_status_fields)
+        return dump_response(DocumentStatusResponse, document_dict)
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>")
@@ -1304,7 +1264,7 @@ class DocumentRenameApi(DocumentResource):
         except services.errors.document.DocumentIndexingError:
             raise DocumentIndexingError("Cannot delete document during indexing.")
 
-        return DocumentResponse.model_validate(document, from_attributes=True).model_dump(mode="json")
+        return dump_response(DocumentResponse, document)
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/website-sync")

api/controllers/console/datasets/datasets_segments.py

@@ -1,11 +1,12 @@
 import uuid
 from typing import Literal
+from typing import cast as type_cast
 from uuid import UUID
 
 from flask import request
-from flask_restx import Resource, marshal
+from flask_restx import Resource
 from pydantic import BaseModel, Field
-from sqlalchemy import String, cast, func, or_, select
+from sqlalchemy import String, case, cast, func, literal, or_, select
 from sqlalchemy.dialects.postgresql import JSONB
 from werkzeug.exceptions import Forbidden, NotFound
 
@@ -13,7 +14,12 @@ import services
 from configs import dify_config
 from controllers.common.controller_schemas import ChildChunkCreatePayload, ChildChunkUpdatePayload
 from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.app.error import ProviderNotInitializeError
 from controllers.console.datasets.error import (
@@ -34,9 +40,17 @@ from core.rag.index_processor.constant.index_type import IndexTechniqueType
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from fields.base import ResponseModel
-from fields.segment_fields import child_chunk_fields, segment_fields
+from fields.segment_fields import (
+    ChildChunkDetailResponse,
+    ChildChunkListResponse,
+    ChildChunkResponse,
+    SegmentDetailResponse,
+    SegmentResponse,
+    segment_response_with_summary,
+    segment_responses_with_summaries,
+)
 from graphon.model_runtime.entities.model_entities import ModelType
-from libs.helper import escape_like_pattern
+from libs.helper import dump_response, escape_like_pattern
 from libs.login import current_account_with_tenant, login_required
 from models.dataset import ChildChunk, DocumentSegment
 from models.model import UploadFile
@@ -44,20 +58,10 @@ from services.dataset_service import DatasetService, DocumentService, SegmentSer
 from services.entities.knowledge_entities.knowledge_entities import ChildChunkUpdateArgs, SegmentUpdateArgs
 from services.errors.chunk import ChildChunkDeleteIndexError as ChildChunkDeleteIndexServiceError
 from services.errors.chunk import ChildChunkIndexingError as ChildChunkIndexingServiceError
+from services.summary_index_service import SummaryIndexService
 from tasks.batch_create_segment_to_index_task import batch_create_segment_to_index_task
 
 
-def _get_segment_with_summary(segment, dataset_id):
-    """Helper function to marshal segment and add summary information."""
-    from services.summary_index_service import SummaryIndexService
-
-    segment_dict = dict(marshal(segment, segment_fields))  # type: ignore
-    # Query summary for this segment (only enabled summaries)
-    summary = SummaryIndexService.get_segment_summary(segment_id=segment.id, dataset_id=dataset_id)
-    segment_dict["summary"] = summary.summary_content if summary else None
-    return segment_dict
-
-
 class SegmentListQuery(BaseModel):
     limit: int = Field(default=20, ge=1, le=100)
     status: list[str] = Field(default_factory=list)
@@ -67,6 +71,16 @@ class SegmentListQuery(BaseModel):
     page: int = Field(default=1, ge=1)
 
 
+class SegmentIdListQuery(BaseModel):
+    segment_id: list[str] = Field(default_factory=list, description="Segment IDs")
+
+
+class ChildChunkListQuery(BaseModel):
+    limit: int = Field(default=20, ge=1, le=100)
+    keyword: str | None = None
+    page: int = Field(default=1, ge=1)
+
+
 class SegmentCreatePayload(BaseModel):
     content: str
     answer: str | None = None
@@ -92,13 +106,35 @@ class SegmentBatchImportStatusResponse(ResponseModel):
     job_status: str
 
 
+class ConsoleSegmentListResponse(ResponseModel):
+    data: list[SegmentResponse]
+    limit: int
+    total: int
+    total_pages: int
+    page: int
+
+
+class ChildChunkBatchUpdateResponse(ResponseModel):
+    data: list[ChildChunkResponse]
+
+
 class ChildChunkBatchUpdatePayload(BaseModel):
     chunks: list[ChildChunkUpdateArgs]
 
 
+class SegmentDocParams:
+    DATASET_DOCUMENT = {"dataset_id": "Dataset ID", "document_id": "Document ID"}
+    DATASET_DOCUMENT_ACTION = {**DATASET_DOCUMENT, "action": "Action"}
+    DATASET_DOCUMENT_SEGMENT = {**DATASET_DOCUMENT, "segment_id": "Segment ID"}
+    DATASET_DOCUMENT_PARENT_SEGMENT = {**DATASET_DOCUMENT, "segment_id": "Parent segment ID"}
+    DATASET_DOCUMENT_CHILD_CHUNK = {**DATASET_DOCUMENT_PARENT_SEGMENT, "child_chunk_id": "Child chunk ID"}
+
+
 register_schema_models(
     console_ns,
     SegmentListQuery,
+    SegmentIdListQuery,
+    ChildChunkListQuery,
     SegmentCreatePayload,
     SegmentUpdatePayload,
     BatchImportPayload,
@@ -107,11 +143,24 @@ register_schema_models(
     ChildChunkBatchUpdatePayload,
     ChildChunkUpdateArgs,
 )
-register_response_schema_models(console_ns, SegmentBatchImportStatusResponse, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    SegmentResponse,
+    ConsoleSegmentListResponse,
+    SegmentDetailResponse,
+    ChildChunkDetailResponse,
+    ChildChunkListResponse,
+    ChildChunkBatchUpdateResponse,
+    SegmentBatchImportStatusResponse,
+    SimpleResultResponse,
+)
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments")
 class DatasetDocumentSegmentListApi(Resource):
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
+    @console_ns.doc(params=query_params_from_model(SegmentListQuery))
+    @console_ns.response(200, "Segments retrieved successfully", console_ns.models[ConsoleSegmentListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -134,12 +183,7 @@ class DatasetDocumentSegmentListApi(Resource):
         if not document:
             raise NotFound("Document not found.")
 
-        args = SegmentListQuery.model_validate(
-            {
-                **request.args.to_dict(),
-                "status": request.args.getlist("status"),
-            }
-        )
+        args = query_params_from_request(SegmentListQuery, list_fields=("status",))
 
         page = args.page
         limit = min(args.limit, 100)
@@ -169,12 +213,17 @@ class DatasetDocumentSegmentListApi(Resource):
             # Use database-specific methods for JSON array search
             if dify_config.SQLALCHEMY_DATABASE_URI_SCHEME == "postgresql":
                 # PostgreSQL: Use jsonb_array_elements_text to properly handle Unicode/Chinese text
-                # Guard with jsonb_typeof to avoid "cannot extract elements from a scalar" error
-                # when keywords is null or a non-array JSON value.
+                # Feed the set-returning function a JSON array in every row. Filtering in
+                # the subquery is not enough because PostgreSQL can still evaluate the
+                # SRF on scalar JSON before applying the predicate.
+                keywords_jsonb = cast(DocumentSegment.keywords, JSONB)
+                keywords_array = case(
+                    (func.jsonb_typeof(keywords_jsonb) == "array", keywords_jsonb),
+                    else_=cast(literal("[]"), JSONB),
+                )
                 keywords_condition = func.array_to_string(
                     func.array(
-                        select(func.jsonb_array_elements_text(cast(DocumentSegment.keywords, JSONB)))
-                        .where(func.jsonb_typeof(cast(DocumentSegment.keywords, JSONB)) == "array")
+                        select(func.jsonb_array_elements_text(keywords_array))
                         .correlate(DocumentSegment)
                         .scalar_subquery()
                     ),
@@ -200,38 +249,30 @@ class DatasetDocumentSegmentListApi(Resource):
 
         segments = db.paginate(select=query, page=page, per_page=limit, max_per_page=100, error_out=False)
 
-        # Query summaries for all segments in this page (batch query for efficiency)
-        segment_ids = [segment.id for segment in segments.items]
-        summaries = {}
+        segment_list = list(segments.items)
+        segment_ids = [segment.id for segment in segment_list]
+        summaries: dict[str, str | None] = {}
         if segment_ids:
-            from services.summary_index_service import SummaryIndexService
-
             summary_records = SummaryIndexService.get_segments_summaries(
                 segment_ids=segment_ids, dataset_id=dataset_id_str
             )
-            # Only include enabled summaries (already filtered by service)
             summaries = {chunk_id: summary.summary_content for chunk_id, summary in summary_records.items()}
 
-        # Add summary to each segment
-        segments_with_summary = []
-        for segment in segments.items:
-            segment_dict = dict(marshal(segment, segment_fields))  # type: ignore
-            segment_dict["summary"] = summaries.get(segment.id)
-            segments_with_summary.append(segment_dict)
-
         response = {
-            "data": segments_with_summary,
+            "data": segment_responses_with_summaries(segment_list, summaries),
             "limit": limit,
             "total": segments.total,
             "total_pages": segments.pages,
             "page": page,
         }
-        return response, 200
+        return dump_response(ConsoleSegmentListResponse, response), 200
 
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
+    @console_ns.doc(params=query_params_from_model(SegmentIdListQuery))
     @console_ns.response(204, "Segments deleted successfully")
     def delete(self, dataset_id: UUID, document_id: UUID):
         current_user, _ = current_account_with_tenant()
@@ -263,6 +304,8 @@ class DatasetDocumentSegmentListApi(Resource):
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segment/<string:action>")
 class DatasetDocumentSegmentApi(Resource):
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_ACTION)
+    @console_ns.doc(params=query_params_from_model(SegmentIdListQuery))
     @setup_required
     @login_required
     @account_initialization_required
@@ -316,11 +359,12 @@ class DatasetDocumentSegmentApi(Resource):
             SegmentService.update_segments_status(segment_ids, action, dataset, document)
         except Exception as e:
             raise InvalidActionError(str(e))
-        return {"result": "success"}, 200
+        return dump_response(SimpleResultResponse, {"result": "success"}), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segment")
 class DatasetDocumentSegmentAddApi(Resource):
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
     @setup_required
     @login_required
     @account_initialization_required
@@ -328,6 +372,7 @@ class DatasetDocumentSegmentAddApi(Resource):
     @cloud_edition_billing_knowledge_limit_check("add_segment")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[SegmentCreatePayload.__name__])
+    @console_ns.response(200, "Segment created successfully", console_ns.models[SegmentDetailResponse.__name__])
     def post(self, dataset_id: UUID, document_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
@@ -367,18 +412,25 @@ class DatasetDocumentSegmentAddApi(Resource):
         payload = SegmentCreatePayload.model_validate(console_ns.payload or {})
         payload_dict = payload.model_dump(exclude_none=True)
         SegmentService.segment_create_args_validate(payload_dict, document)
-        segment = SegmentService.create_segment(payload_dict, document, dataset)
-        return {"data": _get_segment_with_summary(segment, dataset_id_str), "doc_form": document.doc_form}, 200
+        segment = type_cast(DocumentSegment, SegmentService.create_segment(payload_dict, document, dataset))
+        summary = SummaryIndexService.get_segment_summary(segment_id=segment.id, dataset_id=dataset_id_str)
+        response = {
+            "data": segment_response_with_summary(segment, summary.summary_content if summary else None),
+            "doc_form": document.doc_form,
+        }
+        return dump_response(SegmentDetailResponse, response), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>")
 class DatasetDocumentSegmentUpdateApi(Resource):
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[SegmentUpdatePayload.__name__])
+    @console_ns.response(200, "Segment updated successfully", console_ns.models[SegmentDetailResponse.__name__])
     def patch(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
@@ -435,12 +487,18 @@ class DatasetDocumentSegmentUpdateApi(Resource):
         segment = SegmentService.update_segment(
             SegmentUpdateArgs.model_validate(payload.model_dump(exclude_none=True)), segment, document, dataset
         )
-        return {"data": _get_segment_with_summary(segment, dataset_id_str), "doc_form": document.doc_form}, 200
+        summary = SummaryIndexService.get_segment_summary(segment_id=segment.id, dataset_id=dataset_id_str)
+        response = {
+            "data": segment_response_with_summary(segment, summary.summary_content if summary else None),
+            "doc_form": document.doc_form,
+        }
+        return dump_response(SegmentDetailResponse, response), 200
 
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
     @console_ns.response(204, "Segment deleted successfully")
     def delete(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
@@ -518,11 +576,11 @@ class DatasetDocumentSegmentBatchImportApi(Resource):
         try:
             # async job
             job_id = str(uuid.uuid4())
-            indexing_cache_key = f"segment_batch_import_{str(job_id)}"
+            indexing_cache_key = f"segment_batch_import_{job_id}"
             # send batch add segments task
             redis_client.setnx(indexing_cache_key, "waiting")
             batch_create_segment_to_index_task.delay(
-                str(job_id),
+                job_id,
                 upload_file_id,
                 dataset_id_str,
                 document_id_str,
@@ -531,7 +589,7 @@ class DatasetDocumentSegmentBatchImportApi(Resource):
             )
         except Exception as e:
             return {"error": str(e)}, 500
-        return {"job_id": job_id, "job_status": "waiting"}, 200
+        return dump_response(SegmentBatchImportStatusResponse, {"job_id": job_id, "job_status": "waiting"}), 200
 
     @console_ns.response(200, "Batch import status", console_ns.models[SegmentBatchImportStatusResponse.__name__])
     @setup_required
@@ -546,11 +604,13 @@ class DatasetDocumentSegmentBatchImportApi(Resource):
         if cache_result is None:
             raise ValueError("The job does not exist.")
 
-        return {"job_id": job_id, "job_status": cache_result.decode()}, 200
+        response = {"job_id": job_id, "job_status": cache_result.decode()}
+        return dump_response(SegmentBatchImportStatusResponse, response), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks")
 class ChildChunkAddApi(Resource):
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
     @setup_required
     @login_required
     @account_initialization_required
@@ -558,6 +618,7 @@ class ChildChunkAddApi(Resource):
     @cloud_edition_billing_knowledge_limit_check("add_segment")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[ChildChunkCreatePayload.__name__])
+    @console_ns.response(200, "Child chunk created successfully", console_ns.models[ChildChunkDetailResponse.__name__])
     def post(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
@@ -608,8 +669,11 @@ class ChildChunkAddApi(Resource):
             child_chunk = SegmentService.create_child_chunk(payload.content, segment, document, dataset)
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
-        return {"data": marshal(child_chunk, child_chunk_fields)}, 200
+        return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200
 
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
+    @console_ns.doc(params=query_params_from_model(ChildChunkListQuery))
+    @console_ns.response(200, "Child chunks retrieved successfully", console_ns.models[ChildChunkListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -637,13 +701,7 @@ class ChildChunkAddApi(Resource):
         )
         if not segment:
             raise NotFound("Segment not found.")
-        args = SegmentListQuery.model_validate(
-            {
-                "limit": request.args.get("limit", default=20, type=int),
-                "keyword": request.args.get("keyword"),
-                "page": request.args.get("page", default=1, type=int),
-            }
-        )
+        args = query_params_from_request(ChildChunkListQuery, use_defaults_for_malformed_ints=True)
 
         page = args.page
         limit = min(args.limit, 100)
@@ -652,19 +710,27 @@ class ChildChunkAddApi(Resource):
         child_chunks = SegmentService.get_child_chunks(
             segment_id_str, document_id_str, dataset_id_str, page, limit, keyword
         )
-        return {
-            "data": marshal(child_chunks.items, child_chunk_fields),
+        response = {
+            "data": child_chunks.items,
             "total": child_chunks.total,
             "total_pages": child_chunks.pages,
             "page": page,
             "limit": limit,
-        }, 200
+        }
+        return dump_response(ChildChunkListResponse, response), 200
 
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
+    @console_ns.response(
+        200,
+        "Child chunks updated successfully",
+        console_ns.models[ChildChunkBatchUpdateResponse.__name__],
+    )
+    @console_ns.expect(console_ns.models[ChildChunkBatchUpdatePayload.__name__])
     def patch(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
@@ -702,7 +768,7 @@ class ChildChunkAddApi(Resource):
             child_chunks = SegmentService.update_child_chunks(payload.chunks, segment, document, dataset)
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
-        return {"data": marshal(child_chunks, child_chunk_fields)}, 200
+        return dump_response(ChildChunkBatchUpdateResponse, {"data": child_chunks}), 200
 
 
 @console_ns.route(
@@ -713,6 +779,7 @@ class ChildChunkUpdateApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK)
     @console_ns.response(204, "Child chunk deleted successfully")
     def delete(self, dataset_id: UUID, document_id: UUID, segment_id: UUID, child_chunk_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
@@ -743,7 +810,7 @@ class ChildChunkUpdateApi(Resource):
         child_chunk = db.session.scalar(
             select(ChildChunk)
             .where(
-                ChildChunk.id == str(child_chunk_id_str),
+                ChildChunk.id == child_chunk_id_str,
                 ChildChunk.tenant_id == current_tenant_id,
                 ChildChunk.segment_id == segment.id,
                 ChildChunk.document_id == document_id_str,
@@ -770,7 +837,9 @@ class ChildChunkUpdateApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
+    @console_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK)
     @console_ns.expect(console_ns.models[ChildChunkUpdatePayload.__name__])
+    @console_ns.response(200, "Child chunk updated successfully", console_ns.models[ChildChunkDetailResponse.__name__])
     def patch(self, dataset_id: UUID, document_id: UUID, segment_id: UUID, child_chunk_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
@@ -800,7 +869,7 @@ class ChildChunkUpdateApi(Resource):
         child_chunk = db.session.scalar(
             select(ChildChunk)
             .where(
-                ChildChunk.id == str(child_chunk_id_str),
+                ChildChunk.id == child_chunk_id_str,
                 ChildChunk.tenant_id == current_tenant_id,
                 ChildChunk.segment_id == segment.id,
                 ChildChunk.document_id == document_id_str,
@@ -822,4 +891,4 @@ class ChildChunkUpdateApi(Resource):
             child_chunk = SegmentService.update_child_chunk(payload.content, child_chunk, segment, document, dataset)
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
-        return {"data": marshal(child_chunk, child_chunk_fields)}, 200
+        return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200

api/controllers/console/datasets/metadata.py

@@ -7,14 +7,20 @@ from werkzeug.exceptions import NotFound
 from controllers.common.controller_schemas import MetadataUpdatePayload
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
-from controllers.console.wraps import account_initialization_required, enterprise_license_required, setup_required
+from controllers.console.wraps import (
+    account_initialization_required,
+    enterprise_license_required,
+    setup_required,
+    with_current_user,
+)
 from fields.dataset_fields import (
     DatasetMetadataBuiltInFieldsResponse,
     DatasetMetadataListResponse,
     DatasetMetadataResponse,
 )
 from libs.helper import dump_response
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models.account import Account
 from services.dataset_service import DatasetService
 from services.entities.knowledge_entities.knowledge_entities import (
     DocumentMetadataOperation,
@@ -43,8 +49,8 @@ class DatasetMetadataCreateApi(Resource):
     @enterprise_license_required
     @console_ns.response(201, "Metadata created successfully", console_ns.models[DatasetMetadataResponse.__name__])
     @console_ns.expect(console_ns.models[MetadataArgs.__name__])
-    def post(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def post(self, current_user: Account, dataset_id: UUID):
         metadata_args = MetadataArgs.model_validate(console_ns.payload or {})
 
         dataset_id_str = str(dataset_id)
@@ -80,8 +86,8 @@ class DatasetMetadataApi(Resource):
     @enterprise_license_required
     @console_ns.response(200, "Metadata updated successfully", console_ns.models[DatasetMetadataResponse.__name__])
     @console_ns.expect(console_ns.models[MetadataUpdatePayload.__name__])
-    def patch(self, dataset_id: UUID, metadata_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def patch(self, current_user: Account, dataset_id: UUID, metadata_id: UUID):
         payload = MetadataUpdatePayload.model_validate(console_ns.payload or {})
         name = payload.name
 
@@ -100,8 +106,8 @@ class DatasetMetadataApi(Resource):
     @account_initialization_required
     @enterprise_license_required
     @console_ns.response(204, "Metadata deleted successfully")
-    def delete(self, dataset_id: UUID, metadata_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def delete(self, current_user: Account, dataset_id: UUID, metadata_id: UUID):
         dataset_id_str = str(dataset_id)
         metadata_id_str = str(metadata_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -137,8 +143,8 @@ class DatasetMetadataBuiltInFieldActionApi(Resource):
     @account_initialization_required
     @enterprise_license_required
     @console_ns.response(204, "Action completed successfully")
-    def post(self, dataset_id: UUID, action: Literal["enable", "disable"]):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def post(self, current_user: Account, dataset_id: UUID, action: Literal["enable", "disable"]):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -165,8 +171,8 @@ class DocumentMetadataEditApi(Resource):
         204,
         "Documents metadata updated successfully",
     )
-    def post(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def post(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:

api/controllers/console/datasets/rag_pipeline/rag_pipeline_import.py

@@ -10,6 +10,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_user,
 )
 from extensions.ext_database import db
 from fields.rag_pipeline_fields import (
@@ -17,7 +18,8 @@ from fields.rag_pipeline_fields import (
     pipeline_import_check_dependencies_fields,
     pipeline_import_fields,
 )
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models.account import Account
 from models.dataset import Pipeline
 from services.entities.dsl_entities import ImportStatus
 from services.rag_pipeline.rag_pipeline_dsl_service import RagPipelineDslService
@@ -62,9 +64,9 @@ class RagPipelineImportApi(Resource):
     @edit_permission_required
     @marshal_with(pipeline_import_model)
     @console_ns.expect(console_ns.models[RagPipelineImportPayload.__name__])
-    def post(self):
+    @with_current_user
+    def post(self, current_user: Account):
         # Check user role first
-        current_user, _ = current_account_with_tenant()
         payload = RagPipelineImportPayload.model_validate(console_ns.payload or {})
 
         # Use a plain Session so that caught exceptions inside the service
@@ -105,9 +107,8 @@ class RagPipelineImportConfirmApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @marshal_with(pipeline_import_model)
-    def post(self, import_id: str):
-        current_user, _ = current_account_with_tenant()
-
+    @with_current_user
+    def post(self, current_user: Account, import_id: str):
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = RagPipelineDslService(session)
             account = current_user

api/controllers/console/feature.py

@@ -2,13 +2,36 @@ from flask_restx import Resource
 from werkzeug.exceptions import Unauthorized
 
 from controllers.common.schema import register_response_schema_models
+from fields.base import ResponseModel
+from libs.helper import dump_response
 from libs.login import current_user, login_required
-from services.feature_service import FeatureModel, FeatureService, LimitationModel, SystemFeatureModel
+from services.feature_service import (
+    FeatureModel,
+    FeatureService,
+    LimitationModel,
+    SystemFeatureModel,
+)
 
 from . import console_ns
 from .wraps import account_initialization_required, cloud_utm_record, setup_required, with_current_tenant_id
 
-register_response_schema_models(console_ns, FeatureModel, LimitationModel, SystemFeatureModel)
+
+class TrialModelsResponse(ResponseModel):
+    trial_models: list[str]
+
+
+class AppDslVersionResponse(ResponseModel):
+    app_dsl_version: str
+
+
+register_response_schema_models(
+    console_ns,
+    AppDslVersionResponse,
+    FeatureModel,
+    LimitationModel,
+    SystemFeatureModel,
+    TrialModelsResponse,
+)
 
 
 @console_ns.route("/features")
@@ -54,6 +77,43 @@ class FeatureVectorSpaceApi(Resource):
         return FeatureService.get_vector_space(current_tenant_id).model_dump()
 
 
+@console_ns.route("/trial-models")
+class TrialModelsApi(Resource):
+    @console_ns.doc("get_trial_models")
+    @console_ns.doc(description="Get hosted trial model provider configuration")
+    @console_ns.response(
+        200,
+        "Success",
+        console_ns.models[TrialModelsResponse.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def get(self):
+        """Get hosted trial model provider configuration for model-provider pages."""
+        return dump_response(
+            TrialModelsResponse,
+            {"trial_models": FeatureService.get_trial_models()},
+        )
+
+
+@console_ns.route("/app-dsl-version")
+class AppDslVersionApi(Resource):
+    @console_ns.doc("get_app_dsl_version")
+    @console_ns.doc(description="Get current app DSL version")
+    @console_ns.response(
+        200,
+        "Success",
+        console_ns.models[AppDslVersionResponse.__name__],
+    )
+    def get(self):
+        """Get current app DSL version for workflow clipboard compatibility."""
+        return dump_response(
+            AppDslVersionResponse,
+            {"app_dsl_version": FeatureService.get_app_dsl_version()},
+        )
+
+
 @console_ns.route("/system-features")
 class SystemFeatureApi(Resource):
     @console_ns.doc("get_system_features")

api/controllers/console/human_input_form.py

@@ -12,8 +12,9 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
 
 from controllers.common.human_input import HumanInputFormSubmitPayload
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import account_initialization_required, model_validate, setup_required
 from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.apps.advanced_chat.app_generator import AdvancedChatAppGenerator
 from core.app.apps.base_app_generator import BaseAppGenerator
@@ -33,6 +34,8 @@ from services.workflow_event_snapshot_service import build_workflow_event_stream
 
 logger = logging.getLogger(__name__)
 
+register_schema_models(console_ns, HumanInputFormSubmitPayload)
+
 
 def _jsonify_form_definition(form: Form) -> Response:
     payload = form.get_definition().model_dump()
@@ -76,7 +79,9 @@ class ConsoleHumanInputFormApi(Resource):
 
     @account_initialization_required
     @login_required
-    def post(self, form_token: str):
+    @model_validate(HumanInputFormSubmitPayload)
+    @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    def post(self, payload: HumanInputFormSubmitPayload, form_token: str):
         """
         Submit human input form by form token.
 
@@ -90,7 +95,6 @@ class ConsoleHumanInputFormApi(Resource):
             "action": "Approve"
         }
         """
-        payload = HumanInputFormSubmitPayload.model_validate(request.get_json())
         current_user, _ = current_account_with_tenant()
 
         service = HumanInputService(db.engine)

api/controllers/console/snippets/payloads.py

@@ -0,0 +1,160 @@
+import uuid
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class SnippetListQuery(BaseModel):
+    """Query parameters for listing snippets."""
+
+    page: int = Field(default=1, ge=1, le=99999)
+    limit: int = Field(default=20, ge=1, le=100)
+    keyword: str | None = None
+    is_published: bool | None = Field(default=None, description="Filter by published status")
+    creators: list[str] | None = Field(default=None, description="Filter by creator account IDs")
+    tag_ids: list[str] | None = Field(default=None, description="Filter by tag IDs")
+
+    @field_validator("creators", mode="before")
+    @classmethod
+    def parse_creators(cls, value: object) -> list[str] | None:
+        """Normalize creators filter from query string or list input."""
+        return cls._normalize_string_list(value)
+
+    @field_validator("tag_ids", mode="before")
+    @classmethod
+    def parse_tag_ids(cls, value: object) -> list[str] | None:
+        """Normalize and validate tag IDs from query string or list input."""
+        items = cls._normalize_string_list(value)
+        if not items:
+            return None
+        try:
+            return [str(uuid.UUID(item)) for item in items]
+        except ValueError as exc:
+            raise ValueError("Invalid UUID format in tag_ids.") from exc
+
+    @staticmethod
+    def _normalize_string_list(value: object) -> list[str] | None:
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return [item.strip() for item in value.split(",") if item.strip()] or None
+        if isinstance(value, list):
+            return [str(item).strip() for item in value if str(item).strip()] or None
+        return None
+
+
+class IconInfo(BaseModel):
+    """Icon information model."""
+
+    icon: str | None = None
+    icon_type: Literal["emoji", "image"] | None = None
+    icon_background: str | None = None
+    icon_url: str | None = None
+
+
+class InputFieldDefinition(BaseModel):
+    """Input field definition for snippet parameters."""
+
+    default: str | None = None
+    hint: bool | None = None
+    label: str | None = None
+    max_length: int | None = None
+    options: list[str] | None = None
+    placeholder: str | None = None
+    required: bool | None = None
+    type: str | None = None  # e.g., "text-input"
+
+
+class CreateSnippetPayload(BaseModel):
+    """Payload for creating a new snippet."""
+
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=2000)
+    type: Literal["node", "group"] = "node"
+    icon_info: IconInfo | None = None
+    graph: dict[str, Any] | None = None
+    input_fields: list[InputFieldDefinition] | None = Field(default_factory=list)
+
+
+class UpdateSnippetPayload(BaseModel):
+    """Payload for updating a snippet."""
+
+    name: str | None = Field(default=None, min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=2000)
+    icon_info: IconInfo | None = None
+
+
+class SnippetDraftSyncPayload(BaseModel):
+    """Payload for syncing snippet draft workflow."""
+
+    graph: dict[str, Any]
+    hash: str | None = None
+    conversation_variables: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Ignored. Snippet workflows do not persist conversation variables.",
+    )
+    input_fields: list[dict[str, Any]] | None = None
+
+
+class SnippetWorkflowListQuery(BaseModel):
+    """Query parameters for listing snippet published workflows."""
+
+    page: int = Field(default=1, ge=1, le=99999)
+    limit: int = Field(default=10, ge=1, le=100)
+
+
+class WorkflowRunQuery(BaseModel):
+    """Query parameters for workflow runs."""
+
+    last_id: str | None = None
+    limit: int = Field(default=20, ge=1, le=100)
+
+
+class SnippetDraftRunPayload(BaseModel):
+    """Payload for running snippet draft workflow."""
+
+    inputs: dict[str, Any]
+    files: list[dict[str, Any]] | None = None
+
+
+class SnippetDraftNodeRunPayload(BaseModel):
+    """Payload for running a single node in snippet draft workflow."""
+
+    inputs: dict[str, Any]
+    query: str = ""
+    files: list[dict[str, Any]] | None = None
+
+
+class SnippetIterationNodeRunPayload(BaseModel):
+    """Payload for running an iteration node in snippet draft workflow."""
+
+    inputs: dict[str, Any] | None = None
+
+
+class SnippetLoopNodeRunPayload(BaseModel):
+    """Payload for running a loop node in snippet draft workflow."""
+
+    inputs: dict[str, Any] | None = None
+
+
+class PublishWorkflowPayload(BaseModel):
+    """Payload for publishing snippet workflow."""
+
+    knowledge_base_setting: dict[str, Any] | None = None
+
+
+class SnippetImportPayload(BaseModel):
+    """Payload for importing snippet from DSL."""
+
+    mode: str = Field(..., description="Import mode: yaml-content or yaml-url")
+    yaml_content: str | None = Field(default=None, description="YAML content (required for yaml-content mode)")
+    yaml_url: str | None = Field(default=None, description="YAML URL (required for yaml-url mode)")
+    name: str | None = Field(default=None, description="Override snippet name")
+    description: str | None = Field(default=None, description="Override snippet description")
+    snippet_id: str | None = Field(default=None, description="Snippet ID to update (optional)")
+
+
+class IncludeSecretQuery(BaseModel):
+    """Query parameter for including secret variables in export."""
+
+    include_secret: str = Field(default="false", description="Whether to include secret variables")

api/controllers/console/snippets/snippet_workflow.py

@@ -0,0 +1,638 @@
+import logging
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from flask import request
+from flask_restx import Resource
+from pydantic import Field
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
+
+from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.console import console_ns
+from controllers.console.app.error import DraftWorkflowNotExist, DraftWorkflowNotSync
+from controllers.console.app.workflow import (
+    RESTORE_SOURCE_WORKFLOW_MUST_BE_PUBLISHED_MESSAGE,
+    WorkflowPaginationResponse,
+    WorkflowResponse,
+)
+from controllers.console.snippets.payloads import (
+    PublishWorkflowPayload,
+    SnippetDraftNodeRunPayload,
+    SnippetDraftRunPayload,
+    SnippetDraftSyncPayload,
+    SnippetIterationNodeRunPayload,
+    SnippetLoopNodeRunPayload,
+    SnippetWorkflowListQuery,
+    WorkflowRunQuery,
+)
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+)
+from core.app.apps.base_app_queue_manager import AppQueueManager
+from core.app.entities.app_invoke_entities import InvokeFrom
+from extensions.ext_database import db
+from extensions.ext_redis import redis_client
+from fields.workflow_run_fields import (
+    WorkflowRunDetailResponse,
+    WorkflowRunNodeExecutionListResponse,
+    WorkflowRunNodeExecutionResponse,
+    WorkflowRunPaginationResponse,
+)
+from graphon.graph_engine.manager import GraphEngineManager
+from libs import helper
+from libs.helper import TimestampField
+from libs.login import current_account_with_tenant, login_required
+from models.snippet import CustomizedSnippet
+from services.errors.app import IsDraftWorkflowError, WorkflowHashNotEqualError, WorkflowNotFoundError
+from services.snippet_generate_service import SnippetGenerateService
+from services.snippet_service import SnippetService
+
+logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# Register Pydantic models with Swagger
+class SnippetWorkflowResponse(WorkflowResponse):
+    input_fields: list[dict] = Field(default_factory=list)
+
+
+register_schema_models(
+    console_ns,
+    SnippetDraftSyncPayload,
+    SnippetDraftNodeRunPayload,
+    SnippetDraftRunPayload,
+    SnippetIterationNodeRunPayload,
+    SnippetLoopNodeRunPayload,
+    SnippetWorkflowListQuery,
+    WorkflowRunQuery,
+    PublishWorkflowPayload,
+)
+register_response_schema_models(
+    console_ns,
+    SnippetWorkflowResponse,
+    WorkflowPaginationResponse,
+    WorkflowRunPaginationResponse,
+    WorkflowRunDetailResponse,
+    WorkflowRunNodeExecutionListResponse,
+    WorkflowRunNodeExecutionResponse,
+)
+
+
+class SnippetNotFoundError(Exception):
+    """Snippet not found error."""
+
+    pass
+
+
+def get_snippet(view_func: Callable[P, R]):
+    """Decorator to fetch and validate snippet access."""
+
+    @wraps(view_func)
+    def decorated_view(*args: P.args, **kwargs: P.kwargs):
+        if not kwargs.get("snippet_id"):
+            raise ValueError("missing snippet_id in path parameters")
+
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet_id = str(kwargs.get("snippet_id"))
+        del kwargs["snippet_id"]
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=snippet_id,
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        kwargs["snippet"] = snippet
+
+        return view_func(*args, **kwargs)
+
+    return decorated_view
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft")
+class SnippetDraftWorkflowApi(Resource):
+    @console_ns.doc("get_snippet_draft_workflow")
+    @console_ns.response(200, "Draft workflow retrieved successfully", console_ns.models[SnippetWorkflowResponse.__name__])
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get draft workflow for snippet."""
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_draft_workflow(snippet=snippet)
+
+        if not workflow:
+            raise DraftWorkflowNotExist()
+
+        db.session.expunge(workflow)
+        workflow.conversation_variables = []
+        workflow.input_fields = snippet.input_fields_list
+        return SnippetWorkflowResponse.model_validate(workflow, from_attributes=True).model_dump(mode="json")
+
+    @console_ns.doc("sync_snippet_draft_workflow")
+    @console_ns.expect(console_ns.models.get(SnippetDraftSyncPayload.__name__))
+    @console_ns.response(200, "Draft workflow synced successfully")
+    @console_ns.response(400, "Hash mismatch")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet):
+        """Sync draft workflow for snippet."""
+        current_user, _ = current_account_with_tenant()
+
+        payload = SnippetDraftSyncPayload.model_validate(console_ns.payload or {})
+
+        try:
+            snippet_service = SnippetService()
+            workflow = snippet_service.sync_draft_workflow(
+                snippet=snippet,
+                graph=payload.graph,
+                unique_hash=payload.hash,
+                account=current_user,
+                input_fields=payload.input_fields,
+            )
+        except WorkflowHashNotEqualError:
+            raise DraftWorkflowNotSync()
+        except ValueError as e:
+            return {"message": str(e)}, 400
+
+        return {
+            "result": "success",
+            "hash": workflow.unique_hash,
+            "updated_at": TimestampField().format(workflow.updated_at or workflow.created_at),
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/config")
+class SnippetDraftConfigApi(Resource):
+    @console_ns.doc("get_snippet_draft_config")
+    @console_ns.response(200, "Draft config retrieved successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get snippet draft workflow configuration limits."""
+        return {
+            "parallel_depth_limit": 3,
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/publish")
+class SnippetPublishedWorkflowApi(Resource):
+    @console_ns.doc("get_snippet_published_workflow")
+    @console_ns.response(200, "Published workflow retrieved successfully", console_ns.models[SnippetWorkflowResponse.__name__])
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get published workflow for snippet."""
+        if not snippet.is_published:
+            return None
+
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_published_workflow(snippet=snippet)
+
+        if not workflow:
+            return None
+
+        workflow.input_fields = snippet.input_fields_list
+        return SnippetWorkflowResponse.model_validate(workflow, from_attributes=True).model_dump(mode="json")
+
+    @console_ns.doc("publish_snippet_workflow")
+    @console_ns.expect(console_ns.models.get(PublishWorkflowPayload.__name__))
+    @console_ns.response(200, "Workflow published successfully")
+    @console_ns.response(400, "No draft workflow found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet):
+        """Publish snippet workflow."""
+        current_user, _ = current_account_with_tenant()
+        snippet_service = SnippetService()
+
+        with Session(db.engine) as session:
+            snippet = session.merge(snippet)
+            try:
+                workflow = snippet_service.publish_workflow(
+                    session=session,
+                    snippet=snippet,
+                    account=current_user,
+                )
+                workflow_created_at = TimestampField().format(workflow.created_at)
+                session.commit()
+            except ValueError as e:
+                return {"message": str(e)}, 400
+
+        return {
+            "result": "success",
+            "created_at": workflow_created_at,
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/default-workflow-block-configs")
+class SnippetDefaultBlockConfigsApi(Resource):
+    @console_ns.doc("get_snippet_default_block_configs")
+    @console_ns.response(200, "Default block configs retrieved successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get default block configurations for snippet workflow."""
+        snippet_service = SnippetService()
+        return snippet_service.get_default_block_configs()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows")
+class SnippetPublishedAllWorkflowApi(Resource):
+    @console_ns.expect(console_ns.models[SnippetWorkflowListQuery.__name__])
+    @console_ns.doc("get_all_snippet_published_workflows")
+    @console_ns.doc(description="Get all published workflows for a snippet")
+    @console_ns.doc(params={"snippet_id": "Snippet ID"})
+    @console_ns.response(200, "Published workflows retrieved successfully", console_ns.models[WorkflowPaginationResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get all published workflow versions for snippet."""
+        args = SnippetWorkflowListQuery.model_validate(request.args.to_dict(flat=True))
+
+        snippet_service = SnippetService()
+        with Session(db.engine) as session:
+            workflows, has_more = snippet_service.get_all_published_workflows(
+                session=session,
+                snippet=snippet,
+                page=args.page,
+                limit=args.limit,
+            )
+
+        return WorkflowPaginationResponse.model_validate(
+            {
+                "items": workflows,
+                "page": args.page,
+                "limit": args.limit,
+                "has_more": has_more,
+            },
+            from_attributes=True,
+        ).model_dump(mode="json")
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/<string:workflow_id>/restore")
+class SnippetDraftWorkflowRestoreApi(Resource):
+    @console_ns.doc("restore_snippet_workflow_to_draft")
+    @console_ns.doc(description="Restore a published snippet workflow version into the draft workflow")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "workflow_id": "Published workflow ID"})
+    @console_ns.response(200, "Workflow restored successfully")
+    @console_ns.response(400, "Source workflow must be published")
+    @console_ns.response(404, "Workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, workflow_id: str):
+        """Restore a published snippet workflow version into the draft workflow."""
+        current_user, _ = current_account_with_tenant()
+        snippet_service = SnippetService()
+
+        try:
+            workflow = snippet_service.restore_published_workflow_to_draft(
+                snippet=snippet,
+                workflow_id=workflow_id,
+                account=current_user,
+            )
+        except IsDraftWorkflowError as exc:
+            raise BadRequest(RESTORE_SOURCE_WORKFLOW_MUST_BE_PUBLISHED_MESSAGE) from exc
+        except WorkflowNotFoundError as exc:
+            raise NotFound(str(exc)) from exc
+        except ValueError as exc:
+            raise BadRequest(str(exc)) from exc
+
+        return {
+            "result": "success",
+            "hash": workflow.unique_hash,
+            "updated_at": TimestampField().format(workflow.updated_at or workflow.created_at),
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs")
+class SnippetWorkflowRunsApi(Resource):
+    @console_ns.doc("list_snippet_workflow_runs")
+    @console_ns.response(200, "Workflow runs retrieved successfully", console_ns.models[WorkflowRunPaginationResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    def get(self, snippet: CustomizedSnippet):
+        """List workflow runs for snippet."""
+        query = WorkflowRunQuery.model_validate(
+            {
+                "last_id": request.args.get("last_id"),
+                "limit": request.args.get("limit", type=int, default=20),
+            }
+        )
+        args = {
+            "last_id": query.last_id,
+            "limit": query.limit,
+        }
+
+        snippet_service = SnippetService()
+        result = snippet_service.get_snippet_workflow_runs(snippet=snippet, args=args)
+
+        return WorkflowRunPaginationResponse.model_validate(result, from_attributes=True).model_dump(mode="json")
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/<uuid:run_id>")
+class SnippetWorkflowRunDetailApi(Resource):
+    @console_ns.doc("get_snippet_workflow_run_detail")
+    @console_ns.response(200, "Workflow run detail retrieved successfully", console_ns.models[WorkflowRunDetailResponse.__name__])
+    @console_ns.response(404, "Workflow run not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    def get(self, snippet: CustomizedSnippet, run_id):
+        """Get workflow run detail for snippet."""
+        run_id = str(run_id)
+
+        snippet_service = SnippetService()
+        workflow_run = snippet_service.get_snippet_workflow_run(snippet=snippet, run_id=run_id)
+
+        if not workflow_run:
+            raise NotFound("Workflow run not found")
+
+        return WorkflowRunDetailResponse.model_validate(workflow_run, from_attributes=True).model_dump(mode="json")
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/<uuid:run_id>/node-executions")
+class SnippetWorkflowRunNodeExecutionsApi(Resource):
+    @console_ns.doc("list_snippet_workflow_run_node_executions")
+    @console_ns.response(
+        200,
+        "Node executions retrieved successfully",
+        console_ns.models[WorkflowRunNodeExecutionListResponse.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    def get(self, snippet: CustomizedSnippet, run_id):
+        """List node executions for a workflow run."""
+        run_id = str(run_id)
+
+        snippet_service = SnippetService()
+        node_executions = snippet_service.get_snippet_workflow_run_node_executions(
+            snippet=snippet,
+            run_id=run_id,
+        )
+
+        return WorkflowRunNodeExecutionListResponse.model_validate(
+            {"data": node_executions}, from_attributes=True
+        ).model_dump(mode="json")
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/run")
+class SnippetDraftNodeRunApi(Resource):
+    @console_ns.doc("run_snippet_draft_node")
+    @console_ns.doc(description="Run a single node in snippet draft workflow (single-step debugging)")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.expect(console_ns.models.get(SnippetDraftNodeRunPayload.__name__))
+    @console_ns.response(
+        200, "Node run completed successfully", console_ns.models[WorkflowRunNodeExecutionResponse.__name__]
+    )
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Run a single node in snippet draft workflow.
+
+        Executes a specific node with provided inputs for single-step debugging.
+        Returns the node execution result including status, outputs, and timing.
+        """
+        current_user, _ = current_account_with_tenant()
+        payload = SnippetDraftNodeRunPayload.model_validate(console_ns.payload or {})
+
+        user_inputs = payload.inputs
+
+        # Get draft workflow for file parsing
+        snippet_service = SnippetService()
+        draft_workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not draft_workflow:
+            raise NotFound("Draft workflow not found")
+
+        files = SnippetGenerateService.parse_files(draft_workflow, payload.files)
+
+        workflow_node_execution = SnippetGenerateService.run_draft_node(
+            snippet=snippet,
+            node_id=node_id,
+            user_inputs=user_inputs,
+            account=current_user,
+            query=payload.query,
+            files=files,
+        )
+
+        return WorkflowRunNodeExecutionResponse.model_validate(
+            workflow_node_execution, from_attributes=True
+        ).model_dump(mode="json")
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/last-run")
+class SnippetDraftNodeLastRunApi(Resource):
+    @console_ns.doc("get_snippet_draft_node_last_run")
+    @console_ns.doc(description="Get last run result for a node in snippet draft workflow")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.response(
+        200, "Node last run retrieved successfully", console_ns.models[WorkflowRunNodeExecutionResponse.__name__]
+    )
+    @console_ns.response(404, "Snippet, draft workflow, or node last run not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    def get(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Get the last run result for a specific node in snippet draft workflow.
+
+        Returns the most recent execution record for the given node,
+        including status, inputs, outputs, and timing information.
+        """
+        snippet_service = SnippetService()
+        draft_workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not draft_workflow:
+            raise NotFound("Draft workflow not found")
+
+        node_exec = snippet_service.get_snippet_node_last_run(
+            snippet=snippet,
+            workflow=draft_workflow,
+            node_id=node_id,
+        )
+        if node_exec is None:
+            raise NotFound("Node last run not found")
+
+        return WorkflowRunNodeExecutionResponse.model_validate(node_exec, from_attributes=True).model_dump(mode="json")
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/iteration/nodes/<string:node_id>/run")
+class SnippetDraftRunIterationNodeApi(Resource):
+    @console_ns.doc("run_snippet_draft_iteration_node")
+    @console_ns.doc(description="Run draft workflow iteration node for snippet")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.expect(console_ns.models.get(SnippetIterationNodeRunPayload.__name__))
+    @console_ns.response(200, "Iteration node run started successfully (SSE stream)")
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Run a draft workflow iteration node for snippet.
+
+        Iteration nodes execute their internal sub-graph multiple times over an input list.
+        Returns an SSE event stream with iteration progress and results.
+        """
+        current_user, _ = current_account_with_tenant()
+        args = SnippetIterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
+
+        try:
+            response = SnippetGenerateService.generate_single_iteration(
+                snippet=snippet, user=current_user, node_id=node_id, args=args, streaming=True
+            )
+
+            return helper.compact_generate_response(response)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/loop/nodes/<string:node_id>/run")
+class SnippetDraftRunLoopNodeApi(Resource):
+    @console_ns.doc("run_snippet_draft_loop_node")
+    @console_ns.doc(description="Run draft workflow loop node for snippet")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.expect(console_ns.models.get(SnippetLoopNodeRunPayload.__name__))
+    @console_ns.response(200, "Loop node run started successfully (SSE stream)")
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Run a draft workflow loop node for snippet.
+
+        Loop nodes execute their internal sub-graph repeatedly until a condition is met.
+        Returns an SSE event stream with loop progress and results.
+        """
+        current_user, _ = current_account_with_tenant()
+        args = SnippetLoopNodeRunPayload.model_validate(console_ns.payload or {})
+
+        try:
+            response = SnippetGenerateService.generate_single_loop(
+                snippet=snippet, user=current_user, node_id=node_id, args=args, streaming=True
+            )
+
+            return helper.compact_generate_response(response)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/run")
+class SnippetDraftWorkflowRunApi(Resource):
+    @console_ns.doc("run_snippet_draft_workflow")
+    @console_ns.expect(console_ns.models.get(SnippetDraftRunPayload.__name__))
+    @console_ns.response(200, "Draft workflow run started successfully (SSE stream)")
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet):
+        """
+        Run draft workflow for snippet.
+
+        Executes the snippet's draft workflow with the provided inputs
+        and returns an SSE event stream with execution progress and results.
+        """
+        current_user, _ = current_account_with_tenant()
+
+        payload = SnippetDraftRunPayload.model_validate(console_ns.payload or {})
+        args = payload.model_dump(exclude_none=True)
+
+        try:
+            response = SnippetGenerateService.generate(
+                snippet=snippet,
+                user=current_user,
+                args=args,
+                invoke_from=InvokeFrom.DEBUGGER,
+                streaming=True,
+            )
+
+            return helper.compact_generate_response(response)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/tasks/<string:task_id>/stop")
+class SnippetWorkflowTaskStopApi(Resource):
+    @console_ns.doc("stop_snippet_workflow_task")
+    @console_ns.response(200, "Task stopped successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, task_id: str):
+        """
+        Stop a running snippet workflow task.
+
+        Uses both the legacy stop flag mechanism and the graph engine
+        command channel for backward compatibility.
+        """
+        # Stop using both mechanisms for backward compatibility
+        # Legacy stop flag mechanism (without user check)
+        AppQueueManager.set_stop_flag_no_user_check(task_id)
+
+        # New graph engine command channel mechanism
+        GraphEngineManager(redis_client).send_stop_command(task_id)
+
+        return {"result": "success"}

api/controllers/console/snippets/snippet_workflow_draft_variable.py

@@ -0,0 +1,319 @@
+"""
+Snippet draft workflow variable APIs.
+
+Mirrors console app routes under /apps/.../workflows/draft/variables for snippet scope,
+using CustomizedSnippet.id as WorkflowDraftVariable.app_id (same invariant as snippet execution).
+
+Snippet workflows do not expose system variables (`node_id == sys`) or conversation variables
+(`node_id == conversation`): paginated list queries exclude those rows; single-variable GET/PATCH/DELETE/reset
+reject them; `GET .../system-variables` and `GET .../conversation-variables` return empty lists for API parity.
+Other routes mirror `workflow_draft_variable` app APIs under `/snippets/...`.
+"""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, ParamSpec, TypeVar
+
+from flask import Response, request
+from flask_restx import Resource, marshal, marshal_with
+from sqlalchemy.orm import Session
+
+from controllers.console import console_ns
+from controllers.console.app.error import DraftWorkflowNotExist
+from controllers.console.app.workflow_draft_variable import (
+    WorkflowDraftVariableListQuery,
+    WorkflowDraftVariableUpdatePayload,
+    _ensure_variable_access,
+    _file_access_controller,
+    validate_node_id,
+    workflow_draft_variable_list_model,
+    workflow_draft_variable_list_without_value_model,
+    workflow_draft_variable_model,
+)
+from controllers.console.snippets.snippet_workflow import get_snippet
+from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from controllers.web.error import InvalidArgumentError, NotFoundError
+from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
+from extensions.ext_database import db
+from factories.file_factory import build_from_mapping, build_from_mappings
+from factories.variable_factory import build_segment_with_type
+from graphon.variables.types import SegmentType
+from libs.login import current_user, login_required
+from models.snippet import CustomizedSnippet
+from models.workflow import WorkflowDraftVariable
+from services.snippet_service import SnippetService
+from services.workflow_draft_variable_service import WorkflowDraftVariableList, WorkflowDraftVariableService
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+_SNIPPET_EXCLUDED_DRAFT_VARIABLE_NODE_IDS: frozenset[str] = frozenset(
+    {SYSTEM_VARIABLE_NODE_ID, CONVERSATION_VARIABLE_NODE_ID}
+)
+
+
+def _ensure_snippet_draft_variable_row_allowed(
+    *,
+    variable: WorkflowDraftVariable,
+    variable_id: str,
+) -> None:
+    """Snippet scope only supports canvas-node draft variables; treat sys/conversation rows as not found."""
+    if variable.node_id in _SNIPPET_EXCLUDED_DRAFT_VARIABLE_NODE_IDS:
+        raise NotFoundError(description=f"variable not found, id={variable_id}")
+
+
+def _snippet_draft_var_prerequisite(f: Callable[P, R]) -> Callable[P, R]:
+    """Setup, auth, snippet resolution, and tenant edit permission (same stack as snippet workflow APIs)."""
+
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    @wraps(f)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return f(*args, **kwargs)
+
+    return wrapper
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/variables")
+class SnippetWorkflowVariableCollectionApi(Resource):
+    @console_ns.expect(console_ns.models[WorkflowDraftVariableListQuery.__name__])
+    @console_ns.doc("get_snippet_workflow_variables")
+    @console_ns.doc(description="List draft workflow variables without values (paginated, snippet scope)")
+    @console_ns.response(
+        200,
+        "Workflow variables retrieved successfully",
+        workflow_draft_variable_list_without_value_model,
+    )
+    @_snippet_draft_var_prerequisite
+    @marshal_with(workflow_draft_variable_list_without_value_model)
+    def get(self, snippet: CustomizedSnippet) -> WorkflowDraftVariableList:
+        args = WorkflowDraftVariableListQuery.model_validate(request.args.to_dict(flat=True))  # type: ignore
+
+        snippet_service = SnippetService()
+        if snippet_service.get_draft_workflow(snippet=snippet) is None:
+            raise DraftWorkflowNotExist()
+
+        with Session(bind=db.engine, expire_on_commit=False) as session:
+            draft_var_srv = WorkflowDraftVariableService(session=session)
+            workflow_vars = draft_var_srv.list_variables_without_values(
+                app_id=snippet.id,
+                page=args.page,
+                limit=args.limit,
+                user_id=current_user.id,
+                exclude_node_ids=_SNIPPET_EXCLUDED_DRAFT_VARIABLE_NODE_IDS,
+            )
+
+        return workflow_vars
+
+    @console_ns.doc("delete_snippet_workflow_variables")
+    @console_ns.doc(description="Delete all draft workflow variables for the current user (snippet scope)")
+    @console_ns.response(204, "Workflow variables deleted successfully")
+    @_snippet_draft_var_prerequisite
+    def delete(self, snippet: CustomizedSnippet) -> Response:
+        draft_var_srv = WorkflowDraftVariableService(session=db.session())
+        draft_var_srv.delete_user_workflow_variables(snippet.id, user_id=current_user.id)
+        db.session.commit()
+        return Response("", 204)
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/variables")
+class SnippetNodeVariableCollectionApi(Resource):
+    @console_ns.doc("get_snippet_node_variables")
+    @console_ns.doc(description="Get variables for a specific node (snippet draft workflow)")
+    @console_ns.response(200, "Node variables retrieved successfully", workflow_draft_variable_list_model)
+    @_snippet_draft_var_prerequisite
+    @marshal_with(workflow_draft_variable_list_model)
+    def get(self, snippet: CustomizedSnippet, node_id: str) -> WorkflowDraftVariableList:
+        validate_node_id(node_id)
+        with Session(bind=db.engine, expire_on_commit=False) as session:
+            draft_var_srv = WorkflowDraftVariableService(session=session)
+            node_vars = draft_var_srv.list_node_variables(snippet.id, node_id, user_id=current_user.id)
+
+        return node_vars
+
+    @console_ns.doc("delete_snippet_node_variables")
+    @console_ns.doc(description="Delete all variables for a specific node (snippet draft workflow)")
+    @console_ns.response(204, "Node variables deleted successfully")
+    @_snippet_draft_var_prerequisite
+    def delete(self, snippet: CustomizedSnippet, node_id: str) -> Response:
+        validate_node_id(node_id)
+        srv = WorkflowDraftVariableService(db.session())
+        srv.delete_node_variables(snippet.id, node_id, user_id=current_user.id)
+        db.session.commit()
+        return Response("", 204)
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/variables/<uuid:variable_id>")
+class SnippetVariableApi(Resource):
+    @console_ns.doc("get_snippet_workflow_variable")
+    @console_ns.doc(description="Get a specific draft workflow variable (snippet scope)")
+    @console_ns.response(200, "Variable retrieved successfully", workflow_draft_variable_model)
+    @console_ns.response(404, "Variable not found")
+    @_snippet_draft_var_prerequisite
+    @marshal_with(workflow_draft_variable_model)
+    def get(self, snippet: CustomizedSnippet, variable_id: str) -> WorkflowDraftVariable:
+        draft_var_srv = WorkflowDraftVariableService(session=db.session())
+        variable = _ensure_variable_access(
+            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            app_id=snippet.id,
+            variable_id=variable_id,
+        )
+        _ensure_snippet_draft_variable_row_allowed(variable=variable, variable_id=variable_id)
+        return variable
+
+    @console_ns.doc("update_snippet_workflow_variable")
+    @console_ns.doc(description="Update a draft workflow variable (snippet scope)")
+    @console_ns.expect(console_ns.models[WorkflowDraftVariableUpdatePayload.__name__])
+    @console_ns.response(200, "Variable updated successfully", workflow_draft_variable_model)
+    @console_ns.response(404, "Variable not found")
+    @_snippet_draft_var_prerequisite
+    @marshal_with(workflow_draft_variable_model)
+    def patch(self, snippet: CustomizedSnippet, variable_id: str) -> WorkflowDraftVariable:
+        draft_var_srv = WorkflowDraftVariableService(session=db.session())
+        args_model = WorkflowDraftVariableUpdatePayload.model_validate(console_ns.payload or {})
+
+        variable = _ensure_variable_access(
+            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            app_id=snippet.id,
+            variable_id=variable_id,
+        )
+        _ensure_snippet_draft_variable_row_allowed(variable=variable, variable_id=variable_id)
+
+        new_name = args_model.name
+        raw_value = args_model.value
+        if new_name is None and raw_value is None:
+            return variable
+
+        new_value = None
+        if raw_value is not None:
+            if variable.value_type == SegmentType.FILE:
+                if not isinstance(raw_value, dict):
+                    raise InvalidArgumentError(description=f"expected dict for file, got {type(raw_value)}")
+                raw_value = build_from_mapping(
+                    mapping=raw_value,
+                    tenant_id=snippet.tenant_id,
+                    access_controller=_file_access_controller,
+                )
+            elif variable.value_type == SegmentType.ARRAY_FILE:
+                if not isinstance(raw_value, list):
+                    raise InvalidArgumentError(description=f"expected list for files, got {type(raw_value)}")
+                if len(raw_value) > 0 and not isinstance(raw_value[0], dict):
+                    raise InvalidArgumentError(description=f"expected dict for files[0], got {type(raw_value)}")
+                raw_value = build_from_mappings(
+                    mappings=raw_value,
+                    tenant_id=snippet.tenant_id,
+                    access_controller=_file_access_controller,
+                )
+            new_value = build_segment_with_type(variable.value_type, raw_value)
+        draft_var_srv.update_variable(variable, name=new_name, value=new_value)
+        db.session.commit()
+        return variable
+
+    @console_ns.doc("delete_snippet_workflow_variable")
+    @console_ns.doc(description="Delete a draft workflow variable (snippet scope)")
+    @console_ns.response(204, "Variable deleted successfully")
+    @console_ns.response(404, "Variable not found")
+    @_snippet_draft_var_prerequisite
+    def delete(self, snippet: CustomizedSnippet, variable_id: str) -> Response:
+        draft_var_srv = WorkflowDraftVariableService(session=db.session())
+        variable = _ensure_variable_access(
+            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            app_id=snippet.id,
+            variable_id=variable_id,
+        )
+        _ensure_snippet_draft_variable_row_allowed(variable=variable, variable_id=variable_id)
+        draft_var_srv.delete_variable(variable)
+        db.session.commit()
+        return Response("", 204)
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/variables/<uuid:variable_id>/reset")
+class SnippetVariableResetApi(Resource):
+    @console_ns.doc("reset_snippet_workflow_variable")
+    @console_ns.doc(description="Reset a draft workflow variable to its default value (snippet scope)")
+    @console_ns.response(200, "Variable reset successfully", workflow_draft_variable_model)
+    @console_ns.response(204, "Variable reset (no content)")
+    @console_ns.response(404, "Variable not found")
+    @_snippet_draft_var_prerequisite
+    def put(self, snippet: CustomizedSnippet, variable_id: str) -> Response | Any:
+        draft_var_srv = WorkflowDraftVariableService(session=db.session())
+        snippet_service = SnippetService()
+        draft_workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if draft_workflow is None:
+            raise NotFoundError(
+                f"Draft workflow not found, snippet_id={snippet.id}",
+            )
+        variable = _ensure_variable_access(
+            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            app_id=snippet.id,
+            variable_id=variable_id,
+        )
+        _ensure_snippet_draft_variable_row_allowed(variable=variable, variable_id=variable_id)
+
+        resetted = draft_var_srv.reset_variable(draft_workflow, variable)
+        db.session.commit()
+        if resetted is None:
+            return Response("", 204)
+        return marshal(resetted, workflow_draft_variable_model)
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/conversation-variables")
+class SnippetConversationVariableCollectionApi(Resource):
+    @console_ns.doc("get_snippet_conversation_variables")
+    @console_ns.doc(
+        description="Conversation variables are not used in snippet workflows; returns an empty list for API parity"
+    )
+    @console_ns.response(200, "Conversation variables retrieved successfully", workflow_draft_variable_list_model)
+    @_snippet_draft_var_prerequisite
+    @marshal_with(workflow_draft_variable_list_model)
+    def get(self, snippet: CustomizedSnippet) -> WorkflowDraftVariableList:
+        return WorkflowDraftVariableList(variables=[])
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/system-variables")
+class SnippetSystemVariableCollectionApi(Resource):
+    @console_ns.doc("get_snippet_system_variables")
+    @console_ns.doc(
+        description="System variables are not used in snippet workflows; returns an empty list for API parity"
+    )
+    @console_ns.response(200, "System variables retrieved successfully", workflow_draft_variable_list_model)
+    @_snippet_draft_var_prerequisite
+    @marshal_with(workflow_draft_variable_list_model)
+    def get(self, snippet: CustomizedSnippet) -> WorkflowDraftVariableList:
+        return WorkflowDraftVariableList(variables=[])
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/environment-variables")
+class SnippetEnvironmentVariableCollectionApi(Resource):
+    @console_ns.doc("get_snippet_environment_variables")
+    @console_ns.doc(description="Get environment variables from snippet draft workflow graph")
+    @console_ns.response(200, "Environment variables retrieved successfully")
+    @console_ns.response(404, "Draft workflow not found")
+    @_snippet_draft_var_prerequisite
+    def get(self, snippet: CustomizedSnippet) -> dict[str, list[dict[str, Any]]]:
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if workflow is None:
+            raise DraftWorkflowNotExist()
+
+        env_vars_list: list[dict[str, Any]] = []
+        for v in workflow.environment_variables:
+            env_vars_list.append(
+                {
+                    "id": v.id,
+                    "type": "env",
+                    "name": v.name,
+                    "description": v.description,
+                    "selector": v.selector,
+                    "value_type": v.value_type.exposed_type().value,
+                    "value": v.value,
+                    "edited": False,
+                    "visible": True,
+                    "editable": True,
+                }
+            )
+
+        return {"items": env_vars_list}

api/controllers/console/tag/tags.py

@@ -51,7 +51,7 @@ class TagBindingRemovePayload(BaseModel):
 
 
 class TagListQueryParam(BaseModel):
-    type: Literal["knowledge", "app", ""] = Field("", description="Tag type filter")
+    type: Literal["knowledge", "app", "snippet", ""] = Field("", description="Tag type filter")
     keyword: str | None = Field(None, description="Search keyword")
 
 
@@ -96,7 +96,10 @@ class TagListApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.doc(
-        params={"type": 'Tag type filter. Can be "knowledge" or "app".', "keyword": "Search keyword for tag name."}
+        params={
+            "type": 'Tag type filter. Can be "knowledge", "app", or "snippet".',
+            "keyword": "Search keyword for tag name.",
+        }
     )
     @console_ns.doc(responses={200: ("Success", [console_ns.models[TagResponse.__name__]])})
     @with_current_tenant_id

api/controllers/console/workspace/members.py

@@ -25,12 +25,13 @@ from controllers.console.wraps import (
     account_initialization_required,
     is_allow_transfer_owner,
     setup_required,
+    with_current_user,
 )
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from fields.member_fields import AccountWithRole, AccountWithRoleList
 from libs.helper import extract_remote_ip
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
 from models.account import Account, TenantAccountJoin, TenantAccountRole
 from services.account_service import AccountService, RegisterService, TenantService
 from services.errors.account import AccountAlreadyInTenantError
@@ -136,8 +137,8 @@ class MemberListApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[AccountWithRoleList.__name__])
-    def get(self):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account):
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
         members = TenantService.get_tenant_members(current_user.current_tenant)
@@ -154,7 +155,8 @@ class MemberInviteEmailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_user
+    def post(self, current_user: Account):
         payload = console_ns.payload or {}
         args = MemberInvitePayload.model_validate(payload)
 
@@ -163,7 +165,6 @@ class MemberInviteEmailApi(Resource):
         interface_language = args.language
         if not TenantAccountRole.is_non_owner_role(invitee_role):
             return {"code": "invalid-role", "message": "Invalid role"}, 400
-        current_user, _ = current_account_with_tenant()
         inviter = current_user
         if not inviter.current_tenant:
             raise ValueError("No current tenant")
@@ -223,8 +224,8 @@ class MemberCancelInviteApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def delete(self, member_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def delete(self, current_user: Account, member_id: UUID):
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
         member = db.session.get(Account, str(member_id))
@@ -256,14 +257,14 @@ class MemberUpdateRoleApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def put(self, member_id: UUID):
+    @with_current_user
+    def put(self, current_user: Account, member_id: UUID):
         payload = console_ns.payload or {}
         args = MemberRoleUpdatePayload.model_validate(payload)
         new_role = args.role
 
         if not TenantAccountRole.is_valid_role(new_role):
             return {"code": "invalid-role", "message": "Invalid role"}, 400
-        current_user, _ = current_account_with_tenant()
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
         if not _is_role_enabled(new_role, current_user.current_tenant.id):
@@ -297,8 +298,8 @@ class DatasetOperatorMemberListApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[AccountWithRoleList.__name__])
-    def get(self):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account):
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
         members = TenantService.get_dataset_operator_members(current_user.current_tenant)
@@ -317,13 +318,13 @@ class SendOwnerTransferEmailApi(Resource):
     @login_required
     @account_initialization_required
     @is_allow_transfer_owner
-    def post(self):
+    @with_current_user
+    def post(self, current_user: Account):
         payload = console_ns.payload or {}
         args = OwnerTransferEmailPayload.model_validate(payload)
         ip_address = extract_remote_ip(request)
         if AccountService.is_email_send_ip_limit(ip_address):
             raise EmailSendIpLimitError()
-        current_user, _ = current_account_with_tenant()
         # check if the current user is the owner of the workspace
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
@@ -355,11 +356,11 @@ class OwnerTransferCheckApi(Resource):
     @login_required
     @account_initialization_required
     @is_allow_transfer_owner
-    def post(self):
+    @with_current_user
+    def post(self, current_user: Account):
         payload = console_ns.payload or {}
         args = OwnerTransferCheckPayload.model_validate(payload)
         # check if the current user is the owner of the workspace
-        current_user, _ = current_account_with_tenant()
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
         if not TenantService.is_owner(current_user, current_user.current_tenant):
@@ -399,12 +400,12 @@ class OwnerTransfer(Resource):
     @login_required
     @account_initialization_required
     @is_allow_transfer_owner
-    def post(self, member_id: UUID):
+    @with_current_user
+    def post(self, current_user: Account, member_id: UUID):
         payload = console_ns.payload or {}
         args = OwnerTransferPayload.model_validate(payload)
 
         # check if the current user is the owner of the workspace
-        current_user, _ = current_account_with_tenant()
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
         if not TenantService.is_owner(current_user, current_user.current_tenant):

api/controllers/console/workspace/snippets.py

@@ -0,0 +1,407 @@
+import logging
+import re
+from urllib.parse import quote
+
+from flask import Response, request
+from flask_restx import Resource, marshal
+from sqlalchemy.orm import Session
+from werkzeug.datastructures import MultiDict
+from werkzeug.exceptions import NotFound
+
+from controllers.common.schema import register_schema_models
+from controllers.console import console_ns
+from controllers.console.snippets.payloads import (
+    CreateSnippetPayload,
+    IncludeSecretQuery,
+    SnippetImportPayload,
+    SnippetListQuery,
+    UpdateSnippetPayload,
+)
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+)
+from extensions.ext_database import db
+from fields.snippet_fields import snippet_fields, snippet_list_fields, snippet_pagination_fields
+from libs.login import current_account_with_tenant, login_required
+from models.snippet import SnippetType
+from services.app_dsl_service import ImportStatus
+from services.snippet_dsl_service import SnippetDslService
+from services.snippet_service import SnippetService
+
+logger = logging.getLogger(__name__)
+_TAG_IDS_BRACKET_PATTERN = re.compile(r"^tag_ids\[(\d+)\]$")
+
+
+def _normalize_snippet_list_query_args(query_args: MultiDict[str, str]) -> dict[str, str | list[str]]:
+    normalized: dict[str, str | list[str]] = {}
+    indexed_tag_ids: list[tuple[int, str]] = []
+
+    for key in query_args:
+        match = _TAG_IDS_BRACKET_PATTERN.fullmatch(key)
+        if match:
+            indexed_tag_ids.extend((int(match.group(1)), value) for value in query_args.getlist(key))
+            continue
+
+        value = query_args.get(key)
+        if value is not None:
+            normalized[key] = value
+
+    if indexed_tag_ids:
+        normalized["tag_ids"] = [value for _, value in sorted(indexed_tag_ids)]
+
+    return normalized
+
+
+# Register Pydantic models with Swagger
+register_schema_models(
+    console_ns,
+    SnippetListQuery,
+    CreateSnippetPayload,
+    UpdateSnippetPayload,
+    SnippetImportPayload,
+    IncludeSecretQuery,
+)
+
+# Create namespace models for marshaling
+snippet_model = console_ns.model("Snippet", snippet_fields)
+snippet_list_model = console_ns.model("SnippetList", snippet_list_fields)
+snippet_pagination_model = console_ns.model("SnippetPagination", snippet_pagination_fields)
+
+
+@console_ns.route("/workspaces/current/customized-snippets")
+class CustomizedSnippetsApi(Resource):
+    @console_ns.doc("list_customized_snippets")
+    @console_ns.expect(console_ns.models.get(SnippetListQuery.__name__))
+    @console_ns.response(200, "Snippets retrieved successfully", snippet_pagination_model)
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def get(self):
+        """List customized snippets with pagination and search."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        query = SnippetListQuery.model_validate(_normalize_snippet_list_query_args(request.args))
+
+        snippets, total, has_more = SnippetService.get_snippets(
+            tenant_id=current_tenant_id,
+            page=query.page,
+            limit=query.limit,
+            keyword=query.keyword,
+            is_published=query.is_published,
+            creators=query.creators,
+            tag_ids=query.tag_ids,
+        )
+
+        return {
+            "data": marshal(snippets, snippet_list_fields),
+            "page": query.page,
+            "limit": query.limit,
+            "total": total,
+            "has_more": has_more,
+        }, 200
+
+    @console_ns.doc("create_customized_snippet")
+    @console_ns.expect(console_ns.models.get(CreateSnippetPayload.__name__))
+    @console_ns.response(201, "Snippet created successfully", snippet_model)
+    @console_ns.response(400, "Invalid request")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def post(self):
+        """Create a new customized snippet."""
+        current_user, current_tenant_id = current_account_with_tenant()
+
+        payload = CreateSnippetPayload.model_validate(console_ns.payload or {})
+
+        try:
+            snippet_type = SnippetType(payload.type)
+        except ValueError:
+            snippet_type = SnippetType.NODE
+
+        try:
+            if payload.graph is not None:
+                SnippetService.validate_snippet_graph_forbidden_nodes(payload.graph)
+
+            snippet = SnippetService.create_snippet(
+                tenant_id=current_tenant_id,
+                name=payload.name,
+                description=payload.description,
+                snippet_type=snippet_type,
+                icon_info=payload.icon_info.model_dump() if payload.icon_info else None,
+                input_fields=[f.model_dump() for f in payload.input_fields] if payload.input_fields else None,
+                account=current_user,
+            )
+        except ValueError as e:
+            return {"message": str(e)}, 400
+
+        return marshal(snippet, snippet_fields), 201
+
+
+@console_ns.route("/workspaces/current/customized-snippets/<uuid:snippet_id>")
+class CustomizedSnippetDetailApi(Resource):
+    @console_ns.doc("get_customized_snippet")
+    @console_ns.response(200, "Snippet retrieved successfully", snippet_model)
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def get(self, snippet_id: str):
+        """Get customized snippet details."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        return marshal(snippet, snippet_fields), 200
+
+    @console_ns.doc("update_customized_snippet")
+    @console_ns.expect(console_ns.models.get(UpdateSnippetPayload.__name__))
+    @console_ns.response(200, "Snippet updated successfully", snippet_model)
+    @console_ns.response(400, "Invalid request")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def patch(self, snippet_id: str):
+        """Update customized snippet."""
+        current_user, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        payload = UpdateSnippetPayload.model_validate(console_ns.payload or {})
+        update_data = payload.model_dump(exclude_unset=True)
+
+        if "icon_info" in update_data and update_data["icon_info"] is not None:
+            update_data["icon_info"] = payload.icon_info.model_dump() if payload.icon_info else None
+
+        if not update_data:
+            return {"message": "No valid fields to update"}, 400
+
+        try:
+            with Session(db.engine, expire_on_commit=False) as session:
+                snippet = session.merge(snippet)
+                snippet = SnippetService.update_snippet(
+                    session=session,
+                    snippet=snippet,
+                    account_id=current_user.id,
+                    data=update_data,
+                )
+                session.commit()
+        except ValueError as e:
+            return {"message": str(e)}, 400
+
+        return marshal(snippet, snippet_fields), 200
+
+    @console_ns.doc("delete_customized_snippet")
+    @console_ns.response(204, "Snippet deleted successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def delete(self, snippet_id: str):
+        """Delete customized snippet."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        with Session(db.engine) as session:
+            snippet = session.merge(snippet)
+            SnippetService.delete_snippet(
+                session=session,
+                snippet=snippet,
+            )
+            session.commit()
+
+        return "", 204
+
+
+@console_ns.route("/workspaces/current/customized-snippets/<uuid:snippet_id>/export")
+class CustomizedSnippetExportApi(Resource):
+    @console_ns.doc("export_customized_snippet")
+    @console_ns.doc(description="Export snippet configuration as DSL")
+    @console_ns.doc(params={"snippet_id": "Snippet ID to export"})
+    @console_ns.response(200, "Snippet exported successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def get(self, snippet_id: str):
+        """Export snippet as DSL."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        # Get include_secret parameter
+        query = IncludeSecretQuery.model_validate(request.args.to_dict())
+
+        with Session(db.engine) as session:
+            export_service = SnippetDslService(session)
+            result = export_service.export_snippet_dsl(snippet=snippet, include_secret=query.include_secret == "true")
+
+        # Set filename with .snippet extension
+        filename = f"{snippet.name}.snippet"
+        encoded_filename = quote(filename)
+        
+        response = Response(
+            result,
+            mimetype="application/x-yaml",
+        )
+        response.headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{encoded_filename}"
+        response.headers["Content-Type"] = "application/x-yaml"
+        
+        return response
+
+
+@console_ns.route("/workspaces/current/customized-snippets/imports")
+class CustomizedSnippetImportApi(Resource):
+    @console_ns.doc("import_customized_snippet")
+    @console_ns.doc(description="Import snippet from DSL")
+    @console_ns.expect(console_ns.models.get(SnippetImportPayload.__name__))
+    @console_ns.response(200, "Snippet imported successfully")
+    @console_ns.response(202, "Import pending confirmation")
+    @console_ns.response(400, "Import failed")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def post(self):
+        """Import snippet from DSL."""
+        current_user, _ = current_account_with_tenant()
+        payload = SnippetImportPayload.model_validate(console_ns.payload or {})
+
+        with Session(db.engine) as session:
+            import_service = SnippetDslService(session)
+            result = import_service.import_snippet(
+                account=current_user,
+                import_mode=payload.mode,
+                yaml_content=payload.yaml_content,
+                yaml_url=payload.yaml_url,
+                snippet_id=payload.snippet_id,
+                name=payload.name,
+                description=payload.description,
+            )
+            session.commit()
+
+        # Return appropriate status code based on result
+        status = result.status
+        if status == ImportStatus.FAILED:
+            return result.model_dump(mode="json"), 400
+        elif status == ImportStatus.PENDING:
+            return result.model_dump(mode="json"), 202
+        return result.model_dump(mode="json"), 200
+
+
+@console_ns.route("/workspaces/current/customized-snippets/imports/<string:import_id>/confirm")
+class CustomizedSnippetImportConfirmApi(Resource):
+    @console_ns.doc("confirm_snippet_import")
+    @console_ns.doc(description="Confirm a pending snippet import")
+    @console_ns.doc(params={"import_id": "Import ID to confirm"})
+    @console_ns.response(200, "Import confirmed successfully")
+    @console_ns.response(400, "Import failed")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def post(self, import_id: str):
+        """Confirm a pending snippet import."""
+        current_user, _ = current_account_with_tenant()
+
+        with Session(db.engine) as session:
+            import_service = SnippetDslService(session)
+            result = import_service.confirm_import(import_id=import_id, account=current_user)
+            session.commit()
+
+        if result.status == ImportStatus.FAILED:
+            return result.model_dump(mode="json"), 400
+        return result.model_dump(mode="json"), 200
+
+
+@console_ns.route("/workspaces/current/customized-snippets/<uuid:snippet_id>/check-dependencies")
+class CustomizedSnippetCheckDependenciesApi(Resource):
+    @console_ns.doc("check_snippet_dependencies")
+    @console_ns.doc(description="Check dependencies for a snippet")
+    @console_ns.doc(params={"snippet_id": "Snippet ID"})
+    @console_ns.response(200, "Dependencies checked successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def get(self, snippet_id: str):
+        """Check dependencies for a snippet."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        with Session(db.engine) as session:
+            import_service = SnippetDslService(session)
+            result = import_service.check_dependencies(snippet=snippet)
+
+        return result.model_dump(mode="json"), 200
+
+
+@console_ns.route("/workspaces/current/customized-snippets/<uuid:snippet_id>/use-count/increment")
+class CustomizedSnippetUseCountIncrementApi(Resource):
+    @console_ns.doc("increment_snippet_use_count")
+    @console_ns.doc(description="Increment snippet use count by 1")
+    @console_ns.doc(params={"snippet_id": "Snippet ID"})
+    @console_ns.response(200, "Use count incremented successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def post(self, snippet_id: str):
+        """Increment snippet use count when it is inserted into a workflow."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        with Session(db.engine) as session:
+            snippet = session.merge(snippet)
+            SnippetService.increment_use_count(session=session, snippet=snippet)
+            session.commit()
+            session.refresh(snippet)
+
+        return {"result": "success", "use_count": snippet.use_count}, 200

api/controllers/console/workspace/workspace.py

@@ -29,7 +29,7 @@ from controllers.console.wraps import (
 from enums.cloud_plan import CloudPlan
 from extensions.ext_database import db
 from fields.base import ResponseModel
-from libs.helper import TimestampField, to_timestamp
+from libs.helper import TimestampField, dump_response, to_timestamp
 from libs.login import current_account_with_tenant, login_required
 from models.account import Tenant, TenantCustomConfigDict, TenantStatus
 from services.account_service import TenantService
@@ -56,6 +56,11 @@ class WorkspaceCustomConfigPayload(BaseModel):
     replace_webapp_logo: str | None = None
 
 
+class WorkspaceCustomConfigResponse(ResponseModel):
+    remove_webapp_brand: bool | None = None
+    replace_webapp_logo: str | None = None
+
+
 class WorkspaceInfoPayload(BaseModel):
     name: str
 
@@ -69,7 +74,7 @@ class TenantInfoResponse(ResponseModel):
     role: str | None = None
     in_trial: bool | None = None
     trial_end_reason: str | None = None
-    custom_config: dict | None = None
+    custom_config: WorkspaceCustomConfigResponse | None = None
     trial_credits: int | None = None
     trial_credits_used: int | None = None
     next_credit_reset_date: int | None = None
@@ -101,9 +106,13 @@ register_schema_models(
     SwitchWorkspacePayload,
     WorkspaceCustomConfigPayload,
     WorkspaceInfoPayload,
-    TenantInfoResponse,
 )
-register_response_schema_models(console_ns, WorkspacePermissionResponse)
+register_response_schema_models(
+    console_ns,
+    TenantInfoResponse,
+    WorkspaceCustomConfigResponse,
+    WorkspacePermissionResponse,
+)
 
 provider_fields = {
     "provider_name": fields.String,
@@ -238,13 +247,7 @@ class TenantApi(Resource):
             else:
                 raise Unauthorized("workspace is archived")
 
-        return (
-            TenantInfoResponse.model_validate(
-                WorkspaceService.get_tenant_info(tenant),
-                from_attributes=True,
-            ).model_dump(mode="json"),
-            200,
-        )
+        return dump_response(TenantInfoResponse, WorkspaceService.get_tenant_info(tenant)), 200
 
 
 @console_ns.route("/workspaces/switch")

api/controllers/console/wraps.py

@@ -7,7 +7,9 @@ from functools import wraps
 from typing import Concatenate
 
 from flask import abort, request
+from pydantic import BaseModel, ValidationError
 from sqlalchemy import select
+from werkzeug.exceptions import UnprocessableEntity
 
 from configs import dify_config
 from controllers.console.auth.error import AuthenticationFailedError, EmailCodeError
@@ -512,9 +514,79 @@ def with_current_tenant_id[T, **P, R](
 def with_current_user[T, **P, R](
     view: Callable[Concatenate[T, Account, P], R],
 ) -> Callable[Concatenate[T, P], R]:
+    """Inject the current authenticated Account into the handler as the first argument after self.
+
+    Usage::
+
+        class MyResource(Resource):
+            @login_required
+            @with_current_user
+            def get(self, current_user: Account):
+                ...
+    """
+
     @wraps(view)
     def decorated(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
         current_user, _ = current_account_with_tenant()
         return view(self, current_user, *args, **kwargs)
 
     return decorated
+
+
+def with_current_user_id[T, **P, R](
+    view: Callable[Concatenate[T, str, P], R],
+) -> Callable[Concatenate[T, P], R]:
+    """Inject the current authenticated user's ID (as a string) into the handler.
+
+    Use this when the handler only needs the user ID and not the full Account object.
+
+    Usage::
+
+        class MyResource(Resource):
+            @login_required
+            @with_current_user_id
+            def get(self, current_user_id: str):
+                ...
+    """
+
+    @wraps(view)
+    def decorated(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+        current_user, _ = current_account_with_tenant()
+        return view(self, str(current_user.id), *args, **kwargs)
+
+    return decorated
+
+
+def model_validate[T, M: BaseModel, **P, R](
+    model: type[M],
+) -> Callable[
+    [Callable[Concatenate[T, M, P], R]],
+    Callable[Concatenate[T, P], R],
+]:
+    """Validate request data and inject the model instance as the first arg after self.
+
+    Source is determined by HTTP method:
+      GET/DELETE -> request.args
+      POST/PUT/PATCH -> JSON body
+    """
+
+    def decorator(
+        view: Callable[Concatenate[T, M, P], R],
+    ) -> Callable[Concatenate[T, P], R]:
+        @wraps(view)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            if request.method in ("GET", "DELETE"):
+                raw = request.args.to_dict(flat=True)
+            else:
+                raw = request.get_json(silent=True) or {}
+
+            try:
+                validated = model.model_validate(raw)
+            except ValidationError as exc:
+                raise UnprocessableEntity(exc.json())
+
+            return view(self, validated, *args, **kwargs)
+
+        return wrapper
+
+    return decorator

api/controllers/inner_api/plugin/wraps.py

@@ -45,6 +45,15 @@ def get_user(tenant_id: str, user_id: str | None) -> EndUser:
                     .limit(1)
                 )
             else:
+                # Try id first (preserves the original "explicit end-user
+                # id → that specific user" semantics for callers that pass
+                # a known EndUser.id). Fall back to session_id so daemon-
+                # supplied session UUIDs dedup against the row created on
+                # the first Reverse Invocation call — without this, an
+                # id-only lookup never matched (create writes user_id to
+                # session_id, id is auto-generated) and a fresh EndUser
+                # was created per call, breaking multi-turn chat
+                # continuation (see #36736).
                 user_model = session.scalar(
                     select(EndUser)
                     .where(
@@ -53,6 +62,15 @@ def get_user(tenant_id: str, user_id: str | None) -> EndUser:
                     )
                     .limit(1)
                 )
+                if user_model is None:
+                    user_model = session.scalar(
+                        select(EndUser)
+                        .where(
+                            EndUser.session_id == user_id,
+                            EndUser.tenant_id == tenant_id,
+                        )
+                        .limit(1)
+                    )
 
             if not user_model:
                 user_model = EndUser(

api/controllers/service_api/app/annotation.py

@@ -6,7 +6,7 @@ from flask_restx import Resource
 from flask_restx.api import HTTPStatus
 from pydantic import BaseModel, Field, TypeAdapter
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console.wraps import edit_permission_required
 from controllers.service_api import service_api_ns
 from controllers.service_api.wraps import validate_app_token
@@ -32,8 +32,19 @@ class AnnotationReplyActionPayload(BaseModel):
     embedding_model_name: str = Field(description="Embedding model name")
 
 
+class AnnotationListQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, description="Number of annotations per page")
+    keyword: str = Field(default="", description="Keyword to search annotations")
+
+
 register_schema_models(
-    service_api_ns, AnnotationCreatePayload, AnnotationReplyActionPayload, Annotation, AnnotationList
+    service_api_ns,
+    AnnotationCreatePayload,
+    AnnotationReplyActionPayload,
+    AnnotationListQuery,
+    Annotation,
+    AnnotationList,
 )
 
 
@@ -100,6 +111,7 @@ class AnnotationReplyActionStatusApi(Resource):
 class AnnotationListApi(Resource):
     @service_api_ns.doc("list_annotations")
     @service_api_ns.doc(description="List annotations for the application")
+    @service_api_ns.doc(params=query_params_from_model(AnnotationListQuery))
     @service_api_ns.doc(
         responses={
             200: "Annotations retrieved successfully",
@@ -114,18 +126,18 @@ class AnnotationListApi(Resource):
     @validate_app_token
     def get(self, app_model: App):
         """List annotations for the application."""
-        page = request.args.get("page", default=1, type=int)
-        limit = request.args.get("limit", default=20, type=int)
-        keyword = request.args.get("keyword", default="", type=str)
+        query = AnnotationListQuery.model_validate(request.args.to_dict(flat=True))
 
-        annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(app_model.id, page, limit, keyword)
+        annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(
+            app_model.id, query.page, query.limit, query.keyword
+        )
         annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
         response = AnnotationList(
             data=annotation_models,
-            has_more=len(annotation_list) == limit,
-            limit=limit,
+            has_more=len(annotation_list) == query.limit,
+            limit=query.limit,
             total=total,
-            page=page,
+            page=query.page,
         )
         return response.model_dump(mode="json")
 

api/controllers/service_api/dataset/document.py

@@ -12,7 +12,6 @@ from typing import Self
 from uuid import UUID
 
 from flask import request, send_file
-from flask_restx import marshal
 from pydantic import BaseModel, Field, field_validator, model_validator
 from sqlalchemy import desc, func, select
 from werkzeug.exceptions import Forbidden, NotFound
@@ -27,7 +26,12 @@ from controllers.common.errors import (
     UnsupportedFileTypeError,
 )
 from controllers.common.fields import UrlResponse
-from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    query_params_from_model,
+    register_enum_models,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.service_api import service_api_ns
 from controllers.service_api.app.error import ProviderNotInitializeError
 from controllers.service_api.dataset.error import (
@@ -44,7 +48,13 @@ from core.errors.error import ProviderTokenNotInitError
 from core.rag.entities import PreProcessingRule, Rule, Segmentation
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
 from extensions.ext_database import db
-from fields.document_fields import document_fields, document_status_fields
+from fields.base import ResponseModel
+from fields.document_fields import (
+    DocumentListResponse,
+    DocumentResponse,
+    DocumentStatusListResponse,
+)
+from libs.helper import dump_response
 from libs.login import current_user
 from models.dataset import Dataset, Document, DocumentSegment
 from models.enums import SegmentStatus
@@ -107,6 +117,44 @@ class DocumentListQuery(BaseModel):
     status: str | None = Field(default=None, description="Document status filter")
 
 
+DOCUMENT_CREATE_BY_FILE_PARAMS = {
+    "dataset_id": "Dataset ID",
+    "file": {
+        "in": "formData",
+        "type": "file",
+        "required": True,
+        "description": "Document file to upload.",
+    },
+    "data": {
+        "in": "formData",
+        "type": "string",
+        "required": False,
+        "description": "Optional JSON string with document creation settings.",
+    },
+}
+DOCUMENT_UPDATE_BY_FILE_PARAMS = {
+    "dataset_id": "Dataset ID",
+    "document_id": "Document ID",
+    "file": {
+        "in": "formData",
+        "type": "file",
+        "required": False,
+        "description": "Replacement document file.",
+    },
+    "data": {
+        "in": "formData",
+        "type": "string",
+        "required": False,
+        "description": "Optional JSON string with document update settings.",
+    },
+}
+
+
+class DocumentAndBatchResponse(ResponseModel):
+    document: DocumentResponse
+    batch: str
+
+
 register_enum_models(service_api_ns, RetrievalMethod)
 
 register_schema_models(
@@ -121,7 +169,14 @@ register_schema_models(
     PreProcessingRule,
     Segmentation,
 )
-register_response_schema_models(service_api_ns, UrlResponse)
+register_response_schema_models(
+    service_api_ns,
+    UrlResponse,
+    DocumentResponse,
+    DocumentAndBatchResponse,
+    DocumentListResponse,
+    DocumentStatusListResponse,
+)
 
 
 def _create_document_by_text(tenant_id: str, dataset_id: UUID) -> tuple[Mapping[str, object], int]:
@@ -188,8 +243,7 @@ def _create_document_by_text(tenant_id: str, dataset_id: UUID) -> tuple[Mapping[
         raise ProviderNotInitializeError(ex.description)
     document = documents[0]
 
-    documents_and_batch_fields = {"document": marshal(document, document_fields), "batch": batch}
-    return documents_and_batch_fields, 200
+    return dump_response(DocumentAndBatchResponse, {"document": document, "batch": batch}), 200
 
 
 def _update_document_by_text(tenant_id: str, dataset_id: UUID, document_id: UUID) -> tuple[Mapping[str, object], int]:
@@ -248,8 +302,7 @@ def _update_document_by_text(tenant_id: str, dataset_id: UUID, document_id: UUID
         raise ProviderNotInitializeError(ex.description)
     document = documents[0]
 
-    documents_and_batch_fields = {"document": marshal(document, document_fields), "batch": batch}
-    return documents_and_batch_fields, 200
+    return dump_response(DocumentAndBatchResponse, {"document": document, "batch": batch}), 200
 
 
 @service_api_ns.route("/datasets/<uuid:dataset_id>/document/create-by-text")
@@ -267,6 +320,9 @@ class DocumentAddByTextApi(DatasetApiResource):
             400: "Bad request - invalid parameters",
         }
     )
+    @service_api_ns.response(
+        200, "Document created successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_resource_check("documents", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@@ -296,6 +352,9 @@ class DeprecatedDocumentAddByTextApi(DatasetApiResource):
             400: "Bad request - invalid parameters",
         }
     )
+    @service_api_ns.response(
+        200, "Document created successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_resource_check("documents", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@@ -319,6 +378,9 @@ class DocumentUpdateByTextApi(DatasetApiResource):
             404: "Document not found",
         }
     )
+    @service_api_ns.response(
+        200, "Document updated successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
     def post(self, tenant_id: str, dataset_id: UUID, document_id: UUID):
@@ -347,6 +409,9 @@ class DeprecatedDocumentUpdateByTextApi(DatasetApiResource):
             404: "Document not found",
         }
     )
+    @service_api_ns.response(
+        200, "Document updated successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
     def post(self, tenant_id: str, dataset_id: UUID, document_id: UUID):
@@ -363,7 +428,7 @@ class DocumentAddByFileApi(DatasetApiResource):
 
     @service_api_ns.doc("create_document_by_file")
     @service_api_ns.doc(description="Create a new document by uploading a file")
-    @service_api_ns.doc(params={"dataset_id": "Dataset ID"})
+    @service_api_ns.doc(consumes=["multipart/form-data"], params=DOCUMENT_CREATE_BY_FILE_PARAMS)
     @service_api_ns.doc(
         responses={
             200: "Document created successfully",
@@ -371,6 +436,9 @@ class DocumentAddByFileApi(DatasetApiResource):
             400: "Bad request - invalid file or parameters",
         }
     )
+    @service_api_ns.response(
+        200, "Document created successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_resource_check("documents", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@@ -462,8 +530,7 @@ class DocumentAddByFileApi(DatasetApiResource):
         except ProviderTokenNotInitError as ex:
             raise ProviderNotInitializeError(ex.description)
         document = documents[0]
-        documents_and_batch_fields = {"document": marshal(document, document_fields), "batch": batch}
-        return documents_and_batch_fields, 200
+        return dump_response(DocumentAndBatchResponse, {"document": document, "batch": batch}), 200
 
 
 def _update_document_by_file(tenant_id: str, dataset_id: UUID, document_id: UUID) -> tuple[Mapping[str, object], int]:
@@ -539,8 +606,7 @@ def _update_document_by_file(tenant_id: str, dataset_id: UUID, document_id: UUID
     except ProviderTokenNotInitError as ex:
         raise ProviderNotInitializeError(ex.description)
     document = documents[0]
-    documents_and_batch_fields = {"document": marshal(document, document_fields), "batch": document.batch}
-    return documents_and_batch_fields, 200
+    return dump_response(DocumentAndBatchResponse, {"document": document, "batch": document.batch}), 200
 
 
 @service_api_ns.route(
@@ -558,7 +624,7 @@ class DeprecatedDocumentUpdateByFileApi(DatasetApiResource):
             "Use PATCH /datasets/{dataset_id}/documents/{document_id} instead."
         )
     )
-    @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @service_api_ns.doc(consumes=["multipart/form-data"], params=DOCUMENT_UPDATE_BY_FILE_PARAMS)
     @service_api_ns.doc(
         responses={
             200: "Document updated successfully",
@@ -566,6 +632,9 @@ class DeprecatedDocumentUpdateByFileApi(DatasetApiResource):
             404: "Document not found",
         }
     )
+    @service_api_ns.response(
+        200, "Document updated successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
     def post(self, tenant_id: str, dataset_id: UUID, document_id: UUID):
@@ -577,7 +646,7 @@ class DeprecatedDocumentUpdateByFileApi(DatasetApiResource):
 class DocumentListApi(DatasetApiResource):
     @service_api_ns.doc("list_documents")
     @service_api_ns.doc(description="List all documents in a dataset")
-    @service_api_ns.doc(params={"dataset_id": "Dataset ID"})
+    @service_api_ns.doc(params={"dataset_id": "Dataset ID", **query_params_from_model(DocumentListQuery)})
     @service_api_ns.doc(
         responses={
             200: "Documents retrieved successfully",
@@ -585,6 +654,9 @@ class DocumentListApi(DatasetApiResource):
             404: "Dataset not found",
         }
     )
+    @service_api_ns.response(
+        200, "Documents retrieved successfully", service_api_ns.models[DocumentListResponse.__name__]
+    )
     def get(self, tenant_id, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         tenant_id = str(tenant_id)
@@ -618,14 +690,14 @@ class DocumentListApi(DatasetApiResource):
         )
 
         response = {
-            "data": marshal(documents, document_fields),
+            "data": documents,
             "has_more": len(documents) == query_params.limit,
             "limit": query_params.limit,
             "total": paginated_documents.total,
             "page": query_params.page,
         }
 
-        return response
+        return dump_response(DocumentListResponse, response)
 
 
 @service_api_ns.route("/datasets/<uuid:dataset_id>/documents/download-zip")
@@ -680,6 +752,11 @@ class DocumentIndexingStatusApi(DatasetApiResource):
             404: "Dataset or documents not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Indexing status retrieved successfully",
+        service_api_ns.models[DocumentStatusListResponse.__name__],
+    )
     def get(self, tenant_id, dataset_id: UUID, batch: str):
         dataset_id_str = str(dataset_id)
         tenant_id = str(tenant_id)
@@ -729,9 +806,8 @@ class DocumentIndexingStatusApi(DatasetApiResource):
                 "completed_segments": completed_segments,
                 "total_segments": total_segments,
             }
-            documents_status.append(marshal(document_dict, document_status_fields))
-        data = {"data": documents_status}
-        return data
+            documents_status.append(document_dict)
+        return dump_response(DocumentStatusListResponse, {"data": documents_status})
 
 
 @service_api_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/download")
@@ -890,7 +966,7 @@ class DocumentApi(DatasetApiResource):
 
     @service_api_ns.doc("update_document_by_file")
     @service_api_ns.doc(description="Update an existing document by uploading a file")
-    @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @service_api_ns.doc(consumes=["multipart/form-data"], params=DOCUMENT_UPDATE_BY_FILE_PARAMS)
     @service_api_ns.doc(
         responses={
             200: "Document updated successfully",
@@ -898,6 +974,9 @@ class DocumentApi(DatasetApiResource):
             404: "Document not found",
         }
     )
+    @service_api_ns.response(
+        200, "Document updated successfully", service_api_ns.models[DocumentAndBatchResponse.__name__]
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
     def patch(self, tenant_id: str, dataset_id: UUID, document_id: UUID):

api/controllers/service_api/dataset/segment.py

@@ -1,15 +1,18 @@
-from typing import Any
+from typing import cast
 from uuid import UUID
 
-from flask import request
-from flask_restx import marshal
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ValidationError, field_validator
 from sqlalchemy import select
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
 from controllers.common.controller_schemas import ChildChunkCreatePayload, ChildChunkUpdatePayload
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.service_api import service_api_ns
 from controllers.service_api.app.error import ProviderNotInitializeError
 from controllers.service_api.wraps import (
@@ -22,10 +25,19 @@ from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.model_manager import ModelManager
 from core.rag.index_processor.constant.index_type import IndexTechniqueType
 from extensions.ext_database import db
-from fields.segment_fields import child_chunk_fields, segment_fields
+from fields.base import ResponseModel
+from fields.segment_fields import (
+    ChildChunkDetailResponse,
+    ChildChunkListResponse,
+    SegmentDetailResponse,
+    SegmentResponse,
+    segment_response_with_summary,
+    segment_responses_with_summaries,
+)
 from graphon.model_runtime.entities.model_entities import ModelType
+from libs.helper import dump_response
 from libs.login import current_account_with_tenant
-from models.dataset import Dataset
+from models.dataset import Dataset, DocumentSegment
 from services.dataset_service import DatasetService, DocumentService, SegmentService
 from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs
 from services.errors.chunk import ChildChunkDeleteIndexError, ChildChunkIndexingError
@@ -34,35 +46,27 @@ from services.errors.chunk import ChildChunkIndexingError as ChildChunkIndexingS
 from services.summary_index_service import SummaryIndexService
 
 
-def _marshal_segment_with_summary(segment, dataset_id: str) -> dict[str, Any]:
-    """Marshal a single segment and enrich it with summary content."""
-    segment_dict: dict[str, Any] = dict(marshal(segment, segment_fields))  # type: ignore[arg-type]
-    summary = SummaryIndexService.get_segment_summary(segment_id=segment.id, dataset_id=dataset_id)
-    segment_dict["summary"] = summary.summary_content if summary else None
-    return segment_dict
+class SegmentCreateItemPayload(BaseModel):
+    content: str = Field(min_length=1)
+    answer: str | None = None
+    keywords: list[str] | None = None
+    attachment_ids: list[str] | None = None
 
-
-def _marshal_segments_with_summary(segments, dataset_id: str) -> list[dict[str, Any]]:
-    """Marshal multiple segments and enrich them with summary content (batch query)."""
-    segment_ids = [segment.id for segment in segments]
-    summaries: dict[str, str | None] = {}
-    if segment_ids:
-        summary_records = SummaryIndexService.get_segments_summaries(segment_ids=segment_ids, dataset_id=dataset_id)
-        summaries = {chunk_id: record.summary_content for chunk_id, record in summary_records.items()}
-
-    result: list[dict[str, Any]] = []
-    for segment in segments:
-        segment_dict: dict[str, Any] = dict(marshal(segment, segment_fields))  # type: ignore[arg-type]
-        segment_dict["summary"] = summaries.get(segment.id)
-        result.append(segment_dict)
-    return result
+    @field_validator("content")
+    @classmethod
+    def validate_content(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Content is empty")
+        return value
 
 
 class SegmentCreatePayload(BaseModel):
-    segments: list[dict[str, Any]] | None = None
+    segments: list[SegmentCreateItemPayload] = Field(min_length=1)
 
 
 class SegmentListQuery(BaseModel):
+    limit: int = Field(default=20, ge=1)
+    page: int = Field(default=1, ge=1)
     status: list[str] = Field(default_factory=list)
     keyword: str | None = None
 
@@ -77,9 +81,31 @@ class ChildChunkListQuery(BaseModel):
     page: int = Field(default=1, ge=1)
 
 
+class SegmentDocParams:
+    DATASET_DOCUMENT = {"dataset_id": "Dataset ID", "document_id": "Document ID"}
+    DATASET_DOCUMENT_SEGMENT = {**DATASET_DOCUMENT, "segment_id": "Segment ID"}
+    DATASET_DOCUMENT_PARENT_SEGMENT = {**DATASET_DOCUMENT, "segment_id": "Parent segment ID"}
+    DATASET_DOCUMENT_CHILD_CHUNK = {**DATASET_DOCUMENT_PARENT_SEGMENT, "child_chunk_id": "Child chunk ID"}
+
+
+class SegmentCreateListResponse(ResponseModel):
+    data: list[SegmentResponse]
+    doc_form: str
+
+
+class SegmentListResponse(ResponseModel):
+    data: list[SegmentResponse]
+    doc_form: str
+    total: int
+    has_more: bool
+    limit: int
+    page: int
+
+
 register_schema_models(
     service_api_ns,
     SegmentCreatePayload,
+    SegmentCreateItemPayload,
     SegmentListQuery,
     SegmentUpdateArgs,
     SegmentUpdatePayload,
@@ -87,6 +113,15 @@ register_schema_models(
     ChildChunkListQuery,
     ChildChunkUpdatePayload,
 )
+register_response_schema_models(
+    service_api_ns,
+    SegmentResponse,
+    SegmentCreateListResponse,
+    SegmentListResponse,
+    SegmentDetailResponse,
+    ChildChunkDetailResponse,
+    ChildChunkListResponse,
+)
 
 
 @service_api_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments")
@@ -96,7 +131,7 @@ class SegmentApi(DatasetApiResource):
     @service_api_ns.expect(service_api_ns.models[SegmentCreatePayload.__name__])
     @service_api_ns.doc("create_segments")
     @service_api_ns.doc(description="Create segments in a document")
-    @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
     @service_api_ns.doc(
         responses={
             200: "Segments created successfully",
@@ -105,6 +140,11 @@ class SegmentApi(DatasetApiResource):
             404: "Dataset or document not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Segments created successfully",
+        service_api_ns.models[SegmentCreateListResponse.__name__],
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@@ -144,26 +184,35 @@ class SegmentApi(DatasetApiResource):
             except ProviderTokenNotInitError as ex:
                 raise ProviderNotInitializeError(ex.description)
         # validate args
-        payload = SegmentCreatePayload.model_validate(service_api_ns.payload or {})
-        if payload.segments is not None:
-            segments_limit = dify_config.DATASET_MAX_SEGMENTS_PER_REQUEST
-            if segments_limit > 0 and len(payload.segments) > segments_limit:
-                raise ValueError(f"Exceeded maximum segments limit of {segments_limit}.")
+        try:
+            payload = SegmentCreatePayload.model_validate(service_api_ns.payload or {})
+        except ValidationError as e:
+            return {"error": str(e)}, 400
+        segments_limit = dify_config.DATASET_MAX_SEGMENTS_PER_REQUEST
+        if segments_limit > 0 and len(payload.segments) > segments_limit:
+            raise ValueError(f"Exceeded maximum segments limit of {segments_limit}.")
+        segment_items = [segment.model_dump(exclude_none=True) for segment in payload.segments]
 
-            for args_item in payload.segments:
-                SegmentService.segment_create_args_validate(args_item, document)
-            segments = SegmentService.multi_create_segment(payload.segments, document, dataset)
-            return {
-                "data": _marshal_segments_with_summary(segments, dataset_id_str),
-                "doc_form": document.doc_form,
-            }, 200
-        else:
-            return {"error": "Segments is required"}, 400
+        for args_item in segment_items:
+            SegmentService.segment_create_args_validate(args_item, document)
+        segments = cast(list[DocumentSegment], SegmentService.multi_create_segment(segment_items, document, dataset))
+        segment_ids = [segment.id for segment in segments]
+        summaries: dict[str, str | None] = {}
+        if segment_ids:
+            summary_records = SummaryIndexService.get_segments_summaries(
+                segment_ids=segment_ids, dataset_id=dataset_id_str
+            )
+            summaries = {chunk_id: record.summary_content for chunk_id, record in summary_records.items()}
+        response = {
+            "data": segment_responses_with_summaries(segments, summaries),
+            "doc_form": document.doc_form,
+        }
+        return dump_response(SegmentCreateListResponse, response), 200
 
-    @service_api_ns.expect(service_api_ns.models[SegmentListQuery.__name__])
     @service_api_ns.doc("list_segments")
     @service_api_ns.doc(description="List segments in a document")
-    @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
+    @service_api_ns.doc(params=query_params_from_model(SegmentListQuery))
     @service_api_ns.doc(
         responses={
             200: "Segments retrieved successfully",
@@ -171,12 +220,22 @@ class SegmentApi(DatasetApiResource):
             404: "Dataset or document not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Segments retrieved successfully",
+        service_api_ns.models[SegmentListResponse.__name__],
+    )
     def get(self, tenant_id: str, dataset_id: UUID, document_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
         """Get segments."""
         # check dataset
-        page = request.args.get("page", default=1, type=int)
-        limit = request.args.get("limit", default=20, type=int)
+        args = query_params_from_request(
+            SegmentListQuery,
+            list_fields=("status",),
+            use_defaults_for_malformed_ints=True,
+        )
+        page = args.page
+        limit = args.limit
         dataset_id_str = str(dataset_id)
         dataset = db.session.scalar(
             select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
@@ -205,13 +264,6 @@ class SegmentApi(DatasetApiResource):
             except ProviderTokenNotInitError as ex:
                 raise ProviderNotInitializeError(ex.description)
 
-        args = SegmentListQuery.model_validate(
-            {
-                "status": request.args.getlist("status"),
-                "keyword": request.args.get("keyword"),
-            }
-        )
-
         segments, total = SegmentService.get_segments(
             document_id=document_id_str,
             tenant_id=current_tenant_id,
@@ -220,9 +272,16 @@ class SegmentApi(DatasetApiResource):
             page=page,
             limit=limit,
         )
+        segment_ids = [segment.id for segment in segments]
+        summaries: dict[str, str | None] = {}
+        if segment_ids:
+            summary_records = SummaryIndexService.get_segments_summaries(
+                segment_ids=segment_ids, dataset_id=dataset_id_str
+            )
+            summaries = {chunk_id: record.summary_content for chunk_id, record in summary_records.items()}
 
         response = {
-            "data": _marshal_segments_with_summary(segments, dataset_id_str),
+            "data": segment_responses_with_summaries(segments, summaries),
             "doc_form": document.doc_form,
             "total": total,
             "has_more": len(segments) == limit,
@@ -230,16 +289,14 @@ class SegmentApi(DatasetApiResource):
             "page": page,
         }
 
-        return response, 200
+        return dump_response(SegmentListResponse, response), 200
 
 
 @service_api_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>")
 class DatasetSegmentApi(DatasetApiResource):
     @service_api_ns.doc("delete_segment")
     @service_api_ns.doc(description="Delete a specific segment")
-    @service_api_ns.doc(
-        params={"dataset_id": "Dataset ID", "document_id": "Document ID", "segment_id": "Segment ID to delete"}
-    )
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
     @service_api_ns.doc(
         responses={
             204: "Segment deleted successfully",
@@ -275,9 +332,7 @@ class DatasetSegmentApi(DatasetApiResource):
     @service_api_ns.expect(service_api_ns.models[SegmentUpdatePayload.__name__])
     @service_api_ns.doc("update_segment")
     @service_api_ns.doc(description="Update a specific segment")
-    @service_api_ns.doc(
-        params={"dataset_id": "Dataset ID", "document_id": "Document ID", "segment_id": "Segment ID to update"}
-    )
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
     @service_api_ns.doc(
         responses={
             200: "Segment updated successfully",
@@ -285,6 +340,7 @@ class DatasetSegmentApi(DatasetApiResource):
             404: "Dataset, document, or segment not found",
         }
     )
+    @service_api_ns.response(200, "Segment updated successfully", service_api_ns.models[SegmentDetailResponse.__name__])
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
     def post(self, tenant_id: str, dataset_id: UUID, document_id: UUID, segment_id: UUID):
@@ -328,13 +384,16 @@ class DatasetSegmentApi(DatasetApiResource):
         payload = SegmentUpdatePayload.model_validate(service_api_ns.payload or {})
 
         updated_segment = SegmentService.update_segment(payload.segment, segment, document, dataset)
-        return {
-            "data": _marshal_segment_with_summary(updated_segment, dataset_id_str),
+        summary = SummaryIndexService.get_segment_summary(segment_id=updated_segment.id, dataset_id=dataset_id_str)
+        response = {
+            "data": segment_response_with_summary(updated_segment, summary.summary_content if summary else None),
             "doc_form": document.doc_form,
-        }, 200
+        }
+        return dump_response(SegmentDetailResponse, response), 200
 
     @service_api_ns.doc("get_segment")
     @service_api_ns.doc(description="Get a specific segment by ID")
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
     @service_api_ns.doc(
         responses={
             200: "Segment retrieved successfully",
@@ -342,6 +401,11 @@ class DatasetSegmentApi(DatasetApiResource):
             404: "Dataset, document, or segment not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Segment retrieved successfully",
+        service_api_ns.models[SegmentDetailResponse.__name__],
+    )
     def get(self, tenant_id: str, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
@@ -364,7 +428,12 @@ class DatasetSegmentApi(DatasetApiResource):
         if not segment:
             raise NotFound("Segment not found.")
 
-        return {"data": _marshal_segment_with_summary(segment, dataset_id_str), "doc_form": document.doc_form}, 200
+        summary = SummaryIndexService.get_segment_summary(segment_id=segment.id, dataset_id=dataset_id_str)
+        response = {
+            "data": segment_response_with_summary(segment, summary.summary_content if summary else None),
+            "doc_form": document.doc_form,
+        }
+        return dump_response(SegmentDetailResponse, response), 200
 
 
 @service_api_ns.route(
@@ -376,9 +445,7 @@ class ChildChunkApi(DatasetApiResource):
     @service_api_ns.expect(service_api_ns.models[ChildChunkCreatePayload.__name__])
     @service_api_ns.doc("create_child_chunk")
     @service_api_ns.doc(description="Create a new child chunk for a segment")
-    @service_api_ns.doc(
-        params={"dataset_id": "Dataset ID", "document_id": "Document ID", "segment_id": "Parent segment ID"}
-    )
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
     @service_api_ns.doc(
         responses={
             200: "Child chunk created successfully",
@@ -386,6 +453,11 @@ class ChildChunkApi(DatasetApiResource):
             404: "Dataset, document, or segment not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Child chunk created successfully",
+        service_api_ns.models[ChildChunkDetailResponse.__name__],
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@@ -437,14 +509,12 @@ class ChildChunkApi(DatasetApiResource):
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
 
-        return {"data": marshal(child_chunk, child_chunk_fields)}, 200
+        return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200
 
-    @service_api_ns.expect(service_api_ns.models[ChildChunkListQuery.__name__])
     @service_api_ns.doc("list_child_chunks")
     @service_api_ns.doc(description="List child chunks for a segment")
-    @service_api_ns.doc(
-        params={"dataset_id": "Dataset ID", "document_id": "Document ID", "segment_id": "Parent segment ID"}
-    )
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
+    @service_api_ns.doc(params=query_params_from_model(ChildChunkListQuery))
     @service_api_ns.doc(
         responses={
             200: "Child chunks retrieved successfully",
@@ -452,6 +522,11 @@ class ChildChunkApi(DatasetApiResource):
             404: "Dataset, document, or segment not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Child chunks retrieved successfully",
+        service_api_ns.models[ChildChunkListResponse.__name__],
+    )
     def get(self, tenant_id: str, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
         """Get child chunks."""
@@ -475,13 +550,7 @@ class ChildChunkApi(DatasetApiResource):
         if not segment:
             raise NotFound("Segment not found.")
 
-        args = ChildChunkListQuery.model_validate(
-            {
-                "limit": request.args.get("limit", default=20, type=int),
-                "keyword": request.args.get("keyword"),
-                "page": request.args.get("page", default=1, type=int),
-            }
-        )
+        args = query_params_from_request(ChildChunkListQuery, use_defaults_for_malformed_ints=True)
 
         page = args.page
         limit = min(args.limit, 100)
@@ -491,13 +560,14 @@ class ChildChunkApi(DatasetApiResource):
             segment_id_str, document_id_str, dataset_id_str, page, limit, keyword
         )
 
-        return {
-            "data": marshal(child_chunks.items, child_chunk_fields),
+        response = {
+            "data": child_chunks.items,
             "total": child_chunks.total,
             "total_pages": child_chunks.pages,
             "page": page,
             "limit": limit,
-        }, 200
+        }
+        return dump_response(ChildChunkListResponse, response), 200
 
 
 @service_api_ns.route(
@@ -508,14 +578,7 @@ class DatasetChildChunkApi(DatasetApiResource):
 
     @service_api_ns.doc("delete_child_chunk")
     @service_api_ns.doc(description="Delete a specific child chunk")
-    @service_api_ns.doc(
-        params={
-            "dataset_id": "Dataset ID",
-            "document_id": "Document ID",
-            "segment_id": "Parent segment ID",
-            "child_chunk_id": "Child chunk ID to delete",
-        }
-    )
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK)
     @service_api_ns.doc(
         responses={
             204: "Child chunk deleted successfully",
@@ -549,7 +612,7 @@ class DatasetChildChunkApi(DatasetApiResource):
             raise NotFound("Segment not found.")
 
         # validate segment belongs to the specified document
-        if str(segment.document_id) != str(document_id_str):
+        if segment.document_id != document_id_str:
             raise NotFound("Document not found.")
 
         child_chunk_id_str = str(child_chunk_id)
@@ -561,7 +624,7 @@ class DatasetChildChunkApi(DatasetApiResource):
             raise NotFound("Child chunk not found.")
 
         # validate child chunk belongs to the specified segment
-        if str(child_chunk.segment_id) != str(segment.id):
+        if child_chunk.segment_id != segment.id:
             raise NotFound("Child chunk not found.")
 
         try:
@@ -574,14 +637,7 @@ class DatasetChildChunkApi(DatasetApiResource):
     @service_api_ns.expect(service_api_ns.models[ChildChunkUpdatePayload.__name__])
     @service_api_ns.doc("update_child_chunk")
     @service_api_ns.doc(description="Update a specific child chunk")
-    @service_api_ns.doc(
-        params={
-            "dataset_id": "Dataset ID",
-            "document_id": "Document ID",
-            "segment_id": "Parent segment ID",
-            "child_chunk_id": "Child chunk ID to update",
-        }
-    )
+    @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK)
     @service_api_ns.doc(
         responses={
             200: "Child chunk updated successfully",
@@ -589,6 +645,11 @@ class DatasetChildChunkApi(DatasetApiResource):
             404: "Dataset, document, segment, or child chunk not found",
         }
     )
+    @service_api_ns.response(
+        200,
+        "Child chunk updated successfully",
+        service_api_ns.models[ChildChunkDetailResponse.__name__],
+    )
     @cloud_edition_billing_resource_check("vector_space", "dataset")
     @cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
     @cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@@ -616,7 +677,7 @@ class DatasetChildChunkApi(DatasetApiResource):
             raise NotFound("Segment not found.")
 
         # validate segment belongs to the specified document
-        if str(segment.document_id) != str(document_id_str):
+        if segment.document_id != document_id_str:
             raise NotFound("Segment not found.")
 
         child_chunk_id_str = str(child_chunk_id)
@@ -628,7 +689,7 @@ class DatasetChildChunkApi(DatasetApiResource):
             raise NotFound("Child chunk not found.")
 
         # validate child chunk belongs to the specified segment
-        if str(child_chunk.segment_id) != str(segment.id):
+        if child_chunk.segment_id != segment.id:
             raise NotFound("Child chunk not found.")
 
         # validate args
@@ -639,4 +700,4 @@ class DatasetChildChunkApi(DatasetApiResource):
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
 
-        return {"data": marshal(child_chunk, child_chunk_fields)}, 200
+        return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200

api/controllers/web/app.py

@@ -4,7 +4,7 @@ from typing import Any, cast
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, ConfigDict, Field
-from werkzeug.exceptions import Unauthorized
+from werkzeug.exceptions import BadRequest, Unauthorized
 
 from constants import HEADER_NAME_APP_CODE
 from controllers.common import fields
@@ -58,6 +58,9 @@ class AppParameterApi(WebApiResource):
     )
     def get(self, app_model: App, end_user: EndUser):
         """Retrieve app parameters."""
+        if not app_model.enable_site:
+            raise BadRequest("Site is disabled.")
+
         if app_model.mode in {AppMode.ADVANCED_CHAT, AppMode.WORKFLOW}:
             workflow = app_model.workflow
             if workflow is None:

api/core/agent/cot_agent_runner.py

@@ -397,39 +397,40 @@ class CotAgentRunner(BaseAgentRunner, ABC):
         current_scratchpad: AgentScratchpadUnit | None = None
 
         for message in self.history_prompt_messages:
-            if isinstance(message, AssistantPromptMessage):
-                if not current_scratchpad:
-                    assert isinstance(message.content, str)
-                    current_scratchpad = AgentScratchpadUnit(
-                        agent_response=message.content,
-                        thought=message.content or "I am thinking about how to help you",
-                        action_str="",
-                        action=None,
-                        observation=None,
-                    )
-                    scratchpads.append(current_scratchpad)
-                if message.tool_calls:
-                    try:
-                        current_scratchpad.action = AgentScratchpadUnit.Action(
-                            action_name=message.tool_calls[0].function.name,
-                            action_input=json.loads(message.tool_calls[0].function.arguments),
+            match message:
+                case AssistantPromptMessage():
+                    if not current_scratchpad:
+                        assert isinstance(message.content, str)
+                        current_scratchpad = AgentScratchpadUnit(
+                            agent_response=message.content,
+                            thought=message.content or "I am thinking about how to help you",
+                            action_str="",
+                            action=None,
+                            observation=None,
                         )
-                        current_scratchpad.action_str = json.dumps(current_scratchpad.action.to_dict())
-                    except Exception:
-                        logger.exception("Failed to parse tool call from assistant message")
-            elif isinstance(message, ToolPromptMessage):
-                if current_scratchpad:
-                    assert isinstance(message.content, str)
-                    current_scratchpad.observation = message.content
-                else:
-                    raise NotImplementedError("expected str type")
-            elif isinstance(message, UserPromptMessage):
-                if scratchpads:
-                    result.append(AssistantPromptMessage(content=self._format_assistant_message(scratchpads)))
-                    scratchpads = []
-                    current_scratchpad = None
+                        scratchpads.append(current_scratchpad)
+                    if message.tool_calls:
+                        try:
+                            current_scratchpad.action = AgentScratchpadUnit.Action(
+                                action_name=message.tool_calls[0].function.name,
+                                action_input=json.loads(message.tool_calls[0].function.arguments),
+                            )
+                            current_scratchpad.action_str = json.dumps(current_scratchpad.action.to_dict())
+                        except Exception:
+                            logger.exception("Failed to parse tool call from assistant message")
+                case ToolPromptMessage():
+                    if current_scratchpad:
+                        assert isinstance(message.content, str)
+                        current_scratchpad.observation = message.content
+                    else:
+                        raise NotImplementedError("expected str type")
+                case UserPromptMessage():
+                    if scratchpads:
+                        result.append(AssistantPromptMessage(content=self._format_assistant_message(scratchpads)))
+                        scratchpads = []
+                        current_scratchpad = None
 
-                result.append(message)
+                    result.append(message)
 
         if scratchpads:
             result.append(AssistantPromptMessage(content=self._format_assistant_message(scratchpads)))

api/core/agent/cot_completion_agent_runner.py

@@ -39,16 +39,17 @@ class CotCompletionAgentRunner(CotAgentRunner):
         historic_prompt = ""
 
         for message in historic_prompt_messages:
-            if isinstance(message, UserPromptMessage):
-                historic_prompt += f"Question: {message.content}\n\n"
-            elif isinstance(message, AssistantPromptMessage):
-                if isinstance(message.content, str):
-                    historic_prompt += message.content + "\n\n"
-                elif isinstance(message.content, list):
-                    for content in message.content:
-                        if not isinstance(content, TextPromptMessageContent):
-                            continue
-                        historic_prompt += content.data
+            match message:
+                case UserPromptMessage():
+                    historic_prompt += f"Question: {message.content}\n\n"
+                case AssistantPromptMessage():
+                    if isinstance(message.content, str):
+                        historic_prompt += message.content + "\n\n"
+                    elif isinstance(message.content, list):
+                        for content in message.content:
+                            if not isinstance(content, TextPromptMessageContent):
+                                continue
+                            historic_prompt += content.data
 
         return historic_prompt
 

api/core/app/apps/advanced_chat/generate_response_converter.py

@@ -134,17 +134,18 @@ class AdvancedChatAppGenerateResponseConverter(
                 "created_at": chunk.created_at,
             }
 
-            if isinstance(sub_stream_response, MessageEndStreamResponse):
-                sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
-                metadata = sub_stream_response_dict.get("metadata", {})
-                sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
-                response_chunk.update(sub_stream_response_dict)
-            elif isinstance(sub_stream_response, ErrorStreamResponse):
-                data = cls._error_to_stream_response(sub_stream_response.err)
-                response_chunk.update(data)
-            elif isinstance(sub_stream_response, NodeStartStreamResponse | NodeFinishStreamResponse):
-                response_chunk.update(sub_stream_response.to_ignore_detail_dict())
-            else:
-                response_chunk.update(sub_stream_response.model_dump(mode="json"))
+            match sub_stream_response:
+                case MessageEndStreamResponse():
+                    sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
+                    metadata = sub_stream_response_dict.get("metadata", {})
+                    sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
+                    response_chunk.update(sub_stream_response_dict)
+                case ErrorStreamResponse():
+                    data = cls._error_to_stream_response(sub_stream_response.err)
+                    response_chunk.update(data)
+                case NodeStartStreamResponse() | NodeFinishStreamResponse():
+                    response_chunk.update(sub_stream_response.to_ignore_detail_dict())
+                case _:
+                    response_chunk.update(sub_stream_response.model_dump(mode="json"))
 
             yield response_chunk

api/core/app/apps/advanced_chat/generate_task_pipeline.py

@@ -161,16 +161,17 @@ class AdvancedChatAppGenerateTaskPipeline(GraphRuntimeStateSupport):
             stream=stream,
         )
 
-        if isinstance(user, EndUser):
-            self._user_id = user.id
-            user_session_id = user.session_id
-            self._created_by_role = CreatorUserRole.END_USER
-        elif isinstance(user, Account):
-            self._user_id = user.id
-            user_session_id = user.id
-            self._created_by_role = CreatorUserRole.ACCOUNT
-        else:
-            raise NotImplementedError(f"User type not supported: {type(user)}")
+        match user:
+            case EndUser():
+                self._user_id = user.id
+                user_session_id = user.session_id
+                self._created_by_role = CreatorUserRole.END_USER
+            case Account():
+                self._user_id = user.id
+                user_session_id = user.id
+                self._created_by_role = CreatorUserRole.ACCOUNT
+            case _:
+                raise NotImplementedError(f"User type not supported: {type(user)}")
 
         self._workflow_system_variables = build_system_variables(
             query=message.query,

api/core/app/apps/agent_chat/generate_response_converter.py

@@ -112,15 +112,16 @@ class AgentChatAppGenerateResponseConverter(AppGenerateResponseConverter[Chatbot
                 "created_at": chunk.created_at,
             }
 
-            if isinstance(sub_stream_response, MessageEndStreamResponse):
-                sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
-                metadata = sub_stream_response_dict.get("metadata", {})
-                sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
-                response_chunk.update(sub_stream_response_dict)
-            elif isinstance(sub_stream_response, ErrorStreamResponse):
-                data = cls._error_to_stream_response(sub_stream_response.err)
-                response_chunk.update(data)
-            else:
-                response_chunk.update(sub_stream_response.model_dump(mode="json"))
+            match sub_stream_response:
+                case MessageEndStreamResponse():
+                    sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
+                    metadata = sub_stream_response_dict.get("metadata", {})
+                    sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
+                    response_chunk.update(sub_stream_response_dict)
+                case ErrorStreamResponse():
+                    data = cls._error_to_stream_response(sub_stream_response.err)
+                    response_chunk.update(data)
+                case _:
+                    response_chunk.update(sub_stream_response.model_dump(mode="json"))
 
             yield response_chunk

api/core/app/apps/base_app_queue_manager.py

@@ -209,14 +209,16 @@ class AppQueueManager(ABC):
 
     def _check_for_sqlalchemy_models(self, data: Any):
         # from entity to dict or list
-        if isinstance(data, dict):
-            for value in data.values():
-                self._check_for_sqlalchemy_models(value)
-        elif isinstance(data, list):
-            for item in data:
-                self._check_for_sqlalchemy_models(item)
-        else:
-            if isinstance(data, DeclarativeMeta) or hasattr(data, "_sa_instance_state"):
-                raise TypeError(
-                    "Critical Error: Passing SQLAlchemy Model instances that cause thread safety issues is not allowed."
-                )
+        match data:
+            case dict():
+                for value in data.values():
+                    self._check_for_sqlalchemy_models(value)
+            case list():
+                for item in data:
+                    self._check_for_sqlalchemy_models(item)
+            case _:
+                if isinstance(data, DeclarativeMeta) or hasattr(data, "_sa_instance_state"):
+                    raise TypeError(
+                        "Critical Error: Passing SQLAlchemy Model instances that"
+                        " cause thread safety issues is not allowed."
+                    )

api/core/app/apps/base_app_runner.py

@@ -305,26 +305,27 @@ class AppRunner:
                     text += message.content
                 elif isinstance(message.content, list):
                     for content in message.content:
-                        if isinstance(content, str):
-                            text += content
-                        elif isinstance(content, TextPromptMessageContent):
-                            text += content.data
-                        elif isinstance(content, ImagePromptMessageContent):
-                            if message_id and user_id and tenant_id:
-                                try:
-                                    self._handle_multimodal_image_content(
-                                        content=content,
-                                        message_id=message_id,
-                                        user_id=user_id,
-                                        tenant_id=tenant_id,
-                                        queue_manager=queue_manager,
-                                    )
-                                except Exception:
-                                    _logger.exception("Failed to handle multimodal image output")
-                            else:
-                                _logger.warning("Received multimodal output but missing required parameters")
-                        else:
-                            text += content.data if hasattr(content, "data") else str(content)
+                        match content:
+                            case str():
+                                text += content
+                            case TextPromptMessageContent():
+                                text += content.data
+                            case ImagePromptMessageContent():
+                                if message_id and user_id and tenant_id:
+                                    try:
+                                        self._handle_multimodal_image_content(
+                                            content=content,
+                                            message_id=message_id,
+                                            user_id=user_id,
+                                            tenant_id=tenant_id,
+                                            queue_manager=queue_manager,
+                                        )
+                                    except Exception:
+                                        _logger.exception("Failed to handle multimodal image output")
+                                else:
+                                    _logger.warning("Received multimodal output but missing required parameters")
+                            case _:
+                                text += content.data if hasattr(content, "data") else str(content)
 
                 if not model:
                     model = result.model

api/core/app/apps/chat/generate_response_converter.py

@@ -112,15 +112,16 @@ class ChatAppGenerateResponseConverter(AppGenerateResponseConverter[ChatbotAppBl
                 "created_at": chunk.created_at,
             }
 
-            if isinstance(sub_stream_response, MessageEndStreamResponse):
-                sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
-                metadata = sub_stream_response_dict.get("metadata", {})
-                sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
-                response_chunk.update(sub_stream_response_dict)
-            elif isinstance(sub_stream_response, ErrorStreamResponse):
-                data = cls._error_to_stream_response(sub_stream_response.err)
-                response_chunk.update(data)
-            else:
-                response_chunk.update(sub_stream_response.model_dump(mode="json"))
+            match sub_stream_response:
+                case MessageEndStreamResponse():
+                    sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
+                    metadata = sub_stream_response_dict.get("metadata", {})
+                    sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
+                    response_chunk.update(sub_stream_response_dict)
+                case ErrorStreamResponse():
+                    data = cls._error_to_stream_response(sub_stream_response.err)
+                    response_chunk.update(data)
+                case _:
+                    response_chunk.update(sub_stream_response.model_dump(mode="json"))
 
             yield response_chunk

api/core/app/apps/common/workflow_response_converter.py

@@ -276,17 +276,18 @@ class WorkflowResponseConverter:
 
         created_by: CreatedByDict | dict[str, object] = {}
         user = self._user
-        if isinstance(user, Account):
-            created_by = AccountCreatedByDict(
-                id=user.id,
-                name=user.name,
-                email=user.email,
-            )
-        elif isinstance(user, EndUser):
-            created_by = EndUserCreatedByDict(
-                id=user.id,
-                user=user.session_id,
-            )
+        match user:
+            case Account():
+                created_by = AccountCreatedByDict(
+                    id=user.id,
+                    name=user.name,
+                    email=user.email,
+                )
+            case EndUser():
+                created_by = EndUserCreatedByDict(
+                    id=user.id,
+                    user=user.session_id,
+                )
 
         return WorkflowFinishStreamResponse(
             task_id=task_id,
@@ -455,17 +456,18 @@ class WorkflowResponseConverter:
 
         created_by: Mapping[str, object]
         user = creator_user
-        if isinstance(user, Account):
-            created_by = {
-                "id": user.id,
-                "name": user.name,
-                "email": user.email,
-            }
-        else:
-            created_by = {
-                "id": user.id,
-                "user": user.session_id,
-            }
+        match user:
+            case Account():
+                created_by = {
+                    "id": user.id,
+                    "name": user.name,
+                    "email": user.email,
+                }
+            case _:
+                created_by = {
+                    "id": user.id,
+                    "user": user.session_id,
+                }
 
         return WorkflowFinishStreamResponse(
             task_id=task_id,
@@ -562,15 +564,16 @@ class WorkflowResponseConverter:
         outputs, outputs_truncated = self._truncate_mapping(encoded_outputs)
         metadata = self._merge_metadata(event.execution_metadata, snapshot)
 
-        if isinstance(event, QueueNodeSucceededEvent):
-            status = WorkflowNodeExecutionStatus.SUCCEEDED
-            error_message = event.error
-        elif isinstance(event, QueueNodeFailedEvent):
-            status = WorkflowNodeExecutionStatus.FAILED
-            error_message = event.error
-        else:
-            status = WorkflowNodeExecutionStatus.EXCEPTION
-            error_message = event.error
+        match event:
+            case QueueNodeSucceededEvent():
+                status = WorkflowNodeExecutionStatus.SUCCEEDED
+                error_message = event.error
+            case QueueNodeFailedEvent():
+                status = WorkflowNodeExecutionStatus.FAILED
+                error_message = event.error
+            case _:
+                status = WorkflowNodeExecutionStatus.EXCEPTION
+                error_message = event.error
 
         return NodeFinishStreamResponse(
             task_id=task_id,

api/core/app/apps/completion/generate_response_converter.py

@@ -109,17 +109,18 @@ class CompletionAppGenerateResponseConverter(AppGenerateResponseConverter[Comple
                 "created_at": chunk.created_at,
             }
 
-            if isinstance(sub_stream_response, MessageEndStreamResponse):
-                sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
-                metadata = sub_stream_response_dict.get("metadata", {})
-                if not isinstance(metadata, dict):
-                    metadata = {}
-                sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
-                response_chunk.update(sub_stream_response_dict)
-            elif isinstance(sub_stream_response, ErrorStreamResponse):
-                data = cls._error_to_stream_response(sub_stream_response.err)
-                response_chunk.update(data)
-            else:
-                response_chunk.update(sub_stream_response.model_dump(mode="json"))
+            match sub_stream_response:
+                case MessageEndStreamResponse():
+                    sub_stream_response_dict = sub_stream_response.model_dump(mode="json")
+                    metadata = sub_stream_response_dict.get("metadata", {})
+                    if not isinstance(metadata, dict):
+                        metadata = {}
+                    sub_stream_response_dict["metadata"] = cls._get_simple_metadata(metadata)
+                    response_chunk.update(sub_stream_response_dict)
+                case ErrorStreamResponse():
+                    data = cls._error_to_stream_response(sub_stream_response.err)
+                    response_chunk.update(data)
+                case _:
+                    response_chunk.update(sub_stream_response.model_dump(mode="json"))
 
             yield response_chunk

api/core/app/apps/pipeline/generate_response_converter.py

@@ -1,5 +1,5 @@
 from collections.abc import Generator
-from typing import Any, cast
+from typing import Any, cast, override
 
 from core.app.apps.base_app_generate_response_converter import AppGenerateResponseConverter
 from core.app.entities.task_entities import (
@@ -15,6 +15,7 @@ from core.app.entities.task_entities import (
 
 class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter[WorkflowAppBlockingResponse]):
     @classmethod
+    @override
     def convert_blocking_full_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, object]:
         """
         Convert blocking full response.
@@ -24,6 +25,7 @@ class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter[Workflow
         return dict(blocking_response.model_dump())
 
     @classmethod
+    @override
     def convert_blocking_simple_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, object]:
         """
         Convert blocking simple response.
@@ -33,6 +35,7 @@ class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter[Workflow
         return cls.convert_blocking_full_response(blocking_response)
 
     @classmethod
+    @override
     def convert_stream_full_response(
         cls, stream_response: Generator[AppStreamResponse, None, None]
     ) -> Generator[dict[str, Any] | str, None, None]:
@@ -66,6 +69,7 @@ class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter[Workflow
             yield response_chunk
 
     @classmethod
+    @override
     def convert_stream_simple_response(
         cls, stream_response: Generator[AppStreamResponse, None, None]
     ) -> Generator[dict[str, Any] | str, None, None]:

api/core/app/apps/workflow/app_generator.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Any, Literal, overload
 from flask import Flask, current_app
 from pydantic import ValidationError
 from sqlalchemy import select
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
 
 import contexts
 from configs import dify_config
@@ -58,6 +58,25 @@ logger = logging.getLogger(__name__)
 
 
 class WorkflowAppGenerator(BaseAppGenerator):
+    @staticmethod
+    def _ensure_snippet_start_node_in_worker(*, session: Session, workflow: Workflow) -> Workflow:
+        """Re-apply snippet virtual Start injection after worker reloads workflow from DB."""
+        if workflow.kind_or_standard != "snippet":
+            return workflow
+
+        from models.snippet import CustomizedSnippet
+        from services.snippet_generate_service import SnippetGenerateService
+
+        snippet = session.scalar(
+            select(CustomizedSnippet).where(
+                CustomizedSnippet.id == workflow.app_id,
+                CustomizedSnippet.tenant_id == workflow.tenant_id,
+            )
+        )
+        if snippet is None:
+            return workflow
+        return SnippetGenerateService.ensure_start_node_for_worker(workflow, snippet)
+
     @staticmethod
     def _should_prepare_user_inputs(args: Mapping[str, Any]) -> bool:
         return not bool(args.get(SKIP_PREPARE_USER_INPUTS_KEY))
@@ -575,6 +594,8 @@ class WorkflowAppGenerator(BaseAppGenerator):
                 if workflow is None:
                     raise ValueError("Workflow not found")
 
+                workflow = self._ensure_snippet_start_node_in_worker(session=session, workflow=workflow)
+
                 # Determine system_user_id based on invocation source
                 is_external_api_call = application_generate_entity.invoke_from in {
                     InvokeFrom.WEB_APP,

api/core/app/task_pipeline/based_generate_task_pipeline.py

@@ -46,13 +46,14 @@ class BasedGenerateTaskPipeline:
         e = event.error
         err: Exception
 
-        if isinstance(e, InvokeAuthorizationError):
-            err = InvokeAuthorizationError("Incorrect API key provided")
-        elif isinstance(e, InvokeError | ValueError):
-            err = e
-        else:
-            description = getattr(e, "description", None)
-            err = Exception(description if description is not None else str(e))
+        match e:
+            case InvokeAuthorizationError():
+                err = InvokeAuthorizationError("Incorrect API key provided")
+            case InvokeError() | ValueError():
+                err = e
+            case _:
+                description = getattr(e, "description", None)
+                err = Exception(description if description is not None else str(e))
 
         if not message_id or not session:
             return err

api/core/base/tts/app_generator_tts_publisher.py

@@ -91,26 +91,28 @@ class AppGeneratorTTSPublisher:
                         )
                         future_queue.put(futures_result)
                     break
-                elif isinstance(message.event, QueueAgentMessageEvent | QueueLLMChunkEvent):
-                    message_content = message.event.chunk.delta.message.content
-                    if not message_content:
-                        continue
-                    match message_content:
-                        case str():
-                            self.msg_text += message_content
-                        case list():
-                            for content in message_content:
-                                if not isinstance(content, TextPromptMessageContent):
-                                    continue
-                                self.msg_text += content.data
-                elif isinstance(message.event, QueueTextChunkEvent):
-                    self.msg_text += message.event.text
-                elif isinstance(message.event, QueueNodeSucceededEvent):
-                    if message.event.outputs is None:
-                        continue
-                    output = message.event.outputs.get("output", "")
-                    if isinstance(output, str):
-                        self.msg_text += output
+                else:
+                    match message.event:
+                        case QueueAgentMessageEvent() | QueueLLMChunkEvent():
+                            message_content = message.event.chunk.delta.message.content
+                            if not message_content:
+                                continue
+                            match message_content:
+                                case str():
+                                    self.msg_text += message_content
+                                case list():
+                                    for content in message_content:
+                                        if not isinstance(content, TextPromptMessageContent):
+                                            continue
+                                        self.msg_text += content.data
+                        case QueueTextChunkEvent():
+                            self.msg_text += message.event.text
+                        case QueueNodeSucceededEvent():
+                            if message.event.outputs is None:
+                                continue
+                            output = message.event.outputs.get("output", "")
+                            if isinstance(output, str):
+                                self.msg_text += output
                 self.last_message = message
                 sentence_arr, text_tmp = self._extract_sentence(self.msg_text)
                 if len(sentence_arr) >= min(self.max_sentence, 7):

api/core/helper/code_executor/template_transformer.py

@@ -77,17 +77,16 @@ class TemplateTransformer(ABC):
         """
 
         def convert_scientific_notation(value: Any) -> Any:
-            if isinstance(value, str):
-                # Check if the string looks like scientific notation
-                if re.match(r"^-?\d+\.?\d*e[+-]\d+$", value, re.IGNORECASE):
+            match value:
+                case str() if re.match(r"^-?\d+\.?\d*e[+-]\d+$", value, re.IGNORECASE):
                     try:
                         return float(value)
                     except ValueError:
                         pass
-            elif isinstance(value, dict):
-                return {k: convert_scientific_notation(v) for k, v in value.items()}
-            elif isinstance(value, list):
-                return [convert_scientific_notation(v) for v in value]
+                case dict():
+                    return {k: convert_scientific_notation(v) for k, v in value.items()}
+                case list():
+                    return [convert_scientific_notation(v) for v in value]
             return value
 
         return convert_scientific_notation(result)

api/core/logging/filters.py

@@ -83,15 +83,16 @@ class IdentityContextFilter(logging.Filter):
 
             identity: IdentityDict = {}
 
-            if isinstance(user, Account):
-                if user.current_tenant_id:
-                    identity["tenant_id"] = user.current_tenant_id
-                identity["user_id"] = user.id
-                identity["user_type"] = "account"
-            elif isinstance(user, EndUser):
-                identity["tenant_id"] = user.tenant_id
-                identity["user_id"] = user.id
-                identity["user_type"] = user.type or "end_user"
+            match user:
+                case Account():
+                    if user.current_tenant_id:
+                        identity["tenant_id"] = user.current_tenant_id
+                    identity["user_id"] = user.id
+                    identity["user_type"] = "account"
+                case EndUser():
+                    identity["tenant_id"] = user.tenant_id
+                    identity["user_id"] = user.id
+                    identity["user_type"] = user.type or "end_user"
 
             return identity
         except Exception:

api/core/mcp/server/streamable_http.py

@@ -72,20 +72,21 @@ def handle_mcp_request(
 
     try:
         # Dispatch request to appropriate handler based on instance type
-        if isinstance(request_root, mcp_types.InitializeRequest):
-            return create_success_response(handle_initialize(mcp_server.description))
-        elif isinstance(request_root, mcp_types.ListToolsRequest):
-            return create_success_response(
-                handle_list_tools(
-                    app.name, app.mode, user_input_form, mcp_server.description, mcp_server.parameters_dict
+        match request_root:
+            case mcp_types.InitializeRequest():
+                return create_success_response(handle_initialize(mcp_server.description))
+            case mcp_types.ListToolsRequest():
+                return create_success_response(
+                    handle_list_tools(
+                        app.name, app.mode, user_input_form, mcp_server.description, mcp_server.parameters_dict
+                    )
                 )
-            )
-        elif isinstance(request_root, mcp_types.CallToolRequest):
-            return create_success_response(handle_call_tool(app, request, user_input_form, end_user))
-        elif isinstance(request_root, mcp_types.PingRequest):
-            return create_success_response(handle_ping())
-        else:
-            return create_error_response(mcp_types.METHOD_NOT_FOUND, f"Method not found: {request_type.__name__}")
+            case mcp_types.CallToolRequest():
+                return create_success_response(handle_call_tool(app, request, user_input_form, end_user))
+            case mcp_types.PingRequest():
+                return create_success_response(handle_ping())
+            case _:
+                return create_error_response(mcp_types.METHOD_NOT_FOUND, f"Method not found: {request_type.__name__}")
 
     except ValueError as e:
         logger.exception("Invalid params")
@@ -202,12 +203,13 @@ def extract_answer_from_response(app: App, response: Any) -> str:
     """Extract answer from app generate response"""
     answer = ""
 
-    if isinstance(response, RateLimitGenerator):
-        answer = process_streaming_response(response)
-    elif isinstance(response, Mapping):
-        answer = process_mapping_response(app, response)
-    else:
-        logger.warning("Unexpected response type: %s", type(response))
+    match response:
+        case RateLimitGenerator():
+            answer = process_streaming_response(response)
+        case Mapping():
+            answer = process_mapping_response(app, response)
+        case _:
+            logger.warning("Unexpected response type: %s", type(response))
 
     return answer
 

api/core/mcp/session/base_session.py

@@ -240,30 +240,31 @@ class BaseSession[
                     self.check_receiver_status()
                     continue
 
-            if response_or_error is None:
-                raise MCPConnectionError(
-                    ErrorData(
-                        code=500,
-                        message="No response received",
-                    )
-                )
-            elif isinstance(response_or_error, HTTPStatusError):
-                # HTTPStatusError from streamable_client with preserved response object
-                if response_or_error.response.status_code == 401:
-                    raise MCPAuthError(response=response_or_error.response)
-                else:
+            match response_or_error:
+                case None:
                     raise MCPConnectionError(
-                        ErrorData(code=response_or_error.response.status_code, message=str(response_or_error))
+                        ErrorData(
+                            code=500,
+                            message="No response received",
+                        )
                     )
-            elif isinstance(response_or_error, JSONRPCError):
-                if response_or_error.error.code == 401:
-                    raise MCPAuthError(message=response_or_error.error.message)
-                else:
-                    raise MCPConnectionError(
-                        ErrorData(code=response_or_error.error.code, message=response_or_error.error.message)
-                    )
-            else:
-                return result_type.model_validate(response_or_error.result)
+                case HTTPStatusError():
+                    # HTTPStatusError from streamable_client with preserved response object
+                    if response_or_error.response.status_code == 401:
+                        raise MCPAuthError(response=response_or_error.response)
+                    else:
+                        raise MCPConnectionError(
+                            ErrorData(code=response_or_error.response.status_code, message=str(response_or_error))
+                        )
+                case JSONRPCError():
+                    if response_or_error.error.code == 401:
+                        raise MCPAuthError(message=response_or_error.error.message)
+                    else:
+                        raise MCPConnectionError(
+                            ErrorData(code=response_or_error.error.code, message=response_or_error.error.message)
+                        )
+                case _:
+                    return result_type.model_validate(response_or_error.result)
 
         finally:
             self._response_streams.pop(request_id, None)
@@ -316,65 +317,79 @@ class BaseSession[
                 message = self._read_stream.get(timeout=DEFAULT_RESPONSE_READ_TIMEOUT)
                 if message is None:
                     break
-                if isinstance(message, HTTPStatusError):
-                    response_queue = self._response_streams.get(self._request_id - 1)
-                    if response_queue is not None:
-                        # For 401 errors, pass the HTTPStatusError directly to preserve response object
-                        if message.response.status_code == 401:
-                            response_queue.put(message)
-                        else:
-                            response_queue.put(
-                                JSONRPCError(
-                                    jsonrpc="2.0",
-                                    id=self._request_id - 1,
-                                    error=ErrorData(code=message.response.status_code, message=message.args[0]),
+                match message:
+                    case HTTPStatusError():
+                        response_queue = self._response_streams.get(self._request_id - 1)
+                        if response_queue is not None:
+                            # For 401 errors, pass the HTTPStatusError directly to preserve response object
+                            if message.response.status_code == 401:
+                                response_queue.put(message)
+                            else:
+                                response_queue.put(
+                                    JSONRPCError(
+                                        jsonrpc="2.0",
+                                        id=self._request_id - 1,
+                                        error=ErrorData(code=message.response.status_code, message=message.args[0]),
+                                    )
                                 )
-                            )
-                    else:
-                        self._handle_incoming(RuntimeError(f"Received response with an unknown request ID: {message}"))
-                elif isinstance(message, Exception):
-                    self._handle_incoming(message)
-                elif isinstance(message.message.root, JSONRPCRequest):
-                    validated_request = self._receive_request_type.model_validate(
-                        message.message.root.model_dump(by_alias=True, mode="json", exclude_none=True)
-                    )
-
-                    responder = RequestResponder[ReceiveRequestT, SendResultT](
-                        request_id=message.message.root.id,
-                        request_meta=validated_request.root.params.meta if validated_request.root.params else None,
-                        request=validated_request,  # type: ignore[arg-type]  # mypy can't narrow constrained TypeVar from model_validate
-                        session=self,
-                        on_complete=lambda r: self._in_flight.pop(r.request_id, None),
-                    )
-
-                    self._in_flight[responder.request_id] = responder
-                    self._received_request(responder)
-
-                    if not responder.completed:
-                        self._handle_incoming(responder)
-
-                elif isinstance(message.message.root, JSONRPCNotification):
-                    try:
-                        notification = self._receive_notification_type.model_validate(
-                            message.message.root.model_dump(by_alias=True, mode="json", exclude_none=True)
-                        )
-                        # Handle cancellation notifications
-                        if isinstance(notification.root, CancelledNotification):
-                            cancelled_id = notification.root.params.requestId
-                            if cancelled_id in self._in_flight:
-                                self._in_flight[cancelled_id].cancel()
                         else:
-                            self._received_notification(notification)  # type: ignore[arg-type]
-                            self._handle_incoming(notification)  # type: ignore[arg-type]
-                    except Exception as e:
-                        # For other validation errors, log and continue
-                        logger.warning("Failed to validate notification: %s. Message was: %s", e, message.message.root)
-                else:  # Response or error
-                    response_queue = self._response_streams.get(message.message.root.id)
-                    if response_queue is not None:
-                        response_queue.put(message.message.root)
-                    else:
-                        self._handle_incoming(RuntimeError(f"Server Error: {message}"))
+                            self._handle_incoming(
+                                RuntimeError(f"Received response with an unknown request ID: {message}")
+                            )
+                    case Exception():
+                        self._handle_incoming(message)
+                    case SessionMessage(message=JSONRPCMessage(root=JSONRPCRequest())):
+                        request_root = message.message.root
+                        if not isinstance(request_root, JSONRPCRequest):
+                            continue
+
+                        validated_request = self._receive_request_type.model_validate(
+                            request_root.model_dump(by_alias=True, mode="json", exclude_none=True)
+                        )
+
+                        responder = RequestResponder[ReceiveRequestT, SendResultT](
+                            request_id=request_root.id,
+                            request_meta=validated_request.root.params.meta if validated_request.root.params else None,
+                            request=validated_request,  # type: ignore[arg-type]  # mypy can't narrow constrained TypeVar from model_validate
+                            session=self,
+                            on_complete=lambda r: self._in_flight.pop(r.request_id, None),
+                        )
+
+                        self._in_flight[responder.request_id] = responder
+                        self._received_request(responder)
+
+                        if not responder.completed:
+                            self._handle_incoming(responder)
+
+                    case SessionMessage(message=JSONRPCMessage(root=JSONRPCNotification())):
+                        try:
+                            notification = self._receive_notification_type.model_validate(
+                                message.message.root.model_dump(by_alias=True, mode="json", exclude_none=True)
+                            )
+                            # Handle cancellation notifications
+                            if isinstance(notification.root, CancelledNotification):
+                                cancelled_id = notification.root.params.requestId
+                                if cancelled_id in self._in_flight:
+                                    self._in_flight[cancelled_id].cancel()
+                            else:
+                                self._received_notification(notification)  # type: ignore[arg-type]
+                                self._handle_incoming(notification)  # type: ignore[arg-type]
+                        except Exception as e:
+                            # For other validation errors, log and continue
+                            logger.warning(
+                                "Failed to validate notification: %s. Message was: %s", e, message.message.root
+                            )
+                    case _:  # Response or error
+                        response_root = message.message.root
+                        if not isinstance(response_root, (JSONRPCResponse, JSONRPCError)):
+                            self._handle_incoming(RuntimeError(f"Server Error: {message}"))
+                            continue
+
+                        response_queue = self._response_streams.get(response_root.id)
+                        if response_queue is not None:
+                            response_queue.put(response_root)
+                        else:
+                            self._handle_incoming(RuntimeError(f"Server Error: {message}"))
             except queue.Empty:
                 continue
             except Exception:

api/core/rag/extractor/blob/blob.py

@@ -54,36 +54,39 @@ class Blob(BaseModel):
 
     def as_string(self) -> str:
         """Read data as a string."""
-        if self.data is None and self.path:
-            return Path(str(self.path)).read_text(encoding=self.encoding)
-        elif isinstance(self.data, bytes):
-            return self.data.decode(self.encoding)
-        elif isinstance(self.data, str):
-            return self.data
-        else:
-            raise ValueError(f"Unable to get string for blob {self}")
+        match self.data:
+            case None if self.path:
+                return Path(str(self.path)).read_text(encoding=self.encoding)
+            case bytes():
+                return self.data.decode(self.encoding)
+            case str():
+                return self.data
+            case _:
+                raise ValueError(f"Unable to get string for blob {self}")
 
     def as_bytes(self) -> bytes:
         """Read data as bytes."""
-        if isinstance(self.data, bytes):
-            return self.data
-        elif isinstance(self.data, str):
-            return self.data.encode(self.encoding)
-        elif self.data is None and self.path:
-            return Path(str(self.path)).read_bytes()
-        else:
-            raise ValueError(f"Unable to get bytes for blob {self}")
+        match self.data:
+            case bytes():
+                return self.data
+            case str():
+                return self.data.encode(self.encoding)
+            case None if self.path:
+                return Path(str(self.path)).read_bytes()
+            case _:
+                raise ValueError(f"Unable to get bytes for blob {self}")
 
     @contextlib.contextmanager
     def as_bytes_io(self) -> Generator[BytesIO | BufferedReader, None, None]:
         """Read data as a byte stream."""
-        if isinstance(self.data, bytes):
-            yield BytesIO(self.data)
-        elif self.data is None and self.path:
-            with open(str(self.path), "rb") as f:
-                yield f
-        else:
-            raise NotImplementedError(f"Unable to convert blob {self}")
+        match self.data:
+            case bytes():
+                yield BytesIO(self.data)
+            case None if self.path:
+                with open(str(self.path), "rb") as f:
+                    yield f
+            case _:
+                raise NotImplementedError(f"Unable to convert blob {self}")
 
     @classmethod
     def from_path(

api/core/rag/retrieval/dataset_retrieval.py

@@ -1525,16 +1525,18 @@ class DatasetRetrieval:
                 filters.append(json_field.like(f"%{escaped_value}", escape="\\"))
 
             case "is" | "=":
-                if isinstance(value, str):
-                    filters.append(json_field == value)
-                elif isinstance(value, (int, float)):
-                    filters.append(DatasetDocument.doc_metadata[metadata_name].as_float() == value)
+                match value:
+                    case str():
+                        filters.append(json_field == value)
+                    case int() | float():
+                        filters.append(DatasetDocument.doc_metadata[metadata_name].as_float() == value)
 
             case "is not" | "≠":
-                if isinstance(value, str):
-                    filters.append(json_field != value)
-                elif isinstance(value, (int, float)):
-                    filters.append(DatasetDocument.doc_metadata[metadata_name].as_float() != value)
+                match value:
+                    case str():
+                        filters.append(json_field != value)
+                    case int() | float():
+                        filters.append(DatasetDocument.doc_metadata[metadata_name].as_float() != value)
 
             case "empty":
                 filters.append(DatasetDocument.doc_metadata[metadata_name].is_(None))
@@ -1554,12 +1556,13 @@ class DatasetRetrieval:
             case "≥" | ">=":
                 filters.append(DatasetDocument.doc_metadata[metadata_name].as_float() >= value)
             case "in" | "not in":
-                if isinstance(value, str):
-                    value_list = [v.strip() for v in value.split(",") if v.strip()]
-                elif isinstance(value, (list, tuple)):
-                    value_list = [str(v) for v in value if v is not None]
-                else:
-                    value_list = [str(value)] if value is not None else []
+                match value:
+                    case str():
+                        value_list = [v.strip() for v in value.split(",") if v.strip()]
+                    case list() | tuple():
+                        value_list = [str(v) for v in value if v is not None]
+                    case _:
+                        value_list = [str(value)] if value is not None else []
 
                 if not value_list:
                     # `field in []` is False, `field not in []` is True
@@ -1706,12 +1709,13 @@ class DatasetRetrieval:
         usage = None
         for result in invoke_result:
             text = result.delta.message.content
-            if isinstance(text, str):
-                full_text += text
-            elif isinstance(text, list):
-                for i in text:
-                    if i.data:
-                        full_text += i.data
+            match text:
+                case str():
+                    full_text += text
+                case list():
+                    for i in text:
+                        if i.data:
+                            full_text += i.data
 
             if not model:
                 model = result.model

api/core/tools/tool_manager.py

@@ -863,7 +863,7 @@ class ToolManager:
         return controller
 
     @classmethod
-    def user_get_api_provider(cls, provider: str, tenant_id: str):
+    def user_get_api_provider(cls, provider: str, tenant_id: str, mask: bool = True):
         """
         get api provider
         """
@@ -902,8 +902,10 @@ class ToolManager:
             tenant_id=tenant_id,
             controller=controller,
         )
-
-        masked_credentials = encrypter.mask_plugin_credentials(encrypter.decrypt(credentials))
+        if mask:
+            masked_credentials = encrypter.mask_plugin_credentials(encrypter.decrypt(credentials))
+        else:
+            masked_credentials = encrypter.decrypt(credentials)
 
         try:
             icon = emoji_icon_adapter.validate_json(provider_obj.icon)

api/core/tools/utils/parser.py

@@ -6,7 +6,7 @@ from json.decoder import JSONDecodeError
 from typing import Any, TypedDict
 
 import httpx
-from flask import request
+from flask import has_request_context, request
 from yaml import YAMLError, safe_load
 
 from core.tools.entities.common_entities import I18nObject
@@ -44,7 +44,7 @@ class ApiBasedToolSchemaParser:
             raise ToolProviderNotFoundError("No server found in the openapi yaml.")
 
         server_url = openapi["servers"][0]["url"]
-        request_env = request.headers.get("X-Request-Env")
+        request_env = request.headers.get("X-Request-Env") if has_request_context() else None
         if request_env:
             matched_servers = [server["url"] for server in openapi["servers"] if server["env"] == request_env]
             server_url = matched_servers[0] if matched_servers else server_url

api/core/workflow/snippet_start.py

@@ -0,0 +1,21 @@
+"""Shared snippet virtual Start-node identifiers and compatibility helpers.
+
+Snippet workflows do not persist a real canvas Start node, so the backend
+injects one at runtime. Existing workflow references commonly use the public
+selector shape ``#start.<var>#``; keep that contract stable by treating the
+runtime-only snippet Start node as compatible with the legacy ``start`` id.
+"""
+
+from __future__ import annotations
+
+
+LEGACY_START_NODE_ID = "start"
+SNIPPET_VIRTUAL_START_NODE_ID = "__snippet_virtual_start__"
+
+
+def get_compatible_start_aliases(*, workflow_kind: str | None, root_node_id: str | None) -> tuple[str, ...]:
+    """Return additional selector ids that should mirror snippet Start inputs."""
+    if workflow_kind == "snippet" and root_node_id == SNIPPET_VIRTUAL_START_NODE_ID:
+        return (LEGACY_START_NODE_ID,)
+
+    return ()

api/core/workflow/variable_pool_initializer.py

@@ -10,6 +10,19 @@ def add_variables_to_pool(variable_pool: VariablePool, variables: Sequence[Varia
         variable_pool.add(variable.selector, variable)
 
 
-def add_node_inputs_to_pool(variable_pool: VariablePool, *, node_id: str, inputs: Mapping[str, Any]) -> None:
-    for key, value in inputs.items():
-        variable_pool.add((node_id, key), value)
+def add_node_inputs_to_pool(
+    variable_pool: VariablePool,
+    *,
+    node_id: str,
+    inputs: Mapping[str, Any],
+    aliases: Sequence[str] = (),
+) -> None:
+    """Store node inputs under the primary node id and any compatible aliases."""
+    node_ids: list[str] = [node_id]
+    for alias in aliases:
+        if alias not in node_ids:
+            node_ids.append(alias)
+
+    for current_node_id in node_ids:
+        for key, value in inputs.items():
+            variable_pool.add((current_node_id, key), value)

api/dev/generate_swagger_markdown_docs.py

@@ -103,7 +103,11 @@ def _replace_schema_table_type(markdown: str, definition_name: str, row_name: st
         lines[index] = "|".join(cells)
         break
 
-    return "\n".join(lines)
+    return "\n".join(lines) + ("\n" if markdown.endswith("\n") else "")
+
+
+def _has_union_schema(schema: object) -> bool:
+    return isinstance(schema, dict) and (isinstance(schema.get("oneOf"), list) or isinstance(schema.get("anyOf"), list))
 
 
 def _patch_union_schema_markdown(markdown: str, spec_path: Path) -> str:
@@ -117,8 +121,20 @@ def _patch_union_schema_markdown(markdown: str, spec_path: Path) -> str:
     for definition_name, schema in definitions.items():
         if not isinstance(definition_name, str) or not isinstance(schema, dict):
             continue
-        one_of = schema.get("oneOf")
-        if not isinstance(one_of, list):
+
+        properties = schema.get("properties")
+        if isinstance(properties, dict):
+            for property_name, property_schema in properties.items():
+                if isinstance(property_name, str) and _has_union_schema(property_schema):
+                    markdown = _replace_schema_table_type(
+                        markdown,
+                        definition_name,
+                        property_name,
+                        _schema_markdown_type(property_schema),
+                    )
+
+        union_variants = schema.get("oneOf") or schema.get("anyOf")
+        if not isinstance(union_variants, list):
             continue
 
         markdown = _replace_schema_table_type(
@@ -128,7 +144,7 @@ def _patch_union_schema_markdown(markdown: str, spec_path: Path) -> str:
             _schema_markdown_type(schema),
         )
 
-        for variant in one_of:
+        for variant in union_variants:
             variant_name = _definition_ref_name(variant)
             variant_schema = definitions.get(variant_name) if variant_name is not None else None
             if not isinstance(variant_name, str) or not isinstance(variant_schema, dict):
@@ -150,7 +166,7 @@ def _patch_union_schema_markdown(markdown: str, spec_path: Path) -> str:
 
 def _convert_spec_to_markdown(spec_path: Path, markdown_path: Path) -> None:
     markdown_path.parent.mkdir(parents=True, exist_ok=True)
-    with tempfile.TemporaryDirectory(prefix=f"{markdown_path.stem}-", dir=markdown_path.parent) as temp_dir:
+    with tempfile.TemporaryDirectory(prefix=f"{markdown_path.stem}-") as temp_dir:
         temp_markdown_path = Path(temp_dir) / markdown_path.name
         result = subprocess.run(
             [
@@ -158,12 +174,13 @@ def _convert_spec_to_markdown(spec_path: Path, markdown_path: Path) -> None:
                 "--yes",
                 SWAGGER_MARKDOWN_PACKAGE,
                 "-i",
-                str(spec_path),
+                str(spec_path.resolve()),
                 "-o",
-                str(temp_markdown_path),
+                str(temp_markdown_path.resolve()),
             ],
             check=False,
             capture_output=True,
+            cwd=temp_dir,
             text=True,
         )
         if result.returncode != 0:

api/events/event_handlers/delete_tool_parameters_cache_when_sync_draft_workflow.py

@@ -1,6 +1,7 @@
 import logging
 
 from core.tools.entities.tool_entities import ToolProviderType
+from core.tools.errors import ToolProviderNotFoundError
 from core.tools.tool_manager import ToolManager
 from core.tools.utils.configuration import ToolParameterConfigurationManager
 from core.workflow.human_input_adapter import adapt_node_config_for_graph
@@ -38,6 +39,14 @@ def handle(sender, **kwargs):
                     identity_id=f"WORKFLOW.{app.id}.{node_data.get('id')}",
                 )
                 manager.delete_tool_parameters_cache()
+            except ToolProviderNotFoundError as exc:
+                logger.info(
+                    "Skipped deleting tool parameters cache for workflow %s node %s "
+                    "because tool provider is missing: %s",
+                    app.id,
+                    node_data.get("id"),
+                    exc,
+                )
             except Exception:
                 # tool dose not exist
                 logger.exception(

api/extensions/ext_commands.py

@@ -15,14 +15,18 @@ def init_app(app: DifyApp):
         data_migrate,
         delete_archived_workflow_runs,
         export_app_messages,
+        export_migration_data,
+        export_migration_data_template,
         extract_plugins,
         extract_unique_plugins,
         file_usage,
         fix_app_site_missing,
+        import_migration_data,
         install_plugins,
         install_rag_pipeline_plugins,
         migrate_data_for_plugin,
         migrate_oss,
+        migration_data_wizard,
         old_metadata_migration,
         remove_orphaned_files_on_storage,
         reset_email,
@@ -70,6 +74,10 @@ def init_app(app: DifyApp):
         clean_workflow_runs,
         clean_expired_messages,
         export_app_messages,
+        export_migration_data,
+        export_migration_data_template,
+        import_migration_data,
+        migration_data_wizard,
     ]
     for cmd in cmds_to_register:
         app.cli.add_command(cmd)

api/extensions/storage/aliyun_oss_storage.py

@@ -1,5 +1,6 @@
 import posixpath
 from collections.abc import Generator
+from typing import override
 
 import oss2 as aliyun_s3
 
@@ -29,9 +30,11 @@ class AliyunOssStorage(BaseStorage):
             cloudbox_id=dify_config.ALIYUN_CLOUDBOX_ID,
         )
 
+    @override
     def save(self, filename, data):
         self.client.put_object(self.__wrapper_folder_filename(filename), data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         obj = self.client.get_object(self.__wrapper_folder_filename(filename))
         data = obj.read()
@@ -39,17 +42,21 @@ class AliyunOssStorage(BaseStorage):
             return b""
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         obj = self.client.get_object(self.__wrapper_folder_filename(filename))
         while chunk := obj.read(4096):
             yield chunk
 
+    @override
     def download(self, filename: str, target_filepath):
         self.client.get_object_to_file(self.__wrapper_folder_filename(filename), target_filepath)
 
+    @override
     def exists(self, filename: str):
         return self.client.object_exists(self.__wrapper_folder_filename(filename))
 
+    @override
     def delete(self, filename: str):
         self.client.delete_object(self.__wrapper_folder_filename(filename))
 

api/extensions/storage/aws_s3_storage.py

@@ -1,5 +1,6 @@
 import logging
 from collections.abc import Generator
+from typing import override
 
 import boto3
 from botocore.client import Config
@@ -48,9 +49,11 @@ class AwsS3Storage(BaseStorage):
                 # other error, raise exception
                 raise
 
+    @override
     def save(self, filename, data):
         self.client.put_object(Bucket=self.bucket_name, Key=filename, Body=data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         try:
             data: bytes = self.client.get_object(Bucket=self.bucket_name, Key=filename)["Body"].read()
@@ -61,6 +64,7 @@ class AwsS3Storage(BaseStorage):
                 raise
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         try:
             response = self.client.get_object(Bucket=self.bucket_name, Key=filename)
@@ -73,9 +77,11 @@ class AwsS3Storage(BaseStorage):
             else:
                 raise
 
+    @override
     def download(self, filename, target_filepath):
         self.client.download_file(self.bucket_name, filename, target_filepath)
 
+    @override
     def exists(self, filename):
         try:
             self.client.head_object(Bucket=self.bucket_name, Key=filename)
@@ -83,5 +89,6 @@ class AwsS3Storage(BaseStorage):
         except:
             return False
 
+    @override
     def delete(self, filename: str):
         self.client.delete_object(Bucket=self.bucket_name, Key=filename)

api/extensions/storage/azure_blob_storage.py

@@ -1,5 +1,6 @@
 from collections.abc import Generator
 from datetime import timedelta
+from typing import override
 
 from azure.identity import ChainedTokenCredential, DefaultAzureCredential
 from azure.storage.blob import AccountSasPermissions, BlobServiceClient, ResourceTypes, generate_account_sas
@@ -26,6 +27,7 @@ class AzureBlobStorage(BaseStorage):
         else:
             self.credential = None
 
+    @override
     def save(self, filename, data):
         if not self.bucket_name:
             return
@@ -34,6 +36,7 @@ class AzureBlobStorage(BaseStorage):
         blob_container = client.get_container_client(container=self.bucket_name)
         blob_container.upload_blob(filename, data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         if not self.bucket_name:
             raise FileNotFoundError("Azure bucket name is not configured.")
@@ -46,6 +49,7 @@ class AzureBlobStorage(BaseStorage):
             raise TypeError(f"Expected bytes from blob.readall(), got {type(data).__name__}")
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         if not self.bucket_name:
             raise FileNotFoundError("Azure bucket name is not configured.")
@@ -55,6 +59,7 @@ class AzureBlobStorage(BaseStorage):
         blob_data = blob.download_blob()
         yield from blob_data.chunks()
 
+    @override
     def download(self, filename, target_filepath):
         if not self.bucket_name:
             return
@@ -66,6 +71,7 @@ class AzureBlobStorage(BaseStorage):
             blob_data = blob.download_blob()
             blob_data.readinto(my_blob)
 
+    @override
     def exists(self, filename):
         if not self.bucket_name:
             return False
@@ -75,6 +81,7 @@ class AzureBlobStorage(BaseStorage):
         blob = client.get_blob_client(container=self.bucket_name, blob=filename)
         return blob.exists()
 
+    @override
     def delete(self, filename: str):
         if not self.bucket_name:
             return

api/extensions/storage/baidu_obs_storage.py

@@ -1,6 +1,7 @@
 import base64
 import hashlib
 from collections.abc import Generator
+from typing import override
 
 from baidubce.auth.bce_credentials import BceCredentials
 from baidubce.bce_client_configuration import BceClientConfiguration
@@ -26,6 +27,7 @@ class BaiduObsStorage(BaseStorage):
 
         self.client = BosClient(config=client_config)
 
+    @override
     def save(self, filename, data):
         md5 = hashlib.md5()
         md5.update(data)
@@ -34,24 +36,29 @@ class BaiduObsStorage(BaseStorage):
             bucket_name=self.bucket_name, key=filename, data=data, content_length=len(data), content_md5=content_md5
         )
 
+    @override
     def load_once(self, filename: str) -> bytes:
         response = self.client.get_object(bucket_name=self.bucket_name, key=filename)
         data: bytes = response.data.read()
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         response = self.client.get_object(bucket_name=self.bucket_name, key=filename).data
         while chunk := response.read(4096):
             yield chunk
 
+    @override
     def download(self, filename, target_filepath):
         self.client.get_object_to_file(bucket_name=self.bucket_name, key=filename, file_name=target_filepath)
 
+    @override
     def exists(self, filename):
         res = self.client.get_object_meta_data(bucket_name=self.bucket_name, key=filename)
         if res is None:
             return False
         return True
 
+    @override
     def delete(self, filename: str):
         self.client.delete_object(bucket_name=self.bucket_name, key=filename)

api/extensions/storage/clickzetta_volume/clickzetta_volume_storage.py

@@ -10,7 +10,7 @@ import tempfile
 from collections.abc import Generator
 from io import BytesIO
 from pathlib import Path
-from typing import Any
+from typing import Any, override
 
 import clickzetta
 from pydantic import BaseModel, model_validator
@@ -251,6 +251,7 @@ class ClickZettaVolumeStorage(BaseStorage):
             # Don't raise exception, let the operation continue
             # The table might exist but not be visible due to permissions
 
+    @override
     def save(self, filename: str, data: bytes):
         """Save data to ClickZetta Volume.
 
@@ -304,6 +305,7 @@ class ClickZettaVolumeStorage(BaseStorage):
             # Clean up temporary file
             Path(temp_file_path).unlink(missing_ok=True)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         """Load file content from ClickZetta Volume.
 
@@ -364,6 +366,7 @@ class ClickZettaVolumeStorage(BaseStorage):
             logger.debug("File %s loaded from ClickZetta Volume", filename)
             return content
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         """Load file as stream from ClickZetta Volume.
 
@@ -382,6 +385,7 @@ class ClickZettaVolumeStorage(BaseStorage):
 
         logger.debug("File %s loaded as stream from ClickZetta Volume", filename)
 
+    @override
     def download(self, filename: str, target_filepath: str):
         """Download file from ClickZetta Volume to local path.
 
@@ -395,6 +399,7 @@ class ClickZettaVolumeStorage(BaseStorage):
 
         logger.debug("File %s downloaded from ClickZetta Volume to %s", filename, target_filepath)
 
+    @override
     def exists(self, filename: str) -> bool:
         """Check if file exists in ClickZetta Volume.
 
@@ -436,6 +441,7 @@ class ClickZettaVolumeStorage(BaseStorage):
             logger.warning("Error checking file existence for %s: %s", filename, e)
             return False
 
+    @override
     def delete(self, filename: str):
         """Delete file from ClickZetta Volume.
 
@@ -472,6 +478,7 @@ class ClickZettaVolumeStorage(BaseStorage):
 
         logger.debug("File %s deleted from ClickZetta Volume", filename)
 
+    @override
     def scan(self, path: str, files: bool = True, directories: bool = False) -> list[str]:
         """Scan files and directories in ClickZetta Volume.
 

api/extensions/storage/google_cloud_storage.py

@@ -1,7 +1,7 @@
 import base64
 import io
 from collections.abc import Generator
-from typing import Any
+from typing import Any, override
 
 from google.cloud import storage as google_cloud_storage  # type: ignore
 from pydantic import TypeAdapter
@@ -29,12 +29,14 @@ class GoogleCloudStorage(BaseStorage):
         else:
             self.client = google_cloud_storage.Client()
 
+    @override
     def save(self, filename, data):
         bucket = self.client.get_bucket(self.bucket_name)
         blob = bucket.blob(filename)
         with io.BytesIO(data) as stream:
             blob.upload_from_file(stream)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         bucket = self.client.get_bucket(self.bucket_name)
         blob = bucket.get_blob(filename)
@@ -43,6 +45,7 @@ class GoogleCloudStorage(BaseStorage):
         data: bytes = blob.download_as_bytes()
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         bucket = self.client.get_bucket(self.bucket_name)
         blob = bucket.get_blob(filename)
@@ -52,6 +55,7 @@ class GoogleCloudStorage(BaseStorage):
             while chunk := blob_stream.read(4096):
                 yield chunk
 
+    @override
     def download(self, filename, target_filepath):
         bucket = self.client.get_bucket(self.bucket_name)
         blob = bucket.get_blob(filename)
@@ -59,11 +63,13 @@ class GoogleCloudStorage(BaseStorage):
             raise FileNotFoundError("File not found")
         blob.download_to_filename(target_filepath)
 
+    @override
     def exists(self, filename):
         bucket = self.client.get_bucket(self.bucket_name)
         blob = bucket.blob(filename)
         return blob.exists()
 
+    @override
     def delete(self, filename: str):
         bucket = self.client.get_bucket(self.bucket_name)
         bucket.delete_blob(filename)

api/extensions/storage/huawei_obs_storage.py

@@ -1,4 +1,5 @@
 from collections.abc import Generator
+from typing import override
 
 from obs import ObsClient
 
@@ -20,27 +21,33 @@ class HuaweiObsStorage(BaseStorage):
             path_style=dify_config.HUAWEI_OBS_PATH_STYLE,
         )
 
+    @override
     def save(self, filename, data):
         self.client.putObject(bucketName=self.bucket_name, objectKey=filename, content=data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         data: bytes = self.client.getObject(bucketName=self.bucket_name, objectKey=filename)["body"].response.read()
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         response = self.client.getObject(bucketName=self.bucket_name, objectKey=filename)["body"].response
         while chunk := response.read(4096):
             yield chunk
 
+    @override
     def download(self, filename, target_filepath):
         self.client.getObject(bucketName=self.bucket_name, objectKey=filename, downloadPath=target_filepath)
 
+    @override
     def exists(self, filename):
         res = self._get_meta(filename)
         if res is None:
             return False
         return True
 
+    @override
     def delete(self, filename: str):
         self.client.deleteObject(bucketName=self.bucket_name, objectKey=filename)
 

api/extensions/storage/opendal_storage.py

@@ -2,7 +2,7 @@ import logging
 import os
 from collections.abc import Generator
 from pathlib import Path
-from typing import Any
+from typing import Any, override
 
 import opendal
 from dotenv import dotenv_values
@@ -41,10 +41,12 @@ class OpenDALStorage(BaseStorage):
         logger.debug("opendal operator created with scheme %s", scheme)
         logger.debug("added retry layer to opendal operator")
 
+    @override
     def save(self, filename: str, data: bytes):
         self.op.write(path=filename, bs=data)
         logger.debug("file %s saved", filename)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         if not self.exists(filename):
             raise FileNotFoundError("File not found")
@@ -53,6 +55,7 @@ class OpenDALStorage(BaseStorage):
         logger.debug("file %s loaded", filename)
         return content
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         if not self.exists(filename):
             raise FileNotFoundError("File not found")
@@ -67,6 +70,7 @@ class OpenDALStorage(BaseStorage):
                 yield chunk
         logger.debug("file %s loaded as stream", filename)
 
+    @override
     def download(self, filename: str, target_filepath: str):
         if not self.exists(filename):
             raise FileNotFoundError("File not found")
@@ -74,9 +78,11 @@ class OpenDALStorage(BaseStorage):
         Path(target_filepath).write_bytes(self.op.read(path=filename))
         logger.debug("file %s downloaded to %s", filename, target_filepath)
 
+    @override
     def exists(self, filename: str) -> bool:
         return self.op.exists(path=filename)
 
+    @override
     def delete(self, filename: str):
         if self.exists(filename):
             self.op.delete(path=filename)
@@ -84,6 +90,7 @@ class OpenDALStorage(BaseStorage):
             return
         logger.debug("file %s not found, skip delete", filename)
 
+    @override
     def scan(self, path: str, files: bool = True, directories: bool = False) -> list[str]:
         if not self.exists(path):
             raise FileNotFoundError("Path not found")

api/extensions/storage/oracle_oci_storage.py

@@ -1,4 +1,5 @@
 from collections.abc import Generator
+from typing import override
 
 import boto3
 from botocore.exceptions import ClientError
@@ -22,9 +23,11 @@ class OracleOCIStorage(BaseStorage):
             region_name=dify_config.OCI_REGION,
         )
 
+    @override
     def save(self, filename, data):
         self.client.put_object(Bucket=self.bucket_name, Key=filename, Body=data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         try:
             data: bytes = self.client.get_object(Bucket=self.bucket_name, Key=filename)["Body"].read()
@@ -35,6 +38,7 @@ class OracleOCIStorage(BaseStorage):
                 raise
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         try:
             response = self.client.get_object(Bucket=self.bucket_name, Key=filename)
@@ -45,9 +49,11 @@ class OracleOCIStorage(BaseStorage):
             else:
                 raise
 
+    @override
     def download(self, filename, target_filepath):
         self.client.download_file(self.bucket_name, filename, target_filepath)
 
+    @override
     def exists(self, filename):
         try:
             self.client.head_object(Bucket=self.bucket_name, Key=filename)
@@ -55,5 +61,6 @@ class OracleOCIStorage(BaseStorage):
         except:
             return False
 
+    @override
     def delete(self, filename: str):
         self.client.delete_object(Bucket=self.bucket_name, Key=filename)

api/extensions/storage/supabase_storage.py

@@ -1,6 +1,7 @@
 import io
 from collections.abc import Generator
 from pathlib import Path
+from typing import override
 
 from supabase import Client
 
@@ -28,29 +29,35 @@ class SupabaseStorage(BaseStorage):
         if not self.bucket_exists():
             self.client.storage.create_bucket(id=id, name=bucket_name)
 
+    @override
     def save(self, filename, data):
         self.client.storage.from_(self.bucket_name).upload(filename, data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         content: bytes = self.client.storage.from_(self.bucket_name).download(filename)
         return content
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         result = self.client.storage.from_(self.bucket_name).download(filename)
         byte_stream = io.BytesIO(result)
         while chunk := byte_stream.read(4096):  # Read in chunks of 4KB
             yield chunk
 
+    @override
     def download(self, filename, target_filepath):
         result = self.client.storage.from_(self.bucket_name).download(filename)
         Path(target_filepath).write_bytes(result)
 
+    @override
     def exists(self, filename):
         result = self.client.storage.from_(self.bucket_name).list(path=filename)
         if len(result) > 0:
             return True
         return False
 
+    @override
     def delete(self, filename: str):
         self.client.storage.from_(self.bucket_name).remove([filename])
 

api/extensions/storage/tencent_cos_storage.py

@@ -1,4 +1,5 @@
 from collections.abc import Generator
+from typing import override
 
 from qcloud_cos import CosConfig, CosS3Client
 
@@ -29,23 +30,29 @@ class TencentCosStorage(BaseStorage):
             )
         self.client = CosS3Client(config)
 
+    @override
     def save(self, filename, data):
         self.client.put_object(Bucket=self.bucket_name, Body=data, Key=filename)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         data: bytes = self.client.get_object(Bucket=self.bucket_name, Key=filename)["Body"].get_raw_stream().read()
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         response = self.client.get_object(Bucket=self.bucket_name, Key=filename)
         yield from response["Body"].get_stream(chunk_size=4096)
 
+    @override
     def download(self, filename, target_filepath):
         response = self.client.get_object(Bucket=self.bucket_name, Key=filename)
         response["Body"].get_stream_to_file(target_filepath)
 
+    @override
     def exists(self, filename):
         return self.client.object_exists(Bucket=self.bucket_name, Key=filename)
 
+    @override
     def delete(self, filename: str):
         self.client.delete_object(Bucket=self.bucket_name, Key=filename)

api/extensions/storage/volcengine_tos_storage.py

@@ -1,4 +1,5 @@
 from collections.abc import Generator
+from typing import override
 
 import tos
 
@@ -27,11 +28,13 @@ class VolcengineTosStorage(BaseStorage):
             region=dify_config.VOLCENGINE_TOS_REGION,
         )
 
+    @override
     def save(self, filename, data):
         if not self.bucket_name:
             raise ValueError("VOLCENGINE_TOS_BUCKET_NAME is not set")
         self.client.put_object(bucket=self.bucket_name, key=filename, content=data)
 
+    @override
     def load_once(self, filename: str) -> bytes:
         if not self.bucket_name:
             raise FileNotFoundError("VOLCENGINE_TOS_BUCKET_NAME is not set")
@@ -40,6 +43,7 @@ class VolcengineTosStorage(BaseStorage):
             raise TypeError(f"Expected bytes, got {type(data).__name__}")
         return data
 
+    @override
     def load_stream(self, filename: str) -> Generator:
         if not self.bucket_name:
             raise FileNotFoundError("VOLCENGINE_TOS_BUCKET_NAME is not set")
@@ -47,11 +51,13 @@ class VolcengineTosStorage(BaseStorage):
         while chunk := response.read(4096):
             yield chunk
 
+    @override
     def download(self, filename, target_filepath):
         if not self.bucket_name:
             raise ValueError("VOLCENGINE_TOS_BUCKET_NAME is not set")
         self.client.get_object_to_file(bucket=self.bucket_name, key=filename, file_path=target_filepath)
 
+    @override
     def exists(self, filename):
         if not self.bucket_name:
             return False
@@ -60,6 +66,7 @@ class VolcengineTosStorage(BaseStorage):
             return False
         return True
 
+    @override
     def delete(self, filename: str):
         if not self.bucket_name:
             return

api/fields/agent_fields.py

@@ -0,0 +1,192 @@
+from typing import Any, Literal
+
+from pydantic import Field
+
+from fields.base import ResponseModel
+from models.agent import (
+    AgentConfigRevisionOperation,
+    AgentIconType,
+    AgentKind,
+    AgentScope,
+    AgentSource,
+    AgentStatus,
+    WorkflowAgentBindingType,
+)
+from models.agent_config_entities import (
+    AgentSoulConfig,
+    DeclaredOutputConfig,
+    DeclaredOutputType,
+    WorkflowNodeJobConfig,
+)
+from services.entities.agent_entities import (
+    ComposerCandidateCapabilities,
+    ComposerSaveStrategy,
+    ComposerVariant,
+)
+
+
+class AgentConfigSnapshotSummaryResponse(ResponseModel):
+    id: str
+    agent_id: str | None = None
+    version: int
+    summary: str | None = None
+    version_note: str | None = None
+    created_by: str | None = None
+    created_at: str | None = None
+
+
+class AgentRosterResponse(ResponseModel):
+    id: str
+    name: str
+    description: str
+    icon_type: AgentIconType | None = None
+    icon: str | None = None
+    icon_background: str | None = None
+    agent_kind: AgentKind
+    scope: AgentScope
+    source: AgentSource
+    app_id: str | None = None
+    workflow_id: str | None = None
+    workflow_node_id: str | None = None
+    active_config_snapshot_id: str | None = None
+    active_config_snapshot: AgentConfigSnapshotSummaryResponse | None = None
+    status: AgentStatus
+    created_by: str | None = None
+    updated_by: str | None = None
+    archived_by: str | None = None
+    archived_at: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class AgentInviteOptionResponse(AgentRosterResponse):
+    is_in_current_workflow: bool = False
+    in_current_workflow_count: int = 0
+    existing_node_ids: list[str] = Field(default_factory=list)
+
+
+class AgentRosterListResponse(ResponseModel):
+    data: list[AgentRosterResponse]
+    page: int
+    limit: int
+    total: int
+    has_more: bool
+
+
+class AgentInviteOptionsResponse(ResponseModel):
+    data: list[AgentInviteOptionResponse]
+    page: int
+    limit: int
+    total: int
+    has_more: bool
+
+
+class AgentConfigRevisionResponse(ResponseModel):
+    id: str
+    previous_snapshot_id: str | None = None
+    current_snapshot_id: str
+    revision: int
+    operation: AgentConfigRevisionOperation
+    summary: str | None = None
+    version_note: str | None = None
+    created_by: str | None = None
+    created_at: str | None = None
+
+
+class AgentConfigSnapshotDetailResponse(AgentConfigSnapshotSummaryResponse):
+    config_snapshot: AgentSoulConfig
+    revisions: list[AgentConfigRevisionResponse] = Field(default_factory=list)
+
+
+class AgentConfigSnapshotListResponse(ResponseModel):
+    data: list[AgentConfigSnapshotSummaryResponse]
+
+
+class AgentComposerAgentResponse(ResponseModel):
+    id: str
+    name: str
+    description: str
+    scope: AgentScope
+    status: AgentStatus
+    active_config_snapshot_id: str | None = None
+
+
+class AgentComposerBindingResponse(ResponseModel):
+    id: str
+    binding_type: WorkflowAgentBindingType
+    agent_id: str | None = None
+    current_snapshot_id: str | None = None
+    workflow_id: str
+    node_id: str
+
+
+class AgentComposerSoulLockResponse(ResponseModel):
+    locked: bool
+    can_unlock: bool = False
+    reason: str | None = None
+
+
+class AgentComposerImpactBindingResponse(ResponseModel):
+    app_id: str
+    workflow_id: str
+    node_id: str
+
+
+class AgentComposerImpactResponse(ResponseModel):
+    current_snapshot_id: str | None = None
+    workflow_node_count: int
+    bindings: list[AgentComposerImpactBindingResponse] = Field(default_factory=list)
+
+
+class WorkflowAgentComposerResponse(ResponseModel):
+    variant: Literal[ComposerVariant.WORKFLOW]
+    agent: AgentComposerAgentResponse | None = None
+    active_config_snapshot: AgentConfigSnapshotSummaryResponse | None = None
+    binding: AgentComposerBindingResponse | None = None
+    soul_lock: AgentComposerSoulLockResponse
+    agent_soul: AgentSoulConfig
+    node_job: WorkflowNodeJobConfig
+    effective_declared_outputs: list[DeclaredOutputConfig] = Field(default_factory=list)
+    save_options: list[ComposerSaveStrategy]
+    impact_summary: AgentComposerImpactResponse | None = None
+    app_id: str | None = None
+    workflow_id: str | None = None
+    node_id: str | None = None
+
+
+class AgentAppComposerResponse(ResponseModel):
+    variant: Literal[ComposerVariant.AGENT_APP]
+    agent: AgentComposerAgentResponse
+    active_config_snapshot: AgentConfigSnapshotSummaryResponse
+    agent_soul: AgentSoulConfig
+    save_options: list[ComposerSaveStrategy]
+
+
+class AgentComposerValidateResponse(ResponseModel):
+    result: Literal["success"]
+    errors: list[str] = Field(default_factory=list)
+
+
+class AgentComposerNodeJobCandidatesResponse(ResponseModel):
+    previous_node_outputs: list[dict[str, Any]] = Field(default_factory=list)
+    declare_output_types: list[DeclaredOutputType] = Field(default_factory=list)
+    human_contacts: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class AgentComposerSoulCandidatesResponse(ResponseModel):
+    skills_files: list[dict[str, Any]] = Field(default_factory=list)
+    dify_tools: list[dict[str, Any]] = Field(default_factory=list)
+    cli_tools: list[dict[str, Any]] = Field(default_factory=list)
+    knowledge_datasets: list[dict[str, Any]] = Field(default_factory=list)
+    human_contacts: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class AgentComposerCandidatesResponse(ResponseModel):
+    variant: ComposerVariant
+    allowed_node_job_candidates: AgentComposerNodeJobCandidatesResponse = Field(
+        default_factory=AgentComposerNodeJobCandidatesResponse
+    )
+    allowed_soul_candidates: AgentComposerSoulCandidatesResponse = Field(
+        default_factory=AgentComposerSoulCandidatesResponse
+    )
+    capabilities: ComposerCandidateCapabilities = Field(default_factory=ComposerCandidateCapabilities)

api/fields/document_fields.py

@@ -1,95 +1,112 @@
-from flask_restx import fields
+"""Response schemas for dataset document endpoints."""
 
-from fields.dataset_fields import dataset_fields
-from libs.helper import TimestampField
+from datetime import datetime
+from typing import Any
 
-document_metadata_fields = {
-    "id": fields.String,
-    "name": fields.String,
-    "type": fields.String,
-    "value": fields.String,
-}
+from pydantic import Field, field_validator
 
-document_fields = {
-    "id": fields.String,
-    "position": fields.Integer,
-    "data_source_type": fields.String,
-    "data_source_info": fields.Raw(attribute="data_source_info_dict"),
-    "data_source_detail_dict": fields.Raw(attribute="data_source_detail_dict"),
-    "dataset_process_rule_id": fields.String,
-    "name": fields.String,
-    "created_from": fields.String,
-    "created_by": fields.String,
-    "created_at": TimestampField,
-    "tokens": fields.Integer,
-    "indexing_status": fields.String,
-    "error": fields.String,
-    "enabled": fields.Boolean,
-    "disabled_at": TimestampField,
-    "disabled_by": fields.String,
-    "archived": fields.Boolean,
-    "display_status": fields.String,
-    "word_count": fields.Integer,
-    "hit_count": fields.Integer,
-    "doc_form": fields.String,
-    "doc_metadata": fields.List(fields.Nested(document_metadata_fields), attribute="doc_metadata_details"),
-    # Summary index generation status:
-    # "SUMMARIZING" (when task is queued and generating)
-    "summary_index_status": fields.String,
-    # Whether this document needs summary index generation
-    "need_summary": fields.Boolean,
-}
+from fields.base import ResponseModel
+from libs.helper import to_timestamp
 
-document_with_segments_fields = {
-    "id": fields.String,
-    "position": fields.Integer,
-    "data_source_type": fields.String,
-    "data_source_info": fields.Raw(attribute="data_source_info_dict"),
-    "data_source_detail_dict": fields.Raw(attribute="data_source_detail_dict"),
-    "dataset_process_rule_id": fields.String,
-    "process_rule_dict": fields.Raw(attribute="process_rule_dict"),
-    "name": fields.String,
-    "created_from": fields.String,
-    "created_by": fields.String,
-    "created_at": TimestampField,
-    "tokens": fields.Integer,
-    "indexing_status": fields.String,
-    "error": fields.String,
-    "enabled": fields.Boolean,
-    "disabled_at": TimestampField,
-    "disabled_by": fields.String,
-    "archived": fields.Boolean,
-    "display_status": fields.String,
-    "word_count": fields.Integer,
-    "hit_count": fields.Integer,
-    "completed_segments": fields.Integer,
-    "total_segments": fields.Integer,
-    "doc_metadata": fields.List(fields.Nested(document_metadata_fields), attribute="doc_metadata_details"),
-    # Summary index generation status:
-    # "SUMMARIZING" (when task is queued and generating)
-    "summary_index_status": fields.String,
-    "need_summary": fields.Boolean,  # Whether this document needs summary index generation
-}
 
-dataset_and_document_fields = {
-    "dataset": fields.Nested(dataset_fields),
-    "documents": fields.List(fields.Nested(document_fields)),
-    "batch": fields.String,
-}
+def normalize_enum(value: Any) -> Any:
+    if isinstance(value, str) or value is None:
+        return value
+    return getattr(value, "value", value)
 
-document_status_fields = {
-    "id": fields.String,
-    "indexing_status": fields.String,
-    "processing_started_at": TimestampField,
-    "parsing_completed_at": TimestampField,
-    "cleaning_completed_at": TimestampField,
-    "splitting_completed_at": TimestampField,
-    "completed_at": TimestampField,
-    "paused_at": TimestampField,
-    "error": fields.String,
-    "stopped_at": TimestampField,
-    "completed_segments": fields.Integer,
-    "total_segments": fields.Integer,
-}
 
-document_status_fields_list = {"data": fields.List(fields.Nested(document_status_fields))}
+class DocumentMetadataResponse(ResponseModel):
+    id: str
+    name: str
+    type: str
+    value: str | int | float | bool | None = None
+
+
+class DocumentResponse(ResponseModel):
+    id: str
+    position: int | None = None
+    data_source_type: str | None = None
+    data_source_info: Any = Field(default=None, validation_alias="data_source_info_dict")
+    data_source_detail_dict: Any = None
+    dataset_process_rule_id: str | None = None
+    name: str
+    created_from: str | None = None
+    created_by: str | None = None
+    created_at: int | None = None
+    tokens: int | None = None
+    indexing_status: str | None = None
+    error: str | None = None
+    enabled: bool | None = None
+    disabled_at: int | None = None
+    disabled_by: str | None = None
+    archived: bool | None = None
+    display_status: str | None = None
+    word_count: int | None = None
+    hit_count: int | None = None
+    doc_form: str | None = None
+    doc_metadata: list[DocumentMetadataResponse] = Field(default_factory=list, validation_alias="doc_metadata_details")
+    summary_index_status: str | None = None
+    need_summary: bool | None = None
+
+    @field_validator("data_source_type", "indexing_status", "display_status", "doc_form", mode="before")
+    @classmethod
+    def _normalize_enum_fields(cls, value: Any) -> Any:
+        return normalize_enum(value)
+
+    @field_validator("doc_metadata", mode="before")
+    @classmethod
+    def _normalize_doc_metadata(cls, value: Any) -> list[Any]:
+        if value is None:
+            return []
+        return value
+
+    @field_validator("created_at", "disabled_at", mode="before")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
+        return to_timestamp(value)
+
+
+class DocumentListResponse(ResponseModel):
+    data: list[DocumentResponse]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
+class DocumentStatusResponse(ResponseModel):
+    id: str
+    indexing_status: str
+    processing_started_at: int | None
+    parsing_completed_at: int | None
+    cleaning_completed_at: int | None
+    splitting_completed_at: int | None
+    completed_at: int | None
+    paused_at: int | None
+    error: str | None
+    stopped_at: int | None
+    completed_segments: int | None = None
+    total_segments: int | None = None
+
+    @field_validator("indexing_status", mode="before")
+    @classmethod
+    def _normalize_indexing_status(cls, value: Any) -> Any:
+        return normalize_enum(value)
+
+    @field_validator(
+        "processing_started_at",
+        "parsing_completed_at",
+        "cleaning_completed_at",
+        "splitting_completed_at",
+        "completed_at",
+        "paused_at",
+        "stopped_at",
+        mode="before",
+    )
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
+        return to_timestamp(value)
+
+
+class DocumentStatusListResponse(ResponseModel):
+    data: list[DocumentStatusResponse]

api/fields/segment_fields.py

@@ -1,53 +1,109 @@
-from flask_restx import fields
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
 
-from libs.helper import TimestampField
+from pydantic import field_serializer
 
-child_chunk_fields = {
-    "id": fields.String,
-    "segment_id": fields.String,
-    "content": fields.String,
-    "position": fields.Integer,
-    "word_count": fields.Integer,
-    "type": fields.String,
-    "created_at": TimestampField,
-    "updated_at": TimestampField,
-}
+from fields.base import ResponseModel
+from libs.helper import to_timestamp
 
-attachment_fields = {
-    "id": fields.String,
-    "name": fields.String,
-    "size": fields.Integer,
-    "extension": fields.String,
-    "mime_type": fields.String,
-    "source_url": fields.String,
-}
 
-segment_fields = {
-    "id": fields.String,
-    "position": fields.Integer,
-    "document_id": fields.String,
-    "content": fields.String,
-    "sign_content": fields.String,
-    "answer": fields.String,
-    "word_count": fields.Integer,
-    "tokens": fields.Integer,
-    "keywords": fields.List(fields.String),
-    "index_node_id": fields.String,
-    "index_node_hash": fields.String,
-    "hit_count": fields.Integer,
-    "enabled": fields.Boolean,
-    "disabled_at": TimestampField,
-    "disabled_by": fields.String,
-    "status": fields.String,
-    "created_by": fields.String,
-    "created_at": TimestampField,
-    "updated_at": TimestampField,
-    "updated_by": fields.String,
-    "indexing_at": TimestampField,
-    "completed_at": TimestampField,
-    "error": fields.String,
-    "stopped_at": TimestampField,
-    "child_chunks": fields.List(fields.Nested(child_chunk_fields)),
-    "attachments": fields.List(fields.Nested(attachment_fields)),
-    "summary": fields.String,  # Summary content for the segment
-}
+class SegmentAttachmentResponse(ResponseModel):
+    id: str
+    name: str
+    size: int
+    extension: str
+    mime_type: str | None
+    source_url: str
+
+
+class ChildChunkResponse(ResponseModel):
+    id: str
+    segment_id: str
+    content: str
+    position: int
+    word_count: int
+    type: str
+    created_at: datetime | int
+    updated_at: datetime | int
+
+    @field_serializer("created_at", "updated_at")
+    def serialize_timestamp(self, value: datetime | int) -> int:
+        return to_timestamp(value)
+
+
+class SegmentResponse(ResponseModel):
+    id: str
+    position: int
+    document_id: str
+    content: str
+    sign_content: str
+    answer: str | None
+    word_count: int
+    tokens: int
+    keywords: list[str] | None
+    index_node_id: str | None
+    index_node_hash: str | None
+    hit_count: int
+    enabled: bool
+    disabled_at: datetime | int | None
+    disabled_by: str | None
+    status: str
+    created_by: str
+    created_at: datetime | int
+    updated_at: datetime | int
+    updated_by: str | None
+    indexing_at: datetime | int | None
+    completed_at: datetime | int | None
+    error: str | None
+    stopped_at: datetime | int | None
+    child_chunks: list[ChildChunkResponse]
+    attachments: list[SegmentAttachmentResponse]
+    summary: str | None
+
+    @field_serializer("created_at", "updated_at")
+    def serialize_required_timestamp(self, value: datetime | int) -> int:
+        return to_timestamp(value)
+
+    @field_serializer("disabled_at", "indexing_at", "completed_at", "stopped_at")
+    def serialize_optional_timestamp(self, value: datetime | int | None) -> int | None:
+        return to_timestamp(value)
+
+
+@dataclass(frozen=True)
+class SegmentWithSummary:
+    segment: Any
+    summary: str | None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.segment, name)
+
+
+def segment_response_with_summary(segment: Any, summary: str | None) -> SegmentResponse:
+    response_source = SegmentWithSummary(segment=segment, summary=summary)
+    return SegmentResponse.model_validate(response_source, from_attributes=True)
+
+
+def segment_responses_with_summaries(
+    segments: Iterable[Any],
+    summaries: Mapping[str, str | None],
+) -> list[SegmentResponse]:
+    return [segment_response_with_summary(segment, summaries.get(segment.id)) for segment in segments]
+
+
+class SegmentDetailResponse(ResponseModel):
+    data: SegmentResponse
+    doc_form: str
+
+
+class ChildChunkDetailResponse(ResponseModel):
+    data: ChildChunkResponse
+
+
+class ChildChunkListResponse(ResponseModel):
+    data: list[ChildChunkResponse]
+    total: int
+    total_pages: int
+    page: int
+    limit: int

api/fields/snippet_fields.py

@@ -0,0 +1,51 @@
+from flask_restx import fields
+
+from fields.member_fields import simple_account_fields
+from libs.helper import TimestampField
+
+tag_fields = {"id": fields.String, "name": fields.String, "type": fields.String}
+
+# Snippet list item fields (lightweight for list display)
+snippet_list_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "description": fields.String,
+    "type": fields.String,
+    "version": fields.Integer,
+    "use_count": fields.Integer,
+    "is_published": fields.Boolean,
+    "icon_info": fields.Raw,
+    "tags": fields.List(fields.Nested(tag_fields)),
+    "created_by": fields.String,
+    "created_at": TimestampField,
+    "updated_by": fields.String,
+    "updated_at": TimestampField,
+}
+
+# Full snippet fields (includes creator info and graph data)
+snippet_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "description": fields.String,
+    "type": fields.String,
+    "version": fields.Integer,
+    "use_count": fields.Integer,
+    "is_published": fields.Boolean,
+    "icon_info": fields.Raw,
+    "graph": fields.Raw(attribute="graph_dict"),
+    "input_fields": fields.Raw(attribute="input_fields_list"),
+    "tags": fields.List(fields.Nested(tag_fields)),
+    "created_by": fields.Nested(simple_account_fields, attribute="created_by_account", allow_null=True),
+    "created_at": TimestampField,
+    "updated_by": fields.Nested(simple_account_fields, attribute="updated_by_account", allow_null=True),
+    "updated_at": TimestampField,
+}
+
+# Pagination response fields
+snippet_pagination_fields = {
+    "data": fields.List(fields.Nested(snippet_list_fields)),
+    "page": fields.Integer,
+    "limit": fields.Integer,
+    "total": fields.Integer,
+    "has_more": fields.Boolean,
+}

api/models/__init__.py

@@ -100,6 +100,7 @@ from .provider import (
     TenantDefaultModel,
     TenantPreferredModelProvider,
 )
+from .snippet import CustomizedSnippet, SnippetType
 from .source import DataSourceApiKeyAuthBinding, DataSourceOauthBinding
 from .task import CeleryTask, CeleryTaskSet
 from .tools import (
@@ -125,12 +126,14 @@ from .workflow import (
     WorkflowAppLog,
     WorkflowAppLogCreatedFrom,
     WorkflowArchiveLog,
+    WorkflowKind,
     WorkflowNodeExecutionModel,
     WorkflowNodeExecutionOffload,
     WorkflowNodeExecutionTriggeredFrom,
     WorkflowPause,
     WorkflowRun,
     WorkflowType,
+    resolve_workflow_kind,
 )
 
 __all__ = [
@@ -168,6 +171,7 @@ __all__ = [
     "Conversation",
     "ConversationVariable",
     "CreatorUserRole",
+    "CustomizedSnippet",
     "DataSourceApiKeyAuthBinding",
     "DataSourceOauthBinding",
     "Dataset",
@@ -213,6 +217,7 @@ __all__ = [
     "RecommendedApp",
     "SavedMessage",
     "Site",
+    "SnippetType",
     "Tag",
     "TagBinding",
     "Tenant",
@@ -242,6 +247,7 @@ __all__ = [
     "WorkflowAppLog",
     "WorkflowAppLogCreatedFrom",
     "WorkflowArchiveLog",
+    "WorkflowKind",
     "WorkflowComment",
     "WorkflowCommentMention",
     "WorkflowCommentReply",
@@ -255,4 +261,5 @@ __all__ = [
     "WorkflowToolProvider",
     "WorkflowTriggerStatus",
     "WorkflowType",
+    "resolve_workflow_kind",
 ]

api/models/enums.py

@@ -224,6 +224,7 @@ class TagType(StrEnum):
 
     KNOWLEDGE = "knowledge"
     APP = "app"
+    SNIPPET = "snippet"
 
 
 class DatasetMetadataType(StrEnum):

api/models/model.py

@@ -2474,7 +2474,7 @@ class Tag(TypeBase):
         sa.Index("tag_name_idx", "name"),
     )
 
-    TAG_TYPE_LIST = ["knowledge", "app"]
+    TAG_TYPE_LIST = ["knowledge", "app", "snippet"]
 
     id: Mapped[str] = mapped_column(
         StringUUID, insert_default=lambda: str(uuid4()), default_factory=lambda: str(uuid4()), init=False

api/models/snippet.py

@@ -0,0 +1,117 @@
+import json
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy import DateTime, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from libs.uuid_utils import uuidv7
+
+from .account import Account
+from .base import Base
+from .engine import db
+from .model import Tag, TagBinding
+from .types import AdjustedJSON, LongText, StringUUID
+
+
+class SnippetType(StrEnum):
+    """Snippet Type Enum"""
+
+    NODE = "node"
+    GROUP = "group"
+
+
+class CustomizedSnippet(Base):
+    """
+    Customized Snippet Model
+
+    Stores reusable workflow components (nodes or node groups) that can be
+    shared across applications within a workspace.
+    """
+
+    __tablename__ = "customized_snippets"
+    __table_args__ = (
+        sa.PrimaryKeyConstraint("id", name="customized_snippet_pkey"),
+        sa.Index("customized_snippet_tenant_idx", "tenant_id"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, default=lambda: str(uuidv7()))
+    tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(LongText, nullable=True)
+    type: Mapped[str] = mapped_column(String(50), nullable=False, server_default=sa.text("'node'"))
+
+    # Workflow reference for published version
+    workflow_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+
+    # State flags
+    is_published: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, server_default=sa.text("false"))
+    version: Mapped[int] = mapped_column(sa.Integer, nullable=False, server_default=sa.text("1"))
+    use_count: Mapped[int] = mapped_column(sa.Integer, nullable=False, server_default=sa.text("0"))
+
+    # Visual customization
+    icon_info: Mapped[dict | None] = mapped_column(AdjustedJSON, nullable=True)
+
+    # Snippet configuration (stored as JSON text)
+    input_fields: Mapped[str | None] = mapped_column(LongText, nullable=True)
+
+    # Audit fields
+    created_by: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, server_default=func.current_timestamp())
+    updated_by: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    )
+
+    @property
+    def graph_dict(self) -> dict[str, Any]:
+        """Get graph from associated workflow."""
+        if self.workflow_id:
+            from .workflow import Workflow
+
+            workflow = db.session.get(Workflow, self.workflow_id)
+            if workflow:
+                return json.loads(workflow.graph) if workflow.graph else {}
+        return {}
+
+    @property
+    def input_fields_list(self) -> list[dict[str, Any]]:
+        """Parse input_fields JSON to list."""
+        return json.loads(self.input_fields) if self.input_fields else []
+
+    @property
+    def tags(self):
+        """Get snippet tags."""
+        tags = db.session.scalars(
+            sa.select(Tag)
+            .join(TagBinding, Tag.id == TagBinding.tag_id)
+            .where(
+                TagBinding.target_id == self.id,
+                TagBinding.tenant_id == self.tenant_id,
+                Tag.tenant_id == self.tenant_id,
+                Tag.type == "snippet",
+            )
+        ).all()
+
+        return tags or []
+
+    @property
+    def created_by_account(self) -> Account | None:
+        """Get the account that created this snippet."""
+        if self.created_by:
+            return db.session.get(Account, self.created_by)
+        return None
+
+    @property
+    def updated_by_account(self) -> Account | None:
+        """Get the account that last updated this snippet."""
+        if self.updated_by:
+            return db.session.get(Account, self.updated_by)
+        return None
+
+    @property
+    def version_str(self) -> str:
+        """Get version as string for API response."""
+        return str(self.version)

api/models/workflow.py

@@ -112,6 +112,7 @@ class WorkflowType(StrEnum):
     WORKFLOW = "workflow"
     CHAT = "chat"
     RAG_PIPELINE = "rag-pipeline"
+    SNIPPET = "snippet"
 
     @classmethod
     def value_of(cls, value: str) -> "WorkflowType":
@@ -140,6 +141,26 @@ class WorkflowType(StrEnum):
         return cls.WORKFLOW if app_mode == AppMode.WORKFLOW else cls.CHAT
 
 
+class WorkflowKind(StrEnum):
+    STANDARD = "standard"
+    SNIPPET = "snippet"
+
+    @classmethod
+    def value_of(cls, value: str) -> "WorkflowKind":
+        for kind in cls:
+            if kind.value == value:
+                return kind
+        raise ValueError(f"invalid workflow kind value {value}")
+
+
+def resolve_workflow_kind(kind: str | WorkflowKind | None) -> WorkflowKind:
+    if kind is None:
+        return WorkflowKind.STANDARD
+    if isinstance(kind, WorkflowKind):
+        return kind
+    return WorkflowKind.value_of(kind)
+
+
 class _InvalidGraphDefinitionError(Exception):
     pass
 
@@ -187,6 +208,12 @@ class Workflow(Base):  # bug
     tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
     type: Mapped[WorkflowType] = mapped_column(EnumText(WorkflowType, length=255), nullable=False)
+    kind: Mapped[WorkflowKind | None] = mapped_column(
+        EnumText(WorkflowKind, length=255),
+        nullable=True,
+        default=WorkflowKind.STANDARD,
+        server_default=sa.text("'standard'"),
+    )
     version: Mapped[str] = mapped_column(String(255), nullable=False)
     marked_name: Mapped[str] = mapped_column(String(255), default="", server_default="")
     marked_comment: Mapped[str] = mapped_column(String(255), default="", server_default="")
@@ -228,12 +255,14 @@ class Workflow(Base):  # bug
         rag_pipeline_variables: list[dict],
         marked_name: str = "",
         marked_comment: str = "",
+        kind: str | None = WorkflowKind.STANDARD.value,
     ) -> "Workflow":
         workflow = Workflow()
         workflow.id = str(uuid4())
         workflow.tenant_id = tenant_id
         workflow.app_id = app_id
         workflow.type = WorkflowType(type)
+        workflow.kind = resolve_workflow_kind(kind)
         workflow.version = version
         workflow.graph = graph
         workflow.features = features
@@ -255,6 +284,14 @@ class Workflow(Base):  # bug
     def updated_by_account(self):
         return db.session.get(Account, self.updated_by) if self.updated_by else None
 
+    @property
+    def kind_or_standard(self) -> str:
+        return self.resolved_kind.value
+
+    @property
+    def resolved_kind(self) -> WorkflowKind:
+        return resolve_workflow_kind(self.kind)
+
     @property
     def graph_dict(self) -> Mapping[str, Any]:
         # TODO(QuantumGhost): Consider caching `graph_dict` to avoid repeated JSON decoding.
@@ -543,13 +580,16 @@ class Workflow(Base):  # bug
         def decrypt_func(
             var: VariableBase,
         ) -> StringVariable | IntegerVariable | FloatVariable | SecretVariable:
-            if isinstance(var, SecretVariable):
-                return var.model_copy(update={"value": encrypter.decrypt_token(tenant_id=tenant_id, token=var.value)})
-            elif isinstance(var, (StringVariable, IntegerVariable, FloatVariable)):
-                return var
-            else:
-                # Other variable types are not supported for environment variables
-                raise AssertionError(f"Unexpected variable type for environment variable: {type(var)}")
+            match var:
+                case SecretVariable():
+                    return var.model_copy(
+                        update={"value": encrypter.decrypt_token(tenant_id=tenant_id, token=var.value)}
+                    )
+                case StringVariable() | IntegerVariable() | FloatVariable():
+                    return var
+                case _:
+                    # Other variable types are not supported for environment variables
+                    raise AssertionError(f"Unexpected variable type for environment variable: {type(var)}")
 
         decrypted_results: list[SecretVariable | StringVariable | IntegerVariable | FloatVariable] = [
             decrypt_func(var) for var in results
@@ -1638,31 +1678,32 @@ class WorkflowDraftVariable(Base):
         # rather than their serialized forms.
         # However, multiple components in the codebase depend on
         # `WorkflowEntry.handle_special_values`, making a comprehensive migration challenging.
-        if isinstance(value, dict):
-            if not maybe_file_object(value):
-                return cast(Any, value)
-            tenant_id = _resolve_workflow_app_tenant_id(self.app_id)
-            return build_file_from_stored_mapping(
-                file_mapping=cast(dict[str, Any], value),
-                tenant_id=tenant_id,
-            )
-        elif isinstance(value, list) and value:
-            value_list = cast(list[Any], value)
-            first: Any = value_list[0]
-            if not maybe_file_object(first):
-                return cast(Any, value)
-            tenant_id = _resolve_workflow_app_tenant_id(self.app_id)
-            file_list: list[File] = []
-            for item in value_list:
-                file_list.append(
-                    build_file_from_stored_mapping(
-                        file_mapping=cast(dict[str, Any], item),
-                        tenant_id=tenant_id,
-                    )
+        match value:
+            case dict():
+                if not maybe_file_object(value):
+                    return cast(Any, value)
+                tenant_id = _resolve_workflow_app_tenant_id(self.app_id)
+                return build_file_from_stored_mapping(
+                    file_mapping=cast(dict[str, Any], value),
+                    tenant_id=tenant_id,
                 )
-            return cast(Any, file_list)
-        else:
-            return cast(Any, value)
+            case list() if value:
+                value_list = cast(list[Any], value)
+                first: Any = value_list[0]
+                if not maybe_file_object(first):
+                    return cast(Any, value)
+                tenant_id = _resolve_workflow_app_tenant_id(self.app_id)
+                file_list: list[File] = []
+                for item in value_list:
+                    file_list.append(
+                        build_file_from_stored_mapping(
+                            file_mapping=cast(dict[str, Any], item),
+                            tenant_id=tenant_id,
+                        )
+                    )
+                return cast(Any, file_list)
+            case _:
+                return cast(Any, value)
 
     def build_segment_from_serialized_value(self, segment_type: SegmentType, value: Any) -> Segment:
         # Persisted draft variable rows may contain historical file payloads.
@@ -1671,13 +1712,14 @@ class WorkflowDraftVariable(Base):
         # serialized JSON blob.
         match segment_type:
             case SegmentType.FILE:
-                if isinstance(value, File):
-                    return build_segment_with_type(segment_type, value)
-                elif isinstance(value, dict):
-                    file = self._rebuild_file_types(value)
-                    return build_segment_with_type(segment_type, file)
-                else:
-                    raise TypeMismatchError(f"expected dict or File for FileSegment, got {type(value)}")
+                match value:
+                    case File():
+                        return build_segment_with_type(segment_type, value)
+                    case dict():
+                        file = self._rebuild_file_types(value)
+                        return build_segment_with_type(segment_type, file)
+                    case _:
+                        raise TypeMismatchError(f"expected dict or File for FileSegment, got {type(value)}")
             case SegmentType.ARRAY_FILE:
                 if not isinstance(value, list):
                     raise TypeMismatchError(f"expected list for ArrayFileSegment, got {type(value)}")
@@ -1692,25 +1734,26 @@ class WorkflowDraftVariable(Base):
         # structural reconstruction. Persisted draft-variable payloads should go
         # through `build_segment_from_serialized_value()` so file metadata is
         # rebuilt from canonical storage records.
-        if isinstance(value, dict):
-            if not maybe_file_object(value):
-                return cast(Any, value)
-            normalized_file = dict(value)
-            normalized_file.pop("tenant_id", None)
-            return build_file_from_mapping_without_lookup(file_mapping=normalized_file)
-        elif isinstance(value, list) and value:
-            value_list = cast(list[Any], value)
-            first: Any = value_list[0]
-            if not maybe_file_object(first):
-                return cast(Any, value)
-            file_list: list[File] = []
-            for item in value_list:
-                normalized_file = dict(cast(dict[str, Any], item))
+        match value:
+            case dict():
+                if not maybe_file_object(value):
+                    return cast(Any, value)
+                normalized_file = dict(value)
                 normalized_file.pop("tenant_id", None)
-                file_list.append(build_file_from_mapping_without_lookup(file_mapping=normalized_file))
-            return cast(Any, file_list)
-        else:
-            return cast(Any, value)
+                return build_file_from_mapping_without_lookup(file_mapping=normalized_file)
+            case list() if value:
+                value_list = cast(list[Any], value)
+                first: Any = value_list[0]
+                if not maybe_file_object(first):
+                    return cast(Any, value)
+                file_list: list[File] = []
+                for item in value_list:
+                    normalized_file = dict(cast(dict[str, Any], item))
+                    normalized_file.pop("tenant_id", None)
+                    file_list.append(build_file_from_mapping_without_lookup(file_mapping=normalized_file))
+                return cast(Any, file_list)
+            case _:
+                return cast(Any, value)
 
     @classmethod
     def build_segment_with_type(cls, segment_type: SegmentType, value: Any) -> Segment:
@@ -1719,13 +1762,14 @@ class WorkflowDraftVariable(Base):
         # their serialized dictionary or list representations, respectively.
         match segment_type:
             case SegmentType.FILE:
-                if isinstance(value, File):
-                    return build_segment_with_type(segment_type, value)
-                elif isinstance(value, dict):
-                    file = cls.rebuild_file_types(value)
-                    return build_segment_with_type(segment_type, file)
-                else:
-                    raise TypeMismatchError(f"expected dict or File for FileSegment, got {type(value)}")
+                match value:
+                    case File():
+                        return build_segment_with_type(segment_type, value)
+                    case dict():
+                        file = cls.rebuild_file_types(value)
+                        return build_segment_with_type(segment_type, file)
+                    case _:
+                        raise TypeMismatchError(f"expected dict or File for FileSegment, got {type(value)}")
             case SegmentType.ARRAY_FILE:
                 if not isinstance(value, list):
                     raise TypeMismatchError(f"expected list for ArrayFileSegment, got {type(value)}")
@@ -2099,17 +2143,18 @@ class WorkflowPauseReason(DefaultFieldsDCMixin, TypeBase):
 
     @classmethod
     def from_entity(cls, *, pause_id: str, pause_reason: PauseReason) -> "WorkflowPauseReason":
-        if isinstance(pause_reason, HumanInputRequired):
-            return cls(
-                pause_id=pause_id,
-                type_=PauseReasonType.HUMAN_INPUT_REQUIRED,
-                form_id=pause_reason.form_id,
-                node_id=pause_reason.node_id,
-            )
-        elif isinstance(pause_reason, SchedulingPause):
-            return cls(pause_id=pause_id, type_=PauseReasonType.SCHEDULED_PAUSE, message=pause_reason.message)
-        else:
-            raise AssertionError(f"Unknown pause reason type: {pause_reason}")
+        match pause_reason:
+            case HumanInputRequired():
+                return cls(
+                    pause_id=pause_id,
+                    type_=PauseReasonType.HUMAN_INPUT_REQUIRED,
+                    form_id=pause_reason.form_id,
+                    node_id=pause_reason.node_id,
+                )
+            case SchedulingPause():
+                return cls(pause_id=pause_id, type_=PauseReasonType.SCHEDULED_PAUSE, message=pause_reason.message)
+            case _:
+                raise AssertionError(f"Unknown pause reason type: {pause_reason}")
 
     def to_entity(self) -> PauseReason:
         if self.type_ == PauseReasonType.HUMAN_INPUT_REQUIRED:

api/openapi/markdown/service-swagger.md

@@ -112,6 +112,14 @@ List annotations for the application
 
 List annotations for the application
 
+##### Parameters
+
+| Name | Located in | Description | Required | Schema |
+| ---- | ---------- | ----------- | -------- | ------ |
+| keyword | query | Keyword to search annotations | No | string |
+| limit | query | Number of annotations per page | No | integer |
+| page | query | Page number | No | integer |
+
 ##### Responses
 
 | Code | Description | Schema |
@@ -745,15 +753,17 @@ Create a new document by uploading a file
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
+| data | formData | Optional JSON string with document creation settings. | No | string |
+| file | formData | Document file to upload. | Yes | file |
 | dataset_id | path | Dataset ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document created successfully |
-| 400 | Bad request - invalid file or parameters |
-| 401 | Unauthorized - invalid API token |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document created successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 400 | Bad request - invalid file or parameters |  |
+| 401 | Unauthorized - invalid API token |  |
 
 ### /datasets/{dataset_id}/document/create-by-text
 
@@ -771,11 +781,11 @@ Create a new document by providing text content
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document created successfully |
-| 400 | Bad request - invalid parameters |
-| 401 | Unauthorized - invalid API token |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document created successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 400 | Bad request - invalid parameters |  |
+| 401 | Unauthorized - invalid API token |  |
 
 ### /datasets/{dataset_id}/document/create_by_file
 
@@ -788,15 +798,17 @@ Create a new document by uploading a file
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
+| data | formData | Optional JSON string with document creation settings. | No | string |
+| file | formData | Document file to upload. | Yes | file |
 | dataset_id | path | Dataset ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document created successfully |
-| 400 | Bad request - invalid file or parameters |
-| 401 | Unauthorized - invalid API token |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document created successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 400 | Bad request - invalid file or parameters |  |
+| 401 | Unauthorized - invalid API token |  |
 
 ### /datasets/{dataset_id}/document/create_by_text
 
@@ -815,11 +827,11 @@ Deprecated legacy alias for creating a new document by providing text content. U
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document created successfully |
-| 400 | Bad request - invalid parameters |
-| 401 | Unauthorized - invalid API token |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document created successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 400 | Bad request - invalid parameters |  |
+| 401 | Unauthorized - invalid API token |  |
 
 ### /datasets/{dataset_id}/documents
 
@@ -833,14 +845,18 @@ List all documents in a dataset
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
 | dataset_id | path | Dataset ID | Yes | string |
+| keyword | query | Search keyword | No | string |
+| limit | query | Number of items per page | No | integer |
+| page | query | Page number | No | integer |
+| status | query | Document status filter | No | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Documents retrieved successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Documents retrieved successfully | [DocumentListResponse](#documentlistresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset not found |  |
 
 ### /datasets/{dataset_id}/documents/download-zip
 
@@ -948,11 +964,11 @@ Get indexing status for documents in a batch
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Indexing status retrieved successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset or documents not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Indexing status retrieved successfully | [DocumentStatusListResponse](#documentstatuslistresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset or documents not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}
 
@@ -1011,16 +1027,18 @@ Update an existing document by uploading a file
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
+| data | formData | Optional JSON string with document update settings. | No | string |
+| file | formData | Replacement document file. | No | file |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document updated successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Document not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/download
 
@@ -1056,17 +1074,20 @@ List segments in a document
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
-| payload | body |  | Yes | [SegmentListQuery](#segmentlistquery) |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
+| keyword | query |  | No | string |
+| limit | query |  | No | integer |
+| page | query |  | No | integer |
+| status | query |  | No | [ string ] |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Segments retrieved successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset or document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Segments retrieved successfully | [SegmentListResponse](#segmentlistresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset or document not found |  |
 
 #### POST
 ##### Description
@@ -1083,12 +1104,12 @@ Create segments in a document
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Segments created successfully |
-| 400 | Bad request - segments data is missing |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset or document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Segments created successfully | [SegmentCreateListResponse](#segmentcreatelistresponse) |
+| 400 | Bad request - segments data is missing |  |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset or document not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}
 
@@ -1103,7 +1124,7 @@ Delete a specific segment
 | ---- | ---------- | ----------- | -------- | ------ |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
-| segment_id | path | Segment ID to delete | Yes | string |
+| segment_id | path | Segment ID | Yes | string |
 
 ##### Responses
 
@@ -1122,17 +1143,17 @@ Get a specific segment by ID
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
-| dataset_id | path |  | Yes | string |
-| document_id | path |  | Yes | string |
-| segment_id | path |  | Yes | string |
+| dataset_id | path | Dataset ID | Yes | string |
+| document_id | path | Document ID | Yes | string |
+| segment_id | path | Segment ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Segment retrieved successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset, document, or segment not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Segment retrieved successfully | [SegmentDetailResponse](#segmentdetailresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset, document, or segment not found |  |
 
 #### POST
 ##### Description
@@ -1146,15 +1167,15 @@ Update a specific segment
 | payload | body |  | Yes | [SegmentUpdatePayload](#segmentupdatepayload) |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
-| segment_id | path | Segment ID to update | Yes | string |
+| segment_id | path | Segment ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Segment updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset, document, or segment not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Segment updated successfully | [SegmentDetailResponse](#segmentdetailresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset, document, or segment not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks
 
@@ -1167,18 +1188,20 @@ List child chunks for a segment
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
-| payload | body |  | Yes | [ChildChunkListQuery](#childchunklistquery) |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
 | segment_id | path | Parent segment ID | Yes | string |
+| keyword | query |  | No | string |
+| limit | query |  | No | integer |
+| page | query |  | No | integer |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Child chunks retrieved successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset, document, or segment not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Child chunks retrieved successfully | [ChildChunkListResponse](#childchunklistresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset, document, or segment not found |  |
 
 #### POST
 ##### Description
@@ -1196,11 +1219,11 @@ Create a new child chunk for a segment
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Child chunk created successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset, document, or segment not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Child chunk created successfully | [ChildChunkDetailResponse](#childchunkdetailresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset, document, or segment not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}
 
@@ -1213,7 +1236,7 @@ Delete a specific child chunk
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
-| child_chunk_id | path | Child chunk ID to delete | Yes | string |
+| child_chunk_id | path | Child chunk ID | Yes | string |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
 | segment_id | path | Parent segment ID | Yes | string |
@@ -1236,18 +1259,18 @@ Update a specific child chunk
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
 | payload | body |  | Yes | [ChildChunkUpdatePayload](#childchunkupdatepayload) |
-| child_chunk_id | path | Child chunk ID to update | Yes | string |
+| child_chunk_id | path | Child chunk ID | Yes | string |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
 | segment_id | path | Parent segment ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Child chunk updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Dataset, document, segment, or child chunk not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Child chunk updated successfully | [ChildChunkDetailResponse](#childchunkdetailresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Dataset, document, segment, or child chunk not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/update-by-file
 
@@ -1261,16 +1284,18 @@ Deprecated legacy alias for updating an existing document by uploading a file. U
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
+| data | formData | Optional JSON string with document update settings. | No | string |
+| file | formData | Replacement document file. | No | file |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document updated successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Document not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/update-by-text
 
@@ -1289,11 +1314,11 @@ Update an existing document by providing text content
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document updated successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Document not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/update_by_file
 
@@ -1307,16 +1332,18 @@ Deprecated legacy alias for updating an existing document by uploading a file. U
 
 | Name | Located in | Description | Required | Schema |
 | ---- | ---------- | ----------- | -------- | ------ |
+| data | formData | Optional JSON string with document update settings. | No | string |
+| file | formData | Replacement document file. | No | file |
 | dataset_id | path | Dataset ID | Yes | string |
 | document_id | path | Document ID | Yes | string |
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document updated successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Document not found |  |
 
 ### /datasets/{dataset_id}/documents/{document_id}/update_by_text
 
@@ -1336,11 +1363,11 @@ Deprecated legacy alias for updating an existing document by providing text cont
 
 ##### Responses
 
-| Code | Description |
-| ---- | ----------- |
-| 200 | Document updated successfully |
-| 401 | Unauthorized - invalid API token |
-| 404 | Document not found |
+| Code | Description | Schema |
+| ---- | ----------- | ------ |
+| 200 | Document updated successfully | [DocumentAndBatchResponse](#documentandbatchresponse) |
+| 401 | Unauthorized - invalid API token |  |
+| 404 | Document not found |  |
 
 ### /datasets/{dataset_id}/hit-testing
 
@@ -2169,6 +2196,14 @@ Returns a list of available models for the specified model type.
 | page | integer |  | Yes |
 | total | integer |  | Yes |
 
+#### AnnotationListQuery
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| keyword | string | Keyword to search annotations | No |
+| limit | integer | Number of annotations per page | No |
+| page | integer | Page number | No |
+
 #### AnnotationReplyActionPayload
 
 | Name | Type | Description | Required |
@@ -2206,6 +2241,12 @@ Returns a list of available models for the specified model type.
 | ---- | ---- | ----------- | -------- |
 | content | string |  | Yes |
 
+#### ChildChunkDetailResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [ChildChunkResponse](#childchunkresponse) |  | Yes |
+
 #### ChildChunkListQuery
 
 | Name | Type | Description | Required |
@@ -2214,6 +2255,29 @@ Returns a list of available models for the specified model type.
 | limit | integer |  | No |
 | page | integer |  | No |
 
+#### ChildChunkListResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [ [ChildChunkResponse](#childchunkresponse) ] |  | Yes |
+| limit | integer |  | Yes |
+| page | integer |  | Yes |
+| total | integer |  | Yes |
+| total_pages | integer |  | Yes |
+
+#### ChildChunkResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| content | string |  | Yes |
+| created_at | integer |  | Yes |
+| id | string |  | Yes |
+| position | integer |  | Yes |
+| segment_id | string |  | Yes |
+| type | string |  | Yes |
+| updated_at | integer |  | Yes |
+| word_count | integer |  | Yes |
+
 #### ChildChunkUpdatePayload
 
 | Name | Type | Description | Required |
@@ -2238,7 +2302,7 @@ Condition detail
 | ---- | ---- | ----------- | -------- |
 | comparison_operator | string | *Enum:* `"<"`, `"="`, `">"`, `"after"`, `"before"`, `"contains"`, `"empty"`, `"end with"`, `"in"`, `"is"`, `"is not"`, `"not contains"`, `"not empty"`, `"not in"`, `"start with"`, `"≠"`, `"≤"`, `"≥"` | Yes |
 | name | string |  | Yes |
-| value |  |  | No |
+| value | string<br>[ string ]<br>integer<br>number |  | No |
 
 #### ConversationListQuery
 
@@ -2587,6 +2651,13 @@ Condition detail
 | inputs | object |  | Yes |
 | is_published | boolean |  | Yes |
 
+#### DocumentAndBatchResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| batch | string |  | Yes |
+| document | [DocumentResponse](#documentresponse) |  | Yes |
+
 #### DocumentBatchDownloadZipPayload
 
 Request payload for bulk downloading documents as a zip archive.
@@ -2604,6 +2675,16 @@ Request payload for bulk downloading documents as a zip archive.
 | page | integer | Page number | No |
 | status | string | Document status filter | No |
 
+#### DocumentListResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [ [DocumentResponse](#documentresponse) ] |  | Yes |
+| has_more | boolean |  | Yes |
+| limit | integer |  | Yes |
+| page | integer |  | Yes |
+| total | integer |  | Yes |
+
 #### DocumentMetadataOperation
 
 | Name | Type | Description | Required |
@@ -2612,6 +2693,67 @@ Request payload for bulk downloading documents as a zip archive.
 | metadata_list | [ [MetadataDetail](#metadatadetail) ] |  | Yes |
 | partial_update | boolean |  | No |
 
+#### DocumentMetadataResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| id | string |  | Yes |
+| name | string |  | Yes |
+| type | string |  | Yes |
+| value | string<br>integer<br>number<br>boolean |  | No |
+
+#### DocumentResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| archived | boolean |  | No |
+| created_at | integer |  | No |
+| created_by | string |  | No |
+| created_from | string |  | No |
+| data_source_detail_dict |  |  | No |
+| data_source_info |  |  | No |
+| data_source_type | string |  | No |
+| dataset_process_rule_id | string |  | No |
+| disabled_at | integer |  | No |
+| disabled_by | string |  | No |
+| display_status | string |  | No |
+| doc_form | string |  | No |
+| doc_metadata | [ [DocumentMetadataResponse](#documentmetadataresponse) ] |  | No |
+| enabled | boolean |  | No |
+| error | string |  | No |
+| hit_count | integer |  | No |
+| id | string |  | Yes |
+| indexing_status | string |  | No |
+| name | string |  | Yes |
+| need_summary | boolean |  | No |
+| position | integer |  | No |
+| summary_index_status | string |  | No |
+| tokens | integer |  | No |
+| word_count | integer |  | No |
+
+#### DocumentStatusListResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [ [DocumentStatusResponse](#documentstatusresponse) ] |  | Yes |
+
+#### DocumentStatusResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| cleaning_completed_at | integer |  | Yes |
+| completed_at | integer |  | Yes |
+| completed_segments | integer |  | No |
+| error | string |  | Yes |
+| id | string |  | Yes |
+| indexing_status | string |  | Yes |
+| parsing_completed_at | integer |  | Yes |
+| paused_at | integer |  | Yes |
+| processing_started_at | integer |  | Yes |
+| splitting_completed_at | integer |  | Yes |
+| stopped_at | integer |  | Yes |
+| total_segments | integer |  | No |
+
 #### DocumentTextCreatePayload
 
 | Name | Type | Description | Required |
@@ -2846,7 +2988,7 @@ Note: The SQLAlchemy model defines an `is_anonymous` property for Flask-Login se
 | ---- | ---- | ----------- | -------- |
 | id | string |  | Yes |
 | name | string |  | Yes |
-| value |  |  | No |
+| value | string<br>integer<br>number |  | No |
 
 #### MetadataFilteringCondition
 
@@ -2938,19 +3080,98 @@ Metadata operation data
 | segmentation | [Segmentation](#segmentation) |  | No |
 | subchunk_segmentation | [Segmentation](#segmentation) |  | No |
 
+#### SegmentAttachmentResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| extension | string |  | Yes |
+| id | string |  | Yes |
+| mime_type | string |  | Yes |
+| name | string |  | Yes |
+| size | integer |  | Yes |
+| source_url | string |  | Yes |
+
+#### SegmentCreateItemPayload
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| answer | string |  | No |
+| attachment_ids | [ string ] |  | No |
+| content | string |  | Yes |
+| keywords | [ string ] |  | No |
+
+#### SegmentCreateListResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [ [SegmentResponse](#segmentresponse) ] |  | Yes |
+| doc_form | string |  | Yes |
+
 #### SegmentCreatePayload
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| segments | [ object ] |  | No |
+| segments | [ [SegmentCreateItemPayload](#segmentcreateitempayload) ] |  | Yes |
+
+#### SegmentDetailResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [SegmentResponse](#segmentresponse) |  | Yes |
+| doc_form | string |  | Yes |
 
 #### SegmentListQuery
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | keyword | string |  | No |
+| limit | integer |  | No |
+| page | integer |  | No |
 | status | [ string ] |  | No |
 
+#### SegmentListResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| data | [ [SegmentResponse](#segmentresponse) ] |  | Yes |
+| doc_form | string |  | Yes |
+| has_more | boolean |  | Yes |
+| limit | integer |  | Yes |
+| page | integer |  | Yes |
+| total | integer |  | Yes |
+
+#### SegmentResponse
+
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| answer | string |  | Yes |
+| attachments | [ [SegmentAttachmentResponse](#segmentattachmentresponse) ] |  | Yes |
+| child_chunks | [ [ChildChunkResponse](#childchunkresponse) ] |  | Yes |
+| completed_at | integer |  | Yes |
+| content | string |  | Yes |
+| created_at | integer |  | Yes |
+| created_by | string |  | Yes |
+| disabled_at | integer |  | Yes |
+| disabled_by | string |  | Yes |
+| document_id | string |  | Yes |
+| enabled | boolean |  | Yes |
+| error | string |  | Yes |
+| hit_count | integer |  | Yes |
+| id | string |  | Yes |
+| index_node_hash | string |  | Yes |
+| index_node_id | string |  | Yes |
+| indexing_at | integer |  | Yes |
+| keywords | [ string ] |  | Yes |
+| position | integer |  | Yes |
+| sign_content | string |  | Yes |
+| status | string |  | Yes |
+| stopped_at | integer |  | Yes |
+| summary | string |  | Yes |
+| tokens | integer |  | Yes |
+| updated_at | integer |  | Yes |
+| updated_by | string |  | Yes |
+| word_count | integer |  | Yes |
+
 #### SegmentUpdateArgs
 
 | Name | Type | Description | Required |
@@ -3118,7 +3339,7 @@ Accept the legacy single-tag Service API payload while exposing a normalized tag
 | created_by_end_user | [SimpleEndUser](#simpleenduser) |  | No |
 | created_by_role | string |  | No |
 | created_from | string |  | No |
-| details |  |  | No |
+| details | object<br>[ object ]<br>string<br>integer<br>number<br>boolean |  | No |
 | id | string |  | Yes |
 | workflow_run | [WorkflowRunForLogResponse](#workflowrunforlogresponse) |  | No |
 
@@ -3140,7 +3361,7 @@ Accept the legacy single-tag Service API payload while exposing a normalized tag
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | created_at | integer |  | No |
-| elapsed_time |  |  | No |
+| elapsed_time | number<br>integer |  | No |
 | error | string |  | No |
 | exceptions_count | integer |  | No |
 | finished_at | integer |  | No |
@@ -3164,11 +3385,11 @@ Accept the legacy single-tag Service API payload while exposing a normalized tag
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | created_at | integer |  | No |
-| elapsed_time |  |  | No |
+| elapsed_time | number<br>integer |  | No |
 | error | string |  | No |
 | finished_at | integer |  | No |
 | id | string |  | Yes |
-| inputs |  |  | No |
+| inputs | object<br>[ object ]<br>string<br>integer<br>number<br>boolean |  | No |
 | outputs | object |  | No |
 | status | string |  | Yes |
 | total_steps | integer |  | No |

api/openapi/markdown/web-swagger.md

@@ -1323,7 +1323,6 @@ Returns Server-Sent Events stream.
 
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
-| app_dsl_version | string |  | Yes |
 | branding | [BrandingModel](#brandingmodel) |  | Yes |
 | enable_change_email | boolean |  | Yes |
 | enable_collaboration_mode | boolean |  | Yes |
@@ -1343,7 +1342,6 @@ Returns Server-Sent Events stream.
 | plugin_manager | [PluginManagerModel](#pluginmanagermodel) |  | Yes |
 | sso_enforced_for_signin | boolean |  | Yes |
 | sso_enforced_for_signin_protocol | string |  | Yes |
-| trial_models | [ string ] |  | Yes |
 | webapp_auth | [WebAppAuthModel](#webappauthmodel) |  | Yes |
 
 #### TextToAudioPayload

api/providers/trace/trace-aliyun/src/dify_trace_aliyun/aliyun_trace.py

@@ -75,20 +75,23 @@ class AliyunDataTrace(BaseTraceInstance):
         self.trace_client = TraceClient(service_name=aliyun_config.app_name, endpoint=endpoint)
 
     def trace(self, trace_info: BaseTraceInfo):
-        if isinstance(trace_info, WorkflowTraceInfo):
-            self.workflow_trace(trace_info)
-        if isinstance(trace_info, MessageTraceInfo):
-            self.message_trace(trace_info)
-        if isinstance(trace_info, ModerationTraceInfo):
-            pass
-        if isinstance(trace_info, SuggestedQuestionTraceInfo):
-            self.suggested_question_trace(trace_info)
-        if isinstance(trace_info, DatasetRetrievalTraceInfo):
-            self.dataset_retrieval_trace(trace_info)
-        if isinstance(trace_info, ToolTraceInfo):
-            self.tool_trace(trace_info)
-        if isinstance(trace_info, GenerateNameTraceInfo):
-            pass
+        match trace_info:
+            case WorkflowTraceInfo():
+                self.workflow_trace(trace_info)
+            case MessageTraceInfo():
+                self.message_trace(trace_info)
+            case ModerationTraceInfo():
+                pass
+            case SuggestedQuestionTraceInfo():
+                self.suggested_question_trace(trace_info)
+            case DatasetRetrievalTraceInfo():
+                self.dataset_retrieval_trace(trace_info)
+            case ToolTraceInfo():
+                self.tool_trace(trace_info)
+            case GenerateNameTraceInfo():
+                pass
+            case _:
+                pass
 
     def api_check(self):
         return self.trace_client.api_check()

api/providers/trace/trace-arize-phoenix/src/dify_trace_arize_phoenix/arize_phoenix_trace.py

@@ -708,20 +708,23 @@ class ArizePhoenixDataTrace(BaseTraceInstance):
         logger.info("[Arize/Phoenix] Trace Entity Info: %s", trace_info)
         logger.info("[Arize/Phoenix] Trace Entity Type: %s", type(trace_info))
         try:
-            if isinstance(trace_info, WorkflowTraceInfo):
-                self.workflow_trace(trace_info)
-            if isinstance(trace_info, MessageTraceInfo):
-                self.message_trace(trace_info)
-            if isinstance(trace_info, ModerationTraceInfo):
-                self.moderation_trace(trace_info)
-            if isinstance(trace_info, SuggestedQuestionTraceInfo):
-                self.suggested_question_trace(trace_info)
-            if isinstance(trace_info, DatasetRetrievalTraceInfo):
-                self.dataset_retrieval_trace(trace_info)
-            if isinstance(trace_info, ToolTraceInfo):
-                self.tool_trace(trace_info)
-            if isinstance(trace_info, GenerateNameTraceInfo):
-                self.generate_name_trace(trace_info)
+            match trace_info:
+                case WorkflowTraceInfo():
+                    self.workflow_trace(trace_info)
+                case MessageTraceInfo():
+                    self.message_trace(trace_info)
+                case ModerationTraceInfo():
+                    self.moderation_trace(trace_info)
+                case SuggestedQuestionTraceInfo():
+                    self.suggested_question_trace(trace_info)
+                case DatasetRetrievalTraceInfo():
+                    self.dataset_retrieval_trace(trace_info)
+                case ToolTraceInfo():
+                    self.tool_trace(trace_info)
+                case GenerateNameTraceInfo():
+                    self.generate_name_trace(trace_info)
+                case _:
+                    pass
 
         except Exception as e:
             logger.error("[Arize/Phoenix] Trace Entity Error: %s", str(e), exc_info=True)

api/providers/trace/trace-langfuse/src/dify_trace_langfuse/langfuse_trace.py

@@ -107,20 +107,23 @@ class LangFuseDataTrace(BaseTraceInstance):
         return start_time + timedelta(seconds=ttft_seconds)
 
     def trace(self, trace_info: BaseTraceInfo):
-        if isinstance(trace_info, WorkflowTraceInfo):
-            self.workflow_trace(trace_info)
-        if isinstance(trace_info, MessageTraceInfo):
-            self.message_trace(trace_info)
-        if isinstance(trace_info, ModerationTraceInfo):
-            self.moderation_trace(trace_info)
-        if isinstance(trace_info, SuggestedQuestionTraceInfo):
-            self.suggested_question_trace(trace_info)
-        if isinstance(trace_info, DatasetRetrievalTraceInfo):
-            self.dataset_retrieval_trace(trace_info)
-        if isinstance(trace_info, ToolTraceInfo):
-            self.tool_trace(trace_info)
-        if isinstance(trace_info, GenerateNameTraceInfo):
-            self.generate_name_trace(trace_info)
+        match trace_info:
+            case WorkflowTraceInfo():
+                self.workflow_trace(trace_info)
+            case MessageTraceInfo():
+                self.message_trace(trace_info)
+            case ModerationTraceInfo():
+                self.moderation_trace(trace_info)
+            case SuggestedQuestionTraceInfo():
+                self.suggested_question_trace(trace_info)
+            case DatasetRetrievalTraceInfo():
+                self.dataset_retrieval_trace(trace_info)
+            case ToolTraceInfo():
+                self.tool_trace(trace_info)
+            case GenerateNameTraceInfo():
+                self.generate_name_trace(trace_info)
+            case _:
+                pass
 
     def workflow_trace(self, trace_info: WorkflowTraceInfo):
         trace_id = trace_info.trace_id or trace_info.workflow_run_id

api/providers/trace/trace-langsmith/src/dify_trace_langsmith/langsmith_trace.py

@@ -48,20 +48,23 @@ class LangSmithDataTrace(BaseTraceInstance):
         self.file_base_url = os.getenv("FILES_URL", "http://127.0.0.1:5001")
 
     def trace(self, trace_info: BaseTraceInfo):
-        if isinstance(trace_info, WorkflowTraceInfo):
-            self.workflow_trace(trace_info)
-        if isinstance(trace_info, MessageTraceInfo):
-            self.message_trace(trace_info)
-        if isinstance(trace_info, ModerationTraceInfo):
-            self.moderation_trace(trace_info)
-        if isinstance(trace_info, SuggestedQuestionTraceInfo):
-            self.suggested_question_trace(trace_info)
-        if isinstance(trace_info, DatasetRetrievalTraceInfo):
-            self.dataset_retrieval_trace(trace_info)
-        if isinstance(trace_info, ToolTraceInfo):
-            self.tool_trace(trace_info)
-        if isinstance(trace_info, GenerateNameTraceInfo):
-            self.generate_name_trace(trace_info)
+        match trace_info:
+            case WorkflowTraceInfo():
+                self.workflow_trace(trace_info)
+            case MessageTraceInfo():
+                self.message_trace(trace_info)
+            case ModerationTraceInfo():
+                self.moderation_trace(trace_info)
+            case SuggestedQuestionTraceInfo():
+                self.suggested_question_trace(trace_info)
+            case DatasetRetrievalTraceInfo():
+                self.dataset_retrieval_trace(trace_info)
+            case ToolTraceInfo():
+                self.tool_trace(trace_info)
+            case GenerateNameTraceInfo():
+                self.generate_name_trace(trace_info)
+            case _:
+                pass
 
     def workflow_trace(self, trace_info: WorkflowTraceInfo):
         # trace_id must equal the root run's run_id (LangSmith protocol); external trace_id

api/providers/trace/trace-opik/src/dify_trace_opik/opik_trace.py

@@ -96,20 +96,23 @@ class OpikDataTrace(BaseTraceInstance):
         self.file_base_url = os.getenv("FILES_URL", "http://127.0.0.1:5001")
 
     def trace(self, trace_info: BaseTraceInfo):
-        if isinstance(trace_info, WorkflowTraceInfo):
-            self.workflow_trace(trace_info)
-        if isinstance(trace_info, MessageTraceInfo):
-            self.message_trace(trace_info)
-        if isinstance(trace_info, ModerationTraceInfo):
-            self.moderation_trace(trace_info)
-        if isinstance(trace_info, SuggestedQuestionTraceInfo):
-            self.suggested_question_trace(trace_info)
-        if isinstance(trace_info, DatasetRetrievalTraceInfo):
-            self.dataset_retrieval_trace(trace_info)
-        if isinstance(trace_info, ToolTraceInfo):
-            self.tool_trace(trace_info)
-        if isinstance(trace_info, GenerateNameTraceInfo):
-            self.generate_name_trace(trace_info)
+        match trace_info:
+            case WorkflowTraceInfo():
+                self.workflow_trace(trace_info)
+            case MessageTraceInfo():
+                self.message_trace(trace_info)
+            case ModerationTraceInfo():
+                self.moderation_trace(trace_info)
+            case SuggestedQuestionTraceInfo():
+                self.suggested_question_trace(trace_info)
+            case DatasetRetrievalTraceInfo():
+                self.dataset_retrieval_trace(trace_info)
+            case ToolTraceInfo():
+                self.tool_trace(trace_info)
+            case GenerateNameTraceInfo():
+                self.generate_name_trace(trace_info)
+            case _:
+                pass
 
     def workflow_trace(self, trace_info: WorkflowTraceInfo):
         workflow_metadata = wrap_metadata(

api/providers/trace/trace-weave/src/dify_trace_weave/weave_trace.py

@@ -80,20 +80,23 @@ class WeaveDataTrace(BaseTraceInstance):
 
     def trace(self, trace_info: BaseTraceInfo):
         logger.debug("Trace info: %s", trace_info)
-        if isinstance(trace_info, WorkflowTraceInfo):
-            self.workflow_trace(trace_info)
-        if isinstance(trace_info, MessageTraceInfo):
-            self.message_trace(trace_info)
-        if isinstance(trace_info, ModerationTraceInfo):
-            self.moderation_trace(trace_info)
-        if isinstance(trace_info, SuggestedQuestionTraceInfo):
-            self.suggested_question_trace(trace_info)
-        if isinstance(trace_info, DatasetRetrievalTraceInfo):
-            self.dataset_retrieval_trace(trace_info)
-        if isinstance(trace_info, ToolTraceInfo):
-            self.tool_trace(trace_info)
-        if isinstance(trace_info, GenerateNameTraceInfo):
-            self.generate_name_trace(trace_info)
+        match trace_info:
+            case WorkflowTraceInfo():
+                self.workflow_trace(trace_info)
+            case MessageTraceInfo():
+                self.message_trace(trace_info)
+            case ModerationTraceInfo():
+                self.moderation_trace(trace_info)
+            case SuggestedQuestionTraceInfo():
+                self.suggested_question_trace(trace_info)
+            case DatasetRetrievalTraceInfo():
+                self.dataset_retrieval_trace(trace_info)
+            case ToolTraceInfo():
+                self.tool_trace(trace_info)
+            case GenerateNameTraceInfo():
+                self.generate_name_trace(trace_info)
+            case _:
+                pass
 
     def workflow_trace(self, trace_info: WorkflowTraceInfo):
         trace_id = trace_info.trace_id or trace_info.message_id or trace_info.workflow_run_id

api/services/app_dsl_service.py

@@ -97,6 +97,7 @@ class AppDslService:
         icon: str | None = None,
         icon_background: str | None = None,
         app_id: str | None = None,
+        import_app_id: str | None = None,
     ) -> Import:
         """Import an app from YAML content or URL."""
         import_id = str(uuid.uuid4())
@@ -262,6 +263,7 @@ class AppDslService:
                 icon=icon,
                 icon_background=icon_background,
                 dependencies=check_dependencies_pending_data,
+                import_app_id=import_app_id,
             )
 
             draft_var_srv = WorkflowDraftVariableService(session=self._session)
@@ -385,6 +387,7 @@ class AppDslService:
         icon: str | None = None,
         icon_background: str | None = None,
         dependencies: list[PluginDependency] | None = None,
+        import_app_id: str | None = None,
     ) -> App:
         """Create a new app or update an existing one."""
         app_data = data.get("app", {})
@@ -417,7 +420,7 @@ class AppDslService:
 
             # Create new app
             app = App()
-            app.id = str(uuid4())
+            app.id = import_app_id or str(uuid4())
             app.tenant_id = account.current_tenant_id
             app.mode = app_mode
             app.name = name or app_data.get("name", "")

api/services/data_migration/__init__.py

@@ -0,0 +1,17 @@
+from services.data_migration.entities import (
+    ConflictStrategy,
+    ExportSelection,
+    IdStrategy,
+    ImportOptions,
+    MigrationDataError,
+    MigrationPackage,
+)
+
+__all__ = [
+    "ConflictStrategy",
+    "ExportSelection",
+    "IdStrategy",
+    "ImportOptions",
+    "MigrationDataError",
+    "MigrationPackage",
+]

api/services/data_migration/dependency_discovery_service.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from services.data_migration.entities import DependencyKind
+
+
+@dataclass(frozen=True)
+class DiscoveredDependency:
+    kind: DependencyKind
+    provider_id: str
+    provider_name: str | None = None
+    source: str | None = None
+
+
+class DependencyDiscoveryService:
+    def discover_from_dsl(self, dsl: dict[str, Any]) -> list[DiscoveredDependency]:
+        seen: set[tuple[DependencyKind, str]] = set()
+        result: list[DiscoveredDependency] = []
+        for node in self._nodes_from_dsl(dsl):
+            data = node.get("data", {}) if isinstance(node, dict) else {}
+            for dependency in self._dependencies_from_node(data):
+                key = (dependency.kind, dependency.provider_id)
+                if dependency.provider_id and key not in seen:
+                    seen.add(key)
+                    result.append(dependency)
+        return result
+
+    def _nodes_from_dsl(self, dsl: dict[str, Any]) -> list[dict[str, Any]]:
+        nodes: list[dict[str, Any]] = []
+        graph = dsl.get("graph") if isinstance(dsl, dict) else None
+        if isinstance(graph, dict) and isinstance(graph.get("nodes"), list):
+            nodes.extend(node for node in graph["nodes"] if isinstance(node, dict))
+        workflow = dsl.get("workflow") if isinstance(dsl, dict) else None
+        workflow_graph = workflow.get("graph") if isinstance(workflow, dict) else None
+        if isinstance(workflow_graph, dict) and isinstance(workflow_graph.get("nodes"), list):
+            nodes.extend(node for node in workflow_graph["nodes"] if isinstance(node, dict))
+        return nodes
+
+    def _dependencies_from_node(self, data: dict[str, Any]) -> list[DiscoveredDependency]:
+        dependencies: list[DiscoveredDependency] = []
+        node_type = data.get("type")
+        if node_type == "tool":
+            dependency = self._from_tool_config(data, source="tool_node")
+            if dependency:
+                dependencies.append(dependency)
+        if node_type == "agent":
+            for tool_config in self._agent_tool_configs(data):
+                if isinstance(tool_config, dict):
+                    dependency = self._from_tool_config(tool_config, source="agent_node")
+                    if dependency:
+                        dependencies.append(dependency)
+        return dependencies
+
+    def _agent_tool_configs(self, data: dict[str, Any]) -> list[dict[str, Any]]:
+        configs = data.get("tools")
+        if isinstance(configs, list):
+            return [config for config in configs if isinstance(config, dict)]
+        agent_parameters = data.get("agent_parameters")
+        if not isinstance(agent_parameters, dict):
+            return []
+        tools_parameter = agent_parameters.get("tools")
+        if not isinstance(tools_parameter, dict):
+            return []
+        value = tools_parameter.get("value", [])
+        if not isinstance(value, list):
+            return []
+        return [config for config in value if isinstance(config, dict)]
+
+    def _from_tool_config(self, config: dict[str, Any], *, source: str) -> DiscoveredDependency | None:
+        provider_id = config.get("provider_id") or config.get("provider_name") or config.get("provider")
+        if not provider_id:
+            return None
+        provider_type = str(config.get("provider_type") or config.get("type") or "")
+        kind = self._kind_from_provider_type(provider_type)
+        return DiscoveredDependency(
+            kind=kind,
+            provider_id=str(provider_id),
+            provider_name=config.get("provider_name"),
+            source=source,
+        )
+
+    def _kind_from_provider_type(self, provider_type: str) -> DependencyKind:
+        normalized = provider_type.lower()
+        if normalized in {"api", "custom", "api_tool"}:
+            return DependencyKind.API_TOOL
+        if normalized in {"workflow", "workflow_tool"}:
+            return DependencyKind.WORKFLOW_TOOL
+        if normalized == "mcp":
+            return DependencyKind.MCP_TOOL
+        return DependencyKind.BUILTIN_OR_PLUGIN_TOOL