fix(knowledge): respect TiDB collection deletion constraints

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

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

@@ -0,0 +1,40 @@
+---
+name: backend-code-review
+description: Use only when the user explicitly requests a review or audit of backend code under `api/`. Supports pending-change, file-focused, and pasted-diff reviews. Do not use for implementation-only requests, diagnosis without review intent, frontend code, or backend code outside `api/`.
+---
+
+# Backend Code Review
+
+Review the requested scope for concrete, reproducible defects. The nearest `AGENTS.md` owns package facts and commands; this skill owns the review workflow and routes to its bundled rule packs.
+
+## Evidence First
+
+1. Establish the requested review scope and inspect the relevant diff or files.
+2. Read the changed lines, their behavior owner, nearby tests, and local docstrings or comments that define contracts.
+3. Trace callers, persistence boundaries, authorization, generated schemas, or external I/O only when they decide correctness.
+4. Report only findings tied to an observable failure, violated contract, security boundary, data integrity risk, or demonstrated maintenance problem.
+
+## Rule Routing
+
+Read only the packs matched by the diff:
+
+- Models or migrations: [`references/db-schema-rule.md`][db-schema]
+- Controller, service, core/domain, library, or model dependency direction: [`references/architecture-rule.md`][architecture]
+- Table access outside an established repository boundary: [`references/repositories-rule.md`][repositories]
+- SQLAlchemy sessions, queries, transactions, CRUD, concurrency, or raw SQL: [`references/sqlalchemy-rule.md`][sqlalchemy]
+
+When no pack applies, review correctness, security, behavior changes, and test evidence directly. Check current official documentation only when local code and contracts do not settle framework or library behavior.
+
+## Severity And Output
+
+- **P0**: security or privacy exposure, data loss, or a production-wide outage.
+- **P1**: user-visible regression, broken authorization or tenant isolation, invalid public contract, or failed primary workflow.
+- **P2**: concrete correctness, performance, maintainability, or test defect likely to cause incorrect behavior.
+- **P3**: minor actionable cleanup; omit unless the user requested a thorough audit.
+
+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.
+
+[architecture]: references/architecture-rule.md
+[db-schema]: references/db-schema-rule.md
+[repositories]: references/repositories-rule.md
+[sqlalchemy]: references/sqlalchemy-rule.md

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

@@ -0,0 +1,93 @@
+# Rule Catalog — Architecture
+
+## Scope
+- Covers: controller/service/core-domain/libs/model layering, dependency direction, responsibility placement, observability-friendly flow.
+
+## Rules
+
+### Keep business logic out of controllers
+- Category: maintainability
+- Description: Controllers should parse input, call services, and return serialized responses. Business decisions inside controllers make behavior hard to reuse and test.
+- Suggested fix: Move domain/business logic into the service or core/domain layer. Keep controller handlers thin and orchestration-focused.
+- Example:
+  - Bad:
+    ```python
+    @bp.post("/apps/<app_id>/publish")
+    def publish_app(app_id: str):
+        payload = request.get_json() or {}
+        if payload.get("force") and current_user.role != "admin":
+            raise ValueError("only admin can force publish")
+        app = App.query.get(app_id)
+        app.status = "published"
+        db.session.commit()
+        return {"result": "ok"}
+    ```
+  - Good:
+    ```python
+    @bp.post("/apps/<app_id>/publish")
+    def publish_app(app_id: str):
+        payload = PublishRequest.model_validate(request.get_json() or {})
+        app_service.publish_app(app_id=app_id, force=payload.force, actor_id=current_user.id)
+        return {"result": "ok"}
+    ```
+
+### Preserve layer dependency direction
+- Category: best practices
+- Description: Controllers may depend on services, and services may depend on core/domain abstractions. Reversing this direction (for example, core importing controller/web modules) creates cycles and leaks transport concerns into domain code.
+- Suggested fix: Extract shared contracts into core/domain or service-level modules and make upper layers depend on lower, not the reverse.
+- Example:
+  - Bad:
+    ```python
+    # core/policy/publish_policy.py
+    from controllers.console.app import request_context
+
+
+    def can_publish() -> bool:
+        return request_context.current_user.is_admin
+    ```
+  - Good:
+    ```python
+    # core/policy/publish_policy.py
+    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)
+    ```
+
+### Keep libs business-agnostic
+- Category: maintainability
+- Description: Modules under `api/libs/` should remain reusable, business-agnostic building blocks. They must not encode product/domain-specific rules, workflow orchestration, or business decisions.
+- Suggested fix:
+  - If business logic appears in `api/libs/`, extract it into the appropriate `services/` or `core/` module and keep `libs` focused on generic, cross-cutting helpers.
+  - Keep `libs` dependencies clean: avoid importing service/controller/domain-specific modules into `api/libs/`.
+- Example:
+  - Bad:
+    ```python
+    # api/libs/conversation_filter.py
+    from services.conversation_service import ConversationService
+
+
+    def should_archive_conversation(conversation, tenant_id: str) -> bool:
+        # Domain policy and service dependency are leaking into libs.
+        service = ConversationService()
+        if service.has_paid_plan(tenant_id):
+            return conversation.idle_days > 90
+        return conversation.idle_days > 30
+    ```
+  - Good:
+    ```python
+    # api/libs/datetime_utils.py (business-agnostic helper)
+    def older_than_days(idle_days: int, threshold_days: int) -> bool:
+        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

@@ -0,0 +1,154 @@
+# Rule Catalog — DB Schema Design
+
+## Scope
+- Covers: model/base inheritance, schema boundaries in model properties, tenant-aware schema design, index redundancy checks, dialect portability in models, and cross-database compatibility in migrations.
+- Does NOT cover: session lifecycle, transaction boundaries, and query execution patterns (handled by `sqlalchemy-rule.md`).
+
+## Rules
+
+### Do not query other tables inside `@property`
+- Category: [maintainability, performance]
+- Description: A model `@property` must not open sessions or query other tables. This hides dependencies across models, tightly couples schema objects to data access, and can cause N+1 query explosions when iterating collections.
+- Suggested fix:
+  - Keep model properties pure and local to already-loaded fields.
+  - Move cross-table data fetching to service/repository methods.
+  - For list/batch reads, fetch required related data explicitly (join/preload/bulk query) before rendering derived values.
+- Example:
+  - Bad:
+    ```python
+    class Conversation(TypeBase):
+        __tablename__ = "conversations"
+
+        @property
+        def app_name(self) -> str:
+            with Session(db.engine, expire_on_commit=False) as session:
+                app = session.execute(select(App).where(App.id == self.app_id)).scalar_one()
+                return app.name
+    ```
+  - Good:
+    ```python
+    class Conversation(TypeBase):
+        __tablename__ = "conversations"
+
+        @property
+        def display_title(self) -> str:
+            return self.name or "Untitled"
+
+
+    # Service/repository layer performs explicit batch fetch for related App rows.
+    ```
+
+### Prefer including `tenant_id` in model definitions
+- Category: maintainability
+- Description: In multi-tenant domains, include `tenant_id` in schema definitions whenever the entity belongs to tenant-owned data. This improves data isolation safety and keeps future partitioning/sharding strategies practical as data volume grows.
+- Suggested fix:
+  - Add a `tenant_id` column and ensure related unique/index constraints include tenant dimension when applicable.
+  - Propagate `tenant_id` through service/repository contracts to keep access paths tenant-aware.
+  - Exception: if a table is explicitly designed as non-tenant-scoped global metadata, document that design decision clearly.
+- Example:
+  - Bad:
+    ```python
+    from sqlalchemy.orm import Mapped
+
+
+    class Dataset(TypeBase):
+        __tablename__ = "datasets"
+        id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
+        name: Mapped[str] = mapped_column(sa.String(255), nullable=False)
+    ```
+  - Good:
+    ```python
+    from sqlalchemy.orm import Mapped
+
+
+    class Dataset(TypeBase):
+        __tablename__ = "datasets"
+        id: Mapped[str] = mapped_column(StringUUID, primary_key=True)
+        tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False, index=True)
+        name: Mapped[str] = mapped_column(sa.String(255), nullable=False)
+    ```
+
+### Detect and avoid duplicate/redundant indexes
+- Category: performance
+- Description: Review index definitions for leftmost-prefix redundancy. For example, index `(a, b, c)` can safely cover most lookups for `(a, b)`. Keeping both may increase write overhead and can mislead the optimizer into suboptimal execution plans.
+- Suggested fix:
+  - Before adding an index, compare against existing composite indexes by leftmost-prefix rules.
+  - Drop or avoid creating redundant prefixes unless there is a proven query-pattern need.
+  - Apply the same review standard in both model `__table_args__` and migration index DDL.
+- Example:
+  - Bad:
+    ```python
+    __table_args__ = (
+        sa.Index("idx_msg_tenant_app", "tenant_id", "app_id"),
+        sa.Index("idx_msg_tenant_app_created", "tenant_id", "app_id", "created_at"),
+    )
+    ```
+  - Good:
+    ```python
+    __table_args__ = (
+        # Keep the wider index unless profiling proves a dedicated short index is needed.
+        sa.Index("idx_msg_tenant_app_created", "tenant_id", "app_id", "created_at"),
+    )
+    ```
+
+### Avoid PostgreSQL-only dialect usage in models; wrap in `models.types`
+- Category: maintainability
+- Description: Model/schema definitions should avoid PostgreSQL-only constructs directly in business models. When database-specific behavior is required, encapsulate it in `api/models/types.py` using both PostgreSQL and MySQL dialect implementations, then consume that abstraction from model code.
+- Suggested fix:
+  - Do not directly place dialect-only types/operators in model columns when a portable wrapper can be used.
+  - Add or extend wrappers in `models.types` (for example, `AdjustedJSON`, `LongText`, `BinaryData`) to normalize behavior across PostgreSQL and MySQL.
+- Example:
+  - Bad:
+    ```python
+    from sqlalchemy.dialects.postgresql import JSONB
+    from sqlalchemy.orm import Mapped
+
+
+    class ToolConfig(TypeBase):
+        __tablename__ = "tool_configs"
+        config: Mapped[dict] = mapped_column(JSONB, nullable=False)
+    ```
+  - Good:
+    ```python
+    from sqlalchemy.orm import Mapped
+
+    from models.types import AdjustedJSON
+
+
+    class ToolConfig(TypeBase):
+        __tablename__ = "tool_configs"
+        config: Mapped[dict] = mapped_column(AdjustedJSON(), nullable=False)
+    ```
+
+### Guard migration incompatibilities with dialect checks and shared types
+- Category: maintainability
+- Description: Migration scripts under `api/migrations/versions/` must account for PostgreSQL/MySQL incompatibilities explicitly. For dialect-sensitive DDL or defaults, branch on the active dialect (for example, `conn.dialect.name == "postgresql"`), and prefer reusable compatibility abstractions from `models.types` where applicable.
+- Suggested fix:
+  - In migration upgrades/downgrades, bind connection and branch by dialect for incompatible SQL fragments.
+  - Reuse `models.types` wrappers in column definitions when that keeps behavior aligned with runtime models.
+  - Avoid one-dialect-only migration logic unless there is a documented, deliberate compatibility exception.
+- Example:
+  - Bad:
+    ```python
+    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=sa.text("'database'::character varying"),
+                nullable=False,
+            )
+        )
+    ```
+  - Good:
+    ```python
+    def _is_pg(conn) -> bool:
+        return conn.dialect.name == "postgresql"
+
+
+    conn = op.get_bind()
+    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))
+    ```

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

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

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

@@ -0,0 +1,133 @@
+# Rule Catalog — SQLAlchemy Patterns
+
+## Scope
+- Covers: SQLAlchemy session and transaction lifecycle, query construction, tenant scoping, raw SQL boundaries, and write-path concurrency safeguards.
+- Does NOT cover: table/model schema and migration design details (handled by `db-schema-rule.md`).
+
+## Rules
+
+### Use Session context manager with explicit transaction control behavior
+- Category: best practices
+- Description: Session and transaction lifecycle must be explicit and bounded on write paths. Missing commits can silently drop intended updates, while ad-hoc or long-lived transactions increase contention, lock duration, and deadlock risk.
+- Suggested fix:
+  - Use **explicit `session.commit()`** after completing a related write unit.
+  - Or use **`session.begin()` context manager** for automatic commit/rollback on a scoped block.
+  - Keep transaction windows short: avoid network I/O, heavy computation, or unrelated work inside the transaction.
+- Example:
+  - Bad:
+    ```python
+    # Missing commit: write may never be persisted.
+    with Session(db.engine, expire_on_commit=False) as session:
+        run = session.get(WorkflowRun, run_id)
+        run.status = "cancelled"
+
+    # Long transaction: external I/O inside a DB transaction.
+    with Session(db.engine, expire_on_commit=False) as session, session.begin():
+        run = session.get(WorkflowRun, run_id)
+        run.status = "cancelled"
+        call_external_api()
+    ```
+  - Good:
+    ```python
+    # Option 1: explicit commit.
+    with Session(db.engine, expire_on_commit=False) as session:
+        run = session.get(WorkflowRun, run_id)
+        run.status = "cancelled"
+        session.commit()
+
+    # Option 2: scoped transaction with automatic commit/rollback.
+    with Session(db.engine, expire_on_commit=False) as session, session.begin():
+        run = session.get(WorkflowRun, run_id)
+        run.status = "cancelled"
+
+    # Keep non-DB work outside transaction scope.
+    call_external_api()
+    ```
+
+### Enforce tenant_id scoping on shared-resource queries
+- Category: security
+- Description: Reads and writes against shared tables must be scoped by `tenant_id` to prevent cross-tenant data leakage or corruption.
+- Suggested fix: Add `tenant_id` predicate to all tenant-owned entity queries and propagate tenant context through service/repository interfaces.
+- Example:
+  - Bad:
+    ```python
+    stmt = select(Workflow).where(Workflow.id == workflow_id)
+    workflow = session.execute(stmt).scalar_one_or_none()
+    ```
+  - Good:
+    ```python
+    stmt = select(Workflow).where(
+        Workflow.id == workflow_id,
+        Workflow.tenant_id == tenant_id,
+    )
+    workflow = session.execute(stmt).scalar_one_or_none()
+    ```
+
+### Prefer SQLAlchemy expressions over raw SQL by default
+- Category: maintainability
+- Description: Raw SQL should be exceptional. ORM/Core expressions are easier to evolve, safer to compose, and more consistent with the codebase.
+- Suggested fix: Rewrite straightforward raw SQL into SQLAlchemy `select/update/delete` expressions; keep raw SQL only when required by clear technical constraints.
+- Example:
+  - Bad:
+    ```python
+    row = session.execute(
+        text("SELECT * FROM workflows WHERE id = :id AND tenant_id = :tenant_id"),
+        {"id": workflow_id, "tenant_id": tenant_id},
+    ).first()
+    ```
+  - Good:
+    ```python
+    stmt = select(Workflow).where(
+        Workflow.id == workflow_id,
+        Workflow.tenant_id == tenant_id,
+    )
+    row = session.execute(stmt).scalar_one_or_none()
+    ```
+
+### Protect write paths with concurrency safeguards
+- Category: quality
+- Description: Multi-writer paths without explicit concurrency control can silently overwrite data. Choose the safeguard based on contention level, lock scope, and throughput cost instead of defaulting to one strategy.
+- Suggested fix:
+  - **Optimistic locking**: Use when contention is usually low and retries are acceptable. Add a version (or updated_at) guard in `WHERE` and treat `rowcount == 0` as a conflict.
+  - **Redis distributed lock**: Use when the critical section spans multiple steps/processes (or includes non-DB side effects) and you need cross-worker mutual exclusion.
+  - **SELECT ... FOR UPDATE**: Use when contention is high on the same rows and strict in-transaction serialization is required. Keep transactions short to reduce lock wait/deadlock risk.
+  - In all cases, scope by `tenant_id` and verify affected row counts for conditional writes.
+- Example:
+  - Bad:
+    ```python
+    # No tenant scope, no conflict detection, and no lock on a contested write path.
+    session.execute(update(WorkflowRun).where(WorkflowRun.id == run_id).values(status="cancelled"))
+    session.commit()  # silently overwrites concurrent updates
+    ```
+  - Good:
+    ```python
+    # 1) Optimistic lock (low contention, retry on conflict)
+    result = session.execute(
+        update(WorkflowRun)
+        .where(
+            WorkflowRun.id == run_id,
+            WorkflowRun.tenant_id == tenant_id,
+            WorkflowRun.version == expected_version,
+        )
+        .values(status="cancelled", version=WorkflowRun.version + 1)
+    )
+    if result.rowcount == 0:
+        raise WorkflowStateConflictError("stale version, retry")
+
+    # 2) Redis distributed lock (cross-worker critical section)
+    lock_name = f"workflow_run_lock:{tenant_id}:{run_id}"
+    with redis_client.lock(lock_name, timeout=20):
+        session.execute(
+            update(WorkflowRun)
+            .where(WorkflowRun.id == run_id, WorkflowRun.tenant_id == tenant_id)
+            .values(status="cancelled")
+        )
+        session.commit()
+
+    # 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()
+    ).scalar_one()
+    run.status = "cancelled"
+    session.commit()
+    ```

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

@@ -1,483 +0,0 @@
----
-name: component-refactoring
-description: Refactor high-complexity React components in Dify frontend. Use when `pnpm analyze-component --json` shows complexity > 50 or lineCount > 300, when the user asks for code splitting, hook extraction, or complexity reduction, or when `pnpm analyze-component` warns to refactor before testing; avoid for simple/well-structured components, third-party wrappers, or when the user explicitly wants testing without refactoring.
----
-
-# Dify Component Refactoring Skill
-
-Refactor high-complexity React components in the Dify frontend codebase with the patterns and workflow below.
-
-> **Complexity Threshold**: Components with complexity > 50 (measured by `pnpm analyze-component`) should be refactored before testing.
-
-## Quick Reference
-
-### Commands (run from `web/`)
-
-Use paths relative to `web/` (e.g., `app/components/...`).
-Use `refactor-component` for refactoring prompts and `analyze-component` for testing prompts and metrics.
-
-```bash
-cd web
-
-# Generate refactoring prompt
-pnpm refactor-component <path>
-
-# Output refactoring analysis as JSON
-pnpm refactor-component <path> --json
-
-# Generate testing prompt (after refactoring)
-pnpm analyze-component <path>
-
-# Output testing analysis as JSON
-pnpm analyze-component <path> --json
-```
-
-### Complexity Analysis
-
-```bash
-# Analyze component complexity
-pnpm analyze-component <path> --json
-
-# Key metrics to check:
-# - complexity: normalized score 0-100 (target < 50)
-# - maxComplexity: highest single function complexity
-# - lineCount: total lines (target < 300)
-```
-
-### Complexity Score Interpretation
-
-| Score | Level | Action |
-|-------|-------|--------|
-| 0-25 | 🟢 Simple | Ready for testing |
-| 26-50 | 🟡 Medium | Consider minor refactoring |
-| 51-75 | 🟠 Complex | **Refactor before testing** |
-| 76-100 | 🔴 Very Complex | **Must refactor** |
-
-## Core Refactoring Patterns
-
-### Pattern 1: Extract Custom Hooks
-
-**When**: Component has complex state management, multiple `useState`/`useEffect`, or business logic mixed with UI.
-
-**Dify Convention**: Place hooks in a `hooks/` subdirectory or alongside the component as `use-<feature>.ts`.
-
-```typescript
-// ❌ Before: Complex state logic in component
-const Configuration: FC = () => {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-  const [datasetConfigs, setDatasetConfigs] = useState<DatasetConfigs>(...)
-  const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
-  // 50+ lines of state management logic...
-  
-  return <div>...</div>
-}
-
-// ✅ After: Extract to custom hook
-// hooks/use-model-config.ts
-export const useModelConfig = (appId: string) => {
-  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
-  const [completionParams, setCompletionParams] = useState<FormValue>({})
-  
-  // Related state management logic here
-  
-  return { modelConfig, setModelConfig, completionParams, setCompletionParams }
-}
-
-// Component becomes cleaner
-const Configuration: FC = () => {
-  const { modelConfig, setModelConfig } = useModelConfig(appId)
-  return <div>...</div>
-}
-```
-
-**Dify Examples**:
-- `web/app/components/app/configuration/hooks/use-advanced-prompt-config.ts`
-- `web/app/components/app/configuration/debug/hooks.tsx`
-- `web/app/components/workflow/hooks/use-workflow.ts`
-
-### Pattern 2: Extract Sub-Components
-
-**When**: Single component has multiple UI sections, conditional rendering blocks, or repeated patterns.
-
-**Dify Convention**: Place sub-components in subdirectories or as separate files in the same directory.
-
-```typescript
-// ❌ Before: Monolithic JSX with multiple sections
-const AppInfo = () => {
-  return (
-    <div>
-      {/* 100 lines of header UI */}
-      {/* 100 lines of operations UI */}
-      {/* 100 lines of modals */}
-    </div>
-  )
-}
-
-// ✅ After: Split into focused components
-// app-info/
-//   ├── index.tsx           (orchestration only)
-//   ├── app-header.tsx      (header UI)
-//   ├── app-operations.tsx  (operations UI)
-//   └── app-modals.tsx      (modal management)
-
-const AppInfo = () => {
-  const { showModal, setShowModal } = useAppInfoModals()
-  
-  return (
-    <div>
-      <AppHeader appDetail={appDetail} />
-      <AppOperations onAction={handleAction} />
-      <AppModals show={showModal} onClose={() => setShowModal(null)} />
-    </div>
-  )
-}
-```
-
-**Dify Examples**:
-- `web/app/components/app/configuration/` directory structure
-- `web/app/components/workflow/nodes/` per-node organization
-
-### Pattern 3: Simplify Conditional Logic
-
-**When**: Deep nesting (> 3 levels), complex ternaries, or multiple `if/else` chains.
-
-```typescript
-// ❌ Before: Deeply nested conditionals
-const Template = useMemo(() => {
-  if (appDetail?.mode === AppModeEnum.CHAT) {
-    switch (locale) {
-      case LanguagesSupported[1]:
-        return <TemplateChatZh />
-      case LanguagesSupported[7]:
-        return <TemplateChatJa />
-      default:
-        return <TemplateChatEn />
-    }
-  }
-  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
-    // Another 15 lines...
-  }
-  // More conditions...
-}, [appDetail, locale])
-
-// ✅ After: Use lookup tables + early returns
-const TEMPLATE_MAP = {
-  [AppModeEnum.CHAT]: {
-    [LanguagesSupported[1]]: TemplateChatZh,
-    [LanguagesSupported[7]]: TemplateChatJa,
-    default: TemplateChatEn,
-  },
-  [AppModeEnum.ADVANCED_CHAT]: {
-    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
-    // ...
-  },
-}
-
-const Template = useMemo(() => {
-  const modeTemplates = TEMPLATE_MAP[appDetail?.mode]
-  if (!modeTemplates) return null
-  
-  const TemplateComponent = modeTemplates[locale] || modeTemplates.default
-  return <TemplateComponent appDetail={appDetail} />
-}, [appDetail, locale])
-```
-
-### Pattern 4: Extract API/Data Logic
-
-**When**: Component directly handles API calls, data transformation, or complex async operations.
-
-**Dify Convention**: Use `@tanstack/react-query` hooks from `web/service/use-*.ts` or create custom data hooks.
-
-```typescript
-// ❌ Before: API logic in component
-const MCPServiceCard = () => {
-  const [basicAppConfig, setBasicAppConfig] = useState({})
-  
-  useEffect(() => {
-    if (isBasicApp && appId) {
-      (async () => {
-        const res = await fetchAppDetail({ url: '/apps', id: appId })
-        setBasicAppConfig(res?.model_config || {})
-      })()
-    }
-  }, [appId, isBasicApp])
-  
-  // More API-related logic...
-}
-
-// ✅ After: Extract to data hook using React Query
-// use-app-config.ts
-import { useQuery } from '@tanstack/react-query'
-import { get } from '@/service/base'
-
-const NAME_SPACE = 'appConfig'
-
-export const useAppConfig = (appId: string, isBasicApp: boolean) => {
-  return useQuery({
-    enabled: isBasicApp && !!appId,
-    queryKey: [NAME_SPACE, 'detail', appId],
-    queryFn: () => get<AppDetailResponse>(`/apps/${appId}`),
-    select: data => data?.model_config || {},
-  })
-}
-
-// Component becomes cleaner
-const MCPServiceCard = () => {
-  const { data: config, isLoading } = useAppConfig(appId, isBasicApp)
-  // UI only
-}
-```
-
-**React Query Best Practices in Dify**:
-- Define `NAME_SPACE` for query key organization
-- Use `enabled` option for conditional fetching
-- Use `select` for data transformation
-- Export invalidation hooks: `useInvalidXxx`
-
-**Dify Examples**:
-- `web/service/use-workflow.ts`
-- `web/service/use-common.ts`
-- `web/service/knowledge/use-dataset.ts`
-- `web/service/knowledge/use-document.ts`
-
-### Pattern 5: Extract Modal/Dialog Management
-
-**When**: Component manages multiple modals with complex open/close states.
-
-**Dify Convention**: Modals should be extracted with their state management.
-
-```typescript
-// ❌ Before: Multiple modal states in component
-const AppInfo = () => {
-  const [showEditModal, setShowEditModal] = useState(false)
-  const [showDuplicateModal, setShowDuplicateModal] = useState(false)
-  const [showConfirmDelete, setShowConfirmDelete] = useState(false)
-  const [showSwitchModal, setShowSwitchModal] = useState(false)
-  const [showImportDSLModal, setShowImportDSLModal] = useState(false)
-  // 5+ more modal states...
-}
-
-// ✅ After: Extract to modal management hook
-type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | 'import' | null
-
-const useAppInfoModals = () => {
-  const [activeModal, setActiveModal] = useState<ModalType>(null)
-  
-  const openModal = useCallback((type: ModalType) => setActiveModal(type), [])
-  const closeModal = useCallback(() => setActiveModal(null), [])
-  
-  return {
-    activeModal,
-    openModal,
-    closeModal,
-    isOpen: (type: ModalType) => activeModal === type,
-  }
-}
-```
-
-### Pattern 6: Extract Form Logic
-
-**When**: Complex form validation, submission handling, or field transformation.
-
-**Dify Convention**: Use `@tanstack/react-form` patterns from `web/app/components/base/form/`.
-
-```typescript
-// ✅ Use existing form infrastructure
-import { useAppForm } from '@/app/components/base/form'
-
-const ConfigForm = () => {
-  const form = useAppForm({
-    defaultValues: { name: '', description: '' },
-    onSubmit: handleSubmit,
-  })
-  
-  return <form.Provider>...</form.Provider>
-}
-```
-
-## Dify-Specific Refactoring Guidelines
-
-### 1. Context Provider Extraction
-
-**When**: Component provides complex context values with multiple states.
-
-```typescript
-// ❌ Before: Large context value object
-const value = {
-  appId, isAPIKeySet, isTrailFinished, mode, modelModeType,
-  promptMode, isAdvancedMode, isAgent, isOpenAI, isFunctionCall,
-  // 50+ more properties...
-}
-return <ConfigContext.Provider value={value}>...</ConfigContext.Provider>
-
-// ✅ After: Split into domain-specific contexts
-<ModelConfigProvider value={modelConfigValue}>
-  <DatasetConfigProvider value={datasetConfigValue}>
-    <UIConfigProvider value={uiConfigValue}>
-      {children}
-    </UIConfigProvider>
-  </DatasetConfigProvider>
-</ModelConfigProvider>
-```
-
-**Dify Reference**: `web/context/` directory structure
-
-### 2. Workflow Node Components
-
-**When**: Refactoring workflow node components (`web/app/components/workflow/nodes/`).
-
-**Conventions**:
-- Keep node logic in `use-interactions.ts`
-- Extract panel UI to separate files
-- Use `_base` components for common patterns
-
-```
-nodes/<node-type>/
-  ├── index.tsx              # Node registration
-  ├── node.tsx               # Node visual component
-  ├── panel.tsx              # Configuration panel
-  ├── use-interactions.ts    # Node-specific hooks
-  └── types.ts               # Type definitions
-```
-
-### 3. Configuration Components
-
-**When**: Refactoring app configuration components.
-
-**Conventions**:
-- Separate config sections into subdirectories
-- Use existing patterns from `web/app/components/app/configuration/`
-- Keep feature toggles in dedicated components
-
-### 4. Tool/Plugin Components
-
-**When**: Refactoring tool-related components (`web/app/components/tools/`).
-
-**Conventions**:
-- Follow existing modal patterns
-- Use service hooks from `web/service/use-tools.ts`
-- Keep provider-specific logic isolated
-
-## Refactoring Workflow
-
-### Step 1: Generate Refactoring Prompt
-
-```bash
-pnpm refactor-component <path>
-```
-
-This command will:
-- Analyze component complexity and features
-- Identify specific refactoring actions needed
-- Generate a prompt for AI assistant (auto-copied to clipboard on macOS)
-- Provide detailed requirements based on detected patterns
-
-### Step 2: Analyze Details
-
-```bash
-pnpm analyze-component <path> --json
-```
-
-Identify:
-- Total complexity score
-- Max function complexity
-- Line count
-- Features detected (state, effects, API, etc.)
-
-### Step 3: Plan
-
-Create a refactoring plan based on detected features:
-
-| Detected Feature | Refactoring Action |
-|------------------|-------------------|
-| `hasState: true` + `hasEffects: true` | Extract custom hook |
-| `hasAPI: true` | Extract data/service hook |
-| `hasEvents: true` (many) | Extract event handlers |
-| `lineCount > 300` | Split into sub-components |
-| `maxComplexity > 50` | Simplify conditional logic |
-
-### Step 4: Execute Incrementally
-
-1. **Extract one piece at a time**
-2. **Run lint, type-check, and tests after each extraction**
-3. **Verify functionality before next step**
-
-```
-For each extraction:
-  ┌────────────────────────────────────────┐
-  │ 1. Extract code                        │
-  │ 2. Run: pnpm lint:fix                  │
-  │ 3. Run: pnpm type-check:tsgo           │
-  │ 4. Run: pnpm test                      │
-  │ 5. Test functionality manually         │
-  │ 6. PASS? → Next extraction             │
-  │    FAIL? → Fix before continuing       │
-  └────────────────────────────────────────┘
-```
-
-### Step 5: Verify
-
-After refactoring:
-
-```bash
-# Re-run refactor command to verify improvements
-pnpm refactor-component <path>
-
-# If complexity < 25 and lines < 200, you'll see:
-# ✅ COMPONENT IS WELL-STRUCTURED
-
-# For detailed metrics:
-pnpm analyze-component <path> --json
-
-# Target metrics:
-# - complexity < 50
-# - lineCount < 300
-# - maxComplexity < 30
-```
-
-## Common Mistakes to Avoid
-
-### ❌ Over-Engineering
-
-```typescript
-// ❌ Too many tiny hooks
-const useButtonText = () => useState('Click')
-const useButtonDisabled = () => useState(false)
-const useButtonLoading = () => useState(false)
-
-// ✅ Cohesive hook with related state
-const useButtonState = () => {
-  const [text, setText] = useState('Click')
-  const [disabled, setDisabled] = useState(false)
-  const [loading, setLoading] = useState(false)
-  return { text, setText, disabled, setDisabled, loading, setLoading }
-}
-```
-
-### ❌ Breaking Existing Patterns
-
-- Follow existing directory structures
-- Maintain naming conventions
-- Preserve export patterns for compatibility
-
-### ❌ Premature Abstraction
-
-- Only extract when there's clear complexity benefit
-- Don't create abstractions for single-use code
-- Keep refactored code in the same domain area
-
-## References
-
-### Dify Codebase Examples
-
-- **Hook extraction**: `web/app/components/app/configuration/hooks/`
-- **Component splitting**: `web/app/components/app/configuration/`
-- **Service hooks**: `web/service/use-*.ts`
-- **Workflow patterns**: `web/app/components/workflow/hooks/`
-- **Form patterns**: `web/app/components/base/form/`
-
-### Related Skills
-
-- `frontend-testing` - For testing refactored components
-- `web/docs/test.md` - Testing specification

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

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

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

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

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

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

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

@@ -0,0 +1,33 @@
+---
+name: e2e-cucumber-playwright
+description: Use when writing, changing, or reviewing Cucumber and Playwright tests under `e2e/`, including feature files, step definitions, support code, scenario tags, locators, and assertions. Do not use for Vitest, React Testing Library, backend tests, or generic browser automation outside the E2E suite.
+---
+
+# E2E Cucumber And Playwright
+
+`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, 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.
+
+## Workflow
+
+1. Add E2E coverage only for a critical user journey with a cross-boundary outcome that cheaper owner-level tests do not already prove.
+2. Identify the user-visible behavior and its feature owner. Start from real product defaults and actor roles; setup may establish preconditions but must not manufacture the opposite state to make the scenario meaningful.
+3. Read the target scenario, matching step definitions, and lifecycle files only when session or shared state matters.
+4. Reuse an existing step when wording and behavior match; add one coherent scenario or step when they do not.
+5. Keep browser actions and assertions at the public user boundary; keep setup, seed, polling, and cleanup at their package-defined owners.
+6. 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.
+
+[cucumber]: references/cucumber-best-practices.md
+[playwright]: references/playwright-best-practices.md

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

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

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

@@ -0,0 +1,94 @@
+# Cucumber Best Practices
+
+Use this reference when writing or reviewing Gherkin scenarios, step definitions, parameter expressions, and step reuse.
+
+Official sources:
+
+- 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 usually describe behavior declaratively, not reproduce an interaction script.
+
+Apply it like this:
+
+- write what the user does and what should happen
+- 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 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.
+
+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
+
+Good reuse reduces duplication. Bad reuse hides meaning.
+
+Prefer reuse when:
+
+- the user action is genuinely the same
+- the expected outcome is genuinely the same
+- the wording stays natural across features
+- the parameter is a real product domain value such as a named surface, mode, resource, or status
+
+Write a new step when:
+
+- the behavior is materially different
+- reusing the old wording would make the scenario misleading
+- a supposedly generic step would become an implementation-detail wrapper
+
+Do not optimize for a low step count by making vague steps. Optimize for a small set of truthful, domain-owned steps.
+
+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.
+
+Common examples:
+
+- `{string}` for labels, names, and visible text
+- `{int}` for counts
+- `{float}` for decimal values
+- `{word}` only when the value is truly a single token
+
+Keep expressions readable. If a step needs complicated parsing logic, first ask whether the scenario wording should be simpler.
+
+Use regex for a bounded natural-language alternative only when it keeps Gherkin readable, for example `/(Web app|Backend service API)/`. Avoid broad regexes that accept unowned language.
+
+### 5. Keep step definitions thin and meaningful
+
+Step definitions are glue between Gherkin and automation, not a second abstraction language. 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.
+
+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 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

@@ -0,0 +1,96 @@
+# Playwright Best Practices
+
+Use this reference when writing or reviewing locator, assertion, isolation, or synchronization logic.
+
+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
+
+### 1. Keep scenarios isolated
+
+Playwright's model is built around clean browser contexts so one test does not leak into another.
+
+Apply it like this:
+
+- do not depend on another scenario having run first
+- 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. Select locators by user contract
+
+Prefer built-in locators that match how the target is exposed to users:
+
+- 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
+
+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.
+
+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.
+
+### 3. Use web-first assertions with the right timeout owner
+
+Playwright assertions auto-wait and retry. Prefer them over manual state inspection.
+
+Prefer:
+
+- `await expect(page).toHaveURL(...)`
+- `await expect(locator).toBeVisible()`
+- `await expect(locator).toBeHidden()`
+- `await expect(locator).toBeEnabled()`
+- `await expect(locator).toHaveText(...)`
+
+Avoid:
+
+- `expect(await locator.isVisible()).toBe(true)`
+- custom polling loops for DOM state
+- `waitForTimeout` as synchronization
+
+If a condition genuinely needs custom retry logic, use Playwright's polling/assertion tools deliberately and keep that choice local and explicit.
+
+Use `expect.poll` for non-DOM truth such as API state, backend eventual consistency, generated resources, or captured browser events. For DOM state, use locator assertions so Playwright can apply actionability and web-first retry semantics.
+
+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.
+
+Good pattern:
+
+- assert a meaningful visible state when that is part of the behavior
+- then click/fill/select via locator APIs
+
+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 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?
+- 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,73 +1,49 @@
 ---
 name: frontend-code-review
-description: "Trigger when the user requests a review of frontend files (e.g., `.tsx`, `.ts`, `.js`). Support both pending-change reviews and focused file reviews while applying the checklist rules."
+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
 
-## Intent
-Use this skill whenever the user asks to review frontend code (especially `.tsx`, `.ts`, or `.js` files). Support two review modes:
+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.
 
-1. **Pending-change review** – inspect staged/working-tree files slated for commit and flag checklist violations before submission.
-2. **File-targeted review** – review the specific file(s) the user names and report the relevant checklist findings.
+## Evidence First
 
-Stick to the checklist below for every applicable file and mode.
+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. 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.
 
-## Checklist
-See [references/code-quality.md](references/code-quality.md), [references/performance.md](references/performance.md), [references/business-logic.md](references/business-logic.md) for the living checklist split by category—treat it as the canonical set of rules to follow.
+## Rule Routing
 
-Flag each rule violation with urgency metadata so future reviewers can prioritize fixes.
+Read only the packs matched by the diff:
 
-## Review Process
-1. Open the relevant component/module. Gather lines that relate to class names, React Flow hooks, prop memoization, and styling.
-2. For each rule in the review point, note where the code deviates and capture a representative snippet.
-3. Compose the review section per the template below. Group violations first by **Urgent** flag, then by category order (Code Quality, Performance, Business Logic).
+- DOM semantics, focus, keyboard, forms, disabled state, or visible interaction: [`references/accessibility-ui.md`][accessibility]
+- Dify UI imports, Base UI wrappers, overlays, tokens, or primitive contracts: [`references/dify-ui.md`][dify-ui]
+- Component ownership, props, state, Effects, navigation, or module boundaries: [`references/component-architecture.md`][component-architecture]
+- Generated clients, Query, mutations, auth, SSR, URL state, or persistence: [`references/data-query-contracts.md`][data-query]
+- Test files or a concrete missing-regression-test finding: [`references/testing.md`][testing]
+- Bundle, waterfall, rendering, or subscription cost supported by evidence: [`references/performance.md`][performance]
+- Stable Dify runtime invariants in the named paths: [`references/dify-invariants.md`][dify-invariants]
+- General TypeScript or styling quality not owned above: [`references/code-quality.md`][code-quality]
 
-## Required output
-When invoked, the response must exactly follow one of the two templates:
+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.
 
-### Template A (any findings)
-```
-# Code review
-Found <N> urgent issues need to be fixed:
+## Severity And Output
 
-## 1 <brief description of bug>
-FilePath: <path> line <line>
-<relevant code snippet or pointer>
+- **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.
+- **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.
 
-### Suggested fix
-<brief description of suggested fix>
-
----
-... (repeat for each urgent issue) ...
-
-Found <M> suggestions for improvement:
-
-## 1 <brief description of suggestion>
-FilePath: <path> line <line>
-<relevant code snippet or pointer>
-
-
-### Suggested fix
-<brief description of suggested fix>
-
----
-
-... (repeat for each suggestion) ...
-```
-
-If there are no urgent issues, omit that section. If there are no suggestions, omit that section.
-
-If the issue number is more than 10, summarize as "10+ urgent issues" or "10+ suggestions" and just output the first 10 issues.
-
-Don't compress the blank lines between sections; keep them as-is for readability.
-
-If you use Template A (i.e., there are issues to fix) and at least one issue requires code changes, append a brief follow-up question after the structured output asking whether the user wants you to apply the suggested fix(es). For example: "Would you like me to use the Suggested fix section to address these issues?"
-
-### Template B (no issues)
-```
-## Code review
-No issues found.
-```
-
+[accessibility]: references/accessibility-ui.md
+[code-quality]: references/code-quality.md
+[component-architecture]: references/component-architecture.md
+[data-query]: references/data-query-contracts.md
+[dify-invariants]: references/dify-invariants.md
+[dify-ui]: references/dify-ui.md
+[performance]: references/performance.md
+[testing]: references/testing.md

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

@@ -0,0 +1,135 @@
+# 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.
+
+## 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.
+
+## Long Content And Layout
+
+Flag:
+
+- 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.
+
+The usual Dify layout chain is: container has width constraints, text region uses `min-w-0 flex-1 truncate`, adornments use `shrink-0`.
+
+## Motion, Images, And Copy
+
+Flag:
+
+- `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.*`.
+
+[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/business-logic.md

@@ -1,15 +0,0 @@
-# Rule Catalog — Business Logic
-
-## Can't use workflowStore in Node components
-
-IsUrgent: True
-
-### Description
-
-File path pattern of node components: `web/app/components/workflow/nodes/[nodeName]/node.tsx`
-
-Node components are also used when creating a RAG Pipe from a template, but in that context there is no workflowStore Provider, which results in a blank screen. [This Issue](https://github.com/langgenius/dify/issues/29168) was caused by exactly this reason.
-
-### Suggested Fix
-
-Use `import { useNodes } from 'reactflow'` instead of `import useNodes from '@/app/components/workflow/store/workflow/use-nodes'`.

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

@@ -1,44 +1,71 @@
-# Rule Catalog — Code Quality
+# Code Quality Rules
 
-## Conditional class names use utility function
+## Scope Control
 
-IsUrgent: True
-Category: Code Quality
+Flag changes that expand beyond the requested feature or review scope:
 
-### Description
+- 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.
 
-Ensure conditional CSS is handled via the shared `classNames` instead of custom ternaries, string concatenation, or template strings. Centralizing class logic keeps components consistent and easier to maintain.
+## TypeScript
 
-### Suggested Fix
+Flag:
 
-```ts
-import { cn } from '@/utils/classnames'
-const classNames = cn(isActive ? 'text-primary-600' : 'text-gray-500')
-```
+- `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.
 
-## Tailwind-first styling
+Prefer:
 
-IsUrgent: True
-Category: Code Quality
+- Explicit domain names that match the API contract.
+- Type narrowing at route/API boundaries.
+- Small conversion helpers colocated with the component that needs them.
 
-### Description
+## Styling
 
-Favor Tailwind CSS utility classes instead of adding new `.module.css` files unless a Tailwind combination cannot achieve the required styling. Keeping styles in Tailwind improves consistency and reduces maintenance overhead.
+For Dify UI/Base UI state styling and callback composition, apply the package's [Styling] contract,
+including its documented reasons for direct state access.
 
-Update this file when adding, editing, or removing Code Quality rules so the catalog remains accurate.
+Flag:
 
-## Classname ordering for easy overrides
+- 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.
+- Arbitrary z-index or one-off layering fixes on overlays.
 
-### Description
+Use:
 
-When writing components, always place the incoming `className` prop after the component’s own class values so that downstream consumers can override or extend the styling. This keeps your component’s defaults but still lets external callers change or remove specific styles.
+- `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.
 
-Example:
+## Imports
 
-```tsx
-import { cn } from '@/utils/classnames'
+Flag:
 
-const Button = ({ className }) => {
-  return <div className={cn('bg-primary-600', className)}></div>
-}
-```
+- 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.
+
+[Styling]: ../../../../packages/dify-ui/docs/styling.md

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

@@ -0,0 +1,44 @@
+# Component Architecture Review
+
+Use the canonical reference for the changed concern. These links share rules; they do not activate the implementation skill or its workflow.
+
+| 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] |
+
+## Root-To-Leaf State And Props Audit
+
+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.
+
+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.
+
+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.
+
+## Apply Rules In Their Actual Scope
+
+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.
+
+- 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.
+
+## Preserve Existing Product Contracts
+
+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.
+
+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.
+
+[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

@@ -0,0 +1,28 @@
+# Data, Query, And Contract Review
+
+[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 And Query Conventions
+
+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.
+
+- 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.
+
+## 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.
+
+## Tenant, URL, And Persistence Boundaries
+
+- 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.
+
+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.
+
+[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-invariants.md

@@ -0,0 +1,22 @@
+# 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.

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

@@ -0,0 +1,29 @@
+# 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.
+
+Read `packages/dify-ui/AGENTS.md` and the primitive implementation first, then only the matching
+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`                                   |
+
+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.
+
+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

@@ -1,45 +1,76 @@
-# Rule Catalog — Performance
+# Performance Rules
 
-## React Flow data usage
+Review performance only where there is realistic impact. Do not request `memo`, `useMemo`, `useCallback`, virtualization, or caching as style preferences.
 
-IsUrgent: True
-Category: Performance
+## Async Waterfalls
 
-### Description
+Flag:
 
-When rendering React Flow, prefer `useNodes`/`useEdges` for UI consumption and rely on `useStoreApi` inside callbacks that mutate or read node/edge state. Avoid manually pulling Flow data outside of these hooks.
+- 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.
 
-## Complex prop memoization
+Prefer `Promise.all` for independent work and branch-local awaits for conditionally needed data.
 
-IsUrgent: True
-Category: Performance
+## Bundle Size
 
-### Description
+Flag:
 
-Wrap complex prop values (objects, arrays, maps) in `useMemo` prior to passing them into child components to guarantee stable references and prevent unnecessary renders.
+- 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.
 
-Update this file when adding, editing, or removing Performance rules so the catalog remains accurate.
+Use direct imports and `next/dynamic` where the user-visible path benefits.
 
-Wrong:
+## Server Rendering
 
-```tsx
-<HeavyComp
-    config={{
-        provider: ...,
-        detail: ...
-    }}
-/>
-```
+Flag:
 
-Right:
+- 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.
 
-```tsx
-const config = useMemo(() => ({
-    provider: ...,
-    detail: ...
-}), [provider, detail]);
+Use request-scoped deduplication such as `React.cache()` when repeated server reads in one request are the problem.
 
-<HeavyComp
-    config={config}
-/>
-```
+## 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

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

@@ -0,0 +1,37 @@
+# Testing Review Rules
+
+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
+
+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 incidental visual styling. Low coverage alone is not a finding.
+
+## Flag Low-Value or Fragile Tests
+
+Flag tests that:
+
+- Assert internal state, refs, hook usage, effect dependencies, private DOM structure, or cosmetic classes.
+- Exist only to render a component, exercise a prop, or cover generic invalid inputs without a product scenario.
+- Mock away the behavior under review or use mocks that do not match the public contract.
+- Add production `data-testid` attributes where semantic markup would work.
+- Use fake timers without timer behavior, leave async work unawaited, or leak shared state.
+- Duplicate a contract already protected at a more useful owner boundary.
+
+## Review the Test Boundary
+
+- Prefer semantic queries and accessible names.
+- Prefer real feature components when integration semantics matter.
+- 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

@@ -1,325 +1,13 @@
 ---
 name: frontend-testing
-description: Generate Vitest + React Testing Library tests for Dify frontend components, hooks, and utilities. Triggers on testing, spec files, coverage, Vitest, RTL, unit tests, integration tests, or write/review test requests.
+description: Use when writing or changing Vitest or React Testing Library tests under `web/` or `packages/dify-ui/`, or when the user explicitly requests frontend test strategy, including evaluation of an existing strategy. Do not use for frontend code-review-only requests, general testability discussion, Python tests, or Cucumber/Playwright E2E.
 ---
 
-# Dify Frontend Testing Skill
+# Frontend Testing
 
-This skill enables Claude to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.
+Read the testing policy for the package that owns the changed tests:
 
-> **⚠️ Authoritative Source**: This skill is derived from `web/docs/test.md`. Use Vitest mock/timer APIs (`vi.*`).
+- `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.
 
-## When to Apply This Skill
-
-Apply this skill when the user:
-
-- Asks to **write tests** for a component, hook, or utility
-- Asks to **review existing tests** for completeness
-- Mentions **Vitest**, **React Testing Library**, **RTL**, or **spec files**
-- Requests **test coverage** improvement
-- Uses `pnpm analyze-component` output as context
-- Mentions **testing**, **unit tests**, or **integration tests** for frontend code
-- Wants to understand **testing patterns** in the Dify codebase
-
-**Do NOT apply** when:
-
-- User is asking about backend/API tests (Python/pytest)
-- User is asking about E2E tests (Playwright/Cypress)
-- User is only asking conceptual questions without code context
-
-## Quick Reference
-
-### Tech Stack
-
-| Tool | Version | Purpose |
-|------|---------|---------|
-| Vitest | 4.0.16 | Test runner |
-| React Testing Library | 16.0 | Component testing |
-| jsdom | - | Test environment |
-| nock | 14.0 | HTTP mocking |
-| TypeScript | 5.x | Type safety |
-
-### Key Commands
-
-```bash
-# Run all tests
-pnpm test
-
-# Watch mode
-pnpm test:watch
-
-# Run specific file
-pnpm test path/to/file.spec.tsx
-
-# Generate coverage report
-pnpm test:coverage
-
-# Analyze component complexity
-pnpm analyze-component <path>
-
-# Review existing test
-pnpm analyze-component <path> --review
-```
-
-### File Naming
-
-- Test files: `ComponentName.spec.tsx` (same directory as component)
-- Integration tests: `web/__tests__/` directory
-
-## Test Structure Template
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import Component from './index'
-
-// ✅ Import real project components (DO NOT mock these)
-// import Loading from '@/app/components/base/loading'
-// import { ChildComponent } from './child-component'
-
-// ✅ Mock external dependencies only
-vi.mock('@/service/api')
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({ push: vi.fn() }),
-  usePathname: () => '/test',
-}))
-
-// ✅ Zustand stores: Use real stores (auto-mocked globally)
-// Set test state with: useAppStore.setState({ ... })
-
-// Shared state for mocks (if needed)
-let mockSharedState = false
-
-describe('ComponentName', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()  // ✅ Reset mocks BEFORE each test
-    mockSharedState = false  // ✅ Reset shared state
-  })
-
-  // Rendering tests (REQUIRED)
-  describe('Rendering', () => {
-    it('should render without crashing', () => {
-      // Arrange
-      const props = { title: 'Test' }
-      
-      // Act
-      render(<Component {...props} />)
-      
-      // Assert
-      expect(screen.getByText('Test')).toBeInTheDocument()
-    })
-  })
-
-  // Props tests (REQUIRED)
-  describe('Props', () => {
-    it('should apply custom className', () => {
-      render(<Component className="custom" />)
-      expect(screen.getByRole('button')).toHaveClass('custom')
-    })
-  })
-
-  // User Interactions
-  describe('User Interactions', () => {
-    it('should handle click events', () => {
-      const handleClick = vi.fn()
-      render(<Component onClick={handleClick} />)
-      
-      fireEvent.click(screen.getByRole('button'))
-      
-      expect(handleClick).toHaveBeenCalledTimes(1)
-    })
-  })
-
-  // Edge Cases (REQUIRED)
-  describe('Edge Cases', () => {
-    it('should handle null data', () => {
-      render(<Component data={null} />)
-      expect(screen.getByText(/no data/i)).toBeInTheDocument()
-    })
-
-    it('should handle empty array', () => {
-      render(<Component items={[]} />)
-      expect(screen.getByText(/empty/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-## Testing Workflow (CRITICAL)
-
-### ⚠️ Incremental Approach Required
-
-**NEVER generate all test files at once.** For complex components or multi-file directories:
-
-1. **Analyze & Plan**: List all files, order by complexity (simple → complex)
-1. **Process ONE at a time**: Write test → Run test → Fix if needed → Next
-1. **Verify before proceeding**: Do NOT continue to next file until current passes
-
-```
-For each file:
-  ┌────────────────────────────────────────┐
-  │ 1. Write test                          │
-  │ 2. Run: pnpm test <file>.spec.tsx      │
-  │ 3. PASS? → Mark complete, next file    │
-  │    FAIL? → Fix first, then continue    │
-  └────────────────────────────────────────┘
-```
-
-### Complexity-Based Order
-
-Process in this order for multi-file testing:
-
-1. 🟢 Utility functions (simplest)
-1. 🟢 Custom hooks
-1. 🟡 Simple components (presentational)
-1. 🟡 Medium components (state, effects)
-1. 🔴 Complex components (API, routing)
-1. 🔴 Integration tests (index files - last)
-
-### When to Refactor First
-
-- **Complexity > 50**: Break into smaller pieces before testing
-- **500+ lines**: Consider splitting before testing
-- **Many dependencies**: Extract logic into hooks first
-
-> 📖 See `references/workflow.md` for complete workflow details and todo list format.
-
-## Testing Strategy
-
-### Path-Level Testing (Directory Testing)
-
-When assigned to test a directory/path, test **ALL content** within that path:
-
-- Test all components, hooks, utilities in the directory (not just `index` file)
-- Use incremental approach: one file at a time, verify each before proceeding
-- Goal: 100% coverage of ALL files in the directory
-
-### Integration Testing First
-
-**Prefer integration testing** when writing tests for a directory:
-
-- ✅ **Import real project components** directly (including base components and siblings)
-- ✅ **Only mock**: API services (`@/service/*`), `next/navigation`, complex context providers
-- ❌ **DO NOT mock** base components (`@/app/components/base/*`)
-- ❌ **DO NOT mock** sibling/child components in the same directory
-
-> See [Test Structure Template](#test-structure-template) for correct import/mock patterns.
-
-## Core Principles
-
-### 1. AAA Pattern (Arrange-Act-Assert)
-
-Every test should clearly separate:
-
-- **Arrange**: Setup test data and render component
-- **Act**: Perform user actions
-- **Assert**: Verify expected outcomes
-
-### 2. Black-Box Testing
-
-- Test observable behavior, not implementation details
-- Use semantic queries (getByRole, getByLabelText)
-- Avoid testing internal state directly
-- **Prefer pattern matching over hardcoded strings** in assertions:
-
-```typescript
-// ❌ Avoid: hardcoded text assertions
-expect(screen.getByText('Loading...')).toBeInTheDocument()
-
-// ✅ Better: role-based queries
-expect(screen.getByRole('status')).toBeInTheDocument()
-
-// ✅ Better: pattern matching
-expect(screen.getByText(/loading/i)).toBeInTheDocument()
-```
-
-### 3. Single Behavior Per Test
-
-Each test verifies ONE user-observable behavior:
-
-```typescript
-// ✅ Good: One behavior
-it('should disable button when loading', () => {
-  render(<Button loading />)
-  expect(screen.getByRole('button')).toBeDisabled()
-})
-
-// ❌ Bad: Multiple behaviors
-it('should handle loading state', () => {
-  render(<Button loading />)
-  expect(screen.getByRole('button')).toBeDisabled()
-  expect(screen.getByText('Loading...')).toBeInTheDocument()
-  expect(screen.getByRole('button')).toHaveClass('loading')
-})
-```
-
-### 4. Semantic Naming
-
-Use `should <behavior> when <condition>`:
-
-```typescript
-it('should show error message when validation fails')
-it('should call onSubmit when form is valid')
-it('should disable input when isReadOnly is true')
-```
-
-## Required Test Scenarios
-
-### Always Required (All Components)
-
-1. **Rendering**: Component renders without crashing
-1. **Props**: Required props, optional props, default values
-1. **Edge Cases**: null, undefined, empty values, boundary conditions
-
-### Conditional (When Present)
-
-| Feature | Test Focus |
-|---------|-----------|
-| `useState` | Initial state, transitions, cleanup |
-| `useEffect` | Execution, dependencies, cleanup |
-| Event handlers | All onClick, onChange, onSubmit, keyboard |
-| API calls | Loading, success, error states |
-| Routing | Navigation, params, query strings |
-| `useCallback`/`useMemo` | Referential equality |
-| Context | Provider values, consumer behavior |
-| Forms | Validation, submission, error display |
-
-## Coverage Goals (Per File)
-
-For each test file generated, aim for:
-
-- ✅ **100%** function coverage
-- ✅ **100%** statement coverage
-- ✅ **>95%** branch coverage
-- ✅ **>95%** line coverage
-
-> **Note**: For multi-file directories, process one file at a time with full coverage each. See `references/workflow.md`.
-
-## Detailed Guides
-
-For more detailed information, refer to:
-
-- `references/workflow.md` - **Incremental testing workflow** (MUST READ for multi-file testing)
-- `references/mocking.md` - Mock patterns, Zustand store testing, and best practices
-- `references/async-testing.md` - Async operations and API calls
-- `references/domain-components.md` - Workflow, Dataset, Configuration testing
-- `references/common-patterns.md` - Frequently used testing patterns
-- `references/checklist.md` - Test generation checklist and validation steps
-
-## Authoritative References
-
-### Primary Specification (MUST follow)
-
-- **`web/docs/test.md`** - The canonical testing specification. This skill is derived from this document.
-
-### Reference Examples in Codebase
-
-- `web/utils/classnames.spec.ts` - Utility function tests
-- `web/app/components/base/button/index.spec.tsx` - Component tests
-- `web/__mocks__/provider-context.ts` - Mock factory example
-
-### Project Configuration
-
-- `web/vitest.config.ts` - Vitest configuration
-- `web/vitest.setup.ts` - Test environment setup
-- `web/scripts/analyze-component.js` - Component analysis tool
-- Modules are not mocked automatically. Global mocks live in `web/vitest.setup.ts` (for example `react-i18next`, `next/image`); mock other modules like `ky` or `mime` locally in test files.
+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/frontend-testing/assets/component-test.template.tsx

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

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

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

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

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

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

@@ -1,345 +0,0 @@
-# Async Testing Guide
-
-## Core Async Patterns
-
-### 1. waitFor - Wait for Condition
-
-```typescript
-import { render, screen, waitFor } from '@testing-library/react'
-
-it('should load and display data', async () => {
-  render(<DataComponent />)
-  
-  // Wait for element to appear
-  await waitFor(() => {
-    expect(screen.getByText('Loaded Data')).toBeInTheDocument()
-  })
-})
-
-it('should hide loading spinner after load', async () => {
-  render(<DataComponent />)
-  
-  // Wait for element to disappear
-  await waitFor(() => {
-    expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
-  })
-})
-```
-
-### 2. findBy\* - Async Queries
-
-```typescript
-it('should show user name after fetch', async () => {
-  render(<UserProfile />)
-  
-  // findBy returns a promise, auto-waits up to 1000ms
-  const userName = await screen.findByText('John Doe')
-  expect(userName).toBeInTheDocument()
-  
-  // findByRole with options
-  const button = await screen.findByRole('button', { name: /submit/i })
-  expect(button).toBeEnabled()
-})
-```
-
-### 3. userEvent for Async Interactions
-
-```typescript
-import userEvent from '@testing-library/user-event'
-
-it('should submit form', async () => {
-  const user = userEvent.setup()
-  const onSubmit = vi.fn()
-  
-  render(<Form onSubmit={onSubmit} />)
-  
-  // userEvent methods are async
-  await user.type(screen.getByLabelText('Email'), 'test@example.com')
-  await user.click(screen.getByRole('button', { name: /submit/i }))
-  
-  await waitFor(() => {
-    expect(onSubmit).toHaveBeenCalledWith({ email: 'test@example.com' })
-  })
-})
-```
-
-## Fake Timers
-
-### When to Use Fake Timers
-
-- Testing components with `setTimeout`/`setInterval`
-- Testing debounce/throttle behavior
-- Testing animations or delayed transitions
-- Testing polling or retry logic
-
-### Basic Fake Timer Setup
-
-```typescript
-describe('Debounced Search', () => {
-  beforeEach(() => {
-    vi.useFakeTimers()
-  })
-
-  afterEach(() => {
-    vi.useRealTimers()
-  })
-
-  it('should debounce search input', async () => {
-    const onSearch = vi.fn()
-    render(<SearchInput onSearch={onSearch} debounceMs={300} />)
-    
-    // Type in the input
-    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'query' } })
-    
-    // Search not called immediately
-    expect(onSearch).not.toHaveBeenCalled()
-    
-    // Advance timers
-    vi.advanceTimersByTime(300)
-    
-    // Now search is called
-    expect(onSearch).toHaveBeenCalledWith('query')
-  })
-})
-```
-
-### Fake Timers with Async Code
-
-```typescript
-it('should retry on failure', async () => {
-  vi.useFakeTimers()
-  const fetchData = vi.fn()
-    .mockRejectedValueOnce(new Error('Network error'))
-    .mockResolvedValueOnce({ data: 'success' })
-  
-  render(<RetryComponent fetchData={fetchData} retryDelayMs={1000} />)
-  
-  // First call fails
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledTimes(1)
-  })
-  
-  // Advance timer for retry
-  vi.advanceTimersByTime(1000)
-  
-  // Second call succeeds
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledTimes(2)
-    expect(screen.getByText('success')).toBeInTheDocument()
-  })
-  
-  vi.useRealTimers()
-})
-```
-
-### Common Fake Timer Utilities
-
-```typescript
-// Run all pending timers
-vi.runAllTimers()
-
-// Run only pending timers (not new ones created during execution)
-vi.runOnlyPendingTimers()
-
-// Advance by specific time
-vi.advanceTimersByTime(1000)
-
-// Get current fake time
-Date.now()
-
-// Clear all timers
-vi.clearAllTimers()
-```
-
-## API Testing Patterns
-
-### Loading → Success → Error States
-
-```typescript
-describe('DataFetcher', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should show loading state', () => {
-    mockedApi.fetchData.mockImplementation(() => new Promise(() => {})) // Never resolves
-    
-    render(<DataFetcher />)
-    
-    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument()
-  })
-
-  it('should show data on success', async () => {
-    mockedApi.fetchData.mockResolvedValue({ items: ['Item 1', 'Item 2'] })
-    
-    render(<DataFetcher />)
-    
-    // Use findBy* for multiple async elements (better error messages than waitFor with multiple assertions)
-    const item1 = await screen.findByText('Item 1')
-    const item2 = await screen.findByText('Item 2')
-    expect(item1).toBeInTheDocument()
-    expect(item2).toBeInTheDocument()
-    
-    expect(screen.queryByTestId('loading-spinner')).not.toBeInTheDocument()
-  })
-
-  it('should show error on failure', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Failed to fetch'))
-    
-    render(<DataFetcher />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/failed to fetch/i)).toBeInTheDocument()
-    })
-  })
-
-  it('should retry on error', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
-    render(<DataFetcher />)
-    
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
-    })
-    
-    mockedApi.fetchData.mockResolvedValue({ items: ['Item 1'] })
-    fireEvent.click(screen.getByRole('button', { name: /retry/i }))
-    
-    await waitFor(() => {
-      expect(screen.getByText('Item 1')).toBeInTheDocument()
-    })
-  })
-})
-```
-
-### Testing Mutations
-
-```typescript
-it('should submit form and show success', async () => {
-  const user = userEvent.setup()
-  mockedApi.createItem.mockResolvedValue({ id: '1', name: 'New Item' })
-  
-  render(<CreateItemForm />)
-  
-  await user.type(screen.getByLabelText('Name'), 'New Item')
-  await user.click(screen.getByRole('button', { name: /create/i }))
-  
-  // Button should be disabled during submission
-  expect(screen.getByRole('button', { name: /creating/i })).toBeDisabled()
-  
-  await waitFor(() => {
-    expect(screen.getByText(/created successfully/i)).toBeInTheDocument()
-  })
-  
-  expect(mockedApi.createItem).toHaveBeenCalledWith({ name: 'New Item' })
-})
-```
-
-## useEffect Testing
-
-### Testing Effect Execution
-
-```typescript
-it('should fetch data on mount', async () => {
-  const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
-  
-  render(<ComponentWithEffect fetchData={fetchData} />)
-  
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledTimes(1)
-  })
-})
-```
-
-### Testing Effect Dependencies
-
-```typescript
-it('should refetch when id changes', async () => {
-  const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
-  
-  const { rerender } = render(<ComponentWithEffect id="1" fetchData={fetchData} />)
-  
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledWith('1')
-  })
-  
-  rerender(<ComponentWithEffect id="2" fetchData={fetchData} />)
-  
-  await waitFor(() => {
-    expect(fetchData).toHaveBeenCalledWith('2')
-    expect(fetchData).toHaveBeenCalledTimes(2)
-  })
-})
-```
-
-### Testing Effect Cleanup
-
-```typescript
-it('should cleanup subscription on unmount', () => {
-  const subscribe = vi.fn()
-  const unsubscribe = vi.fn()
-  subscribe.mockReturnValue(unsubscribe)
-  
-  const { unmount } = render(<SubscriptionComponent subscribe={subscribe} />)
-  
-  expect(subscribe).toHaveBeenCalledTimes(1)
-  
-  unmount()
-  
-  expect(unsubscribe).toHaveBeenCalledTimes(1)
-})
-```
-
-## Common Async Pitfalls
-
-### ❌ Don't: Forget to await
-
-```typescript
-// Bad - test may pass even if assertion fails
-it('should load data', () => {
-  render(<Component />)
-  waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-
-// Good - properly awaited
-it('should load data', async () => {
-  render(<Component />)
-  await waitFor(() => {
-    expect(screen.getByText('Data')).toBeInTheDocument()
-  })
-})
-```
-
-### ❌ Don't: Use multiple assertions in single waitFor
-
-```typescript
-// Bad - if first assertion fails, won't know about second
-await waitFor(() => {
-  expect(screen.getByText('Title')).toBeInTheDocument()
-  expect(screen.getByText('Description')).toBeInTheDocument()
-})
-
-// Good - separate waitFor or use findBy
-const title = await screen.findByText('Title')
-const description = await screen.findByText('Description')
-expect(title).toBeInTheDocument()
-expect(description).toBeInTheDocument()
-```
-
-### ❌ Don't: Mix fake timers with real async
-
-```typescript
-// Bad - fake timers don't work well with real Promises
-vi.useFakeTimers()
-await waitFor(() => {
-  expect(screen.getByText('Data')).toBeInTheDocument()
-}) // May timeout!
-
-// Good - use runAllTimers or advanceTimersByTime
-vi.useFakeTimers()
-render(<Component />)
-vi.runAllTimers()
-expect(screen.getByText('Data')).toBeInTheDocument()
-```

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

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

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

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

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

@@ -1,523 +0,0 @@
-# Domain-Specific Component Testing
-
-This guide covers testing patterns for Dify's domain-specific components.
-
-## Workflow Components (`workflow/`)
-
-Workflow components handle node configuration, data flow, and graph operations.
-
-### Key Test Areas
-
-1. **Node Configuration**
-1. **Data Validation**
-1. **Variable Passing**
-1. **Edge Connections**
-1. **Error Handling**
-
-### Example: Node Configuration Panel
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import NodeConfigPanel from './node-config-panel'
-import { createMockNode, createMockWorkflowContext } from '@/__mocks__/workflow'
-
-// Mock workflow context
-vi.mock('@/app/components/workflow/hooks', () => ({
-  useWorkflowStore: () => mockWorkflowStore,
-  useNodesInteractions: () => mockNodesInteractions,
-}))
-
-let mockWorkflowStore = {
-  nodes: [],
-  edges: [],
-  updateNode: vi.fn(),
-}
-
-let mockNodesInteractions = {
-  handleNodeSelect: vi.fn(),
-  handleNodeDelete: vi.fn(),
-}
-
-describe('NodeConfigPanel', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockWorkflowStore = {
-      nodes: [],
-      edges: [],
-      updateNode: vi.fn(),
-    }
-  })
-
-  describe('Node Configuration', () => {
-    it('should render node type selector', () => {
-      const node = createMockNode({ type: 'llm' })
-      render(<NodeConfigPanel node={node} />)
-      
-      expect(screen.getByLabelText(/model/i)).toBeInTheDocument()
-    })
-
-    it('should update node config on change', async () => {
-      const user = userEvent.setup()
-      const node = createMockNode({ type: 'llm' })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      await user.selectOptions(screen.getByLabelText(/model/i), 'gpt-4')
-      
-      expect(mockWorkflowStore.updateNode).toHaveBeenCalledWith(
-        node.id,
-        expect.objectContaining({ model: 'gpt-4' })
-      )
-    })
-  })
-
-  describe('Data Validation', () => {
-    it('should show error for invalid input', async () => {
-      const user = userEvent.setup()
-      const node = createMockNode({ type: 'code' })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      // Enter invalid code
-      const codeInput = screen.getByLabelText(/code/i)
-      await user.clear(codeInput)
-      await user.type(codeInput, 'invalid syntax {{{')
-      
-      await waitFor(() => {
-        expect(screen.getByText(/syntax error/i)).toBeInTheDocument()
-      })
-    })
-
-    it('should validate required fields', async () => {
-      const node = createMockNode({ type: 'http', data: { url: '' } })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      fireEvent.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText(/url is required/i)).toBeInTheDocument()
-      })
-    })
-  })
-
-  describe('Variable Passing', () => {
-    it('should display available variables from upstream nodes', () => {
-      const upstreamNode = createMockNode({
-        id: 'node-1',
-        type: 'start',
-        data: { outputs: [{ name: 'user_input', type: 'string' }] },
-      })
-      const currentNode = createMockNode({
-        id: 'node-2',
-        type: 'llm',
-      })
-      
-      mockWorkflowStore.nodes = [upstreamNode, currentNode]
-      mockWorkflowStore.edges = [{ source: 'node-1', target: 'node-2' }]
-      
-      render(<NodeConfigPanel node={currentNode} />)
-      
-      // Variable selector should show upstream variables
-      fireEvent.click(screen.getByRole('button', { name: /add variable/i }))
-      
-      expect(screen.getByText('user_input')).toBeInTheDocument()
-    })
-
-    it('should insert variable into prompt template', async () => {
-      const user = userEvent.setup()
-      const node = createMockNode({ type: 'llm' })
-      
-      render(<NodeConfigPanel node={node} />)
-      
-      // Click variable button
-      await user.click(screen.getByRole('button', { name: /insert variable/i }))
-      await user.click(screen.getByText('user_input'))
-      
-      const promptInput = screen.getByLabelText(/prompt/i)
-      expect(promptInput).toHaveValue(expect.stringContaining('{{user_input}}'))
-    })
-  })
-})
-```
-
-## Dataset Components (`dataset/`)
-
-Dataset components handle file uploads, data display, and search/filter operations.
-
-### Key Test Areas
-
-1. **File Upload**
-1. **File Type Validation**
-1. **Pagination**
-1. **Search & Filtering**
-1. **Data Format Handling**
-
-### Example: Document Uploader
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import DocumentUploader from './document-uploader'
-
-vi.mock('@/service/datasets', () => ({
-  uploadDocument: vi.fn(),
-  parseDocument: vi.fn(),
-}))
-
-import * as datasetService from '@/service/datasets'
-const mockedService = vi.mocked(datasetService)
-
-describe('DocumentUploader', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  describe('File Upload', () => {
-    it('should accept valid file types', async () => {
-      const user = userEvent.setup()
-      const onUpload = vi.fn()
-      mockedService.uploadDocument.mockResolvedValue({ id: 'doc-1' })
-      
-      render(<DocumentUploader onUpload={onUpload} />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      const input = screen.getByLabelText(/upload/i)
-      
-      await user.upload(input, file)
-      
-      await waitFor(() => {
-        expect(mockedService.uploadDocument).toHaveBeenCalledWith(
-          expect.any(FormData)
-        )
-      })
-    })
-
-    it('should reject invalid file types', async () => {
-      const user = userEvent.setup()
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.exe', { type: 'application/x-msdownload' })
-      const input = screen.getByLabelText(/upload/i)
-      
-      await user.upload(input, file)
-      
-      expect(screen.getByText(/unsupported file type/i)).toBeInTheDocument()
-      expect(mockedService.uploadDocument).not.toHaveBeenCalled()
-    })
-
-    it('should show upload progress', async () => {
-      const user = userEvent.setup()
-      
-      // Mock upload with progress
-      mockedService.uploadDocument.mockImplementation(() => {
-        return new Promise((resolve) => {
-          setTimeout(() => resolve({ id: 'doc-1' }), 100)
-        })
-      })
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      await user.upload(screen.getByLabelText(/upload/i), file)
-      
-      expect(screen.getByRole('progressbar')).toBeInTheDocument()
-      
-      await waitFor(() => {
-        expect(screen.queryByRole('progressbar')).not.toBeInTheDocument()
-      })
-    })
-  })
-
-  describe('Error Handling', () => {
-    it('should handle upload failure', async () => {
-      const user = userEvent.setup()
-      mockedService.uploadDocument.mockRejectedValue(new Error('Upload failed'))
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      await user.upload(screen.getByLabelText(/upload/i), file)
-      
-      await waitFor(() => {
-        expect(screen.getByText(/upload failed/i)).toBeInTheDocument()
-      })
-    })
-
-    it('should allow retry after failure', async () => {
-      const user = userEvent.setup()
-      mockedService.uploadDocument
-        .mockRejectedValueOnce(new Error('Network error'))
-        .mockResolvedValueOnce({ id: 'doc-1' })
-      
-      render(<DocumentUploader />)
-      
-      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
-      await user.upload(screen.getByLabelText(/upload/i), file)
-      
-      await waitFor(() => {
-        expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
-      })
-      
-      await user.click(screen.getByRole('button', { name: /retry/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText(/uploaded successfully/i)).toBeInTheDocument()
-      })
-    })
-  })
-})
-```
-
-### Example: Document List with Pagination
-
-```typescript
-describe('DocumentList', () => {
-  describe('Pagination', () => {
-    it('should load first page on mount', async () => {
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '1', name: 'Doc 1' }],
-        total: 50,
-        page: 1,
-        pageSize: 10,
-      })
-      
-      render(<DocumentList datasetId="ds-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByText('Doc 1')).toBeInTheDocument()
-      })
-      
-      expect(mockedService.getDocuments).toHaveBeenCalledWith('ds-1', { page: 1 })
-    })
-
-    it('should navigate to next page', async () => {
-      const user = userEvent.setup()
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '1', name: 'Doc 1' }],
-        total: 50,
-        page: 1,
-        pageSize: 10,
-      })
-      
-      render(<DocumentList datasetId="ds-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByText('Doc 1')).toBeInTheDocument()
-      })
-      
-      mockedService.getDocuments.mockResolvedValue({
-        data: [{ id: '11', name: 'Doc 11' }],
-        total: 50,
-        page: 2,
-        pageSize: 10,
-      })
-      
-      await user.click(screen.getByRole('button', { name: /next/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText('Doc 11')).toBeInTheDocument()
-      })
-    })
-  })
-
-  describe('Search & Filtering', () => {
-    it('should filter by search query', async () => {
-      const user = userEvent.setup()
-      vi.useFakeTimers()
-      
-      render(<DocumentList datasetId="ds-1" />)
-      
-      await user.type(screen.getByPlaceholderText(/search/i), 'test query')
-      
-      // Debounce
-      vi.advanceTimersByTime(300)
-      
-      await waitFor(() => {
-        expect(mockedService.getDocuments).toHaveBeenCalledWith(
-          'ds-1',
-          expect.objectContaining({ search: 'test query' })
-        )
-      })
-      
-      vi.useRealTimers()
-    })
-  })
-})
-```
-
-## Configuration Components (`app/configuration/`, `config/`)
-
-Configuration components handle forms, validation, and data persistence.
-
-### Key Test Areas
-
-1. **Form Validation**
-1. **Save/Reset**
-1. **Required vs Optional Fields**
-1. **Configuration Persistence**
-1. **Error Feedback**
-
-### Example: App Configuration Form
-
-```typescript
-import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import AppConfigForm from './app-config-form'
-
-vi.mock('@/service/apps', () => ({
-  updateAppConfig: vi.fn(),
-  getAppConfig: vi.fn(),
-}))
-
-import * as appService from '@/service/apps'
-const mockedService = vi.mocked(appService)
-
-describe('AppConfigForm', () => {
-  const defaultConfig = {
-    name: 'My App',
-    description: '',
-    icon: 'default',
-    openingStatement: '',
-  }
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockedService.getAppConfig.mockResolvedValue(defaultConfig)
-  })
-
-  describe('Form Validation', () => {
-    it('should require app name', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Clear name field
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      expect(screen.getByText(/name is required/i)).toBeInTheDocument()
-      expect(mockedService.updateAppConfig).not.toHaveBeenCalled()
-    })
-
-    it('should validate name length', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toBeInTheDocument()
-      })
-      
-      // Enter very long name
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.type(screen.getByLabelText(/name/i), 'a'.repeat(101))
-      
-      expect(screen.getByText(/name must be less than 100 characters/i)).toBeInTheDocument()
-    })
-
-    it('should allow empty optional fields', async () => {
-      const user = userEvent.setup()
-      mockedService.updateAppConfig.mockResolvedValue({ success: true })
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Leave description empty (optional)
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(mockedService.updateAppConfig).toHaveBeenCalled()
-      })
-    })
-  })
-
-  describe('Save/Reset Functionality', () => {
-    it('should save configuration', async () => {
-      const user = userEvent.setup()
-      mockedService.updateAppConfig.mockResolvedValue({ success: true })
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.type(screen.getByLabelText(/name/i), 'Updated App')
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(mockedService.updateAppConfig).toHaveBeenCalledWith(
-          'app-1',
-          expect.objectContaining({ name: 'Updated App' })
-        )
-      })
-      
-      expect(screen.getByText(/saved successfully/i)).toBeInTheDocument()
-    })
-
-    it('should reset to default values', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Make changes
-      await user.clear(screen.getByLabelText(/name/i))
-      await user.type(screen.getByLabelText(/name/i), 'Changed Name')
-      
-      // Reset
-      await user.click(screen.getByRole('button', { name: /reset/i }))
-      
-      expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-    })
-
-    it('should show unsaved changes warning', async () => {
-      const user = userEvent.setup()
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      // Make changes
-      await user.type(screen.getByLabelText(/name/i), ' Updated')
-      
-      expect(screen.getByText(/unsaved changes/i)).toBeInTheDocument()
-    })
-  })
-
-  describe('Error Handling', () => {
-    it('should show error on save failure', async () => {
-      const user = userEvent.setup()
-      mockedService.updateAppConfig.mockRejectedValue(new Error('Server error'))
-      
-      render(<AppConfigForm appId="app-1" />)
-      
-      await waitFor(() => {
-        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
-      })
-      
-      await user.click(screen.getByRole('button', { name: /save/i }))
-      
-      await waitFor(() => {
-        expect(screen.getByText(/failed to save/i)).toBeInTheDocument()
-      })
-    })
-  })
-})
-```

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

@@ -1,512 +0,0 @@
-# Mocking Guide for Dify Frontend Tests
-
-## ⚠️ Important: What NOT to Mock
-
-### DO NOT Mock Base Components
-
-**Never mock components from `@/app/components/base/`** such as:
-
-- `Loading`, `Spinner`
-- `Button`, `Input`, `Select`
-- `Tooltip`, `Modal`, `Dropdown`
-- `Icon`, `Badge`, `Tag`
-
-**Why?**
-
-- Base components will have their own dedicated tests
-- Mocking them creates false positives (tests pass but real integration fails)
-- Using real components tests actual integration behavior
-
-```typescript
-// ❌ WRONG: Don't mock base components
-vi.mock('@/app/components/base/loading', () => () => <div>Loading</div>)
-vi.mock('@/app/components/base/button', () => ({ children }: any) => <button>{children}</button>)
-
-// ✅ CORRECT: Import and use real base components
-import Loading from '@/app/components/base/loading'
-import Button from '@/app/components/base/button'
-// They will render normally in tests
-```
-
-### What TO Mock
-
-Only mock these categories:
-
-1. **API services** (`@/service/*`) - Network calls
-1. **Complex context providers** - When setup is too difficult
-1. **Third-party libraries with side effects** - `next/navigation`, external SDKs
-1. **i18n** - Always mock to return keys
-
-### Zustand Stores - DO NOT Mock Manually
-
-**Zustand is globally mocked** in `web/vitest.setup.ts`. Use real stores with `setState()`:
-
-```typescript
-// ✅ CORRECT: Use real store, set test state
-import { useAppStore } from '@/app/components/app/store'
-
-useAppStore.setState({ appDetail: { id: 'test', name: 'Test' } })
-render(<MyComponent />)
-
-// ❌ WRONG: Don't mock the store module
-vi.mock('@/app/components/app/store', () => ({ ... }))
-```
-
-See [Zustand Store Testing](#zustand-store-testing) section for full details.
-
-## Mock Placement
-
-| Location | Purpose |
-|----------|---------|
-| `web/vitest.setup.ts` | Global mocks shared by all tests (`react-i18next`, `next/image`, `zustand`) |
-| `web/__mocks__/zustand.ts` | Zustand mock implementation (auto-resets stores after each test) |
-| `web/__mocks__/` | Reusable mock factories shared across multiple test files |
-| Test file | Test-specific mocks, inline with `vi.mock()` |
-
-Modules are not mocked automatically. Use `vi.mock` in test files, or add global mocks in `web/vitest.setup.ts`.
-
-**Note**: Zustand is special - it's globally mocked but you should NOT mock store modules manually. See [Zustand Store Testing](#zustand-store-testing).
-
-## Essential Mocks
-
-### 1. i18n (Auto-loaded via Global Mock)
-
-A global mock is defined in `web/vitest.setup.ts` and is auto-loaded by Vitest setup.
-
-The global mock provides:
-
-- `useTranslation` - returns translation keys with namespace prefix
-- `Trans` component - renders i18nKey and components
-- `useMixedTranslation` (from `@/app/components/plugins/marketplace/hooks`)
-- `useGetLanguage` (from `@/context/i18n`) - returns `'en-US'`
-
-**Default behavior**: Most tests should use the global mock (no local override needed).
-
-**For custom translations**: Use the helper function from `@/test/i18n-mock`:
-
-```typescript
-import { createReactI18nextMock } from '@/test/i18n-mock'
-
-vi.mock('react-i18next', () => createReactI18nextMock({
-  'my.custom.key': 'Custom translation',
-  'button.save': 'Save',
-}))
-```
-
-**Avoid**: Manually defining `useTranslation` mocks that just return the key - the global mock already does this.
-
-### 2. Next.js Router
-
-```typescript
-const mockPush = vi.fn()
-const mockReplace = vi.fn()
-
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({
-    push: mockPush,
-    replace: mockReplace,
-    back: vi.fn(),
-    prefetch: vi.fn(),
-  }),
-  usePathname: () => '/current-path',
-  useSearchParams: () => new URLSearchParams('?key=value'),
-}))
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('should navigate on click', () => {
-    render(<Component />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(mockPush).toHaveBeenCalledWith('/expected-path')
-  })
-})
-```
-
-### 3. Portal Components (with Shared State)
-
-```typescript
-// ⚠️ Important: Use shared state for components that depend on each other
-let mockPortalOpenState = false
-
-vi.mock('@/app/components/base/portal-to-follow-elem', () => ({
-  PortalToFollowElem: ({ children, open, ...props }: any) => {
-    mockPortalOpenState = open || false  // Update shared state
-    return <div data-testid="portal" data-open={open}>{children}</div>
-  },
-  PortalToFollowElemContent: ({ children }: any) => {
-    // ✅ Matches actual: returns null when portal is closed
-    if (!mockPortalOpenState) return null
-    return <div data-testid="portal-content">{children}</div>
-  },
-  PortalToFollowElemTrigger: ({ children }: any) => (
-    <div data-testid="portal-trigger">{children}</div>
-  ),
-}))
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockPortalOpenState = false  // ✅ Reset shared state
-  })
-})
-```
-
-### 4. API Service Mocks
-
-```typescript
-import * as api from '@/service/api'
-
-vi.mock('@/service/api')
-
-const mockedApi = vi.mocked(api)
-
-describe('Component', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    
-    // Setup default mock implementation
-    mockedApi.fetchData.mockResolvedValue({ data: [] })
-  })
-
-  it('should show data on success', async () => {
-    mockedApi.fetchData.mockResolvedValue({ data: [{ id: 1 }] })
-    
-    render(<Component />)
-    
-    await waitFor(() => {
-      expect(screen.getByText('1')).toBeInTheDocument()
-    })
-  })
-
-  it('should show error on failure', async () => {
-    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
-    
-    render(<Component />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-### 5. HTTP Mocking with Nock
-
-```typescript
-import nock from 'nock'
-
-const GITHUB_HOST = 'https://api.github.com'
-const GITHUB_PATH = '/repos/owner/repo'
-
-const mockGithubApi = (status: number, body: Record<string, unknown>, delayMs = 0) => {
-  return nock(GITHUB_HOST)
-    .get(GITHUB_PATH)
-    .delay(delayMs)
-    .reply(status, body)
-}
-
-describe('GithubComponent', () => {
-  afterEach(() => {
-    nock.cleanAll()
-  })
-
-  it('should display repo info', async () => {
-    mockGithubApi(200, { name: 'dify', stars: 1000 })
-    
-    render(<GithubComponent />)
-    
-    await waitFor(() => {
-      expect(screen.getByText('dify')).toBeInTheDocument()
-    })
-  })
-
-  it('should handle API error', async () => {
-    mockGithubApi(500, { message: 'Server error' })
-    
-    render(<GithubComponent />)
-    
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument()
-    })
-  })
-})
-```
-
-### 6. Context Providers
-
-```typescript
-import { ProviderContext } from '@/context/provider-context'
-import { createMockProviderContextValue, createMockPlan } from '@/__mocks__/provider-context'
-
-describe('Component with Context', () => {
-  it('should render for free plan', () => {
-    const mockContext = createMockPlan('sandbox')
-    
-    render(
-      <ProviderContext.Provider value={mockContext}>
-        <Component />
-      </ProviderContext.Provider>
-    )
-    
-    expect(screen.getByText('Upgrade')).toBeInTheDocument()
-  })
-
-  it('should render for pro plan', () => {
-    const mockContext = createMockPlan('professional')
-    
-    render(
-      <ProviderContext.Provider value={mockContext}>
-        <Component />
-      </ProviderContext.Provider>
-    )
-    
-    expect(screen.queryByText('Upgrade')).not.toBeInTheDocument()
-  })
-})
-```
-
-### 7. React Query
-
-```typescript
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-
-const createTestQueryClient = () => new QueryClient({
-  defaultOptions: {
-    queries: { retry: false },
-    mutations: { retry: false },
-  },
-})
-
-const renderWithQueryClient = (ui: React.ReactElement) => {
-  const queryClient = createTestQueryClient()
-  return render(
-    <QueryClientProvider client={queryClient}>
-      {ui}
-    </QueryClientProvider>
-  )
-}
-```
-
-## Mock Best Practices
-
-### ✅ DO
-
-1. **Use real base components** - Import from `@/app/components/base/` directly
-1. **Use real project components** - Prefer importing over mocking
-1. **Use real Zustand stores** - Set test state via `store.setState()`
-1. **Reset mocks in `beforeEach`**, not `afterEach`
-1. **Match actual component behavior** in mocks (when mocking is necessary)
-1. **Use factory functions** for complex mock data
-1. **Import actual types** for type safety
-1. **Reset shared mock state** in `beforeEach`
-
-### ❌ DON'T
-
-1. **Don't mock base components** (`Loading`, `Button`, `Tooltip`, etc.)
-1. **Don't mock Zustand store modules** - Use real stores with `setState()`
-1. Don't mock components you can import directly
-1. Don't create overly simplified mocks that miss conditional logic
-1. Don't forget to clean up nock after each test
-1. Don't use `any` types in mocks without necessity
-
-### Mock Decision Tree
-
-```
-Need to use a component in test?
-│
-├─ Is it from @/app/components/base/*?
-│  └─ YES → Import real component, DO NOT mock
-│
-├─ Is it a project component?
-│  └─ YES → Prefer importing real component
-│           Only mock if setup is extremely complex
-│
-├─ Is it an API service (@/service/*)?
-│  └─ YES → Mock it
-│
-├─ Is it a third-party lib with side effects?
-│  └─ YES → Mock it (next/navigation, external SDKs)
-│
-├─ Is it a Zustand store?
-│  └─ YES → DO NOT mock the module!
-│           Use real store + setState() to set test state
-│           (Global mock handles auto-reset)
-│
-└─ Is it i18n?
-   └─ YES → Uses shared mock (auto-loaded). Override only for custom translations
-```
-
-## Zustand Store Testing
-
-### Global Zustand Mock (Auto-loaded)
-
-Zustand is globally mocked in `web/vitest.setup.ts` following the [official Zustand testing guide](https://zustand.docs.pmnd.rs/guides/testing). The mock in `web/__mocks__/zustand.ts` provides:
-
-- Real store behavior with `getState()`, `setState()`, `subscribe()` methods
-- Automatic store reset after each test via `afterEach`
-- Proper test isolation between tests
-
-### ✅ Recommended: Use Real Stores (Official Best Practice)
-
-**DO NOT mock store modules manually.** Import and use the real store, then use `setState()` to set test state:
-
-```typescript
-// ✅ CORRECT: Use real store with setState
-import { useAppStore } from '@/app/components/app/store'
-
-describe('MyComponent', () => {
-  it('should render app details', () => {
-    // Arrange: Set test state via setState
-    useAppStore.setState({
-      appDetail: {
-        id: 'test-app',
-        name: 'Test App',
-        mode: 'chat',
-      },
-    })
-
-    // Act
-    render(<MyComponent />)
-
-    // Assert
-    expect(screen.getByText('Test App')).toBeInTheDocument()
-    // Can also verify store state directly
-    expect(useAppStore.getState().appDetail?.name).toBe('Test App')
-  })
-
-  // No cleanup needed - global mock auto-resets after each test
-})
-```
-
-### ❌ Avoid: Manual Store Module Mocking
-
-Manual mocking conflicts with the global Zustand mock and loses store functionality:
-
-```typescript
-// ❌ WRONG: Don't mock the store module
-vi.mock('@/app/components/app/store', () => ({
-  useStore: (selector) => mockSelector(selector),  // Missing getState, setState!
-}))
-
-// ❌ WRONG: This conflicts with global zustand mock
-vi.mock('@/app/components/workflow/store', () => ({
-  useWorkflowStore: vi.fn(() => mockState),
-}))
-```
-
-**Problems with manual mocking:**
-
-1. Loses `getState()`, `setState()`, `subscribe()` methods
-1. Conflicts with global Zustand mock behavior
-1. Requires manual maintenance of store API
-1. Tests don't reflect actual store behavior
-
-### When Manual Store Mocking is Necessary
-
-In rare cases where the store has complex initialization or side effects, you can mock it, but ensure you provide the full store API:
-
-```typescript
-// If you MUST mock (rare), include full store API
-const mockStore = {
-  appDetail: { id: 'test', name: 'Test' },
-  setAppDetail: vi.fn(),
-}
-
-vi.mock('@/app/components/app/store', () => ({
-  useStore: Object.assign(
-    (selector: (state: typeof mockStore) => unknown) => selector(mockStore),
-    {
-      getState: () => mockStore,
-      setState: vi.fn(),
-      subscribe: vi.fn(),
-    },
-  ),
-}))
-```
-
-### Store Testing Decision Tree
-
-```
-Need to test a component using Zustand store?
-│
-├─ Can you use the real store?
-│  └─ YES → Use real store + setState (RECOMMENDED)
-│           useAppStore.setState({ ... })
-│
-├─ Does the store have complex initialization/side effects?
-│  └─ YES → Consider mocking, but include full API
-│           (getState, setState, subscribe)
-│
-└─ Are you testing the store itself (not a component)?
-   └─ YES → Test store directly with getState/setState
-            const store = useMyStore
-            store.setState({ count: 0 })
-            store.getState().increment()
-            expect(store.getState().count).toBe(1)
-```
-
-### Example: Testing Store Actions
-
-```typescript
-import { useCounterStore } from '@/stores/counter'
-
-describe('Counter Store', () => {
-  it('should increment count', () => {
-    // Initial state (auto-reset by global mock)
-    expect(useCounterStore.getState().count).toBe(0)
-
-    // Call action
-    useCounterStore.getState().increment()
-
-    // Verify state change
-    expect(useCounterStore.getState().count).toBe(1)
-  })
-
-  it('should reset to initial state', () => {
-    // Set some state
-    useCounterStore.setState({ count: 100 })
-    expect(useCounterStore.getState().count).toBe(100)
-
-    // After this test, global mock will reset to initial state
-  })
-})
-```
-
-## Factory Function Pattern
-
-```typescript
-// __mocks__/data-factories.ts
-import type { User, Project } from '@/types'
-
-export const createMockUser = (overrides: Partial<User> = {}): User => ({
-  id: 'user-1',
-  name: 'Test User',
-  email: 'test@example.com',
-  role: 'member',
-  createdAt: new Date().toISOString(),
-  ...overrides,
-})
-
-export const createMockProject = (overrides: Partial<Project> = {}): Project => ({
-  id: 'project-1',
-  name: 'Test Project',
-  description: 'A test project',
-  owner: createMockUser(),
-  members: [],
-  createdAt: new Date().toISOString(),
-  ...overrides,
-})
-
-// Usage in tests
-it('should display project owner', () => {
-  const project = createMockProject({
-    owner: createMockUser({ name: 'John Doe' }),
-  })
-  
-  render(<ProjectCard project={project} />)
-  expect(screen.getByText('John Doe')).toBeInTheDocument()
-})
-```

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

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

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

@@ -0,0 +1,69 @@
+---
+name: how-to-write-component
+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.
+---
+
+# React Component Architecture
+
+Use this skill to make component ownership and lifecycle explicit before implementation. Classify every stateful value on three independent dimensions:
+
+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.
+
+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].
+- 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].
+
+## Common Workflow
+
+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
+[runtime]: references/runtime.md
+[state]: references/state.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

@@ -0,0 +1,64 @@
+# Component Data And Queries
+
+Read this document when a component consumes generated contracts, nullable API values, TanStack Query, mutations, prefetching, authentication, or workspace state.
+
+## Generated Contracts
+
+- Treat generated contracts as authoritative at API, query, mutation, cache, and service boundaries. Enterprise APIs use `packages/contracts/generated/enterprise/*`.
+- Backend Pydantic and OpenAPI schemas own API shape. Follow the generated `{ params, query?, body? }` input shape; when it is wrong, fix the backend schema and regenerate `packages/contracts/generated/*`.
+- Do not hand-write DTO mirrors, widen generated fields or enums, edit generated output, or add a parallel frontend status layer unless it models product state absent from the API.
+- Check deprecated markers, schema shape, and the actual consumer before assuming that a generated operation is ready to use.
+- 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. 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.
+- 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.
+- 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.
+- 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

@@ -0,0 +1,34 @@
+# Component Interactions And Overlays
+
+Read this document when a change involves application hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces. Overlay primitive selection and layering are owned by the [overlay contract].
+
+## Focus And Semantics
+
+- Preserve a visible focus indicator on the final focusable element. Styled Dify UI controls usually provide it; headless anatomy parts and direct trigger exports may not.
+- Native buttons, links, custom trigger renderers, clickable rows, icon controls, and menu-like items must retain their correct native semantics and accessible name.
+- Do not hide an outline without an equivalent visible `focus-visible` treatment. Follow an existing Dify UI pattern rather than inventing a call-site style.
+
+## Keyboard Commands
+
+- Distinguish application commands from widget-local keyboard semantics. Use `@tanstack/react-hotkeys` for application commands; keep menu navigation, dialog Escape handling, editor behavior, and ARIA widget keys in their local primitive or owner.
+- Use `useHotkey` or `useHotkeys` for registered commands. When an existing `onKeyDown` intentionally owns the command, use `matchesKeyboardEvent` rather than duplicating modifier parsing or adding another global listener.
+- Keep registration and keycap or menu display derived from one canonical command. Distinguish registered commands, held keys, and display-only accelerators.
+- Keep a single-owner command beside its component. Create a feature-local hotkey module only when several production files share it; tests alone do not justify extraction.
+- Make availability and scope explicit with `enabled`, `ignoreInputs`, and `target`. Put a target ref on the actual behavior owner rather than creating wrapper DOM solely for hotkey scope.
+- Preserve existing `preventDefault` and propagation behavior when migrating command APIs.
+- Test observable command behavior, disabled and input scope, target scope, and the registration/display contract at the owning feature boundary.
+
+## Secondary Surfaces
+
+- Follow the [overlay contract] for primitive choice and shared mechanics. The nearest consumer `AGENTS.md` owns application-specific composite reuse policy.
+- 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.
+- 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 contract]: ../../../../packages/dify-ui/docs/overlays.md
+[state ownership]: state.md

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

@@ -0,0 +1,53 @@
+# Component Ownership And Modules
+
+Read this document when auditing, adding, moving, splitting, or refactoring React components or feature modules.
+
+## Vertical Modules
+
+- Organize code by product workflow, route, or behavior owner. Keep components, hooks, local types, atoms, query helpers, tests, and small utilities beside the code that changes with them.
+- Name page and tab folders after the current route, tab, or user-visible surface. Do not preserve stale parent groupings that no longer own multiple surfaces.
+- Split a growing page or tab by product or visual owners. Keep the feature root for its public entrypoint and genuinely cross-owner coordination.
+- Import other features only through explicit public entrypoints. Avoid barrels that merely re-export secondary owners.
+- Promote code outside a feature only when multiple verticals use the same stable contract. Possible future reuse is not sufficient.
+
+## Component Ownership
+
+- 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, 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.
+- 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

@@ -0,0 +1,28 @@
+# Component Effects, Navigation, And Runtime Cost
+
+Read this document when a change introduces Effects, navigation side effects, memoization, preloading, or render-cost optimizations.
+
+## Effects
+
+- Keep render pure: do not read or write `ref.current` during render except for predictable null-guarded lazy initialization. Update interaction-owned refs in event handlers, synchronize external-system refs after commit, and use state or derivation for rendered values.
+- Use Effects only to synchronize with a named external system such as a browser API, subscription, timer, analytics integration, non-React widget, or imperative DOM API.
+- Do not use Effects to transform render state, handle user actions, copy query data, reset state from props, or fetch data owned by framework APIs or TanStack Query.
+- Initialize query-backed form sessions after their defaults are available instead of copying data through Effects. Use a stable semantic identity key when the represented identity changes; use the intended surface lifecycle for per-session reset.
+- 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
+
+- Use `Link` for ordinary navigation.
+- Use router APIs for command-flow side effects such as mutation success, guarded redirects, or form submission.
+- Keep shareable navigation state in the URL rather than hidden component state.
+
+## Runtime Cost
+
+- Move changing state to the smallest consumer before considering memoization. Stable parent content can be lifted and passed as children.
+- 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.
+- Use narrow selectors or field-level atoms for broad stores and subscriptions. Do not optimize simple primitive expressions merely for stylistic consistency.

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

@@ -0,0 +1,88 @@
+# Component State And URL Ownership
+
+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, 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 And Sessions
+
+- 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.
+- 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.
+- 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.
+
+## Build A Clean Jotai Graph
+
+- 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 `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.
+- `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

.agents/skills/orpc-contract-first/SKILL.md

@@ -1,46 +0,0 @@
----
-name: orpc-contract-first
-description: Guide for implementing oRPC contract-first API patterns in Dify frontend. Triggers when creating new API contracts, adding service endpoints, integrating TanStack Query with typed contracts, or migrating legacy service calls to oRPC. Use for all API layer work in web/contract and web/service directories.
----
-
-# oRPC Contract-First Development
-
-## Project Structure
-
-```
-web/contract/
-├── base.ts           # Base contract (inputStructure: 'detailed')
-├── router.ts         # Router composition & type exports
-├── marketplace.ts    # Marketplace contracts
-└── console/          # Console contracts by domain
-    ├── system.ts
-    └── billing.ts
-```
-
-## Workflow
-
-1. **Create contract** in `web/contract/console/{domain}.ts`
-   - Import `base` from `../base` and `type` from `@orpc/contract`
-   - Define route with `path`, `method`, `input`, `output`
-
-2. **Register in router** at `web/contract/router.ts`
-   - Import directly from domain file (no barrel files)
-   - Nest by API prefix: `billing: { invoices, bindPartnerStack }`
-
-3. **Create hooks** in `web/service/use-{domain}.ts`
-   - Use `consoleQuery.{group}.{contract}.queryKey()` for query keys
-   - Use `consoleClient.{group}.{contract}()` for API calls
-
-## Key Rules
-
-- **Input structure**: Always use `{ params, query?, body? }` format
-- **Path params**: Use `{paramName}` in path, match in `params` object
-- **Router nesting**: Group by API prefix (e.g., `/billing/*` → `billing: {}`)
-- **No barrel files**: Import directly from specific files
-- **Types**: Import from `@/types/`, use `type<T>()` helper
-
-## Type Export
-
-```typescript
-export type ConsoleInputs = InferContractRouterInputs<typeof consoleRouterContract>
-```

.claude/skills/backend-code-review

@@ -0,0 +1 @@
+../../.agents/skills/backend-code-review

.claude/skills/component-refactoring

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

.claude/skills/e2e-cucumber-playwright

@@ -0,0 +1 @@
+../../.agents/skills/e2e-cucumber-playwright

.claude/skills/how-to-write-component

@@ -0,0 +1 @@
+../../.agents/skills/how-to-write-component

.claude/skills/orpc-contract-first

@@ -1 +0,0 @@
-../../.agents/skills/orpc-contract-first

.coveragerc

@@ -1,5 +1,6 @@
 [run]
 omit =
+    api/conftest.py
     api/tests/*
     api/migrations/*
     api/core/rag/datasource/vdb/*

.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.
-}
+}

.devcontainer/post_create_command.sh

@@ -7,7 +7,7 @@ cd web && pnpm install
 pipx install uv
 
 echo "alias start-api=\"cd $WORKSPACE_ROOT/api && uv run python -m flask run --host 0.0.0.0 --port=5001 --debug\"" >> ~/.bashrc
-echo "alias start-worker=\"cd $WORKSPACE_ROOT/api && uv run python -m celery -A app.celery worker -P threads -c 1 --loglevel INFO -Q dataset,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention\"" >> ~/.bashrc
+echo "alias start-worker=\"cd $WORKSPACE_ROOT/api && uv run python -m celery -A app.celery worker -P threads -c 1 --loglevel INFO -Q dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention\"" >> ~/.bashrc
 echo "alias start-web=\"cd $WORKSPACE_ROOT/web && pnpm dev:inspect\"" >> ~/.bashrc
 echo "alias start-web-prod=\"cd $WORKSPACE_ROOT/web && pnpm build && pnpm start\"" >> ~/.bashrc
 echo "alias start-containers=\"cd $WORKSPACE_ROOT/docker && docker-compose -f docker-compose.middleware.yaml -p dify --env-file middleware.env up -d\"" >> ~/.bashrc

.dockerignore

@@ -0,0 +1,15 @@
+**/node_modules
+**/.pnpm-store
+**/dist
+**/.next
+**/.turbo
+**/.cache
+**/__pycache__
+**/*.pyc
+**/.mypy_cache
+**/.ruff_cache
+.git
+.github
+*.md
+!web/README.md
+!api/README.md

.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

.gitattributes

@@ -5,3 +5,7 @@
 # them.
 
 *.sh      text eol=lf
+
+# Codegen output must stay byte-identical across platforms so
+# `pnpm tree:check` in CI does not trip on CRLF rewrites.
+*.generated.ts  text eol=lf

.github/CODEOWNERS

@@ -4,7 +4,10 @@
 # Owners can be @username, @org/team-name, or email addresses.
 # For more information, see: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
-* @crazywoola @laipz8200 @Yeuoly
+* @crazywoola @laipz8200
+
+# Lint bulk suppression baselines.
+/oxlint-suppressions.json
 
 # CODEOWNERS file
 /.github/CODEOWNERS @laipz8200 @crazywoola
@@ -12,37 +15,45 @@
 # Agents
 /.agents/skills/ @hyoban
 
+# Packages
+/packages/ @lyzno1
+/packages/contracts/ @crazywoola @laipz8200
+
 # Docs
 /docs/ @crazywoola
 
+# CLI
+/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 - MCP
-/api/core/mcp/ @Nov1c444
-/api/core/entities/mcp_provider.py @Nov1c444
-/api/services/tools/mcp_tools_manage_service.py @Nov1c444
-/api/controllers/mcp/ @Nov1c444
-/api/controllers/console/app/mcp_server.py @Nov1c444
-
-# Backend - Tests
+# Backend - Tests (default owners, domain-specific rules below will override)
 /api/tests/ @laipz8200 @QuantumGhost
-
-/api/tests/**/*mcp* @Nov1c444
-
-# Backend - Workflow - Engine (Core graph execution engine)
-/api/core/workflow/graph_engine/ @laipz8200 @QuantumGhost
-/api/core/workflow/runtime/ @laipz8200 @QuantumGhost
-/api/core/workflow/graph/ @laipz8200 @QuantumGhost
-/api/core/workflow/graph_events/ @laipz8200 @QuantumGhost
-/api/core/workflow/node_events/ @laipz8200 @QuantumGhost
-/api/core/model_runtime/ @laipz8200 @QuantumGhost
-
-# Backend - Workflow - Nodes (Agent, Iteration, Loop, LLM)
-/api/core/workflow/nodes/agent/ @Nov1c444
-/api/core/workflow/nodes/iteration/ @Nov1c444
-/api/core/workflow/nodes/loop/ @Nov1c444
-/api/core/workflow/nodes/llm/ @Nov1c444
+/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
@@ -83,50 +94,49 @@
 /api/tasks/deal_dataset_vector_index_task.py @JohnJyong
 
 # Backend - Plugins
-/api/core/plugin/ @Mairuis @Yeuoly @Stream29
-/api/services/plugin/ @Mairuis @Yeuoly @Stream29
-/api/controllers/console/workspace/plugin.py @Mairuis @Yeuoly @Stream29
-/api/controllers/inner_api/plugin/ @Mairuis @Yeuoly @Stream29
-/api/tasks/process_tenant_plugin_autoupgrade_check_task.py @Mairuis @Yeuoly @Stream29
+/api/core/plugin/ @WH-2099
+/api/services/plugin/ @WH-2099
+/api/controllers/console/workspace/plugin.py @WH-2099
+/api/controllers/inner_api/plugin/ @WH-2099
+/api/tasks/process_tenant_plugin_autoupgrade_check_task.py @WH-2099
 
 # Backend - Trigger/Schedule/Webhook
-/api/controllers/trigger/ @Mairuis @Yeuoly
-/api/controllers/console/app/workflow_trigger.py @Mairuis @Yeuoly
-/api/controllers/console/workspace/trigger_providers.py @Mairuis @Yeuoly
-/api/core/trigger/ @Mairuis @Yeuoly
-/api/core/app/layers/trigger_post_layer.py @Mairuis @Yeuoly
-/api/services/trigger/ @Mairuis @Yeuoly
-/api/models/trigger.py @Mairuis @Yeuoly
-/api/fields/workflow_trigger_fields.py @Mairuis @Yeuoly
-/api/repositories/workflow_trigger_log_repository.py @Mairuis @Yeuoly
-/api/repositories/sqlalchemy_workflow_trigger_log_repository.py @Mairuis @Yeuoly
-/api/libs/schedule_utils.py @Mairuis @Yeuoly
-/api/services/workflow/scheduler.py @Mairuis @Yeuoly
-/api/schedule/trigger_provider_refresh_task.py @Mairuis @Yeuoly
-/api/schedule/workflow_schedule_task.py @Mairuis @Yeuoly
-/api/tasks/trigger_processing_tasks.py @Mairuis @Yeuoly
-/api/tasks/trigger_subscription_refresh_tasks.py @Mairuis @Yeuoly
-/api/tasks/workflow_schedule_tasks.py @Mairuis @Yeuoly
-/api/tasks/workflow_cfs_scheduler/ @Mairuis @Yeuoly
-/api/events/event_handlers/sync_plugin_trigger_when_app_created.py @Mairuis @Yeuoly
-/api/events/event_handlers/update_app_triggers_when_app_published_workflow_updated.py @Mairuis @Yeuoly
-/api/events/event_handlers/sync_workflow_schedule_when_app_published.py @Mairuis @Yeuoly
-/api/events/event_handlers/sync_webhook_when_app_created.py @Mairuis @Yeuoly
+/api/controllers/trigger/ @CourTeous33
+/api/controllers/console/app/workflow_trigger.py @CourTeous33
+/api/controllers/console/workspace/trigger_providers.py @CourTeous33
+/api/core/trigger/ @CourTeous33
+/api/core/app/layers/trigger_post_layer.py @CourTeous33
+/api/services/trigger/ @CourTeous33
+/api/models/trigger.py @CourTeous33
+/api/repositories/workflow_trigger_log_repository.py @CourTeous33
+/api/repositories/sqlalchemy_workflow_trigger_log_repository.py @CourTeous33
+/api/libs/schedule_utils.py @CourTeous33
+/api/services/workflow/scheduler.py @CourTeous33
+/api/schedule/trigger_provider_refresh_task.py @CourTeous33
+/api/schedule/workflow_schedule_task.py @CourTeous33
+/api/tasks/trigger_processing_tasks.py @CourTeous33
+/api/tasks/trigger_subscription_refresh_tasks.py @CourTeous33
+/api/tasks/workflow_schedule_tasks.py @CourTeous33
+/api/tasks/workflow_cfs_scheduler/ @CourTeous33
+/api/events/event_handlers/sync_plugin_trigger_when_app_created.py @CourTeous33
+/api/events/event_handlers/update_app_triggers_when_app_published_workflow_updated.py @CourTeous33
+/api/events/event_handlers/sync_workflow_schedule_when_app_published.py @CourTeous33
+/api/events/event_handlers/sync_webhook_when_app_created.py @CourTeous33
 
 # Backend - Async Workflow
-/api/services/async_workflow_service.py @Mairuis @Yeuoly
-/api/tasks/async_workflow_tasks.py @Mairuis @Yeuoly
+/api/services/async_workflow_service.py @Mairuis
+/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/ @GarfieldDai @GareArc
-/api/services/enterprise/ @GarfieldDai @GareArc
-/api/services/feature_service.py @GarfieldDai @GareArc
-/api/controllers/console/feature.py @GarfieldDai @GareArc
-/api/controllers/web/feature.py @GarfieldDai @GareArc
+/api/configs/enterprise/ @GareArc
+/api/services/enterprise/ @GareArc
+/api/services/feature_service.py @GareArc
+/api/controllers/console/feature.py @GareArc
+/api/controllers/web/feature.py @GareArc
 
 # Backend - Database Migrations
 /api/migrations/ @snakevash @laipz8200 @MRZHUH
@@ -137,6 +147,19 @@
 # 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
+/web/features/ @lyzno1
+/web/hooks/ @lyzno1
+/web/scripts/gen-icons.mjs @lyzno1
+
 # Frontend - Web Tests
 /.github/workflows/web-tests.yml @iamjoel
 
@@ -160,6 +183,7 @@
 
 # Frontend - App - API Documentation
 /web/app/components/develop/ @JzoNgKVO @iamjoel
+/web/app/components/develop/template/*.mdx @JzoNgKVO @iamjoel @RiskeyL
 
 # Frontend - App - Logs and Annotations
 /web/app/components/app/workflow-log/ @JzoNgKVO @iamjoel
@@ -189,7 +213,6 @@
 /web/app/components/rag-pipeline/store/ @iamjoel @zxhlyh
 
 # Frontend - RAG - Documents List
-/web/app/components/datasets/documents/list.tsx @iamjoel @WTW0313
 /web/app/components/datasets/documents/create-from-pipeline/ @iamjoel @WTW0313
 
 # Frontend - RAG - Segments List
@@ -208,22 +231,22 @@
 /web/app/components/plugins/marketplace/ @iamjoel @Yessenia-d
 
 # Frontend - Login and Registration
-/web/app/signin/ @douxc @iamjoel
-/web/app/signup/ @douxc @iamjoel
-/web/app/reset-password/ @douxc @iamjoel
-/web/app/install/ @douxc @iamjoel
-/web/app/init/ @douxc @iamjoel
-/web/app/forgot-password/ @douxc @iamjoel
-/web/app/account/ @douxc @iamjoel
+/web/app/signin/ @iamjoel
+/web/app/signup/ @iamjoel
+/web/app/reset-password/ @iamjoel
+/web/app/install/ @iamjoel
+/web/app/init/ @iamjoel
+/web/app/forgot-password/ @iamjoel
+/web/app/account/ @iamjoel
 
 # Frontend - Service Authentication
-/web/service/base.ts @douxc @iamjoel
+/web/service/base.ts @iamjoel
 
 # Frontend - WebApp Authentication and Access Control
-/web/app/(shareLayout)/components/ @douxc @iamjoel
-/web/app/(shareLayout)/webapp-signin/ @douxc @iamjoel
-/web/app/(shareLayout)/webapp-reset-password/ @douxc @iamjoel
-/web/app/components/app/app-access-control/ @douxc @iamjoel
+/web/app/(shareLayout)/components/ @iamjoel
+/web/app/(shareLayout)/webapp-signin/ @iamjoel
+/web/app/(shareLayout)/webapp-reset-password/ @iamjoel
+/web/app/components/app/app-access-control/ @iamjoel
 
 # Frontend - Explore Page
 /web/app/components/explore/ @CodingOnStar @iamjoel
@@ -242,18 +265,37 @@
 /web/app/components/base/**/*.spec.tsx @hyoban @CodingOnStar
 
 # Frontend - Utils and Hooks
-/web/utils/classnames.ts @iamjoel @zxhlyh
 /web/utils/time.ts @iamjoel @zxhlyh
 /web/utils/format.ts @iamjoel @zxhlyh
 /web/utils/clipboard.ts @iamjoel @zxhlyh
-/web/hooks/use-document-title.ts @iamjoel @zxhlyh
 
 # Frontend - Billing and Education
 /web/app/components/billing/ @iamjoel @zxhlyh
-/web/app/education-apply/ @iamjoel @zxhlyh
+/web/app/education/ @iamjoel @zxhlyh
 
 # Frontend - Workspace
 /web/app/components/header/account-dropdown/workplace-selector/ @iamjoel @zxhlyh
 
+# Frontend - App Shell and Console Bootstrap
+/web/app/layout.tsx @iamjoel @lyzno1
+/web/app/error.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/layout.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/providers.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/hydration-boundary.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/profile-bootstrap-gate.tsx @iamjoel @lyzno1
+/web/app/(commonLayout)/error.tsx @iamjoel @lyzno1
+/web/app/account/(commonLayout)/layout.tsx @iamjoel @lyzno1
+/web/app/components/main-nav/* @iamjoel @lyzno1
+/web/app/components/main-nav/components/* @iamjoel @lyzno1
+/web/context/query-client.tsx @iamjoel @lyzno1
+/web/context/query-client-server.ts @iamjoel @lyzno1
+/web/proxy.ts @iamjoel @lyzno1
+/web/app/auth/refresh/route.ts @iamjoel @lyzno1
+/web/service/server.ts @iamjoel @lyzno1
+
+# Frontend - Browser Mode Tests
+/web/app/**/*.browser.spec.ts @lyzno1
+/web/app/**/*.browser.spec.tsx @lyzno1
+
 # Docker
 /docker/* @laipz8200

.github/DISCUSSION_TEMPLATE/general.yml

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

.github/DISCUSSION_TEMPLATE/help.yml

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

.github/DISCUSSION_TEMPLATE/suggestion.yml

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

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/feature_request.yml

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

.github/ISSUE_TEMPLATE/refactor.yml

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

.github/actions/setup-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

@@ -0,0 +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 and Node.js
+      uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
+      with:
+        install: false
+    - name: Setup Vite+
+      uses: voidzero-dev/setup-vp@9fd26ff49f9b5e6276c2b493da4454ad4527f7f4 # v1.20.0
+      with:
+        node-manager: false
+        package-manager: |
+          pnpm: false
+          npm: false
+        cache: 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/dependabot.yml

@@ -1,12 +1,223 @@
 version: 2
+
 updates:
-  - package-ecosystem: "npm"
-    directory: "/web"
+  - package-ecosystem: 'uv'
+    directory: '/api'
+    open-pull-requests-limit: 10
     schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 2
-  - package-ecosystem: "uv"
-    directory: "/api"
+      interval: 'weekly'
+    groups:
+      flask:
+        patterns:
+          - 'flask'
+          - 'flask-*'
+          - 'werkzeug'
+          - 'gunicorn'
+      google:
+        patterns:
+          - 'google-*'
+          - 'googleapis-*'
+      opentelemetry:
+        patterns:
+          - 'opentelemetry-*'
+      pydantic:
+        patterns:
+          - 'pydantic'
+          - 'pydantic-*'
+      llm:
+        patterns:
+          - 'langfuse'
+          - 'langsmith'
+          - 'litellm'
+          - 'mlflow*'
+          - 'opik'
+          - 'weave*'
+          - 'arize*'
+          - 'tiktoken'
+          - 'transformers'
+      database:
+        patterns:
+          - 'sqlalchemy'
+          - 'psycopg2*'
+          - 'psycogreen'
+          - 'redis*'
+          - 'alembic*'
+      storage:
+        patterns:
+          - 'boto3*'
+          - 'botocore*'
+          - 'azure-*'
+          - 'bce-*'
+          - 'cos-python-*'
+          - 'esdk-obs-*'
+          - 'google-cloud-storage'
+          - 'opendal'
+          - 'oss2'
+          - 'supabase*'
+          - 'tos*'
+      vdb:
+        patterns:
+          - 'alibabacloud*'
+          - 'chromadb'
+          - 'clickhouse-*'
+          - 'clickzetta-*'
+          - 'couchbase'
+          - 'elasticsearch'
+          - 'opensearch-py'
+          - 'oracledb'
+          - 'pgvect*'
+          - 'pymilvus'
+          - 'pymochow'
+          - 'pyobvector'
+          - 'qdrant-client'
+          - 'intersystems-*'
+          - 'tablestore'
+          - 'tcvectordb'
+          - 'tidb-vector'
+          - 'upstash-*'
+          - 'volcengine-*'
+          - 'weaviate-*'
+          - 'xinference-*'
+          - 'mo-vector'
+          - 'mysql-connector-*'
+      dev:
+        patterns:
+          - 'coverage'
+          - 'dotenv-linter'
+          - 'faker'
+          - 'lxml-stubs'
+          - 'basedpyright'
+          - 'ruff'
+          - 'pytest*'
+          - 'types-*'
+          - 'boto3-stubs'
+          - 'hypothesis'
+          - 'pandas-stubs'
+          - 'scipy-stubs'
+          - 'import-linter'
+          - 'celery-types'
+          - 'mypy*'
+          - 'pyrefly'
+      python-packages:
+        patterns:
+          - '*'
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    open-pull-requests-limit: 5
     schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 2
+      interval: 'weekly'
+    groups:
+      github-actions-dependencies:
+        patterns:
+          - '*'
+  - package-ecosystem: 'uv'
+    directory: '/api'
+    target-branch: 'lts/1.13.x'
+    open-pull-requests-limit: 10
+    schedule:
+      interval: 'weekly'
+    groups:
+      flask:
+        patterns:
+          - 'flask'
+          - 'flask-*'
+          - 'werkzeug'
+          - 'gunicorn'
+      google:
+        patterns:
+          - 'google-*'
+          - 'googleapis-*'
+      opentelemetry:
+        patterns:
+          - 'opentelemetry-*'
+      pydantic:
+        patterns:
+          - 'pydantic'
+          - 'pydantic-*'
+      llm:
+        patterns:
+          - 'langfuse'
+          - 'langsmith'
+          - 'litellm'
+          - 'mlflow*'
+          - 'opik'
+          - 'weave*'
+          - 'arize*'
+          - 'tiktoken'
+          - 'transformers'
+      database:
+        patterns:
+          - 'sqlalchemy'
+          - 'psycopg2*'
+          - 'psycogreen'
+          - 'redis*'
+          - 'alembic*'
+      storage:
+        patterns:
+          - 'boto3*'
+          - 'botocore*'
+          - 'azure-*'
+          - 'bce-*'
+          - 'cos-python-*'
+          - 'esdk-obs-*'
+          - 'google-cloud-storage'
+          - 'opendal'
+          - 'oss2'
+          - 'supabase*'
+          - 'tos*'
+      vdb:
+        patterns:
+          - 'alibabacloud*'
+          - 'chromadb'
+          - 'clickhouse-*'
+          - 'clickzetta-*'
+          - 'couchbase'
+          - 'elasticsearch'
+          - 'opensearch-py'
+          - 'oracledb'
+          - 'pgvect*'
+          - 'pymilvus'
+          - 'pymochow'
+          - 'pyobvector'
+          - 'qdrant-client'
+          - 'intersystems-*'
+          - 'tablestore'
+          - 'tcvectordb'
+          - 'tidb-vector'
+          - 'upstash-*'
+          - 'volcengine-*'
+          - 'weaviate-*'
+          - 'xinference-*'
+          - 'mo-vector'
+          - 'mysql-connector-*'
+      dev:
+        patterns:
+          - 'coverage'
+          - 'dotenv-linter'
+          - 'faker'
+          - 'lxml-stubs'
+          - 'basedpyright'
+          - 'ruff'
+          - 'pytest*'
+          - 'types-*'
+          - 'boto3-stubs'
+          - 'hypothesis'
+          - 'pandas-stubs'
+          - 'scipy-stubs'
+          - 'import-linter'
+          - 'celery-types'
+          - 'mypy*'
+          - 'pyrefly'
+      python-packages:
+        patterns:
+          - '*'
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    target-branch: 'lts/1.13.x'
+    open-pull-requests-limit: 5
+    schedule:
+      interval: 'weekly'
+    groups:
+      github-actions-dependencies:
+        patterns:
+          - '*'

.github/labeler.yml

@@ -1,3 +1,14 @@
 web:
   - changed-files:
-      - any-glob-to-any-file: 'web/**'
+      - any-glob-to-any-file:
+          - 'web/**'
+          - 'packages/**'
+          - 'package.json'
+          - 'pnpm-lock.yaml'
+          - 'pnpm-workspace.yaml'
+
+e2e:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'e2e/**'
+          - '.github/workflows/web-e2e.yml'

.github/linters/.hadolint.yaml

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

.github/linters/.yaml-lint.yml

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

.github/linters/editorconfig-checker.json

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

.github/pull_request_template.md

@@ -1,23 +1,24 @@
 > [!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
 
 <!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. -->
+<!-- If this PR was created by an automated agent, add `From <Tool Name>` as the final line of the description. Example: `From Codex`. -->
 
 ## Screenshots
 
 | Before | After |
-|--------|-------|
-| ... | ... |
+| ------ | ----- |
+| ...    | ...   |
 
 ## Checklist
 
 - [ ] This change requires a documentation update, included: [Dify Document](https://github.com/langgenius/dify-docs)
-- [x] I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
-- [x] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
-- [x] I've updated the documentation accordingly.
-- [x] I ran `make lint` and `make type-check` (backend) and `cd web && npx lint-staged` (frontend) to appease the lint gods
+- [ ] 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 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 `vp staged` (frontend) to appease the lint gods

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

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_SHA=${BASE_SHA:-}
+HEAD_SHA=${HEAD_SHA:-}
+MAIN_REF=${MAIN_REF:-origin/main}
+REMEDIATION_HINT="Changes should be made from the main branch using git cherry-pick -x."
+
+error() {
+  printf 'ERROR: %s\n' "$1" >&2
+}
+
+if [[ -z "$BASE_SHA" || -z "$HEAD_SHA" ]]; then
+  error "BASE_SHA and HEAD_SHA are required. $REMEDIATION_HINT"
+  exit 2
+fi
+
+if ! git rev-parse --verify "$BASE_SHA^{commit}" > /dev/null 2>&1; then
+  error "Base commit '$BASE_SHA' is not available in the local git checkout."
+  exit 2
+fi
+
+if ! git rev-parse --verify "$HEAD_SHA^{commit}" > /dev/null 2>&1; then
+  error "Head commit '$HEAD_SHA' is not available in the local git checkout."
+  exit 2
+fi
+
+if ! git rev-parse --verify "$MAIN_REF^{commit}" > /dev/null 2>&1; then
+  error "Main ref '$MAIN_REF' is not available in the local git checkout. $REMEDIATION_HINT"
+  exit 2
+fi
+
+failed=0
+checked=0
+
+while IFS= read -r commit_sha; do
+  [[ -n "$commit_sha" ]] || continue
+
+  checked=$((checked + 1))
+  subject=$(git log -1 --format=%s "$commit_sha")
+  source_sha=$(
+    git log -1 --format=%B "$commit_sha" \
+      | sed -nE 's/^\(cherry picked from commit ([0-9a-fA-F]{7,64})\)$/\1/p' \
+      | tail -n 1
+  )
+
+  if [[ -z "$source_sha" ]]; then
+    error "Commit $commit_sha ($subject) is missing cherry-pick provenance. $REMEDIATION_HINT If version differences prevent using git cherry-pick -x, manually add '(cherry picked from commit <sha>)' to the commit message."
+    failed=1
+    continue
+  fi
+
+  if ! git cat-file -e "$source_sha^{commit}" 2> /dev/null; then
+    error "Commit $commit_sha ($subject) references source $source_sha, but that commit is not available locally. $REMEDIATION_HINT"
+    failed=1
+    continue
+  fi
+
+  if ! git merge-base --is-ancestor "$source_sha" "$MAIN_REF"; then
+    error "Commit $commit_sha ($subject) references source $source_sha, but that source is not reachable from main ($MAIN_REF). $REMEDIATION_HINT"
+    failed=1
+  fi
+done < <(git rev-list --reverse "$BASE_SHA..$HEAD_SHA")
+
+if [[ "$failed" -ne 0 ]]; then
+  exit 1
+fi
+
+if [[ "$checked" -eq 0 ]]; then
+  echo "No PR commits to check."
+else
+  echo "Verified $checked PR commit(s) include cherry-pick provenance from main."
+fi

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

@@ -0,0 +1,82 @@
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const repoRoot = process.cwd()
+const baseSha = process.env.BASE_SHA || ''
+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', 'locales', 'en-US', `${fileStem}.json`)
+
+const readCurrentJson = (fileStem) => {
+  const filePath = englishPath(fileStem)
+  if (!fs.existsSync(filePath)) return null
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+
+const readBaseJson = (fileStem) => {
+  if (!baseSha) return null
+
+  try {
+    const relativePath = `web/i18n/locales/en-US/${fileStem}.json`
+    const content = execFileSync('git', ['show', `${baseSha}:${relativePath}`], {
+      encoding: 'utf8',
+    })
+    return JSON.parse(content)
+  } catch {
+    return null
+  }
+}
+
+const compareJson = (beforeValue, afterValue) =>
+  JSON.stringify(beforeValue) === JSON.stringify(afterValue)
+
+const changes = {}
+
+for (const fileStem of files) {
+  const currentJson = readCurrentJson(fileStem)
+  const beforeJson = readBaseJson(fileStem) || {}
+  const afterJson = currentJson || {}
+  const added = {}
+  const updated = {}
+  const deleted = []
+
+  for (const [key, value] of Object.entries(afterJson)) {
+    if (!(key in beforeJson)) {
+      added[key] = value
+      continue
+    }
+
+    if (!compareJson(beforeJson[key], value)) {
+      updated[key] = {
+        before: beforeJson[key],
+        after: value,
+      }
+    }
+  }
+
+  for (const key of Object.keys(beforeJson)) {
+    if (!(key in afterJson)) deleted.push(key)
+  }
+
+  changes[fileStem] = {
+    fileDeleted: currentJson === null,
+    added,
+    updated,
+    deleted,
+  }
+}
+
+fs.writeFileSync(
+  outputPath,
+  JSON.stringify({
+    baseSha,
+    headSha,
+    files,
+    changes,
+  }),
+)

.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

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

.github/workflows/api-tests.yml

@@ -2,32 +2,91 @@ name: Run Pytest
 
 on:
   workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+
+permissions:
+  contents: read
 
 concurrency:
   group: api-tests-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
-  test:
-    name: API Tests
-    runs-on: ubuntu-latest
+  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:
+    needs: api-unit-plan
+    name: API Unit Tests (${{ matrix.python-version }}, shard ${{ matrix.shardIndex }}/${{ matrix.shardTotal }})
+    runs-on: depot-ubuntu-24.04
+    env:
+      PYTHONUNBUFFERED: '1'
+      COVERAGE_FILE: coverage-unit-${{ matrix.python-version }}-${{ matrix.shardIndex }}
     defaults:
       run:
         shell: bash
     strategy:
+      fail-fast: false
       matrix:
         python-version:
-          - "3.11"
-          - "3.12"
+          - '3.12'
+        shardIndex:
+          - 1
+          - 2
+        shardTotal:
+          - 2
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -39,61 +98,249 @@ jobs:
       - name: Install dependencies
         run: uv sync --project api --dev
 
-      - name: Run dify config tests
-        run: uv run --project api dev/pytest/pytest_config_tests.py
-
-      - name: Set up dotenvs
-        run: |
-          cp docker/.env.example docker/.env
-          cp docker/middleware.env.example docker/middleware.env
-
-      - name: Expose Service Ports
-        run: sh .github/workflows/expose_service_ports.sh
-
-      - name: Set up Sandbox
-        uses: hoverkraft-tech/compose-action@v2
+      - name: Download shared plan
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          compose-file: |
-            docker/docker-compose.middleware.yaml
-          services: |
-            db_postgres
-            redis
-            sandbox
-            ssrf_proxy
+          name: api-unit-plan
 
-      - name: setup test config
+      - name: Run Unit Tests
         run: |
-          cp api/tests/integration_tests/.env.example api/tests/integration_tests/.env
+          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 \
+            -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: Run API Tests
-        env:
-          STORAGE_TYPE: opendal
-          OPENDAL_SCHEME: fs
-          OPENDAL_FS_ROOT: /tmp/dify-storage
+      - 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-${{ 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 (${{ matrix.python-version }})
+    runs-on: depot-ubuntu-24.04-4
+    env:
+      COVERAGE_FILE: coverage-integration-${{ matrix.python-version }}
+      STORAGE_TYPE: opendal
+      OPENDAL_SCHEME: fs
+      OPENDAL_FS_ROOT: /tmp/dify-storage
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - '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: ${{ matrix.python-version }}
+          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 Integration Tests
+        run: |
+          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 \
-            api/tests/test_containers_integration_tests \
-            api/tests/unit_tests
+            api/tests/test_containers_integration_tests
 
-      - name: Coverage Summary
+      - name: Upload integration coverage data
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-coverage-integration-${{ matrix.python-version }}
+          path: ${{ env.COVERAGE_FILE }}
+          if-no-files-found: error
+          retention-days: 1
+
+  api-coverage:
+    name: API Coverage
+    runs-on: depot-ubuntu-24.04
+    needs:
+      - api-unit
+      - api-controllers
+      - api-integration
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      COVERAGE_FILE: .coverage
+    defaults:
+      run:
+        shell: bash
+
+    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'
+
+      - name: Download coverage data
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: coverage-data
+          pattern: api-coverage-*
+          merge-multiple: true
+
+      - name: Combine coverage
         run: |
-          set -x
-          # Extract coverage percentage and create a summary
-          TOTAL_COVERAGE=$(python -c 'import json; print(json.load(open("coverage.json"))["totals"]["percent_covered_display"])')
+          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"))')
 
-          # Create a detailed coverage summary
-          echo "### Test Coverage Summary :test_tube:" >> $GITHUB_STEP_SUMMARY
-          echo "Total Coverage: ${TOTAL_COVERAGE}%" >> $GITHUB_STEP_SUMMARY
-          {
-            echo ""
-            echo "<details><summary>File-level coverage (click to expand)</summary>"
-            echo ""
-            echo '```'
-            uv run --project api coverage report -m
-            echo '```'
-            echo "</details>"
-          } >> $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
+
+          uvx --from "coverage==$coverage_version" coverage combine "${unit_coverage[@]}" "${controller_coverage[@]}" "${integration_coverage[@]}"
+          uvx --from "coverage==$coverage_version" 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
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          files: ./coverage.xml
+          disable_search: true
+          flags: api
+        env:
+          CODECOV_TOKEN: ${{ env.CODECOV_TOKEN }}

.github/workflows/autofix.yml

@@ -1,41 +1,79 @@
 name: autofix.ci
 on:
   pull_request:
-    branches: ["main"]
-  push:
-    branches: ["main"]
+    branches: ['main']
+  merge_group:
+    branches: ['main']
+    types: [checks_requested]
 permissions:
   contents: read
 
 jobs:
   autofix:
     if: github.repository == 'langgenius/dify'
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04-4
     steps:
-      - uses: actions/checkout@v6
+      - name: Complete merge group check
+        if: github.event_name == 'merge_group'
+        run: echo "autofix.ci updates pull request branches, not merge group refs."
+
+      - if: github.event_name != 'merge_group'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Check Docker Compose inputs
+        if: github.event_name != 'merge_group'
         id: docker-compose-changes
-        uses: tj-actions/changed-files@v47
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
         with:
           files: |
             docker/generate_docker_compose
             docker/.env.example
             docker/docker-compose-template.yaml
             docker/docker-compose.yaml
-      - uses: actions/setup-python@v6
+      - name: Check api inputs
+        if: github.event_name != 'merge_group'
+        id: api-changes
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
         with:
-          python-version: "3.11"
+          files: |
+            api/**
+      - name: Check frontend contract inputs
+        if: github.event_name != 'merge_group'
+        id: frontend-contract-changes
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
+        with:
+          files: |
+            api/**
+            packages/contracts/openapi-ts.api.config.ts
+            packages/contracts/package.json
+            packages/contracts/openapi/**
+            pnpm-lock.yaml
+            pnpm-workspace.yaml
+      - name: Check dify-agent inputs
+        if: github.event_name != 'merge_group'
+        id: dify-agent-changes
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
+        with:
+          files: |
+            dify-agent/**/*.py
+            dify-agent/pyproject.toml
+            dify-agent/uv.lock
+      - 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'
 
-      - uses: astral-sh/setup-uv@v7
+      - 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: steps.docker-compose-changes.outputs.any_changed == 'true'
+        if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'
         run: |
           cd docker
           ./generate_docker_compose
 
-      - run: |
+      - if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
+        run: |
           cd api
           uv sync --dev
           # fmt first to avoid line too long
@@ -45,12 +83,19 @@ jobs:
           # Format code
           uv run ruff format ..
 
-      - name: count migration progress
+      - if: github.event_name != 'merge_group' && steps.dify-agent-changes.outputs.any_changed == 'true'
         run: |
-          cd api
-          ./cnt_base.sh
+          cd dify-agent
+          uv sync --dev
+          # fmt first to avoid line too long
+          uv run ruff format .
+          # Fix lint errors
+          uv run ruff check --fix .
+          # Format code
+          uv run ruff format .
 
       - name: ast-grep
+        if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
         run: |
           # ast-grep exits 1 if no matches are found; allow idempotent runs.
           uvx --from ast-grep-cli ast-grep --pattern 'db.session.query($WHATEVER).filter($HERE)' --rewrite 'db.session.query($WHATEVER).where($HERE)' -l py --update-all || true
@@ -79,9 +124,19 @@ jobs:
           find . -name "*.py" -type f -exec sed -i.bak -E 's/"([^"]+)" \| None/Optional["\1"]/g; s/'"'"'([^'"'"']+)'"'"' \| None/Optional['"'"'\1'"'"']/g' {} \;
           find . -name "*.py.bak" -type f -delete
 
-      # mdformat breaks YAML front matter in markdown files. Add --exclude for directories containing YAML front matter.
-      - name: mdformat
-        run: |
-          uvx --python 3.13 mdformat . --exclude ".agents/skills/**"
+      - name: Setup web environment
+        if: github.event_name != 'merge_group' && steps.frontend-contract-changes.outputs.any_changed == 'true'
+        uses: ./.github/actions/setup-web
 
-      - uses: autofix-ci/action@635ffb0c9798bd160680f18fd73371e355b85f27
+      - name: Generate API docs
+        if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
+        run: |
+          cd api
+          uv run dev/generate_swagger_markdown_docs.py --swagger-dir ../packages/contracts/openapi --markdown-dir openapi/markdown --keep-swagger-json
+
+      - name: Generate frontend contracts
+        if: github.event_name != 'merge_group' && steps.frontend-contract-changes.outputs.any_changed == 'true'
+        run: pnpm --dir packages/contracts gen-api-contract
+
+      - if: github.event_name != 'merge_group'
+        uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4

.github/workflows/build-push.yml

@@ -3,14 +3,13 @@ name: Build and Push API & Web
 on:
   push:
     branches:
-      - "main"
-      - "deploy/**"
-      - "build/**"
-      - "release/e-*"
-      - "hotfix/**"
-      - "feat/hitl-backend"
+      - 'main'
+      - 'deploy/**'
+      - 'build/**'
+      - 'release/e-*'
+      - 'hotfix/**'
     tags:
-      - "*"
+      - '*'
 
 concurrency:
   group: build-push-${{ github.head_ref || github.run_id }}
@@ -21,30 +20,75 @@ env:
   DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
   DIFY_WEB_IMAGE_NAME: ${{ vars.DIFY_WEB_IMAGE_NAME || 'langgenius/dify-web' }}
   DIFY_API_IMAGE_NAME: ${{ vars.DIFY_API_IMAGE_NAME || 'langgenius/dify-api' }}
+  DIFY_AGENT_IMAGE_NAME: ${{ vars.DIFY_AGENT_IMAGE_NAME || 'langgenius/dify-agent-backend' }}
+  DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME: ${{ vars.DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME || 'langgenius/dify-agent-local-sandbox' }}
 
 jobs:
   build:
-    runs-on: ${{ matrix.platform == 'linux/arm64' && 'arm64_runner' || 'ubuntu-latest' }}
+    runs-on: ${{ matrix.runs_on }}
     if: github.repository == 'langgenius/dify'
+    permissions:
+      contents: read
+      id-token: write
     strategy:
       matrix:
         include:
-          - service_name: "build-api-amd64"
-            image_name_env: "DIFY_API_IMAGE_NAME"
-            context: "api"
+          - service_name: 'build-api-amd64'
+            image_name_env: 'DIFY_API_IMAGE_NAME'
+            artifact_context: 'api'
+            build_context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
             platform: linux/amd64
-          - service_name: "build-api-arm64"
-            image_name_env: "DIFY_API_IMAGE_NAME"
-            context: "api"
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-api-arm64'
+            image_name_env: 'DIFY_API_IMAGE_NAME'
+            artifact_context: 'api'
+            build_context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
             platform: linux/arm64
-          - service_name: "build-web-amd64"
-            image_name_env: "DIFY_WEB_IMAGE_NAME"
-            context: "web"
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-web-amd64'
+            image_name_env: 'DIFY_WEB_IMAGE_NAME'
+            artifact_context: 'web'
+            build_context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
             platform: linux/amd64
-          - service_name: "build-web-arm64"
-            image_name_env: "DIFY_WEB_IMAGE_NAME"
-            context: "web"
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-web-arm64'
+            image_name_env: 'DIFY_WEB_IMAGE_NAME'
+            artifact_context: 'web'
+            build_context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
             platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-agent-amd64'
+            image_name_env: 'DIFY_AGENT_IMAGE_NAME'
+            artifact_context: 'agent'
+            build_context: '{{defaultContext}}'
+            file: 'dify-agent/Dockerfile'
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-agent-arm64'
+            image_name_env: 'DIFY_AGENT_IMAGE_NAME'
+            artifact_context: 'agent'
+            build_context: '{{defaultContext}}'
+            file: 'dify-agent/Dockerfile'
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-agent-local-sandbox-amd64'
+            image_name_env: 'DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME'
+            artifact_context: 'local-sandbox'
+            build_context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+          - service_name: 'build-agent-local-sandbox-arm64'
+            image_name_env: 'DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME'
+            artifact_context: 'local-sandbox'
+            build_context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
 
     steps:
       - name: Prepare
@@ -53,34 +97,32 @@ jobs:
           echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Set up Depot CLI
+        uses: depot/setup-action@91bc8495a33ebfc504ffc89e5674379ccf23c29c # v1.7.2
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ${{ env[matrix.image_name_env] }}
 
       - name: Build Docker image
         id: build
-        uses: docker/build-push-action@v6
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
         with:
-          context: "{{defaultContext}}:${{ matrix.context }}"
+          project: ${{ vars.DEPOT_PROJECT_ID }}
+          context: ${{ matrix.build_context }}
+          file: ${{ matrix.file }}
           platforms: ${{ matrix.platform }}
           build-args: COMMIT_SHA=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
+          build-contexts: ${{ matrix.build_contexts }}
           labels: ${{ steps.meta.outputs.labels }}
           outputs: type=image,name=${{ env[matrix.image_name_env] }},push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=${{ matrix.service_name }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.service_name }}
 
       - name: Export digest
         env:
@@ -91,43 +133,80 @@ jobs:
           touch "/tmp/digests/${sanitized_digest}"
 
       - name: Upload digest
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: digests-${{ matrix.context }}-${{ env.PLATFORM_PAIR }}
+          name: digests-${{ matrix.artifact_context }}-${{ env.PLATFORM_PAIR }}
           path: /tmp/digests/*
           if-no-files-found: error
           retention-days: 1
 
+  fork-build-validate:
+    if: github.repository != 'langgenius/dify'
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        include:
+          - service_name: 'validate-api-amd64'
+            build_context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'validate-web-amd64'
+            build_context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
+          - service_name: 'validate-agent-amd64'
+            build_context: '{{defaultContext}}'
+            file: 'dify-agent/Dockerfile'
+          - service_name: 'validate-agent-local-sandbox-amd64'
+            build_context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Validate Docker image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          push: false
+          context: ${{ matrix.build_context }}
+          file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
+          platforms: linux/amd64
+
   create-manifest:
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     if: github.repository == 'langgenius/dify'
     strategy:
       matrix:
         include:
-          - service_name: "merge-api-images"
-            image_name_env: "DIFY_API_IMAGE_NAME"
-            context: "api"
-          - service_name: "merge-web-images"
-            image_name_env: "DIFY_WEB_IMAGE_NAME"
-            context: "web"
+          - service_name: 'merge-api-images'
+            image_name_env: 'DIFY_API_IMAGE_NAME'
+            context: 'api'
+          - service_name: 'merge-web-images'
+            image_name_env: 'DIFY_WEB_IMAGE_NAME'
+            context: 'web'
+          - service_name: 'merge-agent-images'
+            image_name_env: 'DIFY_AGENT_IMAGE_NAME'
+            context: 'agent'
+          - service_name: 'merge-agent-local-sandbox-images'
+            image_name_env: 'DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME'
+            context: 'local-sandbox'
     steps:
       - name: Download digests
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           path: /tmp/digests
           pattern: digests-${{ matrix.context }}-*
           merge-multiple: true
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           username: ${{ env.DOCKERHUB_USER }}
           password: ${{ env.DOCKERHUB_TOKEN }}
 
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ${{ env[matrix.image_name_env] }}
           tags: |
@@ -150,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

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

.github/workflows/cli-edge.yml

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

.github/workflows/cli-release.yml

@@ -0,0 +1,152 @@
+name: CLI Release
+
+on:
+  workflow_dispatch:
+    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
+  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]
+
+concurrency:
+  group: difyctl-release
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: validate manifest + resolve target Dify release
+    runs-on: depot-ubuntu-24.04
+    if: github.repository == 'langgenius/dify'
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+    outputs:
+      dify_tag: ${{ steps.resolve.outputs.dify_tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Validate manifest
+        run: node scripts/release-naming.mjs validate
+
+      - name: Resolve target Dify release
+        id: resolve
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_TAG: ${{ github.event.release.tag_name }}
+          INPUT_TAG: ${{ inputs.release_tag }}
+        run: |
+          if [ -n "$EVENT_TAG" ]; then
+              tag="$EVENT_TAG"
+          elif [ -n "$INPUT_TAG" ]; then
+              tag="$INPUT_TAG"
+          else
+              tag="$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq .tag_name)"
+          fi
+          if [ -z "$tag" ]; then
+              echo "::error::could not resolve a target Dify release tag"
+              exit 1
+          fi
+          if ! gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+              echo "::error::target Dify release ${tag} not found"
+              exit 1
+          fi
+          echo "dify_tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "::notice::target Dify release ${tag}"
+
+      - name: Compatibility check
+        env:
+          DIFY_TAG: ${{ steps.resolve.outputs.dify_tag }}
+        run: node scripts/release-naming.mjs compat-check "$DIFY_TAG"
+
+  release:
+    name: build + attach standalone binaries (all targets)
+    needs: validate
+    runs-on: depot-ubuntu-24.04
+    permissions:
+      contents: write
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+    env:
+      DIFY_TAG: ${{ needs.validate.outputs.dify_tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 1
+
+      - name: Enable cross-arch native prebuilds
+        working-directory: ./
+        run: cat cli/scripts/cross-arch.pnpm.yaml >> pnpm-workspace.yaml
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Export manifest to env
+        run: node scripts/release-naming.mjs github-env >> "$GITHUB_ENV"
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version-file: cli/.bun-version
+
+      - name: Compile standalone binaries (all targets)
+        run: |
+          CLI_VERSION="$version" \
+          DIFYCTL_COMMIT="$(git rev-parse HEAD)" \
+          DIFYCTL_BUILD_DATE="$(git log -1 --format=%cI HEAD)" \
+            pnpm build:bin
+
+      - name: Generate sha256 checksum file
+        run: scripts/release-write-checksums.sh
+
+      - name: Attach difyctl assets to Dify release
+        if: ${{ !inputs.dry_run }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "$DIFY_TAG" dist/bin/${tagPrefix}* \
+              --repo "$GITHUB_REPOSITORY" --clobber
+
+      - name: Prune stale difyctl assets
+        if: ${{ !inputs.dry_run }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          new_set="$(cd dist/bin && ls ${tagPrefix}*)"
+          gh release view "$DIFY_TAG" --repo "$GITHUB_REPOSITORY" \
+              --json assets --jq '.assets[].name' \
+            | { grep -E "^${tagPrefix}" || true; } \
+            | while IFS= read -r name; do
+                if ! printf '%s\n' "$new_set" | grep -qxF -- "$name"; then
+                    echo "::notice::pruning stale asset ${name}"
+                    gh release delete-asset "$DIFY_TAG" "$name" \
+                        --repo "$GITHUB_REPOSITORY" --yes
+                fi
+              done

.github/workflows/cli-smoke.yml

@@ -0,0 +1,60 @@
+name: CLI Smoke (live dify)
+
+on:
+  workflow_dispatch:
+    inputs:
+      dify_version:
+        description: 'Dify image tag to test against (e.g. 1.7.0)'
+        type: string
+        required: true
+      cli_ref:
+        description: 'Git ref to build the cli from (default: current branch)'
+        type: string
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout cli ref
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.cli_ref || github.ref }}
+          persist-credentials: false
+
+      - name: Setup web environment
+        uses: ./.github/actions/setup-web
+
+      - name: Bring up dify
+        env:
+          DIFY_VERSION: ${{ inputs.dify_version }}
+        run: |
+          cd docker
+          cp .env.example .env
+          DIFY_API_IMAGE_TAG="$DIFY_VERSION" \
+          DIFY_WEB_IMAGE_TAG="$DIFY_VERSION" \
+          docker compose up -d api worker web db redis
+          for i in $(seq 1 60); do
+              if curl -fsS http://localhost:5001/health >/dev/null 2>&1; then
+                  echo "dify api ready after ${i}s"
+                  break
+              fi
+              sleep 1
+          done
+
+      - name: Run smoke against live dify
+        working-directory: ./cli
+        run: pnpm exec node scripts/run-smoke.ts --base-url http://localhost:5001
+
+      - name: Dump dify logs on failure
+        if: failure()
+        run: |
+          cd docker
+          docker compose logs api worker web --tail=200

.github/workflows/cli-tests.yml

@@ -0,0 +1,59 @@
+name: CLI Tests
+
+on:
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cli-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: CLI Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [depot-ubuntu-24.04, windows-latest, macos-latest]
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./cli
+
+    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: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Validate release manifest
+        if: matrix.os == 'depot-ubuntu-24.04'
+        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@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          directory: cli/coverage
+          flags: cli
+        env:
+          CODECOV_TOKEN: ${{ env.CODECOV_TOKEN }}

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

@@ -9,20 +9,20 @@ concurrency:
 
 jobs:
   db-migration-test-postgres:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -37,10 +37,10 @@ jobs:
       - name: Prepare middleware env
         run: |
           cd docker
-          cp middleware.env.example middleware.env
+          cp envs/middleware.env.example middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@v2.0.2
+        uses: hoverkraft-tech/compose-action@b659c744ee9bed25aea2307c017ad849bd104433 # v3.2.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -59,20 +59,20 @@ jobs:
         run: uv run --directory api flask upgrade-db
 
   db-migration-test-mysql:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
-          python-version: "3.12"
+          python-version: '3.12'
           cache-dependency-glob: api/uv.lock
 
       - name: Install dependencies
@@ -87,14 +87,14 @@ jobs:
       - name: Prepare middleware env for MySQL
         run: |
           cd docker
-          cp middleware.env.example middleware.env
+          cp envs/middleware.env.example middleware.env
           sed -i 's/DB_TYPE=postgresql/DB_TYPE=mysql/' middleware.env
           sed -i 's/DB_HOST=db_postgres/DB_HOST=db_mysql/' middleware.env
           sed -i 's/DB_PORT=5432/DB_PORT=3306/' middleware.env
           sed -i 's/DB_USERNAME=postgres/DB_USERNAME=mysql/' middleware.env
 
       - name: Set up Middlewares
-        uses: hoverkraft-tech/compose-action@v2.0.2
+        uses: hoverkraft-tech/compose-action@b659c744ee9bed25aea2307c017ad849bd104433 # v3.2.0
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml
@@ -110,6 +110,28 @@ jobs:
           sed -i 's/DB_PORT=5432/DB_PORT=3306/' .env
           sed -i 's/DB_USERNAME=postgres/DB_USERNAME=root/' .env
 
+      # hoverkraft-tech/compose-action@v2.6.0 only waits for `docker compose up -d`
+      # to return (container processes started); it does not wait on healthcheck
+      # status. mysql:8.0's first-time init takes 15-30s, so without an explicit
+      # wait the migration runs while InnoDB is still initialising and gets
+      # killed with "Lost connection during query". Poll a real SELECT until it
+      # succeeds.
+      - name: Wait for MySQL to accept queries
+        run: |
+          set +e
+          for i in $(seq 1 60); do
+            if docker run --rm --network host mysql:8.0 \
+                mysql -h 127.0.0.1 -P 3306 -uroot -pdifyai123456 \
+                -e 'SELECT 1' >/dev/null 2>&1; then
+              echo "MySQL ready after ${i}s"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "MySQL not ready after 60s; dumping container logs:"
+          docker compose -f docker/docker-compose.middleware.yaml --profile mysql logs --tail=200 db_mysql
+          exit 1
+
       - name: Run DB Migration
         env:
           DEBUG: true

.github/workflows/deploy-agent-dev.yml

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

.github/workflows/deploy-agent.yml

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

.github/workflows/deploy-dev.yml

@@ -2,21 +2,21 @@ name: Deploy Dev
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ['Build and Push API & Web']
     branches:
-      - "deploy/dev"
+      - 'deploy/dev'
     types:
       - completed
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     if: |
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.head_branch == 'deploy/dev'
     steps:
       - name: Deploy to server
-        uses: appleboy/ssh-action@v1
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
         with:
           host: ${{ secrets.SSH_HOST }}
           username: ${{ secrets.SSH_USER }}

.github/workflows/deploy-enterprise.yml

@@ -5,15 +5,15 @@ permissions:
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ['Build and Push API & Web']
     branches:
-      - "deploy/enterprise"
+      - 'deploy/enterprise'
     types:
       - completed
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     if: |
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.head_branch == 'deploy/enterprise'

.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-hitl.yml

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

.github/workflows/deploy-knowledge.yml

@@ -0,0 +1,78 @@
+name: Deploy Knowledge
+
+permissions:
+  actions: read
+  contents: read
+
+on:
+  workflow_run:
+    workflows: ['Build and Push API & Web']
+    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_repository.full_name == github.repository
+    steps:
+      - 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: |
+            await require('./.github/scripts/knowledge-deploy-gates.cjs')({ github, context, core });
+
+      - 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: |
+            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/deploy-saas.yml

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

.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

@@ -3,10 +3,21 @@ name: Build docker image
 on:
   pull_request:
     branches:
-      - "main"
+      - 'main'
     paths:
       - api/Dockerfile
+      - api/Dockerfile.dockerignore
+      - api/pyproject.toml
+      - api/uv.lock
+      - dify-agent/pyproject.toml
+      - dify-agent/README.md
+      - dify-agent/src/**
       - web/Dockerfile
+      - dify-agent-runtime/docker/Dockerfile
+      - dify-agent-runtime/go.mod
+      - dify-agent-runtime/go.sum
+      - dify-agent-runtime/cmd/**
+      - dify-agent-runtime/internal/**
 
 concurrency:
   group: docker-build-${{ github.head_ref || github.run_id }}
@@ -14,35 +25,84 @@ concurrency:
 
 jobs:
   build-docker:
-    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ${{ matrix.runs_on }}
+    permissions:
+      contents: read
+      id-token: write
     strategy:
       matrix:
         include:
-          - service_name: "api-amd64"
+          - service_name: 'api-amd64'
             platform: linux/amd64
-            context: "api"
-          - service_name: "api-arm64"
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'api-arm64'
             platform: linux/arm64
-            context: "api"
-          - service_name: "web-amd64"
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'web-amd64'
             platform: linux/amd64
-            context: "web"
-          - service_name: "web-arm64"
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
+          - service_name: 'web-arm64'
             platform: linux/arm64
-            context: "web"
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
+          - service_name: 'local-sandbox-amd64'
+            platform: linux/amd64
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
+          - service_name: 'local-sandbox-arm64'
+            platform: linux/arm64
+            runs_on: depot-ubuntu-24.04-4
+            context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
     steps:
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Set up Depot CLI
+        uses: depot/setup-action@91bc8495a33ebfc504ffc89e5674379ccf23c29c # v1.7.2
 
       - name: Build Docker Image
-        uses: docker/build-push-action@v6
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
+        with:
+          project: ${{ vars.DEPOT_PROJECT_ID }}
+          push: false
+          context: ${{ matrix.context }}
+          file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
+          platforms: ${{ matrix.platform }}
+
+  build-docker-fork:
+    if: github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        include:
+          - service_name: 'api-amd64'
+            context: '{{defaultContext}}'
+            file: 'api/Dockerfile'
+          - service_name: 'web-amd64'
+            context: '{{defaultContext}}'
+            file: 'web/Dockerfile'
+          - service_name: 'local-sandbox-amd64'
+            context: '{{defaultContext}}:dify-agent-runtime'
+            file: 'docker/Dockerfile'
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Build Docker Image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           push: false
-          context: "{{defaultContext}}:${{ matrix.context }}"
-          file: "${{ matrix.file }}"
-          platforms: ${{ matrix.platform }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          context: ${{ matrix.context }}
+          file: ${{ matrix.file }}
+          build-contexts: ${{ matrix.build_contexts }}
+          platforms: linux/amd64

.github/workflows/expose_service_ports.sh

@@ -1,17 +0,0 @@
-#!/bin/bash
-
-yq eval '.services.weaviate.ports += ["8080:8080"]' -i docker/docker-compose.yaml
-yq eval '.services.weaviate.ports += ["50051:50051"]' -i docker/docker-compose.yaml
-yq eval '.services.qdrant.ports += ["6333:6333"]' -i docker/docker-compose.yaml
-yq eval '.services.chroma.ports += ["8000:8000"]' -i docker/docker-compose.yaml
-yq eval '.services["milvus-standalone"].ports += ["19530:19530"]' -i docker/docker-compose.yaml
-yq eval '.services.pgvector.ports += ["5433:5432"]' -i docker/docker-compose.yaml
-yq eval '.services["pgvecto-rs"].ports += ["5431:5432"]' -i docker/docker-compose.yaml
-yq eval '.services["elasticsearch"].ports += ["9200:9200"]' -i docker/docker-compose.yaml
-yq eval '.services.couchbase-server.ports += ["8091-8096:8091-8096"]' -i docker/docker-compose.yaml
-yq eval '.services.couchbase-server.ports += ["11210:11210"]' -i docker/docker-compose.yaml
-yq eval '.services.tidb.ports += ["4000:4000"]' -i docker/tidb/docker-compose.yaml
-yq eval '.services.oceanbase.ports += ["2881:2881"]' -i docker/docker-compose.yaml
-yq eval '.services.opengauss.ports += ["6600:6600"]' -i docker/docker-compose.yaml
-
-echo "Ports exposed for sandbox, weaviate (HTTP 8080, gRPC 50051), tidb, qdrant, chroma, milvus, pgvector, pgvecto-rs, elasticsearch, couchbase, opengauss"

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

@@ -0,0 +1,49 @@
+name: Hotfix Cherry-Pick Provenance
+
+on:
+  pull_request:
+    branches:
+      - 'hotfix/**'
+      - 'lts/**'
+    types:
+      - opened
+      - edited
+      - reopened
+      - ready_for_review
+      - synchronize
+
+permissions:
+  contents: read
+
+concurrency:
+  group: hotfix-cherry-pick-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-cherry-pick-provenance:
+    name: Require cherry-pick provenance
+    runs-on: depot-ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Fetch PR base, PR head, and main
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          git fetch --no-tags --prune origin \
+            "+refs/heads/main:refs/remotes/origin/main" \
+            "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}" \
+            "+refs/pull/${PR_NUMBER}/head:refs/remotes/pull/${PR_NUMBER}/head"
+
+      - name: Load checker from main
+        run: git show origin/main:.github/scripts/check-hotfix-cherry-picks.sh > "$RUNNER_TEMP/check-hotfix-cherry-picks.sh"
+
+      - name: Check PR commits
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          MAIN_REF: origin/main
+        run: bash "$RUNNER_TEMP/check-hotfix-cherry-picks.sh"

.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"