Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
docs: simplify frontend review guidance (#44609)
yyh1cfcafca221e
diff --git a/.agents/skills/frontend-code-review/SKILL.md b/.agents/skills/frontend-code-review/SKILL.mdindex b8f6b046e2e..4b44c9e761d 100644--- a/.agents/skills/frontend-code-review/SKILL.md+++ b/.agents/skills/frontend-code-review/SKILL.md@@ -1,6 +1,6 @@---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: Review frontend code under `web/` or `packages/dify-ui/` when the user explicitly requests a review or audit. Supports PRs, branches, pending changes, files, and pasted diffs. Do not use for implementation-only requests, diagnosis without review intent, or backend-only code.---# Frontend Code Review@@ -9,40 +9,38 @@ Review the requested scope for concrete defects and violations of explicit proje## 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 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.+1. Resolve the requested target and scope. For a PR or branch, establish its actual base and head; do not assume the tracking branch is the review base. Include local edits only when they belong to the requested scope. Give delegated reviewers the same scope and revisions.+2. Read the changed code, its behavior owner, and the applicable scoped `AGENTS.md`. For a diff review, distinguish introduced or re-exposed defects from unrelated existing issues; a file audit may include existing defects.+3. Trace affected consumers and contracts. When logic is removed or moved, identify the behavior it preserved and where that responsibility now lives. Check affected public types, examples, and tests when they decide correctness.+4. Verify candidates against actual defaults, guards, reachable states, and documented exceptions. Report an observable failure, security boundary violation, or concrete maintenance cost. Explicit team conventions are also contracts: establish their scope without inventing user impact to justify them.## Rule Routing-Read only the packs matched by the diff:+Read only the packs for contracts affected by the change, not every topic present in a file:-- DOM semantics, focus, keyboard, forms, disabled state, or visible interaction: [`references/accessibility-ui.md`][accessibility]-- Dify UI imports, Base UI wrappers, overlays, tokens, or primitive contracts: [`references/dify-ui.md`][dify-ui]-- Component ownership, props, state, Effects, navigation, or module boundaries: [`references/component-architecture.md`][component-architecture]+- Changes to semantics, naming, keyboard/focus, forms, pending states, or responsive interaction: [`references/accessibility-ui.md`][accessibility]+- Changes to Dify UI composition, public API, primitive behavior, or state styling: [`references/dify-ui.md`][dify-ui]+- Changes to component/module ownership, props, state, Effects, or navigation: [`references/component-architecture.md`][component-architecture]- Generated clients, Query, mutations, auth, SSR, URL state, or persistence: [`references/data-query-contracts.md`][data-query]- Test files or a concrete missing-regression-test finding: [`references/testing.md`][testing]- Bundle, waterfall, rendering, or subscription cost supported by evidence: [`references/performance.md`][performance]-- Stable Dify runtime invariants in the named paths: [`references/dify-invariants.md`][dify-invariants]-- General TypeScript or styling quality not owned above: [`references/code-quality.md`][code-quality]+- Changes to type boundaries, styling composition, or localized copy not covered above: [`references/code-quality.md`][code-quality]-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.+Follow a known contract directly; use an index only to discover its owner. Project documents define local requirements; installed dependencies and their public APIs establish version-specific behavior. Resolve disagreements with implementation and tests rather than treating existing code as the standard. For unresolved framework, browser, or accessibility behavior, consult current official documentation or standards; use a targeted guidance search when it helps locate them.## 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, or a material violation of an explicit project contract.+- **P0**: critical impact requiring immediate intervention, such as widespread unavailability, severe data loss, or a security/privacy breach.+- **P1**: major reachable failure of a primary workflow or public contract that should block delivery.+- **P2**: narrower correctness, accessibility, performance, or test defect; concrete maintenance cost; 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 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.+Choose severity by impact, reachability, and recovery, not by topic; accessibility failures are correctness defects. Lead with verified findings ordered by severity. Include a tight file and line reference, the triggering scenario or applicable project rule, and a concrete fix direction. Deduplicate findings with the same cause. State material verification gaps separately; lack of verification is not itself a defect. When no findings remain, say so briefly. 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[component-architecture]: references/component-architecture.md[data-query]: references/data-query-contracts.md-[dify-invariants]: references/dify-invariants.md[dify-ui]: references/dify-ui.md[performance]: references/performance.md[testing]: references/testing.mddiff --git a/.agents/skills/frontend-code-review/references/accessibility-ui.md b/.agents/skills/frontend-code-review/references/accessibility-ui.mdindex ed3dc42b6e2..b92154ea5f7 100644--- a/.agents/skills/frontend-code-review/references/accessibility-ui.md+++ b/.agents/skills/frontend-code-review/references/accessibility-ui.md@@ -1,135 +1,83 @@-# Accessibility And UI Rules--Accessibility findings are first-class review findings. Treat broken keyboard access, missing accessible names, focus loss, and unreachable popup content as correctness bugs, not polish.--## Review Evidence--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 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:--- Interactive elements without visible `focus-visible` treatment.-- `outline-none` / `outline-hidden` without an equivalent focus-visible ring or state.-- Custom interactive elements missing keyboard handling.-- Focus trapped, lost, or sent to the wrong surface after dialog/popover/menu close.-- Focus ring applied to the wrong DOM node. Verify the actual focus target, especially with Base UI controls such as Slider.--Use `focus-visible` for keyboard focus. Use `focus-within` or `has-[:focus-visible]` when the visual wrapper is not the focused element.+# Accessibility And Interaction Review++Broken keyboard access, missing accessible names, focus loss, and unreachable content are+correctness defects. Review the rendered behavior and the feature's workflow, including the+primitive defaults and composed props. Missing attributes, handlers, or classes at a call site+do not establish a defect when their owner already supplies them.++## Semantics And Names++- Does the final element preserve the intended action, navigation, or field semantics and its+ keyboard behavior? Check the primitive's composition contract before judging its rendered tag.+- Do controls, meaningful images, and icon-only actions have usable text alternatives? Does+ decorative content interfere with the resulting name or accessibility tree?+- When labels, help, errors, or hidden text change, read [Accessible names and descriptions].+ Check computed names and descriptions in the affected states, including content that unmounts.+ A matching `aria-label` string alone does not establish a redundant override.+- For page structure changes, read [Page landmarks] and inspect the composed page with its parent+ layouts. Check heading relationships, landmark names, and affected semantic test locators.++## Keyboard, Focus, And Async Transitions++- Can users reach, operate, and leave the changed control or surface by keyboard? Follow+ [Keyboard commands] for application hotkeys; widget key behavior belongs to its primitive.+- Is the actual focus target visibly indicated? Read [Styling] for indicator ownership, including+ text controls and wrappers around native inputs. Fix the owning component instead of adding+ duplicate indicators at call sites.+- Does focus remain useful through pending, success, failure, dismissal, and retry? Check the+ focused control, the next keyboard action, and any focus-return target when availability changes.+ Follow the [Button contract] for loading and disabled buttons; other controls need their own+ interaction contract, not an automatic native-disabled or `aria-disabled` substitution.+- Are unavailable actions blocked through supported pointer and keyboard paths? Check existing+ primitive handling before requesting additional event guards.+- Can users understand why they cannot proceed and perceive the status needed to continue?+ Keep names available during loading and check the feature-owned feedback path. For Web toasts,+ follow [Toasts] rather than requiring a toast or live region for every state change.## Forms-Flag:--- Inputs, selects, switches, checkboxes, radios, comboboxes, or sliders without a label relationship.-- Missing stable `name` on form fields that submit or validate.-- Incorrect input `type`, `inputMode`, `autoComplete`, or `spellCheck` for email, token, URL, number, search, code, or username fields.-- Labels that are not clickable.-- Non-submit buttons inside forms missing `type="button"`.-- Errors not associated with fields or not reachable by screen readers.-- Error recovery that does not focus or expose the first invalid field.-- `onPaste` blocking paste.-- Placeholder text used as the only label.-- Password managers accidentally triggered on non-auth fields because autocomplete is missing or wrong.--Prefer visible labels 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 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.-- 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.--Use native `disabled` when the control must not be interactive. Use `aria-disabled` only when the element must remain focusable and the code handles all blocked interactions.--For repeated shared disabled reasons, prefer a visible group message or badge plus native disabled controls. Use per-control popover/info only when the reason is item-specific.--## Overlays And Popup Reachability--Flag:--- Tooltip used for long, structured, interactive, or unique information.-- Tooltip content required to understand or complete a flow.-- PreviewCard content that touch or screen-reader users cannot reach through the trigger's click destination.-- Popover/dialog/menu triggers without accessible names.-- Popup content without title/description where the primitive requires them.--Use Popover for explanatory content, rich help, and infotips. Use Tooltip only as a short visual label for a trigger that already has an accessible name.+Read [Forms] when submission, field composition, validation, or reset behavior changes.-## Long Content And Layout+- Does the intended form own submission, including keyboard submission? Check final button types+ and primitive defaults instead of requiring redundant `type` props at every call site.+- Do the intended values participate in submission and validation, with the right name and+ disabled/read-only behavior? Follow the selected control's contract for labels and value types.+- Can users enter the required data with supported input methods, paste, and relevant autofill?+ Verify input attributes against the field's purpose rather than applying one input template.+- Are errors associated with their fields, exposed at the right time, and recoverable? Verify+ invalid-field focus and reset through the actual form/control integration.-Flag:+## Overlays And Content Reachability-- Text in flex/grid children without `min-w-0` when it can overflow.-- 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.+Read [Overlays] for semantic selection, portals, presence, layering, and dismissal. Use the+[Infotip contract] when an information icon opens an explanation; text length alone does not+choose between Tooltip, Infotip, and Popover.-The usual Dify layout chain is: container has width constraints, text region uses `min-w-0 flex-1 truncate`, adornments use `shrink-0`.+- Can pointer, keyboard, touch, and assistive-technology users reach content needed for the flow?+ A supplementary hover preview must not be the only route to essential information.+- Does the trigger keep its name while closed, and does the open popup have the required name?+ Check the selected primitive's contract before adding titles or descriptions.+- Do open/close transitions preserve the intended focus, dismissal, and draft lifetime? Trace the+ root and content lifetimes separately; portal placement alone does not reset ancestor state.-## Motion, Images, And Copy+## Visual And Runtime Evidence-Flag:+For changed layouts, check whether long or localized content, supported viewport sizes, zoom,+or forced colors obscure information, controls, or focus. For changed motion, check relevant+reduced-motion behavior and whether interaction remains usable. Report the demonstrated failure,+not the absence of a preferred CSS utility.-- `transition-all`.-- Animations that do not respect reduced motion.-- Layout-affecting animation where transform/opacity would work.-- Images without dimensions.-- Loading copy using `...` instead of `…`.-- Hardcoded dates, times, numbers, or currency formats instead of `Intl.*`.+When source evidence cannot settle native focus transitions, keyboard behavior, layout, or popup+presence, verify in the browser. Mocked DOM results and type checks alone do not establish those+behaviors. Consult current official Base UI documentation, installed declarations, or browser+and accessibility standards when the relevant local contract does not settle the question.[Accessible names and descriptions]: ../../../../packages/dify-ui/docs/accessible-names-and-descriptions.md+[Button contract]: ../../../../packages/dify-ui/src/button/README.md+[Forms]: ../../../../packages/dify-ui/docs/forms.md+[Infotip contract]: ../../../../packages/dify-ui/src/infotip/README.md+[Keyboard commands]: ../../../../web/docs/hotkeys.md+[Overlays]: ../../../../packages/dify-ui/docs/overlays.md[Page landmarks]: ../../../../web/docs/landmarks.md-[Web Interface Guidelines]: https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md+[Styling]: ../../../../packages/dify-ui/docs/styling.md+[Toasts]: ../../../../web/docs/toasts.mddiff --git a/.agents/skills/frontend-code-review/references/code-quality.md b/.agents/skills/frontend-code-review/references/code-quality.mdindex 862c03a66f6..48d3aef839a 100644--- a/.agents/skills/frontend-code-review/references/code-quality.md+++ b/.agents/skills/frontend-code-review/references/code-quality.md@@ -1,71 +1,34 @@-# Code Quality Rules--## Scope Control--Flag changes that expand beyond the requested feature or review scope:--- Repo-wide cleanup mixed into a targeted fix.-- Compatibility exports, aliases, shims, or wrapper layers added without an explicit migration requirement.-- Shared abstractions created before there is stable cross-feature reuse.-- Business components moved into generic shared locations without a clear ownership boundary.--## TypeScript--Flag:--- `any` or broad `Record<string, any>` where generated/API types or local domain types exist.-- Re-declared API shapes instead of importing generated or returned types.-- Weak route/query param typing that leaks `string | string[] | undefined` deep into components.-- Runtime wrappers added only to satisfy TypeScript when a narrower type boundary would preserve the existing runtime shape.--Prefer:--- Explicit domain names that match the API contract.-- Type narrowing at route/API boundaries.-- Small conversion helpers colocated with the component that needs them.--## 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 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 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.-- Z-index, forced backdrops, or other one-off layering fixes on overlays and body-level portals.--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.-- 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--Flag:--- Barrel imports from `@langgenius/dify-ui`; consumers must use subpath exports.-- New overlay imports from legacy `@/app/components/base/modal`, `dialog`, or `drawer`.-- Cross-feature imports that bypass explicit top-level public files.-- Direct imports from generated/internal implementation files when a feature contract already exposes the intended surface.--## Copy And i18n--Flag:--- User-facing hardcoded strings in `web/`.-- Added or renamed i18n keys that are not present in every supported locale file for the touched namespace.-- Translation namespace drift, especially using unrelated module namespaces for local feature copy.-- Generic button labels like `Continue` where the action is specific.-- Error messages that state only the failure and not the next step.--Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.-+# Code Quality Review++Use this pack for changed type, styling, or copy contracts. Scope and reporting thresholds come+from the skill entrypoint; do not turn general style preferences into findings.++## Types And Boundaries++[Ownership] defines module boundaries, extraction, props, and domain types; [Data] owns generated+API types. For Dify UI public exports and upstream-derived props, use [Public API authoring].++- Identify the actual type information lost by a widened field, DTO mirror, or assertion. Trace+ consumers before proposing a new abstraction or adapter.+- Check that moved imports still use the intended public boundary. Distinguish an application+ bypassing that boundary from the implementation that owns a library integration.+- Require a real migration or compatibility need for new aliases and forwarding layers. Check+ whether an existing owner can express the behavior with less state or indirection.++## Styling And Copy++- Use [Styling] for tokens, class composition, state callbacks, and focus ownership, and [Overlays]+ for portal/layering changes. Report the violated contract or rendered failure, not the absence+ of a preferred utility class.+- Apply [Web requirements] to localized strings and supported locales. Keep keys in the owning+ feature namespace; aliases are for crossing namespaces. Verify changed keys and interpolation+ against their consumers rather than reviewing only the English text.+- Check whether action and recovery copy explains the real next step. A generic label or wording+ preference alone is not a defect; establish ambiguity or an applicable naming contract.++[Data]: ../../how-to-write-component/references/data.md+[Overlays]: ../../../../packages/dify-ui/docs/overlays.md+[Ownership]: ../../how-to-write-component/references/ownership.md+[Public API authoring]: ../../../../packages/dify-ui/docs/authoring.md[Styling]: ../../../../packages/dify-ui/docs/styling.md+[Web requirements]: ../../../../web/AGENTS.mddiff --git a/.agents/skills/frontend-code-review/references/data-query-contracts.md b/.agents/skills/frontend-code-review/references/data-query-contracts.mdindex 686431c38df..424ac33edfb 100644--- a/.agents/skills/frontend-code-review/references/data-query-contracts.md+++ b/.agents/skills/frontend-code-review/references/data-query-contracts.md@@ -10,13 +10,14 @@ Review explicit team conventions as contracts, including direct generated option- 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.-- Check whether a new or changed toast reports something the user cannot already see. Flag a success toast for a result visible in place, a second error toast for a failure another layer already reports, and validation reported through a toast.+- Trace feature feedback and shared error handling before adding or keeping a toast; apply the [Toast contract] to the result visible to the user.## Imperative Access And SSR- 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.+- Check server-side authorization and request/tenant isolation independently of rendering performance, including server actions and shared caches.## Tenant, URL, And Persistence Boundaries@@ -27,3 +28,4 @@ Report the violated rule and applicable scope or the concrete failing path. Do n[Data and queries]: ../../how-to-write-component/references/data.md[State ownership]: ../../how-to-write-component/references/state.md+[Toast contract]: ../../../../web/docs/toasts.mddiff --git a/.agents/skills/frontend-code-review/references/dify-invariants.md b/.agents/skills/frontend-code-review/references/dify-invariants.mddeleted file mode 100644index c6934b06bf6..00000000000--- a/.agents/skills/frontend-code-review/references/dify-invariants.md+++ /dev/null@@ -1,22 +0,0 @@-# Dify Invariants--Use these stable Dify-specific runtime rules in addition to the generic review packs.--This file is not a place for active feature notes. Do not add rules for one branch, one PR, or a short-lived product decision such as a specific agent-v2, plugin, model-provider, or onboarding task. Keep a rule here only when all of these are true:--- It is a stable Dify runtime invariant.-- Generic React, TypeScript, accessibility, dify-ui, query, or performance rules would not catch it.-- The failure mode is concrete enough to produce a file-line review finding.-- The rule is likely to remain valid across normal feature work.--## Workflow Nodes And RAG Pipe--Flag:--- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` importing workflow store hooks that are unavailable in RAG Pipe template rendering.-- Node UI relying on provider context that is not mounted in every rendering surface.-- Store reads in render where React Flow `useNodes` / `useEdges` provide the actual node/edge source.--Known failure mode: workflow node components can also render while creating a RAG Pipe from a template. In that context there may be no workflowStore provider, causing a blank screen.--Prefer React Flow hooks for node/edge UI consumption. Use store APIs only where the provider is guaranteed and the code path is workflow-only.diff --git a/.agents/skills/frontend-code-review/references/dify-ui.md b/.agents/skills/frontend-code-review/references/dify-ui.mdindex 4a1619c2492..9cc4da33006 100644--- a/.agents/skills/frontend-code-review/references/dify-ui.md+++ b/.agents/skills/frontend-code-review/references/dify-ui.md@@ -1,29 +1,38 @@# Dify UI Review Routing-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.+Use this reference for changes to `packages/dify-ui/` or its application consumers. Review the+contract owned by the changed layer: upstream behavior, Dify primitive integration, or feature+composition.-Read `packages/dify-ui/AGENTS.md` and the primitive implementation first, then only the matching-owner:+## Find The Owner-| 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 changes follow [Package rules]; Web consumers follow [Web rules]. Keep their respective+ package boundaries and application requirements in scope.+- If the affected contract is known, read its owner guide directly. Use the [Package index] only+ to discover available primitives, public subpaths, or the matching guide; do not load every guide.+- Trace implementation, public types, tests, and stories as needed to decide a candidate. If they+ disagree with documentation, establish which contract applies before reporting a violation.+- For upstream-derived behavior, check the installed API and current official [Base UI docs].+ Do not assume the latest upstream example matches the installed version or Dify wrapper.-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.+## Check The Changed Boundary-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.+- Does a wrapper preserve the public types, value relationships, events, and anatomy its consumers+ rely on? Follow the package's public API authoring contract when that surface changes.+- Does `render` composition forward the required props and ref, preserve event handling, and read+ state from the owning part? Use the styling and upstream composition contracts to check callback+ merging; do not introduce parallel React state merely to reproduce primitive state styles.+- Does the change preserve the documented owner of focus, positioning, portals, and dismissal?+ Check shared fixes at that owner and feature-specific composition at the consumer. Consult the+ overlay contract for presence and the form/control contract for labels, values, and validation.+- For custom primitive integrations, trace the upstream APIs they actually use and verify the+ resulting public behavior. A thin passthrough and a Dify-authored Field/Form integration have+ different responsibilities; test those responsibilities without duplicating upstream coverage.++Report an observable defect or an applicable explicit contract violation. Do not turn a preferred+composition, a newer upstream example, or a missing call-site style into a finding on its own.++[Base UI docs]: https://base-ui.com/react+[Package index]: ../../../../packages/dify-ui/README.md+[Package rules]: ../../../../packages/dify-ui/AGENTS.md+[Web rules]: ../../../../web/AGENTS.mddiff --git a/.agents/skills/frontend-code-review/references/performance.md b/.agents/skills/frontend-code-review/references/performance.mdindex 1e9aaf8ce5d..84f79bba4d7 100644--- a/.agents/skills/frontend-code-review/references/performance.md+++ b/.agents/skills/frontend-code-review/references/performance.md@@ -1,76 +1,24 @@-# Performance Rules+# Performance Review-Review performance only where there is realistic impact. Do not request `memo`, `useMemo`, `useCallback`, virtualization, or caching as style preferences.+Use [Runtime] for ownership, Effects, request concurrency, optional surfaces, and subscription rules. Use [Data and queries] for cache, SSR, authentication, and tenant boundaries. These references own the rules; this pack adds evidence questions.-## Async Waterfalls+## Establish The Cost-Flag:+Report a reachable cost with a causal path, such as request ordering, bundle output, repeated expensive computation, or browser rendering evidence. A missing optimization alone is not a finding.-- Awaiting remote feature flags or fetches before checking cheap synchronous conditions.-- Sequential awaits for independent operations.-- API routes or server components starting requests late when they could start early.-- Nested per-item fetches running serially when each item can fetch in parallel.-- Suspense boundaries that force the whole page to wait when a lower boundary could stream or isolate loading.+- For waterfalls, establish that the requests are independent and on the user-visible critical path. Preserve execution conditions and failure ownership when proposing concurrency or streaming.+- For eager imports, identify the module's cost and when the feature needs it. Check actual bundler behavior before treating a barrel import or dynamic path as a bundle regression.+- For server work, identify duplicated requests or serialized data and the request-local owner that can safely deduplicate them.+- For subscriptions and rendering, trace the changing value to the affected consumer before proposing narrower state, selectors, or memoization.+- For lists, layout, and motion, establish the supported data size or interaction and the rendering cost. Do not request virtualization, caching, or an animation rewrite solely because a particular API or CSS property appears.-Prefer `Promise.all` for independent work and branch-local awaits for conditionally needed data.+## Distinguish Value And Reference Identity-## Bundle Size+- TanStack Query keys are hashed by value by default. Recreating an equivalent key or generated input/options object does not itself create a new query or justify `useMemo`; inspect the key's values and query policy. See [Query keys].+- Query `select` functions can recompute when their reference changes. Require a stable selector only when that recomputation has a demonstrated cost. The top-level query result is intentionally not referentially stable; read the fields the consumer needs. See [Query render optimizations].+- For React dependencies, memoized children, and library APIs, identify the specific consumer whose behavior or cost depends on reference identity. First check that an Effect belongs there; do not use memoization to hide an ownership or dependency problem.-Flag:--- Barrel imports from heavy libraries or `@langgenius/dify-ui`.-- Dynamic paths that prevent static trace analysis.-- Heavy components loaded eagerly when hidden behind a dialog, tab, command, or feature activation.-- Analytics, logging, editor, visualization, or third-party SDK code loaded before it is needed.-- Feature-local optional modules imported at top level only for rare flows.--Use direct imports and `next/dynamic` where the user-visible path benefits.--## Server Rendering--Flag:--- Request-specific mutable state stored at module scope in SSR/RSC paths.-- Large duplicate data serialized across RSC/client boundaries.-- Static I/O repeated per request when it could be hoisted safely.-- Cross-request cache without a bounded invalidation strategy.-- Server actions lacking API-route-equivalent auth checks.--Use request-scoped deduplication such as `React.cache()` when repeated server reads in one request are the problem.--## Re-rendering--Flag:--- Effects or subscriptions reading broad state when a derived boolean or narrower selector is enough.-- Components defined inside components.-- Derived rendering state stored in state/effects.-- Non-primitive default props recreated for memoized children.-- Expensive work recalculated on every render where it affects real interaction cost.-- High-frequency transient values stored in state when refs or CSS variables would avoid render loops.--Do not flag simple primitive expressions wrapped or not wrapped in `useMemo`; prefer no memo for simple work.--Require stable object/array/function identity only when:--- The child is memoized and identity affects renders.-- The value is an effect/query dependency.-- A library API requires stable references.-- Profiling or local behavior shows avoidable re-rendering.--## DOM, Lists, And Rendering--Flag:--- Layout reads in render (`getBoundingClientRect`, `offset*`, `scrollTop`).-- Interleaved DOM reads/writes that can cause layout thrashing.-- Large lists rendering without virtualization, pagination, or `content-visibility`.-- SVG/animation code animating expensive properties when transform/opacity would work.-- `transition-all`.-- Long-running non-critical browser work performed immediately instead of idle/deferred scheduling.--## React Flow--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`.--[Dify invariants]: dify-invariants.md+[Data and queries]: data-query-contracts.md+[Query keys]: https://tanstack.com/query/latest/docs/framework/react/guides/query-keys+[Query render optimizations]: https://tanstack.com/query/latest/docs/framework/react/guides/render-optimizations+[Runtime]: ../../how-to-write-component/references/runtime.mddiff --git a/.agents/skills/how-to-write-component/references/data.md b/.agents/skills/how-to-write-component/references/data.mdindex bff14eca6ce..6fb5eeee92b 100644--- a/.agents/skills/how-to-write-component/references/data.md+++ b/.agents/skills/how-to-write-component/references/data.md@@ -48,6 +48,7 @@ Read this document when a component consumes generated contracts, nullable API v- 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.+- Enforce authentication and authorization at each server action or API boundary; a client guard does not protect server execution. Keep request-specific mutable state scoped to its request, and partition shared sensitive caches by authoritative identity.- Treat Server Components as query prefetch-and-dehydrate owners by default. Do not render or pass an imperative queryresult 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, adiff --git a/packages/dify-ui/docs/styling.md b/packages/dify-ui/docs/styling.mdindex 63cd359a48a..a29542b424d 100644--- a/packages/dify-ui/docs/styling.md+++ b/packages/dify-ui/docs/styling.md@@ -34,6 +34,9 @@ See Base UI's [styling] and [composition] guides for the upstream contracts.## Tailwind CSS v4+When merging default classes with an incoming `className`, use the local `cn(...)` helper and put+defaults first so callers can override them. Resolve state callbacks before merging their classes.+Import Tailwind from the consumer's root stylesheet as described in the [Tailwind CSS v4 upgradeguide], then import the Dify UI CSS entry: