Merge remote-tracking branch 'upstream/main' into feat/model-type-migration-script-2

Co-authored-by: GareArc <garethcxy@dify.ai>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: L1nSn0w <l1nsn0w@qq.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: gigglewang <gigglewang@dify.ai>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Co-authored-by: Xiyuan Chen <52963600+GareArc@users.noreply.github.com>

.agents/skills/how-to-write-component/SKILL.md

@@ -12,7 +12,7 @@ Use this as the decision guide for React/TypeScript component structure. Existin
 - Search before adding UI, hooks, helpers, or styling patterns. Reuse existing base components, feature components, hooks, utilities, and design styles when they fit.
 - Group code by feature workflow, route, or ownership area: components, hooks, local types, query helpers, atoms, constants, and small utilities should live near the code that changes with them.
 - Promote code to shared only when multiple verticals need the same stable primitive. Otherwise keep it local and compose shared primitives inside the owning feature.
-- Use Tailwind CSS v4.1+ rules via the `tailwind-css-rules` skill. Prefer v4 utilities, `gap`, `text-size/line-height`, `min-h-dvh`, and avoid deprecated utilities and `@apply`.
+- Follow Dify's CSS-first Tailwind v4 contract from `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md`. Prefer design-system tokens, utilities, and radius mappings over generic Tailwind guidance.
 
 ## Ownership
 

.agents/skills/tailwind-css-rules/SKILL.md

@@ -1,367 +0,0 @@
----
-name: tailwind-css-rules
-description: Tailwind CSS v4.1+ rules and best practices. Use when writing, reviewing, refactoring, or upgrading Tailwind CSS classes and styles, especially v4 utility migrations, layout spacing, typography, responsive variants, dark mode, gradients, CSS variables, and component styling.
----
-
-# Tailwind CSS Rules and Best Practices
-
-## Core Principles
-
-- **Always use Tailwind CSS v4.1+** - Ensure the codebase is using the latest version
-- **Do not use deprecated or removed utilities** - ALWAYS use the replacement
-- **Never use `@apply`** - Use CSS variables, the `--spacing()` function, or framework components instead
-- **Check for redundant classes** - Remove any classes that aren't necessary
-- **Group elements logically** to simplify responsive tweaks later
-
-## Upgrading to Tailwind CSS v4
-
-### Before Upgrading
-
-- **Always read the upgrade documentation first** - Read https://tailwindcss.com/docs/upgrade-guide and https://tailwindcss.com/blog/tailwindcss-v4 before starting an upgrade.
-- Ensure the git repository is in a clean state before starting
-
-### Upgrade Process
-
-1. Run the upgrade command: `npx @tailwindcss/upgrade@latest` for both major and minor updates
-2. The tool will convert JavaScript config files to the new CSS format
-3. Review all changes extensively to clean up any false positives
-4. Test thoroughly across your application
-
-## Breaking Changes Reference
-
-### Removed Utilities (NEVER use these in v4)
-
-| ❌ Deprecated           | ✅ Replacement                                    |
-| ----------------------- | ------------------------------------------------- |
-| `bg-opacity-*`          | Use opacity modifiers like `bg-black/50`          |
-| `text-opacity-*`        | Use opacity modifiers like `text-black/50`        |
-| `border-opacity-*`      | Use opacity modifiers like `border-black/50`      |
-| `divide-opacity-*`      | Use opacity modifiers like `divide-black/50`      |
-| `ring-opacity-*`        | Use opacity modifiers like `ring-black/50`        |
-| `placeholder-opacity-*` | Use opacity modifiers like `placeholder-black/50` |
-| `flex-shrink-*`         | `shrink-*`                                        |
-| `flex-grow-*`           | `grow-*`                                          |
-| `overflow-ellipsis`     | `text-ellipsis`                                   |
-| `decoration-slice`      | `box-decoration-slice`                            |
-| `decoration-clone`      | `box-decoration-clone`                            |
-
-### Renamed Utilities
-
-Use the v4 name when migrating code that still carries Tailwind v3 semantics. Do not blanket-replace existing v4 classes: classes such as `rounded-sm`, `shadow-sm`, `ring-1`, and `ring-2` are valid in this codebase when they intentionally represent the current design scale.
-
-| ❌ v3 pattern       | ✅ v4 pattern                                      |
-| ------------------- | -------------------------------------------------- |
-| `bg-gradient-*`     | `bg-linear-*`                                      |
-| old shadow scale    | verify against the current Tailwind/design scale   |
-| old blur scale      | verify against the current Tailwind/design scale   |
-| old radius scale    | use the Dify radius token mapping when applicable  |
-| `outline-none`      | `outline-hidden`                                   |
-| bare `ring` utility | use an explicit ring width such as `ring-1`/`ring-2`/`ring-3` |
-
-For Figma radius tokens, follow `packages/dify-ui/AGENTS.md`. For example, `--radius/xs` maps to `rounded-sm`; do not rewrite it to `rounded-xs`.
-
-## Layout and Spacing Rules
-
-### Flexbox and Grid Spacing
-
-#### Always use gap utilities for internal spacing
-
-Gap provides consistent spacing without edge cases (no extra space on last items). It's cleaner and more maintainable than margins on children.
-
-```html
-<!-- ❌ Don't do this -->
-<div class="flex">
-  <div class="mr-4">Item 1</div>
-  <div class="mr-4">Item 2</div>
-  <div>Item 3</div>
-  <!-- No margin on last -->
-</div>
-
-<!-- ✅ Do this instead -->
-<div class="flex gap-4">
-  <div>Item 1</div>
-  <div>Item 2</div>
-  <div>Item 3</div>
-</div>
-```
-
-#### Gap vs Space utilities
-
-- **Never use `space-x-*` or `space-y-*` in flex/grid layouts** - always use gap
-- Space utilities add margins to children and have issues with wrapped items
-- Gap works correctly with flex-wrap and all flex directions
-
-```html
-<!-- ❌ Avoid space utilities in flex containers -->
-<div class="flex flex-wrap space-x-4">
-  <!-- Space utilities break with wrapped items -->
-</div>
-
-<!-- ✅ Use gap for consistent spacing -->
-<div class="flex flex-wrap gap-4">
-  <!-- Gap works perfectly with wrapping -->
-</div>
-```
-
-### General Spacing Guidelines
-
-- **Prefer top and left margins** over bottom and right margins (unless conditionally rendered)
-- **Use padding on parent containers** instead of bottom margins on the last child
-- **Always use `min-h-dvh` instead of `min-h-screen`** - `min-h-screen` is buggy on mobile Safari
-- **Prefer `size-*` utilities** over separate `w-*` and `h-*` when setting equal dimensions
-- For max-widths, prefer the container scale (e.g., `max-w-2xs` over `max-w-72`)
-
-## Typography Rules
-
-### Line Heights
-
-- **Never use `leading-*` classes** - Always use line height modifiers with text size
-- **Always use fixed line heights from the spacing scale** - Don't use named values
-
-```html
-<!-- ❌ Don't do this -->
-<p class="text-base leading-7">Text with separate line height</p>
-<p class="text-lg leading-relaxed">Text with named line height</p>
-
-<!-- ✅ Do this instead -->
-<p class="text-base/7">Text with line height modifier</p>
-<p class="text-lg/8">Text with specific line height</p>
-```
-
-### Font Size Reference
-
-Be precise with font sizes - know the actual pixel values:
-
-- `text-xs` = 12px
-- `text-sm` = 14px
-- `text-base` = 16px
-- `text-lg` = 18px
-- `text-xl` = 20px
-
-## Color and Opacity
-
-### Opacity Modifiers
-
-**Never use `bg-opacity-*`, `text-opacity-*`, etc.** - use the opacity modifier syntax:
-
-```html
-<!-- ❌ Don't do this -->
-<div class="bg-red-500 bg-opacity-60">Old opacity syntax</div>
-
-<!-- ✅ Do this instead -->
-<div class="bg-red-500/60">Modern opacity syntax</div>
-```
-
-## Responsive Design
-
-### Breakpoint Optimization
-
-- **Check for redundant classes across breakpoints**
-- **Only add breakpoint variants when values change**
-
-```html
-<!-- ❌ Redundant breakpoint classes -->
-<div class="px-4 md:px-4 lg:px-4">
-  <!-- md:px-4 and lg:px-4 are redundant -->
-</div>
-
-<!-- ✅ Efficient breakpoint usage -->
-<div class="px-4 lg:px-8">
-  <!-- Only specify when value changes -->
-</div>
-```
-
-## Dark Mode
-
-### Dark Mode Best Practices
-
-- Use the plain `dark:` variant pattern
-- Put light mode styles first, then dark mode styles
-- Ensure `dark:` variant comes before other variants
-
-```html
-<!-- ✅ Correct dark mode pattern -->
-<div class="bg-white text-black dark:bg-black dark:text-white">
-  <button class="hover:bg-gray-100 dark:hover:bg-gray-800">Click me</button>
-</div>
-```
-
-## Gradient Utilities
-
-- **ALWAYS Use `bg-linear-*` instead of `bg-gradient-*` utilities** - The gradient utilities were renamed in v4
-- Use the new `bg-radial` or `bg-radial-[<position>]` to create radial gradients
-- Use the new `bg-conic` or `bg-conic-*` to create conic gradients
-
-```html
-<!-- ✅ Use the new gradient utilities -->
-<div class="h-14 bg-linear-to-br from-violet-500 to-fuchsia-500"></div>
-<div
-  class="size-18 bg-radial-[at_50%_75%] from-sky-200 via-blue-400 to-indigo-900 to-90%"
-></div>
-<div
-  class="size-24 bg-conic-180 from-indigo-600 via-indigo-50 to-indigo-600"
-></div>
-
-<!-- ❌ Do not use bg-gradient-* utilities -->
-<div class="h-14 bg-gradient-to-br from-violet-500 to-fuchsia-500"></div>
-```
-
-## Working with CSS Variables
-
-### Accessing Theme Values
-
-Tailwind CSS v4 exposes all theme values as CSS variables:
-
-```css
-/* Access colors, and other theme values */
-.custom-element {
-  background: var(--color-red-500);
-  border-radius: var(--radius-lg);
-}
-```
-
-### The `--spacing()` Function
-
-Use the dedicated `--spacing()` function for spacing calculations:
-
-```css
-.custom-class {
-  margin-top: calc(100vh - --spacing(16));
-}
-```
-
-### Extending theme values
-
-Use CSS to extend theme values:
-
-```css
-@import "tailwindcss";
-
-@theme {
-  --color-mint-500: oklch(0.72 0.11 178);
-}
-```
-
-```html
-<div class="bg-mint-500">
-  <!-- ... -->
-</div>
-```
-
-## New v4 Features
-
-### Container Queries
-
-Use the `@container` class and size variants:
-
-```html
-<article class="@container">
-  <div class="flex flex-col @md:flex-row @lg:gap-8">
-    <img class="w-full @md:w-48" />
-    <div class="mt-4 @md:mt-0">
-      <!-- Content adapts to container size -->
-    </div>
-  </div>
-</article>
-```
-
-### Container Query Units
-
-Use container-based units like `cqw` for responsive sizing:
-
-```html
-<div class="@container">
-  <h1 class="text-[50cqw]">Responsive to container width</h1>
-</div>
-```
-
-### Text Shadows (v4.1)
-
-Use text-shadow-\* utilities from text-shadow-2xs to text-shadow-lg:
-
-```html
-<!-- ✅ Text shadow examples -->
-<h1 class="text-shadow-lg">Large shadow</h1>
-<p class="text-shadow-sm/50">Small shadow with opacity</p>
-```
-
-### Masking (v4.1)
-
-Use the new composable mask utilities for image and gradient masks:
-
-```html
-<!-- ✅ Linear gradient masks on specific sides -->
-<div class="mask-t-from-50%">Top fade</div>
-<div class="mask-b-from-20% mask-b-to-80%">Bottom gradient</div>
-<div class="mask-linear-from-white mask-linear-to-black/60">
-  Fade from white to black
-</div>
-
-<!-- ✅ Radial gradient masks -->
-<div class="mask-radial-[100%_100%] mask-radial-from-75% mask-radial-at-left">
-  Radial mask
-</div>
-```
-
-## Component Patterns
-
-### Avoiding Utility Inheritance
-
-Don't add utilities to parents that you override in children:
-
-```html
-<!-- ❌ Avoid this pattern -->
-<div class="text-center">
-  <h1>Centered Heading</h1>
-  <div class="text-left">Left-aligned content</div>
-</div>
-
-<!-- ✅ Better approach -->
-<div>
-  <h1 class="text-center">Centered Heading</h1>
-  <div>Left-aligned content</div>
-</div>
-```
-
-### Component Extraction
-
-- Extract repeated patterns into framework components, not CSS classes
-- Keep utility classes in templates/JSX
-- Use data attributes for complex state-based styling
-
-## CSS Best Practices
-
-### Nesting Guidelines
-
-- Use nesting when styling both parent and children
-- Avoid empty parent selectors
-
-```css
-/* ✅ Good nesting - parent has styles */
-.card {
-  padding: --spacing(4);
-
-  > .card-title {
-    font-weight: bold;
-  }
-}
-
-/* ❌ Avoid empty parents */
-ul {
-  > li {
-    /* Parent has no styles */
-  }
-}
-```
-
-## Common Pitfalls to Avoid
-
-1. **Using old opacity utilities** - Always use `/opacity` syntax like `bg-red-500/60`
-2. **Redundant breakpoint classes** - Only specify changes
-3. **Space utilities in flex/grid** - Always use gap
-4. **Leading utilities** - Use line-height modifiers like `text-sm/6`
-5. **Arbitrary values** - Use the design scale
-6. **@apply directive** - Use components or CSS variables
-7. **min-h-screen on mobile** - Use min-h-dvh
-8. **Separate width/height** - Use size utilities when equal
-9. **Arbitrary values** - Always use Tailwind's predefined scale whenever possible (e.g., use `ml-4` over `ml-[16px]`)

.dockerignore

@@ -0,0 +1,15 @@
+**/node_modules
+**/.pnpm-store
+**/dist
+**/.next
+**/.turbo
+**/.cache
+**/__pycache__
+**/*.pyc
+**/.mypy_cache
+**/.ruff_cache
+.git
+.github
+*.md
+!web/README.md
+!api/README.md

.gitattributes

@@ -5,3 +5,7 @@
 # them.
 
 *.sh      text eol=lf
+
+# Codegen output must stay byte-identical across platforms so
+# `pnpm tree:check` in CI does not trip on CRLF rewrites.
+*.generated.ts  text eol=lf

.github/CODEOWNERS

@@ -18,6 +18,10 @@
 # Docs
 /docs/ @crazywoola
 
+# CLI
+/cli/ @langgenius/maintainers
+/.github/workflows/cli-tests.yml @langgenius/maintainers
+
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost
 
@@ -92,28 +96,28 @@
 /api/tasks/process_tenant_plugin_autoupgrade_check_task.py @WH-2099
 
 # Backend - Trigger/Schedule/Webhook
-/api/controllers/trigger/ @Mairuis
-/api/controllers/console/app/workflow_trigger.py @Mairuis
-/api/controllers/console/workspace/trigger_providers.py @Mairuis
-/api/core/trigger/ @Mairuis
-/api/core/app/layers/trigger_post_layer.py @Mairuis
-/api/services/trigger/ @Mairuis
-/api/models/trigger.py @Mairuis
-/api/fields/workflow_trigger_fields.py @Mairuis
-/api/repositories/workflow_trigger_log_repository.py @Mairuis
-/api/repositories/sqlalchemy_workflow_trigger_log_repository.py @Mairuis
-/api/libs/schedule_utils.py @Mairuis
-/api/services/workflow/scheduler.py @Mairuis
-/api/schedule/trigger_provider_refresh_task.py @Mairuis
-/api/schedule/workflow_schedule_task.py @Mairuis
-/api/tasks/trigger_processing_tasks.py @Mairuis
-/api/tasks/trigger_subscription_refresh_tasks.py @Mairuis
-/api/tasks/workflow_schedule_tasks.py @Mairuis
-/api/tasks/workflow_cfs_scheduler/ @Mairuis
-/api/events/event_handlers/sync_plugin_trigger_when_app_created.py @Mairuis
-/api/events/event_handlers/update_app_triggers_when_app_published_workflow_updated.py @Mairuis
-/api/events/event_handlers/sync_workflow_schedule_when_app_published.py @Mairuis
-/api/events/event_handlers/sync_webhook_when_app_created.py @Mairuis
+/api/controllers/trigger/ @CourTeous33
+/api/controllers/console/app/workflow_trigger.py @CourTeous33
+/api/controllers/console/workspace/trigger_providers.py @CourTeous33
+/api/core/trigger/ @CourTeous33
+/api/core/app/layers/trigger_post_layer.py @CourTeous33
+/api/services/trigger/ @CourTeous33
+/api/models/trigger.py @CourTeous33
+/api/fields/workflow_trigger_fields.py @CourTeous33
+/api/repositories/workflow_trigger_log_repository.py @CourTeous33
+/api/repositories/sqlalchemy_workflow_trigger_log_repository.py @CourTeous33
+/api/libs/schedule_utils.py @CourTeous33
+/api/services/workflow/scheduler.py @CourTeous33
+/api/schedule/trigger_provider_refresh_task.py @CourTeous33
+/api/schedule/workflow_schedule_task.py @CourTeous33
+/api/tasks/trigger_processing_tasks.py @CourTeous33
+/api/tasks/trigger_subscription_refresh_tasks.py @CourTeous33
+/api/tasks/workflow_schedule_tasks.py @CourTeous33
+/api/tasks/workflow_cfs_scheduler/ @CourTeous33
+/api/events/event_handlers/sync_plugin_trigger_when_app_created.py @CourTeous33
+/api/events/event_handlers/update_app_triggers_when_app_published_workflow_updated.py @CourTeous33
+/api/events/event_handlers/sync_workflow_schedule_when_app_published.py @CourTeous33
+/api/events/event_handlers/sync_webhook_when_app_created.py @CourTeous33
 
 # Backend - Async Workflow
 /api/services/async_workflow_service.py @Mairuis

.github/actions/setup-web/action.yml

@@ -5,11 +5,11 @@ runs:
   using: composite
   steps:
     - name: Setup pnpm
-      uses: pnpm/action-setup@8912a9102ac27614460f54aedde9e1e7f9aec20d # v6.0.5
+      uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
       with:
         run_install: false
     - name: Setup Vite+
-      uses: voidzero-dev/setup-vp@4f5aa3e38c781f1b01e78fb9255527cee8a6efa6 # v1.8.0
+      uses: voidzero-dev/setup-vp@ca1c46663915d6c1042ae23bd39ab85718bfb0fa # v1.10.0
       with:
         node-version-file: .nvmrc
         cache: true

.github/workflows/api-tests.yml

@@ -195,7 +195,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
         with:
           files: ./coverage.xml
           disable_search: true

.github/workflows/build-push.yml

@@ -35,15 +35,15 @@ jobs:
           - service_name: "build-api-amd64"
             image_name_env: "DIFY_API_IMAGE_NAME"
             artifact_context: "api"
-            build_context: "{{defaultContext}}:api"
-            file: "Dockerfile"
+            build_context: "{{defaultContext}}"
+            file: "api/Dockerfile"
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
           - service_name: "build-api-arm64"
             image_name_env: "DIFY_API_IMAGE_NAME"
             artifact_context: "api"
-            build_context: "{{defaultContext}}:api"
-            file: "Dockerfile"
+            build_context: "{{defaultContext}}"
+            file: "api/Dockerfile"
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
           - service_name: "build-web-amd64"
@@ -117,8 +117,8 @@ jobs:
       matrix:
         include:
           - service_name: "validate-api-amd64"
-            build_context: "{{defaultContext}}:api"
-            file: "Dockerfile"
+            build_context: "{{defaultContext}}"
+            file: "api/Dockerfile"
           - service_name: "validate-web-amd64"
             build_context: "{{defaultContext}}"
             file: "web/Dockerfile"

.github/workflows/cli-release.yml

@@ -0,0 +1,88 @@
+name: CLI Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'difyctl-v*'
+
+concurrency:
+  group: cli-release-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: build standalone binaries (all targets)
+    runs-on: depot-ubuntu-24.04
+    if: github.repository == 'langgenius/dify'
+    permissions:
+      contents: write
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5 # v2.0.2
+        with:
+          bun-version: latest
+
+      - name: Read cli/package.json
+        id: manifest
+        run: |
+          version=$(node -p "require('./package.json').version")
+          channel=$(node -p "require('./package.json').difyctl.channel")
+          minDify=$(node -p "require('./package.json').difyctl.compat.minDify")
+          maxDify=$(node -p "require('./package.json').difyctl.compat.maxDify")
+          {
+              echo "version=$version"
+              echo "channel=$channel"
+              echo "minDify=$minDify"
+              echo "maxDify=$maxDify"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Validate manifest
+        run: scripts/release-validate-manifest.sh
+
+      - name: Install cross-arch native prebuilds
+        # Re-installs node_modules with every @napi-rs/keyring platform variant
+        # so `bun build --compile` can embed the right .node into each target.
+        working-directory: ./
+        run: NPM_CONFIG_USERCONFIG="$PWD/cli/scripts/cross-arch.npmrc" pnpm install --frozen-lockfile
+
+      - name: Compile standalone binaries (all targets)
+        env:
+          CLI_VERSION: ${{ steps.manifest.outputs.version }}
+          DIFYCTL_CHANNEL: ${{ steps.manifest.outputs.channel }}
+          DIFYCTL_MIN_DIFY: ${{ steps.manifest.outputs.minDify }}
+          DIFYCTL_MAX_DIFY: ${{ steps.manifest.outputs.maxDify }}
+        run: |
+          DIFYCTL_COMMIT="$(git rev-parse HEAD)" \
+          DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
+            pnpm build:bin
+
+      - name: Generate sha256 checksum file
+        env:
+          CLI_VERSION: ${{ steps.manifest.outputs.version }}
+        run: scripts/release-write-checksums.sh
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2
+        with:
+          tag_name: difyctl-v${{ steps.manifest.outputs.version }}
+          name: difyctl ${{ steps.manifest.outputs.version }}
+          prerelease: ${{ steps.manifest.outputs.channel != 'stable' }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: |
+            cli/dist/bin/difyctl-v*

.github/workflows/cli-smoke.yml

@@ -0,0 +1,60 @@
+name: CLI Smoke (live dify)
+
+on:
+  workflow_dispatch:
+    inputs:
+      dify_version:
+        description: "Dify image tag to test against (e.g. 1.7.0)"
+        type: string
+        required: true
+      cli_ref:
+        description: "Git ref to build the cli from (default: current branch)"
+        type: string
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout cli ref
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Bring up dify
+        env:
+          DIFY_VERSION: ${{ inputs.dify_version }}
+        run: |
+          cd docker
+          cp .env.example .env
+          DIFY_API_IMAGE_TAG="$DIFY_VERSION" \
+          DIFY_WEB_IMAGE_TAG="$DIFY_VERSION" \
+          docker compose up -d api worker web db redis
+          for i in $(seq 1 60); do
+              if curl -fsS http://localhost:5001/health >/dev/null 2>&1; then
+                  echo "dify api ready after ${i}s"
+                  break
+              fi
+              sleep 1
+          done
+
+      - name: Run smoke against live dify
+        working-directory: ./cli
+        run: pnpm exec tsx scripts/run-smoke.ts --base-url http://localhost:5001
+
+      - name: Dump dify logs on failure
+        if: failure()
+        run: |
+          cd docker
+          docker compose logs api worker web --tail=200

.github/workflows/cli-tests.yml

@@ -0,0 +1,46 @@
+name: CLI Tests
+
+on:
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cli-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: CLI Tests
+    runs-on: depot-ubuntu-24.04
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: CI pipeline (typecheck, lint, coverage, build)
+        run: pnpm ci
+
+      - name: Report coverage
+        if: ${{ env.CODECOV_TOKEN != '' }}
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        with:
+          directory: cli/coverage
+          flags: cli
+        env:
+          CODECOV_TOKEN: ${{ env.CODECOV_TOKEN }}

.github/workflows/docker-build.yml

@@ -6,6 +6,12 @@ on:
       - "main"
     paths:
       - api/Dockerfile
+      - api/Dockerfile.dockerignore
+      - api/pyproject.toml
+      - api/uv.lock
+      - dify-agent/pyproject.toml
+      - dify-agent/README.md
+      - dify-agent/src/**
       - web/Dockerfile
 
 concurrency:
@@ -25,13 +31,13 @@ jobs:
           - service_name: "api-amd64"
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
-            context: "{{defaultContext}}:api"
-            file: "Dockerfile"
+            context: "{{defaultContext}}"
+            file: "api/Dockerfile"
           - service_name: "api-arm64"
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
-            context: "{{defaultContext}}:api"
-            file: "Dockerfile"
+            context: "{{defaultContext}}"
+            file: "api/Dockerfile"
           - service_name: "web-amd64"
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
@@ -64,8 +70,8 @@ jobs:
       matrix:
         include:
           - service_name: "api-amd64"
-            context: "{{defaultContext}}:api"
-            file: "Dockerfile"
+            context: "{{defaultContext}}"
+            file: "api/Dockerfile"
           - service_name: "web-amd64"
             context: "{{defaultContext}}"
             file: "web/Dockerfile"

.github/workflows/main-ci.yml

@@ -42,6 +42,7 @@ jobs:
     runs-on: depot-ubuntu-24.04
     outputs:
       api-changed: ${{ steps.changes.outputs.api }}
+      cli-changed: ${{ steps.changes.outputs.cli }}
       e2e-changed: ${{ steps.changes.outputs.e2e }}
       web-changed: ${{ steps.changes.outputs.web }}
       vdb-changed: ${{ steps.changes.outputs.vdb }}
@@ -62,6 +63,18 @@ jobs:
               - 'docker/generate_docker_compose'
               - 'docker/ssrf_proxy/**'
               - 'docker/volumes/sandbox/conf/**'
+            cli:
+              - 'cli/**'
+              - 'packages/tsconfig/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'eslint.config.mjs'
+              - '.npmrc'
+              - '.nvmrc'
+              - '.github/workflows/cli-tests.yml'
+              - '.github/workflows/cli-docker-build.yml'
+              - '.github/actions/setup-web/**'
             web:
               - 'web/**'
               - 'packages/**'
@@ -184,6 +197,66 @@ jobs:
           echo "API tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
           exit 1
 
+  cli-tests-run:
+    name: Run CLI Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.cli-changed == 'true'
+    uses: ./.github/workflows/cli-tests.yml
+    secrets: inherit
+
+  cli-tests-skip:
+    name: Skip CLI Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.cli-changed != 'true'
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Report skipped CLI tests
+        run: echo "No CLI-related changes detected; skipping CLI tests."
+
+  cli-tests:
+    name: CLI Tests
+    if: ${{ always() }}
+    needs:
+      - pre_job
+      - check-changes
+      - cli-tests-run
+      - cli-tests-skip
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Finalize CLI Tests status
+        env:
+          SHOULD_SKIP_WORKFLOW: ${{ needs.pre_job.outputs.should_skip }}
+          TESTS_CHANGED: ${{ needs.check-changes.outputs.cli-changed }}
+          RUN_RESULT: ${{ needs.cli-tests-run.result }}
+          SKIP_RESULT: ${{ needs.cli-tests-skip.result }}
+        run: |
+          if [[ "$SHOULD_SKIP_WORKFLOW" == 'true' ]]; then
+            echo "CLI tests were skipped because this workflow run duplicated a successful or newer run."
+            exit 0
+          fi
+
+          if [[ "$TESTS_CHANGED" == 'true' ]]; then
+            if [[ "$RUN_RESULT" == 'success' ]]; then
+              echo "CLI tests ran successfully."
+              exit 0
+            fi
+
+            echo "CLI tests were required but finished with result: $RUN_RESULT" >&2
+            exit 1
+          fi
+
+          if [[ "$SKIP_RESULT" == 'success' ]]; then
+            echo "CLI tests were skipped because no CLI-related files changed."
+            exit 0
+          fi
+
+          echo "CLI tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
+          exit 1
+
   web-tests-run:
     name: Run Web Tests
     needs:

.github/workflows/pyrefly-type-coverage-comment.yml

@@ -63,8 +63,8 @@ jobs:
         id: render
         run: |
           comment_body="$(uv run --directory api python libs/pyrefly_type_coverage.py \
-            --base base_report.json \
-            < pr_report.json)"
+            --base "$GITHUB_WORKSPACE/base_report.json" \
+            < "$GITHUB_WORKSPACE/pr_report.json")"
 
           {
             echo "### Pyrefly Type Coverage"

.github/workflows/pyrefly-type-coverage.yml

@@ -65,6 +65,9 @@ jobs:
           # Save structured data for the fork-PR comment workflow
           cp /tmp/pyrefly_report_pr.json pr_report.json
           cp /tmp/pyrefly_report_base.json base_report.json
+          # Keep fork-PR comments correct while the trusted workflow_run job is
+          # still using the default-branch renderer, which resolves --base from api/.
+          cp /tmp/pyrefly_report_base.json api/base_report.json
 
       - name: Save PR number
         run: |
@@ -77,6 +80,7 @@ jobs:
           path: |
             pr_report.json
             base_report.json
+            api/base_report.json
             pr_number.txt
 
       - name: Comment PR with type coverage

.github/workflows/style.yml

@@ -47,6 +47,10 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         run: uv run --directory api --dev lint-imports
 
+      - name: Run Response Contract Linter
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: uv run --project api --dev python api/dev/lint_response_contracts.py --fail-on-mismatch
+
       - name: Run Type Checks
         if: steps.changed-files.outputs.any_changed == 'true'
         run: make type-check-core

.github/workflows/translate-i18n-claude.yml

@@ -158,7 +158,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@476e359e6203e73dad705c8b322e333fabbd7416 # v1.0.119
+        uses: anthropics/claude-code-action@1dc994ee7a008f0ecc866d9ac23ef036b7229f84 # v1.0.127
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/web-tests.yml

@@ -39,7 +39,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Run tests
-        run: vp test run --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --coverage
+        run: vp test run --reporter=blob --reporter=minimal --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --coverage
 
       - name: Upload blob report
         if: ${{ !cancelled() }}
@@ -83,7 +83,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
         with:
           directory: web/coverage
           flags: web
@@ -117,7 +117,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
         with:
           directory: packages/dify-ui/coverage
           flags: dify-ui

.gitignore

@@ -115,6 +115,12 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+
+# cli/ has a src/env/ module (DIFY_* registry) — don't treat it as a venv
+!/cli/src/env/
+!/cli/src/commands/env/
+# cli/scripts/lib/ holds TS build helpers (resolve-buildinfo etc.) — don't treat as Python lib/
+!/cli/scripts/lib/
 .conda/
 
 # Spyder project settings
@@ -247,6 +253,7 @@ scripts/stress-test/reports/
 # settings
 *.local.json
 *.local.md
+*.local.toml
 
 # Code Agent Folder
 .qoder/*

Makefile

@@ -75,13 +75,19 @@ check:
 	@echo "✅ Code check complete"
 
 lint:
-	@echo "🔧 Running ruff format, check with fixes, import linter, and dotenv-linter..."
+	@echo "🔧 Running ruff format, check with fixes, response contract lint, import linter, and dotenv-linter..."
 	@uv run --project api --dev ruff format ./api
 	@uv run --project api --dev ruff check --fix ./api
+	@$(MAKE) api-contract-lint
 	@uv run --directory api --dev lint-imports
 	@uv run --project api --dev dotenv-linter ./api/.env.example ./web/.env.example
 	@echo "✅ Linting complete"
 
+api-contract-lint:
+	@echo "🔎 Linting Flask response contracts..."
+	@uv run --project api --dev python api/dev/lint_response_contracts.py
+	@echo "✅ Response contract lint complete"
+
 type-check:
 	@echo "📝 Running type checks (pyrefly + mypy)..."
 	@./dev/pyrefly-check-local $(PATH_TO_CHECK)
@@ -191,6 +197,7 @@ help:
 	@echo "  make format         - Format code with ruff"
 	@echo "  make check          - Check code with ruff"
 	@echo "  make lint           - Format, fix, and lint code (ruff, imports, dotenv)"
+	@echo "  make api-contract-lint - Check Flask response docs against returned schemas"
 	@echo "  make type-check     - Run type checks (pyrefly, mypy)"
 	@echo "  make type-check-core - Run core type checks (pyrefly, mypy)"
 	@echo "  make test           - Run backend unit tests (or TARGET_TESTS=./api/tests/<target_tests>)"
@@ -204,4 +211,4 @@ help:
 	@echo "  make build-push-all - Build and push all Docker images"
 
 # Phony targets
-.PHONY: build-web build-api push-web push-api build-all push-all build-push-all dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint type-check test test-all
+.PHONY: build-web build-api push-web push-api build-all push-all build-push-all dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint api-contract-lint type-check test test-all

api/.env.example

@@ -657,6 +657,7 @@ PLUGIN_REMOTE_INSTALL_PORT=5003
 PLUGIN_REMOTE_INSTALL_HOST=localhost
 PLUGIN_MAX_PACKAGE_SIZE=15728640
 PLUGIN_MODEL_SCHEMA_CACHE_TTL=3600
+PLUGIN_MODEL_PROVIDERS_CACHE_TTL=86400
 INNER_API_KEY_FOR_PLUGIN=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y1
 
 # Marketplace configuration
@@ -767,6 +768,7 @@ EVENT_BUS_REDIS_CHANNEL_TYPE=pubsub
 # Whether to use Redis cluster mode while use redis as event bus.
 #  It's highly recommended to enable this for large deployments.
 EVENT_BUS_REDIS_USE_CLUSTERS=false
+EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS=2000
 
 # Whether to Enable human input timeout check task
 ENABLE_HUMAN_INPUT_TIMEOUT_TASK=true

api/AGENTS.md

@@ -195,6 +195,7 @@ Before opening a PR / submitting:
 - Controllers: parse input via Pydantic, invoke services, return serialised responses; no business logic.
 - Services: coordinate repositories, providers, background tasks; keep side effects explicit.
 - Document non-obvious behaviour with concise docstrings and comments.
+- For `204 No Content` responses, return an empty body only; never return a dict, model, or other payload.
 - For Flask-RESTX controller request, query, and response schemas, follow `controllers/API_SCHEMA_GUIDE.md`.
   In short: use Pydantic models, document GET query params with `query_params_from_model(...)`, register response
   DTOs with `register_response_schema_models(...)`, serialize response DTOs with `dump_response(...)`,

api/Dockerfile

@@ -22,9 +22,11 @@ RUN apt-get update \
           libmpfr-dev libmpc-dev
 
 # Install Python dependencies (workspace members under providers/vdb/)
-COPY pyproject.toml uv.lock ./
-COPY providers ./providers
-# Trust the checked-in lock during image builds; dev-only path sources live outside the api/ context.
+COPY api/pyproject.toml api/uv.lock ./
+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
 
 # production stage
@@ -108,10 +110,10 @@ RUN python -c "import tiktoken; tiktoken.encoding_for_model('gpt2')" \
     && chown -R dify:dify ${TIKTOKEN_CACHE_DIR}
 
 # Copy source code
-COPY --chown=dify:dify . /app/api/
+COPY --chown=dify:dify api /app/api/
 
 # Prepare entrypoint script
-COPY --chown=dify:dify --chmod=755 docker/entrypoint.sh /entrypoint.sh
+COPY --chown=dify:dify --chmod=755 api/docker/entrypoint.sh /entrypoint.sh
 
 
 ARG COMMIT_SHA

api/Dockerfile.dockerignore

@@ -0,0 +1,25 @@
+*
+
+!api/
+!api/**
+!dify-agent/
+!dify-agent/pyproject.toml
+!dify-agent/README.md
+!dify-agent/src/
+!dify-agent/src/**
+
+api/.venv
+api/.venv/**
+api/.env
+api/*.env.*
+api/.idea
+api/.mypy_cache
+api/.ruff_cache
+api/storage/generate_files/*
+api/storage/privkeys/*
+api/storage/tools/*
+api/storage/upload_files/*
+api/logs
+api/*.log*
+**/__pycache__
+**/*.pyc

api/app_factory.py

@@ -159,6 +159,7 @@ def initialize_extensions(app: DifyApp):
         ext_logstore,
         ext_mail,
         ext_migrate,
+        ext_oauth_bearer,
         ext_orjson,
         ext_otel,
         ext_proxy_fix,
@@ -203,6 +204,7 @@ def initialize_extensions(app: DifyApp):
         ext_enterprise_telemetry,
         ext_request_logging,
         ext_session_factory,
+        ext_oauth_bearer,
     ]
     for ext in extensions:
         short_name = ext.__name__.split(".")[-1]
@@ -221,10 +223,11 @@ def initialize_extensions(app: DifyApp):
 
 def create_migrations_app() -> DifyApp:
     app = create_flask_app_with_configs()
-    from extensions import ext_database, ext_migrate
+    from extensions import ext_commands, ext_database, ext_migrate
 
     # Initialize only required extensions
     ext_database.init_app(app)
     ext_migrate.init_app(app)
+    ext_commands.init_app(app)
 
     return app

api/clients/agent_backend/request_builder.py

@@ -49,15 +49,20 @@ class AgentBackendModelConfig(BaseModel):
     model: str
     user_id: str | None = None
     credentials: dict[str, DifyPluginCredentialValue] = Field(default_factory=dict)
+    model_settings: dict[str, JsonValue] = Field(default_factory=dict)
 
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
 
 
 class AgentBackendOutputConfig(BaseModel):
-    """API-side structured output declaration for the conventional output layer."""
+    """API-side structured output declaration for the conventional output layer.
+
+    The structured-output tool name is fixed to ``final_output`` inside
+    ``dify_agent.layers.output`` so callers only control the JSON Schema plus
+    optional description/strictness metadata.
+    """
 
     json_schema: dict[str, JsonValue]
-    name: str = "final_result"
     description: str | None = None
     strict: bool | None = None
 
@@ -138,6 +143,7 @@ class AgentBackendRunRequestBuilder:
                         model_provider=run_input.model.model_provider,
                         model=run_input.model.model,
                         credentials=run_input.model.credentials,
+                        model_settings=run_input.model.model_settings or None,
                     ),
                 ),
             ]
@@ -151,7 +157,6 @@ class AgentBackendRunRequestBuilder:
                     metadata=run_input.metadata,
                     config=DifyOutputLayerConfig(
                         json_schema=run_input.output.json_schema,
-                        name=run_input.output.name,
                         description=run_input.output.description,
                         strict=run_input.output.strict,
                     ),

api/commands/__init__.py

@@ -3,6 +3,7 @@ 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 .plugin import (
     extract_plugins,
     extract_unique_plugins,
@@ -44,6 +45,7 @@ __all__ = [
     "clear_orphaned_file_records",
     "convert_to_agent_apps",
     "create_tenant",
+    "data_migrate",
     "delete_archived_workflow_runs",
     "export_app_messages",
     "extract_plugins",
@@ -52,6 +54,7 @@ __all__ = [
     "fix_app_site_missing",
     "install_plugins",
     "install_rag_pipeline_plugins",
+    "legacy_model_types",
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",
     "migrate_knowledge_vector_database",

api/commands/data_migrate.py

@@ -0,0 +1,168 @@
+import io
+import os
+import sys
+from contextlib import nullcontext
+from pathlib import Path
+from typing import cast
+
+import click
+
+from extensions.ext_database import db
+from graphon.model_runtime.entities.model_entities import ModelType
+from services.legacy_model_type_migration import (
+    VALID_TABLE_NAMES,
+    LegacyModelTypeMigrationService,
+    load_tenant_ids_from_file,
+)
+
+_SUPPORTED_MODEL_TYPE_CHOICES = (
+    ModelType.LLM.value,
+    ModelType.TEXT_EMBEDDING.value,
+    ModelType.RERANK.value,
+)
+_DEFAULT_CONCURRENCY = os.cpu_count() or 1
+
+
+def _normalize_multi_value_option(
+    values: tuple[str, ...],
+    *,
+    valid_values: tuple[str, ...],
+    option_name: str,
+) -> tuple[str, ...]:
+    normalized_values: list[str] = []
+    seen_values: set[str] = set()
+
+    for value in values:
+        for item in value.split(","):
+            normalized_item = item.strip()
+            if not normalized_item:
+                continue
+            if normalized_item not in valid_values:
+                raise click.BadParameter(
+                    f"invalid value '{normalized_item}'. valid values: {', '.join(valid_values)}",
+                    param_hint=option_name,
+                )
+            if normalized_item in seen_values:
+                continue
+            seen_values.add(normalized_item)
+            normalized_values.append(normalized_item)
+
+    return tuple(normalized_values)
+
+
+@click.group(
+    "data-migrate",
+    help="Online data migration commands.",
+)
+def data_migrate() -> None:
+    """Namespace for production data migration commands."""
+
+
+@click.command(
+    "legacy-model-types",
+    help=(
+        "Migrate legacy provider model_type values to canonical values. "
+        "Default is dry-run and emits JSON lines only. "
+        "If --tables includes provider_model_credentials, the command may also update "
+        "provider_models and load_balancing_model_configs references so merged credentials stay reachable."
+    ),
+)
+@click.option(
+    "--apply",
+    is_flag=True,
+    default=False,
+    help="Apply the migration. Default is dry-run.",
+)
+@click.option(
+    "--tables",
+    "tables",
+    multiple=True,
+    type=str,
+    help=(
+        "Limit model_type migration to specific tables. Accepts comma-separated values or repeated flags. "
+        "When provider_model_credentials is selected, provider_models and "
+        "load_balancing_model_configs may also be updated for credential reference rewrites."
+        "Default to: "
+    ),
+)
+@click.option(
+    "--model-types",
+    "model_types",
+    multiple=True,
+    type=str,
+    help=(
+        "Canonical model types to migrate. Accepts comma-separated values or repeated flags. "
+        "Defaults to: `llm,text-embedding,rerank`"
+    ),
+)
+@click.option(
+    "--tenant-id-file",
+    type=click.Path(exists=True, dir_okay=False, readable=True, resolve_path=True),
+    help="Optional file containing tenant ids, one per line.",
+)
+@click.option(
+    "--output",
+    type=click.Path(dir_okay=False, resolve_path=True, path_type=Path),
+    help="Optional file path for JSON lines event logs. Defaults to stdout.",
+)
+@click.option(
+    "--concurrency",
+    type=click.IntRange(min=1),
+    default=_DEFAULT_CONCURRENCY,
+    show_default=True,
+    help="Number of tenant-level worker threads to run in parallel.",
+)
+def legacy_model_types(
+    apply: bool,
+    tables: tuple[str, ...],
+    model_types: tuple[str, ...],
+    tenant_id_file: str | None,
+    output: Path | None,
+    concurrency: int = _DEFAULT_CONCURRENCY,
+) -> None:
+    """
+    Migrate legacy provider-related model_type values and emit JSON lines events.
+    """
+
+    normalized_tables = _normalize_multi_value_option(
+        tables,
+        valid_values=VALID_TABLE_NAMES,
+        option_name="--tables",
+    )
+    normalized_model_types = _normalize_multi_value_option(
+        model_types,
+        valid_values=_SUPPORTED_MODEL_TYPE_CHOICES,
+        option_name="--model-types",
+    )
+    selected_model_types = (
+        tuple(ModelType.value_of(model_type) for model_type in normalized_model_types)
+        if normalized_model_types
+        else (
+            ModelType.LLM,
+            ModelType.TEXT_EMBEDDING,
+            ModelType.RERANK,
+        )
+    )
+    tenant_ids = load_tenant_ids_from_file(tenant_id_file) if tenant_id_file else None
+
+    if output is None:
+        output_context = nullcontext(sys.stdout)
+    else:
+        try:
+            output_context = output.open("w", encoding="utf-8")
+        except OSError as exc:
+            raise click.ClickException(f"failed to open output file '{output}': {exc.strerror or exc}") from exc
+
+    with output_context as output_stream:
+        LegacyModelTypeMigrationService(
+            engine=db.engine,
+            apply=apply,
+            concurrency=concurrency,
+            output=cast(io.TextIOBase, output_stream),
+            tables=normalized_tables or None,
+            model_types=selected_model_types,
+            tenant_ids=tenant_ids,
+        ).migrate()
+
+
+data_migrate.add_command(legacy_model_types)

api/commands/plugin.py

@@ -11,6 +11,7 @@ from configs import dify_config
 from core.helper import encrypter
 from core.plugin.entities.plugin_daemon import CredentialType
 from core.plugin.impl.plugin import PluginInstaller
+from core.plugin.plugin_service import PluginService
 from core.tools.utils.system_encryption import encrypt_system_params
 from extensions.ext_database import db
 from models import Tenant
@@ -20,7 +21,6 @@ from models.source import DataSourceApiKeyAuthBinding, DataSourceOauthBinding
 from models.tools import ToolOAuthSystemClient
 from services.plugin.data_migration import PluginDataMigration
 from services.plugin.plugin_migration import PluginMigration
-from services.plugin.plugin_service import PluginService
 
 logger = logging.getLogger(__name__)
 

api/configs/app_config.py

@@ -1,6 +1,6 @@
 import logging
 from pathlib import Path
-from typing import Any
+from typing import Any, override
 
 from pydantic.fields import FieldInfo
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, TomlConfigSettingsSource
@@ -25,6 +25,7 @@ class RemoteSettingsSourceFactory(PydanticBaseSettingsSource):
     def __init__(self, settings_cls: type[BaseSettings]):
         super().__init__(settings_cls)
 
+    @override
     def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
         raise NotImplementedError
 
@@ -90,6 +91,7 @@ class DifyConfig(
     # Thanks for your concentration and consideration.
 
     @classmethod
+    @override
     def settings_customise_sources(
         cls,
         settings_cls: type[BaseSettings],

api/configs/deploy/__init__.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from pydantic import Field
 from pydantic_settings import BaseSettings
 
@@ -23,7 +25,7 @@ class DeploymentConfig(BaseSettings):
         default=False,
     )
 
-    EDITION: str = Field(
+    EDITION: Literal["SELF_HOSTED", "CLOUD"] = Field(
         description="Deployment edition of the application (e.g., 'SELF_HOSTED', 'CLOUD')",
         default="SELF_HOSTED",
     )

api/configs/extra/__init__.py

@@ -1,3 +1,4 @@
+from configs.extra.agent_backend_config import AgentBackendConfig
 from configs.extra.archive_config import ArchiveStorageConfig
 from configs.extra.notion_config import NotionConfig
 from configs.extra.sentry_config import SentryConfig
@@ -5,6 +6,7 @@ from configs.extra.sentry_config import SentryConfig
 
 class ExtraServiceConfig(
     # place the configs in alphabet order
+    AgentBackendConfig,
     ArchiveStorageConfig,
     NotionConfig,
     SentryConfig,

api/configs/extra/agent_backend_config.py

@@ -0,0 +1,23 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class AgentBackendConfig(BaseSettings):
+    """
+    Configuration settings for the Agent backend runtime integration.
+    """
+
+    AGENT_BACKEND_BASE_URL: str | None = Field(
+        description="Base URL for the Dify Agent backend service.",
+        default=None,
+    )
+
+    AGENT_BACKEND_USE_FAKE: bool = Field(
+        description="Use the deterministic in-process fake Agent backend client.",
+        default=False,
+    )
+
+    AGENT_BACKEND_FAKE_SCENARIO: str = Field(
+        description="Scenario used by the fake Agent backend client.",
+        default="success",
+    )

api/configs/feature/__init__.py

@@ -265,6 +265,11 @@ class PluginConfig(BaseSettings):
         default=60 * 60,
     )
 
+    PLUGIN_MODEL_PROVIDERS_CACHE_TTL: PositiveInt = Field(
+        description="TTL in seconds for caching tenant plugin model providers in Redis",
+        default=60 * 60 * 24,
+    )
+
     PLUGIN_MAX_FILE_SIZE: PositiveInt = Field(
         description="Maximum allowed size (bytes) for plugin-generated files",
         default=50 * 1024 * 1024,
@@ -520,6 +525,44 @@ class HttpConfig(BaseSettings):
     def WEB_API_CORS_ALLOW_ORIGINS(self) -> list[str]:
         return self.inner_WEB_API_CORS_ALLOW_ORIGINS.split(",")
 
+    OPENAPI_ENABLED: bool = Field(
+        description=(
+            "Enable the /openapi/v1/* endpoint group used by difyctl and other "
+            "programmatic clients. Set to true to activate; disabled by default."
+        ),
+        validation_alias=AliasChoices("OPENAPI_ENABLED"),
+        default=False,
+    )
+
+    inner_OPENAPI_CORS_ALLOW_ORIGINS: str = Field(
+        description=(
+            "Comma-separated allowlist for /openapi/v1/* CORS. "
+            "Default empty = same-origin only. Browser-cookie routes within "
+            "the group reject cross-origin OPTIONS regardless of this list."
+        ),
+        validation_alias=AliasChoices("OPENAPI_CORS_ALLOW_ORIGINS"),
+        default="",
+    )
+
+    @computed_field
+    def OPENAPI_CORS_ALLOW_ORIGINS(self) -> list[str]:
+        return [o for o in self.inner_OPENAPI_CORS_ALLOW_ORIGINS.split(",") if o]
+
+    inner_OPENAPI_KNOWN_CLIENT_IDS: str = Field(
+        description=(
+            "Comma-separated client_id values accepted at "
+            "POST /openapi/v1/oauth/device/code. New CLIs / SDKs added here "
+            "without code changes. Unknown client_id returns 400 unsupported_client."
+        ),
+        validation_alias=AliasChoices("OPENAPI_KNOWN_CLIENT_IDS"),
+        default="difyctl",
+    )
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def OPENAPI_KNOWN_CLIENT_IDS(self) -> frozenset[str]:
+        return frozenset(c for c in self.inner_OPENAPI_KNOWN_CLIENT_IDS.split(",") if c)
+
     HTTP_REQUEST_MAX_CONNECT_TIMEOUT: int = Field(
         ge=1, description="Maximum connection timeout in seconds for HTTP requests", default=10
     )
@@ -895,6 +938,17 @@ class AuthConfig(BaseSettings):
         default=86400,
     )
 
+    ENABLE_OAUTH_BEARER: bool = Field(
+        description="Enable OAuth bearer authentication (device-flow + Service API /v1/* bearer middleware).",
+        default=True,
+    )
+
+    OPENAPI_RATE_LIMIT_PER_TOKEN: PositiveInt = Field(
+        description="Per-token rate limit on /openapi/v1/* (requests per minute). "
+        "Bucket keyed on sha256(token), shared across api replicas via Redis.",
+        default=60,
+    )
+
 
 class ModerationConfig(BaseSettings):
     """
@@ -1181,6 +1235,14 @@ class CeleryScheduleTasksConfig(BaseSettings):
         description="Enable scheduled workflow run cleanup task",
         default=False,
     )
+    ENABLE_CLEAN_OAUTH_ACCESS_TOKENS_TASK: bool = Field(
+        description="Enable scheduled cleanup of revoked/expired OAuth access-token rows past retention.",
+        default=True,
+    )
+    OAUTH_ACCESS_TOKEN_RETENTION_DAYS: PositiveInt = Field(
+        description="Days to retain revoked OAuth access-token rows before deletion.",
+        default=30,
+    )
     ENABLE_MAIL_CLEAN_DOCUMENT_NOTIFY_TASK: bool = Field(
         description="Enable mail clean document notify task",
         default=False,

api/configs/middleware/cache/redis_pubsub_config.py

@@ -2,6 +2,7 @@ from typing import Literal, Protocol, cast
 from urllib.parse import quote_plus, urlunparse
 
 from pydantic import AliasChoices, Field
+from pydantic.types import NonNegativeInt
 from pydantic_settings import BaseSettings
 
 
@@ -70,6 +71,24 @@ class RedisPubSubConfig(BaseSettings):
         default=600,
     )
 
+    PUBSUB_LISTENER_JOIN_TIMEOUT_MS: NonNegativeInt = Field(
+        validation_alias=AliasChoices("EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS", "PUBSUB_LISTENER_JOIN_TIMEOUT_MS"),
+        description=(
+            "Maximum time (milliseconds) that ``Subscription.close()`` waits for its listener thread to "
+            "finish before returning. Bounds the tail latency between a terminal event being delivered to "
+            "an SSE client and the response stream actually closing.\n\n"
+            "The listener thread blocks on a polling read (XREAD BLOCK for streams, get_message timeout "
+            "for pubsub/sharded) with a fixed 1s window, so close() naturally has to wait up to ~1s for "
+            "the thread to notice the subscription was closed. Setting this lower (e.g. 100) lets close() "
+            "return promptly while the daemon listener thread cleans itself up on the next poll "
+            "boundary - safe because the listener holds no critical state and exits within one poll "
+            "window. Setting it higher (e.g. 5000) gives the listener more grace before close() gives up "
+            "and logs a warning. Default 2000ms preserves the pre-change behaviour.\n\n"
+            "Also accepts ENV: EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS."
+        ),
+        default=2000,
+    )
+
     def _build_default_pubsub_url(self) -> str:
         defaults = _redis_defaults(self)
         if not defaults.REDIS_HOST or not defaults.REDIS_PORT:

api/configs/remote_settings_sources/apollo/__init__.py

@@ -1,5 +1,5 @@
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, override
 
 from pydantic import Field
 from pydantic.fields import FieldInfo
@@ -48,6 +48,7 @@ class ApolloSettingsSource(RemoteSettingsSource):
         self.namespace = configs["APOLLO_NAMESPACE"]
         self.remote_configs = self.client.get_all_dicts(self.namespace)
 
+    @override
     def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
         if not isinstance(self.remote_configs, dict):
             raise ValueError(f"remote configs is not dict, but {type(self.remote_configs)}")

api/configs/remote_settings_sources/nacos/__init__.py

@@ -1,7 +1,7 @@
 import logging
 import os
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, override
 
 from pydantic.fields import FieldInfo
 
@@ -41,6 +41,7 @@ class NacosSettingsSource(RemoteSettingsSource):
         except Exception as e:
             raise RuntimeError(f"Failed to parse config: {e}")
 
+    @override
     def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
         field_value = self.remote_configs.get(field_name)
         if field_value is None:

api/context/execution_context.py

@@ -10,7 +10,7 @@ import threading
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator
 from contextlib import AbstractContextManager, contextmanager
-from typing import Any, Protocol, final, runtime_checkable
+from typing import Any, Protocol, final, override, runtime_checkable
 
 from pydantic import BaseModel
 
@@ -133,10 +133,12 @@ class NullAppContext(AppContext):
         self._config = config or {}
         self._extensions: dict[str, Any] = {}
 
+    @override
     def get_config(self, key: str, default: Any = None) -> Any:
         """Get configuration value by key."""
         return self._config.get(key, default)
 
+    @override
     def get_extension(self, name: str) -> Any:
         """Get extension by name."""
         return self._extensions.get(name)
@@ -146,6 +148,7 @@ class NullAppContext(AppContext):
         self._extensions[name] = extension
 
     @contextmanager
+    @override
     def enter(self) -> Generator[None, None, None]:
         """Enter null context (no-op)."""
         yield

api/context/flask_app_context.py

@@ -6,7 +6,7 @@ import contextvars
 import threading
 from collections.abc import Generator
 from contextlib import contextmanager
-from typing import Any, final
+from typing import Any, final, override
 
 from flask import Flask, current_app, g
 
@@ -30,15 +30,18 @@ class FlaskAppContext(AppContext):
         """
         self._flask_app = flask_app
 
+    @override
     def get_config(self, key: str, default: Any = None) -> Any:
         """Get configuration value from Flask app config."""
         return self._flask_app.config.get(key, default)
 
+    @override
     def get_extension(self, name: str) -> Any:
         """Get Flask extension by name."""
         return self._flask_app.extensions.get(name)
 
     @contextmanager
+    @override
     def enter(self) -> Generator[None, None, None]:
         """Enter Flask app context."""
         with self._flask_app.app_context():

api/controllers/common/helpers.py

@@ -36,6 +36,24 @@ class FileInfo(BaseModel):
     size: int
 
 
+def decode_remote_url(url: str, query_string: bytes | str = b"") -> str:
+    decoded_url = urllib.parse.unquote(url)
+    if isinstance(query_string, bytes):
+        raw_query = query_string.decode()
+    else:
+        raw_query = query_string
+    if not raw_query:
+        return decoded_url
+
+    if decoded_url.endswith(("?", "&")):
+        separator = ""
+    elif urllib.parse.urlsplit(decoded_url).query:
+        separator = "&"
+    else:
+        separator = "?"
+    return f"{decoded_url}{separator}{raw_query}"
+
+
 def guess_file_info_from_response(response: httpx.Response):
     url = str(response.url)
     # Try to extract filename from URL

api/controllers/console/agent/roster.py

@@ -1,3 +1,5 @@
+from uuid import UUID
+
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
@@ -80,7 +82,7 @@ class AgentRosterDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, agent_id):
+    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))
 
@@ -89,7 +91,7 @@ class AgentRosterDetailApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def patch(self, agent_id):
+    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(
@@ -100,7 +102,7 @@ class AgentRosterDetailApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def delete(self, agent_id):
+    def delete(self, agent_id: UUID):
         account, tenant_id = current_account_with_tenant()
         _agent_roster_service().archive_roster_agent(tenant_id=tenant_id, agent_id=str(agent_id), account_id=account.id)
         return "", 204
@@ -111,7 +113,7 @@ class AgentRosterVersionsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, agent_id):
+    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))}
 
@@ -121,7 +123,7 @@ class AgentRosterVersionDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, agent_id, version_id):
+    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,

api/controllers/console/apikey.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from uuid import UUID
 
 import flask_restx
 from flask_restx import Resource
@@ -146,7 +147,7 @@ class BaseApiKeyResource(Resource):
         db.session.execute(delete(ApiToken).where(ApiToken.id == api_key_id))
         db.session.commit()
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/apps/<uuid:resource_id>/api-keys")
@@ -155,7 +156,7 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(description="Get all API keys for an app")
     @console_ns.doc(params={"resource_id": "App ID"})
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
-    def get(self, resource_id):  # type: ignore
+    def get(self, resource_id: UUID):
         """Get all API keys for an app"""
         return super().get(resource_id)
 
@@ -164,7 +165,7 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(params={"resource_id": "App ID"})
     @console_ns.response(201, "API key created successfully", console_ns.models[ApiKeyItem.__name__])
     @console_ns.response(400, "Maximum keys exceeded")
-    def post(self, resource_id):  # type: ignore
+    def post(self, resource_id: UUID):
         """Create a new API key for an app"""
         return super().post(resource_id)
 
@@ -180,9 +181,9 @@ class AppApiKeyResource(BaseApiKeyResource):
     @console_ns.doc(description="Delete an API key for an app")
     @console_ns.doc(params={"resource_id": "App ID", "api_key_id": "API key ID"})
     @console_ns.response(204, "API key deleted successfully")
-    def delete(self, resource_id, api_key_id):
+    def delete(self, resource_id: UUID, api_key_id: UUID):
         """Delete an API key for an app"""
-        return super().delete(resource_id, api_key_id)
+        return super().delete(str(resource_id), str(api_key_id))
 
     resource_type = ApiTokenType.APP
     resource_model = App
@@ -195,7 +196,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(description="Get all API keys for a dataset")
     @console_ns.doc(params={"resource_id": "Dataset ID"})
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
-    def get(self, resource_id):  # type: ignore
+    def get(self, resource_id: UUID):
         """Get all API keys for a dataset"""
         return super().get(resource_id)
 
@@ -204,7 +205,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(params={"resource_id": "Dataset ID"})
     @console_ns.response(201, "API key created successfully", console_ns.models[ApiKeyItem.__name__])
     @console_ns.response(400, "Maximum keys exceeded")
-    def post(self, resource_id):  # type: ignore
+    def post(self, resource_id: UUID):
         """Create a new API key for a dataset"""
         return super().post(resource_id)
 
@@ -220,9 +221,9 @@ class DatasetApiKeyResource(BaseApiKeyResource):
     @console_ns.doc(description="Delete an API key for a dataset")
     @console_ns.doc(params={"resource_id": "Dataset ID", "api_key_id": "API key ID"})
     @console_ns.response(204, "API key deleted successfully")
-    def delete(self, resource_id, api_key_id):
+    def delete(self, resource_id: UUID, api_key_id: UUID):
         """Delete an API key for a dataset"""
-        return super().delete(resource_id, api_key_id)
+        return super().delete(str(resource_id), str(api_key_id))
 
     resource_type = ApiTokenType.DATASET
     resource_model = Dataset

api/controllers/console/app/annotation.py

@@ -159,13 +159,15 @@ class AppAnnotationSettingUpdateApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self, app_id: UUID, annotation_setting_id):
-        annotation_setting_id = str(annotation_setting_id)
+    def post(self, app_id: UUID, annotation_setting_id: UUID):
+        annotation_setting_id_str = str(annotation_setting_id)
 
         args = AnnotationSettingUpdatePayload.model_validate(console_ns.payload)
 
         setting_args: UpdateAnnotationSettingArgs = {"score_threshold": args.score_threshold}
-        result = AppAnnotationService.update_app_annotation_setting(str(app_id), annotation_setting_id, setting_args)
+        result = AppAnnotationService.update_app_annotation_setting(
+            str(app_id), annotation_setting_id_str, setting_args
+        )
         return result, 200
 
 
@@ -181,9 +183,9 @@ class AnnotationReplyActionStatusApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
-    def get(self, app_id: UUID, job_id, action):
-        job_id = str(job_id)
-        app_annotation_job_key = f"{action}_app_annotation_job_{str(job_id)}"
+    def get(self, app_id: UUID, job_id: UUID, action: str):
+        job_id_str = str(job_id)
+        app_annotation_job_key = f"{action}_app_annotation_job_{job_id_str}"
         cache_result = redis_client.get(app_annotation_job_key)
         if cache_result is None:
             raise ValueError("The job does not exist.")
@@ -191,10 +193,10 @@ class AnnotationReplyActionStatusApi(Resource):
         job_status = cache_result.decode()
         error_msg = ""
         if job_status == "error":
-            app_annotation_error_key = f"{action}_app_annotation_error_{str(job_id)}"
+            app_annotation_error_key = f"{action}_app_annotation_error_{job_id_str}"
             error_msg = redis_client.get(app_annotation_error_key).decode()
 
-        return {"job_id": job_id, "job_status": job_status, "error_msg": error_msg}, 200
+        return {"job_id": job_id_str, "job_status": job_status, "error_msg": error_msg}, 200
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotations")
@@ -269,12 +271,12 @@ class AnnotationApi(Resource):
                     "message": "annotation_ids are required if the parameter is provided.",
                 }, 400
 
-            result = AppAnnotationService.delete_app_annotations_in_batch(str(app_id), annotation_ids)
-            return result, 204
+            AppAnnotationService.delete_app_annotations_in_batch(str(app_id), annotation_ids)
+            return "", 204
         # If no annotation_ids are provided, handle clearing all annotations
         else:
             AppAnnotationService.clear_all_annotations(str(app_id))
-            return {"result": "success"}, 204
+            return "", 204
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotations/export")
@@ -335,7 +337,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @edit_permission_required
     def delete(self, app_id: UUID, annotation_id: UUID):
         AppAnnotationService.delete_app_annotation(str(app_id), str(annotation_id))
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotations/batch-import")

api/controllers/console/app/app.py

@@ -16,7 +16,7 @@ from controllers.common.fields import RedirectUrlResponse, SimpleResultResponse
 from controllers.common.helpers import FileInfo
 from controllers.common.schema import register_enum_models, 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.app.wraps import get_app_model, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
 from controllers.console.wraps import (
     account_initialization_required,
@@ -26,7 +26,6 @@ from controllers.console.wraps import (
     is_admin_or_owner_required,
     setup_required,
 )
-from core.db.session_factory import session_factory
 from core.ops.ops_trace_manager import OpsTraceManager
 from core.rag.entities import PreProcessingRule, Rule, Segmentation
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
@@ -633,7 +632,7 @@ class AppApi(Resource):
         app_service = AppService()
         app_service.delete_app(app_model)
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/apps/<uuid:app_id>/copy")
@@ -852,11 +851,11 @@ class AppTraceApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_session
     @get_app_model
-    def get(self, app_model):
+    def get(self, session: Session, app_model: App):
         """Get app trace"""
-        with session_factory.create_session() as session:
-            app_trace_config = OpsTraceManager.get_app_tracing_config(app_model.id, session)
+        app_trace_config = OpsTraceManager.get_app_tracing_config(app_model.id, session)
 
         return app_trace_config
 

api/controllers/console/app/app_import.py

@@ -97,7 +97,7 @@ class AppImportConfirmApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self, import_id):
+    def post(self, import_id: str):
         # Check user role first
         current_user, _ = current_account_with_tenant()
 

api/controllers/console/app/completion.py

@@ -131,7 +131,7 @@ class CompletionMessageStopApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
-    def post(self, app_model, task_id):
+    def post(self, app_model, task_id: str):
         if not isinstance(current_user, Account):
             raise ValueError("current_user must be an Account instance")
 
@@ -212,7 +212,7 @@ class ChatMessageStopApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT])
-    def post(self, app_model, task_id):
+    def post(self, app_model, task_id: str):
         if not isinstance(current_user, Account):
             raise ValueError("current_user must be an Account instance")
 

api/controllers/console/app/conversation.py

@@ -1,4 +1,5 @@
 from typing import Literal
+from uuid import UUID
 
 import sqlalchemy as sa
 from flask import abort, request
@@ -29,9 +30,6 @@ from fields.conversation_fields import (
 from fields.conversation_fields import (
     ConversationWithSummaryPagination as ConversationWithSummaryPaginationResponse,
 )
-from fields.conversation_fields import (
-    ResultResponse,
-)
 from libs.datetime_utils import naive_utc_now, parse_time_range
 from libs.login import current_account_with_tenant, login_required
 from models import Conversation, EndUser, Message, MessageAnnotation
@@ -77,7 +75,6 @@ register_schema_models(
     ConversationMessageDetailResponse,
     ConversationWithSummaryPaginationResponse,
     ConversationDetailResponse,
-    ResultResponse,
     CompletionConversationQuery,
     ChatConversationQuery,
 )
@@ -137,7 +134,7 @@ class CompletionConversationApi(Resource):
                 .join(  # type: ignore
                     MessageAnnotation, MessageAnnotation.conversation_id == Conversation.id
                 )
-                .distinct()
+                .group_by(Conversation.id)
             )
         elif args.annotation_status == "not_annotated":
             query = (
@@ -168,10 +165,10 @@ class CompletionConversationDetailApi(Resource):
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
-    def get(self, app_model, conversation_id):
-        conversation_id = str(conversation_id)
+    def get(self, app_model, conversation_id: UUID):
+        conversation_id_str = str(conversation_id)
         return ConversationMessageDetailResponse.model_validate(
-            _get_conversation(app_model, conversation_id), from_attributes=True
+            _get_conversation(app_model, conversation_id_str), from_attributes=True
         ).model_dump(mode="json")
 
     @console_ns.doc("delete_completion_conversation")
@@ -185,16 +182,16 @@ class CompletionConversationDetailApi(Resource):
     @account_initialization_required
     @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
-    def delete(self, app_model, conversation_id):
+    def delete(self, app_model, conversation_id: UUID):
         current_user, _ = current_account_with_tenant()
-        conversation_id = str(conversation_id)
+        conversation_id_str = str(conversation_id)
 
         try:
-            ConversationService.delete(app_model, conversation_id, current_user)
+            ConversationService.delete(app_model, conversation_id_str, current_user)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
 
-        return ResultResponse(result="success").model_dump(mode="json"), 204
+        return "", 204
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-conversations")
@@ -275,7 +272,7 @@ class ChatConversationApi(Resource):
                     .join(  # type: ignore
                         MessageAnnotation, MessageAnnotation.conversation_id == Conversation.id
                     )
-                    .distinct()
+                    .group_by(Conversation.id)
                 )
             case "not_annotated":
                 query = (
@@ -321,10 +318,10 @@ 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, conversation_id):
-        conversation_id = str(conversation_id)
+    def get(self, app_model, conversation_id: UUID):
+        conversation_id_str = str(conversation_id)
         return ConversationDetailResponse.model_validate(
-            _get_conversation(app_model, conversation_id), from_attributes=True
+            _get_conversation(app_model, conversation_id_str), from_attributes=True
         ).model_dump(mode="json")
 
     @console_ns.doc("delete_chat_conversation")
@@ -338,16 +335,16 @@ 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, conversation_id):
+    def delete(self, app_model, conversation_id: UUID):
         current_user, _ = current_account_with_tenant()
-        conversation_id = str(conversation_id)
+        conversation_id_str = str(conversation_id)
 
         try:
-            ConversationService.delete(app_model, conversation_id, current_user)
+            ConversationService.delete(app_model, conversation_id_str, current_user)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
 
-        return ResultResponse(result="success").model_dump(mode="json"), 204
+        return "", 204
 
 
 def _get_conversation(app_model, conversation_id):

api/controllers/console/app/mcp_server.py

@@ -1,6 +1,7 @@
 import json
 from datetime import datetime
 from typing import Any
+from uuid import UUID
 
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
@@ -162,7 +163,7 @@ class AppMCPServerRefreshController(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def get(self, server_id):
+    def get(self, server_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
         server = db.session.scalar(
             select(AppMCPServer)

api/controllers/console/app/message.py

@@ -1,6 +1,7 @@
 import logging
 from datetime import datetime
 from typing import Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -336,13 +337,13 @@ 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, message_id):
+    def get(self, app_model, message_id: UUID):
         current_user, _ = current_account_with_tenant()
-        message_id = str(message_id)
+        message_id_str = str(message_id)
 
         try:
             questions = MessageService.get_suggested_questions_after_answer(
-                app_model=app_model, message_id=message_id, user=current_user, invoke_from=InvokeFrom.DEBUGGER
+                app_model=app_model, message_id=message_id_str, user=current_user, invoke_from=InvokeFrom.DEBUGGER
             )
         except MessageNotExistsError:
             raise NotFound("Message not found")
@@ -416,11 +417,11 @@ class MessageApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, app_model, message_id: str):
-        message_id = str(message_id)
+    def get(self, app_model, message_id: UUID):
+        message_id_str = str(message_id)
 
         message = db.session.scalar(
-            select(Message).where(Message.id == message_id, Message.app_id == app_model.id).limit(1)
+            select(Message).where(Message.id == message_id_str, Message.app_id == app_model.id).limit(1)
         )
 
         if not message:

api/controllers/console/app/ops_trace.py

@@ -128,6 +128,6 @@ class TraceAppConfigApi(Resource):
             result = OpsService.delete_tracing_app_config(app_id=app_model.id, tracing_provider=args.tracing_provider)
             if not result:
                 raise TracingConfigNotExist()
-            return {"result": "success"}, 204
+            return "", 204
         except Exception as e:
             raise BadRequest(str(e))

api/controllers/console/app/workflow_comment.py

@@ -311,7 +311,7 @@ class WorkflowCommentDetailApi(Resource):
             user_id=current_user.id,
         )
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/resolve")
@@ -431,7 +431,7 @@ class WorkflowCommentReplyDetailApi(Resource):
             user_id=current_user.id,
         )
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflow/comments/mention-users")

api/controllers/console/app/workflow_draft_variable.py

@@ -2,6 +2,7 @@ import logging
 from collections.abc import Callable
 from functools import wraps
 from typing import Any, TypedDict
+from uuid import UUID
 
 from flask import Response, request
 from flask_restx import Resource, fields, marshal, marshal_with
@@ -345,14 +346,15 @@ class VariableApi(Resource):
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
-    def get(self, app_model: App, variable_id: str):
+    def get(self, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
+        variable_id_str = str(variable_id)
         variable = _ensure_variable_access(
-            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
-            variable_id=variable_id,
+            variable_id=variable_id_str,
         )
         return variable
 
@@ -363,7 +365,7 @@ class VariableApi(Resource):
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
-    def patch(self, app_model: App, variable_id: str):
+    def patch(self, app_model: App, variable_id: UUID):
         # Request payload for file types:
         #
         # Local File:
@@ -390,10 +392,11 @@ class VariableApi(Resource):
         )
         args_model = WorkflowDraftVariableUpdatePayload.model_validate(console_ns.payload or {})
 
+        variable_id_str = str(variable_id)
         variable = _ensure_variable_access(
-            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
-            variable_id=variable_id,
+            variable_id=variable_id_str,
         )
 
         new_name = args_model.name
@@ -434,14 +437,15 @@ class VariableApi(Resource):
     @console_ns.response(204, "Variable deleted successfully")
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
-    def delete(self, app_model: App, variable_id: str):
+    def delete(self, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
+        variable_id_str = str(variable_id)
         variable = _ensure_variable_access(
-            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
-            variable_id=variable_id,
+            variable_id=variable_id_str,
         )
         draft_var_srv.delete_variable(variable)
         db.session.commit()
@@ -457,7 +461,7 @@ class VariableResetApi(Resource):
     @console_ns.response(204, "Variable reset (no content)")
     @console_ns.response(404, "Variable not found")
     @_api_prerequisite
-    def put(self, app_model: App, variable_id: str):
+    def put(self, app_model: App, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -468,10 +472,11 @@ class VariableResetApi(Resource):
             raise NotFoundError(
                 f"Draft workflow not found, app_id={app_model.id}",
             )
+        variable_id_str = str(variable_id)
         variable = _ensure_variable_access(
-            variable=draft_var_srv.get_variable(variable_id=variable_id),
+            variable=draft_var_srv.get_variable(variable_id=variable_id_str),
             app_id=app_model.id,
-            variable_id=variable_id,
+            variable_id=variable_id_str,
         )
 
         resetted = draft_var_srv.reset_variable(draft_workflow, variable)

api/controllers/console/app/workflow_run.py

@@ -1,5 +1,6 @@
 from datetime import UTC, datetime, timedelta
 from typing import Literal, cast
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -188,7 +189,7 @@ class WorkflowRunExportApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model()
-    def get(self, app_model: App, run_id: str):
+    def get(self, app_model: App, run_id: UUID):
         tenant_id = str(app_model.tenant_id)
         app_id = str(app_model.id)
         run_id_str = str(run_id)
@@ -367,14 +368,14 @@ class WorkflowRunDetailApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, run_id):
+    def get(self, app_model: App, run_id: UUID):
         """
         Get workflow run detail
         """
-        run_id = str(run_id)
+        run_id_str = str(run_id)
 
         workflow_run_service = WorkflowRunService()
-        workflow_run = workflow_run_service.get_workflow_run(app_model=app_model, run_id=run_id)
+        workflow_run = workflow_run_service.get_workflow_run(app_model=app_model, run_id=run_id_str)
         if workflow_run is None:
             raise NotFoundError("Workflow run not found")
 
@@ -396,17 +397,17 @@ class WorkflowRunNodeExecutionListApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, run_id):
+    def get(self, app_model: App, run_id: UUID):
         """
         Get workflow run node execution list
         """
-        run_id = str(run_id)
+        run_id_str = str(run_id)
 
         workflow_run_service = WorkflowRunService()
         user = cast("Account | EndUser", current_user)
         node_executions = workflow_run_service.get_workflow_run_node_executions(
             app_model=app_model,
-            run_id=run_id,
+            run_id=run_id_str,
             user=user,
         )
 

api/controllers/console/app/wraps.py

@@ -1,16 +1,38 @@
+"""Controller decorators for console app resources.
+
+`with_session` opens one SQLAlchemy session for a request handler and injects it
+as the first argument after `self`. Handlers use a transaction by default so
+migrated write paths keep commit/rollback handling; pure read handlers may opt
+out with `write=False`. App-loading decorators prefer that injected session when
+present, while still supporting existing handlers that have not been migrated
+yet and still rely on Flask-SQLAlchemy's scoped `db.session`.
+"""
+
 from collections.abc import Callable
 from functools import wraps
-from typing import overload
+from typing import Concatenate, cast, overload
 
 from sqlalchemy import select
+from sqlalchemy.orm import Session
 
 from controllers.console.app.error import AppNotFoundError
+from core.db.session_factory import session_factory
 from extensions.ext_database import db
 from libs.login import current_account_with_tenant
 from models import App, AppMode
 
 
-def _load_app_model(app_id: str) -> App | None:
+def _load_app_model(session: Session, app_id: str) -> App | None:
+    """Load the tenant-scoped app row with the request session owned by `with_session`."""
+    _, current_tenant_id = current_account_with_tenant()
+    app_model = session.scalar(
+        select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
+    )
+    return app_model
+
+
+def _load_app_model_from_scoped_session(app_id: str) -> App | None:
+    """Load the app row for legacy handlers that have not adopted request session injection yet."""
     _, current_tenant_id = current_account_with_tenant()
     app_model = db.session.scalar(
         select(App).where(App.id == app_id, App.tenant_id == current_tenant_id, App.status == "normal").limit(1)
@@ -23,6 +45,63 @@ def _load_app_model_with_trial(app_id: str) -> App | None:
     return app_model
 
 
+@overload
+def with_session[T, **P, R](
+    view: Callable[Concatenate[T, Session, P], R],
+    *,
+    write: bool = True,
+) -> Callable[Concatenate[T, P], R]: ...
+
+
+@overload
+def with_session[T, **P, R](
+    view: None = None,
+    *,
+    write: bool = True,
+) -> Callable[[Callable[Concatenate[T, Session, P], R]], Callable[Concatenate[T, P], R]]: ...
+
+
+def with_session[T, **P, R](
+    view: Callable[Concatenate[T, Session, P], R] | None = None,
+    *,
+    write: bool = True,
+) -> (
+    Callable[Concatenate[T, P], R] | Callable[[Callable[Concatenate[T, Session, P], R]], Callable[Concatenate[T, P], R]]
+):
+    """Inject a request-scoped session, using a transaction only for write handlers."""
+
+    def decorator(view: Callable[Concatenate[T, Session, P], R]) -> Callable[Concatenate[T, P], R]:
+        @wraps(view)
+        def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+            if write:
+                with session_factory.get_session_maker().begin() as session:
+                    return view(self, session, *args, **kwargs)
+
+            with session_factory.create_session() as session:
+                return view(self, session, *args, **kwargs)
+
+        return wrapper
+
+    if view is None:
+        return decorator
+    return decorator(view)
+
+
+def _get_injected_session(args: tuple[object, ...]) -> Session | None:
+    """Return the request session inserted by `with_session`, if this handler has been migrated."""
+    if len(args) < 2:
+        return None
+
+    candidate = args[1]
+    if isinstance(candidate, Session):
+        return candidate
+
+    if hasattr(candidate, "scalar") and hasattr(candidate, "commit") and hasattr(candidate, "rollback"):
+        return cast(Session, candidate)
+
+    return None
+
+
 @overload
 def get_app_model[**P, R](
     view: Callable[P, R],
@@ -44,6 +123,13 @@ def get_app_model[**P, R](
     *,
     mode: AppMode | list[AppMode] | None = None,
 ) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
+    """Inject the App model for handlers that receive an `app_id` path parameter.
+
+    New handlers may compose `@with_session` above this decorator so the app row
+    is loaded through the same request-scoped session used by the controller.
+    Existing handlers continue to work through `db.session` until migrated.
+    """
+
     def decorator(view_func: Callable[P, R]) -> Callable[P, R]:
         @wraps(view_func)
         def decorated_view(*args: P.args, **kwargs: P.kwargs) -> R:
@@ -55,7 +141,11 @@ def get_app_model[**P, R](
 
             del kwargs["app_id"]
 
-            app_model = _load_app_model(app_id)
+            session = _get_injected_session(args)
+            if session is None:
+                app_model = _load_app_model_from_scoped_session(app_id)
+            else:
+                app_model = _load_app_model(session, app_id)
 
             if not app_model:
                 raise AppNotFoundError()

api/controllers/console/auth/data_source_bearer_auth.py

@@ -1,3 +1,5 @@
+from uuid import UUID
+
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
@@ -87,10 +89,10 @@ class ApiKeyAuthDataSourceBindingDelete(Resource):
     @account_initialization_required
     @is_admin_or_owner_required
     @console_ns.response(204, "Binding deleted successfully")
-    def delete(self, binding_id):
+    def delete(self, binding_id: UUID):
         # The role of the current user in the table must be admin or owner
         _, current_tenant_id = current_account_with_tenant()
 
-        ApiKeyAuthService.delete_provider_auth(current_tenant_id, binding_id)
+        ApiKeyAuthService.delete_provider_auth(current_tenant_id, str(binding_id))
 
-        return {"result": "success"}, 204
+        return "", 204

api/controllers/console/auth/data_source_oauth.py

@@ -1,4 +1,5 @@
 import logging
+from uuid import UUID
 
 import httpx
 from flask import current_app, redirect, request
@@ -158,16 +159,15 @@ class OAuthDataSourceSync(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider, binding_id):
-        provider = str(provider)
-        binding_id = str(binding_id)
+    def get(self, provider: str, binding_id: UUID):
+        binding_id_str = str(binding_id)
         OAUTH_DATASOURCE_PROVIDERS = get_oauth_providers()
         with current_app.app_context():
             oauth_provider = OAUTH_DATASOURCE_PROVIDERS.get(provider)
         if not oauth_provider:
             return {"error": "Invalid provider"}, 400
         try:
-            oauth_provider.sync_data_source(binding_id)
+            oauth_provider.sync_data_source(binding_id_str)
         except httpx.HTTPStatusError as e:
             logger.exception(
                 "An error occurred during the OAuthCallback process with %s: %s", provider, e.response.text

api/controllers/console/datasets/data_source.py

@@ -1,6 +1,7 @@
 import json
 from collections.abc import Generator
 from typing import Any, Literal, cast
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource, fields, marshal_with
@@ -47,7 +48,6 @@ class NotionEstimatePayload(BaseModel):
 class DataSourceNotionListQuery(BaseModel):
     dataset_id: str | None = Field(default=None, description="Dataset ID")
     credential_id: str = Field(..., description="Credential ID", min_length=1)
-    datasource_parameters: dict[str, Any] | None = Field(default=None, description="Datasource parameters JSON string")
 
 
 class DataSourceNotionPreviewQuery(BaseModel):
@@ -204,9 +204,6 @@ class DataSourceNotionListApi(Resource):
 
         query = DataSourceNotionListQuery.model_validate(request.args.to_dict())
 
-        # Get datasource_parameters from query string (optional, for GitHub and other datasources)
-        datasource_parameters = query.datasource_parameters or {}
-
         datasource_provider_service = DatasourceProviderService()
         credential = datasource_provider_service.get_datasource_credentials(
             tenant_id=current_tenant_id,
@@ -254,7 +251,7 @@ class DataSourceNotionListApi(Resource):
             online_document_result: Generator[OnlineDocumentPagesMessage, None, None] = (
                 datasource_runtime.get_online_document_pages(
                     user_id=current_user.id,
-                    datasource_parameters=datasource_parameters,
+                    datasource_parameters={},
                     provider_type=datasource_runtime.datasource_provider_type(),
                 )
             )
@@ -293,7 +290,7 @@ class DataSourceNotionApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[TextContentResponse.__name__])
-    def get(self, page_id, page_type):
+    def get(self, page_id: UUID, page_type: str):
         _, current_tenant_id = current_account_with_tenant()
 
         query = DataSourceNotionPreviewQuery.model_validate(request.args.to_dict())
@@ -306,11 +303,11 @@ class DataSourceNotionApi(Resource):
             plugin_id="langgenius/notion_datasource",
         )
 
-        page_id = str(page_id)
+        page_id_str = str(page_id)
 
         extractor = NotionExtractor(
             notion_workspace_id="",
-            notion_obj_id=page_id,
+            notion_obj_id=page_id_str,
             notion_page_type=page_type,
             notion_access_token=credential.get("integration_secret"),
             tenant_id=current_tenant_id,
@@ -367,7 +364,7 @@ class DataSourceNotionDatasetSyncApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -385,7 +382,7 @@ class DataSourceNotionDocumentSyncApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def get(self, dataset_id, document_id):
+    def get(self, dataset_id: UUID, document_id: UUID):
         dataset_id_str = str(dataset_id)
         document_id_str = str(document_id)
         dataset = DatasetService.get_dataset(dataset_id_str)

api/controllers/console/datasets/datasets.py

@@ -1,15 +1,17 @@
-from typing import Any, cast
+from datetime import datetime
+from typing import Any
+from uuid import UUID
 
 from flask import request
-from flask_restx import Resource, fields, marshal, marshal_with
-from pydantic import BaseModel, Field, field_validator
+from flask_restx import Resource
+from pydantic import BaseModel, Field, field_validator, model_validator
 from sqlalchemy import func, select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
 from configs import dify_config
 from controllers.common.fields import ApiBaseUrlResponse, SimpleResultResponse, UsageCheckResponse
-from controllers.common.schema import get_or_create_model, register_response_schema_models, 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.apikey import ApiKeyItem, ApiKeyList
 from controllers.console.app.error import ProviderNotInitializeError
@@ -30,26 +32,10 @@ from core.rag.extractor.entity.extract_setting import ExtractSetting, NotionInfo
 from core.rag.index_processor.constant.index_type import IndexTechniqueType
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
 from extensions.ext_database import db
-from fields.app_fields import app_detail_kernel_fields, related_app_list
-from fields.dataset_fields import (
-    content_fields,
-    dataset_detail_fields,
-    dataset_fields,
-    dataset_query_detail_fields,
-    dataset_retrieval_model_fields,
-    doc_metadata_fields,
-    external_knowledge_info_fields,
-    external_retrieval_model_fields,
-    file_info_fields,
-    icon_info_fields,
-    keyword_setting_fields,
-    reranking_model_fields,
-    tag_fields,
-    vector_setting_fields,
-    weighted_score_fields,
-)
-from fields.document_fields import document_status_fields
+from fields.base import ResponseModel
+from fields.dataset_fields import DatasetDetailResponse
 from graphon.model_runtime.entities.model_entities import ModelType
+from libs.helper import build_icon_url, dump_response, to_timestamp
 from libs.login import current_account_with_tenant, login_required
 from libs.url_utils import normalize_api_base_url
 from models import ApiToken, Dataset, Document, DocumentSegment, UploadFile
@@ -61,58 +47,6 @@ from services.dataset_service import DatasetPermissionService, DatasetService, D
 
 register_response_schema_models(console_ns, ApiBaseUrlResponse, SimpleResultResponse, UsageCheckResponse)
 
-# Register models for flask_restx to avoid dict type issues in Swagger
-dataset_base_model = get_or_create_model("DatasetBase", dataset_fields)
-
-tag_model = get_or_create_model("Tag", tag_fields)
-
-keyword_setting_model = get_or_create_model("DatasetKeywordSetting", keyword_setting_fields)
-vector_setting_model = get_or_create_model("DatasetVectorSetting", vector_setting_fields)
-
-weighted_score_fields_copy = weighted_score_fields.copy()
-weighted_score_fields_copy["keyword_setting"] = fields.Nested(keyword_setting_model)
-weighted_score_fields_copy["vector_setting"] = fields.Nested(vector_setting_model)
-weighted_score_model = get_or_create_model("DatasetWeightedScore", weighted_score_fields_copy)
-
-reranking_model = get_or_create_model("DatasetRerankingModel", reranking_model_fields)
-
-dataset_retrieval_model_fields_copy = dataset_retrieval_model_fields.copy()
-dataset_retrieval_model_fields_copy["reranking_model"] = fields.Nested(reranking_model)
-dataset_retrieval_model_fields_copy["weights"] = fields.Nested(weighted_score_model, allow_null=True)
-dataset_retrieval_model = get_or_create_model("DatasetRetrievalModel", dataset_retrieval_model_fields_copy)
-
-external_knowledge_info_model = get_or_create_model("ExternalKnowledgeInfo", external_knowledge_info_fields)
-
-external_retrieval_model = get_or_create_model("ExternalRetrievalModel", external_retrieval_model_fields)
-
-doc_metadata_model = get_or_create_model("DatasetDocMetadata", doc_metadata_fields)
-
-icon_info_model = get_or_create_model("DatasetIconInfo", icon_info_fields)
-
-dataset_detail_fields_copy = dataset_detail_fields.copy()
-dataset_detail_fields_copy["retrieval_model_dict"] = fields.Nested(dataset_retrieval_model)
-dataset_detail_fields_copy["tags"] = fields.List(fields.Nested(tag_model))
-dataset_detail_fields_copy["external_knowledge_info"] = fields.Nested(external_knowledge_info_model)
-dataset_detail_fields_copy["external_retrieval_model"] = fields.Nested(external_retrieval_model, allow_null=True)
-dataset_detail_fields_copy["doc_metadata"] = fields.List(fields.Nested(doc_metadata_model))
-dataset_detail_fields_copy["icon_info"] = fields.Nested(icon_info_model)
-dataset_detail_model = get_or_create_model("DatasetDetail", dataset_detail_fields_copy)
-
-file_info_model = get_or_create_model("DatasetFileInfo", file_info_fields)
-
-content_fields_copy = content_fields.copy()
-content_fields_copy["file_info"] = fields.Nested(file_info_model, allow_null=True)
-content_model = get_or_create_model("DatasetContent", content_fields_copy)
-
-dataset_query_detail_fields_copy = dataset_query_detail_fields.copy()
-dataset_query_detail_fields_copy["queries"] = fields.Nested(content_model)
-dataset_query_detail_model = get_or_create_model("DatasetQueryDetail", dataset_query_detail_fields_copy)
-
-app_detail_kernel_model = get_or_create_model("AppDetailKernel", app_detail_kernel_fields)
-related_app_list_copy = related_app_list.copy()
-related_app_list_copy["data"] = fields.List(fields.Nested(app_detail_kernel_model))
-related_app_list_model = get_or_create_model("RelatedAppList", related_app_list_copy)
-
 
 def _validate_indexing_technique(value: str | None) -> str | None:
     if value is None:
@@ -208,9 +142,165 @@ class ConsoleDatasetListQuery(BaseModel):
     tag_ids: list[str] = Field(default_factory=list, description="Filter by tag IDs")
 
 
+class DatasetListItemResponse(DatasetDetailResponse):
+    partial_member_list: list[str]
+
+
+class DatasetListResponse(ResponseModel):
+    data: list[DatasetListItemResponse]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
+class DatasetDetailWithPartialMembersResponse(DatasetDetailResponse):
+    partial_member_list: list[str] | None = None
+
+
+class DatasetQueryFileInfoResponse(ResponseModel):
+    id: str
+    name: str
+    size: int
+    extension: str
+    mime_type: str
+    source_url: str
+
+
+class DatasetQueryContentResponse(ResponseModel):
+    content_type: str
+    content: str
+    file_info: DatasetQueryFileInfoResponse | None = None
+
+
+class DatasetQueryDetailResponse(ResponseModel):
+    id: str
+    queries: list[DatasetQueryContentResponse]
+    source: str
+    source_app_id: str | None
+    created_by_role: str
+    created_by: str
+    created_at: int
+
+    @field_validator("created_at", mode="before")
+    @classmethod
+    def _normalize_created_at(cls, value: datetime | int | None) -> int | None:
+        return to_timestamp(value)
+
+
+class DatasetQueryListResponse(ResponseModel):
+    data: list[DatasetQueryDetailResponse]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
+class RelatedAppResponse(ResponseModel):
+    id: str
+    name: str
+    description: str
+    mode: str = Field(validation_alias="mode_compatible_with_agent")
+    icon_type: str | None
+    icon: str | None
+    icon_background: str | None
+    icon_url: str | None = None
+
+    @model_validator(mode="after")
+    def _set_icon_url(self) -> "RelatedAppResponse":
+        self.icon_url = self.icon_url or build_icon_url(self.icon_type, self.icon)
+        return self
+
+
+class RelatedAppListResponse(ResponseModel):
+    data: list[RelatedAppResponse]
+    total: 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(
+        "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]
+
+
+class ErrorDocsResponse(DocumentStatusListResponse):
+    total: int
+
+
+class IndexingEstimatePreviewItemResponse(ResponseModel):
+    content: str
+    child_chunks: list[str] | None = None
+    summary: str | None = None
+
+
+class IndexingEstimateQaPreviewItemResponse(ResponseModel):
+    question: str
+    answer: str
+
+
+class IndexingEstimateResponse(ResponseModel):
+    total_segments: int
+    preview: list[IndexingEstimatePreviewItemResponse]
+    qa_preview: list[IndexingEstimateQaPreviewItemResponse] | None = None
+
+
+class RetrievalSettingResponse(ResponseModel):
+    retrieval_method: list[str]
+
+
+class PartialMemberListResponse(ResponseModel):
+    data: list[str]
+
+
+class AutoDisableLogsResponse(ResponseModel):
+    document_ids: list[str]
+    count: int
+
+
 register_schema_models(
     console_ns, DatasetCreatePayload, DatasetUpdatePayload, IndexingEstimatePayload, ConsoleDatasetListQuery
 )
+register_response_schema_models(
+    console_ns,
+    DatasetDetailResponse,
+    DatasetDetailWithPartialMembersResponse,
+    DatasetListResponse,
+    DatasetQueryListResponse,
+    IndexingEstimateResponse,
+    RelatedAppListResponse,
+    DocumentStatusListResponse,
+    ErrorDocsResponse,
+    RetrievalSettingResponse,
+    PartialMemberListResponse,
+    AutoDisableLogsResponse,
+)
 
 
 def _get_retrieval_methods_by_vector_type(vector_type: str | None, is_mock: bool = False) -> dict[str, list[str]]:
@@ -293,17 +383,8 @@ def _get_retrieval_methods_by_vector_type(vector_type: str | None, is_mock: bool
 class DatasetListApi(Resource):
     @console_ns.doc("get_datasets")
     @console_ns.doc(description="Get list of datasets")
-    @console_ns.doc(
-        params={
-            "page": "Page number (default: 1)",
-            "limit": "Number of items per page (default: 20)",
-            "ids": "Filter by dataset IDs (list)",
-            "keyword": "Search keyword",
-            "tag_ids": "Filter by tag IDs (list)",
-            "include_all": "Include all datasets (default: false)",
-        }
-    )
-    @console_ns.response(200, "Datasets retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(ConsoleDatasetListQuery))
+    @console_ns.response(200, "Datasets retrieved successfully", console_ns.models[DatasetListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -342,7 +423,7 @@ class DatasetListApi(Resource):
         for embedding_model in embedding_models:
             model_names.append(f"{embedding_model.model}:{embedding_model.provider.provider}")
 
-        data = cast(list[dict[str, Any]], marshal(datasets, dataset_detail_fields))
+        data = [dump_response(DatasetDetailResponse, dataset) for dataset in datasets]
         dataset_ids = [item["id"] for item in data if item.get("permission") == "partial_members"]
         partial_members_map: dict[str, list[str]] = {}
         if dataset_ids:
@@ -379,12 +460,12 @@ class DatasetListApi(Resource):
             "total": total,
             "page": query.page,
         }
-        return response, 200
+        return dump_response(DatasetListResponse, response), 200
 
     @console_ns.doc("create_dataset")
     @console_ns.doc(description="Create a new dataset")
     @console_ns.expect(console_ns.models[DatasetCreatePayload.__name__])
-    @console_ns.response(201, "Dataset created successfully")
+    @console_ns.response(201, "Dataset created successfully", console_ns.models[DatasetDetailResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -413,7 +494,7 @@ class DatasetListApi(Resource):
         except services.errors.dataset.DatasetNameDuplicateError:
             raise DatasetNameDuplicateError()
 
-        return marshal(dataset, dataset_detail_fields), 201
+        return dump_response(DatasetDetailResponse, dataset), 201
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>")
@@ -421,13 +502,17 @@ class DatasetApi(Resource):
     @console_ns.doc("get_dataset")
     @console_ns.doc(description="Get dataset details")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Dataset retrieved successfully", dataset_detail_model)
+    @console_ns.response(
+        200,
+        "Dataset retrieved successfully",
+        console_ns.models[DatasetDetailWithPartialMembersResponse.__name__],
+    )
     @console_ns.response(404, "Dataset not found")
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -437,7 +522,7 @@ class DatasetApi(Resource):
             DatasetService.check_dataset_permission(dataset, current_user)
         except services.errors.account.NoPermissionError as e:
             raise Forbidden(str(e))
-        data = cast(dict[str, Any], marshal(dataset, dataset_detail_fields))
+        data = dump_response(DatasetDetailResponse, dataset)
         if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
             if dataset.embedding_model_provider:
                 provider_id = ModelProviderID(dataset.embedding_model_provider)
@@ -470,14 +555,18 @@ class DatasetApi(Resource):
     @console_ns.doc("update_dataset")
     @console_ns.doc(description="Update dataset details")
     @console_ns.expect(console_ns.models[DatasetUpdatePayload.__name__])
-    @console_ns.response(200, "Dataset updated successfully", dataset_detail_model)
+    @console_ns.response(
+        200,
+        "Dataset updated successfully",
+        console_ns.models[DatasetDetailWithPartialMembersResponse.__name__],
+    )
     @console_ns.response(404, "Dataset not found")
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def patch(self, dataset_id):
+    def patch(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -506,7 +595,7 @@ class DatasetApi(Resource):
         if dataset is None:
             raise NotFound("Dataset not found.")
 
-        result_data = cast(dict[str, Any], marshal(dataset, dataset_detail_fields))
+        result_data = dump_response(DatasetDetailResponse, dataset)
         tenant_id = current_tenant_id
 
         if payload.partial_member_list is not None and payload.permission == DatasetPermissionEnum.PARTIAL_TEAM:
@@ -525,7 +614,7 @@ class DatasetApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Dataset deleted successfully")
-    def delete(self, dataset_id):
+    def delete(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         current_user, _ = current_account_with_tenant()
 
@@ -535,7 +624,7 @@ class DatasetApi(Resource):
         try:
             if DatasetService.delete_dataset(dataset_id_str, current_user):
                 DatasetPermissionService.clear_partial_member_list(dataset_id_str)
-                return {"result": "success"}, 204
+                return "", 204
             else:
                 raise NotFound("Dataset not found.")
         except services.errors.dataset.DatasetInUseError:
@@ -555,7 +644,7 @@ class DatasetUseCheckApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
 
         dataset_is_using = DatasetService.dataset_use_check(dataset_id_str)
@@ -567,11 +656,15 @@ class DatasetQueryApi(Resource):
     @console_ns.doc("get_dataset_queries")
     @console_ns.doc(description="Get dataset query history")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Query history retrieved successfully", dataset_query_detail_model)
+    @console_ns.response(
+        200,
+        "Query history retrieved successfully",
+        console_ns.models[DatasetQueryListResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -589,20 +682,24 @@ class DatasetQueryApi(Resource):
         dataset_queries, total = DatasetService.get_dataset_queries(dataset_id=dataset.id, page=page, per_page=limit)
 
         response = {
-            "data": marshal(dataset_queries, dataset_query_detail_model),
+            "data": dataset_queries,
             "has_more": len(dataset_queries) == limit,
             "limit": limit,
             "total": total,
             "page": page,
         }
-        return response, 200
+        return dump_response(DatasetQueryListResponse, response), 200
 
 
 @console_ns.route("/datasets/indexing-estimate")
 class DatasetIndexingEstimateApi(Resource):
     @console_ns.doc("estimate_dataset_indexing")
     @console_ns.doc(description="Estimate dataset indexing cost")
-    @console_ns.response(200, "Indexing estimate calculated successfully")
+    @console_ns.response(
+        200,
+        "Indexing estimate calculated successfully",
+        console_ns.models[IndexingEstimateResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -699,12 +796,15 @@ class DatasetRelatedAppListApi(Resource):
     @console_ns.doc("get_dataset_related_apps")
     @console_ns.doc(description="Get applications related to dataset")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Related apps retrieved successfully", related_app_list_model)
+    @console_ns.response(
+        200,
+        "Related apps retrieved successfully",
+        console_ns.models[RelatedAppListResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
-    @marshal_with(related_app_list_model)
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -724,7 +824,7 @@ class DatasetRelatedAppListApi(Resource):
             if app_model:
                 related_apps.append(app_model)
 
-        return {"data": related_apps, "total": len(related_apps)}, 200
+        return dump_response(RelatedAppListResponse, {"data": related_apps, "total": len(related_apps)}), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/indexing-status")
@@ -732,15 +832,19 @@ class DatasetIndexingStatusApi(Resource):
     @console_ns.doc("get_dataset_indexing_status")
     @console_ns.doc(description="Get dataset indexing status")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Indexing status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Indexing status retrieved successfully",
+        console_ns.models[DocumentStatusListResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
-        dataset_id = str(dataset_id)
+        dataset_id_str = str(dataset_id)
         documents = db.session.scalars(
-            select(Document).where(Document.dataset_id == dataset_id, Document.tenant_id == current_tenant_id)
+            select(Document).where(Document.dataset_id == dataset_id_str, Document.tenant_id == current_tenant_id)
         ).all()
         documents_status = []
         for document in documents:
@@ -778,9 +882,8 @@ class DatasetIndexingStatusApi(Resource):
                 "completed_segments": completed_segments,
                 "total_segments": total_segments,
             }
-            documents_status.append(marshal(document_dict, document_status_fields))
-        data = {"data": documents_status}
-        return data, 200
+            documents_status.append(document_dict)
+        return dump_response(DocumentStatusListResponse, {"data": documents_status}), 200
 
 
 @console_ns.route("/datasets/api-keys")
@@ -849,15 +952,15 @@ class DatasetApiDeleteApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def delete(self, api_key_id):
+    def delete(self, api_key_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
-        api_key_id = str(api_key_id)
+        api_key_id_str = str(api_key_id)
         key = db.session.scalar(
             select(ApiToken)
             .where(
                 ApiToken.tenant_id == current_tenant_id,
                 ApiToken.type == self.resource_type,
-                ApiToken.id == api_key_id,
+                ApiToken.id == api_key_id_str,
             )
             .limit(1)
         )
@@ -873,7 +976,7 @@ class DatasetApiDeleteApi(Resource):
         db.session.delete(key)
         db.session.commit()
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/api-keys/<string:status>")
@@ -882,7 +985,7 @@ class DatasetEnableApiApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self, dataset_id, status):
+    def post(self, dataset_id: UUID, status: str):
         dataset_id_str = str(dataset_id)
 
         DatasetService.update_dataset_api_status(dataset_id_str, status == "enable")
@@ -907,13 +1010,18 @@ class DatasetApiBaseUrlApi(Resource):
 class DatasetRetrievalSettingApi(Resource):
     @console_ns.doc("get_dataset_retrieval_setting")
     @console_ns.doc(description="Get dataset retrieval settings")
-    @console_ns.response(200, "Retrieval settings retrieved successfully")
+    @console_ns.response(
+        200, "Retrieval settings retrieved successfully", console_ns.models[RetrievalSettingResponse.__name__]
+    )
     @setup_required
     @login_required
     @account_initialization_required
     def get(self):
         vector_type = dify_config.VECTOR_STORE
-        return _get_retrieval_methods_by_vector_type(vector_type, is_mock=False)
+        return dump_response(
+            RetrievalSettingResponse,
+            _get_retrieval_methods_by_vector_type(vector_type, is_mock=False),
+        )
 
 
 @console_ns.route("/datasets/retrieval-setting/<string:vector_type>")
@@ -921,12 +1029,19 @@ class DatasetRetrievalSettingMockApi(Resource):
     @console_ns.doc("get_dataset_retrieval_setting_mock")
     @console_ns.doc(description="Get mock dataset retrieval settings by vector type")
     @console_ns.doc(params={"vector_type": "Vector store type"})
-    @console_ns.response(200, "Mock retrieval settings retrieved successfully")
+    @console_ns.response(
+        200,
+        "Mock retrieval settings retrieved successfully",
+        console_ns.models[RetrievalSettingResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, vector_type):
-        return _get_retrieval_methods_by_vector_type(vector_type, is_mock=True)
+    def get(self, vector_type: str):
+        return dump_response(
+            RetrievalSettingResponse,
+            _get_retrieval_methods_by_vector_type(vector_type, is_mock=True),
+        )
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/error-docs")
@@ -934,19 +1049,19 @@ class DatasetErrorDocs(Resource):
     @console_ns.doc("get_dataset_error_docs")
     @console_ns.doc(description="Get dataset error documents")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Error documents retrieved successfully")
+    @console_ns.response(200, "Error documents retrieved successfully", console_ns.models[ErrorDocsResponse.__name__])
     @console_ns.response(404, "Dataset not found")
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
         results = DocumentService.get_error_documents_by_dataset_id(dataset_id_str)
 
-        return {"data": [marshal(item, document_status_fields) for item in results], "total": len(results)}, 200
+        return dump_response(ErrorDocsResponse, {"data": results, "total": len(results)}), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/permission-part-users")
@@ -954,13 +1069,17 @@ class DatasetPermissionUserListApi(Resource):
     @console_ns.doc("get_dataset_permission_users")
     @console_ns.doc(description="Get dataset permission user list")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Permission users retrieved successfully")
+    @console_ns.response(
+        200,
+        "Permission users retrieved successfully",
+        console_ns.models[PartialMemberListResponse.__name__],
+    )
     @console_ns.response(404, "Dataset not found")
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -973,9 +1092,7 @@ class DatasetPermissionUserListApi(Resource):
 
         partial_members_list = DatasetPermissionService.get_dataset_partial_member_list(dataset_id_str)
 
-        return {
-            "data": partial_members_list,
-        }, 200
+        return dump_response(PartialMemberListResponse, {"data": partial_members_list}), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/auto-disable-logs")
@@ -983,14 +1100,18 @@ class DatasetAutoDisableLogApi(Resource):
     @console_ns.doc("get_dataset_auto_disable_logs")
     @console_ns.doc(description="Get dataset auto disable logs")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
-    @console_ns.response(200, "Auto disable logs retrieved successfully")
+    @console_ns.response(
+        200,
+        "Auto disable logs retrieved successfully",
+        console_ns.models[AutoDisableLogsResponse.__name__],
+    )
     @console_ns.response(404, "Dataset not found")
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
-        return DatasetService.get_dataset_auto_disable_logs(dataset_id_str), 200
+        return dump_response(AutoDisableLogsResponse, DatasetService.get_dataset_auto_disable_logs(dataset_id_str)), 200

api/controllers/console/datasets/datasets_document.py

@@ -5,6 +5,7 @@ from collections.abc import Sequence
 from contextlib import ExitStack
 from datetime import datetime
 from typing import Any, Literal, cast
+from uuid import UUID
 
 import sqlalchemy as sa
 from flask import request, send_file
@@ -315,9 +316,9 @@ class DatasetDocumentListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id):
+    def get(self, dataset_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
-        dataset_id = str(dataset_id)
+        dataset_id_str = str(dataset_id)
         raw_args = request.args.to_dict()
         param = DocumentDatasetListParam.model_validate(raw_args)
         page = param.page
@@ -342,7 +343,7 @@ class DatasetDocumentListApi(Resource):
                     )
         except (ArgumentTypeError, ValueError, Exception):
             fetch = False
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -351,7 +352,7 @@ class DatasetDocumentListApi(Resource):
         except services.errors.account.NoPermissionError as e:
             raise Forbidden(str(e))
 
-        query = select(Document).where(Document.dataset_id == str(dataset_id), Document.tenant_id == current_tenant_id)
+        query = select(Document).where(Document.dataset_id == dataset_id_str, Document.tenant_id == current_tenant_id)
 
         if status:
             query = DocumentService.apply_display_status_filter(query, status)
@@ -372,7 +373,7 @@ class DatasetDocumentListApi(Resource):
                     sa.select(
                         DocumentSegment.document_id, sa.func.sum(DocumentSegment.hit_count).label("total_hit_count")
                     )
-                    .where(DocumentSegment.dataset_id == str(dataset_id))
+                    .where(DocumentSegment.dataset_id == dataset_id_str)
                     .group_by(DocumentSegment.document_id)
                     .subquery()
                 )
@@ -444,11 +445,11 @@ class DatasetDocumentListApi(Resource):
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[KnowledgeConfig.__name__])
     @console_ns.response(200, "Documents created successfully", console_ns.models[DatasetAndDocumentResponse.__name__])
-    def post(self, dataset_id):
+    def post(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
-        dataset_id = str(dataset_id)
+        dataset_id_str = str(dataset_id)
 
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
 
         if not dataset:
             raise NotFound("Dataset not found.")
@@ -472,7 +473,7 @@ class DatasetDocumentListApi(Resource):
 
         try:
             documents, batch = DocumentService.save_document_with_dataset_id(dataset, knowledge_config, current_user)
-            dataset = DatasetService.get_dataset(dataset_id)
+            dataset = DatasetService.get_dataset(dataset_id_str)
 
         except ProviderTokenNotInitError as ex:
             raise ProviderNotInitializeError(ex.description)
@@ -490,9 +491,9 @@ class DatasetDocumentListApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Documents deleted successfully")
-    def delete(self, dataset_id):
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+    def delete(self, dataset_id: UUID):
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
         # check user's model setting
@@ -504,7 +505,7 @@ class DatasetDocumentListApi(Resource):
         except services.errors.document.DocumentIndexingError:
             raise DocumentIndexingError("Cannot delete document during indexing.")
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/init")
@@ -582,11 +583,11 @@ class DocumentIndexingEstimateApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id):
+    def get(self, dataset_id: UUID, document_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        document = self.get_document(dataset_id, document_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        document = self.get_document(dataset_id_str, document_id_str)
 
         if document.indexing_status in {IndexingStatus.COMPLETED, IndexingStatus.ERROR}:
             raise DocumentAlreadyFinishedError()
@@ -624,7 +625,7 @@ class DocumentIndexingEstimateApi(DocumentResource):
                         data_process_rule_dict,
                         document.doc_form,
                         "English",
-                        dataset_id,
+                        dataset_id_str,
                     )
                     return estimate_response.model_dump(), 200
                 except LLMBadRequestError:
@@ -647,11 +648,10 @@ class DocumentBatchIndexingEstimateApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, batch):
+    def get(self, dataset_id: UUID, batch: str):
         _, current_tenant_id = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        batch = str(batch)
-        documents = self.get_batch_documents(dataset_id, batch)
+        dataset_id_str = str(dataset_id)
+        documents = self.get_batch_documents(dataset_id_str, batch)
         if not documents:
             return {"tokens": 0, "total_price": 0, "currency": "USD", "total_segments": 0, "preview": []}, 200
         data_process_rule = documents[0].dataset_process_rule
@@ -725,7 +725,7 @@ class DocumentBatchIndexingEstimateApi(DocumentResource):
                     data_process_rule_dict,
                     document.doc_form,
                     "English",
-                    dataset_id,
+                    dataset_id_str,
                 )
                 return response.model_dump(), 200
             except LLMBadRequestError:
@@ -745,10 +745,9 @@ class DocumentBatchIndexingStatusApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, batch):
-        dataset_id = str(dataset_id)
-        batch = str(batch)
-        documents = self.get_batch_documents(dataset_id, batch)
+    def get(self, dataset_id: UUID, batch: str):
+        dataset_id_str = str(dataset_id)
+        documents = self.get_batch_documents(dataset_id_str, batch)
         documents_status = []
         for document in documents:
             completed_segments = (
@@ -800,16 +799,16 @@ class DocumentIndexingStatusApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id):
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        document = self.get_document(dataset_id, document_id)
+    def get(self, dataset_id: UUID, document_id: UUID):
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        document = self.get_document(dataset_id_str, document_id_str)
 
         completed_segments = (
             db.session.scalar(
                 select(func.count(DocumentSegment.id)).where(
                     DocumentSegment.completed_at.isnot(None),
-                    DocumentSegment.document_id == str(document_id),
+                    DocumentSegment.document_id == str(document_id_str),
                     DocumentSegment.status != SegmentStatus.RE_SEGMENT,
                 )
             )
@@ -818,7 +817,7 @@ class DocumentIndexingStatusApi(DocumentResource):
         total_segments = (
             db.session.scalar(
                 select(func.count(DocumentSegment.id)).where(
-                    DocumentSegment.document_id == str(document_id),
+                    DocumentSegment.document_id == str(document_id_str),
                     DocumentSegment.status != SegmentStatus.RE_SEGMENT,
                 )
             )
@@ -861,10 +860,10 @@ class DocumentApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id):
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        document = self.get_document(dataset_id, document_id)
+    def get(self, dataset_id: UUID, document_id: UUID):
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        document = self.get_document(dataset_id_str, document_id_str)
 
         metadata = request.args.get("metadata", "all")
         if metadata not in self.METADATA_CHOICES:
@@ -873,7 +872,7 @@ class DocumentApi(DocumentResource):
         if metadata == "only":
             response = {"id": document.id, "doc_type": document.doc_type, "doc_metadata": document.doc_metadata_details}
         elif metadata == "without":
-            dataset_process_rules = DatasetService.get_process_rules(dataset_id)
+            dataset_process_rules = DatasetService.get_process_rules(dataset_id_str)
             document_process_rules = document.dataset_process_rule.to_dict() if document.dataset_process_rule else {}
             response = {
                 "id": document.id,
@@ -907,7 +906,7 @@ class DocumentApi(DocumentResource):
                 "need_summary": document.need_summary if document.need_summary is not None else False,
             }
         else:
-            dataset_process_rules = DatasetService.get_process_rules(dataset_id)
+            dataset_process_rules = DatasetService.get_process_rules(dataset_id_str)
             document_process_rules = document.dataset_process_rule.to_dict() if document.dataset_process_rule else {}
             response = {
                 "id": document.id,
@@ -950,23 +949,23 @@ class DocumentApi(DocumentResource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Document deleted successfully")
-    def delete(self, dataset_id, document_id):
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+    def delete(self, dataset_id: UUID, document_id: UUID):
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
 
-        document = self.get_document(dataset_id, document_id)
+        document = self.get_document(dataset_id_str, document_id_str)
 
         try:
             DocumentService.delete_document(document)
         except services.errors.document.DocumentIndexingError:
             raise DocumentIndexingError("Cannot delete document during indexing.")
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/download")
@@ -980,7 +979,7 @@ class DocumentDownloadApi(DocumentResource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def get(self, dataset_id: str, document_id: str) -> dict[str, Any]:
+    def get(self, dataset_id: UUID, document_id: UUID) -> dict[str, Any]:
         # Reuse the shared permission/tenant checks implemented in DocumentResource.
         document = self.get_document(str(dataset_id), str(document_id))
         return {"url": DocumentService.get_document_download_url(document)}
@@ -997,16 +996,16 @@ class DocumentBatchDownloadZipApi(DocumentResource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[DocumentBatchDownloadZipPayload.__name__])
-    def post(self, dataset_id: str):
+    def post(self, dataset_id: UUID):
         """Stream a ZIP archive containing the requested uploaded documents."""
         # Parse and validate request payload.
         payload = DocumentBatchDownloadZipPayload.model_validate(console_ns.payload or {})
 
         current_user, current_tenant_id = current_account_with_tenant()
-        dataset_id = str(dataset_id)
+        dataset_id_str = str(dataset_id)
         document_ids: list[str] = [str(document_id) for document_id in payload.document_ids]
         upload_files, download_name = DocumentService.prepare_document_batch_download_zip(
-            dataset_id=dataset_id,
+            dataset_id=dataset_id_str,
             document_ids=document_ids,
             tenant_id=current_tenant_id,
             current_user=current_user,
@@ -1044,11 +1043,11 @@ class DocumentProcessingApi(DocumentResource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def patch(self, dataset_id, document_id, action: Literal["pause", "resume"]):
+    def patch(self, dataset_id: UUID, document_id: UUID, action: Literal["pause", "resume"]):
         current_user, _ = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        document = self.get_document(dataset_id, document_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        document = self.get_document(dataset_id_str, document_id_str)
 
         # The role of the current user in the ta table must be admin, owner, dataset_operator, or editor
         if not current_user.is_dataset_editor:
@@ -1092,11 +1091,11 @@ class DocumentMetadataApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def put(self, dataset_id, document_id):
+    def put(self, dataset_id: UUID, document_id: UUID):
         current_user, _ = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        document = self.get_document(dataset_id, document_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        document = self.get_document(dataset_id_str, document_id_str)
 
         req_data = DocumentMetadataUpdatePayload.model_validate(request.get_json() or {})
 
@@ -1141,10 +1140,10 @@ class DocumentStatusApi(DocumentResource):
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def patch(self, dataset_id, action: Literal["enable", "disable", "archive", "un_archive"]):
+    def patch(self, dataset_id: UUID, action: Literal["enable", "disable", "archive", "un_archive"]):
         current_user, _ = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
 
@@ -1179,16 +1178,16 @@ class DocumentPauseApi(DocumentResource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Document paused successfully")
-    def patch(self, dataset_id, document_id):
+    def patch(self, dataset_id: UUID, document_id: UUID):
         """pause document."""
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
 
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
 
-        document = DocumentService.get_document(dataset.id, document_id)
+        document = DocumentService.get_document(dataset.id, document_id_str)
 
         # 404 if document not found
         if document is None:
@@ -1204,7 +1203,7 @@ class DocumentPauseApi(DocumentResource):
         except services.errors.document.DocumentIndexingError:
             raise DocumentIndexingError("Cannot pause completed document.")
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/processing/resume")
@@ -1214,14 +1213,14 @@ class DocumentRecoverApi(DocumentResource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Document resumed successfully")
-    def patch(self, dataset_id, document_id):
+    def patch(self, dataset_id: UUID, document_id: UUID):
         """recover document."""
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
-        document = DocumentService.get_document(dataset.id, document_id)
+        document = DocumentService.get_document(dataset.id, document_id_str)
 
         # 404 if document not found
         if document is None:
@@ -1236,7 +1235,7 @@ class DocumentRecoverApi(DocumentResource):
         except services.errors.document.DocumentIndexingError:
             raise DocumentIndexingError("Document is not in paused status.")
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/retry")
@@ -1247,11 +1246,11 @@ class DocumentRetryApi(DocumentResource):
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[DocumentRetryPayload.__name__])
     @console_ns.response(204, "Documents retry started successfully")
-    def post(self, dataset_id):
+    def post(self, dataset_id: UUID):
         """retry document."""
         payload = DocumentRetryPayload.model_validate(console_ns.payload or {})
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         retry_documents = []
         if not dataset:
             raise NotFound("Dataset not found.")
@@ -1277,9 +1276,9 @@ class DocumentRetryApi(DocumentResource):
                 logger.exception("Failed to retry document, document id: %s", document_id)
                 continue
         # retry document
-        DocumentService.retry_document(dataset_id, retry_documents)
+        DocumentService.retry_document(dataset_id_str, retry_documents)
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/rename")
@@ -1289,7 +1288,7 @@ class DocumentRenameApi(DocumentResource):
     @account_initialization_required
     @console_ns.response(200, "Document renamed successfully", console_ns.models[DocumentResponse.__name__])
     @console_ns.expect(console_ns.models[DocumentRenamePayload.__name__])
-    def post(self, dataset_id, document_id):
+    def post(self, dataset_id: UUID, document_id: UUID):
         # The role of the current user in the ta table must be admin, owner, editor, or dataset_operator
         current_user, _ = current_account_with_tenant()
         if not current_user.is_dataset_editor:
@@ -1301,7 +1300,7 @@ class DocumentRenameApi(DocumentResource):
         payload = DocumentRenamePayload.model_validate(console_ns.payload or {})
 
         try:
-            document = DocumentService.rename_document(dataset_id, document_id, payload.name)
+            document = DocumentService.rename_document(str(dataset_id), str(document_id), payload.name)
         except services.errors.document.DocumentIndexingError:
             raise DocumentIndexingError("Cannot delete document during indexing.")
 
@@ -1314,15 +1313,15 @@ class WebsiteDocumentSyncApi(DocumentResource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def get(self, dataset_id, document_id):
+    def get(self, dataset_id: UUID, document_id: UUID):
         """sync website document."""
         _, current_tenant_id = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset.id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset.id, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         if document.tenant_id != current_tenant_id:
@@ -1333,7 +1332,7 @@ class WebsiteDocumentSyncApi(DocumentResource):
         if DocumentService.check_archived(document):
             raise ArchivedDocumentImmutableError()
         # sync document
-        DocumentService.sync_website_document(dataset_id, document)
+        DocumentService.sync_website_document(dataset_id_str, document)
 
         return {"result": "success"}, 200
 
@@ -1343,19 +1342,19 @@ class DocumentPipelineExecutionLogApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id):
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
+    def get(self, dataset_id: UUID, document_id: UUID):
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
 
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
-        document = DocumentService.get_document(dataset.id, document_id)
+        document = DocumentService.get_document(dataset.id, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         log = db.session.scalar(
             select(DocumentPipelineExecutionLog)
-            .where(DocumentPipelineExecutionLog.document_id == document_id)
+            .where(DocumentPipelineExecutionLog.document_id == document_id_str)
             .order_by(DocumentPipelineExecutionLog.created_at.desc())
             .limit(1)
         )
@@ -1392,7 +1391,7 @@ class DocumentGenerateSummaryApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def post(self, dataset_id):
+    def post(self, dataset_id: UUID):
         """
         Generate summary index for specified documents.
 
@@ -1401,10 +1400,10 @@ class DocumentGenerateSummaryApi(Resource):
         then asynchronously generates summary indexes for the provided documents.
         """
         current_user, _ = current_account_with_tenant()
-        dataset_id = str(dataset_id)
+        dataset_id_str = str(dataset_id)
 
         # Get dataset
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -1438,7 +1437,7 @@ class DocumentGenerateSummaryApi(Resource):
             raise ValueError("Summary index is not enabled for this dataset. Please enable it in the dataset settings.")
 
         # Verify all documents exist and belong to the dataset
-        documents = DocumentService.get_documents_by_ids(dataset_id, document_list)
+        documents = DocumentService.get_documents_by_ids(dataset_id_str, document_list)
 
         if len(documents) != len(document_list):
             found_ids = {doc.id for doc in documents}
@@ -1452,7 +1451,7 @@ class DocumentGenerateSummaryApi(Resource):
         if documents_to_update:
             document_ids_to_update = [str(doc.id) for doc in documents_to_update]
             DocumentService.update_documents_need_summary(
-                dataset_id=dataset_id,
+                dataset_id=dataset_id_str,
                 document_ids=document_ids_to_update,
                 need_summary=True,
             )
@@ -1465,11 +1464,11 @@ class DocumentGenerateSummaryApi(Resource):
                 continue
 
             # Dispatch async task
-            generate_summary_index_task.delay(dataset_id, document.id)
+            generate_summary_index_task.delay(dataset_id_str, document.id)
             logger.info(
                 "Dispatched summary generation task for document %s in dataset %s",
                 document.id,
-                dataset_id,
+                dataset_id_str,
             )
 
         return {"result": "success"}, 200
@@ -1485,7 +1484,7 @@ class DocumentSummaryStatusApi(DocumentResource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id):
+    def get(self, dataset_id: UUID, document_id: UUID):
         """
         Get summary index generation status for a document.
 
@@ -1499,11 +1498,11 @@ class DocumentSummaryStatusApi(DocumentResource):
         - summaries: List of summary records with status and content preview
         """
         current_user, _ = current_account_with_tenant()
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
 
         # Get dataset
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -1517,8 +1516,8 @@ class DocumentSummaryStatusApi(DocumentResource):
         from services.summary_index_service import SummaryIndexService
 
         result = SummaryIndexService.get_document_summary_status_detail(
-            document_id=document_id,
-            dataset_id=dataset_id,
+            document_id=document_id_str,
+            dataset_id=dataset_id_str,
         )
 
         return result, 200

api/controllers/console/datasets/datasets_segments.py

@@ -1,4 +1,6 @@
 import uuid
+from typing import Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource, marshal
@@ -113,12 +115,12 @@ class DatasetDocumentSegmentListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id):
+    def get(self, dataset_id: UUID, document_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
-        dataset_id = str(dataset_id)
-        document_id = str(document_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        document_id_str = str(document_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -127,7 +129,7 @@ class DatasetDocumentSegmentListApi(Resource):
         except services.errors.account.NoPermissionError as e:
             raise Forbidden(str(e))
 
-        document = DocumentService.get_document(dataset_id, document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
 
         if not document:
             raise NotFound("Document not found.")
@@ -148,7 +150,7 @@ class DatasetDocumentSegmentListApi(Resource):
         query = (
             select(DocumentSegment)
             .where(
-                DocumentSegment.document_id == str(document_id),
+                DocumentSegment.document_id == document_id_str,
                 DocumentSegment.tenant_id == current_tenant_id,
             )
             .order_by(DocumentSegment.position.asc())
@@ -201,7 +203,9 @@ class DatasetDocumentSegmentListApi(Resource):
         if segment_ids:
             from services.summary_index_service import SummaryIndexService
 
-            summary_records = SummaryIndexService.get_segments_summaries(segment_ids=segment_ids, dataset_id=dataset_id)
+            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()}
 
@@ -226,19 +230,19 @@ class DatasetDocumentSegmentListApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Segments deleted successfully")
-    def delete(self, dataset_id, document_id):
+    def delete(self, dataset_id: UUID, document_id: UUID):
         current_user, _ = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         segment_ids = request.args.getlist("segment_id")
@@ -251,7 +255,7 @@ class DatasetDocumentSegmentListApi(Resource):
         except services.errors.account.NoPermissionError as e:
             raise Forbidden(str(e))
         SegmentService.delete_segments(segment_ids, document, dataset)
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segment/<string:action>")
@@ -262,15 +266,15 @@ class DatasetDocumentSegmentApi(Resource):
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def patch(self, dataset_id, document_id, action):
+    def patch(self, dataset_id: UUID, document_id: UUID, action: Literal["enable", "disable"]):
         current_user, current_tenant_id = current_account_with_tenant()
 
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         # check user's model setting
@@ -321,17 +325,17 @@ 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__])
-    def post(self, dataset_id, document_id):
+    def post(self, dataset_id: UUID, document_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         if not current_user.is_dataset_editor:
@@ -361,7 +365,7 @@ class DatasetDocumentSegmentAddApi(Resource):
         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), "doc_form": document.doc_form}, 200
+        return {"data": _get_segment_with_summary(segment, dataset_id_str), "doc_form": document.doc_form}, 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>")
@@ -372,19 +376,19 @@ class DatasetDocumentSegmentUpdateApi(Resource):
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[SegmentUpdatePayload.__name__])
-    def patch(self, dataset_id, document_id, segment_id):
+    def patch(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
@@ -404,10 +408,10 @@ class DatasetDocumentSegmentUpdateApi(Resource):
             except ProviderTokenNotInitError as ex:
                 raise ProviderNotInitializeError(ex.description)
             # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
@@ -428,33 +432,33 @@ 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), "doc_form": document.doc_form}, 200
+        return {"data": _get_segment_with_summary(segment, dataset_id_str), "doc_form": document.doc_form}, 200
 
     @setup_required
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Segment deleted successfully")
-    def delete(self, dataset_id, document_id, segment_id):
+    def delete(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
@@ -467,7 +471,7 @@ class DatasetDocumentSegmentUpdateApi(Resource):
         except services.errors.account.NoPermissionError as e:
             raise Forbidden(str(e))
         SegmentService.delete_segment(segment, document, dataset)
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route(
@@ -483,17 +487,17 @@ class DatasetDocumentSegmentBatchImportApi(Resource):
     @cloud_edition_billing_knowledge_limit_check("add_segment")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[BatchImportPayload.__name__])
-    def post(self, dataset_id, document_id):
+    def post(self, dataset_id: UUID, document_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
 
@@ -517,8 +521,8 @@ class DatasetDocumentSegmentBatchImportApi(Resource):
             batch_create_segment_to_index_task.delay(
                 str(job_id),
                 upload_file_id,
-                dataset_id,
-                document_id,
+                dataset_id_str,
+                document_id_str,
                 current_tenant_id,
                 current_user.id,
             )
@@ -530,7 +534,7 @@ class DatasetDocumentSegmentBatchImportApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, job_id=None, dataset_id=None, document_id=None):
+    def get(self, job_id=None, dataset_id: UUID | None = None, document_id: UUID | None = None):
         if job_id is None:
             raise NotFound("The job does not exist.")
         job_id = str(job_id)
@@ -551,24 +555,24 @@ 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__])
-    def post(self, dataset_id, document_id, segment_id):
+    def post(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
@@ -606,26 +610,26 @@ class ChildChunkAddApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id, document_id, segment_id):
+    def get(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
@@ -642,7 +646,9 @@ class ChildChunkAddApi(Resource):
         limit = min(args.limit, 100)
         keyword = args.keyword
 
-        child_chunks = SegmentService.get_child_chunks(segment_id, document_id, dataset_id, page, limit, keyword)
+        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),
             "total": child_chunks.total,
@@ -656,26 +662,26 @@ class ChildChunkAddApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def patch(self, dataset_id, document_id, segment_id):
+    def patch(self, dataset_id: UUID, document_id: UUID, segment_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
             # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
@@ -705,39 +711,39 @@ class ChildChunkUpdateApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.response(204, "Child chunk deleted successfully")
-    def delete(self, dataset_id, document_id, segment_id, child_chunk_id):
+    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()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
         # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
             raise NotFound("Segment not found.")
         # check child chunk
-        child_chunk_id = str(child_chunk_id)
+        child_chunk_id_str = str(child_chunk_id)
         child_chunk = db.session.scalar(
             select(ChildChunk)
             .where(
-                ChildChunk.id == str(child_chunk_id),
+                ChildChunk.id == str(child_chunk_id_str),
                 ChildChunk.tenant_id == current_tenant_id,
                 ChildChunk.segment_id == segment.id,
-                ChildChunk.document_id == document_id,
+                ChildChunk.document_id == document_id_str,
             )
             .limit(1)
         )
@@ -754,7 +760,7 @@ class ChildChunkUpdateApi(Resource):
             SegmentService.delete_child_chunk(child_chunk, dataset)
         except ChildChunkDeleteIndexServiceError as e:
             raise ChildChunkDeleteIndexError(str(e))
-        return {"result": "success"}, 204
+        return "", 204
 
     @setup_required
     @login_required
@@ -762,39 +768,39 @@ class ChildChunkUpdateApi(Resource):
     @cloud_edition_billing_resource_check("vector_space")
     @cloud_edition_billing_rate_limit_check("knowledge")
     @console_ns.expect(console_ns.models[ChildChunkUpdatePayload.__name__])
-    def patch(self, dataset_id, document_id, segment_id, child_chunk_id):
+    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()
 
         # check dataset
-        dataset_id = str(dataset_id)
-        dataset = DatasetService.get_dataset(dataset_id)
+        dataset_id_str = str(dataset_id)
+        dataset = DatasetService.get_dataset(dataset_id_str)
         if not dataset:
             raise NotFound("Dataset not found.")
         # check user's model setting
         DatasetService.check_dataset_model_setting(dataset)
         # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset_id, document_id)
+        document_id_str = str(document_id)
+        document = DocumentService.get_document(dataset_id_str, document_id_str)
         if not document:
             raise NotFound("Document not found.")
             # check segment
-        segment_id = str(segment_id)
+        segment_id_str = str(segment_id)
         segment = db.session.scalar(
             select(DocumentSegment)
-            .where(DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_tenant_id)
+            .where(DocumentSegment.id == segment_id_str, DocumentSegment.tenant_id == current_tenant_id)
             .limit(1)
         )
         if not segment:
             raise NotFound("Segment not found.")
         # check child chunk
-        child_chunk_id = str(child_chunk_id)
+        child_chunk_id_str = str(child_chunk_id)
         child_chunk = db.session.scalar(
             select(ChildChunk)
             .where(
-                ChildChunk.id == str(child_chunk_id),
+                ChildChunk.id == str(child_chunk_id_str),
                 ChildChunk.tenant_id == current_tenant_id,
                 ChildChunk.segment_id == segment.id,
-                ChildChunk.document_id == document_id,
+                ChildChunk.document_id == document_id_str,
             )
             .limit(1)
         )

api/controllers/console/datasets/external.py

@@ -1,3 +1,5 @@
+from uuid import UUID
+
 from flask import request
 from flask_restx import Resource, fields, marshal
 from pydantic import BaseModel, Field
@@ -8,7 +10,12 @@ from controllers.common.fields import UsageCountResponse
 from controllers.common.schema import get_or_create_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.datasets.error import DatasetNameDuplicateError
-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_tenant_id,
+)
 from fields.dataset_fields import (
     dataset_detail_fields,
     dataset_retrieval_model_fields,
@@ -124,9 +131,9 @@ class ExternalApiTemplateListApi(Resource):
     @console_ns.response(200, "External API templates retrieved successfully")
     @setup_required
     @login_required
+    @with_current_tenant_id
     @account_initialization_required
-    def get(self):
-        _, current_tenant_id = current_account_with_tenant()
+    def get(self, current_tenant_id: str):
         query = ExternalApiTemplateListQuery.model_validate(request.args.to_dict())
 
         external_knowledge_apis, total = ExternalDatasetService.get_external_knowledge_apis(
@@ -175,11 +182,11 @@ class ExternalApiTemplateApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, external_knowledge_api_id):
+    def get(self, external_knowledge_api_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
-        external_knowledge_api_id = str(external_knowledge_api_id)
+        external_knowledge_api_id_str = str(external_knowledge_api_id)
         external_knowledge_api = ExternalDatasetService.get_external_knowledge_api(
-            external_knowledge_api_id, current_tenant_id
+            external_knowledge_api_id_str, current_tenant_id
         )
         if external_knowledge_api is None:
             raise NotFound("API template not found.")
@@ -190,9 +197,9 @@ class ExternalApiTemplateApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.expect(console_ns.models[ExternalKnowledgeApiPayload.__name__])
-    def patch(self, external_knowledge_api_id):
+    def patch(self, external_knowledge_api_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
-        external_knowledge_api_id = str(external_knowledge_api_id)
+        external_knowledge_api_id_str = str(external_knowledge_api_id)
 
         payload = ExternalKnowledgeApiPayload.model_validate(console_ns.payload or {})
         ExternalDatasetService.validate_api_list(payload.settings)
@@ -200,7 +207,7 @@ class ExternalApiTemplateApi(Resource):
         external_knowledge_api = ExternalDatasetService.update_external_knowledge_api(
             tenant_id=current_tenant_id,
             user_id=current_user.id,
-            external_knowledge_api_id=external_knowledge_api_id,
+            external_knowledge_api_id=external_knowledge_api_id_str,
             args=payload.model_dump(),
         )
 
@@ -210,15 +217,15 @@ class ExternalApiTemplateApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(204, "External knowledge API deleted successfully")
-    def delete(self, external_knowledge_api_id):
+    def delete(self, external_knowledge_api_id: UUID):
         current_user, current_tenant_id = current_account_with_tenant()
-        external_knowledge_api_id = str(external_knowledge_api_id)
+        external_knowledge_api_id_str = str(external_knowledge_api_id)
 
         if not (current_user.has_edit_permission or current_user.is_dataset_operator):
             raise Forbidden()
 
-        ExternalDatasetService.delete_external_knowledge_api(current_tenant_id, external_knowledge_api_id)
-        return {"result": "success"}, 204
+        ExternalDatasetService.delete_external_knowledge_api(current_tenant_id, external_knowledge_api_id_str)
+        return "", 204
 
 
 @console_ns.route("/datasets/external-knowledge-api/<uuid:external_knowledge_api_id>/use-check")
@@ -230,12 +237,12 @@ class ExternalApiUseCheckApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, external_knowledge_api_id):
+    def get(self, external_knowledge_api_id: UUID):
         _, current_tenant_id = current_account_with_tenant()
-        external_knowledge_api_id = str(external_knowledge_api_id)
+        external_knowledge_api_id_str = str(external_knowledge_api_id)
 
         external_knowledge_api_is_using, count = ExternalDatasetService.external_knowledge_api_use_check(
-            external_knowledge_api_id, current_tenant_id
+            external_knowledge_api_id_str, current_tenant_id
         )
         return {"is_using": external_knowledge_api_is_using, "count": count}, 200
 
@@ -286,7 +293,7 @@ class ExternalKnowledgeHitTestingApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, dataset_id):
+    def post(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)

api/controllers/console/datasets/hit_testing.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from datetime import datetime
 from typing import Any
+from uuid import UUID
 
 from flask_restx import Resource
 from pydantic import Field, field_validator
@@ -118,7 +119,7 @@ class HitTestingApi(Resource, DatasetsHitTestingBase):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def post(self, dataset_id):
+    def post(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
 
         dataset = self.get_and_validate_dataset(dataset_id_str)

api/controllers/console/datasets/metadata.py

@@ -1,14 +1,19 @@
 from typing import Literal
+from uuid import UUID
 
-from flask_restx import Resource, marshal_with
+from flask_restx import Resource
 from werkzeug.exceptions import NotFound
 
 from controllers.common.controller_schemas import MetadataUpdatePayload
-from controllers.common.fields import SimpleResultResponse
 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 fields.dataset_fields import dataset_metadata_fields
+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 services.dataset_service import DatasetService
 from services.entities.knowledge_entities.knowledge_entities import (
@@ -22,7 +27,12 @@ from services.metadata_service import MetadataService
 register_schema_models(
     console_ns, MetadataArgs, MetadataOperationData, MetadataUpdatePayload, DocumentMetadataOperation, MetadataDetail
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    DatasetMetadataBuiltInFieldsResponse,
+    DatasetMetadataListResponse,
+    DatasetMetadataResponse,
+)
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/metadata")
@@ -31,9 +41,9 @@ class DatasetMetadataCreateApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    @marshal_with(dataset_metadata_fields)
+    @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):
+    def post(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
         metadata_args = MetadataArgs.model_validate(console_ns.payload or {})
 
@@ -44,18 +54,22 @@ class DatasetMetadataCreateApi(Resource):
         DatasetService.check_dataset_permission(dataset, current_user)
 
         metadata = MetadataService.create_metadata(dataset_id_str, metadata_args)
-        return metadata, 201
+        return dump_response(DatasetMetadataResponse, metadata), 201
 
     @setup_required
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def get(self, dataset_id):
+    @console_ns.response(
+        200, "Metadata retrieved successfully", console_ns.models[DatasetMetadataListResponse.__name__]
+    )
+    def get(self, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
             raise NotFound("Dataset not found.")
-        return MetadataService.get_dataset_metadatas(dataset), 200
+        metadata = MetadataService.get_dataset_metadatas(dataset)
+        return dump_response(DatasetMetadataListResponse, metadata), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/metadata/<uuid:metadata_id>")
@@ -64,9 +78,9 @@ class DatasetMetadataApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    @marshal_with(dataset_metadata_fields)
+    @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, metadata_id):
+    def patch(self, dataset_id: UUID, metadata_id: UUID):
         current_user, _ = current_account_with_tenant()
         payload = MetadataUpdatePayload.model_validate(console_ns.payload or {})
         name = payload.name
@@ -79,14 +93,14 @@ class DatasetMetadataApi(Resource):
         DatasetService.check_dataset_permission(dataset, current_user)
 
         metadata = MetadataService.update_metadata_name(dataset_id_str, metadata_id_str, name)
-        return metadata, 200
+        return dump_response(DatasetMetadataResponse, metadata), 200
 
     @setup_required
     @login_required
     @account_initialization_required
     @enterprise_license_required
     @console_ns.response(204, "Metadata deleted successfully")
-    def delete(self, dataset_id, metadata_id):
+    def delete(self, dataset_id: UUID, metadata_id: UUID):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         metadata_id_str = str(metadata_id)
@@ -96,7 +110,8 @@ class DatasetMetadataApi(Resource):
         DatasetService.check_dataset_permission(dataset, current_user)
 
         MetadataService.delete_metadata(dataset_id_str, metadata_id_str)
-        return {"result": "success"}, 204
+        # Frontend callers only await success and invalidate metadata caches; no response body is consumed.
+        return "", 204
 
 
 @console_ns.route("/datasets/metadata/built-in")
@@ -105,9 +120,14 @@ class DatasetMetadataBuiltInFieldApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
+    @console_ns.response(
+        200,
+        "Built-in fields retrieved successfully",
+        console_ns.models[DatasetMetadataBuiltInFieldsResponse.__name__],
+    )
     def get(self):
         built_in_fields = MetadataService.get_built_in_fields()
-        return {"fields": built_in_fields}, 200
+        return dump_response(DatasetMetadataBuiltInFieldsResponse, {"fields": built_in_fields}), 200
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/metadata/built-in/<string:action>")
@@ -116,8 +136,8 @@ class DatasetMetadataBuiltInFieldActionApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self, dataset_id, action: Literal["enable", "disable"]):
+    @console_ns.response(204, "Action completed successfully")
+    def post(self, dataset_id: UUID, action: Literal["enable", "disable"]):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -130,7 +150,8 @@ class DatasetMetadataBuiltInFieldActionApi(Resource):
                 MetadataService.enable_built_in_field(dataset)
             case "disable":
                 MetadataService.disable_built_in_field(dataset)
-        return {"result": "success"}, 200
+        # Frontend callers only await success and invalidate metadata caches; no response body is consumed.
+        return "", 204
 
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/metadata")
@@ -140,8 +161,11 @@ class DocumentMetadataEditApi(Resource):
     @account_initialization_required
     @enterprise_license_required
     @console_ns.expect(console_ns.models[MetadataOperationData.__name__])
-    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self, dataset_id):
+    @console_ns.response(
+        204,
+        "Documents metadata updated successfully",
+    )
+    def post(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
@@ -153,4 +177,5 @@ class DocumentMetadataEditApi(Resource):
 
         MetadataService.update_documents_metadata(dataset, metadata_args)
 
-        return {"result": "success"}, 200
+        # Frontend callers only await success and invalidate caches; no response body is consumed.
+        return "", 204

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

@@ -1,6 +1,6 @@
 from flask_restx import Resource, marshal
 from pydantic import BaseModel
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session
 from werkzeug.exceptions import Forbidden
 
 import services
@@ -54,12 +54,13 @@ class CreateRagPipelineDatasetApi(Resource):
             yaml_content=payload.yaml_content,
         )
         try:
-            with sessionmaker(db.engine).begin() as session:
+            with Session(db.engine, expire_on_commit=False) as session:
                 rag_pipeline_dsl_service = RagPipelineDslService(session)
                 import_info = rag_pipeline_dsl_service.create_rag_pipeline_dataset(
                     tenant_id=current_tenant_id,
                     rag_pipeline_dataset_create_entity=rag_pipeline_dataset_create_entity,
                 )
+                session.commit()
             if rag_pipeline_dataset_create_entity.permission == "partial_members":
                 DatasetPermissionService.update_partial_member_list(
                     current_tenant_id,

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

@@ -1,6 +1,7 @@
 import logging
 from collections.abc import Callable
 from typing import Any, NoReturn
+from uuid import UUID
 
 from flask import Response, request
 from flask_restx import Resource, marshal, marshal_with
@@ -168,21 +169,22 @@ class RagPipelineVariableApi(Resource):
 
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
-    def get(self, pipeline: Pipeline, variable_id: str):
+    def get(self, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
-        variable = draft_var_srv.get_variable(variable_id=variable_id)
+        variable_id_str = str(variable_id)
+        variable = draft_var_srv.get_variable(variable_id=variable_id_str)
         if variable is None:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         if variable.app_id != pipeline.id:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         return variable
 
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
     @console_ns.expect(console_ns.models[WorkflowDraftVariablePatchPayload.__name__])
-    def patch(self, pipeline: Pipeline, variable_id: str):
+    def patch(self, pipeline: Pipeline, variable_id: UUID):
         # Request payload for file types:
         #
         # Local File:
@@ -210,11 +212,12 @@ class RagPipelineVariableApi(Resource):
         payload = WorkflowDraftVariablePatchPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
 
-        variable = draft_var_srv.get_variable(variable_id=variable_id)
+        variable_id_str = str(variable_id)
+        variable = draft_var_srv.get_variable(variable_id=variable_id_str)
         if variable is None:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         if variable.app_id != pipeline.id:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
 
         new_name = args.get(self._PATCH_NAME_FIELD, None)
         raw_value = args.get(self._PATCH_VALUE_FIELD, None)
@@ -250,15 +253,16 @@ class RagPipelineVariableApi(Resource):
         return variable
 
     @_api_prerequisite
-    def delete(self, pipeline: Pipeline, variable_id: str):
+    def delete(self, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
-        variable = draft_var_srv.get_variable(variable_id=variable_id)
+        variable_id_str = str(variable_id)
+        variable = draft_var_srv.get_variable(variable_id=variable_id_str)
         if variable is None:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         if variable.app_id != pipeline.id:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         draft_var_srv.delete_variable(variable)
         db.session.commit()
         return Response("", 204)
@@ -267,7 +271,7 @@ class RagPipelineVariableApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/variables/<uuid:variable_id>/reset")
 class RagPipelineVariableResetApi(Resource):
     @_api_prerequisite
-    def put(self, pipeline: Pipeline, variable_id: str):
+    def put(self, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
             session=db.session(),
         )
@@ -278,11 +282,12 @@ class RagPipelineVariableResetApi(Resource):
             raise NotFoundError(
                 f"Draft workflow not found, pipeline_id={pipeline.id}",
             )
-        variable = draft_var_srv.get_variable(variable_id=variable_id)
+        variable_id_str = str(variable_id)
+        variable = draft_var_srv.get_variable(variable_id=variable_id_str)
         if variable is None:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         if variable.app_id != pipeline.id:
-            raise NotFoundError(description=f"variable not found, id={variable_id}")
+            raise NotFoundError(description=f"variable not found, id={variable_id_str}")
 
         resetted = draft_var_srv.reset_variable(draft_workflow, variable)
         db.session.commit()

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

@@ -1,7 +1,7 @@
 from flask import request
 from flask_restx import Resource, fields, marshal_with  # type: ignore
 from pydantic import BaseModel, Field
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session
 
 from controllers.common.schema import get_or_create_model, register_schema_models
 from controllers.console import console_ns
@@ -67,10 +67,12 @@ class RagPipelineImportApi(Resource):
         current_user, _ = current_account_with_tenant()
         payload = RagPipelineImportPayload.model_validate(console_ns.payload or {})
 
-        # Create service with session
-        with sessionmaker(db.engine).begin() as session:
+        # Use a plain Session so that caught exceptions inside the service
+        # (which return FAILED status instead of re-raising) do not leave the
+        # transaction in a closed state that a .begin() context manager cannot
+        # handle.  See app_import.py for the canonical pattern.
+        with Session(db.engine, expire_on_commit=False) as session:
             import_service = RagPipelineDslService(session)
-            # Import app
             account = current_user
             result = import_service.import_rag_pipeline(
                 account=account,
@@ -80,6 +82,10 @@ class RagPipelineImportApi(Resource):
                 pipeline_id=payload.pipeline_id,
                 dataset_name=payload.name,
             )
+            if result.status == ImportStatus.FAILED:
+                session.rollback()
+            else:
+                session.commit()
 
         # Return appropriate status code based on result
         status = result.status
@@ -99,15 +105,17 @@ class RagPipelineImportConfirmApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @marshal_with(pipeline_import_model)
-    def post(self, import_id):
+    def post(self, import_id: str):
         current_user, _ = current_account_with_tenant()
 
-        # Create service with session
-        with sessionmaker(db.engine).begin() as session:
+        with Session(db.engine, expire_on_commit=False) as session:
             import_service = RagPipelineDslService(session)
-            # Confirm import
             account = current_user
             result = import_service.confirm_import(import_id=import_id, account=account)
+            if result.status == ImportStatus.FAILED:
+                session.rollback()
+            else:
+                session.commit()
 
         # Return appropriate status code based on result
         if result.status == ImportStatus.FAILED:
@@ -124,7 +132,7 @@ class RagPipelineImportCheckDependenciesApi(Resource):
     @edit_permission_required
     @marshal_with(pipeline_import_check_dependencies_model)
     def get(self, pipeline: Pipeline):
-        with sessionmaker(db.engine).begin() as session:
+        with Session(db.engine, expire_on_commit=False) as session:
             import_service = RagPipelineDslService(session)
             result = import_service.check_dependencies(pipeline=pipeline)
 
@@ -142,7 +150,7 @@ class RagPipelineExportApi(Resource):
         # Add include_secret params
         query = IncludeSecretQuery.model_validate(request.args.to_dict())
 
-        with sessionmaker(db.engine).begin() as session:
+        with Session(db.engine, expire_on_commit=False) as session:
             export_service = RagPipelineDslService(session)
             result = export_service.export_rag_pipeline_dsl(
                 pipeline=pipeline, include_secret=query.include_secret == "true"

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

@@ -1,6 +1,7 @@
 import json
 import logging
 from typing import Any, Literal, cast
+from uuid import UUID
 
 from flask import abort, request
 from flask_restx import Resource
@@ -875,14 +876,14 @@ class RagPipelineWorkflowRunDetailApi(Resource):
     @login_required
     @account_initialization_required
     @get_rag_pipeline
-    def get(self, pipeline: Pipeline, run_id):
+    def get(self, pipeline: Pipeline, run_id: UUID):
         """
         Get workflow run detail
         """
-        run_id = str(run_id)
+        run_id_str = str(run_id)
 
         rag_pipeline_service = RagPipelineService()
-        workflow_run = rag_pipeline_service.get_rag_pipeline_workflow_run(pipeline=pipeline, run_id=run_id)
+        workflow_run = rag_pipeline_service.get_rag_pipeline_workflow_run(pipeline=pipeline, run_id=run_id_str)
         if workflow_run is None:
             raise NotFound("Workflow run not found")
 
@@ -900,17 +901,17 @@ class RagPipelineWorkflowRunNodeExecutionListApi(Resource):
     @login_required
     @account_initialization_required
     @get_rag_pipeline
-    def get(self, pipeline: Pipeline, run_id: str):
+    def get(self, pipeline: Pipeline, run_id: UUID):
         """
         Get workflow run node execution list
         """
-        run_id = str(run_id)
+        run_id_str = str(run_id)
 
         rag_pipeline_service = RagPipelineService()
         user = cast("Account | EndUser", current_user)
         node_executions = rag_pipeline_service.get_rag_pipeline_workflow_run_node_executions(
             pipeline=pipeline,
-            run_id=run_id,
+            run_id=run_id_str,
             user=user,
         )
 
@@ -960,15 +961,15 @@ class RagPipelineTransformApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, dataset_id: str):
+    def post(self, dataset_id: UUID):
         current_user, _ = current_account_with_tenant()
 
         if not (current_user.has_edit_permission or current_user.is_dataset_operator):
             raise Forbidden()
 
-        dataset_id = str(dataset_id)
+        dataset_id_str = str(dataset_id)
         rag_pipeline_transform_service = RagPipelineTransformService()
-        result = rag_pipeline_transform_service.transform_dataset(dataset_id)
+        result = rag_pipeline_transform_service.transform_dataset(dataset_id_str)
         return result
 
 

api/controllers/console/explore/completion.py

@@ -133,7 +133,7 @@ class CompletionApi(InstalledAppResource):
 )
 class CompletionStopApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self, installed_app, task_id):
+    def post(self, installed_app, task_id: str):
         app_model = installed_app.app
         if app_model.mode != AppMode.COMPLETION:
             raise NotCompletionAppError()
@@ -209,7 +209,7 @@ class ChatApi(InstalledAppResource):
 )
 class ChatStopApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self, installed_app, task_id):
+    def post(self, installed_app, task_id: str):
         app_model = installed_app.app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:

api/controllers/console/explore/conversation.py

@@ -1,4 +1,5 @@
 from typing import Any
+from uuid import UUID
 
 from flask import request
 from pydantic import BaseModel, Field, TypeAdapter
@@ -91,7 +92,7 @@ class ConversationListApi(InstalledAppResource):
 )
 class ConversationApi(InstalledAppResource):
     @console_ns.response(204, "Conversation deleted successfully")
-    def delete(self, installed_app, c_id):
+    def delete(self, installed_app, c_id: UUID):
         app_model = installed_app.app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
@@ -105,7 +106,7 @@ class ConversationApi(InstalledAppResource):
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
 
-        return ResultResponse(result="success").model_dump(mode="json"), 204
+        return "", 204
 
 
 @console_ns.route(
@@ -114,7 +115,7 @@ class ConversationApi(InstalledAppResource):
 )
 class ConversationRenameApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[ConversationRenamePayload.__name__])
-    def post(self, installed_app, c_id):
+    def post(self, installed_app, c_id: UUID):
         app_model = installed_app.app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
@@ -145,7 +146,7 @@ class ConversationRenameApi(InstalledAppResource):
 )
 class ConversationPinApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def patch(self, installed_app, c_id):
+    def patch(self, installed_app, c_id: UUID):
         app_model = installed_app.app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
@@ -169,7 +170,7 @@ class ConversationPinApi(InstalledAppResource):
 )
 class ConversationUnPinApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def patch(self, installed_app, c_id):
+    def patch(self, installed_app, c_id: UUID):
         app_model = installed_app.app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:

api/controllers/console/explore/installed_app.py

@@ -270,7 +270,7 @@ class InstalledAppApi(InstalledAppResource):
         db.session.delete(installed_app)
         db.session.commit()
 
-        return {"result": "success", "message": "App uninstalled successfully"}, 204
+        return "", 204
 
     @console_ns.response(200, "Success", console_ns.models[SimpleResultMessageResponse.__name__])
     def patch(self, installed_app):

api/controllers/console/explore/message.py

@@ -1,5 +1,6 @@
 import logging
 from typing import Literal
+from uuid import UUID
 
 from flask import request
 from pydantic import BaseModel, TypeAdapter
@@ -95,18 +96,18 @@ class MessageListApi(InstalledAppResource):
 class MessageFeedbackApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[MessageFeedbackPayload.__name__])
     @console_ns.response(200, "Feedback submitted successfully", console_ns.models[ResultResponse.__name__])
-    def post(self, installed_app, message_id):
+    def post(self, installed_app, message_id: UUID):
         current_user, _ = current_account_with_tenant()
         app_model = installed_app.app
 
-        message_id = str(message_id)
+        message_id_str = str(message_id)
 
         payload = MessageFeedbackPayload.model_validate(console_ns.payload or {})
 
         try:
             MessageService.create_feedback(
                 app_model=app_model,
-                message_id=message_id,
+                message_id=message_id_str,
                 user=current_user,
                 rating=FeedbackRating(payload.rating) if payload.rating else None,
                 content=payload.content,
@@ -123,13 +124,13 @@ class MessageFeedbackApi(InstalledAppResource):
 )
 class MessageMoreLikeThisApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[MoreLikeThisQuery.__name__])
-    def get(self, installed_app, message_id):
+    def get(self, installed_app, message_id: UUID):
         current_user, _ = current_account_with_tenant()
         app_model = installed_app.app
         if app_model.mode != "completion":
             raise NotCompletionAppError()
 
-        message_id = str(message_id)
+        message_id_str = str(message_id)
 
         args = MoreLikeThisQuery.model_validate(request.args.to_dict())
 
@@ -139,7 +140,7 @@ class MessageMoreLikeThisApi(InstalledAppResource):
             response = AppGenerateService.generate_more_like_this(
                 app_model=app_model,
                 user=current_user,
-                message_id=message_id,
+                message_id=message_id_str,
                 invoke_from=InvokeFrom.EXPLORE,
                 streaming=streaming,
             )
@@ -169,18 +170,18 @@ class MessageMoreLikeThisApi(InstalledAppResource):
 )
 class MessageSuggestedQuestionApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[SuggestedQuestionsResponse.__name__])
-    def get(self, installed_app, message_id):
+    def get(self, installed_app, message_id: UUID):
         current_user, _ = current_account_with_tenant()
         app_model = installed_app.app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
             raise NotChatAppError()
 
-        message_id = str(message_id)
+        message_id_str = str(message_id)
 
         try:
             questions = MessageService.get_suggested_questions_after_answer(
-                app_model=app_model, user=current_user, message_id=message_id, invoke_from=InvokeFrom.EXPLORE
+                app_model=app_model, user=current_user, message_id=message_id_str, invoke_from=InvokeFrom.EXPLORE
             )
         except MessageNotExistsError:
             raise NotFound("Message not found")

api/controllers/console/explore/saved_message.py

@@ -1,3 +1,5 @@
+from uuid import UUID
+
 from flask import request
 from pydantic import TypeAdapter
 from werkzeug.exceptions import NotFound
@@ -7,9 +9,10 @@ from controllers.common.schema import register_response_schema_models, register_
 from controllers.console import console_ns
 from controllers.console.explore.error import NotCompletionAppError
 from controllers.console.explore.wraps import InstalledAppResource
+from controllers.console.wraps import with_current_user
 from fields.conversation_fields import ResultResponse
 from fields.message_fields import SavedMessageInfiniteScrollPagination, SavedMessageItem
-from libs.login import current_account_with_tenant
+from models import Account
 from services.errors.message import MessageNotExistsError
 from services.saved_message_service import SavedMessageService
 
@@ -20,8 +23,8 @@ register_response_schema_models(console_ns, ResultResponse)
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/saved-messages", endpoint="installed_app_saved_messages")
 class SavedMessageListApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[SavedMessageListQuery.__name__])
-    def get(self, installed_app):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, installed_app):
         app_model = installed_app.app
         if app_model.mode != "completion":
             raise NotCompletionAppError()
@@ -44,8 +47,8 @@ class SavedMessageListApi(InstalledAppResource):
 
     @console_ns.expect(console_ns.models[SavedMessageCreatePayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def post(self, installed_app):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def post(self, current_user: Account, installed_app):
         app_model = installed_app.app
         if app_model.mode != "completion":
             raise NotCompletionAppError()
@@ -65,15 +68,15 @@ class SavedMessageListApi(InstalledAppResource):
 )
 class SavedMessageApi(InstalledAppResource):
     @console_ns.response(204, "Saved message deleted successfully")
-    def delete(self, installed_app, message_id):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def delete(self, current_user: Account, installed_app, message_id: UUID):
         app_model = installed_app.app
 
-        message_id = str(message_id)
+        message_id_str = str(message_id)
 
         if app_model.mode != "completion":
             raise NotCompletionAppError()
 
-        SavedMessageService.delete(app_model, current_user, message_id)
+        SavedMessageService.delete(app_model, current_user, message_id_str)
 
-        return ResultResponse(result="success").model_dump(mode="json"), 204
+        return "", 204

api/controllers/console/explore/workflow.py

@@ -13,6 +13,7 @@ from controllers.console.app.error import (
 )
 from controllers.console.explore.error import NotWorkflowAppError
 from controllers.console.explore.wraps import InstalledAppResource
+from controllers.console.wraps import with_current_user
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.apps.base_app_queue_manager import AppQueueManager
 from core.app.entities.app_invoke_entities import InvokeFrom
@@ -25,7 +26,7 @@ from extensions.ext_redis import redis_client
 from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
-from libs.login import current_account_with_tenant
+from models import Account
 from models.model import AppMode, InstalledApp
 from services.app_generate_service import AppGenerateService
 from services.errors.llm import InvokeRateLimitError
@@ -41,11 +42,11 @@ register_response_schema_models(console_ns, SimpleResultResponse)
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/workflows/run")
 class InstalledAppWorkflowRunApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[WorkflowRunPayload.__name__])
-    def post(self, installed_app: InstalledApp):
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp):
         """
         Run workflow
         """
-        current_user, _ = current_account_with_tenant()
         app_model = installed_app.app
         if not app_model:
             raise NotWorkflowAppError()

api/controllers/console/extension.py

@@ -1,5 +1,6 @@
 from datetime import datetime
 from typing import Any
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -152,7 +153,7 @@ class APIBasedExtensionDetailAPI(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, id):
+    def get(self, id: UUID):
         api_based_extension_id = str(id)
         _, tenant_id = current_account_with_tenant()
 
@@ -168,7 +169,7 @@ class APIBasedExtensionDetailAPI(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, id):
+    def post(self, id: UUID):
         api_based_extension_id = str(id)
         _, current_tenant_id = current_account_with_tenant()
 
@@ -196,7 +197,7 @@ class APIBasedExtensionDetailAPI(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def delete(self, id):
+    def delete(self, id: UUID):
         api_based_extension_id = str(id)
         _, current_tenant_id = current_account_with_tenant()
 
@@ -204,4 +205,4 @@ class APIBasedExtensionDetailAPI(Resource):
 
         APIBasedExtensionService.delete(extension_data_from_db)
 
-        return {"result": "success"}, 204
+        return "", 204

api/controllers/console/feature.py

@@ -3,12 +3,12 @@ from werkzeug.exceptions import Unauthorized
 
 from controllers.common.schema import register_response_schema_models
 from libs.login import current_account_with_tenant, current_user, login_required
-from services.feature_service import FeatureModel, FeatureService, 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
 
-register_response_schema_models(console_ns, FeatureModel, SystemFeatureModel)
+register_response_schema_models(console_ns, FeatureModel, LimitationModel, SystemFeatureModel)
 
 
 @console_ns.route("/features")
@@ -28,7 +28,32 @@ class FeatureApi(Resource):
         """Get feature configuration for current tenant"""
         _, current_tenant_id = current_account_with_tenant()
 
-        return FeatureService.get_features(current_tenant_id).model_dump()
+        payload = FeatureService.get_features(
+            current_tenant_id,
+            exclude_vector_space=True,
+        ).model_dump()
+        payload.pop("vector_space", None)
+        return payload
+
+
+@console_ns.route("/features/vector-space")
+class FeatureVectorSpaceApi(Resource):
+    @console_ns.doc("get_tenant_feature_vector_space")
+    @console_ns.doc(description="Get vector-space usage and limit for current tenant")
+    @console_ns.response(
+        200,
+        "Success",
+        console_ns.models[LimitationModel.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @cloud_utm_record
+    def get(self):
+        """Get vector-space usage and limit for current tenant"""
+        _, current_tenant_id = current_account_with_tenant()
+
+        return FeatureService.get_vector_space(current_tenant_id).model_dump()
 
 
 @console_ns.route("/system-features")

api/controllers/console/files.py

@@ -1,4 +1,5 @@
 from typing import Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -106,10 +107,10 @@ class FilePreviewApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.response(200, "Success", console_ns.models[TextContentResponse.__name__])
-    def get(self, file_id):
-        file_id = str(file_id)
+    def get(self, file_id: UUID):
+        file_id_str = str(file_id)
         _, tenant_id = current_account_with_tenant()
-        text = FileService(db.engine).get_file_preview(file_id, tenant_id)
+        text = FileService(db.engine).get_file_preview(file_id_str, tenant_id)
         return {"content": text}
 
 

api/controllers/console/notification.py

@@ -8,8 +8,14 @@ from pydantic import BaseModel, Field
 from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
-from controllers.console.wraps import account_initialization_required, only_edition_cloud, setup_required
-from libs.login import current_account_with_tenant, login_required
+from controllers.console.wraps import (
+    account_initialization_required,
+    only_edition_cloud,
+    setup_required,
+    with_current_user,
+)
+from libs.login import login_required
+from models import Account
 from services.billing_service import BillingService
 
 # Notification content is stored under three lang tags.
@@ -70,11 +76,10 @@ class NotificationApi(Resource):
     )
     @setup_required
     @login_required
+    @with_current_user
     @account_initialization_required
     @only_edition_cloud
-    def get(self):
-        current_user, _ = current_account_with_tenant()
-
+    def get(self, current_user: Account):
         result = BillingService.get_account_notification(str(current_user.id))
 
         # Proto JSON uses camelCase field names (Kratos default marshaling).
@@ -113,11 +118,11 @@ class NotificationDismissApi(Resource):
     )
     @setup_required
     @login_required
+    @with_current_user
     @account_initialization_required
     @only_edition_cloud
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    def post(self):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account):
         payload = DismissNotificationPayload.model_validate(request.get_json())
         BillingService.dismiss_notification(
             notification_id=payload.notification_id,

api/controllers/console/remote_files.py

@@ -1,6 +1,5 @@
-import urllib.parse
-
 import httpx
+from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
@@ -34,7 +33,7 @@ class GetRemoteFileInfo(Resource):
     @console_ns.response(200, "Success", console_ns.models[RemoteFileInfo.__name__])
     @login_required
     def get(self, url: str):
-        decoded_url = urllib.parse.unquote(url)
+        decoded_url = helpers.decode_remote_url(url, request.query_string)
         resp = ssrf_proxy.head(decoded_url)
         if resp.status_code != httpx.codes.OK:
             resp = ssrf_proxy.get(decoded_url, timeout=3)

api/controllers/console/tag/tags.py

@@ -1,4 +1,5 @@
 from typing import Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -131,17 +132,17 @@ class TagUpdateDeleteApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def patch(self, tag_id):
+    def patch(self, tag_id: UUID):
         current_user, _ = current_account_with_tenant()
-        tag_id = str(tag_id)
+        tag_id_str = str(tag_id)
         # The role of the current user in the ta table must be admin, owner, or editor
         if not (current_user.has_edit_permission or current_user.is_dataset_editor):
             raise Forbidden()
 
         payload = TagUpdateRequestPayload.model_validate(console_ns.payload or {})
-        tag = TagService.update_tags(UpdateTagPayload(name=payload.name), tag_id)
+        tag = TagService.update_tags(UpdateTagPayload(name=payload.name), tag_id_str)
 
-        binding_count = TagService.get_tag_binding_count(tag_id)
+        binding_count = TagService.get_tag_binding_count(tag_id_str)
 
         response = TagResponse.model_validate(
             {"id": tag.id, "name": tag.name, "type": tag.type, "binding_count": binding_count}
@@ -154,10 +155,10 @@ class TagUpdateDeleteApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @console_ns.response(204, "Tag deleted successfully")
-    def delete(self, tag_id):
-        tag_id = str(tag_id)
+    def delete(self, tag_id: UUID):
+        tag_id_str = str(tag_id)
 
-        TagService.delete_tag(tag_id)
+        TagService.delete_tag(tag_id_str)
 
         return "", 204
 

api/controllers/console/workspace/account.py

@@ -56,6 +56,12 @@ from models.enums import CreatorUserRole
 from models.model import UploadFile
 from services.account_service import AccountService
 from services.billing_service import BillingService
+from services.entities.auth_entities import (
+    ChangeEmailNewEmailToken,
+    ChangeEmailNewEmailVerifiedToken,
+    ChangeEmailOldEmailToken,
+    ChangeEmailOldEmailVerifiedToken,
+)
 from services.errors.account import CurrentPasswordIncorrectError as ServiceCurrentPasswordIncorrectError
 
 
@@ -620,8 +626,8 @@ class ChangeEmailSendEmailApi(Resource):
             language = "zh-Hans"
         else:
             language = "en-US"
-        account = None
-        user_email = None
+        account = current_user
+        user_email = current_user.email
         email_for_sending = args.email.lower()
         # Default to the initial phase; any legacy/unexpected client input is
         # coerced back to `old_email` so we never trust the caller to declare
@@ -636,24 +642,18 @@ class ChangeEmailSendEmailApi(Resource):
             if reset_data is None:
                 raise InvalidTokenError()
 
-            # The token used to request a new-email code must come from the
-            # old-email verification step. This prevents the bypass described
-            # in GHSA-4q3w-q5mc-45rq where the phase-1 token was reused here.
-            token_phase = reset_data.get(AccountService.CHANGE_EMAIL_TOKEN_PHASE_KEY)
-            if token_phase != AccountService.CHANGE_EMAIL_PHASE_OLD_VERIFIED:
+            if not isinstance(reset_data, ChangeEmailOldEmailVerifiedToken):
                 raise InvalidTokenError()
-            user_email = reset_data.get("email", "")
+            if not reset_data.is_bound_to_account(current_user.id):
+                raise InvalidTokenError()
+            user_email = reset_data.email
 
             if user_email.lower() != current_user.email.lower():
                 raise InvalidEmailError()
-
-            user_email = current_user.email
         else:
-            account = AccountService.get_account_by_email_with_case_fallback(args.email)
-            if account is None:
-                raise AccountNotFound()
-            email_for_sending = account.email
-            user_email = account.email
+            if email_for_sending != current_user.email.lower():
+                raise InvalidEmailError()
+            email_for_sending = current_user.email
 
         token = AccountService.send_change_email_email(
             account=account,
@@ -674,6 +674,7 @@ class ChangeEmailCheckApi(Resource):
     @login_required
     @account_initialization_required
     def post(self):
+        current_user, _ = current_account_with_tenant()
         payload = console_ns.payload or {}
         args = ChangeEmailValidityPayload.model_validate(payload)
 
@@ -686,42 +687,26 @@ class ChangeEmailCheckApi(Resource):
         token_data = AccountService.get_change_email_data(args.token)
         if token_data is None:
             raise InvalidTokenError()
+        if not token_data.is_bound_to_account(current_user.id):
+            raise InvalidTokenError()
 
-        token_email = token_data.get("email")
-        normalized_token_email = token_email.lower() if isinstance(token_email, str) else token_email
+        normalized_token_email = token_data.email.lower()
         if user_email != normalized_token_email:
             raise InvalidEmailError()
 
-        if args.code != token_data.get("code"):
+        if args.code != token_data.code:
             AccountService.add_change_email_error_rate_limit(user_email)
             raise EmailCodeError()
 
-        # Only advance tokens that were minted by the matching send-code step;
-        # refuse tokens that have already progressed or lack a phase marker so
-        # the chain `old_email -> old_email_verified -> new_email -> new_email_verified`
-        # is strictly enforced.
-        phase_transitions = {
-            AccountService.CHANGE_EMAIL_PHASE_OLD: AccountService.CHANGE_EMAIL_PHASE_OLD_VERIFIED,
-            AccountService.CHANGE_EMAIL_PHASE_NEW: AccountService.CHANGE_EMAIL_PHASE_NEW_VERIFIED,
-        }
-        token_phase = token_data.get(AccountService.CHANGE_EMAIL_TOKEN_PHASE_KEY)
-        if not isinstance(token_phase, str):
-            raise InvalidTokenError()
-        refreshed_phase = phase_transitions.get(token_phase)
-        if refreshed_phase is None:
+        if isinstance(token_data, ChangeEmailOldEmailToken | ChangeEmailNewEmailToken):
+            refreshed_token_data = token_data.promote()
+        else:
             raise InvalidTokenError()
 
         # Verified, revoke the first token
         AccountService.revoke_change_email_token(args.token)
 
-        # Refresh token data by generating a new token that carries the
-        # upgraded phase so later steps can check it.
-        _, new_token = AccountService.generate_change_email_token(
-            user_email,
-            code=args.code,
-            old_email=token_data.get("old_email"),
-            additional_data={AccountService.CHANGE_EMAIL_TOKEN_PHASE_KEY: refreshed_phase},
-        )
+        new_token = AccountService.generate_change_email_token(refreshed_token_data, current_user)
 
         AccountService.reset_change_email_error_rate_limit(user_email)
         return {"is_valid": True, "email": normalized_token_email, "token": new_token}
@@ -746,27 +731,22 @@ class ChangeEmailResetApi(Resource):
         if not AccountService.check_email_unique(normalized_new_email):
             raise EmailAlreadyInUseError()
 
+        current_user, _ = current_account_with_tenant()
         reset_data = AccountService.get_change_email_data(args.token)
         if not reset_data:
             raise InvalidTokenError()
+        if not reset_data.is_bound_to_account(current_user.id):
+            raise InvalidTokenError()
 
-        # Only tokens that completed both verification phases may be used to
-        # change the email. This closes GHSA-4q3w-q5mc-45rq where a token from
-        # the initial send-code step could be replayed directly here.
-        token_phase = reset_data.get(AccountService.CHANGE_EMAIL_TOKEN_PHASE_KEY)
-        if token_phase != AccountService.CHANGE_EMAIL_PHASE_NEW_VERIFIED:
+        if not isinstance(reset_data, ChangeEmailNewEmailVerifiedToken):
             raise InvalidTokenError()
 
         # Bind the new email to the token that was mailed and verified, so a
         # verified token cannot be reused with a different `new_email` value.
-        token_email = reset_data.get("email")
-        normalized_token_email = token_email.lower() if isinstance(token_email, str) else token_email
-        if normalized_token_email != normalized_new_email:
+        if reset_data.email.lower() != normalized_new_email:
             raise InvalidTokenError()
 
-        old_email = reset_data.get("old_email", "")
-        current_user, _ = current_account_with_tenant()
-        if current_user.email.lower() != old_email.lower():
+        if current_user.email.lower() != reset_data.old_email.lower():
             raise AccountNotFound()
 
         # Revoke only after all checks pass so failed attempts don't burn a

api/controllers/console/workspace/members.py

@@ -1,8 +1,10 @@
 from urllib import parse
+from uuid import UUID
 
 from flask import abort, request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, TypeAdapter
+from sqlalchemy import func, select
 
 import services
 from configs import dify_config
@@ -21,15 +23,15 @@ from controllers.console.auth.error import (
 from controllers.console.error import EmailSendIpLimitError, WorkspaceMembersLimitExceeded
 from controllers.console.wraps import (
     account_initialization_required,
-    cloud_edition_billing_resource_check,
     is_allow_transfer_owner,
     setup_required,
 )
 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 models.account import Account, TenantAccountRole
+from models.account import Account, TenantAccountJoin, TenantAccountRole
 from services.account_service import AccountService, RegisterService, TenantService
 from services.errors.account import AccountAlreadyInTenantError
 from services.feature_service import FeatureService
@@ -78,6 +80,54 @@ def _is_role_enabled(role: TenantAccountRole | str, tenant_id: str) -> bool:
     return FeatureService.get_features(tenant_id=tenant_id).dataset_operator_enabled
 
 
+def _normalize_invitee_emails(emails: list[str]) -> list[str]:
+    return list(dict.fromkeys(email.lower() for email in emails))
+
+
+def _count_new_member_invites(tenant_id: str, emails: list[str]) -> int:
+    new_member_count = 0
+    for email in emails:
+        account = AccountService.get_account_by_email_with_case_fallback(email)
+        if not account:
+            new_member_count += 1
+            continue
+
+        exists = db.session.scalar(
+            select(TenantAccountJoin.id)
+            .where(TenantAccountJoin.tenant_id == tenant_id, TenantAccountJoin.account_id == account.id)
+            .limit(1)
+        )
+        if not exists:
+            new_member_count += 1
+
+    return new_member_count
+
+
+def _count_current_members(tenant_id: str) -> int:
+    return (
+        db.session.scalar(select(func.count(TenantAccountJoin.id)).where(TenantAccountJoin.tenant_id == tenant_id)) or 0
+    )
+
+
+def _check_member_invite_limits(tenant_id: str, new_member_count: int) -> None:
+    if new_member_count <= 0:
+        return
+
+    features = FeatureService.get_features(tenant_id=tenant_id)
+
+    if dify_config.ENTERPRISE_ENABLED:
+        workspace_members = features.workspace_members
+        if workspace_members.enabled is True and not workspace_members.is_available(new_member_count):
+            raise WorkspaceMembersLimitExceeded()
+        return
+
+    if dify_config.BILLING_ENABLED and features.billing.enabled is True:
+        members = features.members
+        current_member_count = _count_current_members(tenant_id)
+        if 0 < members.limit < current_member_count + new_member_count:
+            raise WorkspaceMembersLimitExceeded()
+
+
 @console_ns.route("/workspaces/current/members")
 class MemberListApi(Resource):
     """List all members of current tenant."""
@@ -104,12 +154,11 @@ class MemberInviteEmailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @cloud_edition_billing_resource_check("members")
     def post(self):
         payload = console_ns.payload or {}
         args = MemberInvitePayload.model_validate(payload)
 
-        invitee_emails = args.emails
+        invitee_emails = _normalize_invitee_emails(args.emails)
         invitee_role = args.role
         interface_language = args.language
         if not TenantAccountRole.is_non_owner_role(invitee_role):
@@ -129,37 +178,36 @@ class MemberInviteEmailApi(Resource):
         invitation_results = []
         console_web_url = dify_config.CONSOLE_WEB_URL
 
-        workspace_members = FeatureService.get_features(tenant_id=inviter.current_tenant.id).workspace_members
+        tenant_id = inviter.current_tenant.id
+        with redis_client.lock(f"workspace_member_invite:{tenant_id}", timeout=60):
+            new_member_count = _count_new_member_invites(tenant_id, invitee_emails)
+            _check_member_invite_limits(tenant_id, new_member_count)
 
-        if not workspace_members.is_available(len(invitee_emails)):
-            raise WorkspaceMembersLimitExceeded()
-
-        for invitee_email in invitee_emails:
-            normalized_invitee_email = invitee_email.lower()
-            try:
-                if not inviter.current_tenant:
-                    raise ValueError("No current tenant")
-                token = RegisterService.invite_new_member(
-                    tenant=inviter.current_tenant,
-                    email=invitee_email,
-                    language=interface_language,
-                    role=invitee_role,
-                    inviter=inviter,
-                )
-                encoded_invitee_email = parse.quote(normalized_invitee_email)
-                invitation_results.append(
-                    {
-                        "status": "success",
-                        "email": normalized_invitee_email,
-                        "url": f"{console_web_url}/activate?email={encoded_invitee_email}&token={token}",
-                    }
-                )
-            except AccountAlreadyInTenantError:
-                invitation_results.append(
-                    {"status": "success", "email": normalized_invitee_email, "url": f"{console_web_url}/signin"}
-                )
-            except Exception as e:
-                invitation_results.append({"status": "failed", "email": normalized_invitee_email, "message": str(e)})
+            for invitee_email in invitee_emails:
+                try:
+                    if not inviter.current_tenant:
+                        raise ValueError("No current tenant")
+                    token = RegisterService.invite_new_member(
+                        tenant=inviter.current_tenant,
+                        email=invitee_email,
+                        language=interface_language,
+                        role=invitee_role,
+                        inviter=inviter,
+                    )
+                    encoded_invitee_email = parse.quote(invitee_email)
+                    invitation_results.append(
+                        {
+                            "status": "success",
+                            "email": invitee_email,
+                            "url": f"{console_web_url}/activate?email={encoded_invitee_email}&token={token}",
+                        }
+                    )
+                except AccountAlreadyInTenantError:
+                    invitation_results.append(
+                        {"status": "success", "email": invitee_email, "url": f"{console_web_url}/signin"}
+                    )
+                except Exception as e:
+                    invitation_results.append({"status": "failed", "email": invitee_email, "message": str(e)})
 
         return {
             "result": "success",
@@ -175,7 +223,7 @@ class MemberCancelInviteApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def delete(self, member_id):
+    def delete(self, member_id: UUID):
         current_user, _ = current_account_with_tenant()
         if not current_user.current_tenant:
             raise ValueError("No current tenant")
@@ -208,7 +256,7 @@ class MemberUpdateRoleApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def put(self, member_id):
+    def put(self, member_id: UUID):
         payload = console_ns.payload or {}
         args = MemberRoleUpdatePayload.model_validate(payload)
         new_role = args.role
@@ -351,7 +399,7 @@ class OwnerTransfer(Resource):
     @login_required
     @account_initialization_required
     @is_allow_transfer_owner
-    def post(self, member_id):
+    def post(self, member_id: UUID):
         payload = console_ns.payload or {}
         args = OwnerTransferPayload.model_validate(payload)
 

api/controllers/console/workspace/model_providers.py

@@ -194,7 +194,7 @@ class ModelProviderCredentialApi(Resource):
             tenant_id=current_tenant_id, provider=provider, credential_id=args.credential_id
         )
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/credentials/switch")

api/controllers/console/workspace/models.py

@@ -259,7 +259,7 @@ class ModelProviderModelApi(Resource):
             tenant_id=tenant_id, provider=provider, model=args.model, model_type=args.model_type
         )
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/models/credentials")
@@ -395,7 +395,7 @@ class ModelProviderModelCredentialApi(Resource):
             credential_id=args.credential_id,
         )
 
-        return {"result": "success"}, 204
+        return "", 204
 
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/models/credentials/switch")
@@ -532,7 +532,7 @@ class ModelProviderAvailableModelApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, model_type):
+    def get(self, model_type: str):
         _, tenant_id = current_account_with_tenant()
         model_provider_service = ModelProviderService()
         models = model_provider_service.get_models_by_model_type(tenant_id=tenant_id, model_type=model_type)

api/controllers/console/workspace/plugin.py

@@ -15,6 +15,7 @@ from controllers.console import console_ns
 from controllers.console.workspace import plugin_permission_required
 from controllers.console.wraps import account_initialization_required, is_admin_or_owner_required, setup_required
 from core.plugin.impl.exc import PluginDaemonClientSideError
+from core.plugin.plugin_service import PluginService
 from fields.base import ResponseModel
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.login import current_account_with_tenant, login_required
@@ -22,7 +23,6 @@ from models.account import TenantPluginAutoUpgradeStrategy, TenantPluginPermissi
 from services.plugin.plugin_auto_upgrade_service import PluginAutoUpgradeService
 from services.plugin.plugin_parameter_service import PluginParameterService
 from services.plugin.plugin_permission_service import PluginPermissionService
-from services.plugin.plugin_service import PluginService
 
 
 class ParserList(BaseModel):

api/controllers/console/wraps.py

@@ -4,6 +4,7 @@ import os
 import time
 from collections.abc import Callable
 from functools import wraps
+from typing import Concatenate
 
 from flask import abort, request
 from sqlalchemy import select
@@ -16,6 +17,7 @@ from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from libs.encryption import FieldEncryption
 from libs.login import current_account_with_tenant
+from models import Account
 from models.account import AccountStatus
 from models.dataset import RateLimitLog
 from models.model import DifySetup
@@ -82,9 +84,7 @@ def only_edition_self_hosted[**P, R](view: Callable[P, R]) -> Callable[P, R]:
 def cloud_edition_billing_enabled[**P, R](view: Callable[P, R]) -> Callable[P, R]:
     @wraps(view)
     def decorated(*args: P.args, **kwargs: P.kwargs):
-        _, current_tenant_id = current_account_with_tenant()
-        features = FeatureService.get_features(current_tenant_id)
-        if not features.billing.enabled:
+        if not dify_config.BILLING_ENABLED:
             abort(403, "Billing feature is not enabled.")
         return view(*args, **kwargs)
 
@@ -198,15 +198,11 @@ def cloud_utm_record[**P, R](view: Callable[P, R]) -> Callable[P, R]:
     @wraps(view)
     def decorated(*args: P.args, **kwargs: P.kwargs):
         with contextlib.suppress(Exception):
-            _, current_tenant_id = current_account_with_tenant()
-            features = FeatureService.get_features(current_tenant_id)
-
-            if features.billing.enabled:
-                utm_info = request.cookies.get("utm_info")
-
-                if utm_info:
-                    utm_info_dict: UtmInfo = json.loads(utm_info)
-                    OperationService.record_utm(current_tenant_id, utm_info_dict)
+            utm_info = request.cookies.get("utm_info")
+            if dify_config.BILLING_ENABLED and utm_info:
+                _, current_tenant_id = current_account_with_tenant()
+                utm_info_dict: UtmInfo = json.loads(utm_info)
+                OperationService.record_utm(current_tenant_id, utm_info_dict)
 
         return view(*args, **kwargs)
 
@@ -309,7 +305,6 @@ def edit_permission_required[**P, R](f: Callable[P, R]) -> Callable[P, R]:
         from werkzeug.exceptions import Forbidden
 
         from libs.login import current_user
-        from models import Account
 
         user = current_user._get_current_object()  # type: ignore
         if not isinstance(user, Account):
@@ -327,7 +322,6 @@ def is_admin_or_owner_required[**P, R](f: Callable[P, R]) -> Callable[P, R]:
         from werkzeug.exceptions import Forbidden
 
         from libs.login import current_user
-        from models import Account
 
         user = current_user._get_current_object()
         if not isinstance(user, Account) or not user.is_admin_or_owner:
@@ -495,3 +489,25 @@ def decrypt_code_field[**P, R](view: Callable[P, R]) -> Callable[P, R]:
         return view(*args, **kwargs)
 
     return decorated
+
+
+def with_current_tenant_id[T, **P, R](
+    view: Callable[Concatenate[T, str, P], R],
+) -> Callable[Concatenate[T, P], R]:
+    @wraps(view)
+    def decorated(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+        _, current_tenant_id = current_account_with_tenant()
+        return view(self, current_tenant_id, *args, **kwargs)
+
+    return decorated
+
+
+def with_current_user[T, **P, R](
+    view: Callable[Concatenate[T, Account, P], R],
+) -> Callable[Concatenate[T, P], R]:
+    @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

api/controllers/files/image_preview.py

@@ -1,4 +1,5 @@
 from urllib.parse import quote
+from uuid import UUID
 
 from flask import Response, request
 from flask_restx import Resource
@@ -49,8 +50,8 @@ class ImagePreviewApi(Resource):
             415: "Unsupported file type",
         }
     )
-    def get(self, file_id):
-        file_id = str(file_id)
+    def get(self, file_id: UUID):
+        file_id_str = str(file_id)
 
         args = FileSignatureQuery.model_validate(request.args.to_dict(flat=True))
         timestamp = args.timestamp
@@ -59,7 +60,7 @@ class ImagePreviewApi(Resource):
 
         try:
             generator, mimetype = FileService(db.engine).get_image_preview(
-                file_id=file_id,
+                file_id=file_id_str,
                 timestamp=timestamp,
                 nonce=nonce,
                 sign=sign,
@@ -91,14 +92,14 @@ class FilePreviewApi(Resource):
             415: "Unsupported file type",
         }
     )
-    def get(self, file_id):
-        file_id = str(file_id)
+    def get(self, file_id: UUID):
+        file_id_str = str(file_id)
 
         args = FilePreviewQuery.model_validate(request.args.to_dict(flat=True))
 
         try:
             generator, upload_file = FileService(db.engine).get_file_generator_by_file_id(
-                file_id=file_id,
+                file_id=file_id_str,
                 timestamp=args.timestamp,
                 nonce=args.nonce,
                 sign=args.sign,
@@ -159,10 +160,10 @@ class WorkspaceWebappLogoApi(Resource):
             415: "Unsupported file type",
         }
     )
-    def get(self, workspace_id):
-        workspace_id = str(workspace_id)
+    def get(self, workspace_id: UUID):
+        workspace_id_str = str(workspace_id)
 
-        custom_config = TenantService.get_custom_config(workspace_id)
+        custom_config = TenantService.get_custom_config(workspace_id_str)
         webapp_logo_file_id = custom_config.get("replace_webapp_logo") if custom_config is not None else None
 
         if not webapp_logo_file_id:

api/controllers/files/tool_files.py

@@ -1,4 +1,5 @@
 from urllib.parse import quote
+from uuid import UUID
 
 from flask import Response, request
 from flask_restx import Resource
@@ -45,17 +46,19 @@ class ToolFileApi(Resource):
             415: "Unsupported file type",
         }
     )
-    def get(self, file_id, extension):
-        file_id = str(file_id)
+    def get(self, file_id: UUID, extension: str):
+        file_id_str = str(file_id)
 
         args = ToolFileQuery.model_validate(request.args.to_dict())
-        if not verify_tool_file_signature(file_id=file_id, timestamp=args.timestamp, nonce=args.nonce, sign=args.sign):
+        if not verify_tool_file_signature(
+            file_id=file_id_str, timestamp=args.timestamp, nonce=args.nonce, sign=args.sign
+        ):
             raise Forbidden("Invalid request.")
 
         try:
             tool_file_manager = ToolFileManager()
             stream, tool_file = tool_file_manager.get_file_generator_by_tool_file_id(
-                file_id,
+                file_id_str,
             )
 
             if not stream or not tool_file:

api/controllers/openapi/__init__.py

@@ -0,0 +1,128 @@
+from flask import Blueprint
+from flask_restx import Namespace
+
+from libs.device_flow_security import attach_anti_framing
+from libs.external_api import ExternalApi
+
+bp = Blueprint("openapi", __name__, url_prefix="/openapi/v1")
+attach_anti_framing(bp)
+
+api = ExternalApi(
+    bp,
+    version="1.0",
+    title="OpenAPI",
+    description="User-scoped programmatic API (bearer auth)",
+)
+
+openapi_ns = Namespace("openapi", description="User-scoped operations", path="/")
+
+# Register response/query models BEFORE importing controller modules so that
+# @openapi_ns.response / @openapi_ns.expect decorators can resolve model names.
+from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.openapi._models import (
+    AccountPayload,
+    AccountResponse,
+    AppDescribeInfo,
+    AppDescribeQuery,
+    AppDescribeResponse,
+    AppInfoResponse,
+    AppListQuery,
+    AppListResponse,
+    AppListRow,
+    AppRunRequest,
+    DeviceCodeRequest,
+    DeviceCodeResponse,
+    DeviceLookupQuery,
+    DeviceLookupResponse,
+    DeviceMutateRequest,
+    DeviceMutateResponse,
+    DevicePollRequest,
+    MessageMetadata,
+    PermittedExternalAppsListQuery,
+    PermittedExternalAppsListResponse,
+    RevokeResponse,
+    ServerVersionResponse,
+    SessionListResponse,
+    SessionRow,
+    TagItem,
+    UsageInfo,
+    WorkflowRunData,
+    WorkspaceDetailResponse,
+    WorkspaceListResponse,
+    WorkspacePayload,
+    WorkspaceSummaryResponse,
+)
+from fields.file_fields import FileResponse
+
+register_schema_models(
+    openapi_ns,
+    AppDescribeQuery,
+    AppListQuery,
+    AppRunRequest,
+    DeviceCodeRequest,
+    DevicePollRequest,
+    DeviceLookupQuery,
+    DeviceMutateRequest,
+    PermittedExternalAppsListQuery,
+)
+register_response_schema_models(
+    openapi_ns,
+    TagItem,
+    UsageInfo,
+    MessageMetadata,
+    AppListRow,
+    AppListResponse,
+    AppInfoResponse,
+    AppDescribeInfo,
+    AppDescribeResponse,
+    WorkflowRunData,
+    AccountPayload,
+    WorkspacePayload,
+    AccountResponse,
+    SessionRow,
+    SessionListResponse,
+    PermittedExternalAppsListResponse,
+    RevokeResponse,
+    WorkspaceSummaryResponse,
+    WorkspaceListResponse,
+    WorkspaceDetailResponse,
+    DeviceCodeResponse,
+    DeviceLookupResponse,
+    DeviceMutateResponse,
+    FileResponse,
+    ServerVersionResponse,
+)
+
+from . import (
+    _meta,
+    account,
+    app_run,
+    apps,
+    apps_permitted_external,
+    files,
+    human_input_form,
+    index,
+    oauth_device,
+    oauth_device_sso,
+    workflow_events,
+    workspaces,
+)
+
+# Request models are imported from _models.py and registered above.
+
+__all__ = [
+    "_meta",
+    "account",
+    "app_run",
+    "apps",
+    "apps_permitted_external",
+    "files",
+    "human_input_form",
+    "index",
+    "oauth_device",
+    "oauth_device_sso",
+    "workflow_events",
+    "workspaces",
+]
+
+api.add_namespace(openapi_ns)

api/controllers/openapi/_audit.py

@@ -0,0 +1,66 @@
+"""Audit emission for openapi app-run endpoints.
+
+Pattern: logger.info with extra={"audit": True, "event": "app.run.openapi", ...}
+matches the existing oauth_device convention. The EE OTel exporter consults
+its own allowlist to decide whether to ship the line.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+EVENT_APP_RUN_OPENAPI = "app.run.openapi"
+EVENT_OPENAPI_WRONG_SURFACE_DENIED = "openapi.wrong_surface_denied"
+
+
+def emit_app_run(
+    *,
+    app_id: str,
+    tenant_id: str,
+    caller_kind: str,
+    mode: str,
+    surface: str,
+) -> None:
+    logger.info(
+        "audit: %s app_id=%s tenant_id=%s caller_kind=%s mode=%s surface=%s",
+        EVENT_APP_RUN_OPENAPI,
+        app_id,
+        tenant_id,
+        caller_kind,
+        mode,
+        surface,
+        extra={
+            "audit": True,
+            "event": EVENT_APP_RUN_OPENAPI,
+            "app_id": app_id,
+            "tenant_id": tenant_id,
+            "caller_kind": caller_kind,
+            "mode": mode,
+            "surface": surface,
+        },
+    )
+
+
+def emit_wrong_surface(
+    *,
+    subject_type: str | None,
+    attempted_path: str,
+    client_id: str | None,
+    token_id: str | None,
+) -> None:
+    logger.warning(
+        "audit: %s subject_type=%s attempted_path=%s",
+        EVENT_OPENAPI_WRONG_SURFACE_DENIED,
+        subject_type,
+        attempted_path,
+        extra={
+            "audit": True,
+            "event": EVENT_OPENAPI_WRONG_SURFACE_DENIED,
+            "subject_type": subject_type,
+            "attempted_path": attempted_path,
+            "client_id": client_id,
+            "token_id": token_id,
+        },
+    )

api/controllers/openapi/_input_schema.py

@@ -0,0 +1,143 @@
+"""Server-side JSON Schema derivation from Dify `user_input_form`."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from controllers.service_api.app.error import AppUnavailableError
+from models import App
+from models.model import AppMode
+
+JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema"
+
+EMPTY_INPUT_SCHEMA: dict[str, Any] = {
+    "$schema": JSON_SCHEMA_DRAFT,
+    "type": "object",
+    "properties": {},
+    "required": [],
+}
+
+_CHAT_FAMILY = frozenset({AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT})
+
+
+def _file_object_shape() -> dict[str, Any]:
+    """Single-file value shape. Forward-compat placeholder; refine when file-API contract pins."""
+    return {
+        "type": "object",
+        "properties": {
+            "type": {"type": "string"},
+            "transfer_method": {"type": "string"},
+            "url": {"type": "string"},
+            "upload_file_id": {"type": "string"},
+        },
+        "additionalProperties": True,
+    }
+
+
+def _row_to_schema(row_type: str, row: dict[str, Any]) -> dict[str, Any] | None:
+    label = row.get("label") or row.get("variable", "")
+    base: dict[str, Any] = {"title": label} if label else {}
+
+    if row_type in ("text-input", "paragraph"):
+        out: dict[str, Any] = {"type": "string"} | base
+        max_length = row.get("max_length")
+        if isinstance(max_length, int) and max_length > 0:
+            out["maxLength"] = max_length
+        return out
+
+    if row_type == "select":
+        return {"type": "string"} | base | {"enum": list(row.get("options") or [])}
+
+    if row_type == "number":
+        return {"type": "number"} | base
+
+    if row_type == "file":
+        return _file_object_shape() | base
+
+    if row_type == "file-list":
+        return {
+            "type": "array",
+            "items": _file_object_shape(),
+        } | base
+
+    return None
+
+
+def _form_to_jsonschema(form: list[dict[str, Any]]) -> tuple[dict[str, Any], list[str]]:
+    """Translate a user_input_form row list into (properties, required-list).
+
+    Each row is a single-key dict: `{"text-input": {variable, label, required, ...}}`.
+    Unknown variable types are skipped (forward-compat).
+    """
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for row in form:
+        if not isinstance(row, dict) or len(row) != 1:
+            continue
+        ((row_type, row_body),) = row.items()
+        if not isinstance(row_body, dict):
+            continue
+        variable = row_body.get("variable")
+        if not variable:
+            continue
+        schema = _row_to_schema(row_type, row_body)
+        if schema is None:
+            continue
+        properties[variable] = schema
+        if row_body.get("required"):
+            required.append(variable)
+    return properties, required
+
+
+def resolve_app_config(app: App) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Resolve `(features_dict, user_input_form)` for parameters / schema derivation.
+
+    Raises `AppUnavailableError` on misconfigured apps.
+    """
+    if app.mode in {AppMode.ADVANCED_CHAT, AppMode.WORKFLOW}:
+        workflow = app.workflow
+        if workflow is None:
+            raise AppUnavailableError()
+        return (
+            workflow.features_dict,
+            cast(list[dict[str, Any]], workflow.user_input_form(to_old_structure=True)),
+        )
+
+    app_model_config = app.app_model_config
+    if app_model_config is None:
+        raise AppUnavailableError()
+    features_dict = cast(dict[str, Any], app_model_config.to_dict())
+    return features_dict, cast(list[dict[str, Any]], features_dict.get("user_input_form", []))
+
+
+def build_input_schema(app: App) -> dict[str, Any]:
+    """Derive Draft 2020-12 JSON Schema from `user_input_form` + app mode.
+
+    chat / agent-chat / advanced-chat: top-level `query` (required, minLength=1) + `inputs` object.
+    completion / workflow: `inputs` object only.
+    Raises `AppUnavailableError` on misconfigured apps.
+    """
+    _, user_input_form = resolve_app_config(app)
+    inputs_props, inputs_required = _form_to_jsonschema(user_input_form)
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    if app.mode in _CHAT_FAMILY:
+        properties["query"] = {"type": "string", "minLength": 1}
+        required.append("query")
+
+    properties["inputs"] = {
+        "type": "object",
+        "properties": inputs_props,
+        "required": inputs_required,
+        "additionalProperties": False,
+    }
+    required.append("inputs")
+
+    return {
+        "$schema": JSON_SCHEMA_DRAFT,
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }

api/controllers/openapi/_meta.py

@@ -0,0 +1,23 @@
+"""Meta endpoint: `GET /openapi/v1/_version` — no auth.
+
+Returns the server's project version and edition so the difyctl CLI can probe
+compatibility without needing to be logged in. Mirrors the `_health` endpoint
+in `index.py`.
+"""
+
+from flask_restx import Resource
+
+from configs import dify_config
+from controllers.openapi import openapi_ns
+from controllers.openapi._models import ServerVersionResponse
+
+
+@openapi_ns.route("/_version")
+class VersionApi(Resource):
+    @openapi_ns.response(200, "Server version", openapi_ns.models[ServerVersionResponse.__name__])
+    def get(self):
+        edition = dify_config.EDITION if dify_config.EDITION in ("SELF_HOSTED", "CLOUD") else "SELF_HOSTED"
+        return ServerVersionResponse(
+            version=dify_config.project.version,
+            edition=edition,
+        ).model_dump(mode="json")

api/controllers/openapi/_models.py

@@ -0,0 +1,344 @@
+"""Shared response substructures for openapi endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from libs.helper import UUIDStrOrEmpty, uuid_value
+from models.model import AppMode
+
+# Server-side cap on `limit` query param for /openapi/v1/* list endpoints.
+MAX_PAGE_LIMIT = 200
+
+
+class UsageInfo(BaseModel):
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class MessageMetadata(BaseModel):
+    usage: UsageInfo | None = None
+    retriever_resources: list[dict[str, Any]] = []
+
+
+class PaginationEnvelope[T](BaseModel):
+    """Canonical pagination envelope for `/openapi/v1/*` list endpoints."""
+
+    page: int
+    limit: int
+    total: int
+    has_more: bool
+    data: list[T]
+
+    @classmethod
+    def build(cls, *, page: int, limit: int, total: int, items: list[T]) -> PaginationEnvelope[T]:
+        return cls(page=page, limit=limit, total=total, has_more=page * limit < total, data=items)
+
+
+class TagItem(BaseModel):
+    name: str
+
+
+class AppListRow(BaseModel):
+    id: str
+    name: str
+    description: str | None = None
+    mode: AppMode
+    tags: list[TagItem] = []
+    updated_at: str | None = None
+    created_by_name: str | None = None
+    workspace_id: str | None = None
+    workspace_name: str | None = None
+
+
+class AppListResponse(BaseModel):
+    page: int
+    limit: int
+    total: int
+    has_more: bool
+    data: list[AppListRow]
+
+
+class PermittedExternalAppsListResponse(BaseModel):
+    page: int
+    limit: int
+    total: int
+    has_more: bool
+    data: list[AppListRow]
+
+
+class AppInfoResponse(BaseModel):
+    id: str
+    name: str
+    description: str | None = None
+    mode: str
+    author: str | None = None
+    tags: list[TagItem] = []
+
+
+class AppDescribeInfo(AppInfoResponse):
+    updated_at: str | None = None
+    service_api_enabled: bool
+    is_agent: bool = False
+
+
+class AppDescribeResponse(BaseModel):
+    info: AppDescribeInfo | None = None
+    parameters: dict[str, Any] | None = None
+    input_schema: dict[str, Any] | None = None
+
+
+class ChatMessageResponse(BaseModel):
+    event: str
+    task_id: str
+    id: str
+    message_id: str
+    conversation_id: str
+    mode: str
+    answer: str
+    metadata: MessageMetadata = Field(default_factory=MessageMetadata)
+    created_at: int
+
+
+class CompletionMessageResponse(BaseModel):
+    event: str
+    task_id: str
+    id: str
+    message_id: str
+    mode: str
+    answer: str
+    metadata: MessageMetadata = Field(default_factory=MessageMetadata)
+    created_at: int
+
+
+class WorkflowRunData(BaseModel):
+    id: str
+    workflow_id: str
+    status: str
+    outputs: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+    elapsed_time: float | None = None
+    total_tokens: int | None = None
+    total_steps: int | None = None
+    created_at: int | None = None
+    finished_at: int | None = None
+
+
+class WorkflowRunResponse(BaseModel):
+    workflow_run_id: str
+    task_id: str
+    mode: Literal["workflow"] = "workflow"
+    data: WorkflowRunData
+
+
+class AccountPayload(BaseModel):
+    id: str
+    email: str
+    name: str
+
+
+class WorkspacePayload(BaseModel):
+    id: str
+    name: str
+    role: str
+
+
+class AccountResponse(BaseModel):
+    subject_type: str
+    subject_email: str | None = None
+    subject_issuer: str | None = None
+    account: AccountPayload | None = None
+    workspaces: list[WorkspacePayload] = []
+    default_workspace_id: str | None = None
+
+
+class SessionRow(BaseModel):
+    id: str
+    prefix: str
+    client_id: str
+    device_label: str
+    created_at: str | None = None
+    last_used_at: str | None = None
+    expires_at: str | None = None
+
+
+class SessionListResponse(BaseModel):
+    page: int
+    limit: int
+    total: int
+    has_more: bool
+    data: list[SessionRow]
+
+
+class RevokeResponse(BaseModel):
+    status: str
+
+
+class WorkspaceSummaryResponse(BaseModel):
+    id: str
+    name: str
+    role: str
+    status: str
+    current: bool
+
+
+class WorkspaceListResponse(BaseModel):
+    workspaces: list[WorkspaceSummaryResponse]
+
+
+class WorkspaceDetailResponse(BaseModel):
+    id: str
+    name: str
+    role: str
+    status: str
+    current: bool
+    created_at: str | None = None
+
+
+class DeviceCodeResponse(BaseModel):
+    device_code: str
+    user_code: str
+    verification_uri: str
+    expires_in: int
+    interval: int
+
+
+class DeviceLookupResponse(BaseModel):
+    valid: bool
+    expires_in_remaining: int = 0
+    client_id: str | None = None
+
+
+class DeviceMutateResponse(BaseModel):
+    status: str
+
+
+class ServerVersionResponse(BaseModel):
+    """Meta endpoint payload for `GET /openapi/v1/_version` — no auth required."""
+
+    version: str
+    edition: Literal["SELF_HOSTED", "CLOUD"]
+
+
+class AppDescribeQuery(BaseModel):
+    """`?fields=` allow-list for GET /apps/<id>/describe.
+
+    Empty / omitted → all blocks. Unknown member → ValidationError → 422.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    fields: set[str] | None = None
+    workspace_id: str | None = None
+
+    @field_validator("workspace_id", mode="before")
+    @classmethod
+    def _validate_workspace_id(cls, v: object) -> str | None:
+        if v is None or v == "":
+            return None
+        if not isinstance(v, str):
+            raise ValueError("workspace_id must be a string")
+        try:
+            import uuid as _uuid
+
+            _uuid.UUID(v)
+        except ValueError:
+            raise ValueError("workspace_id must be a valid UUID")
+        return v
+
+    @field_validator("fields", mode="before")
+    @classmethod
+    def _parse_fields(cls, v: object) -> set[str] | None:
+        if v is None or v == "":
+            return None
+        if not isinstance(v, str):
+            raise ValueError("fields must be a comma-separated string")
+        _ALLOWED_DESCRIBE_FIELDS = frozenset({"info", "parameters", "input_schema"})
+        members = {m.strip() for m in v.split(",") if m.strip()}
+        unknown = members - _ALLOWED_DESCRIBE_FIELDS
+        if unknown:
+            raise ValueError(f"unknown field(s): {sorted(unknown)}")
+        return members
+
+
+class AppListQuery(BaseModel):
+    """mode is a closed enum."""
+
+    workspace_id: str
+    page: int = Field(1, ge=1)
+    limit: int = Field(20, ge=1, le=MAX_PAGE_LIMIT)
+    mode: AppMode | None = None
+    name: str | None = Field(None, max_length=200)
+    tag: str | None = Field(None, max_length=100)
+
+
+class AppRunRequest(BaseModel):
+    inputs: dict[str, Any]
+    query: str | None = None
+    files: list[dict[str, Any]] | None = None
+    conversation_id: UUIDStrOrEmpty | None = None
+    auto_generate_name: bool = True
+    workflow_id: str | None = None
+    workspace_id: UUIDStrOrEmpty | None = None
+
+    @field_validator("conversation_id", mode="before")
+    @classmethod
+    def _normalize_conv(cls, value: str | None) -> str | None:
+        if isinstance(value, str):
+            value = value.strip()
+        if not value:
+            return None
+        try:
+            return uuid_value(value)
+        except ValueError as exc:
+            raise ValueError("conversation_id must be a valid UUID") from exc
+
+
+class DeviceCodeRequest(BaseModel):
+    client_id: str
+    device_label: str
+
+
+class DevicePollRequest(BaseModel):
+    device_code: str
+    client_id: str
+
+
+class DeviceLookupQuery(BaseModel):
+    user_code: str
+
+
+class DeviceMutateRequest(BaseModel):
+    user_code: str
+
+
+class PermittedExternalAppsListQuery(BaseModel):
+    """Strict (extra='forbid')."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    page: int = Field(1, ge=1)
+    limit: int = Field(20, ge=1, le=MAX_PAGE_LIMIT)
+    mode: AppMode | None = None
+    name: str | None = Field(None, max_length=200)
+
+
+_EMAIL_FIELD = Field(min_length=3, max_length=320, pattern=r"^[^@\s]+@[^@\s]+$")
+
+
+class ExtSubjectAssertionClaims(BaseModel):
+    email: str = _EMAIL_FIELD
+    issuer: str = Field(min_length=1, max_length=255)
+    user_code: str = Field(min_length=1, max_length=32)
+    nonce: str = Field(min_length=1, max_length=128)
+
+
+class ApprovalGrantClaimsPayload(BaseModel):
+    subject_email: str = _EMAIL_FIELD
+    subject_issuer: str = Field(min_length=1, max_length=255)
+    user_code: str = Field(min_length=1, max_length=32)
+    nonce: str = Field(min_length=1, max_length=128)
+    csrf_token: str = Field(min_length=1, max_length=128)

api/controllers/openapi/account.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from flask import request
+from flask_restx import Resource
+from werkzeug.exceptions import BadRequest, NotFound
+
+from controllers.openapi import openapi_ns
+from controllers.openapi._models import (
+    MAX_PAGE_LIMIT,
+    AccountPayload,
+    AccountResponse,
+    PaginationEnvelope,
+    RevokeResponse,
+    SessionListResponse,
+    SessionRow,
+    WorkspacePayload,
+)
+from extensions.ext_database import db
+from extensions.ext_redis import redis_client
+from libs.oauth_bearer import (
+    ACCEPT_USER_ANY,
+    AuthContext,
+    SubjectType,
+    get_auth_ctx,
+    validate_bearer,
+)
+from libs.rate_limit import (
+    LIMIT_ME_PER_ACCOUNT,
+    LIMIT_ME_PER_EMAIL,
+    enforce,
+)
+from services.account_service import AccountService, TenantService
+from services.oauth_device_flow import (
+    list_active_sessions,
+    revoke_oauth_token,
+    token_belongs_to_subject,
+)
+
+
+@openapi_ns.route("/account")
+class AccountApi(Resource):
+    @openapi_ns.response(200, "Account info", openapi_ns.models[AccountResponse.__name__])
+    @validate_bearer(accept=ACCEPT_USER_ANY)
+    def get(self):
+        ctx = get_auth_ctx()
+
+        if ctx.subject_type == SubjectType.EXTERNAL_SSO:
+            enforce(LIMIT_ME_PER_EMAIL, key=f"subject:{ctx.subject_email}")
+        else:
+            enforce(LIMIT_ME_PER_ACCOUNT, key=f"account:{ctx.account_id}")
+
+        if ctx.subject_type == SubjectType.EXTERNAL_SSO:
+            return AccountResponse(
+                subject_type=ctx.subject_type,
+                subject_email=ctx.subject_email,
+                subject_issuer=ctx.subject_issuer,
+                account=None,
+                workspaces=[],
+                default_workspace_id=None,
+            ).model_dump(mode="json")
+
+        account = AccountService.get_account_by_id(db.session, str(ctx.account_id)) if ctx.account_id else None
+        memberships = TenantService.get_account_memberships(db.session, str(ctx.account_id)) if ctx.account_id else []
+        default_ws_id = _pick_default_workspace(memberships)
+
+        return AccountResponse(
+            subject_type=ctx.subject_type,
+            subject_email=ctx.subject_email or (account.email if account else None),
+            account=_account_payload(account) if account else None,
+            workspaces=[_workspace_payload(m) for m in memberships],
+            default_workspace_id=default_ws_id,
+        ).model_dump(mode="json")
+
+
+@openapi_ns.route("/account/sessions/self")
+class AccountSessionsSelfApi(Resource):
+    @openapi_ns.response(200, "Session revoked", openapi_ns.models[RevokeResponse.__name__])
+    @validate_bearer(accept=ACCEPT_USER_ANY)
+    def delete(self):
+        ctx = get_auth_ctx()
+        _require_oauth_subject(ctx)
+        revoke_oauth_token(db.session, redis_client, str(ctx.token_id))
+        return RevokeResponse(status="revoked").model_dump(mode="json"), 200
+
+
+@openapi_ns.route("/account/sessions")
+class AccountSessionsApi(Resource):
+    @openapi_ns.response(200, "Session list", openapi_ns.models[SessionListResponse.__name__])
+    @validate_bearer(accept=ACCEPT_USER_ANY)
+    def get(self):
+        ctx = get_auth_ctx()
+        now = datetime.now(UTC)
+        page = int(request.args.get("page", "1"))
+        limit = min(int(request.args.get("limit", "100")), MAX_PAGE_LIMIT)
+
+        all_rows = list_active_sessions(db.session, ctx, now)
+
+        total = len(all_rows)
+        sliced = all_rows[(page - 1) * limit : page * limit]
+
+        items = [
+            SessionRow(
+                id=str(r.id),
+                prefix=r.prefix,
+                client_id=r.client_id,
+                device_label=r.device_label,
+                created_at=_iso(r.created_at),
+                last_used_at=_iso(r.last_used_at),
+                expires_at=_iso(r.expires_at),
+            )
+            for r in sliced
+        ]
+
+        return (
+            PaginationEnvelope.build(page=page, limit=limit, total=total, items=items).model_dump(mode="json"),
+            200,
+        )
+
+
+@openapi_ns.route("/account/sessions/<string:session_id>")
+class AccountSessionByIdApi(Resource):
+    @openapi_ns.response(200, "Session revoked", openapi_ns.models[RevokeResponse.__name__])
+    @validate_bearer(accept=ACCEPT_USER_ANY)
+    def delete(self, session_id: str):
+        ctx = get_auth_ctx()
+        _require_oauth_subject(ctx)
+
+        # 404 (not 403) on cross-subject so the endpoint doesn't leak
+        # token IDs that belong to other subjects.
+        if not token_belongs_to_subject(db.session, session_id, ctx):
+            raise NotFound("session not found")
+
+        revoke_oauth_token(db.session, redis_client, session_id)
+        return RevokeResponse(status="revoked").model_dump(mode="json"), 200
+
+
+def _require_oauth_subject(ctx: AuthContext) -> None:
+    if not ctx.source.startswith("oauth"):
+        raise BadRequest(
+            "this endpoint revokes OAuth bearer tokens; use /openapi/v1/personal-access-tokens/self for PATs"
+        )
+
+
+def _iso(dt: datetime | None) -> str | None:
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+def _pick_default_workspace(memberships) -> str | None:
+    if not memberships:
+        return None
+    for join, tenant in memberships:
+        if getattr(join, "current", False):
+            return str(tenant.id)
+    return str(memberships[0][1].id)
+
+
+def _workspace_payload(row) -> WorkspacePayload:
+    join, tenant = row
+    return WorkspacePayload(id=str(tenant.id), name=tenant.name, role=getattr(join, "role", ""))
+
+
+def _account_payload(account) -> AccountPayload:
+    return AccountPayload(id=str(account.id), email=account.email, name=account.name)

api/controllers/openapi/app_run.py

@@ -0,0 +1,165 @@
+"""POST /openapi/v1/apps/<app_id>/run — mode-agnostic runner."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from flask import request
+from flask_restx import Resource
+from pydantic import ValidationError
+from werkzeug.exceptions import BadRequest, HTTPException, InternalServerError, NotFound, UnprocessableEntity
+
+import services
+from controllers.openapi import openapi_ns
+from controllers.openapi._audit import emit_app_run
+from controllers.openapi._models import AppRunRequest
+from controllers.openapi.auth.composition import OAUTH_BEARER_PIPELINE
+from controllers.service_api.app.error import (
+    AppUnavailableError,
+    CompletionRequestError,
+    ConversationCompletedError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
+from core.app.apps.base_app_queue_manager import AppQueueManager
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.errors.error import (
+    ModelCurrentlyNotSupportError,
+    ProviderTokenNotInitError,
+    QuotaExceededError,
+)
+from extensions.ext_redis import redis_client
+from graphon.graph_engine.manager import GraphEngineManager
+from graphon.model_runtime.errors.invoke import InvokeError
+from libs import helper
+from libs.oauth_bearer import Scope
+from models.model import App, AppMode
+from services.app_generate_service import AppGenerateService
+from services.errors.app import (
+    IsDraftWorkflowError,
+    WorkflowIdFormatError,
+    WorkflowNotFoundError,
+)
+from services.errors.llm import InvokeRateLimitError
+
+logger = logging.getLogger(__name__)
+
+
+@contextmanager
+def _translate_service_errors() -> Iterator[None]:
+    try:
+        yield
+    except WorkflowNotFoundError as ex:
+        raise NotFound(str(ex))
+    except (IsDraftWorkflowError, WorkflowIdFormatError) as ex:
+        raise BadRequest(str(ex))
+    except services.errors.conversation.ConversationNotExistsError:
+        raise NotFound("Conversation Not Exists.")
+    except services.errors.conversation.ConversationCompletedError:
+        raise ConversationCompletedError()
+    except services.errors.app_model_config.AppModelConfigBrokenError:
+        logger.exception("App model config broken.")
+        raise AppUnavailableError()
+    except ProviderTokenNotInitError as ex:
+        raise ProviderNotInitializeError(ex.description)
+    except QuotaExceededError:
+        raise ProviderQuotaExceededError()
+    except ModelCurrentlyNotSupportError:
+        raise ProviderModelCurrentlyNotSupportError()
+    except InvokeRateLimitError as ex:
+        raise InvokeRateLimitHttpError(ex.description)
+    except InvokeError as e:
+        raise CompletionRequestError(e.description)
+
+
+def _generate(app: App, caller: Any, args: dict[str, Any], streaming: bool):
+    return AppGenerateService.generate(
+        app_model=app,
+        user=caller,
+        args=args,
+        invoke_from=InvokeFrom.OPENAPI,
+        streaming=streaming,
+    )
+
+
+def _run_chat(app: App, caller: Any, payload: AppRunRequest):
+    if not payload.query or not payload.query.strip():
+        raise UnprocessableEntity("query_required_for_chat")
+    args = payload.model_dump(exclude_none=True)
+    with _translate_service_errors():
+        return _generate(app, caller, args, streaming=True)
+
+
+def _run_completion(app: App, caller: Any, payload: AppRunRequest):
+    args = payload.model_dump(exclude_none=True)
+    args["auto_generate_name"] = False
+    args.setdefault("query", "")
+    with _translate_service_errors():
+        return _generate(app, caller, args, streaming=True)
+
+
+def _run_workflow(app: App, caller: Any, payload: AppRunRequest):
+    if payload.query is not None:
+        raise UnprocessableEntity("query_not_supported_for_workflow")
+    args = payload.model_dump(exclude={"query", "conversation_id", "auto_generate_name"}, exclude_none=True)
+    with _translate_service_errors():
+        return _generate(app, caller, args, streaming=True)
+
+
+_DISPATCH: dict[AppMode, Callable[[App, Any, AppRunRequest], Any]] = {
+    AppMode.CHAT: _run_chat,
+    AppMode.AGENT_CHAT: _run_chat,
+    AppMode.ADVANCED_CHAT: _run_chat,
+    AppMode.COMPLETION: _run_completion,
+    AppMode.WORKFLOW: _run_workflow,
+}
+
+
+@openapi_ns.route("/apps/<string:app_id>/run")
+class AppRunApi(Resource):
+    @openapi_ns.expect(openapi_ns.models[AppRunRequest.__name__])
+    @openapi_ns.response(200, "Run result (SSE stream)")
+    @OAUTH_BEARER_PIPELINE.guard(scope=Scope.APPS_RUN)
+    def post(self, app_id: str, app_model: App, caller, caller_kind: str):
+        body = request.get_json(silent=True) or {}
+        try:
+            payload = AppRunRequest.model_validate(body)
+        except ValidationError as exc:
+            raise UnprocessableEntity(exc.json())
+
+        handler = _DISPATCH.get(app_model.mode)
+        if handler is None:
+            raise UnprocessableEntity("mode_not_runnable")
+
+        try:
+            stream_obj = handler(app_model, caller, payload)
+        except HTTPException:
+            raise
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+        emit_app_run(
+            app_id=app_model.id,
+            tenant_id=app_model.tenant_id,
+            caller_kind=caller_kind,
+            mode=str(app_model.mode),
+            surface="apps",
+        )
+
+        return helper.compact_generate_response(stream_obj)
+
+
+@openapi_ns.route("/apps/<string:app_id>/tasks/<string:task_id>/stop")
+class AppRunTaskStopApi(Resource):
+    @openapi_ns.response(200, "Task stopped")
+    @OAUTH_BEARER_PIPELINE.guard(scope=Scope.APPS_RUN)
+    def post(self, app_id: str, task_id: str, app_model: App, caller, caller_kind: str):
+        AppQueueManager.set_stop_flag_no_user_check(task_id)
+        GraphEngineManager(redis_client).send_stop_command(task_id)
+        return {"result": "success"}

api/controllers/openapi/apps.py

@@ -0,0 +1,270 @@
+"""GET /openapi/v1/apps and per-app reads.
+
+Decorator order: `method_decorators` is innermost-first. `validate_bearer`
+is last → outermost → publishes the auth ContextVar before `require_scope`
+reads it.
+"""
+
+from __future__ import annotations
+
+import uuid as _uuid
+from typing import Any, cast
+
+from flask import request
+from flask_restx import Resource
+from pydantic import ValidationError
+from werkzeug.exceptions import Conflict, NotFound, UnprocessableEntity
+
+from controllers.common.fields import Parameters
+from controllers.common.schema import query_params_from_model
+from controllers.openapi import openapi_ns
+from controllers.openapi._input_schema import EMPTY_INPUT_SCHEMA, build_input_schema, resolve_app_config
+from controllers.openapi._models import (
+    AppDescribeInfo,
+    AppDescribeQuery,
+    AppDescribeResponse,
+    AppListQuery,
+    AppListResponse,
+    AppListRow,
+    TagItem,
+)
+from controllers.openapi.auth.surface_gate import accept_subjects
+from controllers.service_api.app.error import AppUnavailableError
+from core.app.app_config.common.parameters_mapping import get_parameters_from_feature_dict
+from extensions.ext_database import db
+from libs.oauth_bearer import (
+    ACCEPT_USER_ANY,
+    AuthContext,
+    Scope,
+    SubjectType,
+    get_auth_ctx,
+    require_scope,
+    require_workspace_member,
+    validate_bearer,
+)
+from models import App
+from services.account_service import TenantService
+from services.app_service import AppListParams, AppService
+from services.tag_service import TagService
+
+_APPS_READ_DECORATORS = [
+    require_scope(Scope.APPS_READ),
+    accept_subjects(SubjectType.ACCOUNT),
+    validate_bearer(accept=ACCEPT_USER_ANY),
+]
+
+_ALLOWED_DESCRIBE_FIELDS: frozenset[str] = frozenset({"info", "parameters", "input_schema"})
+
+
+_EMPTY_PARAMETERS: dict[str, Any] = {
+    "opening_statement": None,
+    "suggested_questions": [],
+    "user_input_form": [],
+    "file_upload": None,
+    "system_parameters": {},
+}
+
+
+class AppReadResource(Resource):
+    """Base for per-app read endpoints; subclasses call `_load()` for SSO/membership/exists checks."""
+
+    method_decorators = _APPS_READ_DECORATORS
+
+    def _load(self, app_id: str, workspace_id: str | None = None) -> tuple[App, AuthContext]:
+        ctx: AuthContext = get_auth_ctx()
+
+        try:
+            parsed_uuid = _uuid.UUID(app_id)
+            is_uuid = True
+        except ValueError:
+            parsed_uuid = None
+            is_uuid = False
+
+        if is_uuid:
+            # ``str(parsed_uuid)`` normalises to the canonical dashed form.
+            app = AppService.get_visible_app_by_id(db.session, str(parsed_uuid))
+            if app is None:
+                raise NotFound("app not found")
+        else:
+            if not workspace_id:
+                raise UnprocessableEntity("workspace_id is required for name-based lookup")
+            matches = AppService.find_visible_apps_by_name(db.session, name=app_id, tenant_id=workspace_id)
+            if len(matches) == 0:
+                raise NotFound("app not found")
+            if len(matches) > 1:
+                lines = [f"app name {app_id!r} is ambiguous — re-run with a UUID:\n\n"]
+                lines.append(f"  {'ID':<36}  {'MODE':<12}  NAME\n")
+                for m in matches:
+                    lines.append(f"  {str(m.id):<36}  {str(m.mode.value):<12}  {m.name}\n")
+                raise Conflict("".join(lines))
+            app = matches[0]
+
+        require_workspace_member(ctx, str(app.tenant_id))
+        return app, ctx
+
+
+def parameters_payload(app: App) -> dict:
+    """Mirrors service_api/app/app.py::AppParameterApi response body."""
+    features_dict, user_input_form = resolve_app_config(app)
+    parameters = get_parameters_from_feature_dict(features_dict=features_dict, user_input_form=user_input_form)
+    return Parameters.model_validate(parameters).model_dump(mode="json")
+
+
+@openapi_ns.route("/apps/<string:app_id>/describe")
+class AppDescribeApi(AppReadResource):
+    @openapi_ns.doc(params=query_params_from_model(AppDescribeQuery))
+    @openapi_ns.response(200, "App description", openapi_ns.models[AppDescribeResponse.__name__])
+    def get(self, app_id: str):
+        try:
+            query = AppDescribeQuery.model_validate(request.args.to_dict(flat=True))
+        except ValidationError as exc:
+            raise UnprocessableEntity(exc.json())
+
+        app, _ = self._load(app_id, workspace_id=query.workspace_id)
+
+        requested = query.fields
+        want_info = requested is None or "info" in requested
+        want_params = requested is None or "parameters" in requested
+        want_schema = requested is None or "input_schema" in requested
+
+        info = (
+            AppDescribeInfo(
+                id=str(app.id),
+                name=app.name,
+                mode=app.mode,
+                description=app.description,
+                tags=[TagItem(name=t.name) for t in app.tags],
+                author=app.author_name,
+                updated_at=app.updated_at.isoformat() if app.updated_at else None,
+                service_api_enabled=bool(app.enable_api),
+                is_agent=app.mode in ("agent-chat", "advanced-chat"),
+            )
+            if want_info
+            else None
+        )
+
+        parameters: dict[str, Any] | None = None
+        input_schema: dict[str, Any] | None = None
+        if want_params:
+            try:
+                parameters = parameters_payload(app)
+            except AppUnavailableError:
+                parameters = dict(_EMPTY_PARAMETERS)
+        if want_schema:
+            try:
+                input_schema = build_input_schema(app)
+            except AppUnavailableError:
+                input_schema = dict(EMPTY_INPUT_SCHEMA)
+
+        return (
+            AppDescribeResponse(
+                info=info,
+                parameters=parameters,
+                input_schema=input_schema,
+            ).model_dump(mode="json", exclude_none=False),
+            200,
+        )
+
+
+@openapi_ns.route("/apps")
+class AppListApi(Resource):
+    method_decorators = _APPS_READ_DECORATORS
+
+    @openapi_ns.doc(params=query_params_from_model(AppListQuery))
+    @openapi_ns.response(200, "App list", openapi_ns.models[AppListResponse.__name__])
+    def get(self):
+        ctx: AuthContext = get_auth_ctx()
+
+        try:
+            query: AppListQuery = AppListQuery.model_validate(request.args.to_dict(flat=True))
+        except ValidationError as exc:
+            raise UnprocessableEntity(exc.json())
+
+        workspace_id = query.workspace_id
+        require_workspace_member(ctx, workspace_id)
+
+        empty = (
+            AppListResponse(page=query.page, limit=query.limit, total=0, has_more=False, data=[]).model_dump(
+                mode="json"
+            ),
+            200,
+        )
+
+        if query.name:
+            try:
+                parsed_uuid = _uuid.UUID(query.name)
+            except ValueError:
+                parsed_uuid = None
+        else:
+            parsed_uuid = None
+
+        tenant_name: str | None = None
+        if parsed_uuid is not None:
+            app: App | None = AppService.get_visible_app_by_id(db.session, str(parsed_uuid))
+            if app is None or str(app.tenant_id) != workspace_id:
+                return empty
+            tenant_name = TenantService.get_tenant_name(db.session, workspace_id)
+            item = AppListRow(
+                id=str(app.id),
+                name=app.name,
+                description=app.description,
+                mode=app.mode,
+                tags=[TagItem(name=t.name) for t in app.tags],
+                updated_at=app.updated_at.isoformat() if app.updated_at else None,
+                created_by_name=getattr(app, "author_name", None),
+                workspace_id=str(workspace_id),
+                workspace_name=tenant_name,
+            )
+            env = AppListResponse(page=1, limit=1, total=1, has_more=False, data=[item])
+            return env.model_dump(mode="json"), 200
+
+        tag_ids: list[str] | None = None
+        if query.tag:
+            tags = TagService.get_tag_by_tag_name("app", workspace_id, query.tag)
+            if not tags:
+                return empty
+            tag_ids = [tag.id for tag in tags]
+
+        params = AppListParams(
+            page=query.page,
+            limit=query.limit,
+            mode=query.mode.value if query.mode else "all",  # type:ignore
+            name=query.name,
+            tag_ids=tag_ids,
+            status="normal",
+            # Visibility gate pushed into the query — pagination.total stays
+            # consistent across pages because invisible rows never count.
+            openapi_visible=True,
+        )
+
+        pagination = AppService().get_paginate_apps(str(ctx.account_id), workspace_id, params)
+        if pagination is None:
+            return empty
+
+        tenant_name = None
+        if pagination.items:
+            tenant_name = TenantService.get_tenant_name(db.session, workspace_id)
+
+        items = [
+            AppListRow(
+                id=str(r.id),
+                name=r.name,
+                description=r.description,
+                mode=r.mode,
+                tags=[TagItem(name=t.name) for t in r.tags],
+                updated_at=r.updated_at.isoformat() if r.updated_at else None,
+                created_by_name=getattr(r, "author_name", None),
+                workspace_id=str(workspace_id),
+                workspace_name=tenant_name,
+            )
+            for r in pagination.items
+        ]
+
+        env = AppListResponse(
+            page=query.page,
+            limit=query.limit,
+            total=cast(int, pagination.total),
+            has_more=query.page * query.limit < cast(int, pagination.total),
+            data=items,
+        )
+        return env.model_dump(mode="json"), 200

api/controllers/openapi/apps_permitted_external.py

@@ -0,0 +1,102 @@
+"""GET /openapi/v1/permitted-external-apps — external-subject app discovery (EE only).
+
+`dfoe_` (External SSO) callers reach apps gated by ACL access-mode
+(public / sso_verified). License-gated: CE deploys never enable the
+EE blueprint chain so this module is unreachable there.
+"""
+
+from __future__ import annotations
+
+from flask import request
+from flask_restx import Resource
+from pydantic import ValidationError
+from werkzeug.exceptions import UnprocessableEntity
+
+from controllers.openapi import openapi_ns
+from controllers.openapi._models import (
+    AppListRow,
+    PermittedExternalAppsListQuery,
+    PermittedExternalAppsListResponse,
+)
+from controllers.openapi.auth.surface_gate import accept_subjects
+from extensions.ext_database import db
+from libs.device_flow_security import enterprise_only
+from libs.oauth_bearer import (
+    ACCEPT_USER_ANY,
+    Scope,
+    SubjectType,
+    require_scope,
+    validate_bearer,
+)
+from models import App
+from services.account_service import TenantService
+from services.app_service import AppService
+from services.enterprise.app_permitted_service import list_permitted_apps
+from services.openapi.license_gate import license_required
+
+
+@openapi_ns.route("/permitted-external-apps")
+class PermittedExternalAppsListApi(Resource):
+    method_decorators = [
+        require_scope(Scope.APPS_READ_PERMITTED_EXTERNAL),
+        license_required,
+        accept_subjects(SubjectType.EXTERNAL_SSO),
+        validate_bearer(accept=ACCEPT_USER_ANY),
+        enterprise_only,
+    ]
+
+    @openapi_ns.response(
+        200, "Permitted external apps list", openapi_ns.models[PermittedExternalAppsListResponse.__name__]
+    )
+    def get(self):
+        try:
+            query = PermittedExternalAppsListQuery.model_validate(request.args.to_dict(flat=True))
+        except ValidationError as exc:
+            raise UnprocessableEntity(exc.json())
+
+        page_result = list_permitted_apps(
+            page=query.page,
+            limit=query.limit,
+            mode=query.mode.value if query.mode else None,
+            name=query.name,
+        )
+
+        if not page_result.app_ids:
+            env = PermittedExternalAppsListResponse(
+                page=query.page, limit=query.limit, total=page_result.total, has_more=False, data=[]
+            )
+            return env.model_dump(mode="json"), 200
+
+        apps_by_id: dict[str, App] = {
+            str(a.id): a for a in AppService.find_visible_apps_by_ids(db.session, page_result.app_ids)
+        }
+        tenant_ids = list({str(a.tenant_id) for a in apps_by_id.values()})
+        tenants_by_id = {str(t.id): t for t in TenantService.get_tenants_by_ids(db.session, tenant_ids)}
+
+        items: list[AppListRow] = []
+        for app_id in page_result.app_ids:
+            app = apps_by_id.get(app_id)
+            if not app or app.status != "normal":
+                continue
+            tenant = tenants_by_id.get(str(app.tenant_id))
+            items.append(
+                AppListRow(
+                    id=str(app.id),
+                    name=app.name,
+                    description=app.description,
+                    mode=app.mode,
+                    tags=[],  # tenant-scoped; not surfaced cross-tenant
+                    updated_at=app.updated_at.isoformat() if app.updated_at else None,
+                    created_by_name=None,  # cross-tenant author leak prevention
+                    workspace_id=str(app.tenant_id),
+                    workspace_name=tenant.name if tenant else None,
+                )
+            )
+        env = PermittedExternalAppsListResponse(
+            page=query.page,
+            limit=query.limit,
+            total=page_result.total,
+            has_more=query.page * query.limit < page_result.total,
+            data=items,
+        )
+        return env.model_dump(mode="json"), 200

api/controllers/openapi/auth/__init__.py

@@ -0,0 +1,3 @@
+from controllers.openapi.auth.composition import OAUTH_BEARER_PIPELINE
+
+__all__ = ["OAUTH_BEARER_PIPELINE"]

api/controllers/openapi/auth/composition.py

@@ -0,0 +1,46 @@
+"""`OAUTH_BEARER_PIPELINE` — the auth scheme for openapi `/run` endpoints.
+
+Endpoints attach via `@OAUTH_BEARER_PIPELINE.guard(scope=…)`. No alternative
+paths. Read endpoints (`/apps`, `/info`, `/parameters`, `/describe`) skip
+the pipeline and use `validate_bearer + require_scope + require_workspace_member`
+inline — they don't need `AppAuthzCheck`/`CallerMount`.
+"""
+
+from __future__ import annotations
+
+from controllers.openapi.auth.pipeline import Pipeline
+from controllers.openapi.auth.steps import (
+    AppAuthzCheck,
+    AppResolver,
+    BearerCheck,
+    CallerMount,
+    ScopeCheck,
+    SurfaceCheck,
+    WorkspaceMembershipCheck,
+)
+from controllers.openapi.auth.strategies import (
+    AccountMounter,
+    AclStrategy,
+    AppAuthzStrategy,
+    EndUserMounter,
+    MembershipStrategy,
+)
+from libs.oauth_bearer import SubjectType
+from services.feature_service import FeatureService
+
+
+def _resolve_app_authz_strategy() -> AppAuthzStrategy:
+    if FeatureService.get_system_features().webapp_auth.enabled:
+        return AclStrategy()
+    return MembershipStrategy()
+
+
+OAUTH_BEARER_PIPELINE = Pipeline(
+    BearerCheck(),
+    SurfaceCheck(accepted=frozenset({SubjectType.ACCOUNT})),
+    ScopeCheck(),
+    AppResolver(),
+    WorkspaceMembershipCheck(),
+    AppAuthzCheck(_resolve_app_authz_strategy),
+    CallerMount(AccountMounter(), EndUserMounter()),
+)

api/controllers/openapi/auth/context.py

@@ -0,0 +1,68 @@
+"""Mutable per-request context for the openapi auth pipeline.
+
+Every field starts None / empty and is filled in by a step. The pipeline
+is the only thing that should construct or mutate Context — handlers
+read populated values via the decorator's kwargs unpacking.
+
+Context is intentionally decoupled from Flask's ``Request``: the pipeline
+guard extracts whatever transport-level inputs the steps need (bearer
+token, path params) at the boundary and writes them into Context fields,
+so steps stay testable without a request object and won't leak coupling
+to a specific framework.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Mapping
+from contextvars import Token
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Literal, Protocol
+
+from werkzeug.exceptions import Unauthorized
+
+from libs.oauth_bearer import AuthContext, Scope, SubjectType
+
+if TYPE_CHECKING:
+    from models import App, Tenant
+
+
+@dataclass
+class Context:
+    required_scope: Scope
+    bearer_token: str | None = None
+    path_params: Mapping[str, str] = field(default_factory=dict)
+    subject_type: SubjectType | None = None
+    subject_email: str | None = None
+    subject_issuer: str | None = None
+    account_id: uuid.UUID | None = None
+    scopes: frozenset[Scope] = field(default_factory=frozenset)
+    token_id: uuid.UUID | None = None
+    token_hash: str | None = None
+    cached_verified_tenants: dict[str, bool] | None = None
+    source: str | None = None
+    expires_at: datetime | None = None
+    app: App | None = None
+    tenant: Tenant | None = None
+    caller: object | None = None
+    caller_kind: Literal["account", "end_user"] | None = None
+    auth_ctx_reset_token: Token[AuthContext] | None = None
+
+    @property
+    def must_tenant(self) -> Tenant:
+        if not self.tenant:
+            raise Unauthorized("tenant is not associated")
+        return self.tenant
+
+    @property
+    def must_subject_type(self) -> SubjectType:
+        if not self.subject_type:
+            raise Unauthorized("subject_type unset — BearerCheck did not run")
+        return self.subject_type
+
+
+class Step(Protocol):
+    """One responsibility. Mutate ctx or raise to short-circuit."""
+
+    def __call__(self, ctx: Context) -> None: ...

api/controllers/openapi/auth/pipeline.py

@@ -0,0 +1,51 @@
+"""Pipeline IS the auth scheme.
+
+`Pipeline.guard(scope=…)` is the only attachment point for endpoints —
+that is the design lock-in: forgetting an auth layer is structurally
+impossible because there is no "sometimes wrap, sometimes don't" choice.
+"""
+
+from __future__ import annotations
+
+from functools import wraps
+
+from flask import request
+
+from controllers.openapi.auth.context import Context, Step
+from libs.oauth_bearer import Scope, extract_bearer, reset_auth_ctx
+
+
+class Pipeline:
+    def __init__(self, *steps: Step) -> None:
+        self._steps = steps
+
+    def run(self, ctx: Context) -> None:
+        for step in self._steps:
+            step(ctx)
+
+    def guard(self, *, scope: Scope):
+        def decorator(view):
+            @wraps(view)
+            def decorated(*args, **kwargs):
+                # Extract transport-level inputs at the boundary so steps
+                # stay decoupled from Flask's request object.
+                ctx = Context(
+                    required_scope=scope,
+                    bearer_token=extract_bearer(request),
+                    path_params=dict(request.view_args or {}),
+                )
+                try:
+                    self.run(ctx)
+                    kwargs.update(
+                        app_model=ctx.app,
+                        caller=ctx.caller,
+                        caller_kind=ctx.caller_kind,
+                    )
+                    return view(*args, **kwargs)
+                finally:
+                    if ctx.auth_ctx_reset_token is not None:
+                        reset_auth_ctx(ctx.auth_ctx_reset_token)
+
+            return decorated
+
+        return decorator