sim117

.

.

.

.

.

.

?

?

?

done

fix

[autofix.ci] apply automated fixes

[autofix.ci] apply automated fixes

[autofix.ci] apply automated fixes (attempt 2/3)

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

@@ -1,168 +1,40 @@
 ---
 name: backend-code-review
-description: Review backend code for quality, security, maintainability, and best practices based on established checklist rules. Use when the user requests a review, analysis, or improvement of backend files (e.g., `.py`) under the `api/` directory. Do NOT use for frontend files (e.g., `.tsx`, `.ts`, `.js`). Supports pending-change review, code snippets review, and file-focused review.
+description: Use only when the user explicitly requests a review or audit of backend code under `api/`. Supports pending-change, file-focused, and pasted-diff reviews. Do not use for implementation-only requests, diagnosis without review intent, frontend code, or backend code outside `api/`.
 ---
 
 # Backend Code Review
 
-## When to use this skill
+Review the requested scope for concrete, reproducible defects. The nearest `AGENTS.md` owns package facts and commands; this skill owns the review workflow and routes to its bundled rule packs.
 
-Use this skill whenever the user asks to **review, analyze, or improve** backend code (e.g., `.py`) under the `api/` directory. Supports the following review modes:
+## Evidence First
 
-- **Pending-change review**: when the user asks to review current changes (inspect staged/working-tree files slated for commit to get the changes).
-- **Code snippets review**: when the user pastes code snippets (e.g., a function/class/module excerpt) into the chat and asks for a review.
-- **File-focused review**: when the user points to specific files and asks for a review of those files (one file or a small, explicit set of files, e.g., `api/...`, `api/app.py`).
+1. Establish the requested review scope and inspect the relevant diff or files.
+2. Read the changed lines, their behavior owner, nearby tests, and local docstrings or comments that define contracts.
+3. Trace callers, persistence boundaries, authorization, generated schemas, or external I/O only when they decide correctness.
+4. Report only findings tied to an observable failure, violated contract, security boundary, data integrity risk, or demonstrated maintenance problem.
 
-Do NOT use this skill when:
+## Rule Routing
 
-- The request is about frontend code or UI (e.g., `.tsx`, `.ts`, `.js`, `web/`).
-- The user is not asking for a review/analysis/improvement of backend code.
-- The scope is not under `api/` (unless the user explicitly asks to review backend-related changes outside `api/`).
+Read only the packs matched by the diff:
 
-## How to use this skill
+- Models or migrations: [`references/db-schema-rule.md`][db-schema]
+- Controller, service, core/domain, library, or model dependency direction: [`references/architecture-rule.md`][architecture]
+- Table access outside an established repository boundary: [`references/repositories-rule.md`][repositories]
+- SQLAlchemy sessions, queries, transactions, CRUD, concurrency, or raw SQL: [`references/sqlalchemy-rule.md`][sqlalchemy]
 
-Follow these steps when using this skill:
+When no pack applies, review correctness, security, behavior changes, and test evidence directly. Check current official documentation only when local code and contracts do not settle framework or library behavior.
 
-1. **Identify the review mode** (pending-change vs snippet vs file-focused) based on the user’s input. Keep the scope tight: review only what the user provided or explicitly referenced.
-2. Follow the rules defined in **Checklist** to perform the review. If no Checklist rule matches, apply **General Review Rules** as a fallback to perform the best-effort review.
-3. Compose the final output strictly follow the **Required Output Format**.
+## Severity And Output
 
-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.
+- **P0**: security or privacy exposure, data loss, or a production-wide outage.
+- **P1**: user-visible regression, broken authorization or tenant isolation, invalid public contract, or failed primary workflow.
+- **P2**: concrete correctness, performance, maintainability, or test defect likely to cause incorrect behavior.
+- **P3**: minor actionable cleanup; omit unless the user requested a thorough audit.
 
-## Checklist
+Lead with findings ordered by severity. Include a tight file and line reference, the failing contract or reproduction path, impact, and a concrete fix direction. If there are no findings, say `No issues found.` and state any material verification gap. Do not add praise sections, speculative risks, or an unsolicited offer to implement fixes.
 
-- db schema design: if the review scope includes code/files under `api/models/` or `api/migrations/`, follow [references/db-schema-rule.md](references/db-schema-rule.md) to perform the review
-- architecture: if the review scope involves controller/service/core-domain/libs/model layering, dependency direction, or moving responsibilities across modules, follow [references/architecture-rule.md](references/architecture-rule.md) to perform the review
-- repositories abstraction: if the review scope contains table/model operations (e.g., `select(...)`, `session.execute(...)`, joins, CRUD) and is not under `api/repositories`, `api/core/repositories`, or `api/extensions/*/repositories/`, follow [references/repositories-rule.md](references/repositories-rule.md) to perform the review
-- sqlalchemy patterns: if the review scope involves SQLAlchemy session/query usage, db transaction/crud usage, or raw SQL usage, follow [references/sqlalchemy-rule.md](references/sqlalchemy-rule.md) to perform the review
-
-## General Review Rules
-
-### 1. Security Review
-
-Check for:
-- SQL injection vulnerabilities
-- Server-Side Request Forgery (SSRF)
-- Command injection
-- Insecure deserialization
-- Hardcoded secrets/credentials
-- Improper authentication/authorization
-- Insecure direct object references
-
-### 2. Performance Review
-
-Check for:
-- N+1 queries
-- Missing database indexes
-- Memory leaks
-- Blocking operations in async code
-- Missing caching opportunities
-
-### 3. Code Quality Review
-
-Check for:
-- Code forward compatibility
-- Code duplication (DRY violations)
-- Functions doing too much (SRP violations)
-- Deep nesting / complex conditionals
-- Magic numbers/strings
-- Poor naming
-- Missing error handling
-- Incomplete type coverage
-
-### 4. Testing Review
-
-Check for:
-- Missing test coverage for new code
-- Tests that don't test behavior
-- Flaky test patterns
-- Missing edge cases
-
-## Required Output Format
-
-When this skill invoked, the response must exactly follow one of the two templates:
-
-### Template A (any findings)
-
-```markdown
-# Code Review Summary
-
-Found <X> critical issues need to be fixed:
-
-## 🔴 Critical (Must Fix)
-
-### 1. <brief description of the issue>
-
-FilePath: <path> line <line>
-<relevant code snippet or pointer>
-
-#### Explanation
-
-<detailed explanation and references of the issue>
-
-#### Suggested Fix
-
-1. <brief description of suggested fix>
-2. <code example> (optional, omit if not applicable)
-
----
-... (repeat for each critical issue) ...
-
-Found <Y> suggestions for improvement:
-
-## 🟡 Suggestions (Should Consider)
-
-### 1. <brief description of the suggestion>
-
-FilePath: <path> line <line>
-<relevant code snippet or pointer>
-
-#### Explanation
-
-<detailed explanation and references of the suggestion>
-
-#### Suggested Fix
-
-1. <brief description of suggested fix>
-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>
-<relevant code snippet or pointer>
-
-#### Explanation
-
-<explanation and references of the optional nit>
-
-#### Suggested Fix
-
-- <minor suggestions>
-
----
-... (repeat for each nits) ...
-
-## ✅ What's Good
-
-- <Positive feedback on good patterns>
-```
-
-- If there are no critical issues or suggestions or option nits or good points, just omit that section.
-- If the issue number is more than 10, summarize as "Found 10+ critical issues/suggestions/optional nits" and only output the first 10 items.
-- Don't compress the blank lines between sections; keep them as-is for readability.
-- If there is any issue requires code changes, append a brief follow-up question to ask whether the user wants to apply the fix(es) after the structured output. For example: "Would you like me to use the Suggested fix(es) to address these issues?"
-
-### Template B (no issues)
-
-```markdown
-## Code Review Summary
-✅ No issues found.
-```
+[architecture]: references/architecture-rule.md
+[db-schema]: references/db-schema-rule.md
+[repositories]: references/repositories-rule.md
+[sqlalchemy]: references/sqlalchemy-rule.md

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

@@ -7,7 +7,6 @@
 
 ### 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.
 - Suggested fix: Move domain/business logic into the service or core/domain layer. Keep controller handlers thin and orchestration-focused.
 - Example:
@@ -34,7 +33,6 @@
 
 ### 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:
@@ -58,7 +56,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.
 - Suggested fix:
   - If business logic appears in `api/libs/`, extract it into the appropriate `services/` or `core/` module and keep `libs` focused on generic, cross-cutting helpers.
@@ -88,4 +85,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

@@ -8,7 +8,6 @@
 
 ### 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.
 - Suggested fix:
   - Keep model properties pure and local to already-loaded fields.
@@ -41,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.
 - Suggested fix:
   - Add a `tenant_id` column and ensure related unique/index constraints include tenant dimension when applicable.
@@ -70,7 +68,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.
 - Suggested fix:
   - Before adding an index, compare against existing composite indexes by leftmost-prefix rules.
@@ -94,7 +91,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.
 - Suggested fix:
   - Do not directly place dialect-only types/operators in model columns when a portable wrapper can be used.
@@ -122,7 +118,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.
 - Suggested fix:
   - In migration upgrades/downgrades, bind connection and branch by dialect for incompatible SQL fragments.

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

@@ -8,7 +8,6 @@
 
 ### 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.

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

@@ -8,7 +8,6 @@
 
 ### 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.
 - Suggested fix:
   - Use **explicit `session.commit()`** after completing a related write unit.
@@ -47,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.
 - Suggested fix: Add `tenant_id` predicate to all tenant-owned entity queries and propagate tenant context through service/repository interfaces.
 - Example:
@@ -67,7 +65,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.
 - Suggested fix: Rewrite straightforward raw SQL into SQLAlchemy `select/update/delete` expressions; keep raw SQL only when required by clear technical constraints.
 - Example:
@@ -89,7 +86,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.
 - Suggested fix:
   - **Optimistic locking**: Use when contention is usually low and retries are acceptable. Add a version (or updated_at) guard in `WHERE` and treat `rowcount == 0` as a conflict.
@@ -136,4 +132,4 @@
     ).scalar_one()
     run.status = "cancelled"
     session.commit()
-    ```
+    ```

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

@@ -1,79 +1,31 @@
 ---
 name: e2e-cucumber-playwright
-description: Write, update, or review Dify end-to-end tests under `e2e/` that use Cucumber, Gherkin, and Playwright. Use when the task involves `.feature` files, `features/step-definitions/`, `features/support/`, `DifyWorld`, scenario tags, locator/assertion choices, or E2E testing best practices for this repository.
+description: Use when writing, changing, or reviewing Cucumber and Playwright tests under `e2e/`, including feature files, step definitions, support code, scenario tags, locators, and assertions. Do not use for Vitest, React Testing Library, backend tests, or generic browser automation outside the E2E suite.
 ---
 
-# Dify E2E Cucumber + Playwright
+# E2E Cucumber And Playwright
 
-Use this skill for Dify's repository-level E2E suite in `e2e/`. Use [`e2e/AGENTS.md`](../../../e2e/AGENTS.md) as the canonical guide for local architecture and conventions, then apply Playwright/Cucumber best practices only where they fit the current suite.
+`e2e/AGENTS.md` owns the suite architecture, lifecycle, commands, tags, generated-client boundaries, fixtures, and cleanup contracts. Read the nearest feature-scoped `AGENTS.md` when one exists. This skill adds no parallel package policy.
 
-## Scope
+## Topic Routing
 
-- Use this skill for `.feature` files, Cucumber step definitions, `DifyWorld`, hooks, tags, and E2E review work under `e2e/`.
-- Do not use this skill for Vitest or React Testing Library work under `web/`; use `frontend-testing` instead.
-- Do not use this skill for backend test or API review tasks under `api/`.
+Read only the bundled reference required by the change:
 
-## Read Order
+- Locator, assertion, isolation, or waiting decisions: [`references/playwright-best-practices.md`][playwright]
+- Scenario wording, step granularity, expressions, or tag design: [`references/cucumber-best-practices.md`][cucumber]
 
-1. Read [`e2e/AGENTS.md`](../../../e2e/AGENTS.md) first.
-2. Read only the files directly involved in the task:
-   - target `.feature` files under `e2e/features/`
-   - related step files under `e2e/features/step-definitions/`
-   - `e2e/features/support/hooks.ts` and `e2e/features/support/world.ts` when session lifecycle or shared state matters
-   - `e2e/scripts/run-cucumber.ts` and `e2e/cucumber.config.ts` when tags or execution flow matter
-3. Read [`references/playwright-best-practices.md`](references/playwright-best-practices.md) only when locator, assertion, isolation, or waiting choices are involved.
-4. Read [`references/cucumber-best-practices.md`](references/cucumber-best-practices.md) only when scenario wording, step granularity, tags, or expression design are involved.
-5. Re-check official Playwright or Cucumber docs with the available documentation tools before introducing a new framework pattern.
-
-## Local Rules
-
-- `e2e/` uses Cucumber for scenarios and Playwright as the browser layer.
-- `DifyWorld` is the per-scenario context object. Type `this` as `DifyWorld` and use `async function`, not arrow functions.
-- Keep glue organized by capability under `e2e/features/step-definitions/`; use `common/` only for broadly reusable steps.
-- Browser session behavior comes from `features/support/hooks.ts`:
-  - default: authenticated session with shared storage state
-  - `@unauthenticated`: clean browser context
-  - `@authenticated`: readability/selective-run tag only unless implementation changes
-  - `@fresh`: only for `e2e:full*` flows
-- Do not import Playwright Test runner patterns that bypass the current Cucumber + `DifyWorld` architecture unless the task is explicitly about changing that architecture.
+Check current official Playwright or Cucumber documentation before introducing a framework pattern that local code and references do not already establish.
 
 ## Workflow
 
-1. Rebuild local context.
-   - Inspect the target feature area.
-   - Reuse an existing step when wording and behavior already match.
-   - Add a new step only for a genuinely new user action or assertion.
-   - Keep edits close to the current capability folder unless the step is broadly reusable.
-2. Write behavior-first scenarios.
-   - Describe user-observable behavior, not DOM mechanics.
-   - Keep each scenario focused on one workflow or outcome.
-   - Keep scenarios independent and re-runnable.
-3. Write step definitions in the local style.
-   - Keep one step to one user-visible action or one assertion.
-   - Prefer Cucumber Expressions such as `{string}` and `{int}`.
-   - Scope locators to stable containers when the page has repeated elements.
-   - Avoid page-object layers or extra helper abstractions unless repeated complexity clearly justifies them.
-4. Use Playwright in the local style.
-   - Prefer user-facing locators: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, then `getByTestId` for explicit contracts.
-   - Use web-first `expect(...)` assertions.
-   - Do not use `waitForTimeout`, manual polling, or raw visibility checks when a locator action or retrying assertion already expresses the behavior.
-5. Validate narrowly.
-   - Run the narrowest tagged scenario or flow that exercises the change.
-   - Run `pnpm -C e2e check`.
-   - Broaden verification only when the change affects hooks, tags, setup, or shared step semantics.
+1. Add E2E coverage only for a critical user journey with a cross-boundary outcome that cheaper owner-level tests do not already prove.
+2. Identify the user-visible behavior and its feature owner. Start from real product defaults and actor roles; setup may establish preconditions but must not manufacture the opposite state to make the scenario meaningful.
+3. Read the target scenario, matching step definitions, and lifecycle files only when session or shared state matters.
+4. Reuse an existing step when wording and behavior match; add one coherent scenario or step when they do not.
+5. Keep browser actions and assertions at the public user boundary; keep setup, seed, polling, and cleanup at their package-defined owners.
+6. Run the narrowest tagged scenario and package checks documented in `e2e/AGENTS.md`; broaden only for shared hooks, tags, or support changes.
 
-## Review Checklist
+For review requests, lead with reproducible correctness failures, flake sources, or demonstrated architecture drift. Report the behavior verified and any external-runtime, browser, or environment gap.
 
-- Does the scenario describe behavior rather than implementation?
-- Does it fit the current session model, tags, and `DifyWorld` usage?
-- Should an existing step be reused instead of adding a new one?
-- Are locators user-facing and assertions web-first?
-- Does the change introduce hidden coupling across scenarios, tags, or instance state?
-- Does it document or implement behavior that differs from the real hooks or configuration?
-
-Lead findings with correctness, flake risk, and architecture drift.
-
-## References
-
-- [`references/playwright-best-practices.md`](references/playwright-best-practices.md)
-- [`references/cucumber-best-practices.md`](references/cucumber-best-practices.md)
+[cucumber]: references/cucumber-best-practices.md
+[playwright]: references/playwright-best-practices.md

.agents/skills/e2e-cucumber-playwright/references/cucumber-best-practices.md

@@ -1,12 +1,12 @@
-# Cucumber Best Practices For Dify E2E
+# Cucumber Best Practices
 
-Use this reference when writing or reviewing Gherkin scenarios, step definitions, parameter expressions, and step reuse in Dify's `e2e/` suite.
+Use this reference when writing or reviewing Gherkin scenarios, step definitions, parameter expressions, and step reuse.
 
 Official sources:
 
-- https://cucumber.io/docs/guides/10-minute-tutorial/
-- https://cucumber.io/docs/cucumber/step-definitions/
-- https://cucumber.io/docs/cucumber/cucumber-expressions/
+- https://cucumber.io/docs/guides/10-minute-tutorial
+- https://cucumber.io/docs/cucumber/step-definitions
+- https://cucumber.io/docs/cucumber/cucumber-expressions
 
 ## What Matters Most
 
@@ -24,11 +24,7 @@ Apply it like this:
 
 A scenario should usually prove one workflow or business outcome. If a scenario wanders across several unrelated behaviors, split it.
 
-In Dify's suite, this means:
-
-- one capability-focused scenario per feature path
-- no long setup chains when existing bootstrap or reusable steps already cover them
-- no hidden dependency on another scenario's side effects
+Keep each scenario centered on one coherent outcome. Avoid hidden dependencies on another scenario's side effects, and keep unavoidable setup outside the behavior narrative unless the precondition matters to the specification.
 
 ### 3. Reuse steps, but only when behavior really matches
 
@@ -39,6 +35,7 @@ Prefer reuse when:
 - the user action is genuinely the same
 - the expected outcome is genuinely the same
 - the wording stays natural across features
+- the parameter is a real product domain value such as a named surface, mode, resource, or status
 
 Write a new step when:
 
@@ -46,6 +43,8 @@ Write a new step when:
 - reusing the old wording would make the scenario misleading
 - a supposedly generic step would become an implementation-detail wrapper
 
+Do not optimize for a low step count by making vague steps. Optimize for a small set of truthful, domain-owned steps.
+
 ### 4. Prefer Cucumber Expressions
 
 Use Cucumber Expressions for parameters unless regex is clearly necessary.
@@ -59,30 +58,17 @@ Common examples:
 
 Keep expressions readable. If a step needs complicated parsing logic, first ask whether the scenario wording should be simpler.
 
+Use regex for a bounded natural-language alternative only when it keeps Gherkin readable, for example `/(Web app|Backend service API)/`. Avoid broad regexes that accept unowned language.
+
 ### 5. Keep step definitions thin and meaningful
 
 Step definitions are glue between Gherkin and automation, not a second abstraction language.
 
-For Dify:
-
-- type `this` as `DifyWorld`
-- use `async function`
-- keep each step to one user-visible action or assertion
-- rely on `DifyWorld` and existing support code for shared context
-- avoid leaking cross-scenario state
+Keep each step to one user-visible action or assertion. In JavaScript and TypeScript, use `async function` when the step reads Cucumber World state because Cucumber binds `this`; do not leak state across scenarios through module globals.
 
 ### 6. Use tags intentionally
 
-Tags should communicate run scope or session semantics, not become ad hoc metadata.
-
-In Dify's current suite:
-
-- capability tags group related scenarios
-- `@unauthenticated` changes session behavior
-- `@authenticated` is descriptive/selective, not a behavior switch by itself
-- `@fresh` belongs to reset/full-install flows only
-
-If a proposed tag implies behavior, verify that hooks or runner configuration actually implement it.
+Tags should communicate selection or execution intent, not become ad hoc metadata. A tag does not change runtime behavior unless configuration or hooks implement it.
 
 ## Review Questions
 

.agents/skills/e2e-cucumber-playwright/references/playwright-best-practices.md

@@ -1,6 +1,6 @@
-# Playwright Best Practices For Dify E2E
+# Playwright Best Practices
 
-Use this reference when writing or reviewing locator, assertion, isolation, or synchronization logic for Dify's Cucumber-based E2E suite.
+Use this reference when writing or reviewing locator, assertion, isolation, or synchronization logic.
 
 Official sources:
 
@@ -13,20 +13,19 @@ Official sources:
 
 ### 1. Keep scenarios isolated
 
-Playwright's model is built around clean browser contexts so one test does not leak into another. In Dify's suite, that principle maps to per-scenario session setup in `features/support/hooks.ts` and `DifyWorld`.
+Playwright's model is built around clean browser contexts so one test does not leak into another.
 
 Apply it like this:
 
 - do not depend on another scenario having run first
-- do not persist ad hoc scenario state outside `DifyWorld`
-- do not couple ordinary scenarios to `@fresh` behavior
-- when a flow needs special auth/session semantics, express that through the existing tag model or explicit hook changes
+- keep scenario state in the runner's scenario-owned context rather than module globals
+- model special authentication or session setup through explicit per-scenario fixtures rather than shared mutable state
 
 ### 2. Prefer user-facing locators
 
 Playwright recommends built-in locators that reflect what users perceive on the page.
 
-Preferred order in this repository:
+Preferred order:
 
 1. `getByRole`
 2. `getByLabel`
@@ -41,6 +40,7 @@ Also remember:
 - repeated content usually needs scoping to a stable container
 - exact text matching is often too brittle when role/name or label already exists
 - `getByTestId` is acceptable when semantics are weak but the contract is intentional
+- when a real UI region, card, status, or icon lacks an accessible name, prefer adding that semantic contract in product code before falling back to `getByTestId`
 
 ### 3. Use web-first assertions
 
@@ -62,6 +62,8 @@ Avoid:
 
 If a condition genuinely needs custom retry logic, use Playwright's polling/assertion tools deliberately and keep that choice local and explicit.
 
+Use `expect.poll` for non-DOM truth such as API state, backend eventual consistency, generated resources, or captured browser events. For DOM state, use locator assertions so Playwright can apply actionability and web-first retry semantics.
+
 ### 4. Let actions wait for actionability
 
 Locator actions already wait for the element to be actionable. Do not preface every click/fill with extra timing logic unless the action needs a specific visible/ready assertion for clarity.
@@ -76,16 +78,9 @@ Bad pattern:
 - stack arbitrary waits before every action
 - wait on unstable implementation details instead of the visible state the user cares about
 
-### 5. Match debugging to the current suite
+### 5. Match debugging to the active harness
 
-Playwright's wider ecosystem supports traces and rich debugging tools. Dify's current suite already captures:
-
-- full-page screenshots
-- page HTML
-- console errors
-- page errors
-
-Use the existing artifact flow by default. If a task is specifically about improving diagnostics, confirm the change fits the current Cucumber architecture before importing broader Playwright tooling.
+Playwright supports traces, screenshots, page snapshots, and browser logs. Configure artifact capture at the runner boundary instead of adding parallel diagnostics to individual scenarios.
 
 ## Review Questions
 
@@ -93,4 +88,4 @@ Use the existing artifact flow by default. If a task is specifically about impro
 - Is this assertion using Playwright's retrying semantics?
 - Is any explicit wait masking a real readiness problem?
 - Does this code preserve per-scenario isolation?
-- Is a new abstraction really needed, or does it bypass the existing `DifyWorld` + step-definition model?
+- Is a new abstraction really needed, or does it bypass the runner's scenario-owned context and lifecycle?

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

@@ -1,94 +1,48 @@
 ---
 name: frontend-code-review
-description: Review Dify frontend code for correctness, accessibility, component design, dify-ui usage, data/query boundaries, performance, and tests. Trigger for `.tsx`, `.ts`, `.js`, UI, React, Next.js, pending-change, or focused frontend review requests.
+description: Use only when the user explicitly requests a review or audit of frontend code under `web/` or `packages/dify-ui/`. Supports pending-change, file-focused, and pasted-diff reviews. Do not use for implementation-only requests, diagnosis without review intent, or backend-only code.
 ---
 
 # Frontend Code Review
 
-## When To Use
+Review the requested scope for concrete, reproducible regressions. This skill owns the review phase and routes directly to its bundled rule packs. For a combined review-and-fix request, establish findings before applying implementation or testing guidance.
 
-Use this skill when the user asks to review, audit, analyze, or sanity-check frontend code under `web/`, `packages/dify-ui/`, or frontend-adjacent TypeScript files.
+## Evidence First
 
-Supported modes:
+1. Establish the review scope from the requested files or current diff.
+2. Read the changed lines, their behavior owner, and the nearest scoped `AGENTS.md`.
+3. Trace public consumers, generated contracts, primitive APIs, or runtime configuration only when they decide correctness.
+4. Report only findings tied to an observable failure, violated contract, security boundary, or demonstrated maintenance risk.
 
-- **Pending-change review**: inspect staged and working-tree changes.
-- **File-focused review**: inspect explicitly named files or paths.
-- **Diff/snippet review**: review pasted diffs or snippets using best-effort references.
+## Rule Routing
 
-Do not use this skill for backend-only code under `api/`; use `backend-code-review` instead.
+Read only the packs matched by the diff:
 
-## Required Context
+- DOM semantics, focus, keyboard, forms, disabled state, or visible interaction: [`references/accessibility-ui.md`][accessibility]
+- Dify UI imports, Base UI wrappers, overlays, tokens, or primitive contracts: [`references/dify-ui.md`][dify-ui]
+- Component ownership, props, state, Effects, navigation, or module boundaries: [`references/component-architecture.md`][component-architecture]
+- Generated clients, Query, mutations, auth, SSR, URL state, or persistence: [`references/data-query-contracts.md`][data-query]
+- Test files or a concrete missing-regression-test finding: [`references/testing.md`][testing]
+- Bundle, waterfall, rendering, or subscription cost supported by evidence: [`references/performance.md`][performance]
+- Stable Dify runtime invariants in the named paths: [`references/dify-invariants.md`][dify-invariants]
+- General TypeScript or styling quality not owned above: [`references/code-quality.md`][code-quality]
 
-Before reviewing, read the relevant local contracts:
+Read `packages/dify-ui/README.md`, `packages/dify-ui/AGENTS.md`, `packages/dify-ui/docs/overlays.md`, or `web/docs/test.md` only when the reviewed code falls under that contract. Check current official documentation when local code and bundled references do not settle a framework, browser, or accessibility behavior.
 
-- `web/AGENTS.md` for Dify frontend workflow, overlays, design tokens, state, and tests.
-- `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md` when code uses or changes `@langgenius/dify-ui/*`.
-- `web/docs/overlay.md` when reviewing dialogs, drawers, popovers, tooltips, menus, selects, comboboxes, or other floating UI.
-- `web/docs/test.md` and the `frontend-testing` skill when reviewing tests or testability.
-- `karpathy-guidelines` for scope control and focused, verifiable changes.
-- `how-to-write-component` when reviewing React component structure, ownership, effects, query/mutation contracts, or memoization.
+## Severity And Output
 
-For any UI, UX, or accessibility review, fetch the latest Web Interface Guidelines before finalizing findings. Treat them as a required baseline, not the complete source of accessibility truth:
+- **P0**: security or privacy leak, data loss, production crash, or inaccessible critical workflow.
+- **P1**: user-visible regression, invalid API or authorization contract, hydration failure, or broken primary interaction.
+- **P2**: concrete maintainability, performance, test, or accessibility defect likely to cause incorrect behavior.
+- **P3**: minor actionable cleanup; omit unless the user requested a thorough audit.
 
-```text
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
+Lead with findings ordered by severity. Include a tight file and line reference, the failing contract or reproduction path, impact, and a concrete fix direction. If there are no findings, say `No issues found.` and state any material verification gap. Do not add praise sections, speculative risks, or an unsolicited offer to implement fixes.
 
-If the review depends on a current framework, SDK, browser API, or accessibility behavior and local code does not settle it, check the current official docs first. For browser compatibility, deprecation, or behavior-sensitive frontend APIs, verify MDN or the relevant standard.
-
-## Rule Packs
-
-Apply every relevant rule pack:
-
-- [references/accessibility-ui.md](references/accessibility-ui.md) — accessibility, semantic HTML, focus, forms, keyboard, disabled states, copy, and long-content behavior. Combines Web Interface Guidelines with Dify UI, Base UI, MDN, and local primitive contracts.
-- [references/dify-ui.md](references/dify-ui.md) — Dify UI primitive usage, Base UI semantics, overlays, forms, tokens, radius mapping, and primitive boundaries.
-- [references/component-architecture.md](references/component-architecture.md) — component ownership, props, state, effects, exports, wrappers, and feature organization.
-- [references/data-query-contracts.md](references/data-query-contracts.md) — generated contracts, TanStack Query, mutations, workspace/auth/SSR boundaries, URL/local storage state.
-- [references/performance.md](references/performance.md) — React/Next performance review rules from Vercel guidance, scoped to real risk.
-- [references/testing.md](references/testing.md) — frontend test review rules.
-- [references/dify-invariants.md](references/dify-invariants.md) — stable Dify-specific runtime invariants that generic React/a11y rules will not catch.
-- [references/code-quality.md](references/code-quality.md) — general TypeScript, styling, naming, and maintainability rules.
-
-## Review Process
-
-1. Identify the review scope. For pending changes, inspect `git diff --stat`, `git diff`, and staged diff if relevant. For file-focused reviews, stay within the named files unless a referenced owner/contract must be read.
-2. Read code around the changed lines and the owning module. Do not review by isolated snippets when nearby ownership, labels, query inputs, or overlay structure decide correctness.
-3. Check user-visible regressions first: accessibility, broken interaction, auth/permission leaks, query/hydration errors, data loss, navigation mistakes, and impossible states.
-4. Then check maintainability and performance: ownership, effects, wrappers, memoization, bundle/waterfall risks, tests, and design-system drift.
-5. Report only actionable findings. Do not list speculative risks, style preferences, or broad refactors unless they are directly tied to a reproducible issue in scope.
-
-## Severity
-
-- **P0**: security/privacy/auth leak, data loss, production crash, inaccessible critical flow, or broken primary workflow.
-- **P1**: user-visible regression, hydration/SSR failure, invalid API/query contract, broken keyboard/focus behavior, or serious design-system/a11y violation.
-- **P2**: maintainability or performance issue likely to cause bugs, duplicated state, incorrect ownership, missing tests for risky behavior, or non-critical a11y issue.
-- **P3**: minor cleanup with clear value. Omit unless the user asked for a thorough audit.
-
-## Output Format
-
-Lead with findings, ordered by severity. Use this structure:
-
-```markdown
-## Findings
-
-- [P1] Short issue title
-  File: `path/to/file.tsx:123`
-  Why it matters and how to reproduce or reason about it.
-  Suggested fix: concrete fix direction.
-
-## Open Questions
-
-- Question or assumption, if any.
-
-## Summary
-
-Brief secondary context. Mention tests not run or residual risk.
-```
-
-Rules:
-
-- If there are no findings, say `No issues found.` and mention any test gaps or residual risk.
-- Always include file and line when available.
-- Keep findings concrete and reproducible.
-- Do not include praise sections by default.
-- Do not ask to apply fixes unless the user explicitly wants review plus implementation.
+[accessibility]: references/accessibility-ui.md
+[code-quality]: references/code-quality.md
+[component-architecture]: references/component-architecture.md
+[data-query]: references/data-query-contracts.md
+[dify-invariants]: references/dify-invariants.md
+[dify-ui]: references/dify-ui.md
+[performance]: references/performance.md
+[testing]: references/testing.md

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

@@ -46,14 +46,13 @@ When existing components already own interaction logic, prefer reusing or extend
 
 Flag:
 
-- `React.FC` / `FC`.
-- Default exports outside framework-required files.
+- Declaration or export rewrites made only for stylistic uniformity, without changing an owned behavior or contract.
 - Named `Props` types for trivial one-off props where inline typing is clearer.
 - Props named by UI implementation instead of domain/API role.
 - API data converted too early or under a generic name that breaks traceability.
 - Callers duplicating fallback checks that the lowest rendering component already handles.
 
-Prefer top-level `function` declarations for components and module helpers. Use arrow functions for callbacks and local lambdas.
+Do not flag `FC`, `React.FC`, function declarations, arrow functions, named exports, or default exports by syntax alone. Report them only when the chosen form causes a concrete type, lifecycle, export, framework, or enforced package-contract defect.
 
 ## Effects
 
@@ -62,7 +61,7 @@ Flag effects that:
 - Transform props/state for rendering.
 - Copy one state value into another representing the same concept.
 - Handle user actions that belong in event handlers.
-- Reset state from props when a keyed reset, stable ID, or render-time derivation would work.
+- Reset local state from props or visibility when derivation, a stable semantic identity, or the intended mounted owner already expresses the lifecycle.
 - Fetch data that belongs in framework APIs or TanStack Query.
 
 If an effect remains, it must synchronize with a named external system: browser API, subscription, timer, analytics-on-visibility, non-React widget, or imperative DOM integration.
@@ -72,11 +71,24 @@ If an effect remains, it must synchronize with a named external system: browser
 Flag:
 
 - Storing derived booleans, disabled flags, default tabs, or loading labels that can be calculated from current query/feature state.
+- Per-session state held by a longer-lived visibility coordinator and cleared through an open-state Effect or a generated key when the primitive's mounted-content lifecycle already matches the intended state lifetime.
+- A DOM field mirrored into competing prop, default, and React state sources when editing does not require those sources to synchronize.
 - Local state used to fake server data or generated contract fields.
 - UI state persisted to localStorage when it is live app state.
 - Feature-local mock shells wired to unrelated existing APIs before the real API is confirmed.
 
-Prefer render-time derivation. Keep true local state for user choices, transient input, controlled popups, and feature UI state that has no server source.
+Review state lifetime before its storage mechanism. For a hidden surface, distinguish the
+visibility coordinator from mounted content. State private to one mounted session belongs in that
+content owner; promote it only when the draft must survive that content owner's unmount or another
+owner coordinates it. A stable semantic identity key may create a new snapshot when the represented
+identity changes; a generated key is not a routine reset command.
+
+Prefer render-time derivation. Keep true local state for user choices, transient input, controlled
+popups, and feature UI state that has no server source. Submit-only DOM fields may remain
+uncontrolled; use local controlled state when React must own the current value to drive rendering
+or coordination. Observing change events or tracking a derived fact such as dirty state does not
+require mirroring the field value. Do not flag controlled state by itself without a concrete
+competing-source, stale-state, or ownership defect.
 
 ## Navigation
 

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

@@ -12,7 +12,7 @@ Flag:
 - Re-declaring API DTOs in components.
 - Adding compatibility layers instead of migrating the pointed line and deleting the old layer.
 
-Use `web/contract/*` as the API shape source of truth. Follow existing `{ params, query?, body? }` input shape.
+Backend Pydantic and OpenAPI schemas own API shape. Generated clients and schemas under `packages/contracts/generated/*` are authoritative at frontend boundaries and use the `{ params, query?, body? }` input shape.
 
 ## Queries
 

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

@@ -1,134 +1,29 @@
-# Dify UI Rules
+# Dify UI Review Routing
 
-Use these rules whenever a review touches `packages/dify-ui/` or code consuming `@langgenius/dify-ui/*`.
+Use this reference when a review touches `packages/dify-ui/` or consumes
+`@langgenius/dify-ui/*`. It routes to owner documentation; it does not redefine package
+contracts.
 
-Before finalizing findings for those files, read the current local docs that apply:
+Read `packages/dify-ui/AGENTS.md` and the primitive implementation first, then only the matching
+owner:
 
-- `packages/dify-ui/README.md`
-- `packages/dify-ui/AGENTS.md`
-- `web/docs/overlay.md` for floating UI
-- `packages/dify-ui/src/<primitive>/index.tsx` for the primitive being changed or consumed
+| Review area                                | Canonical owner                                                     |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| Package boundary and document routing      | `packages/dify-ui/AGENTS.md`                                        |
+| Imports, exports, public types, and anatomy | `packages/dify-ui/docs/authoring.md`                                 |
+| Button or icon-only actions                | `packages/dify-ui/src/button/README.md`, `packages/dify-ui/src/icon-button/README.md` |
+| Compound inputs                            | `packages/dify-ui/src/input-group/README.md`                         |
+| Forms and field semantics                  | `packages/dify-ui/docs/forms.md`                                     |
+| Selection and typed values                 | `packages/dify-ui/docs/selection.md`                                 |
+| Portals, layers, and floating surfaces     | `packages/dify-ui/docs/overlays.md`                                  |
+| Tailwind and radius tokens                 | `packages/dify-ui/docs/styling.md`                                   |
+| Package tests and Storybook                | `packages/dify-ui/docs/testing.md`                                   |
 
-## Package Boundary
+For consumer code under `web/`, also read `web/AGENTS.md` for application-owned reuse policy and
+`packages/dify-ui/README.md` for the available public subpaths.
 
-Flag in `packages/dify-ui`:
-
-- Imports from `web/`.
-- Dependencies on Next.js, i18n, ky, Jotai, Zustand, TanStack Query, oRPC, or business APIs.
-- Business-specific component behavior that belongs in `web/`.
-- Multiple unrelated primitives in one component folder.
-
-`packages/dify-ui` is a primitive layer: Base UI headless components + `cva` + `cn` + Dify design tokens.
-
-## Imports And Exports
-
-Flag:
-
-- Consumer imports from `@langgenius/dify-ui` without a subpath.
-- Missing `package.json#exports` entry for a new primitive.
-- Internal package imports using workspace subpaths instead of relative paths.
-- Exported props using internal-only types that consumers cannot import from the component subpath.
-
-Consumers use subpath exports such as `@langgenius/dify-ui/button`.
-
-## Props And State
-
-Flag:
-
-- Flattened props where related values need a discriminated union, such as `value` / `defaultValue`, `multiple` / `value`, or `clearable` / `onChange`.
-- React state used only to mirror Base UI state for class names.
-- JavaScript conditional class logic for visual states that the Dify UI/Base UI primitive already exposes through `data-*` attributes or CSS variables.
-- Controlled props added when uncontrolled DOM state or CSS variables would be enough.
-- Thin wrappers that rename Base UI parts without adding semantics.
-
-Prefer Base UI/Dify UI data attributes and CSS variables for visual state: `data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`, `group-data-*`, `peer-data-*`, `has-[:focus-visible]`, and primitive CSS variables such as anchor width or transform origin. Use JS conditional classes for product/business state that the primitive does not expose.
-
-## Forms
-
-Flag:
-
-- Form-like UI using unrelated `Input` and `Button` pieces without a submit boundary.
-- Text-like fields not composed through `FieldRoot`, `FieldLabel`, and `FieldControl` when using Dify UI form semantics.
-- Select fields using `FieldLabel` instead of `SelectLabel`.
-- Slider fields using a generic label instead of `SliderLabel`.
-- Checkbox/radio groups missing `FieldsetRoot` and `FieldsetLegend`.
-- Field errors or descriptions rendered without `FieldDescription` / `FieldError` relationships.
-
-`Form` is the submit boundary. Dify UI form primitives are not a form state-management framework; business validation and schema-driven behavior belong in `web/`.
-
-## Overlay Contract
-
-Flag:
-
-- Legacy web overlay imports in new or modified code.
-- Manual portals around Dify UI overlay primitives.
-- Call-site `z-*` overrides on overlays.
-- Missing root `isolation: isolate` assumptions when debugging overlay stacking.
-- Repeated backdrop, z-index, or portal chrome at call sites.
-- Tooltip used for infotips, long text, or interactive content.
-
-All Dify UI body-portalled overlays use `z-50`. Toast uses `z-60`. DOM order handles stacking between overlays.
-
-## Primitive Selection
-
-Flag:
-
-- `Tabs` used for simple mode/filter/view selection where `SegmentedControl` is the semantic primitive.
-- `SegmentedControl` used where `tablist` / `tabpanel` semantics are required.
-- `Select` used for searchable or free-form input.
-- `Combobox` used for unrestricted search text where no selected option is remembered.
-- `Autocomplete` used for closed-list selection.
-- Tooltip or PreviewCard used for content that must be reachable on touch or by screen readers.
-
-Use:
-
-- `Autocomplete` for free-form text with optional suggestions.
-- `Combobox` for searchable selected values from a collection.
-- `Select` for closed, scannable option sets.
-- `Popover` for infotips, help text, rich content, or interactions.
-
-## Bad Usage Patterns To Flag
-
-Flag:
-
-- Manually recreating UI behavior or chrome already owned by `@langgenius/dify-ui/*` or `web/app/components/base/*`, such as buttons, inputs, toggle groups, popovers, dropdown menus, alert dialogs, switches, avatars, scroll areas, toasts, borders, focus states, disabled states, segmented controls, or existing feature components.
-- Styling a raw Base UI primitive directly in `web/` when a Dify UI primitive exists.
-- Wrapping a Dify UI primitive in a feature component that hides its label, error, disabled, or focus contract.
-- Replacing a semantic primitive with a generic `div` plus classes to match a screenshot.
-- Using `Tooltip` because it is visually convenient when the content is actually help text or needs touch access.
-- Adding a `z-*` override to make a child popup appear over a parent dialog.
-- Adding a new app-level wrapper around Dialog, Drawer, Popover, Select, or Combobox that repeats portal/backdrop/positioner logic.
-- Using dify-ui `Input` as a drop-in replacement for legacy inputs that include search, clear, copy, unit, localized placeholder, or number normalization behavior.
-- Building a form row from loose text and controls instead of the matching Field/Form primitives.
-- Adding component state only to style `data-open`, `data-checked`, `data-disabled`, or highlighted states that Base UI already exposes.
-- Passing booleans down only so children can toggle classes already expressible with primitive `data-*` selectors.
-
-## Tokens, Radius, And Styling
-
-Flag:
-
-- `radius-*` class names.
-- Custom Tailwind `borderRadius` extension for Figma radius values.
-- Generic colors where semantic Dify tokens exist.
-- Hardcoded design values where Dify tokens, component variants, or documented Figma radius mappings exist.
-- `!` important modifiers used to fight primitive styles instead of fixing the variant, selector, or component composition.
-- Manual class strings that duplicate primitive variants.
-- `min-w-(--anchor-width)` on picker popups when it defeats viewport clamping.
-
-Use the Figma radius mapping from `packages/dify-ui/AGENTS.md`; for example `--radius/sm` maps to `rounded-md`, and `--radius/md` maps to `rounded-lg`.
-
-Use `!` only for a tightly scoped compatibility override after confirming the primitive API, data attributes, and selector structure cannot express the state.
-
-## Focus Details
-
-Flag focus rings attached to the wrong element. For example, Base UI `Slider.Thumb` focuses an internal `input[type=range]`, so the visible thumb wrapper needs `has-[:focus-visible]` rather than direct wrapper `focus-visible`.
-
-## Custom SVG Icons
-
-Flag:
-
-- New generated React icon components or JSON files under `web/app/components/base/icons/src/...` for custom SVG icons.
-- Custom SVG icons consumed outside the Tailwind `i-custom-*` icon class pipeline.
-- Generated `packages/iconify-collections/custom-*/icons.json` diffs where unrelated existing icons lost or changed intrinsic `width` or `height`.
-
-New custom SVG icons belong in `packages/iconify-collections/assets/...`. Regenerate with `pnpm --filter @dify/iconify-collections generate`, validate with `pnpm --filter @dify/iconify-collections check:dimensions`, and consume the generated icon with Tailwind `i-custom-*` classes.
+Treat the implementation, public types, tests, and stories as evidence for the documented
+contract. If they disagree, identify the actual owner before reporting a finding. Read current
+official Base UI documentation and installed type declarations for upstream-derived behavior.
+Report only a reproducible contract violation or observable defect, not a preference inferred from
+this routing file.

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

@@ -1,72 +1,37 @@
 # Testing Review Rules
 
-Use these rules when reviewing test files, testability of changed code, or risky frontend changes that should have tests.
+`web/docs/test.md` is the canonical frontend testing policy. Use this file only to translate that policy into review findings.
 
-## Missing Coverage
+## Request Missing Tests When Risk Justifies Them
 
-Flag missing tests when the change affects:
+Flag missing coverage when a change alters a reachable contract such as:
 
-- User-visible behavior, navigation, form submission, validation, permissions, or loading/error/empty states.
-- Query/mutation cache behavior.
-- Accessibility-critical behavior such as labels, keyboard flow, focus, disabled state, or popup reachability.
-- URL state parsing/serialization.
-- Storage persistence or one-shot signals.
-- Regression-prone workflow or generated contract migration paths.
+- User interaction, navigation, form submission, validation, or permissions.
+- Query or mutation behavior, URL state, persistence, or one-shot signals.
+- Loading, error, empty, and recovery states that users can encounter.
+- A hidden surface whose close-and-reopen behavior changes whether in-progress state resets or persists.
+- Accessibility-critical labels, keyboard flow, focus, disabled state, or overlay behavior.
+- A regression-prone business rule or bug fix that can be reproduced through a public boundary.
 
-Do not request tests for purely mechanical renames or styling-only changes unless the styling affects layout, focus, or interaction.
+Do not request tests for mechanical changes, pass-through wrappers, implementation details, or visual-only styling unless they affect behavior. Low coverage alone is not a finding.
 
-## Selectors
+## Flag Low-Value or Fragile Tests
 
-Flag:
+Flag tests that:
 
-- `getByTestId` used where role, label, text, placeholder, landmark, or scoped dialog/menu queries are available.
-- Production `data-testid` added only to satisfy tests.
-- Assertions against decorative icons rather than the named control.
-- Tests that cannot find controls semantically but leave broken markup unchanged.
+- Assert internal state, refs, hook usage, effect dependencies, private DOM structure, or cosmetic classes.
+- Exist only to render a component, exercise a prop, or cover generic invalid inputs without a product scenario.
+- Mock away the behavior under review or use mocks that do not match the public contract.
+- Add production `data-testid` attributes where semantic markup would work.
+- Use fake timers without timer behavior, leave async work unawaited, or leak shared state.
+- Duplicate a contract already protected at a more useful owner boundary.
 
-Prefer `getByRole` with accessible name, then `getByLabelText`, `getByPlaceholderText`, `getByText`, and `within(...)`.
+## Review the Test Boundary
 
-## Mocking
+- Prefer semantic queries and accessible names.
+- Prefer real feature components when integration semantics matter.
+- Allow intentional child or provider mocks when setup would dominate the test and that boundary is covered independently.
+- Do not accept semantically inaccurate mocks of Dify UI or legacy base primitives.
+- Require a real-browser or visual verification plan when `happy-dom` cannot represent the risk.
 
-Flag:
-
-- Mocking `@langgenius/dify-ui/*` primitives.
-- Mocking `@/app/components/base/*` components when the real component is practical.
-- Mocking sibling or child components in the same directory for integration behavior.
-- Mocks that do not match the real component's conditional rendering.
-- Module-level mock state not reset in `beforeEach`.
-- `vi.clearAllMocks()` in `afterEach` instead of `beforeEach`.
-
-Use real project components for integration behavior. Mock APIs, `next/navigation`, browser shims, or complex providers only when setup would dominate the test.
-
-## Behavior
-
-Flag:
-
-- Tests inspecting implementation details instead of user-observable behavior.
-- Assertions that hardcode brittle copy when pattern matching or semantic roles would express behavior better.
-- Fake timers used without real timing behavior.
-- Async assertions missing `await`, `findBy*`, or `waitFor`.
-- Test data missing required fields because inline partial objects bypass real types.
-
-Use typed factory functions with complete defaults and partial overrides.
-
-## URL State
-
-For `nuqs` or query-state hooks, flag tests that:
-
-- Mock URL state when URL synchronization is the behavior under review.
-- Do not test parser serialize/parse round trips for custom parsers.
-- Do not assert default-clearing behavior when defaults should be removed from the URL.
-
-Prefer shared `NuqsTestingAdapter` helpers when available.
-
-## Organization
-
-Flag:
-
-- Component/hook/util tests outside sibling `__tests__/` directories.
-- Directory-level reviews that test only `index.tsx` while other files in scope contain behavior.
-- Large test files with repeated setup that should use local builders.
-
-When a component is very complex, prefer a refactor finding before asking for exhaustive tests.
+Treat test quality, determinism, and regression value as the review criteria. Do not use test count or coverage percentage as a proxy for quality.

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

@@ -1,332 +1,16 @@
 ---
 name: frontend-testing
-description: Generate Vitest + React Testing Library tests for Dify frontend components, hooks, and utilities. Triggers on testing, spec files, coverage, Vitest, RTL, unit tests, integration tests, or write/review test requests.
+description: Use when writing or changing Vitest or React Testing Library tests under `web/` or `packages/dify-ui/`, or when the user explicitly requests frontend test strategy, including evaluation of an existing strategy. Do not use for frontend code-review-only requests, general testability discussion, Python tests, or Cucumber/Playwright E2E.
 ---
 
-# Dify Frontend Testing Skill
+# Frontend Testing
 
-This skill enables Codex to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.
+`web/docs/test.md` is the single policy owner. Read it before changing frontend tests; this skill adds no separate requirements.
 
-> **⚠️ Authoritative Source**: This skill is derived from `web/docs/test.md`. Use Vitest mock/timer APIs (`vi.*`).
+1. Identify the observable contract and regression risk.
+2. Choose the smallest boundary that includes the behavior owner.
+3. Establish the failing case first when practical, then implement one coherent scenario.
+4. Run the focused spec before the affected suite and relevant static checks.
+5. Report the behavior verified and any remaining browser, visual, or end-to-end risk.
 
-## When to Apply This Skill
-
-Apply this skill when the user:
-
-- Asks to **write tests** for a component, hook, or utility
-- Asks to **review existing tests** for completeness
-- Mentions **Vitest**, **React Testing Library**, **RTL**, or **spec files**
-- Requests **test coverage** improvement
-- Uses `pnpm analyze-component` output as context
-- Mentions **testing**, **unit tests**, or **integration tests** for frontend code
-- Wants to understand **testing patterns** in the Dify codebase
-
-**Do NOT apply** when:
-
-- User is asking about backend/API tests (Python/pytest)
-- User is asking about E2E tests (Cucumber + Playwright under `e2e/`)
-- User is only asking conceptual questions without code context
-
-## Quick Reference
-
-### Key Commands
-
-Run these commands from `web/`. From the repository root, prefix them with `pnpm -C web`.
-
-```bash
-# Run all tests
-pnpm test
-
-# Watch mode
-pnpm test --watch
-
-# Run specific file
-pnpm test path/to/file.spec.tsx
-
-# Generate coverage report
-pnpm test --coverage
-
-# Analyze component complexity
-pnpm analyze-component <path>
-
-# Review existing test
-pnpm analyze-component <path> --review
-```
-
-### File Naming
-
-- Test files: `ComponentName.spec.tsx` inside a same-level `__tests__/` directory
-- Placement rule: Component, hook, and utility tests must live in a sibling `__tests__/` folder at the same level as the source under test. For example, `foo/index.tsx` maps to `foo/__tests__/index.spec.tsx`, and `foo/bar.ts` maps to `foo/__tests__/bar.spec.ts`.
-- Integration tests: `web/__tests__/` directory
-
-## Test Structure Template
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import Component from './index'
-
-// ✅ Import real project components (DO NOT mock these)
-// import Loading from '@/app/components/base/loading'
-// import { ChildComponent } from './child-component'
-
-// ✅ Mock external dependencies only
-vi.mock('@/service/api')
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({ push: vi.fn() }),
-  usePathname: () => '/test',
-}))
-
-// ✅ Zustand stores: Use real stores (auto-mocked globally)
-// Set test state with: useAppStore.setState({ ... })
-
-// Shared state for mocks (if needed)
-let mockSharedState = false
-
-describe('ComponentName', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()  // ✅ Reset mocks BEFORE each test
-    mockSharedState = false  // ✅ Reset shared state
-  })
-
-  // Rendering tests (REQUIRED)
-  describe('Rendering', () => {
-    it('should render without crashing', () => {
-      // Arrange
-      const props = { title: 'Test' }
-      
-      // Act
-      render(<Component {...props} />)
-      
-      // Assert
-      expect(screen.getByText('Test')).toBeInTheDocument()
-    })
-  })
-
-  // Props tests (REQUIRED when props change observable behavior)
-  describe('Props', () => {
-    it('should disable the action when disabled', () => {
-      render(<Component disabled />)
-      expect(screen.getByRole('button')).toBeDisabled()
-    })
-  })
-
-  // User Interactions
-  describe('User Interactions', () => {
-    it('should handle click events', () => {
-      const handleClick = vi.fn()
-      render(<Component onClick={handleClick} />)
-      
-      fireEvent.click(screen.getByRole('button'))
-      
-      expect(handleClick).toHaveBeenCalledTimes(1)
-    })
-  })
-
-  // Edge Cases (REQUIRED)
-  describe('Edge Cases', () => {
-    it('should handle null data', () => {
-      render(<Component data={null} />)
-      expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty array', () => {
-      render(<Component items={[]} />)
-      expect(screen.getByText(/empty/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-## Testing Workflow (CRITICAL)
-
-### ⚠️ Incremental Approach Required
-
-**NEVER generate all test files at once.** For complex components or multi-file directories:
-
-1. **Analyze & Plan**: List all files, order by complexity (simple → complex)
-1. **Process ONE at a time**: Write test → Run test → Fix if needed → Next
-1. **Verify before proceeding**: Do NOT continue to next file until current passes
-
-```
-For each file:
-  ┌────────────────────────────────────────┐
-  │ 1. Write test                          │
-  │ 2. Run: pnpm test <file>.spec.tsx      │
-  │ 3. PASS? → Mark complete, next file    │
-  │    FAIL? → Fix first, then continue    │
-  └────────────────────────────────────────┘
-```
-
-### Complexity-Based Order
-
-Process in this order for multi-file testing:
-
-1. 🟢 Utility functions (simplest)
-1. 🟢 Custom hooks
-1. 🟡 Simple components (presentational)
-1. 🟡 Medium components (state, effects)
-1. 🔴 Complex components (API, routing)
-1. 🔴 Integration tests (index files - last)
-
-### When to Refactor First
-
-- **Complexity > 50**: Break into smaller pieces before testing
-- **500+ lines**: Consider splitting before testing
-- **Many dependencies**: Extract logic into hooks first
-
-> 📖 See `references/workflow.md` for complete workflow details and todo list format.
-
-## Testing Strategy
-
-### Path-Level Testing (Directory Testing)
-
-When assigned to test a directory/path, test **ALL content** within that path:
-
-- Test all components, hooks, utilities in the directory (not just `index` file)
-- Use incremental approach: one file at a time, verify each before proceeding
-- Goal: 100% coverage of ALL files in the directory
-
-### Integration Testing First
-
-**Prefer integration testing** when writing tests for a directory:
-
-- ✅ **Import real project components** directly (including base components and siblings)
-- ✅ **Only mock**: API services (`@/service/*`), `next/navigation`, complex context providers
-- ❌ **DO NOT mock** base components (`@/app/components/base/*`) or dify-ui primitives (`@langgenius/dify-ui/*`)
-- ❌ **DO NOT mock** sibling/child components in the same directory
-
-> See [Test Structure Template](#test-structure-template) for correct import/mock patterns.
-
-### `nuqs` Query State Testing (Required for URL State Hooks)
-
-When a component or hook uses `useQueryState` / `useQueryStates`:
-
-- ✅ Use `NuqsTestingAdapter` (prefer shared helpers in `web/test/nuqs-testing.tsx`)
-- ✅ Assert URL synchronization via `onUrlUpdate` (`searchParams`, `options.history`)
-- ✅ For custom parsers (`createParser`), keep `parse` and `serialize` bijective and add round-trip edge cases (`%2F`, `%25`, spaces, legacy encoded values)
-- ✅ Verify default-clearing behavior (default values should be removed from URL when applicable)
-- ⚠️ Only mock `nuqs` directly when URL behavior is explicitly out of scope for the test
-
-## Core Principles
-
-### 1. AAA Pattern (Arrange-Act-Assert)
-
-Every test should clearly separate:
-
-- **Arrange**: Setup test data and render component
-- **Act**: Perform user actions
-- **Assert**: Verify expected outcomes
-
-### 2. Black-Box Testing
-
-- Test observable behavior, not implementation details
-- Test product contracts, not cosmetic implementation. Do not add or expand unit tests only to lock pure style classes, spacing, colors, backgrounds, or layout micro-adjustments. Cover visual-only fixes with browser/manual verification, screenshots, or E2E/visual checks when risk justifies it. Add unit tests only when the change affects user-observable behavior, accessibility semantics, state, data flow, routing, or a stable component API contract.
-- Use semantic queries (`getByRole` with accessible `name`, `getByLabelText`, `getByPlaceholderText`, `getByText`, and scoped `within(...)`)
-- Treat `getByTestId` as a last resort. If a control cannot be found by role/name, label, landmark, or dialog scope, fix the component accessibility first instead of adding or relying on `data-testid`.
-- Remove production `data-testid` attributes when semantic selectors can cover the behavior. Keep them only for non-visual mocked boundaries, editor/browser shims such as Monaco, canvas/chart output, or third-party widgets with no accessible DOM in the test environment.
-- Do not assert decorative icons by test id. Assert the named control that contains them, or mark decorative icons `aria-hidden`.
-- Avoid testing internal state directly
-- **Prefer pattern matching over hardcoded strings** in assertions:
-
-```typescript
-// ❌ Avoid: hardcoded text assertions
-expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-// ✅ Better: role-based queries
-expect(screen.getByRole('status')).toBeInTheDocument()
-
-// ✅ Better: pattern matching
-expect(screen.getByText(/loading/i)).toBeInTheDocument()
-```
-
-### 3. Single Behavior Per Test
-
-Each test verifies ONE user-observable behavior:
-
-```typescript
-// ✅ Good: One behavior
-it('should disable button when loading', () => {
-  render(<Button loading />)
-  expect(screen.getByRole('button')).toBeDisabled()
-})
-
-// ❌ Bad: Multiple behaviors
-it('should handle loading state', () => {
-  render(<Button loading />)
-  expect(screen.getByRole('button')).toBeDisabled()
-  expect(screen.getByText('Loading...')).toBeInTheDocument()
-  expect(screen.getByRole('button')).toHaveClass('loading')
-})
-```
-
-### 4. Semantic Naming
-
-Use `should <behavior> when <condition>`:
-
-```typescript
-it('should show error message when validation fails')
-it('should call onSubmit when form is valid')
-it('should disable input when isReadOnly is true')
-```
-
-## Required Test Scenarios
-
-### Always Required (All Components)
-
-1. **Rendering**: Component renders without crashing
-1. **Props**: Required props, optional props, default values that change observable behavior. Do not test pass-through styling props such as `className` unless they are an explicit, stable component API whose absence would break a real integration contract.
-1. **Edge Cases**: null, undefined, empty values, boundary conditions
-
-### 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 |
-
-## Coverage Goals (Per File)
-
-For each test file generated, aim for:
-
-- ✅ **100%** function coverage
-- ✅ **100%** statement coverage
-- ✅ **>95%** branch coverage
-- ✅ **>95%** line coverage
-
-> **Note**: For multi-file directories, process one file at a time with full coverage each. See `references/workflow.md`.
-
-## Detailed Guides
-
-For more detailed information, refer to:
-
-- `references/workflow.md` - **Incremental testing workflow** (MUST READ for multi-file testing)
-- `references/mocking.md` - Mock patterns, Zustand store testing, and best practices
-- `references/async-testing.md` - Async operations and API calls
-- `references/domain-components.md` - Workflow, Dataset, Configuration testing
-- `references/common-patterns.md` - Frequently used testing patterns
-- `references/checklist.md` - Test generation checklist and validation steps
-
-## Authoritative References
-
-### Primary Specification (MUST follow)
-
-- **`web/docs/test.md`** - The canonical testing specification. This skill is derived from this document.
-
-### Reference Examples in Codebase
-
-- `web/utils/classnames.spec.ts` - Utility function tests
-- `web/app/components/base/radio/__tests__/index.spec.tsx` - Component tests
-- `web/__mocks__/provider-context.ts` - Mock factory example
-
-### Project Configuration
-
-- `web/vite.config.ts` - Vite/Vitest configuration
-- `web/vitest.setup.ts` - Test environment setup
-- `web/scripts/analyze-component.js` - Component analysis tool
-- Modules are not mocked automatically. Global mocks live in `web/vitest.setup.ts` (for example `react-i18next`, `next/image`); mock other modules like `ky` or `mime` locally in test files.
+Recommend deleting low-value tests as readily as adding missing behavior coverage. Use `web/docs/test.md` for policy and Web commands; use `packages/dify-ui/docs/testing.md` for Dify UI commands.

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

@@ -1,293 +0,0 @@
-/**
- * Test Template for React Components
- *
- * WHY THIS STRUCTURE?
- * - Organized sections make tests easy to navigate and maintain
- * - Mocks at top ensure consistent test isolation
- * - Factory functions reduce duplication and improve readability
- * - describe blocks group related scenarios for better debugging
- *
- * INSTRUCTIONS:
- * 1. Replace `ComponentName` with your component name
- * 2. Update import path
- * 3. Add/remove test sections based on component features (use analyze-component)
- * 4. Follow AAA pattern: Arrange → Act → Assert
- *
- * RUN FIRST: pnpm analyze-component <path> to identify required test scenarios
- */
-
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-// import ComponentName from './index'
-
-// ============================================================================
-// Mocks
-// ============================================================================
-// WHY: Mocks must be hoisted to top of file (Vitest requirement).
-// They run BEFORE imports, so keep them before component imports.
-
-// i18n (automatically mocked)
-// WHY: Global mock in web/vitest.setup.ts is auto-loaded by Vitest setup
-// The global mock provides: useTranslation, Trans, useMixedTranslation, useGetLanguage
-// No explicit mock needed for most tests
-//
-// Override only if custom translations are required:
-// import { createReactI18nextMock } from '@/test/i18n-mock'
-// vi.mock('react-i18next', () => createReactI18nextMock({
-//   'my.custom.key': 'Custom Translation',
-//   'button.save': 'Save',
-// }))
-
-// Router (if component uses useRouter, usePathname, useSearchParams)
-// WHY: Isolates tests from Next.js routing, enables testing navigation behavior
-// const mockPush = vi.fn()
-// vi.mock('@/next/navigation', () => ({
-//   useRouter: () => ({ push: mockPush }),
-//   usePathname: () => '/test-path',
-// }))
-
-// API services (if component fetches data)
-// WHY: Prevents real network calls, enables testing all states (loading/success/error)
-// vi.mock('@/service/api')
-// import * as api from '@/service/api'
-// const mockedApi = vi.mocked(api)
-
-// Shared mock state (for portal/dropdown components)
-// WHY: Portal components like PortalToFollowElem need shared state between
-// parent and child mocks to correctly simulate open/close behavior
-// let mockOpenState = false
-
-// ============================================================================
-// Test Data Factories
-// ============================================================================
-// WHY FACTORIES?
-// - Avoid hard-coded test data scattered across tests
-// - Easy to create variations with overrides
-// - Type-safe when using actual types from source
-// - Single source of truth for default test values
-
-// const createMockProps = (overrides = {}) => ({
-//   // Default props that make component render successfully
-//   ...overrides,
-// })
-
-// const createMockItem = (overrides = {}) => ({
-//   id: 'item-1',
-//   name: 'Test Item',
-//   ...overrides,
-// })
-
-// ============================================================================
-// Test Helpers
-// ============================================================================
-
-// const renderComponent = (props = {}) => {
-//   return render(<ComponentName {...createMockProps(props)} />)
-// }
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe('ComponentName', () => {
-  // WHY beforeEach with clearAllMocks?
-  // - Ensures each test starts with clean slate
-  // - Prevents mock call history from leaking between tests
-  // - MUST be beforeEach (not afterEach) to reset BEFORE assertions like toHaveBeenCalledTimes
-  beforeEach(() => {
-    vi.clearAllMocks()
-    // Reset shared mock state if used (CRITICAL for portal/dropdown tests)
-    // mockOpenState = false
-  })
-
-  // --------------------------------------------------------------------------
-  // Rendering Tests (REQUIRED - Every component MUST have these)
-  // --------------------------------------------------------------------------
-  // WHY: Catches import errors, missing providers, and basic render issues
-  describe('Rendering', () => {
-    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()
-    })
-
-    it('should render with default props', () => {
-      // WHY: Verifies component works without optional props
-      // render(<ComponentName />)
-      // expect(screen.getByText('...')).toBeInTheDocument()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Props Tests (REQUIRED - Every component MUST test prop behavior)
-  // --------------------------------------------------------------------------
-  // WHY: Props are the component's API contract. Test them thoroughly.
-  describe('Props', () => {
-    it('should apply custom className', () => {
-      // WHY: Common pattern in Dify - components should merge custom classes
-      // render(<ComponentName className="custom-class" />)
-      // expect(screen.getByTestId('component')).toHaveClass('custom-class')
-    })
-
-    it('should use default values for optional props', () => {
-      // WHY: Verifies TypeScript defaults work at runtime
-      // render(<ComponentName />)
-      // expect(screen.getByRole('...')).toHaveAttribute('...', 'default-value')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // User Interactions (if component has event handlers - on*, handle*)
-  // --------------------------------------------------------------------------
-  // WHY: Event handlers are core functionality. Test from user's perspective.
-  describe('User Interactions', () => {
-    it('should call onClick when clicked', async () => {
-      // WHY userEvent over fireEvent?
-      // - userEvent simulates real user behavior (focus, hover, then click)
-      // - fireEvent is lower-level, doesn't trigger all browser events
-      // const user = userEvent.setup()
-      // const handleClick = vi.fn()
-      // render(<ComponentName onClick={handleClick} />)
-      //
-      // await user.click(screen.getByRole('button'))
-      //
-      // expect(handleClick).toHaveBeenCalledTimes(1)
-    })
-
-    it('should call onChange when value changes', async () => {
-      // const user = userEvent.setup()
-      // const handleChange = vi.fn()
-      // render(<ComponentName onChange={handleChange} />)
-      //
-      // await user.type(screen.getByRole('textbox'), 'new value')
-      //
-      // expect(handleChange).toHaveBeenCalled()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // State Management (if component uses useState/useReducer)
-  // --------------------------------------------------------------------------
-  // WHY: Test state through observable UI changes, not internal state values
-  describe('State Management', () => {
-    it('should update state on interaction', async () => {
-      // WHY test via UI, not state?
-      // - State is implementation detail; UI is what users see
-      // - If UI works correctly, state must be correct
-      // const user = userEvent.setup()
-      // render(<ComponentName />)
-      //
-      // // Initial state - verify what user sees
-      // expect(screen.getByText('Initial')).toBeInTheDocument()
-      //
-      // // Trigger state change via user action
-      // await user.click(screen.getByRole('button'))
-      //
-      // // New state - verify UI updated
-      // expect(screen.getByText('Updated')).toBeInTheDocument()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Async Operations (if component fetches data - useQuery, fetch)
-  // --------------------------------------------------------------------------
-  // WHY: Async operations have 3 states users experience: loading, success, error
-  describe('Async Operations', () => {
-    it('should show loading state', () => {
-      // WHY never-resolving promise?
-      // - Keeps component in loading state for assertion
-      // - Alternative: use fake timers
-      // mockedApi.fetchData.mockImplementation(() => new Promise(() => {}))
-      // render(<ComponentName />)
-      //
-      // expect(screen.getByText(/loading/i)).toBeInTheDocument()
-    })
-
-    it('should show data on success', async () => {
-      // WHY waitFor?
-      // - Component updates asynchronously after fetch resolves
-      // - waitFor retries assertion until it passes or times out
-      // mockedApi.fetchData.mockResolvedValue({ items: ['Item 1'] })
-      // render(<ComponentName />)
-      //
-      // await waitFor(() => {
-      //   expect(screen.getByText('Item 1')).toBeInTheDocument()
-      // })
-    })
-
-    it('should show error on failure', async () => {
-      // mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-      // render(<ComponentName />)
-      //
-      // await waitFor(() => {
-      //   expect(screen.getByText(/error/i)).toBeInTheDocument()
-      // })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Edge Cases (REQUIRED - Every component MUST handle edge cases)
-  // --------------------------------------------------------------------------
-  // WHY: Real-world data is messy. Components must handle:
-  // - Null/undefined from API failures or optional fields
-  // - Empty arrays/strings from user clearing data
-  // - Boundary values (0, MAX_INT, special characters)
-  describe('Edge Cases', () => {
-    it('should handle null value', () => {
-      // WHY test null specifically?
-      // - API might return null for missing data
-      // - Prevents "Cannot read property of null" in production
-      // render(<ComponentName value={null} />)
-      // expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle undefined value', () => {
-      // WHY test undefined separately from null?
-      // - TypeScript treats them differently
-      // - Optional props are undefined, not null
-      // render(<ComponentName value={undefined} />)
-      // expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty array', () => {
-      // WHY: Empty state often needs special UI (e.g., "No items yet")
-      // render(<ComponentName items={[]} />)
-      // expect(screen.getByText(/empty/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty string', () => {
-      // WHY: Empty strings are truthy in JS but visually empty
-      // render(<ComponentName text="" />)
-      // expect(screen.getByText(/placeholder/i)).toBeInTheDocument()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Accessibility (optional but recommended for Dify's enterprise users)
-  // --------------------------------------------------------------------------
-  // WHY: Dify has enterprise customers who may require accessibility compliance
-  describe('Accessibility', () => {
-    it('should have accessible name', () => {
-      // WHY getByRole with name?
-      // - Tests that screen readers can identify the element
-      // - Enforces proper labeling practices
-      // render(<ComponentName label="Test Label" />)
-      // expect(screen.getByRole('button', { name: /test label/i })).toBeInTheDocument()
-    })
-
-    it('should support keyboard navigation', async () => {
-      // WHY: Some users can't use a mouse
-      // const user = userEvent.setup()
-      // render(<ComponentName />)
-      //
-      // await user.tab()
-      // expect(screen.getByRole('button')).toHaveFocus()
-    })
-  })
-})

.agents/skills/frontend-testing/assets/hook-test.template.ts

@@ -1,207 +0,0 @@
-/**
- * Test Template for Custom Hooks
- *
- * Instructions:
- * 1. Replace `useHookName` with your hook name
- * 2. Update import path
- * 3. Add/remove test sections based on hook features
- */
-
-import { renderHook, act, waitFor } from '@testing-library/react'
-// import { useHookName } from './use-hook-name'
-
-// ============================================================================
-// Mocks
-// ============================================================================
-
-// API services (if hook fetches data)
-// vi.mock('@/service/api')
-// import * as api from '@/service/api'
-// const mockedApi = vi.mocked(api)
-
-// ============================================================================
-// Test Helpers
-// ============================================================================
-
-// Wrapper for hooks that need context
-// const createWrapper = (contextValue = {}) => {
-//   return ({ children }: { children: React.ReactNode }) => (
-//     <SomeContext.Provider value={contextValue}>
-//       {children}
-//     </SomeContext.Provider>
-//   )
-// }
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe('useHookName', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  // --------------------------------------------------------------------------
-  // Initial State
-  // --------------------------------------------------------------------------
-  describe('Initial State', () => {
-    it('should return initial state', () => {
-      // const { result } = renderHook(() => useHookName())
-      //
-      // expect(result.current.value).toBe(initialValue)
-      // expect(result.current.isLoading).toBe(false)
-    })
-
-    it('should accept initial value from props', () => {
-      // const { result } = renderHook(() => useHookName({ initialValue: 'custom' }))
-      //
-      // expect(result.current.value).toBe('custom')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // State Updates
-  // --------------------------------------------------------------------------
-  describe('State Updates', () => {
-    it('should update value when setValue is called', () => {
-      // const { result } = renderHook(() => useHookName())
-      //
-      // act(() => {
-      //   result.current.setValue('new value')
-      // })
-      //
-      // expect(result.current.value).toBe('new value')
-    })
-
-    it('should reset to initial value', () => {
-      // const { result } = renderHook(() => useHookName({ initialValue: 'initial' }))
-      //
-      // act(() => {
-      //   result.current.setValue('changed')
-      // })
-      // expect(result.current.value).toBe('changed')
-      //
-      // act(() => {
-      //   result.current.reset()
-      // })
-      // expect(result.current.value).toBe('initial')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Async Operations
-  // --------------------------------------------------------------------------
-  describe('Async Operations', () => {
-    it('should fetch data on mount', async () => {
-      // mockedApi.fetchData.mockResolvedValue({ data: 'test' })
-      //
-      // const { result } = renderHook(() => useHookName())
-      //
-      // // Initially loading
-      // expect(result.current.isLoading).toBe(true)
-      //
-      // // Wait for data
-      // await waitFor(() => {
-      //   expect(result.current.isLoading).toBe(false)
-      // })
-      //
-      // expect(result.current.data).toEqual({ data: 'test' })
-    })
-
-    it('should handle fetch error', async () => {
-      // mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-      //
-      // const { result } = renderHook(() => useHookName())
-      //
-      // await waitFor(() => {
-      //   expect(result.current.error).toBeTruthy()
-      // })
-      //
-      // expect(result.current.error?.message).toBe('Network error')
-    })
-
-    it('should refetch when dependency changes', async () => {
-      // mockedApi.fetchData.mockResolvedValue({ data: 'test' })
-      //
-      // const { result, rerender } = renderHook(
-      //   ({ id }) => useHookName(id),
-      //   { initialProps: { id: '1' } }
-      // )
-      //
-      // await waitFor(() => {
-      //   expect(mockedApi.fetchData).toHaveBeenCalledWith('1')
-      // })
-      //
-      // rerender({ id: '2' })
-      //
-      // await waitFor(() => {
-      //   expect(mockedApi.fetchData).toHaveBeenCalledWith('2')
-      // })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Side Effects
-  // --------------------------------------------------------------------------
-  describe('Side Effects', () => {
-    it('should call callback when value changes', () => {
-      // const callback = vi.fn()
-      // const { result } = renderHook(() => useHookName({ onChange: callback }))
-      //
-      // act(() => {
-      //   result.current.setValue('new value')
-      // })
-      //
-      // expect(callback).toHaveBeenCalledWith('new value')
-    })
-
-    it('should cleanup on unmount', () => {
-      // const cleanup = vi.fn()
-      // vi.spyOn(window, 'addEventListener')
-      // vi.spyOn(window, 'removeEventListener')
-      //
-      // const { unmount } = renderHook(() => useHookName())
-      //
-      // expect(window.addEventListener).toHaveBeenCalled()
-      //
-      // unmount()
-      //
-      // expect(window.removeEventListener).toHaveBeenCalled()
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Edge Cases
-  // --------------------------------------------------------------------------
-  describe('Edge Cases', () => {
-    it('should handle null input', () => {
-      // const { result } = renderHook(() => useHookName(null))
-      //
-      // expect(result.current.value).toBeNull()
-    })
-
-    it('should handle rapid updates', () => {
-      // const { result } = renderHook(() => useHookName())
-      //
-      // act(() => {
-      //   result.current.setValue('1')
-      //   result.current.setValue('2')
-      //   result.current.setValue('3')
-      // })
-      //
-      // expect(result.current.value).toBe('3')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // With Context (if hook uses context)
-  // --------------------------------------------------------------------------
-  describe('With Context', () => {
-    it('should use context value', () => {
-      // const wrapper = createWrapper({ someValue: 'context-value' })
-      // const { result } = renderHook(() => useHookName(), { wrapper })
-      //
-      // expect(result.current.contextValue).toBe('context-value')
-    })
-  })
-})

.agents/skills/frontend-testing/assets/utility-test.template.ts

@@ -1,154 +0,0 @@
-/**
- * Test Template for Utility Functions
- *
- * Instructions:
- * 1. Replace `utilityFunction` with your function name
- * 2. Update import path
- * 3. Use test.each for data-driven tests
- */
-
-// import { utilityFunction } from './utility'
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-describe('utilityFunction', () => {
-  // --------------------------------------------------------------------------
-  // Basic Functionality
-  // --------------------------------------------------------------------------
-  describe('Basic Functionality', () => {
-    it('should return expected result for valid input', () => {
-      // expect(utilityFunction('input')).toBe('expected-output')
-    })
-
-    it('should handle multiple arguments', () => {
-      // expect(utilityFunction('a', 'b', 'c')).toBe('abc')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Data-Driven Tests
-  // --------------------------------------------------------------------------
-  describe('Input/Output Mapping', () => {
-    test.each([
-      // [input, expected]
-      ['input1', 'output1'],
-      ['input2', 'output2'],
-      ['input3', 'output3'],
-    ])('should return %s for input %s', (input, expected) => {
-      // expect(utilityFunction(input)).toBe(expected)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Edge Cases
-  // --------------------------------------------------------------------------
-  describe('Edge Cases', () => {
-    it('should handle empty string', () => {
-      // expect(utilityFunction('')).toBe('')
-    })
-
-    it('should handle null', () => {
-      // expect(utilityFunction(null)).toBe(null)
-      // or
-      // expect(() => utilityFunction(null)).toThrow()
-    })
-
-    it('should handle undefined', () => {
-      // expect(utilityFunction(undefined)).toBe(undefined)
-      // or
-      // expect(() => utilityFunction(undefined)).toThrow()
-    })
-
-    it('should handle empty array', () => {
-      // expect(utilityFunction([])).toEqual([])
-    })
-
-    it('should handle empty object', () => {
-      // expect(utilityFunction({})).toEqual({})
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Boundary Conditions
-  // --------------------------------------------------------------------------
-  describe('Boundary Conditions', () => {
-    it('should handle minimum value', () => {
-      // expect(utilityFunction(0)).toBe(0)
-    })
-
-    it('should handle maximum value', () => {
-      // expect(utilityFunction(Number.MAX_SAFE_INTEGER)).toBe(...)
-    })
-
-    it('should handle negative numbers', () => {
-      // expect(utilityFunction(-1)).toBe(...)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Type Coercion (if applicable)
-  // --------------------------------------------------------------------------
-  describe('Type Handling', () => {
-    it('should handle numeric string', () => {
-      // expect(utilityFunction('123')).toBe(123)
-    })
-
-    it('should handle boolean', () => {
-      // expect(utilityFunction(true)).toBe(...)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Error Cases
-  // --------------------------------------------------------------------------
-  describe('Error Handling', () => {
-    it('should throw for invalid input', () => {
-      // expect(() => utilityFunction('invalid')).toThrow('Error message')
-    })
-
-    it('should throw with specific error type', () => {
-      // expect(() => utilityFunction('invalid')).toThrow(ValidationError)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Complex Objects (if applicable)
-  // --------------------------------------------------------------------------
-  describe('Object Handling', () => {
-    it('should preserve object structure', () => {
-      // const input = { a: 1, b: 2 }
-      // expect(utilityFunction(input)).toEqual({ a: 1, b: 2 })
-    })
-
-    it('should handle nested objects', () => {
-      // const input = { nested: { deep: 'value' } }
-      // expect(utilityFunction(input)).toEqual({ nested: { deep: 'transformed' } })
-    })
-
-    it('should not mutate input', () => {
-      // const input = { a: 1 }
-      // const inputCopy = { ...input }
-      // utilityFunction(input)
-      // expect(input).toEqual(inputCopy)
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Array Handling (if applicable)
-  // --------------------------------------------------------------------------
-  describe('Array Handling', () => {
-    it('should process all elements', () => {
-      // expect(utilityFunction([1, 2, 3])).toEqual([2, 4, 6])
-    })
-
-    it('should handle single element array', () => {
-      // expect(utilityFunction([1])).toEqual([2])
-    })
-
-    it('should preserve order', () => {
-      // expect(utilityFunction(['c', 'a', 'b'])).toEqual(['c', 'a', 'b'])
-    })
-  })
-})

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

@@ -1,345 +0,0 @@
-# Async Testing Guide
-
-## Core Async Patterns
-
-### 1. waitFor - Wait for Condition
-
-```typescript
-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()
-  })
-})
-
-it('should hide loading spinner after load', async () => {
-  render(<DataComponent />)
-  
-  // Wait for element to disappear
-  await waitFor(() => {
-    expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
-  })
-})
-```
-
-### 2. findBy\* - Async Queries
-
-```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()
-})
-```
-
-### 3. userEvent for Async Interactions
-
-```typescript
-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' })
-  })
-})
-```
-
-## Fake Timers
-
-### When to Use Fake Timers
-
-- Testing components with `setTimeout`/`setInterval`
-- Testing debounce/throttle behavior
-- Testing animations or delayed transitions
-- Testing polling or retry logic
-
-### Basic Fake Timer Setup
-
-```typescript
-describe('Debounced Search', () => {
-  beforeEach(() => {
-    vi.useFakeTimers()
-  })
-
-  afterEach(() => {
-    vi.useRealTimers()
-  })
-
-  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')
-  })
-})
-```
-
-### Fake Timers with Async Code
-
-```typescript
-it('should retry on failure', async () => {
-  vi.useFakeTimers()
-  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()
-})
-```
-
-### Common Fake Timer Utilities
-
-```typescript
-// Run all pending timers
-vi.runAllTimers()
-
-// Run only pending timers (not new ones created during execution)
-vi.runOnlyPendingTimers()
-
-// Advance by specific time
-vi.advanceTimersByTime(1000)
-
-// Get current fake time
-Date.now()
-
-// Clear all timers
-vi.clearAllTimers()
-```
-
-## API Testing Patterns
-
-### Loading → Success → Error States
-
-```typescript
-describe('DataFetcher', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  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()
-    })
-  })
-
-  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()
-    })
-  })
-})
-```
-
-### Testing Mutations
-
-```typescript
-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' })
-})
-```
-
-## useEffect Testing
-
-### Testing Effect Execution
-
-```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)
-  })
-})
-```
-
-### Testing Effect Dependencies
-
-```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)
-  })
-})
-```
-
-### Testing Effect Cleanup
-
-```typescript
-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)
-})
-```
-
-## Common Async Pitfalls
-
-### ❌ Don't: Forget to await
-
-```typescript
-// Bad - test may pass even if assertion fails
-it('should load data', () => {
-  render(<Component />)
-  waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-
-// Good - properly awaited
-it('should load data', async () => {
-  render(<Component />)
-  await waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-```
-
-### ❌ Don't: Use multiple assertions in single waitFor
-
-```typescript
-// Bad - if first assertion fails, won't know about second
-await waitFor(() => {
-  expect(screen.getByText('Title')).toBeInTheDocument()
-  expect(screen.getByText('Description')).toBeInTheDocument()
-})
-
-// Good - separate waitFor or use findBy
-const title = await screen.findByText('Title')
-const description = await screen.findByText('Description')
-expect(title).toBeInTheDocument()
-expect(description).toBeInTheDocument()
-```
-
-### ❌ Don't: Mix fake timers with real async
-
-```typescript
-// Bad - fake timers don't work well with real Promises
-vi.useFakeTimers()
-await waitFor(() => {
-  expect(screen.getByText('Data')).toBeInTheDocument()
-}) // May timeout!
-
-// Good - use runAllTimers or advanceTimersByTime
-vi.useFakeTimers()
-render(<Component />)
-vi.runAllTimers()
-expect(screen.getByText('Data')).toBeInTheDocument()
-```

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

@@ -1,208 +0,0 @@
-# Test Generation Checklist
-
-Use this checklist when generating or reviewing tests for Dify frontend components.
-
-## Pre-Generation
-
-- [ ] Read the component source code completely
-- [ ] Identify component type (component, hook, utility, page)
-- [ ] Run `pnpm analyze-component <path>` if available
-- [ ] Note complexity score and features detected
-- [ ] Check for existing tests in the same directory
-- [ ] **Identify ALL files in the directory** that need testing (not just index)
-
-## Testing Strategy
-
-### ⚠️ Incremental Workflow (CRITICAL for Multi-File)
-
-- [ ] **NEVER generate all tests at once** - process one file at a time
-- [ ] Order files by complexity: utilities → hooks → simple → complex → integration
-- [ ] Create a todo list to track progress before starting
-- [ ] For EACH file: write → run test → verify pass → then next
-- [ ] **DO NOT proceed** to next file until current one passes
-
-### Path-Level Coverage
-
-- [ ] **Test ALL files** in the assigned directory/path
-- [ ] List all components, hooks, utilities that need coverage
-- [ ] Decide: single spec file (integration) or multiple spec files (unit)
-
-### Complexity Assessment
-
-- [ ] Run `pnpm analyze-component <path>` for complexity score
-- [ ] **Complexity > 50**: Consider refactoring before testing
-- [ ] **500+ lines**: Consider splitting before testing
-- [ ] **30-50 complexity**: Use multiple describe blocks, organized structure
-
-### Integration vs Mocking
-
-- [ ] **DO NOT mock base components or dify-ui primitives** (base `Loading`, `Input`, `Badge`; dify-ui `Button`, `Tooltip`, `Dialog`, etc.)
-- [ ] Import real project components instead of mocking
-- [ ] Only mock: API calls, complex context providers, third-party libs with side effects
-- [ ] Prefer integration testing when using single spec file
-
-## Required Test Sections
-
-### All Components MUST Have
-
-- [ ] **Rendering tests** - Component renders without crashing
-- [ ] **Props tests** - Required props, optional props, default values
-- [ ] **Edge cases** - null, undefined, empty values, boundaries
-
-### 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 |
-
-## Code Quality Checklist
-
-### Structure
-
-- [ ] Uses `describe` blocks to group related tests
-- [ ] Test names follow `should <behavior> when <condition>` pattern
-- [ ] AAA pattern (Arrange-Act-Assert) is clear
-- [ ] Comments explain complex test scenarios
-
-### Mocks
-
-- [ ] **DO NOT mock base components or dify-ui primitives** (`@/app/components/base/*` or `@langgenius/dify-ui/*`)
-- [ ] `vi.clearAllMocks()` in `beforeEach` (not `afterEach`)
-- [ ] Shared mock state reset in `beforeEach`
-- [ ] i18n uses global mock (auto-loaded in `web/vitest.setup.ts`); only override locally for custom translations
-- [ ] Router mocks match actual Next.js API
-- [ ] Mocks reflect actual component conditional behavior
-- [ ] Only mock: API services, complex context providers, third-party libs
-- [ ] For `nuqs` URL-state tests, wrap with `NuqsTestingAdapter` (prefer `web/test/nuqs-testing.tsx`)
-- [ ] For `nuqs` URL-state tests, assert `onUrlUpdate` payload (`searchParams`, `options.history`)
-- [ ] If custom `nuqs` parser exists, add round-trip tests for encoded edge cases (`%2F`, `%25`, spaces, legacy encoded values)
-
-### Queries
-
-- [ ] Prefer semantic queries (`getByRole`, `getByLabelText`)
-- [ ] Use `queryBy*` for absence assertions
-- [ ] Use `findBy*` for async elements
-- [ ] `getByTestId` only as last resort
-
-### Async
-
-- [ ] All async tests use `async/await`
-- [ ] `waitFor` wraps async assertions
-- [ ] Fake timers properly setup/teardown
-- [ ] No floating promises
-
-### TypeScript
-
-- [ ] No `any` types without justification
-- [ ] Mock data uses actual types from source
-- [ ] Factory functions have proper return types
-
-## Coverage Goals (Per File)
-
-For the current file being tested:
-
-- [ ] 100% function coverage
-- [ ] 100% statement coverage
-- [ ] >95% branch coverage
-- [ ] >95% line coverage
-
-## Post-Generation (Per File)
-
-**Run these checks after EACH test file, not just at the end:**
-
-- [ ] Run `pnpm test path/to/file.spec.tsx` - **MUST PASS before next file**
-- [ ] Fix any failures immediately
-- [ ] Mark file as complete in todo list
-- [ ] Only then proceed to next file
-
-### After All Files Complete
-
-- [ ] Run full directory test: `pnpm test path/to/directory/`
-- [ ] Check coverage report: `pnpm test:coverage`
-- [ ] Run `pnpm lint:fix` on all test files
-- [ ] Run `pnpm type-check`
-
-## Common Issues to Watch
-
-### False Positives
-
-```typescript
-// ❌ Mock doesn't match actual behavior
-vi.mock('./Component', () => () => <div>Mocked</div>)
-
-// ✅ Mock matches actual conditional logic
-vi.mock('./Component', () => ({ isOpen }: any) =>
-  isOpen ? <div>Content</div> : null
-)
-```
-
-### State Leakage
-
-```typescript
-// ❌ Shared state not reset
-let mockState = false
-vi.mock('./useHook', () => () => mockState)
-
-// ✅ Reset in beforeEach
-beforeEach(() => {
-  mockState = false
-})
-```
-
-### Async Race Conditions
-
-```typescript
-// ❌ Not awaited
-it('loads data', () => {
-  render(<Component />)
-  expect(screen.getByText('Data')).toBeInTheDocument()
-})
-
-// ✅ Properly awaited
-it('loads data', async () => {
-  render(<Component />)
-  await waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-```
-
-### Missing Edge Cases
-
-Always test these scenarios:
-
-- `null` / `undefined` inputs
-- Empty strings / arrays / objects
-- Boundary values (0, -1, MAX_INT)
-- Error states
-- Loading states
-- Disabled states
-
-## Quick Commands
-
-```bash
-# Run specific test
-pnpm test path/to/file.spec.tsx
-
-# Run with coverage
-pnpm test:coverage path/to/file.spec.tsx
-
-# Watch mode
-pnpm test:watch path/to/file.spec.tsx
-
-# Update snapshots (use sparingly)
-pnpm test -u path/to/file.spec.tsx
-
-# Analyze component
-pnpm analyze-component path/to/component.tsx
-
-# Review existing test
-pnpm analyze-component path/to/component.tsx --review
-```

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

@@ -1,449 +0,0 @@
-# Common Testing Patterns
-
-## Query Priority
-
-Use queries in this order (most to least preferred):
-
-```typescript
-// 1. getByRole - Most recommended (accessibility)
-screen.getByRole('button', { name: /submit/i })
-screen.getByRole('textbox', { name: /email/i })
-screen.getByRole('heading', { level: 1 })
-
-// 2. getByLabelText - Form fields
-screen.getByLabelText('Email address')
-screen.getByLabelText(/password/i)
-
-// 3. getByPlaceholderText - When no label
-screen.getByPlaceholderText('Search...')
-
-// 4. getByText - Non-interactive elements
-screen.getByText('Welcome to Dify')
-screen.getByText(/loading/i)
-
-// 5. getByDisplayValue - Current input value
-screen.getByDisplayValue('current value')
-
-// 6. getByAltText - Images
-screen.getByAltText('Company logo')
-
-// 7. getByTitle - Tooltip elements
-screen.getByTitle('Close')
-
-// 8. getByTestId - Last resort only!
-screen.getByTestId('custom-element')
-```
-
-## Event Handling Patterns
-
-### Click Events
-
-```typescript
-// Basic click
-fireEvent.click(screen.getByRole('button'))
-
-// With userEvent (preferred for realistic interaction)
-const user = userEvent.setup()
-await user.click(screen.getByRole('button'))
-
-// Double click
-await user.dblClick(screen.getByRole('button'))
-
-// Right click
-await user.pointer({ keys: '[MouseRight]', target: screen.getByRole('button') })
-```
-
-### Form Input
-
-```typescript
-const user = userEvent.setup()
-
-// Type in input
-await user.type(screen.getByRole('textbox'), 'Hello World')
-
-// Clear and type
-await user.clear(screen.getByRole('textbox'))
-await user.type(screen.getByRole('textbox'), 'New value')
-
-// Select option
-await user.selectOptions(screen.getByRole('combobox'), 'option-value')
-
-// Check checkbox
-await user.click(screen.getByRole('checkbox'))
-
-// Upload file
-const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-await user.upload(screen.getByLabelText(/upload/i), file)
-```
-
-### Keyboard Events
-
-```typescript
-const user = userEvent.setup()
-
-// Press Enter
-await user.keyboard('{Enter}')
-
-// Press Escape
-await user.keyboard('{Escape}')
-
-// Keyboard shortcut
-await user.keyboard('{Control>}a{/Control}') // Ctrl+A
-
-// Tab navigation
-await user.tab()
-
-// Arrow keys
-await user.keyboard('{ArrowDown}')
-await user.keyboard('{ArrowUp}')
-```
-
-## Component State Testing
-
-### Testing State Transitions
-
-```typescript
-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()
-  })
-})
-```
-
-### Testing Controlled Components
-
-```typescript
-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')
-  })
-})
-```
-
-## Conditional Rendering Testing
-
-```typescript
-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()
-  })
-})
-```
-
-## List Rendering Testing
-
-```typescript
-describe('ItemList', () => {
-  const items = [
-    { id: '1', name: 'Item 1' },
-    { id: '2', name: 'Item 2' },
-    { id: '3', name: 'Item 3' },
-  ]
-
-  it('should render all items', () => {
-    render(<ItemList items={items} />)
-    
-    expect(screen.getAllByRole('listitem')).toHaveLength(3)
-    items.forEach(item => {
-      expect(screen.getByText(item.name)).toBeInTheDocument()
-    })
-  })
-
-  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()
-  })
-})
-```
-
-## Modal/Dialog Testing
-
-```typescript
-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
-  })
-})
-```
-
-## Form Testing
-
-```typescript
-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',
-    })
-  })
-
-  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()
-    })
-  })
-})
-```
-
-## Data-Driven Tests with test.each
-
-```typescript
-describe('StatusBadge', () => {
-  test.each([
-    ['success', 'bg-green-500'],
-    ['warning', 'bg-yellow-500'],
-    ['error', 'bg-red-500'],
-    ['info', 'bg-blue-500'],
-  ])('should apply correct class for %s status', (status, expectedClass) => {
-    render(<StatusBadge status={status} />)
-    
-    expect(screen.getByTestId('status-badge')).toHaveClass(expectedClass)
-  })
-
-  test.each([
-    { input: null, expected: 'Unknown' },
-    { input: undefined, expected: 'Unknown' },
-    { input: '', expected: 'Unknown' },
-    { input: 'invalid', expected: 'Unknown' },
-  ])('should show "Unknown" for invalid input: $input', ({ input, expected }) => {
-    render(<StatusBadge status={input} />)
-    
-    expect(screen.getByText(expected)).toBeInTheDocument()
-  })
-})
-```
-
-## Debugging Tips
-
-```typescript
-// Print entire DOM
-screen.debug()
-
-// Print specific element
-screen.debug(screen.getByRole('button'))
-
-// Log testing playground URL
-screen.logTestingPlaygroundURL()
-
-// Pretty print DOM
-import { prettyDOM } from '@testing-library/react'
-console.log(prettyDOM(screen.getByRole('dialog')))
-
-// Check available roles
-import { getRoles } from '@testing-library/react'
-console.log(getRoles(container))
-```
-
-## Common Mistakes to Avoid
-
-### ❌ Don't Use Implementation Details
-
-```typescript
-// Bad - testing implementation
-expect(component.state.isOpen).toBe(true)
-expect(wrapper.find('.internal-class').length).toBe(1)
-
-// Good - testing behavior
-expect(screen.getByRole('dialog')).toBeInTheDocument()
-```
-
-### ❌ Don't Forget Cleanup
-
-```typescript
-// Bad - may leak state between tests
-it('test 1', () => {
-  render(<Component />)
-})
-
-// Good - cleanup is automatic with RTL, but reset mocks
-beforeEach(() => {
-  vi.clearAllMocks()
-})
-```
-
-### ❌ Don't Use Exact String Matching (Prefer Black-Box Assertions)
-
-```typescript
-// ❌ Bad - hardcoded strings are brittle
-expect(screen.getByText('Submit Form')).toBeInTheDocument()
-expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-// ✅ Good - role-based queries (most semantic)
-expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument()
-expect(screen.getByRole('status')).toBeInTheDocument()
-
-// ✅ Good - pattern matching (flexible)
-expect(screen.getByText(/submit/i)).toBeInTheDocument()
-expect(screen.getByText(/loading/i)).toBeInTheDocument()
-
-// ✅ Good - test behavior, not exact UI text
-expect(screen.getByRole('button')).toBeDisabled()
-expect(screen.getByRole('alert')).toBeInTheDocument()
-```
-
-**Why prefer black-box assertions?**
-
-- Text content may change (i18n, copy updates)
-- Role-based queries test accessibility
-- Pattern matching is resilient to minor changes
-- Tests focus on behavior, not implementation details
-
-### ❌ Don't Assert on Absence Without Query
-
-```typescript
-// Bad - throws if not found
-expect(screen.getByText('Error')).not.toBeInTheDocument() // Error!
-
-// Good - use queryBy for absence assertions
-expect(screen.queryByText('Error')).not.toBeInTheDocument()
-```

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

@@ -1,523 +0,0 @@
-# Domain-Specific Component Testing
-
-This guide covers testing patterns for Dify's domain-specific components.
-
-## Workflow Components (`workflow/`)
-
-Workflow components handle node configuration, data flow, and graph operations.
-
-### Key Test Areas
-
-1. **Node Configuration**
-1. **Data Validation**
-1. **Variable Passing**
-1. **Edge Connections**
-1. **Error Handling**
-
-### Example: Node Configuration Panel
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import NodeConfigPanel from './node-config-panel'
-import { createMockNode, createMockWorkflowContext } from '@/__mocks__/workflow'
-
-// Mock workflow context
-vi.mock('@/app/components/workflow/hooks', () => ({
-  useWorkflowStore: () => mockWorkflowStore,
-  useNodesInteractions: () => mockNodesInteractions,
-}))
-
-let mockWorkflowStore = {
-  nodes: [],
-  edges: [],
-  updateNode: vi.fn(),
-}
-
-let mockNodesInteractions = {
-  handleNodeSelect: vi.fn(),
-  handleNodeDelete: vi.fn(),
-}
-
-describe('NodeConfigPanel', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockWorkflowStore = {
-      nodes: [],
-      edges: [],
-      updateNode: vi.fn(),
-    }
-  })
-
-  describe('Node Configuration', () => {
-    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' })
-      )
-    })
-  })
-
-  describe('Data Validation', () => {
-    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()
-      })
-    })
-
-    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()
-      })
-    })
-  })
-
-  describe('Variable Passing', () => {
-    it('should display available variables from upstream nodes', () => {
-      const upstreamNode = createMockNode({
-        id: 'node-1',
-        type: 'start',
-        data: { outputs: [{ name: 'user_input', type: 'string' }] },
-      })
-      const currentNode = createMockNode({
-        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}}'))
-    })
-  })
-})
-```
-
-## Dataset Components (`dataset/`)
-
-Dataset components handle file uploads, data display, and search/filter operations.
-
-### Key Test Areas
-
-1. **File Upload**
-1. **File Type Validation**
-1. **Pagination**
-1. **Search & Filtering**
-1. **Data Format Handling**
-
-### Example: Document Uploader
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import DocumentUploader from './document-uploader'
-
-vi.mock('@/service/datasets', () => ({
-  uploadDocument: vi.fn(),
-  parseDocument: vi.fn(),
-}))
-
-import * as datasetService from '@/service/datasets'
-const mockedService = vi.mocked(datasetService)
-
-describe('DocumentUploader', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  describe('File Upload', () => {
-    it('should accept valid file types', async () => {
-      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)
-        )
-      })
-    })
-
-    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()
-      })
-    })
-  })
-
-  describe('Error Handling', () => {
-    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()
-      })
-    })
-
-    it('should allow retry after failure', async () => {
-      const user = userEvent.setup()
-      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()
-      })
-    })
-  })
-})
-```
-
-### Example: Document List with Pagination
-
-```typescript
-describe('DocumentList', () => {
-  describe('Pagination', () => {
-    it('should load first page on mount', async () => {
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '1', name: 'Doc 1' }],
-        total: 50,
-        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 })
-    })
-
-    it('should navigate to next page', async () => {
-      const user = userEvent.setup()
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '1', name: 'Doc 1' }],
-        total: 50,
-        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()
-      })
-    })
-  })
-
-  describe('Search & Filtering', () => {
-    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()
-    })
-  })
-})
-```
-
-## Configuration Components (`app/configuration/`, `config/`)
-
-Configuration components handle forms, validation, and data persistence.
-
-### Key Test Areas
-
-1. **Form Validation**
-1. **Save/Reset**
-1. **Required vs Optional Fields**
-1. **Configuration Persistence**
-1. **Error Feedback**
-
-### Example: App Configuration Form
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import AppConfigForm from './app-config-form'
-
-vi.mock('@/service/apps', () => ({
-  updateAppConfig: vi.fn(),
-  getAppConfig: vi.fn(),
-}))
-
-import * as appService from '@/service/apps'
-const mockedService = vi.mocked(appService)
-
-describe('AppConfigForm', () => {
-  const defaultConfig = {
-    name: 'My App',
-    description: '',
-    icon: 'default',
-    openingStatement: '',
-  }
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockedService.getAppConfig.mockResolvedValue(defaultConfig)
-  })
-
-  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()
-      })
-    })
-  })
-
-  describe('Save/Reset Functionality', () => {
-    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()
-    })
-  })
-
-  describe('Error Handling', () => {
-    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

@@ -1,535 +0,0 @@
-# Mocking Guide for Dify Frontend Tests
-
-## ⚠️ Important: What NOT to Mock
-
-### DO NOT Mock Base Components or dify-ui Primitives
-
-**Never mock components from `@/app/components/base/` or from `@langgenius/dify-ui/*`** such as:
-
-- Legacy base (`@/app/components/base/*`): `Loading`, `Spinner`, `Input`, `Badge`, `Tag`
-- dify-ui primitives (`@langgenius/dify-ui/*`): `Button`, `Tooltip`, `Dialog`, `Popover`, `DropdownMenu`, `ContextMenu`, `Select`, `AlertDialog`, `Toast`
-
-**Why?**
-
-- These components have their own dedicated tests
-- Mocking them creates false positives (tests pass but real integration fails)
-- Using real components tests actual integration behavior
-
-```typescript
-// ❌ WRONG: Don't mock base components or dify-ui primitives
-vi.mock('@/app/components/base/loading', () => () => <div>Loading</div>)
-vi.mock('@langgenius/dify-ui/button', () => ({ Button: ({ children }: any) => <button>{children}</button> }))
-
-// ✅ CORRECT: Import and use the real components
-import Loading from '@/app/components/base/loading'
-import { Button } from '@langgenius/dify-ui/button'
-// They will render normally in tests
-```
-
-### What TO Mock
-
-Only mock these categories:
-
-1. **API services** (`@/service/*`) - Network calls
-1. **Complex context providers** - When setup is too difficult
-1. **Third-party libraries with side effects** - `next/navigation`, external SDKs
-1. **i18n** - Always mock to return keys
-
-### Zustand Stores - DO NOT Mock Manually
-
-**Zustand is globally mocked** in `web/vitest.setup.ts`. Use real stores with `setState()`:
-
-```typescript
-// ✅ CORRECT: Use real store, set test state
-import { useAppStore } from '@/app/components/app/store'
-
-useAppStore.setState({ appDetail: { id: 'test', name: 'Test' } })
-render(<MyComponent />)
-
-// ❌ WRONG: Don't mock the store module
-vi.mock('@/app/components/app/store', () => ({ ... }))
-```
-
-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()` |
-
-Modules are not mocked automatically. Use `vi.mock` in test files, or add global mocks in `web/vitest.setup.ts`.
-
-**Note**: Zustand is special - it's globally mocked but you should NOT mock store modules manually. See [Zustand Store Testing](#zustand-store-testing).
-
-## Essential Mocks
-
-### 1. i18n (Auto-loaded via Global Mock)
-
-A global mock is defined in `web/vitest.setup.ts` and is auto-loaded by Vitest setup.
-
-The global mock provides:
-
-- `useTranslation` - returns translation keys with namespace prefix
-- `Trans` component - renders i18nKey and components
-- `useMixedTranslation` (from `@/app/components/plugins/marketplace/hooks`)
-- `useGetLanguage` (from `@/context/i18n`) - returns `'en-US'`
-
-**Default behavior**: Most tests should use the global mock (no local override needed).
-
-**For custom translations**: Use the helper function from `@/test/i18n-mock`:
-
-```typescript
-import { createReactI18nextMock } from '@/test/i18n-mock'
-
-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.
-
-### 2. Next.js Router
-
-```typescript
-const mockPush = vi.fn()
-const mockReplace = vi.fn()
-
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({
-    push: mockPush,
-    replace: mockReplace,
-    back: vi.fn(),
-    prefetch: vi.fn(),
-  }),
-  usePathname: () => '/current-path',
-  useSearchParams: () => new URLSearchParams('?key=value'),
-}))
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should navigate on click', () => {
-    render(<Component />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(mockPush).toHaveBeenCalledWith('/expected-path')
-  })
-})
-```
-
-### 2.1 `nuqs` Query State (Preferred: Testing Adapter)
-
-For tests that validate URL query behavior, use `NuqsTestingAdapter` instead of mocking `nuqs` directly.
-
-```typescript
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
-
-it('should sync query to URL with push history', async () => {
-  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
-    searchParams: '?page=1',
-  })
-
-  act(() => {
-    result.current.setQuery({ page: 2 })
-  })
-
-  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-  const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-  expect(update.options.history).toBe('push')
-  expect(update.searchParams.get('page')).toBe('2')
-})
-```
-
-Use direct `vi.mock('nuqs')` only when URL synchronization is intentionally out of scope.
-
-### 3. Portal Components (with Shared State)
-
-```typescript
-// ⚠️ Important: Use shared state for components that depend on each other
-let mockPortalOpenState = false
-
-vi.mock('@/app/components/base/portal-to-follow-elem', () => ({
-  PortalToFollowElem: ({ children, open, ...props }: any) => {
-    mockPortalOpenState = open || false  // Update shared state
-    return <div data-testid="portal" data-open={open}>{children}</div>
-  },
-  PortalToFollowElemContent: ({ children }: any) => {
-    // ✅ Matches actual: returns null when portal is closed
-    if (!mockPortalOpenState) return null
-    return <div data-testid="portal-content">{children}</div>
-  },
-  PortalToFollowElemTrigger: ({ children }: any) => (
-    <div data-testid="portal-trigger">{children}</div>
-  ),
-}))
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockPortalOpenState = false  // ✅ Reset shared state
-  })
-})
-```
-
-### 4. API Service Mocks
-
-```typescript
-import * as api from '@/service/api'
-
-vi.mock('@/service/api')
-
-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()
-    })
-  })
-
-  it('should show error on failure', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
-    render(<Component />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-### 5. HTTP and `fetch` Mocking
-
-```typescript
-describe('GithubComponent', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should display repo info', async () => {
-    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify({ name: 'dify', stars: 1000 }), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    )
-    
-    render(<GithubComponent />)
-    
-    await waitFor(() => {
-      expect(screen.getByText('dify')).toBeInTheDocument()
-    })
-  })
-
-  it('should handle API error', async () => {
-    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify({ message: 'Server error' }), {
-        status: 500,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    )
-    
-    render(<GithubComponent />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-Prefer mocking `@/service/*` modules or spying on `global.fetch` / `ky` clients with deterministic responses. Do not introduce an HTTP interception dependency such as `nock` or MSW unless it is already declared in the workspace or adding it is part of the task.
-
-### 6. Context Providers
-
-```typescript
-import { ProviderContext } from '@/context/provider-context'
-import { createMockProviderContextValue, createMockPlan } from '@/__mocks__/provider-context'
-
-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()
-  })
-})
-```
-
-### 7. React Query
-
-```typescript
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-
-const createTestQueryClient = () => new QueryClient({
-  defaultOptions: {
-    queries: { retry: false },
-    mutations: { retry: false },
-  },
-})
-
-const renderWithQueryClient = (ui: React.ReactElement) => {
-  const queryClient = createTestQueryClient()
-  return render(
-    <QueryClientProvider client={queryClient}>
-      {ui}
-    </QueryClientProvider>
-  )
-}
-```
-
-## Mock Best Practices
-
-### ✅ DO
-
-1. **Use real base components and dify-ui primitives** - Import from `@/app/components/base/` or `@langgenius/dify-ui/*` directly
-1. **Use real project components** - Prefer importing over mocking
-1. **Use real Zustand stores** - Set test state via `store.setState()`
-1. **Reset mocks in `beforeEach`**, not `afterEach`
-1. **Match actual component behavior** in mocks (when mocking is necessary)
-1. **Use factory functions** for complex mock data
-1. **Import actual types** for type safety
-1. **Reset shared mock state** in `beforeEach`
-
-### ❌ DON'T
-
-1. **Don't mock base components or dify-ui primitives** (`Loading`, `Input`, `Button`, `Tooltip`, `Dialog`, etc.)
-1. **Don't mock Zustand store modules** - Use real stores with `setState()`
-1. Don't mock components you can import directly
-1. Don't create overly simplified mocks that miss conditional logic
-1. Don't leave HTTP mocks or service mock state leaking between tests
-1. Don't use `any` types in mocks without necessity
-
-### Mock Decision Tree
-
-```
-Need to use a component in test?
-│
-├─ Is it from @/app/components/base/* or @langgenius/dify-ui/*?
-│  └─ YES → Import real component, DO NOT mock
-│
-├─ Is it a project component?
-│  └─ YES → Prefer importing real component
-│           Only mock if setup is extremely complex
-│
-├─ Is it an API service (@/service/*)?
-│  └─ YES → Mock it
-│
-├─ Is it a third-party lib with side effects?
-│  └─ YES → Mock it (next/navigation, external SDKs)
-│
-├─ Is it a Zustand store?
-│  └─ YES → DO NOT mock the module!
-│           Use real store + setState() to set test state
-│           (Global mock handles auto-reset)
-│
-└─ Is it i18n?
-   └─ YES → Uses shared mock (auto-loaded). Override only for custom translations
-```
-
-## Zustand Store Testing
-
-### Global Zustand Mock (Auto-loaded)
-
-Zustand is globally mocked in `web/vitest.setup.ts` following the [official Zustand testing guide](https://zustand.docs.pmnd.rs/guides/testing). The mock in `web/__mocks__/zustand.ts` provides:
-
-- Real store behavior with `getState()`, `setState()`, `subscribe()` methods
-- Automatic store reset after each test via `afterEach`
-- Proper test isolation between tests
-
-### ✅ Recommended: Use Real Stores (Official Best Practice)
-
-**DO NOT mock store modules manually.** Import and use the real store, then use `setState()` to set test state:
-
-```typescript
-// ✅ CORRECT: Use real store with setState
-import { useAppStore } from '@/app/components/app/store'
-
-describe('MyComponent', () => {
-  it('should render app details', () => {
-    // Arrange: Set test state via setState
-    useAppStore.setState({
-      appDetail: {
-        id: 'test-app',
-        name: 'Test App',
-        mode: 'chat',
-      },
-    })
-
-    // Act
-    render(<MyComponent />)
-
-    // Assert
-    expect(screen.getByText('Test App')).toBeInTheDocument()
-    // Can also verify store state directly
-    expect(useAppStore.getState().appDetail?.name).toBe('Test App')
-  })
-
-  // No cleanup needed - global mock auto-resets after each test
-})
-```
-
-### ❌ Avoid: Manual Store Module Mocking
-
-Manual mocking conflicts with the global Zustand mock and loses store functionality:
-
-```typescript
-// ❌ WRONG: Don't mock the store module
-vi.mock('@/app/components/app/store', () => ({
-  useStore: (selector) => mockSelector(selector),  // Missing getState, setState!
-}))
-
-// ❌ WRONG: This conflicts with global zustand mock
-vi.mock('@/app/components/workflow/store', () => ({
-  useWorkflowStore: vi.fn(() => mockState),
-}))
-```
-
-**Problems with manual mocking:**
-
-1. Loses `getState()`, `setState()`, `subscribe()` methods
-1. Conflicts with global Zustand mock behavior
-1. Requires manual maintenance of store API
-1. Tests don't reflect actual store behavior
-
-### When Manual Store Mocking is Necessary
-
-In rare cases where the store has complex initialization or side effects, you can mock it, but ensure you provide the full store API:
-
-```typescript
-// If you MUST mock (rare), include full store API
-const mockStore = {
-  appDetail: { id: 'test', name: 'Test' },
-  setAppDetail: vi.fn(),
-}
-
-vi.mock('@/app/components/app/store', () => ({
-  useStore: Object.assign(
-    (selector: (state: typeof mockStore) => unknown) => selector(mockStore),
-    {
-      getState: () => mockStore,
-      setState: vi.fn(),
-      subscribe: vi.fn(),
-    },
-  ),
-}))
-```
-
-### Store Testing Decision Tree
-
-```
-Need to test a component using Zustand store?
-│
-├─ Can you use the real store?
-│  └─ YES → Use real store + setState (RECOMMENDED)
-│           useAppStore.setState({ ... })
-│
-├─ Does the store have complex initialization/side effects?
-│  └─ YES → Consider mocking, but include full API
-│           (getState, setState, subscribe)
-│
-└─ Are you testing the store itself (not a component)?
-   └─ YES → Test store directly with getState/setState
-            const store = useMyStore
-            store.setState({ count: 0 })
-            store.getState().increment()
-            expect(store.getState().count).toBe(1)
-```
-
-### Example: Testing Store Actions
-
-```typescript
-import { useCounterStore } from '@/stores/counter'
-
-describe('Counter Store', () => {
-  it('should increment count', () => {
-    // Initial state (auto-reset by global mock)
-    expect(useCounterStore.getState().count).toBe(0)
-
-    // Call action
-    useCounterStore.getState().increment()
-
-    // Verify state change
-    expect(useCounterStore.getState().count).toBe(1)
-  })
-
-  it('should reset to initial state', () => {
-    // Set some state
-    useCounterStore.setState({ count: 100 })
-    expect(useCounterStore.getState().count).toBe(100)
-
-    // After this test, global mock will reset to initial state
-  })
-})
-```
-
-## Factory Function Pattern
-
-```typescript
-// __mocks__/data-factories.ts
-import type { User, Project } from '@/types'
-
-export const createMockUser = (overrides: Partial<User> = {}): User => ({
-  id: 'user-1',
-  name: 'Test User',
-  email: 'test@example.com',
-  role: 'member',
-  createdAt: new Date().toISOString(),
-  ...overrides,
-})
-
-export const createMockProject = (overrides: Partial<Project> = {}): Project => ({
-  id: 'project-1',
-  name: 'Test Project',
-  description: 'A test project',
-  owner: createMockUser(),
-  members: [],
-  createdAt: new Date().toISOString(),
-  ...overrides,
-})
-
-// Usage in tests
-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

@@ -1,269 +0,0 @@
-# Testing Workflow Guide
-
-This guide defines the workflow for generating tests, especially for complex components or directories with multiple files.
-
-## Scope Clarification
-
-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 |
-
-## ⚠️ Critical Rule: Incremental Approach for Multi-File Testing
-
-When testing a **directory with multiple files**, **NEVER generate all test files at once.** Use an incremental, verify-as-you-go approach.
-
-### 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 |
-
-## Single File Workflow
-
-When testing a **single component, hook, or utility**:
-
-```
-1. Read source code completely
-2. Run `pnpm analyze-component <path>` (if available)
-3. Check complexity score and features detected
-4. Write the test file
-5. Run test: `pnpm test <file>.spec.tsx`
-6. Fix any failures
-7. Verify coverage meets goals (100% function, >95% branch)
-```
-
-## Directory/Multi-File Workflow (MUST FOLLOW)
-
-When testing a **directory or multiple files**, follow this strict workflow:
-
-### Step 1: Analyze and Plan
-
-1. **List all files** that need tests in the directory
-1. **Categorize by complexity**:
-   - 🟢 **Simple**: Utility functions, simple hooks, presentational components
-   - 🟡 **Medium**: Components with state, effects, or event handlers
-   - 🔴 **Complex**: Components with API calls, routing, or many dependencies
-1. **Order by dependency**: Test dependencies before dependents
-1. **Create a todo list** to track progress
-
-### Step 2: Determine Processing Order
-
-Process files in this recommended order:
-
-```
-1. Utility functions (simplest, no React)
-2. Custom hooks (isolated logic)
-3. Simple presentational components (few/no props)
-4. Medium complexity components (state, effects)
-5. Complex components (API, routing, many deps)
-6. Container/index components (integration tests - last)
-```
-
-**Rationale**:
-
-- Simpler files help establish mock patterns
-- Hooks used by components should be tested first
-- Integration tests (index files) depend on child components working
-
-### Step 3: Process Each File Incrementally
-
-**For EACH file in the ordered list:**
-
-```
-┌─────────────────────────────────────────────┐
-│  1. Write test file                         │
-│  2. Run: pnpm test <file>.spec.tsx          │
-│  3. If FAIL → Fix immediately, re-run       │
-│  4. If PASS → Mark complete in todo list    │
-│  5. ONLY THEN proceed to next file          │
-└─────────────────────────────────────────────┘
-```
-
-**DO NOT proceed to the next file until the current one passes.**
-
-### Step 4: Final Verification
-
-After all individual tests pass:
-
-```bash
-# Run all tests in the directory together
-pnpm test path/to/directory/
-
-# Check coverage
-pnpm test:coverage path/to/directory/
-```
-
-## Component Complexity Guidelines
-
-Use `pnpm analyze-component <path>` to assess complexity before testing.
-
-### 🔴 Very Complex Components (Complexity > 50)
-
-**Consider refactoring BEFORE testing:**
-
-- Break component into smaller, testable pieces
-- Extract complex logic into custom hooks
-- Separate container and presentational layers
-
-**If testing as-is:**
-
-- Use integration tests for complex workflows
-- Use `test.each()` for data-driven testing
-- Multiple `describe` blocks for organization
-- Consider testing major sections separately
-
-### 🟡 Medium Complexity (Complexity 30-50)
-
-- Group related tests in `describe` blocks
-- Test integration scenarios between internal parts
-- Focus on state transitions and side effects
-- Use helper functions to reduce test complexity
-
-### 🟢 Simple Components (Complexity < 30)
-
-- Standard test structure
-- Focus on props, rendering, and edge cases
-- Usually straightforward to test
-
-### 📏 Large Files (500+ lines)
-
-Regardless of complexity score:
-
-- **Strongly consider refactoring** before testing
-- If testing as-is, test major sections separately
-- Create helper functions for test setup
-- May need multiple test files
-
-## Todo List Format
-
-When testing multiple files, use a todo list like this:
-
-```
-Testing: path/to/directory/
-
-Ordered by complexity (simple → complex):
-
-☐ utils/helper.ts           [utility, simple]
-☐ hooks/use-custom-hook.ts  [hook, simple]
-☐ empty-state.tsx           [component, simple]
-☐ item-card.tsx             [component, medium]
-☐ list.tsx                  [component, complex]
-☐ index.tsx                 [integration]
-
-Progress: 0/6 complete
-```
-
-Update status as you complete each:
-
-- ☐ → ⏳ (in progress)
-- ⏳ → ✅ (complete and verified)
-- ⏳ → ❌ (blocked, needs attention)
-
-## When to Stop and Verify
-
-**Always run tests after:**
-
-- Completing a test file
-- Making changes to fix a failure
-- Modifying shared mocks
-- Updating test utilities or helpers
-
-**Signs you should pause:**
-
-- More than 2 consecutive test failures
-- Mock-related errors appearing
-- Unclear why a test is failing
-- Test passing but coverage unexpectedly low
-
-## Common Pitfalls to Avoid
-
-### ❌ Don't: Generate Everything First
-
-```
-# BAD: Writing all files then testing
-Write component-a.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
-```
-
-### ✅ Do: Verify Each Step
-
-```
-# GOOD: Incremental with verification
-Write component-a.spec.tsx
-Run pnpm test component-a.spec.tsx ✅
-Write component-b.spec.tsx
-Run pnpm test component-b.spec.tsx ✅
-...continue...
-```
-
-### ❌ Don't: Skip Verification for "Simple" Components
-
-Even simple components can have:
-
-- Import errors
-- Missing mock setup
-- Incorrect assumptions about props
-
-**Always verify, regardless of perceived simplicity.**
-
-### ❌ Don't: Continue When Tests Fail
-
-Failing tests compound:
-
-- A mock issue in file A affects files B, C, D
-- Fixing A later requires revisiting all dependent tests
-- Time wasted on debugging cascading failures
-
-**Fix failures immediately before proceeding.**
-
-## Integration with Codex's Todo Feature
-
-When using Codex for multi-file testing:
-
-1. **Create a todo list** before starting
-1. **Process one file at a time**
-1. **Verify each test passes** before asking for the next
-1. **Mark todos complete** as you progress
-
-Example prompt:
-
-```
-Test all components in `path/to/directory/`.
-First, analyze the directory and create a todo list ordered by complexity.
-Then, process ONE file at a time, waiting for my confirmation that tests pass
-before proceeding to the next.
-```
-
-## Summary Checklist
-
-Before starting multi-file testing:
-
-- [ ] Listed all files needing tests
-- [ ] Ordered by complexity (simple → complex)
-- [ ] Created todo list for tracking
-- [ ] Understand dependencies between files
-
-During testing:
-
-- [ ] Processing ONE file at a time
-- [ ] Running tests after EACH file
-- [ ] Fixing failures BEFORE proceeding
-- [ ] Updating todo list progress
-
-After completion:
-
-- [ ] All individual tests pass
-- [ ] Full directory test run passes
-- [ ] Coverage goals met
-- [ ] Todo list shows all complete

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

@@ -1,125 +1,42 @@
 ---
 name: how-to-write-component
-description: Use when writing, refactoring, or reviewing React/TypeScript components in Dify web, especially decisions about component ownership, props/types, URL/query state, Jotai state, async state, generated API contracts, queries/mutations, overlays, effects, navigation, performance, and empty states.
+description: Use when implementing or refactoring React/TypeScript components and the task requires decisions about component ownership, feature boundaries, state, data flow, effects, or interaction ownership. Do not use for review-only requests, test-only work, copy-only edits, or styling-only changes.
 ---
 
 # How To Write A Component
 
-Use this as the component decision guide for Dify web. Existing code is reference material, not automatic precedent; if touched code violates these rules, adapt it and fix equivalent patterns in the same feature branch.
+Use this skill to route component architecture decisions to its bundled references. Read only the references required by the current change.
 
 ## First Decisions
 
-| Question | Default | Promote or extract only when |
+| Question | Default | Choose differently when |
 | --- | --- | --- |
-| Where should code live? | Keep it local to the feature workflow, route, or owner. | Multiple verticals need the same stable primitive. |
-| How should route/tab folders be named? | Match the current route segment, tab name, or user-visible surface. | Keep a historical or broader parent only when it still owns multiple surfaces. |
-| Who owns state, data, and handlers? | The lowest component that uses them. | A parent coordinates shared loading, errors, empty UI, selection, submission, navigation, or one consistent snapshot. |
-| Should this become Jotai state? | Keep synchronous UI/form state in component or DOM state. | Siblings need one source of truth, the value drives atoms, or scoped workflow state must survive hidden/unmounted steps. |
-| Should URL state enter Jotai? | Let Next.js route params and `nuqs` own URL state and updates. | Query atoms or shared derived atoms need a read-only bridge hydrated at the route/surface boundary. |
-| Should this query/mutation become an atom? | Use TanStack Query hooks at the lowest owner. | It reads atom state, feeds derived atoms, or participates in shared Jotai workflow orchestration. |
-| Should this be a helper/wrapper? | Prefer direct readable code at the use site. | The name captures a stable domain rule or the wrapper owns real behavior, validation, state, error handling, or semantics. |
-| Is an Effect needed? | No. Derive during render or handle the user action in the event handler. | It synchronizes with an external system such as browser APIs, subscriptions, timers, analytics, or imperative DOM/non-React widgets. |
+| Where should code live? | In the product workflow, route, or feature owner. | Several verticals need the same stable contract. |
+| Who owns state and handlers? | The lowest owner that consumes them and whose lifetime matches the state. | Another owner coordinates the value or it must survive the local owner's unmount. |
+| Should React control a value? | Leave submit-only DOM fields uncontrolled. | The workflow must own the current value to drive rendering or coordination. |
+| Should state enter Jotai? | Keep component and form state local. | Siblings need one source of truth or scoped workflow persistence. |
+| Who owns URL state? | Next.js route APIs and `nuqs`. | Atoms require a read-only route-identity bridge. |
+| Who owns remote state? | TanStack Query at the lowest consumer. | Atom state drives the query or shared derivations consume it. |
+| Is a wrapper needed? | Use the primitive or direct code. | The wrapper owns behavior, validation, state, or semantics. |
+| Is an Effect needed? | Derive during render or handle the user action. | A named external system must be synchronized. |
 
-## Core Defaults
+## Topic Routing
 
-- Search before adding UI, hooks, helpers, query utilities, or styling patterns. Reuse existing base components, feature components, hooks, utilities, and design styles when they fit.
-- 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 choices.
-- Group feature code by workflow, route, or ownership area with route-aligned names: components, hooks, local types, query helpers, atoms, constants, tests, and small utilities should live near the code that changes with them.
-- Keep source/default selection, validation, dirty checks, and payload shaping close to the workflow that owns submit behavior. Do not hide flow-specific priority order, fallback behavior, or submit semantics in generic utilities.
-- Prefer direct conditionals for small branch-specific decisions, especially form source selection and request payload assembly.
-- Loading states for page sections, cards, lists, tables, forms, and drawers should be skeletons scoped to the content being loaded. Use spinners only for small inline busy indicators.
+- Component moves, module boundaries, props, types, or owner placement: read [`references/ownership.md`][ownership].
+- Jotai, form drafts, route identity, URL state, or persistence: read [`references/state.md`][state].
+- Generated contracts, nullable API data, Query, mutations, SSR, auth, or workspace state: read [`references/data.md`][data].
+- Hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces: read [`references/interactions.md`][interactions] and the overlay guide it references when applicable. Also read [`references/state.md`][state] when the surface owns a draft or other local session state.
+- Effects, navigation, memoization, preloading, or render cost: read [`references/runtime.md`][runtime].
 
-## Layout And Ownership
+## Workflow
 
-- State-heavy wizards, drawers, modals, and secondary workflows can be a small feature surface: an entry file, one feature-local state file when Jotai is actually needed, and shallow `ui/` owners that match real visual regions.
-- The entry file handles route integration, provider wiring, close behavior, and surface mounting. The composition owner handles high-level workflow branching. The closest visual owner handles section branching.
-- When a page or tab maps to a route segment, name its feature folder after that route/tab surface instead of a stale parent grouping. Remove misleading intermediate folders when only one surface remains.
-- When a tab folder grows into several independent sections or action areas, split the first level by product/visual owners. Keep the root for the entry component and cross-owner state, colocate tests with the owner folder, and put truly shared local UI under a specifically named `components/` file.
-- Repeated TanStack query calls in sibling components are acceptable when each component independently consumes the data; TanStack Query deduplicates and shares cache.
-- Pass stable domain identity across boundaries. Do not forward derived presentation state when the receiver can derive it from its own data source.
-- A component that owns a visual surface should also own data access, loading, empty, and error states for content rendered inside it unless a parent truly coordinates that state.
-- 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 flow.
-- Do not replace prop drilling with one large view-model hook threaded through section props. Move each hook, query, derived value, and handler to the concrete section that consumes it.
-- Keep callbacks in a parent only for workflow coordination such as form submission, shared selection, batch behavior, or navigation. Otherwise let the child, menu, or row own the action.
+1. Identify the behavior owner, the required state lifetime, and the public contract being changed.
+2. Read the nearby implementation, tests, and only the routed skill references.
+3. Implement one coherent vertical slice. Do not expand into equivalent patterns elsewhere unless the current contract cannot be completed without them.
+4. Verify observable behavior at the narrowest sufficient boundary, then run the checks documented by the owning package: `web/docs/test.md` or `web/docs/lint.md` for Web, and `packages/dify-ui/docs/testing.md` for Dify UI.
 
-## Feature-Scoped Jotai
-
-- A Jotai-backed feature has one feature-local state file for shared primitive atoms, query atoms, derived atoms, write-only actions, mutation atoms, submission orchestration, provider exports, and optional scope configuration.
-- Keep component-owned synchronous UI state local even inside Jotai features: dialog open flags, menus/popovers, confirmations, field drafts, and selected local options usually belong in component state.
-- Use uncontrolled `@langgenius/dify-ui/form` and `@langgenius/dify-ui/field` controls for edit/create forms whose fields are read only at submit time. Initialize query-backed defaults with `defaultValue` and keyed remounts.
-- Promote form state to atoms only when another component must react to in-progress values, a draft must survive unmount/remount in the scoped workflow, or multiple steps share the same editable draft before submit.
-- Treat `useParams`, route args, and `nuqs` query state as framework-owned state. When atom logic needs those values, hydrate primitive atoms at the route or surface boundary, such as with `useHydrateAtoms(..., { dangerouslyForceHydrate: true })`; keep URL updates in the route/query-state APIs instead of write atoms.
-- Within a route-owned feature, choose one source for route identity. If route params are bridged into feature atoms, use that bridge consistently for route-derived queries and actions instead of also threading the same route id through page, tab, and section props.
-- For async work tied to atom state, use `atomWithQuery` or `atomWithMutation`; write atoms should update only the inputs that drive those atoms. This applies to pure frontend async work as well as network requests, so do not hand-roll loading/error/in-flight state with `useState` or `useRef` for atom-orchestrated async behavior. For component-owned remote work, use `useQuery` or `useMutation` directly.
-- Row-local async state belongs to the row owner unless it participates in a shared Jotai workflow or needs atom-scoped reset semantics.
-- Leave query and mutation atoms unscoped so they keep shared QueryClient cache and invalidation behavior. Scope resettable primitives and explicit hydration tuples; scope a derived atom only when every dependency should be private to that surface.
-- For scoped primitives that are always hydrated by `ScopeProvider`, prefer `atomWithLazy<T>(() => { throw new Error(...) })` when consumers should see a non-null type.
-- Order state files by dependency graph: types/constants, primitives, query atoms, query-data derived atoms, business/readiness derived atoms, write actions, mutation atoms, submission orchestration, provider exports.
-- Name derived atoms as business facts and write atoms as user or workflow commands. Components should read or write the exact atom they need with `useAtomValue` or `useSetAtom`.
-- Menu/dialog `open` state usually stays local, but a scoped atom is acceptable when a composed menu plus secondary surface would otherwise pass confusing `open`/`onClose` props through unrelated layers. Scope that primitive with the surface instance so reset behavior stays local.
-- Keep independent dialog lifecycles separate. Avoid one discriminated "current action dialog" atom when dialogs have separate open state, loading guards, or reset behavior.
-
-## 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.
-- Avoid barrel files that only re-export secondary owners. `index.tsx` is acceptable for a route/tab entry component; import header controls, switches, sections, and row owners from their concrete owner 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 and one-off UI extensions beside the component that needs them.
-- Avoid `common.tsx` buckets for shared UI. Use a feature-local `components/` folder with concrete filenames that describe the shared role.
-- Do not create type aliases that only rename another type. Use aliases only for real UI concepts, refinements, or reusable local contracts.
-- Name values by their domain role and backend API contract, especially persistent IDs and route params. Normalize framework or route params at the boundary.
-- Put fallback and invariant checks in the lowest component that already handles that state. Do not extract helpers whose only behavior is hiding missing display data.
-
-## Generated API And Nullable Data
-
-- 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 DTO mirrors, widen generated fields/enums, or add parallel frontend enum/status layers unless they model product state not represented by the API.
-- Use generated enum objects and union types directly in props, comparisons, status logic, and i18n keys. Presentation-only tone maps should be keyed by generated enums.
-- Normalize or coerce only at real boundaries: user-entered forms, search, URL/query params, file names, DOM IDs, or legacy adapters.
-- Do not coerce nullable or optional API strings to `''` in query, derived model, or payload-building code. Keep `null` or `undefined` until the final boundary requiring a string.
-- Do not use `value || undefined` for mutation fields where `''` means "clear this value". Trim or normalize at the form boundary, then preserve intentional empty strings.
-- Prefer nullable-tolerant render props for API-returned rows. Narrow only where a real value is required, such as mutation params, route hrefs, select values, query input, or required React keys.
-- Build required values in the same branch that proves them, using `flatMap`, a local loop, or an early return. Avoid truthiness guards, `filter(Boolean)`, `filter(item => item.id)`, and `!` after filters.
-- Use conditional spreads or explicit pushes for conditional array items instead of `undefined` placeholders followed by narrowing filters.
-- Empty collection fallbacks are for not-yet-loaded query data or genuinely nullable collections at the owning render boundary, not for hiding required API fields.
-
-## Queries And Mutations
-
-- Keep `web/contract/*` as the API shape source of truth and follow the `{ params, query?, body? }` input shape.
-- Consume generated queries with `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))`.
-- If a generated query input comes from an atom, including a route-identity bridge atom, keep the query in `atomWithQuery`; do not unwrap the atom in a component just to call `useQuery`.
-- Consume owner-local mutations with `useMutation(consoleQuery.xxx.mutationOptions(...))` or `useMutation(marketplaceQuery.xxx.mutationOptions(...))` when pending/error state is not consumed by feature atoms.
-- In `atomWithQuery`, `atomWithInfiniteQuery`, and `atomWithMutation`, return generated `queryOptions()`, `infiniteOptions()`, or `mutationOptions()` directly. Pass `enabled`, `retry`, `placeholderData`, `select`, and pagination options into the generated call instead of spreading options into a hand-built object.
-- For generated oRPC options with missing required input, branch the whole input with `input: condition ? validInput : skipToken` and `enabled: Boolean(condition)`. Never place `skipToken` inside a nested placeholder payload or coerce required IDs to `''`.
-- When prefetch and render use the same request, extract local query options or a query-options atom so `prefetchQuery` and `useQuery`/`atomWithQuery` share the exact options.
-- For custom query or mutation functions, wrap options with TanStack `queryOptions(...)` or `mutationOptions(...)`.
-- Do not extract generated `queryOptions(...)` into a helper solely to share input construction; extract only when prefetch/render must share exact options or the helper owns real domain behavior.
-- Avoid pass-through hooks and thin `web/service/use-*` wrappers that only rename generated options. Keep feature hooks for real orchestration, workflow state, or shared domain behavior.
-- Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`. Component or atom callbacks may handle local toasts, closing dialogs, and navigation, but should not replace shared invalidation or patch shared server state locally.
-- For overlays that may open heavier secondary content, prefetch from the trigger/menu open event with `queryClient.prefetchQuery(queryOptions)` when `onOpenChange` is available. Do not mount hidden subscribers just to warm cache.
-- Do not use deprecated `useInvalid` or `useReset`.
-- Prefer `mutate(...)`; use `mutateAsync(...)` only when Promise semantics are required, and wrap awaited calls in `try/catch`.
-
-## Boundaries And Overlays
-
-- Use the first level below a page or tab to organize independent page sections when it adds structure or the root folder becomes noisy. 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. Keep adjacent UI as a sibling owner or introduce a correctly named broader owner.
-- 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 when hidden content would obscure the parent.
-- Preserve composability by separating behavior ownership from placement ownership: an action can own trigger/open/menu content while the caller owns slots, offsets, and alignment.
-- When a dialog, dropdown, or popover accepts controlled `open`, mount it unconditionally unless unmounting is required for performance or reset semantics. Use keyed scope or local state reset instead of `{open && <Surface />}` wrappers.
-- When opening a dialog from a menu item, keep the menu and dialog as sibling surfaces. Let the menu command open the dialog, and mount the dialog outside menu popup content.
-- For dialogs and alert dialogs, keep the root responsible for `open` wiring and put query/mutation hooks inside the content component when work should mount only after the overlay opens.
-- Prefer uncontrolled overlay roots when the library can own open state. Use `onOpenChange` for side effects and CSS/data selectors for open-state styling.
-- Avoid wrapper DOM unless it provides layout, semantics, accessibility, state ownership, or library integration. Avoid shallow wrappers, hook-to-props adapters, layout-only render props, children pass-through wrappers, and prop renaming unless they add real behavior or a real boundary.
-
-## Effects, Navigation, And Performance
-
-- Use Effects only to synchronize with external systems. Do not use Effects to transform props/state for rendering, handle user actions, copy state, reset state from props, or fetch data.
-- For forms initialized from query data, prefer keyed remounts or surface-entry atom hydration over Effects that copy query data into form state.
-- Prefer framework data APIs or TanStack Query for data fetching.
-- Prefer `Link` for normal navigation. Use router APIs only for command-flow side effects such as mutation success, guarded redirects, or form submission.
-- Before using `memo`, move changing state down to the smallest component that uses it. If state must wrap stable content, lift the stable content up and pass it as `children`.
-- Avoid `memo`, `useMemo`, and `useCallback` unless there is a clear performance reason.
+[data]: references/data.md
+[interactions]: references/interactions.md
+[ownership]: references/ownership.md
+[runtime]: references/runtime.md
+[state]: references/state.md

.agents/skills/how-to-write-component/references/data.md

@@ -0,0 +1,42 @@
+# Component Data And Queries
+
+Read this document when a component consumes generated contracts, nullable API values, TanStack Query, mutations, prefetching, authentication, or workspace state.
+
+## Generated Contracts
+
+- Treat generated contracts as authoritative at API, query, mutation, cache, and service boundaries. Enterprise APIs use `packages/contracts/generated/enterprise/*`.
+- Backend Pydantic and OpenAPI schemas own API shape. Follow the generated `{ params, query?, body? }` input shape; when it is wrong, fix the backend schema and regenerate `packages/contracts/generated/*`.
+- Do not hand-write DTO mirrors, widen generated fields or enums, edit generated output, or add a parallel frontend status layer unless it models product state absent from the API.
+- Check deprecated markers, schema shape, and the actual consumer before assuming that a generated operation is ready to use.
+- Normalize only at real boundaries such as user input, search, URL params, filenames, DOM IDs, or a required legacy adapter.
+- Preserve `null`, `undefined`, and intentional empty strings until the final boundary. Do not use `value || undefined` when an empty string means clearing a field.
+- Build required values in the branch that proves them. Avoid `filter(Boolean)`, truthiness filters, non-null assertions after filters, and placeholder values used only to satisfy types.
+
+## Queries
+
+- Use generated options directly with `useQuery(consoleQuery.xxx.queryOptions(...))`, `marketplaceQuery`, or the equivalent generated client.
+- If query input comes from atom state, keep it in `atomWithQuery`; do not unwrap the atom in a component solely to call `useQuery`.
+- For missing required input, branch the whole generated input with `skipToken`. Add `enabled` only for an independent execution condition; do not put `skipToken` inside a placeholder payload or coerce IDs to empty strings.
+- Return generated `queryOptions()`, `infiniteOptions()`, or `mutationOptions()` directly from TanStack Query atoms. Pass supported options into the generated call instead of spreading into a parallel object.
+- Share the exact options between prefetch and render when they represent the same request. Do not extract option helpers merely to reuse input construction.
+- Avoid pass-through service hooks that only rename generated options. Keep feature hooks for actual orchestration or shared domain behavior.
+
+## Mutations And Cache
+
+- Use generated `mutationOptions()` directly for owner-local mutations.
+- Put shared invalidation, retries, and cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`. Local callbacks may own toast, close, and navigation effects but must not replace shared cache policy.
+- Prefer `mutate(...)`. Use `mutateAsync(...)` only when Promise composition is required, and catch awaited failures.
+- Preserve intentional empty values and current list/detail ownership when updating data. Do not add optimistic updates without a verified owner contract.
+
+## Prefetch And Hidden Surfaces
+
+- Prefetch expensive secondary content from the trigger or menu-open event when it benefits the visible path. Do not mount hidden subscribers solely to warm the cache.
+- `prefetchQuery` is cache warmup, not an authorization or availability gate. Use a hard fetch boundary when the server must decide whether rendering may proceed.
+
+## SSR, Authentication, And Workspace
+
+- Static configuration owns path-invariant routing. Request-dependent authentication, setup, role, and tenant decisions belong to SSR or runtime decision boundaries.
+- Distinguish soft SSR cache warming from authoritative decisions. Prefetched or placeholder data must not grant access or represent successful availability.
+- Never reuse tenant-scoped state after switching workspaces. Discard it at the switch boundary or isolate it by workspace identity.
+- Do not make product or authorization decisions from bootstrap defaults. Wait for authoritative data, or render an explicit loading or error state.
+- Keep loading and Suspense behavior inside the feature that owns the request. Do not add fake global data merely to bypass that boundary.

.agents/skills/how-to-write-component/references/interactions.md

@@ -0,0 +1,32 @@
+# Component Interactions And Overlays
+
+Read this document when a change involves application hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces. Overlay primitive selection and layering are owned by the [overlay contract].
+
+## Focus And Semantics
+
+- Preserve a visible focus indicator on the final focusable element. Styled Dify UI controls usually provide it; headless anatomy parts and direct trigger exports may not.
+- Native buttons, links, custom trigger renderers, clickable rows, icon controls, and menu-like items must retain their correct native semantics and accessible name.
+- Do not hide an outline without an equivalent visible `focus-visible` treatment. Follow an existing Dify UI pattern rather than inventing a call-site style.
+
+## Keyboard Commands
+
+- Distinguish application commands from widget-local keyboard semantics. Use `@tanstack/react-hotkeys` for application commands; keep menu navigation, dialog Escape handling, editor behavior, and ARIA widget keys in their local primitive or owner.
+- Use `useHotkey` or `useHotkeys` for registered commands. When an existing `onKeyDown` intentionally owns the command, use `matchesKeyboardEvent` rather than duplicating modifier parsing or adding another global listener.
+- Keep registration and keycap or menu display derived from one canonical command. Distinguish registered commands, held keys, and display-only accelerators.
+- Keep a single-owner command beside its component. Create a feature-local hotkey module only when several production files share it; tests alone do not justify extraction.
+- Make availability and scope explicit with `enabled`, `ignoreInputs`, and `target`. Put a target ref on the actual behavior owner rather than creating wrapper DOM solely for hotkey scope.
+- Preserve existing `preventDefault` and propagation behavior when migrating command APIs.
+- Test observable command behavior, disabled and input scope, target scope, and the registration/display contract at the owning feature boundary.
+
+## Secondary Surfaces
+
+- Follow the [overlay contract] for primitive choice and shared mechanics. The nearest consumer `AGENTS.md` owns application-specific composite reuse policy.
+- Separate behavior ownership from placement ownership: the action may own trigger, open state, and menu content while the caller owns slots, offsets, and alignment.
+- Keep menu and dialog surfaces as siblings when a menu command opens a dialog. Mount the dialog outside popup content.
+- Keep overlay open-state ownership separate from content-session ownership. A controlled root does not require controlled fields or root-owned drafts.
+- Match transient state to the primitive's content mount lifecycle. State below an unmounting content boundary gets a fresh instance after unmount; intentionally kept-mounted content needs an explicit persistence or reset policy.
+- Keep a controlled overlay root at its coordination owner so the primitive can complete exit transitions, focus restoration, and detached-handle behavior. Do not conditionally remove the root to reset content state, and use keys only for stable semantic identity.
+- Place query subscriptions and mutation observers at the owner whose lifetime matches when they should run. Mounted-session work may belong inside content; work that must start or stop exactly with `open` needs an explicit open-state condition.
+- Prefer primitive-owned open state unless another owner must observe or coordinate it. Analytics callbacks and local cleanup alone do not require a controlled root.
+
+[overlay contract]: ../../../../packages/dify-ui/docs/overlays.md

.agents/skills/how-to-write-component/references/ownership.md

@@ -0,0 +1,40 @@
+# Component Ownership And Modules
+
+Read this document when adding, moving, splitting, or refactoring React components or feature modules.
+
+## Vertical Modules
+
+- Organize code by product workflow, route, or behavior owner. Keep components, hooks, local types, atoms, query helpers, tests, and small utilities beside the code that changes with them.
+- Name page and tab folders after the current route, tab, or user-visible surface. Do not preserve stale parent groupings that no longer own multiple surfaces.
+- Split a growing page or tab by product or visual owners. Keep the feature root for its public entrypoint and genuinely cross-owner coordination.
+- Import other features only through explicit public entrypoints. Avoid barrels that merely re-export secondary owners.
+- Promote code outside a feature only when multiple verticals use the same stable contract. Possible future reuse is not sufficient.
+
+## Component Ownership
+
+- Put state, data access, loading, empty, error, and handlers in the lowest owner that uses them and whose mounted lifetime matches the required persistence.
+- Keep coordination in a parent only when it needs one consistent snapshot, the value must intentionally survive the local owner's unmount, or the parent coordinates submission, shared selection, batch behavior, navigation, or cross-section loading and errors.
+- Repeated TanStack Query calls in siblings are acceptable when each sibling independently consumes the data; the cache already deduplicates requests.
+- Pass stable domain identity across boundaries. Do not pass raw server data together with separately derived flags for the same concept.
+- One pass-through prop layer is acceptable. Repeated forwarding means ownership should move closer to the consumer or into feature-scoped shared state.
+- Do not replace prop drilling with one large view-model hook. Move each query, derived value, and handler to the concrete owner that consumes it.
+- Keep source selection, defaults, validation, dirty checks, and payload shaping beside the workflow that owns submission.
+
+## Boundaries
+
+- State-heavy wizards, drawers, modals, and secondary workflows can form a small vertical surface with an entrypoint, optional feature-local state, and shallow owners matching real visual regions.
+- The entrypoint owns route integration, provider wiring, placement, and open-state coordination. A content or session owner keeps state scoped to that mounted surface.
+- Judge hook lifetime by the component that declares the hook and the primitive's mount contract, not only by where its rendered controls appear in JSX.
+- Separate hidden dialogs, dropdowns, and popovers into small local owners when their content obscures the parent flow.
+- Keep cohesive forms, menu bodies, and one-off helpers local unless they have their own state, reuse, or semantic boundary.
+- Avoid wrapper components and wrapper DOM that only rename props, pass children through, or hide the real primitive. A wrapper must own behavior, validation, state, accessibility, layout, or library integration.
+- Loading states for page sections, cards, lists, tables, forms, and drawers should use skeletons scoped to the loaded content. Reserve spinners for small inline busy indicators.
+
+## Components And Types
+
+- Choose component declaration and export forms from the actual component contract, framework requirements, and enforced package rules. Existing style is context, not authority; do not rewrite unaffected code solely to normalize `FC`, `function`, arrow-function, named-export, or default-export forms.
+- Type simple one-off props inline. Name a `Props` type when it is reused, exported, complex, or materially clearer.
+- Use API-generated or API-returned types at component boundaries. Keep one-off UI refinements and conversions beside their owner.
+- Preserve domain value types for selections. Do not widen enums, unions, booleans, numbers, objects, or nullable values to `string` before a real boundary requires it.
+- Avoid generic `common.tsx` buckets and aliases that only rename another type. Name files, values, and public types after their domain role.
+- Put fallback and invariant checks in the lowest component that already renders that state. Do not extract helpers whose only purpose is hiding missing display data.

.agents/skills/how-to-write-component/references/runtime.md

@@ -0,0 +1,24 @@
+# Component Effects, Navigation, And Runtime Cost
+
+Read this document when a change introduces Effects, navigation side effects, memoization, preloading, or render-cost optimizations.
+
+## Effects
+
+- Keep render pure: do not read or write `ref.current` during render except for predictable null-guarded lazy initialization. Update interaction-owned refs in event handlers, synchronize external-system refs after commit, and use state or derivation for rendered values.
+- Use Effects only to synchronize with a named external system such as a browser API, subscription, timer, analytics integration, non-React widget, or imperative DOM API.
+- Do not use Effects to transform render state, handle user actions, copy query data, reset state from props, or fetch data owned by framework APIs or TanStack Query.
+- Initialize query-backed form sessions after their defaults are available instead of copying data through Effects. Use a stable semantic identity key when the represented identity changes; use the intended surface lifecycle for per-session reset.
+
+## Navigation
+
+- Use `Link` for ordinary navigation.
+- Use router APIs for command-flow side effects such as mutation success, guarded redirects, or form submission.
+- Keep shareable navigation state in the URL rather than hidden component state.
+
+## Runtime Cost
+
+- Move changing state to the smallest consumer before considering memoization. Stable parent content can be lifted and passed as children.
+- Avoid `memo`, `useMemo`, and `useCallback` unless identity or computation has a demonstrated consumer or measurable cost.
+- Start independent remote work together and await it near the branch that consumes it. Avoid introducing request waterfalls.
+- Load heavy optional surfaces on demand when they sit behind a dialog, tab, command, or feature activation.
+- Use narrow selectors or field-level atoms for broad stores and subscriptions. Do not optimize simple primitive expressions merely for stylistic consistency.

.agents/skills/how-to-write-component/references/state.md

@@ -0,0 +1,40 @@
+# Component State And URL Ownership
+
+Read this document when a change involves Jotai, form drafts, route identity, shared client state, or local persistence.
+
+## Choose The Owner
+
+- Keep synchronous state local when one component owns it: dialog and menu state, confirmations, field drafts, and local selections usually belong to the component or DOM.
+- Use feature-scoped Jotai when siblings need one source of truth, values drive other atoms, or a scoped workflow must preserve state across hidden or unmounted steps.
+- Keep server and cache state in TanStack Query. Use existing feature stores for complex, high-frequency interaction state such as workflow canvas drag, resize, and runtime panels.
+- Use feature-owned storage only for low-frequency client preferences, dismissed notices, and UI defaults. Live application state does not belong in local storage.
+
+## Forms And Sessions
+
+- Keep form state in the narrowest owner whose lifetime matches the draft. A draft scoped to one mounted surface belongs to that content or session owner; a draft that must survive its current owner's unmount belongs to an explicit longer-lived feature owner.
+- Prefer uncontrolled fields when values are only read at submit time. Use local controlled state only when React must own the current value to drive dependent UI or linked fields; track derived facts such as dirty state without mirroring the field value. Controlledness does not decide whether a draft is local or persisted.
+- For query-backed defaults, establish the form session after the required defaults are available. `defaultValue` initializes the current mount; a stable semantic identity key may create a fresh snapshot when the represented identity changes. Do not use a generated key as a routine reset command.
+- Promote drafts beyond the session only when another owner reacts to in-progress values, several workflow steps share one draft, or the draft must intentionally survive unmounting. Start with the lowest shared React owner; use feature-scoped atoms only when their coordination or persistence contract is needed.
+- Keep validation, source priority, fallback behavior, dirty checks, and payload assembly in the workflow that owns submission.
+
+## Route And URL State
+
+- Treat `useParams`, route arguments, and `nuqs` as the owners of URL identity and updates.
+- Hydrate a primitive atom at the route or surface boundary only when query atoms or shared derived atoms require route identity. Keep URL writes in route and query-state APIs.
+- Within one route-owned feature, choose one route-identity source. Do not hydrate route identity into atoms while also threading the same ID through multiple component layers.
+- Put shareable filters, tabs, pagination, and search state in the URL. Keep one-shot navigation signals and transient UI state out of persistent subscriptions.
+
+## Jotai And Query
+
+- A Jotai-backed feature may keep one feature-local state module ordered by dependency: types and constants, primitives, query atoms, query-data derivations, business facts, commands, mutations, submission orchestration, and provider exports.
+- Use `atomWithQuery` or `atomWithMutation` for async work driven by atom state. Do not hand-roll loading, error, or in-flight state for atom-orchestrated work.
+- Use field-specific derived atoms for query results. `jotai-tanstack-query` does not provide TanStack Query tracked properties, so reading a whole query atom subscribes to the entire observer result.
+- Leave query and mutation atoms unscoped so they retain the shared QueryClient cache. Scope resettable primitives and hydration tuples; scope a derived atom only when all dependencies should be private to the surface.
+- Use non-null lazy primitives for values always hydrated by a scope provider. Name derived atoms as business facts and write atoms as user or workflow commands.
+- Keep independent dialog lifecycles separate. A scoped open-state atom is acceptable only when composed sibling surfaces would otherwise pass confusing lifecycle props through unrelated owners.
+
+## Persistence
+
+- Use feature-owned storage modules built on `createLocalStorageState`; callers should not scatter direct storage access or raw keys.
+- Persist high-frequency interaction state only on commit or after updates settle.
+- Do not add ad hoc global event listeners for shared state. Centralize subscriptions through the owning atom, store, or subscription hook.

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

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

.claude/skills/component-refactoring

@@ -1 +0,0 @@
-../../.agents/skills/component-refactoring

.claude/skills/karpathy-guidelines

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

.devcontainer/devcontainer.json

@@ -12,7 +12,7 @@
 	"features": {
 		"ghcr.io/devcontainers/features/node:1": {
 			"nodeGypDependencies": true,
-			"version": "lts"
+			"version": "24.20.0"
 		},
 		"ghcr.io/devcontainers-extra/features/npm-package:1": {
 			"package": "typescript",
@@ -46,4 +46,4 @@
 	// Configure tool-specific properties.
 	// "customizations": {},
 	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-}
+}

.editorconfig

@@ -37,3 +37,7 @@ indent_size = 2
 [package.json]
 indent_style = space
 indent_size = 2
+
+# Oxlint writes its generated suppression baseline without a final newline.
+[oxlint-suppressions.json]
+insert_final_newline = false

.gemini/config.yaml

@@ -1,13 +0,0 @@
-have_fun: false
-memory_config:
-  disabled: false
-code_review:
-  disable: true
-  comment_severity_threshold: MEDIUM
-  max_review_comments: -1
-  pull_request_opened:
-    help: false
-    summary: false
-    code_review: false
-    include_drafts: false
-ignore_patterns: []

.github/CODEOWNERS

@@ -6,8 +6,8 @@
 
 * @crazywoola @laipz8200
 
-# ESLint suppression file is maintained by autofix.ci pruning.
-/eslint-suppressions.json
+# Lint bulk suppression baselines.
+/oxlint-suppressions.json
 
 # CODEOWNERS file
 /.github/CODEOWNERS @laipz8200 @crazywoola
@@ -26,34 +26,16 @@
 /cli/ @GareArc
 /.github/workflows/cli-tests.yml @GareArc
 
+# E2E
+/e2e/ @lyzno1
+/.github/workflows/web-e2e.yml @lyzno1
+
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost
 
-# Backend - MCP
-/api/core/mcp/ @Nov1c444
-/api/core/entities/mcp_provider.py @Nov1c444
-/api/services/tools/mcp_tools_manage_service.py @Nov1c444
-/api/controllers/mcp/ @Nov1c444
-/api/controllers/console/app/mcp_server.py @Nov1c444
-
 # Backend - Tests
 /api/tests/ @laipz8200 @QuantumGhost
 
-/api/tests/**/*mcp* @Nov1c444
-
-# Backend - Workflow - Engine (Core graph execution engine)
-/api/core/workflow/graph_engine/ @laipz8200 @QuantumGhost
-/api/core/workflow/runtime/ @laipz8200 @QuantumGhost
-/api/core/workflow/graph/ @laipz8200 @QuantumGhost
-/api/core/workflow/graph_events/ @laipz8200 @QuantumGhost
-/api/core/workflow/node_events/ @laipz8200 @QuantumGhost
-
-# Backend - Workflow - Nodes (Agent, Iteration, Loop, LLM)
-/api/core/workflow/nodes/agent/ @Nov1c444
-/api/core/workflow/nodes/iteration/ @Nov1c444
-/api/core/workflow/nodes/loop/ @Nov1c444
-/api/core/workflow/nodes/llm/ @Nov1c444
-
 # Backend - RAG (Retrieval Augmented Generation)
 /api/core/rag/ @JohnJyong
 /api/services/rag_pipeline/ @JohnJyong
@@ -107,7 +89,6 @@
 /api/core/app/layers/trigger_post_layer.py @CourTeous33
 /api/services/trigger/ @CourTeous33
 /api/models/trigger.py @CourTeous33
-/api/fields/workflow_trigger_fields.py @CourTeous33
 /api/repositories/workflow_trigger_log_repository.py @CourTeous33
 /api/repositories/sqlalchemy_workflow_trigger_log_repository.py @CourTeous33
 /api/libs/schedule_utils.py @CourTeous33
@@ -132,11 +113,11 @@
 /api/controllers/console/billing/ @hj24 @zyssyz123
 
 # Backend - Enterprise
-/api/configs/enterprise/ @GarfieldDai @GareArc
-/api/services/enterprise/ @GarfieldDai @GareArc
-/api/services/feature_service.py @GarfieldDai @GareArc
-/api/controllers/console/feature.py @GarfieldDai @GareArc
-/api/controllers/web/feature.py @GarfieldDai @GareArc
+/api/configs/enterprise/ @GareArc
+/api/services/enterprise/ @GareArc
+/api/services/feature_service.py @GareArc
+/api/controllers/console/feature.py @GareArc
+/api/controllers/web/feature.py @GareArc
 
 # Backend - Database Migrations
 /api/migrations/ @snakevash @laipz8200 @MRZHUH
@@ -149,7 +130,6 @@
 
 # Frontend - Platform and Features
 /web/config/ @lyzno1
-/web/contract/ @lyzno1
 /web/env.ts @lyzno1
 /web/features/ @lyzno1
 /web/hooks/ @lyzno1
@@ -208,7 +188,6 @@
 /web/app/components/rag-pipeline/store/ @iamjoel @zxhlyh
 
 # Frontend - RAG - Documents List
-/web/app/components/datasets/documents/list.tsx @iamjoel @WTW0313
 /web/app/components/datasets/documents/create-from-pipeline/ @iamjoel @WTW0313
 
 # Frontend - RAG - Segments List
@@ -227,22 +206,22 @@
 /web/app/components/plugins/marketplace/ @iamjoel @Yessenia-d
 
 # Frontend - Login and Registration
-/web/app/signin/ @douxc @iamjoel
-/web/app/signup/ @douxc @iamjoel
-/web/app/reset-password/ @douxc @iamjoel
-/web/app/install/ @douxc @iamjoel
-/web/app/init/ @douxc @iamjoel
-/web/app/forgot-password/ @douxc @iamjoel
-/web/app/account/ @douxc @iamjoel
+/web/app/signin/ @iamjoel
+/web/app/signup/ @iamjoel
+/web/app/reset-password/ @iamjoel
+/web/app/install/ @iamjoel
+/web/app/init/ @iamjoel
+/web/app/forgot-password/ @iamjoel
+/web/app/account/ @iamjoel
 
 # Frontend - Service Authentication
-/web/service/base.ts @douxc @iamjoel
+/web/service/base.ts @iamjoel
 
 # Frontend - WebApp Authentication and Access Control
-/web/app/(shareLayout)/components/ @douxc @iamjoel
-/web/app/(shareLayout)/webapp-signin/ @douxc @iamjoel
-/web/app/(shareLayout)/webapp-reset-password/ @douxc @iamjoel
-/web/app/components/app/app-access-control/ @douxc @iamjoel
+/web/app/(shareLayout)/components/ @iamjoel
+/web/app/(shareLayout)/webapp-signin/ @iamjoel
+/web/app/(shareLayout)/webapp-reset-password/ @iamjoel
+/web/app/components/app/app-access-control/ @iamjoel
 
 # Frontend - Explore Page
 /web/app/components/explore/ @CodingOnStar @iamjoel
@@ -261,17 +240,37 @@
 /web/app/components/base/**/*.spec.tsx @hyoban @CodingOnStar
 
 # Frontend - Utils and Hooks
-/web/utils/classnames.ts @iamjoel @zxhlyh
 /web/utils/time.ts @iamjoel @zxhlyh
 /web/utils/format.ts @iamjoel @zxhlyh
 /web/utils/clipboard.ts @iamjoel @zxhlyh
 
 # Frontend - Billing and Education
 /web/app/components/billing/ @iamjoel @zxhlyh
-/web/app/education-apply/ @iamjoel @zxhlyh
+/web/app/education/ @iamjoel @zxhlyh
 
 # Frontend - Workspace
 /web/app/components/header/account-dropdown/workplace-selector/ @iamjoel @zxhlyh
 
+# Frontend - App Shell and Console Bootstrap
+/web/app/layout.tsx @iamjoel @lyzno1
+/web/app/error.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/layout.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/providers.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/hydration-boundary.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/profile-bootstrap-gate.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/error.tsx @iamjoel @lyzno1
+/web/app/account/(commonLayout)/layout.tsx @iamjoel @lyzno1
+/web/app/components/main-nav/* @iamjoel @lyzno1
+/web/app/components/main-nav/components/* @iamjoel @lyzno1
+/web/context/query-client.tsx @iamjoel @lyzno1
+/web/context/query-client-server.ts @iamjoel @lyzno1
+/web/proxy.ts @iamjoel @lyzno1
+/web/app/auth/refresh/route.ts @iamjoel @lyzno1
+/web/service/server.ts @iamjoel @lyzno1
+
+# Frontend - Browser Mode Tests
+/web/app/**/*.browser.spec.ts @lyzno1
+/web/app/**/*.browser.spec.tsx @lyzno1
+
 # Docker
 /docker/* @laipz8200

.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/actions/setup-web/action.yml

@@ -5,12 +5,12 @@ runs:
   using: composite
   steps:
     - name: Setup pnpm
-      uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+      uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
       with:
         run_install: false
     - name: Setup Vite+
-      uses: voidzero-dev/setup-vp@ca1c46663915d6c1042ae23bd39ab85718bfb0fa # v1.10.0
+      uses: voidzero-dev/setup-vp@1b32467adbe183473499fd9d5d372c3ed9641754 # v1.18.0
       with:
-        node-version-file: .nvmrc
+        node-version-file: package.json
         cache: true
         run-install: true

.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/labeler.yml

@@ -6,4 +6,9 @@ web:
           - 'package.json'
           - 'pnpm-lock.yaml'
           - 'pnpm-workspace.yaml'
-          - '.nvmrc'
+
+e2e:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'e2e/**'
+          - '.github/workflows/web-e2e.yml'

.github/linters/.hadolint.yaml

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

.github/linters/.yaml-lint.yml

@@ -1,10 +1,11 @@
 ---
-
 extends: default
 
 rules:
   brackets:
     max-spaces-inside: 1
+  comments:
+    min-spaces-from-content: 1
   comments-indentation: disable
   document-start: disable
   line-length: disable

.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
 
@@ -21,4 +21,4 @@
 - [ ] I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
 - [ ] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
 - [ ] I've updated the documentation accordingly.
-- [ ] I ran `make lint && make type-check` (backend) and `cd web && pnpm exec vp staged` (frontend) to appease the lint gods
+- [ ] I ran `make lint && make type-check` (backend) and `vp staged` (frontend) to appease the lint gods

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

@@ -45,7 +45,7 @@ while IFS= read -r commit_sha; do
   )
 
   if [[ -z "$source_sha" ]]; then
-    error "Commit $commit_sha ($subject) is missing cherry-pick provenance. $REMEDIATION_HINT"
+    error "Commit $commit_sha ($subject) is missing cherry-pick provenance. $REMEDIATION_HINT If version differences prevent using git cherry-pick -x, manually add '(cherry picked from commit <sha>)' to the commit message."
     failed=1
     continue
   fi

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

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

.github/workflows/accessibility-e2e.yml

@@ -0,0 +1,101 @@
+name: Manual WCAG Accessibility Audit
+run-name: WCAG ${{ inputs.level }} · ${{ inputs.page }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      page:
+        description: Page to scan
+        required: true
+        default: home
+        type: choice
+        options:
+          - home
+          - sign-in
+          - studio
+          - agents
+          - knowledge
+          - integrations
+          - all
+      level:
+        description: WCAG level to scan
+        required: true
+        default: aa
+        type: choice
+        options:
+          - aa
+          - a
+
+permissions:
+  contents: read
+
+concurrency:
+  group: accessibility-e2e-${{ github.ref }}-${{ inputs.page }}-${{ inputs.level }}
+  cancel-in-progress: true
+
+jobs:
+  accessibility:
+    name: WCAG Level ${{ inputs.level == 'a' && 'A' || 'AA' }} · ${{ inputs.page }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup web dependencies
+        uses: ./.github/actions/setup-web
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: |
+            api/uv.lock
+
+      - name: Install API dependencies
+        run: uv sync --project api --dev
+
+      - name: Install Chromium for accessibility E2E
+        timeout-minutes: 15
+        working-directory: ./e2e
+        run: vp run e2e:install:ci:chromium
+
+      - name: Run automated WCAG Level ${{ inputs.level == 'a' && 'A' || 'AA' }} checks
+        working-directory: ./e2e
+        env:
+          E2E_ADMIN_EMAIL: e2e-admin@example.com
+          E2E_ADMIN_NAME: E2E Admin
+          E2E_ADMIN_PASSWORD: E2eAdmin12345
+          E2E_FORCE_WEB_BUILD: '1'
+          E2E_INIT_PASSWORD: E2eInit12345
+          WCAG_PAGE: ${{ inputs.page }}
+        run: |
+          if [[ "$WCAG_PAGE" == "all" ]]; then
+            vp run e2e:accessibility:${{ inputs.level }}
+          else
+            pnpm exec tsx ./scripts/run-cucumber.ts --full -- --tags "@axe and @wcag-${{ inputs.level }} and @wcag-page-$WCAG_PAGE"
+          fi
+
+      - name: Upload accessibility Cucumber report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: cucumber-report-accessibility-${{ inputs.level }}-${{ inputs.page }}
+          path: e2e/cucumber-report
+          retention-days: 7
+
+      - name: Upload accessibility E2E logs
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-logs-accessibility-${{ inputs.level }}-${{ inputs.page }}
+          path: e2e/.logs/*.log
+          include-hidden-files: true
+          retention-days: 7

.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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -47,9 +47,6 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
-      - name: Run dify config tests
-        run: uv run --project api pytest api/tests/unit_tests/configs/test_env_consistency.py
-
       - name: Run Unit Tests
         run: |
           uv run --project api pytest \
@@ -87,17 +84,17 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -142,16 +139,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies

.github/workflows/autofix.yml

@@ -1,26 +1,24 @@
 name: autofix.ci
 on:
   pull_request:
-    branches: ["main"]
+    branches: ['main']
   merge_group:
-    branches: ["main"]
+    branches: ['main']
     types: [checks_requested]
-  push:
-    branches: ["main"]
 permissions:
   contents: read
 
 jobs:
   autofix:
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Complete merge group check
         if: github.event_name == 'merge_group'
         run: echo "autofix.ci updates pull request branches, not merge group refs."
 
       - if: github.event_name != 'merge_group'
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Check Docker Compose inputs
         if: github.event_name != 'merge_group'
@@ -32,18 +30,6 @@ jobs:
             docker/.env.example
             docker/docker-compose-template.yaml
             docker/docker-compose.yaml
-      - name: Check web inputs
-        if: github.event_name != 'merge_group'
-        id: web-changes
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            web/**
-            packages/**
-            package.json
-            pnpm-lock.yaml
-            pnpm-workspace.yaml
-            .nvmrc
       - name: Check api inputs
         if: github.event_name != 'merge_group'
         id: api-changes
@@ -51,6 +37,18 @@ jobs:
         with:
           files: |
             api/**
+      - name: Check frontend contract inputs
+        if: github.event_name != 'merge_group'
+        id: frontend-contract-changes
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
+        with:
+          files: |
+            api/**
+            packages/contracts/openapi-ts.api.config.ts
+            packages/contracts/package.json
+            packages/contracts/openapi/**
+            pnpm-lock.yaml
+            pnpm-workspace.yaml
       - name: Check dify-agent inputs
         if: github.event_name != 'merge_group'
         id: dify-agent-changes
@@ -60,13 +58,13 @@ jobs:
             dify-agent/**/*.py
             dify-agent/pyproject.toml
             dify-agent/uv.lock
-      - if: github.event_name != 'merge_group'
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - if: github.event_name != 'merge_group' && (steps.docker-compose-changes.outputs.any_changed == 'true' || steps.api-changes.outputs.any_changed == 'true' || steps.frontend-contract-changes.outputs.any_changed == 'true' || steps.dify-agent-changes.outputs.any_changed == 'true')
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.11"
+          python-version: '3.11'
 
-      - if: github.event_name != 'merge_group'
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - if: github.event_name != 'merge_group' && (steps.api-changes.outputs.any_changed == 'true' || steps.frontend-contract-changes.outputs.any_changed == 'true' || steps.dify-agent-changes.outputs.any_changed == 'true')
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
 
       - name: Generate Docker Compose
         if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'
@@ -96,12 +94,6 @@ jobs:
           # Format code
           uv run ruff format .
 
-      - name: count migration progress
-        if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
-        run: |
-          cd api
-          ./cnt_base.sh
-
       - name: ast-grep
         if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
         run: |
@@ -133,7 +125,7 @@ jobs:
           find . -name "*.py.bak" -type f -delete
 
       - name: Setup web environment
-        if: github.event_name != 'merge_group'
+        if: github.event_name != 'merge_group' && steps.frontend-contract-changes.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
       - name: Generate API docs
@@ -143,13 +135,8 @@ jobs:
           uv run dev/generate_swagger_markdown_docs.py --swagger-dir ../packages/contracts/openapi --markdown-dir openapi/markdown --keep-swagger-json
 
       - name: Generate frontend contracts
-        if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
-        run: pnpm --dir packages/contracts gen-api-contract-from-openapi
-
-      - name: ESLint autofix
-        if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'
-        run: |
-          vp exec eslint --concurrency=2 --prune-suppressions --quiet || true
+        if: github.event_name != 'merge_group' && steps.frontend-contract-changes.outputs.any_changed == 'true'
+        run: pnpm --dir packages/contracts gen-api-contract
 
       - if: github.event_name != 'merge_group'
         uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4

.github/workflows/build-push.yml

@@ -3,13 +3,13 @@ name: Build and Push API & Web
 on:
   push:
     branches:
-      - "main"
-      - "deploy/**"
-      - "build/**"
-      - "release/e-*"
-      - "hotfix/**"
+      - 'main'
+      - 'deploy/**'
+      - 'build/**'
+      - 'release/e-*'
+      - 'hotfix/**'
     tags:
-      - "*"
+      - '*'
 
 concurrency:
   group: build-push-${{ github.head_ref || github.run_id }}
@@ -33,60 +33,60 @@ 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"
+          - 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"
+          - 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
-          - service_name: "build-agent-local-sandbox-amd64"
-            image_name_env: "DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME"
-            artifact_context: "local-sandbox"
-            build_context: "{{defaultContext}}:dify-agent"
-            file: "docker/local-sandbox/Dockerfile"
+          - service_name: 'build-agent-local-sandbox-amd64'
+            image_name_env: 'DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME'
+            artifact_context: 'local-sandbox'
+            build_context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
             platform: linux/amd64
             runs_on: depot-ubuntu-24.04-4
-          - service_name: "build-agent-local-sandbox-arm64"
-            image_name_env: "DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME"
-            artifact_context: "local-sandbox"
-            build_context: "{{defaultContext}}:dify-agent"
-            file: "docker/local-sandbox/Dockerfile"
+          - service_name: 'build-agent-local-sandbox-arm64'
+            image_name_env: 'DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME'
+            artifact_context: 'local-sandbox'
+            build_context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
             platform: linux/arm64
             runs_on: depot-ubuntu-24.04-4
 
@@ -97,17 +97,17 @@ jobs:
           echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
 
       - name: Login to Docker Hub
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
       - name: Set up Depot CLI
-        uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
+        uses: depot/setup-action@91bc8495a33ebfc504ffc89e5674379ccf23c29c # v1.7.2
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ${{ env[matrix.image_name_env] }}
 
@@ -120,6 +120,7 @@ jobs:
           file: ${{ matrix.file }}
           platforms: ${{ matrix.platform }}
           build-args: COMMIT_SHA=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
+          build-contexts: ${{ matrix.build_contexts }}
           labels: ${{ steps.meta.outputs.labels }}
           outputs: type=image,name=${{ env[matrix.image_name_env] }},push-by-digest=true,name-canonical=true,push=true
 
@@ -145,28 +146,29 @@ 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-agent-amd64"
-            build_context: "{{defaultContext}}"
-            file: "dify-agent/Dockerfile"
-          - service_name: "validate-agent-local-sandbox-amd64"
-            build_context: "{{defaultContext}}:dify-agent"
-            file: "docker/local-sandbox/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'
+          - service_name: 'validate-agent-local-sandbox-amd64'
+            build_context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Validate Docker image
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           push: false
           context: ${{ matrix.build_context }}
           file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
           platforms: linux/amd64
 
   create-manifest:
@@ -176,18 +178,18 @@ 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-agent-images"
-            image_name_env: "DIFY_AGENT_IMAGE_NAME"
-            context: "agent"
-          - service_name: "merge-agent-local-sandbox-images"
-            image_name_env: "DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME"
-            context: "local-sandbox"
+          - 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'
+          - service_name: 'merge-agent-local-sandbox-images'
+            image_name_env: 'DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME'
+            context: 'local-sandbox'
     steps:
       - name: Download digests
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -197,14 +199,14 @@ jobs:
           merge-multiple: true
 
       - name: Login to Docker Hub
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ${{ env[matrix.image_name_env] }}
           tags: |
@@ -227,3 +229,32 @@ jobs:
           IMAGE_VERSION: ${{ steps.meta.outputs.version }}
         run: |
           docker buildx imagetools inspect "$IMAGE_NAME:$IMAGE_VERSION"
+
+  sync-e2b-template:
+    needs: create-manifest
+    runs-on: ubuntu-24.04
+    if: github.repository == 'langgenius/dify' && startsWith(github.ref, 'refs/tags/')
+    strategy:
+      matrix:
+        include:
+          - project: dev
+            api_key_secret: E2B_API_KEY_DEV
+          - project: prod
+            api_key_secret: E2B_API_KEY_PROD
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USER }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
+
+      - name: Sync E2B Template (${{ matrix.project }})
+        env:
+          E2B_API_KEY: ${{ secrets[matrix.api_key_secret] }}
+        run: ./dify-agent-runtime/docker/sync-e2b-template.sh

.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,35 +51,34 @@ 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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
@@ -88,7 +87,7 @@ jobs:
         with:
           bun-version: latest
 
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
         with:
           package_json_field: packageManager
           run_install: false
@@ -101,19 +100,19 @@ 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"
-    if: ${{ inputs.suite_framework_output_error != 'false' }}
+    name: 'Suite: framework + output + error-handling'
+    if: ${{ inputs.suite_framework_output_error }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -123,31 +122,34 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        with: { bun-version: latest }
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
-        with: { package_json_field: packageManager, run_install: false }
+        with:
+          bun-version: latest
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        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\]"
@@ -155,12 +157,12 @@ jobs:
             pnpm test:e2e
           fi
 
-# ════════════════════════════════════════════════════════════════════════════
-# 1-C. Discovery (parallel)
-# ════════════════════════════════════════════════════════════════════════════
+  # ════════════════════════════════════════════════════════════════════════════
+  # 1-C. Discovery (parallel)
+  # ════════════════════════════════════════════════════════════════════════════
   suite-discovery:
-    name: "Suite: discovery"
-    if: ${{ inputs.suite_discovery != 'false' }}
+    name: 'Suite: discovery'
+    if: ${{ inputs.suite_discovery }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -170,32 +172,35 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        with: { bun-version: latest }
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
-        with: { package_json_field: packageManager, run_install: false }
+        with:
+          bun-version: latest
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        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\]"
@@ -203,12 +208,12 @@ 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 }}"
-    if: ${{ inputs.suite_run != 'false' }}
+    name: 'Suite: run / ${{ matrix.name }}'
+    if: ${{ inputs.suite_run }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -233,38 +238,41 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        with: { bun-version: latest }
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
-        with: { package_json_field: packageManager, run_install: false }
+        with:
+          bun-version: latest
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        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\]"
@@ -280,12 +288,12 @@ jobs:
           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)"
-    if: ${{ inputs.suite_auth != 'false' }}
+    name: 'Suite: auth (login / status / whoami)'
+    if: ${{ inputs.suite_auth }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 15
@@ -295,30 +303,33 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        with: { bun-version: latest }
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
-        with: { package_json_field: packageManager, run_install: false }
+        with:
+          bun-version: latest
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        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\]"
@@ -326,15 +337,15 @@ 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' }}
+    if: ${{ inputs.suite_auth || inputs.suite_agent }}
     needs:
       - provision
       - suite-framework-output-error
@@ -351,35 +362,38 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           ref: ${{ inputs.cli_ref || github.ref }}
           persist-credentials: false
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        with: { bun-version: latest }
-      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
-        with: { package_json_field: packageManager, run_install: false }
+        with:
+          bun-version: latest
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        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=()

.github/workflows/cli-edge.yml

@@ -23,7 +23,7 @@ jobs:
         working-directory: ./cli
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -36,7 +36,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5 # v2.0.2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version-file: cli/.bun-version
 

.github/workflows/cli-release.yml

@@ -7,12 +7,22 @@ on:
         description: Dify release tag to attach difyctl assets to (blank = latest stable)
         required: false
         type: string
+      dry_run:
+        description: Build and checksum only — skip asset upload and stale-asset prune
+        required: false
+        type: boolean
+        default: false
   workflow_call:
     inputs:
       release_tag:
         description: Dify release tag to attach difyctl assets to (blank = latest stable)
         required: false
         type: string
+      dry_run:
+        description: Build and checksum only — skip asset upload and stale-asset prune
+        required: false
+        type: boolean
+        default: false
   release:
     types: [released]
 
@@ -35,15 +45,12 @@ jobs:
       dify_tag: ${{ steps.resolve.outputs.dify_tag }}
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Export manifest to env
-        run: node scripts/release-naming.mjs github-env >> "$GITHUB_ENV"
-
       - name: Validate manifest
-        run: scripts/release-validate-manifest.sh
+        run: node scripts/release-naming.mjs validate
 
       - name: Resolve target Dify release
         id: resolve
@@ -75,15 +82,6 @@ jobs:
           DIFY_TAG: ${{ steps.resolve.outputs.dify_tag }}
         run: node scripts/release-naming.mjs compat-check "$DIFY_TAG"
 
-      - name: Reject duplicate difyctl version
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          if gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${difyctlTag}" >/dev/null 2>&1; then
-              echo "::error::difyctl ${version} already released (tag ${difyctlTag} exists); bump cli/package.json version"
-              exit 1
-          fi
-
   release:
     name: build + attach standalone binaries (all targets)
     needs: validate
@@ -98,7 +96,7 @@ jobs:
       DIFY_TAG: ${{ needs.validate.outputs.dify_tag }}
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 1
@@ -114,12 +112,13 @@ jobs:
         run: node scripts/release-naming.mjs github-env >> "$GITHUB_ENV"
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@4bc047ad259df6fc24a6c9b0f9a0cb08cf17fbe5 # v2.0.2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version-file: cli/.bun-version
 
       - name: Compile standalone binaries (all targets)
         run: |
+          CLI_VERSION="$version" \
           DIFYCTL_COMMIT="$(git rev-parse HEAD)" \
           DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
             pnpm build:bin
@@ -128,6 +127,7 @@ jobs:
         run: scripts/release-write-checksums.sh
 
       - name: Attach difyctl assets to Dify release
+        if: ${{ !inputs.dry_run }}
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -135,6 +135,7 @@ jobs:
               --repo "$GITHUB_REPOSITORY" --clobber
 
       - name: Prune stale difyctl assets
+        if: ${{ !inputs.dry_run }}
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -149,18 +150,3 @@ jobs:
                         --repo "$GITHUB_REPOSITORY" --yes
                 fi
               done
-
-      - name: Create provenance tag
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          ref="refs/tags/${difyctlTag}"
-          sha="$(git rev-parse HEAD)"
-          status="$(gh api -X POST "repos/${GITHUB_REPOSITORY}/git/refs" \
-                -f ref="$ref" -f sha="$sha" --silent --include 2>/dev/null \
-                | awk 'NR==1 {print $2; exit}' || true)"
-          case "$status" in
-              201) echo "::notice::created ${ref}" ;;
-              422) echo "::notice::tag ${ref} already exists; skipping (immutable)" ;;
-              *)   echo "::error::provenance tag ${ref} not created (HTTP ${status:-unknown})"; exit 1 ;;
-          esac

.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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -44,9 +44,9 @@ jobs:
 
       - name: Validate release manifest
         if: matrix.os == 'depot-ubuntu-24.04'
-        run: scripts/release-validate-manifest.sh
+        run: node scripts/release-naming.mjs validate
 
-      - name: CI pipeline (typecheck, lint, coverage, build)
+      - name: CI pipeline (tree, coverage, build)
         run: pnpm run ci
 
       - name: Report coverage

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

@@ -13,16 +13,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         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@11beaa1c2dae4e8ed7b1665aa074723b6cecb0e4 # v3.0.0
+        uses: hoverkraft-tech/compose-action@ee6af68587292d72db67743171809c19787df4c9 # v3.1.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -63,16 +63,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         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@11beaa1c2dae4e8ed7b1665aa074723b6cecb0e4 # v3.0.0
+        uses: hoverkraft-tech/compose-action@ee6af68587292d72db67743171809c19787df4c9 # v3.1.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml

.github/workflows/deploy-agent.yml

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

.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-im-dev.yml

@@ -0,0 +1,25 @@
+name: Deploy HITL IM Dev
+
+on:
+  workflow_run:
+    workflows: ['Build and Push API & Web']
+    branches:
+      - 'build/feat/hitl-im-dev'
+    types:
+      - completed
+
+jobs:
+  deploy:
+    runs-on: depot-ubuntu-24.04
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'build/feat/hitl-im-dev'
+    steps:
+      - name: Deploy to server
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        with:
+          host: ${{ secrets.HITL_SSH_HOST }}
+          username: ${{ secrets.SSH_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            ${{ vars.SSH_SCRIPT || secrets.SSH_SCRIPT }}

.github/workflows/deploy-knowledge.yml

@@ -0,0 +1,71 @@
+name: Deploy Knowledge
+
+permissions:
+  actions: read
+  contents: read
+
+on:
+  workflow_run:
+    workflows: ['Build and Push API & Web']
+    branches:
+      - 'deploy/konwledge'
+    types:
+      - completed
+
+jobs:
+  deploy:
+    runs-on: depot-ubuntu-24.04
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'deploy/konwledge'
+    steps:
+      - name: Wait for KnowledgeFS CI
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        timeout-minutes: 35
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const workflowId = "knowledge-fs-ci.yml";
+            const headBranch = context.payload.workflow_run.head_branch;
+            const headSha = context.payload.workflow_run.head_sha;
+            const deadline = Date.now() + 30 * 60 * 1000;
+            const pollIntervalMs = 15 * 1000;
+
+            while (Date.now() < deadline) {
+              const { data } = await github.rest.actions.listWorkflowRuns({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                workflow_id: workflowId,
+                branch: headBranch,
+                event: "push",
+                head_sha: headSha,
+                per_page: 10,
+              });
+              const run = data.workflow_runs[0];
+
+              if (!run) {
+                core.info(`Waiting for ${workflowId} to start for ${headSha}.`);
+              } else if (run.status !== "completed") {
+                core.info(`Waiting for ${run.html_url}; current status is ${run.status}.`);
+              } else if (run.conclusion !== "success") {
+                throw new Error(
+                  `${workflowId} did not succeed for ${headSha}: ${run.conclusion} (${run.html_url})`,
+                );
+              } else {
+                core.info(`KnowledgeFS CI succeeded for ${headSha}: ${run.html_url}`);
+                return;
+              }
+
+              await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            }
+
+            throw new Error(`Timed out waiting for ${workflowId} to succeed for ${headSha}.`);
+
+      - name: Deploy to server
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        with:
+          host: ${{ secrets.SSH_NEW_RAG_HOST }}
+          username: ${{ secrets.SSH_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            ${{ vars.SSH_SCRIPT || secrets.SSH_SCRIPT }}

.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/dify-agent-tests.yml

@@ -0,0 +1,47 @@
+name: Dify Agent Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dify-agent-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  dify-agent-unit:
+    name: Dify Agent Unit Tests
+    runs-on: depot-ubuntu-24.04
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent
+    strategy:
+      matrix:
+        python-version:
+          - '3.12'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+          cache-dependency-glob: dify-agent/uv.lock
+
+      - name: Check UV lockfile
+        run: uv lock --check
+
+      - name: Install dependencies
+        run: uv sync --extra server --dev
+
+      - name: Run unit tests
+        run: uv run pytest

.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
@@ -13,6 +13,11 @@ on:
       - dify-agent/README.md
       - dify-agent/src/**
       - web/Dockerfile
+      - dify-agent-runtime/docker/Dockerfile
+      - dify-agent-runtime/go.mod
+      - dify-agent-runtime/go.sum
+      - dify-agent-runtime/cmd/**
+      - dify-agent-runtime/internal/**
 
 concurrency:
   group: docker-build-${{ github.head_ref || github.run_id }}
@@ -28,29 +33,39 @@ 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'
+          - service_name: 'local-sandbox-amd64'
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
+          - service_name: 'local-sandbox-arm64'
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
     steps:
       - name: Set up Depot CLI
-        uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
+        uses: depot/setup-action@91bc8495a33ebfc504ffc89e5674379ccf23c29c # v1.7.2
 
       - name: Build Docker Image
         uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
@@ -59,6 +74,7 @@ jobs:
           push: false
           context: ${{ matrix.context }}
           file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
           platforms: ${{ matrix.platform }}
 
   build-docker-fork:
@@ -69,20 +85,24 @@ 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'
+          - service_name: 'local-sandbox-amd64'
+            context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Build Docker Image
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           push: false
           context: ${{ matrix.context }}
           file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
           platforms: linux/amd64

.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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 

.github/workflows/labeler.yml

@@ -1,4 +1,4 @@
-name: "Pull Request Labeler"
+name: 'Pull Request Labeler'
 on:
   pull_request_target:
 
@@ -9,6 +9,6 @@ jobs:
       pull-requests: write
     runs-on: depot-ubuntu-24.04
     steps:
-      - uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6.1.0
+      - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0
         with:
           sync-labels: true

.github/workflows/main-ci.yml

@@ -2,12 +2,10 @@ name: Main CI Pipeline
 
 on:
   pull_request:
-    branches: ["main"]
+    branches: ['main']
   merge_group:
-    branches: ["main"]
+    branches: ['main']
     types: [checks_requested]
-  push:
-    branches: ["main"]
 
 permissions:
   actions: write
@@ -17,8 +15,10 @@ permissions:
   statuses: write
 
 concurrency:
-  group: main-ci-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
+  # Pull request deduplication is owned by skip-duplicate-actions so pre_job can
+  # publish should_skip before required status finalizers run.
+  group: main-ci-${{ github.event.merge_group.head_sha || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'merge_group' }}
 
 jobs:
   pre_job:
@@ -29,7 +29,7 @@ jobs:
     steps:
       - id: skip_check
         continue-on-error: true
-        uses: fkirc/skip-duplicate-actions@f75f66ce1886f00957d99748a42c724f4330bdcf # v5.3.1
+        uses: fkirc/skip-duplicate-actions@b974a9395958c231af965b70070979a577efa578 # v5.3.2
         with:
           cancel_others: 'true'
           concurrent_skipping: same_content_newer
@@ -47,14 +47,24 @@ jobs:
       web-changed: ${{ steps.changes.outputs.web }}
       vdb-changed: ${{ steps.changes.outputs.vdb }}
       migration-changed: ${{ steps.changes.outputs.migration }}
+      sandbox-runtime-changed: ${{ steps.changes.outputs.sandbox-runtime }}
+      dify-agent-changed: ${{ steps.changes.outputs.dify-agent }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
         id: changes
         with:
           filters: |
             api:
               - 'api/**'
+              - 'scripts/ast_grep_guard.py'
+              - 'scripts/check_no_new_getattr.py'
+              - 'scripts/check_no_new_controller_sqlalchemy.py'
+              - 'scripts/lint_controller_sqlalchemy.py'
+              - 'scripts/ast_grep_rules/no_new_getattr.yml'
+              - 'scripts/ast_grep_rules/no_new_controller_sqlalchemy.yml'
+              - '.github/workflows/style.yml'
+              - '.github/workflows/main-ci.yml'
               - '.github/workflows/api-tests.yml'
               - 'docker/.env.example'
               - 'docker/envs/middleware.env.example'
@@ -65,15 +75,14 @@ jobs:
               - 'docker/volumes/sandbox/conf/**'
             cli:
               - 'cli/**'
+              - 'packages/contracts/**'
               - 'packages/tsconfig/**'
               - 'package.json'
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
-              - 'eslint.config.mjs'
+              - 'lint.config.ts'
               - '.npmrc'
-              - '.nvmrc'
               - '.github/workflows/cli-tests.yml'
-              - '.github/workflows/cli-docker-build.yml'
               - '.github/actions/setup-web/**'
             web:
               - 'web/**'
@@ -81,7 +90,7 @@ jobs:
               - 'package.json'
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
-              - '.nvmrc'
+              - '.github/workflows/main-ci.yml'
               - '.github/workflows/web-tests.yml'
               - '.github/actions/setup-web/**'
             e2e:
@@ -94,10 +103,10 @@ jobs:
               - 'package.json'
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
-              - '.nvmrc'
               - 'docker/docker-compose.middleware.yaml'
               - 'docker/envs/middleware.env.example'
               - '.github/workflows/web-e2e.yml'
+              - '.github/workflows/main-ci.yml'
               - '.github/actions/setup-web/**'
             vdb:
               - 'api/core/rag/datasource/**'
@@ -124,6 +133,12 @@ jobs:
               - 'docker/volumes/**'
               - 'api/uv.lock'
               - 'api/pyproject.toml'
+            sandbox-runtime:
+              - 'dify-agent-runtime/**'
+              - '.github/workflows/sandbox-runtime-tests.yml'
+            dify-agent:
+              - 'dify-agent/**'
+              - '.github/workflows/dify-agent-tests.yml'
             migration:
               - 'api/migrations/**'
               - 'api/.env.example'
@@ -324,6 +339,9 @@ jobs:
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.e2e-changed == 'true'
     uses: ./.github/workflows/web-e2e.yml
+    with:
+      run-external-runtime: false
+    secrets: inherit
 
   web-e2e-skip:
     name: Skip Web Full-Stack E2E
@@ -379,8 +397,10 @@ jobs:
   style-check:
     name: Style Check
     needs: pre_job
-    if: needs.pre_job.outputs.should_skip != 'true'
     uses: ./.github/workflows/style.yml
+    with:
+      base-rev: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha }}
+      skip-checks: ${{ needs.pre_job.outputs.should_skip == 'true' }}
 
   vdb-tests-run:
     name: Run VDB Tests
@@ -499,3 +519,123 @@ jobs:
 
           echo "DB migration tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
           exit 1
+
+  sandbox-runtime-tests-run:
+    name: Run Sandbox Runtime Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.sandbox-runtime-changed == 'true'
+    uses: ./.github/workflows/sandbox-runtime-tests.yml
+    secrets: inherit
+
+  sandbox-runtime-tests-skip:
+    name: Skip Sandbox Runtime Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.sandbox-runtime-changed != 'true'
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Report skipped sandbox runtime tests
+        run: echo "No sandbox-runtime-related changes detected; skipping sandbox runtime tests."
+
+  sandbox-runtime-tests:
+    name: Sandbox Runtime Tests
+    if: ${{ always() }}
+    needs:
+      - pre_job
+      - check-changes
+      - sandbox-runtime-tests-run
+      - sandbox-runtime-tests-skip
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Finalize Sandbox Runtime Tests status
+        env:
+          SHOULD_SKIP_WORKFLOW: ${{ needs.pre_job.outputs.should_skip }}
+          TESTS_CHANGED: ${{ needs.check-changes.outputs.sandbox-runtime-changed }}
+          RUN_RESULT: ${{ needs.sandbox-runtime-tests-run.result }}
+          SKIP_RESULT: ${{ needs.sandbox-runtime-tests-skip.result }}
+        run: |
+          if [[ "$SHOULD_SKIP_WORKFLOW" == 'true' ]]; then
+            echo "Sandbox runtime tests were skipped because this workflow run duplicated a successful or newer run."
+            exit 0
+          fi
+
+          if [[ "$TESTS_CHANGED" == 'true' ]]; then
+            if [[ "$RUN_RESULT" == 'success' ]]; then
+              echo "Sandbox runtime tests ran successfully."
+              exit 0
+            fi
+
+            echo "Sandbox runtime tests were required but finished with result: $RUN_RESULT" >&2
+            exit 1
+          fi
+
+          if [[ "$SKIP_RESULT" == 'success' ]]; then
+            echo "Sandbox runtime tests were skipped because no sandbox-runtime-related files changed."
+            exit 0
+          fi
+
+          echo "Sandbox runtime tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
+          exit 1
+
+  dify-agent-tests-run:
+    name: Run Dify Agent Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.dify-agent-changed == 'true'
+    uses: ./.github/workflows/dify-agent-tests.yml
+    secrets: inherit
+
+  dify-agent-tests-skip:
+    name: Skip Dify Agent Tests
+    needs:
+      - pre_job
+      - check-changes
+    if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.dify-agent-changed != 'true'
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Report skipped dify agent tests
+        run: echo "No dify-agent-related changes detected; skipping dify agent tests."
+
+  dify-agent-tests:
+    name: Dify Agent Tests
+    if: ${{ always() }}
+    needs:
+      - pre_job
+      - check-changes
+      - dify-agent-tests-run
+      - dify-agent-tests-skip
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Finalize Dify Agent Tests status
+        env:
+          SHOULD_SKIP_WORKFLOW: ${{ needs.pre_job.outputs.should_skip }}
+          TESTS_CHANGED: ${{ needs.check-changes.outputs.dify-agent-changed }}
+          RUN_RESULT: ${{ needs.dify-agent-tests-run.result }}
+          SKIP_RESULT: ${{ needs.dify-agent-tests-skip.result }}
+        run: |
+          if [[ "$SHOULD_SKIP_WORKFLOW" == 'true' ]]; then
+            echo "Dify agent tests were skipped because this workflow run duplicated a successful or newer run."
+            exit 0
+          fi
+
+          if [[ "$TESTS_CHANGED" == 'true' ]]; then
+            if [[ "$RUN_RESULT" == 'success' ]]; then
+              echo "Dify agent tests ran successfully."
+              exit 0
+            fi
+
+            echo "Dify agent tests were required but finished with result: $RUN_RESULT" >&2
+            exit 1
+          fi
+
+          if [[ "$SKIP_RESULT" == 'success' ]]; then
+            echo "Dify agent tests were skipped because no dify-agent-related files changed."
+            exit 0
+          fi
+
+          echo "Dify agent tests were not required, but the skip job finished with result: $SKIP_RESULT" >&2
+          exit 1

.github/workflows/post-merge.yml

@@ -0,0 +1,93 @@
+name: Post-Merge Checks
+
+on:
+  push:
+    branches: ['main']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: post-merge-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  check-changes:
+    name: Check Changed Files
+    runs-on: depot-ubuntu-24.04
+    outputs:
+      external-e2e-changed: ${{ steps.changes.outputs.external_e2e }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: changes
+        with:
+          filters: |
+            external_e2e:
+              - 'e2e/features/agent-v2/**'
+              - 'e2e/features/step-definitions/agent-v2/**'
+              - 'e2e/features/step-definitions/common/**'
+              - 'e2e/features/support/**'
+              - 'e2e/fixtures/auth.ts'
+              - 'e2e/fixtures/test-materials/**'
+              - 'e2e/scripts/**'
+              - 'e2e/support/**'
+              - 'e2e/cucumber.config.ts'
+              - 'e2e/package.json'
+              - 'e2e/test-env.ts'
+              - 'e2e/tsconfig.json'
+              - 'e2e/tsx-register.js'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - '.github/workflows/post-merge.yml'
+              - '.github/workflows/web-e2e.yml'
+              - '.github/actions/setup-web/**'
+              - 'docker/docker-compose.middleware.yaml'
+              - 'docker/envs/middleware.env.example'
+              - 'dify-agent/**'
+              - 'dify-agent-runtime/**'
+              - 'api/pyproject.toml'
+              - 'api/uv.lock'
+              - 'api/tests/integration_tests/.env.example'
+              - 'api/clients/agent_backend/**'
+              - 'api/core/app/apps/agent_app/**'
+              - 'api/core/workflow/nodes/agent_v2/**'
+              - 'api/controllers/console/agent/**'
+              - 'api/services/agent/**'
+              - 'api/core/plugin/**'
+              - 'api/services/plugin/**'
+              - 'api/core/tools/**'
+              - 'api/services/tools/**'
+              - 'packages/contracts/package.json'
+              - 'packages/contracts/generated/api/console/agent/**'
+              - 'packages/contracts/generated/api/console/apps/**'
+              - 'packages/contracts/generated/api/console/datasets/**'
+              - 'packages/contracts/generated/api/console/orpc.gen.ts'
+              - 'packages/contracts/generated/api/console/workspaces/**'
+              - 'packages/contracts/generated/api/service/**'
+              - 'web/features/agent-v2/**'
+              - 'web/app/(commonLayout)/agents/**'
+              - 'web/app/(commonLayout)/@detailSidebar/agents/**'
+              - 'web/app/(commonLayout)/roster/**'
+              - 'web/app/components/base/chat/chat/**'
+              - 'web/app/components/base/voice-input/**'
+              - 'web/app/components/workflow/nodes/agent-v2/**'
+              - 'web/i18n/en-US/agent-v-2.json'
+              - 'web/i18n/en-US/common.json'
+              - 'web/service/base.ts'
+              - 'web/service/client.ts'
+              - 'web/service/console-link.ts'
+              - 'web/service/console-openapi-url.ts'
+              - 'web/service/console-router-loader.ts'
+              - 'web/service/share.ts'
+              - 'web/package.json'
+              - 'pnpm-workspace.yaml'
+
+  external-e2e:
+    name: External Runtime E2E
+    needs: check-changes
+    if: needs.check-changes.outputs.external-e2e-changed == 'true'
+    uses: ./.github/workflows/web-e2e.yml
+    with:
+      run-external-runtime: true
+    secrets: inherit

.github/workflows/pyrefly-diff.yml

@@ -17,12 +17,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout PR branch
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
 

.github/workflows/sandbox-runtime-tests.yml

@@ -0,0 +1,98 @@
+name: Sandbox Runtime Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sandbox-runtime-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  sandbox-runtime-unit:
+    name: Sandbox Runtime Unit Tests
+    runs-on: depot-ubuntu-24.04
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent-runtime
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dify-agent-runtime/go.mod
+          cache-dependency-path: dify-agent-runtime/go.sum
+
+      - name: Run unit tests
+        run: go test -race -count=1 ./...
+
+  sandbox-runtime-lint:
+    name: Sandbox Runtime Lint
+    runs-on: depot-ubuntu-24.04
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent-runtime
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dify-agent-runtime/go.mod
+          cache-dependency-path: dify-agent-runtime/go.sum
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
+        with:
+          working-directory: dify-agent-runtime
+          version: latest
+
+  sandbox-runtime-integration:
+    name: Sandbox Runtime Integration Tests
+    runs-on: depot-ubuntu-24.04
+    defaults:
+      run:
+        shell: bash
+        working-directory: dify-agent-runtime
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dify-agent-runtime/go.mod
+          cache-dependency-path: dify-agent-runtime/go.sum
+
+      - name: Build and start runtime
+        run: make integration-up
+
+      - name: Run integration tests
+        run: make integration-test
+
+      - name: Dump container logs on failure
+        if: failure()
+        run: make integration-logs || true
+
+      - name: Stop runtime container
+        if: always()
+        run: make integration-down

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

@@ -2,10 +2,15 @@ name: Style check
 
 on:
   workflow_call:
-
-concurrency:
-  group: style-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
+    inputs:
+      base-rev:
+        required: true
+        type: string
+      skip-checks:
+        description: Create the required check runs without repeating previously successful work.
+        required: false
+        type: boolean
+        default: false
 
 permissions:
   checks: write
@@ -15,13 +20,15 @@ permissions:
 jobs:
   python-style:
     name: Python Style
+    if: ${{ !inputs.skip-checks }}
     runs-on: depot-ubuntu-24.04
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          fetch-depth: 0
 
       - name: Check changed files
         id: changed-files
@@ -29,14 +36,21 @@ jobs:
         with:
           files: |
             api/**
+            scripts/ast_grep_guard.py
+            scripts/check_no_new_getattr.py
+            scripts/check_no_new_controller_sqlalchemy.py
+            scripts/lint_controller_sqlalchemy.py
+            scripts/ast_grep_rules/no_new_getattr.yml
+            scripts/ast_grep_rules/no_new_controller_sqlalchemy.yml
             .github/workflows/style.yml
+            .github/workflows/main-ci.yml
 
       - name: Setup UV and Python
         if: steps.changed-files.outputs.any_changed == 'true'
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: false
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -51,6 +65,14 @@ jobs:
         if: steps.changed-files.outputs.any_changed == 'true'
         run: uv run --project api --dev python api/dev/lint_response_contracts.py --fail-on-mismatch
 
+      - name: Run No New Getattr Guard
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: uv run --project api python scripts/check_no_new_getattr.py --base-rev "${{ inputs.base-rev }}"
+
+      - name: Run No New Controller SQLAlchemy Guard
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: uv run --project api python scripts/check_no_new_controller_sqlalchemy.py --base-rev "${{ inputs.base-rev }}"
+
       - name: Run Type Checks
         if: steps.changed-files.outputs.any_changed == 'true'
         env:
@@ -63,6 +85,7 @@ jobs:
 
   web-style:
     name: Web Style
+    if: ${{ !inputs.skip-checks }}
     runs-on: depot-ubuntu-24.04
     defaults:
       run:
@@ -73,7 +96,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -89,7 +112,8 @@ jobs:
             package.json
             pnpm-lock.yaml
             pnpm-workspace.yaml
-            .nvmrc
+            knip.config.ts
+            scripts/check-web-production-unused-after-knip-fix.mjs
             .github/workflows/style.yml
             .github/actions/setup-web/**
 
@@ -105,26 +129,30 @@ jobs:
 
       - name: Web dead code check
         if: steps.changed-files.outputs.any_changed == 'true'
+        working-directory: .
         run: vp run knip
 
       - name: Web dead code check production
         if: steps.changed-files.outputs.any_changed == 'true'
+        working-directory: .
         run: vp run knip:production
 
       - name: Web production unused declarations check
         if: steps.changed-files.outputs.any_changed == 'true'
+        working-directory: .
         run: vp run knip:production-unused-check
 
   ts-common-style:
     name: TS Common
-    runs-on: depot-ubuntu-24.04
+    if: ${{ !inputs.skip-checks }}
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       checks: write
       pull-requests: read
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -141,47 +169,32 @@ jobs:
             package.json
             pnpm-lock.yaml
             pnpm-workspace.yaml
-            .nvmrc
+            vite.config.ts
+            lint.config.ts
             eslint.config.mjs
-            .github/workflows/style.yml
-            .github/actions/setup-web/**
+            knip.config.ts
+            scripts/check-web-production-unused-after-knip-fix.mjs
+            oxlint-suppressions.json
+            eslint-suppressions.json
+            .vscode/**
+            .github/**
 
       - name: Setup web environment
         if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
-      - name: Restore ESLint cache
+      - name: Static check
         if: steps.changed-files.outputs.any_changed == 'true'
-        id: eslint-cache-restore
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: .eslintcache
-          key: ${{ runner.os }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'web/eslint.config.mjs', 'web/eslint.constants.mjs', 'web/plugins/eslint/**') }}-${{ github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'web/eslint.config.mjs', 'web/eslint.constants.mjs', 'web/plugins/eslint/**') }}-
-
-      - name: Style check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: vp run lint:ci
-
-      - name: Type check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: vp run type-check
-
-      - name: Save ESLint cache
-        if: steps.changed-files.outputs.any_changed == 'true' && success() && steps.eslint-cache-restore.outputs.cache-hit != 'true'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: .eslintcache
-          key: ${{ steps.eslint-cache-restore.outputs.cache-primary-key }}
+        run: pnpm -w check
 
   superlinter:
     name: SuperLinter
+    if: ${{ !inputs.skip-checks }}
     runs-on: depot-ubuntu-24.04
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -197,18 +210,20 @@ jobs:
             **Dockerfile
             dev/**
             .editorconfig
+            .vite-hooks/**
 
       - name: Super-linter
-        uses: super-linter/super-linter/slim@9e863354e3ff62e0727d37183162c4a88873df41 # v8.6.0
+        uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0
         if: steps.changed-files.outputs.any_changed == 'true'
         env:
           BASH_SEVERITY: warning
           DEFAULT_BRANCH: origin/main
           EDITORCONFIG_FILE_NAME: editorconfig-checker.json
-          FILTER_REGEX_INCLUDE: pnpm-lock.yaml
+          ENABLE_GITHUB_PULL_REQUEST_SUMMARY_COMMENT: false
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           IGNORE_GENERATED_FILES: true
           IGNORE_GITIGNORED_FILES: true
+          VALIDATE_ALL_CODEBASE: false
           VALIDATE_BASH: true
           VALIDATE_BASH_EXEC: true
           # FIXME: temporarily disabled until api-docker.yaml's run script is fixed for shellcheck

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

@@ -24,14 +24,14 @@ jobs:
         working-directory: sdks/nodejs-client
 
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Use Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 22
+          node-version-file: package.json
           cache: ''
           cache-dependency-path: 'pnpm-lock.yaml'
 

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

@@ -8,15 +8,19 @@ on:
   workflow_dispatch:
     inputs:
       files:
-        description: 'Specific files to translate (space-separated, e.g., "app common"). Required for full mode; leave empty in incremental mode to use en-US files changed since HEAD~1.'
+        description: 'Specific files to translate (space-separated, e.g., "app common").
+          Required for full mode; leave empty in incremental mode to use en-US
+          files changed since HEAD~1.'
         required: false
         type: string
       languages:
-        description: 'Specific languages to translate (space-separated, e.g., "zh-Hans ja-JP"). Leave empty for all supported target languages except en-US.'
+        description: 'Specific languages to translate (space-separated, e.g., "zh-Hans
+          ja-JP"). Leave empty for all supported target languages except en-US.'
         required: false
         type: string
       mode:
-        description: 'Sync mode: incremental (compare with previous en-US revision) or full (sync all keys in scope)'
+        description: 'Sync mode: incremental (compare with previous en-US revision) or
+          full (sync all keys in scope)'
         required: false
         default: incremental
         type: choice
@@ -40,7 +44,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -158,7 +162,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@806af32823ef69c8ef357086c573a902af641307 # v1.0.151
+        uses: anthropics/claude-code-action@833fb0f8c9f6686b33d963a8bae0a94f4936ab2a # v1.0.211
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -223,7 +227,7 @@ jobs:
                - Match the existing terminology and register used by each locale.
                - Prefer one Edit per file when stable, but prioritize correctness over batching.
             6. Verify only the edited files.
-               - Run `vp run dify-web#lint:fix --quiet -- <relative edited i18n file paths under web/>`
+               - Run `vp fmt <repo-relative edited paths such as web/i18n/...>`
                - Run `vp run dify-web#i18n:check ${{ steps.context.outputs.FILE_ARGS }} ${{ steps.context.outputs.LANG_ARGS }}`
                - If verification fails, fix the remaining problems before continuing.
             7. Stop after the scoped locale files are updated and verification passes.
@@ -322,7 +326,7 @@ jobs:
             '## Verification',
             '',
             `- \`vp run dify-web#i18n:check --file ${process.env.FILES_IN_SCOPE} --lang ${process.env.TARGET_LANGS}\``,
-            `- \`vp run dify-web#lint:fix --quiet -- <edited i18n files under web/>\``,
+            `- \`vp fmt <repo-relative edited paths such as web/i18n/...>\``,
             '',
             '## Notes',
             '',

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

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

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

@@ -20,23 +20,23 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Free Disk Space
-        uses: endersonmenezes/free-disk-space@7901478139cff6e9d44df5972fd8ab8fcade4db1 # v3.2.2
+        uses: endersonmenezes/free-disk-space@2a22f8c59cae9cddae7194b33e6b92d023b2b4b8 # v4.0.0
         with:
           remove_dotnet: true
           remove_haskell: true
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         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,23 +17,23 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.12"
+          - '3.12'
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Free Disk Space
-        uses: endersonmenezes/free-disk-space@7901478139cff6e9d44df5972fd8ab8fcade4db1 # v3.2.2
+        uses: endersonmenezes/free-disk-space@2a22f8c59cae9cddae7194b33e6b92d023b2b4b8 # v4.0.0
         with:
           remove_dotnet: true
           remove_haskell: true
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         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

@@ -2,25 +2,77 @@ name: Web Full-Stack E2E
 
 on:
   workflow_call:
+    inputs:
+      run-external-runtime:
+        description: Run only the prepared and external runtime suite instead of the core suites.
+        required: true
+        type: boolean
 
 permissions:
   contents: read
 
-concurrency:
-  group: web-e2e-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
 jobs:
-  test:
-    name: Web Full-Stack E2E
+  core-build:
+    name: Prepare Core E2E Web Build
+    if: ${{ !inputs.run-external-runtime }}
     runs-on: depot-ubuntu-24.04-4
-    defaults:
-      run:
-        shell: bash
+    timeout-minutes: 30
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup web dependencies
+        uses: ./.github/actions/setup-web
+
+      - name: Run E2E support unit tests
+        working-directory: ./e2e
+        run: vp run test:unit
+
+      - name: Build production Web app
+        working-directory: ./e2e
+        env:
+          E2E_FORCE_WEB_BUILD: '1'
+        run: vp run e2e:web:build
+
+      - name: Package Web build
+        run: >-
+          tar -cf e2e-web-build.tar -C web
+          .next/BUILD_ID
+          .next/e2e-web-build.sha256
+          .next/standalone
+          .next/static
+
+      - name: Upload Web build
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: core-e2e-web-build
+          path: e2e-web-build.tar
+          if-no-files-found: error
+          overwrite: true
+          retention-days: 7
+
+  chromium-full:
+    name: Chromium Full (${{ matrix.shard }}/3)
+    if: ${{ !inputs.run-external-runtime }}
+    needs: core-build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
+    env:
+      E2E_ADMIN_EMAIL: e2e-admin@example.com
+      E2E_ADMIN_NAME: E2E Admin
+      E2E_ADMIN_PASSWORD: E2eAdmin12345
+      E2E_INIT_PASSWORD: E2eInit12345
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -28,28 +80,182 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install API dependencies
         run: uv sync --project api --dev
 
-      - name: Install Playwright browser
-        working-directory: ./e2e
-        run: vp run e2e:install
+      - name: Download Web build
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: core-e2e-web-build
 
-      - name: Run isolated source-api and built-web Cucumber E2E tests
+      - name: Extract Web build
+        run: tar -xf e2e-web-build.tar -C web
+
+      - name: Install Chromium
+        timeout-minutes: 15
+        working-directory: ./e2e
+        run: vp run e2e:install:ci:chromium
+
+      - name: Run Chromium full shard
+        working-directory: ./e2e
+        run: vp run e2e:full -- --shard ${{ matrix.shard }}/3
+
+      - name: Upload Cucumber report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: cucumber-report-chromium-${{ matrix.shard }}
+          path: e2e/cucumber-report
+          if-no-files-found: ignore
+          overwrite: true
+          retention-days: 7
+
+      - name: Upload E2E logs
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-logs-chromium-${{ matrix.shard }}
+          path: e2e/.logs/*.log
+          if-no-files-found: ignore
+          include-hidden-files: true
+          overwrite: true
+          retention-days: 7
+
+  webkit-smoke:
+    name: WebKit Browser Smoke
+    if: ${{ !inputs.run-external-runtime }}
+    needs: core-build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    env:
+      E2E_ADMIN_EMAIL: e2e-admin@example.com
+      E2E_ADMIN_NAME: E2E Admin
+      E2E_ADMIN_PASSWORD: E2eAdmin12345
+      E2E_BROWSER: webkit
+      E2E_INIT_PASSWORD: E2eInit12345
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup web dependencies
+        uses: ./.github/actions/setup-web
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: api/uv.lock
+
+      - name: Install API dependencies
+        run: uv sync --project api --dev
+
+      - name: Download Web build
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: core-e2e-web-build
+
+      - name: Extract Web build
+        run: tar -xf e2e-web-build.tar -C web
+
+      - name: Install WebKit
+        timeout-minutes: 15
+        working-directory: ./e2e
+        run: vp run e2e:install:ci:webkit
+
+      - name: Run WebKit browser smoke
+        working-directory: ./e2e
+        run: vp run e2e:full -- --tags '@browser-smoke'
+
+      - name: Upload Cucumber report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: cucumber-report-webkit
+          path: e2e/cucumber-report
+          if-no-files-found: ignore
+          overwrite: true
+          retention-days: 7
+
+      - name: Upload E2E logs
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-logs-webkit
+          path: e2e/.logs/*.log
+          if-no-files-found: ignore
+          include-hidden-files: true
+          overwrite: true
+          retention-days: 7
+
+  external-runtime:
+    name: Web Full-Stack E2E
+    if: ${{ inputs.run-external-runtime }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup web dependencies
+        uses: ./.github/actions/setup-web
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: |
+            api/uv.lock
+            dify-agent/uv.lock
+
+      - name: Install API dependencies
+        run: uv sync --project api --dev
+
+      - name: Install Chromium
+        timeout-minutes: 15
+        working-directory: ./e2e
+        run: vp run e2e:install:ci:chromium
+
+      - name: Run prepared and external runtime E2E tests
         working-directory: ./e2e
         env:
           E2E_ADMIN_EMAIL: e2e-admin@example.com
           E2E_ADMIN_NAME: E2E Admin
           E2E_ADMIN_PASSWORD: E2eAdmin12345
-          E2E_FORCE_WEB_BUILD: "1"
+          E2E_AGENT_DECISION_MODEL_NAME: ${{ vars.E2E_AGENT_DECISION_MODEL_NAME || 'gpt-5.5' }}
+          E2E_AGENT_DECISION_MODEL_PROVIDER: ${{ vars.E2E_AGENT_DECISION_MODEL_PROVIDER || 'openai' }}
+          E2E_AGENT_DECISION_MODEL_TYPE: ${{ vars.E2E_AGENT_DECISION_MODEL_TYPE || 'llm' }}
+          E2E_FORCE_WEB_BUILD: '1'
           E2E_INIT_PASSWORD: E2eInit12345
-        run: vp run e2e:full
+          E2E_MARKETPLACE_API_URL: ${{ vars.E2E_MARKETPLACE_API_URL }}
+          E2E_MARKETPLACE_PLUGIN_IDS: ${{ vars.E2E_MARKETPLACE_PLUGIN_IDS }}
+          E2E_MODEL_PROVIDER_CREDENTIALS_JSON: ${{ secrets.E2E_MODEL_PROVIDER_CREDENTIALS_JSON }}
+          E2E_SPEECH_TO_TEXT_MODEL_NAME: ${{ vars.E2E_SPEECH_TO_TEXT_MODEL_NAME || 'gpt-4o-mini-transcribe' }}
+          E2E_SPEECH_TO_TEXT_MODEL_PROVIDER: ${{ vars.E2E_SPEECH_TO_TEXT_MODEL_PROVIDER || 'openai' }}
+          E2E_START_AGENT_BACKEND: ${{ vars.E2E_START_AGENT_BACKEND || '1' }}
+          E2E_STABLE_MODEL_NAME: ${{ vars.E2E_STABLE_MODEL_NAME || 'gpt-5-nano' }}
+          E2E_STABLE_MODEL_PROVIDER: ${{ vars.E2E_STABLE_MODEL_PROVIDER || 'openai' }}
+          E2E_STABLE_MODEL_TYPE: ${{ vars.E2E_STABLE_MODEL_TYPE || 'llm' }}
+        run: |
+          if [[ -z "${E2E_MODEL_PROVIDER_CREDENTIALS_JSON}" ]]; then
+            echo "E2E_MODEL_PROVIDER_CREDENTIALS_JSON is required for external runtime E2E." >&2
+            exit 1
+          fi
+
+          vp run e2e:post-merge
 
       - name: Upload Cucumber report
         if: ${{ !cancelled() }}
@@ -57,6 +263,7 @@ jobs:
         with:
           name: cucumber-report
           path: e2e/cucumber-report
+          overwrite: true
           retention-days: 7
 
       - name: Upload E2E logs
@@ -64,5 +271,17 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: e2e-logs
-          path: e2e/.logs
+          path: e2e/.logs/*.log
+          include-hidden-files: true
+          overwrite: true
+          retention-days: 7
+
+      - name: Upload E2E seed report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-seed-report
+          path: e2e/seed-report
+          if-no-files-found: ignore
+          overwrite: true
           retention-days: 7

.github/workflows/web-tests.yml

@@ -9,16 +9,10 @@ on:
 permissions:
   contents: read
 
-concurrency:
-  group: web-tests-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
 jobs:
   test:
     name: Web Tests (${{ matrix.shardIndex }}/${{ matrix.shardTotal }})
     runs-on: depot-ubuntu-24.04-4
-    env:
-      VITEST_COVERAGE_SCOPE: app-components
     strategy:
       fail-fast: false
       matrix:
@@ -31,7 +25,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -39,7 +33,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Run tests
-        run: vp test run --reporter=blob --reporter=minimal --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --coverage
+        run: vp test run --project unit --reporter=blob --reporter=minimal --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --coverage
 
       - name: Upload blob report
         if: ${{ !cancelled() }}
@@ -50,6 +44,41 @@ jobs:
           include-hidden-files: true
           retention-days: 1
 
+  browser-test:
+    name: Web Browser Tests
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./web
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Install Chromium for Browser Mode
+        timeout-minutes: 15
+        run: vp exec playwright install --with-deps --only-shell chromium
+
+      - name: Run browser tests
+        run: vp test run --project browser --silent=passed-only
+
+      - name: Upload browser failure artifacts
+        if: ${{ failure() && !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: browser-test-failures
+          path: web/.vitest-browser/
+          if-no-files-found: ignore
+          include-hidden-files: true
+          retention-days: 7
+
   merge-reports:
     name: Merge Test Reports
     if: ${{ !cancelled() }}
@@ -64,7 +93,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -92,7 +121,8 @@ jobs:
 
   dify-ui-test:
     name: dify-ui Tests
-    runs-on: depot-ubuntu-24.04-4
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
     env:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     defaults:
@@ -102,7 +132,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -110,11 +140,22 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Install Chromium for Browser Mode
-        run: vp exec playwright install --with-deps chromium
+        timeout-minutes: 15
+        run: vp exec playwright install --with-deps --only-shell chromium
 
       - name: Run dify-ui tests
         run: vp test run --project unit --coverage --silent=passed-only
 
+      - name: Upload dify-ui test failure artifacts
+        if: ${{ failure() && !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dify-ui-test-failures
+          path: packages/dify-ui/.vitest-browser/
+          if-no-files-found: ignore
+          include-hidden-files: true
+          retention-days: 7
+
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' }}
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
@@ -126,7 +167,8 @@ jobs:
 
   dify-ui-storybook-test:
     name: dify-ui Storybook Tests
-    runs-on: depot-ubuntu-24.04-4
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
     defaults:
       run:
         shell: bash
@@ -134,7 +176,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -142,7 +184,18 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Install Chromium for Browser Mode
-        run: vp exec playwright install --with-deps chromium
+        timeout-minutes: 15
+        run: vp exec playwright install --with-deps --only-shell chromium
 
       - name: Run dify-ui Storybook tests
         run: vp run test:storybook
+
+      - name: Upload dify-ui Storybook test failure artifacts
+        if: ${{ failure() && !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dify-ui-storybook-test-failures
+          path: packages/dify-ui/.vitest-browser/
+          if-no-files-found: ignore
+          include-hidden-files: true
+          retention-days: 7

.gitignore

@@ -140,6 +140,9 @@ dmypy.json
 pyrightconfig.json
 !api/pyrightconfig.json
 
+# import-linter
+.import_linter_cache/
+
 # Pyre type checker
 .pyre/
 .idea/'
@@ -214,6 +217,7 @@ sdks/python-client/dify_client.egg-info
 api/.vscode
 # vscode Code History Extension
 .history
+.eslintcache
 
 .idea/
 
@@ -258,7 +262,10 @@ scripts/stress-test/reports/
 # Code Agent Folder
 .qoder/*
 .context/
-.eslintcache
-
 # Vitest local reports
+web/.vitest-browser/
 web/.vitest-reports/
+
+# dify-agent-runtime
+dify-agent-runtime/bin/
+dify-agent-runtime/.integration-state

.nvmrc

@@ -1 +0,0 @@
-22

.vite-hooks/pre-commit

@@ -5,7 +5,6 @@ files=$(git diff --cached --name-only)
 # check if api or web directory is modified
 
 api_modified=false
-web_modified=false
 skip_web_checks=false
 
 git_path() {
@@ -29,10 +28,6 @@ do
             # set api_modified flag to true
             api_modified=true
             ;;
-        web/*)
-            # set web_modified flag to true
-            web_modified=true
-            ;;
     esac
 done
 

.vscode/launch.json.template

@@ -5,7 +5,9 @@
             "name": "Python: API (gevent)",
             "type": "debugpy",
             "request": "launch",
-            "program": "${workspaceFolder}/api/app.py",
+            "module": "gevent.monkey",
+            "args": ["--module", "app"],
+            "gevent": true,
             "jinja": true,
             "justMyCode": true,
             "cwd": "${workspaceFolder}/api",
@@ -33,22 +35,6 @@
             "justMyCode": false,
             "cwd": "${workspaceFolder}/api",
             "python": "${workspaceFolder}/api/.venv/bin/python"
-        },
-        {
-            "name": "Next.js: debug full stack",
-            "type": "node",
-            "request": "launch",
-            "program": "${workspaceFolder}/web/node_modules/next/dist/bin/next",
-            "runtimeArgs": ["--inspect"],
-            "skipFiles": ["<node_internals>/**"],
-            "serverReadyAction": {
-              "action": "debugWithChrome",
-              "killOnServerStop": true,
-              "pattern": "- Local:.+(https?://.+)",
-              "uriFormat": "%s",
-              "webRoot": "${workspaceFolder}/web"
-            },
-            "cwd": "${workspaceFolder}/web"
-          }
+        }
     ]
 }

.vscode/settings.example.json

@@ -1,54 +1,36 @@
 {
-  "cucumber.features": [
-    "e2e/features/**/*.feature",
-  ],
-  "cucumber.glue": [
-    "e2e/features/**/*.ts",
-  ],
+  "cucumber.features": ["e2e/features/**/*.feature"],
+  "cucumber.glue": ["e2e/features/**/*.ts"],
 
   "tailwindCSS.experimental.configFile": "web/app/styles/globals.css",
 
-  // Auto fix
+  "[javascript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[javascriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[typescript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[typescriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[json]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[jsonc]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[markdown]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[mdx]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[yaml]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[toml]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[css]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[scss]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[less]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[html]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[vue]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[svelte]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[graphql]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "[handlebars]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "oxc.disableNestedConfig": true,
+  "oxc.fmt.disableNestedConfig": true,
+
+  "eslint.useFlatConfig": true,
+  "eslint.validate": ["json", "jsonc", "markdown", "yaml", "toml"],
   "editor.codeActionsOnSave": {
-    "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",
-    "javascriptreact",
-    "typescript",
-    "typescriptreact",
-    "vue",
-    "html",
-    "markdown",
-    "json",
-    "jsonc",
-    "yaml",
-    "toml",
-    "xml",
-    "gql",
-    "graphql",
-    "astro",
-    "svelte",
-    "css",
-    "less",
-    "scss",
-    "pcss",
-    "postcss"
-  ]
+    "source.fixAll.oxc": "explicit",
+    "source.fixAll.eslint": "explicit"
+  }
 }

AGENTS.md

@@ -1,46 +1,15 @@
 # AGENTS.md
 
-## Project Overview
+Dify is an open-source platform for building LLM applications, agentic workflows, and RAG pipelines. This monorepo contains the backend API (`api/`), frontend application (`web/`), deployment assets (`docker/`), standalone agent backend (`dify-agent/`), CLI (`cli/`), and end-to-end suite (`e2e/`). Follow the nearest scoped `AGENTS.md` for the files being changed.
 
-Dify is an open-source platform for developing LLM applications with an intuitive interface combining agentic AI workflows, RAG pipelines, agent capabilities, and model management.
+## Repository Gotchas
 
-The codebase is split into:
-
-- **Backend API** (`/api`): Python Flask application organized with Domain-Driven Design
-- **Frontend Web** (`/web`): Next.js application using TypeScript and React
-- **Docker deployment** (`/docker`): Containerized deployment configurations
-- **Dify Agent Backend** (`/dify-agent`): Backend services for managing and executing agent
-
-## Backend Workflow
-
-- Read `api/AGENTS.md` for details
-- Run backend CLI commands through `uv run --project api <command>`.
-- Integration tests are CI-only and are not expected to run in the local environment.
+- Run backend commands through `uv run --project api <command>`.
+- Backend integration tests are CI-only and are not expected to run locally.
+- Keep `docker/.env.example` limited to variables required for a default Docker Compose deployment to start. Put optional and provider-specific settings in the matching `docker/envs/*.env.example` file; `docker/.env` overrides those service-specific env files.
 
 ## Frontend Workflow
 
-- Read `web/AGENTS.md` for details
+- For truncated text disclosure and native `title` decisions, follow [Truncated Text Disclosure].
 
-## Testing & Quality Practices
-
-- Follow TDD: red → green → refactor.
-- Use `pytest` for backend tests with Arrange-Act-Assert structure.
-- Enforce strong typing; avoid `Any` and prefer explicit type annotations.
-- Write self-documenting code; only add comments that explain intent.
-
-## Language Style
-
-- **Python**: Keep type hints on functions and attributes, and implement relevant special methods (e.g., `__repr__`, `__str__`). Prefer `TypedDict` over `dict` or `Mapping` for type safety and better code documentation.
-- **TypeScript**: Use the strict config, rely on ESLint (`pnpm lint:fix` preferred) plus `pnpm type-check`, and avoid `any` types.
-
-## General Practices
-
-- Prefer editing existing files; add new documentation only when requested.
-- Inject dependencies through constructors and preserve clean architecture boundaries.
-- Handle errors with domain-specific exceptions at the correct layer.
-
-## Project Conventions
-
-- Backend architecture adheres to DDD and Clean Architecture principles.
-- Async work runs through Celery with Redis as the broker.
-- Frontend user-facing strings must use `web/i18n/en-US/`; avoid hardcoded text.
+[Truncated Text Disclosure]: web/docs/truncated-text-disclosure.md

CONTRIBUTING.md

@@ -66,7 +66,7 @@ How we prioritize:
 1. Fork the repository
 1. Before you draft a PR, please create an issue to discuss the changes you want to make
 1. Create a new branch for your changes
-1. Please add tests for your changes accordingly
+1. Add or update tests when the change affects observable behavior or carries meaningful regression risk
 1. Ensure your code passes the existing tests
 1. Please link the issue in the PR description, `fixes #<issue_number>`
 1. Get merged!
@@ -77,7 +77,7 @@ How we prioritize:
 
 For setting up the frontend service, please refer to our comprehensive [guide](https://github.com/langgenius/dify/blob/main/web/README.md) in the `web/README.md` file. This document provides detailed instructions to help you set up the frontend environment properly.
 
-**Testing**: All React components must have comprehensive test coverage. See [web/docs/test.md](https://github.com/langgenius/dify/blob/main/web/docs/test.md) for the canonical frontend testing guidelines and follow every requirement described there.
+**Testing**: Add focused tests when a change affects observable behavior or carries meaningful regression risk. See [web/docs/test.md](https://github.com/langgenius/dify/blob/main/web/docs/test.md) for the canonical frontend testing guidelines.
 
 #### Backend
 

Makefile

@@ -2,6 +2,7 @@
 DOCKER_REGISTRY=langgenius
 WEB_IMAGE=$(DOCKER_REGISTRY)/dify-web
 API_IMAGE=$(DOCKER_REGISTRY)/dify-api
+SANDBOX_RUNTIME_IMAGE=$(DOCKER_REGISTRY)/dify-agent-local-sandbox
 VERSION=latest
 DOCKER_DIR=docker
 DOCKER_MIDDLEWARE_ENV=$(DOCKER_DIR)/middleware.env
@@ -106,6 +107,7 @@ test:
 		echo "Target: $(TARGET_TESTS)"; \
 		uv run --project api --dev pytest $(TARGET_TESTS); \
 	else \
+		set -e; \
 		echo "Running backend unit tests"; \
 		uv run --project api --dev pytest -p no:benchmark --timeout "$${PYTEST_TIMEOUT:-20}" -n auto \
 			api/tests/unit_tests \
@@ -123,6 +125,7 @@ test-all:
 		echo "Target: $(TARGET_TESTS)"; \
 		uv run --project api --dev pytest $(TARGET_TESTS); \
 	else \
+		set -e; \
 		echo "Running backend unit tests"; \
 		uv run --project api --dev pytest -p no:benchmark --timeout "$${PYTEST_TIMEOUT:-20}" -n auto \
 			api/tests/unit_tests \
@@ -160,6 +163,13 @@ build-api:
 	docker build -t $(API_IMAGE):$(VERSION) -f api/Dockerfile .
 	@echo "API Docker image built successfully: $(API_IMAGE):$(VERSION)"
 
+build-sandbox-runtime:
+	@echo "Building sandbox runtime Docker image: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)..."
+	docker build -t $(SANDBOX_RUNTIME_IMAGE):$(VERSION) \
+		-f dify-agent-runtime/docker/Dockerfile \
+		dify-agent-runtime
+	@echo "Sandbox runtime Docker image built successfully: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)"
+
 # Push Docker images
 push-web:
 	@echo "Pushing web Docker image: $(WEB_IMAGE):$(VERSION)..."
@@ -171,14 +181,20 @@ push-api:
 	docker push $(API_IMAGE):$(VERSION)
 	@echo "API Docker image pushed successfully: $(API_IMAGE):$(VERSION)"
 
+push-sandbox-runtime:
+	@echo "Pushing sandbox runtime Docker image: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)..."
+	docker push $(SANDBOX_RUNTIME_IMAGE):$(VERSION)
+	@echo "Sandbox runtime Docker image pushed successfully: $(SANDBOX_RUNTIME_IMAGE):$(VERSION)"
+
 # Build all images
-build-all: build-web build-api
+build-all: build-web build-api build-sandbox-runtime
 
 # Push all images
-push-all: push-web push-api
+push-all: push-web push-api push-sandbox-runtime
 
 build-push-api: build-api push-api
 build-push-web: build-web push-web
+build-push-sandbox-runtime: build-sandbox-runtime push-sandbox-runtime
 
 # Build and push all images
 build-push-all: build-all push-all
@@ -206,9 +222,10 @@ help:
 	@echo "Docker Build Targets:"
 	@echo "  make build-web      - Build web Docker image"
 	@echo "  make build-api      - Build API Docker image"
+	@echo "  make build-sandbox-runtime - Build sandbox runtime Docker image"
 	@echo "  make build-all      - Build all Docker images"
 	@echo "  make push-all       - Push all Docker images"
 	@echo "  make build-push-all - Build and push all Docker images"
 
 # Phony targets
-.PHONY: build-web build-api push-web push-api build-all push-all build-push-all dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint api-contract-lint type-check test test-all
+.PHONY: build-web build-api build-sandbox-runtime push-web push-api push-sandbox-runtime build-all push-all build-push-all build-push-sandbox-runtime dev-setup prepare-docker prepare-web prepare-api dev-clean help format check lint api-contract-lint type-check test test-all

README.md

@@ -15,7 +15,7 @@
     <a href="https://discord.gg/FngNHpbcY7" target="_blank">
         <img src="https://img.shields.io/discord/1082486657678311454?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb"
             alt="chat on Discord"></a>
-    <a href="https://reddit.com/r/difyai" target="_blank">  
+    <a href="https://reddit.com/r/difyai" target="_blank">
         <img src="https://img.shields.io/reddit/subreddit-subscribers/difyai?style=plastic&logo=reddit&label=r%2Fdifyai&labelColor=white"
             alt="join Reddit"></a>
     <a href="https://twitter.com/intent/follow?screen_name=dify_ai" target="_blank">
@@ -71,7 +71,7 @@ Dify is an open-source LLM app development platform. Its intuitive interface com
 
 <br/>
 
-The easiest way to start the Dify server is through [Docker Compose](docker/docker-compose.yaml). Before running Dify with the following commands, make sure that [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed on your machine:
+The easiest way to start the Dify server is through [Docker Compose](docker/docker-compose.yaml). Before running Dify with the following commands, make sure that [Docker](https://docs.docker.com/get-docker/) and Docker Compose v2.24.0 or later are installed on your machine:
 
 ```bash
 cd dify
@@ -125,94 +125,50 @@ All of Dify's offerings come with corresponding APIs, so you could effortlessly
 - **Dify for enterprise / organizations<br/>**
   We provide additional enterprise-centric features. [Send us an email](mailto:business@dify.ai?subject=%5BGitHub%5DBusiness%20License%20Inquiry) to discuss your enterprise needs. <br/>
 
-  > For startups and small businesses using AWS, check out [Dify Premium on AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-t22mebxzwjhu6) and deploy it to your own AWS VPC with one click. It's an affordable AMI offering with the option to create apps with custom logo and branding.
-
 ## Staying ahead
 
 Star Dify on GitHub and be instantly notified of new releases.
 
-![star-us](https://github.com/langgenius/dify/assets/13230914/b823edc1-6388-4e25-ad45-2f6b187adbb4)
+<img width="1344" height="720" alt="star" src="https://github.com/user-attachments/assets/dcd086d1-af0f-471b-ae52-1ad2fa040595" />
 
 ## Advanced Setup
 
-### Custom configurations
-
-If you need to customize the configuration, edit `docker/.env`. The essential startup defaults live in [`docker/.env.example`](docker/.env.example), and optional advanced variables are split under `docker/envs/` by theme. After making any changes, re-run `docker compose up -d` from the `docker` directory. You can find the full list of available environment variables [here](https://docs.dify.ai/getting-started/install-self-hosted/environments).
-
-### Metrics Monitoring with Grafana
-
-Import the dashboard to Grafana, using Dify's PostgreSQL database as data source, to monitor metrics in granularity of apps, tenants, messages, and more.
-
-- [Grafana Dashboard by @bowenliang123](https://github.com/bowenliang123/dify-grafana-dashboard)
-
-### Deployment with Kubernetes
-
-If you'd like to configure a highly available setup, there are community-contributed [Helm Charts](https://helm.sh/) and YAML files which allow Dify to be deployed on Kubernetes.
-
-- [Helm Chart by @LeoQuote](https://github.com/douban/charts/tree/master/charts/dify)
-- [Helm Chart by @BorisPolonsky](https://github.com/BorisPolonsky/dify-helm)
-- [Helm Chart by @magicsong](https://github.com/magicsong/ai-charts)
-- [YAML file by @Winson-030](https://github.com/Winson-030/dify-kubernetes)
-- [YAML file by @wyy-holding](https://github.com/wyy-holding/dify-k8s)
-- [🚀 NEW! YAML files (Supports Dify v1.6.0) by @Zhoneym](https://github.com/Zhoneym/DifyAI-Kubernetes)
-
-#### Using Terraform for Deployment
-
-Deploy Dify to Cloud Platform with a single click using [terraform](https://www.terraform.io/)
-
-##### Azure Global
-
-- [Azure Terraform by @nikawang](https://github.com/nikawang/dify-azure-terraform)
-
-##### Google Cloud
-
-- [Google Cloud Terraform by @sotazum](https://github.com/DeNA/dify-google-cloud-terraform)
-
-#### Using AWS CDK for Deployment
-
-Deploy Dify to AWS with [CDK](https://aws.amazon.com/cdk/)
-
-##### AWS
-
-- [AWS CDK by @KevinZhao (EKS based)](https://github.com/aws-samples/solution-for-deploying-dify-on-aws)
-- [AWS CDK by @tmokmss (ECS based)](https://github.com/aws-samples/dify-self-hosted-on-aws)
-
-#### Using Alibaba Cloud Computing Nest
-
-Quickly deploy Dify to Alibaba cloud with [Alibaba Cloud Computing Nest](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceName=Dify%E7%A4%BE%E5%8C%BA%E7%89%88)
-
-#### Using Alibaba Cloud Data Management
-
-One-Click deploy Dify to Alibaba Cloud with [Alibaba Cloud Data Management](https://www.alibabacloud.com/help/en/dms/dify-in-invitational-preview/)
-
-#### Deploy to AKS with Azure Devops Pipeline
-
-One-Click deploy Dify to AKS with [Azure Devops Pipeline Helm Chart by @LeoZhang](https://github.com/Ruiruiz30/Dify-helm-chart-AKS)
+For custom configuration, observability, and deployment options, see [Advanced Setup](docs/ADVANCED_SETUP.md).
 
 ## Contributing
 
-For those who'd like to contribute code, see our [Contribution Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md).
-At the same time, please consider supporting Dify by sharing it on social media and at events and conferences.
+Dify welcomes contributions of all kinds:
 
-> We are looking for contributors to help translate Dify into languages other than Mandarin or English. If you are interested in helping, please see the [i18n README](https://github.com/langgenius/dify/blob/main/web/i18n-config/README.md) for more information, and leave us a comment in the `global-users` channel of our [Discord Community Server](https://discord.gg/8Tpq4AcN9c).
+- **Code**: Read the [Contribution Guide](CONTRIBUTING.md), then browse [good first issues](https://github.com/langgenius/dify/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).
+- **Ideas and feedback**: Start or join a [GitHub Discussion](https://github.com/langgenius/dify/discussions).
+- **Translations**: Follow the [internationalization guide](web/i18n-config/README.md) to add or update a locale.
+- **Community**: Share the apps you build, help other users, and spread the word about Dify.
+
+### Contributors
+
+<a href="https://github.com/langgenius/dify/graphs/contributors">
+  <img alt="Dify contributors" src="https://contrib.rocks/image?repo=langgenius/dify" />
+</a>
 
 ## Community & contact
 
-- [GitHub Discussion](https://github.com/langgenius/dify/discussions). Best for: sharing feedback and asking questions.
-- [GitHub Issues](https://github.com/langgenius/dify/issues). Best for: bugs you encounter using Dify.AI, and feature proposals. See our [Contribution Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md).
-- [Discord](https://discord.gg/FngNHpbcY7). Best for: sharing your applications and hanging out with the community.
-- [X(Twitter)](https://twitter.com/dify_ai). Best for: sharing your applications and hanging out with the community.
+Choose the channel that best fits your question:
 
-**Contributors**
+- [GitHub Discussions](https://github.com/langgenius/dify/discussions): Get help, share feedback, and propose ideas.
+- [GitHub Issues](https://github.com/langgenius/dify/issues): Report reproducible bugs and track engineering work. Read the [Contribution Guide](CONTRIBUTING.md) before opening one.
+- [Discord](https://discord.gg/FngNHpbcY7): Chat in real time, share your apps, and connect with other Dify users.
+- [X](https://x.com/dify_ai): Follow Dify for release news and project updates.
 
-<a href="https://github.com/langgenius/dify/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=langgenius/dify" />
+## Star History
+
+<a href="https://star-history.dera.page/#langgenius/dify&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=langgenius/dify&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=langgenius/dify&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=langgenius/dify&type=date&legend=top-left" />
+ </picture>
 </a>
 
-## Star history
-
-[![Star History Chart](https://api.star-history.com/svg?repos=langgenius/dify&type=Date)](https://star-history.com/#langgenius/dify&Date)
-
 ## Security disclosure
 
 To protect your privacy, please avoid posting security issues on GitHub. Instead, report issues to security@dify.ai, and our team will respond with detailed answer.

api/.env.example

@@ -39,6 +39,9 @@ ENABLE_COLLABORATION_MODE=true
 # Learn app feature toggle
 ENABLE_LEARN_APP=true
 
+# Show the license expiry countdown badge in the console (enterprise only)
+ENABLE_LICENSE_EXPIRY_NOTICE=true
+
 # Access token expiration time in minutes
 ACCESS_TOKEN_EXPIRE_MINUTES=60
 
@@ -86,14 +89,20 @@ REDIS_RETRY_BACKOFF_CAP=10.0
 REDIS_SOCKET_TIMEOUT=5.0
 REDIS_SOCKET_CONNECT_TIMEOUT=5.0
 REDIS_HEALTH_CHECK_INTERVAL=30
+REDIS_KEEPALIVE_IDLE=30
+REDIS_KEEPALIVE_INTERVAL=10
+REDIS_KEEPALIVE_COUNT=10
+REDIS_KEEPALIVE=true
 
 # celery configuration
 CELERY_BROKER_URL=redis://:difyai123456@localhost:${REDIS_PORT}/1
 CELERY_BACKEND=redis
 
-# Ops trace retry configuration
-OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES=60
+# Ops trace configuration
+OPS_TRACE_UNIFIED_ENABLED=false
+OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES=780
 OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS=5
+OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS=3900
 
 # Database configuration
 DB_TYPE=postgresql
@@ -113,6 +122,19 @@ SQLALCHEMY_POOL_RESET_ON_RETURN=rollback
 # storage type: opendal, s3, aliyun-oss, azure-blob, baidu-obs, google-storage, huawei-obs, oci-storage, tencent-cos, volcengine-tos, supabase
 STORAGE_TYPE=opendal
 
+# Key provider configuration, used to encrypt/decrypt tenant credentials (LLM/tool provider secrets)
+# key provider type: local, azure-keyvault
+KEY_PROVIDER_TYPE=local
+
+# Azure Key Vault configuration, required when KEY_PROVIDER_TYPE=azure-keyvault
+# authentication uses DefaultAzureCredential (managed identity, environment variables, or Azure CLI login)
+AZURE_KEYVAULT_VAULT_URL=https://<your-vault-name>.vault.azure.net
+AZURE_KEYVAULT_KEY_SIZE=2048
+# optional: auto-rotate each tenant's key every N days. Leave empty to manage rotation manually.
+# rotation is safe because old key versions are never given an expiry and stay usable forever --
+# do NOT set a rotation policy on this key in the Azure portal that expires old versions.
+AZURE_KEYVAULT_ROTATION_INTERVAL_DAYS=
+
 # Apache OpenDAL storage configuration, refer to https://github.com/apache/opendal
 OPENDAL_SCHEME=fs
 OPENDAL_FS_ROOT=storage
@@ -200,6 +222,7 @@ SUPABASE_URL=your-server-url
 # CORS configuration
 WEB_API_CORS_ALLOW_ORIGINS=http://localhost:3000,*
 CONSOLE_CORS_ALLOW_ORIGINS=http://localhost:3000,*
+WEBSOCKET_MAX_HTTP_BUFFER_SIZE=10485760
 # When the frontend and backend run on different subdomains, set COOKIE_DOMAIN to the site’s top-level domain (e.g., `example.com`). Leading dots are optional.
 COOKIE_DOMAIN=
 
@@ -322,6 +345,7 @@ TIDB_VECTOR_PORT=4000
 TIDB_VECTOR_USER=xxx.root
 TIDB_VECTOR_PASSWORD=xxxxxx
 TIDB_VECTOR_DATABASE=dify
+TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH=false
 
 # Tidb on qdrant configuration
 TIDB_ON_QDRANT_URL=http://127.0.0.1
@@ -329,6 +353,7 @@ TIDB_ON_QDRANT_API_KEY=dify
 TIDB_ON_QDRANT_CLIENT_TIMEOUT=20
 TIDB_ON_QDRANT_GRPC_ENABLED=false
 TIDB_ON_QDRANT_GRPC_PORT=6334
+TIDB_ON_QDRANT_ESTIMATED_STORAGE_LIMITS_MB=sandbox:60,professional:6400,team:25600
 TIDB_PUBLIC_KEY=dify
 TIDB_PRIVATE_KEY=dify
 TIDB_API_URL=http://127.0.0.1
@@ -428,10 +453,12 @@ OPENGAUSS_MAX_CONNECTION=5
 
 # Upload configuration
 UPLOAD_FILE_SIZE_LIMIT=15
+KNOWLEDGE_UPLOAD_FILE_SIZE_LIMIT_FOR_PAID_PLAN=15
 UPLOAD_FILE_BATCH_LIMIT=5
 UPLOAD_IMAGE_FILE_SIZE_LIMIT=10
 UPLOAD_VIDEO_FILE_SIZE_LIMIT=100
 UPLOAD_AUDIO_FILE_SIZE_LIMIT=50
+UPLOAD_SKILL_FILE_SIZE_LIMIT=50
 
 # Comma-separated list of file extensions blocked from upload for security reasons.
 # Extensions should be lowercase without dots (e.g., exe,bat,sh,dll).
@@ -464,6 +491,13 @@ SENDGRID_API_KEY=
 # Sentry configuration
 SENTRY_DSN=
 
+# Cloudflare Turnstile server-side verification for Dify Cloud sign-in
+TURNSTILE_SECRET_KEY=
+# Comma-separated parent or exact hostnames, for example: dify.ai,staging.dify.dev
+TURNSTILE_ALLOWED_HOSTNAMES=
+# Enable only after the compatible web client has been fully deployed.
+TURNSTILE_EMAIL_CODE_VERIFY_REQUIRED=false
+
 # DEBUG
 DEBUG=false
 ENABLE_REQUEST_LOGGING=False
@@ -554,17 +588,19 @@ INDEXING_MAX_SEGMENTATION_TOKENS_LENGTH=4000
 
 # Workflow runtime configuration
 WORKFLOW_MAX_EXECUTION_STEPS=500
-WORKFLOW_MAX_EXECUTION_TIME=1200
+WORKFLOW_MAX_EXECUTION_TIME=3600
 WORKFLOW_CALL_MAX_DEPTH=5
 MAX_VARIABLE_SIZE=204800
+# Maximum concurrent node-builder LLM calls per workflow generation request
+WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS=6
 
 # GraphEngine Worker Pool Configuration
 # Minimum number of workers per GraphEngine instance (default: 1)
 GRAPH_ENGINE_MIN_WORKERS=3
 # Maximum number of workers per GraphEngine instance (default: 10)
 GRAPH_ENGINE_MAX_WORKERS=10
-# Queue depth threshold that triggers worker scale up (default: 3)
-GRAPH_ENGINE_SCALE_UP_THRESHOLD=3
+# Pending task threshold that triggers worker scale up (default: 0)
+GRAPH_ENGINE_SCALE_UP_THRESHOLD=0
 # Seconds of idle time before scaling down workers (default: 5.0)
 GRAPH_ENGINE_SCALE_DOWN_IDLE_TIME=5.0
 
@@ -597,7 +633,7 @@ WORKFLOW_LOG_CLEANUP_BATCH_SIZE=100
 WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS=
 
 # App configuration
-APP_MAX_EXECUTION_TIME=1200
+APP_MAX_EXECUTION_TIME=3600
 APP_DEFAULT_ACTIVE_REQUESTS=0
 APP_MAX_ACTIVE_REQUESTS=0
 
@@ -660,9 +696,33 @@ PLUGIN_REMOTE_INSTALL_PORT=5003
 PLUGIN_REMOTE_INSTALL_HOST=localhost
 PLUGIN_MAX_PACKAGE_SIZE=15728640
 PLUGIN_MODEL_SCHEMA_CACHE_TTL=3600
+PLUGIN_MODEL_PROVIDERS_CACHE_ENABLED=true
 PLUGIN_MODEL_PROVIDERS_CACHE_TTL=86400
+# Comma-separated marketplace plugin IDs whose latest versions are installed for newly registered users.
+# Example: langgenius/openai,langgenius/gemini
+NEW_USER_DEFAULT_PLUGIN_IDS=
+# Comma-separated model_type:provider:model entries assigned after default plugins finish installing.
+# Example: llm:langgenius/openai/openai:gpt-4o-mini,text-embedding:langgenius/openai/openai:text-embedding-3-small
+NEW_USER_DEFAULT_MODELS=
 INNER_API_KEY_FOR_PLUGIN=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y1
 
+# Dify Agent backend
+AGENT_BACKEND_BASE_URL=http://localhost:5050
+# Bearer token sent to the Agent backend control-plane API. Must match DIFY_AGENT_API_TOKEN on the server side.
+AGENT_BACKEND_API_TOKEN=dify-agent-run-token-for-dev-only
+AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS=30
+AGENT_BACKEND_STREAM_MAX_RECONNECTS=3
+# Client deadline for converting a Binding file to a ToolFile through the Agent backend.
+AGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDS=240
+
+# KnowledgeFS (Dataset 2.0)
+KNOWLEDGE_FS_ENABLED=false
+KNOWLEDGE_FS_BASE_URL=
+# Shared with KnowledgeFS; use at least 32 random characters.
+KNOWLEDGE_FS_JWT_SECRET=
+KNOWLEDGE_FS_SSE_READ_TIMEOUT_SECONDS=300
+KNOWLEDGE_FS_TIMEOUT_SECONDS=10
+
 # Marketplace configuration
 MARKETPLACE_ENABLED=true
 MARKETPLACE_API_URL=https://marketplace.dify.ai
@@ -680,6 +740,8 @@ RESET_PASSWORD_TOKEN_EXPIRY_MINUTES=5
 EMAIL_REGISTER_TOKEN_EXPIRY_MINUTES=5
 CHANGE_EMAIL_TOKEN_EXPIRY_MINUTES=5
 OWNER_TRANSFER_TOKEN_EXPIRY_MINUTES=5
+EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES=5
+EMAIL_CODE_LOGIN_MAX_ATTEMPTS=5
 
 CREATE_TIDB_SERVICE_JOB_ENABLED=false
 
@@ -703,7 +765,6 @@ OTEL_MAX_EXPORT_BATCH_SIZE=512
 OTEL_METRIC_EXPORT_INTERVAL=60000
 OTEL_BATCH_EXPORT_TIMEOUT=10000
 OTEL_METRIC_EXPORT_TIMEOUT=30000
-
 # Prevent Clickjacking
 ALLOW_EMBED=false
 
@@ -777,6 +838,12 @@ ENABLE_HUMAN_INPUT_TIMEOUT_TASK=true
 # Human input timeout check interval in minutes
 HUMAN_INPUT_TIMEOUT_TASK_INTERVAL=1
 
+# Whether to recover soft-deleted conversation cleanup jobs periodically
+ENABLE_CONVERSATION_CLEANUP_TASK=true
+# Recovery interval in minutes and maximum conversations dispatched per sweep
+CONVERSATION_CLEANUP_TASK_INTERVAL=5
+CONVERSATION_CLEANUP_BATCH_SIZE=100
+
 # 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.
@@ -784,3 +851,6 @@ HUMAN_INPUT_TIMEOUT_TASK_INTERVAL=1
 DIFY_ENV_NACOS_REQUEST_TIMEOUT=10.0
 # Connect timeout for Nacos requests (default: 3.0)
 DIFY_ENV_NACOS_CONNECT_TIMEOUT=3.0
+
+# skill entry
+ENABLE_SKILL=true

api/.importlinter

@@ -8,7 +8,502 @@ root_packages =
     extensions
     factories
     libs
+    machinery
     models
+    repositories
     tasks
     services
 include_external_packages = True
+
+[importlinter:contract:backend-layers]
+name = Backend modules follow the transport, application, domain, and shared-library layers
+type = layers
+layers =
+    controllers
+    services
+    core
+    libs
+# Migration baseline: keep every exception exact. The default unmatched-import
+# error makes this list shrink whenever a legacy dependency is removed.
+unmatched_ignore_imports_alerting = error
+ignore_imports =
+    core.app.app_config.easy_ui_based_app.dataset.manager -> services.dataset_service
+    core.app.apps.advanced_chat.app_generator -> controllers.console.app.workflow
+    core.app.apps.advanced_chat.app_generator -> services.conversation_service
+    core.app.apps.advanced_chat.app_generator -> services.errors.conversation
+    core.app.apps.advanced_chat.app_generator -> services.workflow_draft_variable_service
+    core.app.apps.advanced_chat.app_runner -> services.conversation_variable_updater
+    core.app.apps.agent_app.app_generator -> services.agent.composer_service
+    core.app.apps.agent_app.app_generator -> services.agent.workspace_service
+    core.app.apps.agent_app.app_generator -> services.conversation_service
+    core.app.apps.agent_app.runtime_request_builder -> services.agent.prompt_mentions
+    core.app.apps.agent_app.session_store -> services.agent.workspace_service
+    core.app.apps.agent_chat.app_generator -> services.conversation_service
+    core.app.apps.base_app_generator -> services.workflow_draft_variable_service
+    core.app.apps.chat.app_generator -> services.conversation_service
+    core.app.apps.common.workflow_response_converter -> services.variable_truncator
+    core.app.apps.completion.app_generator -> services.errors.app
+    core.app.apps.completion.app_generator -> services.errors.message
+    core.app.apps.message_based_app_generator -> services.errors.app_model_config
+    core.app.apps.message_based_app_generator -> services.errors.conversation
+    core.app.apps.message_based_app_generator -> services.errors.message
+    core.app.apps.pipeline.pipeline_generator -> services
+    core.app.apps.pipeline.pipeline_generator -> services.dataset_service
+    core.app.apps.pipeline.pipeline_generator -> services.datasource_provider_service
+    core.app.apps.pipeline.pipeline_generator -> services.feature_service
+    core.app.apps.pipeline.pipeline_generator -> services.workflow_draft_variable_service
+    core.app.apps.pipeline.pipeline_runner -> services.dataset_ref_service
+    core.app.apps.workflow.app_generator -> controllers.console.app.workflow
+    core.app.apps.workflow.app_generator -> services.snippet_generate_service
+    core.app.apps.workflow.app_generator -> services.workflow_draft_variable_service
+    core.app.apps.workflow_app_runner -> tasks.mail_human_input_delivery_task
+    core.app.features.annotation_reply.annotation_reply -> services.annotation_service
+    core.app.features.annotation_reply.annotation_reply -> services.dataset_service
+    core.app.llm.quota -> services.credit_pool_service
+    core.app.task_pipeline.message_cycle_manager -> services.account_service
+    core.app.task_pipeline.message_cycle_manager -> services.annotation_service
+    core.app.workflow.layers.persistence -> services.workflow.inspector_events
+    core.datasource.datasource_manager -> services.datasource_provider_service
+    core.helper.credential_utils -> services.enterprise.plugin_manager_service
+    core.helper.credential_utils -> services.system_feature_service
+    core.indexing_runner -> services.vector_space_admission_service
+    core.mcp.auth_client -> services
+    core.provider_manager -> services.credential_permission_service
+    core.provider_manager -> services.credit_pool_service
+    core.provider_manager -> services.feature_service
+    core.rag.datasource.retrieval_service -> services.external_knowledge_service
+    core.rag.index_processor.index_processor -> services.vector_space_admission_service
+    core.rag.index_processor.index_processor_base -> services.file_service
+    core.rag.index_processor.processor.paragraph_index_processor -> services.account_service
+    core.rag.index_processor.processor.paragraph_index_processor -> services.summary_index_service
+    core.rag.index_processor.processor.parent_child_index_processor -> services.account_service
+    core.rag.index_processor.processor.parent_child_index_processor -> services.summary_index_service
+    core.rag.index_processor.processor.qa_index_processor -> services.summary_index_service
+    core.rag.retrieval.dataset_retrieval -> services.external_knowledge_service
+    core.rag.retrieval.dataset_retrieval -> services.feature_service
+    core.rag.summary_index.summary_index -> services.summary_index_service
+    core.rag.summary_index.summary_index -> tasks.generate_summary_index_task
+    core.repositories.sqlalchemy_workflow_node_execution_repository -> services.file_service
+    core.repositories.sqlalchemy_workflow_node_execution_repository -> services.variable_truncator
+    core.tools.tool_manager -> services
+    core.workflow.node_runtime -> services
+    core.workflow.nodes.agent.message_transformer -> services
+    core.workflow.nodes.agent_v2.agent_node -> services.agent.prompt_mentions
+    core.workflow.nodes.agent_v2.agent_node -> services.agent.workspace_service
+    core.workflow.nodes.agent_v2.dify_tools_builder -> services
+    core.workflow.nodes.agent_v2.runtime_feature_manifest -> services.agent.knowledge_datasets
+    core.workflow.nodes.agent_v2.runtime_request_builder -> services.agent.prompt_mentions
+    core.workflow.nodes.agent_v2.runtime_request_builder -> services.skill_management_service
+    core.workflow.nodes.agent_v2.session_store -> services.agent.workspace_service
+    core.workflow.nodes.agent_v2.validators -> services.agent.knowledge_datasets
+    core.workflow.nodes.agent_v2.workspace_retirement_layer -> tasks.collect_agent_resources_task
+    libs.device_flow_security -> controllers.openapi._models
+    libs.device_flow_security -> services.entities.feature_entities
+    libs.device_flow_security -> services.system_feature_service
+    libs.email_i18n -> services.entities.feature_entities
+    libs.email_i18n -> services.system_feature_service
+    libs.external_api -> core
+    libs.external_api -> core.errors.error
+    libs.external_api -> extensions.ext_logging
+    libs.flask_utils -> models
+    libs.helper -> core.app.features.rate_limiting.rate_limit
+    libs.helper -> models
+    libs.helper -> models.model
+    libs.json_in_md_parser -> core.llm_generator.output_parser.errors
+    libs.login -> extensions.ext_login
+    libs.login -> models
+    libs.login -> models.model
+    libs.oauth -> core.helper.http_client_pooling
+    libs.oauth_bearer -> models
+    libs.rsa -> extensions.ext_storage
+    libs.workspace_permission -> services.enterprise.enterprise_service
+    services.account_service -> controllers
+    services.account_service -> controllers.console.error
+    services.app_generate_service -> controllers.console.app.workflow
+
+[importlinter:contract:no-direct-rsa-imports]
+# Note: `libs` itself is deliberately excluded from source_modules -- import-linter's
+# `forbidden` contract cannot check a package against its own descendant (libs.rsa lives
+# inside libs). Sibling modules under libs/ importing libs.rsa are not covered by this
+# contract; the realistic risk this guards against is application/service code reaching
+# past the key provider abstraction, which is fully covered below.
+name = Only the key provider abstraction may import libs.rsa directly
+type = forbidden
+source_modules =
+    core
+    constants
+    context
+    configs
+    controllers
+    extensions
+    factories
+    models
+    tasks
+    services
+forbidden_modules =
+    libs.rsa
+allow_indirect_imports = True
+
+[importlinter:contract:machinery-framework-boundary]
+name = API machinery is framework neutral
+type = forbidden
+source_modules =
+    machinery
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:workspace-query-service-boundary]
+name = Workspace query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.workspace_query_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:init-validation-service-boundary]
+name = Initialization validation application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.init_validation_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:explore-banner-query-service-boundary]
+name = Explore banner query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.explore_banner_query_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:account-application-boundary]
+name = Account application services and contracts are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.account_avatar_service
+    services.account_change_email_ports
+    services.account_change_email_service
+    services.account_email_registration_service
+    services.account_deletion_service
+    services.account_deletion_feedback_service
+    services.account_education_service
+    services.account_errors
+    services.account_initialization_service
+    services.account_integration_service
+    services.account_password_service
+    services.account_ports
+    services.account_profile_service
+    services.entities.account_entities
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:app-definition-query-service-boundary]
+name = App definition query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_definition_query_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:app-site-service-boundary]
+name = App site application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_site_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:webapp-access-query-service-boundary]
+name = Web app access query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.webapp_access_query_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.enterprise
+    services.feature_service
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:web-app-runtime-query-service-boundary]
+name = Web app runtime query application service does not directly depend on configuration, feature implementation, transport, or ORM modules
+type = forbidden
+source_modules =
+    services.web_app_runtime_query_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.feature_service
+    services.feature_service_gateway
+    sqlalchemy
+    werkzeug
+allow_indirect_imports = True
+
+[importlinter:contract:feature-query-service-boundary]
+name = Feature query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.feature_query_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:data-source-oauth-service-boundary]
+name = Data source OAuth application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.data_source_oauth_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    httpx
+    libs
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:oauth-server-application-service-boundary]
+name = OAuth server application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.oauth_server_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    httpx
+    libs
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:workspace-member-query-service-boundary]
+name = Workspace member query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.workspace_member_query_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.enterprise
+    services.workspace_member_role_resolver
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:setup-service-boundary]
+name = Setup application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.setup_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:schema-definition-service-boundary]
+name = Schema definition application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.schema_definition_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:inner-mail-service-boundary]
+name = Inner mail application service is framework and implementation neutral
+type = forbidden
+source_modules =
+    services.inner_mail_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    tasks
+    werkzeug
+
+[importlinter:contract:web-passport-service-boundary]
+name = Web passport application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.web_passport_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:account-activation-service-boundary]
+name = Account activation application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.account_activation_service
+    services.entities.account_activation_entities
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:tag-application-service-boundary]
+name = Tag application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.tag_application_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:recommended-app-query-service-boundary]
+name = Recommended app query application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.recommended_app_query_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.feature_service
+    services.recommended_app_catalog_gateway
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:recommended-app-catalog-gateway-boundary]
+name = Recommended app catalog gateway does not depend on Flask
+type = forbidden
+source_modules =
+    services.recommended_app_catalog_gateway
+forbidden_modules =
+    flask
+
+[importlinter:contract:billing-application-boundary]
+name = Billing application services and ports are framework and infrastructure neutral
+type = forbidden
+source_modules =
+    services.billing_portal_service
+    services.compliance_download_service
+    services.partner_tenant_binding_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.billing_service
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:workflow-run-archive-application-boundary]
+name = Workflow run archive application service and task domain are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.retention.workflow_run.archive_download_task
+    services.retention.workflow_run.archive_log_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    tasks
+    werkzeug

api/.ruff.toml

@@ -84,7 +84,6 @@ ignore = [
     "SIM105",  # suppressible-exception
     "SIM108",  # if-else-block-instead-of-if-exp
     "SIM113",  # enumerate-for-loop
-    "SIM117",  # multiple-with-statements
     "SIM210",  # if-expr-with-true-false
     "TID252",  # allow relative imports from parent modules
 ]