[autofix.ci] apply automated fixes

Updates the requirements on [bleach](https://github.com/mozilla/bleach), [gevent](https://github.com/gevent/gevent), [python-socketio](https://github.com/miguelgrinberg/python-socketio), [aliyun-log-python-sdk](https://github.com/aliyun/aliyun-log-python-sdk), [resend](https://github.com/resendlabs/resend-python), [json-repair](https://github.com/mangiucugna/json_repair), [tenacity](https://github.com/jd/tenacity), [typer](https://github.com/fastapi/typer), [fastapi](https://github.com/fastapi/fastapi), [jsonschema](https://github.com/python-jsonschema/jsonschema), [jwcrypto](https://github.com/latchset/jwcrypto), shell-session-manager, [uvicorn[standard]](https://github.com/Kludex/uvicorn), [coverage[toml]](https://github.com/coveragepy/coveragepy), [mkdocs-glightbox](https://github.com/blueswen/mkdocs-glightbox), [mkdocs-material](https://github.com/squidfunk/mkdocs-material) and [mkdocstrings-python](https://github.com/mkdocstrings/python) to permit the latest version.

Updates `bleach` from 6.3.0 to 6.4.0
- [Changelog](https://github.com/mozilla/bleach/blob/main/CHANGES)
- [Commits](https://github.com/mozilla/bleach/compare/v6.3.0...v6.4.0)

Updates `gevent` from 26.4.0 to 26.5.0
- [Release notes](https://github.com/gevent/gevent/releases)
- [Changelog](https://github.com/gevent/gevent/blob/master/docs/changelog_pre.rst)
- [Commits](https://github.com/gevent/gevent/compare/26.4.0...26.5.0)

Updates `python-socketio` from 5.16.1 to 5.16.3
- [Release notes](https://github.com/miguelgrinberg/python-socketio/releases)
- [Changelog](https://github.com/miguelgrinberg/python-socketio/blob/main/CHANGES.md)
- [Commits](https://github.com/miguelgrinberg/python-socketio/compare/v5.16.1...v5.16.3)

Updates `aliyun-log-python-sdk` from 0.9.44 to 0.9.47
- [Release notes](https://github.com/aliyun/aliyun-log-python-sdk/releases)
- [Changelog](https://github.com/aliyun/aliyun-log-python-sdk/blob/master/HISTORY.md)
- [Commits](https://github.com/aliyun/aliyun-log-python-sdk/commits)

Updates `resend` from 2.27.0 to 2.32.2
- [Release notes](https://github.com/resendlabs/resend-python/releases)
- [Commits](https://github.com/resendlabs/resend-python/compare/v2.27.0...v2.32.2)

Updates `json-repair` from 0.59.4 to 0.61.0
- [Release notes](https://github.com/mangiucugna/json_repair/releases)
- [Commits](https://github.com/mangiucugna/json_repair/compare/v0.59.4...v0.61.0)

Updates `tenacity` from 8.5.0 to 9.1.4
- [Release notes](https://github.com/jd/tenacity/releases)
- [Commits](https://github.com/jd/tenacity/compare/8.5.0...9.1.4)

Updates `typer` from 0.16.1 to 0.26.7
- [Release notes](https://github.com/fastapi/typer/releases)
- [Changelog](https://github.com/fastapi/typer/blob/master/docs/release-notes.md)
- [Commits](https://github.com/fastapi/typer/compare/0.16.1...0.26.7)

Updates `fastapi` from 0.136.0 to 0.138.0
- [Release notes](https://github.com/fastapi/fastapi/releases)
- [Commits](https://github.com/fastapi/fastapi/compare/0.136.0...0.138.0)

Updates `jsonschema` from 4.23.0 to 4.26.0
- [Release notes](https://github.com/python-jsonschema/jsonschema/releases)
- [Changelog](https://github.com/python-jsonschema/jsonschema/blob/main/CHANGELOG.rst)
- [Commits](https://github.com/python-jsonschema/jsonschema/compare/v4.23.0...v4.26.0)

Updates `jwcrypto` to 1.5.7
- [Release notes](https://github.com/latchset/jwcrypto/releases)
- [Commits](https://github.com/latchset/jwcrypto/compare/v1.5.6...v1.5.7)

Updates `shell-session-manager` from 2.2.0 to 2.2.1

Updates `uvicorn[standard]` from 0.46.0 to 0.49.0
- [Release notes](https://github.com/Kludex/uvicorn/releases)
- [Changelog](https://github.com/Kludex/uvicorn/blob/main/docs/release-notes.md)
- [Commits](https://github.com/Kludex/uvicorn/compare/0.46.0...0.49.0)

Updates `coverage[toml]` to 7.14.2
- [Release notes](https://github.com/coveragepy/coveragepy/releases)
- [Changelog](https://github.com/coveragepy/coveragepy/blob/main/CHANGES.rst)
- [Commits](https://github.com/coveragepy/coveragepy/compare/7.10.7...7.14.2)

Updates `mkdocs-glightbox` to 0.5.2
- [Release notes](https://github.com/blueswen/mkdocs-glightbox/releases)
- [Changelog](https://github.com/blueswen/mkdocs-glightbox/blob/main/CHANGELOG)
- [Commits](https://github.com/blueswen/mkdocs-glightbox/compare/v0.4.0...v0.5.2)

Updates `mkdocs-material` to 9.7.6
- [Release notes](https://github.com/squidfunk/mkdocs-material/releases)
- [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG)
- [Commits](https://github.com/squidfunk/mkdocs-material/compare/9.7.0...9.7.6)

Updates `mkdocstrings-python` to 2.0.5
- [Release notes](https://github.com/mkdocstrings/python/releases)
- [Changelog](https://github.com/mkdocstrings/python/blob/main/CHANGELOG.md)
- [Commits](https://github.com/mkdocstrings/python/compare/2.0.0...2.0.5)

---
updated-dependencies:
- dependency-name: bleach
  dependency-version: 6.4.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: gevent
  dependency-version: 26.5.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: python-socketio
  dependency-version: 5.16.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: python-packages
- dependency-name: aliyun-log-python-sdk
  dependency-version: 0.9.47
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: python-packages
- dependency-name: resend
  dependency-version: 2.32.2
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: json-repair
  dependency-version: 0.61.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: tenacity
  dependency-version: 9.1.4
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: python-packages
- dependency-name: typer
  dependency-version: 0.26.7
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: fastapi
  dependency-version: 0.138.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: jsonschema
  dependency-version: 4.26.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: jwcrypto
  dependency-version: 1.5.7
  dependency-type: direct:production
  dependency-group: python-packages
- dependency-name: shell-session-manager
  dependency-version: 2.2.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: python-packages
- dependency-name: uvicorn[standard]
  dependency-version: 0.49.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: python-packages
- dependency-name: coverage[toml]
  dependency-version: 7.14.2
  dependency-type: direct:development
  dependency-group: python-packages
- dependency-name: mkdocs-glightbox
  dependency-version: 0.5.2
  dependency-type: direct:development
  dependency-group: python-packages
- dependency-name: mkdocs-material
  dependency-version: 9.7.6
  dependency-type: direct:development
  dependency-group: python-packages
- dependency-name: mkdocstrings-python
  dependency-version: 2.0.5
  dependency-type: direct:development
  dependency-group: python-packages
...

Signed-off-by: dependabot[bot] <support@github.com>

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

@@ -28,7 +28,6 @@ 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.
 
@@ -44,7 +43,6 @@ Notes when using this skill:
 ### 1. Security Review
 
 Check for:
-
 - SQL injection vulnerabilities
 - Server-Side Request Forgery (SSRF)
 - Command injection
@@ -56,7 +54,6 @@ Check for:
 ### 2. Performance Review
 
 Check for:
-
 - N+1 queries
 - Missing database indexes
 - Memory leaks
@@ -66,7 +63,6 @@ Check for:
 ### 3. Code Quality Review
 
 Check for:
-
 - Code forward compatibility
 - Code duplication (DRY violations)
 - Functions doing too much (SRP violations)
@@ -79,7 +75,6 @@ Check for:
 ### 4. Testing Review
 
 Check for:
-
 - Missing test coverage for new code
 - Tests that don't test behavior
 - Flaky test patterns
@@ -113,7 +108,6 @@ FilePath: <path> line <line>
 2. <code example> (optional, omit if not applicable)
 
 ---
-
 ... (repeat for each critical issue) ...
 
 Found <Y> suggestions for improvement:
@@ -135,13 +129,11 @@ 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>
@@ -156,7 +148,6 @@ FilePath: <path> line <line>
 - <minor suggestions>
 
 ---
-
 ... (repeat for each nits) ...
 
 ## ✅ What's Good
@@ -173,6 +164,5 @@ FilePath: <path> line <line>
 
 ```markdown
 ## Code Review Summary
-
 ✅ No issues found.
-```
+```

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

@@ -1,13 +1,11 @@
 # 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.
@@ -35,14 +33,12 @@
     ```
 
 ### 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
@@ -50,9 +46,7 @@
     def can_publish() -> bool:
         return request_context.current_user.is_admin
     ```
-
   - Good:
-
     ```python
     # core/policy/publish_policy.py
     def can_publish(role: str) -> bool:
@@ -63,7 +57,6 @@
     ```
 
 ### 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.
@@ -72,7 +65,6 @@
   - 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
@@ -84,9 +76,7 @@
             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:
@@ -98,4 +88,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,14 +1,12 @@
 # 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.
@@ -18,7 +16,6 @@
   - 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"
@@ -29,9 +26,7 @@
                 app = session.execute(select(App).where(App.id == self.app_id)).scalar_one()
                 return app.name
     ```
-
   - Good:
-
     ```python
     class Conversation(TypeBase):
         __tablename__ = "conversations"
@@ -45,7 +40,6 @@
     ```
 
 ### 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.
@@ -55,7 +49,6 @@
   - 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
 
@@ -64,9 +57,7 @@
         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
 
@@ -78,7 +69,6 @@
     ```
 
 ### 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.
@@ -103,7 +93,6 @@
     ```
 
 ### 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.
@@ -112,7 +101,6 @@
   - 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
@@ -121,9 +109,7 @@
         __tablename__ = "tool_configs"
         config: Mapped[dict] = mapped_column(JSONB, nullable=False)
     ```
-
   - Good:
-
     ```python
     from sqlalchemy.orm import Mapped
 
@@ -135,7 +121,6 @@
     ```
 
 ### 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.
@@ -157,7 +142,6 @@
         )
     ```
   - Good:
-
     ```python
     def _is_pg(conn) -> bool:
         return conn.dialect.name == "postgresql"

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

@@ -1,19 +1,17 @@
 # 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:
@@ -28,7 +26,6 @@
             self.session.commit()
     ```
   - Good:
-
     ```python
     # Case A: Existing repository must be reused for all table operations.
     class AppService:
@@ -40,7 +37,6 @@
     # 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.
@@ -50,7 +46,6 @@
             # 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,14 +1,12 @@
 # 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.
@@ -18,7 +16,6 @@
   - 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:
@@ -31,9 +28,7 @@
         run.status = "cancelled"
         call_external_api()
     ```
-
   - Good:
-
     ```python
     # Option 1: explicit commit.
     with Session(db.engine, expire_on_commit=False) as session:
@@ -51,7 +46,6 @@
     ```
 
 ### 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.
@@ -72,7 +66,6 @@
     ```
 
 ### 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.
@@ -95,7 +88,6 @@
     ```
 
 ### 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.
@@ -112,7 +104,6 @@
     session.commit()  # silently overwrites concurrent updates
     ```
   - Good:
-
     ```python
     # 1) Optimistic lock (low contention, retry on conflict)
     result = session.execute(
@@ -145,4 +136,4 @@
     ).scalar_one()
     run.status = "cancelled"
     session.commit()
-    ```
+    ```

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

@@ -1,449 +0,0 @@
----
-name: component-refactoring
-description: Refactor high-complexity React components in Dify frontend. Use when `pnpm analyze-component --json` shows complexity > 50 or lineCount > 300, when the user asks for code splitting, hook extraction, or complexity reduction, or when `pnpm analyze-component` warns to refactor before testing; avoid for simple/well-structured components, third-party wrappers, or when the user explicitly wants testing without refactoring.
----
-
-# Dify Component Refactoring Skill
-
-Refactor high-complexity React components in the Dify frontend codebase with the patterns and workflow below.
-
-> **Complexity Threshold**: Components with complexity > 50 (measured by `pnpm analyze-component`) should be refactored before testing.
-
-## Quick Reference
-
-### Commands (run from `web/`)
-
-Use paths relative to `web/` (e.g., `app/components/...`).
-Use `refactor-component` for refactoring prompts and `analyze-component` for testing prompts and metrics.
-
-```bash
-cd web
-
-# Generate refactoring prompt
-pnpm refactor-component <path>
-
-# Output refactoring analysis as JSON
-pnpm refactor-component <path> --json
-
-# Generate testing prompt (after refactoring)
-pnpm analyze-component <path>
-
-# Output testing analysis as JSON
-pnpm analyze-component <path> --json
-```
-
-### Complexity Analysis
-
-```bash
-# Analyze component complexity
-pnpm analyze-component <path> --json
-
-# Key metrics to check:
-# - complexity: normalized score 0-100 (target < 50)
-# - maxComplexity: highest single function complexity
-# - lineCount: total lines (target < 300)
-```
-
-### 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**           |
-
-## Core Refactoring Patterns
-
-### Pattern 1: Extract Custom Hooks
-
-**When**: Component has complex state management, multiple `useState`/`useEffect`, or business logic mixed with UI.
-
-**Dify Convention**: Place hooks in a `hooks/` subdirectory or alongside the component as `use-<feature>.ts`.
-
-```typescript
-// ❌ Before: Complex state logic in component
-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>
-}
-
-// ✅ After: Extract to custom hook
-// hooks/use-model-config.ts
-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 }
-}
-
-// Component becomes cleaner
-function Configuration() {
-  const { modelConfig, setModelConfig } = useModelConfig(appId)
-  return <div>...</div>
-}
-```
-
-**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`
-
-### Pattern 2: Extract Sub-Components
-
-**When**: Single component has multiple UI sections, conditional rendering blocks, or repeated patterns.
-
-**Dify Convention**: Place sub-components in subdirectories or as separate files in the same directory.
-
-```typescript
-// ❌ Before: Monolithic JSX with multiple sections
-const AppInfo = () => {
-  return (
-    <div>
-      {/* 100 lines of header UI */}
-      {/* 100 lines of operations UI */}
-      {/* 100 lines of modals */}
-    </div>
-  )
-}
-
-// ✅ After: Split into focused components
-// app-info/
-//   ├── index.tsx           (orchestration only)
-//   ├── app-header.tsx      (header UI)
-//   ├── app-operations.tsx  (operations UI)
-//   └── app-modals.tsx      (modal management)
-
-const AppInfo = () => {
-  const { showModal, setShowModal } = useAppInfoModals()
-
-  return (
-    <div>
-      <AppHeader appDetail={appDetail} />
-      <AppOperations onAction={handleAction} />
-      <AppModals show={showModal} onClose={() => setShowModal(null)} />
-    </div>
-  )
-}
-```
-
-**Dify Examples**:
-
-- `web/app/components/app/configuration/` directory structure
-- `web/app/components/workflow/nodes/` per-node organization
-
-### Pattern 3: Simplify Conditional Logic
-
-**When**: Deep nesting (> 3 levels), complex ternaries, or multiple `if/else` chains.
-
-```typescript
-// ❌ Before: Deeply nested conditionals
-const Template = useMemo(() => {
-  if (appDetail?.mode === AppModeEnum.CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateChatZh />
-      case LanguagesSupported[7]:
-        return <TemplateChatJa />
-      default:
-        return <TemplateChatEn />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
-    // Another 15 lines...
-  }
-  // More conditions...
-}, [appDetail, locale])
-
-// ✅ After: Use lookup tables + early returns
-const TEMPLATE_MAP = {
-  [AppModeEnum.CHAT]: {
-    [LanguagesSupported[1]]: TemplateChatZh,
-    [LanguagesSupported[7]]: TemplateChatJa,
-    default: TemplateChatEn,
-  },
-  [AppModeEnum.ADVANCED_CHAT]: {
-    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
-    // ...
-  },
-}
-
-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])
-```
-
-### Pattern 4: Extract API/Data Logic
-
-**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`
-- `web/service/knowledge/use-document.ts`
-
-### Pattern 5: Extract Modal/Dialog Management
-
-**When**: Component manages multiple modals with complex open/close states.
-
-**Dify Convention**: Modals should be extracted with their state management.
-
-```typescript
-// ❌ Before: Multiple modal states in component
-const AppInfo = () => {
-  const [showEditModal, setShowEditModal] = useState(false)
-  const [showDuplicateModal, setShowDuplicateModal] = useState(false)
-  const [showConfirmDelete, setShowConfirmDelete] = useState(false)
-  const [showSwitchModal, setShowSwitchModal] = useState(false)
-  const [showImportDSLModal, setShowImportDSLModal] = useState(false)
-  // 5+ more modal states...
-}
-
-// ✅ After: Extract to modal management hook
-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,
-    closeModal,
-    isOpen: (type: ModalType) => activeModal === type,
-  }
-}
-```
-
-### Pattern 6: Extract Form Logic
-
-**When**: Complex form validation, submission handling, or field transformation.
-
-**Dify Convention**: Use `@tanstack/react-form` patterns from `web/app/components/base/form/`.
-
-```typescript
-// ✅ Use existing form infrastructure
-import { useAppForm } from '@/app/components/base/form'
-
-const ConfigForm = () => {
-  const form = useAppForm({
-    defaultValues: { name: '', description: '' },
-    onSubmit: handleSubmit,
-  })
-
-  return <form.Provider>...</form.Provider>
-}
-```
-
-## Dify-Specific Refactoring Guidelines
-
-### 1. Context Provider Extraction
-
-**When**: Component provides complex context values with multiple states.
-
-```typescript
-// ❌ Before: Large context value object
-const value = {
-  appId, isAPIKeySet, isTrailFinished, mode, modelModeType,
-  promptMode, isAdvancedMode, isAgent, isOpenAI, isFunctionCall,
-  // 50+ more properties...
-}
-return <ConfigContext.Provider value={value}>...</ConfigContext.Provider>
-
-// ✅ After: Split into domain-specific contexts
-<ModelConfigProvider value={modelConfigValue}>
-  <DatasetConfigProvider value={datasetConfigValue}>
-    <UIConfigProvider value={uiConfigValue}>
-      {children}
-    </UIConfigProvider>
-  </DatasetConfigProvider>
-</ModelConfigProvider>
-```
-
-**Dify Reference**: `web/context/` directory structure
-
-### 2. Workflow Node Components
-
-**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
-
-```
-nodes/<node-type>/
-  ├── index.tsx              # Node registration
-  ├── node.tsx               # Node visual component
-  ├── panel.tsx              # Configuration panel
-  ├── use-interactions.ts    # Node-specific hooks
-  └── types.ts               # Type definitions
-```
-
-### 3. Configuration Components
-
-**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
-
-### 4. Tool/Plugin Components
-
-**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
-
-## Refactoring Workflow
-
-### Step 1: Generate Refactoring Prompt
-
-```bash
-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)
-- Provide detailed requirements based on detected patterns
-
-### Step 2: Analyze Details
-
-```bash
-pnpm analyze-component <path> --json
-```
-
-Identify:
-
-- Total complexity score
-- Max function complexity
-- Line count
-- Features detected (state, effects, API, etc.)
-
-### Step 3: Plan
-
-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 |
-
-### Step 4: Execute Incrementally
-
-1. **Extract one piece at a time**
-2. **Run lint, type-check, and tests after each extraction**
-3. **Verify functionality before next step**
-
-```
-For each extraction:
-  ┌────────────────────────────────────────┐
-  │ 1. Extract code                        │
-  │ 2. Run: pnpm lint:fix                  │
-  │ 3. Run: pnpm type-check                │
-  │ 4. Run: pnpm test                      │
-  │ 5. Test functionality manually         │
-  │ 6. PASS? → Next extraction             │
-  │    FAIL? → Fix before continuing       │
-  └────────────────────────────────────────┘
-```
-
-### Step 5: Verify
-
-After refactoring:
-
-```bash
-# Re-run refactor command to verify improvements
-pnpm refactor-component <path>
-
-# If complexity < 25 and lines < 200, you'll see:
-# ✅ COMPONENT IS WELL-STRUCTURED
-
-# For detailed metrics:
-pnpm analyze-component <path> --json
-
-# Target metrics:
-# - complexity < 50
-# - lineCount < 300
-# - maxComplexity < 30
-```
-
-## Common Mistakes to Avoid
-
-### ❌ Over-Engineering
-
-```typescript
-// ❌ Too many tiny hooks
-const useButtonText = () => useState('Click')
-const useButtonDisabled = () => useState(false)
-const useButtonLoading = () => useState(false)
-
-// ✅ Cohesive hook with related state
-const useButtonState = () => {
-  const [text, setText] = useState('Click')
-  const [disabled, setDisabled] = useState(false)
-  const [loading, setLoading] = useState(false)
-  return { text, setText, disabled, setDisabled, loading, setLoading }
-}
-```
-
-### ❌ Breaking Existing Patterns
-
-- Follow existing directory structures
-- Maintain naming conventions
-- Preserve export patterns for compatibility
-
-### ❌ Premature Abstraction
-
-- Only extract when there's clear complexity benefit
-- Don't create abstractions for single-use code
-- Keep refactored code in the same domain area
-
-## References
-
-### Dify Codebase Examples
-
-- **Hook extraction**: `web/app/components/app/configuration/hooks/`
-- **Component splitting**: `web/app/components/app/configuration/`
-- **Service hooks**: `web/service/use-*.ts`
-- **Workflow patterns**: `web/app/components/workflow/hooks/`
-- **Form patterns**: `web/app/components/base/form/`
-
-### Related Skills
-
-- `frontend-testing` - For testing refactored components
-- `web/docs/test.md` - Testing specification

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

@@ -1,496 +0,0 @@
-# Complexity Reduction Patterns
-
-This document provides patterns for reducing cognitive complexity in Dify React components.
-
-## Understanding Complexity
-
-### SonarJS Cognitive Complexity
-
-The `pnpm analyze-component` tool uses SonarJS cognitive complexity metrics:
-
-- **Total Complexity**: Sum of all functions' complexity in the file
-- **Max Complexity**: Highest single function complexity
-
-### 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 1: Replace Conditionals with Lookup Tables
-
-**Before** (complexity: ~15):
-
-```typescript
-const Template = useMemo(() => {
-  if (appDetail?.mode === AppModeEnum.CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateChatZh appDetail={appDetail} />
-      case LanguagesSupported[7]:
-        return <TemplateChatJa appDetail={appDetail} />
-      default:
-        return <TemplateChatEn appDetail={appDetail} />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateAdvancedChatZh appDetail={appDetail} />
-      case LanguagesSupported[7]:
-        return <TemplateAdvancedChatJa appDetail={appDetail} />
-      default:
-        return <TemplateAdvancedChatEn appDetail={appDetail} />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.WORKFLOW) {
-    // Similar pattern...
-  }
-  return null
-}, [appDetail, locale])
-```
-
-**After** (complexity: ~3):
-
-```typescript
-import type { ComponentType } from 'react'
-
-// Define lookup table outside component
-const TEMPLATE_MAP: Record<AppModeEnum, Record<string, ComponentType<TemplateProps>>> = {
-  [AppModeEnum.CHAT]: {
-    [LanguagesSupported[1]]: TemplateChatZh,
-    [LanguagesSupported[7]]: TemplateChatJa,
-    default: TemplateChatEn,
-  },
-  [AppModeEnum.ADVANCED_CHAT]: {
-    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
-    [LanguagesSupported[7]]: TemplateAdvancedChatJa,
-    default: TemplateAdvancedChatEn,
-  },
-  [AppModeEnum.WORKFLOW]: {
-    [LanguagesSupported[1]]: TemplateWorkflowZh,
-    [LanguagesSupported[7]]: TemplateWorkflowJa,
-    default: TemplateWorkflowEn,
-  },
-  // ...
-}
-
-// 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])
-```
-
-## Pattern 2: Use Early Returns
-
-**Before** (complexity: ~10):
-
-```typescript
-const handleSubmit = () => {
-  if (isValid) {
-    if (hasChanges) {
-      if (isConnected) {
-        submitData()
-      } else {
-        showConnectionError()
-      }
-    } else {
-      showNoChangesMessage()
-    }
-  } else {
-    showValidationError()
-  }
-}
-```
-
-**After** (complexity: ~4):
-
-```typescript
-const handleSubmit = () => {
-  if (!isValid) {
-    showValidationError()
-    return
-  }
-
-  if (!hasChanges) {
-    showNoChangesMessage()
-    return
-  }
-
-  if (!isConnected) {
-    showConnectionError()
-    return
-  }
-
-  submitData()
-}
-```
-
-## Pattern 3: Extract Complex Conditions
-
-**Before** (complexity: high):
-
-```typescript
-const canPublish = (() => {
-  if (mode !== AppModeEnum.COMPLETION) {
-    if (!isAdvancedMode) return true
-
-    if (modelModeType === ModelModeType.completion) {
-      if (!hasSetBlockStatus.history || !hasSetBlockStatus.query) return false
-      return true
-    }
-    return true
-  }
-  return !promptEmpty
-})()
-```
-
-**After** (complexity: lower):
-
-```typescript
-// Extract to named functions
-const canPublishInCompletionMode = () => !promptEmpty
-
-const canPublishInChatMode = () => {
-  if (!isAdvancedMode) return true
-  if (modelModeType !== ModelModeType.completion) return true
-  return hasSetBlockStatus.history && hasSetBlockStatus.query
-}
-
-// Clean main logic
-const canPublish =
-  mode === AppModeEnum.COMPLETION ? canPublishInCompletionMode() : canPublishInChatMode()
-```
-
-## Pattern 4: Replace Chained Ternaries
-
-**Before** (complexity: ~5):
-
-```typescript
-const statusText = serverActivated
-  ? t('status.running')
-  : serverPublished
-    ? t('status.inactive')
-    : appUnpublished
-      ? t('status.unpublished')
-      : t('status.notConfigured')
-```
-
-**After** (complexity: ~2):
-
-```typescript
-const getStatusText = () => {
-  if (serverActivated) return t('status.running')
-  if (serverPublished) return t('status.inactive')
-  if (appUnpublished) return t('status.unpublished')
-  return t('status.notConfigured')
-}
-
-const statusText = getStatusText()
-```
-
-Or use lookup:
-
-```typescript
-const STATUS_TEXT_MAP = {
-  running: 'status.running',
-  inactive: 'status.inactive',
-  unpublished: 'status.unpublished',
-  notConfigured: 'status.notConfigured',
-} as const
-
-const getStatusKey = (): keyof typeof STATUS_TEXT_MAP => {
-  if (serverActivated) return 'running'
-  if (serverPublished) return 'inactive'
-  if (appUnpublished) return 'unpublished'
-  return 'notConfigured'
-}
-
-const statusText = t(STATUS_TEXT_MAP[getStatusKey()])
-```
-
-## Pattern 5: Flatten Nested Loops
-
-**Before** (complexity: high):
-
-```typescript
-const processData = (items: Item[]) => {
-  const results: ProcessedItem[] = []
-
-  for (const item of items) {
-    if (item.isValid) {
-      for (const child of item.children) {
-        if (child.isActive) {
-          for (const prop of child.properties) {
-            if (prop.value !== null) {
-              results.push({
-                itemId: item.id,
-                childId: child.id,
-                propValue: prop.value,
-              })
-            }
-          }
-        }
-      }
-    }
-  }
-
-  return results
-}
-```
-
-**After** (complexity: lower):
-
-```typescript
-// Use functional approach
-const processData = (items: Item[]) => {
-  return items
-    .filter((item) => item.isValid)
-    .flatMap((item) =>
-      item.children
-        .filter((child) => child.isActive)
-        .flatMap((child) =>
-          child.properties
-            .filter((prop) => prop.value !== null)
-            .map((prop) => ({
-              itemId: item.id,
-              childId: child.id,
-              propValue: prop.value,
-            })),
-        ),
-    )
-}
-```
-
-## Pattern 6: Extract Event Handler Logic
-
-**Before** (complexity: high in component):
-
-```typescript
-const Component = () => {
-  const handleSelect = (data: DataSet[]) => {
-    if (isEqual(data.map(item => item.id), dataSets.map(item => item.id))) {
-      hideSelectDataSet()
-      return
-    }
-
-    formattingChangedDispatcher()
-    let newDatasets = data
-    if (data.find(item => !item.name)) {
-      const newSelected = produce(data, (draft) => {
-        data.forEach((item, index) => {
-          if (!item.name) {
-            const newItem = dataSets.find(i => i.id === item.id)
-            if (newItem)
-              draft[index] = newItem
-          }
-        })
-      })
-      setDataSets(newSelected)
-      newDatasets = newSelected
-    }
-    else {
-      setDataSets(data)
-    }
-    hideSelectDataSet()
-
-    // 40 more lines of logic...
-  }
-
-  return <div>...</div>
-}
-```
-
-**After** (complexity: lower):
-
-```typescript
-// Extract to hook or utility
-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) {
-          const existing = dataSets.find(i => i.id === item.id)
-          if (existing) draft[index] = existing
-        }
-      })
-    })
-  }
-
-  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>
-}
-```
-
-## Pattern 7: Reduce Boolean Logic Complexity
-
-**Before** (complexity: ~8):
-
-```typescript
-const toggleDisabled =
-  hasInsufficientPermissions ||
-  appUnpublished ||
-  missingStartNode ||
-  triggerModeDisabled ||
-  (isAdvancedApp && !currentWorkflow?.graph) ||
-  (isBasicApp && !basicAppConfig.updated_at)
-```
-
-**After** (complexity: ~3):
-
-```typescript
-// Extract meaningful boolean functions
-const isAppReady = () => {
-  if (isAdvancedApp) return !!currentWorkflow?.graph
-  return !!basicAppConfig.updated_at
-}
-
-const hasRequiredPermissions = () => {
-  return isCurrentWorkspaceEditor && !hasInsufficientPermissions
-}
-
-const canToggle = () => {
-  if (!hasRequiredPermissions()) return false
-  if (!isAppReady()) return false
-  if (missingStartNode) return false
-  if (triggerModeDisabled) return false
-  return true
-}
-
-const toggleDisabled = !canToggle()
-```
-
-## Pattern 8: Simplify useMemo/useCallback Dependencies
-
-**Before** (complexity: multiple recalculations):
-
-```typescript
-const payload = useMemo(() => {
-  let parameters: Parameter[] = []
-  let outputParameters: OutputParameter[] = []
-
-  if (!published) {
-    parameters = (inputs || []).map((item) => ({
-      name: item.variable,
-      description: '',
-      form: 'llm',
-      required: item.required,
-      type: item.type,
-    }))
-    outputParameters = (outputs || []).map((item) => ({
-      name: item.variable,
-      description: '',
-      type: item.value_type,
-    }))
-  } else if (detail && detail.tool) {
-    parameters = (inputs || []).map((item) => ({
-      // Complex transformation...
-    }))
-    outputParameters = (outputs || []).map((item) => ({
-      // Complex transformation...
-    }))
-  }
-
-  return {
-    icon: detail?.icon || icon,
-    label: detail?.label || name,
-    // ...more fields
-  }
-}, [detail, published, workflowAppId, icon, name, description, inputs, outputs])
-```
-
-**After** (complexity: separated concerns):
-
-```typescript
-// Separate transformations
-const useParameterTransform = (inputs: InputVar[], detail?: ToolDetail, published?: boolean) => {
-  return useMemo(() => {
-    if (!published) {
-      return inputs.map((item) => ({
-        name: item.variable,
-        description: '',
-        form: 'llm',
-        required: item.required,
-        type: item.type,
-      }))
-    }
-
-    if (!detail?.tool) return []
-
-    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',
-    }))
-  }, [inputs, detail, published])
-}
-
-// Component uses hook
-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],
-)
-```
-
-## 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 |

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

@@ -1,477 +0,0 @@
-# Component Splitting Patterns
-
-This document provides detailed guidance on splitting large components into smaller, focused components in Dify.
-
-## When to Split Components
-
-Split a component when you identify:
-
-1. **Multiple UI sections** - Distinct visual areas with minimal coupling that can be composed independently
-1. **Conditional rendering blocks** - Large `{condition && <JSX />}` blocks
-1. **Repeated patterns** - Similar UI structures used multiple times
-1. **300+ lines** - Component exceeds manageable size
-1. **Modal clusters** - Multiple modals rendered in one component
-
-## Splitting Strategies
-
-### Strategy 1: Section-Based Splitting
-
-Identify visual sections and extract each as a component.
-
-```typescript
-// ❌ Before: Monolithic component (500+ lines)
-const ConfigurationPage = () => {
-  return (
-    <div>
-      {/* Header Section - 50 lines */}
-      <div className="header">
-        <h1>{t('configuration.title')}</h1>
-        <div className="actions">
-          {isAdvancedMode && <Badge>Advanced</Badge>}
-          <ModelParameterModal ... />
-          <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 ... />}
-      {showUseGPT4Confirm && <Confirm ... />}
-    </div>
-  )
-}
-
-// ✅ After: Split into focused components
-// configuration/
-//   ├── index.tsx              (orchestration)
-//   ├── configuration-header.tsx
-//   ├── configuration-content.tsx
-//   ├── configuration-debug.tsx
-//   └── configuration-modals.tsx
-
-// configuration-header.tsx
-interface ConfigurationHeaderProps {
-  isAdvancedMode: boolean
-  onPublish: () => void
-}
-
-function ConfigurationHeader({
-  isAdvancedMode,
-  onPublish,
-}: ConfigurationHeaderProps) {
-  const { t } = useTranslation()
-
-  return (
-    <div className="header">
-      <h1>{t('configuration.title')}</h1>
-      <div className="actions">
-        {isAdvancedMode && <Badge>Advanced</Badge>}
-        <ModelParameterModal ... />
-        <AppPublisher onPublish={onPublish} />
-      </div>
-    </div>
-  )
-}
-
-// index.tsx (orchestration only)
-const ConfigurationPage = () => {
-  const { modelConfig, setModelConfig } = useModelConfig()
-  const { activeModal, openModal, closeModal } = useModalState()
-
-  return (
-    <div>
-      <ConfigurationHeader
-        isAdvancedMode={isAdvancedMode}
-        onPublish={handlePublish}
-      />
-      <ConfigurationContent
-        modelConfig={modelConfig}
-        onConfigChange={setModelConfig}
-      />
-      {!isMobile && (
-        <ConfigurationDebug
-          inputs={inputs}
-          onSetting={handleSetting}
-        />
-      )}
-      <ConfigurationModals
-        activeModal={activeModal}
-        onClose={closeModal}
-      />
-    </div>
-  )
-}
-```
-
-### Strategy 2: Conditional Block Extraction
-
-Extract large conditional rendering blocks.
-
-```typescript
-// ❌ Before: Large conditional blocks
-const AppInfo = () => {
-  return (
-    <div>
-      {expand ? (
-        <div className="expanded">
-          {/* 100 lines of expanded view */}
-        </div>
-      ) : (
-        <div className="collapsed">
-          {/* 50 lines of collapsed view */}
-        </div>
-      )}
-    </div>
-  )
-}
-
-// ✅ After: Separate view components
-function AppInfoExpanded({ appDetail, onAction }: AppInfoViewProps) {
-  return (
-    <div className="expanded">
-      {/* Clean, focused expanded view */}
-    </div>
-  )
-}
-
-function AppInfoCollapsed({ appDetail, onAction }: AppInfoViewProps) {
-  return (
-    <div className="collapsed">
-      {/* Clean, focused collapsed view */}
-    </div>
-  )
-}
-
-const AppInfo = () => {
-  return (
-    <div>
-      {expand
-        ? <AppInfoExpanded appDetail={appDetail} onAction={handleAction} />
-        : <AppInfoCollapsed appDetail={appDetail} onAction={handleAction} />
-      }
-    </div>
-  )
-}
-```
-
-### Strategy 3: Modal Extraction
-
-Extract modals with their trigger logic.
-
-```typescript
-// ❌ Before: Multiple modals in one component
-const AppInfo = () => {
-  const [showEdit, setShowEdit] = useState(false)
-  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)} />}
-      {showSwitch && <SwitchModal ... />}
-    </div>
-  )
-}
-
-// ✅ After: Modal manager component
-// app-info-modals.tsx
-type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | null
-
-interface AppInfoModalsProps {
-  appDetail: AppDetail
-  activeModal: ModalType
-  onClose: () => void
-  onSuccess: () => void
-}
-
-function AppInfoModals({
-  appDetail,
-  activeModal,
-  onClose,
-  onSuccess,
-}: AppInfoModalsProps) {
-  const handleEdit = async (data) => { /* logic */ }
-  const handleDuplicate = async (data) => { /* logic */ }
-  const handleDelete = async () => { /* logic */ }
-
-  return (
-    <>
-      {activeModal === 'edit' && (
-        <EditModal
-          appDetail={appDetail}
-          onConfirm={handleEdit}
-          onClose={onClose}
-        />
-      )}
-      {activeModal === 'duplicate' && (
-        <DuplicateModal
-          appDetail={appDetail}
-          onConfirm={handleDuplicate}
-          onClose={onClose}
-        />
-      )}
-      {activeModal === 'delete' && (
-        <DeleteConfirm
-          onConfirm={handleDelete}
-          onClose={onClose}
-        />
-      )}
-      {activeModal === 'switch' && (
-        <SwitchModal
-          appDetail={appDetail}
-          onClose={onClose}
-        />
-      )}
-    </>
-  )
-}
-
-// 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}
-        onClose={closeModal}
-        onSuccess={handleSuccess}
-      />
-    </div>
-  )
-}
-```
-
-### Strategy 4: List Item Extraction
-
-Extract repeated item rendering.
-
-```typescript
-// ❌ Before: Inline item rendering
-const OperationsList = () => {
-  return (
-    <div>
-      {operations.map(op => (
-        <div key={op.id} className="operation-item">
-          <span className="icon">{op.icon}</span>
-          <span className="title">{op.title}</span>
-          <span className="description">{op.description}</span>
-          <button onClick={() => op.onClick()}>
-            {op.actionLabel}
-          </button>
-          {op.badge && <Badge>{op.badge}</Badge>}
-          {/* More complex rendering... */}
-        </div>
-      ))}
-    </div>
-  )
-}
-
-// ✅ After: Extracted item component
-interface OperationItemProps {
-  operation: Operation
-  onAction: (id: string) => void
-}
-
-function OperationItem({ operation, onAction }: OperationItemProps) {
-  return (
-    <div className="operation-item">
-      <span className="icon">{operation.icon}</span>
-      <span className="title">{operation.title}</span>
-      <span className="description">{operation.description}</span>
-      <button onClick={() => onAction(operation.id)}>
-        {operation.actionLabel}
-      </button>
-      {operation.badge && <Badge>{operation.badge}</Badge>}
-    </div>
-  )
-}
-
-const OperationsList = () => {
-  const handleAction = useCallback((id: string) => {
-    const op = operations.find(o => o.id === id)
-    op?.onClick()
-  }, [operations])
-
-  return (
-    <div>
-      {operations.map(op => (
-        <OperationItem
-          key={op.id}
-          operation={op}
-          onAction={handleAction}
-        />
-      ))}
-    </div>
-  )
-}
-```
-
-## Directory Structure Patterns
-
-### Pattern A: Flat Structure (Simple Components)
-
-For components with 2-3 sub-components:
-
-```
-component-name/
-  ├── index.tsx           # Main component
-  ├── sub-component-a.tsx
-  ├── sub-component-b.tsx
-  └── types.ts            # Shared types
-```
-
-### Pattern B: Nested Structure (Complex Components)
-
-For components with many sub-components:
-
-```
-component-name/
-  ├── index.tsx           # Main orchestration
-  ├── types.ts            # Shared types
-  ├── hooks/
-  │   ├── use-feature-a.ts
-  │   └── use-feature-b.ts
-  ├── components/
-  │   ├── header/
-  │   │   └── index.tsx
-  │   ├── content/
-  │   │   └── index.tsx
-  │   └── modals/
-  │       └── index.tsx
-  └── utils/
-      └── helpers.ts
-```
-
-### Pattern C: Feature-Based Structure (Dify Standard)
-
-Following Dify's existing patterns:
-
-```
-configuration/
-  ├── index.tsx           # Main page component
-  ├── base/               # Base/shared components
-  │   ├── feature-panel/
-  │   ├── group-name/
-  │   └── operation-btn/
-  ├── config/             # Config section
-  │   ├── index.tsx
-  │   ├── agent/
-  │   └── automatic/
-  ├── dataset-config/     # Dataset section
-  │   ├── index.tsx
-  │   ├── card-item/
-  │   └── params-config/
-  ├── debug/              # Debug section
-  │   ├── index.tsx
-  │   └── hooks.tsx
-  └── hooks/              # Shared hooks
-      └── use-advanced-prompt-config.ts
-```
-
-## Props Design
-
-### Minimal Props Principle
-
-Pass only what's needed:
-
-```typescript
-// ❌ Bad: Passing entire objects when only some fields needed
-<ConfigHeader appDetail={appDetail} modelConfig={modelConfig} />
-
-// ✅ Good: Destructure to minimum required
-<ConfigHeader
-  appName={appDetail.name}
-  isAdvancedMode={modelConfig.isAdvanced}
-  onPublish={handlePublish}
-/>
-```
-
-### Callback Props Pattern
-
-Use callbacks for child-to-parent communication:
-
-```typescript
-// Parent
-const Parent = () => {
-  const [value, setValue] = useState('')
-
-  return (
-    <Child
-      value={value}
-      onChange={setValue}
-      onSubmit={handleSubmit}
-    />
-  )
-}
-
-// Child
-interface ChildProps {
-  value: string
-  onChange: (value: string) => void
-  onSubmit: () => void
-}
-
-function Child({ value, onChange, onSubmit }: ChildProps) {
-  return (
-    <div>
-      <input value={value} onChange={e => onChange(e.target.value)} />
-      <button onClick={onSubmit}>Submit</button>
-    </div>
-  )
-}
-```
-
-### Render Props for Flexibility
-
-When sub-components need parent context:
-
-```typescript
-interface ListProps<T> {
-  items: T[]
-  renderItem: (item: T, index: number) => React.ReactNode
-  renderEmpty?: () => React.ReactNode
-}
-
-function List<T>({ items, renderItem, renderEmpty }: ListProps<T>) {
-  if (items.length === 0 && renderEmpty) {
-    return <>{renderEmpty()}</>
-  }
-
-  return (
-    <div>
-      {items.map((item, index) => renderItem(item, index))}
-    </div>
-  )
-}
-
-// Usage
-<List
-  items={operations}
-  renderItem={(op, i) => <OperationItem key={i} operation={op} />}
-  renderEmpty={() => <EmptyState message="No operations" />}
-/>
-```

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

@@ -1,290 +0,0 @@
-# Hook Extraction Patterns
-
-This document provides detailed guidance on extracting custom hooks from complex components in Dify.
-
-## When to Extract Hooks
-
-Extract a custom hook when you identify:
-
-1. **Coupled state groups** - Multiple `useState` hooks that are always used together
-1. **Complex effects** - `useEffect` with multiple dependencies or cleanup logic
-1. **Business logic** - Data transformations, validations, or calculations
-1. **Reusable patterns** - Logic that appears in multiple components
-
-## Extraction Process
-
-### Step 1: Identify State Groups
-
-Look for state variables that are logically related:
-
-```typescript
-// ❌ These belong together - extract to hook
-const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-const [completionParams, setCompletionParams] = useState<FormValue>({})
-const [modelModeType, setModelModeType] = useState<ModelModeType>(...)
-
-// These are model-related state that should be in useModelConfig()
-```
-
-### Step 2: Identify Related Effects
-
-Find effects that modify the grouped state:
-
-```typescript
-// ❌ These effects belong with the state above
-useEffect(() => {
-  if (hasFetchedDetail && !modelModeType) {
-    const mode = currModel?.model_properties.mode
-    if (mode) {
-      const newModelConfig = produce(modelConfig, (draft) => {
-        draft.mode = mode
-      })
-      setModelConfig(newModelConfig)
-    }
-  }
-}, [textGenerationModelList, hasFetchedDetail, modelModeType, currModel])
-```
-
-### Step 3: Create the Hook
-
-```typescript
-// hooks/use-model-config.ts
-import type { FormValue } from '@/app/components/header/account-setting/model-provider-page/declarations'
-import type { ModelConfig } from '@/models/debug'
-import { produce } from 'immer'
-import { useEffect, useState } from 'react'
-import { ModelModeType } from '@/types/app'
-
-interface UseModelConfigParams {
-  initialConfig?: Partial<ModelConfig>
-  currModel?: { model_properties?: { mode?: ModelModeType } }
-  hasFetchedDetail: boolean
-}
-
-interface UseModelConfigReturn {
-  modelConfig: ModelConfig
-  setModelConfig: (config: ModelConfig) => void
-  completionParams: FormValue
-  setCompletionParams: (params: FormValue) => void
-  modelModeType: ModelModeType
-}
-
-export const useModelConfig = ({
-  initialConfig,
-  currModel,
-  hasFetchedDetail,
-}: UseModelConfigParams): UseModelConfigReturn => {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>({
-    provider: 'langgenius/openai/openai',
-    model_id: 'gpt-3.5-turbo',
-    mode: ModelModeType.unset,
-    // ... default values
-    ...initialConfig,
-  })
-
-  const [completionParams, setCompletionParams] = useState<FormValue>({})
-
-  const modelModeType = modelConfig.mode
-
-  // Fill old app data missing model mode
-  useEffect(() => {
-    if (hasFetchedDetail && !modelModeType) {
-      const mode = currModel?.model_properties?.mode
-      if (mode) {
-        setModelConfig(
-          produce(modelConfig, (draft) => {
-            draft.mode = mode
-          }),
-        )
-      }
-    }
-  }, [hasFetchedDetail, modelModeType, currModel])
-
-  return {
-    modelConfig,
-    setModelConfig,
-    completionParams,
-    setCompletionParams,
-    modelModeType,
-  }
-}
-```
-
-### Step 4: Update Component
-
-```typescript
-// Before: 50+ lines of state management
-function Configuration() {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-  // ... lots of related state and effects
-}
-
-// After: Clean component
-function Configuration() {
-  const {
-    modelConfig,
-    setModelConfig,
-    completionParams,
-    setCompletionParams,
-    modelModeType,
-  } = useModelConfig({
-    currModel,
-    hasFetchedDetail,
-  })
-
-  // Component now focuses on UI
-}
-```
-
-## Naming Conventions
-
-### Hook Names
-
-- Use `use` prefix: `useModelConfig`, `useDatasetConfig`
-- Be specific: `useAdvancedPromptConfig` not `usePrompt`
-- Include domain: `useWorkflowVariables`, `useMCPServer`
-
-### File Names
-
-- Kebab-case: `use-model-config.ts`
-- Place in `hooks/` subdirectory when multiple hooks exist
-- Place alongside component for single-use hooks
-
-### Return Type Names
-
-- Suffix with `Return`: `UseModelConfigReturn`
-- Suffix params with `Params`: `UseModelConfigParams`
-
-## Common Hook Patterns in Dify
-
-### 1. Data Fetching / Mutation Hooks
-
-When hook extraction touches query or mutation code, do not use this reference as the source of truth for data-layer patterns.
-
-- Do not introduce deprecated `useInvalid` / `useReset`.
-- Do not extract thin passthrough `useQuery` hooks; only extract orchestration hooks.
-
-### 2. Form State Hook
-
-```typescript
-// Pattern: Form state + validation + submission
-export const useConfigForm = (initialValues: ConfigFormValues) => {
-  const [values, setValues] = useState(initialValues)
-  const [errors, setErrors] = useState<Record<string, string>>({})
-  const [isSubmitting, setIsSubmitting] = useState(false)
-
-  const validate = useCallback(() => {
-    const newErrors: Record<string, string> = {}
-    if (!values.name) newErrors.name = 'Name is required'
-    setErrors(newErrors)
-    return Object.keys(newErrors).length === 0
-  }, [values])
-
-  const handleChange = useCallback((field: string, value: any) => {
-    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],
-  )
-
-  return { values, errors, isSubmitting, handleChange, handleSubmit }
-}
-```
-
-### 3. Modal State Hook
-
-```typescript
-// Pattern: Multiple modal management
-type ModalType = 'edit' | 'delete' | 'duplicate' | null
-
-export const useModalState = () => {
-  const [activeModal, setActiveModal] = useState<ModalType>(null)
-  const [modalData, setModalData] = useState<any>(null)
-
-  const openModal = useCallback((type: ModalType, data?: any) => {
-    setActiveModal(type)
-    setModalData(data)
-  }, [])
-
-  const closeModal = useCallback(() => {
-    setActiveModal(null)
-    setModalData(null)
-  }, [])
-
-  return {
-    activeModal,
-    modalData,
-    openModal,
-    closeModal,
-    isOpen: useCallback((type: ModalType) => activeModal === type, [activeModal]),
-  }
-}
-```
-
-### 4. Toggle/Boolean Hook
-
-```typescript
-// Pattern: Boolean state with convenience methods
-export const useToggle = (initialValue = false) => {
-  const [value, setValue] = useState(initialValue)
-
-  const toggle = useCallback(() => setValue((v) => !v), [])
-  const setTrue = useCallback(() => setValue(true), [])
-  const setFalse = useCallback(() => setValue(false), [])
-
-  return [value, { toggle, setTrue, setFalse, set: setValue }] as const
-}
-
-// Usage
-const [isExpanded, { toggle, setTrue: expand, setFalse: collapse }] = useToggle()
-```
-
-## Testing Extracted Hooks
-
-After extraction, test hooks in isolation:
-
-```typescript
-// use-model-config.spec.ts
-import { renderHook, act } from '@testing-library/react'
-import { useModelConfig } from './use-model-config'
-
-describe('useModelConfig', () => {
-  it('should initialize with default values', () => {
-    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,
-      }),
-    )
-
-    act(() => {
-      result.current.setModelConfig({
-        ...result.current.modelConfig,
-        model_id: 'gpt-4',
-      })
-    })
-
-    expect(result.current.modelConfig.model_id).toBe('gpt-4')
-  })
-})
-```

.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-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,8 +108,10 @@ 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,12 +85,10 @@ 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.
@@ -191,16 +189,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()
     })
@@ -208,9 +206,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()
     })
@@ -233,9 +231,9 @@ describe('GithubComponent', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     )
-
+    
     render(<GithubComponent />)
-
+    
     await waitFor(() => {
       expect(screen.getByText('dify')).toBeInTheDocument()
     })
@@ -248,9 +246,9 @@ describe('GithubComponent', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     )
-
+    
     render(<GithubComponent />)
-
+    
     await waitFor(() => {
       expect(screen.getByText(/error/i)).toBeInTheDocument()
     })
@@ -269,25 +267,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()
   })
 })
@@ -413,7 +411,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
@@ -441,11 +439,14 @@ 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(),
+    },
+  ),
 }))
 ```
 
@@ -527,7 +528,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

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

@@ -1,6 +1,6 @@
 ---
 name: how-to-write-component
-description: React/TypeScript component style guide. Use when writing, refactoring, or reviewing React components, especially around props typing, state boundaries, shared local state with Jotai atoms, API types, query/mutation contracts, navigation, memoization, wrappers, and empty-state handling.
+description: React/TypeScript component style guide. Use when writing, refactoring, or reviewing React components, especially around abstraction choices, props typing, state boundaries, shared local state with Jotai atoms, API types, query/mutation contracts, navigation, memoization, wrappers, and empty-state handling.
 ---
 
 # How To Write A Component
@@ -12,26 +12,79 @@ Use this as the decision guide for React/TypeScript component structure. Existin
 - Search before adding UI, hooks, helpers, or styling patterns. Reuse existing base components, feature components, hooks, utilities, and design styles when they fit.
 - Group code by feature workflow, route, or ownership area: components, hooks, local types, query helpers, atoms, constants, and small utilities should live near the code that changes with them.
 - Promote code to shared only when multiple verticals need the same stable primitive. Otherwise keep it local and compose shared primitives inside the owning feature.
+- Prefer local code and purpose-named helpers over catch-all utility modules; do not group workflow-specific defaults, validation, payload shaping, or metadata merging in a generic utils file just because they share a DTO.
+- Keep source/default selection, validation, and payload shaping close to the workflow that owns the behavior. Do not extract a shared helper just because two flows read the same DTO when their priority order, fallback behavior, or submit semantics differ.
+- Prefer direct, readable conditionals at the use site for small branch-specific decisions, especially form source selection and request payload assembly. Extract only when the helper name captures a stable domain rule and removes repeated complexity without hiding flow-specific behavior.
+- When fixing an invalid pattern, scan the touched feature or branch for equivalent patterns and fix them together.
 - Follow Dify's CSS-first Tailwind v4 contract from `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md`. Prefer design-system tokens, utilities, and radius mappings over generic Tailwind guidance.
 
+## Feature Workflow Layout
+
+- State-heavy wizards, drawers, modals, and secondary workflows work best as a small feature surface with route/entry files, a single feature-local state file, and feature-local UI.
+- Keep `ui/` shallow with owner files that map to the workflow's real composition boundaries and major visual regions.
+- Owner files contain the section components, field components, skeletons, and one-off helper components that belong to their visual region.
+- Folders represent groups of related files with a shared owner and a stable reason to change together.
+- The entry file handles route integration, provider wiring, close behavior, and feature surface mounting. The composition owner handles high-level workflow branching, and the closest visual owner handles section branching.
+
 ## Ownership
 
 - Put local state, queries, mutations, handlers, and derived UI data in the lowest component that uses them. Extract a purpose-built owner component only when the logic has no natural home.
 - Repeated TanStack query calls in sibling components are acceptable when each component independently consumes the data. Do not hoist a query only because it is duplicated; TanStack Query handles deduplication and cache sharing.
 - Hoist state, queries, or callbacks to a parent only when the parent consumes the data, coordinates shared loading/error/empty UI, needs one consistent snapshot, or owns a workflow spanning children.
+- Pass stable domain identity across boundaries; avoid forwarding derived presentation state when the receiver can derive it from its own data source. A component that owns a visual surface should also own the data access, loading, empty, and error states for content rendered inside it unless a parent truly coordinates that state.
+- Loading states for visual surfaces should use skeleton placeholders scoped to the content that is actually loading, with shape, density, and dimensions close to the final UI. Avoid generic loading text or centered spinners for page sections, cards, lists, tables, forms, and drawers; reserve spinners for small inline busy indicators such as an in-progress status icon.
 - Avoid prop drilling. One pass-through layer is acceptable; repeated forwarding means ownership should move down or into feature-scoped Jotai UI state. Keep server/cache state in query and API data flow.
+- Do not replace prop drilling with one top-level hook that returns a large view model and then thread that object through section props. Move each hook, query, derived value, and handler to the concrete section that consumes it, or use feature-scoped Jotai atoms for simple shared form/UI state when siblings need the same source of truth.
+- When using feature-scoped Jotai state for a form, drawer, or other secondary surface, scope the store to that surface instance when stale cross-instance state is possible. Initialize stable config at the owning boundary, then let descendants read only the atoms or purpose-named hooks they actually need.
 - Keep callbacks in a parent only for workflow coordination such as form submission, shared selection, batch behavior, or navigation. Otherwise let the child or row own its action.
 - Prefer uncontrolled DOM state and CSS variables before adding controlled props.
 
+## Feature-Scoped Jotai State
+
+- A module's feature-local state lives in one state file for Jotai-backed features: primitive atoms, query atoms, derived atoms, write-only action atoms, mutation atoms, submission orchestration, provider exports, and optional scope configuration.
+- Atom order in the state file follows the dependency graph: types/constants, editable primitives, query atoms, query-data derived atoms, readiness/business derived atoms, write actions, mutation atoms, submission orchestration, provider exports.
+- Derived atom names read as business facts. Write atom names read as user or workflow commands.
+- UI components read and write the exact atom they use with `useAtomValue` or `useSetAtom`. Repeated workflow semantics live in named derived atoms or write atoms.
+- Non-query derived atoms return a narrow value with a clear domain name. Query atoms expose the TanStack Query result object so loading, error, fetch, and pagination state stay attached to the query contract.
+- Write-only atoms own state transitions that update multiple primitives, reset dependent state, guard stale async work, or advance the workflow.
+- `jotai-tanstack-query` atoms use the same QueryClient as the React Query provider. Query atoms belong in feature state when atoms are the feature's local state surface.
+- Jotai scope is an optional instance-isolation tool for secondary surfaces with independent local state. Query atoms keep shared cache behavior through the shared QueryClient.
+
 ## Components, Props, And Types
 
 - Type component signatures directly; do not use `FC` or `React.FC`.
 - Prefer `function` for top-level components and module helpers. Use arrow functions for local callbacks, handlers, and lambda-style APIs.
 - Prefer named exports. Use default exports only where the framework requires them, such as Next.js route files.
 - Type simple one-off props inline. Use a named `Props` type only when reused, exported, complex, or clearer.
-- Use API-generated or API-returned types at component boundaries. Keep small UI conversion helpers beside the component that needs them.
-- Name values by their domain role and backend API contract, and keep that name stable across the call chain, especially IDs like `appInstanceId`. Normalize framework or route params at the boundary.
-- Keep fallback and invariant checks at the lowest component that already handles that state; callers should pass raw values through instead of duplicating checks.
+- Use API-generated or API-returned types at component boundaries. Keep small UI conversion helpers and one-off UI extensions beside the component that needs them.
+- Do not create type aliases that only rename another type. Use an alias only when it encodes a real UI concept, refinement, or reusable local contract.
+- Name values by their domain role and backend API contract, and keep that name stable across the call chain, especially persistent IDs and route params. Normalize framework or route params at the boundary.
+- Keep fallback and invariant checks at the lowest component that already handles that state; avoid defensive fallbacks that mask impossible states.
+- Do not extract fallback helpers whose only behavior is hiding missing display data. The component that renders the surface owns the empty, disabled, hidden, or placeholder state.
+
+## Generated API Contracts
+
+- Treat generated contracts as authoritative at API, query, mutation, cache, and service boundaries. For enterprise APIs, use `packages/contracts/generated/enterprise/*`.
+- Do not hand-write local request/response/reply/page/cache-data types that mirror generated DTOs. Import or infer the generated type.
+- Do not widen generated fields or enums for compatibility. Normalize legacy input at the boundary, then return the generated field type.
+- Do not repair generated or API-returned contract fields in components unless the API contract or product requirement says they need normalization. Treat enums, statuses, and presence flags as exact contract values.
+- Use generated enum objects and union types directly in props, comparisons, status logic, and i18n keys. Do not add local enum constants or parallel frontend enum/status layers unless they model real product state not represented by the API. Presentation-only tone maps should be keyed by the generated enum.
+- Normalize or coerce only at a real boundary, such as user-entered forms, search, URL/query params, file names, DOM IDs, or legacy adapters. Preserve user-entered values when whitespace or formatting can be meaningful.
+- Do not coerce nullable or optional API strings to `''` in query, derived model, or payload-building code. Keep `undefined` or `null` until the final boundary that requires a string.
+- Local UI models are fine for presentation, form state, select options, or guarded required-field refinements. Name them as UI concepts, not generated DTO mirrors.
+- Required-value refinements are allowed only after same-branch filtering or early return. Prefer nullable-tolerant props for render-only data.
+- When a component needs a stricter shape than a generated DTO, refine once at the API/query-to-UI boundary into a purpose-named UI type instead of hiding missing fields with generic fallback or coercion helpers.
+
+## Nullable API Data
+
+- Prefer nullable-tolerant call boundaries. Pass API-returned types through for render-only rows, and let the component render fallback, disabled state, or nothing.
+- Narrow only where a real value is required, such as mutation params, route hrefs, select values, or query input. Build that target model with `flatMap`, a local loop, or an early return so the required value is captured in the same branch.
+- If design says a field is the display value, use that field. Only the final component should decide whether a nullable display value renders a placeholder, hides content, or disables an action.
+- Do not wrap required arrays or fields in null-fallback helpers. Use empty collection fallbacks only for not-yet-loaded query data or genuinely nullable collections at the owning render boundary.
+- Do not drop rows only to satisfy props or React keys; use a stable fallback key when possible.
+- Use conditional spreads or explicit pushes for conditional array items instead of `undefined` placeholders followed by a narrowing filter.
+- Avoid truthiness type guards, `filter(Boolean)`, `filter(item => item.id)`, and `!` after those filters.
+- Use type guards only for meaningful domain or runtime validation, such as enum membership, object shape, or a reusable business invariant.
 
 ## Queries And Mutations
 
@@ -39,7 +92,8 @@ Use this as the decision guide for React/TypeScript component structure. Existin
 - Consume queries directly with `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))`.
 - Avoid pass-through hooks and thin `web/service/use-*` wrappers that only rename `queryOptions()` or `mutationOptions()`. Extract a small `queryOptions` helper only when repeated call-site options justify it.
 - Keep feature hooks for real orchestration, workflow state, or shared domain behavior.
-- For missing required query input, use `input: skipToken`; use `enabled` only for extra business gating after the input is valid.
+- For TanStack cache data, use generated or query-derived types; do not create local wrappers for `getQueryData` or `getQueriesData`.
+- For generated oRPC `queryOptions()` / `infiniteOptions()`, do not pass `skipToken` as `input`; keep a valid placeholder input shape and use `enabled` to gate missing required params because the OpenAPI codec encodes input eagerly.
 - Consume mutations directly with `useMutation(consoleQuery.xxx.mutationOptions(...))` or `useMutation(marketplaceQuery.xxx.mutationOptions(...))`; use oRPC clients as `mutationFn` only for custom flows.
 - Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`; components may add UI feedback callbacks, but should not own shared invalidation rules.
 - Do not use deprecated `useInvalid` or `useReset`.
@@ -48,12 +102,13 @@ Use this as the decision guide for React/TypeScript component structure. Existin
 ## Component Boundaries
 
 - Use the first level below a page or tab to organize independent page sections when it adds real structure. This layer is layout/semantic first, not automatically the data owner.
+- Treat component names, semantic roles, and user- or design-marked visual regions as boundary constraints. Do not expand a child component's responsibility just because its data is useful nearby; keep adjacent UI as a sibling owner or introduce a correctly named broader owner.
 - Split deeper components by the data and state each layer actually needs. Each component should access only necessary data, and ownership should stay at the lowest consumer.
 - Keep cohesive forms, menu bodies, and one-off helpers local unless they need their own state, reuse, or semantic boundary.
 - Separate hidden secondary surfaces from the trigger's main flow. For dialogs, dropdowns, popovers, and similar branches, extract a small local component that owns the trigger, open state, and hidden content when it would obscure the parent flow.
 - Preserve composability by separating behavior ownership from layout ownership. A dropdown action may own its trigger, open state, and menu content; the caller owns placement such as slots, offsets, and alignment.
 - Avoid unnecessary DOM hierarchy. Do not add wrapper elements unless they provide layout, semantics, accessibility, state ownership, or integration with a library API; prefer fragments or styling an existing element when possible.
-- Avoid shallow wrappers and prop renaming unless the wrapper adds validation, orchestration, error handling, state ownership, or a real semantic boundary.
+- Avoid shallow wrappers, hook-to-props adapter components, layout-only render-prop wrappers, and prop renaming unless the wrapper adds validation, orchestration, error handling, state ownership, or a real semantic boundary. If a component only calls a hook and forwards every returned field to one child, move the hook into that child or make the wrapper own a real surface.
 
 ## You Might Not Need An Effect
 
@@ -68,4 +123,6 @@ Use this as the decision guide for React/TypeScript component structure. Existin
 ## Navigation And Performance
 
 - Prefer `Link` for normal navigation. Use router APIs only for command-flow side effects such as mutation success, guarded redirects, or form submission.
+- Before reaching for `memo`, first try moving changing state down to the smallest component that actually uses it so unrelated sibling trees stay untouched.
+- If changing state must wrap other content, lift the unchanged content up and pass it as `children` so the stateful wrapper can update without React visiting that subtree.
 - Avoid `memo`, `useMemo`, and `useCallback` unless there is a clear performance reason.

.devcontainer/devcontainer.json

@@ -1,43 +1,49 @@
 // 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/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,4 +1,5 @@
 ---
+
 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,7 +59,8 @@ 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] = {
@@ -77,5 +78,5 @@ fs.writeFileSync(
     headSha,
     files,
     changes,
-  }),
+  })
 )

.github/workflows/api-tests.yml

@@ -25,17 +25,17 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - '3.12'
+          - "3.12"
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -87,17 +87,17 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - '3.12'
+          - "3.12"
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -142,16 +142,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
-          python-version: '3.12'
+          python-version: "3.12"
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -195,7 +195,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           files: ./coverage.xml
           disable_search: true

.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
 
@@ -20,7 +20,7 @@ jobs:
         run: echo "autofix.ci updates pull request branches, not merge group refs."
 
       - if: github.event_name != 'merge_group'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Check Docker Compose inputs
         if: github.event_name != 'merge_group'
@@ -44,12 +44,6 @@ 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
@@ -69,10 +63,10 @@ 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
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Generate Docker Compose
         if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'
@@ -152,12 +146,6 @@ 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,15 @@ 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"
+      - "feat/rbac"
     tags:
-      - '*'
+      - "*"
 
 concurrency:
   group: build-push-${{ github.head_ref || github.run_id }}
@@ -21,6 +22,7 @@ env:
   DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
   DIFY_WEB_IMAGE_NAME: ${{ vars.DIFY_WEB_IMAGE_NAME || 'langgenius/dify-web' }}
   DIFY_API_IMAGE_NAME: ${{ vars.DIFY_API_IMAGE_NAME || 'langgenius/dify-api' }}
+  DIFY_AGENT_IMAGE_NAME: ${{ vars.DIFY_AGENT_IMAGE_NAME || 'langgenius/dify-agent-backend' }}
 
 jobs:
   build:
@@ -32,32 +34,46 @@ 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
+          - service_name: "build-agent-amd64"
+            image_name_env: "DIFY_AGENT_IMAGE_NAME"
+            artifact_context: "agent"
+            build_context: "{{defaultContext}}"
+            file: "dify-agent/Dockerfile"
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: "build-agent-arm64"
+            image_name_env: "DIFY_AGENT_IMAGE_NAME"
+            artifact_context: "agent"
+            build_context: "{{defaultContext}}"
+            file: "dify-agent/Dockerfile"
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
 
@@ -68,7 +84,7 @@ jobs:
           echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
 
       - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
@@ -78,13 +94,13 @@ jobs:
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ${{ env[matrix.image_name_env] }}
 
       - name: Build Docker image
         id: build
-        uses: depot/build-push-action@5f3b3c2e5a00f0093de47f657aeaefcedff27d18 # v1.17.0
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
         with:
           project: ${{ vars.DEPOT_PROJECT_ID }}
           context: ${{ matrix.build_context }}
@@ -116,18 +132,21 @@ 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"
+          - service_name: "validate-agent-amd64"
+            build_context: "{{defaultContext}}"
+            file: "dify-agent/Dockerfile"
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
 
       - name: Validate Docker image
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           push: false
           context: ${{ matrix.build_context }}
@@ -141,12 +160,15 @@ 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"
+          - service_name: "merge-agent-images"
+            image_name_env: "DIFY_AGENT_IMAGE_NAME"
+            context: "agent"
     steps:
       - name: Download digests
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -156,14 +178,14 @@ jobs:
           merge-multiple: true
 
       - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ${{ env[matrix.image_name_env] }}
           tags: |

.github/workflows/cli-e2e.yml

@@ -4,19 +4,19 @@ on:
   workflow_dispatch:
     inputs:
       cli_ref:
-        description: 'Git ref (default: current branch)'
+        description: "Git ref (default: current branch)"
         type: string
         required: false
 
       edition:
-        description: 'Dify edition'
+        description: "Dify edition"
         type: choice
         required: false
         default: ee
         options: [ee, ce]
 
       test_scope:
-        description: 'smoke = [P0] only  /  full = all cases'
+        description: "smoke = [P0] only  /  full = all cases"
         type: choice
         required: false
         default: full
@@ -24,23 +24,23 @@ on:
 
       # ── Suite on/off ────────────────────────────────────────────────────────
       suite_framework_output_error:
-        description: 'framework + output + error-handling suites'
+        description: "framework + output + error-handling suites"
         type: boolean
         default: true
       suite_discovery:
-        description: 'discovery suite (get app / describe app)'
+        description: "discovery suite (get app / describe app)"
         type: boolean
         default: true
       suite_run:
-        description: 'run suite (basic / streaming / conversation / file / hitl)'
+        description: "run suite (basic / streaming / conversation / file / hitl)"
         type: boolean
         default: true
       suite_auth:
-        description: 'auth suite (login / status / whoami / use / devices / logout)'
+        description: "auth suite (login / status / whoami / use / devices / logout)"
         type: boolean
         default: true
       suite_agent:
-        description: 'agent suite'
+        description: "agent suite"
         type: boolean
         default: true
 
@@ -51,34 +51,35 @@ permissions:
 # 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
+  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)
-  # ════════════════════════════════════════════════════════════════════════════
+
+# ════════════════════════════════════════════════════════════════════════════
+# 0. PROVISION — mint token + import DSL fixtures (runs once, outputs IDs)
+# ════════════════════════════════════════════════════════════════════════════
   provision:
-    name: 'Provision: mint token + DSL apps'
+    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 }}
+      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
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -87,7 +88,7 @@ jobs:
         with:
           bun-version: latest
 
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         with:
           package_json_field: packageManager
           run_install: false
@@ -100,18 +101,18 @@ jobs:
         id: out
         working-directory: cli
         env:
-          DIFY_E2E_HOST: ${{ secrets.DIFY_E2E_HOST }}
-          DIFY_E2E_EMAIL: ${{ secrets.DIFY_E2E_EMAIL }}
+          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' }}
+          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)
-  # ════════════════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════════════
+# 1-B. framework + output + error-handling (parallel with run/discovery)
+# ════════════════════════════════════════════════════════════════════════════
   suite-framework-output-error:
-    name: 'Suite: framework + output + error-handling'
+    name: "Suite: framework + output + error-handling"
     if: ${{ inputs.suite_framework_output_error != 'false' }}
     needs: provision
     runs-on: ubuntu-latest
@@ -122,7 +123,7 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -130,23 +131,23 @@ jobs:
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
         with: { bun-version: latest }
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         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_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_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'
+          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\]"
@@ -154,11 +155,11 @@ jobs:
             pnpm test:e2e
           fi
 
-  # ════════════════════════════════════════════════════════════════════════════
-  # 1-C. Discovery (parallel)
-  # ════════════════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════════════
+# 1-C. Discovery (parallel)
+# ════════════════════════════════════════════════════════════════════════════
   suite-discovery:
-    name: 'Suite: discovery'
+    name: "Suite: discovery"
     if: ${{ inputs.suite_discovery != 'false' }}
     needs: provision
     runs-on: ubuntu-latest
@@ -169,7 +170,7 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -177,24 +178,24 @@ jobs:
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
         with: { bun-version: latest }
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         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_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_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'
+          DIFY_E2E_INCLUDE: "test/e2e/suites/discovery/**/*.e2e.ts"
         run: |
           if [ "${{ inputs.test_scope }}" = "smoke" ]; then
             pnpm test:e2e -- -t "\[P0\]"
@@ -202,11 +203,11 @@ jobs:
             pnpm test:e2e
           fi
 
-  # ════════════════════════════════════════════════════════════════════════════
-  # 1-D. Run suite — 5 files in matrix (parallel)
-  # ════════════════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════════════
+# 1-D. Run suite — 5 files in matrix (parallel)
+# ════════════════════════════════════════════════════════════════════════════
   suite-run:
-    name: 'Suite: run / ${{ matrix.name }}'
+    name: "Suite: run / ${{ matrix.name }}"
     if: ${{ inputs.suite_run != 'false' }}
     needs: provision
     runs-on: ubuntu-latest
@@ -232,7 +233,7 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -240,30 +241,30 @@ jobs:
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
         with: { bun-version: latest }
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         with: { package_json_field: packageManager, run_install: false }
       - run: pnpm install --frozen-lockfile
       - run: pnpm tree:gen
 
-      - name: 'Run run/${{ matrix.name }}'
+      - 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_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 }}'
+          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\]"
@@ -273,17 +274,17 @@ jobs:
 
       - name: Upload results on failure
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         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)
-  # ════════════════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════════════
+# 1-E. auth/login + status + whoami (parallel, read-only, safe)
+# ════════════════════════════════════════════════════════════════════════════
   suite-auth-safe:
-    name: 'Suite: auth (login / status / whoami)'
+    name: "Suite: auth (login / status / whoami)"
     if: ${{ inputs.suite_auth != 'false' }}
     needs: provision
     runs-on: ubuntu-latest
@@ -294,7 +295,7 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -302,22 +303,22 @@ jobs:
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
         with: { bun-version: latest }
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         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_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'
+          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\]"
@@ -325,13 +326,13 @@ jobs:
             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.
-  # ════════════════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════════════
+# 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)'
+    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:
@@ -350,7 +351,7 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -358,27 +359,27 @@ jobs:
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
         with: { bun-version: latest }
-      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         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_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 }}
+          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=()
@@ -407,7 +408,7 @@ jobs:
 
       - name: Upload results on failure
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: e2e-last-${{ github.run_id }}
           path: cli/test-results/

.github/workflows/cli-edge.yml

@@ -0,0 +1,74 @@
+name: CLI Edge Publish
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'cli/**'
+      - 'packages/contracts/generated/api/openapi/**'
+  workflow_dispatch:
+
+concurrency:
+  group: difyctl-edge-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: build + publish edge to R2
+    runs-on: ${{ github.repository == 'langgenius/dify' && 'depot-ubuntu-24.04' || 'ubuntu-24.04' }}
+    if: vars.DIFYCTL_R2_BUCKET != ''
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Enable cross-arch native prebuilds
+        working-directory: ./
+        run: cat cli/scripts/cross-arch.pnpm.yaml >> pnpm-workspace.yaml
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5 # v2.0.2
+        with:
+          bun-version-file: cli/.bun-version
+
+      - name: Compute edge version
+        id: ver
+        run: echo "version=$(node scripts/release-naming.mjs edge-version "$(git rev-parse --short HEAD)")" >> "$GITHUB_OUTPUT"
+
+      - name: Compile standalone binaries (all targets, all-or-nothing)
+        run: |
+          CLI_VERSION="${{ steps.ver.outputs.version }}" \
+          DIFYCTL_CHANNEL=edge \
+          DIFYCTL_COMMIT="$(git rev-parse HEAD)" \
+          DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
+            pnpm build:bin
+
+      - name: Generate sha256 checksums
+        run: CLI_VERSION="${{ steps.ver.outputs.version }}" scripts/release-write-checksums.sh
+
+      - name: Smoke the runner-arch binary
+        run: ./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64 version
+
+      - name: Publish to R2
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.DIFYCTL_R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.DIFYCTL_R2_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: auto
+          AWS_REQUEST_CHECKSUM_CALCULATION: WHEN_REQUIRED
+          AWS_RESPONSE_CHECKSUM_VALIDATION: WHEN_REQUIRED
+          DIFYCTL_R2_S3_ENDPOINT: ${{ vars.DIFYCTL_R2_S3_ENDPOINT }}
+          DIFYCTL_R2_BUCKET: ${{ vars.DIFYCTL_R2_BUCKET }}
+          DIFYCTL_R2_PUBLIC_BASE: ${{ vars.DIFYCTL_R2_PUBLIC_BASE }}
+          DIFYCTL_COMMIT: ${{ github.sha }}
+        run: |
+          DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
+            scripts/release-r2-publish.sh edge "${{ steps.ver.outputs.version }}"

.github/workflows/cli-release.yml

@@ -35,7 +35,7 @@ jobs:
       dify_tag: ${{ steps.resolve.outputs.dify_tag }}
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -98,7 +98,7 @@ jobs:
       DIFY_TAG: ${{ needs.validate.outputs.dify_tag }}
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
           fetch-depth: 1

.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
 
@@ -24,7 +24,7 @@ jobs:
         shell: bash
     steps:
       - name: Checkout cli ref
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false

.github/workflows/cli-tests.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -51,7 +51,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' && matrix.os == 'depot-ubuntu-24.04' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           directory: cli/coverage
           flags: cli

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

@@ -13,16 +13,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
-          python-version: '3.12'
+          python-version: "3.12"
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -40,7 +40,7 @@ jobs:
           cp envs/middleware.env.example middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        uses: hoverkraft-tech/compose-action@11beaa1c2dae4e8ed7b1665aa074723b6cecb0e4 # v3.0.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -63,16 +63,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
-          python-version: '3.12'
+          python-version: "3.12"
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -94,7 +94,7 @@ jobs:
           sed -i 's/DB_USERNAME=postgres/DB_USERNAME=mysql/' middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@d2bee4f07e8ca410d6b196d00f90c12e7d48c33a # v2.6.0
+        uses: hoverkraft-tech/compose-action@11beaa1c2dae4e8ed7b1665aa074723b6cecb0e4 # v3.0.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml

.github/workflows/deploy-agent.yml

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

.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,32 +28,32 @@ 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
 
       - name: Build Docker Image
-        uses: depot/build-push-action@5f3b3c2e5a00f0093de47f657aeaefcedff27d18 # v1.17.0
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
         with:
           project: ${{ vars.DEPOT_PROJECT_ID }}
           push: false
@@ -69,18 +69,18 @@ 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
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
 
       - name: Build Docker Image
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           push: false
           context: ${{ matrix.context }}

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

@@ -24,7 +24,7 @@ jobs:
     name: Require cherry-pick provenance
     runs-on: depot-ubuntu-24.04
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 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
@@ -48,7 +48,7 @@ jobs:
       vdb-changed: ${{ steps.changes.outputs.vdb }}
       migration-changed: ${{ steps.changes.outputs.migration }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         id: changes
         with:

.github/workflows/pyrefly-diff.yml

@@ -17,12 +17,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout PR branch
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
 

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

@@ -21,10 +21,10 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.pull_requests[0].head.repo.full_name != github.repository }}
     steps:
       - name: Checkout default branch (trusted code)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
 

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

@@ -17,12 +17,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout PR branch
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
 

.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,19 +11,20 @@ on:
 
 jobs:
   stale:
+
     runs-on: depot-ubuntu-24.04
     permissions:
       issues: write
       pull-requests: write
 
     steps:
-      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
+      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
         with:
           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

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -33,10 +33,10 @@ jobs:
 
       - name: Setup UV and Python
         if: steps.changed-files.outputs.any_changed == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: false
-          python-version: '3.12'
+          python-version: "3.12"
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -71,7 +71,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -114,7 +114,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -132,10 +132,7 @@ 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/**
 
@@ -143,12 +140,6 @@ 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
@@ -180,7 +171,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.github/workflows/tool-test-sdks.yaml

@@ -24,7 +24,7 @@ jobs:
         working-directory: sdks/nodejs-client
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

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

@@ -40,7 +40,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -158,7 +158,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@1dc994ee7a008f0ecc866d9ac23ef036b7229f84 # v1.0.127
+        uses: anthropics/claude-code-action@806af32823ef69c8ef357086c573a902af641307 # v1.0.151
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/trigger-i18n-sync.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 

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

@@ -20,11 +20,11 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - '3.12'
+          - "3.12"
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -36,7 +36,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -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,11 +17,11 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - '3.12'
+          - "3.12"
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -33,7 +33,7 @@ jobs:
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -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

@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -28,10 +28,10 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.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
 

.github/workflows/web-tests.yml

@@ -31,7 +31,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -64,7 +64,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -83,7 +83,7 @@ jobs:
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           directory: web/coverage
           flags: web
@@ -102,7 +102,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -113,13 +113,36 @@ jobs:
         run: vp exec playwright install --with-deps chromium
 
       - name: Run dify-ui tests
-        run: vp test run --coverage --silent=passed-only
+        run: vp test run --project unit --coverage --silent=passed-only
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           directory: packages/dify-ui/coverage
           flags: dify-ui
         env:
           CODECOV_TOKEN: ${{ env.CODECOV_TOKEN }}
+
+  dify-ui-storybook-test:
+    name: dify-ui Storybook Tests
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./packages/dify-ui
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Install Chromium for Browser Mode
+        run: vp exec playwright install --with-deps chromium
+
+      - name: Run dify-ui Storybook tests
+        run: vp run test:storybook

.vscode/settings.example.json

@@ -1,18 +1,32 @@
 {
-  "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",
 
-  // Format
-  "editor.formatOnSave": true,
-  "oxc.fmt.configPath": "./vite.config.ts",
-
-  // Lint fix
+  // Auto fix
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
+    "source.fixAll.eslint": "explicit",
   },
 
+  // 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 }
+  ],
+
   // Enable eslint for all supported languages
   "eslint.validate": [
     "javascript",

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 `vp fmt` for formatting, ESLint for lint-only fixes, plus `pnpm type-check`, and avoid `any` types.
+- **TypeScript**: Use the strict config, rely on ESLint (`pnpm lint:fix` preferred) 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
 

api/.env.example

@@ -774,3 +774,11 @@ EVENT_BUS_LISTENER_JOIN_TIMEOUT_MS=2000
 ENABLE_HUMAN_INPUT_TIMEOUT_TASK=true
 # Human input timeout check interval in minutes
 HUMAN_INPUT_TIMEOUT_TASK_INTERVAL=1
+
+# Nacos remote settings source HTTP timeouts (seconds).
+# Bound how long requests to the Nacos endpoint wait before failing, so a slow or
+# unresponsive Nacos server cannot stall API startup or token refresh.
+# Read timeout for Nacos requests (default: 10.0)
+DIFY_ENV_NACOS_REQUEST_TIMEOUT=10.0
+# Connect timeout for Nacos requests (default: 3.0)
+DIFY_ENV_NACOS_CONNECT_TIMEOUT=3.0

api/clients/agent_backend/__init__.py

@@ -33,6 +33,7 @@ from clients.agent_backend.fake_client import FakeAgentBackendRunClient, FakeAge
 from clients.agent_backend.request_builder import (
     AGENT_SOUL_PROMPT_LAYER_ID,
     DIFY_EXECUTION_CONTEXT_LAYER_ID,
+    DIFY_KNOWLEDGE_BASE_LAYER_ID,
     DIFY_PLUGIN_TOOLS_LAYER_ID,
     WORKFLOW_NODE_JOB_PROMPT_LAYER_ID,
     WORKFLOW_USER_PROMPT_LAYER_ID,
@@ -47,6 +48,7 @@ from clients.agent_backend.request_builder import (
 __all__ = [
     "AGENT_SOUL_PROMPT_LAYER_ID",
     "DIFY_EXECUTION_CONTEXT_LAYER_ID",
+    "DIFY_KNOWLEDGE_BASE_LAYER_ID",
     "DIFY_PLUGIN_TOOLS_LAYER_ID",
     "WORKFLOW_NODE_JOB_PROMPT_LAYER_ID",
     "WORKFLOW_USER_PROMPT_LAYER_ID",

api/clients/agent_backend/request_builder.py

@@ -19,6 +19,7 @@ from agenton.compositor.schemas import LayerSessionSnapshot
 from agenton.layers import ExitIntent
 from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
 from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
+from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
 from dify_agent.layers.dify_plugin import (
     DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
     DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
@@ -31,6 +32,7 @@ from dify_agent.layers.execution_context import (
     DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
     DifyExecutionContextLayerConfig,
 )
+from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
 from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
 from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
 from dify_agent.protocol import (
@@ -38,6 +40,7 @@ from dify_agent.protocol import (
     DIFY_AGENT_MODEL_LAYER_ID,
     DIFY_AGENT_OUTPUT_LAYER_ID,
     CreateRunRequest,
+    DeferredToolResultsPayload,
     LayerExitSignals,
     RunComposition,
     RunLayerSpec,
@@ -53,6 +56,8 @@ 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_KNOWLEDGE_BASE_LAYER_ID = "knowledge"
+DIFY_ASK_HUMAN_LAYER_ID = "ask_human"
 DIFY_SHELL_LAYER_ID = "shell"
 
 
@@ -136,14 +141,22 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    knowledge: DifyKnowledgeBaseLayerConfig | 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
+    # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
+    # the Agent Soul configures human involvement; a deferred call ends the run and
+    # the workflow pauses via the existing HITL form mechanism (ENG-635).
+    ask_human_config: DifyAskHumanLayerConfig | None = None
     # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
     # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
     include_shell: bool = False
     shell_config: DifyShellLayerConfig | None = None
     session_snapshot: CompositorSessionSnapshot | None = None
+    # Human tool results fed back into a continuation run after a HITL submission
+    # (ENG-638). Keyed by the original deferred tool_call_id.
+    deferred_tool_results: DeferredToolResultsPayload | None = None
     include_history: bool = True
     suspend_on_exit: bool = True
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -175,14 +188,21 @@ class AgentBackendAgentAppRunInput(BaseModel):
     idempotency_key: str | None = None
     output: AgentBackendOutputConfig | None = None
     tools: DifyPluginToolsLayerConfig | None = None
+    knowledge: DifyKnowledgeBaseLayerConfig | 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
+    # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
+    # the Agent Soul configures human involvement (ENG-635).
+    ask_human_config: DifyAskHumanLayerConfig | None = None
     # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
     # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
     include_shell: bool = False
     shell_config: DifyShellLayerConfig | None = None
     session_snapshot: CompositorSessionSnapshot | None = None
+    # Human tool results fed back into a continuation run after a HITL submission
+    # (ENG-638). Keyed by the original deferred tool_call_id.
+    deferred_tool_results: DeferredToolResultsPayload | None = None
     include_history: bool = True
     suspend_on_exit: bool = True
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -205,7 +225,7 @@ class AgentBackendRunRequestBuilder:
 
         Layer graph: optional Agent Soul system prompt → user prompt →
         execution context → optional history (multi-turn) → LLM → optional
-        plugin tools → optional structured output. Mirrors the workflow-node
+        plugin tools / knowledge search → optional structured output. Mirrors the workflow-node
         layer ordering minus the workflow-job / previous-node prompt.
         """
         layers: list[RunLayerSpec] = []
@@ -284,6 +304,30 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.knowledge is not None and run_input.knowledge.dataset_ids:
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_KNOWLEDGE_BASE_LAYER_ID,
+                    type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
+                    metadata=run_input.metadata,
+                    config=run_input.knowledge,
+                )
+            )
+
+        if run_input.ask_human_config is not None:
+            # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
+            # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
+            # later resumes with deferred_tool_results. Needs the history layer above.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_ASK_HUMAN_LAYER_ID,
+                    type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.ask_human_config,
+                )
+            )
+
         if run_input.include_shell:
             # Sandboxed bash workspace (dify.shell). Depends on execution_context so
             # the agent server can mint per-command Agent Stub env (back proxy);
@@ -318,6 +362,7 @@ class AgentBackendRunRequestBuilder:
             idempotency_key=run_input.idempotency_key,
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
+            deferred_tool_results=run_input.deferred_tool_results,
             on_exit=LayerExitSignals(
                 default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
             ),
@@ -368,7 +413,12 @@ class AgentBackendRunRequestBuilder:
         )
 
     def build_for_workflow_node(self, run_input: AgentBackendWorkflowNodeRunInput) -> CreateRunRequest:
-        """Build a workflow Agent Node run request without defining another wire schema."""
+        """Build a workflow Agent Node run request without defining another wire schema.
+
+        Layer graph mirrors the workflow surface: prompts → execution context →
+        optional drive/history → LLM → optional plugin tools / knowledge search
+        → optional auxiliary layers such as ask_human, shell, and structured output.
+        """
         layers: list[RunLayerSpec] = []
         if run_input.agent_soul_prompt:
             layers.append(
@@ -453,6 +503,30 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.knowledge is not None and run_input.knowledge.dataset_ids:
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_KNOWLEDGE_BASE_LAYER_ID,
+                    type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
+                    deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
+                    metadata=run_input.metadata,
+                    config=run_input.knowledge,
+                )
+            )
+
+        if run_input.ask_human_config is not None:
+            # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
+            # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
+            # later resumes with deferred_tool_results. Needs the history layer above.
+            layers.append(
+                RunLayerSpec(
+                    name=DIFY_ASK_HUMAN_LAYER_ID,
+                    type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
+                    metadata=run_input.metadata,
+                    config=run_input.ask_human_config,
+                )
+            )
+
         if run_input.include_shell:
             # Sandboxed bash workspace (dify.shell). Depends on execution_context so
             # the agent server can mint per-command Agent Stub env (back proxy);
@@ -487,6 +561,7 @@ class AgentBackendRunRequestBuilder:
             idempotency_key=run_input.idempotency_key,
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
+            deferred_tool_results=run_input.deferred_tool_results,
             on_exit=LayerExitSignals(
                 default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
             ),

api/commands/__init__.py

@@ -11,6 +11,7 @@ from .data_migration import (
     migration_data_wizard,
 )
 from .plugin import (
+    backfill_plugin_auto_upgrade,
     extract_plugins,
     extract_unique_plugins,
     install_plugins,
@@ -21,6 +22,7 @@ from .plugin import (
     setup_system_trigger_oauth_client,
     transform_datasource_credentials,
 )
+from .rbac import migrate_member_roles_to_rbac
 from .retention import (
     archive_workflow_runs,
     clean_expired_messages,
@@ -49,6 +51,7 @@ from .vector import (
 __all__ = [
     "add_qdrant_index",
     "archive_workflow_runs",
+    "backfill_plugin_auto_upgrade",
     "clean_expired_messages",
     "clean_workflow_runs",
     "cleanup_orphaned_draft_variables",
@@ -72,6 +75,7 @@ __all__ = [
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",
     "migrate_knowledge_vector_database",
+    "migrate_member_roles_to_rbac",
     "migrate_oss",
     "migration_data_wizard",
     "old_metadata_migration",

api/commands/plugin.py

@@ -1,10 +1,11 @@
 import json
 import logging
+import time
 from typing import Any, cast
 
 import click
 from pydantic import TypeAdapter
-from sqlalchemy import delete, select
+from sqlalchemy import delete, func, select
 from sqlalchemy.engine import CursorResult
 
 from configs import dify_config
@@ -15,11 +16,13 @@ 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__)
@@ -402,6 +405,110 @@ 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/commands/rbac.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import click
+from sqlalchemy import select
+
+from core.db.session_factory import session_factory
+from models import TenantAccountJoin, TenantAccountRole
+from services.enterprise.rbac_service import ListOption, RBACService
+
+
+def _resolve_builtin_role_id(tenant_id: str, operator_account_id: str, legacy_role: str) -> str:
+    """Resolve a legacy workspace role to the current tenant's builtin RBAC role id.
+
+    The migration replays the old `TenantAccountJoin.role` values onto the
+    RBAC member-role binding API. Builtin RBAC roles are tenant-scoped and
+    identified by runtime ids, so the command must look them up per tenant.
+    """
+    expected_builtin_tag = {
+        TenantAccountRole.OWNER.value: "owner",
+        TenantAccountRole.ADMIN.value: "admin",
+        TenantAccountRole.EDITOR.value: "editor",
+        TenantAccountRole.NORMAL.value: "normal",
+        TenantAccountRole.DATASET_OPERATOR.value: "dataset_operator",
+    }.get(legacy_role)
+    if not expected_builtin_tag:
+        raise ValueError(f"Unsupported legacy workspace role: {legacy_role}")
+
+    roles = RBACService.Roles.list(
+        tenant_id=tenant_id,
+        account_id=operator_account_id,
+        options=ListOption(page_number=1, results_per_page=100),
+    ).data
+    for role in roles:
+        if role.is_builtin and role.category == "global_system_default" and role.role_tag == expected_builtin_tag:
+            return str(role.id)
+
+    raise ValueError(f"Builtin RBAC role not found for tenant={tenant_id}, legacy_role={legacy_role}")
+
+
+@click.command(
+    "rbac-migrate-member-roles", help="Migrate legacy workspace member roles into RBAC member-role bindings."
+)
+@click.option("--tenant-id", help="Only migrate a single workspace.")
+@click.option("--dry-run", is_flag=True, default=False, help="Preview the migration without writing RBAC bindings.")
+def migrate_member_roles_to_rbac(tenant_id: str | None, dry_run: bool) -> None:
+    """Backfill RBAC member-role bindings from legacy `TenantAccountJoin.role` data.
+
+    This is an offline migration command for workspaces that already have
+    members in the legacy role model but need matching records in the RBAC
+    member-role binding store.
+    """
+    click.echo(click.style("Starting RBAC member-role migration.", fg="green"))
+
+    with session_factory.create_session() as session:
+        stmt = select(TenantAccountJoin).order_by(TenantAccountJoin.tenant_id.asc(), TenantAccountJoin.id.asc())
+        if tenant_id:
+            stmt = stmt.where(TenantAccountJoin.tenant_id == tenant_id)
+
+        joins = list(session.scalars(stmt).all())
+
+    if not joins:
+        click.echo(click.style("No workspace members found for migration.", fg="yellow"))
+        return
+
+    owner_account_by_tenant: dict[str, str] = {}
+    resolved_role_ids: dict[tuple[str, str], str] = {}
+    migrated_count = 0
+
+    for join in joins:
+        workspace_id = str(join.tenant_id)
+        member_account_id = str(join.account_id)
+        legacy_role = str(join.role)
+
+        if workspace_id not in owner_account_by_tenant:
+            owner_join = next(
+                (
+                    item
+                    for item in joins
+                    if str(item.tenant_id) == workspace_id and str(item.role) == TenantAccountRole.OWNER.value
+                ),
+                None,
+            )
+            if not owner_join:
+                raise ValueError(f"Workspace owner not found for tenant={workspace_id}")
+            owner_account_by_tenant[workspace_id] = str(owner_join.account_id)
+
+        operator_account_id = owner_account_by_tenant[workspace_id]
+        cache_key = (workspace_id, legacy_role)
+        if cache_key not in resolved_role_ids:
+            resolved_role_ids[cache_key] = _resolve_builtin_role_id(workspace_id, operator_account_id, legacy_role)
+
+        resolved_role_id = resolved_role_ids[cache_key]
+        click.echo(
+            f"tenant={workspace_id} member={member_account_id} "
+            f"legacy_role={legacy_role} -> rbac_role_id={resolved_role_id}"
+        )
+
+        if dry_run:
+            continue
+
+        RBACService.MemberRoles.replace(
+            tenant_id=workspace_id,
+            account_id=operator_account_id,
+            member_account_id=member_account_id,
+            role_ids=[resolved_role_id],
+        )
+        migrated_count += 1
+
+    if dry_run:
+        click.echo(click.style("Dry run completed. No RBAC bindings were written.", fg="yellow"))
+    else:
+        click.echo(click.style(f"RBAC member-role migration completed. Migrated {migrated_count} members.", fg="green"))

api/configs/enterprise/__init__.py

@@ -29,6 +29,11 @@ class EnterpriseFeatureConfig(BaseSettings):
         "This helps gain runtime performance by trading off consistency.",
     )
 
+    RBAC_ENABLED: bool = Field(
+        description="Enable enterprise RBAC APIs. When disabled, compatibility responses fall back to legacy roles.",
+        default=False,
+    )
+
 
 class EnterpriseTelemetryConfig(BaseSettings):
     """

api/configs/remote_settings_sources/nacos/http_request.py

@@ -20,6 +20,12 @@ class NacosHttpClient:
         self.token: str | None = None
         self.token_ttl = 18000
         self.token_expire_time: float = 0
+        # Bounded timeouts so a slow or unresponsive Nacos server cannot hang the API
+        # service indefinitely during startup or token refresh.
+        self.timeout = httpx.Timeout(
+            float(os.getenv("DIFY_ENV_NACOS_REQUEST_TIMEOUT", "10.0")),
+            connect=float(os.getenv("DIFY_ENV_NACOS_CONNECT_TIMEOUT", "3.0")),
+        )
 
     def http_request(
         self, url: str, method: str = "GET", headers: dict[str, str] | None = None, params: dict[str, str] | None = None
@@ -28,12 +34,17 @@ class NacosHttpClient:
             headers = {}
         if params is None:
             params = {}
+        full_url = "http://" + self.server + url
         try:
             self._inject_auth_info(headers, params)
-            response = httpx.request(method, url="http://" + self.server + url, headers=headers, params=params)
+            response = httpx.request(method, url=full_url, headers=headers, params=params, timeout=self.timeout)
             response.raise_for_status()
             return response.text
+        except httpx.TimeoutException as e:
+            logger.warning("Request to Nacos timed out (url=%s, timeout=%s): %s", full_url, self.timeout, e)
+            return f"Request to Nacos timed out: {e}"
         except httpx.RequestError as e:
+            logger.warning("Request to Nacos failed (url=%s): %s", full_url, e)
             return f"Request to Nacos failed: {e}"
 
     def _inject_auth_info(self, headers: dict[str, str], params: dict[str, str], module: str = "config") -> None:
@@ -78,13 +89,16 @@ class NacosHttpClient:
         params = {"username": self.username, "password": self.password}
         url = "http://" + self.server + "/nacos/v1/auth/login"
         try:
-            resp = httpx.request("POST", url, headers=None, params=params)
+            resp = httpx.request("POST", url, headers=None, params=params, timeout=self.timeout)
             resp.raise_for_status()
             response_data = resp.json()
             self.token = response_data.get("accessToken")
             self.token_ttl = response_data.get("tokenTtl", 18000)
             self.token_expire_time = current_time + self.token_ttl - 10
             return self.token
+        except httpx.TimeoutException:
+            logger.exception("[get-access-token] request to Nacos timed out (url=%s, timeout=%s)", url, self.timeout)
+            raise
         except Exception:
             logger.exception("[get-access-token] exception occur")
             raise

api/controllers/common/controller_schemas.py

@@ -1,7 +1,8 @@
-from typing import Any, Literal
+from copy import deepcopy
+from typing import Annotated, Any, Literal, override
 from uuid import UUID
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, GetJsonSchemaHandler, WithJsonSchema, model_validator
 
 from libs.helper import UUIDStrOrEmpty
 
@@ -9,8 +10,53 @@ from libs.helper import UUIDStrOrEmpty
 
 
 class ConversationRenamePayload(BaseModel):
-    name: str | None = None
-    auto_generate: bool = False
+    name: str | None = Field(
+        default=None,
+        description="Conversation name. Required when `auto_generate` is `false`.",
+    )
+    auto_generate: bool = Field(
+        default=False,
+        description="Automatically generate the conversation name. When `true`, the `name` field is ignored.",
+    )
+
+    @classmethod
+    @override
+    def __get_pydantic_json_schema__(cls, core_schema: Any, handler: GetJsonSchemaHandler) -> dict[str, Any]:
+        schema = handler.resolve_ref_schema(handler(core_schema))
+        properties = schema.get("properties")
+        if not isinstance(properties, dict):
+            return schema
+
+        auto_generate_schema = deepcopy(properties.get("auto_generate", {"type": "boolean"}))
+        name_schema = deepcopy(properties.get("name", {"type": "string"}))
+        non_blank_name_schema: dict[str, Any] = {"pattern": r".*\S.*", "type": "string"}
+        if isinstance(name_schema, dict) and isinstance(name_schema.get("title"), str):
+            non_blank_name_schema["title"] = name_schema["title"]
+
+        auto_generate_true_schema = {**auto_generate_schema, "enum": [True]}
+        auto_generate_true_schema.pop("default", None)
+
+        return {
+            **schema,
+            "anyOf": [
+                {
+                    "properties": {
+                        "auto_generate": auto_generate_true_schema,
+                        "name": name_schema,
+                    },
+                    "required": ["auto_generate"],
+                    "type": "object",
+                },
+                {
+                    "properties": {
+                        "auto_generate": {**auto_generate_schema, "enum": [False]},
+                        "name": non_blank_name_schema,
+                    },
+                    "required": ["name"],
+                    "type": "object",
+                },
+            ],
+        }
 
     @model_validator(mode="after")
     def validate_name_requirement(self):
@@ -24,14 +70,28 @@ class ConversationRenamePayload(BaseModel):
 
 
 class MessageListQuery(BaseModel):
-    conversation_id: UUIDStrOrEmpty = Field(description="Conversation UUID")
-    first_id: UUIDStrOrEmpty | None = Field(default=None, description="First message ID for pagination")
-    limit: int = Field(default=20, ge=1, le=100, description="Number of messages to return (1-100)")
+    conversation_id: UUIDStrOrEmpty = Field(description="Conversation ID.")
+    first_id: UUIDStrOrEmpty | None = Field(
+        default=None,
+        description=(
+            "The ID of the first chat record on the current page. Omit this value to fetch the latest messages; "
+            "for subsequent pages, use the first message ID from the current list to fetch older messages."
+        ),
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Number of chat history messages to return per request.",
+    )
 
 
 class MessageFeedbackPayload(BaseModel):
-    rating: Literal["like", "dislike"] | None = None
-    content: str | None = None
+    rating: Literal["like", "dislike"] | None = Field(
+        default=None,
+        description="Feedback rating. Set to `null` to revoke previously submitted feedback.",
+    )
+    content: str | None = Field(default=None, description="Optional text feedback providing additional detail.")
 
 
 # --- Saved message schemas ---
@@ -48,6 +108,39 @@ class SavedMessageCreatePayload(BaseModel):
 
 # --- Workflow schemas ---
 
+WORKFLOW_INPUT_FILE_ITEM_SCHEMA: dict[str, object] = {
+    "type": "object",
+    "required": ["type", "transfer_method"],
+    "properties": {
+        "type": {
+            "description": "File type.",
+            "enum": ["document", "image", "audio", "video", "custom"],
+            "type": "string",
+        },
+        "transfer_method": {
+            "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file.",
+            "enum": ["remote_url", "local_file"],
+            "type": "string",
+        },
+        "url": {
+            "description": "File URL when `transfer_method` is `remote_url`.",
+            "format": "url",
+            "type": "string",
+        },
+        "upload_file_id": {
+            "description": (
+                "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API when "
+                "`transfer_method` is `local_file`."
+            ),
+            "type": "string",
+        },
+    },
+}
+WORKFLOW_INPUT_FILE_LIST_SCHEMA: dict[str, object] = {
+    "anyOf": [{"items": WORKFLOW_INPUT_FILE_ITEM_SCHEMA, "type": "array"}, {"type": "null"}]
+}
+WorkflowInputFileList = Annotated[list[dict[str, Any]] | None, WithJsonSchema(WORKFLOW_INPUT_FILE_LIST_SCHEMA)]
+
 
 class DefaultBlockConfigQuery(BaseModel):
     q: str | None = None
@@ -61,8 +154,22 @@ class WorkflowListQuery(BaseModel):
 
 
 class WorkflowRunPayload(BaseModel):
-    inputs: dict[str, Any]
-    files: list[dict[str, Any]] | None = Field(default=None)
+    inputs: dict[str, Any] = Field(
+        description=(
+            "Key-value pairs for workflow input variables. Values for file-type variables should be arrays of "
+            "file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the "
+            "`user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) "
+            "response to discover the variable names and types expected by your app."
+        )
+    )
+    files: WorkflowInputFileList = Field(
+        default=None,
+        description=(
+            "File list for workflow system file inputs. Available when file upload is enabled for the workflow. "
+            "To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use "
+            "the returned `id` as `upload_file_id` with `transfer_method: local_file`."
+        ),
+    )
 
 
 class WorkflowUpdatePayload(BaseModel):
@@ -77,28 +184,49 @@ DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS = 100
 
 
 class ChildChunkCreatePayload(BaseModel):
-    content: str
+    content: str = Field(description="Child chunk text content.")
 
 
 class ChildChunkUpdatePayload(BaseModel):
-    content: str
+    content: str = Field(description="Child chunk text content.")
 
 
 class DocumentBatchDownloadZipPayload(BaseModel):
     """Request payload for bulk downloading documents as a zip archive."""
 
-    document_ids: list[UUID] = Field(..., min_length=1, max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS)
+    document_ids: list[UUID] = Field(
+        ...,
+        min_length=1,
+        max_length=DOCUMENT_BATCH_DOWNLOAD_ZIP_MAX_DOCS,
+        description="List of document IDs to include in the ZIP download.",
+    )
 
 
 class MetadataUpdatePayload(BaseModel):
-    name: str
+    name: str = Field(description="New metadata field name.")
 
 
 # --- Audio schemas ---
 
 
+UUIDString = Annotated[str, WithJsonSchema({"format": "uuid", "type": "string"})]
+
+
 class TextToAudioPayload(BaseModel):
-    message_id: str | None = Field(default=None, description="Message ID")
-    voice: str | None = Field(default=None, description="Voice to use for TTS")
-    text: str | None = Field(default=None, description="Text to convert to audio")
-    streaming: bool | None = Field(default=None, description="Enable streaming response")
+    message_id: UUIDString | None = Field(
+        default=None,
+        description="Message ID. Takes priority over `text` when both are provided.",
+    )
+    voice: str | None = Field(
+        default=None,
+        description=(
+            "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. "
+            "Omit to use the app's configured voice when available; that value is exposed by "
+            "[Get App Parameters](/api-reference/applications/get-app-parameters) as `text_to_speech.voice`."
+        ),
+    )
+    text: str | None = Field(default=None, description="Speech content to convert.")
+    streaming: bool | None = Field(
+        default=None,
+        description="Reserved for compatibility; TTS response streaming is determined by the provider output.",
+    )

api/controllers/common/fields.py

@@ -153,6 +153,7 @@ class ApiBaseUrlResponse(ResponseModel):
 
 class NewAppResponse(ResponseModel):
     new_app_id: str
+    permission_keys: list[str] = Field(default_factory=list)
 
 
 class Parameters(BaseModel):

api/controllers/common/human_input.py

@@ -35,17 +35,23 @@ class HumanInputFormSubmitPayload(BaseModel):
         ),
         examples=[HUMAN_INPUT_FORM_INPUT_EXAMPLE],
     )
-    action: str
+    action: str = Field(
+        description=(
+            "ID of the action button the recipient selected. Must match one of the `id` values from the form's "
+            "`user_actions` list."
+        )
+    )
 
 
 def stringify_form_default_values(values: dict[str, object]) -> dict[str, str]:
     """Serialize default values into strings expected by human-input form clients."""
     result: dict[str, str] = {}
     for key, value in values.items():
-        if value is None:
-            result[key] = ""
-        elif isinstance(value, (dict, list)):
-            result[key] = json.dumps(value, ensure_ascii=False)
-        else:
-            result[key] = str(value)
+        match value:
+            case None:
+                result[key] = ""
+            case dict() | list():
+                result[key] = json.dumps(value, ensure_ascii=False)
+            case _:
+                result[key] = str(value)
     return result

api/controllers/common/wraps.py

@@ -1,7 +1,36 @@
+"""Shared decorator utilities for Dify controller layers.
+
+This module provides decorators that are not tied to any single API group (e.g.
+console, inner, service).  Currently it exposes the RBAC permission gate, which
+can be applied to any blueprint.
+
+Key exports
+-----------
+``rbac_permission_required`` – decorator that enforces enterprise RBAC access
+    control.  When ``RBAC_ENABLED`` is ``False`` it is a no-op.
+
+``RBACPermission``, ``RBACResourceScope`` – re-exported from ``core.rbac`` so
+    callers only need a single import site.
+
+Private helpers
+---------------
+``_extract_resource_id``, ``_is_resource_owned_by_current_user`` – kept module-
+    private but accessible via the module namespace for unit-test patching.
+"""
+
 from collections.abc import Callable
 from functools import wraps
 
+from sqlalchemy import select
+from werkzeug.exceptions import Forbidden, NotFound
+
+from configs import dify_config
 from core.rbac import RBACPermission, RBACResourceScope
+from extensions.ext_database import db
+from libs.login import current_account_with_tenant
+from models.dataset import Dataset
+from models.model import App
+from services.enterprise.rbac_service import RBACService
 
 __all__ = ["RBACPermission", "RBACResourceScope", "rbac_permission_required"]
 
@@ -14,17 +43,105 @@ def rbac_permission_required[**P, R](
 ) -> Callable[[Callable[P, R]], Callable[P, R]]:
     """Check enterprise RBAC permissions for the current user.
 
+    When ``RBAC_ENABLED`` is ``False`` the decorator is a no-op and the
+    request passes through unchanged. When enabled it extracts the resource ID
+    from ``request.view_args`` for resource-scoped checks, calls the RBAC
+    service ``check-access`` endpoint, and raises ``Forbidden`` if the access
+    is denied. For workspace-level checks, set ``resource_required=False`` so
+    the RBAC request omits ``resource_id``.
+
     Args:
         resource_type: The :class:`RBACResourceScope` member (app/dataset/workspace).
-        scene: The :class:`RBACPermission` permission point.
+        scene: The :class:`RBACPermission` permission point, e.g. ``RBACPermission.APP_DELETE``.
         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:
+            if not dify_config.RBAC_ENABLED:
+                return view(*args, **kwargs)
+
+            current_user, current_tenant_id = current_account_with_tenant()
+            check_resource_type = None if resource_type == RBACResourceScope.WORKSPACE else resource_type
+            resource_id = None
+            if resource_required and check_resource_type:
+                resource_id = _extract_resource_id(resource_type, kwargs)
+                if _is_resource_owned_by_current_user(current_tenant_id, current_user.id, resource_type, resource_id):
+                    return view(*args, **kwargs)
+            allowed = RBACService.CheckAccess.check(
+                current_tenant_id,
+                current_user.id,
+                scene=scene,
+                resource_type=check_resource_type,
+                resource_id=resource_id,
+            )
+
+            if not allowed:
+                raise Forbidden()
+
             return view(*args, **kwargs)
 
         return decorated
 
     return decorator
+
+
+def _is_resource_owned_by_current_user(
+    tenant_id: str, account_id: str, resource_type: RBACResourceScope, resource_id: str
+) -> bool:
+    if resource_type == RBACResourceScope.APP:
+        maintainer = db.session.scalar(
+            select(App.maintainer).where(
+                App.id == resource_id,
+                App.tenant_id == tenant_id,
+                App.status == "normal",
+            )
+        )
+        return maintainer == account_id
+
+    if resource_type == RBACResourceScope.DATASET:
+        maintainer = db.session.scalar(
+            select(Dataset.maintainer).where(
+                Dataset.id == resource_id,
+                Dataset.tenant_id == tenant_id,
+            )
+        )
+        return maintainer == account_id
+
+    return False
+
+
+def _extract_resource_id(resource_type: RBACResourceScope, path_args: dict[str, object] | None = None) -> str:
+    """Extract the resource ID from matched path arguments.
+
+    Some legacy route classes use neutral names such as ``resource_id`` for
+    app/dataset resources, and Agent App routes use ``agent_id`` as the app id.
+    Dataset endpoints behind a rag-pipeline route contain ``pipeline_id``
+    instead of ``dataset_id``. In that case we look up the associated
+    ``Dataset`` row via ``Dataset.pipeline_id``.
+    """
+    from flask import request
+
+    view_args = request.view_args or {}
+    matched_args = {**view_args, **(path_args or {})}
+
+    if resource_type == RBACResourceScope.APP:
+        app_id = matched_args.get("app_id") or matched_args.get("agent_id") or matched_args.get("resource_id")
+        if not app_id:
+            raise ValueError("Missing app_id in request path")
+        return str(app_id)
+
+    if resource_type == RBACResourceScope.DATASET:
+        dataset_id = matched_args.get("dataset_id") or matched_args.get("resource_id")
+        if dataset_id:
+            return str(dataset_id)
+
+        pipeline_id = matched_args.get("pipeline_id")
+        if pipeline_id:
+            dataset = db.session.scalar(select(Dataset).where(Dataset.pipeline_id == str(pipeline_id)))
+            if not dataset:
+                raise NotFound("Dataset not found for pipeline")
+            return str(dataset.id)
+        raise ValueError("Missing dataset_id or pipeline_id in request path")
+    raise ValueError(f"Unknown resource_type: {resource_type}")

api/controllers/console/__init__.py

@@ -139,6 +139,7 @@ from .workspace import (
     model_providers,
     models,
     plugin,
+    rbac,
     snippets,
     tool_providers,
     trigger_providers,
@@ -212,6 +213,7 @@ __all__ = [
     "rag_pipeline_draft_variable",
     "rag_pipeline_import",
     "rag_pipeline_workflow",
+    "rbac",
     "recommended_app",
     "saved_message",
     "setup",

api/controllers/console/agent/app_helpers.py

@@ -0,0 +1,10 @@
+from uuid import UUID
+
+from extensions.ext_database import db
+from models.model import App
+from services.agent.roster_service import AgentRosterService
+
+
+def resolve_agent_app_model(*, tenant_id: str, agent_id: UUID) -> App:
+    """Resolve the hidden Agent App backing an Agent Console resource."""
+    return AgentRosterService(db.session).get_agent_app_model(tenant_id=tenant_id, agent_id=str(agent_id))

api/controllers/console/agent/composer.py

@@ -1,11 +1,17 @@
+from uuid import UUID
+
 from flask_restx import Resource
 
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user_id,
@@ -35,6 +41,10 @@ register_response_schema_models(
 )
 
 
+def _resolve_agent_app_id(*, tenant_id: str, agent_id: UUID) -> str:
+    return resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id).id
+
+
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/nodes/<string:node_id>/agent-composer")
 class WorkflowAgentComposerApi(Resource):
     @console_ns.response(
@@ -63,6 +73,7 @@ class WorkflowAgentComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_user_id
     @with_current_tenant_id
@@ -159,6 +170,7 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @get_app_model(mode=[AppMode.WORKFLOW, AppMode.ADVANCED_CHAT])
     @with_current_user_id
     @with_current_tenant_id
@@ -176,18 +188,18 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
         )
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-composer")
-class AgentAppComposerApi(Resource):
+@console_ns.route("/agent/<uuid:agent_id>/composer")
+class AgentComposerApi(Resource):
     @console_ns.response(200, "Agent app composer state", console_ns.models[AgentAppComposerResponse.__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):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_id = _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         return dump_response(
             AgentAppComposerResponse,
-            AgentComposerService.load_agent_app_composer(tenant_id=tenant_id, app_id=app_model.id),
+            AgentComposerService.load_agent_app_composer(tenant_id=tenant_id, app_id=app_id),
         )
 
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
@@ -196,24 +208,25 @@ class AgentAppComposerApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @get_app_model(mode=[AppMode.AGENT])
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user_id
     @with_current_tenant_id
-    def put(self, tenant_id: str, account_id: str, app_model: App):
+    def put(self, tenant_id: str, account_id: str, agent_id: UUID):
+        app_id = _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         return dump_response(
             AgentAppComposerResponse,
             AgentComposerService.save_agent_app_composer(
                 tenant_id=tenant_id,
-                app_id=app_model.id,
+                app_id=app_id,
                 account_id=account_id,
                 payload=payload,
             ),
         )
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-composer/validate")
-class AgentAppComposerValidateApi(Resource):
+@console_ns.route("/agent/<uuid:agent_id>/composer/validate")
+class AgentComposerValidateApi(Resource):
     @console_ns.expect(console_ns.models[ComposerSavePayload.__name__])
     @console_ns.response(
         200, "Agent app composer validation result", console_ns.models[AgentComposerValidateResponse.__name__]
@@ -221,36 +234,36 @@ class AgentAppComposerValidateApi(Resource):
     @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):
+    def post(self, tenant_id: str, agent_id: UUID):
+        _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         payload = ComposerSavePayload.model_validate(console_ns.payload or {})
         ComposerConfigValidator.validate_save_payload(payload)
         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),
+            agent_id=str(agent_id),
         )
         return dump_response(AgentComposerValidateResponse, {"result": "success", "errors": [], **findings})
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-composer/candidates")
-class AgentAppComposerCandidatesApi(Resource):
+@console_ns.route("/agent/<uuid:agent_id>/composer/candidates")
+class AgentComposerCandidatesApi(Resource):
     @console_ns.response(
         200, "Agent app composer candidates", console_ns.models[AgentComposerCandidatesResponse.__name__]
     )
     @setup_required
     @login_required
     @account_initialization_required
-    @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):
+    def get(self, tenant_id: str, current_user_id: str, agent_id: UUID):
+        app_id = _resolve_agent_app_id(tenant_id=tenant_id, agent_id=agent_id)
         return dump_response(
             AgentComposerCandidatesResponse,
             AgentComposerService.get_agent_app_candidates(
                 tenant_id=tenant_id,
-                app_id=app_model.id,
+                app_id=app_id,
                 user_id=current_user_id,
             ),
         )

api/controllers/console/agent/roster.py

@@ -1,29 +1,65 @@
 from uuid import UUID
 
-from flask import request
+from flask import abort, request
 from flask_restx import Resource
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, Field, field_validator
 
 from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
+from controllers.console.app.app import (
+    AppDetailWithSite as GenericAppDetailWithSite,
+)
+from controllers.console.app.app import (
+    AppListQuery,
+    CopyAppPayload,
+    _normalize_app_list_query_args,
+)
+from controllers.console.app.app import (
+    AppPagination as GenericAppPagination,
+)
+from controllers.console.app.app import (
+    AppPartial as GenericAppPartial,
+)
+from controllers.console.app.app import (
+    UpdateAppPayload as GenericUpdateAppPayload,
+)
 from controllers.console.wraps import (
     account_initialization_required,
+    edit_permission_required,
+    enterprise_license_required,
     setup_required,
     with_current_tenant_id,
+    with_current_user,
 )
 from extensions.ext_database import db
 from fields.agent_fields import (
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
+    AgentLogListResponse,
+    AgentLogMessageListResponse,
+    AgentLogSourceListResponse,
     AgentPublishedReferenceResponse,
     AgentRosterListResponse,
-    AgentRosterResponse,
+    AgentStatisticSummaryEnvelopeResponse,
 )
+from libs.datetime_utils import parse_time_range
 from libs.helper import dump_response
 from libs.login import login_required
+from models import Account
+from models.model import IconType
+from services.agent.errors import AgentNotFoundError
+from services.agent.observability_service import (
+    AgentLogQueryParams,
+    AgentObservabilityService,
+    AgentStatisticsQueryParams,
+)
 from services.agent.roster_service import AgentRosterService
+from services.app_service import AppListParams, AppService, CreateAppParams
+from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.agent_entities import RosterListQuery
+from services.feature_service import FeatureService
 
 
 class AgentInviteOptionsQuery(RosterListQuery):
@@ -34,20 +70,166 @@ class AgentIdPath(BaseModel):
     agent_id: str
 
 
+class AgentAppCreatePayload(BaseModel):
+    name: str = Field(..., min_length=1, description="Agent name")
+    description: str | None = Field(default=None, description="Agent description (max 400 chars)", max_length=400)
+    role: str = Field(..., min_length=1, description="Agent role", max_length=255)
+    icon_type: IconType | None = Field(default=None, description="Icon type")
+    icon: str | None = Field(default=None, description="Icon")
+    icon_background: str | None = Field(default=None, description="Icon background color")
+
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, value: str) -> str:
+        role = value.strip()
+        if not role:
+            raise ValueError("Agent role is required.")
+        return role
+
+
+# Keep agent-app roster DTOs agent-specific instead of reusing the shared
+# /apps response/request models. The roster surface needs Agent-only fields such
+# as `role`, while the generic console/apps contracts must stay unchanged.
+class AgentAppUpdatePayload(GenericUpdateAppPayload):
+    role: str = Field(..., min_length=1, description="Agent role", max_length=255)
+
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, value: str) -> str:
+        role = value.strip()
+        if not role:
+            raise ValueError("Agent role is required.")
+        return role
+
+
+class AgentAppPublishedReferenceResponse(BaseModel):
+    app_id: str
+    app_name: str
+    app_icon_type: str | None = None
+    app_icon: str | None = None
+    app_icon_background: str | None = None
+
+
+class AgentLogsQuery(BaseModel):
+    page: int = Field(default=1, ge=1, description="Page number")
+    limit: int = Field(default=20, ge=1, le=100, description="Page size")
+    keyword: str | None = Field(default=None, description="Search query, answer, or conversation name")
+    status: str | None = Field(default=None, description="Deprecated single status filter")
+    statuses: list[str] = Field(default_factory=list, description="Filter by one or more of success, failed, paused")
+    source: str | None = Field(
+        default=None,
+        description="Deprecated single source filter",
+    )
+    sources: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Filter by one or more source IDs, e.g. webapp:<app_id> "
+            "or workflow:<app_id>:<workflow_id>:<version>:<node_id>"
+        ),
+    )
+    sort_by: str = Field(default="updated_at", description="Sort by created_at or updated_at")
+    sort_order: str = Field(default="desc", description="Sort order: asc or desc")
+    start: str | None = Field(default=None, description="Start date (YYYY-MM-DD HH:MM)")
+    end: str | None = Field(default=None, description="End date (YYYY-MM-DD HH:MM)")
+
+    @field_validator("keyword", "status", "source", "start", "end", mode="before")
+    @classmethod
+    def empty_string_to_none(cls, value: str | None) -> str | None:
+        if value == "":
+            return None
+        return value
+
+    @field_validator("statuses", "sources", mode="before")
+    @classmethod
+    def empty_list_values_to_list(cls, value: object) -> list[str]:
+        if value in (None, ""):
+            return []
+        if isinstance(value, str):
+            return [value]
+        if isinstance(value, list):
+            return [item for item in value if item]
+        return []
+
+    @field_validator("sort_by")
+    @classmethod
+    def validate_sort_by(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in {"created_at", "updated_at"}:
+            raise ValueError("sort_by must be created_at or updated_at")
+        return normalized
+
+    @field_validator("sort_order")
+    @classmethod
+    def validate_sort_order(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in {"asc", "desc"}:
+            raise ValueError("sort_order must be asc or desc")
+        return normalized
+
+
+class AgentStatisticsQuery(BaseModel):
+    source: str | None = Field(
+        default=None,
+        description="Filter by all, console/explore, api/service-api, web-app, debugger, openapi, or trigger",
+    )
+    start: str | None = Field(default=None, description="Start date (YYYY-MM-DD HH:MM)")
+    end: str | None = Field(default=None, description="End date (YYYY-MM-DD HH:MM)")
+
+    @field_validator("source", "start", "end", mode="before")
+    @classmethod
+    def empty_string_to_none(cls, value: str | None) -> str | None:
+        if value == "":
+            return None
+        return value
+
+
+class AgentAppPartial(GenericAppPartial):
+    app_id: str | None = None
+    role: str | None = None
+    active_config_is_published: bool = False
+    published_reference_count: int = 0
+    published_references: list[AgentAppPublishedReferenceResponse] = Field(default_factory=list)
+
+
+class AgentAppDetailWithSite(GenericAppDetailWithSite):
+    app_id: str | None = None
+    role: str | None = None
+    active_config_is_published: bool = False
+
+
+class AgentAppPagination(GenericAppPagination):
+    data: list[AgentAppPartial] = Field(  # type: ignore[assignment]  # pyrefly: ignore[bad-override-mutable-attribute]
+        validation_alias=AliasChoices("items", "data")
+    )
+
+
 register_schema_models(
     console_ns,
+    AgentAppCreatePayload,
+    AgentAppUpdatePayload,
+    CopyAppPayload,
     AgentInviteOptionsQuery,
+    AgentLogsQuery,
+    AgentStatisticsQuery,
     AgentIdPath,
+    AppListQuery,
     RosterListQuery,
 )
 register_response_schema_models(
     console_ns,
+    AgentAppPagination,
+    AgentAppPublishedReferenceResponse,
+    AgentAppDetailWithSite,
+    AgentAppPartial,
     AgentConfigSnapshotDetailResponse,
     AgentConfigSnapshotListResponse,
     AgentInviteOptionsResponse,
+    AgentLogListResponse,
+    AgentLogMessageListResponse,
+    AgentLogSourceListResponse,
     AgentPublishedReferenceResponse,
     AgentRosterListResponse,
-    AgentRosterResponse,
+    AgentStatisticSummaryEnvelopeResponse,
 )
 
 
@@ -55,25 +237,249 @@ def _agent_roster_service() -> AgentRosterService:
     return AgentRosterService(db.session)
 
 
-@console_ns.route("/agents")
-class AgentRosterListApi(Resource):
-    @console_ns.doc(params=query_params_from_model(RosterListQuery))
-    @console_ns.response(200, "Agent roster list", console_ns.models[AgentRosterListResponse.__name__])
+def _serialize_agent_app_detail(app_model) -> dict:
+    """Serialize an Agent App detail using roster-only DTOs.
+
+    `/agent` responses are roster-shaped rather than raw app-shaped: `id`
+    becomes the backing roster Agent id, `app_id` carries the underlying App
+    id, and `role` is injected from the backing roster Agent. Keeping that
+    remap in this serializer lets generated console/agent contracts expose the
+    roster persona fields without widening the shared /apps detail schema.
+    """
+
+    app_model = AppService().get_app(app_model)
+    if FeatureService.get_system_features().webapp_auth.enabled:
+        app_setting = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=str(app_model.id))
+        app_model.access_mode = app_setting.access_mode  # type: ignore[attr-defined]
+
+    roster_service = _agent_roster_service()
+    payload = AgentAppDetailWithSite.model_validate(app_model, from_attributes=True).model_dump(mode="json")
+    agent = roster_service.get_app_backing_agent(tenant_id=app_model.tenant_id, app_id=str(app_model.id))
+    if not agent:
+        raise AgentNotFoundError()
+    payload.pop("bound_agent_id", None)
+    payload["app_id"] = str(app_model.id)
+    payload["id"] = agent.id
+    payload["role"] = agent.role or ""
+    payload["active_config_is_published"] = roster_service.active_config_is_published(
+        tenant_id=app_model.tenant_id,
+        agent=agent,
+    )
+    return payload
+
+
+def _serialize_agent_app_pagination(app_pagination, *, tenant_id: str) -> dict:
+    """Serialize Agent App lists with roster-shaped items.
+
+    Each item starts from the shared App list shape, then drops
+    `bound_agent_id`, rewrites `id` to the backing roster Agent id, stores the
+    original App id in `app_id`, and injects roster-only `role` when a backing
+    Agent is present.
+    """
+
+    app_ids = [str(app.id) for app in app_pagination.items]
+    roster_service = _agent_roster_service()
+    agents_by_app_id = roster_service.load_app_backing_agents_by_app_id(
+        tenant_id=tenant_id,
+        app_ids=app_ids,
+    )
+    active_config_is_published_by_agent_id = roster_service.load_active_config_is_published_by_agent_id(
+        tenant_id=tenant_id,
+        agents=list(agents_by_app_id.values()),
+    )
+    published_references_by_agent_id = roster_service.load_published_references_by_agent_id(
+        tenant_id=tenant_id,
+        agent_ids=[agent.id for agent in agents_by_app_id.values()],
+    )
+    payload = AgentAppPagination.model_validate(app_pagination, from_attributes=True).model_dump(mode="json")
+    for item in payload["data"]:
+        app_id = item["id"]
+        item.pop("bound_agent_id", None)
+        agent = agents_by_app_id.get(app_id)
+        if agent:
+            item["app_id"] = app_id
+            item["id"] = agent.id
+            item["role"] = agent.role or ""
+            item["active_config_is_published"] = active_config_is_published_by_agent_id.get(agent.id, False)
+            published_references = published_references_by_agent_id.get(agent.id, [])
+            item["published_reference_count"] = len(published_references)
+            item["published_references"] = [
+                {
+                    "app_id": reference["app_id"],
+                    "app_name": reference["app_name"],
+                    "app_icon_type": reference["app_icon_type"],
+                    "app_icon": reference["app_icon"],
+                    "app_icon_background": reference["app_icon_background"],
+                }
+                for reference in published_references
+            ]
+    return AgentAppPagination.model_validate(payload).model_dump(
+        mode="json",
+        exclude={"data": {"__all__": {"bound_agent_id"}}},
+    )
+
+
+def _resolve_agent_app_model(*, tenant_id: str, agent_id: UUID):
+    return resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+
+
+def _agent_observability_service() -> AgentObservabilityService:
+    return AgentObservabilityService(db.session)
+
+
+def _parse_observability_time_range(start: str | None, end: str | None, account: Account):
+    timezone = account.timezone or "UTC"
+    try:
+        return parse_time_range(start, end, timezone)
+    except ValueError as exc:
+        abort(400, description=str(exc))
+
+
+def _multi_query_values(name: str, legacy_name: str | None = None) -> list[str]:
+    values: list[str] = []
+    for query_name in (name, f"{name}[]"):
+        values.extend(request.args.getlist(query_name))
+    if legacy_name:
+        values.extend(request.args.getlist(legacy_name))
+    parsed: list[str] = []
+    for value in values:
+        parsed.extend(item.strip() for item in value.split(",") if item.strip())
+    return parsed
+
+
+@console_ns.route("/agent")
+class AgentAppListApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AppListQuery))
+    @console_ns.response(200, "Agent app list", console_ns.models[AgentAppPagination.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str):
-        query = RosterListQuery.model_validate(request.args.to_dict(flat=True))
-        return dump_response(
-            AgentRosterListResponse,
-            _agent_roster_service().list_roster_agents(
-                tenant_id=tenant_id, page=query.page, limit=query.limit, keyword=query.keyword
-            ),
+    def get(self, current_tenant_id: str, current_user: Account):
+        args = AppListQuery.model_validate(_normalize_app_list_query_args(request.args))
+        params = AppListParams(
+            page=args.page,
+            limit=args.limit,
+            mode="agent",
+            name=args.name,
+            tag_ids=args.tag_ids,
+            creator_ids=args.creator_ids,
+            is_created_by_me=args.is_created_by_me,
+            status="normal",
         )
 
+        app_pagination = AppService().get_paginate_apps(current_user.id, current_tenant_id, params, db.session)
+        if app_pagination is None:
+            empty = AgentAppPagination(page=args.page, limit=args.limit, total=0, has_more=False, data=[])
+            return empty.model_dump(mode="json")
 
-@console_ns.route("/agents/invite-options")
+        return _serialize_agent_app_pagination(app_pagination, tenant_id=current_tenant_id)
+
+    @console_ns.expect(console_ns.models[AgentAppCreatePayload.__name__])
+    @console_ns.response(201, "Agent app created successfully", console_ns.models[AgentAppDetailWithSite.__name__])
+    @console_ns.response(403, "Insufficient permissions")
+    @console_ns.response(400, "Invalid request parameters")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account):
+        args = AgentAppCreatePayload.model_validate(console_ns.payload)
+        params = CreateAppParams(
+            name=args.name,
+            description=args.description,
+            mode="agent",
+            agent_role=args.role,
+            icon_type=args.icon_type,
+            icon=args.icon,
+            icon_background=args.icon_background,
+        )
+
+        app = AppService().create_app(current_tenant_id, params, current_user)
+        return _serialize_agent_app_detail(app), 201
+
+
+@console_ns.route("/agent/<uuid:agent_id>")
+class AgentAppApi(Resource):
+    @console_ns.response(200, "Agent app detail", console_ns.models[AgentAppDetailWithSite.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _serialize_agent_app_detail(app_model)
+
+    @console_ns.expect(console_ns.models[AgentAppUpdatePayload.__name__])
+    @console_ns.response(200, "Agent app updated successfully", console_ns.models[AgentAppDetailWithSite.__name__])
+    @console_ns.response(403, "Insufficient permissions")
+    @console_ns.response(400, "Invalid request parameters")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def put(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        args = AgentAppUpdatePayload.model_validate(console_ns.payload)
+        args_dict: AppService.ArgsDict = {
+            "name": args.name,
+            "description": args.description or "",
+            "icon_type": args.icon_type,
+            "icon": args.icon or "",
+            "icon_background": args.icon_background or "",
+            "use_icon_as_answer_icon": args.use_icon_as_answer_icon or False,
+            "max_active_requests": args.max_active_requests or 0,
+            "role": args.role,
+        }
+        updated = AppService().update_app(app_model, args_dict)
+        return _serialize_agent_app_detail(updated)
+
+    @console_ns.response(204, "Agent app deleted successfully")
+    @console_ns.response(403, "Insufficient permissions")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        AppService().delete_app(app_model)
+        return "", 204
+
+
+@console_ns.route("/agent/<uuid:agent_id>/copy")
+class AgentAppCopyApi(Resource):
+    @console_ns.expect(console_ns.models[CopyAppPayload.__name__])
+    @console_ns.response(201, "Agent app copied successfully", console_ns.models[AgentAppDetailWithSite.__name__])
+    @console_ns.response(403, "Insufficient permissions")
+    @console_ns.response(400, "Invalid request parameters")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        args = CopyAppPayload.model_validate(console_ns.payload or {})
+        copied_app = _agent_roster_service().duplicate_agent_app(
+            tenant_id=tenant_id,
+            agent_id=str(agent_id),
+            account=current_user,
+            name=args.name,
+            description=args.description,
+            icon_type=args.icon_type,
+            icon=args.icon,
+            icon_background=args.icon_background,
+        )
+        return _serialize_agent_app_detail(copied_app), 201
+
+
+@console_ns.route("/agent/invite-options")
 class AgentInviteOptionsApi(Resource):
     @console_ns.doc(params=query_params_from_model(AgentInviteOptionsQuery))
     @console_ns.response(200, "Agent invite options", console_ns.models[AgentInviteOptionsResponse.__name__])
@@ -95,21 +501,125 @@ class AgentInviteOptionsApi(Resource):
         )
 
 
-@console_ns.route("/agents/<uuid:agent_id>")
-class AgentRosterDetailApi(Resource):
-    @console_ns.response(200, "Agent detail", console_ns.models[AgentRosterResponse.__name__])
+@console_ns.route("/agent/<uuid:agent_id>/logs")
+class AgentLogsApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentLogsQuery))
+    @console_ns.response(200, "Agent logs", console_ns.models[AgentLogListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
+    @with_current_user
     @with_current_tenant_id
-    def get(self, tenant_id: str, agent_id: UUID):
-        return dump_response(
-            AgentRosterResponse,
-            _agent_roster_service().get_roster_agent_detail(tenant_id=tenant_id, agent_id=str(agent_id)),
-        )
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        query_data: dict[str, object] = dict(request.args.to_dict(flat=True))
+        query_data["sources"] = _multi_query_values("sources", "source")
+        query_data["statuses"] = _multi_query_values("statuses", "status")
+        query = AgentLogsQuery.model_validate(query_data)
+        start, end = _parse_observability_time_range(query.start, query.end, current_user)
+        try:
+            payload = _agent_observability_service().list_logs(
+                app=app_model,
+                agent_id=str(agent_id),
+                params=AgentLogQueryParams(
+                    page=query.page,
+                    limit=query.limit,
+                    keyword=query.keyword,
+                    statuses=tuple(query.statuses),
+                    sources=tuple(query.sources),
+                    sort_by=query.sort_by,
+                    sort_order=query.sort_order,
+                    start=start,
+                    end=end,
+                ),
+            )
+        except ValueError as exc:
+            abort(400, description=str(exc))
+        return dump_response(AgentLogListResponse, payload)
 
 
-@console_ns.route("/agents/<uuid:agent_id>/versions")
+@console_ns.route("/agent/<uuid:agent_id>/logs/<uuid:conversation_id>/messages")
+class AgentLogMessagesApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentLogsQuery))
+    @console_ns.response(200, "Agent log messages", console_ns.models[AgentLogMessageListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID, conversation_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        query_data: dict[str, object] = dict(request.args.to_dict(flat=True))
+        query_data["sources"] = _multi_query_values("sources", "source")
+        query_data["statuses"] = _multi_query_values("statuses", "status")
+        query = AgentLogsQuery.model_validate(query_data)
+        start, end = _parse_observability_time_range(query.start, query.end, current_user)
+        try:
+            payload = _agent_observability_service().list_log_messages(
+                app=app_model,
+                agent_id=str(agent_id),
+                conversation_id=str(conversation_id),
+                params=AgentLogQueryParams(
+                    page=query.page,
+                    limit=query.limit,
+                    keyword=query.keyword,
+                    statuses=tuple(query.statuses),
+                    sources=tuple(query.sources),
+                    sort_by=query.sort_by,
+                    sort_order=query.sort_order,
+                    start=start,
+                    end=end,
+                ),
+            )
+        except ValueError as exc:
+            abort(400, description=str(exc))
+        return dump_response(AgentLogMessageListResponse, payload)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/log-sources")
+class AgentLogSourcesApi(Resource):
+    @console_ns.response(200, "Agent log sources", console_ns.models[AgentLogSourceListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        payload = _agent_observability_service().list_log_sources(app=app_model, agent_id=str(agent_id))
+        return dump_response(AgentLogSourceListResponse, payload)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/statistics/summary")
+class AgentStatisticsSummaryApi(Resource):
+    @console_ns.doc(params=query_params_from_model(AgentStatisticsQuery))
+    @console_ns.response(
+        200,
+        "Agent monitoring summary and chart data",
+        console_ns.models[AgentStatisticSummaryEnvelopeResponse.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = _resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        query = AgentStatisticsQuery.model_validate(request.args.to_dict(flat=True))
+        timezone = current_user.timezone or "UTC"
+        start, end = _parse_observability_time_range(query.start, query.end, current_user)
+        try:
+            payload = _agent_observability_service().get_statistics_summary(
+                app=app_model,
+                agent_id=str(agent_id),
+                params=AgentStatisticsQueryParams(source=query.source, start=start, end=end, timezone=timezone),
+            )
+        except ValueError as exc:
+            abort(400, description=str(exc))
+        return dump_response(AgentStatisticSummaryEnvelopeResponse, payload)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/versions")
 class AgentRosterVersionsApi(Resource):
     @console_ns.response(200, "Agent versions", console_ns.models[AgentConfigSnapshotListResponse.__name__])
     @setup_required
@@ -123,7 +633,7 @@ class AgentRosterVersionsApi(Resource):
         )
 
 
-@console_ns.route("/agents/<uuid:agent_id>/versions/<uuid:version_id>")
+@console_ns.route("/agent/<uuid:agent_id>/versions/<uuid:version_id>")
 class AgentRosterVersionDetailApi(Resource):
     @console_ns.response(200, "Agent version detail", console_ns.models[AgentConfigSnapshotDetailResponse.__name__])
     @setup_required

api/controllers/console/apikey.py

@@ -9,6 +9,7 @@ from sqlalchemy import delete, func, select
 from sqlalchemy.orm import sessionmaker
 from werkzeug.exceptions import Forbidden
 
+from configs import dify_config
 from controllers.common.schema import register_response_schema_models
 from extensions.ext_database import db
 from fields.base import ResponseModel
@@ -22,8 +23,11 @@ from services.api_token_service import ApiTokenCache
 
 from . import console_ns
 from .wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user,
@@ -143,7 +147,7 @@ class BaseApiKeyResource(Resource):
         assert self.resource_id_field is not None, "resource_id_field must be set"
         _get_resource(resource_id, current_tenant_id, self.resource_model)
 
-        if not current_user.is_admin_or_owner:
+        if not dify_config.RBAC_ENABLED and not current_user.is_admin_or_owner:
             raise Forbidden()
 
         key = db.session.scalar(
@@ -186,6 +190,7 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     def post(self, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for an app"""
         return dump_response(ApiKeyItem, self._create_api_key(str(resource_id), current_tenant_id)), 201
@@ -204,6 +209,7 @@ class AppApiKeyResource(BaseApiKeyResource):
     @console_ns.response(204, "API key deleted successfully")
     @with_current_user
     @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     def delete(
         self, current_tenant_id: str, current_user: Account, resource_id: UUID, api_key_id: UUID
     ) -> tuple[str, int]:
@@ -234,6 +240,7 @@ class DatasetApiKeyListResource(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
     def post(self, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for a dataset"""
         return dump_response(ApiKeyItem, self._create_api_key(str(resource_id), current_tenant_id)), 201
@@ -252,6 +259,7 @@ class DatasetApiKeyResource(BaseApiKeyResource):
     @console_ns.response(204, "API key deleted successfully")
     @with_current_user
     @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_API_KEY_MANAGE)
     def delete(
         self, current_tenant_id: str, current_user: Account, resource_id: UUID, api_key_id: UUID
     ) -> tuple[str, int]:

api/controllers/console/app/agent.py

@@ -1,5 +1,6 @@
 import logging
 from typing import Any
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -13,8 +14,17 @@ from controllers.common.schema import (
     register_schema_models,
 )
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required, with_current_user
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+    with_current_tenant_id,
+    with_current_user,
+)
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import uuid_value
@@ -23,7 +33,7 @@ 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_package_service import SkillManifest, SkillPackageError
 from services.agent.skill_standardize_service import SkillStandardizeService
 from services.agent.skill_tool_inference_service import (
     SkillToolInferenceError,
@@ -38,11 +48,18 @@ from services.agent_drive_service import (
     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]
+_WORKFLOW_AGENT_DRIVE_APP_MODES = [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
+_AGENT_SKILL_UPLOAD_PARAMS = {
+    "file": {
+        "in": "formData",
+        "type": "file",
+        "required": True,
+        "description": "Skill package (.zip or .skill).",
+    }
+}
 
 
 class AgentLogQuery(BaseModel):
@@ -72,6 +89,10 @@ class AgentDriveDeleteFileQuery(AgentDriveMutationQuery):
     key: str = Field(min_length=1, description="Drive key, e.g. files/sample.pdf")
 
 
+class AgentDriveDeleteFileByAgentQuery(BaseModel):
+    key: str = Field(min_length=1, description="Drive key, e.g. files/sample.pdf")
+
+
 class AgentLogMetaResponse(ResponseModel):
     status: str
     executor: str
@@ -114,11 +135,6 @@ class AgentSkillUploadResponse(ResponseModel):
     manifest: SkillManifest
 
 
-class AgentSkillStandardizeResponse(ResponseModel):
-    skill: AgentSkillRefConfig
-    manifest: SkillManifest
-
-
 class AgentDriveFileResponse(ResponseModel):
     name: str
     drive_key: str
@@ -138,21 +154,20 @@ class AgentDriveDeleteResponse(ResponseModel):
     config_version_id: str | None = None
 
 
-register_schema_models(console_ns, AgentLogQuery, AgentDriveFilePayload)
+register_schema_models(console_ns, AgentLogQuery, AgentDriveFilePayload, AgentDriveDeleteFileByAgentQuery)
 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:
+    if node_id and app_model.mode != AppMode.AGENT:
         return AgentComposerService.resolve_workflow_node_agent_id(
             tenant_id=app_model.tenant_id, app_id=app_model.id, node_id=node_id
         )
@@ -163,6 +178,171 @@ def _agent_not_bound() -> tuple[dict[str, str], int]:
     return {"code": "agent_not_bound", "message": "no agent is bound for this app/node"}, 400
 
 
+def _upload_skill_for_app(*, current_user: Account, app_model: App):
+    """Upload one skill package and commit its normalized files into the agent 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
+
+
+def _commit_drive_file_for_app(*, current_user: Account, app_model: App, allow_node_id: bool = True):
+    query = query_params_from_request(AgentDriveMutationQuery)
+    node_id = query.node_id if allow_node_id else None
+    agent_id = _resolve_agent_id(app_model, 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=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
+
+
+def _delete_drive_file_for_app(*, current_user: Account, app_model: App, allow_node_id: bool = True):
+    query = query_params_from_request(AgentDriveDeleteFileQuery)
+    node_id = query.node_id if allow_node_id else None
+    agent_id = _resolve_agent_id(app_model, 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=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}
+
+
+def _delete_skill_for_app(*, current_user: Account, app_model: App, slug: str, allow_node_id: bool = True):
+    query = query_params_from_request(AgentDriveMutationQuery)
+    node_id = query.node_id if allow_node_id else None
+    agent_id = _resolve_agent_id(app_model, 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=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}
+
+
+def _infer_skill_tools_for_app(*, 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
+    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
+
+
 @console_ns.route("/apps/<uuid:app_id>/agent/logs")
 class AgentLogApi(Resource):
     @console_ns.doc("get_agent_logs")
@@ -174,6 +354,7 @@ class AgentLogApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=[AppMode.AGENT_CHAT])
     def get(self, app_model: App):
         """Get agent logs"""
@@ -182,86 +363,77 @@ class AgentLogApi(Resource):
         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.route("/agent/<uuid:agent_id>/skills/upload")
+class AgentSkillUploadByAgentApi(Resource):
+    @console_ns.doc("upload_agent_skill_by_agent")
+    @console_ns.doc(description="Upload + standardize a Skill into an Agent App drive")
+    @console_ns.doc(consumes=["multipart/form-data"], params={"agent_id": "Agent ID", **_AGENT_SKILL_UPLOAD_PARAMS})
+    @console_ns.response(201, "Skill uploaded into drive", console_ns.models[AgentSkillUploadResponse.__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
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _upload_skill_for_app(current_user=current_user, app_model=app_model)
+
+
+@console_ns.route("/apps/<uuid:app_id>/agent/skills/upload")
+class AgentSkillUploadApi(Resource):
+    @console_ns.doc("upload_agent_skill")
+    @console_ns.doc(description="Upload + standardize a Skill into the agent drive")
+    @console_ns.doc(
+        consumes=["multipart/form-data"],
+        params={
+            "app_id": "Application ID",
+            **query_params_from_model(AgentDriveMutationQuery),
+            **_AGENT_SKILL_UPLOAD_PARAMS,
+        },
+    )
+    @console_ns.response(201, "Skill uploaded into drive", console_ns.models[AgentSkillUploadResponse.__name__])
+    @console_ns.response(400, "Invalid skill package or no bound agent")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=_WORKFLOW_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 a Skill, validate it, and commit drive-backed skill files."""
+        return _upload_skill_for_app(current_user=current_user, app_model=app_model)
 
-        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("/agent/<uuid:agent_id>/files")
+class AgentDriveFilesByAgentApi(Resource):
+    @console_ns.doc("commit_agent_drive_file_by_agent")
+    @console_ns.doc(description="Commit an uploaded file into the Agent App drive under files/<name>")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @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
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _commit_drive_file_for_app(current_user=current_user, app_model=app_model, allow_node_id=False)
+
+    @console_ns.doc("delete_agent_drive_file_by_agent")
+    @console_ns.doc(description="Delete one Agent App drive file by key")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveDeleteFileByAgentQuery)})
+    @console_ns.response(200, "File removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _delete_drive_file_for_app(current_user=current_user, app_model=app_model, allow_node_id=False)
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/files")
@@ -276,73 +448,11 @@ class AgentDriveFilesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_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
+        return _commit_drive_file_for_app(current_user=current_user, app_model=app_model)
 
     @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)")
@@ -351,36 +461,26 @@ class AgentDriveFilesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_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
+        return _delete_drive_file_for_app(current_user=current_user, app_model=app_model)
 
-        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("/agent/<uuid:agent_id>/skills/<string:slug>")
+class AgentSkillByAgentApi(Resource):
+    @console_ns.doc("delete_agent_skill_by_agent")
+    @console_ns.doc(description="Delete a standardized skill from an Agent App drive")
+    @console_ns.doc(params={"agent_id": "Agent ID", "slug": "Skill slug (single path segment)"})
+    @console_ns.response(200, "Skill removed", console_ns.models[AgentDriveDeleteResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, current_user: Account, agent_id: UUID, slug: str):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _delete_skill_for_app(current_user=current_user, app_model=app_model, slug=slug, allow_node_id=False)
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>")
@@ -400,34 +500,29 @@ class AgentSkillApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_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
+        return _delete_skill_for_app(current_user=current_user, app_model=app_model, slug=slug)
 
-        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("/agent/<uuid:agent_id>/skills/<string:slug>/infer-tools")
+class AgentSkillInferToolsByAgentApi(Resource):
+    @console_ns.doc("infer_agent_skill_tools_by_agent")
+    @console_ns.doc(description="Infer CLI tool + ENV suggestions from a standardized Agent App skill")
+    @console_ns.doc(params={"agent_id": "Agent ID", "slug": "Skill slug (single path segment)"})
+    @console_ns.response(
+        200,
+        "Inference result (draft suggestions, nothing persisted)",
+        console_ns.models[SkillToolInferenceResult.__name__],
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str, agent_id: UUID, slug: str):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        return _infer_skill_tools_for_app(app_model=app_model, slug=slug)
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/skills/<string:slug>/infer-tools")
@@ -451,16 +546,7 @@ class AgentSkillInferToolsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_AGENT_DRIVE_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_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
+        return _infer_skill_tools_for_app(app_model=app_model, slug=slug)

api/controllers/console/app/agent_app_access.py

@@ -5,25 +5,31 @@ reference. This exposes the read-only "Workflow access" surface from the PRD:
 which workflow apps use this Agent, without leaking the workflows' internals.
 """
 
+from uuid import UUID
+
 from flask_restx import Resource
 from pydantic import Field
 
 from controllers.common.schema import register_response_schema_models
 from controllers.console import console_ns
-from controllers.console.app.wraps import get_app_model
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.wraps import account_initialization_required, setup_required, with_current_tenant_id
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.login import login_required
-from models.model import App, AppMode
 from services.agent.roster_service import AgentRosterService
 
 
 class AgentReferencingWorkflowResponse(ResponseModel):
     app_id: str
     app_name: str
+    app_icon_type: str | None = None
+    app_icon: str | None = None
+    app_icon_background: str | None = None
     app_mode: str
+    app_updated_at: int | None = None
     workflow_id: str
+    workflow_version: str
     node_ids: list[str] = Field(default_factory=list)
 
 
@@ -34,23 +40,23 @@ class AgentReferencingWorkflowsResponse(ResponseModel):
 register_response_schema_models(console_ns, AgentReferencingWorkflowsResponse)
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-referencing-workflows")
+@console_ns.route("/agent/<uuid:agent_id>/referencing-workflows")
 class AgentAppReferencingWorkflowsResource(Resource):
     @console_ns.doc("list_agent_app_referencing_workflows")
     @console_ns.doc(description="List workflow apps that reference this Agent App's bound Agent (read-only)")
-    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.doc(params={"agent_id": "Agent ID"})
     @console_ns.response(
         200,
         "Referencing workflows listed successfully",
         console_ns.models[AgentReferencingWorkflowsResponse.__name__],
     )
-    @console_ns.response(404, "App not found")
+    @console_ns.response(404, "Agent not found")
     @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):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         workflows = AgentRosterService(db.session).list_workflows_referencing_app_agent(
             tenant_id=tenant_id, app_id=app_model.id
         )

api/controllers/console/app/agent_app_feature.py

@@ -9,20 +9,27 @@ persists them onto the app's ``app_model_config`` without touching anything the
 Soul owns.
 """
 
+from uuid import UUID
+
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
 from controllers.common.fields import SimpleResultResponse
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
-from controllers.console.app.wraps import get_app_model
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from events.app_event import app_model_config_was_updated
+from extensions.ext_database import db
 from libs.helper import dump_response
 from libs.login import login_required
 from models import Account
@@ -32,7 +39,6 @@ from models.agent_config_entities import (
     AgentSuggestedQuestionsAfterAnswerFeatureConfig,
     AgentTextToSpeechFeatureConfig,
 )
-from models.model import App, AppMode
 from services.agent_app_feature_service import AgentAppFeatureConfigService
 
 
@@ -64,28 +70,28 @@ register_schema_models(console_ns, AgentAppFeaturesPayload)
 register_response_schema_models(console_ns, SimpleResultResponse)
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-features")
+@console_ns.route("/agent/<uuid:agent_id>/features")
 class AgentAppFeatureConfigResource(Resource):
     @console_ns.doc("update_agent_app_features")
     @console_ns.doc(description="Update an Agent App's presentation features (opener, follow-up, citations, ...)")
-    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.doc(params={"agent_id": "Agent ID"})
     @console_ns.expect(console_ns.models[AgentAppFeaturesPayload.__name__])
     @console_ns.response(200, "Features updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(400, "Invalid configuration")
-    @console_ns.response(404, "App not found")
+    @console_ns.response(404, "Agent not found")
     @setup_required
     @login_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT])
     @with_current_user
-    def post(self, current_user: Account, app_model: App):
+    @with_current_tenant_id
+    def post(self, tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         args = AgentAppFeaturesPayload.model_validate(console_ns.payload or {})
 
         new_app_model_config = AgentAppFeatureConfigService.update_features(
-            app_model=app_model,
-            account=current_user,
-            config=args.model_dump(exclude_none=True),
+            app_model=app_model, account=current_user, config=args.model_dump(exclude_none=True), session=db.session
         )
 
         app_model_config_was_updated.send(app_model, app_model_config=new_app_model_config)

api/controllers/console/app/agent_app_sandbox.py

@@ -22,6 +22,7 @@ from controllers.common.schema import (
     register_schema_models,
 )
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 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
@@ -132,18 +133,18 @@ def _handle(exc: Exception) -> tuple[dict[str, object], int]:
     raise exc
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files")
+@console_ns.route("/agent/<uuid:agent_id>/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.doc(params={"agent_id": "Agent 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):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxListQuery)
         try:
             result = AgentAppSandboxService().list_files(
@@ -157,18 +158,18 @@ class AgentAppSandboxListResource(Resource):
         return result.model_dump()
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files/read")
+@console_ns.route("/agent/<uuid:agent_id>/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.doc(params={"agent_id": "Agent 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):
+    def get(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxFileQuery)
         try:
             result = AgentAppSandboxService().read_file(
@@ -182,7 +183,7 @@ class AgentAppSandboxReadResource(Resource):
         return result.model_dump()
 
 
-@console_ns.route("/apps/<uuid:app_id>/agent-sandbox/files/upload")
+@console_ns.route("/agent/<uuid:agent_id>/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")
@@ -191,9 +192,9 @@ class AgentAppSandboxUploadResource(Resource):
     @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):
+    def post(self, tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
         payload = AgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
         try:
             result = AgentAppSandboxService().upload_file(

api/controllers/console/app/agent_drive_inspector.py

@@ -10,6 +10,8 @@ backend — drive data lives in the API's own DB/storage, served straight from
 
 from __future__ import annotations
 
+from uuid import UUID
+
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
@@ -19,8 +21,9 @@ from controllers.common.schema import (
     register_response_schema_models,
 )
 from controllers.console import console_ns
+from controllers.console.agent.app_helpers import resolve_agent_app_model
 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_tenant_id
 from fields.base import ResponseModel
 from libs.login import login_required
 from models.model import App, AppMode
@@ -33,11 +36,19 @@ class AgentDriveListQuery(BaseModel):
     node_id: str | None = Field(default=None, description="Workflow node ID (workflow composer variant)")
 
 
+class AgentDriveListByAgentQuery(BaseModel):
+    prefix: str = Field(default="", description="Key prefix filter: '<slug>/' for one skill, 'files/' for files")
+
+
 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 AgentDriveFileByAgentQuery(BaseModel):
+    key: str = Field(min_length=1, description="Drive key, e.g. tender-analyzer/SKILL.md")
+
+
 class AgentDriveItemResponse(ResponseModel):
     key: str
     size: int | None = None
@@ -85,7 +96,66 @@ 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]
+_WORKFLOW_APP_MODES = [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/files")
+class AgentDriveListByAgentApi(Resource):
+    @console_ns.doc("list_agent_drive_files_by_agent")
+    @console_ns.doc(description="List agent drive entries for an Agent App")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveListByAgentQuery)})
+    @console_ns.response(200, "Drive entries", console_ns.models[AgentDriveListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        query = query_params_from_request(AgentDriveListByAgentQuery)
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            items = AgentDriveService().manifest(tenant_id=tenant_id, agent_id=str(agent_id), prefix=query.prefix)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"items": [{k: v for k, v in item.items() if k != "file_id"} for item in items]}
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/files/preview")
+class AgentDrivePreviewByAgentApi(Resource):
+    @console_ns.doc("preview_agent_drive_file_by_agent")
+    @console_ns.doc(description="Truncated text preview of one Agent App drive value")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveFileByAgentQuery)})
+    @console_ns.response(200, "Preview", console_ns.models[AgentDrivePreviewResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        query = query_params_from_request(AgentDriveFileByAgentQuery)
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            return AgentDriveService().preview(tenant_id=tenant_id, agent_id=str(agent_id), key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+
+
+@console_ns.route("/agent/<uuid:agent_id>/drive/files/download")
+class AgentDriveDownloadByAgentApi(Resource):
+    @console_ns.doc("download_agent_drive_file_by_agent")
+    @console_ns.doc(description="Time-limited external signed URL for one Agent App drive value")
+    @console_ns.doc(params={"agent_id": "Agent ID", **query_params_from_model(AgentDriveFileByAgentQuery)})
+    @console_ns.response(200, "Signed URL", console_ns.models[AgentDriveDownloadResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, agent_id: UUID):
+        query = query_params_from_request(AgentDriveFileByAgentQuery)
+        resolve_agent_app_model(tenant_id=tenant_id, agent_id=agent_id)
+        try:
+            url = AgentDriveService().download_url(tenant_id=tenant_id, agent_id=str(agent_id), key=query.key)
+        except AgentDriveError as exc:
+            return _handle(exc)
+        return {"url": url}
 
 
 @console_ns.route("/apps/<uuid:app_id>/agent/drive/files")
@@ -97,7 +167,7 @@ class AgentDriveListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
     def get(self, app_model: App):
         query = query_params_from_request(AgentDriveListQuery)
         agent_id = _resolve_agent_id(app_model, query.node_id)
@@ -121,7 +191,7 @@ class AgentDrivePreviewApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
     def get(self, app_model: App):
         query = query_params_from_request(AgentDriveFileQuery)
         agent_id = _resolve_agent_id(app_model, query.node_id)
@@ -142,7 +212,7 @@ class AgentDriveDownloadApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=_APP_MODES)
+    @get_app_model(mode=_WORKFLOW_APP_MODES)
     def get(self, app_model: App):
         query = query_params_from_request(AgentDriveFileQuery)
         agent_id = _resolve_agent_id(app_model, query.node_id)
@@ -157,6 +227,9 @@ class AgentDriveDownloadApi(Resource):
 
 __all__ = [
     "AgentDriveDownloadApi",
+    "AgentDriveDownloadByAgentApi",
     "AgentDriveListApi",
+    "AgentDriveListByAgentApi",
     "AgentDrivePreviewApi",
+    "AgentDrivePreviewByAgentApi",
 ]

api/controllers/console/app/annotation.py

@@ -9,11 +9,14 @@ from controllers.common.errors import NoFileUploadedError, TooManyFilesError
 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 (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     annotation_import_concurrency_limit,
     annotation_import_rate_limit,
     cloud_edition_billing_resource_check,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
 )
 from extensions.ext_redis import redis_client
@@ -155,6 +158,7 @@ class AnnotationReplyActionApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID, action: Literal["enable", "disable"]):
         args = AnnotationReplyPayload.model_validate(console_ns.payload)
         match action:
@@ -185,6 +189,7 @@ class AppAnnotationSettingDetailApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID):
         result = AppAnnotationService.get_app_annotation_setting_by_app_id(str(app_id))
         return result, 200
@@ -202,6 +207,7 @@ class AppAnnotationSettingUpdateApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID, annotation_setting_id: UUID):
         annotation_setting_id_str = str(annotation_setting_id)
 
@@ -230,6 +236,7 @@ class AnnotationReplyActionStatusApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID, job_id: UUID, action: str):
         job_id_str = str(job_id)
         app_annotation_job_key = f"{action}_app_annotation_job_{job_id_str}"
@@ -258,6 +265,7 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID):
         args = AnnotationListQuery.model_validate(request.args.to_dict(flat=True))
         page = args.page
@@ -286,6 +294,7 @@ class AnnotationApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID):
         args = CreateAnnotationPayload.model_validate(console_ns.payload)
         upsert_args: UpsertAnnotationArgs = {}
@@ -304,6 +313,7 @@ class AnnotationApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @console_ns.response(204, "Annotations deleted successfully")
     def delete(self, app_id: UUID):
 
@@ -342,6 +352,7 @@ class AnnotationExportApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID):
         annotation_list = AppAnnotationService.export_annotation_list_by_app_id(str(app_id))
         annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
@@ -369,6 +380,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID, annotation_id: UUID):
         args = UpdateAnnotationPayload.model_validate(console_ns.payload)
         update_args: UpdateAnnotationArgs = {}
@@ -383,6 +395,7 @@ class AnnotationUpdateDeleteApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @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))
@@ -410,6 +423,7 @@ class AnnotationBatchImportApi(Resource):
     @annotation_import_rate_limit
     @annotation_import_concurrency_limit
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     def post(self, app_id: UUID):
         from configs import dify_config
 
@@ -462,6 +476,7 @@ class AnnotationBatchImportStatusApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("annotation")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID, job_id: UUID):
         indexing_cache_key = f"app_annotation_batch_import_{str(job_id)}"
         cache_result = redis_client.get(indexing_cache_key)
@@ -492,6 +507,7 @@ class AnnotationHitHistoryListApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_id: UUID, annotation_id: UUID):
         page = request.args.get("page", default=1, type=int)
         limit = request.args.get("limit", default=20, type=int)

api/controllers/console/app/app.py

@@ -1,8 +1,9 @@
 import logging
 import re
 import uuid
+from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, Literal, cast
+from typing import Any, Literal
 
 from flask import request
 from flask_restx import Resource
@@ -10,8 +11,9 @@ from pydantic import AliasChoices, BaseModel, Field, computed_field, field_valid
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from werkzeug.datastructures import MultiDict
-from werkzeug.exceptions import BadRequest
+from werkzeug.exceptions import BadRequest, NotFound
 
+from configs import dify_config
 from controllers.common.fields import RedirectUrlResponse, SimpleResultResponse
 from controllers.common.helpers import FileInfo
 from controllers.common.schema import (
@@ -24,11 +26,14 @@ from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     cloud_edition_billing_resource_check,
     edit_permission_required,
     enterprise_license_required,
     is_admin_or_owner_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user,
@@ -41,12 +46,13 @@ 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, to_timestamp
+from libs.helper import build_icon_url, dump_response, 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, AppService, CreateAppParams
+from services.app_service import AppListParams, AppListSortBy, AppService, CreateAppParams, StarredAppListParams
+from services.enterprise import rbac_service as enterprise_rbac_service
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import ImportMode, ImportStatus
 from services.entities.knowledge_entities.knowledge_entities import (
@@ -63,7 +69,7 @@ from services.entities.knowledge_entities.knowledge_entities import (
 )
 from services.feature_service import FeatureService
 
-ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"]
+ALLOW_CREATE_APP_MODES = ["chat", "agent-chat", "advanced-chat", "workflow", "completion"]
 
 register_enum_models(console_ns, IconType)
 
@@ -71,12 +77,18 @@ _logger = logging.getLogger(__name__)
 _TAG_IDS_BRACKET_PATTERN = re.compile(r"^tag_ids\[(\d+)\]$")
 _CREATOR_IDS_BRACKET_PATTERN = re.compile(r"^creator_ids\[(\d+)\]$")
 AppListMode = Literal["completion", "chat", "advanced-chat", "workflow", "agent-chat", "agent", "channel", "all"]
+DEFAULT_APP_LIST_MODE: AppListMode = "all"
+APP_LIST_PERMISSION_KEYS = frozenset({"app.preview", "app.acl.preview", "app.full_access"})
 
 
-class AppListQuery(BaseModel):
+class AppListBaseQuery(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")
+    mode: AppListMode = Field(default=DEFAULT_APP_LIST_MODE, 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")
@@ -119,6 +131,14 @@ class AppListQuery(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]] = []
@@ -147,12 +167,14 @@ def _normalize_app_list_query_args(query_args: MultiDict[str, str]) -> dict[str,
     return normalized
 
 
+def _has_app_list_permission(permission_keys: Sequence[str]) -> bool:
+    return any(permission_key in APP_LIST_PERMISSION_KEYS for permission_key in permission_keys)
+
+
 class CreateAppPayload(BaseModel):
     name: str = Field(..., min_length=1, description="App name")
     description: str | None = Field(default=None, description="App description (max 400 chars)", max_length=400)
-    mode: Literal["chat", "agent-chat", "agent", "advanced-chat", "workflow", "completion"] = Field(
-        ..., description="App mode"
-    )
+    mode: Literal["chat", "agent-chat", "advanced-chat", "workflow", "completion"] = Field(..., description="App mode")
     icon_type: IconType | None = Field(default=None, description="Icon type")
     icon: str | None = Field(default=None, description="Icon")
     icon_background: str | None = Field(default=None, description="Icon background color")
@@ -387,6 +409,13 @@ class AppPartial(ResponseModel):
     create_user_name: str | None = None
     author_name: str | None = None
     has_draft_trigger: bool | None = None
+    permission_keys: list[str] = Field(default_factory=list)
+    # For Agent App type: the roster Agent backing this app (None otherwise).
+    bound_agent_id: str | None = None
+    # For Agent App responses exposed through /agent.
+    app_id: str | None = None
+    is_starred: bool = False
+    maintainer: str | None = None
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -422,6 +451,8 @@ class AppDetail(ResponseModel):
     updated_at: int | None = None
     access_mode: str | None = None
     tags: list[Tag] = Field(default_factory=list)
+    permission_keys: list[str] = Field(default_factory=list)
+    maintainer: str | None = None
 
     @field_validator("created_at", "updated_at", mode="before")
     @classmethod
@@ -437,6 +468,8 @@ class AppDetailWithSite(AppDetail):
     site: Site | None = None
     # For Agent App type: the roster Agent backing this app (None otherwise).
     bound_agent_id: str | None = None
+    # For Agent App responses exposed through /agent.
+    app_id: str | None = None
 
     @computed_field(return_type=str | None)  # type: ignore
     @property
@@ -456,12 +489,54 @@ 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, AppTraceResponse, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
     AppListQuery,
+    StarredAppListQuery,
     CreateAppPayload,
     UpdateAppPayload,
     CopyAppPayload,
@@ -477,10 +552,7 @@ register_schema_models(
     ModelConfig,
     Site,
     DeletedTool,
-    AppPartial,
     AppDetail,
-    AppDetailWithSite,
-    AppPagination,
     AppExportResponse,
     Segmentation,
     PreProcessingRule,
@@ -500,6 +572,13 @@ register_schema_models(
     LoadBalancingPayload,
 )
 
+register_response_schema_models(
+    console_ns,
+    AppPartial,
+    AppDetailWithSite,
+    AppPagination,
+)
+
 
 @console_ns.route("/apps")
 class AppListApi(Resource):
@@ -521,61 +600,72 @@ 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,
             is_created_by_me=args.is_created_by_me,
         )
 
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            str(current_tenant_id),
+            current_user_id,
+        )
+        if dify_config.RBAC_ENABLED:
+            whitelist_scope = enterprise_rbac_service.RBACService.AppAccess.whitelist_resources(
+                str(current_tenant_id),
+                current_user_id,
+            )
+            can_manage_own_apps = "app.create_and_management" in permissions.workspace.permission_keys
+            has_default_preview = _has_app_list_permission(
+                permissions.app.default_permission_keys
+            ) or _has_app_list_permission(permissions.workspace.permission_keys)
+            permission_app_ids: set[str] | None = None
+            if not has_default_preview:
+                permission_app_ids = {
+                    override.resource_id
+                    for override in permissions.app.overrides
+                    if _has_app_list_permission(override.permission_keys)
+                }
+
+            if getattr(whitelist_scope, "unrestricted", False):
+                accessible_app_ids = permission_app_ids
+            else:
+                accessible_app_ids = set(whitelist_scope.resource_ids)
+                if permission_app_ids is not None:
+                    accessible_app_ids |= permission_app_ids
+                elif has_default_preview:
+                    accessible_app_ids = None
+
+            if accessible_app_ids:
+                params.accessible_app_ids = sorted(accessible_app_ids)
+                params.include_own_apps = can_manage_own_apps
+            elif accessible_app_ids is not None and can_manage_own_apps:
+                params.is_created_by_me = True
+            elif accessible_app_ids is not None:
+                params.accessible_app_ids = []
+
         # get app list
         app_service = AppService()
-        app_pagination = app_service.get_paginate_apps(current_user_id, current_tenant_id, params)
+        app_pagination = app_service.get_paginate_apps(current_user_id, current_tenant_id, params, db.session)
         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
 
-        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
+        app_ids = [str(app.id) for app in app_pagination.items]
+        permission_keys_map = permissions.app.permission_keys_by_resource_ids(app_ids)
+        _enrich_app_list_items(session, apps=app_pagination.items, tenant_id=current_tenant_id)
 
         pagination_model = AppPagination.model_validate(app_pagination, from_attributes=True)
+        if app_pagination.items:
+            pagination_model = pagination_model.model_copy(
+                update={
+                    "data": [
+                        item.model_copy(update={"permission_keys": permission_keys_map.get(str(item.id), [])})
+                        for item in pagination_model.data
+                    ]
+                }
+            )
         return pagination_model.model_dump(mode="json"), 200
 
     @console_ns.doc("create_app")
@@ -587,6 +677,7 @@ class AppListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT, resource_required=False)
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
     @with_current_user
@@ -605,10 +696,89 @@ class AppListApi(Resource):
 
         app_service = AppService()
         app = app_service.create_app(current_tenant_id, params, current_user)
-        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True)
+        permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
+            str(current_tenant_id),
+            current_user.id,
+            [str(app.id)],
+        )
+        app_detail = AppDetailWithSite.model_validate(app, from_attributes=True).model_copy(
+            update={"permission_keys": permission_keys_map.get(str(app.id), [])}
+        )
         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, db.session)
+        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")
@@ -619,8 +789,11 @@ class AppApi(Resource):
     @login_required
     @account_initialization_required
     @enterprise_license_required
+    @with_current_user
+    @with_current_tenant_id
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model(mode=None)
-    def get(self, app_model: App):
+    def get(self, current_tenant_id: str, current_user: Account, app_model: App):
         """Get app detail"""
         app_service = AppService()
 
@@ -628,9 +801,18 @@ class AppApi(Resource):
 
         if FeatureService.get_system_features().webapp_auth.enabled:
             app_setting = EnterpriseService.WebAppAuth.get_app_access_mode_by_id(app_id=str(app_model.id))
-            app_model.access_mode = app_setting.access_mode  # type: ignore[attr-defined]
+            app_model.access_mode = app_setting.access_mode
 
-        response_model = AppDetailWithSite.model_validate(app_model, from_attributes=True)
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            str(current_tenant_id),
+            current_user.id,
+            app_id=str(app_model.id),
+        )
+        permission_keys_map = permissions.app.permission_keys_by_resource_ids([str(app_model.id)])
+
+        response_model = AppDetailWithSite.model_validate(app_model, from_attributes=True).model_copy(
+            update={"permission_keys": permission_keys_map.get(str(app_model.id), [])}
+        )
         return response_model.model_dump(mode="json")
 
     @console_ns.doc("update_app")
@@ -643,8 +825,9 @@ class AppApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=None)
     def put(self, app_model: App):
         """Update app"""
         args = UpdateAppPayload.model_validate(console_ns.payload)
@@ -669,11 +852,12 @@ class AppApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.response(204, "App deleted successfully")
     @console_ns.response(403, "Insufficient permissions")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_DELETE)
+    @get_app_model
     def delete(self, app_model: App):
         """Delete app"""
         app_service = AppService()
@@ -693,10 +877,12 @@ class AppCopyApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @with_current_user
-    def post(self, current_user: Account, app_model: App):
+    @with_current_tenant_id
+    @get_app_model(mode=None)
+    def post(self, current_tenant_id: str, current_user: Account, app_model: App):
         """Copy app"""
         # The role of the current user in the ta table must be admin, owner, or editor
         args = CopyAppPayload.model_validate(console_ns.payload or {})
@@ -738,7 +924,17 @@ class AppCopyApi(Resource):
             stmt = select(App).where(App.id == result.app_id)
             app = session.scalar(stmt)
 
-        response_model = AppDetailWithSite.model_validate(app, from_attributes=True)
+        if not app:
+            raise NotFound("App not found")
+
+        permission_keys_map = enterprise_rbac_service.RBACService.AppPermissions.batch_get(
+            str(current_tenant_id),
+            current_user.id,
+            [str(app.id)],
+        )
+        response_model = AppDetailWithSite.model_validate(app, from_attributes=True).model_copy(
+            update={"permission_keys": permission_keys_map.get(str(app.id), [])}
+        )
         return response_model.model_dump(mode="json"), 201
 
 
@@ -750,11 +946,12 @@ class AppExportApi(Resource):
     @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
     @setup_required
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
+    @get_app_model
     def get(self, app_model: App):
         """Export app"""
         args = AppExportQuery.model_validate(request.args.to_dict(flat=True))
@@ -775,12 +972,12 @@ class AppPublishToCreatorsPlatformApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
     @with_current_user_id
+    @get_app_model(mode=None)
     def post(self, current_user_id: str, app_model: App):
         """Publish app to Creators Platform"""
-        from configs import dify_config
         from core.helper.creators import get_redirect_url, upload_dsl
 
         if not dify_config.CREATORS_PLATFORM_FEATURES_ENABLED:
@@ -805,8 +1002,9 @@ class AppNameApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppNamePayload.model_validate(console_ns.payload)
 
@@ -827,8 +1025,9 @@ class AppIconApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppIconPayload.model_validate(console_ns.payload or {})
 
@@ -854,8 +1053,9 @@ class AppSiteStatus(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=None)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
+    @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppSiteStatusPayload.model_validate(console_ns.payload)
 
@@ -877,6 +1077,7 @@ class AppApiStatus(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @get_app_model(mode=None)
     def post(self, app_model: App):
         args = AppApiStatusPayload.model_validate(console_ns.payload)
@@ -901,6 +1102,7 @@ class AppTraceApi(Resource):
     @login_required
     @account_initialization_required
     @with_session
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model
     def get(self, session: Session, app_model: App):
         """Get app trace"""
@@ -922,6 +1124,7 @@ class AppTraceApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
     @get_app_model
     def post(self, app_model: App):
         # add app trace

api/controllers/console/app/app_import.py

@@ -2,25 +2,36 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
+from configs import dify_config
 from controllers.common.schema import register_enum_models, register_schema_models
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     cloud_edition_billing_resource_check,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_user,
 )
 from extensions.ext_database import db
-from libs.login import login_required
+from extensions.ext_redis import redis_client
+from libs.login import current_account_with_tenant, login_required
 from models.account import Account
 from models.model import App
-from services.app_dsl_service import AppDslService, Import
+from services.app_dsl_service import (
+    IMPORT_INFO_REDIS_KEY_PREFIX,
+    AppDslService,
+    Import,
+    PendingData,
+)
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import CheckDependenciesResult, ImportStatus
 from services.feature_service import FeatureService
 
 from .. import console_ns
+from .permission_keys import get_app_permission_keys
 
 
 class AppImportPayload(BaseModel):
@@ -39,6 +50,24 @@ register_enum_models(console_ns, ImportStatus)
 register_schema_models(console_ns, AppImportPayload, Import, CheckDependenciesResult)
 
 
+def _current_user_and_tenant_id(current_user: Account | None) -> tuple[Account, str | None]:
+    if current_user is None:
+        account, tenant_id = current_account_with_tenant()
+        return account, str(tenant_id) if tenant_id else None
+
+    current_tenant_id = getattr(current_user, "current_tenant_id", None)
+    if current_tenant_id:
+        return current_user, str(current_tenant_id)
+
+    current_tenant = getattr(current_user, "current_tenant", None)
+    current_tenant_object_id = getattr(current_tenant, "id", None)
+    if current_tenant_object_id:
+        return current_user, str(current_tenant_object_id)
+
+    account, fallback_tenant_id = current_account_with_tenant()
+    return account, str(fallback_tenant_id) if fallback_tenant_id else None
+
+
 @console_ns.route("/apps/imports")
 class AppImportApi(Resource):
     @console_ns.expect(console_ns.models[AppImportPayload.__name__])
@@ -50,10 +79,11 @@ class AppImportApi(Resource):
     @account_initialization_required
     @cloud_edition_billing_resource_check("apps")
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL, resource_required=False)
     @with_current_user
-    def post(self, current_user: Account):
-        # Check user role first
+    def post(self, current_user: Account | None = None):
         args = AppImportPayload.model_validate(console_ns.payload)
+        current_user = current_user if current_user is not None else _current_user_and_tenant_id(None)[0]
 
         # AppDslService performs internal commits for some creation paths, so use a plain
         # Session here instead of nesting it inside sessionmaker(...).begin().
@@ -77,6 +107,20 @@ class AppImportApi(Resource):
                 session.rollback()
             else:
                 session.commit()
+
+        is_created_app = args.app_id is None and result.status in {
+            ImportStatus.COMPLETED,
+            ImportStatus.COMPLETED_WITH_WARNINGS,
+        }
+        if dify_config.RBAC_ENABLED and is_created_app and result.app_id:
+            current_user, current_tenant_id = _current_user_and_tenant_id(current_user)
+            if current_tenant_id:
+                result.permission_keys = get_app_permission_keys(
+                    current_tenant_id,
+                    current_user.id,
+                    result.app_id,
+                )
+
         if result.app_id and FeatureService.get_system_features().webapp_auth.enabled:
             # update web app setting as private
             EnterpriseService.WebAppAuth.update_app_access_mode(result.app_id, "private")
@@ -99,9 +143,16 @@ class AppImportConfirmApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL, resource_required=False)
     @with_current_user
-    def post(self, current_user: Account, import_id: str):
-        # Check user role first
+    def post(self, current_user: Account | None = None, import_id: str = ""):
+        current_user = current_user if current_user is not None else _current_user_and_tenant_id(None)[0]
+        redis_key = f"{IMPORT_INFO_REDIS_KEY_PREFIX}{import_id}"
+        pending_data_raw = redis_client.get(redis_key)
+        pending_data: PendingData | None = None
+        if pending_data_raw:
+            pending_data = PendingData.model_validate_json(pending_data_raw)
+
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)
             # Confirm import
@@ -112,6 +163,24 @@ class AppImportConfirmApi(Resource):
             else:
                 session.commit()
 
+        is_created_app = bool(
+            pending_data
+            and pending_data.app_id is None
+            and result.status
+            in {
+                ImportStatus.COMPLETED,
+                ImportStatus.COMPLETED_WITH_WARNINGS,
+            }
+        )
+        if dify_config.RBAC_ENABLED and is_created_app and result.app_id:
+            current_user, current_tenant_id = _current_user_and_tenant_id(current_user)
+            if current_tenant_id:
+                result.permission_keys = get_app_permission_keys(
+                    current_tenant_id,
+                    current_user.id,
+                    result.app_id,
+                )
+
         # Return appropriate status code based on result
         if result.status == ImportStatus.FAILED:
             return result.model_dump(mode="json"), 400
@@ -120,12 +189,17 @@ class AppImportConfirmApi(Resource):
 
 @console_ns.route("/apps/imports/<string:app_id>/check-dependencies")
 class AppImportCheckDependenciesApi(Resource):
-    @console_ns.response(200, "Dependencies checked", console_ns.models[CheckDependenciesResult.__name__])
+    @console_ns.response(
+        200,
+        "Dependencies checked",
+        console_ns.models[CheckDependenciesResult.__name__],
+    )
     @setup_required
     @login_required
     @get_app_model
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     def get(self, app_model: App):
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)

api/controllers/console/app/audio.py

@@ -22,7 +22,13 @@ from controllers.console.app.error import (
     UnsupportedAudioTypeError,
 )
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.login import login_required
@@ -126,10 +132,10 @@ class ChatMessageTextApi(Resource):
         console_ns.models[AudioBinaryResponse.__name__],
     )
     @console_ns.response(400, "Bad request - Invalid parameters")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @get_app_model
     def post(self, app_model: App):
         try:
             payload = TextToSpeechPayload.model_validate(console_ns.payload)
@@ -180,10 +186,11 @@ class TextModesApi(Resource):
         console_ns.models[TextToSpeechVoiceListResponse.__name__],
     )
     @console_ns.response(400, "Invalid language parameter")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App):
         try:
             args = TextToSpeechVoiceQuery.model_validate(request.args.to_dict(flat=True))

api/controllers/console/app/completion.py

@@ -1,5 +1,6 @@
 import logging
 from typing import Any, Literal
+from uuid import UUID
 
 from flask import request
 from flask_restx import Resource
@@ -10,6 +11,7 @@ import services
 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.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.error import (
     AppUnavailableError,
     CompletionRequestError,
@@ -20,9 +22,13 @@ from controllers.console.app.error import (
 )
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
     with_current_user_id,
 )
@@ -110,8 +116,9 @@ class CompletionMessageApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=AppMode.COMPLETION)
     def post(self, current_user: Account, app_model: App):
         args_model = CompletionMessagePayload.model_validate(console_ns.payload)
         args = args_model.model_dump(exclude_none=True, by_alias=True)
@@ -156,8 +163,8 @@ class CompletionMessageStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @with_current_user_id
+    @get_app_model(mode=AppMode.COMPLETION)
     def post(self, current_user_id: str, app_model: App, task_id: str):
 
         AppTaskService.stop_task(
@@ -182,55 +189,33 @@ class ChatMessageApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.AGENT])
     def post(self, current_user: Account, app_model: App):
-        raw_payload = console_ns.payload or {}
-        args_model = ChatMessagePayload.model_validate(raw_payload)
-        args = args_model.model_dump(exclude_none=True, by_alias=True)
+        return _create_chat_message(current_user=current_user, app_model=app_model)
 
-        streaming = _resolve_debugger_chat_streaming(
-            app_mode=AppMode.value_of(app_model.mode),
-            response_mode=args_model.response_mode,
-            response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
-        )
-        if AppMode.value_of(app_model.mode) == AppMode.AGENT:
-            args["response_mode"] = "streaming"
-        args["auto_generate_name"] = False
 
-        external_trace_id = get_external_trace_id(request)
-        if external_trace_id:
-            args["external_trace_id"] = external_trace_id
-
-        try:
-            response = AppGenerateService.generate(
-                app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
-            )
-
-            return helper.compact_generate_response(response)
-        except services.errors.conversation.ConversationNotExistsError:
-            raise NotFound("Conversation Not Exists.")
-        except services.errors.conversation.ConversationCompletedError:
-            raise ConversationCompletedError()
-        except services.errors.app_model_config.AppModelConfigBrokenError:
-            logger.exception("App model config broken.")
-            raise AppUnavailableError()
-        except ProviderTokenNotInitError as ex:
-            raise ProviderNotInitializeError(ex.description)
-        except QuotaExceededError:
-            raise ProviderQuotaExceededError()
-        except ModelCurrentlyNotSupportError:
-            raise ProviderModelCurrentlyNotSupportError()
-        except InvokeRateLimitError as ex:
-            raise InvokeRateLimitHttpError(ex.description)
-        except InvokeError as e:
-            raise CompletionRequestError(e.description)
-        except ValueError as e:
-            raise e
-        except Exception as e:
-            logger.exception("internal server error.")
-            raise InternalServerError()
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages")
+class AgentChatMessageApi(Resource):
+    @console_ns.doc("create_agent_chat_message")
+    @console_ns.doc(description="Generate an Agent App chat message for debugging")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.expect(console_ns.models[ChatMessagePayload.__name__])
+    @console_ns.response(200, "Chat message generated successfully", console_ns.models[GeneratedAppResponse.__name__])
+    @console_ns.response(400, "Invalid request parameters")
+    @console_ns.response(404, "Agent or conversation not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _create_chat_message(current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-messages/<string:task_id>/stop")
@@ -242,15 +227,82 @@ class ChatMessageStopApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user_id
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def post(self, current_user_id: str, app_model: App, task_id: str):
+        return _stop_chat_message(current_user_id=current_user_id, app_model=app_model, task_id=task_id)
 
-        AppTaskService.stop_task(
-            task_id=task_id,
-            invoke_from=InvokeFrom.DEBUGGER,
-            user_id=current_user_id,
-            app_mode=AppMode.value_of(app_model.mode),
+
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages/<string:task_id>/stop")
+class AgentChatMessageStopApi(Resource):
+    @console_ns.doc("stop_agent_chat_message")
+    @console_ns.doc(description="Stop a running Agent App chat message generation")
+    @console_ns.doc(params={"agent_id": "Agent ID", "task_id": "Task ID to stop"})
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user_id
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user_id: str, agent_id: UUID, task_id: str):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _stop_chat_message(current_user_id=current_user_id, app_model=app_model, task_id=task_id)
+
+
+def _create_chat_message(*, current_user: Account, app_model: App):
+    raw_payload = console_ns.payload or {}
+    args_model = ChatMessagePayload.model_validate(raw_payload)
+    args = args_model.model_dump(exclude_none=True, by_alias=True)
+
+    streaming = _resolve_debugger_chat_streaming(
+        app_mode=AppMode.value_of(app_model.mode),
+        response_mode=args_model.response_mode,
+        response_mode_provided=isinstance(raw_payload, dict) and "response_mode" in raw_payload,
+    )
+    if AppMode.value_of(app_model.mode) == AppMode.AGENT:
+        args["response_mode"] = "streaming"
+    args["auto_generate_name"] = False
+
+    external_trace_id = get_external_trace_id(request)
+    if external_trace_id:
+        args["external_trace_id"] = external_trace_id
+
+    try:
+        response = AppGenerateService.generate(
+            app_model=app_model, user=current_user, args=args, invoke_from=InvokeFrom.DEBUGGER, streaming=streaming
         )
 
-        return {"result": "success"}, 200
+        return helper.compact_generate_response(response)
+    except services.errors.conversation.ConversationNotExistsError:
+        raise NotFound("Conversation Not Exists.")
+    except services.errors.conversation.ConversationCompletedError:
+        raise ConversationCompletedError()
+    except services.errors.app_model_config.AppModelConfigBrokenError:
+        logger.exception("App model config broken.")
+        raise AppUnavailableError()
+    except ProviderTokenNotInitError as ex:
+        raise ProviderNotInitializeError(ex.description)
+    except QuotaExceededError:
+        raise ProviderQuotaExceededError()
+    except ModelCurrentlyNotSupportError:
+        raise ProviderModelCurrentlyNotSupportError()
+    except InvokeRateLimitError as ex:
+        raise InvokeRateLimitHttpError(ex.description)
+    except InvokeError as e:
+        raise CompletionRequestError(e.description)
+    except ValueError as e:
+        raise e
+    except Exception as e:
+        logger.exception("internal server error.")
+        raise InternalServerError()
+
+
+def _stop_chat_message(*, current_user_id: str, app_model: App, task_id: str):
+    AppTaskService.stop_task(
+        task_id=task_id,
+        invoke_from=InvokeFrom.DEBUGGER,
+        user_id=current_user_id,
+        app_mode=AppMode.value_of(app_model.mode),
+    )
+
+    return {"result": "success"}, 200

api/controllers/console/app/conversation.py

@@ -13,8 +13,11 @@ from controllers.common.schema import query_params_from_model, register_schema_m
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_user,
 )
@@ -97,9 +100,10 @@ class CompletionConversationApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=AppMode.COMPLETION)
     def get(self, current_user: Account, app_model: App):
         args = CompletionConversationQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -169,9 +173,10 @@ class CompletionConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=AppMode.COMPLETION)
     def get(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return ConversationMessageDetailResponse.model_validate(
@@ -187,9 +192,10 @@ class CompletionConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=AppMode.COMPLETION)
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @get_app_model(mode=AppMode.COMPLETION)
     def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 
@@ -212,9 +218,10 @@ class ChatConversationApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, current_user: Account, app_model: App):
         args = ChatConversationQuery.model_validate(request.args.to_dict(flat=True))
 
@@ -323,9 +330,10 @@ class ChatConversationDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
         return ConversationDetailResponse.model_validate(
@@ -340,10 +348,11 @@ class ChatConversationDetailApi(Resource):
     @console_ns.response(404, "Conversation not found")
     @setup_required
     @login_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_user
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def delete(self, current_user: Account, app_model: App, conversation_id: UUID):
         conversation_id_str = str(conversation_id)
 

api/controllers/console/app/conversation_variables.py

@@ -12,7 +12,13 @@ from sqlalchemy.orm import sessionmaker
 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
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from extensions.ext_database import db
 from fields._value_type_serializer import serialize_value_type
 from fields.base import ResponseModel
@@ -93,6 +99,7 @@ class ConversationVariablesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
     @get_app_model(mode=AppMode.ADVANCED_CHAT)
     def get(self, app_model: App):
         args = ConversationVariablesQuery.model_validate(request.args.to_dict(flat=True))

api/controllers/console/app/mcp_server.py

@@ -12,8 +12,11 @@ from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
 )
@@ -83,6 +86,7 @@ class AppMCPServerController(Resource):
     @login_required
     @account_initialization_required
     @setup_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @get_app_model
     def get(self, app_model: App):
         server = db.session.scalar(select(AppMCPServer).where(AppMCPServer.app_id == app_model.id).limit(1))
@@ -99,11 +103,12 @@ class AppMCPServerController(Resource):
     )
     @console_ns.response(403, "Insufficient permissions")
     @account_initialization_required
-    @get_app_model
     @login_required
     @setup_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
     @with_current_tenant_id
+    @get_app_model
     def post(self, current_tenant_id: str, app_model: App):
         payload = MCPServerCreatePayload.model_validate(console_ns.payload or {})
 
@@ -133,11 +138,12 @@ class AppMCPServerController(Resource):
     )
     @console_ns.response(403, "Insufficient permissions")
     @console_ns.response(404, "Server not found")
-    @get_app_model
     @login_required
     @setup_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
+    @get_app_model
     def put(self, app_model: App):
         payload = MCPServerUpdatePayload.model_validate(console_ns.payload or {})
         server = db.session.get(AppMCPServer, payload.id)
@@ -174,6 +180,7 @@ class AppMCPServerRefreshController(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @with_current_tenant_id
     def get(self, current_tenant_id: str, server_id: UUID):
         server = db.session.scalar(

api/controllers/console/app/message.py

@@ -13,6 +13,7 @@ from controllers.common.controller_schemas import MessageFeedbackPayload as _Mes
 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.agent.app_helpers import resolve_agent_app_model
 from controllers.console.app.error import (
     CompletionRequestError,
     ProviderModelCurrentlyNotSupportError,
@@ -22,9 +23,13 @@ from controllers.console.app.error import (
 from controllers.console.app.wraps import get_app_model
 from controllers.console.explore.error import AppSuggestedQuestionsAfterAnswerDisabledError
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
+    with_current_tenant_id,
     with_current_user,
 )
 from core.app.entities.app_invoke_entities import InvokeFrom
@@ -180,70 +185,30 @@ class ChatMessageListApi(Resource):
     @login_required
     @account_initialization_required
     @setup_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, app_model: App):
-        args = ChatMessagesQuery.model_validate(request.args.to_dict())
+        return _list_chat_messages(app_model=app_model)
 
-        conversation = db.session.scalar(
-            select(Conversation)
-            .where(Conversation.id == args.conversation_id, Conversation.app_id == app_model.id)
-            .limit(1)
-        )
 
-        if not conversation:
-            raise NotFound("Conversation Not Exists.")
-
-        if args.first_id:
-            first_message = db.session.scalar(
-                select(Message).where(Message.conversation_id == conversation.id, Message.id == args.first_id).limit(1)
-            )
-
-            if not first_message:
-                raise NotFound("First message not found")
-
-            history_messages = db.session.scalars(
-                select(Message)
-                .where(
-                    Message.conversation_id == conversation.id,
-                    Message.created_at < first_message.created_at,
-                    Message.id != first_message.id,
-                )
-                .order_by(Message.created_at.desc())
-                .limit(args.limit)
-            ).all()
-        else:
-            history_messages = db.session.scalars(
-                select(Message)
-                .where(Message.conversation_id == conversation.id)
-                .order_by(Message.created_at.desc())
-                .limit(args.limit)
-            ).all()
-
-        # Initialize has_more based on whether we have a full page
-        if len(history_messages) == args.limit:
-            current_page_first_message = history_messages[-1]
-            # Check if there are more messages before the current page
-            has_more = db.session.scalar(
-                select(
-                    exists().where(
-                        Message.conversation_id == conversation.id,
-                        Message.created_at < current_page_first_message.created_at,
-                        Message.id != current_page_first_message.id,
-                    )
-                )
-            )
-        else:
-            # If we don't have a full page, there are no more messages
-            has_more = False
-
-        history_messages = list(reversed(history_messages))
-        attach_message_extra_contents(history_messages)
-
-        return MessageInfiniteScrollPaginationResponse.model_validate(
-            InfiniteScrollPagination(data=history_messages, limit=args.limit, has_more=has_more),
-            from_attributes=True,
-        ).model_dump(mode="json")
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages")
+class AgentChatMessageListApi(Resource):
+    @console_ns.doc("list_agent_chat_messages")
+    @console_ns.doc(description="Get Agent App chat messages for a conversation with pagination")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.doc(params=query_params_from_model(ChatMessagesQuery))
+    @console_ns.response(200, "Success", console_ns.models[MessageInfiniteScrollPaginationResponse.__name__])
+    @console_ns.response(404, "Agent or conversation not found")
+    @login_required
+    @account_initialization_required
+    @setup_required
+    @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _list_chat_messages(app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks")
@@ -255,50 +220,31 @@ class MessageFeedbackApi(Resource):
     @console_ns.response(200, "Feedback updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(404, "Message not found")
     @console_ns.response(403, "Insufficient permissions")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
     @with_current_user
+    @get_app_model
     def post(self, current_user: Account, app_model: App):
-        args = MessageFeedbackPayload.model_validate(console_ns.payload)
+        return _update_message_feedback(current_user=current_user, app_model=app_model)
 
-        message_id = str(args.message_id)
 
-        message = db.session.scalar(
-            select(Message).where(Message.id == message_id, Message.app_id == app_model.id).limit(1)
-        )
-
-        if not message:
-            raise NotFound("Message Not Exists.")
-
-        feedback = message.admin_feedback
-
-        if not args.rating and feedback:
-            db.session.delete(feedback)
-        elif args.rating and feedback:
-            feedback.rating = FeedbackRating(args.rating)
-            feedback.content = args.content
-        elif not args.rating and not feedback:
-            raise ValueError("rating cannot be None when feedback not exists")
-        else:
-            rating_value = args.rating
-            if rating_value is None:
-                raise ValueError("rating is required to create feedback")
-            feedback = MessageFeedback(
-                app_id=app_model.id,
-                conversation_id=message.conversation_id,
-                message_id=message.id,
-                rating=FeedbackRating(rating_value),
-                content=args.content,
-                from_source=FeedbackFromSource.ADMIN,
-                from_account_id=current_user.id,
-            )
-            db.session.add(feedback)
-
-        db.session.commit()
-
-        return {"result": "success"}
+@console_ns.route("/agent/<uuid:agent_id>/feedbacks")
+class AgentMessageFeedbackApi(Resource):
+    @console_ns.doc("create_agent_message_feedback")
+    @console_ns.doc(description="Create or update Agent App message feedback")
+    @console_ns.doc(params={"agent_id": "Agent ID"})
+    @console_ns.expect(console_ns.models[MessageFeedbackPayload.__name__])
+    @console_ns.response(200, "Feedback updated successfully", console_ns.models[SimpleResultResponse.__name__])
+    @console_ns.response(404, "Agent or message not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def post(self, current_tenant_id: str, current_user: Account, agent_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _update_message_feedback(current_user=current_user, app_model=app_model)
 
 
 @console_ns.route("/apps/<uuid:app_id>/annotations/count")
@@ -311,10 +257,11 @@ class MessageAnnotationCountApi(Resource):
         "Annotation count retrieved successfully",
         console_ns.models[AnnotationCountResponse.__name__],
     )
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App):
         count = db.session.scalar(
             select(func.count(MessageAnnotation.id)).where(MessageAnnotation.app_id == app_model.id)
@@ -337,34 +284,32 @@ class MessageSuggestedQuestionApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     @with_current_user
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model(mode=[AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT])
     def get(self, current_user: Account, app_model: App, message_id: UUID):
-        message_id_str = str(message_id)
+        return _get_message_suggested_questions(current_user=current_user, app_model=app_model, message_id=message_id)
 
-        try:
-            questions = MessageService.get_suggested_questions_after_answer(
-                app_model=app_model, message_id=message_id_str, user=current_user, invoke_from=InvokeFrom.DEBUGGER
-            )
-        except MessageNotExistsError:
-            raise NotFound("Message not found")
-        except ConversationNotExistsError:
-            raise NotFound("Conversation not found")
-        except ProviderTokenNotInitError as ex:
-            raise ProviderNotInitializeError(ex.description)
-        except QuotaExceededError:
-            raise ProviderQuotaExceededError()
-        except ModelCurrentlyNotSupportError:
-            raise ProviderModelCurrentlyNotSupportError()
-        except InvokeError as e:
-            raise CompletionRequestError(e.description)
-        except SuggestedQuestionsAfterAnswerDisabledError:
-            raise AppSuggestedQuestionsAfterAnswerDisabledError()
-        except Exception:
-            logger.exception("internal server error.")
-            raise InternalServerError()
 
-        return {"data": questions}
+@console_ns.route("/agent/<uuid:agent_id>/chat-messages/<uuid:message_id>/suggested-questions")
+class AgentMessageSuggestedQuestionApi(Resource):
+    @console_ns.doc("get_agent_message_suggested_questions")
+    @console_ns.doc(description="Get suggested questions for an Agent App message")
+    @console_ns.doc(params={"agent_id": "Agent ID", "message_id": "Message ID"})
+    @console_ns.response(
+        200,
+        "Suggested questions retrieved successfully",
+        console_ns.models[SuggestedQuestionsResponse.__name__],
+    )
+    @console_ns.response(404, "Agent, message, or conversation not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_user
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user: Account, agent_id: UUID, message_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _get_message_suggested_questions(current_user=current_user, app_model=app_model, message_id=message_id)
 
 
 @console_ns.route("/apps/<uuid:app_id>/feedbacks/export")
@@ -380,10 +325,11 @@ class MessageFeedbackExportApi(Resource):
     )
     @console_ns.response(400, "Invalid parameters")
     @console_ns.response(500, "Internal server error")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App):
         args = FeedbackExportQuery.model_validate(request.args.to_dict())
 
@@ -392,6 +338,7 @@ class MessageFeedbackExportApi(Resource):
 
         try:
             export_data = FeedbackService.export_feedbacks(
+                db.session(),
                 app_id=app_model.id,
                 from_source=args.from_source,
                 rating=args.rating,
@@ -418,19 +365,173 @@ class MessageApi(Resource):
     @console_ns.doc(params={"app_id": "Application ID", "message_id": "Message ID"})
     @console_ns.response(200, "Message retrieved successfully", console_ns.models[MessageDetailResponse.__name__])
     @console_ns.response(404, "Message not found")
-    @get_app_model
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
+    @get_app_model
     def get(self, app_model: App, message_id: UUID):
-        message_id_str = str(message_id)
+        return _get_message_detail(app_model=app_model, message_id=message_id)
 
-        message = db.session.scalar(
-            select(Message).where(Message.id == message_id_str, Message.app_id == app_model.id).limit(1)
+
+@console_ns.route("/agent/<uuid:agent_id>/messages/<uuid:message_id>")
+class AgentMessageApi(Resource):
+    @console_ns.doc("get_agent_message")
+    @console_ns.doc(description="Get Agent App message details by ID")
+    @console_ns.doc(params={"agent_id": "Agent ID", "message_id": "Message ID"})
+    @console_ns.response(200, "Message retrieved successfully", console_ns.models[MessageDetailResponse.__name__])
+    @console_ns.response(404, "Agent or message not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, agent_id: UUID, message_id: UUID):
+        app_model = resolve_agent_app_model(tenant_id=current_tenant_id, agent_id=agent_id)
+        return _get_message_detail(app_model=app_model, message_id=message_id)
+
+
+def _list_chat_messages(*, app_model: App):
+    args = ChatMessagesQuery.model_validate(request.args.to_dict())
+
+    conversation = db.session.scalar(
+        select(Conversation)
+        .where(Conversation.id == args.conversation_id, Conversation.app_id == app_model.id)
+        .limit(1)
+    )
+
+    if not conversation:
+        raise NotFound("Conversation Not Exists.")
+
+    if args.first_id:
+        first_message = db.session.scalar(
+            select(Message).where(Message.conversation_id == conversation.id, Message.id == args.first_id).limit(1)
         )
 
-        if not message:
-            raise NotFound("Message Not Exists.")
+        if not first_message:
+            raise NotFound("First message not found")
 
-        attach_message_extra_contents([message])
-        return MessageDetailResponse.model_validate(message, from_attributes=True).model_dump(mode="json")
+        history_messages = db.session.scalars(
+            select(Message)
+            .where(
+                Message.conversation_id == conversation.id,
+                Message.created_at < first_message.created_at,
+                Message.id != first_message.id,
+            )
+            .order_by(Message.created_at.desc())
+            .limit(args.limit)
+        ).all()
+    else:
+        history_messages = db.session.scalars(
+            select(Message)
+            .where(Message.conversation_id == conversation.id)
+            .order_by(Message.created_at.desc())
+            .limit(args.limit)
+        ).all()
+
+    # Initialize has_more based on whether we have a full page
+    if len(history_messages) == args.limit:
+        current_page_first_message = history_messages[-1]
+        # Check if there are more messages before the current page
+        has_more = db.session.scalar(
+            select(
+                exists().where(
+                    Message.conversation_id == conversation.id,
+                    Message.created_at < current_page_first_message.created_at,
+                    Message.id != current_page_first_message.id,
+                )
+            )
+        )
+    else:
+        # If we don't have a full page, there are no more messages
+        has_more = False
+
+    history_messages = list(reversed(history_messages))
+    attach_message_extra_contents(history_messages)
+
+    return MessageInfiniteScrollPaginationResponse.model_validate(
+        InfiniteScrollPagination(data=history_messages, limit=args.limit, has_more=has_more),
+        from_attributes=True,
+    ).model_dump(mode="json")
+
+
+def _update_message_feedback(*, current_user: Account, app_model: App):
+    args = MessageFeedbackPayload.model_validate(console_ns.payload)
+
+    message_id = str(args.message_id)
+
+    message = db.session.scalar(
+        select(Message).where(Message.id == message_id, Message.app_id == app_model.id).limit(1)
+    )
+
+    if not message:
+        raise NotFound("Message Not Exists.")
+
+    feedback = message.admin_feedback
+
+    if not args.rating and feedback:
+        db.session.delete(feedback)
+    elif args.rating and feedback:
+        feedback.rating = FeedbackRating(args.rating)
+        feedback.content = args.content
+    elif not args.rating and not feedback:
+        raise ValueError("rating cannot be None when feedback not exists")
+    else:
+        rating_value = args.rating
+        if rating_value is None:
+            raise ValueError("rating is required to create feedback")
+        feedback = MessageFeedback(
+            app_id=app_model.id,
+            conversation_id=message.conversation_id,
+            message_id=message.id,
+            rating=FeedbackRating(rating_value),
+            content=args.content,
+            from_source=FeedbackFromSource.ADMIN,
+            from_account_id=current_user.id,
+        )
+        db.session.add(feedback)
+
+    db.session.commit()
+
+    return {"result": "success"}
+
+
+def _get_message_suggested_questions(*, current_user: Account, app_model: App, message_id: UUID):
+    message_id_str = str(message_id)
+
+    try:
+        questions = MessageService.get_suggested_questions_after_answer(
+            app_model=app_model, message_id=message_id_str, user=current_user, invoke_from=InvokeFrom.DEBUGGER
+        )
+    except MessageNotExistsError:
+        raise NotFound("Message not found")
+    except ConversationNotExistsError:
+        raise NotFound("Conversation not found")
+    except ProviderTokenNotInitError as ex:
+        raise ProviderNotInitializeError(ex.description)
+    except QuotaExceededError:
+        raise ProviderQuotaExceededError()
+    except ModelCurrentlyNotSupportError:
+        raise ProviderModelCurrentlyNotSupportError()
+    except InvokeError as e:
+        raise CompletionRequestError(e.description)
+    except SuggestedQuestionsAfterAnswerDisabledError:
+        raise AppSuggestedQuestionsAfterAnswerDisabledError()
+    except Exception:
+        logger.exception("internal server error.")
+        raise InternalServerError()
+
+    return {"data": questions}
+
+
+def _get_message_detail(*, app_model: App, message_id: UUID):
+    message_id_str = str(message_id)
+
+    message = db.session.scalar(
+        select(Message).where(Message.id == message_id_str, Message.app_id == app_model.id).limit(1)
+    )
+
+    if not message:
+        raise NotFound("Message Not Exists.")
+
+    attach_message_extra_contents([message])
+    return MessageDetailResponse.model_validate(message, from_attributes=True).model_dump(mode="json")

api/controllers/console/app/model_config.py

@@ -10,8 +10,11 @@ from controllers.common.schema import register_response_schema_models, register_
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
     account_initialization_required,
     edit_permission_required,
+    rbac_permission_required,
     setup_required,
     with_current_tenant_id,
     with_current_user_id,
@@ -86,10 +89,11 @@ class ModelConfigResource(Resource):
     @setup_required
     @login_required
     @edit_permission_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_VIEW_LAYOUT)
     @account_initialization_required
-    @get_app_model(mode=[AppMode.AGENT_CHAT, AppMode.CHAT, AppMode.COMPLETION])
     @with_current_user_id
     @with_current_tenant_id
+    @get_app_model(mode=[AppMode.AGENT_CHAT, AppMode.CHAT, AppMode.COMPLETION])
     def post(self, current_tenant_id: str, current_user_id: str, app_model: App):
         """Modify app model config"""
         # validate config

api/controllers/console/app/ops_trace.py

@@ -9,7 +9,13 @@ from controllers.common.schema import query_params_from_model, register_response
 from controllers.console import console_ns
 from controllers.console.app.error import TracingConfigCheckError, TracingConfigIsExist, TracingConfigNotExist
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import account_initialization_required, setup_required
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    rbac_permission_required,
+    setup_required,
+)
 from fields.base import ResponseModel
 from libs.login import login_required
 from models import App
@@ -64,6 +70,7 @@ class TraceAppConfigApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_MONITOR)
     @get_app_model
     def get(self, app_model: App):
         args = TraceProviderQuery.model_validate(request.args.to_dict(flat=True))  # type: ignore