chore: exclude api and dify-agent from fmt

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

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

@@ -28,6 +28,7 @@ Follow these steps when using this skill:
 3. Compose the final output strictly follow the **Required Output Format**.
 
 Notes when using this skill:
+
 - Always include actionable fixes or suggestions (including possible code snippets).
 - Use best-effort `File:Line` references when a file path and line numbers are available; otherwise, use the most specific identifier you can.
 
@@ -43,6 +44,7 @@ Notes when using this skill:
 ### 1. Security Review
 
 Check for:
+
 - SQL injection vulnerabilities
 - Server-Side Request Forgery (SSRF)
 - Command injection
@@ -54,6 +56,7 @@ Check for:
 ### 2. Performance Review
 
 Check for:
+
 - N+1 queries
 - Missing database indexes
 - Memory leaks
@@ -63,6 +66,7 @@ Check for:
 ### 3. Code Quality Review
 
 Check for:
+
 - Code forward compatibility
 - Code duplication (DRY violations)
 - Functions doing too much (SRP violations)
@@ -75,6 +79,7 @@ Check for:
 ### 4. Testing Review
 
 Check for:
+
 - Missing test coverage for new code
 - Tests that don't test behavior
 - Flaky test patterns
@@ -108,6 +113,7 @@ FilePath: <path> line <line>
 2. <code example> (optional, omit if not applicable)
 
 ---
+
 ... (repeat for each critical issue) ...
 
 Found <Y> suggestions for improvement:
@@ -129,11 +135,13 @@ FilePath: <path> line <line>
 2. <code example> (optional, omit if not applicable)
 
 ---
+
 ... (repeat for each suggestion) ...
 
 Found <Z> optional nits:
 
 ## 🟢 Nits (Optional)
+
 ### 1. <brief description of the nit>
 
 FilePath: <path> line <line>
@@ -148,6 +156,7 @@ FilePath: <path> line <line>
 - <minor suggestions>
 
 ---
+
 ... (repeat for each nits) ...
 
 ## ✅ What's Good
@@ -164,5 +173,6 @@ FilePath: <path> line <line>
 
 ```markdown
 ## Code Review Summary
+
 ✅ No issues found.
-```
+```

.agents/skills/backend-code-review/references/architecture-rule.md

@@ -1,11 +1,13 @@
 # Rule Catalog — Architecture
 
 ## Scope
+
 - Covers: controller/service/core-domain/libs/model layering, dependency direction, responsibility placement, observability-friendly flow.
 
 ## Rules
 
 ### Keep business logic out of controllers
+
 - Category: maintainability
 - Severity: critical
 - Description: Controllers should parse input, call services, and return serialized responses. Business decisions inside controllers make behavior hard to reuse and test.
@@ -33,12 +35,14 @@
     ```
 
 ### Preserve layer dependency direction
+
 - Category: best practices
 - Severity: critical
 - Description: Controllers may depend on services, and services may depend on core/domain abstractions. Reversing this direction (for example, core importing controller/web modules) creates cycles and leaks transport concerns into domain code.
 - Suggested fix: Extract shared contracts into core/domain or service-level modules and make upper layers depend on lower, not the reverse.
 - Example:
   - Bad:
+
     ```python
     # core/policy/publish_policy.py
     from controllers.console.app import request_context
@@ -46,7 +50,9 @@
     def can_publish() -> bool:
         return request_context.current_user.is_admin
     ```
+
   - Good:
+
     ```python
     # core/policy/publish_policy.py
     def can_publish(role: str) -> bool:
@@ -57,6 +63,7 @@
     ```
 
 ### Keep libs business-agnostic
+
 - Category: maintainability
 - Severity: critical
 - Description: Modules under `api/libs/` should remain reusable, business-agnostic building blocks. They must not encode product/domain-specific rules, workflow orchestration, or business decisions.
@@ -65,6 +72,7 @@
   - Keep `libs` dependencies clean: avoid importing service/controller/domain-specific modules into `api/libs/`.
 - Example:
   - Bad:
+
     ```python
     # api/libs/conversation_filter.py
     from services.conversation_service import ConversationService
@@ -76,7 +84,9 @@
             return conversation.idle_days > 90
         return conversation.idle_days > 30
     ```
+
   - Good:
+
     ```python
     # api/libs/datetime_utils.py (business-agnostic helper)
     def older_than_days(idle_days: int, threshold_days: int) -> bool:
@@ -88,4 +98,4 @@
     def should_archive_conversation(conversation, tenant_id: str) -> bool:
         threshold_days = 90 if has_paid_plan(tenant_id) else 30
         return older_than_days(conversation.idle_days, threshold_days)
-    ```
+    ```

.agents/skills/backend-code-review/references/db-schema-rule.md

@@ -1,12 +1,14 @@
 # Rule Catalog — DB Schema Design
 
 ## Scope
+
 - Covers: model/base inheritance, schema boundaries in model properties, tenant-aware schema design, index redundancy checks, dialect portability in models, and cross-database compatibility in migrations.
 - Does NOT cover: session lifecycle, transaction boundaries, and query execution patterns (handled by `sqlalchemy-rule.md`).
 
 ## Rules
 
 ### Do not query other tables inside `@property`
+
 - Category: [maintainability, performance]
 - Severity: critical
 - Description: A model `@property` must not open sessions or query other tables. This hides dependencies across models, tightly couples schema objects to data access, and can cause N+1 query explosions when iterating collections.
@@ -16,6 +18,7 @@
   - For list/batch reads, fetch required related data explicitly (join/preload/bulk query) before rendering derived values.
 - Example:
   - Bad:
+
     ```python
     class Conversation(TypeBase):
         __tablename__ = "conversations"
@@ -26,7 +29,9 @@
                 app = session.execute(select(App).where(App.id == self.app_id)).scalar_one()
                 return app.name
     ```
+
   - Good:
+
     ```python
     class Conversation(TypeBase):
         __tablename__ = "conversations"
@@ -40,6 +45,7 @@
     ```
 
 ### Prefer including `tenant_id` in model definitions
+
 - Category: maintainability
 - Severity: suggestion
 - Description: In multi-tenant domains, include `tenant_id` in schema definitions whenever the entity belongs to tenant-owned data. This improves data isolation safety and keeps future partitioning/sharding strategies practical as data volume grows.
@@ -49,6 +55,7 @@
   - Exception: if a table is explicitly designed as non-tenant-scoped global metadata, document that design decision clearly.
 - Example:
   - Bad:
+
     ```python
     from sqlalchemy.orm import Mapped
 
@@ -57,7 +64,9 @@
         id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
         name: Mapped[str] = mapped_column(sa.String(255), nullable=False)
     ```
+
   - Good:
+
     ```python
     from sqlalchemy.orm import Mapped
 
@@ -69,6 +78,7 @@
     ```
 
 ### Detect and avoid duplicate/redundant indexes
+
 - Category: performance
 - Severity: suggestion
 - Description: Review index definitions for leftmost-prefix redundancy. For example, index `(a, b, c)` can safely cover most lookups for `(a, b)`. Keeping both may increase write overhead and can mislead the optimizer into suboptimal execution plans.
@@ -93,6 +103,7 @@
     ```
 
 ### Avoid PostgreSQL-only dialect usage in models; wrap in `models.types`
+
 - Category: maintainability
 - Severity: critical
 - Description: Model/schema definitions should avoid PostgreSQL-only constructs directly in business models. When database-specific behavior is required, encapsulate it in `api/models/types.py` using both PostgreSQL and MySQL dialect implementations, then consume that abstraction from model code.
@@ -101,6 +112,7 @@
   - Add or extend wrappers in `models.types` (for example, `AdjustedJSON`, `LongText`, `BinaryData`) to normalize behavior across PostgreSQL and MySQL.
 - Example:
   - Bad:
+
     ```python
     from sqlalchemy.dialects.postgresql import JSONB
     from sqlalchemy.orm import Mapped
@@ -109,7 +121,9 @@
         __tablename__ = "tool_configs"
         config: Mapped[dict] = mapped_column(JSONB, nullable=False)
     ```
+
   - Good:
+
     ```python
     from sqlalchemy.orm import Mapped
 
@@ -121,6 +135,7 @@
     ```
 
 ### Guard migration incompatibilities with dialect checks and shared types
+
 - Category: maintainability
 - Severity: critical
 - Description: Migration scripts under `api/migrations/versions/` must account for PostgreSQL/MySQL incompatibilities explicitly. For dialect-sensitive DDL or defaults, branch on the active dialect (for example, `conn.dialect.name == "postgresql"`), and prefer reusable compatibility abstractions from `models.types` where applicable.
@@ -142,6 +157,7 @@
         )
     ```
   - Good:
+
     ```python
     def _is_pg(conn) -> bool:
         return conn.dialect.name == "postgresql"

.agents/skills/backend-code-review/references/repositories-rule.md

@@ -1,17 +1,19 @@
 # Rule Catalog - Repositories Abstraction
 
 ## Scope
+
 - Covers: when to reuse existing repository abstractions, when to introduce new repositories, and how to preserve dependency direction between service/core and infrastructure implementations.
 - Does NOT cover: SQLAlchemy session lifecycle and query-shape specifics (handled by `sqlalchemy-rule.md`), and table schema/migration design (handled by `db-schema-rule.md`).
 
 ## Rules
 
 ### Introduce repositories abstraction
+
 - Category: maintainability
 - Severity: suggestion
 - Description: If a table/model already has a repository abstraction, all reads/writes/queries for that table should use the existing repository. If no repository exists, introduce one only when complexity justifies it, such as large/high-volume tables, repeated complex query logic, or likely storage-strategy variation.
 - Suggested fix:
-  - First check  `api/repositories`, `api/core/repositories`, and `api/extensions/*/repositories/` to verify whether the table/model already has a repository abstraction. If it exists, route all operations through it and add missing repository methods instead of bypassing it with ad-hoc SQLAlchemy access.
+  - First check `api/repositories`, `api/core/repositories`, and `api/extensions/*/repositories/` to verify whether the table/model already has a repository abstraction. If it exists, route all operations through it and add missing repository methods instead of bypassing it with ad-hoc SQLAlchemy access.
   - If no repository exists, add one only when complexity warrants it (for example, repeated complex queries, large data domains, or multiple storage strategies), while preserving dependency direction (service/core depends on abstraction; infra provides implementation).
 - Example:
   - Bad:
@@ -26,6 +28,7 @@
             self.session.commit()
     ```
   - Good:
+
     ```python
     # Case A: Existing repository must be reused for all table operations.
     class AppService:
@@ -37,6 +40,7 @@
     # If the query is missing, extend the existing abstraction.
     active_apps = self.app_repo.list_active_for_tenant(tenant_id=tenant_id)
     ```
+
   - Bad:
     ```python
     # No repository exists, but large-domain query logic is scattered in service code.
@@ -46,6 +50,7 @@
             # many filters/joins/pagination variants duplicated across services
     ```
   - Good:
+
     ```python
     # Case B: Introduce repository for large/complex domains or storage variation.
     class ConversationRepository(Protocol):

.agents/skills/backend-code-review/references/sqlalchemy-rule.md

@@ -1,12 +1,14 @@
 # Rule Catalog — SQLAlchemy Patterns
 
 ## Scope
+
 - Covers: SQLAlchemy session and transaction lifecycle, query construction, tenant scoping, raw SQL boundaries, and write-path concurrency safeguards.
 - Does NOT cover: table/model schema and migration design details (handled by `db-schema-rule.md`).
 
 ## Rules
 
 ### Use Session context manager with explicit transaction control behavior
+
 - Category: best practices
 - Severity: critical
 - Description: Session and transaction lifecycle must be explicit and bounded on write paths. Missing commits can silently drop intended updates, while ad-hoc or long-lived transactions increase contention, lock duration, and deadlock risk.
@@ -16,6 +18,7 @@
   - Keep transaction windows short: avoid network I/O, heavy computation, or unrelated work inside the transaction.
 - Example:
   - Bad:
+
     ```python
     # Missing commit: write may never be persisted.
     with Session(db.engine, expire_on_commit=False) as session:
@@ -28,7 +31,9 @@
         run.status = "cancelled"
         call_external_api()
     ```
+
   - Good:
+
     ```python
     # Option 1: explicit commit.
     with Session(db.engine, expire_on_commit=False) as session:
@@ -46,6 +51,7 @@
     ```
 
 ### Enforce tenant_id scoping on shared-resource queries
+
 - Category: security
 - Severity: critical
 - Description: Reads and writes against shared tables must be scoped by `tenant_id` to prevent cross-tenant data leakage or corruption.
@@ -66,6 +72,7 @@
     ```
 
 ### Prefer SQLAlchemy expressions over raw SQL by default
+
 - Category: maintainability
 - Severity: suggestion
 - Description: Raw SQL should be exceptional. ORM/Core expressions are easier to evolve, safer to compose, and more consistent with the codebase.
@@ -88,6 +95,7 @@
     ```
 
 ### Protect write paths with concurrency safeguards
+
 - Category: quality
 - Severity: critical
 - Description: Multi-writer paths without explicit concurrency control can silently overwrite data. Choose the safeguard based on contention level, lock scope, and throughput cost instead of defaulting to one strategy.
@@ -104,6 +112,7 @@
     session.commit()  # silently overwrites concurrent updates
     ```
   - Good:
+
     ```python
     # 1) Optimistic lock (low contention, retry on conflict)
     result = session.execute(
@@ -136,4 +145,4 @@
     ).scalar_one()
     run.status = "cancelled"
     session.commit()
-    ```
+    ```

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

@@ -46,12 +46,12 @@ pnpm analyze-component <path> --json
 
 ### Complexity Score Interpretation
 
-| Score | Level | Action |
-|-------|-------|--------|
-| 0-25 | 🟢 Simple | Ready for testing |
-| 26-50 | 🟡 Medium | Consider minor refactoring |
-| 51-75 | 🟠 Complex | **Refactor before testing** |
-| 76-100 | 🔴 Very Complex | **Must refactor** |
+| Score  | Level           | Action                      |
+| ------ | --------------- | --------------------------- |
+| 0-25   | 🟢 Simple       | Ready for testing           |
+| 26-50  | 🟡 Medium       | Consider minor refactoring  |
+| 51-75  | 🟠 Complex      | **Refactor before testing** |
+| 76-100 | 🔴 Very Complex | **Must refactor**           |
 
 ## Core Refactoring Patterns
 
@@ -67,9 +67,9 @@ function Configuration() {
   const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
   const [datasetConfigs, setDatasetConfigs] = useState<DatasetConfigs>(...)
   const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
+
   // 50+ lines of state management logic...
-  
+
   return <div>...</div>
 }
 
@@ -78,9 +78,9 @@ function Configuration() {
 export const useModelConfig = (appId: string) => {
   const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
   const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
+
   // Related state management logic here
-  
+
   return { modelConfig, setModelConfig, completionParams, setCompletionParams }
 }
 
@@ -92,6 +92,7 @@ function Configuration() {
 ```
 
 **Dify Examples**:
+
 - `web/app/components/app/configuration/hooks/use-advanced-prompt-config.ts`
 - `web/app/components/app/configuration/debug/hooks.tsx`
 - `web/app/components/workflow/hooks/use-workflow.ts`
@@ -123,7 +124,7 @@ const AppInfo = () => {
 
 const AppInfo = () => {
   const { showModal, setShowModal } = useAppInfoModals()
-  
+
   return (
     <div>
       <AppHeader appDetail={appDetail} />
@@ -135,6 +136,7 @@ const AppInfo = () => {
 ```
 
 **Dify Examples**:
+
 - `web/app/components/app/configuration/` directory structure
 - `web/app/components/workflow/nodes/` per-node organization
 
@@ -177,7 +179,7 @@ const TEMPLATE_MAP = {
 const Template = useMemo(() => {
   const modeTemplates = TEMPLATE_MAP[appDetail?.mode]
   if (!modeTemplates) return null
-  
+
   const TemplateComponent = modeTemplates[locale] || modeTemplates.default
   return <TemplateComponent appDetail={appDetail} />
 }, [appDetail, locale])
@@ -188,11 +190,13 @@ const Template = useMemo(() => {
 **When**: Component directly handles API calls, data transformation, or complex async operations.
 
 **Dify Convention**:
+
 - This skill is for component decomposition, not query/mutation design.
 - 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.
 
 **Dify Examples**:
+
 - `web/service/use-workflow.ts`
 - `web/service/use-common.ts`
 - `web/service/knowledge/use-dataset.ts`
@@ -220,10 +224,10 @@ type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | 'import' | null
 
 const useAppInfoModals = () => {
   const [activeModal, setActiveModal] = useState<ModalType>(null)
-  
+
   const openModal = useCallback((type: ModalType) => setActiveModal(type), [])
   const closeModal = useCallback(() => setActiveModal(null), [])
-  
+
   return {
     activeModal,
     openModal,
@@ -248,7 +252,7 @@ const ConfigForm = () => {
     defaultValues: { name: '', description: '' },
     onSubmit: handleSubmit,
   })
-  
+
   return <form.Provider>...</form.Provider>
 }
 ```
@@ -285,6 +289,7 @@ return <ConfigContext.Provider value={value}>...</ConfigContext.Provider>
 **When**: Refactoring workflow node components (`web/app/components/workflow/nodes/`).
 
 **Conventions**:
+
 - Keep node logic in `use-interactions.ts`
 - Extract panel UI to separate files
 - Use `_base` components for common patterns
@@ -303,6 +308,7 @@ nodes/<node-type>/
 **When**: Refactoring app configuration components.
 
 **Conventions**:
+
 - Separate config sections into subdirectories
 - Use existing patterns from `web/app/components/app/configuration/`
 - Keep feature toggles in dedicated components
@@ -312,6 +318,7 @@ nodes/<node-type>/
 **When**: Refactoring tool-related components (`web/app/components/tools/`).
 
 **Conventions**:
+
 - Follow existing modal patterns
 - Use service hooks from `web/service/use-tools.ts`
 - Keep provider-specific logic isolated
@@ -325,6 +332,7 @@ pnpm refactor-component <path>
 ```
 
 This command will:
+
 - Analyze component complexity and features
 - Identify specific refactoring actions needed
 - Generate a prompt for AI assistant (auto-copied to clipboard on macOS)
@@ -337,6 +345,7 @@ pnpm analyze-component <path> --json
 ```
 
 Identify:
+
 - Total complexity score
 - Max function complexity
 - Line count
@@ -346,13 +355,13 @@ Identify:
 
 Create a refactoring plan based on detected features:
 
-| Detected Feature | Refactoring Action |
-|------------------|-------------------|
-| `hasState: true` + `hasEffects: true` | Extract custom hook |
-| `hasAPI: true` | Extract data/service hook |
-| `hasEvents: true` (many) | Extract event handlers |
-| `lineCount > 300` | Split into sub-components |
-| `maxComplexity > 50` | Simplify conditional logic |
+| Detected Feature                      | Refactoring Action         |
+| ------------------------------------- | -------------------------- |
+| `hasState: true` + `hasEffects: true` | Extract custom hook        |
+| `hasAPI: true`                        | Extract data/service hook  |
+| `hasEvents: true` (many)              | Extract event handlers     |
+| `lineCount > 300`                     | Split into sub-components  |
+| `maxComplexity > 50`                  | Simplify conditional logic |
 
 ### Step 4: Execute Incrementally
 

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

@@ -13,16 +13,16 @@ The `pnpm analyze-component` tool uses SonarJS cognitive complexity metrics:
 
 ### What Increases Complexity
 
-| Pattern | Complexity Impact |
-|---------|-------------------|
-| `if/else` | +1 per branch |
-| Nested conditions | +1 per nesting level |
-| `switch/case` | +1 per case |
-| `for/while/do` | +1 per loop |
-| `&&`/`||` chains | +1 per operator |
-| Nested callbacks | +1 per nesting level |
-| `try/catch` | +1 per catch |
-| Ternary expressions | +1 per nesting |
+| Pattern             | Complexity Impact    |
+| ------------------- | -------------------- | -------- | --------------- |
+| `if/else`           | +1 per branch        |
+| Nested conditions   | +1 per nesting level |
+| `switch/case`       | +1 per case          |
+| `for/while/do`      | +1 per loop          |
+| `&&`/`              |                      | ` chains | +1 per operator |
+| Nested callbacks    | +1 per nesting level |
+| `try/catch`         | +1 per catch         |
+| Ternary expressions | +1 per nesting       |
 
 ## Pattern 1: Replace Conditionals with Lookup Tables
 
@@ -85,10 +85,10 @@ const TEMPLATE_MAP: Record<AppModeEnum, Record<string, ComponentType<TemplatePro
 // Clean component logic
 const Template = useMemo(() => {
   if (!appDetail?.mode) return null
-  
+
   const templates = TEMPLATE_MAP[appDetail.mode]
   if (!templates) return null
-  
+
   const TemplateComponent = templates[locale] ?? templates.default
   return <TemplateComponent appDetail={appDetail} />
 }, [appDetail, locale])
@@ -124,17 +124,17 @@ const handleSubmit = () => {
     showValidationError()
     return
   }
-  
+
   if (!hasChanges) {
     showNoChangesMessage()
     return
   }
-  
+
   if (!isConnected) {
     showConnectionError()
     return
   }
-  
+
   submitData()
 }
 ```
@@ -146,12 +146,10 @@ const handleSubmit = () => {
 ```typescript
 const canPublish = (() => {
   if (mode !== AppModeEnum.COMPLETION) {
-    if (!isAdvancedMode)
-      return true
+    if (!isAdvancedMode) return true
 
     if (modelModeType === ModelModeType.completion) {
-      if (!hasSetBlockStatus.history || !hasSetBlockStatus.query)
-        return false
+      if (!hasSetBlockStatus.history || !hasSetBlockStatus.query) return false
       return true
     }
     return true
@@ -173,9 +171,8 @@ const canPublishInChatMode = () => {
 }
 
 // Clean main logic
-const canPublish = mode === AppModeEnum.COMPLETION
-  ? canPublishInCompletionMode()
-  : canPublishInChatMode()
+const canPublish =
+  mode === AppModeEnum.COMPLETION ? canPublishInCompletionMode() : canPublishInChatMode()
 ```
 
 ## Pattern 4: Replace Chained Ternaries
@@ -232,7 +229,7 @@ const statusText = t(STATUS_TEXT_MAP[getStatusKey()])
 ```typescript
 const processData = (items: Item[]) => {
   const results: ProcessedItem[] = []
-  
+
   for (const item of items) {
     if (item.isValid) {
       for (const child of item.children) {
@@ -250,7 +247,7 @@ const processData = (items: Item[]) => {
       }
     }
   }
-  
+
   return results
 }
 ```
@@ -261,19 +258,19 @@ const processData = (items: Item[]) => {
 // Use functional approach
 const processData = (items: Item[]) => {
   return items
-    .filter(item => item.isValid)
-    .flatMap(item =>
+    .filter((item) => item.isValid)
+    .flatMap((item) =>
       item.children
-        .filter(child => child.isActive)
-        .flatMap(child =>
+        .filter((child) => child.isActive)
+        .flatMap((child) =>
           child.properties
-            .filter(prop => prop.value !== null)
-            .map(prop => ({
+            .filter((prop) => prop.value !== null)
+            .map((prop) => ({
               itemId: item.id,
               childId: child.id,
               propValue: prop.value,
-            }))
-        )
+            })),
+        ),
     )
 }
 ```
@@ -309,10 +306,10 @@ const Component = () => {
       setDataSets(data)
     }
     hideSelectDataSet()
-    
+
     // 40 more lines of logic...
   }
-  
+
   return <div>...</div>
 }
 ```
@@ -325,7 +322,7 @@ const useDatasetSelection = (dataSets: DataSet[], setDataSets: SetState<DataSet[
   const normalizeSelection = (data: DataSet[]) => {
     const hasUnloadedItem = data.some(item => !item.name)
     if (!hasUnloadedItem) return data
-    
+
     return produce(data, (draft) => {
       data.forEach((item, index) => {
         if (!item.name) {
@@ -335,33 +332,33 @@ const useDatasetSelection = (dataSets: DataSet[], setDataSets: SetState<DataSet[
       })
     })
   }
-  
+
   const hasSelectionChanged = (newData: DataSet[]) => {
     return !isEqual(
       newData.map(item => item.id),
       dataSets.map(item => item.id)
     )
   }
-  
+
   return { normalizeSelection, hasSelectionChanged }
 }
 
 // Component becomes cleaner
 const Component = () => {
   const { normalizeSelection, hasSelectionChanged } = useDatasetSelection(dataSets, setDataSets)
-  
+
   const handleSelect = (data: DataSet[]) => {
     if (!hasSelectionChanged(data)) {
       hideSelectDataSet()
       return
     }
-    
+
     formattingChangedDispatcher()
     const normalized = normalizeSelection(data)
     setDataSets(normalized)
     hideSelectDataSet()
   }
-  
+
   return <div>...</div>
 }
 ```
@@ -371,12 +368,13 @@ const Component = () => {
 **Before** (complexity: ~8):
 
 ```typescript
-const toggleDisabled = hasInsufficientPermissions
-  || appUnpublished
-  || missingStartNode
-  || triggerModeDisabled
-  || (isAdvancedApp && !currentWorkflow?.graph)
-  || (isBasicApp && !basicAppConfig.updated_at)
+const toggleDisabled =
+  hasInsufficientPermissions ||
+  appUnpublished ||
+  missingStartNode ||
+  triggerModeDisabled ||
+  (isAdvancedApp && !currentWorkflow?.graph) ||
+  (isBasicApp && !basicAppConfig.updated_at)
 ```
 
 **After** (complexity: ~3):
@@ -425,8 +423,7 @@ const payload = useMemo(() => {
       description: '',
       type: item.value_type,
     }))
-  }
-  else if (detail && detail.tool) {
+  } else if (detail && detail.tool) {
     parameters = (inputs || []).map((item) => ({
       // Complex transformation...
     }))
@@ -434,7 +431,7 @@ const payload = useMemo(() => {
       // Complex transformation...
     }))
   }
-  
+
   return {
     icon: detail?.icon || icon,
     label: detail?.label || name,
@@ -450,7 +447,7 @@ const payload = useMemo(() => {
 const useParameterTransform = (inputs: InputVar[], detail?: ToolDetail, published?: boolean) => {
   return useMemo(() => {
     if (!published) {
-      return inputs.map(item => ({
+      return inputs.map((item) => ({
         name: item.variable,
         description: '',
         form: 'llm',
@@ -458,15 +455,16 @@ const useParameterTransform = (inputs: InputVar[], detail?: ToolDetail, publishe
         type: item.type,
       }))
     }
-    
+
     if (!detail?.tool) return []
-    
-    return inputs.map(item => ({
+
+    return inputs.map((item) => ({
       name: item.variable,
       required: item.required,
       type: item.type === 'paragraph' ? 'string' : item.type,
-      description: detail.tool.parameters.find(p => p.name === item.variable)?.llm_description || '',
-      form: detail.tool.parameters.find(p => p.name === item.variable)?.form || 'llm',
+      description:
+        detail.tool.parameters.find((p) => p.name === item.variable)?.llm_description || '',
+      form: detail.tool.parameters.find((p) => p.name === item.variable)?.form || 'llm',
     }))
   }, [inputs, detail, published])
 }
@@ -475,21 +473,24 @@ const useParameterTransform = (inputs: InputVar[], detail?: ToolDetail, publishe
 const parameters = useParameterTransform(inputs, detail, published)
 const outputParameters = useOutputTransform(outputs, detail, published)
 
-const payload = useMemo(() => ({
-  icon: detail?.icon || icon,
-  label: detail?.label || name,
-  parameters,
-  outputParameters,
-  // ...
-}), [detail, icon, name, parameters, outputParameters])
+const payload = useMemo(
+  () => ({
+    icon: detail?.icon || icon,
+    label: detail?.label || name,
+    parameters,
+    outputParameters,
+    // ...
+  }),
+  [detail, icon, name, parameters, outputParameters],
+)
 ```
 
 ## Target Metrics After Refactoring
 
-| Metric | Target |
-|--------|--------|
-| Total Complexity | < 50 |
-| Max Function Complexity | < 30 |
-| Function Length | < 30 lines |
-| Nesting Depth | ≤ 3 levels |
-| Conditional Chains | ≤ 3 conditions |
+| Metric                  | Target         |
+| ----------------------- | -------------- |
+| Total Complexity        | < 50           |
+| Max Function Complexity | < 30           |
+| Function Length         | < 30 lines     |
+| Nesting Depth           | ≤ 3 levels     |
+| Conditional Chains      | ≤ 3 conditions |

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

@@ -32,17 +32,17 @@ const ConfigurationPage = () => {
           <AppPublisher ... />
         </div>
       </div>
-      
+
       {/* Config Section - 200 lines */}
       <div className="config">
         <Config />
       </div>
-      
+
       {/* Debug Section - 150 lines */}
       <div className="debug">
         <Debug ... />
       </div>
-      
+
       {/* Modals Section - 100 lines */}
       {showSelectDataSet && <SelectDataSet ... />}
       {showHistoryModal && <EditHistoryModal ... />}
@@ -70,7 +70,7 @@ function ConfigurationHeader({
   onPublish,
 }: ConfigurationHeaderProps) {
   const { t } = useTranslation()
-  
+
   return (
     <div className="header">
       <h1>{t('configuration.title')}</h1>
@@ -87,7 +87,7 @@ function ConfigurationHeader({
 const ConfigurationPage = () => {
   const { modelConfig, setModelConfig } = useModelConfig()
   const { activeModal, openModal, closeModal } = useModalState()
-  
+
   return (
     <div>
       <ConfigurationHeader
@@ -175,15 +175,15 @@ const AppInfo = () => {
   const [showDuplicate, setShowDuplicate] = useState(false)
   const [showDelete, setShowDelete] = useState(false)
   const [showSwitch, setShowSwitch] = useState(false)
-  
+
   const onEdit = async (data) => { /* 20 lines */ }
   const onDuplicate = async (data) => { /* 20 lines */ }
   const onDelete = async () => { /* 15 lines */ }
-  
+
   return (
     <div>
       {/* Main content */}
-      
+
       {showEdit && <EditModal onConfirm={onEdit} onClose={() => setShowEdit(false)} />}
       {showDuplicate && <DuplicateModal onConfirm={onDuplicate} onClose={() => setShowDuplicate(false)} />}
       {showDelete && <DeleteConfirm onConfirm={onDelete} onClose={() => setShowDelete(false)} />}
@@ -248,12 +248,12 @@ function AppInfoModals({
 // Parent component
 const AppInfo = () => {
   const { activeModal, openModal, closeModal } = useModalState()
-  
+
   return (
     <div>
       {/* Main content with openModal triggers */}
       <Button onClick={() => openModal('edit')}>Edit</Button>
-      
+
       <AppInfoModals
         appDetail={appDetail}
         activeModal={activeModal}
@@ -418,7 +418,7 @@ Use callbacks for child-to-parent communication:
 // Parent
 const Parent = () => {
   const [value, setValue] = useState('')
-  
+
   return (
     <Child
       value={value}
@@ -460,7 +460,7 @@ function List<T>({ items, renderItem, renderEmpty }: ListProps<T>) {
   if (items.length === 0 && renderEmpty) {
     return <>{renderEmpty()}</>
   }
-  
+
   return (
     <div>
       {items.map((item, index) => renderItem(item, index))}

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

@@ -81,9 +81,9 @@ export const useModelConfig = ({
     // ... default values
     ...initialConfig,
   })
-  
+
   const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
+
   const modelModeType = modelConfig.mode
 
   // Fill old app data missing model mode
@@ -91,9 +91,11 @@ export const useModelConfig = ({
     if (hasFetchedDetail && !modelModeType) {
       const mode = currModel?.model_properties?.mode
       if (mode) {
-        setModelConfig(produce(modelConfig, (draft) => {
-          draft.mode = mode
-        }))
+        setModelConfig(
+          produce(modelConfig, (draft) => {
+            draft.mode = mode
+          }),
+        )
       }
     }
   }, [hasFetchedDetail, modelModeType, currModel])
@@ -129,7 +131,7 @@ function Configuration() {
     currModel,
     hasFetchedDetail,
   })
-  
+
   // Component now focuses on UI
 }
 ```
@@ -179,18 +181,21 @@ export const useConfigForm = (initialValues: ConfigFormValues) => {
   }, [values])
 
   const handleChange = useCallback((field: string, value: any) => {
-    setValues(prev => ({ ...prev, [field]: value }))
+    setValues((prev) => ({ ...prev, [field]: value }))
   }, [])
 
-  const handleSubmit = useCallback(async (onSubmit: (values: ConfigFormValues) => Promise<void>) => {
-    if (!validate()) return
-    setIsSubmitting(true)
-    try {
-      await onSubmit(values)
-    } finally {
-      setIsSubmitting(false)
-    }
-  }, [values, validate])
+  const handleSubmit = useCallback(
+    async (onSubmit: (values: ConfigFormValues) => Promise<void>) => {
+      if (!validate()) return
+      setIsSubmitting(true)
+      try {
+        await onSubmit(values)
+      } finally {
+        setIsSubmitting(false)
+      }
+    },
+    [values, validate],
+  )
 
   return { values, errors, isSubmitting, handleChange, handleSubmit }
 }
@@ -233,7 +238,7 @@ export const useModalState = () => {
 export const useToggle = (initialValue = false) => {
   const [value, setValue] = useState(initialValue)
 
-  const toggle = useCallback(() => setValue(v => !v), [])
+  const toggle = useCallback(() => setValue((v) => !v), [])
   const setTrue = useCallback(() => setValue(true), [])
   const setFalse = useCallback(() => setValue(false), [])
 
@@ -255,18 +260,22 @@ import { useModelConfig } from './use-model-config'
 
 describe('useModelConfig', () => {
   it('should initialize with default values', () => {
-    const { result } = renderHook(() => useModelConfig({
-      hasFetchedDetail: false,
-    }))
+    const { result } = renderHook(() =>
+      useModelConfig({
+        hasFetchedDetail: false,
+      }),
+    )
 
     expect(result.current.modelConfig.provider).toBe('langgenius/openai/openai')
     expect(result.current.modelModeType).toBe(ModelModeType.unset)
   })
 
   it('should update model config', () => {
-    const { result } = renderHook(() => useModelConfig({
-      hasFetchedDetail: true,
-    }))
+    const { result } = renderHook(() =>
+      useModelConfig({
+        hasFetchedDetail: true,
+      }),
+    )
 
     act(() => {
       result.current.setModelConfig({

.agents/skills/e2e-cucumber-playwright/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "E2E Cucumber + Playwright"
-  short_description: "Write and review Dify E2E scenarios."
-  default_prompt: "Use $e2e-cucumber-playwright to write or review a Dify E2E scenario under e2e/."
+  display_name: 'E2E Cucumber + Playwright'
+  short_description: 'Write and review Dify E2E scenarios.'
+  default_prompt: 'Use $e2e-cucumber-playwright to write or review a Dify E2E scenario under e2e/.'

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

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

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

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

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

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

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

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

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

@@ -93,10 +93,10 @@ describe('ComponentName', () => {
     it('should render without crashing', () => {
       // Arrange
       const props = { title: 'Test' }
-      
+
       // Act
       render(<Component {...props} />)
-      
+
       // Assert
       expect(screen.getByText('Test')).toBeInTheDocument()
     })
@@ -115,9 +115,9 @@ describe('ComponentName', () => {
     it('should handle click events', () => {
       const handleClick = vi.fn()
       render(<Component onClick={handleClick} />)
-      
+
       fireEvent.click(screen.getByRole('button'))
-      
+
       expect(handleClick).toHaveBeenCalledTimes(1)
     })
   })
@@ -278,16 +278,16 @@ it('should disable input when isReadOnly is true')
 
 ### Conditional (When Present)
 
-| Feature | Test Focus |
-|---------|-----------|
-| `useState` | Initial state, transitions, cleanup |
-| `useEffect` | Execution, dependencies, cleanup |
-| Event handlers | All onClick, onChange, onSubmit, keyboard |
-| API calls | Loading, success, error states |
-| Routing | Navigation, params, query strings |
-| `useCallback`/`useMemo` | Referential equality |
-| Context | Provider values, consumer behavior |
-| Forms | Validation, submission, error display |
+| Feature                 | Test Focus                                |
+| ----------------------- | ----------------------------------------- |
+| `useState`              | Initial state, transitions, cleanup       |
+| `useEffect`             | Execution, dependencies, cleanup          |
+| Event handlers          | All onClick, onChange, onSubmit, keyboard |
+| API calls               | Loading, success, error states            |
+| Routing                 | Navigation, params, query strings         |
+| `useCallback`/`useMemo` | Referential equality                      |
+| Context                 | Provider values, consumer behavior        |
+| Forms                   | Validation, submission, error display     |
 
 ## Coverage Goals (Per File)
 

.agents/skills/frontend-testing/assets/component-test.template.tsx

@@ -108,10 +108,8 @@ describe('ComponentName', () => {
     it('should render without crashing', () => {
       // Arrange - Setup data and mocks
       // const props = createMockProps()
-
       // Act - Render the component
       // render(<ComponentName {...props} />)
-
       // Assert - Verify expected output
       // Prefer getByRole for accessibility; it's what users "see"
       // expect(screen.getByRole('...')).toBeInTheDocument()

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

@@ -9,7 +9,7 @@ import { render, screen, waitFor } from '@testing-library/react'
 
 it('should load and display data', async () => {
   render(<DataComponent />)
-  
+
   // Wait for element to appear
   await waitFor(() => {
     expect(screen.getByText('Loaded Data')).toBeInTheDocument()
@@ -18,7 +18,7 @@ it('should load and display data', async () => {
 
 it('should hide loading spinner after load', async () => {
   render(<DataComponent />)
-  
+
   // Wait for element to disappear
   await waitFor(() => {
     expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
@@ -31,11 +31,11 @@ it('should hide loading spinner after load', async () => {
 ```typescript
 it('should show user name after fetch', async () => {
   render(<UserProfile />)
-  
+
   // findBy returns a promise, auto-waits up to 1000ms
   const userName = await screen.findByText('John Doe')
   expect(userName).toBeInTheDocument()
-  
+
   // findByRole with options
   const button = await screen.findByRole('button', { name: /submit/i })
   expect(button).toBeEnabled()
@@ -50,13 +50,13 @@ import userEvent from '@testing-library/user-event'
 it('should submit form', async () => {
   const user = userEvent.setup()
   const onSubmit = vi.fn()
-  
+
   render(<Form onSubmit={onSubmit} />)
-  
+
   // userEvent methods are async
   await user.type(screen.getByLabelText('Email'), 'test@example.com')
   await user.click(screen.getByRole('button', { name: /submit/i }))
-  
+
   await waitFor(() => {
     expect(onSubmit).toHaveBeenCalledWith({ email: 'test@example.com' })
   })
@@ -87,16 +87,16 @@ describe('Debounced Search', () => {
   it('should debounce search input', async () => {
     const onSearch = vi.fn()
     render(<SearchInput onSearch={onSearch} debounceMs={300} />)
-    
+
     // Type in the input
     fireEvent.change(screen.getByRole('textbox'), { target: { value: 'query' } })
-    
+
     // Search not called immediately
     expect(onSearch).not.toHaveBeenCalled()
-    
+
     // Advance timers
     vi.advanceTimersByTime(300)
-    
+
     // Now search is called
     expect(onSearch).toHaveBeenCalledWith('query')
   })
@@ -111,23 +111,23 @@ it('should retry on failure', async () => {
   const fetchData = vi.fn()
     .mockRejectedValueOnce(new Error('Network error'))
     .mockResolvedValueOnce({ data: 'success' })
-  
+
   render(<RetryComponent fetchData={fetchData} retryDelayMs={1000} />)
-  
+
   // First call fails
   await waitFor(() => {
     expect(fetchData).toHaveBeenCalledTimes(1)
   })
-  
+
   // Advance timer for retry
   vi.advanceTimersByTime(1000)
-  
+
   // Second call succeeds
   await waitFor(() => {
     expect(fetchData).toHaveBeenCalledTimes(2)
     expect(screen.getByText('success')).toBeInTheDocument()
   })
-  
+
   vi.useRealTimers()
 })
 ```
@@ -163,31 +163,31 @@ describe('DataFetcher', () => {
 
   it('should show loading state', () => {
     mockedApi.fetchData.mockImplementation(() => new Promise(() => {})) // Never resolves
-    
+
     render(<DataFetcher />)
-    
+
     expect(screen.getByTestId('loading-spinner')).toBeInTheDocument()
   })
 
   it('should show data on success', async () => {
     mockedApi.fetchData.mockResolvedValue({ items: ['Item 1', 'Item 2'] })
-    
+
     render(<DataFetcher />)
-    
+
     // Use findBy* for multiple async elements (better error messages than waitFor with multiple assertions)
     const item1 = await screen.findByText('Item 1')
     const item2 = await screen.findByText('Item 2')
     expect(item1).toBeInTheDocument()
     expect(item2).toBeInTheDocument()
-    
+
     expect(screen.queryByTestId('loading-spinner')).not.toBeInTheDocument()
   })
 
   it('should show error on failure', async () => {
     mockedApi.fetchData.mockRejectedValue(new Error('Failed to fetch'))
-    
+
     render(<DataFetcher />)
-    
+
     await waitFor(() => {
       expect(screen.getByText(/failed to fetch/i)).toBeInTheDocument()
     })
@@ -195,16 +195,16 @@ describe('DataFetcher', () => {
 
   it('should retry on error', async () => {
     mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
+
     render(<DataFetcher />)
-    
+
     await waitFor(() => {
       expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
     })
-    
+
     mockedApi.fetchData.mockResolvedValue({ items: ['Item 1'] })
     fireEvent.click(screen.getByRole('button', { name: /retry/i }))
-    
+
     await waitFor(() => {
       expect(screen.getByText('Item 1')).toBeInTheDocument()
     })
@@ -218,19 +218,19 @@ describe('DataFetcher', () => {
 it('should submit form and show success', async () => {
   const user = userEvent.setup()
   mockedApi.createItem.mockResolvedValue({ id: '1', name: 'New Item' })
-  
+
   render(<CreateItemForm />)
-  
+
   await user.type(screen.getByLabelText('Name'), 'New Item')
   await user.click(screen.getByRole('button', { name: /create/i }))
-  
+
   // Button should be disabled during submission
   expect(screen.getByRole('button', { name: /creating/i })).toBeDisabled()
-  
+
   await waitFor(() => {
     expect(screen.getByText(/created successfully/i)).toBeInTheDocument()
   })
-  
+
   expect(mockedApi.createItem).toHaveBeenCalledWith({ name: 'New Item' })
 })
 ```
@@ -242,9 +242,9 @@ it('should submit form and show success', async () => {
 ```typescript
 it('should fetch data on mount', async () => {
   const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
-  
+
   render(<ComponentWithEffect fetchData={fetchData} />)
-  
+
   await waitFor(() => {
     expect(fetchData).toHaveBeenCalledTimes(1)
   })
@@ -256,15 +256,15 @@ it('should fetch data on mount', async () => {
 ```typescript
 it('should refetch when id changes', async () => {
   const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
-  
+
   const { rerender } = render(<ComponentWithEffect id="1" fetchData={fetchData} />)
-  
+
   await waitFor(() => {
     expect(fetchData).toHaveBeenCalledWith('1')
   })
-  
+
   rerender(<ComponentWithEffect id="2" fetchData={fetchData} />)
-  
+
   await waitFor(() => {
     expect(fetchData).toHaveBeenCalledWith('2')
     expect(fetchData).toHaveBeenCalledTimes(2)
@@ -279,13 +279,13 @@ it('should cleanup subscription on unmount', () => {
   const subscribe = vi.fn()
   const unsubscribe = vi.fn()
   subscribe.mockReturnValue(unsubscribe)
-  
+
   const { unmount } = render(<SubscriptionComponent subscribe={subscribe} />)
-  
+
   expect(subscribe).toHaveBeenCalledTimes(1)
-  
+
   unmount()
-  
+
   expect(unsubscribe).toHaveBeenCalledTimes(1)
 })
 ```

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

@@ -51,16 +51,16 @@ Use this checklist when generating or reviewing tests for Dify frontend componen
 
 ### Conditional Sections (Add When Feature Present)
 
-| Feature | Add Tests For |
-|---------|---------------|
-| `useState` | Initial state, transitions, cleanup |
-| `useEffect` | Execution, dependencies, cleanup |
-| Event handlers | onClick, onChange, onSubmit, keyboard |
-| API calls | Loading, success, error states |
-| Routing | Navigation, params, query strings |
-| `useCallback`/`useMemo` | Referential equality |
-| Context | Provider values, consumer behavior |
-| Forms | Validation, submission, error display |
+| Feature                 | Add Tests For                         |
+| ----------------------- | ------------------------------------- |
+| `useState`              | Initial state, transitions, cleanup   |
+| `useEffect`             | Execution, dependencies, cleanup      |
+| Event handlers          | onClick, onChange, onSubmit, keyboard |
+| API calls               | Loading, success, error states        |
+| Routing                 | Navigation, params, query strings     |
+| `useCallback`/`useMemo` | Referential equality                  |
+| Context                 | Provider values, consumer behavior    |
+| Forms                   | Validation, submission, error display |
 
 ## Code Quality Checklist
 
@@ -110,8 +110,8 @@ For the current file being tested:
 
 - [ ] 100% function coverage
 - [ ] 100% statement coverage
-- [ ] >95% branch coverage
-- [ ] >95% line coverage
+- [ ] > 95% branch coverage
+- [ ] > 95% line coverage
 
 ## Post-Generation (Per File)
 

.agents/skills/frontend-testing/references/common-patterns.md

@@ -107,13 +107,13 @@ describe('Counter', () => {
   it('should increment count', async () => {
     const user = userEvent.setup()
     render(<Counter initialCount={0} />)
-    
+
     // Initial state
     expect(screen.getByText('Count: 0')).toBeInTheDocument()
-    
+
     // Trigger transition
     await user.click(screen.getByRole('button', { name: /increment/i }))
-    
+
     // New state
     expect(screen.getByText('Count: 1')).toBeInTheDocument()
   })
@@ -127,17 +127,17 @@ describe('ControlledInput', () => {
   it('should call onChange with new value', async () => {
     const user = userEvent.setup()
     const handleChange = vi.fn()
-    
+
     render(<ControlledInput value="" onChange={handleChange} />)
-    
+
     await user.type(screen.getByRole('textbox'), 'a')
-    
+
     expect(handleChange).toHaveBeenCalledWith('a')
   })
 
   it('should display controlled value', () => {
     render(<ControlledInput value="controlled" onChange={vi.fn()} />)
-    
+
     expect(screen.getByRole('textbox')).toHaveValue('controlled')
   })
 })
@@ -149,26 +149,26 @@ describe('ControlledInput', () => {
 describe('ConditionalComponent', () => {
   it('should show loading state', () => {
     render(<DataDisplay isLoading={true} data={null} />)
-    
+
     expect(screen.getByText(/loading/i)).toBeInTheDocument()
     expect(screen.queryByTestId('data-content')).not.toBeInTheDocument()
   })
 
   it('should show error state', () => {
     render(<DataDisplay isLoading={false} data={null} error="Failed to load" />)
-    
+
     expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
   })
 
   it('should show data when loaded', () => {
     render(<DataDisplay isLoading={false} data={{ name: 'Test' }} />)
-    
+
     expect(screen.getByText('Test')).toBeInTheDocument()
   })
 
   it('should show empty state when no data', () => {
     render(<DataDisplay isLoading={false} data={[]} />)
-    
+
     expect(screen.getByText(/no data/i)).toBeInTheDocument()
   })
 })
@@ -186,7 +186,7 @@ describe('ItemList', () => {
 
   it('should render all items', () => {
     render(<ItemList items={items} />)
-    
+
     expect(screen.getAllByRole('listitem')).toHaveLength(3)
     items.forEach(item => {
       expect(screen.getByText(item.name)).toBeInTheDocument()
@@ -196,17 +196,17 @@ describe('ItemList', () => {
   it('should handle item selection', async () => {
     const user = userEvent.setup()
     const onSelect = vi.fn()
-    
+
     render(<ItemList items={items} onSelect={onSelect} />)
-    
+
     await user.click(screen.getByText('Item 2'))
-    
+
     expect(onSelect).toHaveBeenCalledWith(items[1])
   })
 
   it('should handle empty list', () => {
     render(<ItemList items={[]} />)
-    
+
     expect(screen.getByText(/no items/i)).toBeInTheDocument()
   })
 })
@@ -218,55 +218,55 @@ describe('ItemList', () => {
 describe('Modal', () => {
   it('should not render when closed', () => {
     render(<Modal isOpen={false} onClose={vi.fn()} />)
-    
+
     expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
   })
 
   it('should render when open', () => {
     render(<Modal isOpen={true} onClose={vi.fn()} />)
-    
+
     expect(screen.getByRole('dialog')).toBeInTheDocument()
   })
 
   it('should call onClose when clicking overlay', async () => {
     const user = userEvent.setup()
     const handleClose = vi.fn()
-    
+
     render(<Modal isOpen={true} onClose={handleClose} />)
-    
+
     await user.click(screen.getByTestId('modal-overlay'))
-    
+
     expect(handleClose).toHaveBeenCalled()
   })
 
   it('should call onClose when pressing Escape', async () => {
     const user = userEvent.setup()
     const handleClose = vi.fn()
-    
+
     render(<Modal isOpen={true} onClose={handleClose} />)
-    
+
     await user.keyboard('{Escape}')
-    
+
     expect(handleClose).toHaveBeenCalled()
   })
 
   it('should trap focus inside modal', async () => {
     const user = userEvent.setup()
-    
+
     render(
       <Modal isOpen={true} onClose={vi.fn()}>
         <button>First</button>
         <button>Second</button>
       </Modal>
     )
-    
+
     // Focus should cycle within modal
     await user.tab()
     expect(screen.getByText('First')).toHaveFocus()
-    
+
     await user.tab()
     expect(screen.getByText('Second')).toHaveFocus()
-    
+
     await user.tab()
     expect(screen.getByText('First')).toHaveFocus() // Cycles back
   })
@@ -280,13 +280,13 @@ describe('LoginForm', () => {
   it('should submit valid form', async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn()
-    
+
     render(<LoginForm onSubmit={onSubmit} />)
-    
+
     await user.type(screen.getByLabelText(/email/i), 'test@example.com')
     await user.type(screen.getByLabelText(/password/i), 'password123')
     await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
+
     expect(onSubmit).toHaveBeenCalledWith({
       email: 'test@example.com',
       password: 'password123',
@@ -295,39 +295,39 @@ describe('LoginForm', () => {
 
   it('should show validation errors', async () => {
     const user = userEvent.setup()
-    
+
     render(<LoginForm onSubmit={vi.fn()} />)
-    
+
     // Submit empty form
     await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
+
     expect(screen.getByText(/email is required/i)).toBeInTheDocument()
     expect(screen.getByText(/password is required/i)).toBeInTheDocument()
   })
 
   it('should validate email format', async () => {
     const user = userEvent.setup()
-    
+
     render(<LoginForm onSubmit={vi.fn()} />)
-    
+
     await user.type(screen.getByLabelText(/email/i), 'invalid-email')
     await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
+
     expect(screen.getByText(/invalid email/i)).toBeInTheDocument()
   })
 
   it('should disable submit button while submitting', async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn(() => new Promise(resolve => setTimeout(resolve, 100)))
-    
+
     render(<LoginForm onSubmit={onSubmit} />)
-    
+
     await user.type(screen.getByLabelText(/email/i), 'test@example.com')
     await user.type(screen.getByLabelText(/password/i), 'password123')
     await user.click(screen.getByRole('button', { name: /sign in/i }))
-    
+
     expect(screen.getByRole('button', { name: /signing in/i })).toBeDisabled()
-    
+
     await waitFor(() => {
       expect(screen.getByRole('button', { name: /sign in/i })).toBeEnabled()
     })
@@ -346,7 +346,7 @@ describe('StatusBadge', () => {
     ['info', 'bg-blue-500'],
   ])('should apply correct class for %s status', (status, expectedClass) => {
     render(<StatusBadge status={status} />)
-    
+
     expect(screen.getByTestId('status-badge')).toHaveClass(expectedClass)
   })
 
@@ -357,7 +357,7 @@ describe('StatusBadge', () => {
     { input: 'invalid', expected: 'Unknown' },
   ])('should show "Unknown" for invalid input: $input', ({ input, expected }) => {
     render(<StatusBadge status={input} />)
-    
+
     expect(screen.getByText(expected)).toBeInTheDocument()
   })
 })

.agents/skills/frontend-testing/references/domain-components.md

@@ -53,18 +53,18 @@ describe('NodeConfigPanel', () => {
     it('should render node type selector', () => {
       const node = createMockNode({ type: 'llm' })
       render(<NodeConfigPanel node={node} />)
-      
+
       expect(screen.getByLabelText(/model/i)).toBeInTheDocument()
     })
 
     it('should update node config on change', async () => {
       const user = userEvent.setup()
       const node = createMockNode({ type: 'llm' })
-      
+
       render(<NodeConfigPanel node={node} />)
-      
+
       await user.selectOptions(screen.getByLabelText(/model/i), 'gpt-4')
-      
+
       expect(mockWorkflowStore.updateNode).toHaveBeenCalledWith(
         node.id,
         expect.objectContaining({ model: 'gpt-4' })
@@ -76,14 +76,14 @@ describe('NodeConfigPanel', () => {
     it('should show error for invalid input', async () => {
       const user = userEvent.setup()
       const node = createMockNode({ type: 'code' })
-      
+
       render(<NodeConfigPanel node={node} />)
-      
+
       // Enter invalid code
       const codeInput = screen.getByLabelText(/code/i)
       await user.clear(codeInput)
       await user.type(codeInput, 'invalid syntax {{{')
-      
+
       await waitFor(() => {
         expect(screen.getByText(/syntax error/i)).toBeInTheDocument()
       })
@@ -91,11 +91,11 @@ describe('NodeConfigPanel', () => {
 
     it('should validate required fields', async () => {
       const node = createMockNode({ type: 'http', data: { url: '' } })
-      
+
       render(<NodeConfigPanel node={node} />)
-      
+
       fireEvent.click(screen.getByRole('button', { name: /save/i }))
-      
+
       await waitFor(() => {
         expect(screen.getByText(/url is required/i)).toBeInTheDocument()
       })
@@ -113,28 +113,28 @@ describe('NodeConfigPanel', () => {
         id: 'node-2',
         type: 'llm',
       })
-      
+
       mockWorkflowStore.nodes = [upstreamNode, currentNode]
       mockWorkflowStore.edges = [{ source: 'node-1', target: 'node-2' }]
-      
+
       render(<NodeConfigPanel node={currentNode} />)
-      
+
       // Variable selector should show upstream variables
       fireEvent.click(screen.getByRole('button', { name: /add variable/i }))
-      
+
       expect(screen.getByText('user_input')).toBeInTheDocument()
     })
 
     it('should insert variable into prompt template', async () => {
       const user = userEvent.setup()
       const node = createMockNode({ type: 'llm' })
-      
+
       render(<NodeConfigPanel node={node} />)
-      
+
       // Click variable button
       await user.click(screen.getByRole('button', { name: /insert variable/i }))
       await user.click(screen.getByText('user_input'))
-      
+
       const promptInput = screen.getByLabelText(/prompt/i)
       expect(promptInput).toHaveValue(expect.stringContaining('{{user_input}}'))
     })
@@ -179,14 +179,14 @@ describe('DocumentUploader', () => {
       const user = userEvent.setup()
       const onUpload = vi.fn()
       mockedService.uploadDocument.mockResolvedValue({ id: 'doc-1' })
-      
+
       render(<DocumentUploader onUpload={onUpload} />)
-      
+
       const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
       const input = screen.getByLabelText(/upload/i)
-      
+
       await user.upload(input, file)
-      
+
       await waitFor(() => {
         expect(mockedService.uploadDocument).toHaveBeenCalledWith(
           expect.any(FormData)
@@ -196,35 +196,35 @@ describe('DocumentUploader', () => {
 
     it('should reject invalid file types', async () => {
       const user = userEvent.setup()
-      
+
       render(<DocumentUploader />)
-      
+
       const file = new File(['content'], 'test.exe', { type: 'application/x-msdownload' })
       const input = screen.getByLabelText(/upload/i)
-      
+
       await user.upload(input, file)
-      
+
       expect(screen.getByText(/unsupported file type/i)).toBeInTheDocument()
       expect(mockedService.uploadDocument).not.toHaveBeenCalled()
     })
 
     it('should show upload progress', async () => {
       const user = userEvent.setup()
-      
+
       // Mock upload with progress
       mockedService.uploadDocument.mockImplementation(() => {
         return new Promise((resolve) => {
           setTimeout(() => resolve({ id: 'doc-1' }), 100)
         })
       })
-      
+
       render(<DocumentUploader />)
-      
+
       const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
       await user.upload(screen.getByLabelText(/upload/i), file)
-      
+
       expect(screen.getByRole('progressbar')).toBeInTheDocument()
-      
+
       await waitFor(() => {
         expect(screen.queryByRole('progressbar')).not.toBeInTheDocument()
       })
@@ -235,12 +235,12 @@ describe('DocumentUploader', () => {
     it('should handle upload failure', async () => {
       const user = userEvent.setup()
       mockedService.uploadDocument.mockRejectedValue(new Error('Upload failed'))
-      
+
       render(<DocumentUploader />)
-      
+
       const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
       await user.upload(screen.getByLabelText(/upload/i), file)
-      
+
       await waitFor(() => {
         expect(screen.getByText(/upload failed/i)).toBeInTheDocument()
       })
@@ -251,18 +251,18 @@ describe('DocumentUploader', () => {
       mockedService.uploadDocument
         .mockRejectedValueOnce(new Error('Network error'))
         .mockResolvedValueOnce({ id: 'doc-1' })
-      
+
       render(<DocumentUploader />)
-      
+
       const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
       await user.upload(screen.getByLabelText(/upload/i), file)
-      
+
       await waitFor(() => {
         expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
       })
-      
+
       await user.click(screen.getByRole('button', { name: /retry/i }))
-      
+
       await waitFor(() => {
         expect(screen.getByText(/uploaded successfully/i)).toBeInTheDocument()
       })
@@ -283,13 +283,13 @@ describe('DocumentList', () => {
         page: 1,
         pageSize: 10,
       })
-      
+
       render(<DocumentList datasetId="ds-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByText('Doc 1')).toBeInTheDocument()
       })
-      
+
       expect(mockedService.getDocuments).toHaveBeenCalledWith('ds-1', { page: 1 })
     })
 
@@ -301,22 +301,22 @@ describe('DocumentList', () => {
         page: 1,
         pageSize: 10,
       })
-      
+
       render(<DocumentList datasetId="ds-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByText('Doc 1')).toBeInTheDocument()
       })
-      
+
       mockedService.getDocuments.mockResolvedValue({
         data: [{ id: '11', name: 'Doc 11' }],
         total: 50,
         page: 2,
         pageSize: 10,
       })
-      
+
       await user.click(screen.getByRole('button', { name: /next/i }))
-      
+
       await waitFor(() => {
         expect(screen.getByText('Doc 11')).toBeInTheDocument()
       })
@@ -327,21 +327,21 @@ describe('DocumentList', () => {
     it('should filter by search query', async () => {
       const user = userEvent.setup()
       vi.useFakeTimers()
-      
+
       render(<DocumentList datasetId="ds-1" />)
-      
+
       await user.type(screen.getByPlaceholderText(/search/i), 'test query')
-      
+
       // Debounce
       vi.advanceTimersByTime(300)
-      
+
       await waitFor(() => {
         expect(mockedService.getDocuments).toHaveBeenCalledWith(
           'ds-1',
           expect.objectContaining({ search: 'test query' })
         )
       })
-      
+
       vi.useRealTimers()
     })
   })
@@ -391,50 +391,50 @@ describe('AppConfigForm', () => {
   describe('Form Validation', () => {
     it('should require app name', async () => {
       const user = userEvent.setup()
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
       })
-      
+
       // Clear name field
       await user.clear(screen.getByLabelText(/name/i))
       await user.click(screen.getByRole('button', { name: /save/i }))
-      
+
       expect(screen.getByText(/name is required/i)).toBeInTheDocument()
       expect(mockedService.updateAppConfig).not.toHaveBeenCalled()
     })
 
     it('should validate name length', async () => {
       const user = userEvent.setup()
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toBeInTheDocument()
       })
-      
+
       // Enter very long name
       await user.clear(screen.getByLabelText(/name/i))
       await user.type(screen.getByLabelText(/name/i), 'a'.repeat(101))
-      
+
       expect(screen.getByText(/name must be less than 100 characters/i)).toBeInTheDocument()
     })
 
     it('should allow empty optional fields', async () => {
       const user = userEvent.setup()
       mockedService.updateAppConfig.mockResolvedValue({ success: true })
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
       })
-      
+
       // Leave description empty (optional)
       await user.click(screen.getByRole('button', { name: /save/i }))
-      
+
       await waitFor(() => {
         expect(mockedService.updateAppConfig).toHaveBeenCalled()
       })
@@ -445,58 +445,58 @@ describe('AppConfigForm', () => {
     it('should save configuration', async () => {
       const user = userEvent.setup()
       mockedService.updateAppConfig.mockResolvedValue({ success: true })
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
       })
-      
+
       await user.clear(screen.getByLabelText(/name/i))
       await user.type(screen.getByLabelText(/name/i), 'Updated App')
       await user.click(screen.getByRole('button', { name: /save/i }))
-      
+
       await waitFor(() => {
         expect(mockedService.updateAppConfig).toHaveBeenCalledWith(
           'app-1',
           expect.objectContaining({ name: 'Updated App' })
         )
       })
-      
+
       expect(screen.getByText(/saved successfully/i)).toBeInTheDocument()
     })
 
     it('should reset to default values', async () => {
       const user = userEvent.setup()
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
       })
-      
+
       // Make changes
       await user.clear(screen.getByLabelText(/name/i))
       await user.type(screen.getByLabelText(/name/i), 'Changed Name')
-      
+
       // Reset
       await user.click(screen.getByRole('button', { name: /reset/i }))
-      
+
       expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
     })
 
     it('should show unsaved changes warning', async () => {
       const user = userEvent.setup()
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
       })
-      
+
       // Make changes
       await user.type(screen.getByLabelText(/name/i), ' Updated')
-      
+
       expect(screen.getByText(/unsaved changes/i)).toBeInTheDocument()
     })
   })
@@ -505,15 +505,15 @@ describe('AppConfigForm', () => {
     it('should show error on save failure', async () => {
       const user = userEvent.setup()
       mockedService.updateAppConfig.mockRejectedValue(new Error('Server error'))
-      
+
       render(<AppConfigForm appId="app-1" />)
-      
+
       await waitFor(() => {
         expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
       })
-      
+
       await user.click(screen.getByRole('button', { name: /save/i }))
-      
+
       await waitFor(() => {
         expect(screen.getByText(/failed to save/i)).toBeInTheDocument()
       })

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

@@ -54,12 +54,12 @@ See [Zustand Store Testing](#zustand-store-testing) section for full details.
 
 ## Mock Placement
 
-| Location | Purpose |
-|----------|---------|
-| `web/vitest.setup.ts` | Global mocks shared by all tests (`react-i18next`, `zustand`, clipboard, FloatingPortal, Monaco, localStorage`) |
-| `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()` |
+| Location                   | Purpose                                                                                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `web/vitest.setup.ts`      | Global mocks shared by all tests (`react-i18next`, `zustand`, clipboard, FloatingPortal, Monaco, localStorage`) |
+| `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()`                                                                    |
 
 Modules are not mocked automatically. Use `vi.mock` in test files, or add global mocks in `web/vitest.setup.ts`.
 
@@ -85,10 +85,12 @@ The global mock provides:
 ```typescript
 import { createReactI18nextMock } from '@/test/i18n-mock'
 
-vi.mock('react-i18next', () => createReactI18nextMock({
-  'my.custom.key': 'Custom translation',
-  'button.save': 'Save',
-}))
+vi.mock('react-i18next', () =>
+  createReactI18nextMock({
+    'my.custom.key': 'Custom translation',
+    'button.save': 'Save',
+  }),
+)
 ```
 
 **Avoid**: Manually defining `useTranslation` mocks that just return the key - the global mock already does this.
@@ -189,16 +191,16 @@ const mockedApi = vi.mocked(api)
 describe('Component', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    
+
     // Setup default mock implementation
     mockedApi.fetchData.mockResolvedValue({ data: [] })
   })
 
   it('should show data on success', async () => {
     mockedApi.fetchData.mockResolvedValue({ data: [{ id: 1 }] })
-    
+
     render(<Component />)
-    
+
     await waitFor(() => {
       expect(screen.getByText('1')).toBeInTheDocument()
     })
@@ -206,9 +208,9 @@ describe('Component', () => {
 
   it('should show error on failure', async () => {
     mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
+
     render(<Component />)
-    
+
     await waitFor(() => {
       expect(screen.getByText(/error/i)).toBeInTheDocument()
     })
@@ -231,9 +233,9 @@ describe('GithubComponent', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     )
-    
+
     render(<GithubComponent />)
-    
+
     await waitFor(() => {
       expect(screen.getByText('dify')).toBeInTheDocument()
     })
@@ -246,9 +248,9 @@ describe('GithubComponent', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     )
-    
+
     render(<GithubComponent />)
-    
+
     await waitFor(() => {
       expect(screen.getByText(/error/i)).toBeInTheDocument()
     })
@@ -267,25 +269,25 @@ import { createMockProviderContextValue, createMockPlan } from '@/__mocks__/prov
 describe('Component with Context', () => {
   it('should render for free plan', () => {
     const mockContext = createMockPlan('sandbox')
-    
+
     render(
       <ProviderContext.Provider value={mockContext}>
         <Component />
       </ProviderContext.Provider>
     )
-    
+
     expect(screen.getByText('Upgrade')).toBeInTheDocument()
   })
 
   it('should render for pro plan', () => {
     const mockContext = createMockPlan('professional')
-    
+
     render(
       <ProviderContext.Provider value={mockContext}>
         <Component />
       </ProviderContext.Provider>
     )
-    
+
     expect(screen.queryByText('Upgrade')).not.toBeInTheDocument()
   })
 })
@@ -411,7 +413,7 @@ Manual mocking conflicts with the global Zustand mock and loses store functional
 ```typescript
 // ❌ WRONG: Don't mock the store module
 vi.mock('@/app/components/app/store', () => ({
-  useStore: (selector) => mockSelector(selector),  // Missing getState, setState!
+  useStore: (selector) => mockSelector(selector), // Missing getState, setState!
 }))
 
 // ❌ WRONG: This conflicts with global zustand mock
@@ -439,14 +441,11 @@ const mockStore = {
 }
 
 vi.mock('@/app/components/app/store', () => ({
-  useStore: Object.assign(
-    (selector: (state: typeof mockStore) => unknown) => selector(mockStore),
-    {
-      getState: () => mockStore,
-      setState: vi.fn(),
-      subscribe: vi.fn(),
-    },
-  ),
+  useStore: Object.assign((selector: (state: typeof mockStore) => unknown) => selector(mockStore), {
+    getState: () => mockStore,
+    setState: vi.fn(),
+    subscribe: vi.fn(),
+  }),
 }))
 ```
 
@@ -528,7 +527,7 @@ it('should display project owner', () => {
   const project = createMockProject({
     owner: createMockUser({ name: 'John Doe' }),
   })
-  
+
   render(<ProjectCard project={project} />)
   expect(screen.getByText('John Doe')).toBeInTheDocument()
 })

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

@@ -6,10 +6,10 @@ This guide defines the workflow for generating tests, especially for complex com
 
 This guide addresses **multi-file workflow** (how to process multiple test files). For coverage requirements within a single test file, see `web/docs/test.md` § Coverage Goals.
 
-| Scope | Rule |
-|-------|------|
-| **Single file** | Complete coverage in one generation (100% function, >95% branch) |
-| **Multi-file directory** | Process one file at a time, verify each before proceeding |
+| Scope                    | Rule                                                             |
+| ------------------------ | ---------------------------------------------------------------- |
+| **Single file**          | Complete coverage in one generation (100% function, >95% branch) |
+| **Multi-file directory** | Process one file at a time, verify each before proceeding        |
 
 ## ⚠️ Critical Rule: Incremental Approach for Multi-File Testing
 
@@ -17,14 +17,14 @@ When testing a **directory with multiple files**, **NEVER generate all test file
 
 ### Why Incremental?
 
-| Batch Approach (❌) | Incremental Approach (✅) |
-|---------------------|---------------------------|
-| Generate 5+ tests at once | Generate 1 test at a time |
-| Run tests only at the end | Run test immediately after each file |
-| Multiple failures compound | Single point of failure, easy to debug |
-| Hard to identify root cause | Clear cause-effect relationship |
-| Mock issues affect many files | Mock issues caught early |
-| Messy git history | Clean, atomic commits possible |
+| Batch Approach (❌)           | Incremental Approach (✅)              |
+| ----------------------------- | -------------------------------------- |
+| Generate 5+ tests at once     | Generate 1 test at a time              |
+| Run tests only at the end     | Run test immediately after each file   |
+| Multiple failures compound    | Single point of failure, easy to debug |
+| Hard to identify root cause   | Clear cause-effect relationship        |
+| Mock issues affect many files | Mock issues caught early               |
+| Messy git history             | Clean, atomic commits possible         |
 
 ## Single File Workflow
 
@@ -190,7 +190,7 @@ Update status as you complete each:
 ```
 # BAD: Writing all files then testing
 Write component-a.spec.tsx
-Write component-b.spec.tsx  
+Write component-b.spec.tsx
 Write component-c.spec.tsx
 Write component-d.spec.tsx
 Run pnpm test  ← Multiple failures, hard to debug

.claude/skills/karpathy-guidelines

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

.devcontainer/devcontainer.json

@@ -1,49 +1,43 @@
 // For format details, see https://aka.ms/devcontainer.json. For config options, see the
 // README at: https://github.com/devcontainers/templates/tree/main/src/anaconda
 {
-	"name": "Python 3.12",
-	"build": {
-		"context": "..",
-		"dockerfile": "Dockerfile"
-	},
-	"mounts": [
-		"source=dify-dev-tmp,target=/tmp,type=volume"
-	],
-	"features": {
-		"ghcr.io/devcontainers/features/node:1": {
-			"nodeGypDependencies": true,
-			"version": "lts"
-		},
-		"ghcr.io/devcontainers-extra/features/npm-package:1": {
-			"package": "typescript",
-			"version": "latest"
-		},
-		"ghcr.io/devcontainers/features/docker-in-docker:2": {
-			"moby": true,
-			"azureDnsAutoDetection": true,
-			"installDockerBuildx": true,
-			"version": "latest",
-			"dockerDashComposeVersion": "v2"
-		}
-	},
-	"customizations": {
-		"vscode": {
-			"extensions": [
-				"ms-python.pylint",
-				"GitHub.copilot",
-				"ms-python.python"
-			]
-		}
-	},
-	"postStartCommand": "./.devcontainer/post_start_command.sh",
-	"postCreateCommand": "./.devcontainer/post_create_command.sh"
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
-	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "python --version",
-	// Configure tool-specific properties.
-	// "customizations": {},
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-}
+  "name": "Python 3.12",
+  "build": {
+    "context": "..",
+    "dockerfile": "Dockerfile"
+  },
+  "mounts": ["source=dify-dev-tmp,target=/tmp,type=volume"],
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "nodeGypDependencies": true,
+      "version": "lts"
+    },
+    "ghcr.io/devcontainers-extra/features/npm-package:1": {
+      "package": "typescript",
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "moby": true,
+      "azureDnsAutoDetection": true,
+      "installDockerBuildx": true,
+      "version": "latest",
+      "dockerDashComposeVersion": "v2"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-python.pylint", "GitHub.copilot", "ms-python.python"]
+    }
+  },
+  "postStartCommand": "./.devcontainer/post_start_command.sh",
+  "postCreateCommand": "./.devcontainer/post_create_command.sh"
+  // Features to add to the dev container. More info: https://containers.dev/features.
+  // "features": {},
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  // "forwardPorts": [],
+  // Use 'postCreateCommand' to run commands after the container is created.
+  // "postCreateCommand": "python --version",
+  // Configure tool-specific properties.
+  // "customizations": {},
+  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+}

.github/CODEOWNERS

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

.github/DISCUSSION_TEMPLATE/general.yml

@@ -1,17 +1,17 @@
-title: "General Discussion"
+title: 'General Discussion'
 body:
   - type: checkboxes
     attributes:
       label: Self Checks
-      description: "To make sure we get to you in time, please check the following :)"
+      description: 'To make sure we get to you in time, please check the following :)'
       options:
         - label: I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
           required: true
         - label: I confirm that I am using English to submit this report (我已阅读并同意 [Language Policy](https://github.com/langgenius/dify/issues/1542)).
           required: true
-        - label: "[FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)"
+        - label: '[FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)'
           required: true
-        - label: "Please do not modify this template :) and fill in all the required fields."
+        - label: 'Please do not modify this template :) and fill in all the required fields.'
           required: true
   - type: textarea
     attributes:

.github/DISCUSSION_TEMPLATE/help.yml

@@ -1,17 +1,17 @@
-title: "Help"
+title: 'Help'
 body:
   - type: checkboxes
     attributes:
       label: Self Checks
-      description: "To make sure we get to you in time, please check the following :)"
+      description: 'To make sure we get to you in time, please check the following :)'
       options:
         - label: I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
           required: true
         - label: I confirm that I am using English to submit this report (我已阅读并同意 [Language Policy](https://github.com/langgenius/dify/issues/1542)).
           required: true
-        - label: "[FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)"
+        - label: '[FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)'
           required: true
-        - label: "Please do not modify this template :) and fill in all the required fields."
+        - label: 'Please do not modify this template :) and fill in all the required fields.'
           required: true
   - type: textarea
     attributes:

.github/DISCUSSION_TEMPLATE/suggestion.yml

@@ -3,15 +3,15 @@ body:
   - type: checkboxes
     attributes:
       label: Self Checks
-      description: "To make sure we get to you in time, please check the following :)"
+      description: 'To make sure we get to you in time, please check the following :)'
       options:
         - label: I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
           required: true
         - label: I confirm that I am using English to submit this report (我已阅读并同意 [Language Policy](https://github.com/langgenius/dify/issues/1542)).
           required: true
-        - label: "[FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)"
+        - label: '[FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)'
           required: true
-        - label: "Please do not modify this template :) and fill in all the required fields."
+        - label: 'Please do not modify this template :) and fill in all the required fields.'
           required: true
   - type: textarea
     attributes:

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,4 +1,4 @@
-name: "🕷️ Bug report"
+name: '🕷️ Bug report'
 description: Report errors or unexpected behavior
 labels:
   - bug
@@ -6,7 +6,7 @@ body:
   - type: checkboxes
     attributes:
       label: Self Checks
-      description: "To make sure we get to you in time, please check the following :)"
+      description: 'To make sure we get to you in time, please check the following :)'
       options:
         - label: I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
           required: true
@@ -18,7 +18,7 @@ body:
           required: true
         - label: 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
           required: true
-        - label: "Please do not modify this template :) and fill in all the required fields."
+        - label: 'Please do not modify this template :) and fill in all the required fields.'
           required: true
 
   - type: input

.github/ISSUE_TEMPLATE/config.yml

@@ -1,13 +1,13 @@
 blank_issues_enabled: false
 contact_links:
   - name: "\U0001F510 Security Vulnerabilities"
-    url: "https://github.com/langgenius/dify/security/advisories/new"
+    url: 'https://github.com/langgenius/dify/security/advisories/new'
     about: Report security vulnerabilities through GitHub Security Advisories to ensure responsible disclosure. 💡 Please do not report security vulnerabilities in public issues.
   - name: "\U0001F4A1 Model Providers & Plugins"
-    url: "https://github.com/langgenius/dify-official-plugins/issues/new/choose"
+    url: 'https://github.com/langgenius/dify-official-plugins/issues/new/choose'
     about: Report issues with official plugins or model providers, you will need to provide the plugin version and other relevant details.
   - name: "\U0001F4AC Documentation Issues"
-    url: "https://github.com/langgenius/dify-docs/issues/new"
+    url: 'https://github.com/langgenius/dify-docs/issues/new'
     about: Report issues with the documentation, such as typos, outdated information, or missing content. Please provide the specific section and details of the issue.
   - name: "\U0001F4E7 Discussions"
     url: https://github.com/langgenius/dify/discussions/categories/general

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,4 +1,4 @@
-name: "⭐ Feature or enhancement request"
+name: '⭐ Feature or enhancement request'
 description: Propose something new.
 labels:
   - enhancement
@@ -6,7 +6,7 @@ body:
   - type: checkboxes
     attributes:
       label: Self Checks
-      description: "To make sure we get to you in time, please check the following :)"
+      description: 'To make sure we get to you in time, please check the following :)'
       options:
         - label: I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
           required: true
@@ -14,7 +14,7 @@ body:
           required: true
         - label: I confirm that I am using English to submit this report, otherwise it will be closed.
           required: true
-        - label: "Please do not modify this template :) and fill in all the required fields."
+        - label: 'Please do not modify this template :) and fill in all the required fields.'
           required: true
   - type: textarea
     attributes:

.github/ISSUE_TEMPLATE/refactor.yml

@@ -1,11 +1,11 @@
-name: "✨ Refactor or Chore"
+name: '✨ Refactor or Chore'
 description: Refactor existing code or perform maintenance chores to improve readability and reliability.
-title: "[Refactor/Chore] "
+title: '[Refactor/Chore] '
 body:
   - type: checkboxes
     attributes:
       label: Self Checks
-      description: "To make sure we get to you in time, please check the following :)"
+      description: 'To make sure we get to you in time, please check the following :)'
       options:
         - label: I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
           required: true
@@ -17,26 +17,26 @@ body:
           required: true
         - label: 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
           required: true
-        - label: "Please do not modify this template :) and fill in all the required fields."
+        - label: 'Please do not modify this template :) and fill in all the required fields.'
           required: true
   - type: textarea
     id: description
     attributes:
       label: Description
-      placeholder: "Describe the refactor or chore you are proposing."
+      placeholder: 'Describe the refactor or chore you are proposing.'
     validations:
       required: true
   - type: textarea
     id: motivation
     attributes:
       label: Motivation
-      placeholder: "Explain why this refactor or chore is necessary."
+      placeholder: 'Explain why this refactor or chore is necessary.'
     validations:
       required: false
   - type: textarea
     id: additional-context
     attributes:
       label: Additional Context
-      placeholder: "Add any other context or screenshots about the request here."
+      placeholder: 'Add any other context or screenshots about the request here.'
     validations:
       required: false

.github/dependabot.yml

@@ -1,223 +1,223 @@
 version: 2
 
 updates:
-  - package-ecosystem: "uv"
-    directory: "/api"
+  - package-ecosystem: 'uv'
+    directory: '/api'
     open-pull-requests-limit: 10
     schedule:
-      interval: "weekly"
+      interval: 'weekly'
     groups:
       flask:
         patterns:
-          - "flask"
-          - "flask-*"
-          - "werkzeug"
-          - "gunicorn"
+          - 'flask'
+          - 'flask-*'
+          - 'werkzeug'
+          - 'gunicorn'
       google:
         patterns:
-          - "google-*"
-          - "googleapis-*"
+          - 'google-*'
+          - 'googleapis-*'
       opentelemetry:
         patterns:
-          - "opentelemetry-*"
+          - 'opentelemetry-*'
       pydantic:
         patterns:
-          - "pydantic"
-          - "pydantic-*"
+          - 'pydantic'
+          - 'pydantic-*'
       llm:
         patterns:
-          - "langfuse"
-          - "langsmith"
-          - "litellm"
-          - "mlflow*"
-          - "opik"
-          - "weave*"
-          - "arize*"
-          - "tiktoken"
-          - "transformers"
+          - 'langfuse'
+          - 'langsmith'
+          - 'litellm'
+          - 'mlflow*'
+          - 'opik'
+          - 'weave*'
+          - 'arize*'
+          - 'tiktoken'
+          - 'transformers'
       database:
         patterns:
-          - "sqlalchemy"
-          - "psycopg2*"
-          - "psycogreen"
-          - "redis*"
-          - "alembic*"
+          - 'sqlalchemy'
+          - 'psycopg2*'
+          - 'psycogreen'
+          - 'redis*'
+          - 'alembic*'
       storage:
         patterns:
-          - "boto3*"
-          - "botocore*"
-          - "azure-*"
-          - "bce-*"
-          - "cos-python-*"
-          - "esdk-obs-*"
-          - "google-cloud-storage"
-          - "opendal"
-          - "oss2"
-          - "supabase*"
-          - "tos*"
+          - '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-*"
+          - '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"
+          - '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: "/"
+          - '*'
+  - package-ecosystem: 'github-actions'
+    directory: '/'
     open-pull-requests-limit: 5
     schedule:
-      interval: "weekly"
+      interval: 'weekly'
     groups:
       github-actions-dependencies:
         patterns:
-          - "*"
-  - package-ecosystem: "uv"
-    directory: "/api"
-    target-branch: "lts/1.13.x"
+          - '*'
+  - package-ecosystem: 'uv'
+    directory: '/api'
+    target-branch: 'lts/1.13.x'
     open-pull-requests-limit: 10
     schedule:
-      interval: "weekly"
+      interval: 'weekly'
     groups:
       flask:
         patterns:
-          - "flask"
-          - "flask-*"
-          - "werkzeug"
-          - "gunicorn"
+          - 'flask'
+          - 'flask-*'
+          - 'werkzeug'
+          - 'gunicorn'
       google:
         patterns:
-          - "google-*"
-          - "googleapis-*"
+          - 'google-*'
+          - 'googleapis-*'
       opentelemetry:
         patterns:
-          - "opentelemetry-*"
+          - 'opentelemetry-*'
       pydantic:
         patterns:
-          - "pydantic"
-          - "pydantic-*"
+          - 'pydantic'
+          - 'pydantic-*'
       llm:
         patterns:
-          - "langfuse"
-          - "langsmith"
-          - "litellm"
-          - "mlflow*"
-          - "opik"
-          - "weave*"
-          - "arize*"
-          - "tiktoken"
-          - "transformers"
+          - 'langfuse'
+          - 'langsmith'
+          - 'litellm'
+          - 'mlflow*'
+          - 'opik'
+          - 'weave*'
+          - 'arize*'
+          - 'tiktoken'
+          - 'transformers'
       database:
         patterns:
-          - "sqlalchemy"
-          - "psycopg2*"
-          - "psycogreen"
-          - "redis*"
-          - "alembic*"
+          - 'sqlalchemy'
+          - 'psycopg2*'
+          - 'psycogreen'
+          - 'redis*'
+          - 'alembic*'
       storage:
         patterns:
-          - "boto3*"
-          - "botocore*"
-          - "azure-*"
-          - "bce-*"
-          - "cos-python-*"
-          - "esdk-obs-*"
-          - "google-cloud-storage"
-          - "opendal"
-          - "oss2"
-          - "supabase*"
-          - "tos*"
+          - '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-*"
+          - '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"
+          - '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"
+          - '*'
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    target-branch: 'lts/1.13.x'
     open-pull-requests-limit: 5
     schedule:
-      interval: "weekly"
+      interval: 'weekly'
     groups:
       github-actions-dependencies:
         patterns:
-          - "*"
+          - '*'

.github/linters/.hadolint.yaml

@@ -1 +1 @@
-failure-threshold: "error"
+failure-threshold: 'error'

.github/linters/.yaml-lint.yml

@@ -1,5 +1,4 @@
 ---
-
 extends: default
 
 rules:

.github/linters/editorconfig-checker.json

@@ -1,22 +1,22 @@
 {
-    "Verbose": false,
-    "Debug": false,
-    "IgnoreDefaults": false,
-    "SpacesAfterTabs": false,
-    "NoColor": false,
-    "Exclude": [
-        "^web/public/vs/",
-        "^web/public/pdf.worker.min.mjs$",
-        "web/app/components/base/icons/src/vender/"
-    ],
-    "AllowedContentTypes": [],
-    "PassedFiles": [],
-    "Disable": {
-        "EndOfLine": false,
-        "Indentation": false,
-        "IndentSize": true,
-        "InsertFinalNewline": false,
-        "TrimTrailingWhitespace": false,
-        "MaxLineLength": false
-    }
+  "Verbose": false,
+  "Debug": false,
+  "IgnoreDefaults": false,
+  "SpacesAfterTabs": false,
+  "NoColor": false,
+  "Exclude": [
+    "^web/public/vs/",
+    "^web/public/pdf.worker.min.mjs$",
+    "web/app/components/base/icons/src/vender/"
+  ],
+  "AllowedContentTypes": [],
+  "PassedFiles": [],
+  "Disable": {
+    "EndOfLine": false,
+    "Indentation": false,
+    "IndentSize": true,
+    "InsertFinalNewline": false,
+    "TrimTrailingWhitespace": false,
+    "MaxLineLength": false
+  }
 }

.github/pull_request_template.md

@@ -12,8 +12,8 @@
 ## Screenshots
 
 | Before | After |
-|--------|-------|
-| ... | ... |
+| ------ | ----- |
+| ...    | ...   |
 
 ## Checklist
 

.github/scripts/generate-i18n-changes.mjs

@@ -8,31 +8,31 @@ const headSha = process.env.HEAD_SHA || ''
 const files = (process.env.CHANGED_FILES || '').split(/\s+/).filter(Boolean)
 const outputPath = process.env.I18N_CHANGES_OUTPUT_PATH || '/tmp/i18n-changes.json'
 
-const englishPath = fileStem => path.join(repoRoot, 'web', 'i18n', 'en-US', `${fileStem}.json`)
+const englishPath = (fileStem) => path.join(repoRoot, 'web', 'i18n', 'en-US', `${fileStem}.json`)
 
 const readCurrentJson = (fileStem) => {
   const filePath = englishPath(fileStem)
-  if (!fs.existsSync(filePath))
-    return null
+  if (!fs.existsSync(filePath)) return null
 
   return JSON.parse(fs.readFileSync(filePath, 'utf8'))
 }
 
 const readBaseJson = (fileStem) => {
-  if (!baseSha)
-    return null
+  if (!baseSha) return null
 
   try {
     const relativePath = `web/i18n/en-US/${fileStem}.json`
-    const content = execFileSync('git', ['show', `${baseSha}:${relativePath}`], { encoding: 'utf8' })
+    const content = execFileSync('git', ['show', `${baseSha}:${relativePath}`], {
+      encoding: 'utf8',
+    })
     return JSON.parse(content)
-  }
-  catch {
+  } catch {
     return null
   }
 }
 
-const compareJson = (beforeValue, afterValue) => JSON.stringify(beforeValue) === JSON.stringify(afterValue)
+const compareJson = (beforeValue, afterValue) =>
+  JSON.stringify(beforeValue) === JSON.stringify(afterValue)
 
 const changes = {}
 
@@ -59,8 +59,7 @@ for (const fileStem of files) {
   }
 
   for (const key of Object.keys(beforeJson)) {
-    if (!(key in afterJson))
-      deleted.push(key)
+    if (!(key in afterJson)) deleted.push(key)
   }
 
   changes[fileStem] = {
@@ -78,5 +77,5 @@ fs.writeFileSync(
     headSha,
     files,
     changes,
-  })
+  }),
 )

.github/workflows/api-tests.yml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
@@ -87,7 +87,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
@@ -151,7 +151,7 @@ jobs:
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies

.github/workflows/autofix.yml

@@ -1,12 +1,12 @@
 name: autofix.ci
 on:
   pull_request:
-    branches: ["main"]
+    branches: ['main']
   merge_group:
-    branches: ["main"]
+    branches: ['main']
     types: [checks_requested]
   push:
-    branches: ["main"]
+    branches: ['main']
 permissions:
   contents: read
 
@@ -44,6 +44,12 @@ jobs:
             pnpm-lock.yaml
             pnpm-workspace.yaml
             .nvmrc
+            vite.config.ts
+            eslint.config.mjs
+            web/eslint.config.mjs
+            .vscode/**
+            .github/workflows/autofix.yml
+            .github/workflows/style.yml
       - name: Check api inputs
         if: github.event_name != 'merge_group'
         id: api-changes
@@ -63,7 +69,7 @@ jobs:
       - if: github.event_name != 'merge_group'
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          python-version: "3.11"
+          python-version: '3.11'
 
       - if: github.event_name != 'merge_group'
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
@@ -146,6 +152,12 @@ jobs:
         if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
         run: pnpm --dir packages/contracts gen-api-contract-from-openapi
 
+      - name: Format web files
+        if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'
+        env:
+          CHANGED_FILES: ${{ steps.web-changes.outputs.all_changed_files }}
+        run: vp fmt --no-error-on-unmatched-pattern $CHANGED_FILES
+
       - name: ESLint autofix
         if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'
         run: |

.github/workflows/build-push.yml

@@ -3,14 +3,14 @@ name: Build and Push API & Web
 on:
   push:
     branches:
-      - "main"
-      - "deploy/**"
-      - "build/**"
-      - "release/e-*"
-      - "hotfix/**"
-      - "feat/hitl-backend"
+      - 'main'
+      - 'deploy/**'
+      - 'build/**'
+      - 'release/e-*'
+      - 'hotfix/**'
+      - 'feat/hitl-backend'
     tags:
-      - "*"
+      - '*'
 
 concurrency:
   group: build-push-${{ github.head_ref || github.run_id }}
@@ -32,32 +32,32 @@ jobs:
     strategy:
       matrix:
         include:
-          - service_name: "build-api-amd64"
-            image_name_env: "DIFY_API_IMAGE_NAME"
-            artifact_context: "api"
-            build_context: "{{defaultContext}}"
-            file: "api/Dockerfile"
+          - service_name: 'build-api-amd64'
+            image_name_env: 'DIFY_API_IMAGE_NAME'
+            artifact_context: 'api'
+            build_context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
-          - service_name: "build-api-arm64"
-            image_name_env: "DIFY_API_IMAGE_NAME"
-            artifact_context: "api"
-            build_context: "{{defaultContext}}"
-            file: "api/Dockerfile"
+          - service_name: 'build-api-arm64'
+            image_name_env: 'DIFY_API_IMAGE_NAME'
+            artifact_context: 'api'
+            build_context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
-          - service_name: "build-web-amd64"
-            image_name_env: "DIFY_WEB_IMAGE_NAME"
-            artifact_context: "web"
-            build_context: "{{defaultContext}}"
-            file: "web/Dockerfile"
+          - service_name: 'build-web-amd64'
+            image_name_env: 'DIFY_WEB_IMAGE_NAME'
+            artifact_context: 'web'
+            build_context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
-          - service_name: "build-web-arm64"
-            image_name_env: "DIFY_WEB_IMAGE_NAME"
-            artifact_context: "web"
-            build_context: "{{defaultContext}}"
-            file: "web/Dockerfile"
+          - service_name: 'build-web-arm64'
+            image_name_env: 'DIFY_WEB_IMAGE_NAME'
+            artifact_context: 'web'
+            build_context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
 
@@ -116,12 +116,12 @@ jobs:
     strategy:
       matrix:
         include:
-          - service_name: "validate-api-amd64"
-            build_context: "{{defaultContext}}"
-            file: "api/Dockerfile"
-          - service_name: "validate-web-amd64"
-            build_context: "{{defaultContext}}"
-            file: "web/Dockerfile"
+          - service_name: 'validate-api-amd64'
+            build_context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'validate-web-amd64'
+            build_context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
     steps:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
@@ -141,12 +141,12 @@ jobs:
     strategy:
       matrix:
         include:
-          - service_name: "merge-api-images"
-            image_name_env: "DIFY_API_IMAGE_NAME"
-            context: "api"
-          - service_name: "merge-web-images"
-            image_name_env: "DIFY_WEB_IMAGE_NAME"
-            context: "web"
+          - service_name: 'merge-api-images'
+            image_name_env: 'DIFY_API_IMAGE_NAME'
+            context: 'api'
+          - service_name: 'merge-web-images'
+            image_name_env: 'DIFY_WEB_IMAGE_NAME'
+            context: 'web'
     steps:
       - name: Download digests
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

.github/workflows/cli-e2e.yml

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

.github/workflows/cli-smoke.yml

@@ -4,11 +4,11 @@ on:
   workflow_dispatch:
     inputs:
       dify_version:
-        description: "Dify image tag to test against (e.g. 1.7.0)"
+        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)"
+        description: 'Git ref to build the cli from (default: current branch)'
         type: string
         required: false
 

.github/workflows/cli-tests.yml

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

.github/workflows/db-migration-test.yml

@@ -22,7 +22,7 @@ jobs:
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -72,7 +72,7 @@ jobs:
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies

.github/workflows/deploy-dev.yml

@@ -2,9 +2,9 @@ name: Deploy Dev
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ['Build and Push API & Web']
     branches:
-      - "deploy/dev"
+      - 'deploy/dev'
     types:
       - completed
 

.github/workflows/deploy-enterprise.yml

@@ -5,9 +5,9 @@ permissions:
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ['Build and Push API & Web']
     branches:
-      - "deploy/enterprise"
+      - 'deploy/enterprise'
     types:
       - completed
 

.github/workflows/deploy-hitl.yml

@@ -2,9 +2,9 @@ name: Deploy HITL
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ['Build and Push API & Web']
     branches:
-      - "build/feat/hitl"
+      - 'build/feat/hitl'
     types:
       - completed
 

.github/workflows/deploy-saas.yml

@@ -5,9 +5,9 @@ permissions:
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ['Build and Push API & Web']
     branches:
-      - "deploy/saas"
+      - 'deploy/saas'
     types:
       - completed
 

.github/workflows/docker-build.yml

@@ -3,7 +3,7 @@ name: Build docker image
 on:
   pull_request:
     branches:
-      - "main"
+      - 'main'
     paths:
       - api/Dockerfile
       - api/Dockerfile.dockerignore
@@ -28,26 +28,26 @@ jobs:
     strategy:
       matrix:
         include:
-          - service_name: "api-amd64"
+          - service_name: 'api-amd64'
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
-            context: "{{defaultContext}}"
-            file: "api/Dockerfile"
-          - service_name: "api-arm64"
+            context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'api-arm64'
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
-            context: "{{defaultContext}}"
-            file: "api/Dockerfile"
-          - service_name: "web-amd64"
+            context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'web-amd64'
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
-            context: "{{defaultContext}}"
-            file: "web/Dockerfile"
-          - service_name: "web-arm64"
+            context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
+          - service_name: 'web-arm64'
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
-            context: "{{defaultContext}}"
-            file: "web/Dockerfile"
+            context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
     steps:
       - name: Set up Depot CLI
         uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
@@ -69,12 +69,12 @@ jobs:
     strategy:
       matrix:
         include:
-          - service_name: "api-amd64"
-            context: "{{defaultContext}}"
-            file: "api/Dockerfile"
-          - service_name: "web-amd64"
-            context: "{{defaultContext}}"
-            file: "web/Dockerfile"
+          - service_name: 'api-amd64'
+            context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'web-amd64'
+            context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
     steps:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

.github/workflows/labeler.yml

@@ -1,4 +1,4 @@
-name: "Pull Request Labeler"
+name: 'Pull Request Labeler'
 on:
   pull_request_target:
 

.github/workflows/main-ci.yml

@@ -2,12 +2,12 @@ name: Main CI Pipeline
 
 on:
   pull_request:
-    branches: ["main"]
+    branches: ['main']
   merge_group:
-    branches: ["main"]
+    branches: ['main']
     types: [checks_requested]
   push:
-    branches: ["main"]
+    branches: ['main']
 
 permissions:
   actions: write

.github/workflows/semantic-pull-request.yml

@@ -8,7 +8,7 @@ on:
       - reopened
       - synchronize
   merge_group:
-    branches: ["main"]
+    branches: ['main']
     types: [checks_requested]
 
 jobs:

.github/workflows/stale.yml

@@ -11,7 +11,6 @@ on:
 
 jobs:
   stale:
-
     runs-on: depot-ubuntu-24.04
     permissions:
       issues: write
@@ -23,8 +22,8 @@ jobs:
           days-before-issue-stale: 15
           days-before-issue-close: 3
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          stale-issue-message: "Closed due to inactivity. If you have any questions, you can reopen it."
-          stale-pr-message: "Closed due to inactivity. If you have any questions, you can reopen it."
+          stale-issue-message: 'Closed due to inactivity. If you have any questions, you can reopen it.'
+          stale-pr-message: 'Closed due to inactivity. If you have any questions, you can reopen it.'
           stale-issue-label: 'no-issue-activity'
           stale-pr-label: 'no-pr-activity'
           any-of-labels: '🌚 invalid,🙋‍♂️ question,wont-fix,no-issue-activity,no-pr-activity,💪 enhancement,🤔 cant-reproduce,🙏 help wanted'

.github/workflows/style.yml

@@ -36,7 +36,7 @@ jobs:
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: false
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -132,7 +132,10 @@ jobs:
             pnpm-lock.yaml
             pnpm-workspace.yaml
             .nvmrc
+            vite.config.ts
             eslint.config.mjs
+            .vscode/**
+            .github/workflows/autofix.yml
             .github/workflows/style.yml
             .github/actions/setup-web/**
 
@@ -140,6 +143,12 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
+      - name: Format check
+        if: steps.changed-files.outputs.any_changed == 'true'
+        env:
+          CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
+        run: vp fmt --check --no-error-on-unmatched-pattern $CHANGED_FILES
+
       - name: Restore ESLint cache
         if: steps.changed-files.outputs.any_changed == 'true'
         id: eslint-cache-restore

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

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
@@ -48,16 +48,16 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
-#      - name: Set up Vector Store (TiDB)
-#        uses: hoverkraft-tech/compose-action@v2.0.2
-#        with:
-#          compose-file: docker/tidb/docker-compose.yaml
-#          services: |
-#            tidb
-#            tiflash
+      #      - name: Set up Vector Store (TiDB)
+      #        uses: hoverkraft-tech/compose-action@v2.0.2
+      #        with:
+      #          compose-file: docker/tidb/docker-compose.yaml
+      #          services: |
+      #            tidb
+      #            tiflash
 
-#      - name: Check VDB Ready (TiDB)
-#        run: uv run --project api python api/providers/vdb/tidb-vector/tests/integration_tests/check_tiflash_ready.py
+      #      - 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: |

.github/workflows/vdb-tests.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
@@ -45,16 +45,16 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
-#      - name: Set up Vector Store (TiDB)
-#        uses: hoverkraft-tech/compose-action@v2.0.2
-#        with:
-#          compose-file: docker/tidb/docker-compose.yaml
-#          services: |
-#            tidb
-#            tiflash
+      #      - name: Set up Vector Store (TiDB)
+      #        uses: hoverkraft-tech/compose-action@v2.0.2
+      #        with:
+      #          compose-file: docker/tidb/docker-compose.yaml
+      #          services: |
+      #            tidb
+      #            tiflash
 
-#      - name: Check VDB Ready (TiDB)
-#        run: uv run --project api python api/providers/vdb/tidb-vector/tests/integration_tests/check_tiflash_ready.py
+      #      - 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: |

.github/workflows/web-e2e.yml

@@ -31,7 +31,7 @@ jobs:
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install API dependencies
@@ -47,7 +47,7 @@ jobs:
           E2E_ADMIN_EMAIL: e2e-admin@example.com
           E2E_ADMIN_NAME: E2E Admin
           E2E_ADMIN_PASSWORD: E2eAdmin12345
-          E2E_FORCE_WEB_BUILD: "1"
+          E2E_FORCE_WEB_BUILD: '1'
           E2E_INIT_PASSWORD: E2eInit12345
         run: vp run e2e:full
 

.vscode/settings.example.json

@@ -1,31 +1,17 @@
 {
-  "cucumber.features": [
-    "e2e/features/**/*.feature",
-  ],
-  "cucumber.glue": [
-    "e2e/features/**/*.ts",
-  ],
+  "cucumber.features": ["e2e/features/**/*.feature"],
+  "cucumber.glue": ["e2e/features/**/*.ts"],
 
   "tailwindCSS.experimental.configFile": "web/app/styles/globals.css",
 
-  // Auto fix
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit",
-  },
+  // Format
+  "editor.formatOnSave": true,
+  "oxc.fmt.configPath": "./vite.config.ts",
 
-  // Silent the stylistic rules in your IDE, but still auto fix them
-  "eslint.rules.customizations": [
-    { "rule": "style/*", "severity": "off", "fixable": true },
-    { "rule": "format/*", "severity": "off", "fixable": true },
-    { "rule": "*-indent", "severity": "off", "fixable": true },
-    { "rule": "*-spacing", "severity": "off", "fixable": true },
-    { "rule": "*-spaces", "severity": "off", "fixable": true },
-    { "rule": "*-order", "severity": "off", "fixable": true },
-    { "rule": "*-dangle", "severity": "off", "fixable": true },
-    { "rule": "*-newline", "severity": "off", "fixable": true },
-    { "rule": "*quotes", "severity": "off", "fixable": true },
-    { "rule": "*semi", "severity": "off", "fixable": true }
-  ],
+  // Lint fix
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
 
   // Enable eslint for all supported languages
   "eslint.validate": [

AGENTS.md

@@ -31,7 +31,7 @@ The codebase is split into:
 ## Language Style
 
 - **Python**: Keep type hints on functions and attributes, and implement relevant special methods (e.g., `__repr__`, `__str__`). Prefer `TypedDict` over `dict` or `Mapping` for type safety and better code documentation.
-- **TypeScript**: Use the strict config, rely on ESLint (`pnpm lint:fix` preferred) plus `pnpm type-check`, and avoid `any` types.
+- **TypeScript**: Use the strict config, rely on `vp fmt` for formatting, ESLint for lint-only fixes, plus `pnpm type-check`, and avoid `any` types.
 
 ## General Practices
 

CONTRIBUTING.md

@@ -34,11 +34,11 @@ Don't forget to link an existing issue or open a new issue in the PR's descripti
 
 How we prioritize:
 
-| Issue Type | Priority |
-| ------------------------------------------------------------ | --------------- |
-| Bugs in core functions (cloud service, cannot login, applications not working, security loopholes) | Critical |
-| Non-critical bugs, performance boosts | Medium Priority |
-| Minor fixes (typos, confusing but working UI) | Low Priority |
+| Issue Type                                                                                         | Priority        |
+| -------------------------------------------------------------------------------------------------- | --------------- |
+| Bugs in core functions (cloud service, cannot login, applications not working, security loopholes) | Critical        |
+| Non-critical bugs, performance boosts                                                              | Medium Priority |
+| Minor fixes (typos, confusing but working UI)                                                      | Low Priority    |
 
 ### Feature requests
 
@@ -52,12 +52,12 @@ How we prioritize:
 
 How we prioritize:
 
-| Feature Type | Priority |
-| ------------------------------------------------------------ | --------------- |
-| High-Priority Features as being labeled by a team member | High Priority |
+| Feature Type                                                                                                                      | Priority        |
+| --------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| High-Priority Features as being labeled by a team member                                                                          | High Priority   |
 | Popular feature requests from our [community feedback board](https://github.com/langgenius/dify/discussions/categories/feedbacks) | Medium Priority |
-| Non-core features and minor enhancements | Low Priority |
-| Valuable but not immediate | Future-Feature |
+| Non-core features and minor enhancements                                                                                          | Low Priority    |
+| Valuable but not immediate                                                                                                        | Future-Feature  |
 
 ## Submitting your PR
 

Makefile

@@ -157,7 +157,7 @@ build-web:
 
 build-api:
 	@echo "Building API Docker image: $(API_IMAGE):$(VERSION)..."
-	docker build -t $(API_IMAGE):$(VERSION) ./api
+	docker build -t $(API_IMAGE):$(VERSION) -f api/Dockerfile .
 	@echo "API Docker image built successfully: $(API_IMAGE):$(VERSION)"
 
 # Push Docker images

api/Dockerfile.dockerignore

@@ -8,18 +8,30 @@
 !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*
+# Environment configuration and example
+.env
+*.env.*
+
+# Python related files
 **/__pycache__
 **/*.pyc
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.import_linter_cache/
+**/.pytest_cache/
+**/.hypothesis/
+
+
+# Upload files and logs
+api/storage/**
+api/logs/
+api/*.log*
+
+# Tests
+api/tests
+
+
+# Editor configuration
+**/.vscode/
+**/.idea/

api/app.py

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

api/app_factory.py

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

api/celery_entrypoint.py

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

api/clients/agent_backend/__init__.py

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

api/clients/agent_backend/event_adapter.py

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

api/clients/agent_backend/fake_client.py

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

api/clients/agent_backend/request_builder.py

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

api/clients/agent_backend/workspace_files_client.py

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

api/commands/__init__.py

@@ -11,7 +11,6 @@ from .data_migration import (
     migration_data_wizard,
 )
 from .plugin import (
-    backfill_plugin_auto_upgrade,
     extract_plugins,
     extract_unique_plugins,
     install_plugins,
@@ -50,7 +49,6 @@ from .vector import (
 __all__ = [
     "add_qdrant_index",
     "archive_workflow_runs",
-    "backfill_plugin_auto_upgrade",
     "clean_expired_messages",
     "clean_workflow_runs",
     "cleanup_orphaned_draft_variables",

api/commands/data_migrate.py

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

api/commands/plugin.py

@@ -1,11 +1,10 @@
 import json
 import logging
-import time
 from typing import Any, cast
 
 import click
 from pydantic import TypeAdapter
-from sqlalchemy import delete, func, select
+from sqlalchemy import delete, select
 from sqlalchemy.engine import CursorResult
 
 from configs import dify_config
@@ -16,13 +15,11 @@ 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
-from models.account import TenantPluginAutoUpgradeStrategy
 from models.oauth import DatasourceOauthParamConfig, DatasourceProvider
 from models.provider_ids import DatasourceProviderID, ToolProviderID
 from models.source import DataSourceApiKeyAuthBinding, DataSourceOauthBinding
 from models.tools import ToolOAuthSystemClient
 from services.plugin.data_migration import PluginDataMigration
-from services.plugin.plugin_auto_upgrade_service import PluginAutoUpgradeService
 from services.plugin.plugin_migration import PluginMigration
 
 logger = logging.getLogger(__name__)
@@ -405,110 +402,6 @@ def migrate_data_for_plugin():
     click.echo(click.style("Migrate data for plugin completed.", fg="green"))
 
 
-def _candidate_auto_upgrade_strategy_tenant_ids_stmt(limit: int | None = None):
-    category_count = len(TenantPluginAutoUpgradeStrategy.PluginCategory)
-    stmt = (
-        select(TenantPluginAutoUpgradeStrategy.tenant_id)
-        .group_by(TenantPluginAutoUpgradeStrategy.tenant_id)
-        .having(func.count(func.distinct(TenantPluginAutoUpgradeStrategy.category)) < category_count)
-        .order_by(TenantPluginAutoUpgradeStrategy.tenant_id)
-    )
-
-    if limit is not None:
-        stmt = stmt.limit(limit)
-
-    return stmt
-
-
-def _count_auto_upgrade_strategy_tenant_ids(limit: int | None) -> int:
-    candidate_stmt = _candidate_auto_upgrade_strategy_tenant_ids_stmt(limit).subquery()
-    return db.session.scalar(select(func.count()).select_from(candidate_stmt)) or 0
-
-
-def _iter_auto_upgrade_strategy_tenant_ids(limit: int | None):
-    stmt = _candidate_auto_upgrade_strategy_tenant_ids_stmt(limit).execution_options(yield_per=1000)
-    yield from db.session.scalars(stmt)
-
-
-@click.command(
-    "backfill-plugin-auto-upgrade",
-    help="Backfill category-scoped plugin auto-upgrade strategies and normalize plugin lists.",
-)
-@click.option("--tenant-id", multiple=True, help="Tenant ID to backfill. Can be passed multiple times.")
-@click.option("--limit", type=int, default=None, help="Maximum number of candidate tenants to process.")
-@click.option("--batch-size", type=int, default=500, show_default=True, help="Progress reporting batch size.")
-@click.option("--dry-run", is_flag=True, help="Only print candidate tenant count.")
-def backfill_plugin_auto_upgrade(
-    tenant_id: tuple[str, ...],
-    limit: int | None,
-    batch_size: int,
-    dry_run: bool,
-):
-    """
-    Backfill historical auto-upgrade strategies after the category column exists.
-
-    Missing category rows are created from the tenant's tool/default row. Pure default
-    strategies become latest for model plugins and fix-only for all other categories.
-    Tenants with include/exclude plugin IDs are split
-    by installed plugin category using plugin daemon metadata.
-    """
-    start_at = time.perf_counter()
-    candidate_count = len(tenant_id) if tenant_id else _count_auto_upgrade_strategy_tenant_ids(limit)
-    click.echo(click.style(f"Found {candidate_count} candidate tenants.", fg="yellow"))
-
-    if dry_run:
-        elapsed = time.perf_counter() - start_at
-        click.echo(click.style(f"Dry run completed. elapsed={elapsed:.2f}s", fg="green"))
-        return
-
-    tenant_ids = list(tenant_id) if tenant_id else _iter_auto_upgrade_strategy_tenant_ids(limit)
-
-    backfilled_count = 0
-    created_count = 0
-    normalized_count = 0
-    skipped_count = 0
-    failed_count = 0
-    for index, current_tenant_id in enumerate(tenant_ids, start=1):
-        try:
-            result = PluginAutoUpgradeService.backfill_strategy_categories(
-                current_tenant_id,
-            )
-        except Exception as e:
-            failed_count += 1
-            click.echo(click.style(f"Failed tenant {current_tenant_id}: {str(e)}", fg="red"))
-            continue
-
-        if result.created_count > 0:
-            backfilled_count += 1
-            created_count += result.created_count
-        elif not result.normalized:
-            skipped_count += 1
-        if result.normalized:
-            normalized_count += 1
-
-        if batch_size > 0 and index % batch_size == 0:
-            click.echo(
-                click.style(
-                    f"Processed {index}/{candidate_count} tenants. "
-                    f"backfilled={backfilled_count}, created_rows={created_count}, "
-                    f"normalized={normalized_count}, skipped={skipped_count}, failed={failed_count}, "
-                    f"elapsed={time.perf_counter() - start_at:.2f}s",
-                    fg="yellow",
-                )
-            )
-
-    elapsed = time.perf_counter() - start_at
-    click.echo(
-        click.style(
-            f"Backfill plugin auto-upgrade strategy categories completed. "
-            f"backfilled={backfilled_count}, created_rows={created_count}, "
-            f"normalized={normalized_count}, skipped={skipped_count}, failed={failed_count}, "
-            f"elapsed={elapsed:.2f}s",
-            fg="green",
-        )
-    )
-
-
 @click.command("extract-plugins", help="Extract plugins.")
 @click.option("--output_file", prompt=True, help="The file to store the extracted plugins.", default="plugins.jsonl")
 @click.option("--workers", prompt=True, help="The number of workers to extract plugins.", default=10)

api/configs/enterprise/__init__.py

@@ -16,7 +16,7 @@ class EnterpriseFeatureConfig(BaseSettings):
 
     CAN_REPLACE_LOGO: bool = Field(
         description="Allow customization of the enterprise logo.",
-        default=False,
+        default=True,
     )
 
     ENTERPRISE_REQUEST_TIMEOUT: int = Field(

api/configs/extra/agent_backend_config.py

@@ -31,3 +31,13 @@ class AgentBackendConfig(BaseSettings):
         ),
         default=False,
     )
+
+    AGENT_DRIVE_MANIFEST_ENABLED: bool = Field(
+        description=(
+            "Inject the dify.drive layer (Skills & Files drive manifest declaration) "
+            "into Agent runs. The declaration is an index only — the agent backend "
+            "pulls the actual SKILL.md / files through the back proxy. Keep it off "
+            "until the agent backend registers the dify.drive layer type."
+        ),
+        default=False,
+    )

api/configs/feature/__init__.py

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

api/context/execution_context.py

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

api/controllers/common/controller_schemas.py

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

api/controllers/common/errors.py

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

api/controllers/common/fields.py

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

api/controllers/common/schema.py

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

api/controllers/common/wraps.py

@@ -0,0 +1,30 @@
+from collections.abc import Callable
+from functools import wraps
+
+from core.rbac import RBACPermission, RBACResourceScope
+
+__all__ = ["RBACPermission", "RBACResourceScope", "rbac_permission_required"]
+
+
+def rbac_permission_required[**P, R](
+    resource_type: RBACResourceScope,
+    scene: RBACPermission,
+    *,
+    resource_required: bool = True,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Check enterprise RBAC permissions for the current user.
+
+    Args:
+        resource_type: The :class:`RBACResourceScope` member (app/dataset/workspace).
+        scene: The :class:`RBACPermission` permission point.
+        resource_required: Whether a concrete resource ID is required.
+    """
+
+    def decorator(view: Callable[P, R]) -> Callable[P, R]:
+        @wraps(view)
+        def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
+            return view(*args, **kwargs)
+
+        return decorated
+
+    return decorator

api/controllers/console/__init__.py

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

api/controllers/console/agent/composer.py

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

api/controllers/console/agent/roster.py

@@ -8,23 +8,22 @@ from controllers.common.schema import query_params_from_model, register_response
 from controllers.console import console_ns
 from controllers.console.wraps import (
     account_initialization_required,
-    edit_permission_required,
     setup_required,
     with_current_tenant_id,
-    with_current_user_id,
 )
 from extensions.ext_database import db
 from fields.agent_fields import (
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
+    AgentPublishedReferenceResponse,
     AgentRosterListResponse,
     AgentRosterResponse,
 )
 from libs.helper import dump_response
 from libs.login import login_required
 from services.agent.roster_service import AgentRosterService
-from services.entities.agent_entities import RosterAgentCreatePayload, RosterAgentUpdatePayload, RosterListQuery
+from services.entities.agent_entities import RosterListQuery
 
 
 class AgentInviteOptionsQuery(RosterListQuery):
@@ -39,8 +38,6 @@ register_schema_models(
     console_ns,
     AgentInviteOptionsQuery,
     AgentIdPath,
-    RosterAgentCreatePayload,
-    RosterAgentUpdatePayload,
     RosterListQuery,
 )
 register_response_schema_models(
@@ -48,6 +45,7 @@ register_response_schema_models(
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
+    AgentPublishedReferenceResponse,
     AgentRosterListResponse,
     AgentRosterResponse,
 )
@@ -74,23 +72,6 @@ class AgentRosterListApi(Resource):
             ),
         )
 
-    @console_ns.expect(console_ns.models[RosterAgentCreatePayload.__name__])
-    @console_ns.response(201, "Agent created", console_ns.models[AgentRosterResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
-    @with_current_tenant_id
-    def post(self, tenant_id: str, account_id: str):
-        payload = RosterAgentCreatePayload.model_validate(console_ns.payload or {})
-        service = _agent_roster_service()
-        agent = service.create_roster_agent(tenant_id=tenant_id, account_id=account_id, payload=payload)
-        return dump_response(
-            AgentRosterResponse,
-            service.get_roster_agent_detail(tenant_id=tenant_id, agent_id=agent.id),
-        ), 201
-
 
 @console_ns.route("/agents/invite-options")
 class AgentInviteOptionsApi(Resource):
@@ -127,34 +108,6 @@ class AgentRosterDetailApi(Resource):
             _agent_roster_service().get_roster_agent_detail(tenant_id=tenant_id, agent_id=str(agent_id)),
         )
 
-    @console_ns.expect(console_ns.models[RosterAgentUpdatePayload.__name__])
-    @console_ns.response(200, "Agent updated", console_ns.models[AgentRosterResponse.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
-    @with_current_tenant_id
-    def patch(self, tenant_id: str, account_id: str, agent_id: UUID):
-        payload = RosterAgentUpdatePayload.model_validate(console_ns.payload or {})
-        return dump_response(
-            AgentRosterResponse,
-            _agent_roster_service().update_roster_agent(
-                tenant_id=tenant_id, agent_id=str(agent_id), account_id=account_id, payload=payload
-            ),
-        )
-
-    @console_ns.response(204, "Agent archived")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @edit_permission_required
-    @with_current_user_id
-    @with_current_tenant_id
-    def delete(self, tenant_id: str, account_id: str, agent_id: UUID):
-        _agent_roster_service().archive_roster_agent(tenant_id=tenant_id, agent_id=str(agent_id), account_id=account_id)
-        return "", 204
-
 
 @console_ns.route("/agents/<uuid:agent_id>/versions")
 class AgentRosterVersionsApi(Resource):

api/controllers/console/app/advanced_prompt_template.py

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

api/controllers/console/app/agent.py

@@ -1,15 +1,48 @@
-from flask import request
-from flask_restx import Resource, fields
-from pydantic import BaseModel, Field, field_validator
+import logging
+from typing import Any
 
-from controllers.common.schema import register_schema_models
+from flask import request
+from flask_restx import Resource
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+    register_schema_models,
+)
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
+from extensions.ext_database import db
+from fields.base import ResponseModel
 from libs.helper import uuid_value
 from libs.login import login_required
-from models.model import App, AppMode
+from models import Account
+from models.agent_config_entities import AgentFileRefConfig, AgentSkillRefConfig
+from models.model import App, AppMode, UploadFile
+from services.agent.composer_service import AgentComposerService
+from services.agent.skill_package_service import SkillManifest, SkillPackageError, SkillPackageService
+from services.agent.skill_standardize_service import SkillStandardizeService
+from services.agent.skill_tool_inference_service import (
+    SkillToolInferenceError,
+    SkillToolInferenceResult,
+    SkillToolInferenceService,
+)
+from services.agent_drive_service import (
+    AgentDriveError,
+    AgentDriveService,
+    DriveCommitItem,
+    DriveFileRef,
+    normalize_drive_key,
+)
 from services.agent_service import AgentService
+from services.file_service import FileService
+
+logger = logging.getLogger(__name__)
+
+_AGENT_DRIVE_APP_MODES = [AppMode.AGENT, AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
 
 
 class AgentLogQuery(BaseModel):
@@ -22,7 +55,112 @@ class AgentLogQuery(BaseModel):
         return uuid_value(value)
 
 
-register_schema_models(console_ns, AgentLogQuery)
+class AgentDriveFilePayload(BaseModel):
+    upload_file_id: str = Field(..., description="UploadFile UUID from POST /console/api/files/upload")
+
+    @field_validator("upload_file_id")
+    @classmethod
+    def validate_upload_file_id(cls, value: str) -> str:
+        return uuid_value(value)
+
+
+class AgentDriveMutationQuery(BaseModel):
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+class AgentDriveDeleteFileQuery(AgentDriveMutationQuery):
+    key: str = Field(min_length=1, description="Drive key, e.g. files/sample.pdf")
+
+
+class AgentLogMetaResponse(ResponseModel):
+    status: str
+    executor: str
+    start_time: str
+    elapsed_time: float | None = None
+    total_tokens: int
+    agent_mode: str
+    iterations: int
+
+
+class AgentToolCallResponse(ResponseModel):
+    status: str
+    error: str | None = None
+    time_cost: float | int
+    tool_name: str
+    tool_label: str
+    tool_input: dict[str, Any]
+    tool_output: dict[str, Any]
+    tool_parameters: dict[str, Any]
+    tool_icon: Any = Field(default=None)
+
+
+class AgentIterationLogResponse(ResponseModel):
+    tokens: int
+    tool_calls: list[AgentToolCallResponse]
+    tool_raw: dict[str, Any]
+    thought: str | None = None
+    created_at: str
+    files: list[Any] = Field(default_factory=list)
+
+
+class AgentLogResponse(ResponseModel):
+    meta: AgentLogMetaResponse
+    iterations: list[AgentIterationLogResponse]
+    files: list[Any] = Field(default_factory=list)
+
+
+class AgentSkillUploadResponse(ResponseModel):
+    skill: AgentSkillRefConfig
+    manifest: SkillManifest
+
+
+class AgentSkillStandardizeResponse(ResponseModel):
+    skill: AgentSkillRefConfig
+    manifest: SkillManifest
+
+
+class AgentDriveFileResponse(ResponseModel):
+    name: str
+    drive_key: str
+    file_id: str
+    size: int | None = None
+    mime_type: str | None = None
+
+
+class AgentDriveFileCommitResponse(ResponseModel):
+    file: AgentDriveFileResponse
+    config_version_id: str | None = None
+
+
+class AgentDriveDeleteResponse(ResponseModel):
+    result: str
+    removed_keys: list[str] = Field(default_factory=list)
+    config_version_id: str | None = None
+
+
+register_schema_models(console_ns, AgentLogQuery, AgentDriveFilePayload)
+register_response_schema_models(
+    console_ns,
+    AgentDriveDeleteResponse,
+    AgentDriveFileCommitResponse,
+    AgentDriveFileResponse,
+    AgentLogResponse,
+    AgentSkillStandardizeResponse,
+    AgentSkillUploadResponse,
+    SkillToolInferenceResult,
+)
+
+
+def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+    if node_id:
+        return AgentComposerService.resolve_workflow_node_agent_id(
+            tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
+        )
+    return app_model.bound_agent_id
+
+
+def _agent_not_bound() -> tuple[dict[str, str], int]:
+    return {"code": "agent_not_bound", "message": "no agent is bound for this app/node"}, 400
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/logs")
@@ -30,10 +168,8 @@ class AgentLogApi(Resource):
     @console_ns.doc("get_agent_logs")
     @console_ns.doc(description="Get agent execution logs for an application")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.expect(console_ns.models[AgentLogQuery.__name__])
-    @console_ns.response(
-        200, "Agent logs retrieved successfully", fields.List(fields.Raw(description="Agent log entries"))
-    )
+    @console_ns.doc(params=query_params_from_model(AgentLogQuery))
+    @console_ns.response(200, "Agent logs retrieved successfully", console_ns.models[AgentLogResponse.__name__])
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
     @login_required
@@ -44,3 +180,287 @@ class AgentLogApi(Resource):
         args = AgentLogQuery.model_validate(request.args.to_dict(flat=True))
 
         return AgentService.get_agent_logs(app_model, args.conversation_id, args.message_id)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/upload")
+class AgentSkillUploadApi(Resource):
+    @console_ns.doc("upload_agent_skill")
+    @console_ns.doc(description="Upload + validate a Skill package (.zip/.skill) and extract its manifest")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(201, "Skill validated", console_ns.models[AgentSkillUploadResponse.__name__])
+    @console_ns.response(400, "Invalid skill package")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """Validate an uploaded Skill package and persist the archive.
+
+        Returns a validated skill ref (to bind into the Agent soul config on save)
+        plus its manifest. Standardizing into the agent drive is ENG-594.
+        """
+        if "file" not in request.files:
+            return {"code": "no_file", "message": "no skill file uploaded"}, 400
+        if len(request.files) > 1:
+            return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+
+        upload = request.files["file"]
+        content = upload.stream.read()
+        try:
+            manifest = SkillPackageService().validate_and_extract(content=content, filename=upload.filename or "")
+        except SkillPackageError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+
+        upload_file = FileService(db.engine).upload_file(
+            filename=upload.filename or "skill.zip",
+            content=content,
+            mimetype=upload.mimetype or "application/zip",
+            user=current_user,
+        )
+        skill_ref = manifest.to_skill_ref(file_id=upload_file.id)
+        return {"skill": skill_ref.model_dump(exclude_none=True), "manifest": manifest.model_dump()}, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/standardize")
+class AgentSkillStandardizeApi(Resource):
+    @console_ns.doc("standardize_agent_skill")
+    @console_ns.doc(description="Validate + standardize a Skill into the agent drive (ENG-594)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveMutationQuery)})
+    @console_ns.response(
+        201,
+        "Skill standardized into drive",
+        console_ns.models[AgentSkillStandardizeResponse.__name__],
+    )
+    @console_ns.response(400, "Invalid skill package or no bound agent")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """Upload a Skill, validate it, and standardize it into the app agent's drive."""
+        query = query_params_from_request(AgentDriveMutationQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        if "file" not in request.files:
+            return {"code": "no_file", "message": "no skill file uploaded"}, 400
+        if len(request.files) > 1:
+            return {"code": "too_many_files", "message": "only one skill file is allowed"}, 400
+
+        upload = request.files["file"]
+        content = upload.stream.read()
+        try:
+            result = SkillStandardizeService().standardize(
+                content=content,
+                filename=upload.filename or "",
+                tenant_id=app_model.tenant_id,
+                user_id=current_user.id,
+                agent_id=agent_id,
+            )
+        except (SkillPackageError, AgentDriveError) as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+        return result, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/files")
+class AgentDriveFilesApi(Resource):
+    @console_ns.doc("commit_agent_drive_file")
+    @console_ns.doc(description="Commit an uploaded file into the agent drive under files/<name> (ENG-625 D3)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveMutationQuery)})
+    @console_ns.expect(console_ns.models[AgentDriveFilePayload.__name__])
+    @console_ns.response(
+        201, "File committed into the agent drive", console_ns.models[AgentDriveFileCommitResponse.__name__]
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """ADD FILE: commit one uploaded file into the bound agent's drive."""
+        query = query_params_from_request(AgentDriveMutationQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        payload = AgentDriveFilePayload.model_validate(console_ns.payload or {})
+
+        upload_file = db.session.scalar(
+            select(UploadFile).where(
+                UploadFile.id == payload.upload_file_id,
+                UploadFile.tenant_id == app_model.tenant_id,
+            )
+        )
+        if upload_file is None:
+            return {"code": "upload_file_not_found", "message": "upload file not found in this workspace"}, 404
+
+        try:
+            key = normalize_drive_key(f"files/{upload_file.name}")
+            committed = AgentDriveService().commit(
+                tenant_id=app_model.tenant_id,
+                user_id=current_user.id,
+                agent_id=agent_id,
+                items=[
+                    DriveCommitItem(
+                        key=key,
+                        file_ref=DriveFileRef(kind="upload_file", id=upload_file.id),
+                        # ADD FILE uploads exist solely to live in the drive, so the
+                        # drive owns (and physically cleans) the value on delete.
+                        value_owned_by_drive=True,
+                    )
+                ],
+            )
+        except AgentDriveError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+
+        row = committed[0]
+        file_ref = AgentFileRefConfig.model_validate(
+            {
+                "id": row["key"],
+                "name": upload_file.name,
+                "file_id": upload_file.id,
+                "drive_key": row["key"],
+                "type": row.get("mime_type"),
+                "size": row.get("size"),
+            }
+        )
+        config_version_id = AgentComposerService.add_drive_file_ref(
+            tenant_id=app_model.tenant_id,
+            agent_id=agent_id,
+            account_id=current_user.id,
+            file_ref=file_ref,
+            app_id=app_model.id,
+            node_id=query.node_id,
+        )
+        return {
+            "file": {
+                "name": upload_file.name,
+                "drive_key": row["key"],
+                "file_id": upload_file.id,
+                "size": row.get("size"),
+                "mime_type": row.get("mime_type"),
+            },
+            "config_version_id": config_version_id,
+        }, 201
+
+    @console_ns.doc("delete_agent_drive_file")
+    @console_ns.doc(description="Delete one drive file by key; soul ref first, then the KV row (ENG-625 D5)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveDeleteFileQuery)})
+    @console_ns.response(200, "File removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def delete(self, current_user: Account, app_model: App):
+        query = query_params_from_request(AgentDriveDeleteFileQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            key = normalize_drive_key(query.key)
+        except AgentDriveError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+
+        config_version_id = AgentComposerService.remove_drive_refs(
+            tenant_id=app_model.tenant_id,
+            agent_id=agent_id,
+            account_id=current_user.id,
+            file_key=key,
+            app_id=app_model.id,
+            node_id=query.node_id,
+        )
+        removed_keys: list[str] = []
+        try:
+            removed_keys = AgentDriveService().delete(tenant_id=app_model.tenant_id, agent_id=agent_id, key=key)
+        except AgentDriveError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+        except Exception:
+            # Soul-first ordering: the ref is already gone; orphan KV rows are
+            # harmless and an idempotent DELETE retry cleans them.
+            logger.exception("agent drive delete failed for key %s (soul already updated)", key)
+        return {"result": "success", "removed_keys": removed_keys, "config_version_id": config_version_id}
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>")
+class AgentSkillApi(Resource):
+    @console_ns.doc("delete_agent_skill")
+    @console_ns.doc(
+        description="Delete a standardized skill: soul ref first, then the <slug>/ drive prefix (ENG-625 D5)"
+    )
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "slug": "Skill slug (single path segment)",
+            **query_params_from_model(AgentDriveMutationQuery),
+        }
+    )
+    @console_ns.response(200, "Skill removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @with_current_user
+    def delete(self, current_user: Account, app_model: App, slug: str):
+        query = query_params_from_request(AgentDriveMutationQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        if "/" in slug or not slug.strip():
+            return {"code": "drive_key_invalid", "message": "skill slug must be a single path segment"}, 400
+
+        config_version_id = AgentComposerService.remove_drive_refs(
+            tenant_id=app_model.tenant_id,
+            agent_id=agent_id,
+            account_id=current_user.id,
+            skill_slug=slug,
+            app_id=app_model.id,
+            node_id=query.node_id,
+        )
+        removed_keys: list[str] = []
+        try:
+            removed_keys = AgentDriveService().delete(
+                tenant_id=app_model.tenant_id, agent_id=agent_id, prefix=f"{slug}/"
+            )
+        except AgentDriveError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code
+        except Exception:
+            logger.exception("agent drive delete failed for skill %s (soul already updated)", slug)
+        return {"result": "success", "removed_keys": removed_keys, "config_version_id": config_version_id}
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>/infer-tools")
+class AgentSkillInferToolsApi(Resource):
+    @console_ns.doc("infer_agent_skill_tools")
+    @console_ns.doc(
+        description="Infer CLI tool + ENV suggestions from a standardized skill's SKILL.md (draft only, ENG-371)"
+    )
+    @console_ns.doc(
+        params={
+            "app_id": "Application ID",
+            "slug": "Skill slug (single path segment)",
+            **query_params_from_model(AgentDriveMutationQuery),
+        }
+    )
+    @console_ns.response(
+        200,
+        "Inference result (draft suggestions, nothing persisted)",
+        console_ns.models[SkillToolInferenceResult.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    def post(self, app_model: App, slug: str):
+        """Suggest CLI tools/env for a skill. Saving still goes through composer validation."""
+        query = query_params_from_request(AgentDriveMutationQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        if "/" in slug or not slug.strip():
+            return {"code": "drive_key_invalid", "message": "skill slug must be a single path segment"}, 400
+        try:
+            return SkillToolInferenceService().infer(tenant_id=app_model.tenant_id, agent_id=agent_id, slug=slug)
+        except SkillToolInferenceError as exc:
+            return {"code": exc.code, "message": exc.message}, exc.status_code

api/controllers/console/app/agent_app_sandbox.py

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

api/controllers/console/app/agent_app_workspace.py

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

api/controllers/console/app/agent_drive_inspector.py

@@ -0,0 +1,162 @@
+"""Console read-only inspector for the agent drive (ENG-624).
+
+``agent-drive`` looks at the *static* drive assets (standardized skills and
+committed files); the sibling ``agent-sandbox`` routes look at a *runtime*
+sandbox workspace. Unlike the sandbox routes this never proxies to the agent
+backend — drive data lives in the API's own DB/storage, served straight from
+``AgentDriveService``. Download hands the browser an **external** signed URL
+(the inner manifest hands agents internal ones — the two must never mix).
+"""
+
+from __future__ import annotations
+
+from flask_restx import Resource
+from pydantic import BaseModel, Field
+
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_response_schema_models,
+)
+from controllers.console import console_ns
+from controllers.console.app.wraps import get_app_model
+from controllers.console.wraps import account_initialization_required, setup_required
+from fields.base import ResponseModel
+from libs.login import login_required
+from models.model import App, AppMode
+from services.agent.composer_service import AgentComposerService
+from services.agent_drive_service import AgentDriveError, AgentDriveService
+
+
+class AgentDriveListQuery(BaseModel):
+    prefix: str = Field(default="", description="Key prefix filter: '<slug>/' for one skill, 'files/' for files")
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+class AgentDriveFileQuery(BaseModel):
+    key: str = Field(min_length=1, description="Drive key, e.g. tender-analyzer/SKILL.md")
+    node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
+
+
+class AgentDriveItemResponse(ResponseModel):
+    key: str
+    size: int | None = None
+    mime_type: str | None = None
+    hash: str | None = None
+    file_kind: str
+    created_at: int | None = None
+
+
+class AgentDriveListResponse(ResponseModel):
+    items: list[AgentDriveItemResponse] = Field(default_factory=list)
+
+
+class AgentDrivePreviewResponse(ResponseModel):
+    key: str
+    size: int | None = None
+    truncated: bool
+    binary: bool
+    text: str | None = None
+
+
+class AgentDriveDownloadResponse(ResponseModel):
+    url: str
+
+
+register_response_schema_models(
+    console_ns, AgentDriveListResponse, AgentDrivePreviewResponse, AgentDriveDownloadResponse
+)
+
+
+def _resolve_agent_id(app_model: App, node_id: str | None) -> str | None:
+    """Agent identity for the drive: app-bound agent, or the workflow node binding."""
+    if node_id:
+        return AgentComposerService.resolve_workflow_node_agent_id(
+            tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
+        )
+    return app_model.bound_agent_id
+
+
+def _agent_not_bound() -> tuple[dict[str, object], int]:
+    return {"code": "agent_not_bound", "message": "no agent is bound for this app/node"}, 400
+
+
+def _handle(exc: AgentDriveError) -> tuple[dict[str, object], int]:
+    return {"code": exc.code, "message": exc.message}, exc.status_code
+
+
+_APP_MODES = [AppMode.AGENT, AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/files")
+class AgentDriveListApi(Resource):
+    @console_ns.doc("list_agent_drive_files")
+    @console_ns.doc(description="List agent drive entries (read-only inspector; one endpoint for both tabs)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveListQuery)})
+    @console_ns.response(200, "Drive entries", console_ns.models[AgentDriveListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_APP_MODES)
+    def get(self, app_model: App):
+        query = query_params_from_request(AgentDriveListQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            items = AgentDriveService().manifest(tenant_id=app_model.tenant_id, agent_id=agent_id, prefix=query.prefix)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        # the inner manifest exposes file_id for agent-side pulls; the console
+        # inspector is a pure read surface and does not need value pointers
+        return {"items": [{k: v for k, v in item.items() if k != "file_id"} for item in items]}
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/files/preview")
+class AgentDrivePreviewApi(Resource):
+    @console_ns.doc("preview_agent_drive_file")
+    @console_ns.doc(description="Truncated text preview of one drive value (binary-safe; SKILL.md is the main case)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveFileQuery)})
+    @console_ns.response(200, "Preview", console_ns.models[AgentDrivePreviewResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_APP_MODES)
+    def get(self, app_model: App):
+        query = query_params_from_request(AgentDriveFileQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            return AgentDriveService().preview(tenant_id=app_model.tenant_id, agent_id=agent_id, key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/drive/files/download")
+class AgentDriveDownloadApi(Resource):
+    @console_ns.doc("download_agent_drive_file")
+    @console_ns.doc(description="Time-limited external signed URL for one drive value (no streaming proxy)")
+    @console_ns.doc(params={"app_id": "Application ID", **query_params_from_model(AgentDriveFileQuery)})
+    @console_ns.response(200, "Signed URL", console_ns.models[AgentDriveDownloadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_APP_MODES)
+    def get(self, app_model: App):
+        query = query_params_from_request(AgentDriveFileQuery)
+        agent_id = _resolve_agent_id(app_model, query.node_id)
+        if not agent_id:
+            return _agent_not_bound()
+        try:
+            url = AgentDriveService().download_url(tenant_id=app_model.tenant_id, agent_id=agent_id, key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"url": url}
+
+
+__all__ = [
+    "AgentDriveDownloadApi",
+    "AgentDriveListApi",
+    "AgentDrivePreviewApi",
+]

api/controllers/console/app/annotation.py

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

api/controllers/console/app/app.py

@@ -1,7 +1,6 @@
 import logging
 import re
 import uuid
-from collections.abc import Sequence
 from datetime import datetime
 from typing import Any, Literal, cast
 
@@ -42,12 +41,12 @@ from core.trigger.constants import TRIGGER_NODE_TYPES
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from graphon.enums import WorkflowExecutionStatus
-from libs.helper import build_icon_url, dump_response, to_timestamp
+from libs.helper import build_icon_url, to_timestamp
 from libs.login import login_required
 from models import Account, App, DatasetPermissionEnum, Workflow
 from models.model import IconType
 from services.app_dsl_service import AppDslService
-from services.app_service import AppListParams, AppListSortBy, AppService, CreateAppParams, StarredAppListParams
+from services.app_service import AppListParams, AppService, CreateAppParams
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import ImportMode, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
@@ -74,14 +73,10 @@ _CREATOR_IDS_BRACKET_PATTERN = re.compile(r"^creator_ids\[(\d+)\]$")
 AppListMode = Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"]
 
 
-class AppListBaseQuery(BaseModel):
+class AppListQuery(BaseModel):
     page: int = Field(default=1, ge=1, le=99999, description="Page number (1-99999)")
     limit: int = Field(default=20, ge=1, le=100, description="Page size (1-100)")
     mode: AppListMode = Field(default=cast(AppListMode, "all"), description="App mode filter")
-    sort_by: AppListSortBy = Field(
-        default="last_modified",
-        description="Sort apps by last modified, recently created, or earliest created",
-    )
     name: str | None = Field(default=None, description="Filter by app name")
     tag_ids: list[str] | None = Field(default=None, description="Filter by tag IDs")
     creator_ids: list[str] | None = Field(default=None, description="Filter by creator account IDs")
@@ -124,14 +119,6 @@ class AppListBaseQuery(BaseModel):
             raise ValueError("Invalid UUID format in creator_ids.") from exc
 
 
-class AppListQuery(AppListBaseQuery):
-    pass
-
-
-class StarredAppListQuery(AppListBaseQuery):
-    pass
-
-
 def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str, str | list[str]]:
     normalized: dict[str, str | list[str]] = {}
     indexed_tag_ids: list[tuple[int, str]] = []
@@ -224,6 +211,11 @@ class AppTracePayload(BaseModel):
         return value
 
 
+class AppTraceResponse(ResponseModel):
+    enabled: bool
+    tracing_provider: str | None = None
+
+
 type JSONValue = Any
 
 
@@ -395,7 +387,6 @@ class AppPartial(ResponseModel):
     create_user_name: str | None = None
     author_name: str | None = None
     has_draft_trigger: bool | None = None
-    is_starred: bool = False
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -465,54 +456,12 @@ class AppExportResponse(ResponseModel):
     data: str
 
 
-def _enrich_app_list_items(session: Session, *, apps: Sequence[App], tenant_id: str) -> None:
-    if FeatureService.get_system_features().webapp_auth.enabled:
-        app_ids = [str(app.id) for app in apps]
-        res = EnterpriseService.WebAppAuth.batch_get_app_access_mode_by_id(app_ids=app_ids)
-        if len(res) != len(app_ids):
-            raise BadRequest("Invalid app id in webapp auth")
-
-        for app in apps:
-            if str(app.id) in res:
-                app.access_mode = res[str(app.id)].access_mode
-
-    workflow_capable_app_ids = [str(app.id) for app in apps if app.mode in {"workflow", "advanced-chat"}]
-    draft_trigger_app_ids: set[str] = set()
-    if workflow_capable_app_ids:
-        draft_workflows = (
-            session.execute(
-                select(Workflow).where(
-                    Workflow.version == Workflow.VERSION_DRAFT,
-                    Workflow.app_id.in_(workflow_capable_app_ids),
-                    Workflow.tenant_id == tenant_id,
-                )
-            )
-            .scalars()
-            .all()
-        )
-        trigger_node_types = TRIGGER_NODE_TYPES
-        for workflow in draft_workflows:
-            node_id = None
-            try:
-                for node_id, node_data in workflow.walk_nodes():
-                    if node_data.get("type") in trigger_node_types:
-                        draft_trigger_app_ids.add(str(workflow.app_id))
-                        break
-            except Exception:
-                _logger.exception("error while walking nodes, workflow_id=%s, node_id=%s", workflow.id, node_id)
-                continue
-
-    for app in apps:
-        app.has_draft_trigger = str(app.id) in draft_trigger_app_ids
-
-
 register_enum_models(console_ns, RetrievalMethod, WorkflowExecutionStatus, DatasetPermissionEnum)
-register_response_schema_models(console_ns, RedirectUrlResponse, SimpleResultResponse)
+register_response_schema_models(console_ns, AppTraceResponse, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
     AppListQuery,
-    StarredAppListQuery,
     CreateAppPayload,
     UpdateAppPayload,
     CopyAppPayload,
@@ -572,7 +521,6 @@ class AppListApi(Resource):
             page=args.page,
             limit=args.limit,
             mode=args.mode,
-            sort_by=args.sort_by,
             name=args.name,
             tag_ids=args.tag_ids,
             creator_ids=args.creator_ids,
@@ -586,7 +534,46 @@ class AppListApi(Resource):
             empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
             return empty.model_dump(mode="json"), 200
 
-        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
+        if FeatureService.get_system_features().webapp_auth.enabled:
+            app_ids = [str(app.id) for app in app_pagination.items]
+            res = EnterpriseService.WebAppAuth.batch_get_app_access_mode_by_id(app_ids=app_ids)
+            if len(res) != len(app_ids):
+                raise BadRequest("Invalid app id in webapp auth")
+
+            for app in app_pagination.items:
+                if str(app.id) in res:
+                    app.access_mode = res[str(app.id)].access_mode
+
+        workflow_capable_app_ids = [
+            str(app.id) for app in app_pagination.items if app.mode in {"workflow", "advanced-chat"}
+        ]
+        draft_trigger_app_ids: set[str] = set()
+        if workflow_capable_app_ids:
+            draft_workflows = (
+                session.execute(
+                    select(Workflow).where(
+                        Workflow.version == Workflow.VERSION_DRAFT,
+                        Workflow.app_id.in_(workflow_capable_app_ids),
+                        Workflow.tenant_id == current_tenant_id,
+                    )
+                )
+                .scalars()
+                .all()
+            )
+            trigger_node_types = TRIGGER_NODE_TYPES
+            for workflow in draft_workflows:
+                node_id = None
+                try:
+                    for node_id, node_data in workflow.walk_nodes():
+                        if node_data.get("type") in trigger_node_types:
+                            draft_trigger_app_ids.add(str(workflow.app_id))
+                            break
+                except Exception:
+                    _logger.exception("error while walking nodes, workflow_id=%s, node_id=%s", workflow.id, node_id)
+                    continue
+
+        for app in app_pagination.items:
+            app.has_draft_trigger = str(app.id) in draft_trigger_app_ids
 
         pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
         return pagination_model.model_dump(mode="json"), 200
@@ -594,7 +581,7 @@ class AppListApi(Resource):
     @console_ns.doc("create_app")
     @console_ns.doc(description="Create a new application")
     @console_ns.expect(console_ns.models[CreateAppPayload.__name__])
-    @console_ns.response(201, "App created successfully", console_ns.models[AppDetail.__name__])
+    @console_ns.response(201, "App created successfully", console_ns.models[AppDetailWithSite.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(400, "Invalid request parameters")
     @setup_required
@@ -618,82 +605,10 @@ class AppListApi(Resource):
 
         app_service = AppService()
         app = app_service.create_app(current_tenant_id, params, current_user)
-        app_detail = AppDetail.model_validate(app, from_attributes=True)
+        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True)
         return app_detail.model_dump(mode="json"), 201
 
 
-@console_ns.route("/apps/starred")
-class StarredAppListApi(Resource):
-    @console_ns.doc("list_starred_apps")
-    @console_ns.doc(description="Get applications starred by the current account")
-    @console_ns.doc(params=query_params_from_model(StarredAppListQuery))
-    @console_ns.response(200, "Success", console_ns.models[AppPagination.__name__])
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @enterprise_license_required
-    @with_session(write=False)
-    @with_current_user_id
-    @with_current_tenant_id
-    def get(self, current_tenant_id: str, current_user_id: str, session: Session):
-        args = StarredAppListQuery.model_validate(_normalize_app_list_query_args(request.args))
-        params = StarredAppListParams(
-            page=args.page,
-            limit=args.limit,
-            mode=args.mode,
-            sort_by=args.sort_by,
-            name=args.name,
-            tag_ids=args.tag_ids,
-            creator_ids=args.creator_ids,
-            is_created_by_me=args.is_created_by_me,
-        )
-
-        app_pagination = AppService().get_paginate_starred_apps(current_user_id, current_tenant_id, params)
-        if not app_pagination:
-            empty = AppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
-            return empty.model_dump(mode="json"), 200
-
-        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
-
-        pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
-        return pagination_model.model_dump(mode="json"), 200
-
-
-@console_ns.route("/apps/<uuid:app_id>/star")
-class AppStarApi(Resource):
-    @console_ns.doc("star_app")
-    @console_ns.doc(description="Star an application for the current account")
-    @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    @console_ns.response(404, "App not found")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @enterprise_license_required
-    @with_current_user_id
-    @with_session
-    @get_app_model(mode=None)
-    def post(self, session: Session, current_user_id: str, app_model: App):
-        AppService.star_app(session, app=app_model, account_id=current_user_id)
-        return dump_response(SimpleResultResponse, {"result": "success"})
-
-    @console_ns.doc("unstar_app")
-    @console_ns.doc(description="Remove the current account's star from an application")
-    @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Success", console_ns.models[SimpleResultResponse.__name__])
-    @console_ns.response(404, "App not found")
-    @setup_required
-    @login_required
-    @account_initialization_required
-    @enterprise_license_required
-    @with_current_user_id
-    @with_session
-    @get_app_model(mode=None)
-    def delete(self, session: Session, current_user_id: str, app_model: App):
-        AppService.unstar_app(session, app=app_model, account_id=current_user_id)
-        return dump_response(SimpleResultResponse, {"result": "success"})
-
-
 @console_ns.route("/apps/<uuid:app_id>")
 class AppApi(Resource):
     @console_ns.doc("get_app_detail")
@@ -832,7 +747,7 @@ class AppExportApi(Resource):
     @console_ns.doc("export_app")
     @console_ns.doc(description="Export application configuration as DSL")
     @console_ns.doc(params={"app_id": "Application ID to export"})
-    @console_ns.expect(console_ns.models[AppExportQuery.__name__])
+    @console_ns.doc(params=query_params_from_model(AppExportQuery))
     @console_ns.response(200, "App exported successfully", console_ns.models[AppExportResponse.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @get_app_model
@@ -907,7 +822,7 @@ class AppIconApi(Resource):
     @console_ns.doc(description="Update application icon")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AppIconPayload.__name__])
-    @console_ns.response(200, "Icon updated successfully")
+    @console_ns.response(200, "Icon updated successfully", console_ns.models[AppDetail.__name__])
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required
@@ -977,7 +892,11 @@ class AppTraceApi(Resource):
     @console_ns.doc("get_app_trace")
     @console_ns.doc(description="Get app tracing configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Trace configuration retrieved successfully")
+    @console_ns.response(
+        200,
+        "Trace configuration retrieved successfully",
+        console_ns.models[AppTraceResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/audio.py

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

api/controllers/console/app/completion.py

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

api/controllers/console/app/conversation.py

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

api/controllers/console/app/conversation_variables.py

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

api/controllers/console/app/generator.py

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

api/controllers/console/app/mcp_server.py

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

api/controllers/console/app/message.py

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