fix(api): restore quota support helper binding

Signed-off-by: -LAN- <laipz8200@outlook.com>

.agents/skills/component-refactoring/SKILL.md

@@ -63,7 +63,7 @@ pnpm analyze-component <path> --json
 
 ```typescript
 // ❌ Before: Complex state logic in component
-function Configuration() {
+const Configuration: FC = () => {
   const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
   const [datasetConfigs, setDatasetConfigs] = useState<DatasetConfigs>(...)
   const [completionParams, setCompletionParams] = useState<FormValue>({})
@@ -85,7 +85,7 @@ export const useModelConfig = (appId: string) => {
 }
 
 // Component becomes cleaner
-function Configuration() {
+const Configuration: FC = () => {
   const { modelConfig, setModelConfig } = useModelConfig(appId)
   return <div>...</div>
 }
@@ -189,6 +189,8 @@ const Template = useMemo(() => {
 
 **Dify Convention**:
 - This skill is for component decomposition, not query/mutation design.
+- When refactoring data fetching, follow `web/AGENTS.md`.
+- Use `frontend-query-mutation` for contracts, query shape, data-fetching wrappers, query/mutation call-site patterns, conditional queries, invalidation, and mutation error handling.
 - Do not introduce deprecated `useInvalid` / `useReset`.
 - Do not add thin passthrough `useQuery` wrappers during refactoring; only extract a custom hook when it truly orchestrates multiple queries/mutations or shared derived state.
 

.agents/skills/component-refactoring/references/complexity-patterns.md

@@ -60,10 +60,8 @@ const Template = useMemo(() => {
 **After** (complexity: ~3):
 
 ```typescript
-import type { ComponentType } from 'react'
-
 // Define lookup table outside component
-const TEMPLATE_MAP: Record<AppModeEnum, Record<string, ComponentType<TemplateProps>>> = {
+const TEMPLATE_MAP: Record<AppModeEnum, Record<string, FC<TemplateProps>>> = {
   [AppModeEnum.CHAT]: {
     [LanguagesSupported[1]]: TemplateChatZh,
     [LanguagesSupported[7]]: TemplateChatJa,

.agents/skills/component-refactoring/references/component-splitting.md

@@ -65,10 +65,10 @@ interface ConfigurationHeaderProps {
   onPublish: () => void
 }
 
-function ConfigurationHeader({
+const ConfigurationHeader: FC<ConfigurationHeaderProps> = ({
   isAdvancedMode,
   onPublish,
-}: ConfigurationHeaderProps) {
+}) => {
   const { t } = useTranslation()
   
   return (
@@ -136,7 +136,7 @@ const AppInfo = () => {
 }
 
 // ✅ After: Separate view components
-function AppInfoExpanded({ appDetail, onAction }: AppInfoViewProps) {
+const AppInfoExpanded: FC<AppInfoViewProps> = ({ appDetail, onAction }) => {
   return (
     <div className="expanded">
       {/* Clean, focused expanded view */}
@@ -144,7 +144,7 @@ function AppInfoExpanded({ appDetail, onAction }: AppInfoViewProps) {
   )
 }
 
-function AppInfoCollapsed({ appDetail, onAction }: AppInfoViewProps) {
+const AppInfoCollapsed: FC<AppInfoViewProps> = ({ appDetail, onAction }) => {
   return (
     <div className="collapsed">
       {/* Clean, focused collapsed view */}
@@ -203,12 +203,12 @@ interface AppInfoModalsProps {
   onSuccess: () => void
 }
 
-function AppInfoModals({
+const AppInfoModals: FC<AppInfoModalsProps> = ({
   appDetail,
   activeModal,
   onClose,
   onSuccess,
-}: AppInfoModalsProps) {
+}) => {
   const handleEdit = async (data) => { /* logic */ }
   const handleDuplicate = async (data) => { /* logic */ }
   const handleDelete = async () => { /* logic */ }
@@ -296,7 +296,7 @@ interface OperationItemProps {
   onAction: (id: string) => void
 }
 
-function OperationItem({ operation, onAction }: OperationItemProps) {
+const OperationItem: FC<OperationItemProps> = ({ operation, onAction }) => {
   return (
     <div className="operation-item">
       <span className="icon">{operation.icon}</span>
@@ -435,7 +435,7 @@ interface ChildProps {
   onSubmit: () => void
 }
 
-function Child({ value, onChange, onSubmit }: ChildProps) {
+const Child: FC<ChildProps> = ({ value, onChange, onSubmit }) => {
   return (
     <div>
       <input value={value} onChange={e => onChange(e.target.value)} />

.agents/skills/component-refactoring/references/hook-extraction.md

@@ -112,13 +112,13 @@ export const useModelConfig = ({
 
 ```typescript
 // Before: 50+ lines of state management
-function Configuration() {
+const Configuration: FC = () => {
   const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
   // ... lots of related state and effects
 }
 
 // After: Clean component
-function Configuration() {
+const Configuration: FC = () => {
   const {
     modelConfig,
     setModelConfig,
@@ -159,6 +159,8 @@ function Configuration() {
 
 When hook extraction touches query or mutation code, do not use this reference as the source of truth for data-layer patterns.
 
+- Follow `web/AGENTS.md` first.
+- Use `frontend-query-mutation` for contracts, query shape, data-fetching wrappers, query/mutation call-site patterns, conditional queries, invalidation, and mutation error handling.
 - Do not introduce deprecated `useInvalid` / `useReset`.
 - Do not extract thin passthrough `useQuery` hooks; only extract orchestration hooks.
 

.agents/skills/e2e-cucumber-playwright/SKILL.md

@@ -23,7 +23,7 @@ Use this skill for Dify's repository-level E2E suite in `e2e/`. Use [`e2e/AGENTS
    - `e2e/scripts/run-cucumber.ts` and `e2e/cucumber.config.ts` when tags or execution flow matter
 3. Read [`references/playwright-best-practices.md`](references/playwright-best-practices.md) only when locator, assertion, isolation, or waiting choices are involved.
 4. Read [`references/cucumber-best-practices.md`](references/cucumber-best-practices.md) only when scenario wording, step granularity, tags, or expression design are involved.
-5. Re-check official Playwright or Cucumber docs with the available documentation tools before introducing a new framework pattern.
+5. Re-check official docs with Context7 before introducing a new Playwright or Cucumber pattern.
 
 ## Local Rules
 

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

@@ -1,93 +1,73 @@
 ---
 name: frontend-code-review
-description: Review Dify frontend code for correctness, accessibility, component design, dify-ui usage, data/query boundaries, performance, and tests. Trigger for `.tsx`, `.ts`, `.js`, UI, React, Next.js, pending-change, or focused frontend review requests.
+description: "Trigger when the user requests a review of frontend files (e.g., `.tsx`, `.ts`, `.js`). Support both pending-change reviews and focused file reviews while applying the checklist rules."
 ---
 
 # Frontend Code Review
 
-## When To Use
+## Intent
+Use this skill whenever the user asks to review frontend code (especially `.tsx`, `.ts`, or `.js` files). Support two review modes:
 
-Use this skill when the user asks to review, audit, analyze, or sanity-check frontend code under `web/`, `packages/dify-ui/`, or frontend-adjacent TypeScript files.
+1. **Pending-change review** – inspect staged/working-tree files slated for commit and flag checklist violations before submission.
+2. **File-targeted review** – review the specific file(s) the user names and report the relevant checklist findings.
 
-Supported modes:
+Stick to the checklist below for every applicable file and mode.
 
-- **Pending-change review**: inspect staged and working-tree changes.
-- **File-focused review**: inspect explicitly named files or paths.
-- **Diff/snippet review**: review pasted diffs or snippets using best-effort references.
+## Checklist
+See [references/code-quality.md](references/code-quality.md), [references/performance.md](references/performance.md), [references/business-logic.md](references/business-logic.md) for the living checklist split by category—treat it as the canonical set of rules to follow.
 
-Do not use this skill for backend-only code under `api/`; use `backend-code-review` instead.
-
-## Required Context
-
-Before reviewing, read the relevant local contracts:
-
-- `web/AGENTS.md` for Dify frontend workflow, overlays, design tokens, state, and tests.
-- `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.
-- `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:
-
-```text
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
-
-If the review depends on a current framework, SDK, browser API, or accessibility behavior and local code does not settle it, check the current official docs first. For browser compatibility, deprecation, or behavior-sensitive frontend APIs, verify MDN or the relevant standard.
-
-## Rule Packs
-
-Apply every relevant rule pack:
-
-- [references/accessibility-ui.md](references/accessibility-ui.md) — accessibility, semantic HTML, focus, forms, keyboard, disabled states, copy, and long-content behavior. Combines Web Interface Guidelines with Dify UI, Base UI, MDN, and local primitive contracts.
-- [references/dify-ui.md](references/dify-ui.md) — Dify UI primitive usage, Base UI semantics, overlays, forms, tokens, radius mapping, and primitive boundaries.
-- [references/component-architecture.md](references/component-architecture.md) — component ownership, props, state, effects, exports, wrappers, and feature organization.
-- [references/data-query-contracts.md](references/data-query-contracts.md) — generated contracts, TanStack Query, mutations, workspace/auth/SSR boundaries, URL/local storage state.
-- [references/performance.md](references/performance.md) — React/Next performance review rules from Vercel guidance, scoped to real risk.
-- [references/testing.md](references/testing.md) — frontend test review rules.
-- [references/dify-invariants.md](references/dify-invariants.md) — stable Dify-specific runtime invariants that generic React/a11y rules will not catch.
-- [references/code-quality.md](references/code-quality.md) — general TypeScript, styling, naming, and maintainability rules.
+Flag each rule violation with urgency metadata so future reviewers can prioritize fixes.
 
 ## Review Process
+1. Open the relevant component/module. Gather lines that relate to class names, React Flow hooks, prop memoization, and styling.
+2. For each rule in the review point, note where the code deviates and capture a representative snippet.
+3. Compose the review section per the template below. Group violations first by **Urgent** flag, then by category order (Code Quality, Performance, Business Logic).
 
-1. Identify the review scope. For pending changes, inspect `git diff --stat`, `git diff`, and staged diff if relevant. For file-focused reviews, stay within the named files unless a referenced owner/contract must be read.
-2. Read code around the changed lines and the owning module. Do not review by isolated snippets when nearby ownership, labels, query inputs, or overlay structure decide correctness.
-3. Check user-visible regressions first: accessibility, broken interaction, auth/permission leaks, query/hydration errors, data loss, navigation mistakes, and impossible states.
-4. Then check maintainability and performance: ownership, effects, wrappers, memoization, bundle/waterfall risks, tests, and design-system drift.
-5. Report only actionable findings. Do not list speculative risks, style preferences, or broad refactors unless they are directly tied to a reproducible issue in scope.
+## Required output
+When invoked, the response must exactly follow one of the two templates:
 
-## Severity
+### Template A (any findings)
+```
+# Code review
+Found <N> urgent issues need to be fixed:
 
-- **P0**: security/privacy/auth leak, data loss, production crash, inaccessible critical flow, or broken primary workflow.
-- **P1**: user-visible regression, hydration/SSR failure, invalid API/query contract, broken keyboard/focus behavior, or serious design-system/a11y violation.
-- **P2**: maintainability or performance issue likely to cause bugs, duplicated state, incorrect ownership, missing tests for risky behavior, or non-critical a11y issue.
-- **P3**: minor cleanup with clear value. Omit unless the user asked for a thorough audit.
+## 1 <brief description of bug>
+FilePath: <path> line <line>
+<relevant code snippet or pointer>
 
-## Output Format
 
-Lead with findings, ordered by severity. Use this structure:
+### Suggested fix
+<brief description of suggested fix>
 
-```markdown
-## Findings
+---
+... (repeat for each urgent issue) ...
 
-- [P1] Short issue title
-  File: `path/to/file.tsx:123`
-  Why it matters and how to reproduce or reason about it.
-  Suggested fix: concrete fix direction.
+Found <M> suggestions for improvement:
 
-## Open Questions
+## 1 <brief description of suggestion>
+FilePath: <path> line <line>
+<relevant code snippet or pointer>
 
-- Question or assumption, if any.
 
-## Summary
+### Suggested fix
+<brief description of suggested fix>
 
-Brief secondary context. Mention tests not run or residual risk.
+---
+
+... (repeat for each suggestion) ...
 ```
 
-Rules:
+If there are no urgent issues, omit that section. If there are no suggestions, omit that section.
+
+If the issue number is more than 10, summarize as "10+ urgent issues" or "10+ suggestions" and just output the first 10 issues.
+
+Don't compress the blank lines between sections; keep them as-is for readability.
+
+If you use Template A (i.e., there are issues to fix) and at least one issue requires code changes, append a brief follow-up question after the structured output asking whether the user wants you to apply the suggested fix(es). For example: "Would you like me to use the Suggested fix section to address these issues?"
+
+### Template B (no issues)
+```
+## Code review
+No issues found.
+```
 
-- If there are no findings, say `No issues found.` and mention any test gaps or residual risk.
-- Always include file and line when available.
-- Keep findings concrete and reproducible.
-- Do not include praise sections by default.
-- Do not ask to apply fixes unless the user explicitly wants review plus implementation.

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

@@ -1,109 +0,0 @@
-# Accessibility And UI Rules
-
-Accessibility findings are first-class review findings. Treat broken keyboard access, missing accessible names, focus loss, and unreachable popup content as correctness bugs, not polish.
-
-Before finalizing UI or accessibility findings, fetch the latest Web Interface Guidelines as a required baseline:
-
-```text
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
-
-Do not treat that document as the complete accessibility rule set. Combine it with:
-
-- `packages/dify-ui/README.md`, `packages/dify-ui/AGENTS.md`, and the relevant primitive implementation when code uses `@langgenius/dify-ui/*`.
-- Base UI docs and local `.d.ts` contracts when primitive semantics, focus target, labels, or popup reachability are unclear.
-- MDN or relevant WAI-ARIA/browser standards when behavior, compatibility, or deprecation status matters.
-- The current feature's product semantics, because an accessible primitive can still be used in an inaccessible workflow.
-
-## Semantic HTML
-
-Flag:
-
-- Clickable `div` or `span` used for actions.
-- Router navigation implemented with button or `onClick` when a `Link` / `<a>` is the real semantic element.
-- Icon-only buttons without `aria-label` or `aria-labelledby`.
-- Decorative icons missing `aria-hidden="true"`.
-- Images without `alt`; use `alt=""` only when truly decorative.
-- Heading levels that skip hierarchy in page-level content.
-
-Prefer semantic HTML before ARIA.
-
-## Keyboard And Focus
-
-Flag:
-
-- Interactive elements without visible `focus-visible` treatment.
-- `outline-none` / `outline-hidden` without an equivalent focus-visible ring or state.
-- Custom interactive elements missing keyboard handling.
-- Focus trapped, lost, or sent to the wrong surface after dialog/popover/menu close.
-- Focus ring applied to the wrong DOM node. Verify the actual focus target, especially with Base UI controls such as Slider.
-
-Use `focus-visible` for keyboard focus. Use `focus-within` or `has-[:focus-visible]` when the visual wrapper is not the focused element.
-
-## Forms
-
-Flag:
-
-- Inputs, selects, switches, checkboxes, radios, comboboxes, or sliders without a label relationship.
-- Missing stable `name` on form fields that submit or validate.
-- Incorrect input `type`, `inputMode`, `autoComplete`, or `spellCheck` for email, token, URL, number, search, code, or username fields.
-- Labels that are not clickable.
-- Submit buttons disabled before a request starts, preventing normal submit behavior.
-- Non-submit buttons inside forms missing `type="button"`.
-- Errors not associated with fields or not reachable by screen readers.
-- Error recovery that does not focus or expose the first invalid field.
-- `onPaste` blocking paste.
-- Placeholder text used as the only label.
-- Password managers accidentally triggered on non-auth fields because autocomplete is missing or wrong.
-
-Prefer visible labels. If visible surrounding text already labels the control, use a visually hidden label or a precise `aria-label`.
-
-## Disabled, Loading, And Async States
-
-Flag:
-
-- Loading state without `aria-busy`, `role="status"`, or another accessible update path when it changes user interaction.
-- Spinner or decorative loading icon exposed to screen readers.
-- Disabled controls that hide the reason users cannot proceed.
-- `aria-disabled` used without manually blocking click, Space, and Enter.
-- Toasts, inline validation, or async status changes that are not announced when users need the update to continue.
-- Icon-only loading/error affordances without text or accessible status where the state matters.
-
-Use native `disabled` when the control must not be interactive. Use `aria-disabled` only when the element must remain focusable and the code handles all blocked interactions.
-
-For repeated shared disabled reasons, prefer a visible group message or badge plus native disabled controls. Use per-control popover/info only when the reason is item-specific.
-
-## Overlays And Popup Reachability
-
-Flag:
-
-- Tooltip used for long, structured, interactive, or unique information.
-- Tooltip content required to understand or complete a flow.
-- PreviewCard content that touch or screen-reader users cannot reach through the trigger's click destination.
-- Popover/dialog/menu triggers without accessible names.
-- Popup content without title/description where the primitive requires them.
-
-Use Popover for explanatory content, rich help, and infotips. Use Tooltip only as a short visual label for a trigger that already has an accessible name.
-
-## Long Content And Layout
-
-Flag:
-
-- Text in flex/grid children without `min-w-0` when it can overflow.
-- Names, labels, file names, model names, workspace names, or user content lacking `truncate`, `line-clamp`, or `break-words`.
-- Right-side icons, badges, checks, or actions that shrink before the text area.
-- Empty arrays or empty strings rendering broken layout instead of an empty state.
-- Button, tab, badge, chip, menu item, or card text that can overlap sibling controls at common viewport widths.
-
-The usual Dify layout chain is: container has width constraints, text region uses `min-w-0 flex-1 truncate`, adornments use `shrink-0`.
-
-## Motion, Images, And Copy
-
-Flag:
-
-- `transition-all`.
-- Animations that do not respect reduced motion.
-- Layout-affecting animation where transform/opacity would work.
-- Images without dimensions.
-- Loading copy using `...` instead of `…`.
-- Hardcoded dates, times, numbers, or currency formats instead of `Intl.*`.

.agents/skills/frontend-code-review/references/business-logic.md

@@ -0,0 +1,15 @@
+# Rule Catalog — Business Logic
+
+## Can't use workflowStore in Node components
+
+IsUrgent: True
+
+### Description
+
+File path pattern of node components: `web/app/components/workflow/nodes/[nodeName]/node.tsx`
+
+Node components are also used when creating a RAG Pipe from a template, but in that context there is no workflowStore Provider, which results in a blank screen. [This Issue](https://github.com/langgenius/dify/issues/29168) was caused by exactly this reason.
+
+### Suggested Fix
+
+Use `import { useNodes } from 'reactflow'` instead of `import useNodes from '@/app/components/workflow/store/workflow/use-nodes'`.

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

@@ -1,66 +1,44 @@
-# Code Quality Rules
+# Rule Catalog — Code Quality
 
-## Scope Control
+## Conditional class names use utility function
 
-Flag changes that expand beyond the requested feature or review scope:
+IsUrgent: True
+Category: Code Quality
 
-- Repo-wide cleanup mixed into a targeted fix.
-- Compatibility exports, aliases, shims, or wrapper layers added without an explicit migration requirement.
-- Shared abstractions created before there is stable cross-feature reuse.
-- Business components moved into generic shared locations without a clear ownership boundary.
+### Description
 
-## TypeScript
+Ensure conditional CSS is handled via the shared `classNames` instead of custom ternaries, string concatenation, or template strings. Centralizing class logic keeps components consistent and easier to maintain.
 
-Flag:
+### Suggested Fix
 
-- `any` or broad `Record<string, any>` where generated/API types or local domain types exist.
-- Re-declared API shapes instead of importing generated or returned types.
-- Weak route/query param typing that leaks `string | string[] | undefined` deep into components.
-- Runtime wrappers added only to satisfy TypeScript when a narrower type boundary would preserve the existing runtime shape.
+```ts
+import { cn } from '@/utils/classnames'
+const classNames = cn(isActive ? 'text-primary-600' : 'text-gray-500')
+```
 
-Prefer:
+## Tailwind-first styling
 
-- Explicit domain names that match the API contract.
-- Type narrowing at route/API boundaries.
-- Small conversion helpers colocated with the component that needs them.
+IsUrgent: True
+Category: Code Quality
 
-## Styling
+### Description
 
-Flag:
+Favor Tailwind CSS utility classes instead of adding new `.module.css` files unless a Tailwind combination cannot achieve the required styling. Keeping styles in Tailwind improves consistency and reduces maintenance overhead.
 
-- New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
-- 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.
-- 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.
+Update this file when adding, editing, or removing Code Quality rules so the catalog remains accurate.
 
-Use:
+## Classname ordering for easy overrides
 
-- `cn(...)` from the local package or utility already used by the file.
-- Dify semantic tokens and Tailwind v4 utilities.
-- Existing component variants before one-off class forks.
-- Primitive selectors such as `data-disabled:*`, `data-checked:*`, `data-highlighted:*`, `group-data-*`, `peer-data-*`, and `has-[:focus-visible]` before adding React state or boolean props solely for styling.
-- Component-level variants, semantic tokens, and normal cascade/order before `!` overrides. Use `!` only for a contained compatibility override that cannot be expressed through the component API or local selector structure.
+### Description
 
-## Imports
+When writing components, always place the incoming `className` prop after the component’s own class values so that downstream consumers can override or extend the styling. This keeps your component’s defaults but still lets external callers change or remove specific styles.
 
-Flag:
+Example:
 
-- Barrel imports from `@langgenius/dify-ui`; consumers must use subpath exports.
-- New overlay imports from legacy `@/app/components/base/modal`, `dialog`, or `drawer`.
-- Cross-feature imports that bypass explicit top-level public files.
-- Direct imports from generated/internal implementation files when a feature contract already exposes the intended surface.
+```tsx
+import { cn } from '@/utils/classnames'
 
-## Copy And i18n
-
-Flag:
-
-- User-facing hardcoded strings in `web/`.
-- 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.
+const Button = ({ className }) => {
+  return <div className={cn('bg-primary-600', className)}></div>
+}
+```

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

@@ -1,85 +0,0 @@
-# Component Architecture Rules
-
-Use these rules for React component structure, ownership, state, props, effects, and module organization.
-
-## Ownership
-
-Flag:
-
-- State, query, mutation, or handlers hoisted above the lowest component that actually uses them.
-- Parent components owning row/item actions that do not coordinate a workflow.
-- Prop drilling through multiple pass-through layers.
-- A page/tab-level section component becoming the data owner without needing a shared snapshot or shared loading/error/empty UI.
-- Feature code promoted to shared only because it appears once or might be reused later.
-
-Accept repeated TanStack Query calls in siblings when each component independently consumes the data. Cache deduplication is not a reason to hoist by itself.
-
-## Component Boundaries
-
-Flag:
-
-- 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.
-- Business forms, menu bodies, or one-off helpers moved away from their owner without reuse or semantic value.
-
-Prefer colocated components split by actual data and state needs.
-
-## Bad Component Design Patterns
-
-Flag:
-
-- 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.
-- A feature component that accepts pre-rendered fragments only to avoid placing ownership correctly.
-- A child component that receives both raw server data and separately derived flags for the same concept.
-- A wrapper that changes accessible semantics of the primitive it wraps.
-- 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.
-
-## Props And Types
-
-Flag:
-
-- `React.FC` / `FC`.
-- Default exports outside framework-required files.
-- Named `Props` types for trivial one-off props where inline typing is clearer.
-- Props named by UI implementation instead of domain/API role.
-- API data converted too early or under a generic name that breaks traceability.
-- Callers duplicating fallback checks that the lowest rendering component already handles.
-
-Prefer top-level `function` declarations for components and module helpers. Use arrow functions for callbacks and local lambdas.
-
-## Effects
-
-Flag effects that:
-
-- Transform props/state for rendering.
-- Copy one state value into another representing the same concept.
-- Handle user actions that belong in event handlers.
-- Reset state from props when a keyed reset, stable ID, or render-time derivation would work.
-- Fetch data that belongs in framework APIs or TanStack Query.
-
-If an effect remains, it must synchronize with a named external system: browser API, subscription, timer, analytics-on-visibility, non-React widget, or imperative DOM integration.
-
-## State Modeling
-
-Flag:
-
-- Storing derived booleans, disabled flags, default tabs, or loading labels that can be calculated from current query/feature state.
-- Local state used to fake server data or generated contract fields.
-- UI state persisted to localStorage when it is live app state.
-- Feature-local mock shells wired to unrelated existing APIs before the real API is confirmed.
-
-Prefer render-time derivation. Keep true local state for user choices, transient input, controlled popups, and feature UI state that has no server source.
-
-## Navigation
-
-Flag:
-
-- Imperative router navigation for ordinary links.
-- Button semantics used for navigation.
-- Navigation state hidden in component state when URL state is required for shareable filters, tabs, or pagination.
-
-Use `Link` for normal navigation. Use router APIs for mutation success, guarded redirects, command flows, or form submission side effects.

.agents/skills/frontend-code-review/references/data-query-contracts.md

@@ -1,74 +0,0 @@
-# Data, Query, And Contract Rules
-
-Use these rules for generated contracts, TanStack Query, mutations, auth/SSR boundaries, URL state, and client persistence.
-
-## Generated Contracts
-
-Flag:
-
-- New legacy service/helper wrappers around generated `queryOptions()` or `mutationOptions()`.
-- Continuing to use deprecated contract operations when a ready generated contract exists.
-- Assuming a generated file means an operation is ready without checking deprecated markers, schema shape, and the actual UI consumer.
-- Re-declaring API DTOs in components.
-- Adding compatibility layers instead of migrating the pointed line and deleting the old layer.
-
-Use `web/contract/*` as the API shape source of truth. Follow existing `{ params, query?, body? }` input shape.
-
-## Queries
-
-Flag:
-
-- `enabled` used to hide missing required input instead of `input: skipToken`.
-- Fake fallback IDs or placeholder inputs used to force a query to run.
-- Query results copied into local state for rendering.
-- Shared query behavior such as invalidation, stale defaults, or retry rules reimplemented at call sites.
-- `prefetchQuery` treated as a hard gate or as returning data/errors to the caller.
-
-Use `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))` directly unless a feature hook performs real orchestration.
-
-## Mutations
-
-Flag:
-
-- Deprecated `useInvalid` or `useReset`.
-- `mutateAsync` used without a need for Promise semantics.
-- Awaited mutations without `try/catch`.
-- Components owning shared cache invalidation that belongs in query defaults.
-- Optimistic updates that do not match current list/detail ownership.
-
-Use generated `mutationOptions()` directly when possible. Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`.
-
-## SSR, Auth, And Route Boundaries
-
-Flag:
-
-- Request-time auth, setup, workspace role, or tenant decisions moved into static `next.config redirects()`.
-- Dynamic role gates depending on `workspaces.current` implemented as static path redirects.
-- Authorization logic depending on soft `prefetchQuery`.
-- Removing a client fallback before server API unavailable behavior is defined.
-- Global placeholder query contracts introduced to solve a route-local Suspense issue.
-- Branding-sensitive UI reading placeholder defaults without checking pending/placeholder state.
-
-Separate hard gates from soft prefetches. `fetchQuery` can be a server decision boundary; `prefetchQuery` is cache warmup.
-
-## Workspace And Tenant
-
-Flag:
-
-- Treating workspace switch as ordinary CRUD invalidation when the current app flow performs server switch plus full reload.
-- Query keys that omit workspace/tenant identity when the query truly varies by workspace and no full reload boundary applies.
-- Mixing `workspace_id` and `tenant_id` without tracing the current backend/API contract.
-
-Current Dify workspace switch should be reviewed as a tenant cache boundary first.
-
-## URL State And Local Storage
-
-Flag:
-
-- Shareable filters, tabs, pagination, selected panels, or search state hidden only in component state.
-- One-shot navigation signals modeled as subscribed persistent state.
-- Live app state stored in localStorage.
-- Direct `window.localStorage`, `globalThis.localStorage`, or raw storage calls in app code.
-- High-frequency interaction state persisted on every change instead of on commit/settle.
-
-Use URL state for shareable UI state, feature/Jotai/store state for live UI state, and `@/hooks/use-local-storage` only for low-frequency client-only preferences, dismissed notices, and UI defaults.

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

@@ -1,22 +0,0 @@
-# Dify Invariants
-
-Use these stable Dify-specific runtime rules in addition to the generic review packs.
-
-This file is not a place for active feature notes. Do not add rules for one branch, one PR, or a short-lived product decision such as a specific agent-v2, plugin, model-provider, or onboarding task. Keep a rule here only when all of these are true:
-
-- It is a stable Dify runtime invariant.
-- Generic React, TypeScript, accessibility, dify-ui, query, or performance rules would not catch it.
-- The failure mode is concrete enough to produce a file-line review finding.
-- The rule is likely to remain valid across normal feature work.
-
-## Workflow Nodes And RAG Pipe
-
-Flag:
-
-- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` importing workflow store hooks that are unavailable in RAG Pipe template rendering.
-- Node UI relying on provider context that is not mounted in every rendering surface.
-- Store reads in render where React Flow `useNodes` / `useEdges` provide the actual node/edge source.
-
-Known failure mode: workflow node components can also render while creating a RAG Pipe from a template. In that context there may be no workflowStore provider, causing a blank screen.
-
-Prefer React Flow hooks for node/edge UI consumption. Use store APIs only where the provider is guaranteed and the code path is workflow-only.

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

@@ -1,123 +0,0 @@
-# Dify UI Rules
-
-Use these rules whenever a review touches `packages/dify-ui/` or code consuming `@langgenius/dify-ui/*`.
-
-Before finalizing findings for those files, read the current local docs that apply:
-
-- `packages/dify-ui/README.md`
-- `packages/dify-ui/AGENTS.md`
-- `web/docs/overlay.md` for floating UI
-- `packages/dify-ui/src/<primitive>/index.tsx` for the primitive being changed or consumed
-
-## Package Boundary
-
-Flag in `packages/dify-ui`:
-
-- Imports from `web/`.
-- Dependencies on Next.js, i18n, ky, Jotai, Zustand, TanStack Query, oRPC, or business APIs.
-- Business-specific component behavior that belongs in `web/`.
-- Multiple unrelated primitives in one component folder.
-
-`packages/dify-ui` is a primitive layer: Base UI headless components + `cva` + `cn` + Dify design tokens.
-
-## Imports And Exports
-
-Flag:
-
-- Consumer imports from `@langgenius/dify-ui` without a subpath.
-- Missing `package.json#exports` entry for a new primitive.
-- Internal package imports using workspace subpaths instead of relative paths.
-- Exported props using internal-only types that consumers cannot import from the component subpath.
-
-Consumers use subpath exports such as `@langgenius/dify-ui/button`.
-
-## Props And State
-
-Flag:
-
-- Flattened props where related values need a discriminated union, such as `value` / `defaultValue`, `multiple` / `value`, or `clearable` / `onChange`.
-- React state used only to mirror Base UI state for class names.
-- JavaScript conditional class logic for visual states that the Dify UI/Base UI primitive already exposes through `data-*` attributes or CSS variables.
-- Controlled props added when uncontrolled DOM state or CSS variables would be enough.
-- Thin wrappers that rename Base UI parts without adding semantics.
-
-Prefer Base UI/Dify UI data attributes and CSS variables for visual state: `data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`, `group-data-*`, `peer-data-*`, `has-[:focus-visible]`, and primitive CSS variables such as anchor width or transform origin. Use JS conditional classes for product/business state that the primitive does not expose.
-
-## Forms
-
-Flag:
-
-- Form-like UI using unrelated `Input` and `Button` pieces without a submit boundary.
-- Text-like fields not composed through `FieldRoot`, `FieldLabel`, and `FieldControl` when using Dify UI form semantics.
-- Select fields using `FieldLabel` instead of `SelectLabel`.
-- Slider fields using a generic label instead of `SliderLabel`.
-- Checkbox/radio groups missing `FieldsetRoot` and `FieldsetLegend`.
-- Field errors or descriptions rendered without `FieldDescription` / `FieldError` relationships.
-
-`Form` is the submit boundary. Dify UI form primitives are not a form state-management framework; business validation and schema-driven behavior belong in `web/`.
-
-## Overlay Contract
-
-Flag:
-
-- Legacy web overlay imports in new or modified code.
-- Manual portals around Dify UI overlay primitives.
-- Call-site `z-*` overrides on overlays.
-- Missing root `isolation: isolate` assumptions when debugging overlay stacking.
-- Repeated backdrop, z-index, or portal chrome at call sites.
-- Tooltip used for infotips, long text, or interactive content.
-
-All Dify UI body-portalled overlays use `z-50`. Toast uses `z-60`. DOM order handles stacking between overlays.
-
-## Primitive Selection
-
-Flag:
-
-- `Tabs` used for simple mode/filter/view selection where `SegmentedControl` is the semantic primitive.
-- `SegmentedControl` used where `tablist` / `tabpanel` semantics are required.
-- `Select` used for searchable or free-form input.
-- `Combobox` used for unrestricted search text where no selected option is remembered.
-- `Autocomplete` used for closed-list selection.
-- Tooltip or PreviewCard used for content that must be reachable on touch or by screen readers.
-
-Use:
-
-- `Autocomplete` for free-form text with optional suggestions.
-- `Combobox` for searchable selected values from a collection.
-- `Select` for closed, scannable option sets.
-- `Popover` for infotips, help text, rich content, or interactions.
-
-## Bad Usage Patterns To Flag
-
-Flag:
-
-- 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.
-- Using `Tooltip` because it is visually convenient when the content is actually help text or needs touch access.
-- Adding a `z-*` override to make a child popup appear over a parent dialog.
-- Adding a new app-level wrapper around Dialog, Drawer, Popover, Select, or Combobox that repeats portal/backdrop/positioner logic.
-- Using dify-ui `Input` as a drop-in replacement for legacy inputs that include search, clear, copy, unit, localized placeholder, or number normalization behavior.
-- Building a form row from loose text and controls instead of the matching Field/Form primitives.
-- Adding component state only to style `data-open`, `data-checked`, `data-disabled`, or highlighted states that Base UI already exposes.
-- Passing booleans down only so children can toggle classes already expressible with primitive `data-*` selectors.
-
-## Tokens, Radius, And Styling
-
-Flag:
-
-- `radius-*` class names.
-- Custom Tailwind `borderRadius` extension for Figma radius values.
-- Generic colors where semantic Dify tokens exist.
-- Hardcoded design values where Dify tokens, component variants, or documented Figma radius mappings exist.
-- `!` important modifiers used to fight primitive styles instead of fixing the variant, selector, or component composition.
-- Manual class strings that duplicate primitive variants.
-- `min-w-(--anchor-width)` on picker popups when it defeats viewport clamping.
-
-Use the Figma radius mapping from `packages/dify-ui/AGENTS.md`; for example `--radius/sm` maps to `rounded-md`, and `--radius/md` maps to `rounded-lg`.
-
-Use `!` only for a tightly scoped compatibility override after confirming the primitive API, data attributes, and selector structure cannot express the state.
-
-## 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`.

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

@@ -1,78 +1,45 @@
-# Performance Rules
+# Rule Catalog — Performance
 
-Review performance only where there is realistic impact. Do not request `memo`, `useMemo`, `useCallback`, virtualization, or caching as style preferences.
+## React Flow data usage
 
-## Async Waterfalls
+IsUrgent: True
+Category: Performance
 
-Flag:
+### Description
 
-- Awaiting remote feature flags or fetches before checking cheap synchronous conditions.
-- Sequential awaits for independent operations.
-- API routes or server components starting requests late when they could start early.
-- Nested per-item fetches running serially when each item can fetch in parallel.
-- Suspense boundaries that force the whole page to wait when a lower boundary could stream or isolate loading.
+When rendering React Flow, prefer `useNodes`/`useEdges` for UI consumption and rely on `useStoreApi` inside callbacks that mutate or read node/edge state. Avoid manually pulling Flow data outside of these hooks.
 
-Prefer `Promise.all` for independent work and branch-local awaits for conditionally needed data.
+## Complex prop memoization
 
-## Bundle Size
+IsUrgent: True
+Category: Performance
 
-Flag:
+### Description
 
-- Barrel imports from heavy libraries or `@langgenius/dify-ui`.
-- Dynamic paths that prevent static trace analysis.
-- Heavy components loaded eagerly when hidden behind a dialog, tab, command, or feature activation.
-- Analytics, logging, editor, visualization, or third-party SDK code loaded before it is needed.
-- Feature-local optional modules imported at top level only for rare flows.
+Wrap complex prop values (objects, arrays, maps) in `useMemo` prior to passing them into child components to guarantee stable references and prevent unnecessary renders.
 
-Use direct imports and `next/dynamic` where the user-visible path benefits.
+Update this file when adding, editing, or removing Performance rules so the catalog remains accurate.
 
-## Server Rendering
+Wrong:
 
-Flag:
+```tsx
+<HeavyComp
+    config={{
+        provider: ...,
+        detail: ...
+    }}
+/>
+```
 
-- Request-specific mutable state stored at module scope in SSR/RSC paths.
-- Large duplicate data serialized across RSC/client boundaries.
-- Static I/O repeated per request when it could be hoisted safely.
-- Cross-request cache without a bounded invalidation strategy.
-- Server actions lacking API-route-equivalent auth checks.
+Right:
 
-Use request-scoped deduplication such as `React.cache()` when repeated server reads in one request are the problem.
+```tsx
+const config = useMemo(() => ({
+    provider: ...,
+    detail: ...
+}), [provider, detail]);
 
-## Re-rendering
-
-Flag:
-
-- Effects or subscriptions reading broad state when a derived boolean or narrower selector is enough.
-- Components defined inside components.
-- Derived rendering state stored in state/effects.
-- Non-primitive default props recreated for memoized children.
-- Expensive work recalculated on every render where it affects real interaction cost.
-- High-frequency transient values stored in state when refs or CSS variables would avoid render loops.
-
-Do not flag simple primitive expressions wrapped or not wrapped in `useMemo`; prefer no memo for simple work.
-
-Require stable object/array/function identity only when:
-
-- The child is memoized and identity affects renders.
-- The value is an effect/query dependency.
-- A library API requires stable references.
-- Profiling or local behavior shows avoidable re-rendering.
-
-## DOM, Lists, And Rendering
-
-Flag:
-
-- Layout reads in render (`getBoundingClientRect`, `offset*`, `scrollTop`).
-- Interleaved DOM reads/writes that can cause layout thrashing.
-- Large lists rendering without virtualization, pagination, or `content-visibility`.
-- SVG/animation code animating expensive properties when transform/opacity would work.
-- `transition-all`.
-- Long-running non-critical browser work performed immediately instead of idle/deferred scheduling.
-
-## React Flow
-
-For workflow React Flow components, keep this Dify-specific rule:
-
-- UI consumption should use React Flow hooks such as `useNodes` / `useEdges`.
-- Callback-only reads or mutations can use `useStoreApi`.
-- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` must not depend on workflow stores that are absent in RAG Pipe template rendering.
+<HeavyComp
+    config={config}
+/>
+```

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

@@ -1,72 +0,0 @@
-# Testing Review Rules
-
-Use these rules when reviewing test files, testability of changed code, or risky frontend changes that should have tests.
-
-## Missing Coverage
-
-Flag missing tests when the change affects:
-
-- User-visible behavior, navigation, form submission, validation, permissions, or loading/error/empty states.
-- Query/mutation cache behavior.
-- Accessibility-critical behavior such as labels, keyboard flow, focus, disabled state, or popup reachability.
-- URL state parsing/serialization.
-- Storage persistence or one-shot signals.
-- Regression-prone workflow or generated contract migration paths.
-
-Do not request tests for purely mechanical renames or styling-only changes unless the styling affects layout, focus, or interaction.
-
-## Selectors
-
-Flag:
-
-- `getByTestId` used where role, label, text, placeholder, landmark, or scoped dialog/menu queries are available.
-- Production `data-testid` added only to satisfy tests.
-- Assertions against decorative icons rather than the named control.
-- Tests that cannot find controls semantically but leave broken markup unchanged.
-
-Prefer `getByRole` with accessible name, then `getByLabelText`, `getByPlaceholderText`, `getByText`, and `within(...)`.
-
-## Mocking
-
-Flag:
-
-- Mocking `@langgenius/dify-ui/*` primitives.
-- Mocking `@/app/components/base/*` components when the real component is practical.
-- Mocking sibling or child components in the same directory for integration behavior.
-- Mocks that do not match the real component's conditional rendering.
-- Module-level mock state not reset in `beforeEach`.
-- `vi.clearAllMocks()` in `afterEach` instead of `beforeEach`.
-
-Use real project components for integration behavior. Mock APIs, `next/navigation`, browser shims, or complex providers only when setup would dominate the test.
-
-## Behavior
-
-Flag:
-
-- Tests inspecting implementation details instead of user-observable behavior.
-- Assertions that hardcode brittle copy when pattern matching or semantic roles would express behavior better.
-- Fake timers used without real timing behavior.
-- Async assertions missing `await`, `findBy*`, or `waitFor`.
-- Test data missing required fields because inline partial objects bypass real types.
-
-Use typed factory functions with complete defaults and partial overrides.
-
-## URL State
-
-For `nuqs` or query-state hooks, flag tests that:
-
-- Mock URL state when URL synchronization is the behavior under review.
-- Do not test parser serialize/parse round trips for custom parsers.
-- Do not assert default-clearing behavior when defaults should be removed from the URL.
-
-Prefer shared `NuqsTestingAdapter` helpers when available.
-
-## Organization
-
-Flag:
-
-- Component/hook/util tests outside sibling `__tests__/` directories.
-- Directory-level reviews that test only `index.tsx` while other files in scope contain behavior.
-- Large test files with repeated setup that should use local builders.
-
-When a component is very complex, prefer a refactor finding before asking for exhaustive tests.

.agents/skills/frontend-query-mutation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: frontend-query-mutation
+description: Guide for implementing Dify frontend query and mutation patterns with TanStack Query and oRPC. Trigger when creating or updating contracts in web/contract, wiring router composition, consuming consoleQuery or marketplaceQuery in components or services, deciding whether to call queryOptions()/mutationOptions() directly or extract a helper or use-* hook, configuring oRPC experimental_defaults/default options, handling conditional queries, cache updates/invalidation, mutation error handling, or migrating legacy service calls to contract-first query and mutation helpers.
+---
+
+# Frontend Query & Mutation
+
+## Intent
+
+- Keep contract as the single source of truth in `web/contract/*`.
+- Prefer contract-shaped `queryOptions()` and `mutationOptions()`.
+- Keep default cache behavior with `consoleQuery`/`marketplaceQuery` setup, and keep business orchestration in feature vertical hooks when direct contract calls are not enough.
+- Treat `web/service/use-*` query or mutation wrappers as legacy migration targets, not the preferred destination.
+- Keep abstractions minimal to preserve TypeScript inference.
+
+## Workflow
+
+1. Identify the change surface.
+   - Read `references/contract-patterns.md` for contract files, router composition, client helpers, and query or mutation call-site shape.
+   - Read `references/runtime-rules.md` for conditional queries, default options, cache updates/invalidation, error handling, and legacy migrations.
+   - Read both references when a task spans contract shape and runtime behavior.
+2. Implement the smallest abstraction that fits the task.
+   - Default to direct `useQuery(...)` or `useMutation(...)` calls with oRPC helpers at the call site.
+   - Extract a small shared query helper only when multiple call sites share the same extra options.
+   - Create or keep feature hooks only for real orchestration or shared domain behavior.
+   - When touching thin `web/service/use-*` wrappers, migrate them away when feasible.
+3. Preserve Dify conventions.
+   - Keep contract inputs in `{ params, query?, body? }` shape.
+   - Bind default cache updates/invalidation in `createTanstackQueryUtils(...experimental_defaults...)`; use feature hooks only for workflows that cannot be expressed as default operation behavior.
+   - Prefer `mutate(...)`; use `mutateAsync(...)` only when Promise semantics are required.
+
+## Files Commonly Touched
+
+- `web/contract/console/*.ts`
+- `web/contract/marketplace.ts`
+- `web/contract/router.ts`
+- `web/service/client.ts`
+- legacy `web/service/use-*.ts` files when migrating wrappers away
+- component and hook call sites using `consoleQuery` or `marketplaceQuery`
+
+## References
+
+- Use `references/contract-patterns.md` for contract shape, router registration, query and mutation helpers, and anti-patterns that degrade inference.
+- Use `references/runtime-rules.md` for conditional queries, invalidation, `mutate` versus `mutateAsync`, and legacy migration rules.
+
+Treat this skill as the single query and mutation entry point for Dify frontend work. Keep detailed rules in the reference files instead of duplicating them in project docs.

.agents/skills/frontend-query-mutation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Query & Mutation"
+  short_description: "Dify TanStack Query, oRPC, and default option patterns"
+  default_prompt: "Use this skill when implementing or reviewing Dify frontend contracts, query and mutation call sites, oRPC default options, conditional queries, cache updates/invalidation, or legacy query/mutation migrations."

.agents/skills/frontend-query-mutation/references/contract-patterns.md

@@ -0,0 +1,129 @@
+# Contract Patterns
+
+## Table of Contents
+
+- Intent
+- Minimal structure
+- Core workflow
+- Query usage decision rule
+- Mutation usage decision rule
+- Thin hook decision rule
+- Anti-patterns
+- Contract rules
+- Type export
+
+## Intent
+
+- Keep contract as the single source of truth in `web/contract/*`.
+- Default query usage to call-site `useQuery(consoleQuery|marketplaceQuery.xxx.queryOptions(...))` when endpoint behavior maps 1:1 to the contract.
+- Keep abstractions minimal and preserve TypeScript inference.
+
+## Minimal Structure
+
+```text
+web/contract/
+├── base.ts
+├── router.ts
+├── marketplace.ts
+└── console/
+    ├── billing.ts
+    └── ...other domains
+web/service/client.ts
+```
+
+## Core Workflow
+
+1. Define contract in `web/contract/console/{domain}.ts` or `web/contract/marketplace.ts`.
+   - Use `base.route({...}).output(type<...>())` as the baseline.
+   - Add `.input(type<...>())` only when the request has `params`, `query`, or `body`.
+   - For `GET` without input, omit `.input(...)`; do not use `.input(type<unknown>())`.
+2. Register contract in `web/contract/router.ts`.
+   - Import directly from domain files and nest by API prefix.
+3. Consume from UI call sites via oRPC query utilities.
+
+```typescript
+import { useQuery } from '@tanstack/react-query'
+import { consoleQuery } from '@/service/client'
+
+const invoiceQuery = useQuery(consoleQuery.billing.invoices.queryOptions({
+  staleTime: 5 * 60 * 1000,
+  throwOnError: true,
+  select: invoice => invoice.url,
+}))
+```
+
+## Query Usage Decision Rule
+
+1. Default to direct `*.queryOptions(...)` usage at the call site.
+2. If 3 or more call sites share the same extra options, extract a small query helper, not a `use-*` passthrough hook.
+3. Create or keep feature hooks only for orchestration.
+   - Combine multiple queries or mutations.
+   - Share domain-level derived state or invalidation helpers.
+   - Prefer `web/features/{domain}/hooks/*` for feature-owned workflows.
+4. Treat `web/service/use-{domain}.ts` as legacy.
+   - Do not create new thin service wrappers for oRPC contracts.
+   - When touching existing wrappers, inline direct `consoleQuery` or `marketplaceQuery` consumption when the wrapper is only a passthrough.
+
+```typescript
+const invoicesBaseQueryOptions = () =>
+  consoleQuery.billing.invoices.queryOptions({ retry: false })
+
+const invoiceQuery = useQuery({
+  ...invoicesBaseQueryOptions(),
+  throwOnError: true,
+})
+```
+
+## Mutation Usage Decision Rule
+
+1. Default to mutation helpers from `consoleQuery` or `marketplaceQuery`, for example `useMutation(consoleQuery.billing.bindPartnerStack.mutationOptions(...))`.
+2. If the mutation flow is heavily custom, use oRPC clients as `mutationFn`, for example `consoleClient.xxx` or `marketplaceClient.xxx`, instead of handwritten non-oRPC mutation logic.
+
+```typescript
+const createTagMutation = useMutation(consoleQuery.tags.create.mutationOptions())
+```
+
+## Thin Hook Decision Rule
+
+Remove thin hooks when they only rename a single oRPC query or mutation helper.
+Keep hooks when they orchestrate business behavior across multiple operations, own local workflow state, or normalize a feature-specific API.
+Prefer feature vertical hooks for kept orchestration. Do not move new contract-first wrappers into `web/service/use-*`.
+
+Use:
+
+```typescript
+const deleteTagMutation = useMutation(consoleQuery.tags.delete.mutationOptions())
+```
+
+Keep:
+
+```typescript
+const applyTagBindingsMutation = useApplyTagBindingsMutation()
+```
+
+`useApplyTagBindingsMutation` is acceptable because it coordinates bind and unbind requests, computes deltas, and exposes a feature-level workflow rather than a single endpoint passthrough.
+
+## Anti-Patterns
+
+- Do not wrap `useQuery` with `options?: Partial<UseQueryOptions>`.
+- Do not split local `queryKey` and `queryFn` when oRPC `queryOptions` already exists and fits the use case.
+- Do not create thin `use-*` passthrough hooks for a single endpoint.
+- Do not create business-layer helpers whose only purpose is to call `consoleQuery.xxx.mutationOptions()` or `queryOptions()`.
+- Do not introduce new `web/service/use-*` files for oRPC contract passthroughs.
+- These patterns can degrade inference, especially around `throwOnError` and `select`, and add unnecessary indirection.
+
+## Contract Rules
+
+- Input structure: always use `{ params, query?, body? }`.
+- No-input `GET`: omit `.input(...)`; do not use `.input(type<unknown>())`.
+- Path params: use `{paramName}` in the path and match it in the `params` object.
+- Router nesting: group by API prefix, for example `/billing/*` becomes `billing: {}`.
+- No barrel files: import directly from specific files.
+- Types: import from `@/types/` and use the `type<T>()` helper.
+- Mutations: prefer `mutationOptions`; use explicit `mutationKey` mainly for defaults, filtering, and devtools.
+
+## Type Export
+
+```typescript
+export type ConsoleInputs = InferContractRouterInputs<typeof consoleRouterContract>
+```

.agents/skills/frontend-query-mutation/references/runtime-rules.md

@@ -0,0 +1,172 @@
+# Runtime Rules
+
+## Table of Contents
+
+- Conditional queries
+- oRPC default options
+- Cache invalidation
+- Key API guide
+- `mutate` vs `mutateAsync`
+- Legacy migration
+
+## Conditional Queries
+
+Prefer contract-shaped `queryOptions(...)`.
+When required input is missing, prefer `input: skipToken` instead of placeholder params or non-null assertions.
+Use `enabled` only for extra business gating after the input itself is already valid.
+
+```typescript
+import { skipToken, useQuery } from '@tanstack/react-query'
+
+// Disable the query by skipping input construction.
+function useAccessMode(appId: string | undefined) {
+  return useQuery(consoleQuery.accessControl.appAccessMode.queryOptions({
+    input: appId
+      ? { params: { appId } }
+      : skipToken,
+  }))
+}
+
+// Avoid runtime-only guards that bypass type checking.
+function useBadAccessMode(appId: string | undefined) {
+  return useQuery(consoleQuery.accessControl.appAccessMode.queryOptions({
+    input: { params: { appId: appId! } },
+    enabled: !!appId,
+  }))
+}
+```
+
+## oRPC Default Options
+
+Use `experimental_defaults` in `createTanstackQueryUtils` when a contract operation should always carry shared TanStack Query behavior, such as default stale time, mutation cache writes, or invalidation.
+
+Place defaults at the query utility creation point in `web/service/client.ts`:
+
+```typescript
+export const consoleQuery = createTanstackQueryUtils(consoleClient, {
+  path: ['console'],
+  experimental_defaults: {
+    tags: {
+      create: {
+        mutationOptions: {
+          onSuccess: (tag, _variables, _result, context) => {
+            context.client.setQueryData(
+              consoleQuery.tags.list.queryKey({
+                input: {
+                  query: {
+                    type: tag.type,
+                  },
+                },
+              }),
+              (oldTags: Tag[] | undefined) => oldTags ? [tag, ...oldTags] : oldTags,
+            )
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+Rules:
+
+- Keep defaults inline in the `consoleQuery` or `marketplaceQuery` initialization when they need sibling oRPC key builders.
+- Do not create a wrapper function solely to host `createTanstackQueryUtils`.
+- Do not split defaults into a vertical feature file if that forces handwritten operation paths such as `generateOperationKey(['console', ...])`.
+- Keep feature-level orchestration in the feature vertical; keep query utility lifecycle defaults with the query utility.
+- Prefer call-site callbacks for UI feedback only; shared cache behavior belongs in oRPC defaults when it is tied to a contract operation.
+
+## Cache Invalidation
+
+Bind shared invalidation in oRPC defaults when it is tied to a contract operation.
+Use feature vertical hooks only for multi-operation workflows or domain orchestration that cannot live in a single operation default.
+Components may add UI feedback in call-site callbacks, but they should not decide which queries to invalidate.
+
+Use:
+
+- `.key()` for namespace or prefix invalidation
+- `.queryKey(...)` only for exact cache reads or writes such as `getQueryData` and `setQueryData`
+- `queryClient.invalidateQueries(...)` in mutation `onSuccess`
+
+Do not use deprecated `useInvalid` from `use-base.ts`.
+
+```typescript
+// Feature orchestration owns cache invalidation only when defaults are not enough.
+export const useUpdateAccessMode = () => {
+  const queryClient = useQueryClient()
+
+  return useMutation(consoleQuery.accessControl.updateAccessMode.mutationOptions({
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: consoleQuery.accessControl.appWhitelistSubjects.key(),
+      })
+    },
+  }))
+}
+
+// Component only adds UI behavior.
+updateAccessMode({ appId, mode }, {
+  onSuccess: () => toast.success('...'),
+})
+
+// Avoid putting invalidation knowledge in the component.
+mutate({ appId, mode }, {
+  onSuccess: () => {
+    queryClient.invalidateQueries({
+      queryKey: consoleQuery.accessControl.appWhitelistSubjects.key(),
+    })
+  },
+})
+```
+
+## Key API Guide
+
+- `.key(...)`
+  - Use for partial matching operations.
+  - Prefer it for invalidation, refetch, and cancel patterns.
+  - Example: `queryClient.invalidateQueries({ queryKey: consoleQuery.billing.key() })`
+- `.queryKey(...)`
+  - Use for a specific query's full key.
+  - Prefer it for exact cache addressing and direct reads or writes.
+- `.mutationKey(...)`
+  - Use for a specific mutation's full key.
+  - Prefer it for mutation defaults registration, mutation-status filtering, and devtools grouping.
+
+## `mutate` vs `mutateAsync`
+
+Prefer `mutate` by default.
+Use `mutateAsync` only when Promise semantics are truly required, such as parallel mutations or sequential steps with result dependencies.
+
+Rules:
+
+- Event handlers should usually call `mutate(...)` with `onSuccess` or `onError`.
+- Every `await mutateAsync(...)` must be wrapped in `try/catch`.
+- Do not use `mutateAsync` when callbacks already express the flow clearly.
+
+```typescript
+// Default case.
+mutation.mutate(data, {
+  onSuccess: result => router.push(result.url),
+})
+
+// Promise semantics are required.
+try {
+  const order = await createOrder.mutateAsync(orderData)
+  await confirmPayment.mutateAsync({ orderId: order.id, token })
+  router.push(`/orders/${order.id}`)
+}
+catch (error) {
+  toast.error(error instanceof Error ? error.message : 'Unknown error')
+}
+```
+
+## Legacy Migration
+
+When touching old code, migrate it toward these rules:
+
+| Old pattern | New pattern |
+|---|---|
+| `useInvalid(key)` in service wrappers | oRPC defaults, or a feature vertical hook for real orchestration |
+| component-triggered invalidation after mutation | move invalidation into oRPC defaults or a feature vertical hook |
+| imperative fetch plus manual invalidation | wrap it in `useMutation(...mutationOptions(...))` |
+| `await mutateAsync()` without `try/catch` | switch to `mutate(...)` or add `try/catch` |

.agents/skills/frontend-testing/SKILL.md

@@ -5,7 +5,7 @@ description: Generate Vitest + React Testing Library tests for Dify frontend com
 
 # Dify Frontend Testing Skill
 
-This skill enables Codex to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.
+This skill enables Claude to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.
 
 > **⚠️ Authoritative Source**: This skill is derived from `web/docs/test.md`. Use Vitest mock/timer APIs (`vi.*`).
 
@@ -24,27 +24,35 @@ Apply this skill when the user:
 **Do NOT apply** when:
 
 - User is asking about backend/API tests (Python/pytest)
-- User is asking about E2E tests (Cucumber + Playwright under `e2e/`)
+- User is asking about E2E tests (Playwright/Cypress)
 - User is only asking conceptual questions without code context
 
 ## Quick Reference
 
-### Key Commands
+### Tech Stack
 
-Run these commands from `web/`. From the repository root, prefix them with `pnpm -C web`.
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Vitest | 4.0.16 | Test runner |
+| React Testing Library | 16.0 | Component testing |
+| jsdom | - | Test environment |
+| nock | 14.0 | HTTP mocking |
+| TypeScript | 5.x | Type safety |
+
+### Key Commands
 
 ```bash
 # Run all tests
 pnpm test
 
 # Watch mode
-pnpm test --watch
+pnpm test:watch
 
 # Run specific file
 pnpm test path/to/file.spec.tsx
 
 # Generate coverage report
-pnpm test --coverage
+pnpm test:coverage
 
 # Analyze component complexity
 pnpm analyze-component <path>
@@ -220,10 +228,7 @@ Every test should clearly separate:
 ### 2. Black-Box Testing
 
 - Test observable behavior, not implementation details
-- Use semantic queries (`getByRole` with accessible `name`, `getByLabelText`, `getByPlaceholderText`, `getByText`, and scoped `within(...)`)
-- Treat `getByTestId` as a last resort. If a control cannot be found by role/name, label, landmark, or dialog scope, fix the component accessibility first instead of adding or relying on `data-testid`.
-- Remove production `data-testid` attributes when semantic selectors can cover the behavior. Keep them only for non-visual mocked boundaries, editor/browser shims such as Monaco, canvas/chart output, or third-party widgets with no accessible DOM in the test environment.
-- Do not assert decorative icons by test id. Assert the named control that contains them, or mark decorative icons `aria-hidden`.
+- Use semantic queries (getByRole, getByLabelText)
 - Avoid testing internal state directly
 - **Prefer pattern matching over hardcoded strings** in assertions:
 

.agents/skills/frontend-testing/references/mocking.md

@@ -56,7 +56,7 @@ See [Zustand Store Testing](#zustand-store-testing) section for full details.
 
 | Location | Purpose |
 |----------|---------|
-| `web/vitest.setup.ts` | Global mocks shared by all tests (`react-i18next`, `zustand`, clipboard, FloatingPortal, Monaco, localStorage`) |
+| `web/vitest.setup.ts` | Global mocks shared by all tests (`react-i18next`, `next/image`, `zustand`) |
 | `web/__mocks__/zustand.ts` | Zustand mock implementation (auto-resets stores after each test) |
 | `web/__mocks__/` | Reusable mock factories shared across multiple test files |
 | Test file | Test-specific mocks, inline with `vi.mock()` |
@@ -216,21 +216,28 @@ describe('Component', () => {
 })
 ```
 
-### 5. HTTP and `fetch` Mocking
+### 5. HTTP Mocking with Nock
 
 ```typescript
+import nock from 'nock'
+
+const GITHUB_HOST = 'https://api.github.com'
+const GITHUB_PATH = '/repos/owner/repo'
+
+const mockGithubApi = (status: number, body: Record<string, unknown>, delayMs = 0) => {
+  return nock(GITHUB_HOST)
+    .get(GITHUB_PATH)
+    .delay(delayMs)
+    .reply(status, body)
+}
+
 describe('GithubComponent', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
+  afterEach(() => {
+    nock.cleanAll()
   })
 
   it('should display repo info', async () => {
-    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify({ name: 'dify', stars: 1000 }), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    )
+    mockGithubApi(200, { name: 'dify', stars: 1000 })
     
     render(<GithubComponent />)
     
@@ -240,12 +247,7 @@ describe('GithubComponent', () => {
   })
 
   it('should handle API error', async () => {
-    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify({ message: 'Server error' }), {
-        status: 500,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    )
+    mockGithubApi(500, { message: 'Server error' })
     
     render(<GithubComponent />)
     
@@ -256,8 +258,6 @@ describe('GithubComponent', () => {
 })
 ```
 
-Prefer mocking `@/service/*` modules or spying on `global.fetch` / `ky` clients with deterministic responses. Do not introduce an HTTP interception dependency such as `nock` or MSW unless it is already declared in the workspace or adding it is part of the task.
-
 ### 6. Context Providers
 
 ```typescript
@@ -332,7 +332,7 @@ const renderWithQueryClient = (ui: React.ReactElement) => {
 1. **Don't mock Zustand store modules** - Use real stores with `setState()`
 1. Don't mock components you can import directly
 1. Don't create overly simplified mocks that miss conditional logic
-1. Don't leave HTTP mocks or service mock state leaking between tests
+1. Don't forget to clean up nock after each test
 1. Don't use `any` types in mocks without necessity
 
 ### Mock Decision Tree

.agents/skills/frontend-testing/references/workflow.md

@@ -227,12 +227,12 @@ Failing tests compound:
 
 **Fix failures immediately before proceeding.**
 
-## Integration with Codex's Todo Feature
+## Integration with Claude's Todo Feature
 
-When using Codex for multi-file testing:
+When using Claude for multi-file testing:
 
-1. **Create a todo list** before starting
-1. **Process one file at a time**
+1. **Ask Claude to create a todo list** before starting
+1. **Request one file at a time** or ensure Claude processes incrementally
 1. **Verify each test passes** before asking for the next
 1. **Mark todos complete** as you progress
 

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

@@ -1,71 +0,0 @@
----
-name: how-to-write-component
-description: React/TypeScript component style guide. Use when writing, refactoring, or reviewing React components, especially around props typing, state boundaries, shared local state with Jotai atoms, API types, query/mutation contracts, navigation, memoization, wrappers, and empty-state handling.
----
-
-# How To Write A Component
-
-Use this as the decision guide for React/TypeScript component structure. Existing code is reference material, not automatic precedent; when it conflicts with these rules, adapt the approach instead of reproducing the violation.
-
-## Core Defaults
-
-- Search before adding UI, hooks, helpers, or styling patterns. Reuse existing base components, feature components, hooks, utilities, and design styles when they fit.
-- Group code by feature workflow, route, or ownership area: components, hooks, local types, query helpers, atoms, constants, and small utilities should live near the code that changes with them.
-- Promote code to shared only when multiple verticals need the same stable primitive. Otherwise keep it local and compose shared primitives inside the owning feature.
-- Follow Dify's CSS-first Tailwind v4 contract from `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md`. Prefer design-system tokens, utilities, and radius mappings over generic Tailwind guidance.
-
-## Ownership
-
-- Put local state, queries, mutations, handlers, and derived UI data in the lowest component that uses them. Extract a purpose-built owner component only when the logic has no natural home.
-- Repeated TanStack query calls in sibling components are acceptable when each component independently consumes the data. Do not hoist a query only because it is duplicated; TanStack Query handles deduplication and cache sharing.
-- Hoist state, queries, or callbacks to a parent only when the parent consumes the data, coordinates shared loading/error/empty UI, needs one consistent snapshot, or owns a workflow spanning children.
-- Avoid prop drilling. One pass-through layer is acceptable; repeated forwarding means ownership should move down or into feature-scoped Jotai UI state. Keep server/cache state in query and API data flow.
-- Keep callbacks in a parent only for workflow coordination such as form submission, shared selection, batch behavior, or navigation. Otherwise let the child or row own its action.
-- Prefer uncontrolled DOM state and CSS variables before adding controlled props.
-
-## Components, Props, And Types
-
-- Type component signatures directly; do not use `FC` or `React.FC`.
-- Prefer `function` for top-level components and module helpers. Use arrow functions for local callbacks, handlers, and lambda-style APIs.
-- Prefer named exports. Use default exports only where the framework requires them, such as Next.js route files.
-- Type simple one-off props inline. Use a named `Props` type only when reused, exported, complex, or clearer.
-- Use API-generated or API-returned types at component boundaries. Keep small UI conversion helpers beside the component that needs them.
-- Name values by their domain role and backend API contract, and keep that name stable across the call chain, especially IDs like `appInstanceId`. Normalize framework or route params at the boundary.
-- Keep fallback and invariant checks at the lowest component that already handles that state; callers should pass raw values through instead of duplicating checks.
-
-## Queries And Mutations
-
-- Keep `web/contract/*` as the single source of truth for API shape; follow existing domain/router patterns and the `{ params, query?, body? }` input shape.
-- Consume queries directly with `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))`.
-- Avoid pass-through hooks and thin `web/service/use-*` wrappers that only rename `queryOptions()` or `mutationOptions()`. Extract a small `queryOptions` helper only when repeated call-site options justify it.
-- Keep feature hooks for real orchestration, workflow state, or shared domain behavior.
-- For missing required query input, use `input: skipToken`; use `enabled` only for extra business gating after the input is valid.
-- Consume mutations directly with `useMutation(consoleQuery.xxx.mutationOptions(...))` or `useMutation(marketplaceQuery.xxx.mutationOptions(...))`; use oRPC clients as `mutationFn` only for custom flows.
-- Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`; components may add UI feedback callbacks, but should not own shared invalidation rules.
-- Do not use deprecated `useInvalid` or `useReset`.
-- Prefer `mutate(...)`; use `mutateAsync(...)` only when Promise semantics are required, and wrap awaited calls in `try/catch`.
-
-## Component Boundaries
-
-- Use the first level below a page or tab to organize independent page sections when it adds real structure. This layer is layout/semantic first, not automatically the data owner.
-- Split deeper components by the data and state each layer actually needs. Each component should access only necessary data, and ownership should stay at the lowest consumer.
-- Keep cohesive forms, menu bodies, and one-off helpers local unless they need their own state, reuse, or semantic boundary.
-- Separate hidden secondary surfaces from the trigger's main flow. For dialogs, dropdowns, popovers, and similar branches, extract a small local component that owns the trigger, open state, and hidden content when it would obscure the parent flow.
-- Preserve composability by separating behavior ownership from layout ownership. A dropdown action may own its trigger, open state, and menu content; the caller owns placement such as slots, offsets, and alignment.
-- Avoid unnecessary DOM hierarchy. Do not add wrapper elements unless they provide layout, semantics, accessibility, state ownership, or integration with a library API; prefer fragments or styling an existing element when possible.
-- Avoid shallow wrappers and prop renaming unless the wrapper adds validation, orchestration, error handling, state ownership, or a real semantic boundary.
-
-## You Might Not Need An Effect
-
-- Use Effects only to synchronize with external systems such as browser APIs, non-React widgets, subscriptions, timers, analytics that must run because the component was shown, or imperative DOM integration.
-- Do not use Effects to transform props or state for rendering. Calculate derived values during render, and use `useMemo` only when the calculation is actually expensive.
-- Do not use Effects to handle user actions. Put action-specific logic in the event handler where the cause is known.
-- Do not use Effects to copy one state value into another state value representing the same concept. Pick one source of truth and derive the rest during render.
-- Do not reset or adjust state from props with an Effect. Prefer a `key` reset, storing a stable ID and deriving the selected object, or guarded same-component render-time adjustment when truly necessary.
-- Prefer framework data APIs or TanStack Query for data fetching instead of writing request Effects in components.
-- If an Effect still seems necessary, first name the external system it synchronizes with. If there is no external system, remove the Effect and restructure the state or event flow.
-
-## Navigation And Performance
-
-- Prefer `Link` for normal navigation. Use router APIs only for command-flow side effects such as mutation success, guarded redirects, or form submission.
-- Avoid `memo`, `useMemo`, and `useCallback` unless there is a clear performance reason.

.claude/skills/frontend-query-mutation

@@ -0,0 +1 @@
+../../.agents/skills/frontend-query-mutation

.claude/skills/how-to-write-component

@@ -1 +0,0 @@
-../../.agents/skills/how-to-write-component

.coveragerc

@@ -1,6 +1,5 @@
 [run]
 omit =
-    api/conftest.py
     api/tests/*
     api/migrations/*
     api/core/rag/datasource/vdb/*

.dockerignore

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

.gitattributes

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

.github/CODEOWNERS

@@ -4,7 +4,7 @@
 # Owners can be @username, @org/team-name, or email addresses.
 # For more information, see: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
-* @crazywoola @laipz8200
+* @crazywoola @laipz8200 @Yeuoly
 
 # ESLint suppression file is maintained by autofix.ci pruning.
 /eslint-suppressions.json
@@ -18,10 +18,6 @@
 # Docs
 /docs/ @crazywoola
 
-# CLI
-/cli/ @langgenius/maintainers
-/.github/workflows/cli-tests.yml @langgenius/maintainers
-
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost
 
@@ -89,39 +85,39 @@
 /api/tasks/deal_dataset_vector_index_task.py @JohnJyong
 
 # Backend - Plugins
-/api/core/plugin/ @WH-2099
-/api/services/plugin/ @WH-2099
-/api/controllers/console/workspace/plugin.py @WH-2099
-/api/controllers/inner_api/plugin/ @WH-2099
-/api/tasks/process_tenant_plugin_autoupgrade_check_task.py @WH-2099
+/api/core/plugin/ @Mairuis @Yeuoly @Stream29
+/api/services/plugin/ @Mairuis @Yeuoly @Stream29
+/api/controllers/console/workspace/plugin.py @Mairuis @Yeuoly @Stream29
+/api/controllers/inner_api/plugin/ @Mairuis @Yeuoly @Stream29
+/api/tasks/process_tenant_plugin_autoupgrade_check_task.py @Mairuis @Yeuoly @Stream29
 
 # Backend - Trigger/Schedule/Webhook
-/api/controllers/trigger/ @CourTeous33
-/api/controllers/console/app/workflow_trigger.py @CourTeous33
-/api/controllers/console/workspace/trigger_providers.py @CourTeous33
-/api/core/trigger/ @CourTeous33
-/api/core/app/layers/trigger_post_layer.py @CourTeous33
-/api/services/trigger/ @CourTeous33
-/api/models/trigger.py @CourTeous33
-/api/fields/workflow_trigger_fields.py @CourTeous33
-/api/repositories/workflow_trigger_log_repository.py @CourTeous33
-/api/repositories/sqlalchemy_workflow_trigger_log_repository.py @CourTeous33
-/api/libs/schedule_utils.py @CourTeous33
-/api/services/workflow/scheduler.py @CourTeous33
-/api/schedule/trigger_provider_refresh_task.py @CourTeous33
-/api/schedule/workflow_schedule_task.py @CourTeous33
-/api/tasks/trigger_processing_tasks.py @CourTeous33
-/api/tasks/trigger_subscription_refresh_tasks.py @CourTeous33
-/api/tasks/workflow_schedule_tasks.py @CourTeous33
-/api/tasks/workflow_cfs_scheduler/ @CourTeous33
-/api/events/event_handlers/sync_plugin_trigger_when_app_created.py @CourTeous33
-/api/events/event_handlers/update_app_triggers_when_app_published_workflow_updated.py @CourTeous33
-/api/events/event_handlers/sync_workflow_schedule_when_app_published.py @CourTeous33
-/api/events/event_handlers/sync_webhook_when_app_created.py @CourTeous33
+/api/controllers/trigger/ @Mairuis @Yeuoly
+/api/controllers/console/app/workflow_trigger.py @Mairuis @Yeuoly
+/api/controllers/console/workspace/trigger_providers.py @Mairuis @Yeuoly
+/api/core/trigger/ @Mairuis @Yeuoly
+/api/core/app/layers/trigger_post_layer.py @Mairuis @Yeuoly
+/api/services/trigger/ @Mairuis @Yeuoly
+/api/models/trigger.py @Mairuis @Yeuoly
+/api/fields/workflow_trigger_fields.py @Mairuis @Yeuoly
+/api/repositories/workflow_trigger_log_repository.py @Mairuis @Yeuoly
+/api/repositories/sqlalchemy_workflow_trigger_log_repository.py @Mairuis @Yeuoly
+/api/libs/schedule_utils.py @Mairuis @Yeuoly
+/api/services/workflow/scheduler.py @Mairuis @Yeuoly
+/api/schedule/trigger_provider_refresh_task.py @Mairuis @Yeuoly
+/api/schedule/workflow_schedule_task.py @Mairuis @Yeuoly
+/api/tasks/trigger_processing_tasks.py @Mairuis @Yeuoly
+/api/tasks/trigger_subscription_refresh_tasks.py @Mairuis @Yeuoly
+/api/tasks/workflow_schedule_tasks.py @Mairuis @Yeuoly
+/api/tasks/workflow_cfs_scheduler/ @Mairuis @Yeuoly
+/api/events/event_handlers/sync_plugin_trigger_when_app_created.py @Mairuis @Yeuoly
+/api/events/event_handlers/update_app_triggers_when_app_published_workflow_updated.py @Mairuis @Yeuoly
+/api/events/event_handlers/sync_workflow_schedule_when_app_published.py @Mairuis @Yeuoly
+/api/events/event_handlers/sync_webhook_when_app_created.py @Mairuis @Yeuoly
 
 # Backend - Async Workflow
-/api/services/async_workflow_service.py @Mairuis
-/api/tasks/async_workflow_tasks.py @Mairuis
+/api/services/async_workflow_service.py @Mairuis @Yeuoly
+/api/tasks/async_workflow_tasks.py @Mairuis @Yeuoly
 
 # Backend - Billing
 /api/services/billing_service.py @hj24 @zyssyz123
@@ -166,7 +162,6 @@
 
 # Frontend - App - API Documentation
 /web/app/components/develop/ @JzoNgKVO @iamjoel
-/web/app/components/develop/template/*.mdx @JzoNgKVO @iamjoel @RiskeyL
 
 # Frontend - App - Logs and Annotations
 /web/app/components/app/workflow-log/ @JzoNgKVO @iamjoel

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

@@ -1,15 +1,10 @@
 name: Setup Web Environment
-description: Set up Node.js, Vite+, pnpm, and web dependencies
 
 runs:
   using: composite
   steps:
-    - name: Setup pnpm
-      uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
-      with:
-        run_install: false
     - name: Setup Vite+
-      uses: voidzero-dev/setup-vp@ca1c46663915d6c1042ae23bd39ab85718bfb0fa # v1.10.0
+      uses: voidzero-dev/setup-vp@4f5aa3e38c781f1b01e78fb9255527cee8a6efa6 # v1.8.0
       with:
         node-version-file: .nvmrc
         cache: true

.github/dependabot.yml

@@ -110,114 +110,3 @@ updates:
       github-actions-dependencies:
         patterns:
           - "*"
-  - package-ecosystem: "uv"
-    directory: "/api"
-    target-branch: "lts/1.13.x"
-    open-pull-requests-limit: 10
-    schedule:
-      interval: "weekly"
-    groups:
-      flask:
-        patterns:
-          - "flask"
-          - "flask-*"
-          - "werkzeug"
-          - "gunicorn"
-      google:
-        patterns:
-          - "google-*"
-          - "googleapis-*"
-      opentelemetry:
-        patterns:
-          - "opentelemetry-*"
-      pydantic:
-        patterns:
-          - "pydantic"
-          - "pydantic-*"
-      llm:
-        patterns:
-          - "langfuse"
-          - "langsmith"
-          - "litellm"
-          - "mlflow*"
-          - "opik"
-          - "weave*"
-          - "arize*"
-          - "tiktoken"
-          - "transformers"
-      database:
-        patterns:
-          - "sqlalchemy"
-          - "psycopg2*"
-          - "psycogreen"
-          - "redis*"
-          - "alembic*"
-      storage:
-        patterns:
-          - "boto3*"
-          - "botocore*"
-          - "azure-*"
-          - "bce-*"
-          - "cos-python-*"
-          - "esdk-obs-*"
-          - "google-cloud-storage"
-          - "opendal"
-          - "oss2"
-          - "supabase*"
-          - "tos*"
-      vdb:
-        patterns:
-          - "alibabacloud*"
-          - "chromadb"
-          - "clickhouse-*"
-          - "clickzetta-*"
-          - "couchbase"
-          - "elasticsearch"
-          - "opensearch-py"
-          - "oracledb"
-          - "pgvect*"
-          - "pymilvus"
-          - "pymochow"
-          - "pyobvector"
-          - "qdrant-client"
-          - "intersystems-*"
-          - "tablestore"
-          - "tcvectordb"
-          - "tidb-vector"
-          - "upstash-*"
-          - "volcengine-*"
-          - "weaviate-*"
-          - "xinference-*"
-          - "mo-vector"
-          - "mysql-connector-*"
-      dev:
-        patterns:
-          - "coverage"
-          - "dotenv-linter"
-          - "faker"
-          - "lxml-stubs"
-          - "basedpyright"
-          - "ruff"
-          - "pytest*"
-          - "types-*"
-          - "boto3-stubs"
-          - "hypothesis"
-          - "pandas-stubs"
-          - "scipy-stubs"
-          - "import-linter"
-          - "celery-types"
-          - "mypy*"
-          - "pyrefly"
-      python-packages:
-        patterns:
-          - "*"
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    target-branch: "lts/1.13.x"
-    open-pull-requests-limit: 5
-    schedule:
-      interval: "weekly"
-    groups:
-      github-actions-dependencies:
-        patterns:
-          - "*"

.github/scripts/check-hotfix-cherry-picks.sh

@@ -1,73 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-BASE_SHA=${BASE_SHA:-}
-HEAD_SHA=${HEAD_SHA:-}
-MAIN_REF=${MAIN_REF:-origin/main}
-REMEDIATION_HINT="Changes should be made from the main branch using git cherry-pick -x."
-
-error() {
-  printf 'ERROR: %s\n' "$1" >&2
-}
-
-if [[ -z "$BASE_SHA" || -z "$HEAD_SHA" ]]; then
-  error "BASE_SHA and HEAD_SHA are required. $REMEDIATION_HINT"
-  exit 2
-fi
-
-if ! git rev-parse --verify "$BASE_SHA^{commit}" > /dev/null 2>&1; then
-  error "Base commit '$BASE_SHA' is not available in the local git checkout."
-  exit 2
-fi
-
-if ! git rev-parse --verify "$HEAD_SHA^{commit}" > /dev/null 2>&1; then
-  error "Head commit '$HEAD_SHA' is not available in the local git checkout."
-  exit 2
-fi
-
-if ! git rev-parse --verify "$MAIN_REF^{commit}" > /dev/null 2>&1; then
-  error "Main ref '$MAIN_REF' is not available in the local git checkout. $REMEDIATION_HINT"
-  exit 2
-fi
-
-failed=0
-checked=0
-
-while IFS= read -r commit_sha; do
-  [[ -n "$commit_sha" ]] || continue
-
-  checked=$((checked + 1))
-  subject=$(git log -1 --format=%s "$commit_sha")
-  source_sha=$(
-    git log -1 --format=%B "$commit_sha" \
-      | sed -nE 's/^\(cherry picked from commit ([0-9a-fA-F]{7,64})\)$/\1/p' \
-      | tail -n 1
-  )
-
-  if [[ -z "$source_sha" ]]; then
-    error "Commit $commit_sha ($subject) is missing cherry-pick provenance. $REMEDIATION_HINT"
-    failed=1
-    continue
-  fi
-
-  if ! git cat-file -e "$source_sha^{commit}" 2> /dev/null; then
-    error "Commit $commit_sha ($subject) references source $source_sha, but that commit is not available locally. $REMEDIATION_HINT"
-    failed=1
-    continue
-  fi
-
-  if ! git merge-base --is-ancestor "$source_sha" "$MAIN_REF"; then
-    error "Commit $commit_sha ($subject) references source $source_sha, but that source is not reachable from main ($MAIN_REF). $REMEDIATION_HINT"
-    failed=1
-  fi
-done < <(git rev-list --reverse "$BASE_SHA..$HEAD_SHA")
-
-if [[ "$failed" -ne 0 ]]; then
-  exit 1
-fi
-
-if [[ "$checked" -eq 0 ]]; then
-  echo "No PR commits to check."
-else
-  echo "Verified $checked PR commit(s) include cherry-pick provenance from main."
-fi

.github/workflows/api-tests.yml

@@ -48,23 +48,10 @@ jobs:
         run: uv sync --project api --dev
 
       - name: Run dify config tests
-        run: uv run --project api pytest api/tests/unit_tests/configs/test_env_consistency.py
+        run: uv run --project api dev/pytest/pytest_config_tests.py
 
       - name: Run Unit Tests
-        run: |
-          uv run --project api pytest \
-            -p no:benchmark \
-            --timeout "${PYTEST_TIMEOUT:-20}" \
-            -n auto \
-            api/tests/unit_tests \
-            api/providers/vdb/*/tests/unit_tests \
-            api/providers/trace/*/tests/unit_tests \
-            --ignore=api/tests/unit_tests/controllers
-          # Controller tests register Flask routes at import time, so keep them out of xdist.
-          uv run --project api pytest \
-            --timeout "${PYTEST_TIMEOUT:-20}" \
-            --cov-append \
-            api/tests/unit_tests/controllers
+        run: uv run --project api bash dev/pytest/pytest_unit_tests.sh
 
       - name: Upload unit coverage data
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -109,11 +96,32 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
+      - name: Set up dotenvs
+        run: |
+          cp docker/.env.example docker/.env
+          cp docker/envs/middleware.env.example docker/middleware.env
+
+      - name: Expose Service Ports
+        run: sh .github/workflows/expose_service_ports.sh
+
+      - name: Set up Sandbox
+        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        with:
+          compose-file: |
+            docker/docker-compose.middleware.yaml
+          services: |
+            db_postgres
+            redis
+            sandbox
+            ssrf_proxy
+
+      - name: setup test config
+        run: |
+          cp api/tests/integration_tests/.env.example api/tests/integration_tests/.env
+
       - name: Run Integration Tests
         run: |
           uv run --project api pytest \
-            -p no:benchmark \
-            --start-middleware \
             -n auto \
             --timeout "${PYTEST_TIMEOUT:-180}" \
             api/tests/integration_tests/workflow \
@@ -195,7 +203,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
         with:
           files: ./coverage.xml
           disable_search: true

.github/workflows/autofix.yml

@@ -51,15 +51,6 @@ jobs:
         with:
           files: |
             api/**
-      - name: Check dify-agent inputs
-        if: github.event_name != 'merge_group'
-        id: dify-agent-changes
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            dify-agent/**/*.py
-            dify-agent/pyproject.toml
-            dify-agent/uv.lock
       - if: github.event_name != 'merge_group'
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
@@ -85,17 +76,6 @@ jobs:
           # Format code
           uv run ruff format ..
 
-      - if: github.event_name != 'merge_group' && steps.dify-agent-changes.outputs.any_changed == 'true'
-        run: |
-          cd dify-agent
-          uv sync --dev
-          # fmt first to avoid line too long
-          uv run ruff format .
-          # Fix lint errors
-          uv run ruff check --fix .
-          # Format code
-          uv run ruff format .
-
       - name: count migration progress
         if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
         run: |
@@ -140,11 +120,7 @@ jobs:
         if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
         run: |
           cd api
-          uv run dev/generate_swagger_markdown_docs.py --swagger-dir ../packages/contracts/openapi --markdown-dir openapi/markdown --keep-swagger-json
-
-      - name: Generate frontend contracts
-        if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
-        run: pnpm --dir packages/contracts gen-api-contract-from-openapi
+          uv run dev/generate_swagger_markdown_docs.py --swagger-dir openapi --markdown-dir openapi/markdown
 
       - name: ESLint autofix
         if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'

.github/workflows/build-push.yml

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

.github/workflows/cli-release.yml

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

.github/workflows/cli-smoke.yml

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

.github/workflows/cli-tests.yml

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

.github/workflows/deploy-agent-dev.yml

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

.github/workflows/docker-build.yml

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

.github/workflows/expose_service_ports.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+yq eval '.services.weaviate.ports += ["8080:8080"]' -i docker/docker-compose.yaml
+yq eval '.services.weaviate.ports += ["50051:50051"]' -i docker/docker-compose.yaml
+yq eval '.services.qdrant.ports += ["6333:6333"]' -i docker/docker-compose.yaml
+yq eval '.services.chroma.ports += ["8000:8000"]' -i docker/docker-compose.yaml
+yq eval '.services["milvus-standalone"].ports += ["19530:19530"]' -i docker/docker-compose.yaml
+yq eval '.services.pgvector.ports += ["5433:5432"]' -i docker/docker-compose.yaml
+yq eval '.services["pgvecto-rs"].ports += ["5431:5432"]' -i docker/docker-compose.yaml
+yq eval '.services["elasticsearch"].ports += ["9200:9200"]' -i docker/docker-compose.yaml
+yq eval '.services.couchbase-server.ports += ["8091-8096:8091-8096"]' -i docker/docker-compose.yaml
+yq eval '.services.couchbase-server.ports += ["11210:11210"]' -i docker/docker-compose.yaml
+yq eval '.services.tidb.ports += ["4000:4000"]' -i docker/tidb/docker-compose.yaml
+yq eval '.services.oceanbase.ports += ["2881:2881"]' -i docker/docker-compose.yaml
+yq eval '.services.opengauss.ports += ["6600:6600"]' -i docker/docker-compose.yaml
+
+echo "Ports exposed for sandbox, weaviate (HTTP 8080, gRPC 50051), tidb, qdrant, chroma, milvus, pgvector, pgvecto-rs, elasticsearch, couchbase, opengauss"

.github/workflows/hotfix-cherry-pick.yml

@@ -1,49 +0,0 @@
-name: Hotfix Cherry-Pick Provenance
-
-on:
-  pull_request:
-    branches:
-      - 'hotfix/**'
-      - 'lts/**'
-    types:
-      - opened
-      - edited
-      - reopened
-      - ready_for_review
-      - synchronize
-
-permissions:
-  contents: read
-
-concurrency:
-  group: hotfix-cherry-pick-${{ github.event.pull_request.number || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  check-cherry-pick-provenance:
-    name: Require cherry-pick provenance
-    runs-on: depot-ubuntu-24.04
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-
-      - name: Fetch PR base, PR head, and main
-        env:
-          BASE_REF: ${{ github.base_ref }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-          git fetch --no-tags --prune origin \
-            "+refs/heads/main:refs/remotes/origin/main" \
-            "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}" \
-            "+refs/pull/${PR_NUMBER}/head:refs/remotes/pull/${PR_NUMBER}/head"
-
-      - name: Load checker from main
-        run: git show origin/main:.github/scripts/check-hotfix-cherry-picks.sh > "$RUNNER_TEMP/check-hotfix-cherry-picks.sh"
-
-      - name: Check PR commits
-        env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          MAIN_REF: origin/main
-        run: bash "$RUNNER_TEMP/check-hotfix-cherry-picks.sh"

.github/workflows/labeler.yml

@@ -9,6 +9,6 @@ jobs:
       pull-requests: write
     runs-on: depot-ubuntu-24.04
     steps:
-      - uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6.1.0
+      - uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
         with:
           sync-labels: true

.github/workflows/main-ci.yml

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

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

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

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

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

.github/workflows/style.yml

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

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

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

.github/workflows/vdb-tests-full.yml

@@ -48,6 +48,14 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
+      - name: Set up dotenvs
+        run: |
+          cp docker/.env.example docker/.env
+          cp docker/envs/middleware.env.example docker/middleware.env
+
+      - name: Expose Service Ports
+        run: sh .github/workflows/expose_service_ports.sh
+
 #      - name: Set up Vector Store (TiDB)
 #        uses: hoverkraft-tech/compose-action@v2.0.2
 #        with:
@@ -56,13 +64,32 @@ jobs:
 #            tidb
 #            tiflash
 
+      - name: Set up Full Vector Store Matrix
+        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        with:
+          compose-file: |
+            docker/docker-compose.yaml
+          services: |
+            weaviate
+            qdrant
+            couchbase-server
+            etcd
+            minio
+            milvus-standalone
+            pgvecto-rs
+            pgvector
+            chroma
+            elasticsearch
+            oceanbase
+
+      - name: setup test config
+        run: |
+          echo $(pwd)
+          ls -lah .
+          cp api/tests/integration_tests/.env.example api/tests/integration_tests/.env
+
 #      - name: Check VDB Ready (TiDB)
 #        run: uv run --project api python api/providers/vdb/tidb-vector/tests/integration_tests/check_tiflash_ready.py
 
       - name: Test Vector Stores
-        run: |
-          uv run --project api pytest \
-            --start-vdb \
-            --vdb-services "weaviate,qdrant,couchbase-server,etcd,minio,milvus-standalone,pgvecto-rs,pgvector,chroma,elasticsearch,oceanbase" \
-            --timeout "${PYTEST_TIMEOUT:-180}" \
-            api/providers/vdb/*/tests/integration_tests
+        run: uv run --project api bash dev/pytest/pytest_vdb.sh

.github/workflows/vdb-tests.yml

@@ -45,6 +45,14 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
+      - name: Set up dotenvs
+        run: |
+          cp docker/.env.example docker/.env
+          cp docker/envs/middleware.env.example docker/middleware.env
+
+      - name: Expose Service Ports
+        run: sh .github/workflows/expose_service_ports.sh
+
 #      - name: Set up Vector Store (TiDB)
 #        uses: hoverkraft-tech/compose-action@v2.0.2
 #        with:
@@ -53,14 +61,31 @@ jobs:
 #            tidb
 #            tiflash
 
+      - name: Set up Vector Stores for Smoke Coverage
+        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        with:
+          compose-file: |
+            docker/docker-compose.yaml
+          services: |
+            db_postgres
+            redis
+            weaviate
+            qdrant
+            pgvector
+            chroma
+
+      - name: setup test config
+        run: |
+          echo $(pwd)
+          ls -lah .
+          cp api/tests/integration_tests/.env.example api/tests/integration_tests/.env
+
 #      - name: Check VDB Ready (TiDB)
 #        run: uv run --project api python api/providers/vdb/tidb-vector/tests/integration_tests/check_tiflash_ready.py
 
       - name: Test Vector Stores
         run: |
-          uv run --project api pytest \
-            --start-vdb \
-            --timeout "${PYTEST_TIMEOUT:-180}" \
+          uv run --project api pytest --timeout "${PYTEST_TIMEOUT:-180}" \
             api/providers/vdb/vdb-chroma/tests/integration_tests \
             api/providers/vdb/vdb-pgvector/tests/integration_tests \
             api/providers/vdb/vdb-qdrant/tests/integration_tests \

.github/workflows/web-tests.yml

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

.gitignore

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

AGENTS.md

@@ -9,7 +9,6 @@ The codebase is split into:
 - **Backend API** (`/api`): Python Flask application organized with Domain-Driven Design
 - **Frontend Web** (`/web`): Next.js application using TypeScript and React
 - **Docker deployment** (`/docker`): Containerized deployment configurations
-- **Dify Agent Backend** (`/dify-agent`): Backend services for managing and executing agent
 
 ## Backend Workflow
 

Makefile

@@ -3,10 +3,6 @@ DOCKER_REGISTRY=langgenius
 WEB_IMAGE=$(DOCKER_REGISTRY)/dify-web
 API_IMAGE=$(DOCKER_REGISTRY)/dify-api
 VERSION=latest
-DOCKER_DIR=docker
-DOCKER_MIDDLEWARE_ENV=$(DOCKER_DIR)/middleware.env
-DOCKER_MIDDLEWARE_ENV_EXAMPLE=$(DOCKER_DIR)/envs/middleware.env.example
-DOCKER_MIDDLEWARE_PROJECT=dify-middlewares-dev
 
 # Default target - show help
 .DEFAULT_GOAL := help
@@ -21,13 +17,8 @@ dev-setup: prepare-docker prepare-web prepare-api
 # Step 1: Prepare Docker middleware
 prepare-docker:
 	@echo "🐳 Setting up Docker middleware..."
-	@if [ ! -f "$(DOCKER_MIDDLEWARE_ENV)" ]; then \
-		cp "$(DOCKER_MIDDLEWARE_ENV_EXAMPLE)" "$(DOCKER_MIDDLEWARE_ENV)"; \
-		echo "Docker middleware.env created"; \
-	else \
-		echo "Docker middleware.env already exists"; \
-	fi
-	@cd $(DOCKER_DIR) && docker compose -f docker-compose.middleware.yaml --env-file middleware.env -p $(DOCKER_MIDDLEWARE_PROJECT) up -d
+	@cp -n docker/middleware.env.example docker/middleware.env 2>/dev/null || echo "Docker middleware.env already exists"
+	@cd docker && docker compose -f docker-compose.middleware.yaml --env-file middleware.env -p dify-middlewares-dev up -d
 	@echo "✅ Docker middleware started"
 
 # Step 2: Prepare web environment
@@ -48,18 +39,12 @@ prepare-api:
 # Clean dev environment
 dev-clean:
 	@echo "⚠️  Stopping Docker containers..."
-	@if [ -f "$(DOCKER_MIDDLEWARE_ENV)" ]; then \
-		cd $(DOCKER_DIR) && docker compose -f docker-compose.middleware.yaml --env-file middleware.env -p $(DOCKER_MIDDLEWARE_PROJECT) down; \
-	else \
-		echo "Docker middleware.env does not exist, skipping compose down"; \
-	fi
+	@cd docker && docker compose -f docker-compose.middleware.yaml --env-file middleware.env -p dify-middlewares-dev down
 	@echo "🗑️  Removing volumes..."
 	@rm -rf docker/volumes/db
-	@rm -rf docker/volumes/mysql
 	@rm -rf docker/volumes/redis
 	@rm -rf docker/volumes/plugin_daemon
 	@rm -rf docker/volumes/weaviate
-	@rm -rf docker/volumes/sandbox/dependencies
 	@rm -rf api/storage
 	@echo "✅ Cleanup complete"
 
@@ -75,29 +60,24 @@ check:
 	@echo "✅ Code check complete"
 
 lint:
-	@echo "🔧 Running ruff format, check with fixes, response contract lint, import linter, and dotenv-linter..."
+	@echo "🔧 Running ruff format, check with fixes, import linter, and dotenv-linter..."
 	@uv run --project api --dev ruff format ./api
 	@uv run --project api --dev ruff check --fix ./api
-	@$(MAKE) api-contract-lint
 	@uv run --directory api --dev lint-imports
 	@uv run --project api --dev dotenv-linter ./api/.env.example ./web/.env.example
 	@echo "✅ Linting complete"
 
-api-contract-lint:
-	@echo "🔎 Linting Flask response contracts..."
-	@uv run --project api --dev python api/dev/lint_response_contracts.py
-	@echo "✅ Response contract lint complete"
-
 type-check:
-	@echo "📝 Running type checks (pyrefly + mypy)..."
-	@./dev/pyrefly-check-local $(PATH_TO_CHECK)
-	@uv --directory api run mypy --exclude-gitignore --exclude '(^|/)conftest\.py$$' --exclude 'tests/' --exclude 'migrations/' --exclude 'dev/generate_swagger_specs.py' --exclude 'dev/generate_fastopenapi_specs.py' --check-untyped-defs --disable-error-code=import-untyped .
+	@echo "📝 Running type checks (basedpyright + pyrefly + mypy)..."
+	@./dev/basedpyright-check $(PATH_TO_CHECK)
+	@./dev/pyrefly-check-local
+	@uv --directory api run mypy --exclude-gitignore --exclude 'tests/' --exclude 'migrations/' --exclude 'dev/generate_swagger_specs.py' --check-untyped-defs --disable-error-code=import-untyped .
 	@echo "✅ Type checks complete"
 
 type-check-core:
-	@echo "📝 Running core type checks (pyrefly + mypy)..."
-	@./dev/pyrefly-check-local $(PATH_TO_CHECK)
-	@uv --directory api run mypy --exclude-gitignore --exclude '(^|/)conftest\.py$$' --exclude 'tests/' --exclude 'migrations/' --exclude 'dev/generate_swagger_specs.py' --exclude 'dev/generate_fastopenapi_specs.py' --check-untyped-defs --disable-error-code=import-untyped .
+	@echo "📝 Running core type checks (basedpyright + mypy)..."
+	@./dev/basedpyright-check $(PATH_TO_CHECK)
+	@uv --directory api run mypy --exclude-gitignore --exclude 'tests/' --exclude 'migrations/' --exclude 'dev/generate_swagger_specs.py'  --exclude 'dev/generate_fastopenapi_specs.py' --check-untyped-defs --disable-error-code=import-untyped .
 	@echo "✅ Core type checks complete"
 
 test:
@@ -106,46 +86,7 @@ test:
 		echo "Target: $(TARGET_TESTS)"; \
 		uv run --project api --dev pytest $(TARGET_TESTS); \
 	else \
-		echo "Running backend unit tests"; \
-		uv run --project api --dev pytest -p no:benchmark --timeout "$${PYTEST_TIMEOUT:-20}" -n auto \
-			api/tests/unit_tests \
-			api/providers/vdb/*/tests/unit_tests \
-			api/providers/trace/*/tests/unit_tests \
-			--ignore=api/tests/unit_tests/controllers; \
-		uv run --project api --dev pytest --timeout "$${PYTEST_TIMEOUT:-20}" --cov-append \
-			api/tests/unit_tests/controllers; \
-	fi
-	@echo "✅ Unit tests complete"
-
-test-all:
-	@echo "🧪 Running full backend test suite..."
-	@if [ -n "$(TARGET_TESTS)" ]; then \
-		echo "Target: $(TARGET_TESTS)"; \
-		uv run --project api --dev pytest $(TARGET_TESTS); \
-	else \
-		echo "Running backend unit tests"; \
-		uv run --project api --dev pytest -p no:benchmark --timeout "$${PYTEST_TIMEOUT:-20}" -n auto \
-			api/tests/unit_tests \
-			api/providers/vdb/*/tests/unit_tests \
-			api/providers/trace/*/tests/unit_tests \
-			--ignore=api/tests/unit_tests/controllers; \
-		uv run --project api --dev pytest --timeout "$${PYTEST_TIMEOUT:-20}" --cov-append \
-			api/tests/unit_tests/controllers; \
-		echo "Running backend integration tests"; \
-		uv run --project api --dev pytest -p no:benchmark --start-middleware -n auto \
-			--timeout "$${PYTEST_TIMEOUT:-180}" \
-			--cov-append \
-			api/tests/integration_tests/workflow \
-			api/tests/integration_tests/tools \
-			api/tests/test_containers_integration_tests; \
-		echo "Running VDB smoke tests"; \
-		uv run --project api --dev pytest --start-vdb \
-			--timeout "$${PYTEST_TIMEOUT:-180}" \
-			--cov-append \
-			api/providers/vdb/vdb-chroma/tests/integration_tests \
-			api/providers/vdb/vdb-pgvector/tests/integration_tests \
-			api/providers/vdb/vdb-qdrant/tests/integration_tests \
-			api/providers/vdb/vdb-weaviate/tests/integration_tests; \
+		PYTEST_XDIST_ARGS="-n auto" uv run --project api --dev dev/pytest/pytest_unit_tests.sh; \
 	fi
 	@echo "✅ Tests complete"
 
@@ -191,17 +132,15 @@ help:
 	@echo "  make prepare-docker - Set up Docker middleware"
 	@echo "  make prepare-web    - Set up web environment"
 	@echo "  make prepare-api    - Set up API environment"
-	@echo "  make dev-clean      - Stop Docker middleware containers and remove dev data"
+	@echo "  make dev-clean      - Stop Docker middleware containers"
 	@echo ""
 	@echo "Backend Code Quality:"
 	@echo "  make format         - Format code with ruff"
 	@echo "  make check          - Check code with ruff"
 	@echo "  make lint           - Format, fix, and lint code (ruff, imports, dotenv)"
-	@echo "  make api-contract-lint - Check Flask response docs against returned schemas"
-	@echo "  make type-check     - Run type checks (pyrefly, mypy)"
-	@echo "  make type-check-core - Run core type checks (pyrefly, mypy)"
+	@echo "  make type-check     - Run type checks (basedpyright, pyrefly, mypy)"
+	@echo "  make type-check-core - Run core type checks (basedpyright, mypy)"
 	@echo "  make test           - Run backend unit tests (or TARGET_TESTS=./api/tests/<target_tests>)"
-	@echo "  make test-all       - Run full backend tests, including Docker-backed suites"
 	@echo ""
 	@echo "Docker Build Targets:"
 	@echo "  make build-web      - Build web Docker image"
@@ -211,4 +150,4 @@ help:
 	@echo "  make build-push-all - Build and push all Docker images"
 
 # Phony targets
-.PHONY: build-web build-api push-web push-api build-all push-all build-push-all dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint api-contract-lint type-check test test-all
+.PHONY: build-web build-api push-web push-api build-all push-all build-push-all dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint type-check test

SECURITY.md

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

api/.env.example

@@ -34,7 +34,7 @@ TRIGGER_URL=http://localhost:5001
 FILES_ACCESS_TIMEOUT=300
 
 # Collaboration mode toggle
-ENABLE_COLLABORATION_MODE=true
+ENABLE_COLLABORATION_MODE=false
 
 # Access token expiration time in minutes
 ACCESS_TOKEN_EXPIRE_MINUTES=60
@@ -88,10 +88,6 @@ REDIS_HEALTH_CHECK_INTERVAL=30
 CELERY_BROKER_URL=redis://:difyai123456@localhost:${REDIS_PORT}/1
 CELERY_BACKEND=redis
 
-# Ops trace retry configuration
-OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES=60
-OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS=5
-
 # Database configuration
 DB_TYPE=postgresql
 DB_USERNAME=postgres
@@ -557,7 +553,7 @@ MAX_VARIABLE_SIZE=204800
 
 # GraphEngine Worker Pool Configuration
 # Minimum number of workers per GraphEngine instance (default: 1)
-GRAPH_ENGINE_MIN_WORKERS=3
+GRAPH_ENGINE_MIN_WORKERS=1
 # Maximum number of workers per GraphEngine instance (default: 10)
 GRAPH_ENGINE_MAX_WORKERS=10
 # Queue depth threshold that triggers worker scale up (default: 3)
@@ -657,7 +653,6 @@ PLUGIN_REMOTE_INSTALL_PORT=5003
 PLUGIN_REMOTE_INSTALL_HOST=localhost
 PLUGIN_MAX_PACKAGE_SIZE=15728640
 PLUGIN_MODEL_SCHEMA_CACHE_TTL=3600
-PLUGIN_MODEL_PROVIDERS_CACHE_TTL=86400
 INNER_API_KEY_FOR_PLUGIN=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y1
 
 # Marketplace configuration
@@ -768,7 +763,6 @@ EVENT_BUS_REDIS_CHANNEL_TYPE=pubsub
 # Whether to use Redis cluster mode while use redis as event bus.
 #  It's highly recommended to enable this for large deployments.
 EVENT_BUS_REDIS_USE_CLUSTERS=false
-EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS=2000
 
 # Whether to Enable human input timeout check task
 ENABLE_HUMAN_INPUT_TIMEOUT_TASK=true

api/AGENTS.md

@@ -180,8 +180,6 @@ Quick checks while iterating:
 - Format: `make format`
 - Lint (includes auto-fix): `make lint`
 - Type check: `make type-check`
-- Unit tests: `make test`
-- Full backend tests, including Docker-backed suites: `make test-all`
 - Targeted tests: `make test TARGET_TESTS=./api/tests/<target_tests>`
 
 Before opening a PR / submitting:
@@ -195,10 +193,9 @@ Before opening a PR / submitting:
 - Controllers: parse input via Pydantic, invoke services, return serialised responses; no business logic.
 - Services: coordinate repositories, providers, background tasks; keep side effects explicit.
 - Document non-obvious behaviour with concise docstrings and comments.
-- For `204 No Content` responses, return an empty body only; never return a dict, model, or other payload.
 - For Flask-RESTX controller request, query, and response schemas, follow `controllers/API_SCHEMA_GUIDE.md`.
   In short: use Pydantic models, document GET query params with `query_params_from_model(...)`, register response
-  DTOs with `register_response_schema_models(...)`, serialize response DTOs with `dump_response(...)`,
+  DTOs with `register_response_schema_models(...)`, serialize with `ResponseModel.model_validate(...).model_dump(...)`,
   and avoid adding new legacy `ns.model(...)`, `@marshal_with(...)`, or GET `@ns.expect(...)` patterns.
 
 ### Miscellaneous

api/Dockerfile

@@ -17,17 +17,14 @@ FROM base AS packages
 RUN apt-get update \
     && apt-get install -y --no-install-recommends \
           # basic environment
-          git g++ \
+          g++ \
           # for building gmpy2
           libmpfr-dev libmpc-dev
 
 # Install Python dependencies (workspace members under providers/vdb/)
-COPY api/pyproject.toml api/uv.lock ./
-COPY api/providers ./providers
-COPY dify-agent/pyproject.toml dify-agent/README.md /app/dify-agent/
-COPY dify-agent/src /app/dify-agent/src
-# Trust the checked-in lock during image builds; local path sources are copied from the repository context.
-RUN uv sync --frozen --no-dev --no-editable
+COPY pyproject.toml uv.lock ./
+COPY providers ./providers
+RUN uv sync --locked --no-dev
 
 # production stage
 FROM base AS production
@@ -110,10 +107,10 @@ RUN python -c "import tiktoken; tiktoken.encoding_for_model('gpt2')" \
     && chown -R dify:dify ${TIKTOKEN_CACHE_DIR}
 
 # Copy source code
-COPY --chown=dify:dify api /app/api/
+COPY --chown=dify:dify . /app/api/
 
 # Prepare entrypoint script
-COPY --chown=dify:dify --chmod=755 api/docker/entrypoint.sh /entrypoint.sh
+COPY --chown=dify:dify --chmod=755 docker/entrypoint.sh /entrypoint.sh
 
 
 ARG COMMIT_SHA

api/Dockerfile.dockerignore

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

api/README.md

@@ -99,7 +99,7 @@ The scripts resolve paths relative to their location, so you can run them from a
    ./dev/reformat               # Run all formatters and linters
    uv run ruff check --fix ./   # Fix linting issues
    uv run ruff format ./        # Format code
-   uv run pyrefly check         # Type checking
+   uv run basedpyright .        # Type checking
    ```
 
 ## Generate TS stub

api/app_factory.py

@@ -117,7 +117,7 @@ def create_flask_app_with_configs() -> DifyApp:
             logger.warning("Failed to add trace headers to response", exc_info=True)
         return response
 
-    # Capture the decorator return values so static checkers do not treat the hooks as unused.
+    # Capture the decorator's return value to avoid pyright reportUnusedFunction
     _ = before_request
     _ = add_trace_headers
 
@@ -159,7 +159,6 @@ def initialize_extensions(app: DifyApp):
         ext_logstore,
         ext_mail,
         ext_migrate,
-        ext_oauth_bearer,
         ext_orjson,
         ext_otel,
         ext_proxy_fix,
@@ -182,6 +181,7 @@ def initialize_extensions(app: DifyApp):
         ext_import_modules,
         ext_orjson,
         ext_forward_refs,
+        ext_set_secretkey,
         ext_compress,
         ext_code_based_extension,
         ext_database,
@@ -189,7 +189,6 @@ def initialize_extensions(app: DifyApp):
         ext_migrate,
         ext_redis,
         ext_storage,
-        ext_set_secretkey,
         ext_logstore,  # Initialize logstore after storage, before celery
         ext_celery,
         ext_login,
@@ -204,7 +203,6 @@ def initialize_extensions(app: DifyApp):
         ext_enterprise_telemetry,
         ext_request_logging,
         ext_session_factory,
-        ext_oauth_bearer,
     ]
     for ext in extensions:
         short_name = ext.__name__.split(".")[-1]
@@ -223,11 +221,10 @@ def initialize_extensions(app: DifyApp):
 
 def create_migrations_app() -> DifyApp:
     app = create_flask_app_with_configs()
-    from extensions import ext_commands, ext_database, ext_migrate
+    from extensions import ext_database, ext_migrate
 
     # Initialize only required extensions
     ext_database.init_app(app)
     ext_migrate.init_app(app)
-    ext_commands.init_app(app)
 
     return app

api/clients/__init__.py

@@ -1 +0,0 @@
-"""External service client packages."""

api/clients/agent_backend/__init__.py

@@ -1,82 +0,0 @@
-"""API-side integration boundary for the Dify Agent backend.
-
-Public wire DTOs come from ``dify_agent.protocol``. This package only contains
-API adapters: request building from Dify product concepts, a thin client wrapper,
-event adaptation for future workflow integration, and deterministic fakes.
-"""
-
-from clients.agent_backend.client import AgentBackendRunClient, DifyAgentBackendRunClient
-from clients.agent_backend.errors import (
-    AgentBackendError,
-    AgentBackendHTTPError,
-    AgentBackendRequestBuildError,
-    AgentBackendRunFailedError,
-    AgentBackendStreamError,
-    AgentBackendTransportError,
-    AgentBackendValidationError,
-)
-from clients.agent_backend.event_adapter import (
-    AgentBackendInternalEvent,
-    AgentBackendInternalEventType,
-    AgentBackendRunCancelledInternalEvent,
-    AgentBackendRunEventAdapter,
-    AgentBackendRunFailedInternalEvent,
-    AgentBackendRunPausedInternalEvent,
-    AgentBackendRunStartedInternalEvent,
-    AgentBackendRunSucceededInternalEvent,
-    AgentBackendStreamInternalEvent,
-)
-from clients.agent_backend.factory import create_agent_backend_run_client
-from clients.agent_backend.fake_client import FakeAgentBackendRunClient, FakeAgentBackendScenario
-from clients.agent_backend.request_builder import (
-    AGENT_SOUL_PROMPT_LAYER_ID,
-    DIFY_EXECUTION_CONTEXT_LAYER_ID,
-    DIFY_PLUGIN_TOOLS_LAYER_ID,
-    WORKFLOW_NODE_JOB_PROMPT_LAYER_ID,
-    WORKFLOW_USER_PROMPT_LAYER_ID,
-    AgentBackendAgentAppRunInput,
-    AgentBackendModelConfig,
-    AgentBackendOutputConfig,
-    AgentBackendRunRequestBuilder,
-    AgentBackendWorkflowNodeRunInput,
-    CleanupLayerSpec,
-    extract_cleanup_layer_specs,
-    redact_for_agent_backend_log,
-)
-
-__all__ = [
-    "AGENT_SOUL_PROMPT_LAYER_ID",
-    "DIFY_EXECUTION_CONTEXT_LAYER_ID",
-    "DIFY_PLUGIN_TOOLS_LAYER_ID",
-    "WORKFLOW_NODE_JOB_PROMPT_LAYER_ID",
-    "WORKFLOW_USER_PROMPT_LAYER_ID",
-    "AgentBackendAgentAppRunInput",
-    "AgentBackendError",
-    "AgentBackendHTTPError",
-    "AgentBackendInternalEvent",
-    "AgentBackendInternalEventType",
-    "AgentBackendModelConfig",
-    "AgentBackendOutputConfig",
-    "AgentBackendRequestBuildError",
-    "AgentBackendRunCancelledInternalEvent",
-    "AgentBackendRunClient",
-    "AgentBackendRunEventAdapter",
-    "AgentBackendRunFailedError",
-    "AgentBackendRunFailedInternalEvent",
-    "AgentBackendRunPausedInternalEvent",
-    "AgentBackendRunRequestBuilder",
-    "AgentBackendRunStartedInternalEvent",
-    "AgentBackendRunSucceededInternalEvent",
-    "AgentBackendStreamError",
-    "AgentBackendStreamInternalEvent",
-    "AgentBackendTransportError",
-    "AgentBackendValidationError",
-    "AgentBackendWorkflowNodeRunInput",
-    "CleanupLayerSpec",
-    "DifyAgentBackendRunClient",
-    "FakeAgentBackendRunClient",
-    "FakeAgentBackendScenario",
-    "create_agent_backend_run_client",
-    "extract_cleanup_layer_specs",
-    "redact_for_agent_backend_log",
-]

api/clients/agent_backend/client.py

@@ -1,130 +0,0 @@
-"""Synchronous API-side wrapper around the public ``dify-agent`` client.
-
-``dify-agent`` owns the cross-service DTOs and HTTP/SSE implementation. The API
-backend keeps this thin wrapper so workflow code depends on a local protocol,
-gets API-native errors, and can use a deterministic fake in tests without
-creating another wire contract.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Iterator
-from typing import Protocol
-
-from dify_agent.client import (
-    DifyAgentClientError,
-    DifyAgentHTTPError,
-    DifyAgentStreamError,
-    DifyAgentTimeoutError,
-    DifyAgentValidationError,
-)
-from dify_agent.protocol import (
-    CancelRunRequest,
-    CancelRunResponse,
-    CreateRunRequest,
-    CreateRunResponse,
-    RunEvent,
-    RunStatusResponse,
-)
-
-from clients.agent_backend.errors import (
-    AgentBackendError,
-    AgentBackendHTTPError,
-    AgentBackendStreamError,
-    AgentBackendTransportError,
-    AgentBackendValidationError,
-)
-
-
-class AgentBackendRunClient(Protocol):
-    """Local boundary used by API workflow integrations to run Agent backend jobs."""
-
-    def create_run(self, request: CreateRunRequest) -> CreateRunResponse:
-        """Create one Agent backend run and return its accepted status."""
-
-    def cancel_run(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
-        """Request explicit cancellation for one Agent backend run."""
-
-    def stream_events(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
-        """Yield public ``dify-agent`` run events in stream order."""
-
-    def wait_run(self, run_id: str, *, timeout_seconds: float | None = None) -> RunStatusResponse:
-        """Wait for a run to reach a terminal status and return that status."""
-
-
-class _DifyAgentSyncClient(Protocol):
-    """Subset of ``dify_agent.client.Client`` used by the API wrapper."""
-
-    def create_run_sync(self, request: CreateRunRequest) -> CreateRunResponse:
-        """Create one run synchronously."""
-
-    def cancel_run_sync(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
-        """Cancel one run synchronously."""
-
-    def stream_events_sync(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
-        """Stream run events synchronously."""
-
-    def wait_run_sync(self, run_id: str, *, timeout_seconds: float | None = None) -> RunStatusResponse:
-        """Wait for terminal run status synchronously."""
-
-
-class DifyAgentBackendRunClient:
-    """Adapter from API sync call sites to ``dify_agent.client.Client`` sync methods."""
-
-    client: _DifyAgentSyncClient
-
-    def __init__(self, client: _DifyAgentSyncClient) -> None:
-        self.client = client
-
-    def create_run(self, request: CreateRunRequest) -> CreateRunResponse:
-        """Create one run through ``POST /runs`` and normalize client exceptions."""
-        try:
-            return self.client.create_run_sync(request)
-        except Exception as exc:
-            raise _normalize_dify_agent_error(exc) from exc
-
-    def cancel_run(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
-        """Cancel one run through ``POST /runs/{run_id}/cancel`` and normalize exceptions."""
-        try:
-            return self.client.cancel_run_sync(run_id, request=request)
-        except Exception as exc:
-            raise _normalize_dify_agent_error(exc) from exc
-
-    def stream_events(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
-        """Stream run events from ``/events/sse`` with the wrapped client's reconnect policy."""
-        try:
-            yield from self.client.stream_events_sync(run_id, after=after)
-        except Exception as exc:
-            raise _normalize_dify_agent_error(exc) from exc
-
-    def wait_run(self, run_id: str, *, timeout_seconds: float | None = None) -> RunStatusResponse:
-        """Poll run status until terminal state and normalize client exceptions."""
-        try:
-            return self.client.wait_run_sync(run_id, timeout_seconds=timeout_seconds)
-        except Exception as exc:
-            raise _normalize_dify_agent_error(exc) from exc
-
-
-def _normalize_dify_agent_error(exc: Exception) -> AgentBackendError:
-    """Map public ``dify-agent`` client errors to API-side integration errors."""
-    match exc:
-        case DifyAgentValidationError() as error:
-            return AgentBackendValidationError(
-                "Agent backend request or response validation failed", detail=error.detail
-            )
-        case DifyAgentHTTPError() as error:
-            return AgentBackendHTTPError(
-                f"Agent backend HTTP {error.status_code}",
-                status_code=error.status_code,
-                detail=error.detail,
-            )
-        case DifyAgentTimeoutError() as error:
-            return AgentBackendTransportError(str(error))
-        case DifyAgentStreamError() as error:
-            return AgentBackendStreamError(str(error))
-        case DifyAgentClientError() as error:
-            return AgentBackendTransportError(str(error))
-        case AgentBackendError() as error:
-            return error
-        case _:
-            return AgentBackendTransportError(str(exc) or type(exc).__name__)

api/clients/agent_backend/errors.py

@@ -1,61 +0,0 @@
-"""API-side errors for the Dify Agent backend integration.
-
-The wire protocol and low-level HTTP behaviour are owned by ``dify-agent``.
-This module only normalizes those client errors into the API backend's boundary
-so workflow/node code does not depend directly on transport-specific exception
-classes.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-
-class AgentBackendError(Exception):
-    """Base error for API-side Agent backend integration failures."""
-
-
-class AgentBackendRequestBuildError(AgentBackendError):
-    """Raised when Dify product/workflow state cannot be mapped to a run request."""
-
-
-class AgentBackendTransportError(AgentBackendError):
-    """Raised for timeout or request-level failures talking to Agent backend."""
-
-
-class AgentBackendHTTPError(AgentBackendTransportError):
-    """Raised for Agent backend HTTP errors after status/detail normalization."""
-
-    status_code: int
-    detail: object
-
-    def __init__(self, message: str, *, status_code: int, detail: object) -> None:
-        self.status_code = status_code
-        self.detail = detail
-        super().__init__(message)
-
-
-class AgentBackendValidationError(AgentBackendError):
-    """Raised for local request validation or Agent backend 422 responses."""
-
-    detail: object
-
-    def __init__(self, message: str, *, detail: object) -> None:
-        self.detail = detail
-        super().__init__(message)
-
-
-class AgentBackendStreamError(AgentBackendError):
-    """Raised when an Agent backend event stream is malformed or exhausted."""
-
-
-class AgentBackendRunFailedError(AgentBackendError):
-    """Raised by callers that choose to translate a terminal failed run into an exception."""
-
-    run_id: str
-    detail: Any
-
-    def __init__(self, run_id: str, detail: Any) -> None:
-        self.run_id = run_id
-        self.detail = detail
-        super().__init__(f"Agent backend run failed: {run_id}")

api/clients/agent_backend/event_adapter.py

@@ -1,167 +0,0 @@
-"""Adapt public ``dify-agent`` run events into API-internal event semantics.
-
-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.
-"""
-
-from __future__ import annotations
-
-from enum import StrEnum
-from typing import Annotated, Literal, cast
-
-from agenton.compositor import CompositorSessionSnapshot
-from dify_agent.protocol import (
-    PydanticAIStreamRunEvent,
-    RunCancelledEvent,
-    RunEvent,
-    RunFailedEvent,
-    RunPausedEvent,
-    RunStartedEvent,
-    RunSucceededEvent,
-)
-from pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter
-
-_EVENT_DATA_ADAPTER = TypeAdapter(object)
-
-
-class AgentBackendInternalEventType(StrEnum):
-    """API-only event labels used before Graphon/AppQueue integration."""
-
-    RUN_STARTED = "run_started"
-    STREAM_EVENT = "stream_event"
-    RUN_PAUSED = "run_paused"
-    RUN_SUCCEEDED = "run_succeeded"
-    RUN_FAILED = "run_failed"
-    RUN_CANCELLED = "run_cancelled"
-
-
-class AgentBackendInternalEventBase(BaseModel):
-    """Common fields preserved from public Dify Agent run events."""
-
-    run_id: str
-    source_event_id: str | None = None
-
-    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
-
-
-class AgentBackendRunStartedInternalEvent(AgentBackendInternalEventBase):
-    """API-internal marker for a started Agent backend run."""
-
-    type: Literal[AgentBackendInternalEventType.RUN_STARTED] = AgentBackendInternalEventType.RUN_STARTED
-
-
-class AgentBackendStreamInternalEvent(AgentBackendInternalEventBase):
-    """API-internal wrapper for one pydantic-ai stream event payload."""
-
-    type: Literal[AgentBackendInternalEventType.STREAM_EVENT] = AgentBackendInternalEventType.STREAM_EVENT
-    event_kind: str | None = None
-    data: JsonValue
-
-
-class AgentBackendRunSucceededInternalEvent(AgentBackendInternalEventBase):
-    """API-internal terminal success event carrying final output and session state."""
-
-    type: Literal[AgentBackendInternalEventType.RUN_SUCCEEDED] = AgentBackendInternalEventType.RUN_SUCCEEDED
-    output: JsonValue
-    session_snapshot: CompositorSessionSnapshot
-
-
-class AgentBackendRunPausedInternalEvent(AgentBackendInternalEventBase):
-    """API-internal resumable pause event for human handoff and Babysit flows."""
-
-    type: Literal[AgentBackendInternalEventType.RUN_PAUSED] = AgentBackendInternalEventType.RUN_PAUSED
-    reason: str
-    message: str | None = None
-    session_snapshot: CompositorSessionSnapshot | None = None
-
-
-class AgentBackendRunFailedInternalEvent(AgentBackendInternalEventBase):
-    """API-internal terminal failure event carrying the backend-safe error text."""
-
-    type: Literal[AgentBackendInternalEventType.RUN_FAILED] = AgentBackendInternalEventType.RUN_FAILED
-    error: str
-    reason: str | None = None
-
-
-class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):
-    """API-internal terminal cancellation event."""
-
-    type: Literal[AgentBackendInternalEventType.RUN_CANCELLED] = AgentBackendInternalEventType.RUN_CANCELLED
-    reason: str | None = None
-    message: str | None = None
-
-
-type AgentBackendInternalEvent = Annotated[
-    AgentBackendRunStartedInternalEvent
-    | AgentBackendStreamInternalEvent
-    | AgentBackendRunPausedInternalEvent
-    | AgentBackendRunSucceededInternalEvent
-    | AgentBackendRunFailedInternalEvent
-    | AgentBackendRunCancelledInternalEvent,
-    Field(discriminator="type"),
-]
-
-
-class AgentBackendRunEventAdapter:
-    """Maps public ``dify-agent`` event variants to API-internal event variants."""
-
-    def adapt(self, event: RunEvent) -> list[AgentBackendInternalEvent]:
-        """Return zero or more API-internal events derived from one public run event."""
-        match event:
-            case RunStartedEvent():
-                return [
-                    AgentBackendRunStartedInternalEvent(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                    )
-                ]
-            case PydanticAIStreamRunEvent():
-                data = cast(JsonValue, _EVENT_DATA_ADAPTER.dump_python(event.data, mode="json"))
-                event_kind = data.get("event_kind") if isinstance(data, dict) else None
-                return [
-                    AgentBackendStreamInternalEvent(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                        event_kind=event_kind if isinstance(event_kind, str) else None,
-                        data=data,
-                    )
-                ]
-            case RunSucceededEvent():
-                return [
-                    AgentBackendRunSucceededInternalEvent(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                        output=event.data.output,
-                        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(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                        error=event.data.error,
-                        reason=event.data.reason,
-                    )
-                ]
-            case RunCancelledEvent():
-                return [
-                    AgentBackendRunCancelledInternalEvent(
-                        run_id=event.run_id,
-                        source_event_id=event.id,
-                        reason=event.data.reason,
-                        message=event.data.message,
-                    )
-                ]
-        raise TypeError(f"unsupported agent backend run event: {type(event).__name__}")

api/clients/agent_backend/factory.py

@@ -1,22 +0,0 @@
-"""Factories for API-side Agent backend clients."""
-
-from __future__ import annotations
-
-from dify_agent.client import Client
-
-from clients.agent_backend.client import AgentBackendRunClient, DifyAgentBackendRunClient
-from clients.agent_backend.fake_client import FakeAgentBackendRunClient, FakeAgentBackendScenario
-
-
-def create_agent_backend_run_client(
-    *,
-    base_url: str | None = None,
-    use_fake: bool = False,
-    fake_scenario: str | FakeAgentBackendScenario = FakeAgentBackendScenario.SUCCESS,
-) -> AgentBackendRunClient:
-    """Create the API-side run client without hiding the ``dify-agent`` protocol."""
-    if use_fake:
-        return FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario(fake_scenario))
-    if base_url is None:
-        raise ValueError("base_url is required when creating a real Agent backend client")
-    return DifyAgentBackendRunClient(Client(base_url=base_url))

api/clients/agent_backend/fake_client.py

@@ -1,141 +0,0 @@
-"""Deterministic fake Agent backend client using public ``dify-agent`` events.
-
-Tests should exercise the same ``RunEvent`` DTOs as the real HTTP client. This
-fake therefore replaces the previous custom mock protocol instead of emulating a
-separate ``agent-backend.v1`` event stream.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Iterator
-from datetime import UTC, datetime
-from enum import StrEnum
-
-from agenton.compositor import CompositorSessionSnapshot
-from dify_agent.protocol import (
-    CancelRunRequest,
-    CancelRunResponse,
-    CreateRunRequest,
-    CreateRunResponse,
-    RunEvent,
-    RunFailedEvent,
-    RunFailedEventData,
-    RunPausedEvent,
-    RunPausedEventData,
-    RunStartedEvent,
-    RunStatusResponse,
-    RunSucceededEvent,
-    RunSucceededEventData,
-)
-
-_FIXED_TIME = datetime(2026, 1, 1, tzinfo=UTC)
-
-
-class FakeAgentBackendScenario(StrEnum):
-    """Deterministic fake scenarios for API-side integration tests."""
-
-    SUCCESS = "success"
-    FAILED = "failed"
-    PAUSED = "paused"
-
-
-class FakeAgentBackendRunClient:
-    """In-memory implementation of ``AgentBackendRunClient`` for unit tests."""
-
-    scenario: FakeAgentBackendScenario
-    run_id: str
-    request: CreateRunRequest | None
-
-    def __init__(
-        self,
-        *,
-        scenario: FakeAgentBackendScenario = FakeAgentBackendScenario.SUCCESS,
-        run_id: str = "fake-run-1",
-    ) -> None:
-        self.scenario = scenario
-        self.run_id = run_id
-        self.request = None
-
-    def create_run(self, request: CreateRunRequest) -> CreateRunResponse:
-        """Record the request and return a deterministic accepted response."""
-        self.request = request
-        return CreateRunResponse(run_id=self.run_id, status="running")
-
-    def cancel_run(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
-        """Return a deterministic cancellation response."""
-        del request
-        return CancelRunResponse(run_id=run_id, status="cancelled")
-
-    def stream_events(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
-        """Yield the deterministic public ``RunEvent`` sequence for ``run_id``."""
-        for event in self._events(run_id):
-            if after is not None and event.id is not None and event.id <= after:
-                continue
-            yield event
-
-    def wait_run(self, run_id: str, *, timeout_seconds: float | None = None) -> RunStatusResponse:
-        """Return a deterministic terminal status; timeout is accepted for protocol parity."""
-        del timeout_seconds
-        match self.scenario:
-            case FakeAgentBackendScenario.SUCCESS:
-                return RunStatusResponse(
-                    run_id=run_id,
-                    status="succeeded",
-                    created_at=_FIXED_TIME,
-                    updated_at=_FIXED_TIME,
-                )
-            case FakeAgentBackendScenario.FAILED:
-                return RunStatusResponse(
-                    run_id=run_id,
-                    status="failed",
-                    created_at=_FIXED_TIME,
-                    updated_at=_FIXED_TIME,
-                    error="fake failure",
-                )
-            case FakeAgentBackendScenario.PAUSED:
-                return RunStatusResponse(
-                    run_id=run_id,
-                    status="paused",
-                    created_at=_FIXED_TIME,
-                    updated_at=_FIXED_TIME,
-                )
-
-    def _events(self, run_id: str) -> tuple[RunEvent, ...]:
-        match self.scenario:
-            case FakeAgentBackendScenario.SUCCESS:
-                return (
-                    RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),
-                    RunSucceededEvent(
-                        id="2-0",
-                        run_id=run_id,
-                        created_at=_FIXED_TIME,
-                        data=RunSucceededEventData(
-                            output={"text": "hello agent"},
-                            session_snapshot=CompositorSessionSnapshot(layers=[]),
-                        ),
-                    ),
-                )
-            case FakeAgentBackendScenario.FAILED:
-                return (
-                    RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),
-                    RunFailedEvent(
-                        id="2-0",
-                        run_id=run_id,
-                        created_at=_FIXED_TIME,
-                        data=RunFailedEventData(error="fake failure", reason="unit_test"),
-                    ),
-                )
-            case FakeAgentBackendScenario.PAUSED:
-                return (
-                    RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),
-                    RunPausedEvent(
-                        id="2-0",
-                        run_id=run_id,
-                        created_at=_FIXED_TIME,
-                        data=RunPausedEventData(
-                            reason="human_input_required",
-                            message="Agent requested human input.",
-                            session_snapshot=CompositorSessionSnapshot(layers=[]),
-                        ),
-                    ),
-                )

api/clients/agent_backend/request_builder.py

@@ -1,513 +0,0 @@
-"""Build ``dify-agent`` run requests from API-side product concepts.
-
-This module is intentionally an adapter, not a wire DTO package. The emitted
-object is always ``dify_agent.protocol.CreateRunRequest`` so the Agent backend
-protocol has a single owner. API-only context such as Agent Soul vs workflow job
-prompt is preserved in layer names and metadata until the dedicated product
-schemas land in later phases. Dify-owned execution identifiers are emitted as an
-explicit ``dify.execution_context`` layer so the run request stays fully
-composition-driven.
-"""
-
-from __future__ import annotations
-
-from typing import ClassVar, cast
-
-from agenton.compositor import CompositorSessionSnapshot
-from agenton.compositor.schemas import LayerSessionSnapshot
-from agenton.layers import ExitIntent
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
-from dify_agent.layers.dify_plugin import (
-    DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
-    DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-    DifyPluginCredentialValue,
-    DifyPluginLLMLayerConfig,
-    DifyPluginToolsLayerConfig,
-)
-from dify_agent.layers.execution_context import (
-    DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
-    DifyExecutionContextLayerConfig,
-)
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
-from dify_agent.protocol import (
-    DIFY_AGENT_HISTORY_LAYER_ID,
-    DIFY_AGENT_MODEL_LAYER_ID,
-    DIFY_AGENT_OUTPUT_LAYER_ID,
-    CreateRunRequest,
-    LayerExitSignals,
-    RunComposition,
-    RunLayerSpec,
-    RunPurpose,
-)
-from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
-
-AGENT_SOUL_PROMPT_LAYER_ID = "agent_soul_prompt"
-WORKFLOW_NODE_JOB_PROMPT_LAYER_ID = "workflow_node_job_prompt"
-WORKFLOW_USER_PROMPT_LAYER_ID = "workflow_user_prompt"
-AGENT_APP_USER_PROMPT_LAYER_ID = "agent_app_user_prompt"
-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],
-) -> CompositorSessionSnapshot:
-    """Keep only snapshot layers whose names appear in the cleanup spec list.
-
-    The agenton compositor rejects a snapshot whose layer-name sequence does
-    not match the active composition exactly. Cleanup-replay drops plugin
-    layers, so we must drop the matching snapshot entries here.
-    """
-    kept_names = {spec.name for spec in specs}
-    filtered_layers: list[LayerSessionSnapshot] = [layer for layer in snapshot.layers if layer.name in kept_names]
-    if len(filtered_layers) == len(snapshot.layers):
-        return snapshot
-    return CompositorSessionSnapshot(schema_version=snapshot.schema_version, layers=filtered_layers)
-
-
-class AgentBackendModelConfig(BaseModel):
-    """API-side model/plugin selection before it is converted to Dify Agent layers."""
-
-    plugin_id: str
-    model_provider: str
-    model: str
-    credentials: dict[str, DifyPluginCredentialValue] = Field(default_factory=dict)
-    model_settings: dict[str, JsonValue] = Field(default_factory=dict)
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
-class AgentBackendOutputConfig(BaseModel):
-    """API-side structured output declaration for the conventional output layer.
-
-    The structured-output tool name is fixed to ``final_output`` inside
-    ``dify_agent.layers.output`` so callers only control the JSON Schema plus
-    optional description/strictness metadata.
-    """
-
-    json_schema: dict[str, JsonValue]
-    description: str | None = None
-    strict: bool | None = None
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
-class AgentBackendWorkflowNodeRunInput(BaseModel):
-    """Inputs needed to build the first workflow-node-oriented Agent backend run request."""
-
-    model: AgentBackendModelConfig
-    execution_context: DifyExecutionContextLayerConfig
-    workflow_node_job_prompt: str
-    user_prompt: str
-    agent_soul_prompt: str | None = None
-    purpose: RunPurpose = "workflow_node"
-    idempotency_key: str | None = None
-    output: AgentBackendOutputConfig | None = None
-    tools: DifyPluginToolsLayerConfig | None = None
-    # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
-    # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
-    include_shell: bool = False
-    shell_config: DifyShellLayerConfig | None = None
-    session_snapshot: CompositorSessionSnapshot | None = None
-    include_history: bool = True
-    suspend_on_exit: bool = True
-    metadata: dict[str, JsonValue] = Field(default_factory=dict)
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
-
-    @field_validator("workflow_node_job_prompt", "user_prompt")
-    @classmethod
-    def _reject_blank_prompt(cls, value: str) -> str:
-        if not value.strip():
-            raise ValueError("prompt must not be blank")
-        return value
-
-
-class AgentBackendAgentAppRunInput(BaseModel):
-    """Inputs to build one Agent App conversation-turn run request.
-
-    Unlike the workflow-node input there is no workflow-node-job prompt and no
-    previous-node context: the user prompt is the chat message, and multi-turn
-    continuity comes from ``session_snapshot`` + the history layer keyed by the
-    conversation.
-    """
-
-    model: AgentBackendModelConfig
-    execution_context: DifyExecutionContextLayerConfig
-    user_prompt: str
-    agent_soul_prompt: str | None = None
-    purpose: RunPurpose = "agent_app"
-    idempotency_key: str | None = None
-    output: AgentBackendOutputConfig | None = None
-    tools: DifyPluginToolsLayerConfig | None = None
-    # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
-    # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
-    include_shell: bool = False
-    shell_config: DifyShellLayerConfig | None = None
-    session_snapshot: CompositorSessionSnapshot | None = None
-    include_history: bool = True
-    suspend_on_exit: bool = True
-    metadata: dict[str, JsonValue] = Field(default_factory=dict)
-
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
-
-    @field_validator("user_prompt")
-    @classmethod
-    def _reject_blank_prompt(cls, value: str) -> str:
-        if not value.strip():
-            raise ValueError("prompt must not be blank")
-        return value
-
-
-class AgentBackendRunRequestBuilder:
-    """Converts API product state into the public ``dify-agent`` run protocol."""
-
-    def build_for_agent_app(self, run_input: AgentBackendAgentAppRunInput) -> CreateRunRequest:
-        """Build an Agent App conversation-turn run request.
-
-        Layer graph: optional Agent Soul system prompt → user prompt →
-        execution context → optional history (multi-turn) → LLM → optional
-        plugin tools → optional structured output. Mirrors the workflow-node
-        layer ordering minus the workflow-job / previous-node prompt.
-        """
-        layers: list[RunLayerSpec] = []
-        if run_input.agent_soul_prompt:
-            layers.append(
-                RunLayerSpec(
-                    name=AGENT_SOUL_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "agent_soul"},
-                    config=PromptLayerConfig(prefix=run_input.agent_soul_prompt),
-                )
-            )
-
-        layers.extend(
-            [
-                RunLayerSpec(
-                    name=AGENT_APP_USER_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "agent_app_user_prompt"},
-                    config=PromptLayerConfig(user=run_input.user_prompt),
-                ),
-                RunLayerSpec(
-                    name=DIFY_EXECUTION_CONTEXT_LAYER_ID,
-                    type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=run_input.execution_context,
-                ),
-            ]
-        )
-
-        if run_input.include_history:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_AGENT_HISTORY_LAYER_ID,
-                    type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "agent_session_history"},
-                )
-            )
-
-        layers.append(
-            RunLayerSpec(
-                name=DIFY_AGENT_MODEL_LAYER_ID,
-                type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
-                deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
-                metadata=run_input.metadata,
-                config=DifyPluginLLMLayerConfig(
-                    plugin_id=run_input.model.plugin_id,
-                    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,
-                ),
-            )
-        )
-
-        if run_input.tools is not None and run_input.tools.tools:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_PLUGIN_TOOLS_LAYER_ID,
-                    type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
-                    metadata=run_input.metadata,
-                    config=run_input.tools,
-                )
-            )
-
-        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.
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_SHELL_LAYER_ID,
-                    type=DIFY_SHELL_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=run_input.shell_config or DifyShellLayerConfig(),
-                )
-            )
-
-        if run_input.output is not None:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_AGENT_OUTPUT_LAYER_ID,
-                    type=DIFY_OUTPUT_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=DifyOutputLayerConfig(
-                        json_schema=run_input.output.json_schema,
-                        description=run_input.output.description,
-                        strict=run_input.output.strict,
-                    ),
-                )
-            )
-
-        return CreateRunRequest(
-            composition=RunComposition(layers=layers),
-            purpose=run_input.purpose,
-            idempotency_key=run_input.idempotency_key,
-            metadata=run_input.metadata,
-            session_snapshot=run_input.session_snapshot,
-            on_exit=LayerExitSignals(
-                default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
-            ),
-        )
-
-    def build_cleanup_request(
-        self,
-        *,
-        session_snapshot: CompositorSessionSnapshot,
-        composition_layer_specs: list[CleanupLayerSpec],
-        idempotency_key: str | None = None,
-        metadata: dict[str, JsonValue] | None = None,
-    ) -> CreateRunRequest:
-        """Build a lifecycle-only cleanup request that replays the prior layers.
-
-        The agenton compositor enforces that the session snapshot's layer names
-        match the active composition in order, so cleanup must replay the same
-        non-plugin layer graph that produced the snapshot. Plugin layers
-        (``dify.plugin.llm``, ``dify.plugin.tools``) are excluded from both the
-        composition and the snapshot before submission because their configs
-        require credentials that are not persisted between runs.
-        """
-        if not composition_layer_specs:
-            raise ValueError(
-                "build_cleanup_request requires composition_layer_specs; an empty "
-                "composition would fail the agent backend's snapshot validation."
-            )
-        request_metadata = dict(metadata or {})
-        request_metadata["agent_backend_lifecycle"] = "session_cleanup"
-        layers = [
-            RunLayerSpec(
-                name=spec.name,
-                type=spec.type,
-                deps=dict(spec.deps),
-                metadata=dict(spec.metadata),
-                config=spec.config,
-            )
-            for spec in composition_layer_specs
-        ]
-        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, composition_layer_specs)
-        return CreateRunRequest(
-            composition=RunComposition(layers=layers),
-            purpose="workflow_node",
-            idempotency_key=idempotency_key,
-            metadata=request_metadata,
-            session_snapshot=filtered_snapshot,
-            on_exit=LayerExitSignals(default=ExitIntent.DELETE),
-        )
-
-    def build_for_workflow_node(self, run_input: AgentBackendWorkflowNodeRunInput) -> CreateRunRequest:
-        """Build a workflow Agent Node run request without defining another wire schema."""
-        layers: list[RunLayerSpec] = []
-        if run_input.agent_soul_prompt:
-            layers.append(
-                RunLayerSpec(
-                    name=AGENT_SOUL_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "agent_soul"},
-                    config=PromptLayerConfig(prefix=run_input.agent_soul_prompt),
-                )
-            )
-
-        layers.extend(
-            [
-                RunLayerSpec(
-                    name=WORKFLOW_NODE_JOB_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "workflow_node_job"},
-                    config=PromptLayerConfig(prefix=run_input.workflow_node_job_prompt),
-                ),
-                RunLayerSpec(
-                    name=WORKFLOW_USER_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "workflow_user_prompt"},
-                    config=PromptLayerConfig(user=run_input.user_prompt),
-                ),
-                RunLayerSpec(
-                    name=DIFY_EXECUTION_CONTEXT_LAYER_ID,
-                    type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=run_input.execution_context,
-                ),
-            ]
-        )
-
-        if run_input.include_history:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_AGENT_HISTORY_LAYER_ID,
-                    type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
-                    metadata={**run_input.metadata, "origin": "agent_session_history"},
-                )
-            )
-
-        layers.extend(
-            [
-                RunLayerSpec(
-                    name=DIFY_AGENT_MODEL_LAYER_ID,
-                    type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
-                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
-                    metadata=run_input.metadata,
-                    config=DifyPluginLLMLayerConfig(
-                        plugin_id=run_input.model.plugin_id,
-                        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,
-                    ),
-                ),
-            ]
-        )
-
-        if run_input.tools is not None and run_input.tools.tools:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_PLUGIN_TOOLS_LAYER_ID,
-                    type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
-                    metadata=run_input.metadata,
-                    config=run_input.tools,
-                )
-            )
-
-        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.
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_SHELL_LAYER_ID,
-                    type=DIFY_SHELL_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=run_input.shell_config or DifyShellLayerConfig(),
-                )
-            )
-
-        if run_input.output is not None:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_AGENT_OUTPUT_LAYER_ID,
-                    type=DIFY_OUTPUT_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=DifyOutputLayerConfig(
-                        json_schema=run_input.output.json_schema,
-                        description=run_input.output.description,
-                        strict=run_input.output.strict,
-                    ),
-                )
-            )
-
-        return CreateRunRequest(
-            composition=RunComposition(layers=layers),
-            purpose=run_input.purpose,
-            idempotency_key=run_input.idempotency_key,
-            metadata=run_input.metadata,
-            session_snapshot=run_input.session_snapshot,
-            on_exit=LayerExitSignals(
-                default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
-            ),
-        )
-
-
-_SENSITIVE_KEY_PARTS = ("secret", "credential", "token", "password", "api_key")
-
-
-def redact_for_agent_backend_log(value: object) -> object:
-    """Return a JSON-like copy with credential-bearing keys redacted for logs/tests."""
-    if isinstance(value, BaseModel):
-        return redact_for_agent_backend_log(value.model_dump(mode="json", warnings=False))
-    if isinstance(value, dict):
-        redacted: dict[object, object] = {}
-        for key, item in value.items():
-            key_text = str(key).lower()
-            if any(part in key_text for part in _SENSITIVE_KEY_PARTS):
-                redacted[key] = "[REDACTED]"
-            else:
-                redacted[key] = redact_for_agent_backend_log(item)
-        return redacted
-    if isinstance(value, list):
-        return [redact_for_agent_backend_log(item) for item in value]
-    return value

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/__init__.py

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

api/commands/data_migrate.py

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

api/commands/data_migration.py

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

api/commands/plugin.py

@@ -11,7 +11,6 @@ from configs import dify_config
 from core.helper import encrypter
 from core.plugin.entities.plugin_daemon import CredentialType
 from core.plugin.impl.plugin import PluginInstaller
-from core.plugin.plugin_service import PluginService
 from core.tools.utils.system_encryption import encrypt_system_params
 from extensions.ext_database import db
 from models import Tenant
@@ -21,6 +20,7 @@ from models.source import DataSourceApiKeyAuthBinding, DataSourceOauthBinding
 from models.tools import ToolOAuthSystemClient
 from services.plugin.data_migration import PluginDataMigration
 from services.plugin.plugin_migration import PluginMigration
+from services.plugin.plugin_service import PluginService
 
 logger = logging.getLogger(__name__)
 
@@ -185,9 +185,9 @@ def transform_datasource_credentials(environment: str):
         firecrawl_plugin_id = "langgenius/firecrawl_datasource"
         jina_plugin_id = "langgenius/jina_datasource"
         if environment == "online":
-            notion_plugin_unique_identifier = plugin_migration._fetch_plugin_unique_identifier(notion_plugin_id)
-            firecrawl_plugin_unique_identifier = plugin_migration._fetch_plugin_unique_identifier(firecrawl_plugin_id)
-            jina_plugin_unique_identifier = plugin_migration._fetch_plugin_unique_identifier(jina_plugin_id)
+            notion_plugin_unique_identifier = plugin_migration._fetch_plugin_unique_identifier(notion_plugin_id)  # pyright: ignore[reportPrivateUsage]
+            firecrawl_plugin_unique_identifier = plugin_migration._fetch_plugin_unique_identifier(firecrawl_plugin_id)  # pyright: ignore[reportPrivateUsage]
+            jina_plugin_unique_identifier = plugin_migration._fetch_plugin_unique_identifier(jina_plugin_id)  # pyright: ignore[reportPrivateUsage]
         else:
             notion_plugin_unique_identifier = None
             firecrawl_plugin_unique_identifier = None

api/commands/system.py

@@ -14,7 +14,6 @@ from libs.rsa import generate_key_pair
 from models import Tenant
 from models.model import App, AppMode, Conversation
 from models.provider import Provider, ProviderModel
-from models.tools import ApiToolProvider, BuiltinToolProvider, MCPToolProvider
 
 logger = logging.getLogger(__name__)
 
@@ -24,16 +23,13 @@ DB_UPGRADE_LOCK_TTL_SECONDS = 60
 @click.command(
     "reset-encrypt-key-pair",
     help="Reset the asymmetric key pair of workspace for encrypt LLM credentials. "
-    "After the reset, all LLM credentials and tool provider credentials "
-    "(builtin / API / MCP) will be purged, requiring re-entry. "
+    "After the reset, all LLM credentials will become invalid, "
+    "requiring re-entry."
     "Only support SELF_HOSTED mode.",
 )
 @click.confirmation_option(
     prompt=click.style(
-        "Are you sure you want to reset encrypt key pair? "
-        "This will also purge builtin / API / MCP tool provider records for every tenant. "
-        "This operation cannot be rolled back!",
-        fg="red",
+        "Are you sure you want to reset encrypt key pair? This operation cannot be rolled back!", fg="red"
     )
 )
 def reset_encrypt_key_pair():
@@ -57,13 +53,6 @@ def reset_encrypt_key_pair():
             session.execute(delete(Provider).where(Provider.provider_type == "custom", Provider.tenant_id == tenant.id))
             session.execute(delete(ProviderModel).where(ProviderModel.tenant_id == tenant.id))
 
-            # Purge tool provider records that hold credentials encrypted under the
-            # tenant key. Leaving them in place causes /console/api/workspaces/current/
-            # tool-providers to 500 because decryption fails on stale ciphertext (#35396).
-            session.execute(delete(BuiltinToolProvider).where(BuiltinToolProvider.tenant_id == tenant.id))
-            session.execute(delete(ApiToolProvider).where(ApiToolProvider.tenant_id == tenant.id))
-            session.execute(delete(MCPToolProvider).where(MCPToolProvider.tenant_id == tenant.id))
-
             click.echo(
                 click.style(
                     f"Congratulations! The asymmetric key pair of workspace {tenant.id} has been reset.",

api/commands/vector.py

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

api/configs/app_config.py

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

api/configs/deploy/__init__.py

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

api/configs/enterprise/__init__.py

@@ -23,12 +23,6 @@ class EnterpriseFeatureConfig(BaseSettings):
         ge=1, description="Maximum timeout in seconds for enterprise requests", default=5
     )
 
-    ENTERPRISE_DISABLE_RUNTIME_CREDENTIAL_CHECK: bool = Field(
-        default=False,
-        description="If disabled, credential policy check is only performed when saving workflows."
-        "This helps gain runtime performance by trading off consistency.",
-    )
-
 
 class EnterpriseTelemetryConfig(BaseSettings):
     """

api/configs/extra/__init__.py

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

api/configs/extra/agent_backend_config.py

@@ -1,33 +0,0 @@
-from pydantic import Field
-from pydantic_settings import BaseSettings
-
-
-class AgentBackendConfig(BaseSettings):
-    """
-    Configuration settings for the Agent backend runtime integration.
-    """
-
-    AGENT_BACKEND_BASE_URL: str | None = Field(
-        description="Base URL for the Dify Agent backend service.",
-        default=None,
-    )
-
-    AGENT_BACKEND_USE_FAKE: bool = Field(
-        description="Use the deterministic in-process fake Agent backend client.",
-        default=False,
-    )
-
-    AGENT_BACKEND_FAKE_SCENARIO: str = Field(
-        description="Scenario used by the fake Agent backend client.",
-        default="success",
-    )
-
-    AGENT_SHELL_ENABLED: bool = Field(
-        description=(
-            "Inject the dify.shell layer (sandboxed bash workspace) into Agent runs. "
-            "Requires the agent backend to be wired with a shellctl entrypoint; keep it "
-            "off until shellctl is deployed, otherwise every agent run that includes the "
-            "shell layer will fail."
-        ),
-        default=False,
-    )

api/configs/feature/__init__.py

@@ -23,9 +23,9 @@ class SecurityConfig(BaseSettings):
     """
 
     SECRET_KEY: str = Field(
-        description="Secret key for secure session cookie signing. "
-        "Leave empty to let Dify generate a persistent key in the storage directory, "
-        "or set a strong value via the `SECRET_KEY` environment variable.",
+        description="Secret key for secure session cookie signing."
+        "Make sure you are changing this key for your deployment with a strong key."
+        "Generate a strong key using `openssl rand -base64 42` or set via the `SECRET_KEY` environment variable.",
         default="",
     )
 
@@ -265,11 +265,6 @@ class PluginConfig(BaseSettings):
         default=60 * 60,
     )
 
-    PLUGIN_MODEL_PROVIDERS_CACHE_TTL: PositiveInt = Field(
-        description="TTL in seconds for caching tenant plugin model providers in Redis",
-        default=60 * 60 * 24,
-    )
-
     PLUGIN_MAX_FILE_SIZE: PositiveInt = Field(
         description="Maximum allowed size (bytes) for plugin-generated files",
         default=50 * 1024 * 1024,
@@ -525,44 +520,6 @@ class HttpConfig(BaseSettings):
     def WEB_API_CORS_ALLOW_ORIGINS(self) -> list[str]:
         return self.inner_WEB_API_CORS_ALLOW_ORIGINS.split(",")
 
-    OPENAPI_ENABLED: bool = Field(
-        description=(
-            "Enable the /openapi/v1/* endpoint group used by difyctl and other "
-            "programmatic clients. Set to true to activate; disabled by default."
-        ),
-        validation_alias=AliasChoices("OPENAPI_ENABLED"),
-        default=False,
-    )
-
-    inner_OPENAPI_CORS_ALLOW_ORIGINS: str = Field(
-        description=(
-            "Comma-separated allowlist for /openapi/v1/* CORS. "
-            "Default empty = same-origin only. Browser-cookie routes within "
-            "the group reject cross-origin OPTIONS regardless of this list."
-        ),
-        validation_alias=AliasChoices("OPENAPI_CORS_ALLOW_ORIGINS"),
-        default="",
-    )
-
-    @computed_field
-    def OPENAPI_CORS_ALLOW_ORIGINS(self) -> list[str]:
-        return [o for o in self.inner_OPENAPI_CORS_ALLOW_ORIGINS.split(",") if o]
-
-    inner_OPENAPI_KNOWN_CLIENT_IDS: str = Field(
-        description=(
-            "Comma-separated client_id values accepted at "
-            "POST /openapi/v1/oauth/device/code. New CLIs / SDKs added here "
-            "without code changes. Unknown client_id returns 400 unsupported_client."
-        ),
-        validation_alias=AliasChoices("OPENAPI_KNOWN_CLIENT_IDS"),
-        default="difyctl",
-    )
-
-    @computed_field  # type: ignore[misc]
-    @property
-    def OPENAPI_KNOWN_CLIENT_IDS(self) -> frozenset[str]:
-        return frozenset(c for c in self.inner_OPENAPI_KNOWN_CLIENT_IDS.split(",") if c)
-
     HTTP_REQUEST_MAX_CONNECT_TIMEOUT: int = Field(
         ge=1, description="Maximum connection timeout in seconds for HTTP requests", default=10
     )
@@ -804,7 +761,7 @@ class WorkflowConfig(BaseSettings):
     # GraphEngine Worker Pool Configuration
     GRAPH_ENGINE_MIN_WORKERS: PositiveInt = Field(
         description="Minimum number of workers per GraphEngine instance",
-        default=3,
+        default=1,
     )
 
     GRAPH_ENGINE_MAX_WORKERS: PositiveInt = Field(
@@ -938,22 +895,6 @@ class AuthConfig(BaseSettings):
         default=86400,
     )
 
-    ENABLE_OAUTH_BEARER: bool = Field(
-        description="Enable OAuth bearer authentication (device-flow + Service API /v1/* bearer middleware).",
-        default=True,
-    )
-
-    OPENAPI_RATE_LIMIT_PER_TOKEN: PositiveInt = Field(
-        description="Per-token rate limit on /openapi/v1/* (requests per minute). "
-        "Bucket keyed on sha256(token), shared across api replicas via Redis.",
-        default=60,
-    )
-
-    DEVICE_FLOW_APPROVE_RATE_LIMIT_PER_HOUR: PositiveInt = Field(
-        description="Max device-flow approve requests per session per hour on /openapi/oauth/device/approve.",
-        default=10,
-    )
-
 
 class ModerationConfig(BaseSettings):
     """
@@ -1196,18 +1137,6 @@ class MultiModalTransferConfig(BaseSettings):
     )
 
 
-class OpsTraceConfig(BaseSettings):
-    OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES: PositiveInt = Field(
-        description="Maximum retry attempts for transient ops trace provider dispatch failures.",
-        default=60,
-    )
-
-    OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS: PositiveInt = Field(
-        description="Delay in seconds between transient ops trace provider dispatch retry attempts.",
-        default=5,
-    )
-
-
 class CeleryBeatConfig(BaseSettings):
     CELERY_BEAT_SCHEDULER_TIME: int = Field(
         description="Interval in days for Celery Beat scheduler execution, default to 1 day",
@@ -1240,14 +1169,6 @@ class CeleryScheduleTasksConfig(BaseSettings):
         description="Enable scheduled workflow run cleanup task",
         default=False,
     )
-    ENABLE_CLEAN_OAUTH_ACCESS_TOKENS_TASK: bool = Field(
-        description="Enable scheduled cleanup of revoked/expired OAuth access-token rows past retention.",
-        default=True,
-    )
-    OAUTH_ACCESS_TOKEN_RETENTION_DAYS: PositiveInt = Field(
-        description="Days to retain revoked OAuth access-token rows before deletion.",
-        default=30,
-    )
     ENABLE_MAIL_CLEAN_DOCUMENT_NOTIFY_TASK: bool = Field(
         description="Enable mail clean document notify task",
         default=False,
@@ -1377,7 +1298,7 @@ class PositionConfig(BaseSettings):
 class CollaborationConfig(BaseSettings):
     ENABLE_COLLABORATION_MODE: bool = Field(
         description="Whether to enable collaboration mode features across the workspace",
-        default=True,
+        default=False,
     )
 
 
@@ -1496,7 +1417,6 @@ class FeatureConfig(
     ModelLoadBalanceConfig,
     ModerationConfig,
     MultiModalTransferConfig,
-    OpsTraceConfig,
     PositionConfig,
     RagEtlConfig,
     RepositoryConfig,

api/configs/middleware/__init__.py

@@ -1,5 +1,5 @@
 import os
-from typing import Any, Literal, TypedDict, cast
+from typing import Any, Literal, TypedDict
 from urllib.parse import parse_qsl, quote_plus
 
 from pydantic import Field, NonNegativeFloat, NonNegativeInt, PositiveFloat, PositiveInt, computed_field
@@ -50,30 +50,28 @@ from .vdb.vastbase_vector_config import VastbaseVectorConfig
 from .vdb.vikingdb_config import VikingDBConfig
 from .vdb.weaviate_config import WeaviateConfig
 
-_VALID_STORAGE_TYPE = Literal[
-    "opendal",
-    "s3",
-    "aliyun-oss",
-    "azure-blob",
-    "baidu-obs",
-    "clickzetta-volume",
-    "google-storage",
-    "huawei-obs",
-    "oci-storage",
-    "tencent-cos",
-    "volcengine-tos",
-    "supabase",
-    "local",
-]
-
 
 class StorageConfig(BaseSettings):
-    STORAGE_TYPE: _VALID_STORAGE_TYPE = Field(
+    STORAGE_TYPE: Literal[
+        "opendal",
+        "s3",
+        "aliyun-oss",
+        "azure-blob",
+        "baidu-obs",
+        "clickzetta-volume",
+        "google-storage",
+        "huawei-obs",
+        "oci-storage",
+        "tencent-cos",
+        "volcengine-tos",
+        "supabase",
+        "local",
+    ] = Field(
         description="Type of storage to use."
         " Options: 'opendal', '(deprecated) local', 's3', 'aliyun-oss', 'azure-blob', 'baidu-obs', "
         "'clickzetta-volume', 'google-storage', 'huawei-obs', 'oci-storage', 'tencent-cos', "
         "'volcengine-tos', 'supabase'. Default is 'opendal'.",
-        default=cast(_VALID_STORAGE_TYPE, "opendal"),
+        default="opendal",
     )
 
     STORAGE_LOCAL_PATH: str = Field(

api/configs/middleware/cache/redis_pubsub_config.py

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

api/configs/middleware/vdb/milvus_config.py

@@ -41,21 +41,3 @@ class MilvusConfig(BaseSettings):
         description='Milvus text analyzer parameters, e.g., {"type": "chinese"} for Chinese segmentation support.',
         default=None,
     )
-
-    MILVUS_SECURE: bool = Field(
-        description="Enable TLS for the Milvus connection (one-way TLS). When True, the client uses gRPC over TLS "
-        "and verifies the server certificate. Equivalent to passing secure=True to pymilvus.",
-        default=False,
-    )
-
-    MILVUS_SERVER_PEM_PATH: str | None = Field(
-        description="Filesystem path inside the container to the Milvus server certificate (PEM). Mount this via "
-        "a Kubernetes secret. Used as pymilvus's server_pem_path when MILVUS_SECURE is True.",
-        default=None,
-    )
-
-    MILVUS_SERVER_NAME: str | None = Field(
-        description="Server name (TLS SNI / certificate CN or SAN) to verify against the Milvus server certificate. "
-        "Required when MILVUS_SERVER_PEM_PATH is set.",
-        default=None,
-    )

api/configs/remote_settings_sources/apollo/__init__.py

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

api/configs/remote_settings_sources/nacos/__init__.py

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

api/configs/secret_key.py

@@ -1,38 +0,0 @@
-"""SECRET_KEY persistence helpers for runtime setup."""
-
-from __future__ import annotations
-
-import secrets
-
-from extensions.ext_storage import storage
-
-GENERATED_SECRET_KEY_FILENAME = ".dify_secret_key"
-
-
-def resolve_secret_key(secret_key: str) -> str:
-    """Return an explicit SECRET_KEY or a generated key persisted in storage."""
-    if secret_key:
-        return secret_key
-
-    return _load_or_create_secret_key()
-
-
-def _load_or_create_secret_key() -> str:
-    try:
-        persisted_key = storage.load_once(GENERATED_SECRET_KEY_FILENAME).decode("utf-8").strip()
-        if persisted_key:
-            return persisted_key
-    except FileNotFoundError:
-        pass
-
-    generated_key = secrets.token_urlsafe(48)
-
-    try:
-        storage.save(GENERATED_SECRET_KEY_FILENAME, f"{generated_key}\n".encode())
-    except Exception as exc:
-        raise ValueError(
-            f"SECRET_KEY is not set and could not be generated at {GENERATED_SECRET_KEY_FILENAME}. "
-            "Set SECRET_KEY explicitly or make storage writable."
-        ) from exc
-
-    return generated_key

api/conftest.py

@@ -1,91 +0,0 @@
-"""Global pytest hooks for Dify backend tests.
-
-This root conftest is loaded before package-specific conftests, which lets tests opt
-into Docker-backed middleware before application modules read environment config.
-It intentionally lives at the API root because pytest applies conftest.py files to
-tests below their directory, and this setup is shared by api/tests and api/providers.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-
-from tests.pytest_dify import (
-    DEFAULT_MIDDLEWARE_SERVICES,
-    DEFAULT_VDB_SERVICES,
-    DockerComposeStack,
-    build_middleware_stack,
-    build_vdb_stack,
-    ensure_backend_test_environment,
-    ensure_compose_env_files,
-    parse_services,
-)
-
-_REPO_ROOT = Path(__file__).resolve().parent.parent
-_DIFY_COMPOSE_STACKS_KEY = pytest.StashKey[list[DockerComposeStack]]()
-
-# This must run at import time because package-specific conftests can import the
-# Flask app before pytest_configure hooks from this file are called.
-ensure_backend_test_environment(_REPO_ROOT)
-
-
-def pytest_addoption(parser: pytest.Parser) -> None:
-    group = parser.getgroup("dify")
-    group.addoption(
-        "--start-middleware",
-        action="store_true",
-        default=False,
-        help="Start the Docker middleware services needed by API integration tests.",
-    )
-    group.addoption(
-        "--middleware-services",
-        default=",".join(DEFAULT_MIDDLEWARE_SERVICES),
-        help="Comma-separated services from docker/docker-compose.middleware.yaml to start.",
-    )
-    group.addoption(
-        "--start-vdb",
-        action="store_true",
-        default=False,
-        help="Start vector-store Docker services for VDB integration tests.",
-    )
-    group.addoption(
-        "--vdb-services",
-        default=",".join(DEFAULT_VDB_SERVICES),
-        help="Comma-separated services from docker/docker-compose.yaml to start for VDB tests.",
-    )
-
-
-def pytest_configure(config: pytest.Config) -> None:
-    config.stash[_DIFY_COMPOSE_STACKS_KEY] = []
-
-
-def pytest_sessionstart(session: pytest.Session) -> None:
-    config = session.config
-    if hasattr(config, "workerinput"):
-        return
-
-    stacks: list[DockerComposeStack] = []
-    if config.getoption("start_middleware"):
-        ensure_compose_env_files(_REPO_ROOT)
-        stack = build_middleware_stack(_REPO_ROOT, parse_services(config.getoption("middleware_services")))
-        stack.up()
-        stacks.append(stack)
-
-    if config.getoption("start_vdb"):
-        ensure_compose_env_files(_REPO_ROOT)
-        stack = build_vdb_stack(_REPO_ROOT, parse_services(config.getoption("vdb_services")))
-        stack.up()
-        stacks.append(stack)
-
-    config.stash[_DIFY_COMPOSE_STACKS_KEY] = stacks
-
-
-def pytest_unconfigure(config: pytest.Config) -> None:
-    if hasattr(config, "workerinput"):
-        return
-
-    stacks = config.stash.get(_DIFY_COMPOSE_STACKS_KEY, [])
-    for stack in reversed(stacks):
-        stack.down()

api/constants/model_template.py

@@ -81,15 +81,4 @@ default_app_templates: Mapping[AppMode, Mapping] = {
             },
         },
     },
-    # agent default mode (new Agent App type). The runtime model / prompt / tools
-    # come from the bound Agent Soul snapshot, so no model_config is seeded in the
-    # template; create_app still creates a model-less app_model_config row to hold
-    # app-level presentation features (opener, follow-up, citations, ...).
-    AppMode.AGENT: {
-        "app": {
-            "mode": AppMode.AGENT,
-            "enable_site": True,
-            "enable_api": True,
-        },
-    },
 }

api/context/execution_context.py

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

api/context/flask_app_context.py

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

api/controllers/API_SCHEMA_GUIDE.md

@@ -34,7 +34,6 @@ from controllers.common.schema import (
     register_response_schema_models,
     register_schema_models,
 )
-from libs.helper import dump_response
 ```
 
 Register request payload and query models with `register_schema_models(...)`:
@@ -83,7 +82,7 @@ register_schema_models(console_ns, DraftWorkflowNodeRunPayload)
 def post(self, app_model: App, node_id: str):
     payload = DraftWorkflowNodeRunPayload.model_validate(console_ns.payload or {})
     result = service.run(..., inputs=payload.inputs, query=payload.query)
-    return dump_response(WorkflowRunNodeExecutionResponse, result)
+    return WorkflowRunNodeExecutionResponse.model_validate(result, from_attributes=True).model_dump(mode="json")
 ```
 
 ## Query Parameters
@@ -106,7 +105,7 @@ class WorkflowRunListQuery(BaseModel):
 def get(self, app_model: App):
     query = WorkflowRunListQuery.model_validate(request.args.to_dict(flat=True))
     result = service.list(..., limit=query.limit, last_id=query.last_id)
-    return dump_response(WorkflowRunPaginationResponse, result)
+    return WorkflowRunPaginationResponse.model_validate(result, from_attributes=True).model_dump(mode="json")
 ```
 
 Do not do this for GET query parameters:
@@ -146,25 +145,10 @@ def post(...):
 Serialize explicitly:
 
 ```python
-return dump_response(WorkflowRunNodeExecutionResponse, workflow_node_execution)
-```
-
-`dump_response(...)` is the preferred response serialization helper for a single Pydantic response DTO. It validates
-with `from_attributes=True` and returns `model_dump(mode="json")`, so SQLAlchemy models, plain objects, dictionaries,
-Pydantic aliases, computed fields, and `datetime` values are serialized consistently.
-
-For wrapper responses, pass a dictionary with the public wrapper fields:
-
-```python
-return dump_response(
-    WorkflowRunPaginationResponse,
-    {
-        "data": workflow_runs,
-        "page": page,
-        "limit": limit,
-        "has_more": has_more,
-    },
-)
+return WorkflowRunNodeExecutionResponse.model_validate(
+    workflow_node_execution,
+    from_attributes=True,
+).model_dump(mode="json")
 ```
 
 If the service can return `None`, translate that into the expected HTTP error before validation:
@@ -174,12 +158,9 @@ workflow_run = service.get_workflow_run(...)
 if workflow_run is None:
     raise NotFound("Workflow run not found")
 
-return dump_response(WorkflowRunDetailResponse, workflow_run)
+return WorkflowRunDetailResponse.model_validate(workflow_run, from_attributes=True).model_dump(mode="json")
 ```
 
-Use manual `model_validate(...).model_dump(...)` only when the endpoint needs behavior that `dump_response(...)` does
-not provide, such as returning a non-dict payload, intentionally excluding fields, or composing a `(body, status)` tuple.
-
 ## Legacy Flask-RESTX Patterns
 
 Avoid adding these patterns to new or migrated endpoints:
@@ -209,3 +190,4 @@ Inspect affected endpoints with `jq`. Check that:
 - Request bodies appear only where the endpoint has a body.
 - Responses reference the expected `*Response` schema.
 - Response schemas use public serialized names, not internal validation aliases like `inputs_dict`.
+

api/controllers/common/fields.py

@@ -2,9 +2,8 @@ from __future__ import annotations
 
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, computed_field
+from pydantic import BaseModel, ConfigDict, computed_field
 
-from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
 from models.model import IconType
 
@@ -20,113 +19,6 @@ class SystemParameters(BaseModel):
     workflow_file_upload_limit: int
 
 
-class SimpleResultResponse(ResponseModel):
-    result: str
-
-
-class SimpleResultMessageResponse(ResponseModel):
-    result: str
-    message: str
-
-
-class SimpleMessageResponse(ResponseModel):
-    message: str
-
-
-class SimpleDataResponse(ResponseModel):
-    data: str
-
-
-class SimpleResultDataResponse(ResponseModel):
-    result: str
-    data: str
-
-
-class SimpleResultStringListResponse(ResponseModel):
-    result: str
-    data: list[str]
-
-
-class SimpleResultOptionalDataResponse(ResponseModel):
-    result: str
-    data: str | None = None
-
-
-class AccessTokenData(ResponseModel):
-    access_token: str
-
-
-class AccessTokenResultResponse(ResponseModel):
-    result: str
-    data: AccessTokenData
-
-
-class VerificationTokenResponse(ResponseModel):
-    is_valid: bool
-    email: str
-    token: str
-
-
-class LoginStatusResponse(ResponseModel):
-    logged_in: bool
-    app_logged_in: bool
-
-
-class AccessModeResponse(ResponseModel):
-    access_mode: str = Field(serialization_alias="accessMode", validation_alias="accessMode")
-
-
-class BooleanResultResponse(ResponseModel):
-    result: bool
-
-
-class SuccessResponse(ResponseModel):
-    success: bool
-
-
-class UsageCheckResponse(ResponseModel):
-    is_using: bool
-
-
-class UsageCountResponse(ResponseModel):
-    is_using: bool
-    count: int
-
-
-class IndexInfoResponse(ResponseModel):
-    welcome: str
-    api_version: str
-    server_version: str
-
-
-class AvatarUrlResponse(ResponseModel):
-    avatar_url: str
-
-
-class TextContentResponse(ResponseModel):
-    content: str
-
-
-class AllowedExtensionsResponse(ResponseModel):
-    allowed_extensions: list[str]
-
-
-class UrlResponse(ResponseModel):
-    url: str
-
-
-class RedirectUrlResponse(ResponseModel):
-    redirect_url: str
-
-
-class ApiBaseUrlResponse(ResponseModel):
-    api_base_url: str
-
-
-class NewAppResponse(ResponseModel):
-    new_app_id: str
-
-
 class Parameters(BaseModel):
     opening_statement: str | None = None
     suggested_questions: list[str]

api/controllers/common/helpers.py

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

api/controllers/common/human_input.py

@@ -1,51 +1,6 @@
-import json
-
-from pydantic import BaseModel, Field, JsonValue
-
-HUMAN_INPUT_FORM_INPUT_EXAMPLE = {
-    "decision": "approve",
-    "attachment": {
-        "transfer_method": "local_file",
-        "upload_file_id": "4e0d1b87-52f2-49f6-b8c6-95cd9c954b3e",
-        "type": "document",
-    },
-    "attachments": [
-        {
-            "transfer_method": "local_file",
-            "upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee",
-            "type": "document",
-        },
-        {
-            "transfer_method": "remote_url",
-            "url": "https://example.com/report.pdf",
-            "type": "document",
-        },
-    ],
-}
+from pydantic import BaseModel, JsonValue
 
 
 class HumanInputFormSubmitPayload(BaseModel):
-    inputs: dict[str, JsonValue] = Field(
-        description=(
-            "Submitted human input values keyed by output variable name. "
-            "Use a string for paragraph or select input values, a file mapping for file inputs, "
-            "and a list of file mappings for file-list inputs. Local file mappings use "
-            "`transfer_method=local_file` with `upload_file_id`; remote file mappings use "
-            "`transfer_method=remote_url` with `url` or `remote_url`."
-        ),
-        examples=[HUMAN_INPUT_FORM_INPUT_EXAMPLE],
-    )
+    inputs: dict[str, JsonValue]
     action: str
-
-
-def stringify_form_default_values(values: dict[str, object]) -> dict[str, str]:
-    """Serialize default values into strings expected by human-input form clients."""
-    result: dict[str, str] = {}
-    for key, value in values.items():
-        if value is None:
-            result[key] = ""
-        elif isinstance(value, (dict, list)):
-            result[key] = json.dumps(value, ensure_ascii=False)
-        else:
-            result[key] = str(value)
-    return result

api/controllers/common/schema.py

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

api/controllers/console/__init__.py

@@ -33,6 +33,7 @@ for module_name in RESOURCE_MODULES:
 # Ensure resource modules are imported so route decorators are evaluated.
 # Import other controllers
 from . import (
+    admin,
     apikey,
     extension,
     feature,
@@ -44,16 +45,11 @@ from . import (
     spec,
     version,
 )
-from .agent import composer as agent_composer
-from .agent import roster as agent_roster
 
 # Import app controllers
 from .app import (
     advanced_prompt_template,
     agent,
-    agent_app_access,
-    agent_app_feature,
-    agent_app_workspace,
     annotation,
     app,
     audio,
@@ -71,7 +67,6 @@ from .app import (
     workflow_app_log,
     workflow_comment,
     workflow_draft_variable,
-    workflow_node_output_inspector,
     workflow_run,
     workflow_statistic,
     workflow_trigger,
@@ -122,7 +117,7 @@ from .explore import (
     saved_message,
     trial,
 )
-from .socketio import workflow as socketio_workflow
+from .socketio import workflow as socketio_workflow  # pyright: ignore[reportUnusedImport]
 
 # Import tag controllers
 from .tag import tags
@@ -147,14 +142,10 @@ api.add_namespace(console_ns)
 __all__ = [
     "account",
     "activate",
+    "admin",
     "advanced_prompt_template",
     "agent",
-    "agent_app_access",
-    "agent_app_feature",
-    "agent_app_workspace",
-    "agent_composer",
     "agent_providers",
-    "agent_roster",
     "annotation",
     "api",
     "apikey",
@@ -225,7 +216,6 @@ __all__ = [
     "workflow_app_log",
     "workflow_comment",
     "workflow_draft_variable",
-    "workflow_node_output_inspector",
     "workflow_run",
     "workflow_statistic",
     "workflow_trigger",

api/controllers/console/admin.py

@@ -1,11 +1,64 @@
+import csv
+import io
 from collections.abc import Callable
 from functools import wraps
+from typing import cast
+from uuid import UUID
 
 from flask import request
-from werkzeug.exceptions import Unauthorized
+from flask_restx import Resource
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+from werkzeug.exceptions import BadRequest, NotFound, Unauthorized
 
 from configs import dify_config
+from constants.languages import supported_language
+from controllers.common.schema import register_schema_models
+from controllers.console import console_ns
+from controllers.console.wraps import only_edition_cloud
+from core.db.session_factory import session_factory
+from extensions.ext_database import db
 from libs.token import extract_access_token
+from models.model import App, ExporleBanner, InstalledApp, RecommendedApp, TrialApp
+from services.billing_service import BillingService, LangContentDict
+
+
+class InsertExploreAppPayload(BaseModel):
+    app_id: str = Field(...)
+    desc: str | None = None
+    copyright: str | None = None
+    privacy_policy: str | None = None
+    custom_disclaimer: str | None = None
+    language: str = Field(...)
+    category: str = Field(...)
+    position: int = Field(...)
+    can_trial: bool = Field(default=False)
+    trial_limit: int = Field(default=0)
+
+    @field_validator("language")
+    @classmethod
+    def validate_language(cls, value: str) -> str:
+        return supported_language(value)
+
+
+class InsertExploreBannerPayload(BaseModel):
+    category: str = Field(...)
+    title: str = Field(...)
+    description: str = Field(...)
+    img_src: str = Field(..., alias="img-src")
+    language: str = Field(default="en-US")
+    link: str = Field(...)
+    sort: int = Field(...)
+
+    @field_validator("language")
+    @classmethod
+    def validate_language(cls, value: str) -> str:
+        return supported_language(value)
+
+    model_config = {"populate_by_name": True}
+
+
+register_schema_models(console_ns, InsertExploreAppPayload, InsertExploreBannerPayload)
 
 
 def admin_required[**P, R](view: Callable[P, R]) -> Callable[P, R]:
@@ -23,3 +76,353 @@ def admin_required[**P, R](view: Callable[P, R]) -> Callable[P, R]:
         return view(*args, **kwargs)
 
     return decorated
+
+
+@console_ns.route("/admin/insert-explore-apps")
+class InsertExploreAppListApi(Resource):
+    @console_ns.doc("insert_explore_app")
+    @console_ns.doc(description="Insert or update an app in the explore list")
+    @console_ns.expect(console_ns.models[InsertExploreAppPayload.__name__])
+    @console_ns.response(200, "App updated successfully")
+    @console_ns.response(201, "App inserted successfully")
+    @console_ns.response(404, "App not found")
+    @only_edition_cloud
+    @admin_required
+    def post(self):
+        payload = InsertExploreAppPayload.model_validate(console_ns.payload)
+
+        app = db.session.execute(select(App).where(App.id == payload.app_id)).scalar_one_or_none()
+        if not app:
+            raise NotFound(f"App '{payload.app_id}' is not found")
+
+        site = app.site
+        if not site:
+            desc = payload.desc or ""
+            copy_right = payload.copyright or ""
+            privacy_policy = payload.privacy_policy or ""
+            custom_disclaimer = payload.custom_disclaimer or ""
+        else:
+            desc = site.description or payload.desc or ""
+            copy_right = site.copyright or payload.copyright or ""
+            privacy_policy = site.privacy_policy or payload.privacy_policy or ""
+            custom_disclaimer = site.custom_disclaimer or payload.custom_disclaimer or ""
+
+        with session_factory.create_session() as session:
+            recommended_app = session.execute(
+                select(RecommendedApp).where(RecommendedApp.app_id == payload.app_id)
+            ).scalar_one_or_none()
+
+            if not recommended_app:
+                recommended_app = RecommendedApp(
+                    app_id=app.id,
+                    description=desc,
+                    copyright=copy_right,
+                    privacy_policy=privacy_policy,
+                    custom_disclaimer=custom_disclaimer,
+                    language=payload.language,
+                    category=payload.category,
+                    position=payload.position,
+                )
+
+                db.session.add(recommended_app)
+                if payload.can_trial:
+                    trial_app = db.session.execute(
+                        select(TrialApp).where(TrialApp.app_id == payload.app_id)
+                    ).scalar_one_or_none()
+                    if not trial_app:
+                        db.session.add(
+                            TrialApp(
+                                app_id=payload.app_id,
+                                tenant_id=app.tenant_id,
+                                trial_limit=payload.trial_limit,
+                            )
+                        )
+                    else:
+                        trial_app.trial_limit = payload.trial_limit
+
+                app.is_public = True
+                db.session.commit()
+
+                return {"result": "success"}, 201
+            else:
+                recommended_app.description = desc
+                recommended_app.copyright = copy_right
+                recommended_app.privacy_policy = privacy_policy
+                recommended_app.custom_disclaimer = custom_disclaimer
+                recommended_app.language = payload.language
+                recommended_app.category = payload.category
+                recommended_app.position = payload.position
+
+                if payload.can_trial:
+                    trial_app = db.session.execute(
+                        select(TrialApp).where(TrialApp.app_id == payload.app_id)
+                    ).scalar_one_or_none()
+                    if not trial_app:
+                        db.session.add(
+                            TrialApp(
+                                app_id=payload.app_id,
+                                tenant_id=app.tenant_id,
+                                trial_limit=payload.trial_limit,
+                            )
+                        )
+                    else:
+                        trial_app.trial_limit = payload.trial_limit
+                app.is_public = True
+
+                db.session.commit()
+
+                return {"result": "success"}, 200
+
+
+@console_ns.route("/admin/insert-explore-apps/<uuid:app_id>")
+class InsertExploreAppApi(Resource):
+    @console_ns.doc("delete_explore_app")
+    @console_ns.doc(description="Remove an app from the explore list")
+    @console_ns.doc(params={"app_id": "Application ID to remove"})
+    @console_ns.response(204, "App removed successfully")
+    @only_edition_cloud
+    @admin_required
+    def delete(self, app_id: UUID):
+        with session_factory.create_session() as session:
+            recommended_app = session.execute(
+                select(RecommendedApp).where(RecommendedApp.app_id == str(app_id))
+            ).scalar_one_or_none()
+
+        if not recommended_app:
+            return {"result": "success"}, 204
+
+        with session_factory.create_session() as session:
+            app = session.execute(select(App).where(App.id == recommended_app.app_id)).scalar_one_or_none()
+
+        if app:
+            app.is_public = False
+
+        with session_factory.create_session() as session:
+            installed_apps = (
+                session.execute(
+                    select(InstalledApp).where(
+                        InstalledApp.app_id == recommended_app.app_id,
+                        InstalledApp.tenant_id != InstalledApp.app_owner_tenant_id,
+                    )
+                )
+                .scalars()
+                .all()
+            )
+
+            for installed_app in installed_apps:
+                session.delete(installed_app)
+
+            trial_app = session.execute(
+                select(TrialApp).where(TrialApp.app_id == recommended_app.app_id)
+            ).scalar_one_or_none()
+            if trial_app:
+                session.delete(trial_app)
+
+        db.session.delete(recommended_app)
+        db.session.commit()
+
+        return {"result": "success"}, 204
+
+
+@console_ns.route("/admin/insert-explore-banner")
+class InsertExploreBannerApi(Resource):
+    @console_ns.doc("insert_explore_banner")
+    @console_ns.doc(description="Insert an explore banner")
+    @console_ns.expect(console_ns.models[InsertExploreBannerPayload.__name__])
+    @console_ns.response(201, "Banner inserted successfully")
+    @only_edition_cloud
+    @admin_required
+    def post(self):
+        payload = InsertExploreBannerPayload.model_validate(console_ns.payload)
+
+        banner = ExporleBanner(
+            content={
+                "category": payload.category,
+                "title": payload.title,
+                "description": payload.description,
+                "img-src": payload.img_src,
+            },
+            link=payload.link,
+            sort=payload.sort,
+            language=payload.language,
+        )
+        db.session.add(banner)
+        db.session.commit()
+
+        return {"result": "success"}, 201
+
+
+@console_ns.route("/admin/delete-explore-banner/<uuid:banner_id>")
+class DeleteExploreBannerApi(Resource):
+    @console_ns.doc("delete_explore_banner")
+    @console_ns.doc(description="Delete an explore banner")
+    @console_ns.doc(params={"banner_id": "Banner ID to delete"})
+    @console_ns.response(204, "Banner deleted successfully")
+    @only_edition_cloud
+    @admin_required
+    def delete(self, banner_id):
+        banner = db.session.execute(select(ExporleBanner).where(ExporleBanner.id == banner_id)).scalar_one_or_none()
+        if not banner:
+            raise NotFound(f"Banner '{banner_id}' is not found")
+
+        db.session.delete(banner)
+        db.session.commit()
+
+        return {"result": "success"}, 204
+
+
+class LangContentPayload(BaseModel):
+    lang: str = Field(..., description="Language tag: 'zh' | 'en' | 'jp'")
+    title: str = Field(...)
+    subtitle: str | None = Field(default=None)
+    body: str = Field(...)
+    title_pic_url: str | None = Field(default=None)
+
+
+class UpsertNotificationPayload(BaseModel):
+    notification_id: str | None = Field(default=None, description="Omit to create; supply UUID to update")
+    contents: list[LangContentPayload] = Field(..., min_length=1)
+    start_time: str | None = Field(default=None, description="RFC3339, e.g. 2026-03-01T00:00:00Z")
+    end_time: str | None = Field(default=None, description="RFC3339, e.g. 2026-03-20T23:59:59Z")
+    frequency: str = Field(default="once", description="'once' | 'every_page_load'")
+    status: str = Field(default="active", description="'active' | 'inactive'")
+
+
+class BatchAddNotificationAccountsPayload(BaseModel):
+    notification_id: str = Field(...)
+    user_email: list[str] = Field(..., description="List of account email addresses")
+
+
+register_schema_models(console_ns, UpsertNotificationPayload, BatchAddNotificationAccountsPayload)
+
+
+@console_ns.route("/admin/upsert_notification")
+class UpsertNotificationApi(Resource):
+    @console_ns.doc("upsert_notification")
+    @console_ns.doc(
+        description=(
+            "Create or update an in-product notification. "
+            "Supply notification_id to update an existing one; omit it to create a new one. "
+            "Pass at least one language variant in contents (zh / en / jp)."
+        )
+    )
+    @console_ns.expect(console_ns.models[UpsertNotificationPayload.__name__])
+    @console_ns.response(200, "Notification upserted successfully")
+    @only_edition_cloud
+    @admin_required
+    def post(self):
+        payload = UpsertNotificationPayload.model_validate(console_ns.payload)
+        result = BillingService.upsert_notification(
+            contents=[cast(LangContentDict, c.model_dump()) for c in payload.contents],
+            frequency=payload.frequency,
+            status=payload.status,
+            notification_id=payload.notification_id,
+            start_time=payload.start_time,
+            end_time=payload.end_time,
+        )
+        return {"result": "success", "notification_id": result.get("notificationId")}, 200
+
+
+@console_ns.route("/admin/batch_add_notification_accounts")
+class BatchAddNotificationAccountsApi(Resource):
+    @console_ns.doc("batch_add_notification_accounts")
+    @console_ns.doc(
+        description=(
+            "Register target accounts for a notification by email address. "
+            'JSON body: {"notification_id": "...", "user_email": ["a@example.com", ...]}. '
+            "File upload: multipart/form-data with a 'file' field (CSV or TXT, one email per line) "
+            "plus a 'notification_id' field. "
+            "Emails that do not match any account are silently skipped."
+        )
+    )
+    @console_ns.response(200, "Accounts added successfully")
+    @only_edition_cloud
+    @admin_required
+    def post(self):
+        from models.account import Account
+
+        if "file" in request.files:
+            notification_id = request.form.get("notification_id", "").strip()
+            if not notification_id:
+                raise BadRequest("notification_id is required.")
+            emails = self._parse_emails_from_file()
+        else:
+            payload = BatchAddNotificationAccountsPayload.model_validate(console_ns.payload)
+            notification_id = payload.notification_id
+            emails = payload.user_email
+
+        if not emails:
+            raise BadRequest("No valid email addresses provided.")
+
+        # Resolve emails → account IDs in chunks to avoid large IN-clause
+        account_ids: list[str] = []
+        chunk_size = 500
+        for i in range(0, len(emails), chunk_size):
+            chunk = emails[i : i + chunk_size]
+            rows = db.session.execute(select(Account.id, Account.email).where(Account.email.in_(chunk))).all()
+            account_ids.extend(str(row.id) for row in rows)
+
+        if not account_ids:
+            raise BadRequest("None of the provided emails matched an existing account.")
+
+        # Send to dify-saas in batches of 1000
+        total_count = 0
+        batch_size = 1000
+        for i in range(0, len(account_ids), batch_size):
+            batch = account_ids[i : i + batch_size]
+            result = BillingService.batch_add_notification_accounts(
+                notification_id=notification_id,
+                account_ids=batch,
+            )
+            total_count += result.get("count", 0)
+
+        return {
+            "result": "success",
+            "emails_provided": len(emails),
+            "accounts_matched": len(account_ids),
+            "count": total_count,
+        }, 200
+
+    @staticmethod
+    def _parse_emails_from_file() -> list[str]:
+        """Parse email addresses from an uploaded CSV or TXT file."""
+        file = request.files["file"]
+        if not file.filename:
+            raise BadRequest("Uploaded file has no filename.")
+
+        filename_lower = file.filename.lower()
+        if not filename_lower.endswith((".csv", ".txt")):
+            raise BadRequest("Invalid file type. Only CSV (.csv) and TXT (.txt) files are allowed.")
+
+        try:
+            content = file.stream.read().decode("utf-8")
+        except UnicodeDecodeError:
+            try:
+                file.stream.seek(0)
+                content = file.stream.read().decode("gbk")
+            except UnicodeDecodeError:
+                raise BadRequest("Unable to decode the file. Please use UTF-8 or GBK encoding.")
+
+        emails: list[str] = []
+        if filename_lower.endswith(".csv"):
+            reader = csv.reader(io.StringIO(content))
+            for row in reader:
+                for cell in row:
+                    cell = cell.strip()
+                    if cell:
+                        emails.append(cell)
+        else:
+            for line in content.splitlines():
+                line = line.strip()
+                if line:
+                    emails.append(line)
+
+        # Deduplicate while preserving order
+        seen: set[str] = set()
+        unique_emails: list[str] = []
+        for email in emails:
+            if email.lower() not in seen:
+                seen.add(email.lower())
+                unique_emails.append(email)
+
+        return unique_emails