Merge branch 'main' into codex/page-title-updates

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

.agents/skills/frontend-code-review/SKILL.md

@@ -25,6 +25,7 @@ Before reviewing, read the relevant local contracts:
 - `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md` when code uses or changes `@langgenius/dify-ui/*`.
 - `web/docs/overlay.md` when reviewing dialogs, drawers, popovers, tooltips, menus, selects, comboboxes, or other floating UI.
 - `web/docs/test.md` and the `frontend-testing` skill when reviewing tests or testability.
+- `karpathy-guidelines` for scope control and focused, verifiable changes.
 - `how-to-write-component` when reviewing React component structure, ownership, effects, query/mutation contracts, or memoization.
 
 For any UI, UX, or accessibility review, fetch the latest Web Interface Guidelines before finalizing findings. Treat them as a required baseline, not the complete source of accessibility truth:

.agents/skills/frontend-code-review/references/code-quality.md

@@ -29,10 +29,11 @@ Prefer:
 Flag:
 
 - New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
+- Component-level plain `.css` files or component CSS imported through `globals.css`; use scoped `*.module.css` only when Tailwind and component variants cannot express the style.
 - Generic color utilities where Dify semantic tokens exist.
 - Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist.
 - `!` important modifiers or important CSS overrides without a narrow, documented reason.
-- Manual string concatenation for conditional classes.
+- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes.
 - JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors.
 - Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides.
 - Arbitrary z-index or one-off layering fixes on overlays.
@@ -59,8 +60,9 @@ Flag:
 Flag:
 
 - User-facing hardcoded strings in `web/`.
+- Added or renamed i18n keys that are not present in every supported locale file for the touched namespace.
 - Translation namespace drift, especially using unrelated module namespaces for local feature copy.
 - Generic button labels like `Continue` where the action is specific.
 - Error messages that state only the failure and not the next step.
 
-Use feature-local translation keys by default. Alias only when crossing namespaces.
+Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.

.agents/skills/frontend-code-review/references/component-architecture.md

@@ -18,6 +18,7 @@ Accept repeated TanStack Query calls in siblings when each component independent
 
 Flag:
 
+- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities.
 - Shallow wrappers that only rename props or hide the real primitive.
 - Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration.
 - Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component.
@@ -29,6 +30,7 @@ Prefer colocated components split by actual data and state needs.
 
 Flag:
 
+- Refactors of existing navigation, sidebar, dropdown, webapp list, or app-switching UI that do not preserve behavior-sensitive interactions such as expand/collapse arrows, hover persistence, pin/delete controls, routing, keyboard/focus handling, or open-state ownership.
 - Components that mix data fetching, mutation side effects, popup state, form validation, layout, and row rendering without a clear owner.
 - Generic components with many boolean props that encode one feature's workflow.
 - A shared component that imports feature-specific copy, routes, or API contracts.
@@ -38,6 +40,8 @@ Flag:
 - A component that exposes controlled props but still keeps a competing private state for the same value.
 - A component that cannot render empty, loading, or missing optional API fields without caller-side preprocessing.
 
+When existing components already own interaction logic, prefer reusing or extending them. If a refactor is necessary, preserve the old interaction contract and add or update focused tests for changed behavior.
+
 ## Props And Types
 
 Flag:

.agents/skills/frontend-code-review/references/dify-ui.md

@@ -91,6 +91,7 @@ Use:
 
 Flag:
 
+- Manually recreating UI behavior or chrome already owned by `@langgenius/dify-ui/*` or `web/app/components/base/*`, such as buttons, inputs, toggle groups, popovers, dropdown menus, alert dialogs, switches, avatars, scroll areas, toasts, borders, focus states, disabled states, segmented controls, or existing feature components.
 - Styling a raw Base UI primitive directly in `web/` when a Dify UI primitive exists.
 - Wrapping a Dify UI primitive in a feature component that hides its label, error, disabled, or focus contract.
 - Replacing a semantic primitive with a generic `div` plus classes to match a screenshot.
@@ -121,3 +122,13 @@ Use `!` only for a tightly scoped compatibility override after confirming the pr
 ## Focus Details
 
 Flag focus rings attached to the wrong element. For example, Base UI `Slider.Thumb` focuses an internal `input[type=range]`, so the visible thumb wrapper needs `has-[:focus-visible]` rather than direct wrapper `focus-visible`.
+
+## Custom SVG Icons
+
+Flag:
+
+- New generated React icon components or JSON files under `web/app/components/base/icons/src/...` for custom SVG icons.
+- Custom SVG icons consumed outside the Tailwind `i-custom-*` icon class pipeline.
+- Generated `packages/iconify-collections/custom-*/icons.json` diffs where unrelated existing icons lost or changed intrinsic `width` or `height`.
+
+New custom SVG icons belong in `packages/iconify-collections/assets/...`. Regenerate with `pnpm --filter @dify/iconify-collections generate`, validate with `pnpm --filter @dify/iconify-collections check:dimensions`, and consume the generated icon with Tailwind `i-custom-*` classes.

.agents/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: karpathy-guidelines
+description: Lightweight coding guardrails for making focused, simple, and verifiable changes in this repo. Use for all coding work.
+---
+
+# Karpathy Guidelines
+
+Use this skill whenever you touch code in this repository.
+
+## Principles
+
+- Keep the change small and directly tied to the user request.
+- Prefer the simplest implementation that fits the existing codebase.
+- Read the nearby code first, then match its patterns.
+- Avoid unrelated refactors, broad rewrites, or style churn.
+- Preserve existing behavior unless the user explicitly asked to change it.
+- Treat regressions as a signal to narrow the change, not to add workaround layers.
+
+## Workflow
+
+1. Inspect the current implementation and tests around the change.
+2. Make the smallest coherent edit.
+3. Add or update focused tests when the behavior changes or the risk is non-trivial.
+4. Run the narrowest relevant verification first.
+5. Report exactly what was verified and anything left unverified.
+
+## Review Checklist
+
+- Does this change solve the stated problem without expanding scope?
+- Did it preserve existing route/component/data-flow semantics?
+- Are new abstractions justified by real complexity?
+- Are tests focused on the behavior that could regress?
+- Are unrelated files and generated artifacts left alone?

.claude/skills/karpathy-guidelines

@@ -0,0 +1 @@
+../../.agents/skills/karpathy-guidelines

.github/CODEOWNERS

@@ -23,8 +23,8 @@
 /docs/ @crazywoola
 
 # CLI
-/cli/ @langgenius/maintainers
-/.github/workflows/cli-tests.yml @langgenius/maintainers
+/cli/ @GareArc
+/.github/workflows/cli-tests.yml @GareArc
 
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost

.github/workflows/cli-e2e.yml

@@ -0,0 +1,415 @@
+name: CLI E2E Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      cli_ref:
+        description: "Git ref (default: current branch)"
+        type: string
+        required: false
+
+      edition:
+        description: "Dify edition"
+        type: choice
+        required: false
+        default: ee
+        options: [ee, ce]
+
+      test_scope:
+        description: "smoke = [P0] only  /  full = all cases"
+        type: choice
+        required: false
+        default: full
+        options: [smoke, full]
+
+      # ── Suite on/off ────────────────────────────────────────────────────────
+      suite_framework_output_error:
+        description: "framework + output + error-handling suites"
+        type: boolean
+        default: true
+      suite_discovery:
+        description: "discovery suite (get app / describe app)"
+        type: boolean
+        default: true
+      suite_run:
+        description: "run suite (basic / streaming / conversation / file / hitl)"
+        type: boolean
+        default: true
+      suite_auth:
+        description: "auth suite (login / status / whoami / use / devices / logout)"
+        type: boolean
+        default: true
+      suite_agent:
+        description: "agent suite"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+# ── Shared env injected into every E2E job ───────────────────────────────────
+# Each job reads DIFY_E2E_TOKEN + app IDs from the provision job outputs,
+# so global-setup skips minting and finds existing apps in < 10 s.
+env:
+  DIFY_E2E_NO_KEYRING: "1"   # Linux CI has no keychain; skip probe
+  VITEST_RETRY:        "2"    # Retry flaky staging responses
+
+jobs:
+
+# ════════════════════════════════════════════════════════════════════════════
+# 0. PROVISION — mint token + import DSL fixtures (runs once, outputs IDs)
+# ════════════════════════════════════════════════════════════════════════════
+  provision:
+    name: "Provision: mint token + DSL apps"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      token:                      ${{ steps.out.outputs.DIFY_E2E_TOKEN }}
+      workspace_id:               ${{ steps.out.outputs.DIFY_E2E_WORKSPACE_ID }}
+      workspace_name:             ${{ steps.out.outputs.DIFY_E2E_WORKSPACE_NAME }}
+      ws2_id:                     ${{ steps.out.outputs.DIFY_E2E_WS2_ID }}
+      chat_app_id:                ${{ steps.out.outputs.DIFY_E2E_CHAT_APP_ID }}
+      workflow_app_id:            ${{ steps.out.outputs.DIFY_E2E_WORKFLOW_APP_ID }}
+      file_app_id:                ${{ steps.out.outputs.DIFY_E2E_FILE_APP_ID }}
+      file_chat_app_id:           ${{ steps.out.outputs.DIFY_E2E_FILE_CHAT_APP_ID }}
+      hitl_app_id:                ${{ steps.out.outputs.DIFY_E2E_HITL_APP_ID }}
+      hitl_external_app_id:       ${{ steps.out.outputs.DIFY_E2E_HITL_EXTERNAL_APP_ID }}
+      hitl_single_action_app_id:  ${{ steps.out.outputs.DIFY_E2E_HITL_SINGLE_ACTION_APP_ID }}
+      hitl_multi_node_app_id:     ${{ steps.out.outputs.DIFY_E2E_HITL_MULTI_NODE_APP_ID }}
+      ws2_app_id:                 ${{ steps.out.outputs.DIFY_E2E_WS2_APP_ID }}
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          package_json_field: packageManager
+          run_install: false
+
+      - name: Install CLI dependencies
+        working-directory: cli
+        run: pnpm install --frozen-lockfile
+
+      - name: Mint token & provision apps
+        id: out
+        working-directory: cli
+        env:
+          DIFY_E2E_HOST:     ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:    ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD: ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_TOKEN:    ${{ secrets.DIFY_E2E_TOKEN }}
+          DIFY_E2E_EDITION:  ${{ inputs.edition || 'ee' }}
+        run: bun scripts/e2e-provision.ts
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-B. framework + output + error-handling (parallel with run/discovery)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-framework-output-error:
+    name: "Suite: framework + output + error-handling"
+    if: ${{ inputs.suite_framework_output_error != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run framework + output + error-handling
+        env:
+          DIFY_E2E_HOST:           ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:          ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:       ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:        ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:          ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:   ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME: ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_CHAT_APP_ID:    ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID: ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/framework/**/*.e2e.ts,test/e2e/suites/output/**/*.e2e.ts,test/e2e/suites/error-handling/**/*.e2e.ts"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-C. Discovery (parallel)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-discovery:
+    name: "Suite: discovery"
+    if: ${{ inputs.suite_discovery != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run discovery suite
+        env:
+          DIFY_E2E_HOST:           ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:          ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:       ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:        ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:          ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:   ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME: ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_WS2_ID:         ${{ needs.provision.outputs.ws2_id }}
+          DIFY_E2E_CHAT_APP_ID:    ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID: ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/discovery/**/*.e2e.ts"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-D. Run suite — 5 files in matrix (parallel)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-run:
+    name: "Suite: run / ${{ matrix.name }}"
+    if: ${{ inputs.suite_run != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: basic
+            file: run-app-basic.e2e.ts
+          - name: streaming
+            file: run-app-streaming.e2e.ts
+          - name: conversation
+            file: run-app-conversation.e2e.ts
+          - name: file
+            file: run-app-file.e2e.ts
+          - name: hitl
+            file: run-app-hitl.e2e.ts
+
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: "Run run/${{ matrix.name }}"
+        env:
+          DIFY_E2E_HOST:                      ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:                     ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:                  ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:                   ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_SSO_TOKEN:                 ${{ secrets.DIFY_E2E_SSO_TOKEN }}
+          DIFY_E2E_TOKEN:                     ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:              ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME:            ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_CHAT_APP_ID:               ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID:           ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_FILE_APP_ID:               ${{ needs.provision.outputs.file_app_id }}
+          DIFY_E2E_FILE_CHAT_APP_ID:          ${{ needs.provision.outputs.file_chat_app_id }}
+          DIFY_E2E_HITL_APP_ID:               ${{ needs.provision.outputs.hitl_app_id }}
+          DIFY_E2E_HITL_EXTERNAL_APP_ID:      ${{ needs.provision.outputs.hitl_external_app_id }}
+          DIFY_E2E_HITL_SINGLE_ACTION_APP_ID: ${{ needs.provision.outputs.hitl_single_action_app_id }}
+          DIFY_E2E_HITL_MULTI_NODE_APP_ID:    ${{ needs.provision.outputs.hitl_multi_node_app_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/run/${{ matrix.file }}"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+      - name: Upload results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-run-${{ matrix.name }}-${{ github.run_id }}
+          path: cli/test-results/
+          retention-days: 3
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1-E. auth/login + status + whoami (parallel, read-only, safe)
+# ════════════════════════════════════════════════════════════════════════════
+  suite-auth-safe:
+    name: "Suite: auth (login / status / whoami)"
+    if: ${{ inputs.suite_auth != 'false' }}
+    needs: provision
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run auth/login + status + whoami
+        env:
+          DIFY_E2E_HOST:           ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:          ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:       ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:        ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:          ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:   ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME: ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_WS2_ID:         ${{ needs.provision.outputs.ws2_id }}
+          DIFY_E2E_INCLUDE: "test/e2e/suites/auth/login.e2e.ts,test/e2e/suites/auth/status.e2e.ts,test/e2e/suites/auth/whoami.e2e.ts"
+        run: |
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            pnpm test:e2e -- -t "\[P0\]"
+          else
+            pnpm test:e2e
+          fi
+
+# ════════════════════════════════════════════════════════════════════════════
+# 2. DESTRUCTIVE — auth/use + devices + logout + agent (serial, runs LAST)
+#    Must wait for ALL parallel suites to finish to avoid token revocation
+#    invalidating other in-flight requests.
+# ════════════════════════════════════════════════════════════════════════════
+  suite-last:
+    name: "Suite: auth-use + devices + logout + agent (last, serial)"
+    # Runs when auth is selected; also runs after all parallel jobs finish
+    if: ${{ inputs.suite_auth != 'false' || inputs.suite_agent != 'false' }}
+    needs:
+      - provision
+      - suite-framework-output-error
+      - suite-discovery
+      - suite-run
+      - suite-auth-safe
+    # `needs` on a skipped job is treated as success — safe to proceed even if
+    # some suites were disabled via toggle.
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    defaults:
+      run:
+        working-directory: cli
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-web
+      - uses: oven-sh/setup-bun@v2
+        with: { bun-version: latest }
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with: { package_json_field: packageManager, run_install: false }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm tree:gen
+
+      - name: Run use / devices / logout / agent (serial)
+        env:
+          DIFY_E2E_HOST:                      ${{ secrets.DIFY_E2E_HOST }}
+          DIFY_E2E_EMAIL:                     ${{ secrets.DIFY_E2E_EMAIL }}
+          DIFY_E2E_PASSWORD:                  ${{ secrets.DIFY_E2E_PASSWORD }}
+          DIFY_E2E_EDITION:                   ${{ inputs.edition || 'ee' }}
+          DIFY_E2E_TOKEN:                     ${{ needs.provision.outputs.token }}
+          DIFY_E2E_WORKSPACE_ID:              ${{ needs.provision.outputs.workspace_id }}
+          DIFY_E2E_WORKSPACE_NAME:            ${{ needs.provision.outputs.workspace_name }}
+          DIFY_E2E_WS2_ID:                    ${{ needs.provision.outputs.ws2_id }}
+          DIFY_E2E_CHAT_APP_ID:               ${{ needs.provision.outputs.chat_app_id }}
+          DIFY_E2E_WORKFLOW_APP_ID:           ${{ needs.provision.outputs.workflow_app_id }}
+          DIFY_E2E_HITL_APP_ID:               ${{ needs.provision.outputs.hitl_app_id }}
+          DIFY_E2E_HITL_EXTERNAL_APP_ID:      ${{ needs.provision.outputs.hitl_external_app_id }}
+          DIFY_E2E_HITL_SINGLE_ACTION_APP_ID: ${{ needs.provision.outputs.hitl_single_action_app_id }}
+          DIFY_E2E_HITL_MULTI_NODE_APP_ID:    ${{ needs.provision.outputs.hitl_multi_node_app_id }}
+        run: |
+          # Collect files in safe order: use → devices → logout (revokes last) → agent
+          FILES=()
+          if [ "${{ inputs.suite_auth }}" = "true" ]; then
+            FILES+=(
+              test/e2e/suites/auth/use.e2e.ts
+              test/e2e/suites/auth/devices.e2e.ts
+              test/e2e/suites/auth/logout.e2e.ts
+            )
+          fi
+          if [ "${{ inputs.suite_agent }}" = "true" ]; then
+            while IFS= read -r f; do FILES+=("$f"); done \
+              < <(find test/e2e/suites/agent -name '*.e2e.ts' | sort)
+          fi
+
+          [ ${#FILES[@]} -eq 0 ] && { echo "Nothing to run."; exit 0; }
+
+          # Pass files via DIFY_E2E_INCLUDE (comma-separated) so vitest
+          # config's include list is overridden instead of ANDed.
+          INCLUDE=$(IFS=,; echo "${FILES[*]}")
+          if [ "${{ inputs.test_scope }}" = "smoke" ]; then
+            DIFY_E2E_INCLUDE="$INCLUDE" pnpm test:e2e -- -t "\[P0\]"
+          else
+            DIFY_E2E_INCLUDE="$INCLUDE" pnpm test:e2e
+          fi
+
+      - name: Upload results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-last-${{ github.run_id }}
+          path: cli/test-results/
+          retention-days: 3

.github/workflows/cli-tests.yml

@@ -37,12 +37,17 @@ jobs:
       - name: Setup web environment
         uses: ./.github/actions/setup-web
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
       - name: Validate release manifest
         if: matrix.os == 'depot-ubuntu-24.04'
         run: scripts/release-validate-manifest.sh
 
       - name: CI pipeline (typecheck, lint, coverage, build)
-        run: pnpm ci
+        run: pnpm run ci
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' && matrix.os == 'depot-ubuntu-24.04' }}

api/app.py

@@ -55,7 +55,7 @@ else:
 
 if __name__ == "__main__":
     from gevent import pywsgi
-    from geventwebsocket.handler import WebSocketHandler  # type: ignore[reportMissingTypeStubs]
+    from geventwebsocket.handler import WebSocketHandler
 
     log_startup_banner(HOST, PORT)
     server = pywsgi.WSGIServer((HOST, PORT), socketio_app, handler_class=WebSocketHandler)

api/app_factory.py

@@ -1,7 +1,7 @@
 import logging
 import time
 
-import socketio  # type: ignore[reportMissingTypeStubs]
+import socketio
 from flask import request
 from opentelemetry.trace import get_current_span
 from opentelemetry.trace.span import INVALID_SPAN_ID, INVALID_TRACE_ID

api/celery_entrypoint.py

@@ -1,5 +1,5 @@
-import psycogreen.gevent as pscycogreen_gevent  # type: ignore
-from grpc.experimental import gevent as grpc_gevent  # type: ignore
+import psycogreen.gevent as pscycogreen_gevent
+from grpc.experimental import gevent as grpc_gevent
 
 # grpc gevent
 grpc_gevent.init_gevent()

api/clients/agent_backend/__init__.py

@@ -5,6 +5,8 @@ API adapters: request building from Dify product concepts, a thin client wrapper
 event adaptation for future workflow integration, and deterministic fakes.
 """
 
+from dify_agent.protocol import RuntimeLayerSpec, extract_runtime_layer_specs
+
 from clients.agent_backend.client import AgentBackendRunClient, DifyAgentBackendRunClient
 from clients.agent_backend.errors import (
     AgentBackendError,
@@ -16,12 +18,12 @@ from clients.agent_backend.errors import (
     AgentBackendValidationError,
 )
 from clients.agent_backend.event_adapter import (
+    AgentBackendDeferredToolCallInternalEvent,
     AgentBackendInternalEvent,
     AgentBackendInternalEventType,
     AgentBackendRunCancelledInternalEvent,
     AgentBackendRunEventAdapter,
     AgentBackendRunFailedInternalEvent,
-    AgentBackendRunPausedInternalEvent,
     AgentBackendRunStartedInternalEvent,
     AgentBackendRunSucceededInternalEvent,
     AgentBackendStreamInternalEvent,
@@ -39,8 +41,6 @@ from clients.agent_backend.request_builder import (
     AgentBackendOutputConfig,
     AgentBackendRunRequestBuilder,
     AgentBackendWorkflowNodeRunInput,
-    CleanupLayerSpec,
-    extract_cleanup_layer_specs,
     redact_for_agent_backend_log,
 )
 
@@ -51,6 +51,7 @@ __all__ = [
     "WORKFLOW_NODE_JOB_PROMPT_LAYER_ID",
     "WORKFLOW_USER_PROMPT_LAYER_ID",
     "AgentBackendAgentAppRunInput",
+    "AgentBackendDeferredToolCallInternalEvent",
     "AgentBackendError",
     "AgentBackendHTTPError",
     "AgentBackendInternalEvent",
@@ -63,7 +64,6 @@ __all__ = [
     "AgentBackendRunEventAdapter",
     "AgentBackendRunFailedError",
     "AgentBackendRunFailedInternalEvent",
-    "AgentBackendRunPausedInternalEvent",
     "AgentBackendRunRequestBuilder",
     "AgentBackendRunStartedInternalEvent",
     "AgentBackendRunSucceededInternalEvent",
@@ -72,11 +72,11 @@ __all__ = [
     "AgentBackendTransportError",
     "AgentBackendValidationError",
     "AgentBackendWorkflowNodeRunInput",
-    "CleanupLayerSpec",
     "DifyAgentBackendRunClient",
     "FakeAgentBackendRunClient",
     "FakeAgentBackendScenario",
+    "RuntimeLayerSpec",
     "create_agent_backend_run_client",
-    "extract_cleanup_layer_specs",
+    "extract_runtime_layer_specs",
     "redact_for_agent_backend_log",
 ]

api/clients/agent_backend/event_adapter.py

@@ -2,7 +2,9 @@
 
 The adapter does not define a new cross-service event contract. It consumes
 ``dify_agent.protocol.RunEvent`` and produces small API-internal models that the
-future workflow Agent Node can map to Graphon/AppQueue events in phase 3.
+workflow Agent Node maps to Graphon/AppQueue events. Deferred external tool calls
+remain Dify Agent ``run_succeeded`` payloads on the wire; API code turns them
+into an internal event so workflow pause/session handling stays local to API.
 """
 
 from __future__ import annotations
@@ -12,11 +14,11 @@ from typing import Annotated, Literal, cast
 
 from agenton.compositor import CompositorSessionSnapshot
 from dify_agent.protocol import (
+    DeferredToolCallPayload,
     PydanticAIStreamRunEvent,
     RunCancelledEvent,
     RunEvent,
     RunFailedEvent,
-    RunPausedEvent,
     RunStartedEvent,
     RunSucceededEvent,
 )
@@ -30,7 +32,7 @@ class AgentBackendInternalEventType(StrEnum):
 
     RUN_STARTED = "run_started"
     STREAM_EVENT = "stream_event"
-    RUN_PAUSED = "run_paused"
+    DEFERRED_TOOL_CALL = "deferred_tool_call"
     RUN_SUCCEEDED = "run_succeeded"
     RUN_FAILED = "run_failed"
     RUN_CANCELLED = "run_cancelled"
@@ -67,13 +69,13 @@ class AgentBackendRunSucceededInternalEvent(AgentBackendInternalEventBase):
     session_snapshot: CompositorSessionSnapshot
 
 
-class AgentBackendRunPausedInternalEvent(AgentBackendInternalEventBase):
-    """API-internal resumable pause event for human handoff and Babysit flows."""
+class AgentBackendDeferredToolCallInternalEvent(AgentBackendInternalEventBase):
+    """API-internal representation of a Dify Agent deferred external tool call."""
 
-    type: Literal[AgentBackendInternalEventType.RUN_PAUSED] = AgentBackendInternalEventType.RUN_PAUSED
-    reason: str
+    type: Literal[AgentBackendInternalEventType.DEFERRED_TOOL_CALL] = AgentBackendInternalEventType.DEFERRED_TOOL_CALL
+    deferred_tool_call: DeferredToolCallPayload
     message: str | None = None
-    session_snapshot: CompositorSessionSnapshot | None = None
+    session_snapshot: CompositorSessionSnapshot
 
 
 class AgentBackendRunFailedInternalEvent(AgentBackendInternalEventBase):
@@ -95,7 +97,7 @@ class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):
 type AgentBackendInternalEvent = Annotated[
     AgentBackendRunStartedInternalEvent
     | AgentBackendStreamInternalEvent
-    | AgentBackendRunPausedInternalEvent
+    | AgentBackendDeferredToolCallInternalEvent
     | AgentBackendRunSucceededInternalEvent
     | AgentBackendRunFailedInternalEvent
     | AgentBackendRunCancelledInternalEvent,
@@ -128,6 +130,18 @@ class AgentBackendRunEventAdapter:
                     )
                 ]
             case RunSucceededEvent():
+                if "deferred_tool_call" in event.data.model_fields_set:
+                    if event.data.deferred_tool_call is None:
+                        raise TypeError("run_succeeded deferred_tool_call branch is missing payload")
+                    return [
+                        AgentBackendDeferredToolCallInternalEvent(
+                            run_id=event.run_id,
+                            source_event_id=event.id,
+                            deferred_tool_call=event.data.deferred_tool_call,
+                            message=_deferred_tool_call_message(event.data.deferred_tool_call),
+                            session_snapshot=event.data.session_snapshot,
+                        )
+                    ]
                 return [
                     AgentBackendRunSucceededInternalEvent(
                         run_id=event.run_id,
@@ -136,16 +150,6 @@ class AgentBackendRunEventAdapter:
                         session_snapshot=event.data.session_snapshot,
                     )
                 ]
-            case RunPausedEvent():
-                return [
-                    AgentBackendRunPausedInternalEvent(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                        reason=event.data.reason,
-                        message=event.data.message,
-                        session_snapshot=event.data.session_snapshot,
-                    )
-                ]
             case RunFailedEvent():
                 return [
                     AgentBackendRunFailedInternalEvent(
@@ -165,3 +169,18 @@ class AgentBackendRunEventAdapter:
                     )
                 ]
         raise TypeError(f"unsupported agent backend run event: {type(event).__name__}")
+
+
+def _deferred_tool_call_message(payload: DeferredToolCallPayload) -> str:
+    """Return a concise workflow pause message from deferred-tool arguments."""
+    args = payload.args
+    if isinstance(args, dict):
+        question = args.get("question")
+        if isinstance(question, str) and question.strip():
+            return question
+
+        title = args.get("title")
+        if isinstance(title, str) and title.strip():
+            return title
+
+    return f"Agent backend requested external input via deferred tool '{payload.tool_name}'."

api/clients/agent_backend/fake_client.py

@@ -17,11 +17,10 @@ from dify_agent.protocol import (
     CancelRunResponse,
     CreateRunRequest,
     CreateRunResponse,
+    DeferredToolCallPayload,
     RunEvent,
     RunFailedEvent,
     RunFailedEventData,
-    RunPausedEvent,
-    RunPausedEventData,
     RunStartedEvent,
     RunStatusResponse,
     RunSucceededEvent,
@@ -32,7 +31,11 @@ _FIXED_TIME = datetime(2026, 1, 1, tzinfo=UTC)
 
 
 class FakeAgentBackendScenario(StrEnum):
-    """Deterministic fake scenarios for API-side integration tests."""
+    """Deterministic fake scenarios for API-side integration tests.
+
+    ``PAUSED`` represents the API workflow effect. On the Dify Agent wire
+    protocol it is a succeeded run carrying a deferred external tool call.
+    """
 
     SUCCESS = "success"
     FAILED = "failed"
@@ -95,7 +98,7 @@ class FakeAgentBackendRunClient:
             case FakeAgentBackendScenario.PAUSED:
                 return RunStatusResponse(
                     run_id=run_id,
-                    status="paused",
+                    status="succeeded",
                     created_at=_FIXED_TIME,
                     updated_at=_FIXED_TIME,
                 )
@@ -128,13 +131,17 @@ class FakeAgentBackendRunClient:
             case FakeAgentBackendScenario.PAUSED:
                 return (
                     RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),
-                    RunPausedEvent(
+                    RunSucceededEvent(
                         id="2-0",
                         run_id=run_id,
                         created_at=_FIXED_TIME,
-                        data=RunPausedEventData(
-                            reason="human_input_required",
-                            message="Agent requested human input.",
+                        data=RunSucceededEventData(
+                            deferred_tool_call=DeferredToolCallPayload(
+                                tool_call_id="fake-ask-human-1",
+                                tool_name="ask_human",
+                                args={"question": "Agent requested human input."},
+                                metadata={"layer_type": "dify.ask_human", "schema_version": 1},
+                            ),
                             session_snapshot=CompositorSessionSnapshot(layers=[]),
                         ),
                     ),

api/clients/agent_backend/request_builder.py

@@ -11,7 +11,8 @@ composition-driven.
 
 from __future__ import annotations
 
-from typing import ClassVar, cast
+from collections.abc import Mapping
+from typing import ClassVar
 
 from agenton.compositor import CompositorSessionSnapshot
 from agenton.compositor.schemas import LayerSessionSnapshot
@@ -40,6 +41,7 @@ from dify_agent.protocol import (
     RunComposition,
     RunLayerSpec,
     RunPurpose,
+    RuntimeLayerSpec,
 )
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
 
@@ -51,71 +53,10 @@ DIFY_EXECUTION_CONTEXT_LAYER_ID = "execution_context"
 DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"
 DIFY_SHELL_LAYER_ID = "shell"
 
-# Layer types that hold credentials in their per-run config. These are excluded
-# from the cleanup-replay composition (and from the snapshot that is sent with
-# the cleanup request) because we deliberately do not persist plaintext
-# credentials between runs.
-_CLEANUP_EXCLUDED_LAYER_TYPES: tuple[str, ...] = (
-    DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
-    DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-)
-
-
-class CleanupLayerSpec(BaseModel):
-    """One layer node replayed by an Agent backend cleanup-only run.
-
-    Cleanup composition cannot include credential-bearing plugin layers, so we
-    persist only the non-plugin layer specs together with the original config.
-    Storing the config (rather than just ``name``/``type``) means cleanup does
-    not depend on the original build-time inputs being re-derivable.
-    """
-
-    name: str
-    type: str
-    deps: dict[str, str] = Field(default_factory=dict)
-    metadata: dict[str, JsonValue] = Field(default_factory=dict)
-    config: JsonValue = None
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
-def extract_cleanup_layer_specs(composition: RunComposition) -> list[CleanupLayerSpec]:
-    """Project the in-flight composition into the persistable cleanup spec list.
-
-    Plugin layers are intentionally dropped (their configs hold credentials and
-    the lifecycle contract says "do not include an LLM layer" during cleanup).
-    The filtered names must later drive snapshot filtering so the agenton
-    compositor's name-order check still passes for the cleanup run.
-    """
-    excluded = set(_CLEANUP_EXCLUDED_LAYER_TYPES)
-    specs: list[CleanupLayerSpec] = []
-    for layer in composition.layers:
-        if layer.type in excluded:
-            continue
-        config_value: JsonValue = None
-        if isinstance(layer.config, BaseModel):
-            config_value = layer.config.model_dump(mode="json", warnings=False)
-        else:
-            # ``RunLayerSpec.config`` is typed as ``LayerConfigInput`` which
-            # includes ``Mapping[str, object] | bytes``. In the cleanup-replay
-            # pipeline our builder only emits BaseModel-derived configs or
-            # ``None``, so the wider input alias narrows safely here.
-            config_value = cast(JsonValue, layer.config)
-        specs.append(
-            CleanupLayerSpec(
-                name=layer.name,
-                type=layer.type,
-                deps=dict(layer.deps),
-                metadata=dict(layer.metadata),
-                config=config_value,
-            )
-        )
-    return specs
-
 
 def _filter_snapshot_to_specs(
     snapshot: CompositorSessionSnapshot,
-    specs: list[CleanupLayerSpec],
+    specs: list[RuntimeLayerSpec],
 ) -> CompositorSessionSnapshot:
     """Keep only snapshot layers whose names appear in the cleanup spec list.
 
@@ -142,6 +83,30 @@ class AgentBackendModelConfig(BaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
 
 
+# ``DifyPluginLLMLayerConfig.model_settings`` is pydantic_ai's ``ModelSettings``
+# TypedDict (closed: unknown keys are rejected, explicit ``None`` values fail the
+# per-field type checks). Agent Soul model settings carry a wider, nullable shape
+# (``stop`` / ``response_format`` plus null-padded fields), so the layer config
+# only receives the keys the runtime contract accepts.
+_AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS = (
+    "temperature",
+    "top_p",
+    "presence_penalty",
+    "frequency_penalty",
+    "max_tokens",
+)
+
+
+def _agent_model_settings(settings: Mapping[str, JsonValue]) -> dict[str, JsonValue] | None:
+    sanitized: dict[str, JsonValue] = {
+        key: settings[key] for key in _AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS if settings.get(key) is not None
+    }
+    stop = settings.get("stop")
+    if isinstance(stop, list) and stop:
+        sanitized["stop_sequences"] = stop
+    return sanitized or None
+
+
 class AgentBackendOutputConfig(BaseModel):
     """API-side structured output declaration for the conventional output layer.
 
@@ -283,7 +248,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,
+                    model_settings=_agent_model_settings(run_input.model.model_settings),
                 ),
             )
         )
@@ -300,12 +265,14 @@ class AgentBackendRunRequestBuilder:
             )
 
         if run_input.include_shell:
-            # Sandboxed bash workspace (dify.shell). The layer declares NoLayerDeps,
-            # so the spec carries no deps; shellctl connection is server-injected.
+            # Sandboxed bash workspace (dify.shell). Depends on execution_context so
+            # the agent server can mint per-command Agent Stub env (back proxy);
+            # shellctl connection itself is server-injected.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
                     metadata=run_input.metadata,
                     config=run_input.shell_config or DifyShellLayerConfig(),
                 )
@@ -340,7 +307,7 @@ class AgentBackendRunRequestBuilder:
         self,
         *,
         session_snapshot: CompositorSessionSnapshot,
-        composition_layer_specs: list[CleanupLayerSpec],
+        runtime_layer_specs: list[RuntimeLayerSpec],
         idempotency_key: str | None = None,
         metadata: dict[str, JsonValue] | None = None,
     ) -> CreateRunRequest:
@@ -353,9 +320,9 @@ class AgentBackendRunRequestBuilder:
         composition and the snapshot before submission because their configs
         require credentials that are not persisted between runs.
         """
-        if not composition_layer_specs:
+        if not runtime_layer_specs:
             raise ValueError(
-                "build_cleanup_request requires composition_layer_specs; an empty "
+                "build_cleanup_request requires runtime_layer_specs; an empty "
                 "composition would fail the agent backend's snapshot validation."
             )
         request_metadata = dict(metadata or {})
@@ -368,9 +335,9 @@ class AgentBackendRunRequestBuilder:
                 metadata=dict(spec.metadata),
                 config=spec.config,
             )
-            for spec in composition_layer_specs
+            for spec in runtime_layer_specs
         ]
-        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, composition_layer_specs)
+        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, runtime_layer_specs)
         return CreateRunRequest(
             composition=RunComposition(layers=layers),
             purpose="workflow_node",
@@ -437,7 +404,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,
+                        model_settings=_agent_model_settings(run_input.model.model_settings),
                     ),
                 ),
             ]
@@ -455,12 +422,14 @@ class AgentBackendRunRequestBuilder:
             )
 
         if run_input.include_shell:
-            # Sandboxed bash workspace (dify.shell). The layer declares NoLayerDeps,
-            # so the spec carries no deps; shellctl connection is server-injected.
+            # Sandboxed bash workspace (dify.shell). Depends on execution_context so
+            # the agent server can mint per-command Agent Stub env (back proxy);
+            # shellctl connection itself is server-injected.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
                     metadata=run_input.metadata,
                     config=run_input.shell_config or DifyShellLayerConfig(),
                 )

api/clients/agent_backend/workspace_files_client.py

@@ -1,135 +0,0 @@
-"""API-side client for the agent backend's read-only workspace file endpoints.
-
-The agent backend exposes ``/workspaces/{session_id}/files{,/preview,/download}``
-to inspect a shell-layer sandbox workspace. This thin synchronous client proxies
-those reads for the console FS inspector and normalizes transport/HTTP failures
-into the API backend's ``AgentBackendError`` boundary, preserving the backend's
-status code and ``{code, message}`` detail so the controller can relay them.
-"""
-
-from __future__ import annotations
-
-import base64
-import binascii
-from dataclasses import dataclass
-from typing import Literal
-
-import httpx
-from pydantic import BaseModel
-
-from clients.agent_backend.errors import AgentBackendHTTPError, AgentBackendTransportError
-
-_DEFAULT_TIMEOUT_SECONDS = 30.0
-
-
-class WorkspaceFileEntry(BaseModel):
-    """One entry in a workspace directory listing."""
-
-    name: str
-    type: Literal["file", "dir", "symlink"]
-    size: int
-    mtime: int
-
-
-class WorkspaceListResult(BaseModel):
-    """Directory listing of a workspace path."""
-
-    path: str
-    entries: list[WorkspaceFileEntry]
-    truncated: bool
-
-
-class WorkspacePreviewResult(BaseModel):
-    """Inline preview of a workspace file."""
-
-    path: str
-    size: int
-    truncated: bool
-    binary: bool
-    text: str | None = None
-
-
-@dataclass(frozen=True, slots=True)
-class WorkspaceDownloadResult:
-    """Decoded bytes of a workspace file for download."""
-
-    path: str
-    size: int
-    truncated: bool
-    content: bytes
-
-
-class WorkspaceFilesBackendClient:
-    """Synchronous proxy to the agent backend workspace file endpoints."""
-
-    def __init__(
-        self,
-        base_url: str,
-        *,
-        timeout: float = _DEFAULT_TIMEOUT_SECONDS,
-        transport: httpx.BaseTransport | None = None,
-    ) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout = timeout
-        self._transport = transport
-
-    def list_files(self, session_id: str, path: str) -> WorkspaceListResult:
-        data = self._get(f"/workspaces/{session_id}/files", params={"path": path})
-        return WorkspaceListResult.model_validate(data)
-
-    def preview(self, session_id: str, path: str) -> WorkspacePreviewResult:
-        data = self._get(f"/workspaces/{session_id}/files/preview", params={"path": path})
-        return WorkspacePreviewResult.model_validate(data)
-
-    def download(self, session_id: str, path: str) -> WorkspaceDownloadResult:
-        data = self._get(f"/workspaces/{session_id}/files/download", params={"path": path})
-        encoded = data.get("content_base64")
-        if not isinstance(encoded, str):
-            raise AgentBackendHTTPError("agent backend download response missing content", status_code=502, detail=data)
-        try:
-            content = base64.b64decode(encoded, validate=True)
-        except (binascii.Error, ValueError) as exc:
-            raise AgentBackendHTTPError(
-                "agent backend returned undecodable download content", status_code=502, detail=str(exc)
-            ) from exc
-        size = data.get("size")
-        return WorkspaceDownloadResult(
-            path=str(data.get("path", path)),
-            size=int(size) if isinstance(size, (int, float)) else len(content),
-            truncated=bool(data.get("truncated")),
-            content=content,
-        )
-
-    def _get(self, route: str, *, params: dict[str, str]) -> dict[str, object]:
-        url = f"{self._base_url}{route}"
-        try:
-            with httpx.Client(timeout=self._timeout, transport=self._transport, trust_env=False) as client:
-                response = client.get(url, params=params)
-        except httpx.HTTPError as exc:
-            raise AgentBackendTransportError(f"failed to reach agent backend workspace endpoint: {exc}") from exc
-        if response.status_code >= 400:
-            detail: object
-            try:
-                detail = response.json().get("detail", response.text)
-            except ValueError:
-                detail = response.text
-            raise AgentBackendHTTPError(
-                f"agent backend workspace request failed ({response.status_code})",
-                status_code=response.status_code,
-                detail=detail,
-            )
-        body = response.json()
-        if not isinstance(body, dict):
-            raise AgentBackendHTTPError(
-                "agent backend workspace response was not an object", status_code=502, detail=body
-            )
-        return body
-
-
-__all__ = [
-    "WorkspaceDownloadResult",
-    "WorkspaceFileEntry",
-    "WorkspaceFilesBackendClient",
-    "WorkspaceListResult",
-    "WorkspacePreviewResult",
-]

api/commands/data_migrate.py

@@ -145,7 +145,7 @@ def legacy_model_types(
         option_name="--model-types",
     )
     selected_model_types = (
-        tuple(ModelType.value_of(model_type) for model_type in normalized_model_types)
+        tuple(ModelType(model_type) for model_type in normalized_model_types)
         if normalized_model_types
         else (
             ModelType.LLM,

api/configs/feature/__init__.py

@@ -943,9 +943,10 @@ class AuthConfig(BaseSettings):
         default=True,
     )
 
-    OPENAPI_RATE_LIMIT_PER_TOKEN: PositiveInt = Field(
+    OPENAPI_RATE_LIMIT_PER_TOKEN: NonNegativeInt = Field(
         description="Per-token rate limit on /openapi/v1/* (requests per minute). "
-        "Bucket keyed on sha256(token), shared across api replicas via Redis.",
+        "Bucket keyed on sha256(token), shared across api replicas via Redis. "
+        "Set to 0 to disable the per-token limit entirely.",
         default=60,
     )
 

api/context/execution_context.py

@@ -7,7 +7,6 @@ consumes injected context managers when it needs to preserve thread-local state.
 
 import contextvars
 import threading
-from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator
 from contextlib import AbstractContextManager, contextmanager
 from typing import Any, Protocol, final, override, runtime_checkable
@@ -15,28 +14,25 @@ from typing import Any, Protocol, final, override, runtime_checkable
 from pydantic import BaseModel
 
 
-class AppContext(ABC):
+class AppContext(Protocol):
     """
-    Abstract application context interface.
+    Application context interface.
 
     Application adapters can implement this to restore framework-specific state
     such as Flask app context around worker execution.
     """
 
-    @abstractmethod
     def get_config(self, key: str, default: Any = None) -> Any:
         """Get configuration value by key."""
-        raise NotImplementedError
+        ...
 
-    @abstractmethod
     def get_extension(self, name: str) -> Any:
         """Get application extension by name."""
-        raise NotImplementedError
+        ...
 
-    @abstractmethod
     def enter(self) -> AbstractContextManager[None]:
         """Enter the application context."""
-        raise NotImplementedError
+        ...
 
 
 @runtime_checkable

api/controllers/common/controller_schemas.py

@@ -62,7 +62,7 @@ class WorkflowListQuery(BaseModel):
 
 class WorkflowRunPayload(BaseModel):
     inputs: dict[str, Any]
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class WorkflowUpdatePayload(BaseModel):

api/controllers/common/errors.py

@@ -41,3 +41,13 @@ class NoFileUploadedError(BaseHTTPException):
     error_code = "no_file_uploaded"
     description = "Please upload your file."
     code = 400
+
+
+class NotFoundError(BaseHTTPException):
+    error_code = "not_found"
+    code = 404
+
+
+class InvalidArgumentError(BaseHTTPException):
+    error_code = "invalid_param"
+    code = 400

api/controllers/common/fields.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, computed_field
+from pydantic import BaseModel, ConfigDict, Field, RootModel, computed_field
 
 from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
@@ -24,6 +24,34 @@ class SimpleResultResponse(ResponseModel):
     result: str
 
 
+class GeneratedAppResponse(RootModel[JSONValue]):
+    root: JSONValue
+
+
+class EventStreamResponse(RootModel[str]):
+    root: str
+
+
+class TextFileResponse(RootModel[str]):
+    root: str
+
+
+class RedirectResponse(RootModel[str]):
+    root: str
+
+
+class BinaryFileResponse(RootModel[bytes]):
+    root: bytes
+
+
+class AudioBinaryResponse(RootModel[bytes]):
+    root: bytes
+
+
+class AudioTranscriptResponse(ResponseModel):
+    text: str
+
+
 class SimpleResultMessageResponse(ResponseModel):
     result: str
     message: str

api/controllers/common/schema.py

@@ -1,9 +1,9 @@
 """Helpers for registering Pydantic models with Flask-RESTX namespaces.
 
 Flask-RESTX treats `SchemaModel` bodies as opaque JSON schemas; it does not
-promote Pydantic's nested `$defs` into top-level Swagger `definitions`.
+promote Pydantic's nested `$defs` into top-level OpenAPI component schemas.
 These helpers keep that translation centralized so models registered through
-`register_schema_models` emit resolvable Swagger 2.0 references.
+`register_schema_models` emit resolvable OpenAPI 3 references.
 """
 
 from collections.abc import Iterable, Mapping
@@ -14,7 +14,7 @@ from flask import request
 from flask_restx import Namespace
 from pydantic import BaseModel, TypeAdapter
 
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
+DEFAULT_REF_TEMPLATE_OPENAPI_3_0 = "#/components/schemas/{model}"
 
 
 QueryParamDoc = TypedDict(
@@ -27,12 +27,18 @@ QueryParamDoc = TypedDict(
         "description": NotRequired[str],
         "enum": NotRequired[list[object]],
         "default": NotRequired[object],
+        "format": NotRequired[str],
         "minimum": NotRequired[int | float],
         "maximum": NotRequired[int | float],
+        "exclusiveMinimum": NotRequired[int | float],
+        "exclusiveMaximum": NotRequired[int | float],
         "minLength": NotRequired[int],
         "maxLength": NotRequired[int],
+        "pattern": NotRequired[str],
         "minItems": NotRequired[int],
         "maxItems": NotRequired[int],
+        "uniqueItems": NotRequired[bool],
+        "multipleOf": NotRequired[int | float],
     },
 )
 
@@ -48,7 +54,6 @@ class QueryArgs(Protocol):
 def _register_json_schema(namespace: Namespace, name: str, schema: dict) -> None:
     """Register a JSON schema and promote any nested Pydantic `$defs`."""
 
-    schema = _swagger_2_compatible_schema(schema)
     nested_definitions = schema.get("$defs")
     schema_to_register = dict(schema)
     if isinstance(nested_definitions, dict):
@@ -71,41 +76,12 @@ def _register_schema_model(namespace: Namespace, model: type[BaseModel], *, mode
     _register_json_schema(
         namespace,
         model.__name__,
-        model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0, mode=mode),
+        model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0, mode=mode),
     )
 
 
-def _swagger_2_compatible_schema(value: Any) -> Any:
-    if isinstance(value, list):
-        return [_swagger_2_compatible_schema(item) for item in value]
-
-    if not isinstance(value, dict):
-        return value
-
-    converted = {key: _swagger_2_compatible_schema(child) for key, child in value.items()}
-    any_of = value.get("anyOf")
-    if not isinstance(any_of, list):
-        return converted
-
-    non_null_candidates = [
-        candidate for candidate in any_of if isinstance(candidate, Mapping) and candidate.get("type") != "null"
-    ]
-    has_null_candidate = any(isinstance(candidate, Mapping) and candidate.get("type") == "null" for candidate in any_of)
-    if not has_null_candidate or len(non_null_candidates) != 1:
-        return converted
-
-    non_null_schema = _swagger_2_compatible_schema(dict(non_null_candidates[0]))
-    if not isinstance(non_null_schema, dict):
-        return converted
-
-    converted.pop("anyOf", None)
-    converted.update(non_null_schema)
-    converted["x-nullable"] = True
-    return converted
-
-
 def register_schema_model(namespace: Namespace, model: type[BaseModel]) -> None:
-    """Register a BaseModel and its nested schema definitions for Swagger documentation."""
+    """Register a BaseModel and its nested component schemas for OpenAPI documentation."""
 
     _register_schema_model(namespace, model, mode="validation")
 
@@ -146,7 +122,7 @@ def register_enum_models(namespace: Namespace, *models: type[StrEnum]) -> None:
         _register_json_schema(
             namespace,
             model.__name__,
-            TypeAdapter(model).json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
+            TypeAdapter(model).json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
         )
 
 
@@ -155,10 +131,11 @@ def query_params_from_model(model: type[BaseModel]) -> dict[str, QueryParamDoc]:
 
     `Namespace.expect()` treats Pydantic schema models as request bodies, so GET
     endpoints should keep runtime validation on the Pydantic model and feed this
-    derived mapping to `Namespace.doc(params=...)` for Swagger documentation.
+    derived mapping to `Namespace.doc(params=...)` for OpenAPI documentation.
     """
 
-    schema = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0)
+    schema = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0)
+    definitions = _schema_definitions(schema)
     properties = schema.get("properties", {})
     if not isinstance(properties, Mapping):
         return {}
@@ -171,7 +148,11 @@ def query_params_from_model(model: type[BaseModel]) -> dict[str, QueryParamDoc]:
         if not isinstance(name, str) or not isinstance(property_schema, Mapping):
             continue
 
-        params[name] = _query_param_from_property(property_schema, required=name in required_names)
+        params[name] = _query_param_from_property(
+            property_schema,
+            required=name in required_names,
+            definitions=definitions,
+        )
 
     return params
 
@@ -203,7 +184,7 @@ def query_params_from_request[ModelT: BaseModel](
 
 
 def _drop_malformed_defaulted_integer_params(model: type[BaseModel], params: dict[str, Any]) -> None:
-    properties = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0).get("properties", {})
+    properties = model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0).get("properties", {})
     if not isinstance(properties, Mapping):
         return
 
@@ -228,8 +209,18 @@ def _drop_malformed_defaulted_integer_params(model: type[BaseModel], params: dic
             params.pop(name)
 
 
-def _query_param_from_property(property_schema: Mapping[str, Any], *, required: bool) -> QueryParamDoc:
-    param_schema = _nullable_property_schema(property_schema)
+def _schema_definitions(schema: Mapping[str, Any]) -> Mapping[str, Any]:
+    definitions = schema.get("$defs")
+    return definitions if isinstance(definitions, Mapping) else {}
+
+
+def _query_param_from_property(
+    property_schema: Mapping[str, Any],
+    *,
+    required: bool,
+    definitions: Mapping[str, Any],
+) -> QueryParamDoc:
+    param_schema = _resolve_schema_ref(_nullable_property_schema(property_schema), definitions)
     param_doc: QueryParamDoc = {"in": "query", "required": required}
 
     description = param_schema.get("description")
@@ -242,9 +233,16 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
         if schema_type == "array":
             items = param_schema.get("items")
             if isinstance(items, Mapping):
-                item_type = items.get("type")
+                item_schema = _resolve_schema_ref(items, definitions)
+                item_type = item_schema.get("type")
                 if isinstance(item_type, str):
                     param_doc["items"] = {"type": item_type}
+                item_enum = item_schema.get("enum")
+                if isinstance(item_enum, list):
+                    param_doc.setdefault("items", {})["enum"] = item_enum
+                item_format = item_schema.get("format")
+                if isinstance(item_format, str):
+                    param_doc.setdefault("items", {})["format"] = item_format
 
     enum = param_schema.get("enum")
     if isinstance(enum, list):
@@ -254,6 +252,10 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if default is not None:
         param_doc["default"] = default
 
+    schema_format = param_schema.get("format")
+    if isinstance(schema_format, str):
+        param_doc["format"] = schema_format
+
     minimum = param_schema.get("minimum")
     if isinstance(minimum, int | float):
         param_doc["minimum"] = minimum
@@ -262,6 +264,14 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if isinstance(maximum, int | float):
         param_doc["maximum"] = maximum
 
+    exclusive_minimum = param_schema.get("exclusiveMinimum")
+    if isinstance(exclusive_minimum, int | float):
+        param_doc["exclusiveMinimum"] = exclusive_minimum
+
+    exclusive_maximum = param_schema.get("exclusiveMaximum")
+    if isinstance(exclusive_maximum, int | float):
+        param_doc["exclusiveMaximum"] = exclusive_maximum
+
     min_length = param_schema.get("minLength")
     if isinstance(min_length, int):
         param_doc["minLength"] = min_length
@@ -270,6 +280,10 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if isinstance(max_length, int):
         param_doc["maxLength"] = max_length
 
+    pattern = param_schema.get("pattern")
+    if isinstance(pattern, str):
+        param_doc["pattern"] = pattern
+
     min_items = param_schema.get("minItems")
     if isinstance(min_items, int):
         param_doc["minItems"] = min_items
@@ -278,9 +292,31 @@ def _query_param_from_property(property_schema: Mapping[str, Any], *, required:
     if isinstance(max_items, int):
         param_doc["maxItems"] = max_items
 
+    unique_items = param_schema.get("uniqueItems")
+    if isinstance(unique_items, bool):
+        param_doc["uniqueItems"] = unique_items
+
+    multiple_of = param_schema.get("multipleOf")
+    if isinstance(multiple_of, int | float):
+        param_doc["multipleOf"] = multiple_of
+
     return param_doc
 
 
+def _resolve_schema_ref(property_schema: Mapping[str, Any], definitions: Mapping[str, Any]) -> Mapping[str, Any]:
+    ref = property_schema.get("$ref")
+    if not isinstance(ref, str):
+        return property_schema
+
+    ref_name = ref.rsplit("/", 1)[-1]
+    resolved = definitions.get(ref_name)
+    if not isinstance(resolved, Mapping):
+        return property_schema
+
+    property_without_ref = {key: value for key, value in property_schema.items() if key != "$ref"}
+    return {**resolved, **property_without_ref}
+
+
 def _nullable_property_schema(property_schema: Mapping[str, Any]) -> Mapping[str, Any]:
     any_of = property_schema.get("anyOf")
     if not isinstance(any_of, list):
@@ -297,7 +333,7 @@ def _nullable_property_schema(property_schema: Mapping[str, Any]) -> Mapping[str
 
 
 __all__ = [
-    "DEFAULT_REF_TEMPLATE_SWAGGER_2_0",
+    "DEFAULT_REF_TEMPLATE_OPENAPI_3_0",
     "get_or_create_model",
     "query_params_from_model",
     "query_params_from_request",

api/controllers/console/__init__.py

@@ -53,7 +53,7 @@ from .app import (
     agent,
     agent_app_access,
     agent_app_feature,
-    agent_app_workspace,
+    agent_app_sandbox,
     annotation,
     app,
     audio,
@@ -153,7 +153,7 @@ __all__ = [
     "agent",
     "agent_app_access",
     "agent_app_feature",
-    "agent_app_workspace",
+    "agent_app_sandbox",
     "agent_composer",
     "agent_providers",
     "agent_roster",

api/controllers/console/agent/composer.py

@@ -90,10 +90,12 @@ class WorkflowAgentComposerValidateApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
-    def post(self, app_model: App, node_id: str):
+    @with_current_tenant_id
+    def post(self, tenant_id: str, app_model: App, node_id: str):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
-        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": []})
+        findings = AgentComposerService.collect_validation_findings(tenant_id=tenant_id, payload=payload)
+        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer/candidates")
@@ -105,10 +107,17 @@ class WorkflowAgentComposerCandidatesApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
-    def get(self, app_model: App, node_id: str):
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user_id: str, app_model: App, node_id: str):
         return dump_response(
             AgentComposerCandidatesResponse,
-            AgentComposerService.get_workflow_candidates(app_id=app_model.id),
+            AgentComposerService.get_workflow_candidates(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                node_id=node_id,
+                user_id=current_user_id,
+            ),
         )
 
 
@@ -167,7 +176,7 @@ class AgentAppComposerApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model()
+    @get_app_model(mode=[AppMode.AGENT])
     @with_current_tenant_id
     def get(self, tenant_id: str, app_model: App):
         return dump_response(
@@ -181,7 +190,7 @@ class AgentAppComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model()
+    @get_app_model(mode=[AppMode.AGENT])
     @with_current_user_id
     @with_current_tenant_id
     def put(self, tenant_id: str, account_id: str, app_model: App):
@@ -206,11 +215,13 @@ class AgentAppComposerValidateApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model()
-    def post(self, app_model: App):
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_tenant_id
+    def post(self, tenant_id: str, app_model: App):
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
-        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": []})
+        findings = AgentComposerService.collect_validation_findings(tenant_id=tenant_id, payload=payload)
+        return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent-composer/candidates")
@@ -221,9 +232,15 @@ class AgentAppComposerCandidatesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model()
-    def get(self, app_model: App):
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user_id: str, app_model: App):
         return dump_response(
             AgentComposerCandidatesResponse,
-            AgentComposerService.get_agent_app_candidates(app_id=app_model.id),
+            AgentComposerService.get_agent_app_candidates(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                user_id=current_user_id,
+            ),
         )

api/controllers/console/agent/roster.py

@@ -18,6 +18,7 @@ from fields.agent_fields import (
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
+    AgentPublishedReferenceResponse,
     AgentRosterListResponse,
     AgentRosterResponse,
 )
@@ -48,6 +49,7 @@ register_response_schema_models(
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
+    AgentPublishedReferenceResponse,
     AgentRosterListResponse,
     AgentRosterResponse,
 )

api/controllers/console/app/advanced_prompt_template.py

@@ -1,9 +1,17 @@
+from typing import Any
+
 from flask import request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 
+from controllers.common.schema import (
+    DEFAULT_REF_TEMPLATE_OPENAPI_3_0,
+    query_params_from_model,
+    register_response_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.wraps import account_initialization_required, setup_required
+from fields.base import ResponseModel
 from libs.login import login_required
 from services.advanced_prompt_template_service import AdvancedPromptTemplateArgs, AdvancedPromptTemplateService
 
@@ -15,19 +23,27 @@ class AdvancedPromptTemplateQuery(BaseModel):
     model_name: str = Field(..., description="Model name")
 
 
+class AdvancedPromptTemplateResponse(ResponseModel):
+    chat_prompt_config: dict[str, Any] | None = Field(default=None)
+    completion_prompt_config: dict[str, Any] | None = Field(default=None)
+
+
 console_ns.schema_model(
     AdvancedPromptTemplateQuery.__name__,
-    AdvancedPromptTemplateQuery.model_json_schema(ref_template="#/definitions/{model}"),
+    AdvancedPromptTemplateQuery.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
 )
+register_response_schema_models(console_ns, AdvancedPromptTemplateResponse)
 
 
 @console_ns.route("/app/prompt-templates")
 class AdvancedPromptTemplateList(Resource):
     @console_ns.doc("get_advanced_prompt_templates")
     @console_ns.doc(description="Get advanced prompt templates based on app mode and model configuration")
-    @console_ns.expect(console_ns.models[AdvancedPromptTemplateQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AdvancedPromptTemplateQuery))
     @console_ns.response(
-        200, "Prompt templates retrieved successfully", fields.List(fields.Raw(description="Prompt template data"))
+        200,
+        "Prompt templates retrieved successfully",
+        console_ns.models[AdvancedPromptTemplateResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required

api/controllers/console/app/agent.py

@@ -1,15 +1,24 @@
-from flask import request
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field, field_validator
+from typing import Any
 
-from controllers.common.schema import register_schema_models
+from flask import request
+from flask_restx import Resource
+from pydantic import BaseModel, Field, RootModel, field_validator
+
+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.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
+from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
+from models import Account
 from models.model import App, AppMode
+from services.agent.skill_package_service import SkillPackageError, SkillPackageService
+from services.agent.skill_standardize_service import SkillStandardizeService
+from services.agent_drive_service import AgentDriveError
 from services.agent_service import AgentService
+from services.file_service import FileService
 
 
 class AgentLogQuery(BaseModel):
@@ -22,7 +31,53 @@ class AgentLogQuery(BaseModel):
         return uuid_value(value)
 
 
+class AgentLogMetaResponse(ResponseModel):
+    status: str
+    executor: str
+    start_time: str
+    elapsed_time: float | None = None
+    total_tokens: int
+    agent_mode: str
+    iterations: int
+
+
+class AgentToolCallResponse(ResponseModel):
+    status: str
+    error: str | None = None
+    time_cost: float | int
+    tool_name: str
+    tool_label: str
+    tool_input: dict[str, Any]
+    tool_output: dict[str, Any]
+    tool_parameters: dict[str, Any]
+    tool_icon: Any = Field(default=None)
+
+
+class AgentIterationLogResponse(ResponseModel):
+    tokens: int
+    tool_calls: list[AgentToolCallResponse]
+    tool_raw: dict[str, Any]
+    thought: str | None = None
+    created_at: str
+    files: list[Any] = Field(default_factory=list)
+
+
+class AgentLogResponse(ResponseModel):
+    meta: AgentLogMetaResponse
+    iterations: list[AgentIterationLogResponse]
+    files: list[Any] = Field(default_factory=list)
+
+
+class AgentSkillUploadResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class AgentSkillStandardizeResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(console_ns, AgentLogQuery)
+register_response_schema_models(console_ns, AgentLogResponse, AgentSkillUploadResponse, AgentSkillStandardizeResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/logs")
@@ -30,10 +85,8 @@ class AgentLogApi(Resource):
     @console_ns.doc("get_agent_logs")
     @console_ns.doc(description="Get agent execution logs for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AgentLogQuery.__name__])
-    @console_ns.response(
-        200, "Agent logs retrieved successfully", fields.List(fields.Raw(description="Agent log entries"))
-    )
+    @console_ns.doc(params=query_params_from_model(AgentLogQuery))
+    @console_ns.response(200, "Agent logs retrieved successfully", console_ns.models[AgentLogResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -44,3 +97,84 @@ class AgentLogApi(Resource):
         args = AgentLogQuery.model_validate(request.args.to_dict(flat=True))
 
         return AgentService.get_agent_logs(app_model, args.conversation_id, args.message_id)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/upload")
+class AgentSkillUploadApi(Resource):
+    @console_ns.doc("upload_agent_skill")
+    @console_ns.doc(description="Upload + validate a Skill package (.zip/.skill) and extract its manifest")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(201, "Skill validated", console_ns.models[AgentSkillUploadResponse.__name__])
+    @console_ns.response(400, "Invalid skill package")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """Validate an uploaded Skill package and persist the archive.
+
+        Returns a validated skill ref (to bind into the Agent soul config on save)
+        plus its manifest. Standardizing into the agent drive is ENG-594.
+        """
+        if "file" not in request.files:
+            return {"code": "no_file", "message": "no skill file uploaded"}, 400
+        if len(request.files) > 1:
+            return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+
+        upload = request.files["file"]
+        content = upload.stream.read()
+        try:
+            manifest = SkillPackageService().validate_and_extract(content=content, filename=upload.filename or "")
+        except SkillPackageError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+
+        upload_file = FileService(db.engine).upload_file(
+            filename=upload.filename or "skill.zip",
+            content=content,
+            mimetype=upload.mimetype or "application/zip",
+            user=current_user,
+        )
+        skill_ref = manifest.to_skill_ref(file_id=upload_file.id)
+        return {"skill": skill_ref.model_dump(exclude_none=True), "manifest": manifest.model_dump()}, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/standardize")
+class AgentSkillStandardizeApi(Resource):
+    @console_ns.doc("standardize_agent_skill")
+    @console_ns.doc(description="Validate + standardize a Skill into the agent drive (ENG-594)")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(
+        201,
+        "Skill standardized into drive",
+        console_ns.models[AgentSkillStandardizeResponse.__name__],
+    )
+    @console_ns.response(400, "Invalid skill package or no bound agent")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """Upload a Skill, validate it, and standardize it into the app agent's drive."""
+        agent_id = app_model.bound_agent_id
+        if not agent_id:
+            return {"code": "no_bound_agent", "message": "app has no bound agent"}, 400
+        if "file" not in request.files:
+            return {"code": "no_file", "message": "no skill file uploaded"}, 400
+        if len(request.files) > 1:
+            return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+
+        upload = request.files["file"]
+        content = upload.stream.read()
+        try:
+            result = SkillStandardizeService().standardize(
+                content=content,
+                filename=upload.filename or "",
+                tenant_id=app_model.tenant_id,
+                user_id=current_user.id,
+                agent_id=agent_id,
+            )
+        except (SkillPackageError, AgentDriveError) as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+        return result, 201

api/controllers/console/app/agent_app_sandbox.py

@@ -0,0 +1,306 @@
+"""Console routes for Agent App and workflow Agent sandbox file access.
+
+The API keeps product-facing locators (conversation or workflow node identity)
+on this public boundary and proxies list/read/upload to the agent backend's new
+``/sandbox`` contract.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from dify_agent.client import DifyAgentClientError, DifyAgentHTTPError, DifyAgentTimeoutError
+from flask import request
+from flask_restx import Resource
+from pydantic import BaseModel, Field
+
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+    register_schema_models,
+)
+from controllers.console import console_ns
+from controllers.console.app.wraps import get_app_model
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_tenant_id
+from fields.base import ResponseModel
+from libs.login import login_required
+from models.model import App, AppMode
+from services.agent_app_sandbox_service import (
+    AgentAppSandboxService,
+    AgentSandboxInspectorError,
+    WorkflowAgentSandboxService,
+)
+
+_NODE_EXECUTION_ID_DESCRIPTION = (
+    "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
+)
+
+
+class AgentSandboxListQuery(BaseModel):
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
+    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
+
+
+class AgentSandboxFileQuery(BaseModel):
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+
+
+class AgentSandboxUploadPayload(BaseModel):
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+
+
+class WorkflowAgentSandboxListQuery(BaseModel):
+    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
+
+
+class WorkflowAgentSandboxFileQuery(BaseModel):
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
+
+
+class WorkflowAgentSandboxUploadPayload(BaseModel):
+    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
+
+
+class SandboxFileEntryResponse(ResponseModel):
+    name: str
+    type: Literal["file", "dir", "symlink", "other"]
+    size: int | None = None
+    mtime: int | None = None
+
+
+class SandboxListResponse(ResponseModel):
+    path: str
+    entries: list[SandboxFileEntryResponse] = Field(default_factory=list)
+    truncated: bool = False
+
+
+class SandboxReadResponse(ResponseModel):
+    path: str
+    size: int | None = None
+    truncated: bool
+    binary: bool
+    text: str | None = None
+
+
+class SandboxToolFileResponse(ResponseModel):
+    transfer_method: Literal["tool_file"] = "tool_file"
+    reference: str
+
+
+class SandboxUploadResponse(ResponseModel):
+    path: str
+    file: SandboxToolFileResponse
+
+
+register_schema_models(
+    console_ns,
+    AgentSandboxUploadPayload,
+    WorkflowAgentSandboxUploadPayload,
+)
+register_response_schema_models(console_ns, SandboxListResponse, SandboxReadResponse, SandboxUploadResponse)
+
+
+def _handle(exc: Exception) -> tuple[dict[str, object], int]:
+    if isinstance(exc, AgentSandboxInspectorError):
+        return {"code": exc.code, "message": exc.message}, exc.status_code
+    if isinstance(exc, DifyAgentHTTPError):
+        detail = exc.detail
+        if isinstance(detail, dict):
+            return {
+                "code": detail.get("code", "agent_backend_error"),
+                "message": detail.get("message", str(exc)),
+            }, exc.status_code
+        return {"code": "agent_backend_error", "message": str(detail)}, exc.status_code
+    if isinstance(exc, DifyAgentTimeoutError | DifyAgentClientError):
+        return {"code": "agent_backend_unreachable", "message": str(exc)}, 502
+    raise exc
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files")
+class AgentAppSandboxListResource(Resource):
+    @console_ns.doc("list_agent_app_sandbox_files")
+    @console_ns.doc(description="List a directory in an Agent App conversation sandbox")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentSandboxListQuery)})
+    @console_ns.response(200, "Listing returned", console_ns.models[SandboxListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, app_model: App):
+        query = query_params_from_request(AgentSandboxListQuery)
+        try:
+            result = AgentAppSandboxService().list_files(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                conversation_id=query.conversation_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files/read")
+class AgentAppSandboxReadResource(Resource):
+    @console_ns.doc("read_agent_app_sandbox_file")
+    @console_ns.doc(description="Read a text/binary preview file in an Agent App conversation sandbox")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentSandboxFileQuery)})
+    @console_ns.response(200, "Preview returned", console_ns.models[SandboxReadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, app_model: App):
+        query = query_params_from_request(AgentSandboxFileQuery)
+        try:
+            result = AgentAppSandboxService().read_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                conversation_id=query.conversation_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files/upload")
+class AgentAppSandboxUploadResource(Resource):
+    @console_ns.doc("upload_agent_app_sandbox_file")
+    @console_ns.doc(description="Upload one Agent App sandbox file as a Dify ToolFile mapping")
+    @console_ns.expect(console_ns.models[AgentSandboxUploadPayload.__name__])
+    @console_ns.response(200, "Uploaded", console_ns.models[SandboxUploadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.AGENT])
+    @with_current_tenant_id
+    def post(self, tenant_id: str, app_model: App):
+        payload = AgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
+        try:
+            result = AgentAppSandboxService().upload_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                conversation_id=payload.conversation_id,
+                path=payload.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/sandbox/files")
+class WorkflowAgentSandboxListResource(Resource):
+    @console_ns.doc("list_workflow_agent_sandbox_files")
+    @console_ns.doc(description="List a directory in a workflow Agent node sandbox")
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "workflow_run_id": "Workflow run ID",
+            "node_id": "Workflow Agent node ID",
+            **query_params_from_model(WorkflowAgentSandboxListQuery),
+        }
+    )
+    @console_ns.response(200, "Listing returned", console_ns.models[SandboxListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
+        query = query_params_from_request(WorkflowAgentSandboxListQuery)
+        try:
+            result = WorkflowAgentSandboxService().list_files(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                workflow_run_id=str(workflow_run_id),
+                node_id=node_id,
+                node_execution_id=query.node_execution_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route(
+    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/sandbox/files/read"
+)
+class WorkflowAgentSandboxReadResource(Resource):
+    @console_ns.doc("read_workflow_agent_sandbox_file")
+    @console_ns.doc(description="Read a text/binary preview file in a workflow Agent node sandbox")
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "workflow_run_id": "Workflow run ID",
+            "node_id": "Workflow Agent node ID",
+            **query_params_from_model(WorkflowAgentSandboxFileQuery),
+        }
+    )
+    @console_ns.response(200, "Preview returned", console_ns.models[SandboxReadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_tenant_id
+    def get(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
+        query = query_params_from_request(WorkflowAgentSandboxFileQuery)
+        try:
+            result = WorkflowAgentSandboxService().read_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                workflow_run_id=str(workflow_run_id),
+                node_id=node_id,
+                node_execution_id=query.node_execution_id,
+                path=query.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()
+
+
+@console_ns.route(
+    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/sandbox/files/upload"
+)
+class WorkflowAgentSandboxUploadResource(Resource):
+    @console_ns.doc("upload_workflow_agent_sandbox_file")
+    @console_ns.doc(description="Upload one workflow Agent sandbox file as a Dify ToolFile mapping")
+    @console_ns.expect(console_ns.models[WorkflowAgentSandboxUploadPayload.__name__])
+    @console_ns.response(200, "Uploaded", console_ns.models[SandboxUploadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_tenant_id
+    def post(self, tenant_id: str, app_model: App, workflow_run_id: UUID, node_id: str):
+        payload = WorkflowAgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
+        try:
+            result = WorkflowAgentSandboxService().upload_file(
+                tenant_id=tenant_id,
+                app_id=app_model.id,
+                workflow_run_id=str(workflow_run_id),
+                node_id=node_id,
+                node_execution_id=payload.node_execution_id,
+                path=payload.path,
+            )
+        except Exception as exc:
+            return _handle(exc)
+        return result.model_dump()

api/controllers/console/app/agent_app_workspace.py

@@ -1,319 +0,0 @@
-"""Agent App sandbox file-system inspector (read-only).
-
-Exposes the PRD "rc1-like sandbox file system, downloadable not editable" view
-for an Agent App conversation: list a directory, preview a file, or download a
-file from the conversation's shell-layer workspace. The API never touches
-shellctl directly — it resolves the conversation's sandbox ``session_id`` from
-the stored session snapshot and proxies to the agent backend's read-only
-workspace endpoints.
-"""
-
-from typing import Literal
-from uuid import UUID
-
-from flask import Response
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field
-
-from clients.agent_backend.errors import AgentBackendHTTPError, AgentBackendTransportError
-from clients.agent_backend.workspace_files_client import WorkspaceDownloadResult
-from controllers.common.schema import (
-    query_params_from_model,
-    query_params_from_request,
-    register_response_schema_models,
-)
-from controllers.console import console_ns
-from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
-from fields.base import ResponseModel
-from libs.login import current_account_with_tenant, login_required
-from models.model import App, AppMode
-from services.agent_app_workspace_service import (
-    AgentAppWorkspaceService,
-    AgentWorkspaceInspectorError,
-    WorkflowAgentWorkspaceService,
-)
-
-
-class _WorkspaceFileDownloadField(fields.Raw):
-    __schema_type__ = "string"
-    __schema_format__ = "binary"
-
-
-class AgentWorkspaceListQuery(BaseModel):
-    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
-    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
-
-
-class AgentWorkspaceFileQuery(BaseModel):
-    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
-    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
-
-
-class WorkflowAgentWorkspaceListQuery(BaseModel):
-    path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
-    node_execution_id: str | None = Field(
-        default=None,
-        description=(
-            "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
-        ),
-    )
-
-
-class WorkflowAgentWorkspaceFileQuery(BaseModel):
-    path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
-    node_execution_id: str | None = Field(
-        default=None,
-        description=(
-            "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
-        ),
-    )
-
-
-class WorkspaceFileEntryResponse(ResponseModel):
-    name: str
-    type: Literal["file", "dir", "symlink"]
-    size: int
-    mtime: int
-
-
-class WorkspaceListResponse(ResponseModel):
-    path: str
-    entries: list[WorkspaceFileEntryResponse] = Field(default_factory=list)
-    truncated: bool = False
-
-
-class WorkspacePreviewResponse(ResponseModel):
-    path: str
-    size: int
-    truncated: bool
-    binary: bool
-    text: str | None = None
-
-
-register_response_schema_models(console_ns, WorkspaceListResponse)
-register_response_schema_models(console_ns, WorkspacePreviewResponse)
-
-
-def _handle(exc: Exception) -> tuple[dict[str, object], int]:
-    if isinstance(exc, AgentWorkspaceInspectorError):
-        return {"code": exc.code, "message": exc.message}, exc.status_code
-    if isinstance(exc, AgentBackendHTTPError):
-        detail = exc.detail
-        if isinstance(detail, dict):
-            return {
-                "code": detail.get("code", "agent_backend_error"),
-                "message": detail.get("message", str(exc)),
-            }, exc.status_code
-        return {"code": "agent_backend_error", "message": str(detail)}, exc.status_code
-    if isinstance(exc, AgentBackendTransportError):
-        return {"code": "agent_backend_unreachable", "message": str(exc)}, 502
-    raise exc
-
-
-def _download_response(result: WorkspaceDownloadResult) -> Response | tuple[dict[str, object], int]:
-    if result.truncated:
-        return {
-            "code": "workspace_file_too_large",
-            "message": (
-                "file exceeds the workspace download limit; use preview for partial text or download a smaller file"
-            ),
-            "size": result.size,
-        }, 413
-    filename = result.path.rsplit("/", 1)[-1] or "download"
-    return Response(
-        result.content,
-        mimetype="application/octet-stream",
-        headers={
-            "Content-Disposition": f'attachment; filename="{filename}"',
-            "Content-Length": str(len(result.content)),
-            "X-Workspace-File-Size": str(result.size),
-        },
-    )
-
-
-@console_ns.route("/apps/<uuid:app_id>/agent-workspace/files")
-class AgentAppWorkspaceListResource(Resource):
-    @console_ns.doc("list_agent_app_workspace_files")
-    @console_ns.doc(description="List a directory in an Agent App conversation's sandbox workspace (read-only)")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentWorkspaceListQuery)})
-    @console_ns.response(200, "Listing returned", console_ns.models[WorkspaceListResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
-    def get(self, app_model: App):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(AgentWorkspaceListQuery)
-        try:
-            result = AgentAppWorkspaceService().list_files(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                conversation_id=query.conversation_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route("/apps/<uuid:app_id>/agent-workspace/files/preview")
-class AgentAppWorkspacePreviewResource(Resource):
-    @console_ns.doc("preview_agent_app_workspace_file")
-    @console_ns.doc(description="Preview a text/binary file in an Agent App conversation's sandbox workspace")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentWorkspaceFileQuery)})
-    @console_ns.response(200, "Preview returned", console_ns.models[WorkspacePreviewResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
-    def get(self, app_model: App):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(AgentWorkspaceFileQuery)
-        try:
-            result = AgentAppWorkspaceService().preview(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                conversation_id=query.conversation_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route("/apps/<uuid:app_id>/agent-workspace/files/download")
-class AgentAppWorkspaceDownloadResource(Resource):
-    @console_ns.doc("download_agent_app_workspace_file")
-    @console_ns.doc(description="Download a file from an Agent App conversation's sandbox workspace (read-only)")
-    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentWorkspaceFileQuery)})
-    @console_ns.doc(produces=["application/octet-stream"])
-    @console_ns.response(200, "File bytes", _WorkspaceFileDownloadField)
-    @console_ns.response(413, "File exceeds the workspace download limit")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
-    def get(self, app_model: App):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(AgentWorkspaceFileQuery)
-        try:
-            result = AgentAppWorkspaceService().download(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                conversation_id=query.conversation_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return _download_response(result)
-
-
-@console_ns.route(
-    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/workspace/files"
-)
-class WorkflowAgentWorkspaceListResource(Resource):
-    @console_ns.doc("list_workflow_agent_workspace_files")
-    @console_ns.doc(description="List a directory in a Workflow Agent node's sandbox workspace (read-only)")
-    @console_ns.doc(
-        params={
-            "app_id": "Application ID",
-            "workflow_run_id": "Workflow run ID",
-            "node_id": "Workflow Agent node ID",
-            **query_params_from_model(WorkflowAgentWorkspaceListQuery),
-        }
-    )
-    @console_ns.response(200, "Listing returned", console_ns.models[WorkspaceListResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, workflow_run_id: UUID, node_id: str):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(WorkflowAgentWorkspaceListQuery)
-        try:
-            result = WorkflowAgentWorkspaceService().list_files(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                workflow_run_id=str(workflow_run_id),
-                node_id=node_id,
-                node_execution_id=query.node_execution_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route(
-    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/workspace/files/preview"
-)
-class WorkflowAgentWorkspacePreviewResource(Resource):
-    @console_ns.doc("preview_workflow_agent_workspace_file")
-    @console_ns.doc(description="Preview a text/binary file in a Workflow Agent node's sandbox workspace")
-    @console_ns.doc(
-        params={
-            "app_id": "Application ID",
-            "workflow_run_id": "Workflow run ID",
-            "node_id": "Workflow Agent node ID",
-            **query_params_from_model(WorkflowAgentWorkspaceFileQuery),
-        }
-    )
-    @console_ns.response(200, "Preview returned", console_ns.models[WorkspacePreviewResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, workflow_run_id: UUID, node_id: str):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(WorkflowAgentWorkspaceFileQuery)
-        try:
-            result = WorkflowAgentWorkspaceService().preview(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                workflow_run_id=str(workflow_run_id),
-                node_id=node_id,
-                node_execution_id=query.node_execution_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return result.model_dump()
-
-
-@console_ns.route(
-    "/apps/<uuid:app_id>/workflow-runs/<uuid:workflow_run_id>/agent-nodes/<string:node_id>/workspace/files/download"
-)
-class WorkflowAgentWorkspaceDownloadResource(Resource):
-    @console_ns.doc("download_workflow_agent_workspace_file")
-    @console_ns.doc(description="Download a file from a Workflow Agent node's sandbox workspace (read-only)")
-    @console_ns.doc(
-        params={
-            "app_id": "Application ID",
-            "workflow_run_id": "Workflow run ID",
-            "node_id": "Workflow Agent node ID",
-            **query_params_from_model(WorkflowAgentWorkspaceFileQuery),
-        }
-    )
-    @console_ns.doc(produces=["application/octet-stream"])
-    @console_ns.response(200, "File bytes", _WorkspaceFileDownloadField)
-    @console_ns.response(413, "File exceeds the workspace download limit")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
-    def get(self, app_model: App, workflow_run_id: UUID, node_id: str):
-        _, tenant_id = current_account_with_tenant()
-        query = query_params_from_request(WorkflowAgentWorkspaceFileQuery)
-        try:
-            result = WorkflowAgentWorkspaceService().download(
-                tenant_id=tenant_id,
-                app_id=app_model.id,
-                workflow_run_id=str(workflow_run_id),
-                node_id=node_id,
-                node_execution_id=query.node_execution_id,
-                path=query.path,
-            )
-        except Exception as exc:  # normalized to an HTTP response below
-            return _handle(exc)
-        return _download_response(result)

api/controllers/console/app/annotation.py

@@ -6,7 +6,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, TypeAdapter, field_validator
 
 from controllers.common.errors import NoFileUploadedError, TooManyFilesError
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -24,6 +24,7 @@ from fields.annotation_fields import (
     AnnotationHitHistoryList,
     AnnotationList,
 )
+from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
 from services.annotation_service import (
@@ -56,7 +57,10 @@ class CreateAnnotationPayload(BaseModel):
     question: str | None = Field(default=None, description="Question text")
     answer: str | None = Field(default=None, description="Answer text")
     content: str | None = Field(default=None, description="Content text")
-    annotation_reply: dict[str, Any] | None = Field(default=None, description="Annotation reply data")
+    annotation_reply: dict[str, Any] | None = Field(
+        default=None,
+        description="Annotation reply data",
+    )
 
     @field_validator("message_id")
     @classmethod
@@ -70,13 +74,18 @@ class UpdateAnnotationPayload(BaseModel):
     question: str | None = None
     answer: str | None = None
     content: str | None = None
-    annotation_reply: dict[str, Any] | None = None
+    annotation_reply: dict[str, Any] | None = Field(default=None)
 
 
 class AnnotationReplyStatusQuery(BaseModel):
     action: Literal["enable", "disable"]
 
 
+class AnnotationHitHistoryListQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, description="Page size")
+
+
 class AnnotationFilePayload(BaseModel):
     message_id: str = Field(..., description="Message ID")
 
@@ -86,6 +95,25 @@ class AnnotationFilePayload(BaseModel):
         return uuid_value(value)
 
 
+class AnnotationJobStatusResponse(ResponseModel):
+    job_id: str | None = None
+    job_status: str | None = None
+    error_msg: str | None = None
+    record_count: int | None = None
+
+
+class AnnotationEmbeddingModelResponse(ResponseModel):
+    embedding_provider_name: str | None = None
+    embedding_model_name: str | None = None
+
+
+class AnnotationSettingResponse(ResponseModel):
+    id: str | None = None
+    enabled: bool
+    score_threshold: float | None = None
+    embedding_model: AnnotationEmbeddingModelResponse | None = None
+
+
 register_schema_models(
     console_ns,
     Annotation,
@@ -99,8 +127,19 @@ register_schema_models(
     CreateAnnotationPayload,
     UpdateAnnotationPayload,
     AnnotationReplyStatusQuery,
+    AnnotationHitHistoryListQuery,
     AnnotationFilePayload,
 )
+register_response_schema_models(
+    console_ns,
+    Annotation,
+    AnnotationList,
+    AnnotationExportList,
+    AnnotationHitHistory,
+    AnnotationHitHistoryList,
+    AnnotationJobStatusResponse,
+    AnnotationSettingResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotation-reply/<string:action>")
@@ -109,7 +148,7 @@ class AnnotationReplyActionApi(Resource):
     @console_ns.doc(description="Enable or disable annotation reply for an app")
     @console_ns.doc(params={"app_id": "Application ID", "action": "Action to perform (enable/disable)"})
     @console_ns.expect(console_ns.models[AnnotationReplyPayload.__name__])
-    @console_ns.response(200, "Action completed successfully")
+    @console_ns.response(200, "Action completed successfully", console_ns.models[AnnotationJobStatusResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -136,7 +175,11 @@ class AppAnnotationSettingDetailApi(Resource):
     @console_ns.doc("get_annotation_setting")
     @console_ns.doc(description="Get annotation settings for an app")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Annotation settings retrieved successfully")
+    @console_ns.response(
+        200,
+        "Annotation settings retrieved successfully",
+        console_ns.models[AnnotationSettingResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -153,7 +196,7 @@ class AppAnnotationSettingUpdateApi(Resource):
     @console_ns.doc(description="Update annotation settings for an app")
     @console_ns.doc(params={"app_id": "Application ID", "annotation_setting_id": "Annotation setting ID"})
     @console_ns.expect(console_ns.models[AnnotationSettingUpdatePayload.__name__])
-    @console_ns.response(200, "Settings updated successfully")
+    @console_ns.response(200, "Settings updated successfully", console_ns.models[AnnotationSettingResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -176,7 +219,11 @@ class AnnotationReplyActionStatusApi(Resource):
     @console_ns.doc("get_annotation_reply_action_status")
     @console_ns.doc(description="Get status of annotation reply action job")
     @console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID", "action": "Action type"})
-    @console_ns.response(200, "Job status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Job status retrieved successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -204,8 +251,8 @@ class AnnotationApi(Resource):
     @console_ns.doc("list_annotations")
     @console_ns.doc(description="Get annotations for an app with pagination")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AnnotationListQuery.__name__])
-    @console_ns.response(200, "Annotations retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(AnnotationListQuery))
+    @console_ns.response(200, "Annotations retrieved successfully", console_ns.models[AnnotationList.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -257,6 +304,7 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @console_ns.response(204, "Annotations deleted successfully")
     def delete(self, app_id: UUID):
 
         # Use request.args.getlist to get annotation_ids array directly
@@ -335,6 +383,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @console_ns.response(204, "Annotation deleted successfully")
     def delete(self, app_id: UUID, annotation_id: UUID):
         AppAnnotationService.delete_app_annotation(str(app_id), str(annotation_id))
         return "", 204
@@ -345,7 +394,11 @@ class AnnotationBatchImportApi(Resource):
     @console_ns.doc("batch_import_annotations")
     @console_ns.doc(description="Batch import annotations from CSV file with rate limiting and security checks")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Batch import started successfully")
+    @console_ns.response(
+        200,
+        "Batch import started successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(400, "No file uploaded or too many files")
     @console_ns.response(413, "File too large")
@@ -398,7 +451,11 @@ class AnnotationBatchImportStatusApi(Resource):
     @console_ns.doc("get_batch_import_status")
     @console_ns.doc(description="Get status of batch import job")
     @console_ns.doc(params={"app_id": "Application ID", "job_id": "Job ID"})
-    @console_ns.response(200, "Job status retrieved successfully")
+    @console_ns.response(
+        200,
+        "Job status retrieved successfully",
+        console_ns.models[AnnotationJobStatusResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -424,11 +481,7 @@ class AnnotationHitHistoryListApi(Resource):
     @console_ns.doc("list_annotation_hit_histories")
     @console_ns.doc(description="Get hit histories for an annotation")
     @console_ns.doc(params={"app_id": "Application ID", "annotation_id": "Annotation ID"})
-    @console_ns.expect(
-        console_ns.parser()
-        .add_argument("page", type=int, location="args", default=1, help="Page number")
-        .add_argument("limit", type=int, location="args", default=20, help="Page size")
-    )
+    @console_ns.doc(params=query_params_from_model(AnnotationHitHistoryListQuery))
     @console_ns.response(
         200,
         "Hit histories retrieved successfully",

api/controllers/console/app/app.py

@@ -14,7 +14,12 @@ from werkzeug.exceptions import BadRequest
 
 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.common.schema import (
+    query_params_from_model,
+    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, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
@@ -206,6 +211,11 @@ class AppTracePayload(BaseModel):
         return value
 
 
+class AppTraceResponse(ResponseModel):
+    enabled: bool
+    tracing_provider: str | None = None
+
+
 type JSONValue = Any
 
 
@@ -447,7 +457,7 @@ class AppExportResponse(ResponseModel):
 
 
 register_enum_models(console_ns, RetrievalMethod, WorkflowExecutionStatus, DatasetPermissionEnum)
-register_response_schema_models(console_ns, RedirectUrlResponse, SimpleResultResponse)
+register_response_schema_models(console_ns, AppTraceResponse, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
@@ -495,7 +505,7 @@ register_schema_models(
 class AppListApi(Resource):
     @console_ns.doc("list_apps")
     @console_ns.doc(description="Get list of applications with pagination and filtering")
-    @console_ns.expect(console_ns.models[AppListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AppListQuery))
     @console_ns.response(200, "Success", console_ns.models[AppPagination.__name__])
     @setup_required
     @login_required
@@ -737,7 +747,7 @@ class AppExportApi(Resource):
     @console_ns.doc("export_app")
     @console_ns.doc(description="Export application configuration as DSL")
     @console_ns.doc(params={"app_id": "Application ID to export"})
-    @console_ns.expect(console_ns.models[AppExportQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AppExportQuery))
     @console_ns.response(200, "App exported successfully", console_ns.models[AppExportResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @get_app_model
@@ -812,7 +822,7 @@ class AppIconApi(Resource):
     @console_ns.doc(description="Update application icon")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AppIconPayload.__name__])
-    @console_ns.response(200, "Icon updated successfully")
+    @console_ns.response(200, "Icon updated successfully", console_ns.models[AppDetail.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -882,7 +892,11 @@ class AppTraceApi(Resource):
     @console_ns.doc("get_app_trace")
     @console_ns.doc(description="Get app tracing configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Trace configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Trace configuration retrieved successfully",
+        console_ns.models[AppTraceResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/audio.py

@@ -1,12 +1,14 @@
 import logging
+from typing import Any
 
 from flask import request
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field
+from flask_restx import Resource
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import InternalServerError
 
 import services
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import AudioBinaryResponse
+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.app.error import (
     AppUnavailableError,
@@ -51,7 +53,12 @@ class AudioTranscriptResponse(BaseModel):
     text: str = Field(description="Transcribed text from audio")
 
 
+class TextToSpeechVoiceListResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
 register_schema_models(console_ns, AudioTranscriptResponse, TextToSpeechPayload, TextToSpeechVoiceQuery)
+register_response_schema_models(console_ns, AudioBinaryResponse, TextToSpeechVoiceListResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/audio-to-text")
@@ -113,7 +120,11 @@ class ChatMessageTextApi(Resource):
     @console_ns.doc(description="Convert text to speech for chat messages")
     @console_ns.doc(params={"app_id": "App ID"})
     @console_ns.expect(console_ns.models[TextToSpeechPayload.__name__])
-    @console_ns.response(200, "Text to speech conversion successful")
+    @console_ns.response(
+        200,
+        "Text to speech conversion successful",
+        console_ns.models[AudioBinaryResponse.__name__],
+    )
     @console_ns.response(400, "Bad request - Invalid parameters")
     @get_app_model
     @setup_required
@@ -162,9 +173,11 @@ class TextModesApi(Resource):
     @console_ns.doc("get_text_to_speech_voices")
     @console_ns.doc(description="Get available TTS voices for a specific language")
     @console_ns.doc(params={"app_id": "App ID"})
-    @console_ns.expect(console_ns.models[TextToSpeechVoiceQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TextToSpeechVoiceQuery))
     @console_ns.response(
-        200, "TTS voices retrieved successfully", fields.List(fields.Raw(description="Available voices"))
+        200,
+        "TTS voices retrieved successfully",
+        console_ns.models[TextToSpeechVoiceListResponse.__name__],
     )
     @console_ns.response(400, "Invalid language parameter")
     @get_app_model

api/controllers/console/app/completion.py

@@ -7,7 +7,7 @@ from pydantic import BaseModel, Field, field_validator
 from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
 
 import services
-from controllers.common.fields import SimpleResultResponse
+from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
@@ -64,8 +64,14 @@ class BaseMessagePayload(BaseModel):
     # Soul, so no override ``model_config`` is sent; chat / agent-chat / completion
     # debugging still pass it. Optional here, required in practice by those modes
     # downstream when their config is built from args.
-    model_config_data: dict[str, Any] = Field(default_factory=dict, alias="model_config")
-    files: list[Any] | None = Field(default=None, description="Uploaded files")
+    model_config_data: dict[str, Any] = Field(
+        default_factory=dict,
+        alias="model_config",
+    )
+    files: list[Any] | None = Field(
+        default=None,
+        description="Uploaded files",
+    )
     response_mode: Literal["blocking", "streaming"] = Field(default="blocking", description="Response mode")
     retriever_from: str = Field(default="dev", description="Retriever source")
 
@@ -88,7 +94,7 @@ class ChatMessagePayload(BaseMessagePayload):
 
 
 register_schema_models(console_ns, CompletionMessagePayload, ChatMessagePayload)
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, GeneratedAppResponse, SimpleResultResponse)
 
 
 # define completion message api for user
@@ -98,7 +104,7 @@ class CompletionMessageApi(Resource):
     @console_ns.doc(description="Generate completion message for debugging")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[CompletionMessagePayload.__name__])
-    @console_ns.response(200, "Completion generated successfully")
+    @console_ns.response(200, "Completion generated successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(404, "App not found")
     @setup_required
@@ -170,7 +176,7 @@ class ChatMessageApi(Resource):
     @console_ns.doc(description="Generate chat message for debugging")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
-    @console_ns.response(200, "Chat message generated successfully")
+    @console_ns.response(200, "Chat message generated successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(404, "App or conversation not found")
     @setup_required

api/controllers/console/app/conversation.py

@@ -9,7 +9,7 @@ from sqlalchemy import func, or_
 from sqlalchemy.orm import selectinload
 from werkzeug.exceptions import NotFound
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -91,7 +91,7 @@ class CompletionConversationApi(Resource):
     @console_ns.doc("list_completion_conversations")
     @console_ns.doc(description="Get completion conversations with pagination and filtering")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[CompletionConversationQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(CompletionConversationQuery))
     @console_ns.response(200, "Success", console_ns.models[ConversationPaginationResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
@@ -206,7 +206,7 @@ class ChatConversationApi(Resource):
     @console_ns.doc("list_chat_conversations")
     @console_ns.doc(description="Get chat conversations with pagination, filtering and summary")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ChatConversationQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ChatConversationQuery))
     @console_ns.response(200, "Success", console_ns.models[ConversationWithSummaryPaginationResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required

api/controllers/console/app/conversation_variables.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -84,7 +84,7 @@ class ConversationVariablesApi(Resource):
     @console_ns.doc("get_conversation_variables")
     @console_ns.doc(description="Get conversation variables for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ConversationVariablesQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ConversationVariablesQuery))
     @console_ns.response(
         200,
         "Conversation variables retrieved successfully",

api/controllers/console/app/generator.py

@@ -1,11 +1,12 @@
 from collections.abc import Sequence
-from typing import Literal
+from typing import Any, Literal
 
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from sqlalchemy.orm import Session
 
-from controllers.common.schema import register_enum_models, register_schema_models
+from controllers.common.fields import SimpleDataResponse
+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.error import (
     CompletionRequestError,
@@ -36,7 +37,11 @@ class InstructionGeneratePayload(BaseModel):
     current: str = Field(default="", description="Current instruction text")
     language: str = Field(default="javascript", description="Programming language (javascript/python)")
     instruction: str = Field(..., description="Instruction for generation")
-    model_config_data: ModelConfig = Field(..., alias="model_config", description="Model configuration")
+    model_config_data: ModelConfig = Field(
+        ...,
+        alias="model_config",
+        description="Model configuration",
+    )
     ideal_output: str = Field(default="", description="Expected ideal output")
 
 
@@ -44,6 +49,13 @@ class InstructionTemplatePayload(BaseModel):
     type: str = Field(..., description="Instruction template type")
 
 
+# Upper bound for the generator's free-text inputs. Generous for prose (a
+# detailed instruction rarely passes 2k chars) while keeping the
+# planner+builder prompts well inside every mainstream context window.
+# Mirrored by the ``maxLength`` on the frontend generator textarea.
+_MAX_INSTRUCTION_LENGTH = 10_000
+
+
 class WorkflowGeneratePayload(BaseModel):
     """Payload for the cmd+k `/create` and `/refine` workflow generator endpoint.
 
@@ -55,13 +67,21 @@ class WorkflowGeneratePayload(BaseModel):
     mode: Literal["workflow", "advanced-chat"] = Field(..., description="Target app mode for the generated graph")
     instruction: str = Field(..., description="Natural-language workflow description")
     ideal_output: str = Field(default="", description="Optional sample output for grounding")
-    model_config_data: ModelConfig = Field(..., alias="model_config", description="Model configuration")
+    model_config_data: ModelConfig = Field(
+        ...,
+        alias="model_config",
+        description="Model configuration",
+    )
     current_graph: dict | None = Field(
         default=None,
         description="Existing draft graph to refine (cmd+k `/refine`); omit for create-from-scratch",
     )
 
 
+class GeneratorResponse(RootModel[Any]):
+    root: Any
+
+
 register_enum_models(console_ns, LLMMode)
 register_schema_models(
     console_ns,
@@ -73,6 +93,7 @@ register_schema_models(
     WorkflowGeneratePayload,
     ModelConfig,
 )
+register_response_schema_models(console_ns, GeneratorResponse, SimpleDataResponse)
 
 
 @console_ns.route("/rule-generate")
@@ -80,7 +101,11 @@ class RuleGenerateApi(Resource):
     @console_ns.doc("generate_rule_config")
     @console_ns.doc(description="Generate rule configuration using LLM")
     @console_ns.expect(console_ns.models[RuleGeneratePayload.__name__])
-    @console_ns.response(200, "Rule configuration generated successfully")
+    @console_ns.response(
+        200,
+        "Rule configuration generated successfully",
+        console_ns.models[GeneratorResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -109,7 +134,7 @@ class RuleCodeGenerateApi(Resource):
     @console_ns.doc("generate_rule_code")
     @console_ns.doc(description="Generate code rules using LLM")
     @console_ns.expect(console_ns.models[RuleCodeGeneratePayload.__name__])
-    @console_ns.response(200, "Code rules generated successfully")
+    @console_ns.response(200, "Code rules generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -141,7 +166,7 @@ class RuleStructuredOutputGenerateApi(Resource):
     @console_ns.doc("generate_structured_output")
     @console_ns.doc(description="Generate structured output rules using LLM")
     @console_ns.expect(console_ns.models[RuleStructuredOutputPayload.__name__])
-    @console_ns.response(200, "Structured output generated successfully")
+    @console_ns.response(200, "Structured output generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -173,7 +198,7 @@ class InstructionGenerateApi(Resource):
     @console_ns.doc("generate_instruction")
     @console_ns.doc(description="Generate instruction for workflow nodes or general use")
     @console_ns.expect(console_ns.models[InstructionGeneratePayload.__name__])
-    @console_ns.response(200, "Instruction generated successfully")
+    @console_ns.response(200, "Instruction generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters or flow/workflow not found")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -268,7 +293,7 @@ class InstructionGenerationTemplateApi(Resource):
     @console_ns.doc("get_instruction_template")
     @console_ns.doc(description="Get instruction generation template")
     @console_ns.expect(console_ns.models[InstructionTemplatePayload.__name__])
-    @console_ns.response(200, "Template retrieved successfully")
+    @console_ns.response(200, "Template retrieved successfully", console_ns.models[SimpleDataResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -300,7 +325,7 @@ class WorkflowGenerateApi(Resource):
     @console_ns.doc("generate_workflow_graph")
     @console_ns.doc(description="Generate a Dify workflow graph from natural language")
     @console_ns.expect(console_ns.models[WorkflowGeneratePayload.__name__])
-    @console_ns.response(200, "Workflow graph generated successfully")
+    @console_ns.response(200, "Workflow graph generated successfully", console_ns.models[GeneratorResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(402, "Provider quota exceeded")
     @setup_required
@@ -320,6 +345,22 @@ class WorkflowGenerateApi(Resource):
                 "errors": [{"code": "EMPTY_INSTRUCTION", "detail": "Instruction is required"}],
             }, 400
 
+        # Bound the prompt at the boundary too: an arbitrarily long
+        # instruction (or pasted document) blows the planner/builder context
+        # window and fails with an opaque provider error after two slow LLM
+        # calls. The cap matches the frontend textarea's maxLength.
+        if len(args.instruction) > _MAX_INSTRUCTION_LENGTH or len(args.ideal_output) > _MAX_INSTRUCTION_LENGTH:
+            return {
+                "error": "Instruction is too long",
+                "errors": [
+                    {
+                        "code": "INSTRUCTION_TOO_LONG",
+                        "detail": f"Instruction and ideal output must each be at most "
+                        f"{_MAX_INSTRUCTION_LENGTH} characters",
+                    }
+                ],
+            }, 400
+
         try:
             result = WorkflowGeneratorService.generate_workflow_graph(
                 tenant_id=current_tenant_id,

api/controllers/console/app/mcp_server.py

@@ -27,13 +27,19 @@ from models.model import App, AppMCPServer
 
 class MCPServerCreatePayload(BaseModel):
     description: str | None = Field(default=None, description="Server description")
-    parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="Server parameters configuration",
+    )
 
 
 class MCPServerUpdatePayload(BaseModel):
     id: str = Field(..., description="Server ID")
     description: str | None = Field(default=None, description="Server description")
-    parameters: dict[str, Any] = Field(..., description="Server parameters configuration")
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="Server parameters configuration",
+    )
     status: str | None = Field(default=None, description="Server status")
 
 

api/controllers/console/app/message.py

@@ -10,8 +10,8 @@ from sqlalchemy import exists, func, select
 from werkzeug.exceptions import InternalServerError, NotFound
 
 from controllers.common.controller_schemas import MessageFeedbackPayload as _MessageFeedbackPayloadBase
-from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import SimpleResultResponse, TextFileResponse
+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.app.error import (
     CompletionRequestError,
@@ -166,7 +166,7 @@ register_schema_models(
     MessageDetailResponse,
     MessageInfiniteScrollPaginationResponse,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, SimpleResultResponse, TextFileResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-messages")
@@ -174,7 +174,7 @@ class ChatMessageListApi(Resource):
     @console_ns.doc("list_chat_messages")
     @console_ns.doc(description="Get chat messages for a conversation with pagination")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[ChatMessagesQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ChatMessagesQuery))
     @console_ns.response(200, "Success", console_ns.models[MessageInfiniteScrollPaginationResponse.__name__])
     @console_ns.response(404, "Conversation not found")
     @login_required
@@ -372,8 +372,12 @@ class MessageFeedbackExportApi(Resource):
     @console_ns.doc("export_feedbacks")
     @console_ns.doc(description="Export user feedback data for Google Sheets")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[FeedbackExportQuery.__name__])
-    @console_ns.response(200, "Feedback data exported successfully")
+    @console_ns.doc(params=query_params_from_model(FeedbackExportQuery))
+    @console_ns.response(
+        200,
+        "Feedback data exported successfully",
+        console_ns.models[TextFileResponse.__name__],
+    )
     @console_ns.response(400, "Invalid parameters")
     @console_ns.response(500, "Internal server error")
     @get_app_model

api/controllers/console/app/model_config.py

@@ -5,7 +5,8 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import SimpleResultResponse
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
@@ -29,19 +30,44 @@ from services.app_model_config_service import AppModelConfigService
 class ModelConfigRequest(BaseModel):
     provider: str | None = Field(default=None, description="Model provider")
     model: str | None = Field(default=None, description="Model name")
-    configs: dict[str, Any] | None = Field(default=None, description="Model configuration parameters")
+    configs: dict[str, Any] | None = Field(
+        default=None,
+        description="Model configuration parameters",
+    )
     opening_statement: str | None = Field(default=None, description="Opening statement")
     suggested_questions: list[str] | None = Field(default=None, description="Suggested questions")
-    more_like_this: dict[str, Any] | None = Field(default=None, description="More like this configuration")
-    speech_to_text: dict[str, Any] | None = Field(default=None, description="Speech to text configuration")
-    text_to_speech: dict[str, Any] | None = Field(default=None, description="Text to speech configuration")
-    retrieval_model: dict[str, Any] | None = Field(default=None, description="Retrieval model configuration")
-    tools: list[dict[str, Any]] | None = Field(default=None, description="Available tools")
-    dataset_configs: dict[str, Any] | None = Field(default=None, description="Dataset configurations")
-    agent_mode: dict[str, Any] | None = Field(default=None, description="Agent mode configuration")
+    more_like_this: dict[str, Any] | None = Field(
+        default=None,
+        description="More like this configuration",
+    )
+    speech_to_text: dict[str, Any] | None = Field(
+        default=None,
+        description="Speech to text configuration",
+    )
+    text_to_speech: dict[str, Any] | None = Field(
+        default=None,
+        description="Text to speech configuration",
+    )
+    retrieval_model: dict[str, Any] | None = Field(
+        default=None,
+        description="Retrieval model configuration",
+    )
+    tools: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Available tools",
+    )
+    dataset_configs: dict[str, Any] | None = Field(
+        default=None,
+        description="Dataset configurations",
+    )
+    agent_mode: dict[str, Any] | None = Field(
+        default=None,
+        description="Agent mode configuration",
+    )
 
 
 register_schema_models(console_ns, ModelConfigRequest)
+register_response_schema_models(console_ns, SimpleResultResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/model-config")
@@ -50,7 +76,11 @@ class ModelConfigResource(Resource):
     @console_ns.doc(description="Update application model configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[ModelConfigRequest.__name__])
-    @console_ns.response(200, "Model configuration updated successfully")
+    @console_ns.response(
+        200,
+        "Model configuration updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @console_ns.response(400, "Invalid configuration")
     @console_ns.response(404, "App not found")
     @setup_required

api/controllers/console/app/ops_trace.py

@@ -1,15 +1,16 @@
 from typing import Any
 
 from flask import request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field
 from werkzeug.exceptions import BadRequest
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import TracingConfigCheckError, TracingConfigIsExist, TracingConfigNotExist
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
+from fields.base import ResponseModel
 from libs.login import login_required
 from models import App
 from services.ops_service import OpsService
@@ -21,10 +22,27 @@ class TraceProviderQuery(BaseModel):
 
 class TraceConfigPayload(BaseModel):
     tracing_provider: str = Field(..., description="Tracing provider name")
-    tracing_config: dict[str, Any] = Field(..., description="Tracing configuration data")
+    tracing_config: dict[str, Any] = Field(
+        ...,
+        description="Tracing configuration data",
+    )
+
+
+class TraceAppConfigResponse(ResponseModel):
+    result: str | None = None
+    error: str | None = None
+    has_not_configured: bool | None = None
+    id: str | None = None
+    app_id: str | None = None
+    tracing_provider: str | None = None
+    tracing_config: dict[str, Any] | None = Field(default=None)
+    is_active: bool | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
 
 
 register_schema_models(console_ns, TraceProviderQuery, TraceConfigPayload)
+register_response_schema_models(console_ns, TraceAppConfigResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/trace-config")
@@ -36,9 +54,11 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc("get_trace_app_config")
     @console_ns.doc(description="Get tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[TraceProviderQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TraceProviderQuery))
     @console_ns.response(
-        200, "Tracing configuration retrieved successfully", fields.Raw(description="Tracing configuration data")
+        200,
+        "Tracing configuration retrieved successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
@@ -63,7 +83,9 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[TraceConfigPayload.__name__])
     @console_ns.response(
-        201, "Tracing configuration created successfully", fields.Raw(description="Created configuration data")
+        201,
+        "Tracing configuration created successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
     )
     @console_ns.response(400, "Invalid request parameters or configuration already exists")
     @setup_required
@@ -90,7 +112,11 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc(description="Update an existing tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[TraceConfigPayload.__name__])
-    @console_ns.response(200, "Tracing configuration updated successfully", fields.Raw(description="Success response"))
+    @console_ns.response(
+        200,
+        "Tracing configuration updated successfully",
+        console_ns.models[TraceAppConfigResponse.__name__],
+    )
     @console_ns.response(400, "Invalid request parameters or configuration not found")
     @setup_required
     @login_required
@@ -113,7 +139,7 @@ class TraceAppConfigApi(Resource):
     @console_ns.doc("delete_trace_app_config")
     @console_ns.doc(description="Delete an existing tracing configuration for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[TraceProviderQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(TraceProviderQuery))
     @console_ns.response(204, "Tracing configuration deleted successfully")
     @console_ns.response(400, "Invalid request parameters or configuration not found")
     @setup_required

api/controllers/console/app/statistic.py

@@ -2,15 +2,16 @@ from decimal import Decimal
 
 import sqlalchemy as sa
 from flask import abort, jsonify, request
-from flask_restx import Resource, fields
+from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.datetime_utils import parse_time_range
 from libs.helper import convert_datetime_to_date
 from libs.login import login_required
@@ -31,7 +32,92 @@ class StatisticTimeRangeQuery(BaseModel):
         return value
 
 
+class DailyMessageStatisticItem(ResponseModel):
+    date: str
+    message_count: int
+
+
+class DailyMessageStatisticResponse(ResponseModel):
+    data: list[DailyMessageStatisticItem]
+
+
+class DailyConversationStatisticItem(ResponseModel):
+    date: str
+    conversation_count: int
+
+
+class DailyConversationStatisticResponse(ResponseModel):
+    data: list[DailyConversationStatisticItem]
+
+
+class DailyTerminalStatisticItem(ResponseModel):
+    date: str
+    terminal_count: int
+
+
+class DailyTerminalStatisticResponse(ResponseModel):
+    data: list[DailyTerminalStatisticItem]
+
+
+class DailyTokenCostStatisticItem(ResponseModel):
+    date: str
+    token_count: int
+    total_price: str | float
+    currency: str
+
+
+class DailyTokenCostStatisticResponse(ResponseModel):
+    data: list[DailyTokenCostStatisticItem]
+
+
+class AverageSessionInteractionStatisticItem(ResponseModel):
+    date: str
+    interactions: float
+
+
+class AverageSessionInteractionStatisticResponse(ResponseModel):
+    data: list[AverageSessionInteractionStatisticItem]
+
+
+class UserSatisfactionRateStatisticItem(ResponseModel):
+    date: str
+    rate: float
+
+
+class UserSatisfactionRateStatisticResponse(ResponseModel):
+    data: list[UserSatisfactionRateStatisticItem]
+
+
+class AverageResponseTimeStatisticItem(ResponseModel):
+    date: str
+    latency: float
+
+
+class AverageResponseTimeStatisticResponse(ResponseModel):
+    data: list[AverageResponseTimeStatisticItem]
+
+
+class TokensPerSecondStatisticItem(ResponseModel):
+    date: str
+    tps: float
+
+
+class TokensPerSecondStatisticResponse(ResponseModel):
+    data: list[TokensPerSecondStatisticItem]
+
+
 register_schema_models(console_ns, StatisticTimeRangeQuery)
+register_response_schema_models(
+    console_ns,
+    DailyMessageStatisticResponse,
+    DailyConversationStatisticResponse,
+    DailyTerminalStatisticResponse,
+    DailyTokenCostStatisticResponse,
+    AverageSessionInteractionStatisticResponse,
+    UserSatisfactionRateStatisticResponse,
+    AverageResponseTimeStatisticResponse,
+    TokensPerSecondStatisticResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/statistics/daily-messages")
@@ -39,11 +125,11 @@ class DailyMessageStatistic(Resource):
     @console_ns.doc("get_daily_message_statistics")
     @console_ns.doc(description="Get daily message statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily message statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily message count data")),
+        console_ns.models[DailyMessageStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -99,11 +185,11 @@ class DailyConversationStatistic(Resource):
     @console_ns.doc("get_daily_conversation_statistics")
     @console_ns.doc(description="Get daily conversation statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily conversation statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily conversation count data")),
+        console_ns.models[DailyConversationStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -158,11 +244,11 @@ class DailyTerminalsStatistic(Resource):
     @console_ns.doc("get_daily_terminals_statistics")
     @console_ns.doc(description="Get daily terminal/end-user statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily terminal statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily terminal count data")),
+        console_ns.models[DailyTerminalStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -218,11 +304,11 @@ class DailyTokenCostStatistic(Resource):
     @console_ns.doc("get_daily_token_cost_statistics")
     @console_ns.doc(description="Get daily token cost statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Daily token cost statistics retrieved successfully",
-        fields.List(fields.Raw(description="Daily token cost data")),
+        console_ns.models[DailyTokenCostStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -281,11 +367,11 @@ class AverageSessionInteractionStatistic(Resource):
     @console_ns.doc("get_average_session_interaction_statistics")
     @console_ns.doc(description="Get average session interaction statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Average session interaction statistics retrieved successfully",
-        fields.List(fields.Raw(description="Average session interaction data")),
+        console_ns.models[AverageSessionInteractionStatisticResponse.__name__],
     )
     @setup_required
     @login_required
@@ -360,11 +446,11 @@ class UserSatisfactionRateStatistic(Resource):
     @console_ns.doc("get_user_satisfaction_rate_statistics")
     @console_ns.doc(description="Get user satisfaction rate statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "User satisfaction rate statistics retrieved successfully",
-        fields.List(fields.Raw(description="User satisfaction rate data")),
+        console_ns.models[UserSatisfactionRateStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required
@@ -429,11 +515,11 @@ class AverageResponseTimeStatistic(Resource):
     @console_ns.doc("get_average_response_time_statistics")
     @console_ns.doc(description="Get average response time statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Average response time statistics retrieved successfully",
-        fields.List(fields.Raw(description="Average response time data")),
+        console_ns.models[AverageResponseTimeStatisticResponse.__name__],
     )
     @setup_required
     @login_required
@@ -489,11 +575,11 @@ class TokensPerSecondStatistic(Resource):
     @console_ns.doc("get_tokens_per_second_statistics")
     @console_ns.doc(description="Get tokens per second statistics for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[StatisticTimeRangeQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(StatisticTimeRangeQuery))
     @console_ns.response(
         200,
         "Tokens per second statistics retrieved successfully",
-        fields.List(fields.Raw(description="Tokens per second data")),
+        console_ns.models[TokensPerSecondStatisticResponse.__name__],
     )
     @get_app_model
     @setup_required

api/controllers/console/app/workflow.py

@@ -6,22 +6,34 @@ from typing import Any, NotRequired, TypedDict
 
 from flask import abort, request
 from flask_restx import Resource, fields
-from pydantic import AliasChoices, BaseModel, Field, ValidationError, field_validator
+from pydantic import AliasChoices, BaseModel, Field, RootModel, ValidationError, field_validator
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import BadRequest, Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.controller_schemas import DefaultBlockConfigQuery, WorkflowListQuery, WorkflowUpdatePayload
-from controllers.common.fields import NewAppResponse, SimpleResultResponse
+from controllers.common.errors import InvalidArgumentError
+from controllers.common.fields import GeneratedAppResponse, NewAppResponse, SimpleResultResponse
 from controllers.common.schema import (
+    query_params_from_model,
     register_response_schema_model,
     register_response_schema_models,
     register_schema_models,
 )
 from controllers.console import console_ns
-from controllers.console.app.error import ConversationCompletedError, DraftWorkflowNotExist, DraftWorkflowNotSync
+from controllers.console.app.error import (
+    ConversationCompletedError,
+    DraftWorkflowNotExist,
+    DraftWorkflowNotSync,
+)
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.app_config.features.file_upload.manager import FileUploadConfigManager
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -50,11 +62,12 @@ from graphon.file import helpers as file_helpers
 from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from graphon.variables import SecretVariable, SegmentType, VariableBase
+from graphon.variables.exc import VariableError
 from libs import helper
 from libs.datetime_utils import naive_utc_now
 from libs.helper import TimestampField, dump_response, to_timestamp, uuid_value
-from libs.login import current_account_with_tenant, login_required
-from models import App
+from libs.login import login_required
+from models import Account, App
 from models.model import AppMode
 from models.workflow import Workflow
 from repositories.workflow_collaboration_repository import WORKFLOW_ONLINE_USERS_PREFIX
@@ -86,16 +99,20 @@ class SyncDraftWorkflowPayload(BaseModel):
     graph: dict[str, Any]
     features: dict[str, Any]
     hash: str | None = None
-    environment_variables: list[dict[str, Any]] = Field(default_factory=list)
-    conversation_variables: list[dict[str, Any]] = Field(default_factory=list)
+    environment_variables: list[dict[str, Any]] = Field(
+        default_factory=list,
+    )
+    conversation_variables: list[dict[str, Any]] = Field(
+        default_factory=list,
+    )
 
 
 class BaseWorkflowRunPayload(BaseModel):
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class AdvancedChatWorkflowRunPayload(BaseWorkflowRunPayload):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
     query: str = ""
     conversation_id: str | None = None
     parent_message_id: str | None = None
@@ -109,11 +126,11 @@ class AdvancedChatWorkflowRunPayload(BaseWorkflowRunPayload):
 
 
 class IterationNodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class LoopNodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class DraftWorkflowRunPayload(BaseWorkflowRunPayload):
@@ -138,7 +155,10 @@ class ConvertToWorkflowPayload(BaseModel):
 
 
 class WorkflowFeaturesPayload(BaseModel):
-    features: dict[str, Any] = Field(..., description="Workflow feature configuration")
+    features: dict[str, Any] = Field(
+        ...,
+        description="Workflow feature configuration",
+    )
 
 
 class WorkflowOnlineUsersPayload(BaseModel):
@@ -154,7 +174,7 @@ class WorkflowConversationVariableResponse(ResponseModel):
     id: str
     name: str
     value_type: str
-    value: Any = Field(json_schema_extra={"type": "object"})
+    value: Any
     description: str
 
     @field_validator("value_type", mode="before")
@@ -173,7 +193,7 @@ class PipelineVariableResponse(ResponseModel):
     max_length: int | None = None
     required: bool
     unit: str | None = None
-    default_value: Any = Field(default=None, json_schema_extra={"type": "object"})
+    default_value: Any = Field(default=None)
     options: list[str] | None = None
     placeholder: str | None = None
     tooltips: str | None = None
@@ -190,14 +210,18 @@ class WorkflowEnvironmentVariableResponse(ResponseModel):
     value_type: str
     id: str
     name: str
-    value: Any = Field(json_schema_extra={"type": "object"})
+    value: Any
     description: str
 
 
 class WorkflowResponse(ResponseModel):
     id: str
-    graph: dict[str, Any] = Field(validation_alias=AliasChoices("graph_dict", "graph"))
-    features: dict[str, Any] = Field(validation_alias=AliasChoices("features_dict", "features"))
+    graph: dict[str, Any] = Field(
+        validation_alias=AliasChoices("graph_dict", "graph"),
+    )
+    features: dict[str, Any] = Field(
+        validation_alias=AliasChoices("features_dict", "features"),
+    )
     hash: str = Field(validation_alias=AliasChoices("unique_hash", "hash"))
     version: str
     marked_name: str
@@ -254,6 +278,46 @@ class WorkflowOnlineUsersResponse(ResponseModel):
     data: list[WorkflowOnlineUsersByApp]
 
 
+class WorkflowPublishResponse(ResponseModel):
+    result: str
+    created_at: int
+
+
+class WorkflowRestoreResponse(ResponseModel):
+    result: str
+    hash: str
+    updated_at: int
+
+
+class DefaultBlockConfigsResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
+class DefaultBlockConfigResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class HumanInputFormPreviewResponse(ResponseModel):
+    form_id: str
+    node_id: str
+    node_title: str
+    form_content: str
+    inputs: list[dict[str, Any]] = Field(default_factory=list)
+    actions: list[dict[str, Any]] = Field(default_factory=list)
+    display_in_ui: bool | None = None
+    form_token: str | None = None
+    resolved_default_values: dict[str, Any] = Field(default_factory=dict)
+    expiration_time: int | None = None
+
+
+class HumanInputFormSubmitResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class EmptyObjectResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 class DraftWorkflowTriggerRunPayload(BaseModel):
     node_id: str
 
@@ -291,6 +355,14 @@ register_response_schema_models(
     WorkflowOnlineUser,
     WorkflowOnlineUsersByApp,
     WorkflowOnlineUsersResponse,
+    WorkflowPublishResponse,
+    WorkflowRestoreResponse,
+    DefaultBlockConfigsResponse,
+    DefaultBlockConfigResponse,
+    HumanInputFormPreviewResponse,
+    HumanInputFormSubmitResponse,
+    EmptyObjectResponse,
+    GeneratedAppResponse,
     NewAppResponse,
     SimpleResultResponse,
 )
@@ -401,13 +473,12 @@ class DraftWorkflowApi(Resource):
     )
     @console_ns.response(400, "Invalid workflow configuration")
     @console_ns.response(403, "Permission denied")
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Sync draft workflow
         """
-        current_user, _ = current_account_with_tenant()
-
         content_type = request.headers.get("Content-Type", "")
 
         if "application/json" in content_type:
@@ -447,6 +518,8 @@ class DraftWorkflowApi(Resource):
             )
         except WorkflowHashNotEqualError:
             raise DraftWorkflowNotSync()
+        except VariableError as e:
+            raise InvalidArgumentError(description=str(e))
 
         return {
             "result": "success",
@@ -461,20 +534,19 @@ class AdvancedChatDraftWorkflowRunApi(Resource):
     @console_ns.doc(description="Run draft workflow for advanced chat application")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AdvancedChatWorkflowRunPayload.__name__])
-    @console_ns.response(200, "Workflow run started successfully")
+    @console_ns.response(200, "Workflow run started successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Run draft workflow
         """
-        current_user, _ = current_account_with_tenant()
-
         args_model = AdvancedChatWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = args_model.model_dump(exclude_none=True)
 
@@ -507,19 +579,23 @@ class AdvancedChatDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node for advanced chat")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[IterationNodeRunPayload.__name__])
-    @console_ns.response(200, "Iteration node run started successfully")
+    @console_ns.response(
+        200,
+        "Iteration node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow iteration node
         """
-        current_user, _ = current_account_with_tenant()
         args = IterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -545,19 +621,23 @@ class WorkflowDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[IterationNodeRunPayload.__name__])
-    @console_ns.response(200, "Workflow iteration node run started successfully")
+    @console_ns.response(
+        200,
+        "Workflow iteration node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow iteration node
         """
-        current_user, _ = current_account_with_tenant()
         args = IterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -583,19 +663,19 @@ class AdvancedChatDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node for advanced chat")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[LoopNodeRunPayload.__name__])
-    @console_ns.response(200, "Loop node run started successfully")
+    @console_ns.response(200, "Loop node run started successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow loop node
         """
-        current_user, _ = current_account_with_tenant()
         args = LoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -621,19 +701,23 @@ class WorkflowDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[LoopNodeRunPayload.__name__])
-    @console_ns.response(200, "Workflow loop node run started successfully")
+    @console_ns.response(
+        200,
+        "Workflow loop node run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(404, "Node not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow loop node
         """
-        current_user, _ = current_account_with_tenant()
         args = LoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -661,7 +745,10 @@ class HumanInputFormPreviewPayload(BaseModel):
 
 
 class HumanInputFormSubmitPayload(BaseModel):
-    form_inputs: dict[str, Any] = Field(..., description="Values the user provides for the form's own fields")
+    form_inputs: dict[str, Any] = Field(
+        ...,
+        description="Values the user provides for the form's own fields",
+    )
     inputs: dict[str, Any] = Field(
         ...,
         description="Values used to fill missing upstream variables referenced in form_content",
@@ -691,16 +778,17 @@ class AdvancedChatDraftHumanInputFormPreviewApi(Resource):
     @console_ns.doc(description="Get human input form preview for advanced chat workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormPreviewPayload.__name__])
+    @console_ns.response(200, "Human input form preview", console_ns.models[HumanInputFormPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Preview human input form content and placeholders
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormPreviewPayload.model_validate(console_ns.payload or {})
         inputs = args.inputs
 
@@ -720,16 +808,21 @@ class AdvancedChatDraftHumanInputFormRunApi(Resource):
     @console_ns.doc(description="Submit human input form preview for advanced chat workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(
+        200,
+        "Human input form submission result",
+        console_ns.models[HumanInputFormSubmitResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Submit human input form preview
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormSubmitPayload.model_validate(console_ns.payload or {})
         workflow_service = WorkflowService()
         result = workflow_service.submit_human_input_form_preview(
@@ -749,16 +842,17 @@ class WorkflowDraftHumanInputFormPreviewApi(Resource):
     @console_ns.doc(description="Get human input form preview for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormPreviewPayload.__name__])
+    @console_ns.response(200, "Human input form preview", console_ns.models[HumanInputFormPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Preview human input form content and placeholders
         """
-        current_user, _ = current_account_with_tenant()
         args = HumanInputFormPreviewPayload.model_validate(console_ns.payload or {})
         inputs = args.inputs
 
@@ -778,16 +872,21 @@ class WorkflowDraftHumanInputFormRunApi(Resource):
     @console_ns.doc(description="Submit human input form preview for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(
+        200,
+        "Human input form submission result",
+        console_ns.models[HumanInputFormSubmitResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Submit human input form preview
         """
-        current_user, _ = current_account_with_tenant()
         workflow_service = WorkflowService()
         args = HumanInputFormSubmitPayload.model_validate(console_ns.payload or {})
         result = workflow_service.submit_human_input_form_preview(
@@ -807,16 +906,17 @@ class WorkflowDraftHumanInputDeliveryTestApi(Resource):
     @console_ns.doc(description="Test human input delivery for workflow")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models[HumanInputDeliveryTestPayload.__name__])
+    @console_ns.response(200, "Human input delivery test result", console_ns.models[EmptyObjectResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Test human input delivery
         """
-        current_user, _ = current_account_with_tenant()
         workflow_service = WorkflowService()
         args = HumanInputDeliveryTestPayload.model_validate(console_ns.payload or {})
         workflow_service.test_human_input_delivery(
@@ -835,18 +935,22 @@ class DraftWorkflowRunApi(Resource):
     @console_ns.doc(description="Run draft workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[DraftWorkflowRunPayload.__name__])
-    @console_ns.response(200, "Draft workflow run started successfully")
+    @console_ns.response(
+        200,
+        "Draft workflow run started successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Run draft workflow
         """
-        current_user, _ = current_account_with_tenant()
         args = DraftWorkflowRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         external_trace_id = get_external_trace_id(request)
@@ -911,12 +1015,12 @@ class DraftWorkflowNodeRunApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Run draft workflow node
         """
-        current_user, _ = current_account_with_tenant()
         args_model = DraftWorkflowNodeRunPayload.model_validate(console_ns.payload or {})
         args = args_model.model_dump(exclude_none=True)
 
@@ -977,16 +1081,17 @@ class PublishedWorkflowApi(Resource):
         return dump_response(WorkflowResponse, workflow)
 
     @console_ns.expect(console_ns.models[PublishWorkflowPayload.__name__])
+    @console_ns.response(200, "Workflow published successfully", console_ns.models[WorkflowPublishResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Publish workflow
         """
-        current_user, _ = current_account_with_tenant()
 
         args = PublishWorkflowPayload.model_validate(console_ns.payload or {})
 
@@ -1020,7 +1125,11 @@ class DefaultBlockConfigsApi(Resource):
     @console_ns.doc("get_default_block_configs")
     @console_ns.doc(description="Get default block configurations for workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Default block configurations retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configurations retrieved successfully",
+        console_ns.models[DefaultBlockConfigsResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -1040,9 +1149,13 @@ class DefaultBlockConfigApi(Resource):
     @console_ns.doc("get_default_block_config")
     @console_ns.doc(description="Get default block configuration by type")
     @console_ns.doc(params={"app_id": "Application ID", "block_type": "Block type"})
-    @console_ns.response(200, "Default block configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configuration retrieved successfully",
+        console_ns.models[DefaultBlockConfigResponse.__name__],
+    )
     @console_ns.response(404, "Block type not found")
-    @console_ns.expect(console_ns.models[DefaultBlockConfigQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(DefaultBlockConfigQuery))
     @setup_required
     @login_required
     @account_initialization_required
@@ -1083,14 +1196,14 @@ class ConvertToWorkflowApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.CHAT, AppMode.COMPLETION])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Convert basic mode of chatbot app to workflow mode
         Convert expert mode of chatbot app to workflow mode
         Convert Completion App to Workflow App
         """
-        current_user, _ = current_account_with_tenant()
 
         payload = console_ns.payload or {}
         args = ConvertToWorkflowPayload.model_validate(payload).model_dump(exclude_none=True)
@@ -1122,9 +1235,9 @@ class WorkflowFeaturesApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account, app_model: App):
 
         args = WorkflowFeaturesPayload.model_validate(console_ns.payload or {})
         features = args.features
@@ -1137,7 +1250,7 @@ class WorkflowFeaturesApi(Resource):
 
 @console_ns.route("/apps/<uuid:app_id>/workflows")
 class PublishedAllWorkflowApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowListQuery))
     @console_ns.doc("get_all_published_workflows")
     @console_ns.doc(description="Get all published workflows for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
@@ -1150,12 +1263,12 @@ class PublishedAllWorkflowApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def get(self, app_model: App):
+    def get(self, current_user: Account, app_model: App):
         """
         Get published workflows
         """
-        current_user, _ = current_account_with_tenant()
 
         args = WorkflowListQuery.model_validate(request.args.to_dict(flat=True))
         page = args.page
@@ -1192,16 +1305,16 @@ class DraftWorkflowRestoreApi(Resource):
     @console_ns.doc("restore_workflow_to_draft")
     @console_ns.doc(description="Restore a published workflow version into the draft workflow")
     @console_ns.doc(params={"app_id": "Application ID", "workflow_id": "Published workflow ID"})
-    @console_ns.response(200, "Workflow restored successfully")
+    @console_ns.response(200, "Workflow restored successfully", console_ns.models[WorkflowRestoreResponse.__name__])
     @console_ns.response(400, "Source workflow must be published")
     @console_ns.response(404, "Workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, workflow_id: str):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account, app_model: App, workflow_id: str):
         workflow_service = WorkflowService()
 
         try:
@@ -1237,12 +1350,12 @@ class WorkflowByIdApi(Resource):
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def patch(self, app_model: App, workflow_id: str):
+    def patch(self, current_user: Account, app_model: App, workflow_id: str):
         """
         Update workflow attributes
         """
-        current_user, _ = current_account_with_tenant()
         args = WorkflowUpdatePayload.model_validate(console_ns.payload or {})
 
         # Prepare update data
@@ -1277,6 +1390,7 @@ class WorkflowByIdApi(Resource):
     @account_initialization_required
     @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
     @edit_permission_required
+    @console_ns.response(204, "Workflow deleted successfully")
     def delete(self, app_model: App, workflow_id: str):
         """
         Delete workflow
@@ -1348,19 +1462,23 @@ class DraftWorkflowTriggerRunApi(Resource):
             },
         )
     )
-    @console_ns.response(200, "Trigger event received and workflow executed successfully")
+    @console_ns.response(
+        200,
+        "Trigger event received and workflow executed successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Poll for trigger events and execute full workflow when event arrives
         """
-        current_user, _ = current_account_with_tenant()
         args = DraftWorkflowTriggerRunPayload.model_validate(console_ns.payload or {})
         node_id = args.node_id
         workflow_service = WorkflowService()
@@ -1412,19 +1530,23 @@ class DraftWorkflowTriggerNodeApi(Resource):
     @console_ns.doc("poll_draft_workflow_trigger_node")
     @console_ns.doc(description="Poll for trigger events and execute single node when event arrives")
     @console_ns.doc(params={"app_id": "Application ID", "node_id": "Node ID"})
-    @console_ns.response(200, "Trigger event received and node executed successfully")
+    @console_ns.response(
+        200,
+        "Trigger event received and node executed successfully",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App, node_id: str):
+    def post(self, current_user: Account, app_model: App, node_id: str):
         """
         Poll for trigger events and execute single node when event arrives
         """
-        current_user, _ = current_account_with_tenant()
 
         workflow_service = WorkflowService()
         draft_workflow = workflow_service.get_draft_workflow(app_model)
@@ -1492,19 +1614,19 @@ class DraftWorkflowTriggerRunAllApi(Resource):
     @console_ns.doc(description="Full workflow debug when the start node is a trigger")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[DraftWorkflowTriggerRunAllPayload.__name__])
-    @console_ns.response(200, "Workflow executed successfully")
+    @console_ns.response(200, "Workflow executed successfully", console_ns.models[GeneratedAppResponse.__name__])
     @console_ns.response(403, "Permission denied")
     @console_ns.response(500, "Internal server error")
     @setup_required
     @login_required
     @account_initialization_required
     @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
     @edit_permission_required
-    def post(self, app_model: App):
+    def post(self, current_user: Account, app_model: App):
         """
         Full workflow debug when the start node is a trigger
         """
-        current_user, _ = current_account_with_tenant()
 
         args = DraftWorkflowTriggerRunAllPayload.model_validate(console_ns.payload or {})
         node_ids = args.node_ids
@@ -1565,7 +1687,8 @@ class WorkflowOnlineUsersApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         args = WorkflowOnlineUsersPayload.model_validate(console_ns.payload or {})
 
         app_ids = args.app_ids
@@ -1575,7 +1698,6 @@ class WorkflowOnlineUsersApi(Resource):
         if not app_ids:
             return {"data": []}
 
-        _, current_tenant_id = current_account_with_tenant()
         workflow_service = WorkflowService()
         accessible_app_ids = workflow_service.get_accessible_app_ids(app_ids, current_tenant_id)
         ordered_accessible_app_ids = [app_id for app_id in app_ids if app_id in accessible_app_ids]

api/controllers/console/app/workflow_app_log.py

@@ -7,7 +7,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -166,7 +166,7 @@ class WorkflowAppLogApi(Resource):
     @console_ns.doc("get_workflow_app_logs")
     @console_ns.doc(description="Get workflow application execution logs")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowAppLogQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAppLogQuery))
     @console_ns.response(
         200,
         "Workflow app logs retrieved successfully",
@@ -209,7 +209,7 @@ class WorkflowArchivedLogApi(Resource):
     @console_ns.doc("get_workflow_archived_logs")
     @console_ns.doc(description="Get workflow archived execution logs")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowAppLogQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowAppLogQuery))
     @console_ns.response(
         200,
         "Workflow archived logs retrieved successfully",

api/controllers/console/app/workflow_draft_variable.py

@@ -1,7 +1,7 @@
 import logging
 from collections.abc import Callable
 from functools import wraps
-from typing import Any, Concatenate, TypedDict
+from typing import Any, Concatenate, TypedDict, override
 from uuid import UUID
 
 from flask import Response, request
@@ -9,7 +9,9 @@ from flask_restx import Resource, fields, marshal, marshal_with
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.fields import SimpleResultResponse
+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.app.error import (
     DraftWorkflowNotExist,
@@ -21,13 +23,13 @@ from controllers.console.wraps import (
     setup_required,
     with_current_user,
 )
-from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
 from factories import variable_factory
 from factories.file_factory import build_from_mapping, build_from_mappings
 from factories.variable_factory import build_segment_with_type
+from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
 from graphon.variables.segment_group import SegmentGroup
 from graphon.variables.segments import ArrayFileSegment, FileSegment, Segment
@@ -42,6 +44,28 @@ logger = logging.getLogger(__name__)
 _file_access_controller = DatabaseFileAccessController()
 
 
+class OpaqueRawField(fields.Raw):
+    @override
+    def schema(self) -> dict[str, object]:
+        return {"type": "object"}
+
+
+class JsonValueRawField(fields.Raw):
+    @override
+    def schema(self) -> dict[str, object]:
+        return {
+            "anyOf": [
+                {"type": "string"},
+                {"type": "integer"},
+                {"type": "number"},
+                {"type": "boolean"},
+                {"type": "object", "additionalProperties": True},
+                {"type": "array", "items": {}},
+                {"type": "null"},
+            ]
+        }
+
+
 class WorkflowDraftVariableListQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=100_000, description="Page number")
     limit: int = Field(default=20, ge=1, le=100, description="Items per page")
@@ -54,12 +78,33 @@ class WorkflowDraftVariableUpdatePayload(BaseModel):
 
 class ConversationVariableUpdatePayload(BaseModel):
     conversation_variables: list[dict[str, Any]] = Field(
-        ..., description="Conversation variables for the draft workflow"
+        ...,
+        description="Conversation variables for the draft workflow",
     )
 
 
 class EnvironmentVariableUpdatePayload(BaseModel):
-    environment_variables: list[dict[str, Any]] = Field(..., description="Environment variables for the draft workflow")
+    environment_variables: list[dict[str, Any]] = Field(
+        ...,
+        description="Environment variables for the draft workflow",
+    )
+
+
+class EnvironmentVariableItemResponse(ResponseModel):
+    id: str
+    type: str
+    name: str
+    description: str | None = None
+    selector: list[str]
+    value_type: str
+    value: Any
+    edited: bool
+    visible: bool
+    editable: bool
+
+
+class EnvironmentVariableListResponse(ResponseModel):
+    items: list[EnvironmentVariableItemResponse]
 
 
 register_schema_models(
@@ -69,6 +114,7 @@ register_schema_models(
     ConversationVariableUpdatePayload,
     EnvironmentVariableUpdatePayload,
 )
+register_response_schema_models(console_ns, SimpleResultResponse, EnvironmentVariableListResponse)
 
 
 def _convert_values_to_json_serializable_object(value: Segment):
@@ -155,8 +201,8 @@ _WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS = {
 
 _WORKFLOW_DRAFT_VARIABLE_FIELDS = {
     **_WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS,
-    "value": fields.Raw(attribute=_serialize_var_value),
-    "full_content": fields.Raw(attribute=_serialize_full_content),
+    "value": JsonValueRawField(attribute=_serialize_var_value),
+    "full_content": OpaqueRawField(attribute=_serialize_full_content),
 }
 
 _WORKFLOW_DRAFT_ENV_VARIABLE_FIELDS = {
@@ -181,7 +227,7 @@ def _get_items(var_list: WorkflowDraftVariableList) -> list[WorkflowDraftVariabl
 
 _WORKFLOW_DRAFT_VARIABLE_LIST_WITHOUT_VALUE_FIELDS = {
     "items": fields.List(fields.Nested(_WORKFLOW_DRAFT_VARIABLE_WITHOUT_VALUE_FIELDS), attribute=_get_items),
-    "total": fields.Raw(),
+    "total": fields.Integer,
 }
 
 _WORKFLOW_DRAFT_VARIABLE_LIST_FIELDS = {
@@ -248,7 +294,7 @@ def _api_prerequisite[T, **P, R](
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/variables")
 class WorkflowVariableCollectionApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowDraftVariableListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowDraftVariableListQuery))
     @console_ns.doc("get_workflow_variables")
     @console_ns.doc(description="Get draft workflow variables")
     @console_ns.doc(params={"app_id": "Application ID"})
@@ -544,7 +590,11 @@ class ConversationVariableCollectionApi(Resource):
     @console_ns.doc("update_conversation_variables")
     @console_ns.doc(description="Update conversation variables for workflow draft")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Conversation variables updated successfully")
+    @console_ns.response(
+        200,
+        "Conversation variables updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -587,7 +637,11 @@ class EnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("get_environment_variables")
     @console_ns.doc(description="Get environment variables for workflow")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Environment variables retrieved successfully")
+    @console_ns.response(
+        200,
+        "Environment variables retrieved successfully",
+        console_ns.models[EnvironmentVariableListResponse.__name__],
+    )
     @console_ns.response(404, "Draft workflow not found")
     @_api_prerequisite
     def get(self, _current_user: Account, app_model: App):
@@ -625,7 +679,11 @@ class EnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("update_environment_variables")
     @console_ns.doc(description="Update environment variables for workflow draft")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Environment variables updated successfully")
+    @console_ns.response(
+        200,
+        "Environment variables updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/workflow_node_output_inspector.py

@@ -30,6 +30,8 @@ from uuid import UUID
 from flask import Response
 from flask_restx import Resource
 
+from controllers.common.fields import EventStreamResponse
+from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -38,8 +40,13 @@ from libs.login import login_required
 from models import App, AppMode
 from services.workflow import inspector_events
 from services.workflow.node_output_inspector_service import (
+    CheckResultView,
     NodeOutputInspectorError,
     NodeOutputInspectorService,
+    NodeOutputsView,
+    NodeOutputView,
+    OutputPreviewView,
+    WorkflowRunSnapshotView,
 )
 
 logger = logging.getLogger(__name__)
@@ -54,6 +61,16 @@ _HEARTBEAT_EVERY_TICKS = 15
 # many ticks (= seconds).
 _STREAM_HARD_TIMEOUT_TICKS = 1800  # 30 min
 
+register_response_schema_models(
+    console_ns,
+    EventStreamResponse,
+    CheckResultView,
+    NodeOutputView,
+    NodeOutputsView,
+    WorkflowRunSnapshotView,
+    OutputPreviewView,
+)
+
 
 def _service() -> NodeOutputInspectorService:
     """One-line factory so tests can monkeypatch a stub if needed."""
@@ -124,6 +141,7 @@ class WorkflowDraftRunNodeOutputsApi(Resource):
     @console_ns.doc("get_workflow_draft_run_node_outputs")
     @console_ns.doc(description="Snapshot of every node's declared outputs for a draft workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(200, "Workflow run node outputs", console_ns.models[WorkflowRunSnapshotView.__name__])
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
@@ -146,6 +164,7 @@ class WorkflowDraftRunNodeOutputDetailApi(Resource):
             "node_id": "Node ID inside the workflow graph",
         }
     )
+    @console_ns.response(200, "Workflow run node output detail", console_ns.models[NodeOutputsView.__name__])
     @console_ns.response(404, "Workflow run / node not found")
     @setup_required
     @login_required
@@ -171,6 +190,7 @@ class WorkflowDraftRunNodeOutputPreviewApi(Resource):
             "output_name": "Declared output name as exposed by Composer",
         }
     )
+    @console_ns.response(200, "Workflow run node output preview", console_ns.models[OutputPreviewView.__name__])
     @console_ns.response(404, "Workflow run / node / output not found")
     @setup_required
     @login_required
@@ -309,6 +329,11 @@ class WorkflowDraftRunNodeOutputEventsApi(Resource):
     @console_ns.doc("stream_workflow_draft_run_node_output_events")
     @console_ns.doc(description="Server-Sent Events stream of inspector deltas for a draft workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(
+        200,
+        "Workflow run node output event stream",
+        console_ns.models[EventStreamResponse.__name__],
+    )
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
@@ -338,6 +363,7 @@ class WorkflowPublishedRunNodeOutputsApi(Resource):
     @console_ns.doc("get_workflow_published_run_node_outputs")
     @console_ns.doc(description="Snapshot of every node's declared outputs for a published workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(200, "Workflow run node outputs", console_ns.models[WorkflowRunSnapshotView.__name__])
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required
@@ -360,6 +386,7 @@ class WorkflowPublishedRunNodeOutputDetailApi(Resource):
             "node_id": "Node ID inside the workflow graph",
         }
     )
+    @console_ns.response(200, "Workflow run node output detail", console_ns.models[NodeOutputsView.__name__])
     @console_ns.response(404, "Workflow run / node not found")
     @setup_required
     @login_required
@@ -386,6 +413,7 @@ class WorkflowPublishedRunNodeOutputPreviewApi(Resource):
             "output_name": "Declared output name as exposed by Composer",
         }
     )
+    @console_ns.response(200, "Workflow run node output preview", console_ns.models[OutputPreviewView.__name__])
     @console_ns.response(404, "Workflow run / node / output not found")
     @setup_required
     @login_required
@@ -402,6 +430,11 @@ class WorkflowPublishedRunNodeOutputEventsApi(Resource):
     @console_ns.doc("stream_workflow_published_run_node_output_events")
     @console_ns.doc(description="Server-Sent Events stream of inspector deltas for a published workflow run.")
     @console_ns.doc(params={"app_id": "Application ID", "run_id": "Workflow run ID"})
+    @console_ns.response(
+        200,
+        "Workflow run node output event stream",
+        console_ns.models[EventStreamResponse.__name__],
+    )
     @console_ns.response(404, "Workflow run not found")
     @setup_required
     @login_required

api/controllers/console/app/workflow_run.py

@@ -9,6 +9,7 @@ from sqlalchemy import select
 from sqlalchemy.orm import sessionmaker
 
 from configs import dify_config
+from controllers.common.errors import NotFoundError
 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.app.wraps import get_app_model
@@ -18,7 +19,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from controllers.web.error import NotFoundError
 from core.workflow.human_input_forms import load_form_tokens_by_form_id as _load_form_tokens_by_form_id
 from extensions.ext_database import db
 from fields.base import ResponseModel

api/controllers/console/app/workflow_statistic.py

@@ -3,11 +3,12 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy.orm import sessionmaker
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.datetime_utils import parse_time_range
 from libs.login import login_required
 from models.account import Account
@@ -28,7 +29,50 @@ class WorkflowStatisticQuery(BaseModel):
         return value
 
 
+class WorkflowDailyRunsStatisticItem(ResponseModel):
+    date: str
+    runs: int
+
+
+class WorkflowDailyRunsStatisticResponse(ResponseModel):
+    data: list[WorkflowDailyRunsStatisticItem]
+
+
+class WorkflowDailyTerminalsStatisticItem(ResponseModel):
+    date: str
+    terminal_count: int
+
+
+class WorkflowDailyTerminalsStatisticResponse(ResponseModel):
+    data: list[WorkflowDailyTerminalsStatisticItem]
+
+
+class WorkflowDailyTokenCostStatisticItem(ResponseModel):
+    date: str
+    token_count: int
+
+
+class WorkflowDailyTokenCostStatisticResponse(ResponseModel):
+    data: list[WorkflowDailyTokenCostStatisticItem]
+
+
+class WorkflowAverageAppInteractionStatisticItem(ResponseModel):
+    date: str
+    interactions: float
+
+
+class WorkflowAverageAppInteractionStatisticResponse(ResponseModel):
+    data: list[WorkflowAverageAppInteractionStatisticItem]
+
+
 register_schema_models(console_ns, WorkflowStatisticQuery)
+register_response_schema_models(
+    console_ns,
+    WorkflowDailyRunsStatisticResponse,
+    WorkflowDailyTerminalsStatisticResponse,
+    WorkflowDailyTokenCostStatisticResponse,
+    WorkflowAverageAppInteractionStatisticResponse,
+)
 
 
 @console_ns.route("/apps/<uuid:app_id>/workflow/statistics/daily-conversations")
@@ -41,8 +85,12 @@ class WorkflowDailyRunsStatistic(Resource):
     @console_ns.doc("get_workflow_daily_runs_statistic")
     @console_ns.doc(description="Get workflow daily runs statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Daily runs statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Daily runs statistics retrieved successfully",
+        console_ns.models[WorkflowDailyRunsStatisticResponse.__name__],
+    )
     @get_app_model
     @setup_required
     @login_required
@@ -80,8 +128,12 @@ class WorkflowDailyTerminalsStatistic(Resource):
     @console_ns.doc("get_workflow_daily_terminals_statistic")
     @console_ns.doc(description="Get workflow daily terminals statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Daily terminals statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Daily terminals statistics retrieved successfully",
+        console_ns.models[WorkflowDailyTerminalsStatisticResponse.__name__],
+    )
     @get_app_model
     @setup_required
     @login_required
@@ -119,8 +171,12 @@ class WorkflowDailyTokenCostStatistic(Resource):
     @console_ns.doc("get_workflow_daily_token_cost_statistic")
     @console_ns.doc(description="Get workflow daily token cost statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Daily token cost statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Daily token cost statistics retrieved successfully",
+        console_ns.models[WorkflowDailyTokenCostStatisticResponse.__name__],
+    )
     @get_app_model
     @setup_required
     @login_required
@@ -158,8 +214,12 @@ class WorkflowAverageAppInteractionStatistic(Resource):
     @console_ns.doc("get_workflow_average_app_interaction_statistic")
     @console_ns.doc(description="Get workflow average app interaction statistics")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[WorkflowStatisticQuery.__name__])
-    @console_ns.response(200, "Average app interaction statistics retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WorkflowStatisticQuery))
+    @console_ns.response(
+        200,
+        "Average app interaction statistics retrieved successfully",
+        console_ns.models[WorkflowAverageAppInteractionStatisticResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/workflow_trigger.py

@@ -9,7 +9,7 @@ from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.login import login_required
@@ -86,7 +86,7 @@ register_schema_models(
 class WebhookTriggerApi(Resource):
     """Webhook Trigger API"""
 
-    @console_ns.expect(console_ns.models[Parser.__name__])
+    @console_ns.doc(params=query_params_from_model(Parser))
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/auth/activate.py

@@ -2,15 +2,17 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
+from configs import dify_config
 from constants.languages import supported_language
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
-from controllers.console.error import AlreadyActivateError
+from controllers.console.error import AccountInFreezeError, AlreadyActivateError
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
 from libs.helper import EmailStr, timezone
 from models import AccountStatus
 from services.account_service import RegisterService
+from services.billing_service import BillingService
 
 
 class ActivateCheckQuery(BaseModel):
@@ -67,7 +69,7 @@ register_schema_models(
 class ActivateCheckApi(Resource):
     @console_ns.doc("check_activation_token")
     @console_ns.doc(description="Check if activation token is valid")
-    @console_ns.expect(console_ns.models[ActivateCheckQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ActivateCheckQuery))
     @console_ns.response(
         200,
         "Success",
@@ -120,9 +122,12 @@ class ActivateApi(Resource):
         if invitation is None:
             raise AlreadyActivateError()
 
+        account = invitation["account"]
+        if dify_config.BILLING_ENABLED and BillingService.is_email_in_freeze(account.email):
+            raise AccountInFreezeError()
+
         RegisterService.revoke_token(args.workspace_id, normalized_request_email, args.token)
 
-        account = invitation["account"]
         account.name = args.name
 
         account.interface_language = args.interface_language

api/controllers/console/auth/data_source_bearer_auth.py

@@ -3,6 +3,7 @@ from uuid import UUID
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
+from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from fields.base import ResponseModel
 from libs.login import login_required
@@ -33,7 +34,12 @@ class ApiKeyAuthDataSourceListResponse(ResponseModel):
 
 
 register_schema_models(console_ns, ApiKeyAuthBindingPayload)
-register_response_schema_models(console_ns, ApiKeyAuthDataSourceItem, ApiKeyAuthDataSourceListResponse)
+register_response_schema_models(
+    console_ns,
+    SimpleResultResponse,
+    ApiKeyAuthDataSourceItem,
+    ApiKeyAuthDataSourceListResponse,
+)
 
 
 @console_ns.route("/api-key-auth/data-source")
@@ -64,6 +70,7 @@ class ApiKeyAuthDataSource(Resource):
 
 @console_ns.route("/api-key-auth/data-source/binding")
 class ApiKeyAuthDataSourceBinding(Resource):
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/auth/data_source_oauth.py

@@ -7,7 +7,8 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 from configs import dify_config
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import RedirectResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_model, register_schema_models
 from libs.login import login_required
 from libs.oauth_data_source import NotionOAuth
 
@@ -29,12 +30,24 @@ class OAuthDataSourceSyncResponse(BaseModel):
     result: str = Field(description="Operation result")
 
 
+class OAuthDataSourceCallbackQuery(BaseModel):
+    code: str | None = Field(default=None, description="Authorization code from OAuth provider")
+    error: str | None = Field(default=None, description="Error message from OAuth provider")
+
+
+class OAuthDataSourceBindingQuery(BaseModel):
+    code: str = Field(description="Authorization code from OAuth provider")
+
+
 register_schema_models(
     console_ns,
     OAuthDataSourceResponse,
     OAuthDataSourceBindingResponse,
     OAuthDataSourceSyncResponse,
+    OAuthDataSourceCallbackQuery,
+    OAuthDataSourceBindingQuery,
 )
+register_response_schema_model(console_ns, RedirectResponse)
 
 
 def get_oauth_providers():
@@ -84,14 +97,9 @@ class OAuthDataSource(Resource):
 class OAuthDataSourceCallback(Resource):
     @console_ns.doc("oauth_data_source_callback")
     @console_ns.doc(description="Handle OAuth callback from data source provider")
-    @console_ns.doc(
-        params={
-            "provider": "Data source provider name (notion)",
-            "code": "Authorization code from OAuth provider",
-            "error": "Error message from OAuth provider",
-        }
-    )
-    @console_ns.response(302, "Redirect to console with result")
+    @console_ns.doc(params={"provider": "Data source provider name (notion)"})
+    @console_ns.doc(params=query_params_from_model(OAuthDataSourceCallbackQuery))
+    @console_ns.response(302, "Redirect to console with result", console_ns.models[RedirectResponse.__name__])
     @console_ns.response(400, "Invalid provider")
     def get(self, provider: str):
         OAUTH_DATASOURCE_PROVIDERS = get_oauth_providers()
@@ -115,9 +123,8 @@ class OAuthDataSourceCallback(Resource):
 class OAuthDataSourceBinding(Resource):
     @console_ns.doc("oauth_data_source_binding")
     @console_ns.doc(description="Bind OAuth data source with authorization code")
-    @console_ns.doc(
-        params={"provider": "Data source provider name (notion)", "code": "Authorization code from OAuth provider"}
-    )
+    @console_ns.doc(params={"provider": "Data source provider name (notion)"})
+    @console_ns.doc(params=query_params_from_model(OAuthDataSourceBindingQuery))
     @console_ns.response(
         200,
         "Data source binding success",

api/controllers/console/auth/email_register.py

@@ -15,6 +15,7 @@ from controllers.console.auth.error import (
     InvalidTokenError,
     PasswordMismatchError,
 )
+from fields.base import ResponseModel
 from libs.helper import EmailStr, extract_remote_ip
 from libs.helper import timezone as validate_timezone_string
 from libs.password import valid_password
@@ -58,8 +59,24 @@ class EmailRegisterResetPayload(BaseModel):
         return validate_timezone_string(value)
 
 
+class EmailRegisterTokenPairResponse(ResponseModel):
+    access_token: str
+    refresh_token: str
+    csrf_token: str
+
+
+class EmailRegisterResetResponse(ResponseModel):
+    result: str
+    data: EmailRegisterTokenPairResponse
+
+
 register_schema_models(console_ns, EmailRegisterSendPayload, EmailRegisterValidityPayload, EmailRegisterResetPayload)
-register_response_schema_models(console_ns, SimpleResultDataResponse, VerificationTokenResponse)
+register_response_schema_models(
+    console_ns,
+    SimpleResultDataResponse,
+    VerificationTokenResponse,
+    EmailRegisterResetResponse,
+)
 
 
 @console_ns.route("/email-register/send-email")
@@ -67,6 +84,7 @@ class EmailRegisterSendEmailApi(Resource):
     @setup_required
     @email_password_login_enabled
     @email_register_enabled
+    @console_ns.expect(console_ns.models[EmailRegisterSendPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[SimpleResultDataResponse.__name__])
     def post(self):
         args = EmailRegisterSendPayload.model_validate(console_ns.payload)
@@ -92,6 +110,7 @@ class EmailRegisterCheckApi(Resource):
     @setup_required
     @email_password_login_enabled
     @email_register_enabled
+    @console_ns.expect(console_ns.models[EmailRegisterValidityPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[VerificationTokenResponse.__name__])
     def post(self):
         args = EmailRegisterValidityPayload.model_validate(console_ns.payload)
@@ -133,6 +152,8 @@ class EmailRegisterResetApi(Resource):
     @setup_required
     @email_password_login_enabled
     @email_register_enabled
+    @console_ns.expect(console_ns.models[EmailRegisterResetPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[EmailRegisterResetResponse.__name__])
     def post(self):
         args = EmailRegisterResetPayload.model_validate(console_ns.payload)
 

api/controllers/console/auth/oauth.py

@@ -4,10 +4,13 @@ import urllib.parse
 import httpx
 from flask import current_app, redirect, request
 from flask_restx import Resource
+from pydantic import BaseModel, Field
 from werkzeug.exceptions import Unauthorized
 
 from configs import dify_config
 from constants.languages import languages
+from controllers.common.fields import RedirectResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_model, register_schema_models
 from events.tenant_event import tenant_was_created
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
@@ -31,6 +34,21 @@ from .. import console_ns
 logger = logging.getLogger(__name__)
 
 
+class OAuthLoginQuery(BaseModel):
+    invite_token: str | None = Field(default=None, description="Optional invitation token")
+    timezone: str | None = Field(default=None, description="Preferred timezone")
+    language: str | None = Field(default=None, description="Preferred interface language")
+
+
+class OAuthCallbackQuery(BaseModel):
+    code: str = Field(description="Authorization code from OAuth provider")
+    state: str | None = Field(default=None, description="OAuth state parameter")
+
+
+register_schema_models(console_ns, OAuthLoginQuery, OAuthCallbackQuery)
+register_response_schema_model(console_ns, RedirectResponse)
+
+
 def get_oauth_providers():
     with current_app.app_context():
         if not dify_config.GITHUB_CLIENT_ID or not dify_config.GITHUB_CLIENT_SECRET:
@@ -83,10 +101,9 @@ def _preferred_interface_language(language: str | None = None) -> str:
 class OAuthLogin(Resource):
     @console_ns.doc("oauth_login")
     @console_ns.doc(description="Initiate OAuth login process")
-    @console_ns.doc(
-        params={"provider": "OAuth provider name (github/google)", "invite_token": "Optional invitation token"}
-    )
-    @console_ns.response(302, "Redirect to OAuth authorization URL")
+    @console_ns.doc(params={"provider": "OAuth provider name (github/google)"})
+    @console_ns.doc(params=query_params_from_model(OAuthLoginQuery))
+    @console_ns.response(302, "Redirect to OAuth authorization URL", console_ns.models[RedirectResponse.__name__])
     @console_ns.response(400, "Invalid provider")
     def get(self, provider: str):
         invite_token = request.args.get("invite_token") or None
@@ -110,14 +127,9 @@ class OAuthLogin(Resource):
 class OAuthCallback(Resource):
     @console_ns.doc("oauth_callback")
     @console_ns.doc(description="Handle OAuth callback and complete login process")
-    @console_ns.doc(
-        params={
-            "provider": "OAuth provider name (github/google)",
-            "code": "Authorization code from OAuth provider",
-            "state": "Optional state parameter (used for invite token)",
-        }
-    )
-    @console_ns.response(302, "Redirect to console with access token")
+    @console_ns.doc(params={"provider": "OAuth provider name (github/google)"})
+    @console_ns.doc(params=query_params_from_model(OAuthCallbackQuery))
+    @console_ns.response(302, "Redirect to console with access token", console_ns.models[RedirectResponse.__name__])
     @console_ns.response(400, "OAuth process failed")
     def get(self, provider: str):
         OAUTH_PROVIDERS = get_oauth_providers()

api/controllers/console/auth/oauth_server.py

@@ -1,6 +1,6 @@
 from collections.abc import Callable
 from functools import wraps
-from typing import Concatenate
+from typing import Any, Concatenate
 
 from flask import jsonify, request
 from flask.typing import ResponseReturnValue
@@ -8,6 +8,7 @@ from flask_restx import Resource
 from pydantic import BaseModel
 from werkzeug.exceptions import BadRequest, NotFound
 
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.login import login_required
@@ -36,6 +37,41 @@ class OAuthTokenRequest(BaseModel):
     refresh_token: str | None = None
 
 
+class OAuthProviderAppResponse(BaseModel):
+    app_icon: str
+    app_label: dict[str, Any]
+    scope: str
+
+
+class OAuthProviderAuthorizeResponse(BaseModel):
+    code: str
+
+
+class OAuthProviderTokenResponse(BaseModel):
+    access_token: str
+    token_type: str
+    expires_in: int
+    refresh_token: str
+
+
+class OAuthProviderAccountResponse(BaseModel):
+    name: str
+    email: str
+    avatar: str | None = None
+    interface_language: str
+    timezone: str
+
+
+register_schema_models(console_ns, OAuthClientPayload, OAuthProviderRequest, OAuthTokenRequest)
+register_response_schema_models(
+    console_ns,
+    OAuthProviderAccountResponse,
+    OAuthProviderAppResponse,
+    OAuthProviderAuthorizeResponse,
+    OAuthProviderTokenResponse,
+)
+
+
 def oauth_server_client_id_required[T, **P, R](
     view: Callable[Concatenate[T, OAuthProviderApp, P], R],
 ) -> Callable[Concatenate[T, P], R]:
@@ -110,6 +146,8 @@ def oauth_server_access_token_required[T, **P, R](
 @console_ns.route("/oauth/provider")
 class OAuthServerAppApi(Resource):
     @setup_required
+    @console_ns.expect(console_ns.models[OAuthProviderRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderAppResponse.__name__])
     @oauth_server_client_id_required
     def post(self, oauth_provider_app: OAuthProviderApp):
         payload = OAuthProviderRequest.model_validate(request.get_json())
@@ -134,6 +172,8 @@ class OAuthServerUserAuthorizeApi(Resource):
     @login_required
     @account_initialization_required
     @with_current_user
+    @console_ns.expect(console_ns.models[OAuthClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderAuthorizeResponse.__name__])
     @oauth_server_client_id_required
     def post(self, oauth_provider_app: OAuthProviderApp, current_user: Account):
         user_account_id = current_user.id
@@ -148,6 +188,8 @@ class OAuthServerUserAuthorizeApi(Resource):
 @console_ns.route("/oauth/provider/token")
 class OAuthServerUserTokenApi(Resource):
     @setup_required
+    @console_ns.expect(console_ns.models[OAuthTokenRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderTokenResponse.__name__])
     @oauth_server_client_id_required
     def post(self, oauth_provider_app: OAuthProviderApp):
         payload = OAuthTokenRequest.model_validate(request.get_json())
@@ -198,6 +240,8 @@ class OAuthServerUserTokenApi(Resource):
 @console_ns.route("/oauth/provider/account")
 class OAuthServerUserAccountApi(Resource):
     @setup_required
+    @console_ns.expect(console_ns.models[OAuthClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[OAuthProviderAccountResponse.__name__])
     @oauth_server_client_id_required
     @oauth_server_access_token_required
     def post(self, oauth_provider_app: OAuthProviderApp, account: Account):

api/controllers/console/billing/billing.py

@@ -1,12 +1,12 @@
 import base64
-from typing import Literal
+from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import BadRequest
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -30,11 +30,18 @@ class PartnerTenantsPayload(BaseModel):
     click_id: str = Field(..., description="Click Id from partner referral link")
 
 
+class BillingResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(console_ns, SubscriptionQuery, PartnerTenantsPayload)
+register_response_schema_models(console_ns, BillingResponse)
 
 
 @console_ns.route("/billing/subscription")
 class Subscription(Resource):
+    @console_ns.doc(params=query_params_from_model(SubscriptionQuery))
+    @console_ns.response(200, "Success", console_ns.models[BillingResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -49,6 +56,7 @@ class Subscription(Resource):
 
 @console_ns.route("/billing/invoices")
 class Invoices(Resource):
+    @console_ns.response(200, "Success", console_ns.models[BillingResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -66,7 +74,7 @@ class PartnerTenants(Resource):
     @console_ns.doc(description="Sync partner tenants bindings")
     @console_ns.doc(params={"partner_key": "Partner key"})
     @console_ns.expect(console_ns.models[PartnerTenantsPayload.__name__])
-    @console_ns.response(200, "Tenants synced to partner successfully")
+    @console_ns.response(200, "Tenants synced to partner successfully", console_ns.models[BillingResponse.__name__])
     @console_ns.response(400, "Invalid partner information")
     @setup_required
     @login_required

api/controllers/console/billing/compliance.py

@@ -1,12 +1,16 @@
+from typing import Any
+
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 
+from controllers.common.schema import query_params_from_model, register_response_schema_models
 from libs.helper import extract_remote_ip
 from libs.login import login_required
 from models import Account
 from services.billing_service import BillingService
 
+from ...common.schema import DEFAULT_REF_TEMPLATE_OPENAPI_3_0
 from .. import console_ns
 from ..wraps import (
     account_initialization_required,
@@ -21,17 +25,23 @@ class ComplianceDownloadQuery(BaseModel):
     doc_name: str = Field(..., description="Compliance document name")
 
 
+class ComplianceDownloadResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 console_ns.schema_model(
     ComplianceDownloadQuery.__name__,
-    ComplianceDownloadQuery.model_json_schema(ref_template="#/definitions/{model}"),
+    ComplianceDownloadQuery.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
 )
+register_response_schema_models(console_ns, ComplianceDownloadResponse)
 
 
 @console_ns.route("/compliance/download")
 class ComplianceApi(Resource):
-    @console_ns.expect(console_ns.models[ComplianceDownloadQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ComplianceDownloadQuery))
     @console_ns.doc("download_compliance_document")
     @console_ns.doc(description="Get compliance document download link")
+    @console_ns.response(200, "Success", console_ns.models[ComplianceDownloadResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/datasets/datasets.py

@@ -22,6 +22,8 @@ from controllers.console.wraps import (
     enterprise_license_required,
     is_admin_or_owner_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.indexing_runner import IndexingRunner
@@ -36,9 +38,9 @@ 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.login import login_required
 from libs.url_utils import normalize_api_base_url
-from models import ApiToken, Dataset, Document, DocumentSegment, UploadFile
+from models import Account, ApiToken, Dataset, Document, DocumentSegment, UploadFile
 from models.dataset import DatasetPermission, DatasetPermissionEnum
 from models.enums import ApiTokenType, SegmentStatus
 from models.provider_ids import ModelProviderID
@@ -93,13 +95,13 @@ class DatasetUpdatePayload(BaseModel):
     indexing_technique: str | None = None
     embedding_model: str | None = None
     embedding_model_provider: str | None = None
-    retrieval_model: dict[str, Any] | None = None
-    summary_index_setting: dict[str, Any] | None = None
+    retrieval_model: dict[str, Any] | None = Field(default=None)
+    summary_index_setting: dict[str, Any] | None = Field(default=None)
     partial_member_list: list[dict[str, str]] | None = None
-    external_retrieval_model: dict[str, Any] | None = None
+    external_retrieval_model: dict[str, Any] | None = Field(default=None)
     external_knowledge_id: str | None = None
     external_knowledge_api_id: str | None = None
-    icon_info: dict[str, Any] | None = None
+    icon_info: dict[str, Any] | None = Field(default=None)
     is_multimodal: bool | None = False
 
     @field_validator("indexing_technique")
@@ -389,8 +391,9 @@ class DatasetListApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def get(self):
-        current_user, current_tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account):
         # Convert query parameters to dict, handling list parameters correctly
         query_params: dict[str, str | list[str]] = dict(request.args.to_dict())
         # Handle ids and tag_ids as lists (Flask request.args.getlist returns list even for single value)
@@ -471,9 +474,10 @@ class DatasetListApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def post(self):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account):
         payload = DatasetCreatePayload.model_validate(console_ns.payload or {})
-        current_user, current_tenant_id = current_account_with_tenant()
 
         # The role of the current user in the ta table must be admin, owner, or editor, or dataset_operator
         if not current_user.is_dataset_editor:
@@ -512,8 +516,9 @@ class DatasetApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, current_tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -566,14 +571,15 @@ class DatasetApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def patch(self, dataset_id: UUID):
+    @with_current_user
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, 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.")
 
         payload = DatasetUpdatePayload.model_validate(console_ns.payload or {})
-        current_user, current_tenant_id = current_account_with_tenant()
         # check embedding model setting
         if (
             payload.indexing_technique == IndexTechniqueType.HIGH_QUALITY
@@ -614,9 +620,9 @@ 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: UUID):
+    @with_current_user
+    def delete(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
-        current_user, _ = current_account_with_tenant()
 
         if not (current_user.has_edit_permission or current_user.is_dataset_operator):
             raise Forbidden()
@@ -664,8 +670,8 @@ class DatasetQueryApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -704,10 +710,10 @@ class DatasetIndexingEstimateApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.expect(console_ns.models[IndexingEstimatePayload.__name__])
-    def post(self):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         payload = IndexingEstimatePayload.model_validate(console_ns.payload or {})
         args = payload.model_dump()
-        _, current_tenant_id = current_account_with_tenant()
         # validate args
         DocumentService.estimate_args_validate(args)
         extract_settings = []
@@ -804,8 +810,8 @@ class DatasetRelatedAppListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:
@@ -840,8 +846,8 @@ class DatasetIndexingStatusApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         documents = db.session.scalars(
             select(Document).where(Document.dataset_id == dataset_id_str, Document.tenant_id == current_tenant_id)
@@ -898,8 +904,8 @@ class DatasetApiKeyApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str):
         keys = db.session.scalars(
             select(ApiToken).where(ApiToken.type == self.resource_type, ApiToken.tenant_id == current_tenant_id)
         ).all()
@@ -911,9 +917,8 @@ class DatasetApiKeyApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        _, current_tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         current_key_count = (
             db.session.scalar(
                 select(func.count(ApiToken.id)).where(
@@ -952,8 +957,8 @@ class DatasetApiDeleteApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def delete(self, api_key_id: UUID):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, api_key_id: UUID):
         api_key_id_str = str(api_key_id)
         key = db.session.scalar(
             select(ApiToken)
@@ -1079,8 +1084,8 @@ class DatasetPermissionUserListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
+    @with_current_user
+    def get(self, current_user: Account, dataset_id: UUID):
         dataset_id_str = str(dataset_id)
         dataset = DatasetService.get_dataset(dataset_id_str)
         if dataset is None:

api/controllers/console/datasets/datasets_document.py

@@ -10,13 +10,13 @@ from uuid import UUID
 import sqlalchemy as sa
 from flask import request, send_file
 from flask_restx import Resource
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, RootModel, field_validator
 from sqlalchemy import asc, desc, func, select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
 from controllers.common.controller_schemas import DocumentBatchDownloadZipPayload
-from controllers.common.fields import SimpleResultMessageResponse, SimpleResultResponse, UrlResponse
+from controllers.common.fields import BinaryFileResponse, SimpleResultMessageResponse, SimpleResultResponse, UrlResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from core.errors.error import (
@@ -145,6 +145,10 @@ class DocumentWithSegmentsListResponse(ResponseModel):
     page: int
 
 
+class OpaqueObjectResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(
     console_ns,
     KnowledgeConfig,
@@ -158,6 +162,7 @@ register_schema_models(
 )
 register_response_schema_models(
     console_ns,
+    BinaryFileResponse,
     SimpleResultMessageResponse,
     SimpleResultResponse,
     UrlResponse,
@@ -167,6 +172,7 @@ register_response_schema_models(
     DocumentWithSegmentsResponse,
     DatasetAndDocumentResponse,
     DocumentWithSegmentsListResponse,
+    OpaqueObjectResponse,
 )
 
 
@@ -216,7 +222,7 @@ class GetProcessRuleApi(Resource):
     @console_ns.doc("get_process_rule")
     @console_ns.doc(description="Get dataset document processing rules")
     @console_ns.doc(params={"document_id": "Document ID (optional)"})
-    @console_ns.response(200, "Process rules retrieved successfully")
+    @console_ns.response(200, "Process rules retrieved successfully", console_ns.models[OpaqueObjectResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -537,7 +543,11 @@ class DocumentIndexingEstimateApi(DocumentResource):
     @console_ns.doc("estimate_document_indexing")
     @console_ns.doc(description="Estimate document indexing cost")
     @console_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
-    @console_ns.response(200, "Indexing estimate calculated successfully")
+    @console_ns.response(
+        200,
+        "Indexing estimate calculated successfully",
+        console_ns.models[OpaqueObjectResponse.__name__],
+    )
     @console_ns.response(404, "Document not found")
     @console_ns.response(400, "Document already finished")
     @setup_required
@@ -606,6 +616,11 @@ class DocumentIndexingEstimateApi(DocumentResource):
 
 @console_ns.route("/datasets/<uuid:dataset_id>/batch/<string:batch>/indexing-estimate")
 class DocumentBatchIndexingEstimateApi(DocumentResource):
+    @console_ns.response(
+        200,
+        "Batch indexing estimate calculated successfully",
+        console_ns.models[OpaqueObjectResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -824,7 +839,7 @@ class DocumentApi(DocumentResource):
             "metadata": "Metadata inclusion (all/only/without)",
         }
     )
-    @console_ns.response(200, "Document retrieved successfully")
+    @console_ns.response(200, "Document retrieved successfully", console_ns.models[OpaqueObjectResponse.__name__])
     @console_ns.response(404, "Document not found")
     @setup_required
     @login_required
@@ -966,6 +981,7 @@ class DocumentBatchDownloadZipApi(DocumentResource):
 
     @console_ns.doc("download_dataset_documents_as_zip")
     @console_ns.doc(description="Download selected dataset documents as a single ZIP archive (upload-file only)")
+    @console_ns.response(200, "ZIP archive generated successfully", console_ns.models[BinaryFileResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -1324,6 +1340,11 @@ class WebsiteDocumentSyncApi(DocumentResource):
 
 @console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/pipeline-execution-log")
 class DocumentPipelineExecutionLogApi(DocumentResource):
+    @console_ns.response(
+        200,
+        "Document pipeline execution log retrieved successfully",
+        console_ns.models[OpaqueObjectResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -1464,7 +1485,7 @@ class DocumentSummaryStatusApi(DocumentResource):
     @console_ns.doc("get_document_summary_status")
     @console_ns.doc(description="Get summary index generation status for a document")
     @console_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
-    @console_ns.response(200, "Summary status retrieved successfully")
+    @console_ns.response(200, "Summary status retrieved successfully", console_ns.models[OpaqueObjectResponse.__name__])
     @console_ns.response(404, "Document not found")
     @setup_required
     @login_required

api/controllers/console/datasets/external.py

@@ -1,13 +1,19 @@
+from typing import Any
 from uuid import UUID
 
 from flask import request
 from flask_restx import Resource, fields, marshal
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.exceptions import Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.fields import UsageCountResponse
-from controllers.common.schema import get_or_create_model, register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    get_or_create_model,
+    query_params_from_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 (
@@ -17,6 +23,7 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from fields.base import ResponseModel
 from fields.dataset_fields import (
     dataset_detail_fields,
     dataset_retrieval_model_fields,
@@ -88,13 +95,15 @@ class ExternalDatasetCreatePayload(BaseModel):
     external_knowledge_id: str
     name: str = Field(..., min_length=1, max_length=100)
     description: str | None = Field(None, max_length=400)
-    external_retrieval_model: dict[str, object] | None = None
+    external_retrieval_model: dict[str, object] | None = Field(default=None)
 
 
 class ExternalHitTestingPayload(BaseModel):
     query: str
-    external_retrieval_model: dict[str, object] | None = None
-    metadata_filtering_conditions: dict[str, object] | None = None
+    external_retrieval_model: dict[str, object] | None = Field(default=None)
+    metadata_filtering_conditions: dict[str, object] | None = Field(
+        default=None,
+    )
 
 
 class BedrockRetrievalPayload(BaseModel):
@@ -109,6 +118,34 @@ class ExternalApiTemplateListQuery(BaseModel):
     keyword: str | None = Field(default=None, description="Search keyword")
 
 
+class ExternalKnowledgeDatasetBindingResponse(ResponseModel):
+    id: str
+    name: str
+
+
+class ExternalKnowledgeApiResponse(ResponseModel):
+    id: str
+    tenant_id: str
+    name: str
+    description: str
+    settings: dict[str, Any] | None = Field(default=None)
+    dataset_bindings: list[ExternalKnowledgeDatasetBindingResponse] = Field(default_factory=list)
+    created_by: str
+    created_at: str
+
+
+class ExternalKnowledgeApiListResponse(ResponseModel):
+    data: list[ExternalKnowledgeApiResponse]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
+class ExternalRetrievalTestResponse(RootModel[dict[str, Any] | list[dict[str, Any]]]):
+    root: dict[str, Any] | list[dict[str, Any]]
+
+
 register_schema_models(
     console_ns,
     ExternalKnowledgeApiPayload,
@@ -117,20 +154,24 @@ register_schema_models(
     BedrockRetrievalPayload,
     ExternalApiTemplateListQuery,
 )
+register_response_schema_models(
+    console_ns,
+    ExternalKnowledgeApiResponse,
+    ExternalKnowledgeApiListResponse,
+    ExternalRetrievalTestResponse,
+)
 
 
 @console_ns.route("/datasets/external-knowledge-api")
 class ExternalApiTemplateListApi(Resource):
     @console_ns.doc("get_external_api_templates")
     @console_ns.doc(description="Get external knowledge API templates")
-    @console_ns.doc(
-        params={
-            "page": "Page number (default: 1)",
-            "limit": "Number of items per page (default: 20)",
-            "keyword": "Search keyword",
-        }
+    @console_ns.doc(params=query_params_from_model(ExternalApiTemplateListQuery))
+    @console_ns.response(
+        200,
+        "External API templates retrieved successfully",
+        console_ns.models[ExternalKnowledgeApiListResponse.__name__],
     )
-    @console_ns.response(200, "External API templates retrieved successfully")
     @setup_required
     @login_required
     @with_current_tenant_id
@@ -154,6 +195,11 @@ class ExternalApiTemplateListApi(Resource):
     @login_required
     @account_initialization_required
     @console_ns.expect(console_ns.models[ExternalKnowledgeApiPayload.__name__])
+    @console_ns.response(
+        201,
+        "External API template created successfully",
+        console_ns.models[ExternalKnowledgeApiResponse.__name__],
+    )
     @with_current_user
     @with_current_tenant_id
     def post(self, current_tenant_id: str, current_user: Account):
@@ -180,7 +226,11 @@ class ExternalApiTemplateApi(Resource):
     @console_ns.doc("get_external_api_template")
     @console_ns.doc(description="Get external knowledge API template details")
     @console_ns.doc(params={"external_knowledge_api_id": "External knowledge API ID"})
-    @console_ns.response(200, "External API template retrieved successfully")
+    @console_ns.response(
+        200,
+        "External API template retrieved successfully",
+        console_ns.models[ExternalKnowledgeApiResponse.__name__],
+    )
     @console_ns.response(404, "Template not found")
     @setup_required
     @login_required
@@ -196,6 +246,11 @@ class ExternalApiTemplateApi(Resource):
 
         return external_knowledge_api.to_dict(), 200
 
+    @console_ns.response(
+        200,
+        "External API template updated successfully",
+        console_ns.models[ExternalKnowledgeApiResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -293,7 +348,11 @@ class ExternalKnowledgeHitTestingApi(Resource):
     @console_ns.doc(description="Test external knowledge retrieval for dataset")
     @console_ns.doc(params={"dataset_id": "Dataset ID"})
     @console_ns.expect(console_ns.models[ExternalHitTestingPayload.__name__])
-    @console_ns.response(200, "External hit testing completed successfully")
+    @console_ns.response(
+        200,
+        "External hit testing completed successfully",
+        console_ns.models[ExternalRetrievalTestResponse.__name__],
+    )
     @console_ns.response(404, "Dataset not found")
     @console_ns.response(400, "Invalid parameters")
     @setup_required
@@ -334,7 +393,11 @@ class BedrockRetrievalApi(Resource):
     @console_ns.doc("bedrock_retrieval_test")
     @console_ns.doc(description="Bedrock retrieval test (internal use only)")
     @console_ns.expect(console_ns.models[BedrockRetrievalPayload.__name__])
-    @console_ns.response(200, "Bedrock retrieval test completed")
+    @console_ns.response(
+        200,
+        "Bedrock retrieval test completed",
+        console_ns.models[ExternalRetrievalTestResponse.__name__],
+    )
     def post(self):
         payload = BedrockRetrievalPayload.model_validate(console_ns.payload or {})
 

api/controllers/console/datasets/hit_testing.py

@@ -8,6 +8,7 @@ from controllers.common.schema import register_response_schema_models, register_
 from fields.hit_testing_fields import HitTestingResponse
 from libs.helper import dump_response
 from libs.login import login_required
+from models import Account
 
 from .. import console_ns
 from ..datasets.hit_testing_base import DatasetsHitTestingBase, HitTestingPayload
@@ -15,6 +16,8 @@ from ..wraps import (
     account_initialization_required,
     cloud_edition_billing_rate_limit_check,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 
 register_schema_models(console_ns, HitTestingPayload)
@@ -38,11 +41,16 @@ class HitTestingApi(Resource, DatasetsHitTestingBase):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_rate_limit_check("knowledge")
-    def post(self, dataset_id: UUID) -> dict[str, object]:
+    @with_current_tenant_id
+    @with_current_user
+    def post(self, current_user: Account, current_tenant_id: str, dataset_id: UUID) -> dict[str, object]:
         dataset_id_str = str(dataset_id)
 
-        dataset = self.get_and_validate_dataset(dataset_id_str)
+        dataset = self.get_and_validate_dataset(dataset_id_str, current_user, current_tenant_id)
         args = self.parse_args(console_ns.payload)
         self.hit_testing_args_check(args)
 
-        return dump_response(HitTestingResponse, self.perform_hit_testing(dataset, args))
+        return dump_response(
+            HitTestingResponse,
+            self.perform_hit_testing(dataset, args, current_user, current_tenant_id),
+        )

api/controllers/console/datasets/hit_testing_base.py

@@ -19,7 +19,7 @@ from core.errors.error import (
     QuotaExceededError,
 )
 from graphon.model_runtime.errors.invoke import InvokeError
-from libs.login import current_user
+from libs.login import resolve_account_fallback
 from models.account import Account
 from models.dataset import Dataset
 from services.dataset_service import DatasetService
@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)
 class HitTestingPayload(BaseModel):
     query: str = Field(max_length=250)
     retrieval_model: RetrievalModel | None = None
-    external_retrieval_model: dict[str, Any] | None = None
+    external_retrieval_model: dict[str, Any] | None = Field(default=None)
     attachment_ids: list[str] | None = None
 
 
@@ -71,8 +71,10 @@ class DatasetsHitTestingBase:
         return normalized_records
 
     @staticmethod
-    def get_and_validate_dataset(dataset_id: str) -> Dataset:
-        assert isinstance(current_user, Account)
+    def get_and_validate_dataset(
+        dataset_id: str, current_user: Account | None = None, current_tenant_id: str | None = None
+    ) -> Dataset:
+        current_user, _ = resolve_account_fallback(current_user, current_tenant_id)
         dataset = DatasetService.get_dataset(dataset_id)
         if dataset is None:
             raise NotFound("Dataset not found.")
@@ -95,9 +97,14 @@ class DatasetsHitTestingBase:
         return hit_testing_payload.model_dump(exclude_none=True)
 
     @staticmethod
-    def perform_hit_testing(dataset: Dataset, args: dict[str, Any]) -> dict[str, Any]:
-        assert isinstance(current_user, Account)
+    def perform_hit_testing(
+        dataset: Dataset,
+        args: dict[str, Any],
+        current_user: Account | None = None,
+        current_tenant_id: str | None = None,
+    ) -> dict[str, Any]:
         try:
+            current_user, _ = resolve_account_fallback(current_user, current_tenant_id)
             response = HitTestingService.retrieve(
                 dataset=dataset,
                 query=cast(str, args.get("query")),

api/controllers/console/datasets/metadata.py

@@ -11,6 +11,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     enterprise_license_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from fields.dataset_fields import (
@@ -50,7 +51,8 @@ class DatasetMetadataCreateApi(Resource):
     @console_ns.response(201, "Metadata created successfully", console_ns.models[DatasetMetadataResponse.__name__])
     @console_ns.expect(console_ns.models[MetadataArgs.__name__])
     @with_current_user
-    def post(self, current_user: Account, dataset_id: UUID):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, dataset_id: UUID):
         metadata_args = MetadataArgs.model_validate(console_ns.payload or {})
 
         dataset_id_str = str(dataset_id)
@@ -59,7 +61,7 @@ class DatasetMetadataCreateApi(Resource):
             raise NotFound("Dataset not found.")
         DatasetService.check_dataset_permission(dataset, current_user)
 
-        metadata = MetadataService.create_metadata(dataset_id_str, metadata_args)
+        metadata = MetadataService.create_metadata(dataset_id_str, metadata_args, current_user, current_tenant_id)
         return dump_response(DatasetMetadataResponse, metadata), 201
 
     @setup_required
@@ -87,7 +89,8 @@ class DatasetMetadataApi(Resource):
     @console_ns.response(200, "Metadata updated successfully", console_ns.models[DatasetMetadataResponse.__name__])
     @console_ns.expect(console_ns.models[MetadataUpdatePayload.__name__])
     @with_current_user
-    def patch(self, current_user: Account, dataset_id: UUID, metadata_id: UUID):
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, dataset_id: UUID, metadata_id: UUID):
         payload = MetadataUpdatePayload.model_validate(console_ns.payload or {})
         name = payload.name
 
@@ -98,7 +101,9 @@ class DatasetMetadataApi(Resource):
             raise NotFound("Dataset not found.")
         DatasetService.check_dataset_permission(dataset, current_user)
 
-        metadata = MetadataService.update_metadata_name(dataset_id_str, metadata_id_str, name)
+        metadata = MetadataService.update_metadata_name(
+            dataset_id_str, metadata_id_str, name, current_user, current_tenant_id
+        )
         return dump_response(DatasetMetadataResponse, metadata), 200
 
     @setup_required
@@ -181,7 +186,7 @@ class DocumentMetadataEditApi(Resource):
 
         metadata_args = MetadataOperationData.model_validate(console_ns.payload or {})
 
-        MetadataService.update_documents_metadata(dataset, metadata_args)
+        MetadataService.update_documents_metadata(dataset, metadata_args, current_user)
 
         # Frontend callers only await success and invalidate caches; no response body is consumed.
         return "", 204

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

@@ -6,8 +6,8 @@ from pydantic import BaseModel, Field
 from werkzeug.exceptions import Forbidden, NotFound
 
 from configs import dify_config
-from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import RedirectResponse, SimpleResultResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -16,7 +16,9 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from core.plugin.entities.plugin_daemon import PluginOAuthAuthorizationUrlResponse
 from core.plugin.impl.oauth import OAuthHandler
+from fields.base import ResponseModel
 from graphon.model_runtime.errors.validate import CredentialsValidateFailedError
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.login import login_required
@@ -38,11 +40,11 @@ class DatasourceCredentialDeletePayload(BaseModel):
 class DatasourceCredentialUpdatePayload(BaseModel):
     credential_id: str
     name: str | None = Field(default=None, max_length=100)
-    credentials: dict[str, Any] | None = None
+    credentials: dict[str, Any] | None = Field(default=None)
 
 
 class DatasourceCustomClientPayload(BaseModel):
-    client_params: dict[str, Any] | None = None
+    client_params: dict[str, Any] | None = Field(default=None)
     enable_oauth_custom_client: bool | None = None
 
 
@@ -55,8 +57,25 @@ class DatasourceUpdateNamePayload(BaseModel):
     name: str = Field(max_length=100)
 
 
+class DatasourceOAuthAuthorizationQuery(BaseModel):
+    credential_id: str | None = Field(default=None, description="Credential ID to reauthorize")
+
+
+class DatasourceOAuthCallbackQuery(BaseModel):
+    code: str | None = Field(default=None, description="Authorization code from OAuth provider")
+    state: str | None = Field(default=None, description="OAuth state parameter")
+    error: str | None = Field(default=None, description="Error message from OAuth provider")
+    context_id: str | None = Field(default=None, description="OAuth proxy context ID")
+
+
+class DatasourceCredentialsResponse(ResponseModel):
+    result: Any
+
+
 register_schema_models(
     console_ns,
+    DatasourceOAuthAuthorizationQuery,
+    DatasourceOAuthCallbackQuery,
     DatasourceCredentialPayload,
     DatasourceCredentialDeletePayload,
     DatasourceCredentialUpdatePayload,
@@ -64,11 +83,23 @@ register_schema_models(
     DatasourceDefaultPayload,
     DatasourceUpdateNamePayload,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    DatasourceCredentialsResponse,
+    PluginOAuthAuthorizationUrlResponse,
+    RedirectResponse,
+    SimpleResultResponse,
+)
 
 
 @console_ns.route("/oauth/plugin/<path:provider_id>/datasource/get-authorization-url")
 class DatasourcePluginOAuthAuthorizationUrl(Resource):
+    @console_ns.doc(params=query_params_from_model(DatasourceOAuthAuthorizationQuery))
+    @console_ns.response(
+        200,
+        "Authorization URL retrieved successfully",
+        console_ns.models[PluginOAuthAuthorizationUrlResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -118,6 +149,12 @@ class DatasourcePluginOAuthAuthorizationUrl(Resource):
 
 @console_ns.route("/oauth/plugin/<path:provider_id>/datasource/callback")
 class DatasourceOAuthCallback(Resource):
+    @console_ns.doc(params=query_params_from_model(DatasourceOAuthCallbackQuery))
+    @console_ns.response(
+        302,
+        "Redirect to console OAuth callback page",
+        console_ns.models[RedirectResponse.__name__],
+    )
     @setup_required
     def get(self, provider_id: str):
         context_id = request.cookies.get("context_id") or request.args.get("context_id")
@@ -176,6 +213,7 @@ class DatasourceOAuthCallback(Resource):
 @console_ns.route("/auth/plugin/datasource/<path:provider_id>")
 class DatasourceAuth(Resource):
     @console_ns.expect(console_ns.models[DatasourceCredentialPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -200,6 +238,7 @@ class DatasourceAuth(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @console_ns.response(200, "Success", console_ns.models[DatasourceCredentialsResponse.__name__])
     @with_current_user
     @with_current_tenant_id
     def get(self, current_tenant_id: str, user: Account, provider_id: str):
@@ -243,6 +282,7 @@ class DatasourceAuthDeleteApi(Resource):
 @console_ns.route("/auth/plugin/datasource/<path:provider_id>/update")
 class DatasourceAuthUpdateApi(Resource):
     @console_ns.expect(console_ns.models[DatasourceCredentialUpdatePayload.__name__])
+    @console_ns.response(201, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -266,6 +306,7 @@ class DatasourceAuthUpdateApi(Resource):
 
 @console_ns.route("/auth/plugin/datasource/list")
 class DatasourceAuthListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[DatasourceCredentialsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -278,6 +319,7 @@ class DatasourceAuthListApi(Resource):
 
 @console_ns.route("/auth/plugin/datasource/default-list")
 class DatasourceHardCodeAuthListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[DatasourceCredentialsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -291,6 +333,7 @@ class DatasourceHardCodeAuthListApi(Resource):
 @console_ns.route("/auth/plugin/datasource/<path:provider_id>/custom-client")
 class DatasourceAuthOauthCustomClient(Resource):
     @console_ns.expect(console_ns.models[DatasourceCustomClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

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

@@ -1,9 +1,11 @@
+from typing import Any
+
 from flask_restx import (  # type: ignore
     Resource,  # type: ignore
 )
-from pydantic import BaseModel
+from pydantic import BaseModel, RootModel
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.datasets.wraps import get_rag_pipeline
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
@@ -14,17 +16,23 @@ from services.rag_pipeline.rag_pipeline import RagPipelineService
 
 
 class Parser(BaseModel):
-    inputs: dict
+    inputs: dict[str, Any]
     datasource_type: str
     credential_id: str | None = None
 
 
+class DataSourceContentPreviewResponse(RootModel[Any]):
+    root: Any
+
+
 register_schema_models(console_ns, Parser)
+register_response_schema_models(console_ns, DataSourceContentPreviewResponse)
 
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/datasource/nodes/<string:node_id>/preview")
 class DataSourceContentPreviewApi(Resource):
     @console_ns.expect(console_ns.models[Parser.__name__])
+    @console_ns.response(200, "Success", console_ns.models[DataSourceContentPreviewResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

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

@@ -21,11 +21,14 @@ from controllers.console.wraps import (
     enterprise_license_required,
     knowledge_pipeline_publish_enabled,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import dump_response
 from libs.login import login_required
+from models.account import Account
 from models.dataset import PipelineCustomizedTemplate
 from services.entities.knowledge_entities.rag_pipeline_entities import IconInfo, PipelineTemplateInfoEntity
 from services.rag_pipeline.rag_pipeline import RagPipelineService
@@ -71,7 +74,9 @@ class PipelineTemplateDetailResponse(ResponseModel):
 class CustomizedPipelineTemplatePayload(BaseModel):
     name: str = Field(..., min_length=1, max_length=40)
     description: str = Field(default="", max_length=400)
-    icon_info: dict[str, object] = Field(default_factory=lambda: IconInfo(icon="").model_dump())
+    icon_info: dict[str, object] = Field(
+        default_factory=lambda: IconInfo(icon="").model_dump(),
+    )
 
 
 register_schema_models(
@@ -96,10 +101,11 @@ class PipelineTemplateListApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def get(self) -> JsonResponseWithStatus:
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str) -> JsonResponseWithStatus:
         query = PipelineTemplateListQuery.model_validate(request.args.to_dict(flat=True))
         # get pipeline templates
-        pipeline_templates = RagPipelineService.get_pipeline_templates(query.type, query.language)
+        pipeline_templates = RagPipelineService.get_pipeline_templates(query.type, query.language, current_tenant_id)
         return dump_response(PipelineTemplateListResponse, pipeline_templates), 200
 
 
@@ -128,10 +134,14 @@ class CustomizedPipelineTemplateApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def patch(self, template_id: str) -> tuple[str, int]:
+    @with_current_user
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, template_id: str) -> tuple[str, int]:
         payload = CustomizedPipelineTemplatePayload.model_validate(console_ns.payload or {})
         pipeline_template_info = PipelineTemplateInfoEntity.model_validate(payload.model_dump())
-        RagPipelineService.update_customized_pipeline_template(template_id, pipeline_template_info)
+        RagPipelineService.update_customized_pipeline_template(
+            template_id, pipeline_template_info, current_user, current_tenant_id
+        )
         return "", 204
 
     @console_ns.response(204, "Pipeline template deleted")
@@ -139,8 +149,9 @@ class CustomizedPipelineTemplateApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
-    def delete(self, template_id: str) -> tuple[str, int]:
-        RagPipelineService.delete_customized_pipeline_template(template_id)
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, template_id: str) -> tuple[str, int]:
+        RagPipelineService.delete_customized_pipeline_template(template_id, current_tenant_id)
         return "", 204
 
     @setup_required
@@ -168,8 +179,12 @@ class PublishCustomizedPipelineTemplateApi(Resource):
     @account_initialization_required
     @enterprise_license_required
     @knowledge_pipeline_publish_enabled
-    def post(self, pipeline_id: str) -> tuple[str, int]:
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, pipeline_id: str) -> tuple[str, int]:
         payload = CustomizedPipelineTemplatePayload.model_validate(console_ns.payload or {})
         rag_pipeline_service = RagPipelineService()
-        rag_pipeline_service.publish_customized_pipeline_template(pipeline_id, payload.model_dump())
+        rag_pipeline_service.publish_customized_pipeline_template(
+            pipeline_id, payload.model_dump(), current_user, current_tenant_id
+        )
         return "", 204

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

@@ -10,20 +10,21 @@ from pydantic import BaseModel, Field
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import Forbidden
 
-from controllers.common.schema import register_schema_models
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     DraftWorkflowNotExist,
 )
 from controllers.console.app.workflow_draft_variable import (
     _WORKFLOW_DRAFT_VARIABLE_FIELDS,  # type: ignore[private-usage]
+    EnvironmentVariableListResponse,
     workflow_draft_variable_list_model,
     workflow_draft_variable_list_without_value_model,
     workflow_draft_variable_model,
 )
 from controllers.console.datasets.wraps import get_rag_pipeline
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
-from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
@@ -40,14 +41,9 @@ logger = logging.getLogger(__name__)
 _file_access_controller = DatabaseFileAccessController()
 
 
-def _create_pagination_parser():
-    class PaginationQuery(BaseModel):
-        page: int = Field(default=1, ge=1, le=100_000)
-        limit: int = Field(default=20, ge=1, le=100)
-
-    register_schema_models(console_ns, PaginationQuery)
-
-    return PaginationQuery
+class PaginationQuery(BaseModel):
+    page: int = Field(default=1, ge=1, le=100_000)
+    limit: int = Field(default=20, ge=1, le=100)
 
 
 class WorkflowDraftVariablePatchPayload(BaseModel):
@@ -55,7 +51,7 @@ class WorkflowDraftVariablePatchPayload(BaseModel):
     value: Any | None = None
 
 
-register_schema_models(console_ns, WorkflowDraftVariablePatchPayload)
+register_schema_models(console_ns, PaginationQuery, WorkflowDraftVariablePatchPayload)
 
 
 def _api_prerequisite[T, **P, R](
@@ -87,14 +83,19 @@ def _api_prerequisite[T, **P, R](
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/variables")
 class RagPipelineVariableCollectionApi(Resource):
+    @console_ns.doc(params=query_params_from_model(PaginationQuery))
+    @console_ns.response(
+        200,
+        "Workflow variables retrieved successfully",
+        workflow_draft_variable_list_without_value_model,
+    )
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_without_value_model)
     def get(self, current_user: Account, pipeline: Pipeline):
         """
         Get draft workflow
         """
-        pagination = _create_pagination_parser()
-        query = pagination.model_validate(request.args.to_dict())
+        query = PaginationQuery.model_validate(request.args.to_dict())
 
         # fetch draft workflow by app_model
         rag_pipeline_service = RagPipelineService()
@@ -116,6 +117,7 @@ class RagPipelineVariableCollectionApi(Resource):
 
         return workflow_vars
 
+    @console_ns.response(204, "Workflow variables deleted successfully")
     @_api_prerequisite
     def delete(self, current_user: Account, pipeline: Pipeline):
         draft_var_srv = WorkflowDraftVariableService(
@@ -146,6 +148,7 @@ def validate_node_id(node_id: str) -> NoReturn | None:
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/nodes/<string:node_id>/variables")
 class RagPipelineNodeVariableCollectionApi(Resource):
+    @console_ns.response(200, "Node variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
     def get(self, current_user: Account, pipeline: Pipeline, node_id: str):
@@ -158,6 +161,7 @@ class RagPipelineNodeVariableCollectionApi(Resource):
 
         return node_vars
 
+    @console_ns.response(204, "Node variables deleted successfully")
     @_api_prerequisite
     def delete(self, current_user: Account, pipeline: Pipeline, node_id: str):
         validate_node_id(node_id)
@@ -172,6 +176,7 @@ class RagPipelineVariableApi(Resource):
     _PATCH_NAME_FIELD = "name"
     _PATCH_VALUE_FIELD = "value"
 
+    @console_ns.response(200, "Variable retrieved successfully", workflow_draft_variable_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
     def get(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
@@ -186,6 +191,7 @@ class RagPipelineVariableApi(Resource):
             raise NotFoundError(description=f"variable not found, id={variable_id_str}")
         return variable
 
+    @console_ns.response(200, "Variable updated successfully", workflow_draft_variable_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_model)
     @console_ns.expect(console_ns.models[WorkflowDraftVariablePatchPayload.__name__])
@@ -257,6 +263,7 @@ class RagPipelineVariableApi(Resource):
         db.session.commit()
         return variable
 
+    @console_ns.response(204, "Variable deleted successfully")
     @_api_prerequisite
     def delete(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
@@ -275,6 +282,8 @@ class RagPipelineVariableApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/variables/<uuid:variable_id>/reset")
 class RagPipelineVariableResetApi(Resource):
+    @console_ns.response(200, "Variable reset successfully", workflow_draft_variable_model)
+    @console_ns.response(204, "Variable reset (no content)")
     @_api_prerequisite
     def put(self, _current_user: Account, pipeline: Pipeline, variable_id: UUID):
         draft_var_srv = WorkflowDraftVariableService(
@@ -318,6 +327,7 @@ def _get_variable_list(pipeline: Pipeline, node_id: str, current_user_id: str) -
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/system-variables")
 class RagPipelineSystemVariableCollectionApi(Resource):
+    @console_ns.response(200, "System variables retrieved successfully", workflow_draft_variable_list_model)
     @_api_prerequisite
     @marshal_with(workflow_draft_variable_list_model)
     def get(self, current_user: Account, pipeline: Pipeline):
@@ -326,6 +336,11 @@ class RagPipelineSystemVariableCollectionApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/environment-variables")
 class RagPipelineEnvironmentVariableCollectionApi(Resource):
+    @console_ns.response(
+        200,
+        "Environment variables retrieved successfully",
+        console_ns.models[EnvironmentVariableListResponse.__name__],
+    )
     @_api_prerequisite
     def get(self, _current_user: Account, pipeline: Pipeline):
         """

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

@@ -5,14 +5,14 @@ from uuid import UUID
 
 from flask import abort, request
 from flask_restx import Resource
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, Field, RootModel, ValidationError
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import BadRequest, Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.common.controller_schemas import DefaultBlockConfigQuery, WorkflowListQuery, WorkflowUpdatePayload
 from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     ConversationCompletedError,
@@ -21,6 +21,8 @@ from controllers.console.app.error import (
 )
 from controllers.console.app.workflow import (
     RESTORE_SOURCE_WORKFLOW_MUST_BE_PUBLISHED_MESSAGE,
+    DefaultBlockConfigResponse,
+    DefaultBlockConfigsResponse,
     WorkflowPaginationResponse,
     WorkflowResponse,
 )
@@ -29,6 +31,8 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -46,7 +50,7 @@ from fields.workflow_run_fields import (
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs import helper
 from libs.helper import TimestampField, UUIDStrOrEmpty, dump_response
-from libs.login import current_account_with_tenant, current_user, login_required
+from libs.login import login_required
 from models import Account
 from models.dataset import Pipeline
 from models.model import EndUser
@@ -65,14 +69,14 @@ logger = logging.getLogger(__name__)
 class DraftWorkflowSyncPayload(BaseModel):
     graph: dict[str, Any]
     hash: str | None = None
-    environment_variables: list[dict[str, Any]] | None = None
-    conversation_variables: list[dict[str, Any]] | None = None
-    rag_pipeline_variables: list[dict[str, Any]] | None = None
-    features: dict[str, Any] | None = None
+    environment_variables: list[dict[str, Any]] | None = Field(default=None)
+    conversation_variables: list[dict[str, Any]] | None = Field(default=None)
+    rag_pipeline_variables: list[dict[str, Any]] | None = Field(default=None)
+    features: dict[str, Any] | None = Field(default=None)
 
 
 class NodeRunPayload(BaseModel):
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class NodeRunRequiredPayload(BaseModel):
@@ -129,6 +133,14 @@ class RagPipelineWorkflowPublishResponse(ResponseModel):
     created_at: int
 
 
+class RagPipelineOpaqueResponse(RootModel[Any]):
+    root: Any
+
+
+class RagPipelineStepParametersResponse(ResponseModel):
+    variables: Any
+
+
 register_schema_models(
     console_ns,
     DraftWorkflowSyncPayload,
@@ -147,6 +159,10 @@ register_schema_models(
 )
 register_response_schema_models(
     console_ns,
+    DefaultBlockConfigResponse,
+    DefaultBlockConfigsResponse,
+    RagPipelineOpaqueResponse,
+    RagPipelineStepParametersResponse,
     RagPipelineWorkflowPublishResponse,
     RagPipelineWorkflowSyncResponse,
     SimpleResultResponse,
@@ -187,16 +203,15 @@ class DraftRagPipelineApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
     @edit_permission_required
+    @console_ns.expect(console_ns.models[DraftWorkflowSyncPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[RagPipelineWorkflowSyncResponse.__name__])
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Sync draft workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         content_type = request.headers.get("Content-Type", "")
 
         if "application/json" in content_type:
@@ -244,18 +259,17 @@ class DraftRagPipelineApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/iteration/nodes/<string:node_id>/run")
 class RagPipelineDraftRunIterationNodeApi(Resource):
     @console_ns.expect(console_ns.models[NodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
     @edit_permission_required
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run draft workflow iteration node
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = NodeRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
 
@@ -279,18 +293,17 @@ class RagPipelineDraftRunIterationNodeApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/loop/nodes/<string:node_id>/run")
 class RagPipelineDraftRunLoopNodeApi(Resource):
     @console_ns.expect(console_ns.models[NodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run draft workflow loop node
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = NodeRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
 
@@ -314,18 +327,17 @@ class RagPipelineDraftRunLoopNodeApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/run")
 class DraftRagPipelineRunApi(Resource):
     @console_ns.expect(console_ns.models[DraftWorkflowRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Run draft workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = DraftWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump()
 
@@ -346,18 +358,17 @@ class DraftRagPipelineRunApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/run")
 class PublishedRagPipelineRunApi(Resource):
     @console_ns.expect(console_ns.models[PublishedWorkflowRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Run published workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = PublishedWorkflowRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
         streaming = payload.response_mode == "streaming"
@@ -379,18 +390,17 @@ class PublishedRagPipelineRunApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/datasource/nodes/<string:node_id>/run")
 class RagPipelinePublishedDatasourceNodeRunApi(Resource):
     @console_ns.expect(console_ns.models[DatasourceNodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run rag pipeline datasource
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = DatasourceNodeRunPayload.model_validate(console_ns.payload or {})
 
         rag_pipeline_service = RagPipelineService()
@@ -412,18 +422,17 @@ class RagPipelinePublishedDatasourceNodeRunApi(Resource):
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/datasource/nodes/<string:node_id>/run")
 class RagPipelineDraftDatasourceNodeRunApi(Resource):
     @console_ns.expect(console_ns.models[DatasourceNodeRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @edit_permission_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run rag pipeline datasource
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = DatasourceNodeRunPayload.model_validate(console_ns.payload or {})
 
         rag_pipeline_service = RagPipelineService()
@@ -454,14 +463,12 @@ class RagPipelineDraftNodeRunApi(Resource):
     @login_required
     @edit_permission_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, node_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, node_id: str):
         """
         Run draft workflow node
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         payload = NodeRunRequiredPayload.model_validate(console_ns.payload or {})
         inputs = payload.inputs
 
@@ -485,14 +492,12 @@ class RagPipelineTaskStopApi(Resource):
     @login_required
     @edit_permission_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, task_id: str):
+    def post(self, current_user: Account, pipeline: Pipeline, task_id: str):
         """
         Stop workflow task
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
-
         AppQueueManager.set_stop_flag(task_id, InvokeFrom.DEBUGGER, current_user.id)
 
         return {"result": "success"}
@@ -532,13 +537,12 @@ class PublishedRagPipelineApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Publish workflow
         """
-        # The role of the current user in the ta table must be admin, owner, or editor
-        current_user, _ = current_account_with_tenant()
         rag_pipeline_service = RagPipelineService()
         workflow = rag_pipeline_service.publish_workflow(
             session=db.session,  # type: ignore[reportArgumentType,arg-type]
@@ -558,6 +562,11 @@ class PublishedRagPipelineApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/default-workflow-block-configs")
 class DefaultRagPipelineBlockConfigsApi(Resource):
+    @console_ns.response(
+        200,
+        "Default block configs retrieved successfully",
+        console_ns.models[DefaultBlockConfigsResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -574,6 +583,12 @@ class DefaultRagPipelineBlockConfigsApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/default-workflow-block-configs/<string:block_type>")
 class DefaultRagPipelineBlockConfigApi(Resource):
+    @console_ns.doc(params=query_params_from_model(DefaultBlockConfigQuery))
+    @console_ns.response(
+        200,
+        "Default block config retrieved successfully",
+        console_ns.models[DefaultBlockConfigResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -599,6 +614,7 @@ class DefaultRagPipelineBlockConfigApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows")
 class PublishedAllRagPipelineApi(Resource):
+    @console_ns.doc(params=query_params_from_model(WorkflowListQuery))
     @console_ns.response(
         200,
         "Published workflows retrieved successfully",
@@ -609,13 +625,12 @@ class PublishedAllRagPipelineApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def get(self, pipeline: Pipeline):
+    def get(self, current_user: Account, pipeline: Pipeline):
         """
         Get published workflows
         """
-        current_user, _ = current_account_with_tenant()
-
         query = WorkflowListQuery.model_validate(request.args.to_dict())
 
         page = query.page
@@ -655,9 +670,9 @@ class RagPipelineDraftWorkflowRestoreApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def post(self, pipeline: Pipeline, workflow_id: str):
-        current_user, _ = current_account_with_tenant()
+    def post(self, current_user: Account, pipeline: Pipeline, workflow_id: str):
         rag_pipeline_service = RagPipelineService()
 
         try:
@@ -689,14 +704,13 @@ class RagPipelineByIdApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @with_current_user
     @get_rag_pipeline
-    def patch(self, pipeline: Pipeline, workflow_id: str):
+    @console_ns.expect(console_ns.models[WorkflowUpdatePayload.__name__])
+    def patch(self, current_user: Account, pipeline: Pipeline, workflow_id: str):
         """
         Update workflow attributes
         """
-        # Check permission
-        current_user, _ = current_account_with_tenant()
-
         payload = WorkflowUpdatePayload.model_validate(console_ns.payload or {})
         update_data = payload.model_dump(exclude_unset=True)
 
@@ -754,6 +768,8 @@ class RagPipelineByIdApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/processing/parameters")
 class PublishedRagPipelineSecondStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -774,6 +790,8 @@ class PublishedRagPipelineSecondStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/published/pre-processing/parameters")
 class PublishedRagPipelineFirstStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -794,6 +812,8 @@ class PublishedRagPipelineFirstStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/pre-processing/parameters")
 class DraftRagPipelineFirstStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -814,6 +834,8 @@ class DraftRagPipelineFirstStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflows/draft/processing/parameters")
 class DraftRagPipelineSecondStepApi(Resource):
+    @console_ns.doc(params=query_params_from_model(NodeIdQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineStepParametersResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -835,6 +857,7 @@ class DraftRagPipelineSecondStepApi(Resource):
 
 @console_ns.route("/rag/pipelines/<uuid:pipeline_id>/workflow-runs")
 class RagPipelineWorkflowRunListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(WorkflowRunQuery))
     @console_ns.response(
         200,
         "Workflow runs retrieved successfully",
@@ -855,7 +878,7 @@ class RagPipelineWorkflowRunListApi(Resource):
             }
         )
         args = {
-            "last_id": str(query.last_id) if query.last_id else None,
+            "last_id": query.last_id or None,
             "limit": query.limit,
         }
 
@@ -901,7 +924,8 @@ class RagPipelineWorkflowRunNodeExecutionListApi(Resource):
     @login_required
     @account_initialization_required
     @get_rag_pipeline
-    def get(self, pipeline: Pipeline, run_id: UUID):
+    @with_current_user
+    def get(self, current_user: Account, pipeline: Pipeline, run_id: UUID):
         """
         Get workflow run node execution list
         """
@@ -922,11 +946,12 @@ class RagPipelineWorkflowRunNodeExecutionListApi(Resource):
 
 @console_ns.route("/rag/pipelines/datasource-plugins")
 class DatasourceListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str):
         return jsonable_encoder(RagPipelineManageService.list_rag_pipeline_datasources(current_tenant_id))
 
 
@@ -958,12 +983,12 @@ class RagPipelineWorkflowLastRunApi(Resource):
 
 @console_ns.route("/rag/pipelines/transform/datasets/<uuid:dataset_id>")
 class RagPipelineTransformApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, dataset_id: UUID):
-        current_user, _ = current_account_with_tenant()
-
+    @with_current_user
+    def post(self, current_user: Account, dataset_id: UUID):
         if not (current_user.has_edit_permission or current_user.is_dataset_operator):
             raise Forbidden()
 
@@ -984,13 +1009,13 @@ class RagPipelineDatasourceVariableApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_rag_pipeline
     @edit_permission_required
-    def post(self, pipeline: Pipeline):
+    def post(self, current_user: Account, pipeline: Pipeline):
         """
         Set datasource variables
         """
-        current_user, _ = current_account_with_tenant()
         args = DatasourceVariablesPayload.model_validate(console_ns.payload or {}).model_dump()
 
         rag_pipeline_service = RagPipelineService()
@@ -1006,12 +1031,16 @@ class RagPipelineDatasourceVariableApi(Resource):
 
 @console_ns.route("/rag/pipelines/recommended-plugins")
 class RagPipelineRecommendedPluginApi(Resource):
+    @console_ns.doc(params=query_params_from_model(RagPipelineRecommendedPluginQuery))
+    @console_ns.response(200, "Success", console_ns.models[RagPipelineOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account):
         query = RagPipelineRecommendedPluginQuery.model_validate(request.args.to_dict())
 
         rag_pipeline_service = RagPipelineService()
-        recommended_plugins = rag_pipeline_service.get_recommended_plugins(query.type)
+        recommended_plugins = rag_pipeline_service.get_recommended_plugins(query.type, current_user, current_tenant_id)
         return recommended_plugins

api/controllers/console/datasets/website.py

@@ -1,10 +1,10 @@
-from typing import Literal
+from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel
+from pydantic import BaseModel, RootModel
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.datasets.error import WebsiteCrawlError
 from controllers.console.wraps import account_initialization_required, setup_required
@@ -22,7 +22,12 @@ class WebsiteCrawlStatusQuery(BaseModel):
     provider: Literal["firecrawl", "watercrawl", "jinareader"]
 
 
+class WebsiteCrawlResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(console_ns, WebsiteCrawlPayload, WebsiteCrawlStatusQuery)
+register_response_schema_models(console_ns, WebsiteCrawlResponse)
 
 
 @console_ns.route("/website/crawl")
@@ -30,7 +35,7 @@ class WebsiteCrawlApi(Resource):
     @console_ns.doc("crawl_website")
     @console_ns.doc(description="Crawl website content")
     @console_ns.expect(console_ns.models[WebsiteCrawlPayload.__name__])
-    @console_ns.response(200, "Website crawl initiated successfully")
+    @console_ns.response(200, "Website crawl initiated successfully", console_ns.models[WebsiteCrawlResponse.__name__])
     @console_ns.response(400, "Invalid crawl parameters")
     @setup_required
     @login_required
@@ -57,8 +62,8 @@ class WebsiteCrawlStatusApi(Resource):
     @console_ns.doc("get_crawl_status")
     @console_ns.doc(description="Get website crawl status")
     @console_ns.doc(params={"job_id": "Crawl job ID", "provider": "Crawl provider (firecrawl/watercrawl/jinareader)"})
-    @console_ns.expect(console_ns.models[WebsiteCrawlStatusQuery.__name__])
-    @console_ns.response(200, "Crawl status retrieved successfully")
+    @console_ns.doc(params=query_params_from_model(WebsiteCrawlStatusQuery))
+    @console_ns.response(200, "Crawl status retrieved successfully", console_ns.models[WebsiteCrawlResponse.__name__])
     @console_ns.response(404, "Crawl job not found")
     @console_ns.response(400, "Invalid provider")
     @setup_required

api/controllers/console/explore/audio.py

@@ -5,7 +5,8 @@ from werkzeug.exceptions import InternalServerError
 
 import services
 from controllers.common.controller_schemas import TextToAudioPayload
-from controllers.common.schema import register_schema_model
+from controllers.common.fields import AudioBinaryResponse, AudioTranscriptResponse
+from controllers.common.schema import register_response_schema_models, register_schema_model
 from controllers.console.app.error import (
     AppUnavailableError,
     AudioTooLargeError,
@@ -34,6 +35,7 @@ from .. import console_ns
 logger = logging.getLogger(__name__)
 
 register_schema_model(console_ns, TextToAudioPayload)
+register_response_schema_models(console_ns, AudioBinaryResponse, AudioTranscriptResponse)
 
 
 @console_ns.route(
@@ -41,6 +43,7 @@ register_schema_model(console_ns, TextToAudioPayload)
     endpoint="installed_app_audio",
 )
 class ChatAudioApi(InstalledAppResource):
+    @console_ns.response(200, "Success", console_ns.models[AudioTranscriptResponse.__name__])
     def post(self, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
@@ -84,6 +87,7 @@ class ChatAudioApi(InstalledAppResource):
 )
 class ChatTextApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[TextToAudioPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[AudioBinaryResponse.__name__])
     def post(self, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:

api/controllers/console/explore/banner.py

@@ -1,17 +1,44 @@
+from typing import Any, cast
+
 from flask import request
-from flask_restx import Resource
+from flask_restx import Namespace, Resource
+from pydantic import BaseModel, Field, RootModel
 from sqlalchemy import select
 
+from controllers.common.schema import query_params_from_model, register_response_schema_models
 from controllers.console import api
 from controllers.console.explore.wraps import explore_banner_enabled
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from models.enums import BannerStatus
 from models.model import ExporleBanner
 
 
+class BannerListQuery(BaseModel):
+    language: str = Field(default="en-US", description="Banner language")
+
+
+class BannerResponse(ResponseModel):
+    id: str
+    content: Any
+    link: str | None = None
+    sort: int
+    status: str
+    created_at: str | None = None
+
+
+class BannerListResponse(RootModel[list[BannerResponse]]):
+    root: list[BannerResponse]
+
+
+register_response_schema_models(cast(Namespace, api), BannerListResponse)
+
+
 class BannerApi(Resource):
     """Resource for banner list."""
 
+    @api.doc(params=query_params_from_model(BannerListQuery))
+    @api.response(200, "Success", api.models[BannerListResponse.__name__])
     @explore_banner_enabled
     def get(self):
         """Get banner list."""

api/controllers/console/explore/completion.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel, Field, field_validator
 from werkzeug.exceptions import InternalServerError, NotFound
 
 import services
-from controllers.common.fields import SimpleResultResponse
+from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console.app.error import (
     AppUnavailableError,
@@ -18,7 +18,7 @@ from controllers.console.app.error import (
 )
 from controllers.console.explore.error import NotChatAppError, NotCompletionAppError
 from controllers.console.explore.wraps import InstalledAppResource
-from controllers.console.wraps import with_current_user_id
+from controllers.console.wraps import with_current_user, with_current_user_id
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.entities.app_invoke_entities import InvokeFrom
 from core.errors.error import (
@@ -30,7 +30,6 @@ from extensions.ext_database import db
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
 from libs.datetime_utils import naive_utc_now
-from libs.login import current_user
 from models import Account
 from models.model import AppMode, InstalledApp
 from services.app_generate_service import AppGenerateService
@@ -45,7 +44,7 @@ logger = logging.getLogger(__name__)
 class CompletionMessageExplorePayload(BaseModel):
     inputs: dict[str, Any]
     query: str = ""
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
     response_mode: Literal["blocking", "streaming"] | None = None
     retriever_from: str = Field(default="explore_app")
 
@@ -53,7 +52,7 @@ class CompletionMessageExplorePayload(BaseModel):
 class ChatMessagePayload(BaseModel):
     inputs: dict[str, Any]
     query: str
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
     conversation_id: str | None = None
     parent_message_id: str | None = None
     retriever_from: str = Field(default="explore_app")
@@ -74,7 +73,7 @@ class ChatMessagePayload(BaseModel):
 
 
 register_schema_models(console_ns, CompletionMessageExplorePayload, ChatMessagePayload)
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, GeneratedAppResponse, SimpleResultResponse)
 
 
 # define completion api for user
@@ -84,7 +83,9 @@ register_response_schema_models(console_ns, SimpleResultResponse)
 )
 class CompletionApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[CompletionMessageExplorePayload.__name__])
-    def post(self, installed_app: InstalledApp):
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -101,8 +102,6 @@ class CompletionApi(InstalledAppResource):
         db.session.commit()
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=streaming
             )
@@ -160,7 +159,9 @@ class CompletionStopApi(InstalledAppResource):
 )
 class ChatApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
-    def post(self, installed_app: InstalledApp):
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -177,8 +178,6 @@ class ChatApi(InstalledAppResource):
         db.session.commit()
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             response = AppGenerateService.generate(
                 app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.EXPLORE, streaming=True
             )

api/controllers/console/explore/conversation.py

@@ -7,10 +7,11 @@ from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import NotFound
 
 from controllers.common.controller_schemas import ConversationRenamePayload
-from controllers.common.schema import 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.app.error import AppUnavailableError
 from controllers.console.explore.error import NotChatAppError
 from controllers.console.explore.wraps import InstalledAppResource
+from controllers.console.wraps import with_current_user
 from core.app.entities.app_invoke_entities import InvokeFrom
 from extensions.ext_database import db
 from fields.conversation_fields import (
@@ -19,7 +20,6 @@ from fields.conversation_fields import (
     SimpleConversation,
 )
 from libs.helper import UUIDStrOrEmpty
-from libs.login import current_user
 from models import Account
 from models.model import AppMode, InstalledApp
 from services.conversation_service import ConversationService
@@ -36,7 +36,12 @@ class ConversationListQuery(BaseModel):
 
 
 register_schema_models(console_ns, ConversationListQuery, ConversationRenamePayload)
-register_response_schema_models(console_ns, ResultResponse)
+register_response_schema_models(
+    console_ns,
+    ConversationInfiniteScrollPagination,
+    ResultResponse,
+    SimpleConversation,
+)
 
 
 @console_ns.route(
@@ -44,8 +49,10 @@ register_response_schema_models(console_ns, ResultResponse)
     endpoint="installed_app_conversations",
 )
 class ConversationListApi(InstalledAppResource):
-    @console_ns.expect(console_ns.models[ConversationListQuery.__name__])
-    def get(self, installed_app: InstalledApp):
+    @console_ns.doc(params=query_params_from_model(ConversationListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ConversationInfiniteScrollPagination.__name__])
+    @with_current_user
+    def get(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -66,14 +73,12 @@ class ConversationListApi(InstalledAppResource):
         args = ConversationListQuery.model_validate(raw_args)
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             with sessionmaker(db.engine).begin() as session:
                 pagination = WebConversationService.pagination_by_last_id(
                     session=session,
                     app_model=app_model,
                     user=current_user,
-                    last_id=str(args.last_id) if args.last_id else None,
+                    last_id=args.last_id or None,
                     limit=args.limit,
                     invoke_from=InvokeFrom.EXPLORE,
                     pinned=args.pinned,
@@ -95,7 +100,8 @@ class ConversationListApi(InstalledAppResource):
 )
 class ConversationApi(InstalledAppResource):
     @console_ns.response(204, "Conversation deleted successfully")
-    def delete(self, installed_app: InstalledApp, c_id: UUID):
+    @with_current_user
+    def delete(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -105,8 +111,6 @@ class ConversationApi(InstalledAppResource):
 
         conversation_id = str(c_id)
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             ConversationService.delete(app_model, conversation_id, current_user)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
@@ -120,7 +124,9 @@ class ConversationApi(InstalledAppResource):
 )
 class ConversationRenameApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[ConversationRenamePayload.__name__])
-    def post(self, installed_app: InstalledApp, c_id: UUID):
+    @console_ns.response(200, "Conversation renamed successfully", console_ns.models[SimpleConversation.__name__])
+    @with_current_user
+    def post(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -133,8 +139,6 @@ class ConversationRenameApi(InstalledAppResource):
         payload = ConversationRenamePayload.model_validate(console_ns.payload or {})
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             conversation = ConversationService.rename(
                 app_model, conversation_id, current_user, payload.name, payload.auto_generate
             )
@@ -153,7 +157,8 @@ class ConversationRenameApi(InstalledAppResource):
 )
 class ConversationPinApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def patch(self, installed_app: InstalledApp, c_id: UUID):
+    @with_current_user
+    def patch(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -164,8 +169,6 @@ class ConversationPinApi(InstalledAppResource):
         conversation_id = str(c_id)
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             WebConversationService.pin(app_model, conversation_id, current_user)
         except ConversationNotExistsError:
             raise NotFound("Conversation Not Exists.")
@@ -179,7 +182,8 @@ class ConversationPinApi(InstalledAppResource):
 )
 class ConversationUnPinApi(InstalledAppResource):
     @console_ns.response(200, "Success", console_ns.models[ResultResponse.__name__])
-    def patch(self, installed_app: InstalledApp, c_id: UUID):
+    @with_current_user
+    def patch(self, current_user: Account, installed_app: InstalledApp, c_id: UUID):
         app_model = installed_app.app
         if app_model is None:
             raise AppUnavailableError()
@@ -188,8 +192,6 @@ class ConversationUnPinApi(InstalledAppResource):
             raise NotChatAppError()
 
         conversation_id = str(c_id)
-        if not isinstance(current_user, Account):
-            raise ValueError("current_user must be an Account instance")
         WebConversationService.unpin(app_model, conversation_id, current_user)
 
         return ResultResponse(result="success").model_dump(mode="json")

api/controllers/console/explore/installed_app.py

@@ -5,11 +5,11 @@ from typing import Any
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, computed_field, field_validator
-from sqlalchemy import and_, select
+from sqlalchemy import and_, exists, or_, select
 from werkzeug.exceptions import BadRequest, Forbidden, NotFound
 
 from controllers.common.fields import SimpleMessageResponse, SimpleResultMessageResponse
-from controllers.common.schema import 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.explore.wraps import InstalledAppResource
 from controllers.console.wraps import (
@@ -24,8 +24,8 @@ from graphon.file import helpers as file_helpers
 from libs.datetime_utils import naive_utc_now
 from libs.helper import to_timestamp
 from libs.login import login_required
-from models import Account, App, InstalledApp, RecommendedApp
-from models.model import IconType
+from models import Account, App, AppModelConfig, InstalledApp, RecommendedApp, Workflow
+from models.model import AppMode, IconType
 from services.account_service import TenantService
 from services.enterprise.enterprise_service import EnterpriseService
 from services.feature_service import FeatureService
@@ -61,6 +61,24 @@ def _safe_primitive(value: Any) -> Any:
     return None
 
 
+def _published_app_filter():
+    """Return the SQL predicate for installed-app web API availability.
+
+    The installed-app parameters endpoint reads the published workflow for
+    workflow-style apps and the published app model config for easy UI apps.
+    Keep the list endpoint aligned in SQL so it does not return entries that
+    will immediately fail with app_unavailable when opened.
+    """
+    workflow_app_modes = (AppMode.ADVANCED_CHAT, AppMode.WORKFLOW)
+    has_published_workflow = exists(select(Workflow.id).where(Workflow.id == App.workflow_id))
+    has_published_model_config = exists(select(AppModelConfig.id).where(AppModelConfig.id == App.app_model_config_id))
+
+    return or_(
+        and_(App.mode.in_(workflow_app_modes), App.workflow_id.isnot(None), has_published_workflow),
+        and_(~App.mode.in_(workflow_app_modes), App.app_model_config_id.isnot(None), has_published_model_config),
+    )
+
+
 class InstalledAppInfoResponse(ResponseModel):
     id: str
     name: str | None = None
@@ -135,39 +153,39 @@ register_response_schema_models(console_ns, SimpleMessageResponse, SimpleResultM
 class InstalledAppsListApi(Resource):
     @login_required
     @account_initialization_required
+    @console_ns.doc(params=query_params_from_model(InstalledAppsListQuery))
     @console_ns.response(200, "Success", console_ns.models[InstalledAppListResponse.__name__])
     @with_current_user
     @with_current_tenant_id
     def get(self, current_tenant_id: str, current_user: Account):
         query = InstalledAppsListQuery.model_validate(request.args.to_dict())
 
+        stmt = (
+            select(InstalledApp, App)
+            .join(App, App.id == InstalledApp.app_id)
+            .where(InstalledApp.tenant_id == current_tenant_id, _published_app_filter())
+        )
         if query.app_id:
-            installed_apps = db.session.scalars(
-                select(InstalledApp).where(
-                    and_(InstalledApp.tenant_id == current_tenant_id, InstalledApp.app_id == query.app_id)
-                )
-            ).all()
-        else:
-            installed_apps = db.session.scalars(
-                select(InstalledApp).where(InstalledApp.tenant_id == current_tenant_id)
-            ).all()
+            stmt = stmt.where(InstalledApp.app_id == query.app_id)
+
+        installed_apps = db.session.execute(stmt).all()
 
         if current_user.current_tenant is None:
             raise ValueError("current_user.current_tenant must not be None")
         current_user.role = TenantService.get_user_role(current_user, current_user.current_tenant)
-        installed_app_list: list[dict[str, Any]] = [
-            {
-                "id": installed_app.id,
-                "app": installed_app.app,
-                "app_owner_tenant_id": installed_app.app_owner_tenant_id,
-                "is_pinned": installed_app.is_pinned,
-                "last_used_at": installed_app.last_used_at,
-                "editable": current_user.role in {"owner", "admin"},
-                "uninstallable": current_tenant_id == installed_app.app_owner_tenant_id,
-            }
-            for installed_app in installed_apps
-            if installed_app.app is not None
-        ]
+        installed_app_list: list[dict[str, Any]] = []
+        for installed_app, app_model in installed_apps:
+            installed_app_list.append(
+                {
+                    "id": installed_app.id,
+                    "app": app_model,
+                    "app_owner_tenant_id": installed_app.app_owner_tenant_id,
+                    "is_pinned": installed_app.is_pinned,
+                    "last_used_at": installed_app.last_used_at,
+                    "editable": current_user.role in {"owner", "admin"},
+                    "uninstallable": current_tenant_id == installed_app.app_owner_tenant_id,
+                }
+            )
 
         # filter out apps that user doesn't have access to
         if FeatureService.get_system_features().webapp_auth.enabled:
@@ -217,6 +235,7 @@ class InstalledAppsListApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("apps")
+    @console_ns.expect(console_ns.models[InstalledAppCreatePayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[SimpleMessageResponse.__name__])
     @with_current_tenant_id
     def post(self, current_tenant_id: str):
@@ -278,6 +297,7 @@ class InstalledAppApi(InstalledAppResource):
         return "", 204
 
     @console_ns.response(200, "Success", console_ns.models[SimpleResultMessageResponse.__name__])
+    @console_ns.expect(console_ns.models[InstalledAppUpdatePayload.__name__])
     def patch(self, installed_app: InstalledApp):
         payload = InstalledAppUpdatePayload.model_validate(console_ns.payload or {})
 

api/controllers/console/explore/message.py

@@ -7,7 +7,8 @@ from pydantic import BaseModel, TypeAdapter
 from werkzeug.exceptions import InternalServerError, NotFound
 
 from controllers.common.controller_schemas import MessageFeedbackPayload, MessageListQuery
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import GeneratedAppResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console.app.error import (
     AppMoreLikeThisDisabledError,
     AppUnavailableError,
@@ -52,7 +53,13 @@ class MoreLikeThisQuery(BaseModel):
 
 
 register_schema_models(console_ns, MessageListQuery, MessageFeedbackPayload, MoreLikeThisQuery)
-register_response_schema_models(console_ns, ResultResponse, SuggestedQuestionsResponse)
+register_response_schema_models(
+    console_ns,
+    GeneratedAppResponse,
+    MessageInfiniteScrollPagination,
+    ResultResponse,
+    SuggestedQuestionsResponse,
+)
 
 
 @console_ns.route(
@@ -60,7 +67,8 @@ register_response_schema_models(console_ns, ResultResponse, SuggestedQuestionsRe
     endpoint="installed_app_messages",
 )
 class MessageListApi(InstalledAppResource):
-    @console_ns.expect(console_ns.models[MessageListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(MessageListQuery))
+    @console_ns.response(200, "Success", console_ns.models[MessageInfiniteScrollPagination.__name__])
     @with_current_user
     def get(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app
@@ -129,7 +137,8 @@ class MessageFeedbackApi(InstalledAppResource):
     endpoint="installed_app_more_like_this",
 )
 class MessageMoreLikeThisApi(InstalledAppResource):
-    @console_ns.expect(console_ns.models[MoreLikeThisQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(MoreLikeThisQuery))
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
     @with_current_user
     def get(self, current_user: Account, installed_app: InstalledApp, message_id: UUID):
         app_model = installed_app.app

api/controllers/console/explore/parameter.py

@@ -1,6 +1,9 @@
 from typing import Any, cast
 
+from pydantic import BaseModel, Field
+
 from controllers.common import fields
+from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import AppUnavailableError
 from controllers.console.explore.wraps import InstalledAppResource
@@ -9,10 +12,18 @@ from models.model import AppMode, InstalledApp
 from services.app_service import AppService
 
 
+class ExploreAppMetaResponse(BaseModel):
+    tool_icons: dict[str, Any] = Field(default_factory=dict)
+
+
+register_response_schema_models(console_ns, fields.Parameters, ExploreAppMetaResponse)
+
+
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/parameters", endpoint="installed_app_parameters")
 class AppParameterApi(InstalledAppResource):
     """Resource for app variables."""
 
+    @console_ns.response(200, "Success", console_ns.models[fields.Parameters.__name__])
     def get(self, installed_app: InstalledApp):
         """Retrieve app parameters."""
         app_model = installed_app.app
@@ -42,6 +53,7 @@ class AppParameterApi(InstalledAppResource):
 
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/meta", endpoint="installed_app_meta")
 class ExploreAppMetaApi(InstalledAppResource):
+    @console_ns.response(200, "Success", console_ns.models[ExploreAppMetaResponse.__name__])
     def get(self, installed_app: InstalledApp):
         """Get app meta"""
         app_model = installed_app.app

api/controllers/console/explore/recommended_app.py

@@ -3,10 +3,10 @@ from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field, computed_field, field_validator
+from pydantic import BaseModel, Field, RootModel, computed_field, field_validator
 
 from constants.languages import languages
-from controllers.common.schema import query_params_from_model, register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import account_initialization_required, with_current_user
 from fields.base import ResponseModel
@@ -65,6 +65,10 @@ class RecommendedAppListResponse(ResponseModel):
     categories: list[str]
 
 
+class RecommendedAppDetailResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(
     console_ns,
     RecommendedAppsQuery,
@@ -72,6 +76,7 @@ register_schema_models(
     RecommendedAppResponse,
     RecommendedAppListResponse,
 )
+register_response_schema_models(console_ns, RecommendedAppDetailResponse)
 
 
 @console_ns.route("/explore/apps")
@@ -100,6 +105,7 @@ class RecommendedAppListApi(Resource):
 
 @console_ns.route("/explore/apps/<uuid:app_id>")
 class RecommendedAppApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[RecommendedAppDetailResponse.__name__])
     @login_required
     @account_initialization_required
     def get(self, app_id: UUID):

api/controllers/console/explore/saved_message.py

@@ -5,7 +5,7 @@ from pydantic import TypeAdapter
 from werkzeug.exceptions import NotFound
 
 from controllers.common.controller_schemas import SavedMessageCreatePayload, SavedMessageListQuery
-from controllers.common.schema import 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.app.error import AppUnavailableError
 from controllers.console.explore.error import NotCompletionAppError
@@ -19,12 +19,13 @@ from services.errors.message import MessageNotExistsError
 from services.saved_message_service import SavedMessageService
 
 register_schema_models(console_ns, SavedMessageListQuery, SavedMessageCreatePayload)
-register_response_schema_models(console_ns, ResultResponse)
+register_response_schema_models(console_ns, ResultResponse, SavedMessageInfiniteScrollPagination)
 
 
 @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__])
+    @console_ns.doc(params=query_params_from_model(SavedMessageListQuery))
+    @console_ns.response(200, "Success", console_ns.models[SavedMessageInfiniteScrollPagination.__name__])
     @with_current_user
     def get(self, current_user: Account, installed_app: InstalledApp):
         app_model = installed_app.app

api/controllers/console/explore/trial.py

@@ -3,14 +3,25 @@ from typing import Any, Literal, cast
 
 from flask import request
 from flask_restx import Resource, fields, marshal, marshal_with
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from sqlalchemy import select
 from werkzeug.exceptions import Forbidden, InternalServerError, NotFound
 
 import services
+from controllers.common.fields import (
+    AudioBinaryResponse,
+    AudioTranscriptResponse,
+    GeneratedAppResponse,
+    SimpleResultResponse,
+)
 from controllers.common.fields import Parameters as ParametersResponse
 from controllers.common.fields import Site as SiteResponse
-from controllers.common.schema import get_or_create_model, register_schema_models
+from controllers.common.schema import (
+    get_or_create_model,
+    query_params_from_model,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.app.error import (
     AppUnavailableError,
@@ -33,6 +44,7 @@ from controllers.console.explore.error import (
     NotWorkflowAppError,
 )
 from controllers.console.explore.wraps import TrialAppResource, trial_feature_enable
+from controllers.console.wraps import with_current_user
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.app_config.common.parameters_mapping import get_parameters_from_feature_dict
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -53,6 +65,7 @@ from fields.app_fields import (
 )
 from fields.dataset_fields import dataset_fields
 from fields.member_fields import simple_account_fields
+from fields.message_fields import SuggestedQuestionsResponse
 from fields.workflow_fields import (
     conversation_variable_fields,
     pipeline_variable_fields,
@@ -63,7 +76,6 @@ from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
 from libs.helper import uuid_value
-from libs.login import current_user
 from models import Account
 from models.account import TenantStatus
 from models.model import AppMode, Site
@@ -119,16 +131,28 @@ workflow_fields_copy["conversation_variables"] = fields.List(fields.Nested(conve
 workflow_fields_copy["rag_pipeline_variables"] = fields.List(fields.Nested(pipeline_variable_model))
 workflow_model = get_or_create_model("TrialWorkflow", workflow_fields_copy)
 
+dataset_model = get_or_create_model("TrialDataset", dataset_fields)
+dataset_list_model = get_or_create_model(
+    "TrialDatasetList",
+    {
+        "data": fields.List(fields.Nested(dataset_model)),
+        "has_more": fields.Boolean,
+        "limit": fields.Integer,
+        "total": fields.Integer,
+        "page": fields.Integer,
+    },
+)
+
 
 class WorkflowRunRequest(BaseModel):
     inputs: dict
-    files: list | None = None
+    files: list | None = Field(default=None)
 
 
 class ChatRequest(BaseModel):
     inputs: dict
     query: str
-    files: list | None = None
+    files: list | None = Field(default=None)
     conversation_id: str | None = None
     parent_message_id: str | None = None
     retriever_from: str = "explore_app"
@@ -144,18 +168,43 @@ class TextToSpeechRequest(BaseModel):
 class CompletionRequest(BaseModel):
     inputs: dict
     query: str = ""
-    files: list | None = None
+    files: list | None = Field(default=None)
     response_mode: Literal["blocking", "streaming"] | None = None
     retriever_from: str = "explore_app"
 
 
-register_schema_models(console_ns, WorkflowRunRequest, ChatRequest, TextToSpeechRequest, CompletionRequest)
+class TrialDatasetListQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, description="Number of items per page")
+    ids: list[str] = Field(default_factory=list, description="Dataset IDs")
+
+
+register_schema_models(
+    console_ns,
+    WorkflowRunRequest,
+    ChatRequest,
+    TextToSpeechRequest,
+    CompletionRequest,
+    TrialDatasetListQuery,
+)
+register_response_schema_models(
+    console_ns,
+    ParametersResponse,
+    AudioBinaryResponse,
+    AudioTranscriptResponse,
+    GeneratedAppResponse,
+    SimpleResultResponse,
+    SiteResponse,
+    SuggestedQuestionsResponse,
+)
 
 
 class TrialAppWorkflowRunApi(TrialAppResource):
     @trial_feature_enable
     @console_ns.expect(console_ns.models[WorkflowRunRequest.__name__])
-    def post(self, trial_app):
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
+    @with_current_user
+    def post(self, current_user: Account, trial_app):
         """
         Run workflow
         """
@@ -168,7 +217,6 @@ class TrialAppWorkflowRunApi(TrialAppResource):
 
         request_data = WorkflowRunRequest.model_validate(console_ns.payload)
         args = request_data.model_dump()
-        assert current_user is not None
         try:
             app_id = app_model.id
             user_id = current_user.id
@@ -195,6 +243,7 @@ class TrialAppWorkflowRunApi(TrialAppResource):
 
 
 class TrialAppWorkflowTaskStopApi(TrialAppResource):
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @trial_feature_enable
     def post(self, trial_app, task_id: str):
         """
@@ -206,7 +255,6 @@ class TrialAppWorkflowTaskStopApi(TrialAppResource):
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode != AppMode.WORKFLOW:
             raise NotWorkflowAppError()
-        assert current_user is not None
 
         # Stop using both mechanisms for backward compatibility
         # Legacy stop flag mechanism (without user check)
@@ -220,8 +268,10 @@ class TrialAppWorkflowTaskStopApi(TrialAppResource):
 
 class TrialChatApi(TrialAppResource):
     @console_ns.expect(console_ns.models[ChatRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
     @trial_feature_enable
-    def post(self, trial_app):
+    @with_current_user
+    def post(self, current_user: Account, trial_app):
         app_model = trial_app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
@@ -239,9 +289,6 @@ class TrialChatApi(TrialAppResource):
         args["auto_generate_name"] = False
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
-
             # Get IDs before they might be detached from session
             app_id = app_model.id
             user_id = current_user.id
@@ -276,7 +323,9 @@ class TrialChatApi(TrialAppResource):
 
 
 class TrialMessageSuggestedQuestionApi(TrialAppResource):
-    def get(self, trial_app, message_id):
+    @console_ns.response(200, "Success", console_ns.models[SuggestedQuestionsResponse.__name__])
+    @with_current_user
+    def get(self, current_user: Account, trial_app, message_id):
         app_model = trial_app
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
@@ -285,8 +334,6 @@ class TrialMessageSuggestedQuestionApi(TrialAppResource):
         message_id = str(message_id)
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
             questions = MessageService.get_suggested_questions_after_answer(
                 app_model=app_model, user=current_user, message_id=message_id, invoke_from=InvokeFrom.EXPLORE
             )
@@ -312,16 +359,15 @@ class TrialMessageSuggestedQuestionApi(TrialAppResource):
 
 
 class TrialChatAudioApi(TrialAppResource):
+    @console_ns.response(200, "Success", console_ns.models[AudioTranscriptResponse.__name__])
     @trial_feature_enable
-    def post(self, trial_app):
+    @with_current_user
+    def post(self, current_user: Account, trial_app):
         app_model = trial_app
 
         file = request.files["file"]
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
-
             # Get IDs before they might be detached from session
             app_id = app_model.id
             user_id = current_user.id
@@ -357,8 +403,10 @@ class TrialChatAudioApi(TrialAppResource):
 
 class TrialChatTextApi(TrialAppResource):
     @console_ns.expect(console_ns.models[TextToSpeechRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[AudioBinaryResponse.__name__])
     @trial_feature_enable
-    def post(self, trial_app):
+    @with_current_user
+    def post(self, current_user: Account, trial_app):
         app_model = trial_app
         try:
             request_data = TextToSpeechRequest.model_validate(console_ns.payload)
@@ -366,8 +414,6 @@ class TrialChatTextApi(TrialAppResource):
             message_id = request_data.message_id
             text = request_data.text
             voice = request_data.voice
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
 
             # Get IDs before they might be detached from session
             app_id = app_model.id
@@ -404,8 +450,10 @@ class TrialChatTextApi(TrialAppResource):
 
 class TrialCompletionApi(TrialAppResource):
     @console_ns.expect(console_ns.models[CompletionRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
     @trial_feature_enable
-    def post(self, trial_app):
+    @with_current_user
+    def post(self, current_user: Account, trial_app):
         app_model = trial_app
         if app_model.mode != "completion":
             raise NotCompletionAppError()
@@ -417,9 +465,6 @@ class TrialCompletionApi(TrialAppResource):
         args["auto_generate_name"] = False
 
         try:
-            if not isinstance(current_user, Account):
-                raise ValueError("current_user must be an Account instance")
-
             # Get IDs before they might be detached from session
             app_id = app_model.id
             user_id = current_user.id
@@ -455,6 +500,7 @@ class TrialCompletionApi(TrialAppResource):
 class TrialSitApi(Resource):
     """Resource for trial app sites."""
 
+    @console_ns.response(200, "Success", console_ns.models[SiteResponse.__name__])
     @get_app_model_with_trial(None)
     def get(self, app_model):
         """Retrieve app site info.
@@ -476,6 +522,7 @@ class TrialSitApi(Resource):
 class TrialAppParameterApi(Resource):
     """Resource for app variables."""
 
+    @console_ns.response(200, "Success", console_ns.models[ParametersResponse.__name__])
     @get_app_model_with_trial(None)
     def get(self, app_model):
         """Retrieve app parameters."""
@@ -504,6 +551,7 @@ class TrialAppParameterApi(Resource):
 
 
 class AppApi(Resource):
+    @console_ns.response(200, "Success", app_detail_with_site_model)
     @get_app_model_with_trial(None)
     @marshal_with(app_detail_with_site_model)
     def get(self, app_model):
@@ -516,6 +564,7 @@ class AppApi(Resource):
 
 
 class AppWorkflowApi(Resource):
+    @console_ns.response(200, "Success", workflow_model)
     @get_app_model_with_trial(None)
     @marshal_with(workflow_model)
     def get(self, app_model):
@@ -528,6 +577,8 @@ class AppWorkflowApi(Resource):
 
 
 class DatasetListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(TrialDatasetListQuery))
+    @console_ns.response(200, "Success", dataset_list_model)
     @get_app_model_with_trial(None)
     def get(self, app_model):
         page = request.args.get("page", default=1, type=int)

api/controllers/console/explore/workflow.py

@@ -3,7 +3,7 @@ import logging
 from werkzeug.exceptions import InternalServerError
 
 from controllers.common.controller_schemas import WorkflowRunPayload
-from controllers.common.fields import SimpleResultResponse
+from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_model
 from controllers.console.app.error import (
     CompletionRequestError,
@@ -36,12 +36,13 @@ from .. import console_ns
 logger = logging.getLogger(__name__)
 
 register_schema_model(console_ns, WorkflowRunPayload)
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(console_ns, GeneratedAppResponse, SimpleResultResponse)
 
 
 @console_ns.route("/installed-apps/<uuid:installed_app_id>/workflows/run")
 class InstalledAppWorkflowRunApi(InstalledAppResource):
     @console_ns.expect(console_ns.models[WorkflowRunPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[GeneratedAppResponse.__name__])
     @with_current_user
     def post(self, current_user: Account, installed_app: InstalledApp):
         """

api/controllers/console/extension.py

@@ -14,7 +14,7 @@ from models.api_based_extension import APIBasedExtension
 from services.api_based_extension_service import APIBasedExtensionService
 from services.code_based_extension_service import CodeBasedExtensionService
 
-from ..common.schema import DEFAULT_REF_TEMPLATE_SWAGGER_2_0, register_schema_models
+from ..common.schema import DEFAULT_REF_TEMPLATE_OPENAPI_3_0, query_params_from_model, register_schema_models
 from . import console_ns
 from .wraps import account_initialization_required, setup_required, with_current_tenant_id
 
@@ -60,10 +60,16 @@ class APIBasedExtensionResponse(ResponseModel):
         return to_timestamp(value)
 
 
-register_schema_models(console_ns, APIBasedExtensionPayload, CodeBasedExtensionResponse, APIBasedExtensionResponse)
+register_schema_models(
+    console_ns,
+    CodeBasedExtensionQuery,
+    APIBasedExtensionPayload,
+    CodeBasedExtensionResponse,
+    APIBasedExtensionResponse,
+)
 console_ns.schema_model(
     "APIBasedExtensionListResponse",
-    TypeAdapter(list[APIBasedExtensionResponse]).json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
+    TypeAdapter(list[APIBasedExtensionResponse]).json_schema(ref_template=DEFAULT_REF_TEMPLATE_OPENAPI_3_0),
 )
 
 
@@ -90,7 +96,7 @@ def _serialize_saved_api_based_extension(extension: APIBasedExtension, api_key:
 class CodeBasedExtensionAPI(Resource):
     @console_ns.doc("get_code_based_extension")
     @console_ns.doc(description="Get code-based extension data by module name")
-    @console_ns.doc(params={"module": "Extension module name"})
+    @console_ns.doc(params=query_params_from_model(CodeBasedExtensionQuery))
     @console_ns.response(
         200,
         "Success",

api/controllers/console/feature.py

@@ -1,10 +1,9 @@
 from flask_restx import Resource
-from werkzeug.exceptions import Unauthorized
 
 from controllers.common.schema import register_response_schema_models
 from fields.base import ResponseModel
 from libs.helper import dump_response
-from libs.login import current_user, login_required
+from libs.login import current_account_with_tenant_optional, login_required
 from services.feature_service import (
     FeatureModel,
     FeatureService,
@@ -13,7 +12,12 @@ from services.feature_service import (
 )
 
 from . import console_ns
-from .wraps import account_initialization_required, cloud_utm_record, setup_required, with_current_tenant_id
+from .wraps import (
+    account_initialization_required,
+    cloud_utm_record,
+    setup_required,
+    with_current_tenant_id,
+)
 
 
 class TrialModelsResponse(ResponseModel):
@@ -133,12 +137,6 @@ class SystemFeatureApi(Resource):
 
         Only non-sensitive configuration data should be returned by this endpoint.
         """
-        # NOTE(QuantumGhost): ideally we should access `current_user.is_authenticated`
-        # without a try-catch. However, due to the implementation of user loader (the `load_user_from_request`
-        # in api/extensions/ext_login.py), accessing `current_user.is_authenticated` will
-        # raise `Unauthorized` exception if authentication token is not provided.
-        try:
-            is_authenticated = current_user.is_authenticated
-        except Unauthorized:
-            is_authenticated = False
+        current_user, _ = current_account_with_tenant_optional()
+        is_authenticated = current_user is not None
         return FeatureService.get_system_features(is_authenticated=is_authenticated).model_dump()

api/controllers/console/human_input_form.py

@@ -5,14 +5,18 @@ Console/Studio Human Input Form APIs.
 import json
 import logging
 from collections.abc import Generator
+from typing import Any
 
 from flask import Response, jsonify, request
 from flask_restx import Resource
+from pydantic import RootModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
 
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.fields import EventStreamResponse
 from controllers.common.human_input import HumanInputFormSubmitPayload
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -21,7 +25,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.apps.advanced_chat.app_generator import AdvancedChatAppGenerator
 from core.app.apps.base_app_generator import BaseAppGenerator
 from core.app.apps.common.workflow_response_converter import WorkflowResponseConverter
@@ -40,7 +43,22 @@ from services.workflow_event_snapshot_service import build_workflow_event_stream
 
 logger = logging.getLogger(__name__)
 
+
+class ConsoleHumanInputFormDefinitionResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class ConsoleHumanInputFormSubmitResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(console_ns, HumanInputFormSubmitPayload)
+register_response_schema_models(
+    console_ns,
+    ConsoleHumanInputFormDefinitionResponse,
+    ConsoleHumanInputFormSubmitResponse,
+    EventStreamResponse,
+)
 
 
 def _jsonify_form_definition(form: Form) -> Response:
@@ -67,6 +85,7 @@ class ConsoleHumanInputFormApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @console_ns.response(200, "Success", console_ns.models[ConsoleHumanInputFormDefinitionResponse.__name__])
     @with_current_tenant_id
     def get(self, current_tenant_id: str, form_token: str):
         """
@@ -89,6 +108,7 @@ class ConsoleHumanInputFormApi(Resource):
     @with_current_tenant_id
     @model_validate(HumanInputFormSubmitPayload)
     @console_ns.expect(console_ns.models[HumanInputFormSubmitPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ConsoleHumanInputFormSubmitResponse.__name__])
     def post(
         self,
         payload: HumanInputFormSubmitPayload,
@@ -136,6 +156,7 @@ class ConsoleHumanInputFormApi(Resource):
 class ConsoleWorkflowEventsApi(Resource):
     """Console API for getting workflow execution events after resume."""
 
+    @console_ns.response(200, "SSE event stream", console_ns.models[EventStreamResponse.__name__])
     @account_initialization_required
     @login_required
     @with_current_user

api/controllers/console/notification.py

@@ -6,7 +6,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models
+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,
@@ -14,6 +14,7 @@ from controllers.console.wraps import (
     setup_required,
     with_current_user,
 )
+from fields.base import ResponseModel
 from libs.login import login_required
 from models import Account
 from services.billing_service import BillingService
@@ -56,7 +57,23 @@ class DismissNotificationPayload(BaseModel):
     notification_id: str = Field(...)
 
 
-register_response_schema_models(console_ns, SimpleResultResponse)
+class NotificationItemResponse(ResponseModel):
+    notification_id: str | None = None
+    frequency: str | None = None
+    lang: str
+    title: str
+    subtitle: str
+    body: str
+    title_pic_url: str
+
+
+class NotificationResponse(ResponseModel):
+    should_show: bool
+    notifications: list[NotificationItemResponse]
+
+
+register_schema_models(console_ns, DismissNotificationPayload)
+register_response_schema_models(console_ns, SimpleResultResponse, NotificationResponse)
 
 
 @console_ns.route("/notification")
@@ -74,6 +91,7 @@ class NotificationApi(Resource):
             401: "Unauthorized",
         },
     )
+    @console_ns.response(200, "Success", console_ns.models[NotificationResponse.__name__])
     @setup_required
     @login_required
     @with_current_user
@@ -121,6 +139,7 @@ class NotificationDismissApi(Resource):
     @with_current_user
     @account_initialization_required
     @only_edition_cloud
+    @console_ns.expect(console_ns.models[DismissNotificationPayload.__name__])
     @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     def post(self, current_user: Account):
         payload = DismissNotificationPayload.model_validate(request.get_json())

api/controllers/console/snippets/payloads.py

@@ -76,7 +76,7 @@ class CreateSnippetPayload(BaseModel):
     description: str | None = Field(default=None, max_length=2000)
     type: Literal["node", "group"] = "node"
     icon_info: IconInfo | None = None
-    graph: dict[str, Any] | None = None
+    graph: dict[str, Any] | None = Field(default=None)
     input_fields: list[InputFieldDefinition] | None = Field(default_factory=list)
 
 
@@ -97,7 +97,7 @@ class SnippetDraftSyncPayload(BaseModel):
         default=None,
         description="Ignored. Snippet workflows do not persist conversation variables.",
     )
-    input_fields: list[dict[str, Any]] | None = None
+    input_fields: list[dict[str, Any]] | None = Field(default=None)
 
 
 class SnippetWorkflowListQuery(BaseModel):
@@ -118,7 +118,7 @@ class SnippetDraftRunPayload(BaseModel):
     """Payload for running snippet draft workflow."""
 
     inputs: dict[str, Any]
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class SnippetDraftNodeRunPayload(BaseModel):
@@ -126,25 +126,25 @@ class SnippetDraftNodeRunPayload(BaseModel):
 
     inputs: dict[str, Any]
     query: str = ""
-    files: list[dict[str, Any]] | None = None
+    files: list[dict[str, Any]] | None = Field(default=None)
 
 
 class SnippetIterationNodeRunPayload(BaseModel):
     """Payload for running an iteration node in snippet draft workflow."""
 
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class SnippetLoopNodeRunPayload(BaseModel):
     """Payload for running a loop node in snippet draft workflow."""
 
-    inputs: dict[str, Any] | None = None
+    inputs: dict[str, Any] | None = Field(default=None)
 
 
 class PublishWorkflowPayload(BaseModel):
     """Payload for publishing snippet workflow."""
 
-    knowledge_base_setting: dict[str, Any] | None = None
+    knowledge_base_setting: dict[str, Any] | None = Field(default=None)
 
 
 class SnippetImportPayload(BaseModel):

api/controllers/console/snippets/snippet_workflow.py

@@ -4,17 +4,21 @@ from functools import wraps
 
 from flask import request
 from flask_restx import Resource
-from pydantic import Field
+from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session, sessionmaker
 from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
 
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import GeneratedAppResponse, SimpleResultResponse
+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.app.error import DraftWorkflowNotExist, DraftWorkflowNotSync
 from controllers.console.app.workflow import (
     RESTORE_SOURCE_WORKFLOW_MUST_BE_PUBLISHED_MESSAGE,
+    DefaultBlockConfigsResponse,
     WorkflowPaginationResponse,
+    WorkflowPublishResponse,
     WorkflowResponse,
+    WorkflowRestoreResponse,
 )
 from controllers.console.snippets.payloads import (
     PublishWorkflowPayload,
@@ -30,6 +34,7 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_user,
 )
 from core.app.apps.base_app_queue_manager import AppQueueManager
 from core.app.entities.app_invoke_entities import InvokeFrom
@@ -45,6 +50,7 @@ from graphon.graph_engine.manager import GraphEngineManager
 from libs import helper
 from libs.helper import TimestampField
 from libs.login import current_account_with_tenant, login_required
+from models import Account
 from models.snippet import CustomizedSnippet
 from services.errors.app import IsDraftWorkflowError, WorkflowHashNotEqualError, WorkflowNotFoundError
 from services.snippet_generate_service import SnippetGenerateService
@@ -67,6 +73,10 @@ class SnippetWorkflowResponse(WorkflowResponse):
     input_fields: list[dict] = Field(default_factory=list)
 
 
+class SnippetDraftConfigResponse(BaseModel):
+    parallel_depth_limit: int
+
+
 register_schema_models(
     console_ns,
     SnippetDraftSyncPayload,
@@ -80,8 +90,14 @@ register_schema_models(
 )
 register_response_schema_models(
     console_ns,
+    DefaultBlockConfigsResponse,
+    GeneratedAppResponse,
+    SimpleResultResponse,
+    SnippetDraftConfigResponse,
     SnippetWorkflowResponse,
+    WorkflowPublishResponse,
     WorkflowPaginationResponse,
+    WorkflowRestoreResponse,
     WorkflowRunPaginationResponse,
     WorkflowRunDetailResponse,
     WorkflowRunNodeExecutionListResponse,
@@ -153,17 +169,20 @@ class SnippetDraftWorkflowApi(Resource):
 
     @console_ns.doc("sync_snippet_draft_workflow")
     @console_ns.expect(console_ns.models.get(SnippetDraftSyncPayload.__name__))
-    @console_ns.response(200, "Draft workflow synced successfully")
+    @console_ns.response(
+        200,
+        "Draft workflow synced successfully",
+        console_ns.models[WorkflowRestoreResponse.__name__],
+    )
     @console_ns.response(400, "Hash mismatch")
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet):
+    def post(self, current_user: Account, snippet: CustomizedSnippet):
         """Sync draft workflow for snippet."""
-        current_user, _ = current_account_with_tenant()
-
         payload = SnippetDraftSyncPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -190,7 +209,11 @@ class SnippetDraftWorkflowApi(Resource):
 @console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/config")
 class SnippetDraftConfigApi(Resource):
     @console_ns.doc("get_snippet_draft_config")
-    @console_ns.response(200, "Draft config retrieved successfully")
+    @console_ns.response(
+        200,
+        "Draft config retrieved successfully",
+        console_ns.models[SnippetDraftConfigResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -234,16 +257,16 @@ class SnippetPublishedWorkflowApi(Resource):
 
     @console_ns.doc("publish_snippet_workflow")
     @console_ns.expect(console_ns.models.get(PublishWorkflowPayload.__name__))
-    @console_ns.response(200, "Workflow published successfully")
+    @console_ns.response(200, "Workflow published successfully", console_ns.models[WorkflowPublishResponse.__name__])
     @console_ns.response(400, "No draft workflow found")
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet):
+    def post(self, current_user: Account, snippet: CustomizedSnippet):
         """Publish snippet workflow."""
-        current_user, _ = current_account_with_tenant()
         snippet_service = _snippet_service()
 
         with Session(db.engine) as session:
@@ -268,7 +291,11 @@ class SnippetPublishedWorkflowApi(Resource):
 @console_ns.route("/snippets/<uuid:snippet_id>/workflows/default-workflow-block-configs")
 class SnippetDefaultBlockConfigsApi(Resource):
     @console_ns.doc("get_snippet_default_block_configs")
-    @console_ns.response(200, "Default block configs retrieved successfully")
+    @console_ns.response(
+        200,
+        "Default block configs retrieved successfully",
+        console_ns.models[DefaultBlockConfigsResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -282,7 +309,7 @@ class SnippetDefaultBlockConfigsApi(Resource):
 
 @console_ns.route("/snippets/<uuid:snippet_id>/workflows")
 class SnippetPublishedAllWorkflowApi(Resource):
-    @console_ns.expect(console_ns.models[SnippetWorkflowListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(SnippetWorkflowListQuery))
     @console_ns.doc("get_all_snippet_published_workflows")
     @console_ns.doc(description="Get all published workflows for a snippet")
     @console_ns.doc(params={"snippet_id": "Snippet ID"})
@@ -325,17 +352,17 @@ class SnippetDraftWorkflowRestoreApi(Resource):
     @console_ns.doc("restore_snippet_workflow_to_draft")
     @console_ns.doc(description="Restore a published snippet workflow version into the draft workflow")
     @console_ns.doc(params={"snippet_id": "Snippet ID", "workflow_id": "Published workflow ID"})
-    @console_ns.response(200, "Workflow restored successfully")
+    @console_ns.response(200, "Workflow restored successfully", console_ns.models[WorkflowRestoreResponse.__name__])
     @console_ns.response(400, "Source workflow must be published")
     @console_ns.response(404, "Workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet, workflow_id: str):
+    def post(self, current_user: Account, snippet: CustomizedSnippet, workflow_id: str):
         """Restore a published snippet workflow version into the draft workflow."""
-        current_user, _ = current_account_with_tenant()
         snippet_service = _snippet_service()
 
         try:
@@ -361,6 +388,7 @@ class SnippetDraftWorkflowRestoreApi(Resource):
 @console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs")
 class SnippetWorkflowRunsApi(Resource):
     @console_ns.doc("list_snippet_workflow_runs")
+    @console_ns.doc(params=query_params_from_model(WorkflowRunQuery))
     @console_ns.response(
         200,
         "Workflow runs retrieved successfully",
@@ -455,16 +483,16 @@ class SnippetDraftNodeRunApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet, node_id: str):
+    def post(self, current_user: Account, snippet: CustomizedSnippet, node_id: str):
         """
         Run a single node in snippet draft workflow.
 
         Executes a specific node with provided inputs for single-step debugging.
         Returns the node execution result including status, outputs, and timing.
         """
-        current_user, _ = current_account_with_tenant()
         payload = SnippetDraftNodeRunPayload.model_validate(console_ns.payload or {})
 
         user_inputs = payload.inputs
@@ -534,21 +562,25 @@ class SnippetDraftRunIterationNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow iteration node for snippet")
     @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models.get(SnippetIterationNodeRunPayload.__name__))
-    @console_ns.response(200, "Iteration node run started successfully (SSE stream)")
+    @console_ns.response(
+        200,
+        "Iteration node run started successfully (SSE stream)",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(404, "Snippet or draft workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet, node_id: str):
+    def post(self, current_user: Account, snippet: CustomizedSnippet, node_id: str):
         """
         Run a draft workflow iteration node for snippet.
 
         Iteration nodes execute their internal sub-graph multiple times over an input list.
         Returns an SSE event stream with iteration progress and results.
         """
-        current_user, _ = current_account_with_tenant()
         args = SnippetIterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
 
         try:
@@ -575,21 +607,25 @@ class SnippetDraftRunLoopNodeApi(Resource):
     @console_ns.doc(description="Run draft workflow loop node for snippet")
     @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
     @console_ns.expect(console_ns.models.get(SnippetLoopNodeRunPayload.__name__))
-    @console_ns.response(200, "Loop node run started successfully (SSE stream)")
+    @console_ns.response(
+        200,
+        "Loop node run started successfully (SSE stream)",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(404, "Snippet or draft workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet, node_id: str):
+    def post(self, current_user: Account, snippet: CustomizedSnippet, node_id: str):
         """
         Run a draft workflow loop node for snippet.
 
         Loop nodes execute their internal sub-graph repeatedly until a condition is met.
         Returns an SSE event stream with loop progress and results.
         """
-        current_user, _ = current_account_with_tenant()
         args = SnippetLoopNodeRunPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -614,22 +650,25 @@ class SnippetDraftRunLoopNodeApi(Resource):
 class SnippetDraftWorkflowRunApi(Resource):
     @console_ns.doc("run_snippet_draft_workflow")
     @console_ns.expect(console_ns.models.get(SnippetDraftRunPayload.__name__))
-    @console_ns.response(200, "Draft workflow run started successfully (SSE stream)")
+    @console_ns.response(
+        200,
+        "Draft workflow run started successfully (SSE stream)",
+        console_ns.models[GeneratedAppResponse.__name__],
+    )
     @console_ns.response(404, "Snippet or draft workflow not found")
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @get_snippet
     @edit_permission_required
-    def post(self, snippet: CustomizedSnippet):
+    def post(self, current_user: Account, snippet: CustomizedSnippet):
         """
         Run draft workflow for snippet.
 
         Executes the snippet's draft workflow with the provided inputs
         and returns an SSE event stream with execution progress and results.
         """
-        current_user, _ = current_account_with_tenant()
-
         payload = SnippetDraftRunPayload.model_validate(console_ns.payload or {})
         args = payload.model_dump(exclude_none=True)
 
@@ -654,7 +693,7 @@ class SnippetDraftWorkflowRunApi(Resource):
 @console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/tasks/<string:task_id>/stop")
 class SnippetWorkflowTaskStopApi(Resource):
     @console_ns.doc("stop_snippet_workflow_task")
-    @console_ns.response(200, "Task stopped successfully")
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(404, "Snippet not found")
     @setup_required
     @login_required

api/controllers/console/snippets/snippet_workflow_draft_variable.py

@@ -18,9 +18,12 @@ from flask import Response, request
 from flask_restx import Resource, marshal, marshal_with
 from sqlalchemy.orm import Session, sessionmaker
 
+from controllers.common.errors import InvalidArgumentError, NotFoundError
+from controllers.common.schema import query_params_from_model
 from controllers.console import console_ns
 from controllers.console.app.error import DraftWorkflowNotExist
 from controllers.console.app.workflow_draft_variable import (
+    EnvironmentVariableListResponse,
     WorkflowDraftVariableListQuery,
     WorkflowDraftVariableUpdatePayload,
     ensure_variable_access,
@@ -36,7 +39,6 @@ from controllers.console.wraps import (
     setup_required,
     with_current_user,
 )
-from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
@@ -90,7 +92,7 @@ def _snippet_draft_var_prerequisite[T, **P, R](
 
 @console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/variables")
 class SnippetWorkflowVariableCollectionApi(Resource):
-    @console_ns.expect(console_ns.models[WorkflowDraftVariableListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(WorkflowDraftVariableListQuery))
     @console_ns.doc("get_snippet_workflow_variables")
     @console_ns.doc(description="List draft workflow variables without values (paginated, snippet scope)")
     @console_ns.response(
@@ -305,7 +307,11 @@ class SnippetSystemVariableCollectionApi(Resource):
 class SnippetEnvironmentVariableCollectionApi(Resource):
     @console_ns.doc("get_snippet_environment_variables")
     @console_ns.doc(description="Get environment variables from snippet draft workflow graph")
-    @console_ns.response(200, "Environment variables retrieved successfully")
+    @console_ns.response(
+        200,
+        "Environment variables retrieved successfully",
+        console_ns.models[EnvironmentVariableListResponse.__name__],
+    )
     @console_ns.response(404, "Draft workflow not found")
     @_snippet_draft_var_prerequisite
     def get(self, _current_user: Account, snippet: CustomizedSnippet) -> dict[str, list[dict[str, Any]]]:

api/controllers/console/spec.py

@@ -1,7 +1,10 @@
 import logging
+from typing import Any
 
 from flask_restx import Resource
+from pydantic import RootModel
 
+from controllers.common.schema import register_response_schema_models
 from controllers.console.wraps import (
     account_initialization_required,
     setup_required,
@@ -14,8 +17,16 @@ from . import console_ns
 logger = logging.getLogger(__name__)
 
 
+class SchemaDefinitionsResponse(RootModel[Any]):
+    root: Any
+
+
+register_response_schema_models(console_ns, SchemaDefinitionsResponse)
+
+
 @console_ns.route("/spec/schema-definitions")
 class SpecSchemaDefinitionsApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[SchemaDefinitionsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/tag/tags.py

@@ -7,7 +7,7 @@ from pydantic import BaseModel, Field, field_validator
 from werkzeug.exceptions import Forbidden
 
 from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -95,12 +95,7 @@ class TagListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @console_ns.doc(
-        params={
-            "type": 'Tag type filter. Can be "knowledge", "app", or "snippet".',
-            "keyword": "Search keyword for tag name.",
-        }
-    )
+    @console_ns.doc(params=query_params_from_model(TagListQueryParam))
     @console_ns.doc(responses={200: ("Success", [console_ns.models[TagResponse.__name__]])})
     @with_current_tenant_id
     def get(self, current_tenant_id: str):

api/controllers/console/workspace/account.py

@@ -6,7 +6,7 @@ from typing import Any, Literal
 import pytz
 from flask import request
 from flask_restx import Resource
-from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import BaseModel, Field, RootModel, field_validator, model_validator
 from sqlalchemy import select
 from werkzeug.exceptions import NotFound
 
@@ -236,6 +236,10 @@ class EducationAutocompleteResponse(ResponseModel):
     has_next: bool | None = None
 
 
+class EducationActivateResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
 register_schema_models(
     console_ns,
     AccountIntegrateResponse,
@@ -248,6 +252,7 @@ register_response_schema_models(
     console_ns,
     AccountResponse,
     AvatarUrlResponse,
+    EducationActivateResponse,
     SimpleResultDataResponse,
     SimpleResultResponse,
     VerificationTokenResponse,
@@ -556,6 +561,7 @@ class EducationVerifyApi(Resource):
 @console_ns.route("/account/education")
 class EducationApi(Resource):
     @console_ns.expect(console_ns.models[EducationActivatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[EducationActivateResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -585,7 +591,7 @@ class EducationApi(Resource):
 
 @console_ns.route("/account/education/autocomplete")
 class EducationAutoCompleteApi(Resource):
-    @console_ns.expect(console_ns.models[EducationAutocompleteQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(EducationAutocompleteQuery))
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/workspace/agent_providers.py

@@ -1,5 +1,9 @@
-from flask_restx import Resource, fields
+from typing import Any
 
+from flask_restx import Resource
+from pydantic import RootModel
+
+from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -13,6 +17,17 @@ from models import Account
 from services.agent_service import AgentService
 
 
+class AgentProviderListResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
+class AgentProviderResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+register_response_schema_models(console_ns, AgentProviderListResponse, AgentProviderResponse)
+
+
 @console_ns.route("/workspaces/current/agent-providers")
 class AgentProviderListApi(Resource):
     @console_ns.doc("list_agent_providers")
@@ -20,7 +35,7 @@ class AgentProviderListApi(Resource):
     @console_ns.response(
         200,
         "Success",
-        fields.List(fields.Raw(description="Agent provider information")),
+        console_ns.models[AgentProviderListResponse.__name__],
     )
     @setup_required
     @login_required
@@ -39,7 +54,7 @@ class AgentProviderApi(Resource):
     @console_ns.response(
         200,
         "Success",
-        fields.Raw(description="Agent provider details"),
+        console_ns.models[AgentProviderResponse.__name__],
     )
     @setup_required
     @login_required

api/controllers/console/workspace/endpoint.py

@@ -12,7 +12,7 @@ from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -61,11 +61,15 @@ class EndpointCreateResponse(BaseModel):
 
 
 class EndpointListResponse(BaseModel):
-    endpoints: list[dict[str, Any]] = Field(description="Endpoint information")
+    endpoints: list[dict[str, Any]] = Field(
+        description="Endpoint information",
+    )
 
 
 class PluginEndpointListResponse(BaseModel):
-    endpoints: list[dict[str, Any]] = Field(description="Endpoint information")
+    endpoints: list[dict[str, Any]] = Field(
+        description="Endpoint information",
+    )
 
 
 class EndpointDeleteResponse(BaseModel):
@@ -201,7 +205,7 @@ class DeprecatedEndpointCreateApi(Resource):
 class EndpointListApi(Resource):
     @console_ns.doc("list_endpoints")
     @console_ns.doc(description="List plugin endpoints with pagination")
-    @console_ns.expect(console_ns.models[EndpointListQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(EndpointListQuery))
     @console_ns.response(
         200,
         "Success",
@@ -234,7 +238,7 @@ class EndpointListApi(Resource):
 class EndpointListForSinglePluginApi(Resource):
     @console_ns.doc("list_plugin_endpoints")
     @console_ns.doc(description="List endpoints for a specific plugin")
-    @console_ns.expect(console_ns.models[EndpointListForPluginQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(EndpointListForPluginQuery))
     @console_ns.response(
         200,
         "Success",

api/controllers/console/workspace/load_balancing_config.py

@@ -2,7 +2,7 @@ from flask_restx import Resource
 from pydantic import BaseModel
 from werkzeug.exceptions import Forbidden
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -10,6 +10,7 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from fields.base import ResponseModel
 from graphon.model_runtime.entities.model_entities import ModelType
 from graphon.model_runtime.errors.validate import CredentialsValidateFailedError
 from libs.login import login_required
@@ -23,7 +24,13 @@ class LoadBalancingCredentialPayload(BaseModel):
     credentials: dict[str, object]
 
 
+class LoadBalancingCredentialValidateResponse(ResponseModel):
+    result: str
+    error: str | None = None
+
+
 register_schema_models(console_ns, LoadBalancingCredentialPayload)
+register_response_schema_models(console_ns, LoadBalancingCredentialValidateResponse)
 
 
 @console_ns.route(
@@ -31,6 +38,11 @@ register_schema_models(console_ns, LoadBalancingCredentialPayload)
 )
 class LoadBalancingCredentialsValidateApi(Resource):
     @console_ns.expect(console_ns.models[LoadBalancingCredentialPayload.__name__])
+    @console_ns.response(
+        200,
+        "Credential validation result",
+        console_ns.models[LoadBalancingCredentialValidateResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -75,6 +87,11 @@ class LoadBalancingCredentialsValidateApi(Resource):
 )
 class LoadBalancingConfigCredentialsValidateApi(Resource):
     @console_ns.expect(console_ns.models[LoadBalancingCredentialPayload.__name__])
+    @console_ns.response(
+        200,
+        "Credential validation result",
+        console_ns.models[LoadBalancingCredentialValidateResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/workspace/members.py

@@ -8,7 +8,7 @@ from sqlalchemy import func, select
 
 import services
 from configs import dify_config
-from controllers.common.fields import SimpleResultDataResponse, VerificationTokenResponse
+from controllers.common.fields import SimpleResultDataResponse, SimpleResultResponse, VerificationTokenResponse
 from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.auth.error import (
@@ -29,6 +29,7 @@ from controllers.console.wraps import (
 )
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
+from fields.base import ResponseModel
 from fields.member_fields import AccountWithRole, AccountWithRoleList
 from libs.helper import extract_remote_ip
 from libs.login import login_required
@@ -61,6 +62,24 @@ class OwnerTransferPayload(BaseModel):
     token: str
 
 
+class MemberInviteResultResponse(ResponseModel):
+    status: str
+    email: str
+    url: str | None = None
+    message: str | None = None
+
+
+class MemberInviteResponse(ResponseModel):
+    result: str
+    invitation_results: list[MemberInviteResultResponse]
+    tenant_id: str
+
+
+class MemberActionTenantResponse(ResponseModel):
+    result: str
+    tenant_id: str
+
+
 register_enum_models(console_ns, TenantAccountRole)
 register_schema_models(
     console_ns,
@@ -72,7 +91,14 @@ register_schema_models(
     OwnerTransferCheckPayload,
     OwnerTransferPayload,
 )
-register_response_schema_models(console_ns, SimpleResultDataResponse, VerificationTokenResponse)
+register_response_schema_models(
+    console_ns,
+    SimpleResultDataResponse,
+    SimpleResultResponse,
+    VerificationTokenResponse,
+    MemberInviteResponse,
+    MemberActionTenantResponse,
+)
 
 
 def _is_role_enabled(role: TenantAccountRole | str, tenant_id: str) -> bool:
@@ -152,6 +178,7 @@ class MemberInviteEmailApi(Resource):
     """Invite a new member by email."""
 
     @console_ns.expect(console_ns.models[MemberInvitePayload.__name__])
+    @console_ns.response(201, "Success", console_ns.models[MemberInviteResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -221,6 +248,7 @@ class MemberInviteEmailApi(Resource):
 class MemberCancelInviteApi(Resource):
     """Cancel an invitation by member id."""
 
+    @console_ns.response(200, "Success", console_ns.models[MemberActionTenantResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -254,6 +282,7 @@ class MemberUpdateRoleApi(Resource):
     """Update member role."""
 
     @console_ns.expect(console_ns.models[MemberRoleUpdatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -396,6 +425,7 @@ class OwnerTransferCheckApi(Resource):
 @console_ns.route("/workspaces/current/members/<uuid:member_id>/owner-transfer")
 class OwnerTransfer(Resource):
     @console_ns.expect(console_ns.models[OwnerTransferPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/workspace/model_providers.py

@@ -5,8 +5,8 @@ from flask import request, send_file
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
-from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import BinaryFileResponse, SimpleResultResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -15,6 +15,7 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
+from fields.base import ResponseModel
 from graphon.model_runtime.entities.model_entities import ModelType
 from graphon.model_runtime.errors.validate import CredentialsValidateFailedError
 from graphon.model_runtime.utils.encoders import jsonable_encoder
@@ -22,6 +23,7 @@ from libs.helper import uuid_value
 from libs.login import login_required
 from models import Account
 from services.billing_service import BillingService
+from services.entities.model_provider_entities import ProviderResponse
 from services.model_provider_service import ModelProviderService
 
 
@@ -82,6 +84,23 @@ class ParserPreferredProviderType(BaseModel):
     preferred_provider_type: Literal["system", "custom"]
 
 
+class ModelProviderListResponse(ResponseModel):
+    data: list[ProviderResponse]
+
+
+class ProviderCredentialResponse(ResponseModel):
+    credentials: dict[str, Any] | None = Field(default=None)
+
+
+class ProviderCredentialValidateResponse(ResponseModel):
+    result: Literal["success", "error"]
+    error: str | None = None
+
+
+class ModelProviderPaymentCheckoutUrlResponse(ResponseModel):
+    payment_link: str
+
+
 register_schema_models(
     console_ns,
     ParserModelList,
@@ -93,12 +112,21 @@ register_schema_models(
     ParserCredentialValidate,
     ParserPreferredProviderType,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    BinaryFileResponse,
+    SimpleResultResponse,
+    ModelProviderListResponse,
+    ModelProviderPaymentCheckoutUrlResponse,
+    ProviderCredentialResponse,
+    ProviderCredentialValidateResponse,
+)
 
 
 @console_ns.route("/workspaces/current/model-providers")
 class ModelProviderListApi(Resource):
-    @console_ns.expect(console_ns.models[ParserModelList.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserModelList))
+    @console_ns.response(200, "Success", console_ns.models[ModelProviderListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -115,7 +143,8 @@ class ModelProviderListApi(Resource):
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/credentials")
 class ModelProviderCredentialApi(Resource):
-    @console_ns.expect(console_ns.models[ParserCredentialId.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserCredentialId))
+    @console_ns.response(200, "Success", console_ns.models[ProviderCredentialResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -133,6 +162,7 @@ class ModelProviderCredentialApi(Resource):
         return {"credentials": credentials}
 
     @console_ns.expect(console_ns.models[ParserCredentialCreate.__name__])
+    @console_ns.response(201, "Credential created successfully", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
@@ -157,6 +187,7 @@ class ModelProviderCredentialApi(Resource):
         return {"result": "success"}, 201
 
     @console_ns.expect(console_ns.models[ParserCredentialUpdate.__name__])
+    @console_ns.response(200, "Credential updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
@@ -225,6 +256,11 @@ class ModelProviderCredentialSwitchApi(Resource):
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/credentials/validate")
 class ModelProviderValidateApi(Resource):
     @console_ns.expect(console_ns.models[ParserCredentialValidate.__name__])
+    @console_ns.response(
+        200,
+        "Credential validation result",
+        console_ns.models[ProviderCredentialValidateResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -262,6 +298,7 @@ class ModelProviderIconApi(Resource):
     Get model provider icon
     """
 
+    @console_ns.response(200, "Success", console_ns.models[BinaryFileResponse.__name__])
     def get(self, tenant_id: str, provider: str, icon_type: str, lang: str):
         model_provider_service = ModelProviderService()
         icon, mimetype = model_provider_service.get_model_provider_icon(
@@ -298,6 +335,7 @@ class PreferredProviderTypeUpdateApi(Resource):
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/checkout-url")
 class ModelProviderPaymentCheckoutUrlApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ModelProviderPaymentCheckoutUrlResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/workspace/models.py

@@ -6,7 +6,12 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
 
 from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
+from controllers.common.schema import (
+    query_params_from_model,
+    register_enum_models,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
@@ -15,12 +20,19 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from graphon.model_runtime.entities.model_entities import ModelType
+from core.entities.provider_entities import CredentialConfiguration
+from fields.base import ResponseModel
+from graphon.model_runtime.entities.model_entities import ModelType, ParameterRule
 from graphon.model_runtime.errors.validate import CredentialsValidateFailedError
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.helper import uuid_value
 from libs.login import login_required
 from models import Account
+from services.entities.model_provider_entities import (
+    DefaultModelResponse,
+    ModelWithProviderEntityResponse,
+    ProviderWithModelsResponse,
+)
 from services.model_load_balancing_service import ModelLoadBalancingService
 from services.model_provider_service import ModelProviderService
 
@@ -47,7 +59,7 @@ class ParserDeleteModels(BaseModel):
 
 
 class LoadBalancingPayload(BaseModel):
-    configs: list[dict[str, Any]] | None = None
+    configs: list[dict[str, Any]] | None = Field(default=None)
     enabled: bool | None = None
 
 
@@ -120,6 +132,40 @@ class ParserSwitch(BaseModel):
     credential_id: str
 
 
+class DefaultModelDataResponse(ResponseModel):
+    data: DefaultModelResponse | None = None
+
+
+class ModelWithProviderListResponse(ResponseModel):
+    data: list[ModelWithProviderEntityResponse]
+
+
+class ProviderWithModelsDataResponse(ResponseModel):
+    data: list[ProviderWithModelsResponse]
+
+
+class ModelCredentialLoadBalancingResponse(ResponseModel):
+    enabled: bool
+    configs: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class ModelCredentialResponse(ResponseModel):
+    credentials: dict[str, Any] = Field(default_factory=dict)
+    current_credential_id: str | None = None
+    current_credential_name: str | None = None
+    load_balancing: ModelCredentialLoadBalancingResponse
+    available_credentials: list[CredentialConfiguration]
+
+
+class ModelCredentialValidateResponse(ResponseModel):
+    result: str
+    error: str | None = None
+
+
+class ModelParameterRulesResponse(ResponseModel):
+    data: list[ParameterRule]
+
+
 register_schema_models(
     console_ns,
     ParserGetDefault,
@@ -134,14 +180,24 @@ register_schema_models(
     Inner,
     ParserSwitch,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    SimpleResultResponse,
+    DefaultModelDataResponse,
+    ModelWithProviderListResponse,
+    ProviderWithModelsDataResponse,
+    ModelCredentialResponse,
+    ModelCredentialValidateResponse,
+    ModelParameterRulesResponse,
+)
 
 register_enum_models(console_ns, ModelType)
 
 
 @console_ns.route("/workspaces/current/default-model")
 class DefaultModelApi(Resource):
-    @console_ns.expect(console_ns.models[ParserGetDefault.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserGetDefault))
+    @console_ns.response(200, "Success", console_ns.models[DefaultModelDataResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -191,6 +247,7 @@ class DefaultModelApi(Resource):
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/models")
 class ModelProviderModelApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ModelWithProviderListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -202,6 +259,7 @@ class ModelProviderModelApi(Resource):
         return jsonable_encoder({"data": models})
 
     @console_ns.expect(console_ns.models[ParserPostModels.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
@@ -267,7 +325,8 @@ class ModelProviderModelApi(Resource):
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/models/credentials")
 class ModelProviderModelCredentialApi(Resource):
-    @console_ns.expect(console_ns.models[ParserGetCredentials.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserGetCredentials))
+    @console_ns.response(200, "Success", console_ns.models[ModelCredentialResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -326,6 +385,7 @@ class ModelProviderModelCredentialApi(Resource):
         )
 
     @console_ns.expect(console_ns.models[ParserCreateCredential.__name__])
+    @console_ns.response(201, "Credential created successfully", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
@@ -357,6 +417,7 @@ class ModelProviderModelCredentialApi(Resource):
         return {"result": "success"}, 201
 
     @console_ns.expect(console_ns.models[ParserUpdateCredential.__name__])
+    @console_ns.response(200, "Credential updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
@@ -481,6 +542,11 @@ register_schema_models(console_ns, ParserSwitch, ParserValidate)
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/models/credentials/validate")
 class ModelProviderModelValidateApi(Resource):
     @console_ns.expect(console_ns.models[ParserValidate.__name__])
+    @console_ns.response(
+        200,
+        "Credential validation result",
+        console_ns.models[ModelCredentialValidateResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required
@@ -515,7 +581,8 @@ class ModelProviderModelValidateApi(Resource):
 
 @console_ns.route("/workspaces/current/model-providers/<path:provider>/models/parameter-rules")
 class ModelProviderModelParameterRuleApi(Resource):
-    @console_ns.expect(console_ns.models[ParserParameter.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserParameter))
+    @console_ns.response(200, "Success", console_ns.models[ModelParameterRulesResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -533,6 +600,7 @@ class ModelProviderModelParameterRuleApi(Resource):
 
 @console_ns.route("/workspaces/current/models/model-types/<string:model_type>")
 class ModelProviderAvailableModelApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ProviderWithModelsDataResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/workspace/plugin.py

@@ -4,22 +4,34 @@ from typing import Any, Literal
 
 from flask import request, send_file
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from werkzeug.datastructures import FileStorage
 from werkzeug.exceptions import Forbidden
 
 from configs import dify_config
-from controllers.common.fields import SuccessResponse
-from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
+from controllers.common.fields import BinaryFileResponse, SuccessResponse
+from controllers.common.schema import (
+    query_params_from_model,
+    register_enum_models,
+    register_response_schema_models,
+    register_schema_models,
+)
 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 controllers.console.wraps import (
+    account_initialization_required,
+    is_admin_or_owner_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+    with_current_user_id,
+)
 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
-from models.account import TenantPluginAutoUpgradeStrategy, TenantPluginPermission
+from libs.login import login_required
+from models.account import Account, TenantPluginAutoUpgradeStrategy, TenantPluginPermission
 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
@@ -145,6 +157,58 @@ class PluginDebuggingKeyResponse(ResponseModel):
     port: int
 
 
+class PluginDaemonOperationResponse(RootModel[Any]):
+    root: Any
+
+
+class PluginListResponse(ResponseModel):
+    plugins: Any
+    total: int
+
+
+class PluginVersionsResponse(ResponseModel):
+    versions: Any
+
+
+class PluginInstallationsResponse(ResponseModel):
+    plugins: Any
+
+
+class PluginManifestResponse(ResponseModel):
+    manifest: Any
+
+
+class PluginTasksResponse(ResponseModel):
+    tasks: Any
+
+
+class PluginTaskResponse(ResponseModel):
+    task: Any
+
+
+class PluginPermissionResponse(ResponseModel):
+    install_permission: TenantPluginPermission.InstallPermission
+    debug_permission: TenantPluginPermission.DebugPermission
+
+
+class PluginDynamicOptionsResponse(ResponseModel):
+    options: Any
+
+
+class PluginOperationSuccessResponse(ResponseModel):
+    success: bool
+    message: str | None = None
+
+
+class PluginPreferencesResponse(ResponseModel):
+    permission: PluginPermissionSettingsPayload
+    auto_upgrade: PluginAutoUpgradeSettingsPayload
+
+
+class PluginReadmeResponse(ResponseModel):
+    readme: str
+
+
 register_schema_models(
     console_ns,
     ParserList,
@@ -168,7 +232,24 @@ register_schema_models(
     ParserExcludePlugin,
     ParserReadme,
 )
-register_response_schema_models(console_ns, PluginDebuggingKeyResponse, SuccessResponse)
+register_response_schema_models(
+    console_ns,
+    BinaryFileResponse,
+    PluginDaemonOperationResponse,
+    PluginDebuggingKeyResponse,
+    PluginDynamicOptionsResponse,
+    PluginInstallationsResponse,
+    PluginListResponse,
+    PluginManifestResponse,
+    PluginOperationSuccessResponse,
+    PluginPermissionResponse,
+    PluginPreferencesResponse,
+    PluginReadmeResponse,
+    PluginTaskResponse,
+    PluginTasksResponse,
+    PluginVersionsResponse,
+    SuccessResponse,
+)
 
 register_enum_models(
     console_ns,
@@ -200,9 +281,8 @@ class PluginDebuggingKeyApi(Resource):
     @login_required
     @account_initialization_required
     @plugin_permission_required(debug_required=True)
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         try:
             return {
                 "key": PluginService.get_debugging_key(tenant_id),
@@ -215,15 +295,17 @@ class PluginDebuggingKeyApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/list")
 class PluginListApi(Resource):
-    @console_ns.expect(console_ns.models[ParserList.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserList))
+    @console_ns.response(200, "Success", console_ns.models[PluginListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user_id: str):
         args = ParserList.model_validate(request.args.to_dict(flat=True))
         try:
-            plugins_with_total = PluginService.list_with_total(tenant_id, args.page, args.page_size)
+            plugins_with_total = PluginService.list_with_total(tenant_id, user_id, args.page, args.page_size)
         except PluginDaemonClientSideError as e:
             return {"code": "plugin_error", "message": e.description}, 400
 
@@ -233,6 +315,7 @@ class PluginListApi(Resource):
 @console_ns.route("/workspaces/current/plugin/list/latest-versions")
 class PluginListLatestVersionsApi(Resource):
     @console_ns.expect(console_ns.models[ParserLatest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginVersionsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -250,12 +333,12 @@ class PluginListLatestVersionsApi(Resource):
 @console_ns.route("/workspaces/current/plugin/list/installations/ids")
 class PluginListInstallationsFromIdsApi(Resource):
     @console_ns.expect(console_ns.models[ParserLatest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginInstallationsResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserLatest.model_validate(console_ns.payload)
 
         try:
@@ -268,7 +351,8 @@ class PluginListInstallationsFromIdsApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/icon")
 class PluginIconApi(Resource):
-    @console_ns.expect(console_ns.models[ParserIcon.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserIcon))
+    @console_ns.response(200, "Success", console_ns.models[BinaryFileResponse.__name__])
     @setup_required
     def get(self):
         args = ParserIcon.model_validate(request.args.to_dict(flat=True))
@@ -284,14 +368,15 @@ class PluginIconApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/asset")
 class PluginAssetApi(Resource):
-    @console_ns.expect(console_ns.models[ParserAsset.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserAsset))
+    @console_ns.response(200, "Success", console_ns.models[BinaryFileResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         args = ParserAsset.model_validate(request.args.to_dict(flat=True))
 
-        _, tenant_id = current_account_with_tenant()
         try:
             binary = PluginService.extract_asset(tenant_id, args.plugin_unique_identifier, args.file_name)
             return send_file(io.BytesIO(binary), mimetype="application/octet-stream")
@@ -301,13 +386,13 @@ class PluginAssetApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/upload/pkg")
 class PluginUploadFromPkgApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         file = request.files["pkg"]
         content = _read_upload_content(file, dify_config.PLUGIN_MAX_PACKAGE_SIZE)
         try:
@@ -321,13 +406,13 @@ class PluginUploadFromPkgApi(Resource):
 @console_ns.route("/workspaces/current/plugin/upload/github")
 class PluginUploadFromGithubApi(Resource):
     @console_ns.expect(console_ns.models[ParserGithubUpload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserGithubUpload.model_validate(console_ns.payload)
 
         try:
@@ -340,13 +425,13 @@ class PluginUploadFromGithubApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/upload/bundle")
 class PluginUploadFromBundleApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         file = request.files["bundle"]
         content = _read_upload_content(file, dify_config.PLUGIN_MAX_BUNDLE_SIZE)
         try:
@@ -360,12 +445,13 @@ class PluginUploadFromBundleApi(Resource):
 @console_ns.route("/workspaces/current/plugin/install/pkg")
 class PluginInstallFromPkgApi(Resource):
     @console_ns.expect(console_ns.models[ParserPluginIdentifiers.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserPluginIdentifiers.model_validate(console_ns.payload)
 
         try:
@@ -379,13 +465,13 @@ class PluginInstallFromPkgApi(Resource):
 @console_ns.route("/workspaces/current/plugin/install/github")
 class PluginInstallFromGithubApi(Resource):
     @console_ns.expect(console_ns.models[ParserGithubInstall.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserGithubInstall.model_validate(console_ns.payload)
 
         try:
@@ -405,13 +491,13 @@ class PluginInstallFromGithubApi(Resource):
 @console_ns.route("/workspaces/current/plugin/install/marketplace")
 class PluginInstallFromMarketplaceApi(Resource):
     @console_ns.expect(console_ns.models[ParserPluginIdentifiers.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserPluginIdentifiers.model_validate(console_ns.payload)
 
         try:
@@ -424,13 +510,14 @@ class PluginInstallFromMarketplaceApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/marketplace/pkg")
 class PluginFetchMarketplacePkgApi(Resource):
-    @console_ns.expect(console_ns.models[ParserPluginIdentifierQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserPluginIdentifierQuery))
+    @console_ns.response(200, "Success", console_ns.models[PluginManifestResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         args = ParserPluginIdentifierQuery.model_validate(request.args.to_dict(flat=True))
 
         try:
@@ -448,14 +535,14 @@ class PluginFetchMarketplacePkgApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/fetch-manifest")
 class PluginFetchManifestApi(Resource):
-    @console_ns.expect(console_ns.models[ParserPluginIdentifierQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserPluginIdentifierQuery))
+    @console_ns.response(200, "Success", console_ns.models[PluginManifestResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         args = ParserPluginIdentifierQuery.model_validate(request.args.to_dict(flat=True))
 
         try:
@@ -468,14 +555,14 @@ class PluginFetchManifestApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/tasks")
 class PluginFetchInstallTasksApi(Resource):
-    @console_ns.expect(console_ns.models[ParserTasks.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserTasks))
+    @console_ns.response(200, "Success", console_ns.models[PluginTasksResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         args = ParserTasks.model_validate(request.args.to_dict(flat=True))
 
         try:
@@ -486,13 +573,13 @@ class PluginFetchInstallTasksApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/tasks/<task_id>")
 class PluginFetchInstallTaskApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[PluginTaskResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def get(self, task_id: str):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str, task_id: str):
         try:
             return jsonable_encoder({"task": PluginService.fetch_install_task(tenant_id, task_id)})
         except PluginDaemonClientSideError as e:
@@ -506,9 +593,8 @@ class PluginDeleteInstallTaskApi(Resource):
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self, task_id: str):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str, task_id: str):
         try:
             return {"success": PluginService.delete_install_task(tenant_id, task_id)}
         except PluginDaemonClientSideError as e:
@@ -522,9 +608,8 @@ class PluginDeleteAllInstallTaskItemsApi(Resource):
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         try:
             return {"success": PluginService.delete_all_install_task_items(tenant_id)}
         except PluginDaemonClientSideError as e:
@@ -538,9 +623,8 @@ class PluginDeleteInstallTaskItemApi(Resource):
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self, task_id: str, identifier: str):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str, task_id: str, identifier: str):
         try:
             return {"success": PluginService.delete_install_task_item(tenant_id, task_id, identifier)}
         except PluginDaemonClientSideError as e:
@@ -550,13 +634,13 @@ class PluginDeleteInstallTaskItemApi(Resource):
 @console_ns.route("/workspaces/current/plugin/upgrade/marketplace")
 class PluginUpgradeFromMarketplaceApi(Resource):
     @console_ns.expect(console_ns.models[ParserMarketplaceUpgrade.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserMarketplaceUpgrade.model_validate(console_ns.payload)
 
         try:
@@ -572,13 +656,13 @@ class PluginUpgradeFromMarketplaceApi(Resource):
 @console_ns.route("/workspaces/current/plugin/upgrade/github")
 class PluginUpgradeFromGithubApi(Resource):
     @console_ns.expect(console_ns.models[ParserGithubUpgrade.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDaemonOperationResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserGithubUpgrade.model_validate(console_ns.payload)
 
         try:
@@ -604,11 +688,10 @@ class PluginUninstallApi(Resource):
     @login_required
     @account_initialization_required
     @plugin_permission_required(install_required=True)
-    def post(self):
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         args = ParserUninstall.model_validate(console_ns.payload)
 
-        _, tenant_id = current_account_with_tenant()
-
         try:
             return {"success": PluginService.uninstall(tenant_id, args.plugin_installation_id)}
         except PluginDaemonClientSideError as e:
@@ -622,16 +705,14 @@ class PluginChangePermissionApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
-        current_user, current_tenant_id = current_account_with_tenant()
-        user = current_user
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         if not user.is_admin_or_owner:
             raise Forbidden()
 
         args = ParserPermissionChange.model_validate(console_ns.payload)
 
-        tenant_id = current_tenant_id
-
         return {
             "success": PluginPermissionService.change_permission(
                 tenant_id, args.install_permission, args.debug_permission
@@ -641,12 +722,12 @@ class PluginChangePermissionApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/permission/fetch")
 class PluginFetchPermissionApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[PluginPermissionResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         permission = PluginPermissionService.get_permission(tenant_id)
         if not permission:
             return jsonable_encoder(
@@ -666,21 +747,21 @@ class PluginFetchPermissionApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/parameters/dynamic-options")
 class PluginFetchDynamicSelectOptionsApi(Resource):
-    @console_ns.expect(console_ns.models[ParserDynamicOptions.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserDynamicOptions))
+    @console_ns.response(200, "Success", console_ns.models[PluginDynamicOptionsResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def get(self):
-        current_user, tenant_id = current_account_with_tenant()
-        user_id = current_user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user: Account):
         args = ParserDynamicOptions.model_validate(request.args.to_dict(flat=True))
 
         try:
             options = PluginParameterService.get_dynamic_select_options(
                 tenant_id=tenant_id,
-                user_id=user_id,
+                user_id=current_user.id,
                 plugin_id=args.plugin_id,
                 provider=args.provider,
                 action=args.action,
@@ -697,21 +778,21 @@ class PluginFetchDynamicSelectOptionsApi(Resource):
 @console_ns.route("/workspaces/current/plugin/parameters/dynamic-options-with-credentials")
 class PluginFetchDynamicSelectOptionsWithCredentialsApi(Resource):
     @console_ns.expect(console_ns.models[ParserDynamicOptionsWithCredentials.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginDynamicOptionsResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account):
         """Fetch dynamic options using credentials directly (for edit mode)."""
-        current_user, tenant_id = current_account_with_tenant()
-        user_id = current_user.id
-
         args = ParserDynamicOptionsWithCredentials.model_validate(console_ns.payload)
 
         try:
             options = PluginParameterService.get_dynamic_select_options_with_credentials(
                 tenant_id=tenant_id,
-                user_id=user_id,
+                user_id=current_user.id,
                 plugin_id=args.plugin_id,
                 provider=args.provider,
                 action=args.action,
@@ -728,11 +809,13 @@ class PluginFetchDynamicSelectOptionsWithCredentialsApi(Resource):
 @console_ns.route("/workspaces/current/plugin/preferences/change")
 class PluginChangePreferencesApi(Resource):
     @console_ns.expect(console_ns.models[ParserPreferencesChange.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginOperationSuccessResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         if not user.is_admin_or_owner:
             raise Forbidden()
 
@@ -777,12 +860,12 @@ class PluginChangePreferencesApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/preferences/fetch")
 class PluginFetchPreferencesApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[PluginPreferencesResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         permission = PluginPermissionService.get_permission(tenant_id)
         permission_dict = {
             "install_permission": TenantPluginPermission.InstallPermission.EVERYONE,
@@ -817,13 +900,13 @@ class PluginFetchPreferencesApi(Resource):
 @console_ns.route("/workspaces/current/plugin/preferences/autoupgrade/exclude")
 class PluginAutoUpgradeExcludePluginApi(Resource):
     @console_ns.expect(console_ns.models[ParserExcludePlugin.__name__])
+    @console_ns.response(200, "Success", console_ns.models[PluginOperationSuccessResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         # exclude one single plugin
-        _, tenant_id = current_account_with_tenant()
-
         args = ParserExcludePlugin.model_validate(console_ns.payload)
 
         return jsonable_encoder({"success": PluginAutoUpgradeService.exclude_plugin(tenant_id, args.plugin_id)})
@@ -831,12 +914,13 @@ class PluginAutoUpgradeExcludePluginApi(Resource):
 
 @console_ns.route("/workspaces/current/plugin/readme")
 class PluginReadmeApi(Resource):
-    @console_ns.expect(console_ns.models[ParserReadme.__name__])
+    @console_ns.doc(params=query_params_from_model(ParserReadme))
+    @console_ns.response(200, "Success", console_ns.models[PluginReadmeResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         args = ParserReadme.model_validate(request.args.to_dict(flat=True))
         return jsonable_encoder(
             {"readme": PluginService.fetch_plugin_readme(tenant_id, args.plugin_unique_identifier, args.language)}

api/controllers/console/workspace/snippets.py

@@ -1,14 +1,17 @@
 import logging
 import re
+from typing import Any
 from urllib.parse import quote
 
 from flask import Response, request
 from flask_restx import Resource, marshal
+from pydantic import RootModel
 from sqlalchemy.orm import Session, sessionmaker
 from werkzeug.datastructures import MultiDict
 from werkzeug.exceptions import NotFound
 
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import TextFileResponse
+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.snippets.payloads import (
     CreateSnippetPayload,
@@ -21,10 +24,14 @@ from controllers.console.wraps import (
     account_initialization_required,
     edit_permission_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from extensions.ext_database import db
+from fields.base import ResponseModel
 from fields.snippet_fields import snippet_fields, snippet_list_fields, snippet_pagination_fields
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models import Account
 from models.snippet import SnippetType
 from services.app_dsl_service import ImportStatus
 from services.snippet_dsl_service import SnippetDslService
@@ -35,6 +42,19 @@ _TAG_IDS_BRACKET_PATTERN = re.compile(r"^tag_ids\[(\d+)\]$")
 _CREATOR_IDS_BRACKET_PATTERN = re.compile(r"^creator_ids\[(\d+)\]$")
 
 
+class SnippetImportResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class SnippetDependencyCheckResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class SnippetUseCountResponse(ResponseModel):
+    result: str
+    use_count: int
+
+
 def _snippet_service() -> SnippetService:
     return SnippetService(sessionmaker(bind=db.engine, expire_on_commit=False))
 
@@ -76,6 +96,13 @@ register_schema_models(
     SnippetImportPayload,
     IncludeSecretQuery,
 )
+register_response_schema_models(
+    console_ns,
+    TextFileResponse,
+    SnippetImportResponse,
+    SnippetDependencyCheckResponse,
+    SnippetUseCountResponse,
+)
 
 # Create namespace models for marshaling
 snippet_model = console_ns.model("Snippet", snippet_fields)
@@ -86,15 +113,14 @@ snippet_pagination_model = console_ns.model("SnippetPagination", snippet_paginat
 @console_ns.route("/workspaces/current/customized-snippets")
 class CustomizedSnippetsApi(Resource):
     @console_ns.doc("list_customized_snippets")
-    @console_ns.expect(console_ns.models.get(SnippetListQuery.__name__))
+    @console_ns.doc(params=query_params_from_model(SnippetListQuery))
     @console_ns.response(200, "Snippets retrieved successfully", snippet_pagination_model)
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str):
         """List customized snippets with pagination and search."""
-        _, current_tenant_id = current_account_with_tenant()
-
         query = SnippetListQuery.model_validate(_normalize_snippet_list_query_args(request.args))
 
         snippet_service = _snippet_service()
@@ -124,10 +150,10 @@ class CustomizedSnippetsApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account):
         """Create a new customized snippet."""
-        current_user, current_tenant_id = current_account_with_tenant()
-
         payload = CreateSnippetPayload.model_validate(console_ns.payload or {})
 
         try:
@@ -163,10 +189,9 @@ class CustomizedSnippetDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, snippet_id: str):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, snippet_id: str):
         """Get customized snippet details."""
-        _, current_tenant_id = current_account_with_tenant()
-
         snippet_service = _snippet_service()
         snippet = snippet_service.get_snippet_by_id(
             snippet_id=str(snippet_id),
@@ -187,10 +212,10 @@ class CustomizedSnippetDetailApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def patch(self, snippet_id: str):
+    @with_current_user
+    @with_current_tenant_id
+    def patch(self, current_tenant_id: str, current_user: Account, snippet_id: str):
         """Update customized snippet."""
-        current_user, current_tenant_id = current_account_with_tenant()
-
         snippet_service = _snippet_service()
         snippet = snippet_service.get_snippet_by_id(
             snippet_id=str(snippet_id),
@@ -231,10 +256,9 @@ class CustomizedSnippetDetailApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def delete(self, snippet_id: str):
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, snippet_id: str):
         """Delete customized snippet."""
-        _, current_tenant_id = current_account_with_tenant()
-
         snippet_service = _snippet_service()
         snippet = snippet_service.get_snippet_by_id(
             snippet_id=str(snippet_id),
@@ -260,16 +284,16 @@ class CustomizedSnippetExportApi(Resource):
     @console_ns.doc("export_customized_snippet")
     @console_ns.doc(description="Export snippet configuration as DSL")
     @console_ns.doc(params={"snippet_id": "Snippet ID to export"})
-    @console_ns.response(200, "Snippet exported successfully")
+    @console_ns.doc(params=query_params_from_model(IncludeSecretQuery))
+    @console_ns.response(200, "Snippet exported successfully", console_ns.models[TextFileResponse.__name__])
     @console_ns.response(404, "Snippet not found")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def get(self, snippet_id: str):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, snippet_id: str):
         """Export snippet as DSL."""
-        _, current_tenant_id = current_account_with_tenant()
-
         snippet_service = _snippet_service()
         snippet = snippet_service.get_snippet_by_id(
             snippet_id=str(snippet_id),
@@ -305,16 +329,16 @@ class CustomizedSnippetImportApi(Resource):
     @console_ns.doc("import_customized_snippet")
     @console_ns.doc(description="Import snippet from DSL")
     @console_ns.expect(console_ns.models.get(SnippetImportPayload.__name__))
-    @console_ns.response(200, "Snippet imported successfully")
-    @console_ns.response(202, "Import pending confirmation")
+    @console_ns.response(200, "Snippet imported successfully", console_ns.models[SnippetImportResponse.__name__])
+    @console_ns.response(202, "Import pending confirmation", console_ns.models[SnippetImportResponse.__name__])
     @console_ns.response(400, "Import failed")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self):
+    @with_current_user
+    def post(self, current_user: Account):
         """Import snippet from DSL."""
-        current_user, _ = current_account_with_tenant()
         payload = SnippetImportPayload.model_validate(console_ns.payload or {})
 
         with Session(db.engine) as session:
@@ -344,16 +368,15 @@ class CustomizedSnippetImportConfirmApi(Resource):
     @console_ns.doc("confirm_snippet_import")
     @console_ns.doc(description="Confirm a pending snippet import")
     @console_ns.doc(params={"import_id": "Import ID to confirm"})
-    @console_ns.response(200, "Import confirmed successfully")
+    @console_ns.response(200, "Import confirmed successfully", console_ns.models[SnippetImportResponse.__name__])
     @console_ns.response(400, "Import failed")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self, import_id: str):
+    @with_current_user
+    def post(self, current_user: Account, import_id: str):
         """Confirm a pending snippet import."""
-        current_user, _ = current_account_with_tenant()
-
         with Session(db.engine) as session:
             import_service = SnippetDslService(session)
             result = import_service.confirm_import(import_id=import_id, account=current_user)
@@ -369,16 +392,19 @@ class CustomizedSnippetCheckDependenciesApi(Resource):
     @console_ns.doc("check_snippet_dependencies")
     @console_ns.doc(description="Check dependencies for a snippet")
     @console_ns.doc(params={"snippet_id": "Snippet ID"})
-    @console_ns.response(200, "Dependencies checked successfully")
+    @console_ns.response(
+        200,
+        "Dependencies checked successfully",
+        console_ns.models[SnippetDependencyCheckResponse.__name__],
+    )
     @console_ns.response(404, "Snippet not found")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def get(self, snippet_id: str):
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, snippet_id: str):
         """Check dependencies for a snippet."""
-        _, current_tenant_id = current_account_with_tenant()
-
         snippet_service = _snippet_service()
         snippet = snippet_service.get_snippet_by_id(
             snippet_id=str(snippet_id),
@@ -400,16 +426,15 @@ class CustomizedSnippetUseCountIncrementApi(Resource):
     @console_ns.doc("increment_snippet_use_count")
     @console_ns.doc(description="Increment snippet use count by 1")
     @console_ns.doc(params={"snippet_id": "Snippet ID"})
-    @console_ns.response(200, "Use count incremented successfully")
+    @console_ns.response(200, "Use count incremented successfully", console_ns.models[SnippetUseCountResponse.__name__])
     @console_ns.response(404, "Snippet not found")
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
-    def post(self, snippet_id: str):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, snippet_id: str):
         """Increment snippet use count when it is inserted into a workflow."""
-        _, current_tenant_id = current_account_with_tenant()
-
         snippet_service = _snippet_service()
         snippet = snippet_service.get_snippet_by_id(
             snippet_id=str(snippet_id),

api/controllers/console/workspace/tool_providers.py

@@ -5,32 +5,35 @@ from urllib.parse import urlparse
 
 from flask import make_response, redirect, request, send_file
 from flask_restx import Resource
-from pydantic import BaseModel, Field, HttpUrl, field_validator, model_validator
+from pydantic import BaseModel, Field, HttpUrl, RootModel, field_validator, model_validator
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import Forbidden
 
 from configs import dify_config
-from controllers.common.fields import SimpleResultResponse
-from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.common.fields import BinaryFileResponse, RedirectResponse, SimpleResultResponse
+from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
     enterprise_license_required,
     is_admin_or_owner_required,
     setup_required,
+    with_current_tenant_id,
+    with_current_user,
 )
 from core.db.session_factory import session_factory
 from core.entities.mcp_provider import IdentityMode, MCPAuthentication, MCPConfiguration
 from core.mcp.auth.auth_flow import auth, handle_callback
 from core.mcp.error import MCPAuthError, MCPError, MCPRefreshTokenError
 from core.mcp.mcp_client import MCPClient
-from core.plugin.entities.plugin_daemon import CredentialType
+from core.plugin.entities.plugin_daemon import CredentialType, PluginOAuthAuthorizationUrlResponse
 from core.plugin.impl.oauth import OAuthHandler
 from core.tools.entities.tool_entities import ApiProviderSchemaType, WorkflowToolParameterConfiguration
 from extensions.ext_database import db
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from libs.helper import alphanumeric, uuid_value
-from libs.login import current_account_with_tenant, login_required
+from libs.login import login_required
+from models import Account
 from models.provider_ids import ToolProviderID
 
 # from models.provider_ids import ToolProviderID
@@ -74,7 +77,7 @@ class BuiltinToolAddPayload(BaseModel):
 
 class BuiltinToolUpdatePayload(BaseModel):
     credential_id: str
-    credentials: dict[str, Any] | None = None
+    credentials: dict[str, Any] | None = Field(default=None)
     name: str | None = Field(default=None, max_length=30)
 
 
@@ -105,6 +108,13 @@ class ProviderQuery(BaseModel):
     provider: str
 
 
+class BuiltinCredentialListQuery(BaseModel):
+    include_credential_ids: list[str] = Field(
+        default_factory=list,
+        description="Credential IDs to include even if visibility would hide them",
+    )
+
+
 class ApiToolProviderDeletePayload(BaseModel):
     provider: str
 
@@ -196,7 +206,7 @@ class BuiltinProviderDefaultCredentialPayload(BaseModel):
 
 
 class ToolOAuthCustomClientPayload(BaseModel):
-    client_params: dict[str, Any] | None = None
+    client_params: dict[str, Any] | None = Field(default=None)
     enable_oauth_custom_client: bool | None = True
 
 
@@ -258,8 +268,27 @@ class MCPCallbackQuery(BaseModel):
     state: str
 
 
+class ToolOAuthCustomClientResponse(RootModel[dict[str, Any]]):
+    root: dict[str, Any]
+
+
+class ToolOAuthClientSchemaResponse(RootModel[list[dict[str, Any]]]):
+    root: list[dict[str, Any]]
+
+
+class ToolProviderOpaqueResponse(RootModel[Any]):
+    root: Any
+
+
 register_schema_models(
     console_ns,
+    ToolProviderListQuery,
+    UrlQuery,
+    ProviderQuery,
+    BuiltinCredentialListQuery,
+    WorkflowToolGetQuery,
+    WorkflowToolListQuery,
+    MCPCallbackQuery,
     BuiltinToolCredentialDeletePayload,
     BuiltinToolAddPayload,
     BuiltinToolUpdatePayload,
@@ -278,33 +307,42 @@ register_schema_models(
     MCPProviderDeletePayload,
     MCPAuthPayload,
 )
-register_response_schema_models(console_ns, SimpleResultResponse)
+register_response_schema_models(
+    console_ns,
+    BinaryFileResponse,
+    PluginOAuthAuthorizationUrlResponse,
+    RedirectResponse,
+    SimpleResultResponse,
+    ToolOAuthClientSchemaResponse,
+    ToolOAuthCustomClientResponse,
+    ToolProviderOpaqueResponse,
+)
 
 
 @console_ns.route("/workspaces/current/tool-providers")
 class ToolProviderListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(ToolProviderListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         raw_args = request.args.to_dict()
         query = ToolProviderListQuery.model_validate(raw_args)
 
-        return ToolCommonService.list_tool_providers(user_id, tenant_id, query.type)  # type: ignore
+        return ToolCommonService.list_tool_providers(user.id, tenant_id, query.type)  # type: ignore
 
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/tools")
 class ToolBuiltinProviderListToolsApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider: str):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str, provider: str):
         return jsonable_encoder(
             BuiltinToolManageService.list_builtin_tool_provider_tools(
                 tenant_id,
@@ -315,25 +353,25 @@ class ToolBuiltinProviderListToolsApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/info")
 class ToolBuiltinProviderInfoApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider: str):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str, provider: str):
         return jsonable_encoder(BuiltinToolManageService.get_builtin_tool_provider_info(tenant_id, provider))
 
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/delete")
 class ToolBuiltinProviderDeleteApi(Resource):
     @console_ns.expect(console_ns.models[BuiltinToolCredentialDeletePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self, provider: str):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def post(self, tenant_id: str, provider: str):
         payload = BuiltinToolCredentialDeletePayload.model_validate(console_ns.payload or {})
 
         return BuiltinToolManageService.delete_builtin_tool_provider(
@@ -346,18 +384,17 @@ class ToolBuiltinProviderDeleteApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/add")
 class ToolBuiltinProviderAddApi(Resource):
     @console_ns.expect(console_ns.models[BuiltinToolAddPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self, provider: str):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account, provider: str):
         payload = BuiltinToolAddPayload.model_validate(console_ns.payload or {})
 
         return BuiltinToolManageService.add_builtin_tool_provider(
-            user_id=user_id,
+            user_id=user.id,
             tenant_id=tenant_id,
             provider=provider,
             credentials=payload.credentials,
@@ -370,18 +407,18 @@ class ToolBuiltinProviderAddApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/update")
 class ToolBuiltinProviderUpdateApi(Resource):
     @console_ns.expect(console_ns.models[BuiltinToolUpdatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self, provider: str):
-        user, tenant_id = current_account_with_tenant()
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account, provider: str):
         payload = BuiltinToolUpdatePayload.model_validate(console_ns.payload or {})
 
         result = BuiltinToolManageService.update_builtin_tool_provider(
-            user_id=user_id,
+            user_id=user.id,
             tenant_id=tenant_id,
             provider=provider,
             credential_id=payload.credential_id,
@@ -393,11 +430,14 @@ class ToolBuiltinProviderUpdateApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/credentials")
 class ToolBuiltinProviderGetCredentialsApi(Resource):
+    @console_ns.doc(params=query_params_from_model(BuiltinCredentialListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider: str):
-        user, tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account, provider: str):
         # Optional list of credential IDs to include even if visibility would hide them
         # (used when a workflow/agent node still references another member's only_me credential).
         include_credential_ids = request.args.getlist("include_credential_ids") or [
@@ -416,6 +456,7 @@ class ToolBuiltinProviderGetCredentialsApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/icon")
 class ToolBuiltinProviderIconApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[BinaryFileResponse.__name__])
     @setup_required
     def get(self, provider: str):
         icon_bytes, mimetype = BuiltinToolManageService.get_builtin_tool_provider_icon(provider)
@@ -426,19 +467,18 @@ class ToolBuiltinProviderIconApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/api/add")
 class ToolApiProviderAddApi(Resource):
     @console_ns.expect(console_ns.models[ApiToolProviderAddPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = ApiToolProviderAddPayload.model_validate(console_ns.payload or {})
 
         return ApiToolManageService.create_api_tool_provider(
-            user_id,
+            user.id,
             tenant_id,
             payload.provider,
             payload.icon,
@@ -453,19 +493,19 @@ class ToolApiProviderAddApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/api/remote")
 class ToolApiProviderGetRemoteSchemaApi(Resource):
+    @console_ns.doc(params=query_params_from_model(UrlQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         raw_args = request.args.to_dict()
         query = UrlQuery.model_validate(raw_args)
 
         return ApiToolManageService.get_api_tool_provider_remote_schema(
-            user_id,
+            user.id,
             tenant_id,
             str(query.url),
         )
@@ -473,20 +513,20 @@ class ToolApiProviderGetRemoteSchemaApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/api/tools")
 class ToolApiProviderListToolsApi(Resource):
+    @console_ns.doc(params=query_params_from_model(ProviderQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         raw_args = request.args.to_dict()
         query = ProviderQuery.model_validate(raw_args)
 
         return jsonable_encoder(
             ApiToolManageService.list_api_tool_provider_tools(
-                user_id,
+                user.id,
                 tenant_id,
                 query.provider,
             )
@@ -496,19 +536,18 @@ class ToolApiProviderListToolsApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/api/update")
 class ToolApiProviderUpdateApi(Resource):
     @console_ns.expect(console_ns.models[ApiToolProviderUpdatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = ApiToolProviderUpdatePayload.model_validate(console_ns.payload or {})
 
         return ApiToolManageService.update_api_tool_provider(
-            user_id,
+            user.id,
             tenant_id,
             payload.provider,
             payload.original_provider,
@@ -525,19 +564,18 @@ class ToolApiProviderUpdateApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/api/delete")
 class ToolApiProviderDeleteApi(Resource):
     @console_ns.expect(console_ns.models[ApiToolProviderDeletePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = ApiToolProviderDeletePayload.model_validate(console_ns.payload or {})
 
         return ApiToolManageService.delete_api_tool_provider(
-            user_id,
+            user.id,
             tenant_id,
             payload.provider,
         )
@@ -545,19 +583,19 @@ class ToolApiProviderDeleteApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/api/get")
 class ToolApiProviderGetApi(Resource):
+    @console_ns.doc(params=query_params_from_model(ProviderQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         raw_args = request.args.to_dict()
         query = ProviderQuery.model_validate(raw_args)
 
         return ApiToolManageService.get_api_tool_provider(
-            user_id,
+            user.id,
             tenant_id,
             query.provider,
         )
@@ -565,12 +603,12 @@ class ToolApiProviderGetApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/credential/schema/<path:credential_type>")
 class ToolBuiltinProviderCredentialsSchemaApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider, credential_type):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str, provider, credential_type):
         return jsonable_encoder(
             BuiltinToolManageService.list_builtin_provider_credentials_schema(
                 provider, CredentialType.of(credential_type), tenant_id
@@ -581,6 +619,7 @@ class ToolBuiltinProviderCredentialsSchemaApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/api/schema")
 class ToolApiProviderSchemaApi(Resource):
     @console_ns.expect(console_ns.models[ApiToolSchemaPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -595,12 +634,13 @@ class ToolApiProviderSchemaApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/api/test/pre")
 class ToolApiProviderPreviousTestApi(Resource):
     @console_ns.expect(console_ns.models[ApiToolTestPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str):
         payload = ApiToolTestPayload.model_validate(console_ns.payload or {})
-        _, current_tenant_id = current_account_with_tenant()
         return ApiToolManageService.test_api_tool_preview(
             current_tenant_id,
             payload.provider_name or "",
@@ -615,19 +655,18 @@ class ToolApiProviderPreviousTestApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/workflow/create")
 class ToolWorkflowProviderCreateApi(Resource):
     @console_ns.expect(console_ns.models[WorkflowToolCreatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = WorkflowToolCreatePayload.model_validate(console_ns.payload or {})
 
         return WorkflowToolManageService.create_workflow_tool(
-            user_id=user_id,
+            user_id=user.id,
             tenant_id=tenant_id,
             workflow_app_id=payload.workflow_app_id,
             name=payload.name,
@@ -643,18 +682,18 @@ class ToolWorkflowProviderCreateApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/workflow/update")
 class ToolWorkflowProviderUpdateApi(Resource):
     @console_ns.expect(console_ns.models[WorkflowToolUpdatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = WorkflowToolUpdatePayload.model_validate(console_ns.payload or {})
 
         return WorkflowToolManageService.update_workflow_tool(
-            user_id,
+            user.id,
             tenant_id,
             payload.workflow_tool_id,
             payload.name,
@@ -670,19 +709,18 @@ class ToolWorkflowProviderUpdateApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/workflow/delete")
 class ToolWorkflowProviderDeleteApi(Resource):
     @console_ns.expect(console_ns.models[WorkflowToolDeletePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = WorkflowToolDeletePayload.model_validate(console_ns.payload or {})
 
         return WorkflowToolManageService.delete_workflow_tool(
-            user_id,
+            user.id,
             tenant_id,
             payload.workflow_tool_id,
         )
@@ -690,26 +728,26 @@ class ToolWorkflowProviderDeleteApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/workflow/get")
 class ToolWorkflowProviderGetApi(Resource):
+    @console_ns.doc(params=query_params_from_model(WorkflowToolGetQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         raw_args = request.args.to_dict()
         query = WorkflowToolGetQuery.model_validate(raw_args)
 
         if query.workflow_tool_id:
             tool = WorkflowToolManageService.get_workflow_tool_by_tool_id(
-                user_id,
+                user.id,
                 tenant_id,
                 query.workflow_tool_id,
             )
         elif query.workflow_app_id:
             tool = WorkflowToolManageService.get_workflow_tool_by_app_id(
-                user_id,
+                user.id,
                 tenant_id,
                 query.workflow_app_id,
             )
@@ -721,20 +759,20 @@ class ToolWorkflowProviderGetApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/workflow/tools")
 class ToolWorkflowProviderListToolApi(Resource):
+    @console_ns.doc(params=query_params_from_model(WorkflowToolListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         raw_args = request.args.to_dict()
         query = WorkflowToolListQuery.model_validate(raw_args)
 
         return jsonable_encoder(
             WorkflowToolManageService.list_single_workflow_tools(
-                user_id,
+                user.id,
                 tenant_id,
                 query.workflow_tool_id,
             )
@@ -743,19 +781,18 @@ class ToolWorkflowProviderListToolApi(Resource):
 
 @console_ns.route("/workspaces/current/tools/builtin")
 class ToolBuiltinListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         return jsonable_encoder(
             [
                 provider.to_dict()
                 for provider in BuiltinToolManageService.list_builtin_tools(
-                    user_id,
+                    user.id,
                     tenant_id,
                 )
             ]
@@ -764,12 +801,12 @@ class ToolBuiltinListApi(Resource):
 
 @console_ns.route("/workspaces/current/tools/api")
 class ToolApiListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         return jsonable_encoder(
             [
                 provider.to_dict()
@@ -782,19 +819,18 @@ class ToolApiListApi(Resource):
 
 @console_ns.route("/workspaces/current/tools/workflow")
 class ToolWorkflowListApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        user, tenant_id = current_account_with_tenant()
-
-        user_id = user.id
-
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account):
         return jsonable_encoder(
             [
                 provider.to_dict()
                 for provider in WorkflowToolManageService.list_tenant_workflow_tools(
-                    user_id,
+                    user.id,
                     tenant_id,
                 )
             ]
@@ -803,6 +839,7 @@ class ToolWorkflowListApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-labels")
 class ToolLabelsApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -813,17 +850,22 @@ class ToolLabelsApi(Resource):
 
 @console_ns.route("/oauth/plugin/<path:provider>/tool/authorization-url")
 class ToolPluginOAuthApi(Resource):
+    @console_ns.response(
+        200,
+        "Authorization URL retrieved successfully",
+        console_ns.models[PluginOAuthAuthorizationUrlResponse.__name__],
+    )
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def get(self, provider: str):
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account, provider: str):
         tool_provider = ToolProviderID(provider)
         plugin_id = tool_provider.plugin_id
         provider_name = tool_provider.provider_name
 
-        user, tenant_id = current_account_with_tenant()
-
         oauth_client_params = BuiltinToolManageService.get_oauth_client(tenant_id=tenant_id, provider=provider)
         if oauth_client_params is None:
             raise Forbidden("no oauth available client config found for this tool provider")
@@ -854,6 +896,11 @@ class ToolPluginOAuthApi(Resource):
 
 @console_ns.route("/oauth/plugin/<path:provider>/tool/callback")
 class ToolOAuthCallback(Resource):
+    @console_ns.response(
+        302,
+        "Redirect to console OAuth callback page",
+        console_ns.models[RedirectResponse.__name__],
+    )
     @setup_required
     def get(self, provider: str):
         context_id = request.cookies.get("context_id")
@@ -908,12 +955,13 @@ class ToolOAuthCallback(Resource):
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/default-credential")
 class ToolBuiltinProviderSetDefaultApi(Resource):
     @console_ns.expect(console_ns.models[BuiltinProviderDefaultCredentialPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self, provider: str):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, provider: str):
         payload = BuiltinProviderDefaultCredentialPayload.model_validate(console_ns.payload or {})
         return BuiltinToolManageService.set_default_provider(
             tenant_id=current_tenant_id, provider=provider, id=payload.id
@@ -923,15 +971,15 @@ class ToolBuiltinProviderSetDefaultApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/oauth/custom-client")
 class ToolOAuthCustomClient(Resource):
     @console_ns.expect(console_ns.models[ToolOAuthCustomClientPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    def post(self, provider: str):
+    @with_current_tenant_id
+    def post(self, tenant_id: str, provider: str):
         payload = ToolOAuthCustomClientPayload.model_validate(console_ns.payload or {})
 
-        _, tenant_id = current_account_with_tenant()
-
         return BuiltinToolManageService.save_custom_oauth_client_params(
             tenant_id=tenant_id,
             provider=provider,
@@ -944,8 +992,9 @@ class ToolOAuthCustomClient(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider: str):
-        _, current_tenant_id = current_account_with_tenant()
+    @console_ns.response(200, "Success", console_ns.models[ToolOAuthCustomClientResponse.__name__])
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, provider: str):
         return jsonable_encoder(
             BuiltinToolManageService.get_custom_oauth_client_params(tenant_id=current_tenant_id, provider=provider)
         )
@@ -953,8 +1002,9 @@ class ToolOAuthCustomClient(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def delete(self, provider: str):
-        _, current_tenant_id = current_account_with_tenant()
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str, provider: str):
         return jsonable_encoder(
             BuiltinToolManageService.delete_custom_oauth_client_params(tenant_id=current_tenant_id, provider=provider)
         )
@@ -962,11 +1012,12 @@ class ToolOAuthCustomClient(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/oauth/client-schema")
 class ToolBuiltinProviderGetOauthClientSchemaApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolOAuthClientSchemaResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider: str):
-        _, current_tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, provider: str):
         return jsonable_encoder(
             BuiltinToolManageService.get_builtin_tool_provider_oauth_client_schema(
                 tenant_id=current_tenant_id, provider_name=provider
@@ -976,11 +1027,14 @@ class ToolBuiltinProviderGetOauthClientSchemaApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/builtin/<path:provider>/credential/info")
 class ToolBuiltinProviderGetCredentialInfoApi(Resource):
+    @console_ns.doc(params=query_params_from_model(BuiltinCredentialListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider: str):
-        user, tenant_id = current_account_with_tenant()
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, user: Account, provider: str):
         include_credential_ids = request.args.getlist("include_credential_ids") or [
             s for s in (request.args.get("include_credential_ids") or "").split(",") if s
         ]
@@ -998,12 +1052,14 @@ class ToolBuiltinProviderGetCredentialInfoApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/mcp")
 class ToolProviderMCPApi(Resource):
     @console_ns.expect(console_ns.models[MCPProviderCreatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, user: Account):
         payload = MCPProviderCreatePayload.model_validate(console_ns.payload or {})
-        user, tenant_id = current_account_with_tenant()
 
         # Parse and validate models
         configuration = MCPConfiguration.model_validate(payload.configuration or {})
@@ -1051,14 +1107,15 @@ class ToolProviderMCPApi(Resource):
         return jsonable_encoder(result)
 
     @console_ns.expect(console_ns.models[MCPProviderUpdatePayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def put(self):
+    @with_current_tenant_id
+    def put(self, current_tenant_id: str):
         payload = MCPProviderUpdatePayload.model_validate(console_ns.payload or {})
         configuration = MCPConfiguration.model_validate(payload.configuration or {})
         authentication = MCPAuthentication.model_validate(payload.authentication) if payload.authentication else None
-        _, current_tenant_id = current_account_with_tenant()
 
         # Step 1: Get provider data for URL validation (short-lived session, no network I/O)
         validation_data = None
@@ -1107,9 +1164,9 @@ class ToolProviderMCPApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    def delete(self):
+    @with_current_tenant_id
+    def delete(self, current_tenant_id: str):
         payload = MCPProviderDeletePayload.model_validate(console_ns.payload or {})
-        _, current_tenant_id = current_account_with_tenant()
 
         with sessionmaker(db.engine).begin() as session:
             service = MCPToolManageService(session=session)
@@ -1121,13 +1178,14 @@ class ToolProviderMCPApi(Resource):
 @console_ns.route("/workspaces/current/tool-provider/mcp/auth")
 class ToolMCPAuthApi(Resource):
     @console_ns.expect(console_ns.models[MCPAuthPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def post(self):
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
         payload = MCPAuthPayload.model_validate(console_ns.payload or {})
         provider_id = payload.provider_id
-        _, tenant_id = current_account_with_tenant()
 
         with sessionmaker(db.engine).begin() as session:
             service = MCPToolManageService(session=session)
@@ -1194,11 +1252,12 @@ class ToolMCPAuthApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/mcp/tools/<path:provider_id>")
 class ToolMCPDetailApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider_id: str):
-        _, tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, tenant_id: str, provider_id: str):
         with sessionmaker(db.engine).begin() as session:
             service = MCPToolManageService(session=session)
             provider = service.get_provider(provider_id=provider_id, tenant_id=tenant_id)
@@ -1207,12 +1266,12 @@ class ToolMCPDetailApi(Resource):
 
 @console_ns.route("/workspaces/current/tools/mcp")
 class ToolMCPListAllApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self):
-        _, tenant_id = current_account_with_tenant()
-
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
         with sessionmaker(db.engine).begin() as session:
             service = MCPToolManageService(session=session)
             # Skip sensitive data decryption for list view to improve performance
@@ -1223,11 +1282,12 @@ class ToolMCPListAllApi(Resource):
 
 @console_ns.route("/workspaces/current/tool-provider/mcp/update/<path:provider_id>")
 class ToolMCPUpdateApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ToolProviderOpaqueResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
-    def get(self, provider_id: str):
-        _, tenant_id = current_account_with_tenant()
+    @with_current_tenant_id
+    def get(self, tenant_id: str, provider_id: str):
         with sessionmaker(db.engine).begin() as session:
             service = MCPToolManageService(session=session)
             tools = service.list_provider_tools(
@@ -1239,6 +1299,12 @@ class ToolMCPUpdateApi(Resource):
 
 @console_ns.route("/mcp/oauth/callback")
 class ToolMCPCallbackApi(Resource):
+    @console_ns.doc(params=query_params_from_model(MCPCallbackQuery))
+    @console_ns.response(
+        302,
+        "Redirect to console OAuth callback page",
+        console_ns.models[RedirectResponse.__name__],
+    )
     def get(self):
         raw_args = request.args.to_dict()
         query = MCPCallbackQuery.model_validate(raw_args)