fix(knowledge): respect TiDB collection deletion constraints

Co-authored-by: Asuka Minato <i@asukaminato.eu.org>

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

@@ -41,6 +41,7 @@
     # core/policy/publish_policy.py
     from controllers.console.app import request_context
 
+
     def can_publish() -> bool:
         return request_context.current_user.is_admin
     ```
@@ -50,6 +51,7 @@
     def can_publish(role: str) -> bool:
         return role == "admin"
 
+
     # service layer adapts web/user context to domain input
     allowed = can_publish(role=current_user.role)
     ```
@@ -66,6 +68,7 @@
     # api/libs/conversation_filter.py
     from services.conversation_service import ConversationService
 
+
     def should_archive_conversation(conversation, tenant_id: str) -> bool:
         # Domain policy and service dependency are leaking into libs.
         service = ConversationService()
@@ -79,9 +82,11 @@
     def older_than_days(idle_days: int, threshold_days: int) -> bool:
         return idle_days > threshold_days
 
+
     # services/conversation_service.py (business logic stays in service/core)
     from libs.datetime_utils import older_than_days
 
+
     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

@@ -50,6 +50,7 @@
     ```python
     from sqlalchemy.orm import Mapped
 
+
     class Dataset(TypeBase):
         __tablename__ = "datasets"
         id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
@@ -59,6 +60,7 @@
     ```python
     from sqlalchemy.orm import Mapped
 
+
     class Dataset(TypeBase):
         __tablename__ = "datasets"
         id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
@@ -101,6 +103,7 @@
     from sqlalchemy.dialects.postgresql import JSONB
     from sqlalchemy.orm import Mapped
 
+
     class ToolConfig(TypeBase):
         __tablename__ = "tool_configs"
         config: Mapped[dict] = mapped_column(JSONB, nullable=False)
@@ -111,6 +114,7 @@
 
     from models.types import AdjustedJSON
 
+
     class ToolConfig(TypeBase):
         __tablename__ = "tool_configs"
         config: Mapped[dict] = mapped_column(AdjustedJSON(), nullable=False)
@@ -146,7 +150,5 @@
     default_expr = sa.text("'database'::character varying") if _is_pg(conn) else sa.text("'database'")
 
     with op.batch_alter_table("dataset_keyword_tables") as batch_op:
-        batch_op.add_column(
-            sa.Column("data_source_type", sa.String(255), server_default=default_expr, nullable=False)
-        )
+        batch_op.add_column(sa.Column("data_source_type", sa.String(255), server_default=default_expr, nullable=False))
     ```

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

@@ -18,9 +18,7 @@
     # Existing repository is ignored and service uses ad-hoc table queries.
     class AppService:
         def archive_app(self, app_id: str, tenant_id: str) -> None:
-            app = self.session.execute(
-                select(App).where(App.id == app_id, App.tenant_id == tenant_id)
-            ).scalar_one()
+            app = self.session.execute(select(App).where(App.id == app_id, App.tenant_id == tenant_id)).scalar_one()
             app.archived = True
             self.session.commit()
     ```
@@ -33,6 +31,7 @@
             app.archived = True
             self.app_repo.save(app)
 
+
     # If the query is missing, extend the existing abstraction.
     active_apps = self.app_repo.list_active_for_tenant(tenant_id=tenant_id)
     ```
@@ -50,9 +49,10 @@
     class ConversationRepository(Protocol):
         def list_recent_for_app(self, app_id: str, tenant_id: str, limit: int) -> list[Conversation]: ...
 
+
     class SqlAlchemyConversationRepository:
-        def list_recent_for_app(self, app_id: str, tenant_id: str, limit: int) -> list[Conversation]:
-            ...
+        def list_recent_for_app(self, app_id: str, tenant_id: str, limit: int) -> list[Conversation]: ...
+
 
     class ConversationService:
         def __init__(self, conversation_repo: ConversationRepository):

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

@@ -126,9 +126,7 @@
 
     # 3) Pessimistic lock with SELECT ... FOR UPDATE (high contention)
     run = session.execute(
-        select(WorkflowRun)
-        .where(WorkflowRun.id == run_id, WorkflowRun.tenant_id == tenant_id)
-        .with_for_update()
+        select(WorkflowRun).where(WorkflowRun.id == run_id, WorkflowRun.tenant_id == tenant_id).with_for_update()
     ).scalar_one()
     run.status = "cancelled"
     session.commit()

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

@@ -7,12 +7,14 @@ description: Use when writing, changing, or reviewing Cucumber and Playwright te
 
 `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.
 
+Cucumber owns scenario and hook execution and reporting. Playwright provides browser automation, contexts, pages, locators, actions, assertions, request, and tracing APIs; protocol exceptions remain with the package-defined owner. Their timeout domains remain separate, and importing from `@playwright/test` does not make Playwright Test runner configuration, fixtures, or retries applicable to this suite.
+
 ## Topic Routing
 
 Read only the bundled reference required by the change:
 
 - 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]
+- Scenario wording, step granularity, expressions, World state, hook visibility, or tag design: [`references/cucumber-best-practices.md`][cucumber]
 
 Check current official Playwright or Cucumber documentation before introducing a framework pattern that local code and references do not already establish.
 
@@ -23,7 +25,7 @@ Check current official Playwright or Cucumber documentation before introducing a
 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.
+6. For changes, run the narrowest tagged scenario and package checks documented in `e2e/AGENTS.md`; broaden only for shared hooks, tags, or support changes.
 
 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.
 

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

@@ -4,15 +4,18 @@ Use this reference when writing or reviewing Gherkin scenarios, step definitions
 
 Official sources:
 
-- https://cucumber.io/docs/guides/10-minute-tutorial
-- https://cucumber.io/docs/cucumber/step-definitions
+- https://cucumber.io/docs/bdd/better-gherkin
+- https://cucumber.io/docs/gherkin/reference
+- https://cucumber.io/docs/gherkin/step-organization
+- https://cucumber.io/docs/cucumber/state
 - https://cucumber.io/docs/cucumber/cucumber-expressions
+- https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/world.md
 
 ## What Matters Most
 
 ### 1. Treat scenarios as executable specifications
 
-Cucumber scenarios should describe examples of behavior, not test implementation recipes.
+Cucumber scenarios should usually describe behavior declaratively, not reproduce an interaction script.
 
 Apply it like this:
 
@@ -20,11 +23,15 @@ Apply it like this:
 - avoid UI-internal wording such as selector details, DOM structure, or component names
 - keep language concrete enough that the scenario reads like living documentation
 
+Procedural detail is appropriate when the interaction mechanism is the behavior under test, such as keyboard navigation, focus movement, or a required multi-actor sequence.
+
 ### 2. Keep scenarios focused
 
-A scenario should usually prove one workflow or business outcome. If a scenario wanders across several unrelated behaviors, split it.
+A scenario should prove one business rule or coherent outcome. Cucumber's three-to-five-step recommendation is a review heuristic, not a hard limit: when a scenario is longer, check for multiple outcomes, incidental setup, or UI procedure that can move behind a domain step.
 
-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.
+Use `Given` for initial context, `When` for the event, and `Then` for the expected outcome. Restarting those phases is a prompt to review the narrative, not an automatic failure. Avoid hidden dependencies on another scenario's side effects.
+
+Use `Rule` when several examples illustrate one named business rule. Use a short `Background` only for shared context the reader needs to understand; do not hide fixture preparation, runtime readiness, or long setup there.
 
 ### 3. Reuse steps, but only when behavior really matches
 
@@ -45,6 +52,8 @@ Write a new step when:
 
 Do not optimize for a low step count by making vague steps. Optimize for a small set of truthful, domain-owned steps.
 
+Step definitions share one global matching namespace regardless of their directory. Organize them by domain capability and avoid feature-coupled glue or expressions broad enough to overlap unrelated behavior.
+
 ### 4. Prefer Cucumber Expressions
 
 Use Cucumber Expressions for parameters unless regex is clearly necessary.
@@ -62,18 +71,24 @@ Use regex for a bounded natural-language alternative only when it keeps Gherkin
 
 ### 5. Keep step definitions thin and meaningful
 
-Step definitions are glue between Gherkin and automation, not a second abstraction language.
+Step definitions are glue between Gherkin and automation, not a second abstraction language. A step should express one coherent domain action or outcome; it may call several implementation helpers when that keeps UI mechanics out of the specification.
 
-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.
+Cucumber creates a new World for each scenario. Keep scenario state there rather than in module globals. Cucumber.js supports a `world` proxy for arrow functions, but this suite consistently uses typed `async function (this: DifyWorld, ...)` so ownership and TypeScript discovery remain explicit.
+
+Hooks are invisible to feature readers. Keep them for low-level browser lifecycle, cleanup, and diagnostics; express business-relevant context in Gherkin.
 
 ### 6. Use tags intentionally
 
-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.
+Tags may communicate stable capability grouping, selection, fixture dependency, or conditional-hook intent. A tag changes runtime behavior only when a runner, seed profile, or hook owns that meaning.
 
 ## Review Questions
 
 - Does the scenario read like a real example of product behavior?
+- Does it prove one outcome, or combine several independent phases?
 - Are the steps behavior-oriented instead of implementation-oriented?
+- Is procedural wording necessary to the behavior being tested?
 - Is a reused step still truthful in this feature?
+- Could a new expression overlap an existing step in the global namespace?
+- Would `Rule` clarify the business rule, or would `Background` hide important setup?
 - Is a new tag documenting real behavior, or inventing semantics that the suite does not implement?
 - Would a new reader understand the outcome without opening the step-definition file?

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

@@ -6,8 +6,12 @@ Official sources:
 
 - https://playwright.dev/docs/best-practices
 - https://playwright.dev/docs/locators
+- https://playwright.dev/docs/actionability
 - https://playwright.dev/docs/test-assertions
+- https://playwright.dev/docs/test-timeouts
 - https://playwright.dev/docs/browser-contexts
+- https://playwright.dev/docs/events
+- https://playwright.dev/docs/trace-viewer
 
 ## What Matters Most
 
@@ -21,28 +25,22 @@ Apply it like this:
 - 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
+### 2. Select locators by user contract
 
-Playwright recommends built-in locators that reflect what users perceive on the page.
+Prefer built-in locators that match how the target is exposed to users:
 
-Preferred order:
+- interactive controls: role and accessible name
+- form controls: associated label; use placeholder when it is the relevant stable contract, especially when no label exists
+- non-interactive content: visible text or the relevant text alternative
+- elements without a meaningful user-facing contract: an intentional test id
 
-1. `getByRole`
-2. `getByLabel`
-3. `getByPlaceholder`
-4. `getByText`
-5. `getByTestId` when an explicit test contract is the most stable option
+This is a semantic choice, not a fixed ranking. Do not add incorrect roles or accessible names solely to satisfy a locator. When the product element should have user-facing semantics, fix that contract instead.
 
 Avoid raw CSS/XPath selectors unless no stable user-facing contract exists and adding one is not practical.
 
-Also remember:
+Locators are strict for single-element actions. Scope to a stable region or use `filter({ has, hasText })` to make the intended target unique. Treat `.first()`, `.last()`, or `.nth()` as a review signal: the positional choice should be intentional and stable, not merely silence ambiguity.
 
-- 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
+### 3. Use web-first assertions with the right timeout owner
 
 Playwright assertions auto-wait and retry. Prefer them over manual state inspection.
 
@@ -64,6 +62,8 @@ If a condition genuinely needs custom retry logic, use Playwright's polling/asse
 
 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.
 
+Cucumber step and hook timeouts, Playwright locator/action timeouts, and Playwright assertion timeouts are separate budgets. `browserContext.setDefaultTimeout()` does not change the default five-second assertion timeout. Put an explicit longer assertion timeout only on the readiness owner that needs it; do not raise an outer timeout to mask a shorter inner failure.
+
 ### 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.
@@ -77,15 +77,20 @@ Bad pattern:
 
 - stack arbitrary waits before every action
 - wait on unstable implementation details instead of the visible state the user cares about
+- use `force: true` to bypass a real hit-target, overlay, or disabled-state failure
+
+When synchronizing on a one-shot popup, download, request, or response, create the wait before triggering the action, then await the event. A scenario-owned listener may instead capture events for a later assertion. Do not use `networkidle` as an application-readiness assertion; wait for the user-visible state or owned backend contract.
 
 ### 5. Match debugging to the active harness
 
-Playwright supports traces, screenshots, page snapshots, and browser logs. Configure artifact capture at the runner boundary instead of adding parallel diagnostics to individual scenarios.
+Playwright supports traces, screenshots, page snapshots, and browser logs. Configure artifact capture in Cucumber hooks instead of adding parallel diagnostics to individual scenarios. If tracing is introduced, use `browserContext.tracing`; Playwright Test options such as `trace: 'on-first-retry'`, projects, workers, fixtures, reporters, and retries do not configure this harness.
 
 ## Review Questions
 
 - Would this locator survive DOM refactors that do not change user-visible behavior?
+- Is a positional locator expressing product order, or hiding an ambiguous match?
 - Is this assertion using Playwright's retrying semantics?
-- Is any explicit wait masking a real readiness problem?
+- Does an explicit timeout belong to the condition that is actually slow?
+- Was an event wait registered before the action that emits it?
 - Does this code preserve per-scenario isolation?
 - 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,18 +1,19 @@
 ---
 name: frontend-code-review
-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.
+description: Use only when the user explicitly requests a bug, regression, correctness, security, accessibility, performance, or test-quality review of frontend code under `web/` or `packages/dify-ui/`. Supports pending-change, file-focused, and pasted-diff reviews. Do not use for architecture-oriented evaluation of component ownership, state graphs, props, boundaries, or refactoring design unless concrete defects are also requested; do not use for implementation-only requests, diagnosis without review intent, or backend-only code.
 ---
 
 # Frontend Code Review
 
-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.
+Review the requested scope for concrete defects and violations of explicit project contracts. This skill owns review decisions; its references route to canonical rules without activating another skill's implementation workflow.
 
 ## Evidence First
 
 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.
+3. For a named component or a diff that changes component ownership, props, or state, read the component-architecture rule pack and complete its Root-To-Leaf State And Props Audit before drawing conclusions.
+4. Trace other public consumers, generated contracts, primitive APIs, or runtime configuration only when they decide correctness.
+5. Report findings tied to an observable failure, violated contract, security boundary, or demonstrated maintenance risk. Explicit team conventions are contracts: establish their scope and exceptions, and do not invent user impact to justify a convention finding.
 
 ## Rule Routing
 
@@ -27,16 +28,16 @@ Read only the packs matched by the diff:
 - 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]
 
-Read `packages/dify-ui/README.md`, `packages/dify-ui/AGENTS.md`, `web/docs/overlay.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.
+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.
 
 ## Severity And Output
 
 - **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.
+- **P2**: concrete maintainability, performance, test, or accessibility defect, or a material violation of an explicit project contract.
 - **P3**: minor actionable cleanup; omit unless the user requested a thorough audit.
 
-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.
+Lead with findings ordered by severity. Include a tight file and line reference, the observed failure or applicable project rule, and a concrete fix direction. Explain the rule's applicability for convention findings; describe downstream consequences only when supported by evidence. When no findings remain, say so briefly and state any material verification gap. Do not add praise sections, speculative risks, or an unsolicited offer to implement fixes.
 
 [accessibility]: references/accessibility-ui.md
 [code-quality]: references/code-quality.md

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

@@ -2,32 +2,51 @@
 
 Accessibility findings are first-class review findings. Treat broken keyboard access, missing accessible names, focus loss, and unreachable popup content as correctness bugs, not polish.
 
-Before finalizing UI or accessibility findings, fetch the latest Web Interface Guidelines as a required baseline:
+## Review Evidence
 
-```text
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
-
-Do not treat that document as the complete accessibility rule set. Combine it with:
+Use the sources relevant to the changed contract:
 
 - `packages/dify-ui/README.md`, `packages/dify-ui/AGENTS.md`, and the relevant primitive implementation when code uses `@langgenius/dify-ui/*`.
 - Base UI docs and local `.d.ts` contracts when primitive semantics, focus target, labels, or popup reachability are unclear.
 - MDN or relevant WAI-ARIA/browser standards when behavior, compatibility, or deprecation status matters.
 - The current feature's product semantics, because an accessible primitive can still be used in an inaccessible workflow.
 
+Consult current official documentation or standards when these sources leave a behavior unresolved. The [Web Interface Guidelines] are an optional broader UI reference, not a required fetch for each review.
+
 ## Semantic HTML
 
 Flag:
 
 - Clickable `div` or `span` used for actions.
 - Router navigation implemented with button or `onClick` when a `Link` / `<a>` is the real semantic element.
-- Icon-only buttons without `aria-label` or `aria-labelledby`.
+- Icon-only controls without an accessible name; follow the naming rules below and the Dify UI `IconButton` contract.
 - Decorative icons missing `aria-hidden="true"`.
 - Images without `alt`; use `alt=""` only when truly decorative.
 - Heading levels that skip hierarchy in page-level content.
 
 Prefer semantic HTML before ARIA.
 
+## Page Landmarks
+
+When reviewing Web page layouts, navigation, or landmark changes, read [Page landmarks].
+Inspect the composed page with its parent layouts for missing or duplicate main regions,
+inappropriate nesting or roles, and ambiguous or broken landmark names. Check affected
+unit and E2E locators when semantic elements change. Web owns these composition rules;
+use the existing naming contract for label-source decisions.
+
+## Accessible Names And Descriptions
+
+Read [Accessible names and descriptions] when a change affects labels, ARIA naming, help/error relationships, or hidden text. That document owns the shared implementation and review contract.
+
+Flag violations supported by the final rendered behavior:
+
+- Missing or insufficient names, redundant name overrides, or naming attributes prohibited by the element's role.
+- Overrides that omit visible label wording or suppress necessary descendant information.
+- Broken or stale label/description references, including relationships lost when responsive content or overlays unmount.
+- Descriptions used instead of names, repeated help text, or essential structured content available only as a flattened description.
+
+Inspect the computed name and description in the relevant state. Matching an `aria-label` string to nearby text alone does not prove redundancy.
+
 ## Keyboard And Focus
 
 Flag:
@@ -48,7 +67,6 @@ Flag:
 - Missing stable `name` on form fields that submit or validate.
 - Incorrect input `type`, `inputMode`, `autoComplete`, or `spellCheck` for email, token, URL, number, search, code, or username fields.
 - Labels that are not clickable.
-- Submit buttons disabled before a request starts, preventing normal submit behavior.
 - Non-submit buttons inside forms missing `type="button"`.
 - Errors not associated with fields or not reachable by screen readers.
 - Error recovery that does not focus or expose the first invalid field.
@@ -56,16 +74,20 @@ Flag:
 - Placeholder text used as the only label.
 - Password managers accidentally triggered on non-auth fields because autocomplete is missing or wrong.
 
-Prefer visible labels. If visible surrounding text already labels the control, use a visually hidden label or a precise `aria-label`.
+Prefer visible labels and associate them through the appropriate field primitive, a native `label`, or `aria-labelledby`. Do not duplicate an existing label with hidden text or `aria-label`; follow [Accessible names and descriptions] when no suitable visible label exists.
 
 ## Disabled, Loading, And Async States
 
 Flag:
 
-- Loading state without `aria-busy`, `role="status"`, or another accessible update path when it changes user interaction.
+- Loading controls whose accessible name disappears, or whose user-relevant progress has no
+  feature-owned status path. Follow the Dify UI Button contract for focused loading buttons; do not
+  add `aria-busy` to a button as a generic pending-state substitute.
+- The same pending state passed to both Dify UI Button `loading` and `disabled`, which duplicates
+  state ownership and obscures whether `disabled` expresses independent unavailability.
 - Spinner or decorative loading icon exposed to screen readers.
 - Disabled controls that hide the reason users cannot proceed.
-- `aria-disabled` used without manually blocking click, Space, and Enter.
+- Controls marked `aria-disabled` that still activate through supported pointer or keyboard input. Check the primitive's handling before requesting manual event guards.
 - Toasts, inline validation, or async status changes that are not announced when users need the update to continue.
 - Icon-only loading/error affordances without text or accessible status where the state matters.
 
@@ -90,7 +112,7 @@ Use Popover for explanatory content, rich help, and infotips. Use Tooltip only a
 Flag:
 
 - Text in flex/grid children without `min-w-0` when it can overflow.
-- Names, labels, file names, model names, workspace names, or user content lacking `truncate`, `line-clamp`, or `break-words`.
+- Long names, labels, or user content that overflow, obscure adjacent controls, or become unreadable in supported layouts.
 - Right-side icons, badges, checks, or actions that shrink before the text area.
 - Empty arrays or empty strings rendering broken layout instead of an empty state.
 - Button, tab, badge, chip, menu item, or card text that can overlap sibling controls at common viewport widths.
@@ -107,3 +129,7 @@ Flag:
 - Images without dimensions.
 - Loading copy using `...` instead of `…`.
 - Hardcoded dates, times, numbers, or currency formats instead of `Intl.*`.
+
+[Accessible names and descriptions]: ../../../../packages/dify-ui/docs/accessible-names-and-descriptions.md
+[Page landmarks]: ../../../../web/docs/landmarks.md
+[Web Interface Guidelines]: https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

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

@@ -26,15 +26,17 @@ Prefer:
 
 ## Styling
 
+For Dify UI/Base UI state styling and callback composition, apply the package's [Styling] contract,
+including its documented reasons for direct state access.
+
 Flag:
 
 - New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
 - Component-level plain `.css` files or component CSS imported through `globals.css`; use scoped `*.module.css` only when Tailwind and component variants cannot express the style.
 - Generic color utilities where Dify semantic tokens exist.
-- Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist.
+- Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or standard Tailwind radius classes match the required design value. Apply [Styling] when choosing radius classes.
 - `!` important modifiers or important CSS overrides without a narrow, documented reason.
-- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes.
-- JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors.
+- Manual class-list assembly through string concatenation, template strings, array `.join(' ')`, or a custom conditional combiner instead of `cn(...)`. Conditional values passed to `cn(...)` remain valid.
 - Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides.
 - Arbitrary z-index or one-off layering fixes on overlays.
 
@@ -43,7 +45,6 @@ Use:
 - `cn(...)` from the local package or utility already used by the file.
 - Dify semantic tokens and Tailwind v4 utilities.
 - Existing component variants before one-off class forks.
-- Primitive selectors such as `data-disabled:*`, `data-checked:*`, `data-highlighted:*`, `group-data-*`, `peer-data-*`, and `has-[:focus-visible]` before adding React state or boolean props solely for styling.
 - Component-level variants, semantic tokens, and normal cascade/order before `!` overrides. Use `!` only for a contained compatibility override that cannot be expressed through the component API or local selector structure.
 
 ## Imports
@@ -66,3 +67,5 @@ Flag:
 - Error messages that state only the failure and not the next step.
 
 Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.
+
+[Styling]: ../../../../packages/dify-ui/docs/styling.md

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

@@ -1,88 +1,44 @@
-# Component Architecture Rules
+# Component Architecture Review
 
-Use these rules for React component structure, ownership, state, props, effects, and module organization.
+Use the canonical reference for the changed concern. These links share rules; they do not activate the implementation skill or its workflow.
 
-## Ownership
+| Concern | Canonical rules |
+| --- | --- |
+| Vertical modules, public entrypoints, data/handler placement, wrappers, Props, and types | [Ownership] |
+| Local/Jotai state, form drafts, route identity, URL state, and persistence | [State] |
+| Effects, navigation, memoization, and subscriptions | [Runtime] |
+| Hotkeys, focus, and secondary surfaces | [Interactions] |
 
-Flag:
+## Root-To-Leaf State And Props Audit
 
-- State, query, mutation, or handlers hoisted above the lowest component that actually uses them.
-- Parent components owning row/item actions that do not coordinate a workflow.
-- Prop drilling through multiple pass-through layers.
-- A page/tab-level section component becoming the data owner without needing a shared snapshot or shared loading/error/empty UI.
-- Feature code promoted to shared only because it appears once or might be reused later.
+For a file-focused component review, use the named component as the root. For a pending diff, use each changed page, feature entrypoint, or nearest behavior owner whose state or props contract changed.
 
-Accept repeated TanStack Query calls in siblings when each component independently consumes the data. Cache deduplication is not a reason to hoist by itself.
+1. Build the locally owned rendered component tree from each root to every leaf. Follow imported feature components, conditional branches, lists, portals, dialogs, drawers, and popovers. Stop at third-party or Dify UI primitives and explicit stable public feature boundaries, but record the props passed across that final edge.
+2. At every component, inventory state sources: React state/reducers, form state, URL state, context/store/Jotai reads and writes, queries, mutations, refs that hold workflow state, and custom-hook results.
+3. For every state value, derived fact, and handler, record its consuming branches and required lifetime, including persistence across descendant unmounts. Assess its placement against [Ownership] and [State], including their coordination and persistence exceptions.
+4. Inspect every props edge. Mark values that are read by the child, forwarded unchanged, renamed, recomputed, mirrored into local state, or paired with lifecycle fields such as `data/pending/error/retry` and `open/onOpenChange`.
+5. Trace what each forwarding parent actually owns before reporting an unnecessary intermediary. Apply [Ownership] to distinguish required coordination or persistence from merely redistributing workflow fields, and [State] to determine whether a feature graph is warranted.
+6. Remove unused or redundant props at their source. Do not accept replacing many props with a props bag, context, or hook result unless that abstraction becomes the real owner and gives consumers a narrower contract.
 
-## Component Boundaries
+Review the complete paths before concluding that a state or prop is necessary. When several edges share one ownership defect, report one finding at the highest incorrect owner and include a representative path such as `Root -> Section -> Leaf`; do not emit a duplicate finding for every child.
 
-Flag:
+## Apply Rules In Their Actual Scope
 
-- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities.
-- Shallow wrappers that only rename props or hide the real primitive.
-- Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration.
-- Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component.
-- Business forms, menu bodies, or one-off helpers moved away from their owner without reuse or semantic value.
+Explicit team conventions are reviewable contracts, including module organization and public API boundaries. Check the documented exception before reporting a violation. Do not infer an exception solely because the code appears to work, or invent a user-facing failure for a convention finding.
 
-Prefer colocated components split by actual data and state needs.
+- For owner placement, trace the consumers and required lifetime. Establish whether the parent coordinates a snapshot, submission, navigation, shared UI, or persistence before asking to move state or handlers.
+- For component boundaries, identify the ownership or encapsulation the proposed extraction would improve; file length alone establishes neither.
+- For props and types, check the domain contract and public API. Do not report private props typing style alone; declaration/export syntax matters only for a documented package rule or concrete type, export, or framework defect.
+- For state and Effects, trace the source of truth, external synchronization target, and mount/reset boundary. Controlledness alone does not prove that a draft is lifted or persisted; follow the form and overlay contracts linked by [State].
+- For navigation, distinguish ordinary links from mutation success, guarded redirects, command flows, and submission side effects.
 
-## Bad Component Design Patterns
+## Preserve Existing Product Contracts
 
-Flag:
+During refactors, trace the interaction being moved through its real consumer. Navigation, sidebar, dropdown, webapp-list, and app-switching changes must preserve expansion controls, hover persistence, pin/delete actions, routing, keyboard/focus handling, and open-state ownership where present.
 
-- Refactors of existing navigation, sidebar, dropdown, webapp list, or app-switching UI that do not preserve behavior-sensitive interactions such as expand/collapse arrows, hover persistence, pin/delete controls, routing, keyboard/focus handling, or open-state ownership.
-- Components that mix data fetching, mutation side effects, popup state, form validation, layout, and row rendering without a clear owner.
-- Generic components with many boolean props that encode one feature's workflow.
-- A shared component that imports feature-specific copy, routes, or API contracts.
-- A feature component that accepts pre-rendered fragments only to avoid placing ownership correctly.
-- A child component that receives both raw server data and separately derived flags for the same concept.
-- A wrapper that changes accessible semantics of the primitive it wraps.
-- A component that exposes controlled props but still keeps a competing private state for the same value.
-- A component that cannot render empty, loading, or missing optional API fields without caller-side preprocessing.
+Check that the changed owner still handles reachable empty, loading, and missing optional-data states, and that primitive wrappers preserve accessible semantics and the public controlled-state contract. Report the actual lost behavior or explicit rule violation; use the package testing policy when assessing regression coverage.
 
-When existing components already own interaction logic, prefer reusing or extending them. If a refactor is necessary, preserve the old interaction contract and add or update focused tests for changed behavior.
-
-## Props And Types
-
-Flag:
-
-- 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.
-
-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
-
-Flag effects that:
-
-- Transform props/state for rendering.
-- Copy one state value into another representing the same concept.
-- Handle user actions that belong in event handlers.
-- Reset state from props when a keyed reset, stable ID, or render-time derivation would work.
-- Fetch data that belongs in framework APIs or TanStack Query.
-
-If an effect remains, it must synchronize with a named external system: browser API, subscription, timer, analytics-on-visibility, non-React widget, or imperative DOM integration.
-
-## State Modeling
-
-Flag:
-
-- Storing derived booleans, disabled flags, default tabs, or loading labels that can be calculated from current query/feature state.
-- Local state used to fake server data or generated contract fields.
-- UI state persisted to localStorage when it is live app state.
-- Feature-local mock shells wired to unrelated existing APIs before the real API is confirmed.
-
-Prefer render-time derivation. Keep true local state for user choices, transient input, controlled popups, and feature UI state that has no server source.
-
-## Navigation
-
-Flag:
-
-- Imperative router navigation for ordinary links.
-- Button semantics used for navigation.
-- Navigation state hidden in component state when URL state is required for shareable filters, tabs, or pagination.
-
-Use `Link` for normal navigation. Use router APIs for mutation success, guarded redirects, command flows, or form submission side effects.
+[Interactions]: ../../how-to-write-component/references/interactions.md
+[Ownership]: ../../how-to-write-component/references/ownership.md
+[Runtime]: ../../how-to-write-component/references/runtime.md
+[State]: ../../how-to-write-component/references/state.md

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

@@ -1,74 +1,28 @@
-# Data, Query, And Contract Rules
+# Data, Query, And Contract Review
 
-Use these rules for generated contracts, TanStack Query, mutations, auth/SSR boundaries, URL state, and client persistence.
+[Data and queries] owns generated-client, Query options, mutation/cache, imperative access, SSR, authentication, and tenant rules. [State ownership] owns URL state and persistence. Read only the reference needed by the diff; reading a shared reference does not activate its implementation skill.
 
-## Generated Contracts
+## Generated Contracts And Query Conventions
 
-Flag:
+Review explicit team conventions as contracts, including direct generated options, `skipToken` for missing required input, and shared cache policy. A lint rule may enforce part of a convention; neither a green lint result nor a suppression proves the full contract is satisfied.
 
-- New legacy service/helper wrappers around generated `queryOptions()` or `mutationOptions()`.
-- Continuing to use deprecated contract operations when a ready generated contract exists.
-- Assuming a generated file means an operation is ready without checking deprecated markers, schema shape, and the actual UI consumer.
-- Re-declaring API DTOs in components.
-- Adding compatibility layers instead of migrating the pointed line and deleting the old layer.
+- Establish whether the changed call belongs to a new or migrated surface and whether the generated operation is ready. Check deprecated markers, schema shape, and the real UI consumer before prescribing a migration.
+- Distinguish a pass-through wrapper from a feature hook with actual orchestration. Check whether an independent execution condition or Promise composition justifies the documented query/mutation exception.
+- Trace generated input and output types through their boundaries. Identify the exact DTO mirror, field widening, placeholder input, or lost intentional empty value when reporting a violation.
+- Check whether a local mutation callback owns feature feedback or replaces shared invalidation, retry, or cache defaults. Match optimistic changes to the current list/detail owner.
 
-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.
+## Imperative Access And SSR
 
-## Queries
+- Check freshness, projection, retries, and the caller's execution condition separately against [Data and queries]. Trace Promise ownership to distinguish an awaited hard gate from soft prefetching with an explicit failure owner.
+- For Server Components, identify who renders the data and who may revalidate it. Check dehydration, the same-key client consumer, error handling, and the intended Suspense/server-rendered-content contract when the diff changes streaming.
+- For auth, setup, roles, branding, or availability, trace authoritative data and the loading/fallback path. A static redirect or placeholder value cannot stand in for a request-dependent decision.
 
-Flag:
+## Tenant, URL, And Persistence Boundaries
 
-- `enabled` used to hide missing required input instead of `input: skipToken`.
-- Fake fallback IDs or placeholder inputs used to force a query to run.
-- Query results copied into local state for rendering.
-- Shared query behavior such as invalidation, stale defaults, or retry rules reimplemented at call sites.
-- `prefetchQuery` treated as a hard gate or as returning data/errors to the caller.
+- Trace the current workspace-switch flow and cache lifetime before reporting missing identity in a query key. Verify backend meaning before treating `workspace_id` and `tenant_id` as interchangeable.
+- For URL and storage changes, identify whether the value is shareable navigation state, live app state, a one-shot signal, or a low-frequency preference. Apply [State ownership] to that category and verify its write/reset owner.
 
-Use `useQuery(consoleQuery.xxx.queryOptions(...))` or `useQuery(marketplaceQuery.xxx.queryOptions(...))` directly unless a feature hook performs real orchestration.
+Report the violated rule and applicable scope or the concrete failing path. Do not invent runtime impact when the finding is a team-convention violation.
 
-## Mutations
-
-Flag:
-
-- Deprecated `useInvalid` or `useReset`.
-- `mutateAsync` used without a need for Promise semantics.
-- Awaited mutations without `try/catch`.
-- Components owning shared cache invalidation that belongs in query defaults.
-- Optimistic updates that do not match current list/detail ownership.
-
-Use generated `mutationOptions()` directly when possible. Put shared cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`.
-
-## SSR, Auth, And Route Boundaries
-
-Flag:
-
-- Request-time auth, setup, workspace role, or tenant decisions moved into static `next.config redirects()`.
-- Dynamic role gates depending on `workspaces.current` implemented as static path redirects.
-- Authorization logic depending on soft `prefetchQuery`.
-- Removing a client fallback before server API unavailable behavior is defined.
-- Global placeholder query contracts introduced to solve a route-local Suspense issue.
-- Branding-sensitive UI reading placeholder defaults without checking pending/placeholder state.
-
-Separate hard gates from soft prefetches. `fetchQuery` can be a server decision boundary; `prefetchQuery` is cache warmup.
-
-## Workspace And Tenant
-
-Flag:
-
-- Treating workspace switch as ordinary CRUD invalidation when the current app flow performs server switch plus full reload.
-- Query keys that omit workspace/tenant identity when the query truly varies by workspace and no full reload boundary applies.
-- Mixing `workspace_id` and `tenant_id` without tracing the current backend/API contract.
-
-Current Dify workspace switch should be reviewed as a tenant cache boundary first.
-
-## URL State And Local Storage
-
-Flag:
-
-- Shareable filters, tabs, pagination, selected panels, or search state hidden only in component state.
-- One-shot navigation signals modeled as subscribed persistent state.
-- Live app state stored in localStorage.
-- Direct `window.localStorage`, `globalThis.localStorage`, or raw storage calls in app code.
-- High-frequency interaction state persisted on every change instead of on commit/settle.
-
-Use URL state for shareable UI state, feature/Jotai/store state for live UI state, and `@/hooks/use-local-storage` only for low-frequency client-only preferences, dismissed notices, and UI defaults.
+[Data and queries]: ../../how-to-write-component/references/data.md
+[State ownership]: ../../how-to-write-component/references/state.md

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

@@ -1,141 +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`                                  |
+| State styling, callbacks, and Tailwind     | `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.
-- Canonical primitive boundaries or their associated public types using a redundant `Root` suffix when no higher-level convenience component exists in the same subpath.
-
-Consumers use subpath exports such as `@langgenius/dify-ui/button`.
-
-Canonical boundaries use the primitive name and matching public types (`Select` / `SelectProps`). Keep `Root` only to distinguish a low-level anatomy root from a higher-level convenience component (`CheckboxRoot` / `Checkbox`); implementation aliases should still show their Base UI source (`BaseSelect.Root.Props`).
-
-## 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.
-- Generic Base UI selection primitives wrapped without preserving their value generics, such as `Select.Root<Value, Multiple>`, `RadioGroup<Value>`, or `Radio.Root<Value>`.
-- Shared select/radio option components that type selected values as `string` while callers pass enums, unions, booleans, numbers, objects, or nullable placeholder values.
-
-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.
-
-For non-string `Select` and `RadioGroup` values, prefer explicit domain generics at the root and at child value carriers. JSX children do not inherit the parent generic, so `RadioGroup<PromptMode>` should compose with `Radio<PromptMode>`, `RadioItem<PromptMode>`, or option values from a typed collection. For `Select`, prefer the Base UI `items` collection pattern for typed value-to-label rendering, and flag string coercion helpers used only to recover display labels.
-
-## Forms
-
-Flag:
-
-- Form-like UI using unrelated `Input` and `Button` pieces without a submit boundary.
-- Text-like fields not composed through `Field`, `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 `Fieldset` 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/README.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/performance.md

@@ -71,8 +71,6 @@ Flag:
 
 ## React Flow
 
-For workflow React Flow components, keep this Dify-specific rule:
+Use [Dify invariants] for React Flow node/edge consumption and provider availability in RAG Pipe template rendering. Callback-only reads or mutations can use `useStoreApi`.
 
-- UI consumption should use React Flow hooks such as `useNodes` / `useEdges`.
-- Callback-only reads or mutations can use `useStoreApi`.
-- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` must not depend on workflow stores that are absent in RAG Pipe template rendering.
+[Dify invariants]: dify-invariants.md

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

@@ -1,6 +1,6 @@
 # Testing Review Rules
 
-`web/docs/test.md` is the canonical frontend testing policy. Use this file only to translate that policy into review findings.
+Use `web/docs/test.md` for tests owned by `web/` and `packages/dify-ui/docs/testing.md` for tests owned by Dify UI. These owners define their test boundaries, environments, and checks; this reference only adds review questions.
 
 ## Request Missing Tests When Risk Justifies Them
 
@@ -9,10 +9,11 @@ Flag missing coverage when a change alters a reachable contract such as:
 - 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 mechanical changes, pass-through wrappers, implementation details, or visual-only styling unless they affect behavior. Low coverage alone is not a finding.
+Do not request tests for mechanical changes, pass-through wrappers, implementation details, or incidental visual styling. Low coverage alone is not a finding.
 
 ## Flag Low-Value or Fragile Tests
 
@@ -29,8 +30,8 @@ Flag tests that:
 
 - 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.
+- Check mocks against the owning package's policy; allowed mocks must preserve the public contract and leave the behavior under review real.
+- Apply the owning package's admission policy before requesting new automation. Real-browser verification can be a one-off review; a simulator limitation alone does not justify a permanent test.
+- Check that assertions prove the claimed outcome and add evidence beyond existing tests; a browser runtime does not make weak assertions stronger.
 
 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

@@ -5,12 +5,9 @@ description: Use when writing or changing Vitest or React Testing Library tests
 
 # Frontend Testing
 
-`web/docs/test.md` is the single policy owner. Read it before changing frontend tests; this skill adds no separate requirements.
+Read the testing policy for the package that owns the changed tests:
 
-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.
+- `web/`: `web/docs/test.md` owns Web test boundaries, environments, and commands.
+- `packages/dify-ui/`: `packages/dify-ui/docs/testing.md` owns primitive test boundaries, environments, Storybook, and commands.
 
-Recommend deleting low-value tests as readily as adding missing behavior coverage. Use `web/docs/test.md` for policy and Web commands; use the `packages/dify-ui/README.md` Development section for Dify UI commands.
+This skill adds no parallel policy or check sequence. Follow the selected owner's requirements, including its validation commands. Recommend deleting low-value tests as readily as adding missing behavior coverage, and report the contract verified and any material verification gap.

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

@@ -1,39 +1,67 @@
 ---
 name: how-to-write-component
-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.
+description: Use when implementing, refactoring, or architecture-reviewing React/TypeScript components whose ownership, state lifetimes, data flow, props, feature boundaries, effects, or interaction surfaces need redesign. Do not use for bug, regression, security, or accessibility audits; test-only work; copy-only edits; or styling-only changes.
 ---
 
-# How To Write A Component
+# React Component Architecture
 
-Use this skill to route component architecture decisions to its bundled references. Read only the references required by the current change.
+Use this skill to make component ownership and lifecycle explicit before implementation. Classify every stateful value on three independent dimensions:
 
-## First Decisions
+1. **Owner/source:** a component, parent boundary, URL/framework API, TanStack Query, or feature workflow.
+2. **Graph role:** primitive input, query/mutation node, derived business fact, or workflow command.
+3. **Lifecycle:** instance isolation, persistence, and reset requirements.
 
-| Question | Default | Promote only when |
-| --- | --- | --- |
-| 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 visual owner that consumes them. | A parent coordinates one workflow or consistent snapshot. |
-| 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. |
+Do not force one label to answer all three dimensions.
+
+Keep display state, submit-only fields, and owner-local queries or mutations with the component or DOM that owns their complete lifecycle. A value enters the feature state graph only when it crosses an ownership boundary, participates in shared derivation or coordination, or must outlive/reset independently of its current owner. Driving an owner-local query or command alone is not sufficient. In this repository, use feature-local Jotai as the default representation once a value enters that graph.
+
+## Operating Modes
+
+Choose the mode from the user's requested outcome:
+
+- **Architecture audit:** Perform a read-only, root-to-leaf analysis and propose the target ownership model. Read [`references/audit.md`][audit] and [`references/ownership.md`][ownership].
+- **Refactoring design:** Perform the architecture audit, then provide target contracts, migration slices, and a verification strategy without modifying code. Read [`references/audit.md`][audit] and [`references/ownership.md`][ownership].
+- **Implementation:** Establish the affected owner map, state graph, props edges, and reset boundaries before editing. Implement one coherent vertical slice at a time, then run the final audit in [`references/audit.md`][audit]. Read [`references/ownership.md`][ownership].
+- **Bug or regression review:** Use the frontend code-review workflow unless the user explicitly requests this skill's architecture model as an additional lens.
 
 ## Topic Routing
 
+After selecting the operating mode, read only the topic references required by the change:
+
 - 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.
+- Dify UI wrappers or primitive state styling: read the package's [Public API authoring] and [Styling] contracts.
+- Jotai, graph-entry decisions, form drafts, shared client state, route identity, URL state, isolation/reset, or persistence: read [`references/state.md`][state].
+- Generated contracts, nullable API data, Query, mutations, SSR, authentication, or workspace state: read [`references/data.md`][data].
+- A feature graph that combines Jotai isolation with TanStack Query atoms or commands: read both [`references/state.md`][state] and [`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 session state.
 - Effects, navigation, memoization, preloading, or render cost: read [`references/runtime.md`][runtime].
 
-## Workflow
+## Common Workflow
 
-1. Identify the behavior owner 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 the `packages/dify-ui/README.md` Development section for Dify UI.
+Follow this order so component splitting does not precede ownership decisions:
 
+1. **Boundary and evidence:** identify the route, tab, workflow, or action surface that owns the behavior and lifetime. Inspect nearby implementation, tests, sibling state files, and established feature boundaries.
+2. **Current model:** identify generated data contracts and authoritative external inputs, then inventory state, queries, mutations, derived facts, commands, refs, and meaningful props edges.
+3. **Target graph and owners:** decide explicitly which values remain local and which enter the feature graph. Define authoritative bridges, graph nodes, component owners, and scope/reset boundaries before creating files or wiring components.
+4. **Re-cut the tree:** treat current files as evidence rather than target constraints. Keep, split, merge, remove, rename, promote, or demote components based on ownership, lifecycle, behavior, and independently changing visual regions.
+5. **Contracts and interactions:** place data, loading, empty, error, and handlers at the lowest real consumer. Cross true owner boundaries only with stable identity, a small immutable snapshot, placement, or a named command. Give forms and secondary surfaces explicit lifecycle owners.
+6. **Finish and verify:** remove copied state and unnecessary Effects, wrappers, memoization, or nullable coercion. Rerun the final owner, graph, props-edge, and reset audit, then verify observable behavior at the narrowest sufficient boundary.
+
+## Scope And Verification
+
+In architecture-audit and refactoring-design modes, do not modify code. In implementation mode, complete equivalent ownership fixes inside the audited feature when the target contract depends on them, but do not expand into unrelated features. Incremental slices may retain documented temporary edges; the final requested slice must pass the completion gate in [`references/audit.md`][audit].
+
+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.
+
+[audit]: references/audit.md
+
+## Tailwind CSS
+
+- Write canonical Tailwind v4 classes; prefer canonical utilities over equivalent arbitrary values.
+- Common forms include `w-105` instead of `w-[420px]`, `px-2.25` instead of `px-[9px]`, `bg-linear-to-b` instead of `bg-gradient-to-b`, `wrap-break-word` instead of `break-words`, and `field-sizing-content` instead of `[field-sizing:content]`.
+
+[Public API authoring]: ../../../packages/dify-ui/docs/authoring.md
+[Styling]: ../../../packages/dify-ui/docs/styling.md
 [data]: references/data.md
 [interactions]: references/interactions.md
 [ownership]: references/ownership.md

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

@@ -0,0 +1,64 @@
+# Component Architecture Audit
+
+Read this document for architecture audits, refactoring designs, and the final ownership verification after an implementation refactor.
+
+## Audit Procedure
+
+For a named component, use it as the audit root. For a refactoring request, use the nearest route, page, feature entrypoint, or behavior owner whose state contract is changing.
+
+1. Build the complete locally owned rendered component tree from the root to every leaf. Follow imported feature components, conditional branches, lists, portals, dialogs, drawers, popovers, and secondary surfaces. Stop at third-party primitives, Dify UI primitives, or an explicit stable feature boundary, but record the props passed across the final edge.
+2. At every component, inventory React state and reducers, form and uncontrolled DOM state, URL and route state, Context/Jotai/store reads and writes, queries, mutations, refs that hold workflow or lifecycle state, custom-hook results, render-time derived facts, and workflow commands or handlers.
+3. For every value, record its authoritative owner/source, graph role, declaring component, consuming branches, lifetime and reset/isolation requirements, and whether it is local, shared, forwarded, mirrored, or persisted.
+4. Inspect every meaningful props edge. Mark each prop as consumed, forwarded unchanged, renamed, recomputed, mirrored into local state, or paired with lifecycle fields such as `data/pending/error/retry` and `open/onOpenChange`.
+5. Draw the current state graph in dependency order and assess ownership only after the complete paths are mapped. Group related problems at the highest incorrect owner instead of repeating the same issue for every descendant.
+6. Give every current local component an explicit target disposition: keep, split, merge, remove, rename, promote to an owner, or demote to presentation. Map every current state or workflow owner to a target component and reset boundary.
+7. Redraw the target rendered tree independently of the current file layout. Split only when state lifetime, interaction lifecycle, behavior ownership, or an independently changing visual region establishes a real boundary. Merge or remove components that only forward, rename, or obscure a single owner's contract.
+8. For refactoring design or implementation planning, define ordered migration slices with explicit state-file changes, component moves/splits/merges, observable verification boundaries, and intentionally temporary props edges.
+
+A rename, facade wrapper, props bag, Context, or provider around the same switchboard does not count as a boundary redesign. Correctness bugs may illustrate an ownership defect, but architecture-audit mode does not prioritize or severity-rank bug findings.
+
+## Audit Output
+
+Cover the following information. Merge sections or omit empty tables when the review is small, but do not omit applicable values, paths, edges, owners, or reset boundaries:
+
+1. **Review boundary:** root component, locally owned rendered paths, and stopping boundaries.
+2. **Rendered component tree:** every local branch and secondary surface followed.
+3. **State inventory:** owner/source, graph role, graph-entry decision, declaration, consumers, and lifetime/reset needs for every stateful value, query, mutation, ref, custom-hook result, derived fact, and command.
+4. **Props-edge ledger:** every meaningful parent-child edge and how each prop is treated.
+5. **Current architecture:** state graph, component owners, and ownership assessment.
+6. **Component dispositions:** the target disposition of every current local component and the destination of every current state/workflow owner.
+7. **Target architecture:** target rendered tree, state graph, owners, component contracts, and reset boundaries.
+8. **Migration slices:** required for refactoring design; include them in an audit when they materially clarify how to reach the target.
+
+Use compact tables when they make full accounting easier to verify:
+
+| Value | Source/role | Declared at | Consumers | Props path | Lifetime/reset | Recommended owner |
+| --- | --- | --- | --- | --- | --- | --- |
+
+| Edge | Prop | Treatment | Real consumer | Assessment |
+| --- | --- | --- | --- | --- |
+
+| Current component | Current responsibilities | Target disposition | Target owner(s) | Reason |
+| --- | --- | --- | --- | --- |
+
+| Target component | Owned state/workflow | Children | Public contract | Reset boundary |
+| --- | --- | --- | --- | --- |
+
+## Implementation Completion Gate
+
+Repeat the audit against the final code. Do not describe an implementation or refactor as complete until all applicable checks pass:
+
+- every locally owned rendered path, meaningful props edge, and stateful value is represented in the component tree, inventory, or ledger;
+- every current local component has a target disposition, and every current state/workflow owner maps to an implemented component and reset boundary;
+- every multi-consumer graph value has one authoritative bridge or graph node and a named owner;
+- route or URL identity is read directly by a single consumer or bridged once, not also threaded through descendant props;
+- query keys, observer objects, `refetch`, loading/error groups, and cache invalidation mechanics do not cross a boundary unless the child owns the query surface;
+- no page, hook, provider, or Context mainly destructures, renames, and redistributes another state machine;
+- components consume focused fields, named facts, or domain commands instead of rebuilding shared business conclusions;
+- query and mutation atoms remain cache-shared, while only resettable workflow primitives or boundary snapshots are scoped;
+- a feature scope that depends on application state still observes parent/global atom updates; a fresh `Provider` is used only when full-store isolation is an explicit requirement;
+- scoped-state verification covers parent-store interoperation, sibling-instance isolation when multiple instances are supported, and semantic-identity reset;
+- every remaining multi-layer prop edge is justified as stable identity, an immutable display snapshot, placement, or a named cross-boundary command;
+- the final rendered tree, state graph, owner map, contracts, and reset boundaries match the implemented code rather than only the initial design.
+
+If the user requests incremental commits, a slice may intentionally leave documented edges for a later slice. The final requested slice must still pass this gate.

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

@@ -8,35 +8,57 @@ Read this document when a component consumes generated contracts, nullable API v
 - 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.
+- When a ready generated operation exists for the changed call, migrate deprecated operations and remove the replaced layer instead of adding compatibility wrappers.
 - 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.
+- Build required values in the branch that proves them. Do not use truthiness filters, non-null assertions, or placeholders to conceal missing required input or discard valid `0`, `false`, or empty-string values.
 
 ## 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`.
+- Keep owner-local queries in `useQuery` when their pending, error, and data state serve only that component. Promote them to query atoms only when atom input drives them or other graph nodes consume their result.
+- When a query supplies several sibling owners, shared derived facts, or workflow commands, model it as a graph node with field selectors. Do not keep it in a page and pass its data, query key, observer methods, and status fields back down as a deconstructed query object.
 - 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.
+- For the same logical request, preserve key, input, operation, and result contracts. Share the exact options between prefetch and render only when transport, context, and cache policy are shared; imperative and observer freshness may differ. Do not extract option helpers merely to reuse input construction.
+- In Jotai-backed components, consume field-level selectors or named facts rather than the complete query result unless observer methods such as `refetch` or an infinite-scroll field group are part of that owner's contract.
+- Keep observer methods inside the component that owns the query surface or behind a named graph command. A parent must not pass raw `refetch`, query keys, or invalidation details merely because a descendant action needs fresh data.
+- Treat `refetch()` as an explicit execution command: it can run a query whose observer currently has `enabled: false`. Retry and refresh commands must recheck the permission, identity, or availability condition before including conditionally enabled queries.
+- Cache writes and query-observer notifications may reach React through asynchronous batching, including when `atomWithQuery` observes an existing QueryClient. Tests that call `setQueryData`, invalidate, or complete a refetch must await the resulting DOM fact with `findBy*` or `waitFor`; do not assume the observer rerender is synchronous with the cache call.
 - 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.
+- Keep a mutation in `useMutation` when pending and error state belong to one dialog or form. Use a mutation atom only when shared workflow orchestration or graph-derived state consumes it; query and mutation atoms remain unscoped.
+- Do not introduce deprecated `useInvalid` or `useReset` APIs.
+- Put shared invalidation, retries, and cache behavior in `createTanstackQueryUtils(...experimental_defaults...)`. In oRPC v1, caller options override defaults, including callbacks. Local callbacks may own toast, close, and navigation effects but must preserve shared cache behavior.
+- Workflow-specific invalidation belongs beside the mutation/command that understands which caches become stale. Construct generated query options or keys from graph identity there instead of receiving keys from a rendering parent.
 - 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.
+- Use `query` or `infiniteQuery` for imperative access. `staleTime` defines cache acceptance; `select` projects the return
+  value without replacing cached query-function data. Imperative queries default to no retries when `retry` is not
+  configured, and observer-only `enabled` does not prevent an imperative call.
+- Migrate deprecated `fetchQuery`, `prefetchQuery`, `ensureQueryData`, and their infinite variants when the current `query` or `infiniteQuery` contract applies. A `staleTime` of `0` treats data as stale; a finite value accepts that freshness window; `Infinity` accepts data until invalidation; `'static'` accepts available data even after invalidation.
+- `await` blocks, `return` transfers the Promise, and `void` discards its value without handling rejection. Handle
+  rejection before discarding a potentially rejecting Promise; use `.catch(noop)` only for intentional silence or
+  feedback owned elsewhere. Hard server gates await the query and preserve rejection.
 
 ## 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.
+- Treat Server Components as query prefetch-and-dehydrate owners by default. Do not render or pass an imperative query
+  result when a browser observer can revalidate the same data unless ownership and freshness explicitly prevent drift.
+- Non-blocking RSC streaming requires pending-query dehydration without redacting Next.js server errors, a
+  `HydrationBoundary` around the same-key client consumer, and Suspense when that content must be server-rendered.
 - Never reuse tenant-scoped state after switching workspaces. Discard it at the switch boundary or isolate it by workspace identity.
+- Trace the current switch flow before choosing cache handling: server switch plus full reload is a tenant boundary, not ordinary CRUD invalidation. Include workspace identity in varying query keys when no full-reload boundary applies, and trace the backend contract before interchanging `workspace_id` and `tenant_id`.
 - Do not make product or authorization decisions from bootstrap defaults. Wait for authoritative data, or render an explicit loading or error state.
+- Preserve an existing client fallback until server API-unavailable behavior has an explicit owner.
 - 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

@@ -1,6 +1,6 @@
 # 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 guide].
+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
 
@@ -20,12 +20,15 @@ Read this document when a change involves application hotkeys, focus, dialogs, m
 
 ## Secondary Surfaces
 
-- Follow `web/docs/overlay.md` for primitive choice. Dify UI primitives are the default, with package-approved Web wrappers such as `Infotip` where the overlay guide allows them.
+- Follow the [overlay contract] for primitive choice and shared mechanics. The nearest consumer `AGENTS.md` owns application-specific composite reuse policy.
+- A controlled composite may emit several callbacks synchronously for one gesture, such as changing a mode and then initializing its selection. Every callback sees the same render snapshot. Compose changes through one owner command or functional state update; when later callbacks or immediate side effects require the latest draft before React rerenders, maintain an interaction-owned ref updated in the handlers and clear it at the same semantic reset boundary as the draft.
 - 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.
-- Mount controlled overlays unconditionally unless unmounting is required for performance or reset semantics. Prefer keyed or owner-local reset over conditional wrappers.
-- Put query and mutation work inside dialog or alert-dialog content when it should mount only after opening.
-- Prefer uncontrolled roots when the primitive can own open state. Use controlled state only for business coordination, analytics, cleanup, or explicit reset behavior.
-- Do not add manual portals or call-site z-index escalation. Fix ownership and stacking structure at the shared boundary.
+- Treat an action surface as a state boundary when its input feeds several sibling menus, dialogs, default values, confirmation messages, or mutation parameters. Inject the smallest stable identity or snapshot once; keep the form draft local unless other owners must react to it.
+- Use the [overlay contract] to determine content lifetime and preserve the Root's closing lifecycle. Follow [state ownership] for draft placement and semantic identity; portal placement alone does not locate the state owner.
+- 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.
+- Do not merge dialogs with different loading guards, reset policies, or lifetimes into one discriminated `currentDialog` state merely to reduce atom count.
 
-[overlay guide]: ../../../../web/docs/overlay.md
+[overlay contract]: ../../../../packages/dify-ui/docs/overlays.md
+[state ownership]: state.md

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

@@ -1,6 +1,6 @@
 # Component Ownership And Modules
 
-Read this document when adding, moving, splitting, or refactoring React components or feature modules.
+Read this document when auditing, adding, moving, splitting, or refactoring React components or feature modules.
 
 ## Vertical Modules
 
@@ -12,28 +12,42 @@ Read this document when adding, moving, splitting, or refactoring React componen
 
 ## Component Ownership
 
-- Put state, data access, loading, empty, error, and handlers in the lowest visual owner that uses them.
-- Keep coordination in a parent only when it needs one consistent snapshot or 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.
+- Before declaring state, a query, or a workflow hook in a page or parent, identify the direct descendant branches that consume each returned value.
+- If only one branch consumes a value, declare it in the lowest owner in that branch whose mounted lifetime matches the required persistence. The parent may pass stable identity or the smallest boundary input, but must not own child state merely to construct props.
+- A parent may own a value when it must intentionally survive the local owner's unmount, or when several sibling branches require one live snapshot and the parent genuinely derives or coordinates submission, selection, batch behavior, navigation, lifecycle, loading, or errors. If it only destructures, renames, and forwards fields, it is a switchboard rather than an owner; put the shared workflow in a feature-local state graph so each surface consumes only its named facts and commands. Use a provider only when it becomes the authoritative input, scope, or external-dependency owner.
+- A provider is a real boundary only when it establishes authoritative input, scope/isolation, or a stable external dependency. A provider that calls a large hook and repackages its return value into Context remains a switchboard.
+- A page or feature root may wire route identity, providers, layout, navigation, and genuine cross-surface coordination. It must not call a child-specific state or query hook merely to assemble that child's props.
+- Keep child contracts at the ownership boundary: stable domain identity, a small immutable snapshot, placement options, or named cross-boundary commands. Do not pass an internal state machine as separate `data`, `pending`, `error`, `retry`, `open`, setter, and callback props when the parent does not use them, and do not hide the same fan-out in a props bag or hook result object.
+- Repeated TanStack Query hooks for the same key and input in Client Component siblings under one QueryClient share that cache. Separate Server Component QueryClients do not, so request-level deduplication needs an identified request-local cache or verified framework or transport owner.
+- Treat parent input according to what the child boundary does with it:
+  - If the child only renders or performs a light local decision, pass the snapshot as props. It does not become a new state owner.
+  - If the child builds queries, dialogs, mutations, derivations, commands, or a reset lifecycle around a stable identity or snapshot, give that boundary a feature-local state file. This does not by itself require a new module or directory.
+- Pass stable domain identity or the smallest sufficient action snapshot across boundaries. Do not copy props into atoms merely to avoid passing them, and do not pass raw server data together with separately derived flags for the same concept.
+- One pass-through layer is acceptable for stable identity and placement. It is not permission to relay workflow state and handlers through an unrelated component.
+- Route identity may pass once from a framework route into its feature boundary. If multiple descendants, queries, facts, or commands need it, bridge it into the feature graph and stop passing it as props.
+- A query snapshot may cross once as immutable display input. Query keys, observer methods, retry/loading/error groups, and invalidation mechanics belong to the query surface or feature graph and must not be decomposed into props.
+- Revisit prop forwarding when intermediate components obscure the behavior owner; keep clear data flow rather than introducing shared state merely to avoid passing props.
 - 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
 
+- Prefer reusing or extending the component that already owns an interaction over rebuilding that behavior in a parallel component.
 - 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, close behavior, and mounting. Composition owners handle workflow branches; the closest visual owner handles section branches.
+- 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.
+- Extract components or hooks when they clarify ownership or hide a cohesive implementation; keep logic local when extraction only shortens the file or relocates the same coordination.
 - 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.
+- Keep feature workflows out of shared components: do not encode one feature through many boolean props or import its copy, routes, and API contracts into a generic component. Do not pass pre-rendered fragments merely to avoid assigning the behavior to its owner.
 - 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.
+- Name props and converted data after their domain/API role, preserving traceability to the original contract.
 - 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

@@ -4,9 +4,13 @@ Read this document when a change introduces Effects, navigation side effects, me
 
 ## 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 forms with keyed remounts or surface-entry hydration instead of copying data through Effects.
+- 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.
+- When external synchronization participates in a feature state graph, prefer a small headless runtime controller that reads and writes focused atoms. Do not hide storage, polling, invalidation, and workflow refs in a giant hook that returns a state-and-handler object for another component or provider to redistribute.
+- React state is not an immediate mutex for async serializers, debounce pipelines, migrations, or latest-wins queues because state updates do not synchronously change an in-flight closure. Keep renderable progress in state, but use owner-local refs for immediate locks, active operation identities, and queued latest snapshots; update those refs before awaiting work or scheduling the corresponding state update.
+- A state value and ref may describe one workflow only when their roles are explicit: state renders the external status, while the ref coordinates events between renders. Retire both at the same success, failure, cancellation, identity-change, and unmount boundaries so neither can resurrect stale work.
 
 ## Navigation
 
@@ -17,6 +21,7 @@ Read this document when a change introduces Effects, navigation side effects, me
 ## Runtime Cost
 
 - Move changing state to the smallest consumer before considering memoization. Stable parent content can be lifted and passed as children.
+- When a broad state owner causes unrelated rendering, move the owner or expose a narrower atom/query selector before adding memoization.
 - 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.

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

@@ -2,37 +2,87 @@
 
 Read this document when a change involves Jotai, form drafts, route identity, shared client state, or local persistence.
 
+## Classify State On Two Axes
+
+First identify the owner or source of truth: one component, a parent boundary, URL/framework APIs, TanStack Query, or the feature workflow. Then identify the graph role independently: primitive input, query/mutation node, derived business fact, or workflow command. Finally mark whether any node needs per-instance isolation or reset; this is a lifecycle requirement, not a node type.
+
+A value does not enter the feature state graph solely because it drives an owner-local query or command. It should enter when it participates in shared workflow state: another owner or graph node consumes it, several consumers need one external-source bridge, it feeds reusable business derivation or coordinated writes, or its persistence/isolation must outlive the current owner. Entering the graph does not transfer ownership from URL APIs or Query cache to Jotai.
+
+Once a value enters the graph, represent it in a feature-local Jotai state file by default. Do not leave graph inputs and async nodes inside a component or large custom hook while exporting only the final result through props or Context; that hides the dependency graph instead of modeling it.
+
+Keep values out of the graph when they only affect one component's presentation, are read only at form submission, or are one-off render computations without domain meaning.
+
 ## 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.
+- Use feature-scoped Jotai when siblings need one source of truth, values drive other atoms, a parent input establishes its own state graph, 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.
+- Use Context for an existing authoritative product boundary or stable dependency injection. Do not introduce Context merely to translate a hook result, query observer, or prop fan-out into another large value object.
 
-## Forms
+## Forms And Sessions
 
-- Prefer uncontrolled Dify UI form and field controls when values are only read at submit time. Initialize query-backed defaults with `defaultValue` and keyed remounts.
-- Promote form values to atoms only when another owner reacts to in-progress values, the draft must survive scoped unmounting, or several workflow steps edit the same draft.
+- Follow the [form contract] for field controlledness and the [overlay contract] for Root/content mounting and state lifetime. These primitive contracts also apply when reviewing a consumer.
+- Choose the Web draft owner from the required lifetime. Keep mounted-session drafts in the content owner; start with the lowest shared React owner when another component needs the draft or it must survive unmounting. Use feature-scoped atoms only when their coordination or persistence contract is needed.
+- 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.
 - Keep validation, source priority, fallback behavior, dirty checks, and payload assembly in the workflow that owns submission.
+- Derive booleans, disabled flags, default tabs, and loading labels from current state. Do not mirror one value into competing prop, default, and local sources; controlled state alone is not a competing-source defect.
+- Do not use local state to fake server data or generated contract fields, or connect a feature mock shell to an unrelated API before its actual contract is confirmed.
 
 ## 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.
+- A single consumer should read the owner hook directly. When several consumers, query atoms, or shared derived atoms require route identity, first match the bridge lifetime to the route or surface instance. An unscoped primitive is safe only when the owning store cannot contain two live instances of that bridge; otherwise scope the route primitive by instance. Keep URL writes in route and query-state APIs.
+- A route, framework, or permission bridge that must follow later owner changes should use `dangerouslyForceHydrate: true` at that controlled boundary so descendants observe one synchronous authoritative snapshot. This is the canonical exception to ordinary render-phase write guidance when the hydration tuples contain only those authoritative external inputs and the target store or scope belongs to the current instance. The resulting React warning alone is not an ownership problem, but it must not be used to dismiss cross-instance sharing.
+- A scoped workflow input is different: initialize it once, key the scope by semantic identity when switching entities should reset it, and do not force later parent refreshes into an in-progress session. Never extend the bridge exception to feature-owned primitives, drafts, query or mutation atoms, or edit-session snapshots.
 - 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.
+- A route parameter may cross the route-to-feature entry edge once. After a route bridge exists, queries, facts, commands, and descendant surfaces must read that bridge instead of accepting the same ID as props.
+- Put shareable filters, tabs, selected panels, pagination, and search state in the URL. Keep one-shot navigation signals and transient UI state out of persistent subscriptions.
 
-## Jotai And Query
+## Build A Clean Jotai Graph
 
-- 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.
+- Keep one feature-local state file or folder ordered by dependency: primitives and boundary inputs, query atoms, query-data selectors, business facts, commands, mutation atoms when justified, submission orchestration, then provider exports.
+- Keep graph flow one-way: primitive inputs -> queries -> named facts -> commands. Do not let components maintain a second writable entry for the same fact.
+- Create a derived atom only when its value is reused, consumed by another atom, or deserves a stable business name such as `rows`, `showEmpty`, or `canSubmit`. Leave one-off presentation assembly in the component.
+- Keep internal graph nodes unexported. Export only atoms that a component, provider boundary, or another state module must read or write.
 - 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.
+- Use `selectAtom` or another field-specific derived atom 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. Read the whole result only when the consumer truly needs observer methods or a coordinated group of fields.
+- Name derived atoms as business facts and write atoms as user or workflow commands. Commands should express actions such as selecting a source or submitting a wizard, not merely rename setter callbacks.
+- Treat query keys, observer methods, cache invalidation, retries, and refresh composition as graph internals. Export a named command such as `refreshDocument`, not the query key plus a raw `refetch` callback.
+- A headless runtime controller may synchronize atoms with storage, timers, subscriptions, or other external systems. It should read and write focused graph nodes and render no UI; it must not return a large object for a parent to redistribute.
+
+## Scope, Isolation, And Reset
+
 - 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.
+- `jotai-scope` recursively scopes the dependencies of an explicitly scoped derived or write atom. Review that transitive dependency closure, not only the provider's atom list: scoping a fact or command that reaches a query atom can also privatize route inputs, `queryClientAtom`, and other cache dependencies. Keep query-facing facts and commands outside that scope, or redesign the command to receive the event snapshot it needs instead of reading the query graph.
+- Do not add a derived fact or write command to the scoped list merely because it reads or writes scoped primitives. When consumed inside the scope, an unlisted fact or command can resolve those selected primitive dependencies from the current scope while retaining access to unscoped parent atoms; listing it instead recursively privatizes its dependency closure.
+- Prefer `ScopeProvider` when an instance must isolate selected workflow atoms while retaining access to atoms in the parent application store. A nested `Provider` or `createStore` boundary cuts interoperability with every parent atom, not only `queryClientAtom`; injecting the current QueryClient repairs cache access but does not restore other global state. Use a fresh store only when full-store isolation is intentional, then inject every required external dependency explicitly.
+- Use parent-store interoperation as the boundary test: if descendants must observe application auth, workspace, permissions, cache, or any other parent atom, a fresh `Provider` is not an instance-scope mechanism. Choose it only when the surface intentionally owns a complete store and must not observe later parent-atom updates.
+- For an intentionally unscoped route or parent-input bridge, call `useHydrateAtoms` in the boundary component that returns `ScopeProvider`; hooks read the nearest provider available where that component itself renders. When the bridge requires per-instance isolation, initialize its primitives through the `ScopeProvider` tuples instead. If later authoritative owner changes must follow, render a dedicated hydration bridge beneath that provider so `useHydrateAtoms` resolves the scoped primitives.
+- Use `atomWithLazy` or another non-null lazy primitive for required values injected by a scope provider; fail when the boundary forgot to provide them instead of inventing an empty ID.
+- Maintain the scoped primitive list explicitly. Use a semantic `key` when switching identity should create a fresh session; do not use forced hydration for an edit snapshot that must remain stable while an outer query refreshes.
+- Scope exists for per-instance isolation and natural reset, not as a general module boundary. A state file may be warranted even when its atoms remain unscoped.
 - 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.
 
+## Graph Review Checklist
+
+Before implementation and again after the final slice, draw the actual graph in dependency order and verify:
+
+- every route, URL, parent, and persisted input has one bridge;
+- every query driven by graph input is represented in the graph and remains unscoped;
+- components read field selectors or named facts rather than complete query results;
+- write atoms and exported commands describe user or workflow intent;
+- scoped atoms are limited to primitives and snapshots with a documented reset boundary;
+- the scope still observes required parent/global atom updates, including the application's shared QueryClient;
+- two simultaneously mounted route or surface instances with different identities or URL state do not overwrite each other's bridged primitives or scoped workflow state, and a semantic identity change resets the intended state;
+- no equivalent value remains available through both atoms and descendant props;
+- every exported atom has a real component, boundary, or state-module consumer.
+
 ## 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.
+
+[form contract]: ../../../../packages/dify-ui/docs/forms.md
+[overlay contract]: ../../../../packages/dify-ui/docs/overlays.md

.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

@@ -26,14 +26,34 @@
 /cli/ @GareArc
 /.github/workflows/cli-tests.yml @GareArc
 
+# Dify Agent
+/dify-agent/ @BeautyyuYanli
+
 # E2E
 /e2e/ @lyzno1
+/.github/workflows/web-e2e.yml @lyzno1
 
 # Backend (default owner, more specific rules below will override)
 /api/ @QuantumGhost
 
-# Backend - Tests
+# Backend - Tests (default owners, domain-specific rules below will override)
 /api/tests/ @laipz8200 @QuantumGhost
+/api/tests/*/core/rag/ @JohnJyong
+/api/tests/*/services/rag_pipeline/ @JohnJyong
+/api/tests/*/services/dataset_service/ @JohnJyong
+/api/tests/*/controllers/console/datasets/ @JohnJyong
+/api/tests/*/controllers/service_api/dataset/ @JohnJyong
+/api/tests/*/vdb/ @JohnJyong
+/api/tests/*/core/plugin/ @WH-2099
+/api/tests/*/services/plugin/ @WH-2099
+/api/tests/*/controllers/inner_api/plugin/ @WH-2099
+/api/tests/*/plugin/ @WH-2099
+/api/tests/*/controllers/trigger/ @CourTeous33
+/api/tests/*/core/trigger/ @CourTeous33
+/api/tests/*/trigger/ @CourTeous33
+/api/tests/*/controllers/console/billing/ @zyssyz123
+/api/tests/*/services/enterprise/ @GareArc
+/api/tests/*/migrations/ @snakevash @laipz8200 @MRZHUH
 
 # Backend - RAG (Retrieval Augmented Generation)
 /api/core/rag/ @JohnJyong
@@ -108,8 +128,8 @@
 /api/tasks/async_workflow_tasks.py @Mairuis
 
 # Backend - Billing
-/api/services/billing_service.py @hj24 @zyssyz123
-/api/controllers/console/billing/ @hj24 @zyssyz123
+/api/services/billing_service.py @zyssyz123
+/api/controllers/console/billing/ @zyssyz123
 
 # Backend - Enterprise
 /api/configs/enterprise/ @GareArc
@@ -127,6 +147,12 @@
 # Frontend
 /web/ @iamjoel
 
+# Frontend - Tooling
+/lint.config.ts @hyoban @lyzno1
+/eslint.config.mjs @hyoban @lyzno1
+/knip.config.ts @hyoban @lyzno1
+/vite.config.ts @hyoban @lyzno1
+
 # Frontend - Platform and Features
 /web/config/ @lyzno1
 /web/env.ts @lyzno1
@@ -245,7 +271,7 @@
 
 # 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
@@ -267,5 +293,9 @@
 /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/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: '🕷️ Bug report'
 description: Report errors or unexpected behavior
 labels:
-  - bug
+  - 🐞 bug
 body:
   - type: checkboxes
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,7 @@
 name: '⭐ Feature or enhancement request'
 description: Propose something new.
 labels:
-  - enhancement
+  - 💪 enhancement
 body:
   - type: checkboxes
     attributes:

.github/actions/setup-core-e2e/action.yml

@@ -0,0 +1,29 @@
+name: Setup Core E2E Dependencies
+description: Install API dependencies alongside web dependencies and the selected browser
+
+inputs:
+  browser:
+    description: Browser to install (chromium or webkit)
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Setup web toolchain
+      uses: ./.github/actions/setup-web
+      with:
+        run-install: 'false'
+
+    - name: Setup UV and Python
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      with:
+        enable-cache: true
+        python-version: '3.12'
+        cache-dependency-glob: api/uv.lock
+
+    - name: Install dependencies in parallel
+      shell: bash
+      env:
+        E2E_INSTALL_BROWSER: ${{ inputs.browser }}
+        E2E_SETUP_ACTION_PATH: ${{ github.action_path }}
+      run: bash "$E2E_SETUP_ACTION_PATH/install.sh"

.github/actions/setup-core-e2e/install.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+case "${E2E_INSTALL_BROWSER:-}" in
+  chromium|webkit) ;;
+  *) echo "Expected chromium or webkit" >&2; exit 1 ;;
+esac
+
+# Keep both branches in this step so failures are collected before tests start.
+started=$SECONDS
+timing_dir=$(mktemp -d)
+trap 'rm -rf "$timing_dir"' EXIT
+
+(
+  api_started=$SECONDS
+  uv sync --project api --dev
+  echo "$((SECONDS - api_started))" > "$timing_dir/api"
+) &
+api_pid=$!
+
+(
+  web_started=$SECONDS
+  vp install --frozen-lockfile
+  echo "$((SECONDS - web_started))" > "$timing_dir/web"
+  browser_started=$SECONDS
+  cd e2e
+  vp run "e2e:install:ci:$E2E_INSTALL_BROWSER"
+  echo "$((SECONDS - browser_started))" > "$timing_dir/browser"
+) &
+web_pid=$!
+
+api_status=0
+web_status=0
+wait "$api_pid" || api_status=$?
+wait "$web_pid" || web_status=$?
+
+{
+  echo "### E2E dependency preparation ($E2E_INSTALL_BROWSER)"
+  echo ""
+  echo "Parallel install wall time: $((SECONDS - started))s"
+  echo ""
+  echo "| Phase | Seconds |"
+  echo "| --- | ---: |"
+  for phase in api web browser; do
+    if [[ -f "$timing_dir/$phase" ]]; then
+      echo "| $phase | $(cat "$timing_dir/$phase") |"
+    fi
+  done
+  echo ""
+  echo "API exit status: $api_status; Web/browser exit status: $web_status"
+} >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+
+if (( api_status != 0 || web_status != 0 )); then
+  echo "E2E dependency installation failed (API: $api_status, Web/browser: $web_status)" >&2
+  exit 1
+fi

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

@@ -1,16 +1,29 @@
 name: Setup Web Environment
 description: Set up Node.js, Vite+, pnpm, and web dependencies
 
+inputs:
+  run-install:
+    description: Install web dependencies after setting up the toolchain
+    default: 'true'
+  cache-save:
+    description: Save the dependency cache after the job completes
+    default: 'true'
+
 runs:
   using: composite
   steps:
-    - name: Setup pnpm
-      uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+    - name: Setup pnpm and Node.js
+      uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
       with:
-        run_install: false
+        install: false
     - name: Setup Vite+
-      uses: voidzero-dev/setup-vp@143f5f385f39b1b753ffed1a01ad443811855c8b # v1.16.1
+      uses: voidzero-dev/setup-vp@9fd26ff49f9b5e6276c2b493da4454ad4527f7f4 # v1.20.0
       with:
-        node-version-file: .nvmrc
+        node-manager: false
+        package-manager: |
+          pnpm: false
+          npm: false
         cache: true
-        run-install: true
+        # Nested composite post actions can evaluate inputs in the outer scope.
+        cache-save: ${{ inputs.cache-save || 'true' }}
+        run-install: ${{ inputs.run-install }}

.github/actions/wait-e2e-web-build/action.yml

@@ -0,0 +1,21 @@
+name: Wait for Core E2E Web Build
+description: Wait for the current workflow run's Web build artifact while the producer finishes independently
+
+outputs:
+  artifact-id:
+    description: ID of the ready Web build artifact
+    value: ${{ steps.wait.outputs.result }}
+
+runs:
+  using: composite
+  steps:
+    - name: Wait for build artifact
+      id: wait
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        E2E_WAIT_ACTION_PATH: ${{ github.action_path }}
+      with:
+        result-encoding: string
+        script: |
+          const waitForBuild = require(`${process.env.E2E_WAIT_ACTION_PATH}/wait.cjs`)
+          return await waitForBuild({ github, context, core, runAttempt: Number(process.env.GITHUB_RUN_ATTEMPT) })

.github/actions/wait-e2e-web-build/wait.cjs

@@ -0,0 +1,65 @@
+const { setTimeout: delay } = require('node:timers/promises')
+
+module.exports = async function waitForBuild({
+  github,
+  context,
+  core,
+  runAttempt,
+  now = Date.now,
+  sleep = delay,
+  timeoutMs = 30 * 60 * 1000,
+}) {
+  const started = now()
+  const run = { ...context.repo, run_id: context.runId, per_page: 100 }
+  core.info('Waiting for core-e2e-web-build in this workflow run')
+
+  while (now() - started < timeoutMs) {
+    const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, {
+      ...run,
+      attempt_number: runAttempt,
+    })
+    const producer = jobs.find(
+      (job) =>
+        job.name === 'Prepare Core E2E Web Build' ||
+        job.name.endsWith(' / Prepare Core E2E Web Build'),
+    )
+    if (producer?.status === 'completed' && producer.conclusion !== 'success') {
+      throw new Error(
+        `Web build finished with ${producer.conclusion} before publishing an artifact`,
+      )
+    }
+
+    if (producer && ['in_progress', 'completed'].includes(producer.status)) {
+      const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, run)
+      const upload = producer.steps?.find((step) => step.name === 'Upload Web build')
+      const artifact = artifacts.find((item) => {
+        if (item.expired || !/^core-e2e-web-build-[1-9]\d*$/.test(item.name)) return false
+        if (producer.status === 'in_progress') {
+          // A rebuilding producer must publish this attempt's immutable artifact.
+          return item.name === `core-e2e-web-build-${runAttempt}`
+        }
+        // GitHub relabels reused successful jobs with the current run_attempt.
+        // Their upload step keeps its original timestamps, identifying the artifact
+        // to reuse when only consumers are rerun (including across several attempts).
+        return (
+          upload?.conclusion === 'success' &&
+          item.created_at >= upload.started_at &&
+          item.created_at <= upload.completed_at
+        )
+      })
+      if (artifact) {
+        const seconds = Math.round((now() - started) / 1000)
+        core.info(`Web build artifact ${artifact.name} ready after ${seconds}s`)
+        await core.summary
+          .addHeading('E2E Web build wait')
+          .addRaw(`Artifact wait: ${seconds}s`)
+          .write()
+        return String(artifact.id)
+      }
+    }
+
+    await sleep(Math.min(10000, timeoutMs - (now() - started)))
+  }
+
+  throw new Error('Timed out waiting for core-e2e-web-build in this workflow run')
+}

.github/actions/wait-e2e-web-build/wait.test.cjs

@@ -0,0 +1,164 @@
+const assert = require('node:assert/strict')
+const { test } = require('node:test')
+const waitForBuild = require('./wait.cjs')
+
+function fixture({ artifacts = [], jobs = [producer], error, runAttempt = 2 } = {}) {
+  let elapsed = 0
+  const calls = []
+  const summary = {
+    addHeading() {
+      return this
+    },
+    addRaw() {
+      return this
+    },
+    async write() {},
+  }
+  return {
+    calls,
+    options: {
+      context: { repo: { owner: 'owner', repo: 'repo' }, runId: 123 },
+      core: { info() {}, summary },
+      runAttempt,
+      github: {
+        rest: {
+          actions: { listWorkflowRunArtifacts: 'artifacts', listJobsForWorkflowRunAttempt: 'jobs' },
+        },
+        async paginate(endpoint, params) {
+          calls.push({ endpoint, params })
+          if (error) throw error
+          const values = endpoint === 'artifacts' ? artifacts : jobs
+          return typeof values === 'function' ? values(elapsed) : values
+        },
+      },
+      now: () => elapsed,
+      sleep: async (ms) => {
+        elapsed += ms
+      },
+      timeoutMs: 20000,
+    },
+  }
+}
+
+const producer = {
+  name: 'Run Web Full-Stack E2E / Prepare Core E2E Web Build',
+  status: 'in_progress',
+  run_attempt: 2,
+}
+const artifact = {
+  id: 42,
+  name: 'core-e2e-web-build-2',
+  expired: false,
+  created_at: '2026-09-22T04:08:11Z',
+}
+const oldArtifact = {
+  ...artifact,
+  id: 41,
+  name: 'core-e2e-web-build-1',
+  created_at: '2026-09-22T03:08:11Z',
+}
+const successfulProducer = {
+  ...producer,
+  status: 'completed',
+  conclusion: 'success',
+  steps: [
+    {
+      name: 'Upload Web build',
+      conclusion: 'success',
+      started_at: '2026-09-22T04:08:08Z',
+      completed_at: '2026-09-22T04:08:12Z',
+    },
+  ],
+}
+
+test('starts consuming the current artifact without waiting for producer cache saves', async () => {
+  const { options, calls } = fixture({ artifacts: (elapsed) => (elapsed ? [artifact] : []) })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 10000)
+  assert.deepEqual(
+    calls.map((call) => call.endpoint),
+    ['jobs', 'artifacts', 'jobs', 'artifacts'],
+  )
+  for (const { endpoint, params } of calls) {
+    assert.equal(params.run_id, 123)
+    assert.equal(params.owner, 'owner')
+    assert.equal(params.repo, 'repo')
+    if (endpoint === 'jobs') assert.equal(params.attempt_number, 2)
+  }
+})
+
+test('full reruns ignore the old artifact until the rebuilding producer publishes this attempt', async () => {
+  const { options } = fixture({
+    artifacts: (elapsed) => (elapsed ? [oldArtifact, artifact] : [oldArtifact]),
+  })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 10000)
+})
+
+test('does not use an old artifact before the current producer appears or while it is queued', async () => {
+  const { options } = fixture({
+    artifacts: [oldArtifact],
+    jobs: (elapsed) => (elapsed ? [{ ...producer, status: 'queued' }] : []),
+  })
+  await assert.rejects(waitForBuild(options), /Timed out/)
+})
+
+test('consumer-only reruns reuse the actual successful upload despite a relabeled run_attempt', async () => {
+  const { options } = fixture({
+    runAttempt: 4,
+    artifacts: [oldArtifact, artifact],
+    jobs: [{ ...successfulProducer, run_attempt: 4 }],
+  })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 0)
+})
+
+for (const conclusion of ['failure', 'cancelled', 'skipped']) {
+  test(`does not fall back to an old artifact when the producer finishes with ${conclusion}`, async () => {
+    const { options } = fixture({
+      artifacts: [oldArtifact, artifact],
+      jobs: [{ ...producer, status: 'completed', conclusion }],
+    })
+    await assert.rejects(waitForBuild(options), new RegExp(`Web build finished with ${conclusion}`))
+    assert.equal(options.now(), 0)
+  })
+}
+
+test('ignores unrelated and expired artifacts and stops at the deadline', async () => {
+  const { options } = fixture({
+    artifacts: [
+      { ...artifact, expired: true },
+      { ...artifact, name: 'other' },
+    ],
+  })
+  await assert.rejects(waitForBuild(options), /Timed out/)
+  assert.equal(options.now(), 20000)
+})
+
+test('completed rebuilt producers select their upload instead of the old artifact', async () => {
+  const { options } = fixture({ artifacts: [oldArtifact, artifact], jobs: [successfulProducer] })
+  assert.equal(await waitForBuild(options), '42')
+})
+
+test('allows artifact visibility to catch up after a successful producer finishes', async () => {
+  const { options } = fixture({
+    artifacts: (elapsed) => (elapsed ? [oldArtifact, artifact] : [oldArtifact]),
+    jobs: [successfulProducer],
+  })
+  assert.equal(await waitForBuild(options), '42')
+  assert.equal(options.now(), 10000)
+})
+
+test('does not reuse artifacts without a successful matching upload step', async () => {
+  const { options } = fixture({
+    artifacts: [artifact],
+    jobs: [{ ...successfulProducer, steps: [] }],
+  })
+  await assert.rejects(waitForBuild(options), /Timed out/)
+})
+
+test('reports API errors rather than silently waiting until timeout', async () => {
+  const { options } = fixture({ error: new Error('Resource not accessible by integration') })
+  await assert.rejects(waitForBuild(options), /Resource not accessible/)
+  assert.equal(options.now(), 0)
+})

.github/labeler.yml

@@ -6,7 +6,6 @@ web:
           - 'package.json'
           - 'pnpm-lock.yaml'
           - 'pnpm-workspace.yaml'
-          - '.nvmrc'
 
 e2e:
   - changed-files:

.github/linters/.yaml-lint.yml

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

.github/pull_request_template.md

@@ -1,7 +1,7 @@
 > [!IMPORTANT]
 >
 > 1. Make sure you have read our [contribution guidelines](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md)
-> 1. Ensure there is an associated issue and you have been assigned to it
+> 1. Ensure there is an associated issue
 > 1. Use the correct syntax to link this PR: `Fixes #<issue number>`.
 
 ## Summary
@@ -19,6 +19,6 @@
 
 - [ ] This change requires a documentation update, included: [Dify Document](https://github.com/langgenius/dify-docs)
 - [ ] 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 verified the change and added or updated tests where meaningful regression risk justifies coverage.
 - [ ] 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/generate-i18n-changes.mjs

@@ -8,7 +8,8 @@ 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', 'locales', 'en-US', `${fileStem}.json`)
 
 const readCurrentJson = (fileStem) => {
   const filePath = englishPath(fileStem)
@@ -21,7 +22,7 @@ const readBaseJson = (fileStem) => {
   if (!baseSha) return null
 
   try {
-    const relativePath = `web/i18n/en-US/${fileStem}.json`
+    const relativePath = `web/i18n/locales/en-US/${fileStem}.json`
     const content = execFileSync('git', ['show', `${baseSha}:${relativePath}`], {
       encoding: 'utf8',
     })

.github/scripts/knowledge-deploy-gates.cjs

@@ -0,0 +1,62 @@
+// A workflow_run event is privileged: accept only trusted pushes and the exact tested revision.
+module.exports = async function knowledgeDeployGates({
+  github,
+  context,
+  core,
+  now = Date.now,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+  const source = context.payload.workflow_run
+  const repository = `${context.repo.owner}/${context.repo.repo}`
+  const branch = 'deploy/konwledge'
+  if (
+    source?.event !== 'push' ||
+    source.conclusion !== 'success' ||
+    source.head_branch !== branch ||
+    source.head_repository?.full_name !== repository ||
+    !/^[0-9a-f]{40}$/.test(source.head_sha)
+  ) {
+    throw new Error('Deployment requires a successful trusted branch push.')
+  }
+  const isCurrent = async () => {
+    const { data } = await github.rest.repos.getBranch({ ...context.repo, branch })
+    return data.commit.sha === source.head_sha
+  }
+  const skip = () => {
+    core.info('Skipping a superseded deployment revision.')
+    core.setOutput('current', 'false')
+  }
+  if (!(await isCurrent())) return skip()
+  const deadline = now() + 30 * 60 * 1000
+  while (now() < deadline) {
+    const { data } = await github.rest.actions.listWorkflowRuns({
+      ...context.repo,
+      workflow_id: 'knowledge-fs-ci.yml',
+      branch,
+      event: 'push',
+      head_sha: source.head_sha,
+      per_page: 100,
+    })
+    const run = data.workflow_runs
+      .filter(
+        (candidate) =>
+          candidate.head_sha === source.head_sha &&
+          candidate.head_branch === branch &&
+          candidate.event === 'push' &&
+          candidate.head_repository?.full_name === repository,
+      )
+      .sort((a, b) => b.run_number - a.run_number || b.run_attempt - a.run_attempt)[0]
+    if (run?.status === 'completed') {
+      if (run.conclusion !== 'success')
+        throw new Error(`KnowledgeFS CI did not succeed for ${source.head_sha}: ${run.conclusion}.`)
+      if (!(await isCurrent())) return skip()
+      core.info(`KnowledgeFS CI and image build succeeded for ${source.head_sha}.`)
+      core.setOutput('current', 'true')
+      return
+    }
+    if (!(await isCurrent())) return skip()
+    core.info(`Waiting for KnowledgeFS CI at ${source.head_sha}.`)
+    await sleep(15000)
+  }
+  throw new Error(`Timed out waiting for KnowledgeFS CI for ${source.head_sha}.`)
+}

.github/scripts/knowledge-deploy-gates.test.cjs

@@ -0,0 +1,128 @@
+const assert = require('node:assert/strict')
+const test = require('node:test')
+const gate = require('./knowledge-deploy-gates.cjs')
+const sha = 'a'.repeat(40)
+const otherSha = 'b'.repeat(40)
+function fixture() {
+  const source = {
+    event: 'push',
+    conclusion: 'success',
+    head_branch: 'deploy/konwledge',
+    head_repository: { full_name: 'langgenius/dify' },
+    head_sha: sha,
+  }
+  let time = 0
+  let branchSha = sha
+  let runs = [{ ...source, status: 'completed', run_number: 2, run_attempt: 1 }]
+  const outputs = {}
+  const requests = []
+  return {
+    source,
+    outputs,
+    requests,
+    setRuns: (value) => {
+      runs = value
+    },
+    setBranch: (value) => {
+      branchSha = value
+    },
+    args: {
+      context: { repo: { owner: 'langgenius', repo: 'dify' }, payload: { workflow_run: source } },
+      github: {
+        rest: {
+          repos: { getBranch: async () => ({ data: { commit: { sha: branchSha } } }) },
+          actions: {
+            listWorkflowRuns: async (request) => {
+              requests.push(request)
+              return { data: { workflow_runs: runs } }
+            },
+          },
+        },
+      },
+      core: {
+        info: () => {},
+        setOutput: (key, value) => {
+          outputs[key] = value
+        },
+      },
+      now: () => time,
+      sleep: async (ms) => {
+        time += ms
+      },
+    },
+  }
+}
+test('only a successful CI run from the same branch, repo, event, and SHA admits deployment', async () => {
+  const f = fixture()
+  await gate(f.args)
+  assert.equal(f.outputs.current, 'true')
+  assert.equal(f.requests[0].head_sha, sha)
+  assert.equal(f.requests[0].workflow_id, 'knowledge-fs-ci.yml')
+})
+for (const [name, mutation] of [
+  ['pull request', { event: 'pull_request' }],
+  ['failed build', { conclusion: 'failure' }],
+  ['foreign branch', { head_branch: 'main' }],
+  ['foreign repo', { head_repository: { full_name: 'attacker/fork' } }],
+  ['invalid revision', { head_sha: 'main' }],
+])
+  test(`rejects ${name} workflow events before any API query`, async () => {
+    const f = fixture()
+    Object.assign(f.source, mutation)
+    await assert.rejects(gate(f.args), /trusted branch push/)
+    assert.deepEqual(f.requests, [])
+  })
+for (const conclusion of ['failure', 'cancelled', 'skipped', 'timed_out', 'neutral'])
+  test(`CI ${conclusion} fails closed`, async () => {
+    const f = fixture()
+    f.setRuns([{ ...f.source, status: 'completed', conclusion }])
+    await assert.rejects(gate(f.args), /did not succeed/)
+    assert.notEqual(f.outputs.current, 'true')
+  })
+for (const mutation of [
+  { head_sha: otherSha },
+  { head_branch: 'main' },
+  { event: 'pull_request' },
+  { head_repository: { full_name: 'attacker/fork' } },
+])
+  test(`ignores unrelated successful CI run ${JSON.stringify(mutation)}`, async () => {
+    const f = fixture()
+    f.setRuns([{ ...f.source, ...mutation, status: 'completed' }])
+    await assert.rejects(gate(f.args), /Timed out/)
+    assert.notEqual(f.outputs.current, 'true')
+  })
+test('latest failed attempt cannot be hidden by an earlier successful run', async () => {
+  const f = fixture()
+  f.setRuns([
+    { ...f.source, status: 'completed', run_number: 1, run_attempt: 1 },
+    { ...f.source, status: 'completed', run_number: 2, run_attempt: 1, conclusion: 'failure' },
+  ])
+  await assert.rejects(gate(f.args), /did not succeed/)
+})
+test('stale revision skips without waiting or deploying', async () => {
+  const f = fixture()
+  f.setBranch(otherSha)
+  await gate(f.args)
+  assert.equal(f.outputs.current, 'false')
+  assert.deepEqual(f.requests, [])
+})
+test('branch advancing during CI wait prevents deployment', async () => {
+  const f = fixture()
+  f.setRuns([{ ...f.source, status: 'in_progress' }])
+  f.args.sleep = async () => {
+    f.setBranch(otherSha)
+    f.setRuns([{ ...f.source, status: 'completed' }])
+  }
+  await gate(f.args)
+  assert.equal(f.outputs.current, 'false')
+})
+test('running CI is awaited before reporting success', async () => {
+  const f = fixture()
+  f.setRuns([])
+  f.args.sleep = async () => {
+    f.setRuns([{ ...f.source, status: 'completed' }])
+  }
+  await gate(f.args)
+  assert.equal(f.outputs.current, 'true')
+  assert.equal(f.requests.length, 2)
+})

.github/scripts/size-labeler.test.cjs

@@ -0,0 +1,94 @@
+const fs = require('node:fs')
+const assert = require('node:assert/strict')
+const test = require('node:test')
+const source = fs.readFileSync(
+  require('node:path').join(__dirname, '../workflows/size-labeler.yml'),
+  'utf8',
+)
+const script = source
+  .replace(/\r\n/g, '\n')
+  .split('          script: |\n')[1]
+  .split('\n')
+  .map((l) => l.replace(/^            /, ''))
+  .join('\n')
+const run = new (Object.getPrototypeOf(async function () {}).constructor)(
+  'github',
+  'context',
+  'core',
+  script,
+)
+async function scenario(files, existing = [], changed = files.length) {
+  const calls = []
+  const warnings = []
+  const api = {
+    pulls: {
+      get: async () => ({ data: { changed_files: changed } }),
+      listFiles: 'files',
+    },
+    issues: {
+      listLabelsOnIssue: 'labels',
+      addLabels: async (p) => calls.push(['add', p.labels[0]]),
+      removeLabel: async (p) => calls.push(['remove', p.name]),
+    },
+  }
+  await run(
+    {
+      rest: api,
+      paginate: async (endpoint) =>
+        endpoint === 'files' ? files : existing.map((name) => ({ name })),
+    },
+    {
+      repo: { owner: 'test', repo: 'repo' },
+      payload: { pull_request: { number: 1 } },
+    },
+    { warning: (s) => warnings.push(s) },
+  )
+  return { calls, warnings }
+}
+for (const [n, label] of [
+  [0, 'XS'],
+  [9, 'XS'],
+  [10, 'S'],
+  [29, 'S'],
+  [30, 'M'],
+  [99, 'M'],
+  [100, 'L'],
+  [499, 'L'],
+  [500, 'XL'],
+  [999, 'XL'],
+  [1000, 'XXL'],
+]) {
+  test(`threshold ${n}`, async () =>
+    assert.deepEqual((await scenario([{ filename: 'a.py', additions: n, deletions: 0 }])).calls, [
+      ['add', `size:${label}`],
+    ]))
+}
+test('count deletions', async () =>
+  assert.deepEqual((await scenario([{ filename: 'a.py', additions: 0, deletions: 30 }])).calls, [
+    ['add', 'size:M'],
+  ]))
+test('ignore nested lockfiles', async () =>
+  assert.deepEqual(
+    (
+      await scenario([
+        { filename: 'api/uv.lock', additions: 9000, deletions: 5 },
+        { filename: 'web/pnpm-lock.yaml', additions: 5000, deletions: 0 },
+      ])
+    ).calls,
+    [['add', 'size:XS']],
+  ))
+test('replace stale size only', async () =>
+  assert.deepEqual(
+    (await scenario([{ filename: 'a.py', additions: 10, deletions: 0 }], ['size:L', 'bug', 'web']))
+      .calls,
+    [
+      ['add', 'size:S'],
+      ['remove', 'size:L'],
+    ],
+  ))
+test('idempotent', async () => assert.deepEqual((await scenario([], ['size:XS', 'bug'])).calls, []))
+test('incomplete file list', async () => {
+  const r = await scenario([], ['size:L'], 3001)
+  assert.deepEqual(r.calls, [])
+  assert.equal(r.warnings.length, 1)
+})

.github/workflows/accessibility-e2e.yml

@@ -36,7 +36,7 @@ concurrency:
 jobs:
   accessibility:
     name: WCAG Level ${{ inputs.level == 'a' && 'A' || 'AA' }} · ${{ inputs.page }}
-    runs-on: depot-ubuntu-24.04-4
+    runs-on: ubuntu-24.04
     timeout-minutes: 120
     defaults:
       run:
@@ -52,7 +52,7 @@ jobs:
         uses: ./.github/actions/setup-web
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'
@@ -80,7 +80,7 @@ jobs:
           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"
+            pnpm exec node ./scripts/run-cucumber.ts --full -- --tags "@axe and @wcag-${{ inputs.level }} and @wcag-page-$WCAG_PAGE"
           fi
 
       - name: Upload accessibility Cucumber report

.github/workflows/api-tests.yml

@@ -14,28 +14,79 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  api-unit-plan:
+    name: Plan API unit shards
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: '3.12'
+          enable-cache: false
+      - name: Download shared timing baseline
+        # Public statistics are independent of PR refs and require no credentials.
+        run: |
+          if ! curl --fail --silent --show-error --location \
+            --connect-timeout 5 --max-time 15 --retry 2 --retry-max-time 30 \
+            https://raw.githubusercontent.com/langgenius/dify-test-infra/generated-stats/stats/test-times.json \
+            --output unit-test-durations.json; then
+            rm -f unit-test-durations.json
+            echo '::warning::Timing baseline unavailable; using round-robin file allocation.'
+          fi
+      - name: Freeze file assignments for every shard
+        run: |
+          uv run --project api --no-sync python api/dev/pytest_sharding.py \
+            --shard-index 1 --shard-total 2 \
+            --durations unit-test-durations.json \
+            --write-plan unit-test-plan.json \
+            --split-threshold 60 \
+            --ignore api/tests/unit_tests/controllers \
+            api/tests/unit_tests \
+            api/providers/vdb/*/tests/unit_tests \
+            api/providers/trace/*/tests/unit_tests
+      - name: Upload shared plan
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-unit-plan
+          path: |
+            unit-test-plan.json
+            unit-test-durations.json
+          retention-days: 7
+          if-no-files-found: error
+
   api-unit:
-    name: API Unit Tests
+    needs: api-unit-plan
+    name: API Unit Tests (${{ matrix.python-version }}, shard ${{ matrix.shardIndex }}/${{ matrix.shardTotal }})
     runs-on: depot-ubuntu-24.04
     env:
-      COVERAGE_FILE: coverage-unit
+      PYTHONUNBUFFERED: '1'
+      COVERAGE_FILE: coverage-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
     defaults:
       run:
         shell: bash
     strategy:
+      fail-fast: false
       matrix:
         python-version:
           - '3.12'
+        shardIndex:
+          - 1
+          - 2
+        shardTotal:
+          - 2
 
     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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -47,34 +98,116 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
+      - name: Download shared plan
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: api-unit-plan
+
       - name: Run Unit Tests
         run: |
+          uv run --project api python api/dev/pytest_sharding.py \
+            --plan unit-test-plan.json \
+            --shard-index "${{ matrix.shardIndex }}" \
+            --shard-total "${{ matrix.shardTotal }}" \
+            --ignore api/tests/unit_tests/controllers \
+            api/tests/unit_tests \
+            api/providers/vdb/*/tests/unit_tests \
+            api/providers/trace/*/tests/unit_tests > "$RUNNER_TEMP/unit-test-files.txt"
           uv run --project api pytest \
             -p no:benchmark \
             --timeout "${PYTEST_TIMEOUT:-20}" \
             -n auto \
-            api/tests/unit_tests \
-            api/providers/vdb/*/tests/unit_tests \
-            api/providers/trace/*/tests/unit_tests \
-            --ignore=api/tests/unit_tests/controllers
-          # Controller tests register Flask routes at import time, so keep them out of xdist.
-          uv run --project api pytest \
-            --timeout "${PYTEST_TIMEOUT:-20}" \
-            --cov-append \
-            api/tests/unit_tests/controllers
+            -o 'addopts=--cov=./api --cov-branch --import-mode=importlib' \
+            --cov-report= \
+            --file-shard-plan unit-test-plan.json \
+            --shard-index "${{ matrix.shardIndex }}" \
+            --shard-total "${{ matrix.shardTotal }}" \
+            --write-test-durations "test-results/durations-${{ matrix.shardIndex }}.json" \
+            --junitxml=test-results/unit.xml \
+            "@$RUNNER_TEMP/unit-test-files.txt"
+
+      - name: Upload unit test reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-test-results-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
+          path: test-results/*.xml
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Upload successful timing observations
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-unit-durations-${{ matrix.shardIndex }}
+          path: test-results/durations-*.json
+          retention-days: 7
+          if-no-files-found: error
 
       - name: Upload unit coverage data
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: api-coverage-unit
-          path: coverage-unit
+          name: api-coverage-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
+          retention-days: 1
+
+  api-controllers:
+    name: API Controller Tests (3.12)
+    runs-on: depot-ubuntu-24.04
+    env:
+      PYTHONUNBUFFERED: '1'
+      COVERAGE_FILE: coverage-controllers-3.12
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: api/uv.lock
+
+      - name: Check UV lockfile
+        run: uv lock --project api --check
+
+      - name: Install dependencies
+        run: uv sync --project api --dev
+
+      - name: Run Controller Tests
+        # Controller tests register Flask routes at import time, so keep them out of xdist.
+        run: |
+          uv run --project api pytest \
+            --timeout "${PYTEST_TIMEOUT:-20}" \
+            -o 'addopts=--cov=./api --cov-branch --import-mode=importlib' \
+            --cov-report= \
+            --junitxml=test-results/controllers.xml \
+            api/tests/unit_tests/controllers
+
+      - name: Upload controller test reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-test-results-controllers-3.12
+          path: test-results/*.xml
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Upload controller coverage data
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-coverage-controllers-3.12
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
           retention-days: 1
 
   api-integration:
-    name: API Integration Tests
-    runs-on: depot-ubuntu-24.04
+    name: API Integration Tests (${{ matrix.python-version }})
+    runs-on: depot-ubuntu-24.04-4
     env:
-      COVERAGE_FILE: coverage-integration
+      COVERAGE_FILE: coverage-integration-${{ matrix.python-version }}
       STORAGE_TYPE: opendal
       OPENDAL_SCHEME: fs
       OPENDAL_FS_ROOT: /tmp/dify-storage
@@ -82,6 +215,7 @@ jobs:
       run:
         shell: bash
     strategy:
+      fail-fast: false
       matrix:
         python-version:
           - '3.12'
@@ -90,11 +224,10 @@ jobs:
       - 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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -111,7 +244,10 @@ jobs:
           uv run --project api pytest \
             -p no:benchmark \
             --start-middleware \
+            --middleware-stop-timeout 2 \
             -n auto \
+            -o 'addopts=--cov=./api --cov-branch --import-mode=importlib' \
+            --cov-report= \
             --timeout "${PYTEST_TIMEOUT:-180}" \
             api/tests/integration_tests/workflow \
             api/tests/integration_tests/tools \
@@ -120,8 +256,9 @@ jobs:
       - name: Upload integration coverage data
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: api-coverage-integration
-          path: coverage-integration
+          name: api-coverage-integration-${{ matrix.python-version }}
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
           retention-days: 1
 
   api-coverage:
@@ -129,6 +266,7 @@ jobs:
     runs-on: depot-ubuntu-24.04
     needs:
       - api-unit
+      - api-controllers
       - api-integration
     env:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
@@ -141,18 +279,12 @@ jobs:
       - 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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
-          enable-cache: true
           python-version: '3.12'
-          cache-dependency-glob: api/uv.lock
-
-      - name: Install dependencies
-        run: uv sync --project api --dev
 
       - name: Download coverage data
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -164,35 +296,48 @@ jobs:
       - name: Combine coverage
         run: |
           set -euo pipefail
+          coverage_version=$(python3 -c 'import tomllib; print(next(p["version"] for p in tomllib.load(open("api/uv.lock", "rb"))["package"] if p["name"] == "coverage"))')
 
-          echo "### API Coverage" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "Merged backend coverage report generated for Codecov project status." >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
+          mapfile -t unit_coverage < <(find coverage-data -type f -name 'coverage-unit-*' -print | sort)
+          mapfile -t controller_coverage < <(find coverage-data -type f -name 'coverage-controllers-*' -print | sort)
+          mapfile -t integration_coverage < <(find coverage-data -type f -name 'coverage-integration-*' -print | sort)
+          if [[ "${#unit_coverage[@]}" -ne 2 ]]; then
+            echo "expected 2 unit coverage artifacts, found ${#unit_coverage[@]}" >&2
+            exit 1
+          fi
+          if [[ "${#controller_coverage[@]}" -ne 1 ]]; then
+            echo "expected 1 controller coverage artifact, found ${#controller_coverage[@]}" >&2
+            exit 1
+          fi
+          if [[ "${#integration_coverage[@]}" -ne 1 ]]; then
+            echo "expected 1 integration coverage artifact, found ${#integration_coverage[@]}" >&2
+            exit 1
+          fi
 
-          unit_coverage="$(find coverage-data -type f -name coverage-unit -print -quit)"
-          integration_coverage="$(find coverage-data -type f -name coverage-integration -print -quit)"
-          : "${unit_coverage:?coverage-unit artifact not found}"
-          : "${integration_coverage:?coverage-integration artifact not found}"
+          uvx --from "coverage==$coverage_version" coverage combine "${unit_coverage[@]}" "${controller_coverage[@]}" "${integration_coverage[@]}"
+          uvx --from "coverage==$coverage_version" coverage xml -o coverage.xml
 
-          report_file="$(mktemp)"
-          uv run --project api coverage combine "$unit_coverage" "$integration_coverage"
-          uv run --project api coverage report --show-missing | tee "$report_file"
-          echo "Summary: \`$(tail -n 1 "$report_file")\`" >> "$GITHUB_STEP_SUMMARY"
-          {
-            echo ""
-            echo "<details><summary>Coverage report</summary>"
-            echo ""
-            echo '```'
-            cat "$report_file"
-            echo '```'
-            echo "</details>"
-          } >> "$GITHUB_STEP_SUMMARY"
-          uv run --project api coverage xml -o coverage.xml
+          # Reuse the XML totals instead of analyzing every source file again for a text report.
+          python3 - <<'PY'
+          import os
+          import xml.etree.ElementTree as ET
+
+          coverage = ET.parse("coverage.xml").getroot()
+          with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as summary:
+              summary.write("### API Coverage\n\n")
+              summary.write("Merged backend coverage report generated for Codecov project status.\n\n")
+              summary.write("| Metric | Covered | Total | Coverage |\n")
+              summary.write("| --- | ---: | ---: | ---: |\n")
+              for label, metric in (("Lines", "lines"), ("Branches", "branches")):
+                  covered = int(coverage.attrib[f"{metric}-covered"])
+                  total = int(coverage.attrib[f"{metric}-valid"])
+                  percentage = f"{covered / total:.2%}" if total else "N/A"
+                  summary.write(f"| {label} | {covered} | {total} | {percentage} |\n")
+              summary.write("\nSee Codecov for per-file coverage details.\n")
+          PY
 
       - name: Report coverage
-        if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           files: ./coverage.xml
           disable_search: true

.github/workflows/autofix.yml

@@ -5,8 +5,6 @@ on:
   merge_group:
     branches: ['main']
     types: [checks_requested]
-  push:
-    branches: ['main']
 permissions:
   contents: read
 
@@ -32,28 +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/**
-            cli/**
-            e2e/**
-            packages/**
-            sdks/nodejs-client/**
-            package.json
-            pnpm-lock.yaml
-            pnpm-workspace.yaml
-            .nvmrc
-            vite.config.ts
-            lint.config.ts
-            eslint.config.mjs
-            oxlint-suppressions.json
-            eslint-suppressions.json
-            .vscode/**
-            .github/**
       - name: Check api inputs
         if: github.event_name != 'merge_group'
         id: api-changes
@@ -82,13 +58,13 @@ jobs:
             dify-agent/**/*.py
             dify-agent/pyproject.toml
             dify-agent/uv.lock
-      - if: github.event_name != 'merge_group'
+      - 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'
 
-      - if: github.event_name != 'merge_group'
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.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@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 
       - name: Generate Docker Compose
         if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'
@@ -118,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: |
@@ -155,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
@@ -168,13 +138,5 @@ jobs:
         if: github.event_name != 'merge_group' && steps.frontend-contract-changes.outputs.any_changed == 'true'
         run: pnpm --dir packages/contracts gen-api-contract
 
-      - name: ESLint fallback autofix
-        if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'
-        run: pnpm lint:eslint:fix --quiet || true
-
-      - name: Vite+ static autofix
-        if: github.event_name != 'merge_group' && (steps.web-changes.outputs.any_changed == 'true' || steps.frontend-contract-changes.outputs.any_changed == 'true')
-        run: vp check --fix || true
-
       - if: github.event_name != 'merge_group'
         uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4

.github/workflows/build-push.yml

@@ -103,7 +103,7 @@ jobs:
           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
@@ -160,10 +160,10 @@ jobs:
             file: 'docker/Dockerfile'
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Validate Docker image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           push: false
           context: ${{ matrix.build_context }}
@@ -229,3 +229,38 @@ 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: Use Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: package.json
+          cache: ''
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - 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

@@ -87,10 +87,9 @@ jobs:
         with:
           bun-version: latest
 
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+      - uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
         with:
-          package_json_field: packageManager
-          run_install: false
+          install: false
 
       - name: Install CLI dependencies
         working-directory: cli
@@ -112,7 +111,7 @@ jobs:
   # ════════════════════════════════════════════════════════════════════════════
   suite-framework-output-error:
     name: 'Suite: framework + output + error-handling'
-    if: ${{ inputs.suite_framework_output_error != 'false' }}
+    if: ${{ inputs.suite_framework_output_error }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -129,10 +128,8 @@ jobs:
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        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
+        with:
+          bun-version: latest
       - run: pnpm tree:gen
 
       - name: Run framework + output + error-handling
@@ -159,7 +156,7 @@ jobs:
   # ════════════════════════════════════════════════════════════════════════════
   suite-discovery:
     name: 'Suite: discovery'
-    if: ${{ inputs.suite_discovery != 'false' }}
+    if: ${{ inputs.suite_discovery }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -176,10 +173,8 @@ jobs:
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        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
+        with:
+          bun-version: latest
       - run: pnpm tree:gen
 
       - name: Run discovery suite
@@ -207,7 +202,7 @@ jobs:
   # ════════════════════════════════════════════════════════════════════════════
   suite-run:
     name: 'Suite: run / ${{ matrix.name }}'
-    if: ${{ inputs.suite_run != 'false' }}
+    if: ${{ inputs.suite_run }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -239,10 +234,8 @@ jobs:
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        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
+        with:
+          bun-version: latest
       - run: pnpm tree:gen
 
       - name: 'Run run/${{ matrix.name }}'
@@ -284,7 +277,7 @@ jobs:
   # ════════════════════════════════════════════════════════════════════════════
   suite-auth-safe:
     name: 'Suite: auth (login / status / whoami)'
-    if: ${{ inputs.suite_auth != 'false' }}
+    if: ${{ inputs.suite_auth }}
     needs: provision
     runs-on: ubuntu-latest
     timeout-minutes: 15
@@ -301,10 +294,8 @@ jobs:
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        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
+        with:
+          bun-version: latest
       - run: pnpm tree:gen
 
       - name: Run auth/login + status + whoami
@@ -333,7 +324,7 @@ jobs:
   suite-last:
     name: 'Suite: auth-use + devices + logout + agent (last, serial)'
     # Runs when auth is selected; also runs after all parallel jobs finish
-    if: ${{ inputs.suite_auth != 'false' || inputs.suite_agent != 'false' }}
+    if: ${{ inputs.suite_auth || inputs.suite_agent }}
     needs:
       - provision
       - suite-framework-output-error
@@ -357,10 +348,8 @@ jobs:
 
       - uses: ./.github/actions/setup-web
       - uses: oven-sh/setup-bun@v2
-        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
+        with:
+          bun-version: latest
       - run: pnpm tree:gen
 
       - name: Run use / devices / logout / agent (serial)

.github/workflows/cli-edge.yml

@@ -2,10 +2,11 @@ name: CLI Edge Publish
 
 on:
   push:
-    branches: [main]
+    branches: [main, deploy/konwledge]
     paths:
       - 'cli/**'
       - 'packages/contracts/generated/api/openapi/**'
+      - '.github/workflows/cli-edge.yml'
   workflow_dispatch:
 
 concurrency:

.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]
 
@@ -39,11 +49,8 @@ jobs:
         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
@@ -120,6 +118,7 @@ jobs:
 
       - 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

@@ -51,7 +51,7 @@ jobs:
 
       - name: Run smoke against live dify
         working-directory: ./cli
-        run: pnpm exec tsx scripts/run-smoke.ts --base-url http://localhost:5001
+        run: pnpm exec node scripts/run-smoke.ts --base-url http://localhost:5001
 
       - name: Dump dify logs on failure
         if: failure()

.github/workflows/cli-tests.yml

@@ -44,14 +44,14 @@ 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 (tree, coverage, build)
         run: pnpm run ci
 
       - name: Report coverage
         if: ${{ env.CODECOV_TOKEN != '' && matrix.os == 'depot-ubuntu-24.04' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           directory: cli/coverage
           flags: cli

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

@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'
@@ -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@b659c744ee9bed25aea2307c017ad849bd104433 # v3.2.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -69,7 +69,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'
@@ -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@b659c744ee9bed25aea2307c017ad849bd104433 # v3.2.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml

.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

@@ -7,65 +7,72 @@ permissions:
 on:
   workflow_run:
     workflows: ['Build and Push API & Web']
-    branches:
-      - 'deploy/konwledge'
-    types:
-      - completed
+    branches: ['deploy/konwledge']
+    types: [completed]
+
+# A second workflow used to deploy the same server after KnowledgeFS CI. This is the single
+# Dify deployment owner; the independent KnowledgeFS release retains its own deployment lock.
+concurrency:
+  group: deploy-knowledge-dify-test
+  cancel-in-progress: false
 
 jobs:
   deploy:
     runs-on: depot-ubuntu-24.04
+    timeout-minutes: 340
     if: |
+      github.event.workflow_run.event == 'push' &&
       github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.head_branch == 'deploy/konwledge'
+      github.event.workflow_run.head_branch == 'deploy/konwledge' &&
+      github.event.workflow_run.head_repository.full_name == github.repository
     steps:
-      - name: Wait for KnowledgeFS CI
+      - name: Checkout tested deployment gates
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          persist-credentials: false
+          sparse-checkout: .github/scripts
+
+      - name: Require same-revision KnowledgeFS CI and current branch head
+        id: gates
         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;
+            await require('./.github/scripts/knowledge-deploy-gates.cjs')({ github, context, core });
 
-            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
+      - name: Deploy tested Dify revision while preserving KnowledgeFS
+        if: steps.gates.outputs.current == 'true'
         uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          EXPECTED_DIFY_REVISION: ${{ github.event.workflow_run.head_sha }}
+          DEPLOY_DIR: /home/ubuntu/langgenius
         with:
           host: ${{ secrets.SSH_NEW_RAG_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_PRIVATE_KEY }}
+          # Allow the shared deployment lock and Celery warm shutdown to finish.
+          command_timeout: 300m
+          envs: EXPECTED_DIFY_REVISION,DEPLOY_DIR
           script: |
-            ${{ vars.SSH_SCRIPT || secrets.SSH_SCRIPT }}
+            set -euo pipefail
+            [[ "$EXPECTED_DIFY_REVISION" =~ ^[0-9a-f]{40}$ ]] || {
+              echo 'Expected a full tested Dify revision.' >&2; exit 1;
+            }
+            # Verify the installed bridge forwards revision arguments before invoking it. Never
+            # overwrite an operator's custom entrypoint or fall back to an unverified script.
+            python3 - "$DEPLOY_DIR" <<'PY'
+            import shlex
+            import sys
+            from pathlib import Path
+
+            project = Path(sys.argv[1]).resolve()
+            controller = project / 'knowledge-fs-independent-deploy.py'
+            expected = ('#!/usr/bin/env bash\nset -euo pipefail\nexec python3 ' +
+                        shlex.quote(str(controller)) + ' --dify --project-dir ' +
+                        shlex.quote(str(project)) + ' "$@"\n')
+            if not controller.is_file() or (project / 'deploy.sh').read_text() != expected:
+                raise SystemExit('Expected the installed KnowledgeFS-preserving Dify release bridge.')
+            PY
+            "$DEPLOY_DIR/deploy.sh" --expected-revision "$EXPECTED_DIFY_REVISION"

.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@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        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

@@ -65,7 +65,7 @@ jobs:
             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
@@ -96,10 +96,10 @@ jobs:
             file: 'docker/Dockerfile'
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Build Docker Image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           push: false
           context: ${{ matrix.context }}

.github/workflows/image-resources.yml

@@ -0,0 +1,39 @@
+name: Image optimization
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  image-resources:
+    name: Image optimization
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up workspace toolchain
+        uses: ./.github/actions/setup-web
+        with:
+          run-install: 'false'
+
+      - name: Install image checker dependencies
+        run: pnpm --filter @dify/image-resources... install --frozen-lockfile --ignore-scripts
+
+      - name: Type-check image checker
+        run: pnpm --filter @dify/image-resources type-check
+
+      - name: Test image checker
+        run: pnpm --filter @dify/image-resources test
+
+      - name: Check image optimization
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          pnpm --filter @dify/image-resources check:images --base "$BASE_SHA"

.github/workflows/knowledge-fs-ci.yml

@@ -0,0 +1,532 @@
+name: KnowledgeFS CI
+
+on:
+  pull_request:
+    branches: ['main']
+  merge_group:
+    branches: ['main']
+    types: [checks_requested]
+  push:
+    branches: ['main', 'deploy/konwledge']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: knowledge-fs-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CI: true
+
+jobs:
+  check-changes:
+    name: Check KnowledgeFS changes
+    runs-on: depot-ubuntu-24.04-4
+    outputs:
+      knowledge-fs: ${{ steps.changes.outputs.knowledge-fs }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Detect KnowledgeFS changes
+        id: changes
+        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
+        with:
+          filters: |
+            knowledge-fs:
+              - 'api/knowledge-fs-contract/**'
+              - 'api/tests/knowledge_fs_vector_integration/**'
+              - 'api/services/tidb_binding_service.py'
+              - 'api/tests/unit_tests/services/test_tidb_binding_service.py'
+              - 'api/providers/vdb/vdb-tidb-on-qdrant/**'
+              - 'api/Dockerfile'
+              - 'api/dev/generate_knowledge_fs_contract.py'
+              - 'api/dev/knowledge_fs_product_contract.py'
+              - 'api/knowledge-fs-contract.lock.json'
+              - 'api/knowledge-fs-product-operation-gaps.json'
+              - 'api/knowledge-fs-product-operations.json'
+              - 'api/**/knowledge_fs/**'
+              - 'api/**/*knowledge_fs*'
+              - 'api/**/*knowledge-fs*'
+              - 'api/.env.example'
+              - 'api/app_factory.py'
+              - 'api/commands/__init__.py'
+              - 'api/controllers/console/__init__.py'
+              - 'api/controllers/console/workspace/rbac.py'
+              - 'api/controllers/inner_api/__init__.py'
+              - 'api/controllers/service_api/__init__.py'
+              - 'api/core/agent/base_agent_runner.py'
+              - 'api/core/app/apps/agent_app/runtime_request_builder.py'
+              - 'api/core/rbac/entities.py'
+              - 'api/core/tools/__base/tool_runtime.py'
+              - 'api/core/tools/builtin_tool/_position.yaml'
+              - 'api/core/workflow/node_runtime.py'
+              - 'api/core/workflow/nodes/agent_v2/runtime_request_builder.py'
+              - 'api/extensions/ext_celery.py'
+              - 'api/extensions/ext_commands.py'
+              - 'api/models/__init__.py'
+              - 'api/models/enums.py'
+              - 'api/models/model.py'
+              - 'api/services/account_service.py'
+              - 'api/services/agent_tool_inner_service.py'
+              - 'api/services/enterprise/rbac_service.py'
+              - 'api/services/entities/agent_tool_inner.py'
+              - 'api/services/vector_space_admission_service.py'
+              - 'api/services/knowledge_fs/**'
+              - 'api/services/knowledge_fs_capability.py'
+              - 'api/tests/unit_tests/dev/test_generate_knowledge_fs_contract.py'
+              - 'api/tests/unit_tests/controllers/console/workspace/test_rbac.py'
+              - 'api/tests/unit_tests/core/agent/test_base_agent_runner.py'
+              - 'api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py'
+              - 'api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py'
+              - 'api/tests/unit_tests/core/workflow/nodes/tool/test_tool_node_runtime.py'
+              - 'api/tests/unit_tests/core/workflow/test_node_runtime.py'
+              - 'api/tests/unit_tests/services/enterprise/test_rbac_service.py'
+              - 'api/tests/unit_tests/services/test_account_service.py'
+              - 'api/tests/unit_tests/services/test_agent_tool_inner_service.py'
+              - 'api/tests/unit_tests/services/test_vector_space_admission_service.py'
+              - 'api/tests/unit_tests/services/test_knowledge_fs_capability.py'
+              - 'api/tests/unit_tests/services/test_knowledge_fs_product_operations.py'
+              - 'api/pyproject.toml'
+              - 'api/uv.lock'
+              - 'dify-agent/src/dify_agent/layers/dify_core_tools/client.py'
+              - 'dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_client.py'
+              - 'packages/contracts/generated/api/console/**'
+              - 'packages/contracts/generated/api/service/**'
+              - 'docker/.env.example'
+              - 'docker/README.md'
+              - 'docker/dify-env-sync.py'
+              - 'docker/dify-env-sync.sh'
+              - 'docker/docker-compose-template.yaml'
+              - 'docker/docker-compose.yaml'
+              - 'docker/envs/core-services/api.env.example'
+              - 'docker/envs/core-services/knowledge-fs.env.example'
+              - 'docker/envs/core-services/knowledge-fs-unstructured-service.defaults'
+              - 'docker/envs/core-services/knowledge-fs-unstructured.env.example'
+              - 'docker/knowledge-fs-unstructured-sandbox.compose.yaml'
+              - 'docker/generate_docker_compose'
+              - 'docs/design/knowledge-fs*'
+              - '.github/dependabot.yml'
+              - '.github/workflows/deploy-knowledge.yml'
+              - '.github/workflows/deploy-dev.yml'
+              - '.github/scripts/knowledge-deploy-*'
+              - '.github/workflows/knowledge-fs-ci.yml'
+
+  quality:
+    name: Run KnowledgeFS quality and contract gates
+    needs: check-changes
+    if: needs.check-changes.outputs.knowledge-fs == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: .
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node for deployment gate regression tests
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+
+      - name: Test deployment revision gates
+        run: node --test .github/scripts/knowledge-deploy-gates.test.cjs
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: |
+            api/uv.lock
+            dify-agent/uv.lock
+
+      - name: Verify Dify dependency lock
+        working-directory: .
+        run: uv lock --project api --check
+
+      - name: Install Dify contract dependencies
+        working-directory: .
+        run: uv sync --project api --locked --dev --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant
+
+      # The standalone KnowledgeFS repository owns TypeScript, parser, image and deployment gates.
+      # This repository verifies its immutable published contract and all Dify integration code.
+      - name: Verify pinned KnowledgeFS contract
+        run: uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant python api/dev/generate_knowledge_fs_contract.py --check
+
+      - name: Collect Dify KnowledgeFS gate targets
+        working-directory: .
+        run: |
+          set -euo pipefail
+
+          target_dir="${RUNNER_TEMP:?}/knowledge-fs-ci-targets"
+          mkdir -p "$target_dir"
+
+          production_targets=()
+          add_production_target() {
+            local path="$1"
+            if [[ ! -f "$path" ]]; then
+              echo "required Dify KnowledgeFS production target is missing: $path" >&2
+              exit 1
+            fi
+            production_targets+=("$path")
+          }
+
+          while IFS= read -r -d '' path; do
+            if [[ "$path" == *knowledge_fs* ]]; then
+              add_production_target "$path"
+            fi
+          done < <(
+            find api \
+              \( -path 'api/.venv' -o -path 'api/tests' -o -path 'api/storage' \) -prune \
+              -o -type f -name '*.py' -print0
+          )
+
+          production_touchpoints=(
+            api/app_factory.py
+            api/commands/__init__.py
+            api/controllers/console/__init__.py
+            api/controllers/console/datasets/datasets.py
+            api/controllers/console/workspace/rbac.py
+            api/controllers/inner_api/__init__.py
+            api/controllers/service_api/__init__.py
+            api/core/agent/base_agent_runner.py
+            api/core/app/apps/agent_app/runtime_request_builder.py
+            api/core/rbac/entities.py
+            api/core/tools/__base/tool_runtime.py
+            api/core/workflow/node_runtime.py
+            api/core/workflow/nodes/agent_v2/runtime_request_builder.py
+            api/extensions/ext_celery.py
+            api/extensions/ext_commands.py
+            api/models/__init__.py
+            api/models/enums.py
+            api/models/model.py
+            api/services/account_service.py
+            api/services/agent_tool_inner_service.py
+            api/services/enterprise/rbac_service.py
+            api/services/entities/agent_tool_inner.py
+            api/services/vector_space_admission_service.py
+            api/services/tidb_binding_service.py
+            api/providers/vdb/vdb-tidb-on-qdrant/src/dify_vdb_tidb_on_qdrant/tidb_service.py
+            api/providers/vdb/vdb-tidb-on-qdrant/src/dify_vdb_tidb_on_qdrant/tidb_on_qdrant_vector.py
+          )
+          for path in "${production_touchpoints[@]}"; do
+            add_production_target "$path"
+          done
+          printf '%s\0' "${production_touchpoints[@]}" > "$target_dir/glue-files"
+
+          if ((${#production_targets[@]} == 0)); then
+            echo "Dify KnowledgeFS production target set is empty" >&2
+            exit 1
+          fi
+          printf '%s\0' "${production_targets[@]}" > "$target_dir/production-files"
+
+          test_targets=()
+          add_test_target() {
+            local path="$1"
+            if [[ ! -f "$path" ]]; then
+              echo "required Dify KnowledgeFS unit test is missing: $path" >&2
+              exit 1
+            fi
+            test_targets+=("$path")
+          }
+
+          while IFS= read -r -d '' path; do
+            if [[ "$path" == *knowledge_fs* ]]; then
+              add_test_target "$path"
+            fi
+          done < <(find api/tests/unit_tests -type f -name '*.py' -print0)
+
+          test_touchpoints=(
+            api/tests/unit_tests/controllers/console/datasets/test_datasets.py
+            api/tests/unit_tests/controllers/console/test_wraps.py
+            api/tests/unit_tests/controllers/console/workspace/test_rbac.py
+            api/tests/unit_tests/core/agent/test_base_agent_runner.py
+            api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
+            api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
+            api/tests/unit_tests/core/workflow/nodes/tool/test_tool_node_runtime.py
+            api/tests/unit_tests/core/workflow/test_node_runtime.py
+            api/tests/unit_tests/services/enterprise/test_rbac_service.py
+            api/tests/unit_tests/services/test_account_service.py
+            api/tests/unit_tests/services/test_agent_tool_inner_service.py
+            api/tests/unit_tests/services/test_vector_space_admission_service.py
+            api/tests/unit_tests/services/test_tidb_binding_service.py
+          )
+          for path in "${test_touchpoints[@]}"; do
+            add_test_target "$path"
+          done
+
+          required_test_scopes=(
+            /commands/
+            /configs/
+            /controllers/
+            /core/agent/
+            /core/app/apps/agent_app/
+            /core/tools/builtin_tool/providers/knowledge_fs/
+            /core/workflow/
+            /dev/
+            /extensions/
+            /migrations/
+            /models/
+            /repositories/
+            /services/
+            /tasks/
+          )
+          for required_scope in "${required_test_scopes[@]}"; do
+            scope_found=false
+            for path in "${test_targets[@]}"; do
+              if [[ "$path" == *"$required_scope"* ]]; then
+                scope_found=true
+                break
+              fi
+            done
+            if [[ "$scope_found" != true ]]; then
+              echo "required Dify KnowledgeFS test scope is empty: $required_scope" >&2
+              exit 1
+            fi
+          done
+
+          if ((${#test_targets[@]} == 0)); then
+            echo "Dify KnowledgeFS unit test target set is empty" >&2
+            exit 1
+          fi
+          printf '%s\0' "${test_targets[@]}" > "$target_dir/unit-test-files"
+
+      - name: Lint Dify KnowledgeFS integration
+        working-directory: .
+        run: |
+          set -euo pipefail
+          targets=()
+          while IFS= read -r -d '' path; do
+            targets+=("$path")
+          done < "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/production-files"
+          if ((${#targets[@]} == 0)); then
+            echo "Dify KnowledgeFS production target manifest is empty" >&2
+            exit 1
+          fi
+          uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant --dev ruff format --check "${targets[@]}"
+          uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant --dev ruff check "${targets[@]}"
+
+      - name: Type-check Dify KnowledgeFS integration
+        working-directory: .
+        run: |
+          set -euo pipefail
+          targets=()
+          while IFS= read -r -d '' path; do
+            targets+=("$path")
+          done < "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/production-files"
+          if ((${#targets[@]} == 0)); then
+            echo "Dify KnowledgeFS production target manifest is empty" >&2
+            exit 1
+          fi
+          UV_NO_SYNC=1 PYREFLY_OUTPUT_FORMAT=github ./dev/pyrefly-check-local "${targets[@]}"
+
+          mypy_targets=()
+          for path in "${targets[@]}"; do
+            if [[ "$path" != api/migrations/* ]]; then
+              mypy_targets+=("${path#api/}")
+            fi
+          done
+          if ((${#mypy_targets[@]} == 0)); then
+            echo "Dify KnowledgeFS Mypy target set is empty" >&2
+            exit 1
+          fi
+          uv run --directory api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant --dev mypy \
+            --explicit-package-bases \
+            --exclude-gitignore \
+            --exclude '(^|/)conftest\.py$' \
+            --exclude 'tests/' \
+            --exclude 'migrations/' \
+            --check-untyped-defs \
+            --disable-error-code=import-untyped \
+            "${mypy_targets[@]}"
+
+      - name: Test Dify KnowledgeFS unit surface
+        working-directory: .
+        env:
+          COVERAGE_FILE: ${{ runner.temp }}/dify-knowledge-fs.coverage
+        run: |
+          set -euo pipefail
+          targets=()
+          while IFS= read -r -d '' path; do
+            targets+=("$path")
+          done < "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/unit-test-files"
+          if ((${#targets[@]} == 0)); then
+            echo "Dify KnowledgeFS unit test target manifest is empty" >&2
+            exit 1
+          fi
+          uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant --dev coverage run --branch --source=api -m pytest "${targets[@]}" --no-cov -q
+
+      - name: Enforce Dify KnowledgeFS focused coverage
+        working-directory: .
+        env:
+          COVERAGE_FILE: ${{ runner.temp }}/dify-knowledge-fs.coverage
+          KNOWLEDGE_FS_COVERAGE_BASE: >-
+            ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before || '' }}
+        run: |
+          set -euo pipefail
+          report="${RUNNER_TEMP:?}/dify-knowledge-fs-coverage.json"
+          coverage_base="$KNOWLEDGE_FS_COVERAGE_BASE"
+          if [[ "$GITHUB_EVENT_NAME" == 'push' && "$GITHUB_REF" == 'refs/heads/deploy/konwledge' ]]; then
+            latest_merge="$(git rev-list --first-parent --merges --max-count=1 "${coverage_base}..HEAD")"
+            if [[ -n "$latest_merge" ]]; then
+              # Mainline syncs are already gated on main; cover deployment-branch
+              # changes made after the newest sync instead of the merged diff.
+              coverage_base="$latest_merge"
+            fi
+          fi
+          uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant --dev coverage json --show-contexts -o "$report"
+          uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant --dev python api/dev/check_knowledge_fs_coverage.py \
+            --coverage-json "$report" \
+            --glue-manifest "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/glue-files" \
+            --base "$coverage_base" \
+            --minimum 90 \
+            --glue-minimum 90
+
+      - name: Verify Dify KnowledgeFS contract
+        working-directory: .
+        run: uv run --project api --group vdb-qdrant --group vdb-elasticsearch --group vdb-weaviate --group vdb-tidb-on-qdrant python api/dev/generate_knowledge_fs_contract.py --check
+
+      - name: Verify Dify Agent dependency lock
+        working-directory: .
+        run: uv lock --project dify-agent --check
+
+      - name: Install Dify Agent gate dependencies
+        working-directory: .
+        run: uv sync --project dify-agent --locked --dev
+
+      - name: Lint Dify Agent KnowledgeFS integration
+        working-directory: ./dify-agent
+        run: |
+          uv run --project . --dev ruff format --check \
+            src/dify_agent/layers/dify_core_tools/client.py \
+            tests/local/dify_agent/layers/dify_core_tools/test_client.py
+          uv run --project . --dev ruff check \
+            src/dify_agent/layers/dify_core_tools/client.py \
+            tests/local/dify_agent/layers/dify_core_tools/test_client.py
+
+      - name: Type-check Dify Agent KnowledgeFS integration
+        working-directory: ./dify-agent
+        run: >-
+          uv run --project . --dev pyrefly check --summary=none
+          src/dify_agent/layers/dify_core_tools/client.py
+          tests/local/dify_agent/layers/dify_core_tools/test_client.py
+
+      - name: Test Dify Agent KnowledgeFS integration
+        working-directory: ./dify-agent
+        run: >-
+          uv run --project . --dev python -m pytest
+          tests/local/dify_agent/layers/dify_core_tools/test_client.py
+          -q
+
+  skip:
+    name: Skip KnowledgeFS quality and contract gates
+    needs: check-changes
+    if: needs.check-changes.outputs.knowledge-fs != 'true' && github.event_name != 'workflow_dispatch'
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Report skipped KnowledgeFS checks
+        run: echo "No KnowledgeFS-related changes detected; skipping KnowledgeFS checks."
+
+  final:
+    name: KnowledgeFS CI
+    if: ${{ always() }}
+    needs:
+      - check-changes
+      - quality
+      - vector-backends
+      - skip
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Finalize KnowledgeFS CI status
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          KNOWLEDGE_FS_CHANGED: ${{ needs.check-changes.outputs.knowledge-fs }}
+          QUALITY_RESULT: ${{ needs.quality.result }}
+          VECTOR_RESULT: ${{ needs.vector-backends.result }}
+          SKIP_RESULT: ${{ needs.skip.result }}
+        run: |
+          if [[ "$EVENT_NAME" == 'workflow_dispatch' || "$KNOWLEDGE_FS_CHANGED" == 'true' ]]; then
+            if [[ "$QUALITY_RESULT" == 'success' && "$VECTOR_RESULT" == 'success' ]]; then
+              echo "Dify KnowledgeFS contract and integration checks ran successfully."
+              exit 0
+            fi
+
+            echo "Dify KnowledgeFS integration checks failed: quality=$QUALITY_RESULT vectors=$VECTOR_RESULT" >&2
+            exit 1
+          fi
+
+          if [[ "$SKIP_RESULT" == 'success' ]]; then
+            echo "KnowledgeFS checks were skipped because no related files changed."
+            exit 0
+          fi
+
+          echo "KnowledgeFS change detection or skip reporting failed with result: $SKIP_RESULT" >&2
+          exit 1
+
+  vector-backends:
+    name: Test native KnowledgeFS vector backends
+    needs: check-changes
+    if: needs.check-changes.outputs.knowledge-fs == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: depot-ubuntu-24.04-4
+    services:
+      elasticsearch:
+        image: docker.elastic.co/elasticsearch/elasticsearch:8.14.3
+        env:
+          discovery.type: single-node
+          xpack.security.enabled: 'false'
+          ES_JAVA_OPTS: '-Xms512m -Xmx512m'
+        ports:
+          - 9200:9200
+        options: >-
+          --health-cmd "curl -fsS http://localhost:9200/_cluster/health"
+          --health-interval 10s --health-timeout 5s --health-retries 30
+      weaviate:
+        image: cr.weaviate.io/semitechnologies/weaviate:1.39.2
+        env:
+          AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
+          PERSISTENCE_DATA_PATH: /var/lib/weaviate
+          DEFAULT_VECTORIZER_MODULE: none
+          CLUSTER_HOSTNAME: node1
+        ports:
+          - 8080:8080
+          - 50051:50051
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          python-version: '3.12'
+          cache-dependency-glob: api/uv.lock
+      - name: Install native vector SDKs
+        run: uv sync --project api --locked --dev --group vdb-elasticsearch --group vdb-weaviate
+      - name: Wait for Weaviate readiness
+        run: |
+          for attempt in $(seq 1 60); do
+            if curl -fsS http://localhost:8080/v1/.well-known/ready; then exit 0; fi
+            sleep 2
+          done
+          exit 1
+      - name: Exercise real write, retry, filtered search, isolation and deletion
+        env:
+          KNOWLEDGE_FS_VECTOR_INTEGRATION: '1'
+          DEPLOYMENT_EDITION: COMMUNITY
+          ELASTICSEARCH_HOST: localhost
+          ELASTICSEARCH_PORT: '9200'
+          WEAVIATE_ENDPOINT: http://localhost:8080
+          WEAVIATE_GRPC_ENDPOINT: grpc://localhost:50051
+        run: >-
+          uv run --project api --no-sync pytest
+          api/tests/knowledge_fs_vector_integration --no-cov -q

.github/workflows/main-ci.yml

@@ -15,8 +15,10 @@ permissions:
   statuses: write
 
 concurrency:
-  group: main-ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha || 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:
@@ -35,8 +37,6 @@ jobs:
   # Check which paths were changed to determine which tests to run
   check-changes:
     name: Check Changed Files
-    needs: pre_job
-    if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: depot-ubuntu-24.04
     outputs:
       api-changed: ${{ steps.changes.outputs.api }}
@@ -46,6 +46,12 @@ jobs:
       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 }}
+      python-style-changed: ${{ steps.changes.outputs.python-style }}
+      dify-agent-style-changed: ${{ steps.changes.outputs.dify-agent-style }}
+      web-style-changed: ${{ steps.changes.outputs.web-style }}
+      ts-common-style-changed: ${{ steps.changes.outputs.ts-common-style }}
+      superlinter-changed: ${{ steps.changes.outputs.superlinter }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
@@ -79,7 +85,6 @@ jobs:
               - 'pnpm-workspace.yaml'
               - 'lint.config.ts'
               - '.npmrc'
-              - '.nvmrc'
               - '.github/workflows/cli-tests.yml'
               - '.github/actions/setup-web/**'
             web:
@@ -88,26 +93,26 @@ 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:
               - 'api/**'
-              - 'api/pyproject.toml'
-              - 'api/uv.lock'
               - 'e2e/**'
               - 'web/**'
               - 'packages/**'
               - 'package.json'
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
-              - '.nvmrc'
               - 'docker/docker-compose.middleware.yaml'
               - 'docker/envs/middleware.env.example'
+              - 'docker/ssrf_proxy/**'
+              - 'docker/volumes/sandbox/conf/**'
               - '.github/workflows/web-e2e.yml'
               - '.github/workflows/main-ci.yml'
               - '.github/actions/setup-web/**'
+              - '.github/actions/setup-core-e2e/**'
+              - '.github/actions/wait-e2e-web-build/**'
             vdb:
               - 'api/core/rag/datasource/**'
               - 'api/tests/integration_tests/vdb/**'
@@ -136,6 +141,9 @@ jobs:
             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'
@@ -147,6 +155,62 @@ jobs:
               - 'docker/generate_docker_compose'
               - 'docker/ssrf_proxy/**'
               - 'docker/volumes/sandbox/conf/**'
+            python-style:
+              - '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'
+            dify-agent-style:
+              - 'dify-agent/**'
+              - '.github/workflows/style.yml'
+              - '.github/workflows/main-ci.yml'
+            web-style:
+              - 'web/**'
+              - 'e2e/**'
+              - 'sdks/nodejs-client/**'
+              - 'packages/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'knip.config.ts'
+              - 'scripts/check-web-production-unused-after-knip-fix.mjs'
+              - '.npmrc'
+              - '.github/workflows/main-ci.yml'
+              - '.github/workflows/web-bundle-size.yml'
+              - '.github/workflows/style.yml'
+              - '.github/actions/setup-web/**'
+            ts-common-style:
+              - 'web/**'
+              - 'cli/**'
+              - 'e2e/**'
+              - 'sdks/nodejs-client/**'
+              - 'packages/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'tsconfig.json'
+              - 'vite.config.ts'
+              - 'lint.config.ts'
+              - 'eslint.config.mjs'
+              - 'knip.config.ts'
+              - 'scripts/check-web-production-unused-after-knip-fix.mjs'
+              - 'oxlint-suppressions.json'
+              - 'eslint-suppressions.json'
+              - '.vscode/**'
+              - '.github/**'
+            superlinter:
+              - '**.sh'
+              - '**.yaml'
+              - '**.yml'
+              - '**Dockerfile'
+              - 'dev/**'
+              - '.editorconfig'
+              - '.vite-hooks/**'
 
   # Run tests in parallel while always emitting stable required checks.
   api-tests-run:
@@ -393,11 +457,20 @@ jobs:
 
   style-check:
     name: Style Check
-    needs: pre_job
-    if: needs.pre_job.outputs.should_skip != 'true'
+    if: ${{ always() }}
+    needs:
+      - pre_job
+      - check-changes
     uses: ./.github/workflows/style.yml
     with:
       base-rev: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha }}
+      classification-succeeded: ${{ needs.check-changes.result == 'success' }}
+      run-python-style: ${{ needs.check-changes.outputs.python-style-changed == 'true' }}
+      run-dify-agent-style: ${{ needs.check-changes.outputs.dify-agent-style-changed == 'true' }}
+      run-web-style: ${{ needs.check-changes.outputs.web-style-changed == 'true' }}
+      run-ts-common-style: ${{ needs.check-changes.outputs.ts-common-style-changed == 'true' }}
+      run-superlinter: ${{ needs.check-changes.outputs.superlinter-changed == 'true' }}
+      skip-checks: ${{ needs.pre_job.outputs.should_skip == 'true' }}
 
   vdb-tests-run:
     name: Run VDB Tests
@@ -576,3 +649,63 @@ jobs:
 
           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

@@ -36,15 +36,15 @@ jobs:
               - 'e2e/package.json'
               - 'e2e/test-env.ts'
               - 'e2e/tsconfig.json'
-              - 'e2e/tsx-register.js'
               - 'package.json'
               - 'pnpm-lock.yaml'
-              - '.nvmrc'
               - '.github/workflows/post-merge.yml'
               - '.github/workflows/web-e2e.yml'
               - '.github/actions/setup-web/**'
               - 'docker/docker-compose.middleware.yaml'
               - 'docker/envs/middleware.env.example'
+              - 'docker/ssrf_proxy/**'
+              - 'docker/volumes/sandbox/conf/**'
               - 'dify-agent/**'
               - 'dify-agent-runtime/**'
               - 'api/pyproject.toml'
@@ -54,12 +54,30 @@ jobs:
               - 'api/core/app/apps/agent_app/**'
               - 'api/core/workflow/nodes/agent_v2/**'
               - 'api/controllers/console/agent/**'
+              - 'api/controllers/console/app/agent*.py'
+              - 'api/controllers/console/app/audio.py'
+              - 'api/controllers/common/agent_access.py'
+              - 'api/controllers/inner_api/agent/**'
+              - 'api/controllers/inner_api/wraps.py'
+              - 'api/controllers/service_api/app/completion.py'
+              - 'api/controllers/service_api/wraps.py'
+              - 'api/controllers/web/completion.py'
+              - 'api/controllers/web/wraps.py'
+              - 'api/services/agent_llm_inner_service.py'
+              - 'api/services/agent_tool_inner_service.py'
+              - 'api/services/audio_service.py'
+              - 'api/services/entities/agent_llm_inner.py'
+              - 'api/services/entities/agent_tool_inner.py'
+              - 'api/services/errors/agent_tool_inner.py'
               - 'api/services/agent/**'
               - 'api/core/plugin/**'
               - 'api/services/plugin/**'
               - 'api/core/tools/**'
               - 'api/services/tools/**'
               - 'packages/contracts/package.json'
+              - 'packages/contracts/console.ts'
+              - 'packages/contracts/generated/api/console/router.gen.ts'
+              - 'packages/contracts/generated/api/web/**'
               - 'packages/contracts/generated/api/console/agent/**'
               - 'packages/contracts/generated/api/console/apps/**'
               - 'packages/contracts/generated/api/console/datasets/**'
@@ -67,20 +85,27 @@ jobs:
               - '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/\(commonLayout\)/agents/**'
+              - 'web/app/\(commonLayout\)/@detailSidebar/agents/**'
+              - 'web/app/\(shareLayout\)/chat/**'
+              - 'web/app/\(shareLayout\)/components/**'
+              - 'web/app/components/base/chat/chat-with-history/**'
               - 'web/app/components/base/chat/chat/**'
               - 'web/app/components/base/voice-input/**'
+              - 'web/app/components/workflow/index.tsx'
+              - 'web/app/components/workflow/block-selector/**'
+              - 'web/app/components/workflow/hooks/use-node-keyboard-interactions.ts'
+              - 'web/app/components/workflow/hooks/use-nodes-interactions.ts'
+              - 'web/app/components/workflow/hooks/use-nodes-sync-draft.ts'
+              - 'web/app/components/workflow/nodes/_base/**'
               - 'web/app/components/workflow/nodes/agent-v2/**'
-              - 'web/i18n/en-US/agent-v-2.json'
-              - 'web/i18n/en-US/common.json'
+              - 'web/i18n/locales/en-US/agent-v-2.json'
+              - 'web/i18n/locales/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/console/**'
               - 'web/service/share.ts'
+              - 'web/service/use-share.ts'
+              - 'web/service/webapp-address.ts'
               - 'web/package.json'
               - 'pnpm-workspace.yaml'
 
@@ -88,6 +113,9 @@ jobs:
     name: External Runtime E2E
     needs: check-changes
     if: needs.check-changes.outputs.external-e2e-changed == 'true'
+    permissions:
+      actions: read
+      contents: read
     uses: ./.github/workflows/web-e2e.yml
     with:
       run-external-runtime: true

.github/workflows/pyrefly-diff.yml

@@ -22,7 +22,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
 

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

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
 

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

@@ -22,7 +22,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Python & UV
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
 

.github/workflows/size-labeler.yml

@@ -0,0 +1,55 @@
+name: Pull Request Size Labeler
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, ready_for_review, edited]
+
+permissions:
+  pull-requests: write
+
+concurrency:
+  group: size-labeler-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  label:
+    runs-on: depot-ubuntu-24.04
+    steps:
+      # Only read PR metadata. Never check out or execute the PR's code here.
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo
+            const issue_number = context.payload.pull_request.number
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: issue_number })
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner, repo, pull_number: issue_number, per_page: 100,
+            })
+            // GitHub caps this endpoint at 3,000 files; avoid labeling a partial count.
+            if (files.length !== pr.changed_files) {
+              core.warning('Skipping size label because the changed-file list is incomplete')
+              return
+            }
+            const ignoredNames = new Set(['uv.lock', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'])
+            const changes = files
+              .filter(file => !ignoredNames.has(file.filename.split('/').pop()))
+              .reduce((total, file) => total + file.additions + file.deletions, 0)
+            // Match the descriptions of the repository's existing size labels.
+            const buckets = [
+              [10, 'size:XS'], [30, 'size:S'], [100, 'size:M'],
+              [500, 'size:L'], [1000, 'size:XL'], [Infinity, 'size:XXL'],
+            ]
+            const label = buckets.find(([limit]) => changes < limit)[1]
+            const sizeLabels = new Set(buckets.map(([, name]) => name))
+            const labels = await github.paginate(github.rest.issues.listLabelsOnIssue, {
+              owner, repo, issue_number, per_page: 100,
+            })
+            // Add first so an API error cannot leave the PR without a size label.
+            if (!labels.some(item => item.name === label)) {
+              await github.rest.issues.addLabels({ owner, repo, issue_number, labels: [label] })
+            }
+            for (const item of labels) {
+              if (sizeLabels.has(item.name) && item.name !== label) {
+                await github.rest.issues.removeLabel({ owner, repo, issue_number, name: item.name })
+              }
+            }

.github/workflows/style.yml

@@ -6,6 +6,35 @@ on:
       base-rev:
         required: true
         type: string
+      classification-succeeded:
+        description: Whether the caller successfully classified the changed files.
+        required: true
+        type: boolean
+      run-python-style:
+        description: Run Python style checks for the changed files.
+        required: true
+        type: boolean
+      run-dify-agent-style:
+        description: Run Dify Agent style checks for the changed files.
+        required: true
+        type: boolean
+      run-web-style:
+        description: Run Web style checks for the changed files.
+        required: true
+        type: boolean
+      run-ts-common-style:
+        description: Run shared TypeScript style checks for the changed files.
+        required: true
+        type: boolean
+      run-superlinter:
+        description: Run SuperLinter for the changed files.
+        required: true
+        type: boolean
+      skip-checks:
+        description: Create the required check runs without repeating previously successful work.
+        required: false
+        type: boolean
+        default: false
 
 permissions:
   checks: write
@@ -15,70 +44,82 @@ permissions:
 jobs:
   python-style:
     name: Python Style
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-python-style || inputs.run-dify-agent-style) }}
     runs-on: depot-ubuntu-24.04
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        run: |
+          echo "Changed-file classification failed; refusing to skip Python style checks." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: false
           python-version: '3.12'
-          cache-dependency-glob: api/uv.lock
+          cache-dependency-glob: |
+            api/uv.lock
+            dify-agent/uv.lock
 
       - name: Install dependencies
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv sync --project api --dev
 
       - name: Run Import Linter
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv run --directory api --dev lint-imports
 
       - name: Run Response Contract Linter
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         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'
+        if: inputs.run-python-style
         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'
+        if: inputs.run-python-style
         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'
+        if: inputs.run-python-style
         env:
           PYREFLY_OUTPUT_FORMAT: github
         run: make type-check-core
 
+      - name: Run Dify Agent Ruff
+        if: inputs.run-dify-agent-style
+        run: make -C dify-agent check
+
+      - name: Run Dify Agent Type Checks
+        if: inputs.run-dify-agent-style
+        run: make -C dify-agent typecheck
+
       - name: Dotenv check
-        if: steps.changed-files.outputs.any_changed == 'true'
+        if: inputs.run-python-style
         run: uv run --project api dotenv-linter ./api/.env.example ./web/.env.example
 
-  web-style:
-    name: Web Style
+  web-build:
+    name: Web Build and Bundle Analysis
+    if: ${{ !inputs.skip-checks && inputs.classification-succeeded && inputs.run-web-style }}
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/web-bundle-size.yml
+    with:
+      base-rev: ${{ inputs.base-rev }}
+
+  web-style-checks:
+    name: Web Static Checks
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-web-style) }}
     runs-on: depot-ubuntu-24.04
     defaults:
       run:
@@ -88,131 +129,114 @@ jobs:
       pull-requests: read
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        working-directory: .
+        run: |
+          echo "Changed-file classification failed; refusing to skip Web style checks." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            web/**
-            e2e/**
-            sdks/nodejs-client/**
-            packages/**
-            package.json
-            pnpm-lock.yaml
-            pnpm-workspace.yaml
-            knip.config.ts
-            scripts/check-web-production-unused-after-knip-fix.mjs
-            .nvmrc
-            .github/workflows/style.yml
-            .github/actions/setup-web/**
-
       - name: Setup web environment
-        if: steps.changed-files.outputs.any_changed == 'true'
         uses: ./.github/actions/setup-web
 
+      - name: Check generated i18n types
+        run: vp run i18n:check-types
+
       - name: Web tsslint
-        if: steps.changed-files.outputs.any_changed == 'true'
         env:
           NODE_OPTIONS: --max-old-space-size=4096
         run: vp run lint:tss
 
       - name: Web dead code check
-        if: steps.changed-files.outputs.any_changed == 'true'
         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
 
+  # Preserve the existing required check while build and static checks run in parallel.
+  web-style:
+    name: Web Style
+    if: ${{ always() && !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-web-style) }}
+    needs: [web-build, web-style-checks]
+    runs-on: ubuntu-24.04
+    permissions: {}
+    steps:
+      - name: Verify web checks
+        env:
+          BUILD_RESULT: ${{ needs.web-build.result }}
+          STYLE_RESULT: ${{ needs.web-style-checks.result }}
+        run: |
+          if [[ "$BUILD_RESULT" != 'success' || "$STYLE_RESULT" != 'success' ]]; then
+            echo "Web checks failed: build=$BUILD_RESULT, static checks=$STYLE_RESULT" >&2
+            exit 1
+          fi
+
   ts-common-style:
     name: TS Common
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-ts-common-style) }}
     runs-on: depot-ubuntu-24.04-4
     permissions:
       checks: write
       pull-requests: read
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        run: |
+          echo "Changed-file classification failed; refusing to skip TypeScript style checks." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            web/**
-            cli/**
-            e2e/**
-            sdks/nodejs-client/**
-            packages/**
-            package.json
-            pnpm-lock.yaml
-            pnpm-workspace.yaml
-            .nvmrc
-            vite.config.ts
-            lint.config.ts
-            eslint.config.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: Static check
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: pnpm -w check
+        run: vp run -w check
 
   superlinter:
     name: SuperLinter
+    if: ${{ !inputs.skip-checks && (!inputs.classification-succeeded || inputs.run-superlinter) }}
     runs-on: depot-ubuntu-24.04
 
     steps:
+      - name: Verify changed-file classification
+        if: ${{ !inputs.classification-succeeded }}
+        run: |
+          echo "Changed-file classification failed; refusing to skip SuperLinter." >&2
+          exit 1
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: Check changed files
-        id: changed-files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            **.sh
-            **.yaml
-            **.yml
-            **Dockerfile
-            dev/**
-            .editorconfig
-
       - name: Super-linter
         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

@@ -31,7 +31,7 @@ jobs:
       - name: Use Node.js
         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
@@ -65,7 +69,7 @@ jobs:
             /supported: true/ && value != \"en-US\" {
               printf \"%s \", value
             }
-          " web/i18n-config/languages.ts | sed 's/[[:space:]]*$//')
+          " web/i18n/languages.ts | sed 's/[[:space:]]*$//')
 
           generate_changes_json() {
             node .github/scripts/generate-i18n-changes.mjs
@@ -106,9 +110,9 @@ jobs:
             elif [ "$SYNC_MODE" = "incremental" ]; then
               BASE_SHA=$(git rev-parse HEAD~1 2>/dev/null || true)
               if [ -n "$BASE_SHA" ]; then
-                CHANGED_FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/en-US/*.json' 2>/dev/null | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+                CHANGED_FILES=$(git diff --name-only --find-renames=100% --diff-filter=AMDT "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/' 2>/dev/null | sed -n '\@^web/i18n/locales/en-US/[^/]*\.json$@p' | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
               else
-                CHANGED_FILES=$(find web/i18n/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+                CHANGED_FILES=$(find web/i18n/locales/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
               fi
             elif [ "$SYNC_MODE" = "full" ]; then
               echo "workflow_dispatch full mode requires the files input to stay within CI limits." >&2
@@ -158,7 +162,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@c038e4dcdedfbbca18dfb17df35a17e40ded4ddc # v1.0.186
+        uses: anthropics/claude-code-action@4036a180cf690f49529f5d8c79c998855287f590 # v1.0.230
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -166,12 +170,12 @@ jobs:
           show_full_output: ${{ github.event_name == 'workflow_dispatch' }}
           prompt: |
             You are the i18n sync agent for the Dify repository.
-            Your job is to keep translations synchronized with the English source files under `${{ github.workspace }}/web/i18n/en-US/`.
+            Your job is to keep translations synchronized with the English source files under `${{ github.workspace }}/web/i18n/locales/en-US/`.
 
             Use absolute paths at all times:
             - Repo root: `${{ github.workspace }}`
             - Web directory: `${{ github.workspace }}/web`
-            - Language config: `${{ github.workspace }}/web/i18n-config/languages.ts`
+            - Language config: `${{ github.workspace }}/web/i18n/languages.ts`
 
             Inputs:
             - Files in scope: `${{ steps.context.outputs.CHANGED_FILES }}`
@@ -194,12 +198,12 @@ jobs:
             Required execution plan:
             1. Resolve target languages.
                - Use the provided `Target languages` value as the source of truth.
-               - If it is unexpectedly empty, read `${{ github.workspace }}/web/i18n-config/languages.ts` and use every language with `supported: true` except `en-US`.
+               - If it is unexpectedly empty, read `${{ github.workspace }}/web/i18n/languages.ts` and use every language with `supported: true` except `en-US`.
             2. Stay strictly in scope.
                - Only process the files listed in `Files in scope`.
                - Only process the resolved target languages, never `en-US`.
                - Do not touch unrelated i18n files.
-               - Do not modify `${{ github.workspace }}/web/i18n/en-US/`.
+               - Do not modify `${{ github.workspace }}/web/i18n/locales/en-US/`.
             3. Resolve source changes.
                - If `Structured change set available` is `true`, read `/tmp/i18n-changes.json` and use it as the source of truth for file-level and key-level changes.
                - For each file entry:
@@ -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 fmt <repo-relative edited paths such as web/i18n/...>`
+               - Run `vp fmt <repo-relative edited paths such as web/i18n/locales/...>`
                - 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.
@@ -237,7 +241,7 @@ jobs:
         if: steps.context.outputs.CHANGED_FILES != ''
         shell: bash
         run: |
-          if [ -z "$(git -C "${{ github.workspace }}" status --porcelain -- web/i18n/)" ]; then
+          if [ -z "$(git -C "${{ github.workspace }}" status --porcelain -- web/i18n/locales/)" ]; then
             echo "has_changes=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
@@ -256,7 +260,7 @@ jobs:
         shell: bash
         run: |
           git -C "${{ github.workspace }}" checkout -B "${{ steps.pr_meta.outputs.branch_name }}"
-          git -C "${{ github.workspace }}" add web/i18n/
+          git -C "${{ github.workspace }}" add web/i18n/locales/
           git -C "${{ github.workspace }}" commit -m "chore(i18n): sync translations with en-US"
 
       - name: Push translation branch
@@ -322,7 +326,7 @@ jobs:
             '## Verification',
             '',
             `- \`vp run dify-web#i18n:check --file ${process.env.FILES_IN_SCOPE} --lang ${process.env.TARGET_LANGS}\``,
-            `- \`vp fmt <repo-relative edited paths such as web/i18n/...>\``,
+            `- \`vp fmt <repo-relative edited paths such as web/i18n/locales/...>\``,
             '',
             '## Notes',
             '',

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

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main]
     paths:
-      - 'web/i18n/en-US/*.json'
+      - 'web/i18n/locales/en-US/*.json'
 
 permissions:
   contents: write
@@ -36,9 +36,9 @@ jobs:
           HEAD_SHA="${{ github.sha }}"
 
           if [ -n "$BASE_SHA" ]; then
-            CHANGED_FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/en-US/*.json' 2>/dev/null | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+            CHANGED_FILES=$(git diff --name-only --find-renames=100% --diff-filter=AMDT "$BASE_SHA" "$HEAD_SHA" -- 'web/i18n/' 2>/dev/null | sed -n '\@^web/i18n/locales/en-US/[^/]*\.json$@p' | sed -n 's@^.*/@@p' | sed 's/\.json$//' | tr '\n' ' ' | sed 's/[[:space:]]*$//')
           else
-            CHANGED_FILES=$(find web/i18n/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+            CHANGED_FILES=$(find web/i18n/locales/en-US -maxdepth 1 -type f -name '*.json' -print | sed -n 's@^.*/@@p' | sed 's/\.json$//' | sort | tr '\n' ' ' | sed 's/[[:space:]]*$//')
           fi
 
           export BASE_SHA HEAD_SHA CHANGED_FILES

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

@@ -29,14 +29,14 @@ jobs:
           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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/vdb-tests.yml

@@ -26,14 +26,14 @@ jobs:
           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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/web-bundle-size.yml

@@ -0,0 +1,152 @@
+name: Web Bundle Analysis
+
+on:
+  workflow_call:
+    inputs:
+      base-rev:
+        description: Exact base revision selected by the main CI event.
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  measure:
+    name: Measure ${{ matrix.revision }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - revision: base
+            sha: ${{ inputs.base-rev }}
+          - revision: merge
+            sha: ${{ github.sha }}
+    env:
+      NEXT_TELEMETRY_DISABLED: '1'
+      NODE_OPTIONS: --max-old-space-size=6144
+    steps:
+      # Keep one collector for both revisions, including when it does not exist on base yet.
+      - name: Checkout reporting tools
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Preserve collector
+        run: cp web/scripts/bundle-analysis.ts "$RUNNER_TEMP/bundle-analysis.ts"
+
+      - name: Checkout measured revision
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ matrix.sha }}
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Instrument selected revision
+        run: node "$RUNNER_TEMP/bundle-analysis.ts" instrument web
+
+      - name: Full Vinext build with official Rolldown analysis
+        working-directory: web
+        shell: bash
+        run: |
+          set -o pipefail
+          started=$SECONDS
+          pnpm exec vinext build 2>&1 | tee "$RUNNER_TEMP/vinext-build.log"
+          printf 'Full Vinext build: **%s seconds**.\n' "$((SECONDS - started))" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Collect sizes
+        env:
+          COMMIT_SHA: ${{ matrix.sha }}
+        run: node "$RUNNER_TEMP/bundle-analysis.ts" collect web "$COMMIT_SHA" "$RUNNER_TEMP/bundle-size/summary.json"
+
+      - name: Upload size snapshot
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: web-bundle-summary-${{ matrix.revision }}
+          path: ${{ runner.temp }}/bundle-size/summary.json
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Upload official Rolldown analysis
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: web-bundle-analyzer-${{ matrix.revision }}
+          path: |
+            web/dist/client/bundle-analysis.json
+            web/dist/client/bundle-analysis.md
+            ${{ runner.temp }}/vinext-build.log
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 14
+
+  report:
+    name: Compare bundle sizes
+    needs: measure
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout reporting tools
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
+        with:
+          install: false
+
+      - name: Download size snapshots
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: web-bundle-summary-*
+          path: bundle-results
+
+      - name: Compare and summarize
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          node web/scripts/bundle-analysis.ts compare \
+            bundle-results/web-bundle-summary-base/summary.json \
+            bundle-results/web-bundle-summary-merge/summary.json \
+            bundle-report.md
+          printf '\n[Download base/merge snapshots and official Rolldown analysis reports](%s#artifacts).\n' "$RUN_URL" >> bundle-report.md
+          printf '\nComparison: event base SHA vs the tested merge commit at GITHUB_SHA (PR or merge queue).\n' >> bundle-report.md
+          cat bundle-report.md >> "$GITHUB_STEP_SUMMARY"
+
+      # Forks still receive the job summary and artifacts, without a privileged PR build.
+      - name: Update PR report
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require('node:fs');
+            const { owner, repo } = context.repo;
+            const pull_number = context.payload.pull_request.number;
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number });
+            if (pr.state !== 'open' || pr.head.sha !== context.payload.pull_request.head.sha ||
+                pr.base.sha !== context.payload.pull_request.base.sha) {
+              core.info('Skipping a superseded bundle report.');
+              return;
+            }
+            const body = fs.readFileSync('bundle-report.md', 'utf8');
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number: pull_number, per_page: 100,
+            });
+            const existing = comments.find(comment =>
+              comment.user?.login === 'github-actions[bot]' &&
+              comment.body?.startsWith('<!-- dify-vinext-bundle-size -->'));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number: pull_number, body });
+            }

.github/workflows/web-e2e.yml

@@ -9,16 +9,15 @@ on:
         type: boolean
 
 permissions:
+  actions: read
   contents: read
 
 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
-    timeout-minutes: 120
-    defaults:
-      run:
-        shell: bash
+    timeout-minutes: 30
 
     steps:
       - name: Checkout code
@@ -26,16 +25,221 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Switch Ubuntu mirror
+      - name: Test Web build synchronization
+        run: node --test .github/actions/wait-e2e-web-build/wait.test.cjs
+
+      - name: Compute build source hash
+        id: build-source
+        shell: bash
         run: |
-          sudo sed -i 's|http://us-east-1.ec2.archive.ubuntu.com/ubuntu|http://azure.archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
-          sudo apt-get update
+          # Hash tracked build inputs, excluding generated files and backend-only changes.
+          source_hash=$(git ls-tree -r HEAD -- web packages e2e/scripts e2e/package.json e2e/test-env.ts package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc .github/actions/setup-web .github/workflows/web-e2e.yml | sha256sum | cut -d ' ' -f 1)
+          echo "hash=$source_hash" >> "$GITHUB_OUTPUT"
+
+      - name: Setup web dependencies
+        uses: ./.github/actions/setup-web
+        with:
+          # Browser jobs already save this dependency cache; avoid duplicate uploads.
+          cache-save: 'false'
+
+      - name: Restore Next.js build cache
+        id: next-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: web/.next/cache
+          key: e2e-next-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml') }}-${{ steps.build-source.outputs.hash }}
+          restore-keys: |
+            e2e-next-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml') }}-
+
+      - 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'
+          CACHE_HIT: ${{ steps.next-cache.outputs.cache-hit || 'false' }}
+        run: |
+          started=$SECONDS
+          vp run e2e:web:build
+          {
+            echo "### E2E Web build"
+            echo "Build: $((SECONDS - started))s"
+            echo "Exact cache hit: $CACHE_HIT (false can include a compatible fallback)"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - 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-${{ github.run_attempt }}
+          path: e2e-web-build.tar
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Save Next.js build cache
+        if: github.event_name != 'merge_group' && steps.next-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: web/.next/cache
+          key: ${{ steps.next-cache.outputs.cache-primary-key }}
+
+  chromium-full:
+    name: Chromium Full (${{ matrix.shard }}/3)
+    if: ${{ !inputs.run-external-runtime }}
+    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
+
+      - name: Prepare Chromium E2E dependencies
+        timeout-minutes: 15
+        uses: ./.github/actions/setup-core-e2e
+        with:
+          browser: chromium
+
+      # Install dependencies while core-build runs, then wait only for its artifact.
+      - name: Wait for Web build
+        id: web-build
+        timeout-minutes: 35
+        uses: ./.github/actions/wait-e2e-web-build
+
+      - name: Download Web build
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          artifact-ids: ${{ steps.web-build.outputs.artifact-id }}
+          github-token: ${{ github.token }}
+
+      - name: Extract Web build
+        run: tar -xf e2e-web-build.tar -C web
+
+      - 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 }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    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: Prepare WebKit E2E dependencies
+        timeout-minutes: 15
+        uses: ./.github/actions/setup-core-e2e
+        with:
+          browser: webkit
+
+      # Install dependencies while core-build runs, then wait only for its artifact.
+      - name: Wait for Web build
+        id: web-build
+        timeout-minutes: 35
+        uses: ./.github/actions/wait-e2e-web-build
+
+      - name: Download Web build
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          artifact-ids: ${{ steps.web-build.outputs.artifact-id }}
+          github-token: ${{ github.token }}
+
+      - name: Extract Web build
+        run: tar -xf e2e-web-build.tar -C web
+
+      - 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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: '3.12'
@@ -46,82 +250,12 @@ jobs:
       - name: Install API dependencies
         run: uv sync --project api --dev
 
-      - name: Run E2E support unit tests
-        if: ${{ !inputs.run-external-runtime }}
-        working-directory: ./e2e
-        run: vp run test:unit
-
-      - name: Install Playwright browsers for core E2E
-        if: ${{ !inputs.run-external-runtime }}
-        timeout-minutes: 15
-        working-directory: ./e2e
-        run: vp run e2e:install:ci
-
-      - name: Install Chromium for external runtime E2E
-        if: ${{ inputs.run-external-runtime }}
+      - name: Install Chromium
         timeout-minutes: 15
         working-directory: ./e2e
         run: vp run e2e:install:ci:chromium
 
-      - name: Run isolated source-api and built-web Cucumber E2E tests
-        if: ${{ !inputs.run-external-runtime }}
-        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
-        run: vp run e2e:full
-
-      - name: Preserve Chromium E2E report and logs
-        if: ${{ !cancelled() && !inputs.run-external-runtime }}
-        run: |
-          if [[ -d e2e/cucumber-report ]]; then
-            mv e2e/cucumber-report e2e/cucumber-report-non-external
-          fi
-          if [[ -d e2e/.logs ]]; then
-            mv e2e/.logs e2e/.logs-non-external
-          fi
-
-      - name: Run WebKit keyboard and browser smoke tests
-        if: ${{ !inputs.run-external-runtime }}
-        working-directory: ./e2e
-        env:
-          E2E_ADMIN_EMAIL: e2e-admin@example.com
-          E2E_ADMIN_NAME: E2E Admin
-          E2E_ADMIN_PASSWORD: E2eAdmin12345
-          E2E_BROWSER: webkit
-          E2E_INIT_PASSWORD: E2eInit12345
-        run: |
-          teardown_webkit_smoke() {
-            local run_status=$?
-            trap - EXIT
-            if ! vp run e2e:middleware:down; then
-              echo "::error title=E2E teardown failed::WebKit smoke middleware did not shut down cleanly."
-              if [[ "$run_status" -eq 0 ]]; then
-                run_status=1
-              fi
-            fi
-            exit "$run_status"
-          }
-
-          trap teardown_webkit_smoke EXIT
-          vp run e2e:middleware:up
-          vp run e2e -- --tags '@browser-smoke'
-
-      - name: Preserve WebKit E2E report and logs
-        if: ${{ !cancelled() && !inputs.run-external-runtime }}
-        run: |
-          if [[ -d e2e/cucumber-report ]]; then
-            mv e2e/cucumber-report e2e/cucumber-report-webkit
-          fi
-          if [[ -d e2e/.logs ]]; then
-            mv e2e/.logs e2e/.logs-webkit
-          fi
-
       - name: Run prepared and external runtime E2E tests
-        if: ${{ inputs.run-external-runtime }}
         working-directory: ./e2e
         env:
           E2E_ADMIN_EMAIL: e2e-admin@example.com
@@ -154,10 +288,8 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: cucumber-report
-          path: |
-            e2e/cucumber-report
-            e2e/cucumber-report-non-external
-            e2e/cucumber-report-webkit
+          path: e2e/cucumber-report
+          overwrite: true
           retention-days: 7
 
       - name: Upload E2E logs
@@ -165,18 +297,17 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: e2e-logs
-          path: |
-            e2e/.logs/*.log
-            e2e/.logs-non-external/*.log
-            e2e/.logs-webkit/*.log
+          path: e2e/.logs/*.log
           include-hidden-files: true
+          overwrite: true
           retention-days: 7
 
       - name: Upload E2E seed report
-        if: ${{ !cancelled() && inputs.run-external-runtime }}
+        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

@@ -33,17 +33,52 @@ 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() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: blob-report-${{ matrix.shardIndex }}
-          path: web/.vitest-reports/*
+          path: web/.vitest/blob/*
           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() }}
@@ -68,7 +103,7 @@ jobs:
       - name: Download blob reports
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          path: web/.vitest-reports
+          path: web/.vitest/blob
           pattern: blob-report-*
           merge-multiple: true
 
@@ -76,8 +111,7 @@ jobs:
         run: vp test --merge-reports --coverage --silent=passed-only
 
       - name: Report coverage
-        if: ${{ env.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           directory: web/coverage
           flags: web
@@ -86,7 +120,7 @@ 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 }}
@@ -101,11 +135,6 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Switch Ubuntu mirror
-        run: |
-          sudo sed -i 's|http://us-east-1.ec2.archive.ubuntu.com/ubuntu|http://azure.archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
-          sudo apt-get update
-
       - name: Setup web environment
         uses: ./.github/actions/setup-web
 
@@ -116,9 +145,18 @@ jobs:
       - 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
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           directory: packages/dify-ui/coverage
           flags: dify-ui
@@ -127,7 +165,7 @@ 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:
@@ -140,11 +178,6 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Switch Ubuntu mirror
-        run: |
-          sudo sed -i 's|http://us-east-1.ec2.archive.ubuntu.com/ubuntu|http://azure.archive.ubuntu.com/ubuntu|g' /etc/apt/sources.list.d/ubuntu.sources
-          sudo apt-get update
-
       - name: Setup web environment
         uses: ./.github/actions/setup-web
 
@@ -154,3 +187,13 @@ jobs:
 
       - 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

@@ -185,6 +185,7 @@ docker/volumes/minio/*
 docker/volumes/milvus/*
 docker/volumes/chroma/*
 docker/volumes/opensearch/data/*
+docker/volumes/openshell-mtls/*
 docker/volumes/myscale/data/*
 docker/volumes/myscale/log/*
 docker/volumes/unstructured/*
@@ -263,6 +264,7 @@ scripts/stress-test/reports/
 .qoder/*
 .context/
 # Vitest local reports
+web/.vitest-browser/
 web/.vitest-reports/
 
 # dify-agent-runtime

.nvmrc

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

.vite-hooks/pre-commit

@@ -1,12 +1,5 @@
 #!/bin/sh
-# get the list of modified files
-files=$(git diff --cached --name-only)
-
-# check if api or web directory is modified
-
-api_modified=false
-web_modified=false
-skip_web_checks=false
+set -eu
 
 git_path() {
     git rev-parse --git-path "$1"
@@ -18,46 +11,7 @@ if [ -f "$(git_path MERGE_HEAD)" ] || \
    [ -f "$(git_path SQUASH_MSG)" ] || \
    [ -d "$(git_path rebase-merge)" ] || \
    [ -d "$(git_path rebase-apply)" ]; then
-    skip_web_checks=true
-fi
-
-for file in $files
-do
-    # Use POSIX compliant pattern matching
-    case "$file" in
-        api/*.py)
-            # set api_modified flag to true
-            api_modified=true
-            ;;
-        web/*)
-            # set web_modified flag to true
-            web_modified=true
-            ;;
-    esac
-done
-
-# run linters based on the modified modules
-
-if $api_modified; then
-    echo "Running Ruff linter on api module"
-
-    # run Ruff linter auto-fixing
-    uv run --project api --dev ruff check --fix ./api
-
-    # run Ruff linter checks
-    uv run --project api --dev ruff check  ./api || status=$?
-
-    status=${status:-0}
-
-    if [ $status -ne 0 ]; then
-      echo "Ruff linter on api module error, exit code: $status"
-      echo "Please run 'dev/reformat' to fix the fixable linting errors."
-      exit 1
-    fi
-fi
-
-if $skip_web_checks; then
-    echo "Git operation in progress, skipping web checks"
+    echo "Git operation in progress, skipping staged checks; CI validates the result."
     exit 0
 fi
 

.vscode/settings.example.json

@@ -4,7 +4,6 @@
 
   "tailwindCSS.experimental.configFile": "web/app/styles/globals.css",
 
-  // Format
   "[javascript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
   "[javascriptreact]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
   "[typescript]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
@@ -25,9 +24,9 @@
   "[handlebars]": { "editor.defaultFormatter": "oxc.oxc-vscode" },
   "editor.formatOnSave": true,
   "editor.formatOnSaveMode": "file",
-  "oxc.fmt.configPath": "./vite.config.ts",
+  "oxc.disableNestedConfig": true,
+  "oxc.fmt.disableNestedConfig": true,
 
-  // Lint fix
   "eslint.useFlatConfig": true,
   "eslint.validate": ["json", "jsonc", "markdown", "yaml", "toml"],
   "editor.codeActionsOnSave": {

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-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 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. Apply its guidance within the user's requested scope; explicit user instructions take precedence over workflow defaults.
 
 ## Repository Gotchas
 

CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

CONTRIBUTING.md

@@ -22,6 +22,8 @@ Don't forget to link an existing issue or open a new issue in the PR's descripti
 
 ### Bug reports
 
+For security vulnerabilities, follow our [security policy](./SECURITY.md) and report privately instead of opening a public issue.
+
 > [!IMPORTANT]
 > Please make sure to include the following information when submitting a bug report:
 
@@ -36,7 +38,7 @@ How we prioritize:
 
 | Issue Type | Priority |
 | ------------------------------------------------------------ | --------------- |
-| Bugs in core functions (cloud service, cannot login, applications not working, security loopholes) | Critical |
+| Bugs in core functions (cloud service, cannot login, applications not working) | Critical |
 | Non-critical bugs, performance boosts | Medium Priority |
 | Minor fixes (typos, confusing but working UI) | Low Priority |
 
@@ -71,6 +73,10 @@ How we prioritize:
 1. Please link the issue in the PR description, `fixes #<issue_number>`
 1. Get merged!
 
+### AI-assisted contributions
+
+AI tools are welcome, but you are responsible for understanding and verifying every change you submit. Describe the problem, your solution, and actual test results in your own words. Unreviewed or repetitive low-quality submissions may be closed.
+
 ### Setup the project
 
 #### Frontend

README.md

@@ -58,6 +58,7 @@
   <a href="./docs/sl-SI/README.md"><img alt="README Slovenščina" src="https://img.shields.io/badge/Sloven%C5%A1%C4%8Dina-d9d9d9"></a>
   <a href="./docs/bn-BD/README.md"><img alt="README in বাংলা" src="https://img.shields.io/badge/বাংলা-d9d9d9"></a>
   <a href="./docs/hi-IN/README.md"><img alt="README in हिन्दी" src="https://img.shields.io/badge/Hindi-d9d9d9"></a>
+  <a href="./docs/id-ID/README.md"><img alt="README dalam Bahasa Indonesia" src="https://img.shields.io/badge/Bahasa%20Indonesia-d9d9d9"></a>
 </p>
 
 Dify is an open-source LLM app development platform. Its intuitive interface combines AI workflow, RAG pipeline, agent capabilities, model management, observability features (including [Opik](https://www.comet.com/docs/opik/integrations/dify), [Langfuse](https://docs.langfuse.com), and [Arize Phoenix](https://docs.arize.com/phoenix)) and more, letting you quickly go from prototype to production. Here's a list of the core features:
@@ -104,8 +105,7 @@ Intuitive interface for crafting prompts, comparing model performance, and addin
 **4. RAG Pipeline**:
 Extensive RAG capabilities that cover everything from document ingestion to retrieval, with out-of-box support for text extraction from PDFs, PPTs, and other common document formats.
 
-**5. Agent capabilities**:
-You can define agents based on LLM Function Calling or ReAct, and add pre-built or custom tools for the agent. Dify provides 50+ built-in tools for AI agents, such as Google Search, DALL·E, Stable Diffusion and WolframAlpha.
+**5. Agent**: Autonomous agents with a sandbox of their own: they run commands, install software, and handle files to get open-ended tasks done. Describe the agent you want and it builds itself. Give it skills, connect tools from [Dify Marketplace](https://marketplace.dify.ai/?category=tool), MCP servers, or your own APIs, and put it to work as a chat app or as a step in any workflow.
 
 **6. LLMOps**:
 Monitor and analyze application logs and performance over time. You could continuously improve prompts, datasets, and models based on production data and annotations.
@@ -122,90 +122,42 @@ All of Dify's offerings come with corresponding APIs, so you could effortlessly
   Quickly get Dify running in your environment with this [starter guide](#quick-start).
   Use our [documentation](https://docs.dify.ai) for further references and more in-depth instructions.
 
-- **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/>
+- **[Dify Enterprise](https://dify.ai/dify-enterprise)<br/>**
+  For organizations requiring self-hosting, SSO, RBAC Security and Enterprise Support SLAs, please fill out [this form](https://share-na2.hsforms.com/14-09ff5HS92Sh4m3f4yrcw40s9fk) to speak to a solution representative. <br/>
 
 ## 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/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**
-
-<a href="https://github.com/langgenius/dify/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=langgenius/dify" />
-</a>
+- [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.
 
 ## Star History
 

api/.env.example

@@ -98,9 +98,11 @@ REDIS_KEEPALIVE=true
 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
@@ -220,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=
 
@@ -231,6 +234,7 @@ VECTOR_INDEX_NAME_PREFIX=Vector_index
 
 # Weaviate configuration
 WEAVIATE_ENDPOINT=http://localhost:8080
+WEAVIATE_GRPC_ENDPOINT=grpc://localhost:50051
 WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih
 WEAVIATE_BATCH_SIZE=100
 WEAVIATE_TOKENIZATION=word
@@ -456,6 +460,12 @@ UPLOAD_IMAGE_FILE_SIZE_LIMIT=10
 UPLOAD_VIDEO_FILE_SIZE_LIMIT=100
 UPLOAD_AUDIO_FILE_SIZE_LIMIT=50
 UPLOAD_SKILL_FILE_SIZE_LIMIT=50
+SKILL_PACKAGE_MAX_UNCOMPRESSED_BYTES=209715200
+SKILL_PACKAGE_MAX_ENTRIES=5000
+SKILL_PACKAGE_MAX_SKILL_MD_BYTES=1048576
+AGENT_PACKAGE_MAX_BYTES=536870912
+AGENT_PACKAGE_MAX_MANIFEST_BYTES=5242880
+AGENT_PACKAGE_MAX_ENTRIES=5000
 
 # Comma-separated list of file extensions blocked from upload for security reasons.
 # Extensions should be lowercase without dots (e.g., exe,bat,sh,dll).
@@ -488,6 +498,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
@@ -578,7 +595,7 @@ 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
@@ -623,7 +640,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
 
@@ -698,19 +715,36 @@ INNER_API_KEY_FOR_PLUGIN=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y
 
 # Dify Agent backend
 AGENT_BACKEND_BASE_URL=http://localhost:5050
-# Bearer token sent to the Agent backend /runs API. Must match DIFY_AGENT_API_TOKEN on the server side.
+# 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
-AGENT_BACKEND_RUN_TIMEOUT_SECONDS=1200
+# 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
+# Explicitly bypass the Community edition gate for development deployments.
+KNOWLEDGE_FS_COMMUNITY_DEV_ENABLED=false
+# Production deployments require HTTPS; plain HTTP is limited to non-production or loopback.
 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_DIRECT_ORIGIN=
+KNOWLEDGE_FS_LIFECYCLE_WORKER_ENABLED=false
+KNOWLEDGE_FS_INTEGRATED_PROVISION_READY=false
+KNOWLEDGE_FS_LEGACY_ACL_FREEZE_READY=false
+KNOWLEDGE_FS_LIFECYCLE_POLL_INTERVAL_SECONDS=15
+KNOWLEDGE_FS_LIFECYCLE_LEASE_SECONDS=60
+KNOWLEDGE_FS_LIFECYCLE_BATCH_SIZE=25
+KNOWLEDGE_FS_CAPABILITY_V2_ENABLED=false
+KNOWLEDGE_FS_CAPABILITY_V2_SIGNING_KID=
+KNOWLEDGE_FS_CAPABILITY_V2_PRIVATE_KEY_PEM=
+KNOWLEDGE_FS_CAPABILITY_V2_PREVIOUS_PUBLIC_JWKS=
+KNOWLEDGE_FS_CAPABILITY_V2_ISSUER=dify-control-plane
+KNOWLEDGE_FS_CAPABILITY_V2_AUDIENCE=knowledge-fs
+KNOWLEDGE_FS_CAPABILITY_V2_MAX_TTL_SECONDS=60
 KNOWLEDGE_FS_TIMEOUT_SECONDS=10
+KNOWLEDGE_FS_JWKS_CACHE_MAX_AGE_SECONDS=300
+KNOWLEDGE_FS_PRODUCT_MAX_RESPONSE_BYTES=4194304
 
 # Marketplace configuration
 MARKETPLACE_ENABLED=true
@@ -729,6 +763,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
 
@@ -825,6 +861,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.
@@ -832,3 +874,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

@@ -15,6 +15,109 @@ root_packages =
     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.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
@@ -65,6 +168,276 @@ forbidden_modules =
     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:installed-app-access-boundary]
+name = Installed app access application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.installed_app_access_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:installed-app-management-boundary]
+name = Installed app management service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.installed_app_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:installed-app-conversation-boundary]
+name = Installed app conversation service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.installed_app_conversation_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:conversation-persistence-boundary]
+name = Conversation persistence does not call legacy conversation or workspace services
+type = forbidden
+source_modules =
+    repositories.installed_app_conversation_repository
+    repositories.conversation_lifecycle
+    repositories.agent_workspace_repository
+forbidden_modules =
+    services.conversation_service
+    services.agent.workspace_service
+allow_indirect_imports = True
+
+[importlinter:contract:installed-app-generation-boundary]
+name = Installed app generation service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.installed_app_generation_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_access_service
+    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_forgot_password_service
+    services.account_initialization_service
+    services.account_integration_service
+    services.account_login_service
+    services.account_oauth_service
+    services.account_password_service
+    services.account_ports
+    services.account_profile_service
+    services.entities.account_access_entities
+    services.entities.account_entities
+    services.entities.account_login_entities
+    services.entities.account_oauth_entities
+    services.entities.auth_audit_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:end-user-query-service-boundary]
+name = App-scoped end user query service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_scoped_end_user_query_service
+    services.entities.app_scoped_end_user_entities
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:end-user-command-service-boundary]
+name = App-scoped end user command service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_scoped_end_user_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models.model
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:app-tracing-config-service-boundary]
+name = App tracing configuration service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_tracing_config_service
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:message-file-preview-service-boundary]
+name = Message file preview application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.message_file_preview_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:upload-file-delivery-service-boundary]
+name = Upload file delivery application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.upload_file_delivery_service
+forbidden_modules =
+    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
@@ -79,6 +452,58 @@ forbidden_modules =
     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:oauth-device-application-service-boundary]
+name = OAuth device application service and contracts are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.oauth_device_application_service
+    services.oauth_device_contracts
+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
@@ -125,3 +550,231 @@ forbidden_modules =
     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:file-grant-service-boundary]
+name = File grant application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.file_grant_service
+    services.entities.file_grant_entities
+forbidden_modules =
+    configs
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:plugin-file-upload-service-boundary]
+name = Plugin file upload application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.plugin_file_upload_service
+forbidden_modules =
+    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:tool-file-download-service-boundary]
+name = Tool file download application service is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.tool_file_download_service
+forbidden_modules =
+    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:trial-app-application-boundary]
+name = Trial app access and generation services are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.trial_app_access_service
+    services.trial_app_generation_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.app_generate_service
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:app-preview-query-boundary]
+name = App preview queries are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_preview_query_service
+    services.app_preview_details_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    sqlalchemy
+    werkzeug
+
+[importlinter:contract:message-suggested-questions-boundary]
+name = Message suggested questions port is framework and persistence neutral
+type = forbidden
+source_modules =
+    services.message_suggested_questions_service
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.message_service
+    sqlalchemy
+    werkzeug
+
+[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
+
+[importlinter:contract:app-audio-boundary]
+name = App audio operations and values are framework and persistence neutral
+type = forbidden
+source_modules =
+    services.app_audio_service
+    services.audio_types
+forbidden_modules =
+    controllers
+    extensions
+    flask
+    models
+    repositories
+    services.audio_service
+    sqlalchemy
+    werkzeug

api/AGENTS.md

@@ -23,3 +23,8 @@ Run direct Python commands through `uv run --project api`. Docker-backed integra
 - Use Pydantic v2 for request and response models. Reuse domain-specific exceptions and translate them at the controller boundary.
 - Use existing Celery task and queue owners for asynchronous work; do not route unrelated jobs through workflow-specific services.
 - Celery tasks that may be retried or redelivered must keep side effects idempotent and log affected resource identifiers.
+
+## Typing Best Practises
+
+- Treat nullable types (`T | None`) strictly as union types; document the semantic meaning for each branch.
+- Treat default parameter values as introducing distinct function overloads; verify that every added default has demonstrable practical utility and avoids masking unsafe runtime states.

api/Dockerfile

@@ -1,3 +1,6 @@
+# KnowledgeFS is released independently. Its release controller atomically mounts the tested
+# engine bundles and native dependencies at /app/knowledge-fs in the dedicated Celery workers.
+# Ordinary Dify API images do not rebuild or download a second copy of the private engine.
 # base image
 FROM python:3.12-slim-bookworm AS base
 
@@ -33,7 +36,6 @@ RUN uv sync --frozen --no-dev --no-editable
 FROM base AS production
 
 ENV FLASK_APP=app.py
-ENV EDITION=SELF_HOSTED
 ENV DEPLOY_ENV=PRODUCTION
 ENV CONSOLE_API_URL=http://127.0.0.1:5001
 ENV CONSOLE_WEB_URL=http://127.0.0.1:3000
@@ -54,15 +56,14 @@ WORKDIR /app/api
 
 # Create non-root user
 ARG dify_uid=1001
-ARG NODE_MAJOR=22
-ARG NODE_PACKAGE_VERSION=22.21.0-1nodesource1
+ARG NODE_PACKAGE_VERSION=24.20.0-1nodesource1
 ARG NODESOURCE_KEY_FPR=6F71F525282841EEDAF851B42F59B5F99B1BE0B4
 RUN groupadd -r -g ${dify_uid} dify && \
     useradd -r -u ${dify_uid} -g ${dify_uid} -s /bin/bash dify && \
     chown -R dify:dify /app
 
-RUN \
-    apt-get update \
+RUN NODE_MAJOR="${NODE_PACKAGE_VERSION%%.*}" \
+    && apt-get update \
     && apt-get install -y --no-install-recommends \
         ca-certificates \
         curl \
@@ -91,6 +92,8 @@ RUN \
         media-types \
         # install libmagic to support the use of python-magic guess MIMETYPE
         libmagic1 \
+        # Bounded PDF metadata/rasterization invoked by the local KnowledgeFS worker engine.
+        poppler-utils \
     && apt-get autoremove -y \
     && rm -rf /var/lib/apt/lists/*
 

api/Dockerfile.dockerignore

@@ -7,10 +7,27 @@
 !dify-agent/README.md
 !dify-agent/src/
 !dify-agent/src/**
+!knowledge-fs/
+!knowledge-fs/package.json
+!knowledge-fs/pnpm-lock.yaml
+!knowledge-fs/pnpm-workspace.yaml
+!knowledge-fs/turbo.json
+!knowledge-fs/tsconfig.base.json
+!knowledge-fs/apps/
+!knowledge-fs/apps/api/
+!knowledge-fs/apps/api/**
+!knowledge-fs/packages/
+!knowledge-fs/packages/**
+**/node_modules/
+**/dist/
+**/.turbo/
 
 # Environment configuration and example
 .env
 *.env.*
+**/.env
+**/*.env
+**/*.env.*
 
 # Python related files
 **/__pycache__

api/README.md

@@ -50,7 +50,9 @@ The scripts resolve paths relative to their location, so you can run them from a
    ./dev/start-worker
    ```
 
-1. Optional: start Celery Beat (scheduled tasks).
+1. Start Celery Beat when scheduled tasks are needed. This is required when
+   `KNOWLEDGE_FS_LIFECYCLE_WORKER_ENABLED=true` so provisioning and deletion
+   outbox commands are dispatched to the lifecycle worker.
 
    ```bash
    ./dev/start-beat
@@ -87,16 +89,17 @@ The scripts resolve paths relative to their location, so you can run them from a
    uv sync --group dev
    ```
 
-1. Run the tests locally with mocked system environment variables in `tool.pytest_env` section in `pyproject.toml`, more can check [Claude.md](../CLAUDE.md)
+1. Run the tests locally with mocked system environment variables in `tool.pytest_env` section in `pyproject.toml`, more can check [AGENTS.md](../AGENTS.md)
+
+   Continue in the `api` directory from the previous step.
 
    ```bash
-   cd api
    uv run pytest                           # Run all tests
    uv run pytest tests/unit_tests/         # Unit tests only
    uv run pytest tests/integration_tests/  # Integration tests
 
    # Code quality
-   ./dev/reformat               # Run all formatters and linters
+   ../dev/reformat              # Run all formatters and linters
    uv run ruff check --fix ./   # Fix linting issues
    uv run ruff format ./        # Format code
    uv run pyrefly check         # Type checking

api/app_factory.py

@@ -14,6 +14,7 @@ from contexts.wrapper import RecyclableContextVar
 from controllers.console.error import UnauthorizedAndForceLogout
 from core.logging.context import init_request_context
 from dify_app import DifyApp
+from enums import DeploymentEdition
 from extensions.ext_socketio import sio
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.feature_entities import LicenseStatus
@@ -104,6 +105,10 @@ def create_flask_app_with_configs() -> DifyApp:
     dify_app = DifyApp(__name__)
     dify_app.config.from_mapping(dify_config.model_dump())
     dify_app.config["RESTX_INCLUDE_ALL_MODELS"] = True
+    # flask-restx appends url-map suggestions to 404 bodies: they enumerate routes to
+    # anonymous callers, and a policy 404 on an existing route (edition admission)
+    # ends up suggesting the very path that was just requested.
+    dify_app.config["RESTX_ERROR_404_HELP"] = False
 
     # add before request hook
     @dify_app.before_request
@@ -112,7 +117,7 @@ def create_flask_app_with_configs() -> DifyApp:
         init_request_context()
         RecyclableContextVar.increment_thread_recycles()
 
-        if dify_config.ENTERPRISE_ENABLED:
+        if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.ENTERPRISE:
             surface = _match_license_gated_surface(request.path)
             if surface is not None:
                 try:
@@ -185,6 +190,7 @@ def initialize_extensions(app: DifyApp):
         ext_hosting_provider,
         ext_import_modules,
         ext_key_provider,
+        ext_knowledge_fs_observability,
         ext_logging,
         ext_login,
         ext_logstore,
@@ -236,6 +242,7 @@ def initialize_extensions(app: DifyApp):
         ext_enterprise_telemetry,
         ext_request_logging,
         ext_session_factory,
+        ext_knowledge_fs_observability,
         ext_application_services,
         ext_oauth_bearer,
     ]

api/celery_entrypoint.py

@@ -1,11 +1,15 @@
-import psycogreen.gevent as pscycogreen_gevent
-from grpc.experimental import gevent as grpc_gevent
+from gevent.monkey import is_module_patched
 
-# grpc gevent
-grpc_gevent.init_gevent()
-print("gRPC patched with gevent.", flush=True)  # noqa: T201
-pscycogreen_gevent.patch_psycopg()
-print("psycopg2 patched with gevent.", flush=True)  # noqa: T201
+# Celery patches the stdlib before importing this entrypoint for -P gevent. Prefork workers
+# (including the KnowledgeFS local engine) must retain native subprocess, DB and gRPC behavior.
+if is_module_patched("socket"):
+    import psycogreen.gevent as pscycogreen_gevent
+    from grpc.experimental import gevent as grpc_gevent
+
+    grpc_gevent.init_gevent()
+    print("gRPC patched with gevent.", flush=True)  # noqa: T201
+    pscycogreen_gevent.patch_psycopg()
+    print("psycopg2 patched with gevent.", flush=True)  # noqa: T201
 
 
 from app import app, celery

api/clients/agent_backend/client.py

@@ -23,6 +23,7 @@ from dify_agent.protocol import (
     CancelRunResponse,
     CreateRunRequest,
     CreateRunResponse,
+    RunCancelledEvent,
     RunEvent,
     RunStatusResponse,
 )
@@ -45,6 +46,15 @@ class AgentBackendRunClient(Protocol):
     def cancel_run(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
         """Request explicit cancellation for one Agent backend run."""
 
+    def cancel_run_and_wait(
+        self,
+        run_id: str,
+        request: CancelRunRequest | None = None,
+        *,
+        after: str | None = None,
+    ) -> RunCancelledEvent:
+        """Request cancellation and wait for runner cleanup to finish."""
+
     def stream_events(
         self,
         run_id: str,
@@ -67,6 +77,15 @@ class _DifyAgentSyncClient(Protocol):
     def cancel_run_sync(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
         """Cancel one run synchronously."""
 
+    def cancel_run_and_wait_sync(
+        self,
+        run_id: str,
+        request: CancelRunRequest | None = None,
+        *,
+        after: str | None = None,
+    ) -> RunCancelledEvent:
+        """Cancel one run and wait for its terminal event synchronously."""
+
     def stream_events_sync(
         self,
         run_id: str,
@@ -92,11 +111,9 @@ class DifyAgentBackendRunClient:
         client: _DifyAgentSyncClient,
         *,
         stream_max_reconnects: int = 3,
-        stream_timeout_seconds: float = 1200,
     ) -> None:
         self.client = client
         self._stream_max_reconnects = stream_max_reconnects
-        self._stream_timeout_seconds = stream_timeout_seconds
 
     def create_run(self, request: CreateRunRequest) -> CreateRunResponse:
         """Create one run through ``POST /runs`` and normalize client exceptions."""
@@ -112,6 +129,19 @@ class DifyAgentBackendRunClient:
         except Exception as exc:
             raise _normalize_dify_agent_error(exc) from exc
 
+    def cancel_run_and_wait(
+        self,
+        run_id: str,
+        request: CancelRunRequest | None = None,
+        *,
+        after: str | None = None,
+    ) -> RunCancelledEvent:
+        """Cancel one run, then wait for the cleanup-complete terminal event."""
+        try:
+            return self.client.cancel_run_and_wait_sync(run_id, request=request, after=after)
+        except Exception as exc:
+            raise _normalize_dify_agent_error(exc) from exc
+
     def stream_events(
         self,
         run_id: str,
@@ -125,7 +155,6 @@ class DifyAgentBackendRunClient:
                 run_id,
                 after=after,
                 max_reconnects=self._stream_max_reconnects,
-                timeout_seconds=self._stream_timeout_seconds,
                 should_stop=should_stop,
             )
         except Exception as exc:

api/clients/agent_backend/errors.py

@@ -8,11 +8,40 @@ classes.
 
 from __future__ import annotations
 
+from http import HTTPStatus
 from typing import Any
 
+from dify_agent.client import DifyAgentHTTPError
 from dify_agent.protocol import RunFailureType
 
 
+def backend_reported_failure(exc: DifyAgentHTTPError) -> bool:
+    """Whether the backend itself reported the failure.
+
+    ``DifyAgentValidationError`` is a ``DifyAgentHTTPError`` that the client also
+    raises when a *successful* response fails DTO validation. Those carry a 2xx
+    status and a Pydantic error list, not a backend-authored error envelope.
+    """
+    return exc.status_code >= HTTPStatus.BAD_REQUEST
+
+
+def backend_error_detail(
+    exc: DifyAgentHTTPError,
+    *,
+    default_code: str = "agent_backend_error",
+) -> tuple[str, str]:
+    """Split an Agent backend HTTP error into the code and message the backend itself sent."""
+    detail = exc.detail
+    if isinstance(detail, dict):
+        code = detail.get("code")
+        message = detail.get("message")
+        return (
+            code if isinstance(code, str) and code else default_code,
+            message if isinstance(message, str) and message else str(exc),
+        )
+    return default_code, str(detail)
+
+
 class AgentBackendError(Exception):
     """Base error for API-side Agent backend integration failures."""
 

api/clients/agent_backend/event_adapter.py

@@ -99,6 +99,8 @@ class AgentBackendRunFailedInternalEvent(AgentBackendInternalEventBase):
     error: str
     error_type: RunFailureType | None = None
     reason: str | None = None
+    session_snapshot: CompositorSessionSnapshot | None = None
+    usage: dict[str, JsonValue] | None = None
 
 
 class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):
@@ -107,6 +109,8 @@ class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):
     type: Literal[AgentBackendInternalEventType.RUN_CANCELLED] = AgentBackendInternalEventType.RUN_CANCELLED
     reason: str | None = None
     message: str | None = None
+    session_snapshot: CompositorSessionSnapshot | None = None
+    usage: dict[str, JsonValue] | None = None
 
 
 type AgentBackendInternalEvent = Annotated[
@@ -184,6 +188,8 @@ class AgentBackendRunEventAdapter:
                         error=event.data.error,
                         error_type=event.data.error_type,
                         reason=event.data.reason,
+                        session_snapshot=event.data.session_snapshot,
+                        usage=_agent_run_usage(event.data.usage),
                     )
                 ]
             case RunCancelledEvent():
@@ -193,6 +199,8 @@ class AgentBackendRunEventAdapter:
                         source_event_id=event.id,
                         reason=event.data.reason,
                         message=event.data.message,
+                        session_snapshot=event.data.session_snapshot,
+                        usage=_agent_run_usage(event.data.usage),
                     )
                 ]
         raise TypeError(f"unsupported agent backend run event: {type(event).__name__}")

api/clients/agent_backend/factory.py

@@ -8,6 +8,25 @@ from clients.agent_backend.client import AgentBackendRunClient, DifyAgentBackend
 from clients.agent_backend.fake_client import FakeAgentBackendRunClient, FakeAgentBackendScenario
 
 
+def create_agent_backend_client(
+    *,
+    base_url: str,
+    api_token: str | None = None,
+    stream_timeout: float = 30,
+    timeout: float = 30.0,
+    binding_file_download_timeout: float = 240,
+) -> Client:
+    api_token = api_token.strip() if api_token else None
+    headers = {"Authorization": f"Bearer {api_token}"} if api_token else None
+    return Client(
+        base_url=base_url,
+        stream_timeout=stream_timeout,
+        timeout=timeout,
+        binding_file_download_timeout=binding_file_download_timeout,
+        headers=headers,
+    )
+
+
 def create_agent_backend_run_client(
     *,
     base_url: str | None = None,
@@ -16,18 +35,17 @@ def create_agent_backend_run_client(
     fake_scenario: str | FakeAgentBackendScenario = FakeAgentBackendScenario.SUCCESS,
     stream_read_timeout_seconds: float = 30,
     stream_max_reconnects: int = 3,
-    stream_run_timeout_seconds: float = 1200,
 ) -> AgentBackendRunClient:
     """Create the API-side run client without hiding the ``dify-agent`` protocol."""
     if use_fake:
         return FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario(fake_scenario))
     if base_url is None:
         raise ValueError("base_url is required when creating a real Agent backend client")
-    headers: dict[str, str] = {}
-    if api_token:
-        headers["Authorization"] = f"Bearer {api_token}"
     return DifyAgentBackendRunClient(
-        Client(base_url=base_url, stream_timeout=stream_read_timeout_seconds, headers=headers),
+        create_agent_backend_client(
+            base_url=base_url,
+            api_token=api_token,
+            stream_timeout=stream_read_timeout_seconds,
+        ),
         stream_max_reconnects=stream_max_reconnects,
-        stream_timeout_seconds=stream_run_timeout_seconds,
     )

api/clients/agent_backend/fake_client.py

@@ -18,6 +18,8 @@ from dify_agent.protocol import (
     CreateRunRequest,
     CreateRunResponse,
     DeferredToolCallPayload,
+    RunCancelledEvent,
+    RunCancelledEventData,
     RunEvent,
     RunFailedEvent,
     RunFailedEventData,
@@ -69,6 +71,28 @@ class FakeAgentBackendRunClient:
         del request
         return CancelRunResponse(run_id=run_id, status="cancelled")
 
+    def cancel_run_and_wait(
+        self,
+        run_id: str,
+        request: CancelRunRequest | None = None,
+        *,
+        after: str | None = None,
+    ) -> RunCancelledEvent:
+        """Return a deterministic cleanup-complete cancellation event."""
+        del after
+        request = request or CancelRunRequest()
+        _ = self.cancel_run(run_id, request)
+        return RunCancelledEvent(
+            id="cancel-0",
+            run_id=run_id,
+            created_at=_FIXED_TIME,
+            data=RunCancelledEventData(
+                reason=request.reason,
+                message=request.message,
+                session_snapshot=CompositorSessionSnapshot(layers=[]),
+            ),
+        )
+
     def stream_events(
         self,
         run_id: str,
@@ -133,7 +157,11 @@ class FakeAgentBackendRunClient:
                         id="2-0",
                         run_id=run_id,
                         created_at=_FIXED_TIME,
-                        data=RunFailedEventData(error="fake failure", reason="unit_test"),
+                        data=RunFailedEventData(
+                            error="fake failure",
+                            reason="unit_test",
+                            session_snapshot=CompositorSessionSnapshot(layers=[]),
+                        ),
                     ),
                 )
             case FakeAgentBackendScenario.PAUSED:

api/clients/agent_backend/request_builder.py

@@ -25,19 +25,23 @@ from dify_agent.layers.dify_core_tools import DIFY_CORE_TOOLS_LAYER_TYPE_ID, Dif
 from dify_agent.layers.dify_plugin import (
     DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
     DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
-    DifyPluginCredentialValue,
     DifyPluginLLMLayerConfig,
     DifyPluginToolsLayerConfig,
 )
-from dify_agent.layers.drive import DIFY_DRIVE_LAYER_TYPE_ID, DifyDriveLayerConfig
 from dify_agent.layers.execution_context import (
     DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
     DifyExecutionContextLayerConfig,
 )
 from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
+from dify_agent.layers.knowledge_fs import DIFY_KNOWLEDGE_FS_LAYER_TYPE_ID, DifyKnowledgeFsLayerConfig
 from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
 from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
 from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
+from dify_agent.layers.user_prompt import (
+    DIFY_USER_PROMPT_LAYER_TYPE_ID,
+    DifyUserPromptFileConfig,
+    DifyUserPromptLayerConfig,
+)
 from dify_agent.protocol import (
     DIFY_AGENT_HISTORY_LAYER_ID,
     DIFY_AGENT_MODEL_LAYER_ID,
@@ -57,7 +61,6 @@ AGENT_APP_USER_PROMPT_LAYER_ID = "agent_app_user_prompt"
 DIFY_EXECUTION_CONTEXT_LAYER_ID = "execution_context"
 DIFY_RUNTIME_LAYER_ID = "runtime"
 DIFY_CONFIG_LAYER_ID = "config"
-DIFY_DRIVE_LAYER_ID = "drive"
 DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"
 DIFY_CORE_TOOLS_LAYER_ID = "core_tools"
 DIFY_KNOWLEDGE_BASE_LAYER_ID = "knowledge"
@@ -73,22 +76,19 @@ def _shell_layer_deps() -> dict[str, str]:
     }
 
 
-def _drive_layer_deps() -> dict[str, str]:
-    return {"shell": DIFY_SHELL_LAYER_ID}
-
-
 def _config_layer_deps() -> dict[str, str]:
     return {"shell": DIFY_SHELL_LAYER_ID}
 
 
-def _shell_config_with_drive_ref(
-    shell_config: DifyShellLayerConfig | None,
-    drive_config: DifyDriveLayerConfig | None,
-) -> DifyShellLayerConfig:
-    config = shell_config or DifyShellLayerConfig()
-    if drive_config is None:
-        return config
-    return config.model_copy(update={"agent_stub_drive_ref": drive_config.drive_ref})
+def _knowledge_fs_spec(run_input: AgentBackendWorkflowNodeRunInput | AgentBackendAgentAppRunInput) -> RunLayerSpec:
+    if not run_input.include_shell or run_input.knowledge is not None:
+        raise ValueError("KnowledgeFS requires shell and cannot be combined with legacy knowledge retrieval")
+    return RunLayerSpec(
+        name="knowledge_fs",
+        type=DIFY_KNOWLEDGE_FS_LAYER_TYPE_ID,
+        deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID, "shell": DIFY_SHELL_LAYER_ID},
+        config=run_input.knowledge_fs,
+    )
 
 
 def _markdown_backtick_fence(text: str) -> str:
@@ -150,8 +150,8 @@ class AgentBackendModelConfig(BaseModel):
     plugin_id: str
     model_provider: str
     model: str
-    credentials: dict[str, DifyPluginCredentialValue] = Field(default_factory=dict)
     model_settings: dict[str, JsonValue] = Field(default_factory=dict)
+    context_window_tokens: int | None = Field(default=None, gt=0)
 
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
 
@@ -159,8 +159,12 @@ class AgentBackendModelConfig(BaseModel):
 # ``DifyPluginLLMLayerConfig.model_settings`` is pydantic_ai's ``ModelSettings``
 # TypedDict (closed: unknown keys are rejected, explicit ``None`` values fail the
 # per-field type checks). Agent Soul model settings carry a wider, nullable shape
-# (``stop`` / ``response_format`` plus null-padded fields), so the layer config
-# only receives the keys the runtime contract accepts.
+# (``stop`` / ``response_format`` plus null-padded fields, plus arbitrary
+# plugin-declared parameters such as Qwen's ``enable_thinking``), so the layer
+# config only receives the keys the runtime contract accepts directly; anything
+# else is forwarded through ``extra_body``, the TypedDict's own escape hatch for
+# provider-specific parameters (see
+# ``dify_agent.adapters.llm.model._map_model_settings_to_parameters``).
 _AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS = (
     "temperature",
     "top_p",
@@ -168,6 +172,7 @@ _AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS = (
     "frequency_penalty",
     "max_tokens",
 )
+_AGENT_MODEL_SETTINGS_KNOWN_KEYS = frozenset({*_AGENT_MODEL_SETTINGS_PASSTHROUGH_KEYS, "stop", "response_format"})
 
 
 def _agent_model_settings(settings: Mapping[str, JsonValue]) -> dict[str, JsonValue] | None:
@@ -177,6 +182,15 @@ def _agent_model_settings(settings: Mapping[str, JsonValue]) -> dict[str, JsonVa
     stop = settings.get("stop")
     if isinstance(stop, list) and stop:
         sanitized["stop_sequences"] = stop
+
+    extra_body: dict[str, JsonValue] = {
+        key: value
+        for key, value in settings.items()
+        if key not in _AGENT_MODEL_SETTINGS_KNOWN_KEYS and value is not None
+    }
+    if extra_body:
+        sanitized["extra_body"] = extra_body
+
     return sanitized or None
 
 
@@ -210,10 +224,8 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     tools: DifyPluginToolsLayerConfig | None = None
     core_tools: DifyCoreToolsLayerConfig | None = None
     knowledge: DifyKnowledgeBaseLayerConfig | None = None
+    knowledge_fs: DifyKnowledgeFsLayerConfig | None = None
     config_layer_config: DifyConfigLayerConfig | None = None
-    # Drive Skills & Files declaration (dify.drive) — an index the agent pulls
-    # through the back proxy, never inline content.
-    drive_config: DifyDriveLayerConfig | None = None
     # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
     # the Agent Soul configures human involvement; a deferred call ends the run and
     # the workflow pauses via the existing HITL form mechanism (ENG-635).
@@ -252,6 +264,7 @@ class AgentBackendAgentAppRunInput(BaseModel):
     execution_context: DifyExecutionContextLayerConfig
     backend_binding_ref: str = Field(min_length=1)
     user_prompt: str
+    user_files: list[DifyUserPromptFileConfig] = Field(default_factory=list)
     agent_soul_prompt: str | None = None
     agent_config_version_kind: AgentConfigVersionKind = "snapshot"
     idempotency_key: str | None = None
@@ -259,10 +272,8 @@ class AgentBackendAgentAppRunInput(BaseModel):
     tools: DifyPluginToolsLayerConfig | None = None
     core_tools: DifyCoreToolsLayerConfig | None = None
     knowledge: DifyKnowledgeBaseLayerConfig | None = None
+    knowledge_fs: DifyKnowledgeFsLayerConfig | None = None
     config_layer_config: DifyConfigLayerConfig | None = None
-    # Drive Skills & Files declaration (dify.drive) — an index the agent pulls
-    # through the back proxy, never inline content.
-    drive_config: DifyDriveLayerConfig | None = None
     # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
     # the Agent Soul configures human involvement (ENG-635).
     ask_human_config: DifyAskHumanLayerConfig | None = None
@@ -294,7 +305,7 @@ class AgentBackendRunRequestBuilder:
         """Build an Agent App conversation-turn run request.
 
         Layer graph: optional Agent Soul system prompt → user prompt →
-        execution context → optional shell / config / drive / history
+        execution context → optional shell / config / history
         (multi-turn) → LLM → optional plugin-direct tools / core-routed tools /
         knowledge search / ask_human / structured output. Mirrors the
         workflow-node layer ordering minus the workflow-job / previous-node
@@ -319,9 +330,9 @@ class AgentBackendRunRequestBuilder:
             [
                 RunLayerSpec(
                     name=AGENT_APP_USER_PROMPT_LAYER_ID,
-                    type=PLAIN_PROMPT_LAYER_TYPE_ID,
+                    type=DIFY_USER_PROMPT_LAYER_TYPE_ID,
                     metadata={**run_input.metadata, "origin": "agent_app_user_prompt"},
-                    config=PromptLayerConfig(user=run_input.user_prompt),
+                    config=DifyUserPromptLayerConfig(text=run_input.user_prompt, files=run_input.user_files),
                 ),
                 RunLayerSpec(
                     name=DIFY_EXECUTION_CONTEXT_LAYER_ID,
@@ -332,9 +343,7 @@ class AgentBackendRunRequestBuilder:
             ]
         )
 
-        include_shell = (
-            run_input.include_shell or run_input.config_layer_config is not None or run_input.drive_config is not None
-        )
+        include_shell = run_input.include_shell or run_input.config_layer_config is not None
         if include_shell:
             layers.append(
                 RunLayerSpec(
@@ -344,16 +353,15 @@ class AgentBackendRunRequestBuilder:
                     config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),
                 )
             )
-            # Sandboxed bash workspace (dify.shell). It enters before config/drive
-            # so eager pulls materialize content in the same filesystem used by
-            # model commands.
+            # Sandboxed bash workspace (dify.shell). It enters before config so
+            # eager pulls materialize content in the same filesystem used by model commands.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
                     deps=_shell_layer_deps(),
                     metadata=run_input.metadata,
-                    config=_shell_config_with_drive_ref(run_input.shell_config, run_input.drive_config),
+                    config=run_input.shell_config or DifyShellLayerConfig(),
                 )
             )
 
@@ -368,19 +376,6 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
-        if run_input.drive_config is not None:
-            # Drive Skills & Files declaration (dify.drive): the catalog plus
-            # prompt-mentioned entries eagerly pulled through the shell layer.
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_DRIVE_LAYER_ID,
-                    type=DIFY_DRIVE_LAYER_TYPE_ID,
-                    deps=_drive_layer_deps(),
-                    metadata=run_input.metadata,
-                    config=run_input.drive_config,
-                )
-            )
-
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -400,8 +395,8 @@ class AgentBackendRunRequestBuilder:
                     plugin_id=run_input.model.plugin_id,
                     model_provider=run_input.model.model_provider,
                     model=run_input.model.model,
-                    credentials=run_input.model.credentials,
                     model_settings=_agent_model_settings(run_input.model.model_settings),
+                    context_window_tokens=run_input.model.context_window_tokens,
                 ),
             )
         )
@@ -431,6 +426,8 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.knowledge_fs is not None:
+            layers.append(_knowledge_fs_spec(run_input))
         if run_input.knowledge is not None and run_input.knowledge.sets:
             layers.append(
                 RunLayerSpec(
@@ -482,7 +479,7 @@ class AgentBackendRunRequestBuilder:
         """Build a workflow Agent Node run request without defining another wire schema.
 
         Layer graph mirrors the workflow surface: prompts → execution context →
-        optional shell / config / drive / history → LLM → optional
+        optional shell / config / history → LLM → optional
         plugin-direct tools / core-routed tools / knowledge search /
         ask_human / structured output.
         """
@@ -524,9 +521,7 @@ class AgentBackendRunRequestBuilder:
             ]
         )
 
-        include_shell = (
-            run_input.include_shell or run_input.config_layer_config is not None or run_input.drive_config is not None
-        )
+        include_shell = run_input.include_shell or run_input.config_layer_config is not None
         if include_shell:
             layers.append(
                 RunLayerSpec(
@@ -536,16 +531,15 @@ class AgentBackendRunRequestBuilder:
                     config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),
                 )
             )
-            # Sandboxed bash workspace (dify.shell). It enters before drive so
-            # drive can materialize mentioned targets with `dify-agent drive pull`
-            # in the same shell-visible filesystem used by model commands.
+            # Sandboxed bash workspace (dify.shell). It enters before config so
+            # eager pulls materialize content in the same filesystem used by model commands.
             layers.append(
                 RunLayerSpec(
                     name=DIFY_SHELL_LAYER_ID,
                     type=DIFY_SHELL_LAYER_TYPE_ID,
                     deps=_shell_layer_deps(),
                     metadata=run_input.metadata,
-                    config=_shell_config_with_drive_ref(run_input.shell_config, run_input.drive_config),
+                    config=run_input.shell_config or DifyShellLayerConfig(),
                 )
             )
 
@@ -560,19 +554,6 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
-        if run_input.drive_config is not None:
-            # Drive Skills & Files declaration (dify.drive): the catalog plus
-            # prompt-mentioned entries eagerly pulled through the shell layer.
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_DRIVE_LAYER_ID,
-                    type=DIFY_DRIVE_LAYER_TYPE_ID,
-                    deps=_drive_layer_deps(),
-                    metadata=run_input.metadata,
-                    config=run_input.drive_config,
-                )
-            )
-
         if run_input.include_history:
             layers.append(
                 RunLayerSpec(
@@ -593,8 +574,8 @@ class AgentBackendRunRequestBuilder:
                         plugin_id=run_input.model.plugin_id,
                         model_provider=run_input.model.model_provider,
                         model=run_input.model.model,
-                        credentials=run_input.model.credentials,
                         model_settings=_agent_model_settings(run_input.model.model_settings),
+                        context_window_tokens=run_input.model.context_window_tokens,
                     ),
                 ),
             ]
@@ -625,6 +606,8 @@ class AgentBackendRunRequestBuilder:
                 )
             )
 
+        if run_input.knowledge_fs is not None:
+            layers.append(_knowledge_fs_spec(run_input))
         if run_input.knowledge is not None and run_input.knowledge.sets:
             layers.append(
                 RunLayerSpec(
@@ -673,7 +656,7 @@ class AgentBackendRunRequestBuilder:
         )
 
 
-_SENSITIVE_KEY_PARTS = ("secret", "credential", "token", "password", "api_key")
+_SENSITIVE_KEY_PARTS = ("secret", "credential", "token", "password", "api_key", "base64_data")
 
 
 def redact_for_agent_backend_log(value: object) -> object:
@@ -682,9 +665,10 @@ def redact_for_agent_backend_log(value: object) -> object:
         return redact_for_agent_backend_log(value.model_dump(mode="json", warnings=False))
     if isinstance(value, dict):
         redacted: dict[object, object] = {}
+        is_multimodal_file = value.get("type") == "image" and "filename" in value and "mime_type" in value
         for key, item in value.items():
             key_text = str(key).lower()
-            if any(part in key_text for part in _SENSITIVE_KEY_PARTS):
+            if any(part in key_text for part in _SENSITIVE_KEY_PARTS) or (is_multimodal_file and key_text == "url"):
                 redacted[key] = "[REDACTED]"
             else:
                 redacted[key] = redact_for_agent_backend_log(item)

api/commands/__init__.py

@@ -10,6 +10,7 @@ from .data_migration import (
     import_migration_data,
     migration_data_wizard,
 )
+from .knowledge_fs import knowledge_fs_control_space
 from .plugin import (
     backfill_plugin_auto_upgrade,
     extract_plugins,
@@ -22,7 +23,13 @@ from .plugin import (
     setup_system_trigger_oauth_client,
     transform_datasource_credentials,
 )
-from .rbac import migrate_dataset_permissions_to_rbac, migrate_member_roles_to_rbac
+from .rbac import (
+    migrate_agent_permissions_to_rbac,
+    migrate_dataset_permissions_to_rbac,
+    migrate_member_roles_to_rbac,
+    migrate_only_me_resource_whitelist_scopes_to_automatic_include,
+    migrate_resource_whitelist_scopes_to_automatic_include,
+)
 from .retention import (
     archive_workflow_runs,
     archive_workflow_runs_plan,
@@ -75,13 +82,17 @@ __all__ = [
     "import_migration_data",
     "install_plugins",
     "install_rag_pipeline_plugins",
+    "knowledge_fs_control_space",
     "legacy_model_types",
+    "migrate_agent_permissions_to_rbac",
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",
     "migrate_dataset_permissions_to_rbac",
     "migrate_knowledge_vector_database",
     "migrate_member_roles_to_rbac",
+    "migrate_only_me_resource_whitelist_scopes_to_automatic_include",
     "migrate_oss",
+    "migrate_resource_whitelist_scopes_to_automatic_include",
     "migration_data_wizard",
     "old_metadata_migration",
     "remove_orphaned_files_on_storage",

api/commands/account.py

@@ -8,6 +8,7 @@ from constants.languages import languages
 from extensions.ext_database import db
 from libs.helper import email as email_validate
 from libs.password import hash_password, password_pattern, valid_password
+from services.account_email import normalize_email
 from services.account_service import AccountService, RegisterService, TenantService
 
 
@@ -20,7 +21,7 @@ def reset_password(email, new_password, password_confirm):
     Reset password of owner account
     Only available in SELF_HOSTED mode
     """
-    if str(new_password).strip() != str(password_confirm).strip():
+    if new_password.strip() != password_confirm.strip():
         click.echo(click.style("Passwords do not match.", fg="red"))
         return
     normalized_email = email.strip().lower()
@@ -33,7 +34,7 @@ def reset_password(email, new_password, password_confirm):
 
     try:
         valid_password(new_password)
-    except:
+    except ValueError:
         click.echo(click.style(f"Invalid password. Must match {password_pattern}", fg="red"))
         return
 
@@ -62,7 +63,7 @@ def reset_email(email, new_email, email_confirm):
     Replace account email
     :return:
     """
-    if str(new_email).strip() != str(email_confirm).strip():
+    if new_email.strip() != email_confirm.strip():
         click.echo(click.style("New emails do not match.", fg="red"))
         return
     normalized_new_email = new_email.strip().lower()
@@ -75,13 +76,14 @@ def reset_email(email, new_email, email_confirm):
 
     try:
         email_validate(normalized_new_email)
-    except:
+    except ValueError:
         click.echo(click.style(f"Invalid email: {new_email}", fg="red"))
         return
 
     with Session(db.engine) as session:
         account = session.merge(account)
         account.email = normalized_new_email
+        account.normalized_email = normalize_email(normalized_new_email)
         session.commit()
     click.echo(click.style("Email updated successfully.", fg="green"))
 

api/commands/data_migrate.py

@@ -7,7 +7,11 @@ from typing import cast
 
 import click
 
-from commands.rbac import migrate_dataset_permissions_to_rbac
+from commands.rbac import (
+    migrate_dataset_permissions_to_rbac,
+    migrate_only_me_resource_whitelist_scopes_to_automatic_include,
+    migrate_resource_whitelist_scopes_to_automatic_include,  # noqa: F401
+)
 from extensions.ext_database import db
 from graphon.model_runtime.entities.model_entities import ModelType
 from services.legacy_model_type_migration import (
@@ -179,3 +183,4 @@ def legacy_model_types(
 
 data_migrate.add_command(legacy_model_types)
 data_migrate.add_command(migrate_dataset_permissions_to_rbac)
+data_migrate.add_command(migrate_only_me_resource_whitelist_scopes_to_automatic_include)

api/commands/knowledge_fs.py

@@ -0,0 +1,621 @@
+"""Operator commands for the independent KnowledgeFS control-plane."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from datetime import datetime
+from functools import partial
+from pathlib import Path
+
+import click
+from pydantic import BaseModel, ValidationError
+
+from core.db.session_factory import session_factory
+from services.knowledge_fs.cleanup import (
+    CleanupApprovalInput,
+    CleanupCompletionEvidenceInput,
+    CleanupReadinessEvidenceInput,
+    CleanupStartInput,
+    KnowledgeFSCleanupError,
+    KnowledgeFSCleanupService,
+)
+from services.knowledge_fs.control_space_commands import KnowledgeFSControlSpaceCommandService
+from services.knowledge_fs.control_space_lifecycle import KnowledgeFSControlSpaceLifecycleError
+from services.knowledge_fs.control_space_management import (
+    KnowledgeFSControlSpaceManagementService,
+    KnowledgeFSControlSpaceRegistration,
+)
+from services.knowledge_fs.cutover import (
+    CutoverSmokeResultsInput,
+    FinalDeltaInput,
+    KnowledgeFSCutoverError,
+    KnowledgeFSWorkspaceCutoverService,
+    LegacyDependencyInput,
+    QuarantineResolutionInput,
+    ShadowAuthorizationObservationInput,
+    ShadowCompletionInput,
+    WorkspaceInventoryInput,
+)
+from services.knowledge_fs.greenfield_initializer import KnowledgeFSWorkspaceGreenfieldInitializer
+from services.knowledge_fs.orphan_reconciler import KnowledgeFSOrphanReconciler
+from services.knowledge_fs.remote_registry import get_knowledge_fs_lifecycle_remote
+
+
+@click.group("knowledge-fs-control-space")
+def knowledge_fs_control_space() -> None:
+    """Inspect and repair Dify-owned KnowledgeFS control-space state."""
+
+
+@knowledge_fs_control_space.command("dry-run")
+@click.option("--tenant-id", default=None)
+def dry_run(tenant_id: str | None) -> None:
+    report = _management_service().dry_run(tenant_id=tenant_id)
+    click.echo(json.dumps(report._asdict(), sort_keys=True))
+
+
+@knowledge_fs_control_space.command("inventory")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Create ledgers; omitted means read-only inventory.")
+def inventory(input_path: Path, apply: bool) -> None:
+    """Validate strict Workspace inventory JSONL and optionally create ledgers."""
+
+    service = _cutover_service()
+    for payload in _read_jsonl(input_path, WorkspaceInventoryInput):
+        report = _operator_call(partial(service.inventory, payload, apply=apply))
+        _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("register")
+@click.option("--tenant-id", required=True)
+@click.option("--owner-account-id", required=True)
+@click.option("--provisioning-key", required=True)
+@click.option("--knowledge-space-id", required=True)
+@click.option("--knowledge-space-revision", type=click.IntRange(min=0), required=True)
+def register(
+    tenant_id: str,
+    owner_account_id: str,
+    provisioning_key: str,
+    knowledge_space_id: str,
+    knowledge_space_revision: int,
+) -> None:
+    control_space, replayed = _management_service().register(
+        KnowledgeFSControlSpaceRegistration(
+            tenant_id,
+            owner_account_id,
+            provisioning_key,
+            knowledge_space_id,
+            knowledge_space_revision,
+        )
+    )
+    click.echo(json.dumps({"control_space_id": control_space.id, "replayed": replayed}, sort_keys=True))
+
+
+@knowledge_fs_control_space.command("backfill")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist registrations; omitted means dry-run.")
+def backfill(input_path: Path, apply: bool) -> None:
+    """Backfill strict Workspace inventory JSONL; dry-run unless --apply is explicit."""
+
+    service = _cutover_service()
+    for payload in _read_jsonl(input_path, WorkspaceInventoryInput):
+        report = _operator_call(partial(service.backfill, payload, apply=apply))
+        _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("quarantine-resolve")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist resolutions; omitted means dry-run.")
+def quarantine_resolve(input_path: Path, apply: bool) -> None:
+    """Resolve strict tenant-scoped quarantine JSONL with immutable operator evidence."""
+
+    service = _cutover_service()
+    for payload in _read_jsonl(input_path, QuarantineResolutionInput):
+        report = _operator_call(partial(service.resolve_quarantine, payload, apply=apply))
+        _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("shadow-start")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "started_at", default=None, help="Optional explicit timezone-aware shadow start.")
+def shadow_start(tenant_id: str, expected_cas_version: int, started_at: str | None) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.begin_shadow(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            started_at=_parse_timestamp(started_at) if started_at is not None else None,
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("shadow-report")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist observations; omitted means dry-run.")
+def shadow_report(input_path: Path, apply: bool) -> None:
+    observations = _read_jsonl(input_path, ShadowAuthorizationObservationInput)
+    report = _operator_call(lambda: _cutover_service().record_shadow_report(observations, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("shadow-complete")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist completion; omitted means dry-run.")
+def shadow_complete(input_path: Path, apply: bool) -> None:
+    payload = _read_one_jsonl(input_path, ShadowCompletionInput)
+    report = _operator_call(lambda: _cutover_service().complete_shadow(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("issue-approve")
+@click.option("--tenant-id", required=True)
+@click.option("--issue-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "approved_at", required=True)
+def issue_approve(tenant_id: str, issue_key: str, account_id: str, approved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().approve_issue_fail_closed(
+            tenant_id=tenant_id,
+            issue_key=issue_key,
+            account_id=account_id,
+            approved_at=_parse_timestamp(approved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("issue-resolve")
+@click.option("--tenant-id", required=True)
+@click.option("--issue-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "resolved_at", required=True)
+def issue_resolve(tenant_id: str, issue_key: str, account_id: str, resolved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().resolve_issue(
+            tenant_id=tenant_id,
+            issue_key=issue_key,
+            account_id=account_id,
+            resolved_at=_parse_timestamp(resolved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("shadow-approve")
+@click.option("--tenant-id", required=True)
+@click.option("--diff-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "approved_at", required=True)
+def shadow_approve(tenant_id: str, diff_key: str, account_id: str, approved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().approve_shadow_diff(
+            tenant_id=tenant_id,
+            diff_key=diff_key,
+            account_id=account_id,
+            approved_at=_parse_timestamp(approved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("shadow-resolve")
+@click.option("--tenant-id", required=True)
+@click.option("--diff-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "resolved_at", required=True)
+def shadow_resolve(tenant_id: str, diff_key: str, account_id: str, resolved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().resolve_shadow_diff(
+            tenant_id=tenant_id,
+            diff_key=diff_key,
+            account_id=account_id,
+            resolved_at=_parse_timestamp(resolved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("legacy-dashboard")
+@click.option("--tenant-id", required=True)
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--checked-at", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), default=None)
+@click.option("--apply", is_flag=True, default=False, help="Persist gate evidence; omitted means read-only report.")
+def legacy_dashboard(
+    tenant_id: str,
+    input_path: Path,
+    checked_at: str,
+    expected_cas_version: int | None,
+    apply: bool,
+) -> None:
+    dependencies = _read_jsonl(input_path, LegacyDependencyInput, allow_empty=True)
+    report = _operator_call(
+        lambda: _cutover_service().legacy_dependency_dashboard(
+            tenant_id=tenant_id,
+            dependencies=dependencies,
+            expected_cas_version=expected_cas_version,
+            checked_at=_parse_timestamp(checked_at),
+            apply=apply,
+        )
+    )
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("legacy-check")
+@click.option("--tenant-id", required=True)
+def legacy_check(tenant_id: str) -> None:
+    status_report = _operator_call(lambda: _cutover_service().status(tenant_id=tenant_id))
+    passed = (
+        bool(status_report["legacy_dependency_ready"])
+        and status_report["open_issues"] == 0
+        and status_report["unresolved_cutover_quarantine"] == 0
+    )
+    _echo_json({"tenant_id": tenant_id, "passed": passed, "status": status_report})
+    if not passed:
+        raise click.exceptions.Exit(1)
+
+
+@knowledge_fs_control_space.command("freeze")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "freeze_at", required=True)
+def freeze(tenant_id: str, expected_cas_version: int, freeze_at: str) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.freeze(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            freeze_at=_parse_timestamp(freeze_at),
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("final-delta")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+def final_delta(input_path: Path) -> None:
+    payload = _read_one_jsonl(input_path, FinalDeltaInput)
+    service = _cutover_service()
+    _operator_call(lambda: service.apply_final_delta(payload))
+    _echo_json(service.status(tenant_id=str(payload.tenant_id)))
+
+
+@knowledge_fs_control_space.command("cutover")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "cutover_at", required=True)
+@click.option("--rollback-cutoff-at", required=True)
+def cutover(tenant_id: str, expected_cas_version: int, cutover_at: str, rollback_cutoff_at: str) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.cutover(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            cutover_at=_parse_timestamp(cutover_at),
+            rollback_cutoff_at=_parse_timestamp(rollback_cutoff_at),
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("smoke")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+def smoke(tenant_id: str, expected_cas_version: int, input_path: Path) -> None:
+    results = _read_one_jsonl(input_path, CutoverSmokeResultsInput)
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.record_smoke_results(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            results=results,
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("observe")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--started-at", default=None)
+@click.option("--window-ends-at", default=None)
+@click.option("--maximum-task-expires-at", default=None)
+@click.option("--observed-at", default=None)
+def observe(
+    tenant_id: str,
+    expected_cas_version: int,
+    started_at: str | None,
+    window_ends_at: str | None,
+    maximum_task_expires_at: str | None,
+    observed_at: str | None,
+) -> None:
+    service = _cutover_service()
+    if observed_at is not None:
+        if any(value is not None for value in (started_at, window_ends_at, maximum_task_expires_at)):
+            raise click.UsageError("--observed-at cannot be combined with observation start options")
+        _operator_call(
+            lambda: service.complete_observation(
+                tenant_id=tenant_id,
+                expected_cas_version=expected_cas_version,
+                observed_at=_parse_timestamp(observed_at),
+            )
+        )
+    else:
+        if started_at is None or window_ends_at is None or maximum_task_expires_at is None:
+            raise click.UsageError(
+                "observation start requires --started-at, --window-ends-at, and --maximum-task-expires-at"
+            )
+        _operator_call(
+            lambda: service.begin_observation(
+                tenant_id=tenant_id,
+                expected_cas_version=expected_cas_version,
+                started_at=_parse_timestamp(started_at),
+                window_ends_at=_parse_timestamp(window_ends_at),
+                maximum_task_expires_at=_parse_timestamp(maximum_task_expires_at),
+            )
+        )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("rollback")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "rolled_back_at", required=True)
+def rollback(tenant_id: str, expected_cas_version: int, rolled_back_at: str) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.rollback(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            rolled_back_at=_parse_timestamp(rolled_back_at),
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("status")
+@click.option("--tenant-id", required=True)
+def status(tenant_id: str) -> None:
+    _echo_json(_operator_call(lambda: _cutover_service().status(tenant_id=tenant_id)))
+
+
+@knowledge_fs_control_space.command("greenfield-initialize")
+@click.option("--tenant-id", required=True)
+def greenfield_initialize(tenant_id: str) -> None:
+    """Idempotently initialize one Workspace that has no KnowledgeFS state."""
+
+    _operator_call(lambda: _greenfield_initializer().ensure_initialized(tenant_id=tenant_id))
+    _echo_json(_operator_call(lambda: _cutover_service().status(tenant_id=tenant_id)))
+
+
+@knowledge_fs_control_space.command("cleanup-request")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist readiness evidence; omitted means dry-run.")
+def cleanup_request(input_path: Path, apply: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupReadinessEvidenceInput)
+    report = _cleanup_call(lambda: _cleanup_service().request_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-approve")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist four-eyes approval; omitted means dry-run.")
+def cleanup_approve(input_path: Path, apply: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupApprovalInput)
+    report = _cleanup_call(lambda: _cleanup_service().approve_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-start")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist the irreversible fence; never runs deletion.")
+@click.option(
+    "--acknowledge-irreversible",
+    is_flag=True,
+    default=False,
+    help="Required with --apply; confirms rollback will be permanently closed.",
+)
+def cleanup_start(input_path: Path, apply: bool, acknowledge_irreversible: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupStartInput)
+    if apply and not acknowledge_irreversible:
+        raise click.UsageError("--apply requires --acknowledge-irreversible")
+    report = _cleanup_call(lambda: _cleanup_service().start_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-complete")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist externally verified cleanup completion.")
+@click.option(
+    "--acknowledge-executed",
+    is_flag=True,
+    default=False,
+    help="Required with --apply; confirms the reviewed destructive bundle already executed.",
+)
+def cleanup_complete(input_path: Path, apply: bool, acknowledge_executed: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupCompletionEvidenceInput)
+    if apply and not acknowledge_executed:
+        raise click.UsageError("--apply requires --acknowledge-executed")
+    report = _cleanup_call(lambda: _cleanup_service().complete_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-status")
+@click.option("--tenant-id", required=True)
+@click.option("--request-id", required=True)
+def cleanup_status(tenant_id: str, request_id: str) -> None:
+    _echo_json(_cleanup_call(lambda: _cleanup_service().status(tenant_id=tenant_id, request_id=request_id)))
+
+
+@knowledge_fs_control_space.command("repair")
+@click.option("--tenant-id", required=True)
+@click.option("--control-space-id", required=True)
+@click.option("--expected-resource-version", type=click.IntRange(min=0), required=True)
+@click.option("--knowledge-space-id", required=True)
+@click.option("--knowledge-space-revision", type=click.IntRange(min=0), required=True)
+def repair(
+    tenant_id: str,
+    control_space_id: str,
+    expected_resource_version: int,
+    knowledge_space_id: str,
+    knowledge_space_revision: int,
+) -> None:
+    control_space = _management_service().repair_registration(
+        tenant_id=tenant_id,
+        control_space_id=control_space_id,
+        expected_resource_version=expected_resource_version,
+        knowledge_space_id=knowledge_space_id,
+        knowledge_space_revision=knowledge_space_revision,
+    )
+    click.echo(json.dumps({"control_space_id": control_space.id, "state": control_space.state.value}, sort_keys=True))
+
+
+@knowledge_fs_control_space.command("orphan-report")
+@click.option("--limit", type=click.IntRange(min=1, max=10_000), default=500, show_default=True)
+def orphan_report(limit: int) -> None:
+    report = KnowledgeFSOrphanReconciler(
+        session_factory.get_session_maker(),
+        get_knowledge_fs_lifecycle_remote(),
+    ).reconcile(limit=limit, apply_repairs=False)
+    click.echo(json.dumps(report._asdict(), sort_keys=True))
+
+
+@knowledge_fs_control_space.command("workspace-delete-request")
+@click.option("--tenant-id", required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist durable deletion intents; omitted means dry-run.")
+def workspace_delete_request(tenant_id: str, apply: bool) -> None:
+    """Route every KnowledgeFS Space through the canonical lifecycle deletion path."""
+
+    if not apply:
+        report = _management_service().dry_run(tenant_id=tenant_id)
+        _echo_json(
+            {
+                "apply": False,
+                "by_state": report.by_state,
+                "tenant_id": tenant_id,
+                "total": report.total,
+            }
+        )
+        return
+    results = _lifecycle_call(lambda: _lifecycle_service().request_workspace_cleanup(tenant_id=tenant_id))
+    _echo_json(
+        {
+            "apply": True,
+            "control_space_ids": [result.control_space.id for result in results],
+            "operation_ids": [result.outbox.operation_id for result in results if result.outbox is not None],
+            "tenant_id": tenant_id,
+        }
+    )
+
+
+@knowledge_fs_control_space.command("workspace-delete-finalize")
+@click.option("--tenant-id", required=True)
+@click.option("--apply", is_flag=True, default=False, help="Purge terminal local control-plane rows.")
+@click.option(
+    "--acknowledge-control-plane-purge",
+    is_flag=True,
+    default=False,
+    help="Required with --apply after every remote Space has reached deleted.",
+)
+def workspace_delete_finalize(tenant_id: str, apply: bool, acknowledge_control_plane_purge: bool) -> None:
+    """Release the Workspace FK only after all remote deletions are terminal."""
+
+    service = _lifecycle_service()
+    if not apply:
+        _lifecycle_call(lambda: service.assert_workspace_deletion_allowed(tenant_id=tenant_id))
+        _echo_json({"apply": False, "ready": True, "tenant_id": tenant_id})
+        return
+    if not acknowledge_control_plane_purge:
+        raise click.UsageError("--apply requires --acknowledge-control-plane-purge")
+    deleted = _lifecycle_call(lambda: service.finalize_workspace_deletion(tenant_id=tenant_id))
+    _echo_json({"apply": True, "purged_control_spaces": deleted, "tenant_id": tenant_id})
+
+
+def _read_jsonl[InputT: BaseModel](
+    input_path: Path, input_type: type[InputT], *, allow_empty: bool = False
+) -> tuple[InputT, ...]:
+    records: list[InputT] = []
+    for line_number, line in enumerate(input_path.read_text(encoding="utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            records.append(input_type.model_validate_json(line))
+        except ValidationError as exc:
+            raise click.ClickException(f"invalid strict JSONL at line {line_number}: {exc}") from exc
+    if not records and not allow_empty:
+        raise click.ClickException("strict JSONL input must contain at least one record")
+    return tuple(records)
+
+
+def _read_one_jsonl[InputT: BaseModel](input_path: Path, input_type: type[InputT]) -> InputT:
+    records = _read_jsonl(input_path, input_type)
+    if len(records) != 1:
+        raise click.ClickException("this command requires exactly one JSONL record")
+    return records[0]
+
+
+def _parse_timestamp(value: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise click.ClickException(f"invalid ISO-8601 timestamp: {value}") from exc
+    if parsed.tzinfo is None:
+        raise click.ClickException("operator timestamps must include an explicit timezone")
+    return parsed
+
+
+def _operator_call[ResultT](operation: Callable[[], ResultT]) -> ResultT:
+    try:
+        return operation()
+    except KnowledgeFSCutoverError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _cleanup_call[ResultT](operation: Callable[[], ResultT]) -> ResultT:
+    try:
+        return operation()
+    except KnowledgeFSCleanupError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _lifecycle_call[ResultT](operation: Callable[[], ResultT]) -> ResultT:
+    try:
+        return operation()
+    except KnowledgeFSControlSpaceLifecycleError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _echo_json(payload: object) -> None:
+    click.echo(json.dumps(payload, default=str, sort_keys=True))
+
+
+def _management_service() -> KnowledgeFSControlSpaceManagementService:
+    return KnowledgeFSControlSpaceManagementService(session_factory.get_session_maker())
+
+
+def _cutover_service() -> KnowledgeFSWorkspaceCutoverService:
+    return KnowledgeFSWorkspaceCutoverService(
+        session_factory.get_session_maker(),
+        remote_factory=get_knowledge_fs_lifecycle_remote,
+    )
+
+
+def _greenfield_initializer() -> KnowledgeFSWorkspaceGreenfieldInitializer:
+    return KnowledgeFSWorkspaceGreenfieldInitializer(
+        session_factory.get_session_maker(),
+        cutover=_cutover_service(),
+    )
+
+
+def _cleanup_service() -> KnowledgeFSCleanupService:
+    return KnowledgeFSCleanupService(session_factory.get_session_maker())
+
+
+def _lifecycle_service() -> KnowledgeFSControlSpaceCommandService:
+    return KnowledgeFSControlSpaceCommandService(session_factory.get_session_maker())
+
+
+__all__ = ["knowledge_fs_control_space"]

api/commands/plugin.py

@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)
 @click.command("setup-system-tool-oauth-client", help="Setup system tool oauth client.")
 @click.option("--provider", prompt=True, help="Provider name")
 @click.option("--client-params", prompt=True, help="Client Params")
-def setup_system_tool_oauth_client(provider, client_params):
+def setup_system_tool_oauth_client(provider: str, client_params: str):
     """
     Setup system tool oauth client
     """
@@ -79,7 +79,7 @@ def setup_system_tool_oauth_client(provider, client_params):
 @click.command("setup-system-trigger-oauth-client", help="Setup system trigger oauth client.")
 @click.option("--provider", prompt=True, help="Provider name")
 @click.option("--client-params", prompt=True, help="Client Params")
-def setup_system_trigger_oauth_client(provider, client_params):
+def setup_system_trigger_oauth_client(provider: str, client_params: str):
     """
     Setup system trigger oauth client
     """
@@ -129,7 +129,7 @@ def setup_system_trigger_oauth_client(provider, client_params):
 @click.command("setup-datasource-oauth-client", help="Setup datasource oauth client.")
 @click.option("--provider", prompt=True, help="Provider name")
 @click.option("--client-params", prompt=True, help="Client Params")
-def setup_datasource_oauth_client(provider, client_params):
+def setup_datasource_oauth_client(provider: str, client_params: str):
     """
     Setup datasource oauth client
     """