Merge branch 'main' into feat/migrate-es-toolkit-compat-simple

.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "enabledPlugins": {
+    "feature-dev@claude-plugins-official": true,
+    "context7@claude-plugins-official": true,
+    "typescript-lsp@claude-plugins-official": true,
+    "pyright-lsp@claude-plugins-official": true
+  }
+}

.claude/settings.json.example

@@ -1,19 +0,0 @@
-{
-    "permissions": {
-      "allow": [],
-      "deny": []
-    },
-    "env": {
-      "__comment": "Environment variables for MCP servers. Override in .claude/settings.local.json with actual values.",
-      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-    },
-    "enabledMcpjsonServers": [
-      "context7",
-      "sequential-thinking",
-      "github",
-      "fetch",
-      "playwright",
-      "ide"
-    ],
-    "enableAllProjectMcpServers": true
-  }

.github/workflows/api-tests.yml

@@ -22,12 +22,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
@@ -57,7 +57,7 @@ jobs:
         run: sh .github/workflows/expose_service_ports.sh
 
       - name: Set up Sandbox
-        uses: hoverkraft-tech/compose-action@v2.0.2
+        uses: hoverkraft-tech/compose-action@v2
         with:
           compose-file: |
             docker/docker-compose.middleware.yaml

.github/workflows/autofix.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'langgenius/dify'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Check Docker Compose inputs
         id: docker-compose-changes
@@ -27,7 +27,7 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@v7
 
       - name: Generate Docker Compose
         if: steps.docker-compose-changes.outputs.any_changed == 'true'

.github/workflows/build-push.yml

@@ -90,7 +90,7 @@ jobs:
           touch "/tmp/digests/${sanitized_digest}"
 
       - name: Upload digest
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: digests-${{ matrix.context }}-${{ env.PLATFORM_PAIR }}
           path: /tmp/digests/*

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

@@ -13,13 +13,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
           python-version: "3.12"
@@ -63,13 +63,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
           python-version: "3.12"

.github/workflows/main-ci.yml

@@ -27,7 +27,7 @@ jobs:
       vdb-changed: ${{ steps.changes.outputs.vdb }}
       migration-changed: ${{ steps.changes.outputs.migration }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
         id: changes
         with:
@@ -38,6 +38,7 @@ jobs:
               - '.github/workflows/api-tests.yml'
             web:
               - 'web/**'
+              - '.github/workflows/web-tests.yml'
             vdb:
               - 'api/core/rag/datasource/**'
               - 'docker/**'

.github/workflows/style.yml

@@ -19,13 +19,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: Check changed files
         id: changed-files
-        uses: tj-actions/changed-files@v46
+        uses: tj-actions/changed-files@v47
         with:
           files: |
             api/**
@@ -33,7 +33,7 @@ jobs:
 
       - name: Setup UV and Python
         if: steps.changed-files.outputs.any_changed == 'true'
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: false
           python-version: "3.12"
@@ -68,15 +68,17 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: Check changed files
         id: changed-files
-        uses: tj-actions/changed-files@v46
+        uses: tj-actions/changed-files@v47
         with:
-          files: web/**
+          files: |
+            web/**
+            .github/workflows/style.yml
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -85,7 +87,7 @@ jobs:
           run_install: false
 
       - name: Setup NodeJS
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         if: steps.changed-files.outputs.any_changed == 'true'
         with:
           node-version: 22
@@ -114,14 +116,14 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Check changed files
         id: changed-files
-        uses: tj-actions/changed-files@v46
+        uses: tj-actions/changed-files@v47
         with:
           files: |
             **.sh

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

@@ -25,12 +25,12 @@ jobs:
         working-directory: sdks/nodejs-client
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
           cache: ''

.github/workflows/translate-i18n-base-on-english.yml

@@ -18,7 +18,7 @@ jobs:
       run:
         working-directory: web
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -51,7 +51,7 @@ jobs:
 
       - name: Set up Node.js
         if: env.FILES_CHANGED == 'true'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 'lts/*'
           cache: pnpm

.github/workflows/vdb-tests.yml

@@ -19,19 +19,19 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: Free Disk Space
-        uses: endersonmenezes/free-disk-space@v2
+        uses: endersonmenezes/free-disk-space@v3
         with:
           remove_dotnet: true
           remove_haskell: true
           remove_tool_cache: true
 
       - name: Setup UV and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}

.github/workflows/web-tests.yml

@@ -18,7 +18,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
@@ -29,7 +29,7 @@ jobs:
           run_install: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: pnpm
@@ -360,7 +360,7 @@ jobs:
 
       - name: Upload Coverage Artifact
         if: steps.coverage-summary.outputs.has_coverage == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: web-coverage-report
           path: web/coverage

.mcp.json

@@ -1,34 +0,0 @@
-{
-    "mcpServers": {
-      "context7": {
-        "type": "http",
-        "url": "https://mcp.context7.com/mcp"
-      },
-      "sequential-thinking": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-        "env": {}
-      },
-      "github": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@modelcontextprotocol/server-github"],
-        "env": {
-          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
-        }
-      },
-      "fetch": {
-        "type": "stdio",
-        "command": "uvx",
-        "args": ["mcp-server-fetch"],
-        "env": {}
-      },
-      "playwright": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@playwright/mcp@latest"],
-        "env": {}
-      }
-    }
-  }

api/core/app/apps/base_app_queue_manager.py

@@ -90,6 +90,7 @@ class AppQueueManager:
         """
         self._clear_task_belong_cache()
         self._q.put(None)
+        self._graph_runtime_state = None  # Release reference to allow GC to reclaim memory
 
     def _clear_task_belong_cache(self) -> None:
         """

api/core/mcp/client/streamable_client.py

@@ -313,17 +313,20 @@ class StreamableHTTPTransport:
             if is_initialization:
                 self._maybe_extract_session_id_from_response(response)
 
-            content_type = cast(str, response.headers.get(CONTENT_TYPE, "").lower())
+            # Per https://modelcontextprotocol.io/specification/2025-06-18/basic#notifications:
+            # The server MUST NOT send a response to notifications.
+            if isinstance(message.root, JSONRPCRequest):
+                content_type = cast(str, response.headers.get(CONTENT_TYPE, "").lower())
 
-            if content_type.startswith(JSON):
-                self._handle_json_response(response, ctx.server_to_client_queue)
-            elif content_type.startswith(SSE):
-                self._handle_sse_response(response, ctx)
-            else:
-                self._handle_unexpected_content_type(
-                    content_type,
-                    ctx.server_to_client_queue,
-                )
+                if content_type.startswith(JSON):
+                    self._handle_json_response(response, ctx.server_to_client_queue)
+                elif content_type.startswith(SSE):
+                    self._handle_sse_response(response, ctx)
+                else:
+                    self._handle_unexpected_content_type(
+                        content_type,
+                        ctx.server_to_client_queue,
+                    )
 
     def _handle_json_response(
         self,

api/core/tools/mcp_tool/tool.py

@@ -6,7 +6,15 @@ from typing import Any
 
 from core.mcp.auth_client import MCPClientWithAuthRetry
 from core.mcp.error import MCPConnectionError
-from core.mcp.types import AudioContent, CallToolResult, ImageContent, TextContent
+from core.mcp.types import (
+    AudioContent,
+    BlobResourceContents,
+    CallToolResult,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+    TextResourceContents,
+)
 from core.tools.__base.tool import Tool
 from core.tools.__base.tool_runtime import ToolRuntime
 from core.tools.entities.tool_entities import ToolEntity, ToolInvokeMessage, ToolProviderType
@@ -53,10 +61,19 @@ class MCPTool(Tool):
         for content in result.content:
             if isinstance(content, TextContent):
                 yield from self._process_text_content(content)
-            elif isinstance(content, ImageContent):
-                yield self._process_image_content(content)
-            elif isinstance(content, AudioContent):
-                yield self._process_audio_content(content)
+            elif isinstance(content, ImageContent | AudioContent):
+                yield self.create_blob_message(
+                    blob=base64.b64decode(content.data), meta={"mime_type": content.mimeType}
+                )
+            elif isinstance(content, EmbeddedResource):
+                resource = content.resource
+                if isinstance(resource, TextResourceContents):
+                    yield self.create_text_message(resource.text)
+                elif isinstance(resource, BlobResourceContents):
+                    mime_type = resource.mimeType or "application/octet-stream"
+                    yield self.create_blob_message(blob=base64.b64decode(resource.blob), meta={"mime_type": mime_type})
+                else:
+                    raise ToolInvokeError(f"Unsupported embedded resource type: {type(resource)}")
             else:
                 logger.warning("Unsupported content type=%s", type(content))
 
@@ -101,14 +118,6 @@ class MCPTool(Tool):
         for item in json_list:
             yield self.create_json_message(item)
 
-    def _process_image_content(self, content: ImageContent) -> ToolInvokeMessage:
-        """Process image content and return a blob message."""
-        return self.create_blob_message(blob=base64.b64decode(content.data), meta={"mime_type": content.mimeType})
-
-    def _process_audio_content(self, content: AudioContent) -> ToolInvokeMessage:
-        """Process audio content and return a blob message."""
-        return self.create_blob_message(blob=base64.b64decode(content.data), meta={"mime_type": content.mimeType})
-
     def fork_tool_runtime(self, runtime: ToolRuntime) -> "MCPTool":
         return MCPTool(
             entity=self.entity,

api/services/app_generate_service.py

@@ -14,7 +14,8 @@ from enums.quota_type import QuotaType, unlimited
 from extensions.otel import AppGenerateHandler, trace_span
 from models.model import Account, App, AppMode, EndUser
 from models.workflow import Workflow
-from services.errors.app import InvokeRateLimitError, QuotaExceededError, WorkflowIdFormatError, WorkflowNotFoundError
+from services.errors.app import QuotaExceededError, WorkflowIdFormatError, WorkflowNotFoundError
+from services.errors.llm import InvokeRateLimitError
 from services.workflow_service import WorkflowService
 
 

api/services/async_workflow_service.py

@@ -21,7 +21,7 @@ from models.model import App, EndUser
 from models.trigger import WorkflowTriggerLog
 from models.workflow import Workflow
 from repositories.sqlalchemy_workflow_trigger_log_repository import SQLAlchemyWorkflowTriggerLogRepository
-from services.errors.app import InvokeRateLimitError, QuotaExceededError, WorkflowNotFoundError
+from services.errors.app import QuotaExceededError, WorkflowNotFoundError, WorkflowQuotaLimitError
 from services.workflow.entities import AsyncTriggerResponse, TriggerData, WorkflowTaskData
 from services.workflow.queue_dispatcher import QueueDispatcherManager, QueuePriority
 from services.workflow_service import WorkflowService
@@ -141,7 +141,7 @@ class AsyncWorkflowService:
             trigger_log_repo.update(trigger_log)
             session.commit()
 
-            raise InvokeRateLimitError(
+            raise WorkflowQuotaLimitError(
                 f"Workflow execution quota limit reached for tenant {trigger_data.tenant_id}"
             ) from e
 

api/services/errors/app.py

@@ -18,8 +18,8 @@ class WorkflowIdFormatError(Exception):
     pass
 
 
-class InvokeRateLimitError(Exception):
-    """Raised when rate limit is exceeded for workflow invocations."""
+class WorkflowQuotaLimitError(Exception):
+    """Raised when workflow execution quota is exceeded (for async/background workflows)."""
 
     pass
 

api/services/plugin/plugin_parameter_service.py

@@ -146,7 +146,7 @@ class PluginParameterService:
                 provider,
                 action,
                 resolved_credentials,
-                CredentialType.API_KEY.value,
+                original_subscription.credential_type or CredentialType.UNAUTHORIZED.value,
                 parameter,
             )
             .options

api/services/trigger/trigger_provider_service.py

@@ -868,48 +868,111 @@ class TriggerProviderService:
         if not provider_controller:
             raise ValueError(f"Provider {provider_id} not found")
 
-        subscription = TriggerProviderService.get_subscription_by_id(
-            tenant_id=tenant_id,
-            subscription_id=subscription_id,
-        )
-        if not subscription:
-            raise ValueError(f"Subscription {subscription_id} not found")
+        # Use distributed lock to prevent race conditions on the same subscription
+        lock_key = f"trigger_subscription_rebuild_lock:{tenant_id}_{subscription_id}"
+        with redis_client.lock(lock_key, timeout=20):
+            with Session(db.engine, expire_on_commit=False) as session:
+                try:
+                    # Get subscription within the transaction
+                    subscription: TriggerSubscription | None = (
+                        session.query(TriggerSubscription).filter_by(tenant_id=tenant_id, id=subscription_id).first()
+                    )
+                    if not subscription:
+                        raise ValueError(f"Subscription {subscription_id} not found")
 
-        credential_type = CredentialType.of(subscription.credential_type)
-        if credential_type not in [CredentialType.OAUTH2, CredentialType.API_KEY]:
-            raise ValueError("Credential type not supported for rebuild")
+                    credential_type = CredentialType.of(subscription.credential_type)
+                    if credential_type not in [CredentialType.OAUTH2, CredentialType.API_KEY]:
+                        raise ValueError("Credential type not supported for rebuild")
 
-        # TODO: Trying to invoke update api of the plugin trigger provider
+                    # Decrypt existing credentials for merging
+                    credential_encrypter, _ = create_trigger_provider_encrypter_for_subscription(
+                        tenant_id=tenant_id,
+                        controller=provider_controller,
+                        subscription=subscription,
+                    )
+                    decrypted_credentials = dict(credential_encrypter.decrypt(subscription.credentials))
 
-        # FALLBACK: If the update api is not implemented, delete the previous subscription and create a new one
+                    # Merge credentials: if caller passed HIDDEN_VALUE, retain existing decrypted value
+                    merged_credentials: dict[str, Any] = {
+                        key: value if value != HIDDEN_VALUE else decrypted_credentials.get(key, UNKNOWN_VALUE)
+                        for key, value in credentials.items()
+                    }
 
-        # Delete the previous subscription
-        user_id = subscription.user_id
-        TriggerManager.unsubscribe_trigger(
-            tenant_id=tenant_id,
-            user_id=user_id,
-            provider_id=provider_id,
-            subscription=subscription.to_entity(),
-            credentials=subscription.credentials,
-            credential_type=credential_type,
-        )
+                    user_id = subscription.user_id
 
-        # Create a new subscription with the same subscription_id and endpoint_id
-        new_subscription: TriggerSubscriptionEntity = TriggerManager.subscribe_trigger(
-            tenant_id=tenant_id,
-            user_id=user_id,
-            provider_id=provider_id,
-            endpoint=generate_plugin_trigger_endpoint_url(subscription.endpoint_id),
-            parameters=parameters,
-            credentials=credentials,
-            credential_type=credential_type,
-        )
-        TriggerProviderService.update_trigger_subscription(
-            tenant_id=tenant_id,
-            subscription_id=subscription.id,
-            name=name,
-            parameters=parameters,
-            credentials=credentials,
-            properties=new_subscription.properties,
-            expires_at=new_subscription.expires_at,
-        )
+                    # TODO: Trying to invoke update api of the plugin trigger provider
+
+                    # FALLBACK: If the update api is not implemented,
+                    # delete the previous subscription and create a new one
+
+                    # Unsubscribe the previous subscription (external call, but we'll handle errors)
+                    try:
+                        TriggerManager.unsubscribe_trigger(
+                            tenant_id=tenant_id,
+                            user_id=user_id,
+                            provider_id=provider_id,
+                            subscription=subscription.to_entity(),
+                            credentials=decrypted_credentials,
+                            credential_type=credential_type,
+                        )
+                    except Exception as e:
+                        logger.exception("Error unsubscribing trigger during rebuild", exc_info=e)
+                        # Continue anyway - the subscription might already be deleted externally
+
+                    # Create a new subscription with the same subscription_id and endpoint_id (external call)
+                    new_subscription: TriggerSubscriptionEntity = TriggerManager.subscribe_trigger(
+                        tenant_id=tenant_id,
+                        user_id=user_id,
+                        provider_id=provider_id,
+                        endpoint=generate_plugin_trigger_endpoint_url(subscription.endpoint_id),
+                        parameters=parameters,
+                        credentials=merged_credentials,
+                        credential_type=credential_type,
+                    )
+
+                    # Update the subscription in the same transaction
+                    # Inline update logic to reuse the same session
+                    if name is not None and name != subscription.name:
+                        existing = (
+                            session.query(TriggerSubscription)
+                            .filter_by(tenant_id=tenant_id, provider_id=str(provider_id), name=name)
+                            .first()
+                        )
+                        if existing and existing.id != subscription.id:
+                            raise ValueError(f"Subscription name '{name}' already exists for this provider")
+                        subscription.name = name
+
+                    # Update parameters
+                    subscription.parameters = dict(parameters)
+
+                    # Update credentials with merged (and encrypted) values
+                    subscription.credentials = dict(credential_encrypter.encrypt(merged_credentials))
+
+                    # Update properties
+                    if new_subscription.properties:
+                        properties_encrypter, _ = create_provider_encrypter(
+                            tenant_id=tenant_id,
+                            config=provider_controller.get_properties_schema(),
+                            cache=NoOpProviderCredentialCache(),
+                        )
+                        subscription.properties = dict(properties_encrypter.encrypt(dict(new_subscription.properties)))
+
+                    # Update expiration timestamp
+                    if new_subscription.expires_at is not None:
+                        subscription.expires_at = new_subscription.expires_at
+
+                    # Commit the transaction
+                    session.commit()
+
+                    # Clear subscription cache
+                    delete_cache_for_subscription(
+                        tenant_id=tenant_id,
+                        provider_id=subscription.provider_id,
+                        subscription_id=subscription.id,
+                    )
+
+                except Exception as e:
+                    # Rollback on any error
+                    session.rollback()
+                    logger.exception("Failed to rebuild trigger subscription", exc_info=e)
+                    raise

api/services/trigger/webhook_service.py

@@ -863,10 +863,18 @@ class WebhookService:
                 not_found_in_cache.append(node_id)
                 continue
 
-        with Session(db.engine) as session:
-            try:
-                # lock the concurrent webhook trigger creation
-                redis_client.lock(f"{cls.__WEBHOOK_NODE_CACHE_KEY__}:apps:{app.id}:lock", timeout=10)
+        lock_key = f"{cls.__WEBHOOK_NODE_CACHE_KEY__}:apps:{app.id}:lock"
+        lock = redis_client.lock(lock_key, timeout=10)
+        lock_acquired = False
+
+        try:
+            # acquire the lock with blocking and timeout
+            lock_acquired = lock.acquire(blocking=True, blocking_timeout=10)
+            if not lock_acquired:
+                logger.warning("Failed to acquire lock for webhook sync, app %s", app.id)
+                raise RuntimeError("Failed to acquire lock for webhook trigger synchronization")
+
+            with Session(db.engine) as session:
                 # fetch the non-cached nodes from DB
                 all_records = session.scalars(
                     select(WorkflowWebhookTrigger).where(
@@ -903,11 +911,16 @@ class WebhookService:
                         session.delete(nodes_id_in_db[node_id])
                         redis_client.delete(f"{cls.__WEBHOOK_NODE_CACHE_KEY__}:{app.id}:{node_id}")
                 session.commit()
-            except Exception:
-                logger.exception("Failed to sync webhook relationships for app %s", app.id)
-                raise
-            finally:
-                redis_client.delete(f"{cls.__WEBHOOK_NODE_CACHE_KEY__}:apps:{app.id}:lock")
+        except Exception:
+            logger.exception("Failed to sync webhook relationships for app %s", app.id)
+            raise
+        finally:
+            # release the lock only if it was acquired
+            if lock_acquired:
+                try:
+                    lock.release()
+                except Exception:
+                    logger.exception("Failed to release lock for webhook sync, app %s", app.id)
 
     @classmethod
     def generate_webhook_id(cls) -> str:

api/tests/test_containers_integration_tests/services/test_trigger_provider_service.py

@@ -0,0 +1,682 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+from faker import Faker
+
+from constants import HIDDEN_VALUE, UNKNOWN_VALUE
+from core.plugin.entities.plugin_daemon import CredentialType
+from core.trigger.entities.entities import Subscription as TriggerSubscriptionEntity
+from extensions.ext_database import db
+from models.provider_ids import TriggerProviderID
+from models.trigger import TriggerSubscription
+from services.trigger.trigger_provider_service import TriggerProviderService
+
+
+class TestTriggerProviderService:
+    """Integration tests for TriggerProviderService using testcontainers."""
+
+    @pytest.fixture
+    def mock_external_service_dependencies(self):
+        """Mock setup for external service dependencies."""
+        with (
+            patch("services.trigger.trigger_provider_service.TriggerManager") as mock_trigger_manager,
+            patch("services.trigger.trigger_provider_service.redis_client") as mock_redis_client,
+            patch("services.trigger.trigger_provider_service.delete_cache_for_subscription") as mock_delete_cache,
+            patch("services.account_service.FeatureService") as mock_account_feature_service,
+        ):
+            # Setup default mock returns
+            mock_provider_controller = MagicMock()
+            mock_provider_controller.get_credential_schema_config.return_value = MagicMock()
+            mock_provider_controller.get_properties_schema.return_value = MagicMock()
+            mock_trigger_manager.get_trigger_provider.return_value = mock_provider_controller
+
+            # Mock redis lock
+            mock_lock = MagicMock()
+            mock_lock.__enter__ = MagicMock(return_value=None)
+            mock_lock.__exit__ = MagicMock(return_value=None)
+            mock_redis_client.lock.return_value = mock_lock
+
+            # Setup account feature service mock
+            mock_account_feature_service.get_system_features.return_value.is_allow_register = True
+
+            yield {
+                "trigger_manager": mock_trigger_manager,
+                "redis_client": mock_redis_client,
+                "delete_cache": mock_delete_cache,
+                "provider_controller": mock_provider_controller,
+                "account_feature_service": mock_account_feature_service,
+            }
+
+    def _create_test_account_and_tenant(self, db_session_with_containers, mock_external_service_dependencies):
+        """
+        Helper method to create a test account and tenant for testing.
+
+        Args:
+            db_session_with_containers: Database session from testcontainers infrastructure
+            mock_external_service_dependencies: Mock dependencies
+
+        Returns:
+            tuple: (account, tenant) - Created account and tenant instances
+        """
+        fake = Faker()
+
+        from services.account_service import AccountService, TenantService
+
+        # Setup mocks for account creation
+        mock_external_service_dependencies[
+            "account_feature_service"
+        ].get_system_features.return_value.is_allow_register = True
+        mock_external_service_dependencies[
+            "trigger_manager"
+        ].get_trigger_provider.return_value = mock_external_service_dependencies["provider_controller"]
+
+        # Create account and tenant
+        account = AccountService.create_account(
+            email=fake.email(),
+            name=fake.name(),
+            interface_language="en-US",
+            password=fake.password(length=12),
+        )
+        TenantService.create_owner_tenant_if_not_exist(account, name=fake.company())
+        tenant = account.current_tenant
+
+        return account, tenant
+
+    def _create_test_subscription(
+        self,
+        db_session_with_containers,
+        tenant_id,
+        user_id,
+        provider_id,
+        credential_type,
+        credentials,
+        mock_external_service_dependencies,
+    ):
+        """
+        Helper method to create a test trigger subscription.
+
+        Args:
+            db_session_with_containers: Database session
+            tenant_id: Tenant ID
+            user_id: User ID
+            provider_id: Provider ID
+            credential_type: Credential type
+            credentials: Credentials dict
+            mock_external_service_dependencies: Mock dependencies
+
+        Returns:
+            TriggerSubscription: Created subscription instance
+        """
+        fake = Faker()
+        from core.helper.provider_cache import NoOpProviderCredentialCache
+        from core.helper.provider_encryption import create_provider_encrypter
+
+        # Use mock provider controller to encrypt credentials
+        provider_controller = mock_external_service_dependencies["provider_controller"]
+
+        # Create encrypter for credentials
+        credential_encrypter, _ = create_provider_encrypter(
+            tenant_id=tenant_id,
+            config=provider_controller.get_credential_schema_config(credential_type),
+            cache=NoOpProviderCredentialCache(),
+        )
+
+        subscription = TriggerSubscription(
+            name=fake.word(),
+            tenant_id=tenant_id,
+            user_id=user_id,
+            provider_id=str(provider_id),
+            endpoint_id=fake.uuid4(),
+            parameters={"param1": "value1"},
+            properties={"prop1": "value1"},
+            credentials=dict(credential_encrypter.encrypt(credentials)),
+            credential_type=credential_type.value,
+            credential_expires_at=-1,
+            expires_at=-1,
+        )
+
+        db.session.add(subscription)
+        db.session.commit()
+        db.session.refresh(subscription)
+
+        return subscription
+
+    def test_rebuild_trigger_subscription_success_with_merged_credentials(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test successful rebuild with credential merging (HIDDEN_VALUE handling).
+
+        This test verifies:
+        - Credentials are properly merged (HIDDEN_VALUE replaced with existing values)
+        - Single transaction wraps all operations
+        - Merged credentials are used for subscribe and update
+        - Database state is correctly updated
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        # Create initial subscription with credentials
+        original_credentials = {"api_key": "original-secret-key", "api_secret": "original-secret"}
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            original_credentials,
+            mock_external_service_dependencies,
+        )
+
+        # Prepare new credentials with HIDDEN_VALUE for api_key (should keep original)
+        # and new value for api_secret (should update)
+        new_credentials = {
+            "api_key": HIDDEN_VALUE,  # Should be replaced with original
+            "api_secret": "new-secret-value",  # Should be updated
+        }
+
+        # Mock subscribe_trigger to return a new subscription entity
+        new_subscription_entity = TriggerSubscriptionEntity(
+            endpoint=subscription.endpoint_id,
+            parameters={"param1": "value1"},
+            properties={"prop1": "new_prop_value"},
+            expires_at=1234567890,
+        )
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.return_value = new_subscription_entity
+
+        # Mock unsubscribe_trigger
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.return_value = MagicMock()
+
+        # Execute rebuild
+        TriggerProviderService.rebuild_trigger_subscription(
+            tenant_id=tenant.id,
+            provider_id=provider_id,
+            subscription_id=subscription.id,
+            credentials=new_credentials,
+            parameters={"param1": "updated_value"},
+            name="updated_name",
+        )
+
+        # Verify unsubscribe was called with decrypted original credentials
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.assert_called_once()
+        unsubscribe_call_args = mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.call_args
+        assert unsubscribe_call_args.kwargs["tenant_id"] == tenant.id
+        assert unsubscribe_call_args.kwargs["provider_id"] == provider_id
+        assert unsubscribe_call_args.kwargs["credential_type"] == credential_type
+
+        # Verify subscribe was called with merged credentials (api_key from original, api_secret new)
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.assert_called_once()
+        subscribe_call_args = mock_external_service_dependencies["trigger_manager"].subscribe_trigger.call_args
+        subscribe_credentials = subscribe_call_args.kwargs["credentials"]
+        assert subscribe_credentials["api_key"] == original_credentials["api_key"]  # Merged from original
+        assert subscribe_credentials["api_secret"] == "new-secret-value"  # New value
+
+        # Verify database state was updated
+        db.session.refresh(subscription)
+        assert subscription.name == "updated_name"
+        assert subscription.parameters == {"param1": "updated_value"}
+
+        # Verify credentials in DB were updated with merged values (decrypt to check)
+        from core.helper.provider_cache import NoOpProviderCredentialCache
+        from core.helper.provider_encryption import create_provider_encrypter
+
+        # Use mock provider controller to decrypt credentials
+        provider_controller = mock_external_service_dependencies["provider_controller"]
+        credential_encrypter, _ = create_provider_encrypter(
+            tenant_id=tenant.id,
+            config=provider_controller.get_credential_schema_config(credential_type),
+            cache=NoOpProviderCredentialCache(),
+        )
+        decrypted_db_credentials = dict(credential_encrypter.decrypt(subscription.credentials))
+        assert decrypted_db_credentials["api_key"] == original_credentials["api_key"]
+        assert decrypted_db_credentials["api_secret"] == "new-secret-value"
+
+        # Verify cache was cleared
+        mock_external_service_dependencies["delete_cache"].assert_called_once_with(
+            tenant_id=tenant.id,
+            provider_id=subscription.provider_id,
+            subscription_id=subscription.id,
+        )
+
+    def test_rebuild_trigger_subscription_with_all_new_credentials(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test rebuild when all credentials are new (no HIDDEN_VALUE).
+
+        This test verifies:
+        - All new credentials are used when no HIDDEN_VALUE is present
+        - Merged credentials contain only new values
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        # Create initial subscription
+        original_credentials = {"api_key": "original-key", "api_secret": "original-secret"}
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            original_credentials,
+            mock_external_service_dependencies,
+        )
+
+        # All new credentials (no HIDDEN_VALUE)
+        new_credentials = {
+            "api_key": "completely-new-key",
+            "api_secret": "completely-new-secret",
+        }
+
+        new_subscription_entity = TriggerSubscriptionEntity(
+            endpoint=subscription.endpoint_id,
+            parameters={},
+            properties={},
+            expires_at=-1,
+        )
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.return_value = new_subscription_entity
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.return_value = MagicMock()
+
+        # Execute rebuild
+        TriggerProviderService.rebuild_trigger_subscription(
+            tenant_id=tenant.id,
+            provider_id=provider_id,
+            subscription_id=subscription.id,
+            credentials=new_credentials,
+            parameters={},
+        )
+
+        # Verify subscribe was called with all new credentials
+        subscribe_call_args = mock_external_service_dependencies["trigger_manager"].subscribe_trigger.call_args
+        subscribe_credentials = subscribe_call_args.kwargs["credentials"]
+        assert subscribe_credentials["api_key"] == "completely-new-key"
+        assert subscribe_credentials["api_secret"] == "completely-new-secret"
+
+    def test_rebuild_trigger_subscription_with_all_hidden_values(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test rebuild when all credentials are HIDDEN_VALUE (preserve all existing).
+
+        This test verifies:
+        - All HIDDEN_VALUE credentials are replaced with existing values
+        - Original credentials are preserved
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        original_credentials = {"api_key": "original-key", "api_secret": "original-secret"}
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            original_credentials,
+            mock_external_service_dependencies,
+        )
+
+        # All HIDDEN_VALUE (should preserve all original)
+        new_credentials = {
+            "api_key": HIDDEN_VALUE,
+            "api_secret": HIDDEN_VALUE,
+        }
+
+        new_subscription_entity = TriggerSubscriptionEntity(
+            endpoint=subscription.endpoint_id,
+            parameters={},
+            properties={},
+            expires_at=-1,
+        )
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.return_value = new_subscription_entity
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.return_value = MagicMock()
+
+        # Execute rebuild
+        TriggerProviderService.rebuild_trigger_subscription(
+            tenant_id=tenant.id,
+            provider_id=provider_id,
+            subscription_id=subscription.id,
+            credentials=new_credentials,
+            parameters={},
+        )
+
+        # Verify subscribe was called with all original credentials
+        subscribe_call_args = mock_external_service_dependencies["trigger_manager"].subscribe_trigger.call_args
+        subscribe_credentials = subscribe_call_args.kwargs["credentials"]
+        assert subscribe_credentials["api_key"] == original_credentials["api_key"]
+        assert subscribe_credentials["api_secret"] == original_credentials["api_secret"]
+
+    def test_rebuild_trigger_subscription_with_missing_key_uses_unknown_value(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test rebuild when HIDDEN_VALUE is used for a key that doesn't exist in original.
+
+        This test verifies:
+        - UNKNOWN_VALUE is used when HIDDEN_VALUE key doesn't exist in original credentials
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        # Original has only api_key
+        original_credentials = {"api_key": "original-key"}
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            original_credentials,
+            mock_external_service_dependencies,
+        )
+
+        # HIDDEN_VALUE for non-existent key should use UNKNOWN_VALUE
+        new_credentials = {
+            "api_key": HIDDEN_VALUE,
+            "non_existent_key": HIDDEN_VALUE,  # This key doesn't exist in original
+        }
+
+        new_subscription_entity = TriggerSubscriptionEntity(
+            endpoint=subscription.endpoint_id,
+            parameters={},
+            properties={},
+            expires_at=-1,
+        )
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.return_value = new_subscription_entity
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.return_value = MagicMock()
+
+        # Execute rebuild
+        TriggerProviderService.rebuild_trigger_subscription(
+            tenant_id=tenant.id,
+            provider_id=provider_id,
+            subscription_id=subscription.id,
+            credentials=new_credentials,
+            parameters={},
+        )
+
+        # Verify subscribe was called with original api_key and UNKNOWN_VALUE for missing key
+        subscribe_call_args = mock_external_service_dependencies["trigger_manager"].subscribe_trigger.call_args
+        subscribe_credentials = subscribe_call_args.kwargs["credentials"]
+        assert subscribe_credentials["api_key"] == original_credentials["api_key"]
+        assert subscribe_credentials["non_existent_key"] == UNKNOWN_VALUE
+
+    def test_rebuild_trigger_subscription_rollback_on_error(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test that transaction is rolled back on error.
+
+        This test verifies:
+        - Database transaction is rolled back when an error occurs
+        - Original subscription state is preserved
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        original_credentials = {"api_key": "original-key"}
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            original_credentials,
+            mock_external_service_dependencies,
+        )
+
+        original_name = subscription.name
+        original_parameters = subscription.parameters.copy()
+
+        # Make subscribe_trigger raise an error
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.side_effect = ValueError(
+            "Subscribe failed"
+        )
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.return_value = MagicMock()
+
+        # Execute rebuild and expect error
+        with pytest.raises(ValueError, match="Subscribe failed"):
+            TriggerProviderService.rebuild_trigger_subscription(
+                tenant_id=tenant.id,
+                provider_id=provider_id,
+                subscription_id=subscription.id,
+                credentials={"api_key": "new-key"},
+                parameters={},
+            )
+
+        # Verify subscription state was not changed (rolled back)
+        db.session.refresh(subscription)
+        assert subscription.name == original_name
+        assert subscription.parameters == original_parameters
+
+    def test_rebuild_trigger_subscription_unsubscribe_error_continues(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test that unsubscribe errors are handled gracefully and operation continues.
+
+        This test verifies:
+        - Unsubscribe errors are caught and logged but don't stop the rebuild
+        - Rebuild continues even if unsubscribe fails
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        original_credentials = {"api_key": "original-key"}
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            original_credentials,
+            mock_external_service_dependencies,
+        )
+
+        # Make unsubscribe_trigger raise an error (should be caught and continue)
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.side_effect = ValueError(
+            "Unsubscribe failed"
+        )
+
+        new_subscription_entity = TriggerSubscriptionEntity(
+            endpoint=subscription.endpoint_id,
+            parameters={},
+            properties={},
+            expires_at=-1,
+        )
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.return_value = new_subscription_entity
+
+        # Execute rebuild - should succeed despite unsubscribe error
+        TriggerProviderService.rebuild_trigger_subscription(
+            tenant_id=tenant.id,
+            provider_id=provider_id,
+            subscription_id=subscription.id,
+            credentials={"api_key": "new-key"},
+            parameters={},
+        )
+
+        # Verify subscribe was still called (operation continued)
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.assert_called_once()
+
+        # Verify subscription was updated
+        db.session.refresh(subscription)
+        assert subscription.parameters == {}
+
+    def test_rebuild_trigger_subscription_subscription_not_found(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test error when subscription is not found.
+
+        This test verifies:
+        - Proper error is raised when subscription doesn't exist
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        fake_subscription_id = fake.uuid4()
+
+        with pytest.raises(ValueError, match="not found"):
+            TriggerProviderService.rebuild_trigger_subscription(
+                tenant_id=tenant.id,
+                provider_id=provider_id,
+                subscription_id=fake_subscription_id,
+                credentials={},
+                parameters={},
+            )
+
+    def test_rebuild_trigger_subscription_provider_not_found(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test error when provider is not found.
+
+        This test verifies:
+        - Proper error is raised when provider doesn't exist
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("non_existent_org/non_existent_plugin/non_existent_provider")
+
+        # Make get_trigger_provider return None
+        mock_external_service_dependencies["trigger_manager"].get_trigger_provider.return_value = None
+
+        with pytest.raises(ValueError, match="Provider.*not found"):
+            TriggerProviderService.rebuild_trigger_subscription(
+                tenant_id=tenant.id,
+                provider_id=provider_id,
+                subscription_id=fake.uuid4(),
+                credentials={},
+                parameters={},
+            )
+
+    def test_rebuild_trigger_subscription_unsupported_credential_type(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test error when credential type is not supported for rebuild.
+
+        This test verifies:
+        - Proper error is raised for unsupported credential types (not OAUTH2 or API_KEY)
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.UNAUTHORIZED  # Not supported
+
+        subscription = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            {},
+            mock_external_service_dependencies,
+        )
+
+        with pytest.raises(ValueError, match="Credential type not supported for rebuild"):
+            TriggerProviderService.rebuild_trigger_subscription(
+                tenant_id=tenant.id,
+                provider_id=provider_id,
+                subscription_id=subscription.id,
+                credentials={},
+                parameters={},
+            )
+
+    def test_rebuild_trigger_subscription_name_uniqueness_check(
+        self, db_session_with_containers, mock_external_service_dependencies
+    ):
+        """
+        Test that name uniqueness is checked when updating name.
+
+        This test verifies:
+        - Error is raised when new name conflicts with existing subscription
+        """
+        fake = Faker()
+        account, tenant = self._create_test_account_and_tenant(
+            db_session_with_containers, mock_external_service_dependencies
+        )
+
+        provider_id = TriggerProviderID("test_org/test_plugin/test_provider")
+        credential_type = CredentialType.API_KEY
+
+        # Create first subscription
+        subscription1 = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            {"api_key": "key1"},
+            mock_external_service_dependencies,
+        )
+
+        # Create second subscription with different name
+        subscription2 = self._create_test_subscription(
+            db_session_with_containers,
+            tenant.id,
+            account.id,
+            provider_id,
+            credential_type,
+            {"api_key": "key2"},
+            mock_external_service_dependencies,
+        )
+
+        new_subscription_entity = TriggerSubscriptionEntity(
+            endpoint=subscription2.endpoint_id,
+            parameters={},
+            properties={},
+            expires_at=-1,
+        )
+        mock_external_service_dependencies["trigger_manager"].subscribe_trigger.return_value = new_subscription_entity
+        mock_external_service_dependencies["trigger_manager"].unsubscribe_trigger.return_value = MagicMock()
+
+        # Try to rename subscription2 to subscription1's name (should fail)
+        with pytest.raises(ValueError, match="already exists"):
+            TriggerProviderService.rebuild_trigger_subscription(
+                tenant_id=tenant.id,
+                provider_id=provider_id,
+                subscription_id=subscription2.id,
+                credentials={"api_key": "new-key"},
+                parameters={},
+                name=subscription1.name,  # Conflicting name
+            )

api/tests/unit_tests/tools/test_mcp_tool.py

@@ -0,0 +1,122 @@
+import base64
+from unittest.mock import Mock, patch
+
+import pytest
+
+from core.mcp.types import (
+    AudioContent,
+    BlobResourceContents,
+    CallToolResult,
+    EmbeddedResource,
+    ImageContent,
+    TextResourceContents,
+)
+from core.tools.__base.tool_runtime import ToolRuntime
+from core.tools.entities.common_entities import I18nObject
+from core.tools.entities.tool_entities import ToolEntity, ToolIdentity, ToolInvokeMessage
+from core.tools.mcp_tool.tool import MCPTool
+
+
+def _make_mcp_tool(output_schema: dict | None = None) -> MCPTool:
+    identity = ToolIdentity(
+        author="test",
+        name="test_mcp_tool",
+        label=I18nObject(en_US="Test MCP Tool", zh_Hans="测试MCP工具"),
+        provider="test_provider",
+    )
+    entity = ToolEntity(identity=identity, output_schema=output_schema or {})
+    runtime = Mock(spec=ToolRuntime)
+    runtime.credentials = {}
+    return MCPTool(
+        entity=entity,
+        runtime=runtime,
+        tenant_id="test_tenant",
+        icon="",
+        server_url="https://server.invalid",
+        provider_id="provider_1",
+        headers={},
+    )
+
+
+class TestMCPToolInvoke:
+    @pytest.mark.parametrize(
+        ("content_factory", "mime_type"),
+        [
+            (
+                lambda b64, mt: ImageContent(type="image", data=b64, mimeType=mt),
+                "image/png",
+            ),
+            (
+                lambda b64, mt: AudioContent(type="audio", data=b64, mimeType=mt),
+                "audio/mpeg",
+            ),
+        ],
+    )
+    def test_invoke_image_or_audio_yields_blob(self, content_factory, mime_type) -> None:
+        tool = _make_mcp_tool()
+        raw = b"\x00\x01test-bytes\x02"
+        b64 = base64.b64encode(raw).decode()
+        content = content_factory(b64, mime_type)
+        result = CallToolResult(content=[content])
+
+        with patch.object(tool, "invoke_remote_mcp_tool", return_value=result):
+            messages = list(tool._invoke(user_id="test_user", tool_parameters={}))
+
+        assert len(messages) == 1
+        msg = messages[0]
+        assert msg.type == ToolInvokeMessage.MessageType.BLOB
+        assert isinstance(msg.message, ToolInvokeMessage.BlobMessage)
+        assert msg.message.blob == raw
+        assert msg.meta == {"mime_type": mime_type}
+
+    def test_invoke_embedded_text_resource_yields_text(self) -> None:
+        tool = _make_mcp_tool()
+        text_resource = TextResourceContents(uri="file://test.txt", mimeType="text/plain", text="hello world")
+        content = EmbeddedResource(type="resource", resource=text_resource)
+        result = CallToolResult(content=[content])
+
+        with patch.object(tool, "invoke_remote_mcp_tool", return_value=result):
+            messages = list(tool._invoke(user_id="test_user", tool_parameters={}))
+
+        assert len(messages) == 1
+        msg = messages[0]
+        assert msg.type == ToolInvokeMessage.MessageType.TEXT
+        assert isinstance(msg.message, ToolInvokeMessage.TextMessage)
+        assert msg.message.text == "hello world"
+
+    @pytest.mark.parametrize(
+        ("mime_type", "expected_mime"),
+        [("application/pdf", "application/pdf"), (None, "application/octet-stream")],
+    )
+    def test_invoke_embedded_blob_resource_yields_blob(self, mime_type, expected_mime) -> None:
+        tool = _make_mcp_tool()
+        raw = b"binary-data"
+        b64 = base64.b64encode(raw).decode()
+        blob_resource = BlobResourceContents(uri="file://doc.bin", mimeType=mime_type, blob=b64)
+        content = EmbeddedResource(type="resource", resource=blob_resource)
+        result = CallToolResult(content=[content])
+
+        with patch.object(tool, "invoke_remote_mcp_tool", return_value=result):
+            messages = list(tool._invoke(user_id="test_user", tool_parameters={}))
+
+        assert len(messages) == 1
+        msg = messages[0]
+        assert msg.type == ToolInvokeMessage.MessageType.BLOB
+        assert isinstance(msg.message, ToolInvokeMessage.BlobMessage)
+        assert msg.message.blob == raw
+        assert msg.meta == {"mime_type": expected_mime}
+
+    def test_invoke_yields_variables_when_structured_content_and_schema(self) -> None:
+        tool = _make_mcp_tool(output_schema={"type": "object"})
+        result = CallToolResult(content=[], structuredContent={"a": 1, "b": "x"})
+
+        with patch.object(tool, "invoke_remote_mcp_tool", return_value=result):
+            messages = list(tool._invoke(user_id="test_user", tool_parameters={}))
+
+        # Expect two variable messages corresponding to keys a and b
+        assert len(messages) == 2
+        var_msgs = [m for m in messages if isinstance(m.message, ToolInvokeMessage.VariableMessage)]
+        assert {m.message.variable_name for m in var_msgs} == {"a", "b"}
+        # Validate values
+        values = {m.message.variable_name: m.message.variable_value for m in var_msgs}
+        assert values == {"a": 1, "b": "x"}

api/uv.lock

@@ -3072,11 +3072,11 @@ wheels = [
 
 [[package]]
 name = "json-repair"
-version = "0.54.1"
+version = "0.54.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/00/46/d3a4d9a3dad39bb4a2ad16b8adb9fe2e8611b20b71197fe33daa6768e85d/json_repair-0.54.1.tar.gz", hash = "sha256:d010bc31f1fc66e7c36dc33bff5f8902674498ae5cb8e801ad455a53b455ad1d", size = 38555, upload-time = "2025-11-19T14:55:24.265Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b5/86/48b12ac02032f121ac7e5f11a32143edca6c1e3d19ffc54d6fb9ca0aafd0/json_repair-0.54.3.tar.gz", hash = "sha256:e50feec9725e52ac91f12184609754684ac1656119dfbd31de09bdaf9a1d8bf6", size = 38626, upload-time = "2025-12-15T09:41:58.594Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/db/96/c9aad7ee949cc1bf15df91f347fbc2d3bd10b30b80c7df689ce6fe9332b5/json_repair-0.54.1-py3-none-any.whl", hash = "sha256:016160c5db5d5fe443164927bb58d2dfbba5f43ad85719fa9bc51c713a443ab1", size = 29311, upload-time = "2025-11-19T14:55:22.886Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/08/abe317237add63c3e62f18a981bccf92112b431835b43d844aedaf61f4a0/json_repair-0.54.3-py3-none-any.whl", hash = "sha256:4cdc132ee27d4780576f71bf27a113877046224a808bfc17392e079cb344fb81", size = 29357, upload-time = "2025-12-15T09:41:57.436Z" },
 ]
 
 [[package]]

sdks/nodejs-client/package.json

@@ -54,17 +54,17 @@
     "publish:npm": "./scripts/publish.sh"
   },
   "dependencies": {
-    "axios": "^1.3.5"
+    "axios": "^1.13.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.2.0",
-    "@types/node": "^20.11.30",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.3",
     "@typescript-eslint/eslint-plugin": "^8.50.1",
     "@typescript-eslint/parser": "^8.50.1",
-    "@vitest/coverage-v8": "1.6.1",
-    "eslint": "^9.2.0",
+    "@vitest/coverage-v8": "4.0.16",
+    "eslint": "^9.39.2",
     "tsup": "^8.5.1",
-    "typescript": "^5.4.5",
-    "vitest": "^1.5.0"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   }
 }

sdks/nodejs-client/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

web/app/components/app/configuration/config-var/config-modal/index.tsx

@@ -47,6 +47,12 @@ const getCheckboxDefaultSelectValue = (value: InputVar['default']) => {
 const parseCheckboxSelectValue = (value: string) =>
   value === CHECKBOX_DEFAULT_TRUE_VALUE
 
+const normalizeSelectDefaultValue = (inputVar: InputVar) => {
+  if (inputVar.type === InputVarType.select && inputVar.default === '')
+    return { ...inputVar, default: undefined }
+  return inputVar
+}
+
 export type IConfigModalProps = {
   isCreate?: boolean
   payload?: InputVar
@@ -67,7 +73,7 @@ const ConfigModal: FC<IConfigModalProps> = ({
 }) => {
   const { modelConfig } = useContext(ConfigContext)
   const { t } = useTranslation()
-  const [tempPayload, setTempPayload] = useState<InputVar>(() => payload || getNewVarInWorkflow('') as any)
+  const [tempPayload, setTempPayload] = useState<InputVar>(() => normalizeSelectDefaultValue(payload || getNewVarInWorkflow('') as any))
   const { type, label, variable, options, max_length } = tempPayload
   const modalRef = useRef<HTMLDivElement>(null)
   const appDetail = useAppStore(state => state.appDetail)
@@ -182,6 +188,8 @@ const ConfigModal: FC<IConfigModalProps> = ({
 
     const newPayload = produce(tempPayload, (draft) => {
       draft.type = type
+      if (type === InputVarType.select)
+        draft.default = undefined
       if ([InputVarType.singleFile, InputVarType.multiFiles].includes(type)) {
         (Object.keys(DEFAULT_FILE_UPLOAD_SETTING)).forEach((key) => {
           if (key !== 'max_length')

web/app/components/app/create-app-dialog/app-list/index.spec.tsx

@@ -21,8 +21,8 @@ vi.mock('use-context-selector', async () => {
     useContext: () => ({ hasEditPermission: true }),
   }
 })
-vi.mock('@/hooks/use-tab-searchparams', () => ({
-  useTabSearchParams: () => ['Recommended', vi.fn()],
+vi.mock('nuqs', () => ({
+  useQueryState: () => ['Recommended', vi.fn()],
 }))
 vi.mock('@/service/use-explore', () => ({
   useExploreAppList: () => mockUseExploreAppList(),

web/app/components/app/create-app-dialog/app-list/index.tsx

@@ -20,7 +20,6 @@ import { usePluginDependencies } from '@/app/components/workflow/plugin-dependen
 import { NEED_REFRESH_APP_LIST_KEY } from '@/config'
 import { useAppContext } from '@/context/app-context'
 import ExploreContext from '@/context/explore-context'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { DSLImportMode } from '@/models/app'
 import { importDSL } from '@/service/apps'
 import { fetchAppDetail } from '@/service/explore'
@@ -64,10 +63,7 @@ const Apps = ({
   }
 
   const [currentType, setCurrentType] = useState<AppModeEnum[]>([])
-  const [currCategory, setCurrCategory] = useTabSearchParams({
-    defaultTab: allCategoriesEn,
-    disableSearchParams: true,
-  })
+  const [currCategory, setCurrCategory] = useState<AppCategories | string>(allCategoriesEn)
 
   const {
     data,

web/app/components/app/log/list.tsx

@@ -140,14 +140,14 @@ const getFormattedChatList = (messages: ChatMessage[], conversationId: string, t
         id: item.id,
         content: item.answer,
         agent_thoughts: addFileInfos(item.agent_thoughts ? sortAgentSorts(item.agent_thoughts) : item.agent_thoughts, item.message_files),
-        feedback: item.feedbacks.find(item => item.from_source === 'user'), // user feedback
-        adminFeedback: item.feedbacks.find(item => item.from_source === 'admin'), // admin feedback
+        feedback: item.feedbacks?.find(item => item.from_source === 'user'), // user feedback
+        adminFeedback: item.feedbacks?.find(item => item.from_source === 'admin'), // admin feedback
         feedbackDisabled: false,
         isAnswer: true,
         message_files: getProcessedFilesFromResponse(answerFiles.map((item: any) => ({ ...item, related_id: item.id }))),
         log: [
-          ...item.message,
-          ...(item.message[item.message.length - 1]?.role !== 'assistant'
+          ...(item.message ?? []),
+          ...(item.message?.[item.message.length - 1]?.role !== 'assistant'
             ? [
                 {
                   role: 'assistant',
@@ -166,7 +166,7 @@ const getFormattedChatList = (messages: ChatMessage[], conversationId: string, t
         more: {
           time: dayjs.unix(item.created_at).tz(timezone).format(format),
           tokens: item.answer_tokens + item.message_tokens,
-          latency: item.provider_response_latency.toFixed(2),
+          latency: (item.provider_response_latency ?? 0).toFixed(2),
         },
         citation: item.metadata?.retriever_resources,
         annotation: (() => {

web/app/components/apps/hooks/use-apps-query-state.spec.ts

@@ -1,363 +0,0 @@
-/**
- * Test suite for useAppsQueryState hook
- *
- * This hook manages app filtering state through URL search parameters, enabling:
- * - Bookmarkable filter states (users can share URLs with specific filters active)
- * - Browser history integration (back/forward buttons work with filters)
- * - Multiple filter types: tagIDs, keywords, isCreatedByMe
- *
- * The hook syncs local filter state with URL search parameters, making filter
- * navigation persistent and shareable across sessions.
- */
-import { act, renderHook } from '@testing-library/react'
-
-// Import the hook after mocks are set up
-import useAppsQueryState from './use-apps-query-state'
-
-// Mock Next.js navigation hooks
-const mockPush = vi.fn()
-const mockPathname = '/apps'
-let mockSearchParams = new URLSearchParams()
-
-vi.mock('next/navigation', () => ({
-  usePathname: vi.fn(() => mockPathname),
-  useRouter: vi.fn(() => ({
-    push: mockPush,
-  })),
-  useSearchParams: vi.fn(() => mockSearchParams),
-}))
-
-describe('useAppsQueryState', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockSearchParams = new URLSearchParams()
-  })
-
-  describe('Basic functionality', () => {
-    it('should return query object and setQuery function', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query).toBeDefined()
-      expect(typeof result.current.setQuery).toBe('function')
-    })
-
-    it('should initialize with empty query when no search params exist', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toBeUndefined()
-      expect(result.current.query.keywords).toBeUndefined()
-      expect(result.current.query.isCreatedByMe).toBe(false)
-    })
-  })
-
-  describe('Parsing search params', () => {
-    it('should parse tagIDs from URL', () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2;tag3')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2', 'tag3'])
-    })
-
-    it('should parse single tagID from URL', () => {
-      mockSearchParams.set('tagIDs', 'single-tag')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual(['single-tag'])
-    })
-
-    it('should parse keywords from URL', () => {
-      mockSearchParams.set('keywords', 'search term')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.keywords).toBe('search term')
-    })
-
-    it('should parse isCreatedByMe as true from URL', () => {
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-
-    it('should parse isCreatedByMe as false for other values', () => {
-      mockSearchParams.set('isCreatedByMe', 'false')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.isCreatedByMe).toBe(false)
-    })
-
-    it('should parse all params together', () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2')
-      mockSearchParams.set('keywords', 'test')
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
-      expect(result.current.query.keywords).toBe('test')
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-  })
-
-  describe('Updating query state', () => {
-    it('should update keywords via setQuery', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'new search' })
-      })
-
-      expect(result.current.query.keywords).toBe('new search')
-    })
-
-    it('should update tagIDs via setQuery', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
-      })
-
-      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
-    })
-
-    it('should update isCreatedByMe via setQuery', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ isCreatedByMe: true })
-      })
-
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-
-    it('should support partial updates via callback', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'initial' })
-      })
-
-      act(() => {
-        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
-      })
-
-      expect(result.current.query.keywords).toBe('initial')
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-  })
-
-  describe('URL synchronization', () => {
-    it('should sync keywords to URL', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'search' })
-      })
-
-      // Wait for useEffect to run
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.stringContaining('keywords=search'),
-        { scroll: false },
-      )
-    })
-
-    it('should sync tagIDs to URL with semicolon separator', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.stringContaining('tagIDs=tag1%3Btag2'),
-        { scroll: false },
-      )
-    })
-
-    it('should sync isCreatedByMe to URL', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ isCreatedByMe: true })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.stringContaining('isCreatedByMe=true'),
-        { scroll: false },
-      )
-    })
-
-    it('should remove keywords from URL when empty', async () => {
-      mockSearchParams.set('keywords', 'existing')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: '' })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      // Should be called without keywords param
-      expect(mockPush).toHaveBeenCalled()
-    })
-
-    it('should remove tagIDs from URL when empty array', async () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: [] })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalled()
-    })
-
-    it('should remove isCreatedByMe from URL when false', async () => {
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ isCreatedByMe: false })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalled()
-    })
-  })
-
-  describe('Edge cases', () => {
-    it('should handle empty tagIDs string in URL', () => {
-      // NOTE: This test documents current behavior where ''.split(';') returns ['']
-      // This could potentially cause filtering issues as it's treated as a tag with empty name
-      // rather than absence of tags. Consider updating parseParams if this is problematic.
-      mockSearchParams.set('tagIDs', '')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual([''])
-    })
-
-    it('should handle empty keywords', () => {
-      mockSearchParams.set('keywords', '')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.keywords).toBeUndefined()
-    })
-
-    it('should handle undefined tagIDs', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: undefined })
-      })
-
-      expect(result.current.query.tagIDs).toBeUndefined()
-    })
-
-    it('should handle special characters in keywords', () => {
-      // Use URLSearchParams constructor to properly simulate URL decoding behavior
-      // URLSearchParams.get() decodes URL-encoded characters
-      mockSearchParams = new URLSearchParams('keywords=test%20with%20spaces')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.keywords).toBe('test with spaces')
-    })
-  })
-
-  describe('Memoization', () => {
-    it('should return memoized object reference when query unchanged', () => {
-      const { result, rerender } = renderHook(() => useAppsQueryState())
-
-      const firstResult = result.current
-      rerender()
-      const secondResult = result.current
-
-      expect(firstResult.query).toBe(secondResult.query)
-    })
-
-    it('should return new object reference when query changes', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      const firstQuery = result.current.query
-
-      act(() => {
-        result.current.setQuery({ keywords: 'changed' })
-      })
-
-      expect(result.current.query).not.toBe(firstQuery)
-    })
-  })
-
-  describe('Integration scenarios', () => {
-    it('should handle sequential updates', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'first' })
-      })
-
-      act(() => {
-        result.current.setQuery(prev => ({ ...prev, tagIDs: ['tag1'] }))
-      })
-
-      act(() => {
-        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
-      })
-
-      expect(result.current.query.keywords).toBe('first')
-      expect(result.current.query.tagIDs).toEqual(['tag1'])
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-
-    it('should clear all filters', () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2')
-      mockSearchParams.set('keywords', 'search')
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({
-          tagIDs: undefined,
-          keywords: undefined,
-          isCreatedByMe: false,
-        })
-      })
-
-      expect(result.current.query.tagIDs).toBeUndefined()
-      expect(result.current.query.keywords).toBeUndefined()
-      expect(result.current.query.isCreatedByMe).toBe(false)
-    })
-  })
-})

web/app/components/apps/hooks/use-apps-query-state.spec.tsx

@@ -0,0 +1,248 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
+/**
+ * Test suite for useAppsQueryState hook
+ *
+ * This hook manages app filtering state through URL search parameters, enabling:
+ * - Bookmarkable filter states (users can share URLs with specific filters active)
+ * - Browser history integration (back/forward buttons work with filters)
+ * - Multiple filter types: tagIDs, keywords, isCreatedByMe
+ */
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import useAppsQueryState from './use-apps-query-state'
+
+const renderWithAdapter = (searchParams = '') => {
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  const { result } = renderHook(() => useAppsQueryState(), { wrapper })
+  return { result, onUrlUpdate }
+}
+
+// Groups scenarios for useAppsQueryState behavior.
+describe('useAppsQueryState', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Covers the hook return shape and default values.
+  describe('Initialization', () => {
+    it('should expose query and setQuery when initialized', () => {
+      const { result } = renderWithAdapter()
+
+      expect(result.current.query).toBeDefined()
+      expect(typeof result.current.setQuery).toBe('function')
+    })
+
+    it('should default to empty filters when search params are missing', () => {
+      const { result } = renderWithAdapter()
+
+      expect(result.current.query.tagIDs).toBeUndefined()
+      expect(result.current.query.keywords).toBeUndefined()
+      expect(result.current.query.isCreatedByMe).toBe(false)
+    })
+  })
+
+  // Covers parsing of existing URL search params.
+  describe('Parsing search params', () => {
+    it('should parse tagIDs when URL includes tagIDs', () => {
+      const { result } = renderWithAdapter('?tagIDs=tag1;tag2;tag3')
+
+      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2', 'tag3'])
+    })
+
+    it('should parse keywords when URL includes keywords', () => {
+      const { result } = renderWithAdapter('?keywords=search+term')
+
+      expect(result.current.query.keywords).toBe('search term')
+    })
+
+    it('should parse isCreatedByMe when URL includes true value', () => {
+      const { result } = renderWithAdapter('?isCreatedByMe=true')
+
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+
+    it('should parse all params when URL includes multiple filters', () => {
+      const { result } = renderWithAdapter(
+        '?tagIDs=tag1;tag2&keywords=test&isCreatedByMe=true',
+      )
+
+      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
+      expect(result.current.query.keywords).toBe('test')
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+  })
+
+  // Covers updates driven by setQuery.
+  describe('Updating query state', () => {
+    it('should update keywords when setQuery receives keywords', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'new search' })
+      })
+
+      expect(result.current.query.keywords).toBe('new search')
+    })
+
+    it('should update tagIDs when setQuery receives tagIDs', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
+      })
+
+      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
+    })
+
+    it('should update isCreatedByMe when setQuery receives true', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ isCreatedByMe: true })
+      })
+
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+
+    it('should support partial updates when setQuery uses callback', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'initial' })
+      })
+
+      act(() => {
+        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
+      })
+
+      expect(result.current.query.keywords).toBe('initial')
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+  })
+
+  // Covers URL updates triggered by query changes.
+  describe('URL synchronization', () => {
+    it('should sync keywords to URL when keywords change', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'search' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('keywords')).toBe('search')
+      expect(update.options.history).toBe('push')
+    })
+
+    it('should sync tagIDs to URL when tagIDs change', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('tagIDs')).toBe('tag1;tag2')
+    })
+
+    it('should sync isCreatedByMe to URL when enabled', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ isCreatedByMe: true })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('isCreatedByMe')).toBe('true')
+    })
+
+    it('should remove keywords from URL when keywords are cleared', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?keywords=existing')
+
+      act(() => {
+        result.current.setQuery({ keywords: '' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('keywords')).toBe(false)
+    })
+
+    it('should remove tagIDs from URL when tagIDs are empty', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?tagIDs=tag1;tag2')
+
+      act(() => {
+        result.current.setQuery({ tagIDs: [] })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('tagIDs')).toBe(false)
+    })
+
+    it('should remove isCreatedByMe from URL when disabled', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?isCreatedByMe=true')
+
+      act(() => {
+        result.current.setQuery({ isCreatedByMe: false })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('isCreatedByMe')).toBe(false)
+    })
+  })
+
+  // Covers decoding and empty values.
+  describe('Edge cases', () => {
+    it('should treat empty tagIDs as empty list when URL param is empty', () => {
+      const { result } = renderWithAdapter('?tagIDs=')
+
+      expect(result.current.query.tagIDs).toEqual([])
+    })
+
+    it('should treat empty keywords as undefined when URL param is empty', () => {
+      const { result } = renderWithAdapter('?keywords=')
+
+      expect(result.current.query.keywords).toBeUndefined()
+    })
+
+    it('should decode keywords with spaces when URL contains encoded spaces', () => {
+      const { result } = renderWithAdapter('?keywords=test+with+spaces')
+
+      expect(result.current.query.keywords).toBe('test with spaces')
+    })
+  })
+
+  // Covers multi-step updates that mimic real usage.
+  describe('Integration scenarios', () => {
+    it('should keep accumulated filters when updates are sequential', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'first' })
+      })
+
+      act(() => {
+        result.current.setQuery(prev => ({ ...prev, tagIDs: ['tag1'] }))
+      })
+
+      act(() => {
+        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
+      })
+
+      expect(result.current.query.keywords).toBe('first')
+      expect(result.current.query.tagIDs).toEqual(['tag1'])
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+  })
+})

web/app/components/apps/hooks/use-apps-query-state.ts

@@ -1,6 +1,5 @@
-import type { ReadonlyURLSearchParams } from 'next/navigation'
-import { usePathname, useRouter, useSearchParams } from 'next/navigation'
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { parseAsArrayOf, parseAsBoolean, parseAsString, useQueryStates } from 'nuqs'
+import { useCallback, useMemo } from 'react'
 
 type AppsQuery = {
   tagIDs?: string[]
@@ -8,54 +7,51 @@ type AppsQuery = {
   isCreatedByMe?: boolean
 }
 
-// Parse the query parameters from the URL search string.
-function parseParams(params: ReadonlyURLSearchParams): AppsQuery {
-  const tagIDs = params.get('tagIDs')?.split(';')
-  const keywords = params.get('keywords') || undefined
-  const isCreatedByMe = params.get('isCreatedByMe') === 'true'
-  return { tagIDs, keywords, isCreatedByMe }
-}
-
-// Update the URL search string with the given query parameters.
-function updateSearchParams(query: AppsQuery, current: URLSearchParams) {
-  const { tagIDs, keywords, isCreatedByMe } = query || {}
-
-  if (tagIDs && tagIDs.length > 0)
-    current.set('tagIDs', tagIDs.join(';'))
-  else
-    current.delete('tagIDs')
-
-  if (keywords)
-    current.set('keywords', keywords)
-  else
-    current.delete('keywords')
-
-  if (isCreatedByMe)
-    current.set('isCreatedByMe', 'true')
-  else
-    current.delete('isCreatedByMe')
-}
+const normalizeKeywords = (value: string | null) => value || undefined
 
 function useAppsQueryState() {
-  const searchParams = useSearchParams()
-  const [query, setQuery] = useState<AppsQuery>(() => parseParams(searchParams))
+  const [urlQuery, setUrlQuery] = useQueryStates(
+    {
+      tagIDs: parseAsArrayOf(parseAsString, ';'),
+      keywords: parseAsString,
+      isCreatedByMe: parseAsBoolean,
+    },
+    {
+      history: 'push',
+    },
+  )
 
-  const router = useRouter()
-  const pathname = usePathname()
-  const syncSearchParams = useCallback((params: URLSearchParams) => {
-    const search = params.toString()
-    const query = search ? `?${search}` : ''
-    router.push(`${pathname}${query}`, { scroll: false })
-  }, [router, pathname])
+  const query = useMemo<AppsQuery>(() => ({
+    tagIDs: urlQuery.tagIDs ?? undefined,
+    keywords: normalizeKeywords(urlQuery.keywords),
+    isCreatedByMe: urlQuery.isCreatedByMe ?? false,
+  }), [urlQuery.isCreatedByMe, urlQuery.keywords, urlQuery.tagIDs])
 
-  // Update the URL search string whenever the query changes.
-  useEffect(() => {
-    const params = new URLSearchParams(searchParams)
-    updateSearchParams(query, params)
-    syncSearchParams(params)
-  }, [query, searchParams, syncSearchParams])
+  const setQuery = useCallback((next: AppsQuery | ((prev: AppsQuery) => AppsQuery)) => {
+    const buildPatch = (patch: AppsQuery) => {
+      const result: Partial<typeof urlQuery> = {}
+      if ('tagIDs' in patch)
+        result.tagIDs = patch.tagIDs && patch.tagIDs.length > 0 ? patch.tagIDs : null
+      if ('keywords' in patch)
+        result.keywords = patch.keywords ? patch.keywords : null
+      if ('isCreatedByMe' in patch)
+        result.isCreatedByMe = patch.isCreatedByMe ? true : null
+      return result
+    }
 
-  return useMemo(() => ({ query, setQuery }), [query])
+    if (typeof next === 'function') {
+      setUrlQuery(prev => buildPatch(next({
+        tagIDs: prev.tagIDs ?? undefined,
+        keywords: normalizeKeywords(prev.keywords),
+        isCreatedByMe: prev.isCreatedByMe ?? false,
+      })))
+      return
+    }
+
+    setUrlQuery(buildPatch(next))
+  }, [setUrlQuery])
+
+  return useMemo(() => ({ query, setQuery }), [query, setQuery])
 }
 
 export default useAppsQueryState

web/app/components/apps/list.spec.tsx

@@ -57,8 +57,13 @@ vi.mock('./hooks/use-dsl-drag-drop', () => ({
 }))
 
 const mockSetActiveTab = vi.fn()
-vi.mock('@/hooks/use-tab-searchparams', () => ({
-  useTabSearchParams: () => ['all', mockSetActiveTab],
+vi.mock('nuqs', () => ({
+  useQueryState: () => ['all', mockSetActiveTab],
+  parseAsString: {
+    withDefault: () => ({
+      withOptions: () => ({}),
+    }),
+  },
 }))
 
 // Mock service hooks - use object for mutable state (vi.mock is hoisted)

web/app/components/apps/list.tsx

@@ -13,6 +13,7 @@ import dynamic from 'next/dynamic'
 import {
   useRouter,
 } from 'next/navigation'
+import { parseAsString, useQueryState } from 'nuqs'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Input from '@/app/components/base/input'
@@ -24,7 +25,6 @@ import { NEED_REFRESH_APP_LIST_KEY } from '@/config'
 import { useAppContext } from '@/context/app-context'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { CheckModal } from '@/hooks/use-pay'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { useInfiniteAppList } from '@/service/use-apps'
 import { AppModeEnum } from '@/types/app'
 import AppCard from './app-card'
@@ -47,9 +47,10 @@ const List = () => {
   const router = useRouter()
   const { isCurrentWorkspaceEditor, isCurrentWorkspaceDatasetOperator } = useAppContext()
   const showTagManagementModal = useTagStore(s => s.showTagManagementModal)
-  const [activeTab, setActiveTab] = useTabSearchParams({
-    defaultTab: 'all',
-  })
+  const [activeTab, setActiveTab] = useQueryState(
+    'category',
+    parseAsString.withDefault('all').withOptions({ history: 'push' }),
+  )
   const { query: { tagIDs = [], keywords = '', isCreatedByMe: queryIsCreatedByMe = false }, setQuery } = useAppsQueryState()
   const [isCreatedByMe, setIsCreatedByMe] = useState(queryIsCreatedByMe)
   const [tagFilterValue, setTagFilterValue] = useState<string[]>(tagIDs)

web/app/components/datasets/documents/detail/completed/common/batch-action.tsx

@@ -1,5 +1,5 @@
 import type { FC } from 'react'
-import { RiArchive2Line, RiCheckboxCircleLine, RiCloseCircleLine, RiDeleteBinLine, RiDraftLine } from '@remixicon/react'
+import { RiArchive2Line, RiCheckboxCircleLine, RiCloseCircleLine, RiDeleteBinLine, RiDraftLine, RiRefreshLine } from '@remixicon/react'
 import { useBoolean } from 'ahooks'
 import * as React from 'react'
 import { useTranslation } from 'react-i18next'
@@ -17,6 +17,7 @@ type IBatchActionProps = {
   onBatchDelete: () => Promise<void>
   onArchive?: () => void
   onEditMetadata?: () => void
+  onBatchReIndex?: () => void
   onCancel: () => void
 }
 
@@ -28,6 +29,7 @@ const BatchAction: FC<IBatchActionProps> = ({
   onArchive,
   onBatchDelete,
   onEditMetadata,
+  onBatchReIndex,
   onCancel,
 }) => {
   const { t } = useTranslation()
@@ -91,6 +93,16 @@ const BatchAction: FC<IBatchActionProps> = ({
             <span className="px-0.5">{t(`${i18nPrefix}.archive`)}</span>
           </Button>
         )}
+        {onBatchReIndex && (
+          <Button
+            variant="ghost"
+            className="gap-x-0.5 px-3"
+            onClick={onBatchReIndex}
+          >
+            <RiRefreshLine className="size-4" />
+            <span className="px-0.5">{t(`${i18nPrefix}.reIndex`)}</span>
+          </Button>
+        )}
         <Button
           variant="ghost"
           destructive

web/app/components/datasets/documents/list.tsx

@@ -27,7 +27,7 @@ import { useDatasetDetailContextWithSelector as useDatasetDetailContext } from '
 import useTimestamp from '@/hooks/use-timestamp'
 import { ChunkingMode, DataSourceType, DocumentActionType } from '@/models/datasets'
 import { DatasourceType } from '@/models/pipeline'
-import { useDocumentArchive, useDocumentDelete, useDocumentDisable, useDocumentEnable } from '@/service/knowledge/use-document'
+import { useDocumentArchive, useDocumentBatchRetryIndex, useDocumentDelete, useDocumentDisable, useDocumentEnable } from '@/service/knowledge/use-document'
 import { asyncRunSafe } from '@/utils'
 import { cn } from '@/utils/classnames'
 import { formatNumber } from '@/utils/format'
@@ -221,6 +221,7 @@ const DocumentList: FC<IDocumentListProps> = ({
   const { mutateAsync: enableDocument } = useDocumentEnable()
   const { mutateAsync: disableDocument } = useDocumentDisable()
   const { mutateAsync: deleteDocument } = useDocumentDelete()
+  const { mutateAsync: retryIndexDocument } = useDocumentBatchRetryIndex()
 
   const handleAction = (actionName: DocumentActionType) => {
     return async () => {
@@ -251,6 +252,22 @@ const DocumentList: FC<IDocumentListProps> = ({
     }
   }
 
+  const handleBatchReIndex = async () => {
+    const [e] = await asyncRunSafe<CommonResponse>(retryIndexDocument({ datasetId, documentIds: selectedIds }))
+    if (!e) {
+      onSelectedIdChange([])
+      Toast.notify({ type: 'success', message: t('common.actionMsg.modifiedSuccessfully') })
+      onUpdate()
+    }
+    else {
+      Toast.notify({ type: 'error', message: t('common.actionMsg.modifiedUnsuccessfully') })
+    }
+  }
+
+  const hasErrorDocumentsSelected = useMemo(() => {
+    return localDocs.some(doc => selectedIds.includes(doc.id) && doc.display_status === 'error')
+  }, [localDocs, selectedIds])
+
   const getFileExtension = useCallback((fileName: string): string => {
     if (!fileName)
       return ''
@@ -448,6 +465,7 @@ const DocumentList: FC<IDocumentListProps> = ({
           onBatchDisable={handleAction(DocumentActionType.disable)}
           onBatchDelete={handleAction(DocumentActionType.delete)}
           onEditMetadata={showEditModal}
+          onBatchReIndex={hasErrorDocumentsSelected ? handleBatchReIndex : undefined}
           onCancel={() => {
             onSelectedIdChange([])
           }}

web/app/components/datasets/hit-testing/index.tsx

@@ -34,7 +34,6 @@ import Records from './components/records'
 import ResultItem from './components/result-item'
 import ResultItemExternal from './components/result-item-external'
 import ModifyRetrievalModal from './modify-retrieval-modal'
-import s from './style.module.css'
 
 const limit = 10
 
@@ -115,8 +114,8 @@ const HitTestingPage: FC<Props> = ({ datasetId }: Props) => {
   }, [isMobile, setShowRightPanel])
 
   return (
-    <div className={s.container}>
-      <div className="flex flex-col px-6 py-3">
+    <div className="relative flex h-full w-full gap-x-6 overflow-y-auto pl-6">
+      <div className="flex min-w-0 flex-1 flex-col py-3">
         <div className="mb-4 flex flex-col justify-center">
           <h1 className="text-base font-semibold text-text-primary">{t('datasetHitTesting.title')}</h1>
           <p className="mt-0.5 text-[13px] font-normal leading-4 text-text-tertiary">{t('datasetHitTesting.desc')}</p>
@@ -161,7 +160,7 @@ const HitTestingPage: FC<Props> = ({ datasetId }: Props) => {
         onClose={hideRightPanel}
         footer={null}
       >
-        <div className="flex flex-col pt-3">
+        <div className="flex min-w-0 flex-1 flex-col pt-3">
           {isRetrievalLoading
             ? (
                 <div className="flex h-full flex-col rounded-tl-2xl bg-background-body px-4 py-3">

web/app/components/datasets/hit-testing/style.module.css

@@ -1,43 +0,0 @@
-.container {
-  @apply flex h-full w-full relative overflow-y-auto;
-}
-
-.container>div {
-  @apply flex-1 h-full;
-}
-
-.commonIcon {
-  @apply w-3.5 h-3.5 inline-block align-middle;
-  background-repeat: no-repeat;
-  background-position: center center;
-  background-size: contain;
-}
-
-.app_icon {
-  background-image: url(./assets/grid.svg);
-}
-
-.hit_testing_icon {
-  background-image: url(../documents/assets/target.svg);
-}
-
-.plugin_icon {
-  background-image: url(./assets/plugin.svg);
-}
-
-.cardWrapper {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(284px, auto));
-  grid-gap: 16px;
-  grid-auto-rows: 216px;
-}
-
-.clockWrapper {
-  border: 0.5px solid #eaecf5;
-  @apply rounded-lg w-11 h-11 flex justify-center items-center;
-}
-
-.clockIcon {
-  mask-image: url(./assets/clock.svg);
-  @apply bg-gray-500;
-}

web/app/components/devtools.tsx

@@ -0,0 +1,23 @@
+'use client'
+
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import { formDevtoolsPlugin } from '@tanstack/react-form-devtools'
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
+import * as React from 'react'
+
+export function TanStackDevtoolsWrapper() {
+  return (
+    <TanStackDevtools
+      plugins={[
+        // Query Devtools (Official Plugin)
+        {
+          name: 'React Query',
+          render: () => <ReactQueryDevtoolsPanel />,
+        },
+
+        // Form Devtools (Official Plugin)
+        formDevtoolsPlugin(),
+      ]}
+    />
+  )
+}

web/app/components/explore/app-list/index.spec.tsx

@@ -16,8 +16,8 @@ let mockIsError = false
 const mockHandleImportDSL = vi.fn()
 const mockHandleImportDSLConfirm = vi.fn()
 
-vi.mock('@/hooks/use-tab-searchparams', () => ({
-  useTabSearchParams: () => [mockTabValue, mockSetTab],
+vi.mock('nuqs', () => ({
+  useQueryState: () => [mockTabValue, mockSetTab],
 }))
 
 vi.mock('ahooks', async () => {

web/app/components/explore/app-list/index.tsx

@@ -3,6 +3,7 @@
 import type { CreateAppModalProps } from '@/app/components/explore/create-app-modal'
 import type { App } from '@/models/explore'
 import { useDebounceFn } from 'ahooks'
+import { useQueryState } from 'nuqs'
 import * as React from 'react'
 import { useCallback, useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -15,7 +16,6 @@ import Category from '@/app/components/explore/category'
 import CreateAppModal from '@/app/components/explore/create-app-modal'
 import ExploreContext from '@/context/explore-context'
 import { useImportDSL } from '@/hooks/use-import-dsl'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import {
   DSLImportMode,
 } from '@/models/app'
@@ -47,9 +47,8 @@ const Apps = ({
     handleSearch()
   }
 
-  const [currCategory, setCurrCategory] = useTabSearchParams({
-    defaultTab: allCategoriesEn,
-    disableSearchParams: false,
+  const [currCategory, setCurrCategory] = useQueryState('category', {
+    defaultValue: allCategoriesEn,
   })
 
   const {

web/app/components/plugins/marketplace/context.tsx

@@ -23,6 +23,7 @@ import {
   createContext,
   useContextSelector,
 } from 'use-context-selector'
+import { useMarketplaceFilters } from '@/hooks/use-query-params'
 import { useInstalledPluginList } from '@/service/use-plugins'
 import {
   getValidCategoryKeys,
@@ -38,7 +39,6 @@ import { PLUGIN_TYPE_SEARCH_MAP } from './plugin-type-switch'
 import {
   getMarketplaceListCondition,
   getMarketplaceListFilterType,
-  updateSearchParams,
 } from './utils'
 
 export type MarketplaceContextValue = {
@@ -108,16 +108,22 @@ export const MarketplaceContextProvider = ({
   scrollContainerId,
   showSearchParams,
 }: MarketplaceContextProviderProps) => {
+  // Use nuqs hook for URL-based filter state
+  const [urlFilters, setUrlFilters] = useMarketplaceFilters()
+
   const { data, isSuccess } = useInstalledPluginList(!shouldExclude)
   const exclude = useMemo(() => {
     if (shouldExclude)
       return data?.plugins.map(plugin => plugin.plugin_id)
   }, [data?.plugins, shouldExclude])
-  const queryFromSearchParams = searchParams?.q || ''
-  const tagsFromSearchParams = searchParams?.tags ? getValidTagKeys(searchParams.tags.split(',')) : []
+
+  // Initialize from URL params (legacy support) or use nuqs state
+  const queryFromSearchParams = searchParams?.q || urlFilters.q
+  const tagsFromSearchParams = getValidTagKeys(urlFilters.tags)
   const hasValidTags = !!tagsFromSearchParams.length
-  const hasValidCategory = getValidCategoryKeys(searchParams?.category)
+  const hasValidCategory = getValidCategoryKeys(urlFilters.category)
   const categoryFromSearchParams = hasValidCategory || PLUGIN_TYPE_SEARCH_MAP.all
+
   const [searchPluginText, setSearchPluginText] = useState(queryFromSearchParams)
   const searchPluginTextRef = useRef(searchPluginText)
   const [filterPluginTags, setFilterPluginTags] = useState<string[]>(tagsFromSearchParams)
@@ -159,10 +165,6 @@ export const MarketplaceContextProvider = ({
         sortOrder: sortRef.current.sortOrder,
         type: getMarketplaceListFilterType(activePluginTypeRef.current),
       })
-      const url = new URL(window.location.href)
-      if (searchParams?.language)
-        url.searchParams.set('language', searchParams?.language)
-      history.replaceState({}, '', url)
     }
     else {
       if (shouldExclude && isSuccess) {
@@ -184,28 +186,32 @@ export const MarketplaceContextProvider = ({
     resetPlugins()
   }, [exclude, queryMarketplaceCollectionsAndPlugins, resetPlugins])
 
-  const debouncedUpdateSearchParams = useMemo(() => debounce(() => {
-    updateSearchParams({
-      query: searchPluginTextRef.current,
-      category: activePluginTypeRef.current,
-      tags: filterPluginTagsRef.current,
-    })
-  }, 500), [])
-
-  const handleUpdateSearchParams = useCallback((debounced?: boolean) => {
+  const applyUrlFilters = useCallback(() => {
     if (!showSearchParams)
       return
+    const nextFilters = {
+      q: searchPluginTextRef.current,
+      category: activePluginTypeRef.current,
+      tags: filterPluginTagsRef.current,
+    }
+    const categoryChanged = urlFilters.category !== nextFilters.category
+    setUrlFilters(nextFilters, {
+      history: categoryChanged ? 'push' : 'replace',
+    })
+  }, [setUrlFilters, showSearchParams, urlFilters.category])
+
+  const debouncedUpdateSearchParams = useMemo(() => debounce(() => {
+    applyUrlFilters()
+  }, 500), [applyUrlFilters])
+
+  const handleUpdateSearchParams = useCallback((debounced?: boolean) => {
     if (debounced) {
       debouncedUpdateSearchParams()
     }
     else {
-      updateSearchParams({
-        query: searchPluginTextRef.current,
-        category: activePluginTypeRef.current,
-        tags: filterPluginTagsRef.current,
-      })
+      applyUrlFilters()
     }
-  }, [debouncedUpdateSearchParams, showSearchParams])
+  }, [applyUrlFilters, debouncedUpdateSearchParams])
 
   const handleQueryPlugins = useCallback((debounced?: boolean) => {
     handleUpdateSearchParams(debounced)

web/app/components/plugins/marketplace/plugin-type-switch.tsx

@@ -84,12 +84,14 @@ const PluginTypeSwitch = ({
   const handlePopState = useCallback(() => {
     if (!showSearchParams)
       return
+    // nuqs handles popstate automatically
     const url = new URL(window.location.href)
     const category = url.searchParams.get('category') || PLUGIN_TYPE_SEARCH_MAP.all
     handleActivePluginTypeChange(category)
   }, [showSearchParams, handleActivePluginTypeChange])
 
   useEffect(() => {
+    // nuqs manages popstate internally, but we keep this for URL sync
     window.addEventListener('popstate', handlePopState)
     return () => {
       window.removeEventListener('popstate', handlePopState)

web/app/components/plugins/marketplace/utils.ts

@@ -1,7 +1,6 @@
 import type {
   CollectionsAndPluginsSearchParams,
   MarketplaceCollection,
-  PluginsSearchParams,
 } from '@/app/components/plugins/marketplace/types'
 import type { Plugin } from '@/app/components/plugins/types'
 import { PluginCategoryEnum } from '@/app/components/plugins/types'
@@ -152,22 +151,3 @@ export const getMarketplaceListFilterType = (category: string) => {
 
   return 'plugin'
 }
-
-export const updateSearchParams = (pluginsSearchParams: PluginsSearchParams) => {
-  const { query, category, tags } = pluginsSearchParams
-  const url = new URL(window.location.href)
-  const categoryChanged = url.searchParams.get('category') !== category
-  if (query)
-    url.searchParams.set('q', query)
-  else
-    url.searchParams.delete('q')
-  if (category)
-    url.searchParams.set('category', category)
-  else
-    url.searchParams.delete('category')
-  if (tags && tags.length)
-    url.searchParams.set('tags', tags.join(','))
-  else
-    url.searchParams.delete('tags')
-  history[`${categoryChanged ? 'pushState' : 'replaceState'}`]({}, '', url)
-}

web/app/components/plugins/plugin-page/context.tsx

@@ -3,6 +3,7 @@
 import type { ReactNode, RefObject } from 'react'
 import type { FilterState } from './filter-management'
 import { noop } from 'es-toolkit/function'
+import { useQueryState } from 'nuqs'
 import {
   useMemo,
   useRef,
@@ -13,7 +14,6 @@ import {
   useContextSelector,
 } from 'use-context-selector'
 import { useGlobalPublicStore } from '@/context/global-public-context'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { PLUGIN_PAGE_TABS_MAP, usePluginPageTabs } from '../hooks'
 
 export type PluginPageContextValue = {
@@ -68,8 +68,8 @@ export const PluginPageContextProvider = ({
   const options = useMemo(() => {
     return enable_marketplace ? tabs : tabs.filter(tab => tab.value !== PLUGIN_PAGE_TABS_MAP.marketplace)
   }, [tabs, enable_marketplace])
-  const [activeTab, setActiveTab] = useTabSearchParams({
-    defaultTab: options[0].value,
+  const [activeTab, setActiveTab] = useQueryState('category', {
+    defaultValue: options[0].value,
   })
 
   return (

web/app/components/plugins/plugin-page/index.tsx

@@ -9,10 +9,6 @@ import {
 import { useBoolean } from 'ahooks'
 import { noop } from 'es-toolkit/function'
 import Link from 'next/link'
-import {
-  useRouter,
-  useSearchParams,
-} from 'next/navigation'
 import { useEffect, useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { useContext } from 'use-context-selector'
@@ -25,6 +21,7 @@ import { MARKETPLACE_API_PREFIX, SUPPORT_INSTALL_LOCAL_FILE_EXTENSIONS } from '@
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import I18n from '@/context/i18n'
 import useDocumentTitle from '@/hooks/use-document-title'
+import { usePluginInstallation } from '@/hooks/use-query-params'
 import { fetchBundleInfoFromMarketPlace, fetchManifestFromMarketPlace } from '@/service/plugins'
 import { sleep } from '@/utils'
 import { cn } from '@/utils/classnames'
@@ -42,9 +39,6 @@ import PluginTasks from './plugin-tasks'
 import useReferenceSetting from './use-reference-setting'
 import { useUploader } from './use-uploader'
 
-const PACKAGE_IDS_KEY = 'package-ids'
-const BUNDLE_INFO_KEY = 'bundle-info'
-
 export type PluginPageProps = {
   plugins: React.ReactNode
   marketplace: React.ReactNode
@@ -55,33 +49,13 @@ const PluginPage = ({
 }: PluginPageProps) => {
   const { t } = useTranslation()
   const { locale } = useContext(I18n)
-  const searchParams = useSearchParams()
-  const { replace } = useRouter()
   useDocumentTitle(t('plugin.metadata.title'))
 
-  // just support install one package now
-  const packageId = useMemo(() => {
-    const idStrings = searchParams.get(PACKAGE_IDS_KEY)
-    try {
-      return idStrings ? JSON.parse(idStrings)[0] : ''
-    }
-    catch {
-      return ''
-    }
-  }, [searchParams])
+  // Use nuqs hook for installation state
+  const [{ packageId, bundleInfo }, setInstallState] = usePluginInstallation()
 
   const [uniqueIdentifier, setUniqueIdentifier] = useState<string | null>(null)
-
   const [dependencies, setDependencies] = useState<Dependency[]>([])
-  const bundleInfo = useMemo(() => {
-    const info = searchParams.get(BUNDLE_INFO_KEY)
-    try {
-      return info ? JSON.parse(info) : undefined
-    }
-    catch {
-      return undefined
-    }
-  }, [searchParams])
 
   const [isShowInstallFromMarketplace, {
     setTrue: showInstallFromMarketplace,
@@ -90,11 +64,9 @@ const PluginPage = ({
 
   const hideInstallFromMarketplace = () => {
     doHideInstallFromMarketplace()
-    const url = new URL(window.location.href)
-    url.searchParams.delete(PACKAGE_IDS_KEY)
-    url.searchParams.delete(BUNDLE_INFO_KEY)
-    replace(url.toString())
+    setInstallState(null)
   }
+
   const [manifest, setManifest] = useState<PluginDeclaration | PluginManifestInMarket | null>(null)
 
   useEffect(() => {
@@ -114,12 +86,17 @@ const PluginPage = ({
         return
       }
       if (bundleInfo) {
-        const { data } = await fetchBundleInfoFromMarketPlace(bundleInfo)
-        setDependencies(data.version.dependencies)
-        showInstallFromMarketplace()
+        try {
+          const { data } = await fetchBundleInfoFromMarketPlace(bundleInfo)
+          setDependencies(data.version.dependencies)
+          showInstallFromMarketplace()
+        }
+        catch (error) {
+          console.error('Failed to load bundle info:', error)
+        }
       }
     })()
-  }, [packageId, bundleInfo])
+  }, [packageId, bundleInfo, showInstallFromMarketplace])
 
   const {
     referenceSetting,

web/app/components/sentry-initializer.tsx

@@ -3,14 +3,14 @@
 import * as Sentry from '@sentry/react'
 import { useEffect } from 'react'
 
-const isDevelopment = process.env.NODE_ENV === 'development'
+import { IS_DEV } from '@/config'
 
 const SentryInitializer = ({
   children,
 }: { children: React.ReactElement }) => {
   useEffect(() => {
     const SENTRY_DSN = document?.body?.getAttribute('data-public-sentry-dsn')
-    if (!isDevelopment && SENTRY_DSN) {
+    if (!IS_DEV && SENTRY_DSN) {
       Sentry.init({
         dsn: SENTRY_DSN,
         integrations: [

web/app/components/tools/edit-custom-collection-modal/index.tsx

@@ -48,6 +48,7 @@ const EditCustomCollectionModal: FC<Props> = ({
 
   const [editFirst, setEditFirst] = useState(!isAdd)
   const [paramsSchemas, setParamsSchemas] = useState<CustomParamSchema[]>(payload?.tools || [])
+  const [labels, setLabels] = useState<string[]>(payload?.labels || [])
   const [customCollection, setCustomCollection, getCustomCollection] = useGetState<CustomCollectionBackend>(isAdd
     ? {
         provider: '',
@@ -67,6 +68,15 @@ const EditCustomCollectionModal: FC<Props> = ({
 
   const originalProvider = isEdit ? payload.provider : ''
 
+  // Sync customCollection state when payload changes
+  useEffect(() => {
+    if (isEdit) {
+      setCustomCollection(payload)
+      setParamsSchemas(payload.tools || [])
+      setLabels(payload.labels || [])
+    }
+  }, [isEdit, payload])
+
   const [showEmojiPicker, setShowEmojiPicker] = useState(false)
   const emoji = customCollection.icon
   const setEmoji = (emoji: Emoji) => {
@@ -124,7 +134,6 @@ const EditCustomCollectionModal: FC<Props> = ({
   const [currTool, setCurrTool] = useState<CustomParamSchema | null>(null)
   const [isShowTestApi, setIsShowTestApi] = useState(false)
 
-  const [labels, setLabels] = useState<string[]>(payload?.labels || [])
   const handleLabelSelect = (value: string[]) => {
     setLabels(value)
   }

web/app/components/tools/provider-list.tsx

@@ -1,5 +1,6 @@
 'use client'
 import type { Collection } from './types'
+import { useQueryState } from 'nuqs'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Input from '@/app/components/base/input'
@@ -14,7 +15,6 @@ import CustomCreateCard from '@/app/components/tools/provider/custom-create-card
 import ProviderDetail from '@/app/components/tools/provider/detail'
 import WorkflowToolEmpty from '@/app/components/tools/provider/empty'
 import { useGlobalPublicStore } from '@/context/global-public-context'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { useCheckInstalled, useInvalidateInstalledPluginList } from '@/service/use-plugins'
 import { useAllToolProviders } from '@/service/use-tools'
 import { cn } from '@/utils/classnames'
@@ -45,8 +45,8 @@ const ProviderList = () => {
   const { enable_marketplace } = useGlobalPublicStore(s => s.systemFeatures)
   const containerRef = useRef<HTMLDivElement>(null)
 
-  const [activeTab, setActiveTab] = useTabSearchParams({
-    defaultTab: 'builtin',
+  const [activeTab, setActiveTab] = useQueryState('category', {
+    defaultValue: 'builtin',
   })
   const options = [
     { value: 'builtin', text: t('tools.type.builtIn') },

web/app/components/tools/provider/detail.tsx

@@ -100,9 +100,28 @@ const ProviderDetail = ({
   const [isShowEditCollectionToolModal, setIsShowEditCustomCollectionModal] = useState(false)
   const [showConfirmDelete, setShowConfirmDelete] = useState(false)
   const [deleteAction, setDeleteAction] = useState('')
+
+  const getCustomProvider = useCallback(async () => {
+    setIsDetailLoading(true)
+    const res = await fetchCustomCollection(collection.name)
+    if (res.credentials.auth_type === AuthType.apiKey && !res.credentials.api_key_header_prefix) {
+      if (res.credentials.api_key_value)
+        res.credentials.api_key_header_prefix = AuthHeaderPrefix.custom
+    }
+    setCustomCollection({
+      ...res,
+      labels: collection.labels,
+      provider: collection.name,
+    })
+    setIsDetailLoading(false)
+  }, [collection.labels, collection.name])
+
   const doUpdateCustomToolCollection = async (data: CustomCollectionBackend) => {
     await updateCustomCollection(data)
     onRefreshData()
+    await getCustomProvider()
+    // Use fresh data from form submission to avoid race condition with collection.labels
+    setCustomCollection(prev => prev ? { ...prev, labels: data.labels } : null)
     Toast.notify({
       type: 'success',
       message: t('common.api.actionSuccess'),
@@ -118,20 +137,6 @@ const ProviderDetail = ({
     })
     setIsShowEditCustomCollectionModal(false)
   }
-  const getCustomProvider = useCallback(async () => {
-    setIsDetailLoading(true)
-    const res = await fetchCustomCollection(collection.name)
-    if (res.credentials.auth_type === AuthType.apiKey && !res.credentials.api_key_header_prefix) {
-      if (res.credentials.api_key_value)
-        res.credentials.api_key_header_prefix = AuthHeaderPrefix.custom
-    }
-    setCustomCollection({
-      ...res,
-      labels: collection.labels,
-      provider: collection.name,
-    })
-    setIsDetailLoading(false)
-  }, [collection.labels, collection.name])
   // workflow provider
   const [isShowEditWorkflowToolModal, setIsShowEditWorkflowToolModal] = useState(false)
   const getWorkflowToolProvider = useCallback(async () => {

web/app/components/workflow/index.tsx

@@ -35,6 +35,7 @@ import ReactFlow, {
   useReactFlow,
   useStoreApi,
 } from 'reactflow'
+import { IS_DEV } from '@/config'
 import { useEventEmitterContextContext } from '@/context/event-emitter'
 import {
   useAllBuiltInTools,
@@ -361,7 +362,7 @@ export const Workflow: FC<WorkflowProps> = memo(({
     }
   }, [schemaTypeDefinitions, fetchInspectVars, isLoadedVars, vars, customTools, buildInTools, workflowTools, mcpTools, dataSourceList])
 
-  if (process.env.NODE_ENV === 'development') {
+  if (IS_DEV) {
     store.getState().onError = (code, message) => {
       if (code === '002')
         return

web/app/dev-preview/page.tsx

@@ -1,68 +0,0 @@
-'use client'
-import BaseForm from '../components/base/form/form-scenarios/base'
-import { BaseFieldType } from '../components/base/form/form-scenarios/base/types'
-
-export default function Page() {
-  return (
-    <div className="flex h-screen w-full items-center justify-center p-20">
-      <div className="w-[400px] rounded-lg border border-components-panel-border bg-components-panel-bg">
-        <BaseForm
-          initialData={{
-            type: 'option_1',
-            variable: 'test',
-            label: 'Test',
-            maxLength: 48,
-            required: true,
-          }}
-          configurations={[
-            {
-              type: BaseFieldType.textInput,
-              variable: 'variable',
-              label: 'Variable',
-              required: true,
-              showConditions: [],
-            },
-            {
-              type: BaseFieldType.textInput,
-              variable: 'label',
-              label: 'Label',
-              required: true,
-              showConditions: [],
-            },
-            {
-              type: BaseFieldType.numberInput,
-              variable: 'maxLength',
-              label: 'Max Length',
-              required: true,
-              showConditions: [],
-              max: 100,
-              min: 1,
-            },
-            {
-              type: BaseFieldType.checkbox,
-              variable: 'required',
-              label: 'Required',
-              required: true,
-              showConditions: [],
-            },
-            {
-              type: BaseFieldType.select,
-              variable: 'type',
-              label: 'Type',
-              required: true,
-              showConditions: [],
-              options: [
-                { label: 'Option 1', value: 'option_1' },
-                { label: 'Option 2', value: 'option_2' },
-                { label: 'Option 3', value: 'option_3' },
-              ],
-            },
-          ]}
-          onSubmit={(value) => {
-            console.log('onSubmit', value)
-          }}
-        />
-      </div>
-    </div>
-  )
-}

web/app/education-apply/constants.ts

@@ -1,4 +1,3 @@
 export const EDUCATION_VERIFY_URL_SEARCHPARAMS_ACTION = 'getEducationVerify'
 export const EDUCATION_VERIFYING_LOCALSTORAGE_ITEM = 'educationVerifying'
-export const EDUCATION_PRICING_SHOW_ACTION = 'educationPricing'
 export const EDUCATION_RE_VERIFY_ACTION = 'educationReVerify'

web/app/education-apply/hooks.ts

@@ -15,7 +15,6 @@ import { useModalContextSelector } from '@/context/modal-context'
 import { useProviderContext } from '@/context/provider-context'
 import { useEducationAutocomplete, useEducationVerify } from '@/service/use-education'
 import {
-  EDUCATION_PRICING_SHOW_ACTION,
   EDUCATION_RE_VERIFY_ACTION,
   EDUCATION_VERIFY_URL_SEARCHPARAMS_ACTION,
   EDUCATION_VERIFYING_LOCALSTORAGE_ITEM,
@@ -133,7 +132,6 @@ const useEducationReverifyNotice = ({
 
 export const useEducationInit = () => {
   const setShowAccountSettingModal = useModalContextSelector(s => s.setShowAccountSettingModal)
-  const setShowPricingModal = useModalContextSelector(s => s.setShowPricingModal)
   const setShowEducationExpireNoticeModal = useModalContextSelector(s => s.setShowEducationExpireNoticeModal)
   const educationVerifying = localStorage.getItem(EDUCATION_VERIFYING_LOCALSTORAGE_ITEM)
   const searchParams = useSearchParams()
@@ -160,8 +158,6 @@ export const useEducationInit = () => {
       if (educationVerifyAction === EDUCATION_VERIFY_URL_SEARCHPARAMS_ACTION)
         localStorage.setItem(EDUCATION_VERIFYING_LOCALSTORAGE_ITEM, 'yes')
     }
-    if (educationVerifyAction === EDUCATION_PRICING_SHOW_ACTION)
-      setShowPricingModal()
     if (educationVerifyAction === EDUCATION_RE_VERIFY_ACTION)
       handleVerify()
   }, [setShowAccountSettingModal, educationVerifying, educationVerifyAction])

web/app/layout.tsx

@@ -1,6 +1,7 @@
 import type { Viewport } from 'next'
 import { ThemeProvider } from 'next-themes'
 import { Instrument_Serif } from 'next/font/google'
+import { NuqsAdapter } from 'nuqs/adapters/next/app'
 import GlobalPublicStoreProvider from '@/context/global-public-context'
 import { TanstackQueryInitializer } from '@/context/query-client'
 import { getLocaleOnServer } from '@/i18n-config/server'
@@ -97,17 +98,19 @@ const LocaleLayout = async ({
           disableTransitionOnChange
           enableColorScheme={false}
         >
-          <BrowserInitializer>
-            <SentryInitializer>
-              <TanstackQueryInitializer>
-                <I18nServer>
-                  <GlobalPublicStoreProvider>
-                    {children}
-                  </GlobalPublicStoreProvider>
-                </I18nServer>
-              </TanstackQueryInitializer>
-            </SentryInitializer>
-          </BrowserInitializer>
+          <NuqsAdapter>
+            <BrowserInitializer>
+              <SentryInitializer>
+                <TanstackQueryInitializer>
+                  <I18nServer>
+                    <GlobalPublicStoreProvider>
+                      {children}
+                    </GlobalPublicStoreProvider>
+                  </I18nServer>
+                </TanstackQueryInitializer>
+              </SentryInitializer>
+            </BrowserInitializer>
+          </NuqsAdapter>
         </ThemeProvider>
         <RoutePrefixHandle />
       </body>

web/context/modal-context.test.tsx

@@ -1,4 +1,5 @@
 import { act, render, screen, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import * as React from 'react'
 import { defaultPlan } from '@/app/components/billing/config'
 import { Plan } from '@/app/components/billing/type'
@@ -72,9 +73,11 @@ const createPlan = (overrides: PlanOverrides = {}): PlanShape => ({
 })
 
 const renderProvider = () => render(
-  <ModalContextProvider>
-    <div data-testid="modal-context-test-child" />
-  </ModalContextProvider>,
+  <NuqsTestingAdapter>
+    <ModalContextProvider>
+      <div data-testid="modal-context-test-child" />
+    </ModalContextProvider>
+  </NuqsTestingAdapter>,
 )
 
 describe('ModalContextProvider trigger events limit modal', () => {

web/context/modal-context.tsx

@@ -24,21 +24,22 @@ import type {
 import type { ModerationConfig, PromptVariable } from '@/models/debug'
 import { noop } from 'es-toolkit/function'
 import dynamic from 'next/dynamic'
-import { useSearchParams } from 'next/navigation'
-import { useCallback, useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { createContext, useContext, useContextSelector } from 'use-context-selector'
 import {
-  ACCOUNT_SETTING_MODAL_ACTION,
   DEFAULT_ACCOUNT_SETTING_TAB,
   isValidAccountSettingTab,
 } from '@/app/components/header/account-setting/constants'
 import {
-  EDUCATION_PRICING_SHOW_ACTION,
   EDUCATION_VERIFYING_LOCALSTORAGE_ITEM,
 } from '@/app/education-apply/constants'
 import { useAppContext } from '@/context/app-context'
 import { useProviderContext } from '@/context/provider-context'
-import { removeSpecificQueryParam } from '@/utils'
+import {
+  useAccountSettingModal,
+  usePricingModal,
+} from '@/hooks/use-query-params'
+
 import {
 
   useTriggerEventsLimitModal,
@@ -125,8 +126,6 @@ export type ModalContextState = {
   setShowEducationExpireNoticeModal: Dispatch<SetStateAction<ModalState<ExpireNoticeModalPayloadProps> | null>>
   setShowTriggerEventsLimitModal: Dispatch<SetStateAction<ModalState<TriggerEventsLimitModalPayload> | null>>
 }
-const PRICING_MODAL_QUERY_PARAM = 'pricing'
-const PRICING_MODAL_QUERY_VALUE = 'open'
 
 const ModalContext = createContext<ModalContextState>({
   setShowAccountSettingModal: noop,
@@ -157,16 +156,16 @@ type ModalContextProviderProps = {
 export const ModalContextProvider = ({
   children,
 }: ModalContextProviderProps) => {
-  const searchParams = useSearchParams()
+  // Use nuqs hooks for URL-based modal state management
+  const [showPricingModal, setPricingModalOpen] = usePricingModal()
+  const [urlAccountModalState, setUrlAccountModalState] = useAccountSettingModal<AccountSettingTab>()
 
-  const [showAccountSettingModal, setShowAccountSettingModal] = useState<ModalState<AccountSettingTab> | null>(() => {
-    if (searchParams.get('action') === ACCOUNT_SETTING_MODAL_ACTION) {
-      const tabParam = searchParams.get('tab')
-      const tab = isValidAccountSettingTab(tabParam) ? tabParam : DEFAULT_ACCOUNT_SETTING_TAB
-      return { payload: tab }
-    }
-    return null
-  })
+  const accountSettingCallbacksRef = useRef<Omit<ModalState<AccountSettingTab>, 'payload'> | null>(null)
+  const accountSettingTab = urlAccountModalState.isOpen
+    ? (isValidAccountSettingTab(urlAccountModalState.payload)
+        ? urlAccountModalState.payload
+        : DEFAULT_ACCOUNT_SETTING_TAB)
+    : null
   const [showApiBasedExtensionModal, setShowApiBasedExtensionModal] = useState<ModalState<ApiBasedExtension> | null>(null)
   const [showModerationSettingModal, setShowModerationSettingModal] = useState<ModalState<ModerationConfig> | null>(null)
   const [showExternalDataToolModal, setShowExternalDataToolModal] = useState<ModalState<ExternalDataTool> | null>(null)
@@ -182,9 +181,6 @@ export const ModalContextProvider = ({
   const [showEducationExpireNoticeModal, setShowEducationExpireNoticeModal] = useState<ModalState<ExpireNoticeModalPayloadProps> | null>(null)
   const { currentWorkspace } = useAppContext()
 
-  const [showPricingModal, setShowPricingModal] = useState(
-    searchParams.get(PRICING_MODAL_QUERY_PARAM) === PRICING_MODAL_QUERY_VALUE,
-  )
   const [showAnnotationFullModal, setShowAnnotationFullModal] = useState(false)
   const handleCancelAccountSettingModal = () => {
     const educationVerifying = localStorage.getItem(EDUCATION_VERIFYING_LOCALSTORAGE_ITEM)
@@ -192,54 +188,34 @@ export const ModalContextProvider = ({
     if (educationVerifying === 'yes')
       localStorage.removeItem(EDUCATION_VERIFYING_LOCALSTORAGE_ITEM)
 
-    removeSpecificQueryParam('action')
-    removeSpecificQueryParam('tab')
-    setShowAccountSettingModal(null)
-    if (showAccountSettingModal?.onCancelCallback)
-      showAccountSettingModal?.onCancelCallback()
+    accountSettingCallbacksRef.current?.onCancelCallback?.()
+    accountSettingCallbacksRef.current = null
+    setUrlAccountModalState(null)
   }
 
   const handleAccountSettingTabChange = useCallback((tab: AccountSettingTab) => {
-    setShowAccountSettingModal((prev) => {
-      if (!prev)
-        return { payload: tab }
-      if (prev.payload === tab)
-        return prev
-      return { ...prev, payload: tab }
-    })
-  }, [setShowAccountSettingModal])
+    setUrlAccountModalState({ payload: tab })
+  }, [setUrlAccountModalState])
+
+  const setShowAccountSettingModal = useCallback((next: SetStateAction<ModalState<AccountSettingTab> | null>) => {
+    const currentState = accountSettingTab
+      ? { payload: accountSettingTab, ...(accountSettingCallbacksRef.current ?? {}) }
+      : null
+    const resolvedState = typeof next === 'function' ? next(currentState) : next
+    if (!resolvedState) {
+      accountSettingCallbacksRef.current = null
+      setUrlAccountModalState(null)
+      return
+    }
+    const { payload, ...callbacks } = resolvedState
+    accountSettingCallbacksRef.current = callbacks
+    setUrlAccountModalState({ payload })
+  }, [accountSettingTab, setUrlAccountModalState])
 
   useEffect(() => {
-    if (typeof window === 'undefined')
-      return
-    const url = new URL(window.location.href)
-    if (!showAccountSettingModal?.payload) {
-      if (url.searchParams.get('action') !== ACCOUNT_SETTING_MODAL_ACTION)
-        return
-      url.searchParams.delete('action')
-      url.searchParams.delete('tab')
-      window.history.replaceState(null, '', url.toString())
-      return
-    }
-    url.searchParams.set('action', ACCOUNT_SETTING_MODAL_ACTION)
-    url.searchParams.set('tab', showAccountSettingModal.payload)
-    window.history.replaceState(null, '', url.toString())
-  }, [showAccountSettingModal])
-
-  useEffect(() => {
-    if (typeof window === 'undefined')
-      return
-    const url = new URL(window.location.href)
-    if (showPricingModal) {
-      url.searchParams.set(PRICING_MODAL_QUERY_PARAM, PRICING_MODAL_QUERY_VALUE)
-    }
-    else {
-      url.searchParams.delete(PRICING_MODAL_QUERY_PARAM)
-      if (url.searchParams.get('action') === EDUCATION_PRICING_SHOW_ACTION)
-        url.searchParams.delete('action')
-    }
-    window.history.replaceState(null, '', url.toString())
-  }, [showPricingModal])
+    if (!urlAccountModalState.isOpen)
+      accountSettingCallbacksRef.current = null
+  }, [urlAccountModalState.isOpen])
 
   const { plan, isFetchedPlan } = useProviderContext()
   const {
@@ -337,12 +313,12 @@ export const ModalContextProvider = ({
   }
 
   const handleShowPricingModal = useCallback(() => {
-    setShowPricingModal(true)
-  }, [])
+    setPricingModalOpen(true)
+  }, [setPricingModalOpen])
 
   const handleCancelPricingModal = useCallback(() => {
-    setShowPricingModal(false)
-  }, [])
+    setPricingModalOpen(false)
+  }, [setPricingModalOpen])
 
   return (
     <ModalContext.Provider value={{
@@ -364,9 +340,9 @@ export const ModalContextProvider = ({
       <>
         {children}
         {
-          !!showAccountSettingModal && (
+          accountSettingTab && (
             <AccountSetting
-              activeTab={showAccountSettingModal.payload}
+              activeTab={accountSettingTab}
               onCancel={handleCancelAccountSettingModal}
               onTabChange={handleAccountSettingTabChange}
             />

web/context/query-client.tsx

@@ -2,7 +2,14 @@
 
 import type { FC, PropsWithChildren } from 'react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import { lazy, Suspense } from 'react'
+import { IS_DEV } from '@/config'
+
+const TanStackDevtoolsWrapper = lazy(() =>
+  import('@/app/components/devtools').then(module => ({
+    default: module.TanStackDevtoolsWrapper,
+  })),
+)
 
 const STALE_TIME = 1000 * 60 * 30 // 30 minutes
 
@@ -19,7 +26,11 @@ export const TanstackQueryInitializer: FC<PropsWithChildren> = (props) => {
   return (
     <QueryClientProvider client={client}>
       {children}
-      <ReactQueryDevtools initialIsOpen={false} />
+      {IS_DEV && (
+        <Suspense fallback={null}>
+          <TanStackDevtoolsWrapper />
+        </Suspense>
+      )}
     </QueryClientProvider>
   )
 }

web/hooks/use-query-params.spec.tsx

@@ -0,0 +1,647 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { ACCOUNT_SETTING_MODAL_ACTION } from '@/app/components/header/account-setting/constants'
+import {
+  clearQueryParams,
+  PRICING_MODAL_QUERY_PARAM,
+  PRICING_MODAL_QUERY_VALUE,
+  useAccountSettingModal,
+  useMarketplaceFilters,
+  usePluginInstallation,
+  usePricingModal,
+} from './use-query-params'
+
+const renderWithAdapter = <T,>(hook: () => T, searchParams = '') => {
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  const { result } = renderHook(hook, { wrapper })
+  return { result, onUrlUpdate }
+}
+
+// Query param hooks: defaults, parsing, and URL sync behavior.
+describe('useQueryParams hooks', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Pricing modal query behavior.
+  describe('usePricingModal', () => {
+    it('should return closed state when query param is missing', () => {
+      // Arrange
+      const { result } = renderWithAdapter(() => usePricingModal())
+
+      // Act
+      const [isOpen] = result.current
+
+      // Assert
+      expect(isOpen).toBe(false)
+    })
+
+    it('should return open state when query param matches open value', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => usePricingModal(),
+        `?${PRICING_MODAL_QUERY_PARAM}=${PRICING_MODAL_QUERY_VALUE}`,
+      )
+
+      // Act
+      const [isOpen] = result.current
+
+      // Assert
+      expect(isOpen).toBe(true)
+    })
+
+    it('should return closed state when query param has unexpected value', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => usePricingModal(),
+        `?${PRICING_MODAL_QUERY_PARAM}=closed`,
+      )
+
+      // Act
+      const [isOpen] = result.current
+
+      // Assert
+      expect(isOpen).toBe(false)
+    })
+
+    it('should set pricing param when opening', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => usePricingModal())
+
+      // Act
+      act(() => {
+        result.current[1](true)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get(PRICING_MODAL_QUERY_PARAM)).toBe(PRICING_MODAL_QUERY_VALUE)
+    })
+
+    it('should use push history when opening', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => usePricingModal())
+
+      // Act
+      act(() => {
+        result.current[1](true)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('push')
+    })
+
+    it('should clear pricing param when closing', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => usePricingModal(),
+        `?${PRICING_MODAL_QUERY_PARAM}=${PRICING_MODAL_QUERY_VALUE}`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1](false)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has(PRICING_MODAL_QUERY_PARAM)).toBe(false)
+    })
+
+    it('should use push history when closing', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => usePricingModal(),
+        `?${PRICING_MODAL_QUERY_PARAM}=${PRICING_MODAL_QUERY_VALUE}`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1](false)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('push')
+    })
+
+    it('should respect explicit history options when provided', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => usePricingModal())
+
+      // Act
+      act(() => {
+        result.current[1](true, { history: 'replace' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('replace')
+    })
+  })
+
+  // Account settings modal query behavior.
+  describe('useAccountSettingModal', () => {
+    it('should return closed state with null payload when query params are missing', () => {
+      // Arrange
+      const { result } = renderWithAdapter(() => useAccountSettingModal())
+
+      // Act
+      const [state] = result.current
+
+      // Assert
+      expect(state.isOpen).toBe(false)
+      expect(state.payload).toBeNull()
+    })
+
+    it('should return open state when action matches', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => useAccountSettingModal(),
+        `?action=${ACCOUNT_SETTING_MODAL_ACTION}&tab=billing`,
+      )
+
+      // Act
+      const [state] = result.current
+
+      // Assert
+      expect(state.isOpen).toBe(true)
+      expect(state.payload).toBe('billing')
+    })
+
+    it('should return closed state when action does not match', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => useAccountSettingModal(),
+        '?action=other&tab=billing',
+      )
+
+      // Act
+      const [state] = result.current
+
+      // Assert
+      expect(state.isOpen).toBe(false)
+      expect(state.payload).toBeNull()
+    })
+
+    it('should set action and tab when opening', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => useAccountSettingModal())
+
+      // Act
+      act(() => {
+        result.current[1]({ payload: 'members' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('action')).toBe(ACCOUNT_SETTING_MODAL_ACTION)
+      expect(update.searchParams.get('tab')).toBe('members')
+    })
+
+    it('should use push history when opening from closed state', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => useAccountSettingModal())
+
+      // Act
+      act(() => {
+        result.current[1]({ payload: 'members' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('push')
+    })
+
+    it('should update tab when switching while open', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useAccountSettingModal(),
+        `?action=${ACCOUNT_SETTING_MODAL_ACTION}&tab=billing`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ payload: 'provider' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('tab')).toBe('provider')
+    })
+
+    it('should use replace history when switching tabs while open', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useAccountSettingModal(),
+        `?action=${ACCOUNT_SETTING_MODAL_ACTION}&tab=billing`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ payload: 'provider' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('replace')
+    })
+
+    it('should clear action and tab when closing', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useAccountSettingModal(),
+        `?action=${ACCOUNT_SETTING_MODAL_ACTION}&tab=billing`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1](null)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('action')).toBe(false)
+      expect(update.searchParams.has('tab')).toBe(false)
+    })
+
+    it('should use replace history when closing', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useAccountSettingModal(),
+        `?action=${ACCOUNT_SETTING_MODAL_ACTION}&tab=billing`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1](null)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('replace')
+    })
+  })
+
+  // Marketplace filters query behavior.
+  describe('useMarketplaceFilters', () => {
+    it('should return default filters when query params are missing', () => {
+      // Arrange
+      const { result } = renderWithAdapter(() => useMarketplaceFilters())
+
+      // Act
+      const [filters] = result.current
+
+      // Assert
+      expect(filters.q).toBe('')
+      expect(filters.category).toBe('all')
+      expect(filters.tags).toEqual([])
+    })
+
+    it('should parse filters when query params are present', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?q=prompt&category=tool&tags=ai,ml',
+      )
+
+      // Act
+      const [filters] = result.current
+
+      // Assert
+      expect(filters.q).toBe('prompt')
+      expect(filters.category).toBe('tool')
+      expect(filters.tags).toEqual(['ai', 'ml'])
+    })
+
+    it('should treat empty tags param as empty array', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?tags=',
+      )
+
+      // Act
+      const [filters] = result.current
+
+      // Assert
+      expect(filters.tags).toEqual([])
+    })
+
+    it('should preserve other filters when updating a single field', async () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?category=tool&tags=ai,ml',
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ q: 'search' })
+      })
+
+      // Assert
+      await waitFor(() => expect(result.current[0].q).toBe('search'))
+      expect(result.current[0].category).toBe('tool')
+      expect(result.current[0].tags).toEqual(['ai', 'ml'])
+    })
+
+    it('should clear q param when q is empty', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?q=search',
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ q: '' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('q')).toBe(false)
+    })
+
+    it('should serialize tags as comma-separated values', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => useMarketplaceFilters())
+
+      // Act
+      act(() => {
+        result.current[1]({ tags: ['ai', 'ml'] })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('tags')).toBe('ai,ml')
+    })
+
+    it('should remove tags param when list is empty', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?tags=ai,ml',
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ tags: [] })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('tags')).toBe(false)
+    })
+
+    it('should keep category in the URL when set to default', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?category=tool',
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ category: 'all' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('category')).toBe('all')
+    })
+
+    it('should clear all marketplace filters when set to null', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => useMarketplaceFilters(),
+        '?q=search&category=tool&tags=ai,ml',
+      )
+
+      // Act
+      act(() => {
+        result.current[1](null)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('q')).toBe(false)
+      expect(update.searchParams.has('category')).toBe(false)
+      expect(update.searchParams.has('tags')).toBe(false)
+    })
+
+    it('should use replace history when updating filters', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => useMarketplaceFilters())
+
+      // Act
+      act(() => {
+        result.current[1]({ q: 'search' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('replace')
+    })
+  })
+
+  // Plugin installation query behavior.
+  describe('usePluginInstallation', () => {
+    it('should parse package ids from JSON arrays', () => {
+      // Arrange
+      const bundleInfo = { org: 'org', name: 'bundle', version: '1.0.0' }
+      const { result } = renderWithAdapter(
+        () => usePluginInstallation(),
+        `?package-ids=%5B%22org%2Fplugin%22%5D&bundle-info=${encodeURIComponent(JSON.stringify(bundleInfo))}`,
+      )
+
+      // Act
+      const [state] = result.current
+
+      // Assert
+      expect(state.packageId).toBe('org/plugin')
+      expect(state.bundleInfo).toEqual(bundleInfo)
+    })
+
+    it('should return raw package id when JSON parsing fails', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => usePluginInstallation(),
+        '?package-ids=org/plugin',
+      )
+
+      // Act
+      const [state] = result.current
+
+      // Assert
+      expect(state.packageId).toBe('org/plugin')
+    })
+
+    it('should return raw package id when JSON is not an array', () => {
+      // Arrange
+      const { result } = renderWithAdapter(
+        () => usePluginInstallation(),
+        '?package-ids=%22org%2Fplugin%22',
+      )
+
+      // Act
+      const [state] = result.current
+
+      // Assert
+      expect(state.packageId).toBe('"org/plugin"')
+    })
+
+    it('should write package ids as JSON arrays when setting packageId', async () => {
+      // Arrange
+      const { result, onUrlUpdate } = renderWithAdapter(() => usePluginInstallation())
+
+      // Act
+      act(() => {
+        result.current[1]({ packageId: 'org/plugin' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('package-ids')).toBe('["org/plugin"]')
+    })
+
+    it('should set bundle info when provided', async () => {
+      // Arrange
+      const bundleInfo = { org: 'org', name: 'bundle', version: '1.0.0' }
+      const { result, onUrlUpdate } = renderWithAdapter(() => usePluginInstallation())
+
+      // Act
+      act(() => {
+        result.current[1]({ bundleInfo })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('bundle-info')).toBe(JSON.stringify(bundleInfo))
+    })
+
+    it('should clear installation params when state is null', async () => {
+      // Arrange
+      const bundleInfo = { org: 'org', name: 'bundle', version: '1.0.0' }
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => usePluginInstallation(),
+        `?package-ids=%5B%22org%2Fplugin%22%5D&bundle-info=${encodeURIComponent(JSON.stringify(bundleInfo))}`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1](null)
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('package-ids')).toBe(false)
+      expect(update.searchParams.has('bundle-info')).toBe(false)
+    })
+
+    it('should preserve bundle info when only packageId is updated', async () => {
+      // Arrange
+      const bundleInfo = { org: 'org', name: 'bundle', version: '1.0.0' }
+      const { result, onUrlUpdate } = renderWithAdapter(
+        () => usePluginInstallation(),
+        `?bundle-info=${encodeURIComponent(JSON.stringify(bundleInfo))}`,
+      )
+
+      // Act
+      act(() => {
+        result.current[1]({ packageId: 'org/plugin' })
+      })
+
+      // Assert
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('bundle-info')).toBe(JSON.stringify(bundleInfo))
+    })
+  })
+})
+
+// Utility to clear query params from the current URL.
+describe('clearQueryParams', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    window.history.replaceState(null, '', '/')
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('should remove a single key when provided one key', () => {
+    // Arrange
+    const replaceSpy = vi.spyOn(window.history, 'replaceState')
+    window.history.pushState(null, '', '/?foo=1&bar=2')
+
+    // Act
+    clearQueryParams('foo')
+
+    // Assert
+    expect(replaceSpy).toHaveBeenCalled()
+    const params = new URLSearchParams(window.location.search)
+    expect(params.has('foo')).toBe(false)
+    expect(params.get('bar')).toBe('2')
+    replaceSpy.mockRestore()
+  })
+
+  it('should remove multiple keys when provided an array', () => {
+    // Arrange
+    const replaceSpy = vi.spyOn(window.history, 'replaceState')
+    window.history.pushState(null, '', '/?foo=1&bar=2&baz=3')
+
+    // Act
+    clearQueryParams(['foo', 'baz'])
+
+    // Assert
+    expect(replaceSpy).toHaveBeenCalled()
+    const params = new URLSearchParams(window.location.search)
+    expect(params.has('foo')).toBe(false)
+    expect(params.has('baz')).toBe(false)
+    expect(params.get('bar')).toBe('2')
+    replaceSpy.mockRestore()
+  })
+
+  it('should no-op when window is undefined', () => {
+    // Arrange
+    const replaceSpy = vi.spyOn(window.history, 'replaceState')
+    vi.stubGlobal('window', undefined)
+
+    // Act
+    expect(() => clearQueryParams('foo')).not.toThrow()
+
+    // Assert
+    expect(replaceSpy).not.toHaveBeenCalled()
+    replaceSpy.mockRestore()
+  })
+})

web/hooks/use-query-params.ts

@@ -0,0 +1,222 @@
+'use client'
+
+/**
+ * Centralized URL query parameter management hooks using nuqs
+ *
+ * This file provides type-safe, performant query parameter management
+ * that doesn't trigger full page refreshes (shallow routing).
+ *
+ * Best practices from nuqs documentation:
+ * - Use useQueryState for single parameters
+ * - Use useQueryStates for multiple related parameters (atomic updates)
+ * - Always provide parsers with defaults for type safety
+ * - Use shallow routing to avoid unnecessary re-renders
+ */
+
+import {
+  createParser,
+  parseAsArrayOf,
+  parseAsString,
+  useQueryState,
+  useQueryStates,
+} from 'nuqs'
+import { useCallback } from 'react'
+import { ACCOUNT_SETTING_MODAL_ACTION } from '@/app/components/header/account-setting/constants'
+
+/**
+ * Modal State Query Parameters
+ * Manages modal visibility and configuration via URL
+ */
+export const PRICING_MODAL_QUERY_PARAM = 'pricing'
+export const PRICING_MODAL_QUERY_VALUE = 'open'
+const parseAsPricingModal = createParser<boolean>({
+  parse: value => (value === PRICING_MODAL_QUERY_VALUE ? true : null),
+  serialize: value => (value ? PRICING_MODAL_QUERY_VALUE : ''),
+})
+  .withDefault(false)
+  .withOptions({ history: 'push' })
+
+/**
+ * Hook to manage pricing modal state via URL
+ * @returns [isOpen, setIsOpen] - Tuple like useState
+ *
+ * @example
+ * const [isOpen, setIsOpen] = usePricingModal()
+ * setIsOpen(true) // Sets ?pricing=open
+ * setIsOpen(false) // Removes ?pricing
+ */
+export function usePricingModal() {
+  return useQueryState(
+    PRICING_MODAL_QUERY_PARAM,
+    parseAsPricingModal,
+  )
+}
+
+/**
+ * Hook to manage account setting modal state via URL
+ * @returns [state, setState] - Object with isOpen + payload (tab) and setter
+ *
+ * @example
+ * const [accountModalState, setAccountModalState] = useAccountSettingModal()
+ * setAccountModalState({ payload: 'billing' }) // Sets ?action=showSettings&tab=billing
+ * setAccountModalState(null) // Removes both params
+ */
+export function useAccountSettingModal<T extends string = string>() {
+  const [accountState, setAccountState] = useQueryStates(
+    {
+      action: parseAsString,
+      tab: parseAsString,
+    },
+    {
+      history: 'replace',
+    },
+  )
+
+  const setState = useCallback(
+    (state: { payload: T } | null) => {
+      if (!state) {
+        setAccountState({ action: null, tab: null }, { history: 'replace' })
+        return
+      }
+      const shouldPush = accountState.action !== ACCOUNT_SETTING_MODAL_ACTION
+      setAccountState(
+        { action: ACCOUNT_SETTING_MODAL_ACTION, tab: state.payload },
+        { history: shouldPush ? 'push' : 'replace' },
+      )
+    },
+    [accountState.action, setAccountState],
+  )
+
+  const isOpen = accountState.action === ACCOUNT_SETTING_MODAL_ACTION
+  const currentTab = (isOpen ? accountState.tab : null) as T | null
+
+  return [{ isOpen, payload: currentTab }, setState] as const
+}
+
+/**
+ * Marketplace Search Query Parameters
+ */
+export type MarketplaceFilters = {
+  q: string // search query
+  category: string // plugin category
+  tags: string[] // array of tags
+}
+
+/**
+ * Hook to manage marketplace search/filter state via URL
+ * Provides atomic updates - all params update together
+ *
+ * @example
+ * const [filters, setFilters] = useMarketplaceFilters()
+ * setFilters({ q: 'search', category: 'tool', tags: ['ai'] }) // Updates all at once
+ * setFilters({ q: '' }) // Only updates q, keeps others
+ * setFilters(null) // Clears all marketplace params
+ */
+export function useMarketplaceFilters() {
+  return useQueryStates(
+    {
+      q: parseAsString.withDefault(''),
+      category: parseAsString.withDefault('all').withOptions({ clearOnDefault: false }),
+      tags: parseAsArrayOf(parseAsString).withDefault([]),
+    },
+    {
+      // Update URL without pushing to history (replaceState behavior)
+      history: 'replace',
+    },
+  )
+}
+
+/**
+ * Plugin Installation Query Parameters
+ */
+const PACKAGE_IDS_PARAM = 'package-ids'
+const BUNDLE_INFO_PARAM = 'bundle-info'
+type BundleInfoQuery = {
+  org: string
+  name: string
+  version: string
+}
+
+const parseAsPackageId = createParser<string>({
+  parse: (value) => {
+    try {
+      const parsed = JSON.parse(value)
+      if (Array.isArray(parsed)) {
+        const first = parsed[0]
+        return typeof first === 'string' ? first : null
+      }
+      return value
+    }
+    catch {
+      return value
+    }
+  },
+  serialize: value => JSON.stringify([value]),
+})
+
+const parseAsBundleInfo = createParser<BundleInfoQuery>({
+  parse: (value) => {
+    try {
+      const parsed = JSON.parse(value) as Partial<BundleInfoQuery>
+      if (parsed
+        && typeof parsed.org === 'string'
+        && typeof parsed.name === 'string'
+        && typeof parsed.version === 'string') {
+        return { org: parsed.org, name: parsed.name, version: parsed.version }
+      }
+    }
+    catch {
+      return null
+    }
+    return null
+  },
+  serialize: value => JSON.stringify(value),
+})
+
+/**
+ * Hook to manage plugin installation state via URL
+ * @returns [installState, setInstallState] - installState includes parsed packageId and bundleInfo
+ *
+ * @example
+ * const [installState, setInstallState] = usePluginInstallation()
+ * setInstallState({ packageId: 'org/plugin' }) // Sets ?package-ids=["org/plugin"]
+ * setInstallState({ bundleInfo: { org: 'org', name: 'bundle', version: '1.0.0' } }) // Sets ?bundle-info=...
+ * setInstallState(null) // Clears installation params
+ */
+export function usePluginInstallation() {
+  return useQueryStates(
+    {
+      packageId: parseAsPackageId,
+      bundleInfo: parseAsBundleInfo,
+    },
+    {
+      urlKeys: {
+        packageId: PACKAGE_IDS_PARAM,
+        bundleInfo: BUNDLE_INFO_PARAM,
+      },
+    },
+  )
+}
+
+/**
+ * Utility to clear specific query parameters from URL
+ * This is a client-side utility that should be called from client components
+ *
+ * @param keys - Single key or array of keys to remove from URL
+ *
+ * @example
+ * // In a client component
+ * clearQueryParams('param1')
+ * clearQueryParams(['param1', 'param2'])
+ */
+export function clearQueryParams(keys: string | string[]) {
+  if (typeof window === 'undefined')
+    return
+
+  const url = new URL(window.location.href)
+  const keysArray = Array.isArray(keys) ? keys : [keys]
+
+  keysArray.forEach(key => url.searchParams.delete(key))
+
+  window.history.replaceState(null, '', url.toString())
+}

web/hooks/use-tab-searchparams.spec.ts

@@ -1,545 +0,0 @@
-import type { Mock } from 'vitest'
-/**
- * Test suite for useTabSearchParams hook
- *
- * This hook manages tab state through URL search parameters, enabling:
- * - Bookmarkable tab states (users can share URLs with specific tabs active)
- * - Browser history integration (back/forward buttons work with tabs)
- * - Configurable routing behavior (push vs replace)
- * - Optional search parameter syncing (can disable URL updates)
- *
- * The hook syncs a local tab state with URL search parameters, making tab
- * navigation persistent and shareable across sessions.
- */
-import { act, renderHook } from '@testing-library/react'
-// Import after mocks
-import { usePathname } from 'next/navigation'
-
-import { useTabSearchParams } from './use-tab-searchparams'
-
-// Mock Next.js navigation hooks
-const mockPush = vi.fn()
-const mockReplace = vi.fn()
-const mockPathname = '/test-path'
-const mockSearchParams = new URLSearchParams()
-
-vi.mock('next/navigation', () => ({
-  usePathname: vi.fn(() => mockPathname),
-  useRouter: vi.fn(() => ({
-    push: mockPush,
-    replace: mockReplace,
-  })),
-  useSearchParams: vi.fn(() => mockSearchParams),
-}))
-
-describe('useTabSearchParams', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockSearchParams.delete('category')
-    mockSearchParams.delete('tab')
-  })
-
-  describe('Basic functionality', () => {
-    /**
-     * Test that the hook returns a tuple with activeTab and setActiveTab
-     * This is the primary interface matching React's useState pattern
-     */
-    it('should return activeTab and setActiveTab function', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      const [activeTab, setActiveTab] = result.current
-
-      expect(typeof activeTab).toBe('string')
-      expect(typeof setActiveTab).toBe('function')
-    })
-
-    /**
-     * Test that the hook initializes with the default tab
-     * When no search param is present, should use defaultTab
-     */
-    it('should initialize with default tab when no search param exists', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('overview')
-    })
-
-    /**
-     * Test that the hook reads from URL search parameters
-     * When a search param exists, it should take precedence over defaultTab
-     */
-    it('should initialize with search param value when present', () => {
-      mockSearchParams.set('category', 'settings')
-
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('settings')
-    })
-
-    /**
-     * Test that setActiveTab updates the local state
-     * The active tab should change when setActiveTab is called
-     */
-    it('should update active tab when setActiveTab is called', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('settings')
-    })
-  })
-
-  describe('Routing behavior', () => {
-    /**
-     * Test default push routing behavior
-     * By default, tab changes should use router.push (adds to history)
-     */
-    it('should use push routing by default', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      expect(mockPush).toHaveBeenCalledWith('/test-path?category=settings', { scroll: false })
-      expect(mockReplace).not.toHaveBeenCalled()
-    })
-
-    /**
-     * Test replace routing behavior
-     * When routingBehavior is 'replace', should use router.replace (no history)
-     */
-    it('should use replace routing when specified', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          routingBehavior: 'replace',
-        }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      expect(mockReplace).toHaveBeenCalledWith('/test-path?category=settings', { scroll: false })
-      expect(mockPush).not.toHaveBeenCalled()
-    })
-
-    /**
-     * Test that URL encoding is applied to tab values
-     * Special characters in tab names should be properly encoded
-     */
-    it('should encode special characters in tab values', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings & config')
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        '/test-path?category=settings%20%26%20config',
-        { scroll: false },
-      )
-    })
-
-    /**
-     * Test that URL decoding is applied when reading from search params
-     * Encoded values in the URL should be properly decoded
-     */
-    it('should decode encoded values from search params', () => {
-      mockSearchParams.set('category', 'settings%20%26%20config')
-
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('settings & config')
-    })
-  })
-
-  describe('Custom search parameter name', () => {
-    /**
-     * Test using a custom search parameter name
-     * Should support different param names instead of default 'category'
-     */
-    it('should use custom search param name', () => {
-      mockSearchParams.set('tab', 'profile')
-
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          searchParamName: 'tab',
-        }),
-      )
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('profile')
-    })
-
-    /**
-     * Test that setActiveTab uses the custom param name in the URL
-     */
-    it('should update URL with custom param name', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          searchParamName: 'tab',
-        }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('profile')
-      })
-
-      expect(mockPush).toHaveBeenCalledWith('/test-path?tab=profile', { scroll: false })
-    })
-  })
-
-  describe('Disabled search params mode', () => {
-    /**
-     * Test that disableSearchParams prevents URL updates
-     * When disabled, tab state should be local only
-     */
-    it('should not update URL when disableSearchParams is true', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          disableSearchParams: true,
-        }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      expect(mockPush).not.toHaveBeenCalled()
-      expect(mockReplace).not.toHaveBeenCalled()
-    })
-
-    /**
-     * Test that local state still updates when search params are disabled
-     * The tab state should work even without URL syncing
-     */
-    it('should still update local state when search params disabled', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          disableSearchParams: true,
-        }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('settings')
-    })
-
-    /**
-     * Test that disabled mode always uses defaultTab
-     * Search params should be ignored when disabled
-     */
-    it('should use defaultTab when search params disabled even if URL has value', () => {
-      mockSearchParams.set('category', 'settings')
-
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          disableSearchParams: true,
-        }),
-      )
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('overview')
-    })
-  })
-
-  describe('Edge cases', () => {
-    /**
-     * Test handling of empty string tab values
-     * Empty strings should be handled gracefully
-     */
-    it('should handle empty string tab values', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('')
-      })
-
-      const [activeTab] = result.current
-      expect(activeTab).toBe('')
-      expect(mockPush).toHaveBeenCalledWith('/test-path?category=', { scroll: false })
-    })
-
-    /**
-     * Test that special characters in tab names are properly encoded
-     * This ensures URLs remain valid even with unusual tab names
-     */
-    it('should handle tabs with various special characters', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      // Test tab with slashes
-      act(() => result.current[1]('tab/with/slashes'))
-      expect(result.current[0]).toBe('tab/with/slashes')
-
-      // Test tab with question marks
-      act(() => result.current[1]('tab?with?questions'))
-      expect(result.current[0]).toBe('tab?with?questions')
-
-      // Test tab with hash symbols
-      act(() => result.current[1]('tab#with#hash'))
-      expect(result.current[0]).toBe('tab#with#hash')
-
-      // Test tab with equals signs
-      act(() => result.current[1]('tab=with=equals'))
-      expect(result.current[0]).toBe('tab=with=equals')
-    })
-
-    /**
-     * Test fallback when pathname is not available
-     * Should use window.location.pathname as fallback
-     */
-    it('should fallback to window.location.pathname when hook pathname is null', () => {
-      ;(usePathname as Mock).mockReturnValue(null)
-
-      // Mock window.location.pathname
-      Object.defineProperty(window, 'location', {
-        value: { pathname: '/fallback-path' },
-        writable: true,
-      })
-
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      expect(mockPush).toHaveBeenCalledWith('/fallback-path?category=settings', { scroll: false })
-
-      // Restore mock
-      ;(usePathname as Mock).mockReturnValue(mockPathname)
-    })
-  })
-
-  describe('Multiple instances', () => {
-    /**
-     * Test that multiple instances with different param names work independently
-     * Different hooks should not interfere with each other
-     */
-    it('should support multiple independent tab states', () => {
-      mockSearchParams.set('category', 'overview')
-      mockSearchParams.set('subtab', 'details')
-
-      const { result: result1 } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'home',
-          searchParamName: 'category',
-        }),
-      )
-
-      const { result: result2 } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'info',
-          searchParamName: 'subtab',
-        }),
-      )
-
-      const [activeTab1] = result1.current
-      const [activeTab2] = result2.current
-
-      expect(activeTab1).toBe('overview')
-      expect(activeTab2).toBe('details')
-    })
-  })
-
-  describe('Integration scenarios', () => {
-    /**
-     * Test typical usage in a tabbed interface
-     * Simulates real-world tab switching behavior
-     */
-    it('should handle sequential tab changes', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      // Change to settings tab
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('settings')
-      })
-
-      expect(result.current[0]).toBe('settings')
-      expect(mockPush).toHaveBeenCalledWith('/test-path?category=settings', { scroll: false })
-
-      // Change to profile tab
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('profile')
-      })
-
-      expect(result.current[0]).toBe('profile')
-      expect(mockPush).toHaveBeenCalledWith('/test-path?category=profile', { scroll: false })
-
-      // Verify push was called twice
-      expect(mockPush).toHaveBeenCalledTimes(2)
-    })
-
-    /**
-     * Test that the hook works with complex pathnames
-     * Should handle nested routes and existing query params
-     */
-    it('should work with complex pathnames', () => {
-      ;(usePathname as Mock).mockReturnValue('/app/123/settings')
-
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('advanced')
-      })
-
-      expect(mockPush).toHaveBeenCalledWith('/app/123/settings?category=advanced', { scroll: false })
-
-      // Restore mock
-      ;(usePathname as Mock).mockReturnValue(mockPathname)
-    })
-  })
-
-  describe('Type safety', () => {
-    /**
-     * Test that the return type is a const tuple
-     * TypeScript should infer [string, (tab: string) => void] as const
-     */
-    it('should return a const tuple type', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      // The result should be a tuple with exactly 2 elements
-      expect(result.current).toHaveLength(2)
-      expect(typeof result.current[0]).toBe('string')
-      expect(typeof result.current[1]).toBe('function')
-    })
-  })
-
-  describe('Performance', () => {
-    /**
-     * Test that the hook creates a new function on each render
-     * Note: The current implementation doesn't use useCallback,
-     * so setActiveTab is recreated on each render. This could lead to
-     * unnecessary re-renders in child components that depend on this function.
-     * TODO: Consider memoizing setActiveTab with useCallback for better performance.
-     */
-    it('should create new setActiveTab function on each render', () => {
-      const { result, rerender } = renderHook(() =>
-        useTabSearchParams({ defaultTab: 'overview' }),
-      )
-
-      const [, firstSetActiveTab] = result.current
-      rerender()
-      const [, secondSetActiveTab] = result.current
-
-      // Function reference changes on re-render (not memoized)
-      expect(firstSetActiveTab).not.toBe(secondSetActiveTab)
-
-      // But both functions should work correctly
-      expect(typeof firstSetActiveTab).toBe('function')
-      expect(typeof secondSetActiveTab).toBe('function')
-    })
-  })
-
-  describe('Browser history integration', () => {
-    /**
-     * Test that push behavior adds to browser history
-     * This enables back/forward navigation through tabs
-     */
-    it('should add to history with push behavior', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          routingBehavior: 'push',
-        }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('tab1')
-      })
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('tab2')
-      })
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('tab3')
-      })
-
-      // Each tab change should create a history entry
-      expect(mockPush).toHaveBeenCalledTimes(3)
-    })
-
-    /**
-     * Test that replace behavior doesn't add to history
-     * This prevents cluttering browser history with tab changes
-     */
-    it('should not add to history with replace behavior', () => {
-      const { result } = renderHook(() =>
-        useTabSearchParams({
-          defaultTab: 'overview',
-          routingBehavior: 'replace',
-        }),
-      )
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('tab1')
-      })
-
-      act(() => {
-        const [, setActiveTab] = result.current
-        setActiveTab('tab2')
-      })
-
-      // Should use replace instead of push
-      expect(mockReplace).toHaveBeenCalledTimes(2)
-      expect(mockPush).not.toHaveBeenCalled()
-    })
-  })
-})

web/hooks/use-tab-searchparams.ts

@@ -1,47 +0,0 @@
-'use client'
-import { usePathname, useRouter, useSearchParams } from 'next/navigation'
-import { useState } from 'react'
-
-type UseTabSearchParamsOptions = {
-  defaultTab: string
-  routingBehavior?: 'push' | 'replace'
-  searchParamName?: string
-  disableSearchParams?: boolean
-}
-
-/**
- * Custom hook to manage tab state via URL search parameters in a Next.js application.
- * This hook allows for syncing the active tab with the browser's URL, enabling bookmarking and sharing of URLs with a specific tab activated.
- *
- * @param {UseTabSearchParamsOptions} options Configuration options for the hook:
- * - `defaultTab`: The tab to default to when no tab is specified in the URL.
- * - `routingBehavior`: Optional. Determines how changes to the active tab update the browser's history ('push' or 'replace'). Default is 'push'.
- * - `searchParamName`: Optional. The name of the search parameter that holds the tab state in the URL. Default is 'category'.
- * @returns A tuple where the first element is the active tab and the second element is a function to set the active tab.
- */
-export const useTabSearchParams = ({
-  defaultTab,
-  routingBehavior = 'push',
-  searchParamName = 'category',
-  disableSearchParams = false,
-}: UseTabSearchParamsOptions) => {
-  const pathnameFromHook = usePathname()
-  const router = useRouter()
-  const pathName = pathnameFromHook || window?.location?.pathname
-  const searchParams = useSearchParams()
-  const searchParamValue = searchParams.has(searchParamName) ? decodeURIComponent(searchParams.get(searchParamName)!) : defaultTab
-  const [activeTab, setTab] = useState<string>(
-    !disableSearchParams
-      ? searchParamValue
-      : defaultTab,
-  )
-
-  const setActiveTab = (newActiveTab: string) => {
-    setTab(newActiveTab)
-    if (disableSearchParams)
-      return
-    router[`${routingBehavior}`](`${pathName}?${searchParamName}=${encodeURIComponent(newActiveTab)}`, { scroll: false })
-  }
-
-  return [activeTab, setActiveTab] as const
-}

web/i18n/en-US/dataset.ts

@@ -170,6 +170,7 @@ const translation = {
     enable: 'Enable',
     disable: 'Disable',
     archive: 'Archive',
+    reIndex: 'Re-index',
     delete: 'Delete',
     cancel: 'Cancel',
   },

web/i18n/zh-Hans/dataset.ts

@@ -170,6 +170,7 @@ const translation = {
     enable: '启用',
     disable: '禁用',
     archive: '归档',
+    reIndex: '重新索引',
     delete: '删除',
     cancel: '取消',
   },

web/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "1.11.2",
   "private": true,
-  "packageManager": "pnpm@10.26.1+sha512.664074abc367d2c9324fdc18037097ce0a8f126034160f709928e9e9f95d98714347044e5c3164d65bd5da6c59c6be362b107546292a8eecb7999196e5ce58fa",
+  "packageManager": "pnpm@10.26.2+sha512.0e308ff2005fc7410366f154f625f6631ab2b16b1d2e70238444dd6ae9d630a8482d92a451144debc492416896ed16f7b114a86ec68b8404b2443869e68ffda6",
   "engines": {
     "node": ">=v22.11.0"
   },
@@ -71,7 +71,6 @@
     "@tailwindcss/typography": "^0.5.19",
     "@tanstack/react-form": "^1.23.7",
     "@tanstack/react-query": "^5.90.5",
-    "@tanstack/react-query-devtools": "^5.90.2",
     "abcjs": "^6.5.2",
     "ahooks": "^3.9.5",
     "class-variance-authority": "^0.7.1",
@@ -109,6 +108,7 @@
     "next": "~15.5.9",
     "next-pwa": "^5.6.0",
     "next-themes": "^0.4.6",
+    "nuqs": "^2.8.6",
     "pinyin-pro": "^3.27.0",
     "qrcode.react": "^4.2.0",
     "qs": "^6.14.0",
@@ -134,7 +134,7 @@
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
-    "scheduler": "^0.26.0",
+    "scheduler": "^0.27.0",
     "semver": "^7.7.3",
     "sharp": "^0.33.5",
     "sortablejs": "^1.15.6",
@@ -164,6 +164,9 @@
     "@storybook/addon-themes": "9.1.13",
     "@storybook/nextjs": "9.1.13",
     "@storybook/react": "9.1.13",
+    "@tanstack/react-devtools": "^0.9.0",
+    "@tanstack/react-form-devtools": "^0.2.9",
+    "@tanstack/react-query-devtools": "^5.90.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",

web/pnpm-lock.yaml

@@ -129,9 +129,6 @@ importers:
       '@tanstack/react-query':
         specifier: ^5.90.5
         version: 5.90.12(react@19.2.3)
-      '@tanstack/react-query-devtools':
-        specifier: ^5.90.2
-        version: 5.91.1(@tanstack/react-query@5.90.12(react@19.2.3))(react@19.2.3)
       abcjs:
         specifier: ^6.5.2
         version: 6.5.2
@@ -243,6 +240,9 @@ importers:
       next-themes:
         specifier: ^0.4.6
         version: 0.4.6(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      nuqs:
+        specifier: ^2.8.6
+        version: 2.8.6(next@15.5.9(@babel/core@7.28.5)(@playwright/test@1.57.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(sass@1.95.0))(react@19.2.3)
       pinyin-pro:
         specifier: ^3.27.0
         version: 3.27.0
@@ -319,8 +319,8 @@ importers:
         specifier: ^6.0.0
         version: 6.0.0
       scheduler:
-        specifier: ^0.26.0
-        version: 0.26.0
+        specifier: ^0.27.0
+        version: 0.27.0
       semver:
         specifier: ^7.7.3
         version: 7.7.3
@@ -341,7 +341,7 @@ importers:
         version: 7.0.19
       use-context-selector:
         specifier: ^2.0.0
-        version: 2.0.0(react@19.2.3)(scheduler@0.26.0)
+        version: 2.0.0(react@19.2.3)(scheduler@0.27.0)
       uuid:
         specifier: ^10.0.0
         version: 10.0.0
@@ -403,6 +403,15 @@ importers:
       '@storybook/react':
         specifier: 9.1.13
         version: 9.1.13(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(storybook@9.1.17(@testing-library/dom@10.4.1)(vite@7.3.0(@types/node@18.15.0)(jiti@1.21.7)(sass@1.95.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(typescript@5.9.3)
+      '@tanstack/react-devtools':
+        specifier: ^0.9.0
+        version: 0.9.0(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(csstype@3.2.3)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(solid-js@1.9.10)
+      '@tanstack/react-form-devtools':
+        specifier: ^0.2.9
+        version: 0.2.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)
+      '@tanstack/react-query-devtools':
+        specifier: ^5.90.2
+        version: 5.91.1(@tanstack/react-query@5.90.12(react@19.2.3))(react@19.2.3)
       '@testing-library/dom':
         specifier: ^10.4.1
         version: 10.4.1
@@ -3169,6 +3178,39 @@ packages:
     resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
     engines: {node: '>=10'}
 
+  '@solid-primitives/event-listener@2.4.3':
+    resolution: {integrity: sha512-h4VqkYFv6Gf+L7SQj+Y6puigL/5DIi7x5q07VZET7AWcS+9/G3WfIE9WheniHWJs51OEkRB43w6lDys5YeFceg==}
+    peerDependencies:
+      solid-js: ^1.6.12
+
+  '@solid-primitives/keyboard@1.3.3':
+    resolution: {integrity: sha512-9dQHTTgLBqyAI7aavtO+HnpTVJgWQA1ghBSrmLtMu1SMxLPDuLfuNr+Tk5udb4AL4Ojg7h9JrKOGEEDqsJXWJA==}
+    peerDependencies:
+      solid-js: ^1.6.12
+
+  '@solid-primitives/resize-observer@2.1.3':
+    resolution: {integrity: sha512-zBLje5E06TgOg93S7rGPldmhDnouNGhvfZVKOp+oG2XU8snA+GoCSSCz1M+jpNAg5Ek2EakU5UVQqL152WmdXQ==}
+    peerDependencies:
+      solid-js: ^1.6.12
+
+  '@solid-primitives/rootless@1.5.2':
+    resolution: {integrity: sha512-9HULb0QAzL2r47CCad0M+NKFtQ+LrGGNHZfteX/ThdGvKIg2o2GYhBooZubTCd/RTu2l2+Nw4s+dEfiDGvdrrQ==}
+    peerDependencies:
+      solid-js: ^1.6.12
+
+  '@solid-primitives/static-store@0.1.2':
+    resolution: {integrity: sha512-ReK+5O38lJ7fT+L6mUFvUr6igFwHBESZF+2Ug842s7fvlVeBdIVEdTCErygff6w7uR6+jrr7J8jQo+cYrEq4Iw==}
+    peerDependencies:
+      solid-js: ^1.6.12
+
+  '@solid-primitives/utils@6.3.2':
+    resolution: {integrity: sha512-hZ/M/qr25QOCcwDPOHtGjxTD8w2mNyVAYvcfgwzBHq2RwNqHNdDNsMZYap20+ruRwW4A3Cdkczyoz0TSxLCAPQ==}
+    peerDependencies:
+      solid-js: ^1.6.12
+
+  '@standard-schema/spec@1.0.0':
+    resolution: {integrity: sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA==}
+
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
@@ -3308,13 +3350,67 @@ packages:
     peerDependencies:
       tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
 
+  '@tanstack/devtools-client@0.0.5':
+    resolution: {integrity: sha512-hsNDE3iu4frt9cC2ppn1mNRnLKo2uc1/1hXAyY9z4UYb+o40M2clFAhiFoo4HngjfGJDV3x18KVVIq7W4Un+zA==}
+    engines: {node: '>=18'}
+
+  '@tanstack/devtools-event-bus@0.4.0':
+    resolution: {integrity: sha512-1t+/csFuDzi+miDxAOh6Xv7VDE80gJEItkTcAZLjV5MRulbO/W8ocjHLI2Do/p2r2/FBU0eKCRTpdqvXaYoHpQ==}
+    engines: {node: '>=18'}
+
   '@tanstack/devtools-event-client@0.3.5':
     resolution: {integrity: sha512-RL1f5ZlfZMpghrCIdzl6mLOFLTuhqmPNblZgBaeKfdtk5rfbjykurv+VfYydOFXj0vxVIoA2d/zT7xfD7Ph8fw==}
     engines: {node: '>=18'}
 
+  '@tanstack/devtools-event-client@0.4.0':
+    resolution: {integrity: sha512-RPfGuk2bDZgcu9bAJodvO2lnZeHuz4/71HjZ0bGb/SPg8+lyTA+RLSKQvo7fSmPSi8/vcH3aKQ8EM9ywf1olaw==}
+    engines: {node: '>=18'}
+
+  '@tanstack/devtools-ui@0.4.4':
+    resolution: {integrity: sha512-5xHXFyX3nom0UaNfiOM92o6ziaHjGo3mcSGe2HD5Xs8dWRZNpdZ0Smd0B9ddEhy0oB+gXyMzZgUJb9DmrZV0Mg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      solid-js: '>=1.9.7'
+
+  '@tanstack/devtools-utils@0.0.9':
+    resolution: {integrity: sha512-tCObM6wbEjuHeGNs3JDhrqBhoMxpJpVuVIg5Kc33EmUI1ZO7KLpC1277Qf6AmSWy3aVOreGwn3y5bJzxmAJNXg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/react': ~19.2.7
+      react: '>=17.0.0'
+      solid-js: '>=1.9.7'
+      vue: '>=3.2.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+      solid-js:
+        optional: true
+      vue:
+        optional: true
+
+  '@tanstack/devtools@0.10.1':
+    resolution: {integrity: sha512-1gtPmCDXV4Pl1nVtoqwjV0tc4E9GMuFtlkBX1Lz1KfqI3W9JojT5YsVifOQ/g8BTQ5w5+tyIANwHU7WYgLq/MQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      solid-js: '>=1.9.7'
+
   '@tanstack/form-core@1.27.1':
     resolution: {integrity: sha512-hPM+0tUnZ2C2zb2TE1lar1JJ0S0cbnQHlUwFcCnVBpMV3rjtUzkoM766gUpWrlmTGCzNad0GbJ0aTxVsjT6J8g==}
 
+  '@tanstack/form-core@1.27.6':
+    resolution: {integrity: sha512-1C4PUpOcCpivddKxtAeqdeqncxnPKiPpTVDRknDExCba+6zCsAjxgL+p3qYA3hu+EFyUAdW71rU+uqYbEa7qqA==}
+
+  '@tanstack/form-devtools@0.2.9':
+    resolution: {integrity: sha512-KOJiwvlFPsHeuWXvHUXRVdciXG1OPhg1c476MsLre0YLdaw1jeMlDYSlqq7sdEULX+2Sg/lhNpX86QbQuxzd2A==}
+    peerDependencies:
+      solid-js: '>=1.9.9'
+
+  '@tanstack/pacer-lite@0.1.1':
+    resolution: {integrity: sha512-y/xtNPNt/YeyoVxE/JCx+T7yjEzpezmbb+toK8DDD1P4m7Kzs5YR956+7OKexG3f8aXgC3rLZl7b1V+yNUSy5w==}
+    engines: {node: '>=18'}
+
   '@tanstack/pacer@0.15.4':
     resolution: {integrity: sha512-vGY+CWsFZeac3dELgB6UZ4c7OacwsLb8hvL2gLS6hTgy8Fl0Bm/aLokHaeDIP+q9F9HUZTnp360z9uv78eg8pg==}
     engines: {node: '>=18'}
@@ -3325,6 +3421,20 @@ packages:
   '@tanstack/query-devtools@5.91.1':
     resolution: {integrity: sha512-l8bxjk6BMsCaVQH6NzQEE/bEgFy1hAs5qbgXl0xhzezlaQbPk6Mgz9BqEg2vTLPOHD8N4k+w/gdgCbEzecGyNg==}
 
+  '@tanstack/react-devtools@0.9.0':
+    resolution: {integrity: sha512-Lq0svXOTG5N61SHgx8F0on6zz2GB0kmFjN/yyfNLrJyRgJ+U3jYFRd9ti3uBPABsXzHQMHYYujnTXrOYp/OaUg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/react': ~19.2.7
+      '@types/react-dom': ~19.2.3
+      react: '>=16.8'
+      react-dom: '>=16.8'
+
+  '@tanstack/react-form-devtools@0.2.9':
+    resolution: {integrity: sha512-wg0xrcVY8evIFGVHrnl9s+/9ENzuVbqv5Ru4HyAJjjL4uECtl6KdDJsi0lZdOyoM1UYEQoVdcN8jfBbxkA3q1g==}
+    peerDependencies:
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+
   '@tanstack/react-form@1.27.1':
     resolution: {integrity: sha512-HKP0Ew2ae9AL5vU1PkJ+oAC2p+xBtA905u0fiNLzlfn1vLkBxenfg5L6TOA+rZITHpQsSo10tqwc5Yw6qn8Mpg==}
     peerDependencies:
@@ -5629,6 +5739,11 @@ packages:
   globrex@0.1.2:
     resolution: {integrity: sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg==}
 
+  goober@2.1.18:
+    resolution: {integrity: sha512-2vFqsaDVIT9Gz7N6kAL++pLpp41l3PfDuusHcjnGLfR6+huZkl6ziX+zgVC3ZxpqWhzH6pyDdGrCeDhMIvwaxw==}
+    peerDependencies:
+      csstype: ^3.0.10
+
   got@11.8.6:
     resolution: {integrity: sha512-6tfZ91bOr7bOXnK7PRDCGBLa1H4U080YHNaAQ2KsMGlLEzRbk44nsZF2E1IeRc3vtJHPVbKCYgdFbaGO2ljd8g==}
     engines: {node: '>=10.19.0'}
@@ -6731,6 +6846,27 @@ packages:
   nth-check@2.1.1:
     resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
 
+  nuqs@2.8.6:
+    resolution: {integrity: sha512-aRxeX68b4ULmhio8AADL2be1FWDy0EPqaByPvIYWrA7Pm07UjlrICp/VPlSnXJNAG0+3MQwv3OporO2sOXMVGA==}
+    peerDependencies:
+      '@remix-run/react': '>=2'
+      '@tanstack/react-router': ^1
+      next: '>=14.2.0'
+      react: '>=18.2.0 || ^19.0.0-0'
+      react-router: ^5 || ^6 || ^7
+      react-router-dom: ^5 || ^6 || ^7
+    peerDependenciesMeta:
+      '@remix-run/react':
+        optional: true
+      '@tanstack/react-router':
+        optional: true
+      next:
+        optional: true
+      react-router:
+        optional: true
+      react-router-dom:
+        optional: true
+
   object-assign@4.1.1:
     resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
     engines: {node: '>=0.10.0'}
@@ -7641,9 +7777,6 @@ packages:
     resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
     engines: {node: '>=v12.22.7'}
 
-  scheduler@0.26.0:
-    resolution: {integrity: sha512-NlHwttCI/l5gCPR3D1nNXtWABUmBwvZpEQiD4IXSbIDq8BzLIK/7Ir5gTFSGZDUu37K5cMNp0hFtzO38sC7gWA==}
-
   scheduler@0.27.0:
     resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
 
@@ -7687,6 +7820,16 @@ packages:
   serialize-javascript@6.0.2:
     resolution: {integrity: sha512-Saa1xPByTTq2gdeFZYLLo+RFE35NHZkAbqZeWNd3BpzppeVisAqpDjcp8dyf6uIvEqJRd46jemmyA4iFIeVk8g==}
 
+  seroval-plugins@1.3.3:
+    resolution: {integrity: sha512-16OL3NnUBw8JG1jBLUoZJsLnQq0n5Ua6aHalhJK4fMQkz1lqR7Osz1sA30trBtd9VUDc2NgkuRCn8+/pBwqZ+w==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      seroval: ^1.0
+
+  seroval@1.3.2:
+    resolution: {integrity: sha512-RbcPH1n5cfwKrru7v7+zrZvjLurgHhGyso3HTyGtRivGWgYjbOmGuivCQaORNELjNONoK35nj28EoWul9sb1zQ==}
+    engines: {node: '>=10'}
+
   setimmediate@1.0.5:
     resolution: {integrity: sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==}
 
@@ -7753,6 +7896,9 @@ packages:
     resolution: {integrity: sha512-QlaZEqcAH3/RtNyet1IPIYPsEWAaYyXXv1Krsi+1L/QHppjX4Ifm8MQsBISz9vE8cHicIq3clogsheili5vhaQ==}
     engines: {node: '>= 18'}
 
+  solid-js@1.9.10:
+    resolution: {integrity: sha512-Coz956cos/EPDlhs6+jsdTxKuJDPT7B5SVIWgABwROyxjY7Xbr8wkzD68Et+NxnV7DLJ3nJdAC2r9InuV/4Jew==}
+
   sortablejs@1.15.6:
     resolution: {integrity: sha512-aNfiuwMEpfBM/CN6LY0ibyhxPfPbyFeBTYJKCvzkJ2GkUpazIt3H+QIPAMHwqQ7tMKaHz1Qj+rJJCqljnf4p3A==}
 
@@ -11539,6 +11685,42 @@ snapshots:
 
   '@sindresorhus/is@4.6.0': {}
 
+  '@solid-primitives/event-listener@2.4.3(solid-js@1.9.10)':
+    dependencies:
+      '@solid-primitives/utils': 6.3.2(solid-js@1.9.10)
+      solid-js: 1.9.10
+
+  '@solid-primitives/keyboard@1.3.3(solid-js@1.9.10)':
+    dependencies:
+      '@solid-primitives/event-listener': 2.4.3(solid-js@1.9.10)
+      '@solid-primitives/rootless': 1.5.2(solid-js@1.9.10)
+      '@solid-primitives/utils': 6.3.2(solid-js@1.9.10)
+      solid-js: 1.9.10
+
+  '@solid-primitives/resize-observer@2.1.3(solid-js@1.9.10)':
+    dependencies:
+      '@solid-primitives/event-listener': 2.4.3(solid-js@1.9.10)
+      '@solid-primitives/rootless': 1.5.2(solid-js@1.9.10)
+      '@solid-primitives/static-store': 0.1.2(solid-js@1.9.10)
+      '@solid-primitives/utils': 6.3.2(solid-js@1.9.10)
+      solid-js: 1.9.10
+
+  '@solid-primitives/rootless@1.5.2(solid-js@1.9.10)':
+    dependencies:
+      '@solid-primitives/utils': 6.3.2(solid-js@1.9.10)
+      solid-js: 1.9.10
+
+  '@solid-primitives/static-store@0.1.2(solid-js@1.9.10)':
+    dependencies:
+      '@solid-primitives/utils': 6.3.2(solid-js@1.9.10)
+      solid-js: 1.9.10
+
+  '@solid-primitives/utils@6.3.2(solid-js@1.9.10)':
+    dependencies:
+      solid-js: 1.9.10
+
+  '@standard-schema/spec@1.0.0': {}
+
   '@standard-schema/spec@1.1.0': {}
 
   '@standard-schema/utils@0.3.0': {}
@@ -11766,14 +11948,84 @@ snapshots:
       postcss-selector-parser: 6.0.10
       tailwindcss: 3.4.18(tsx@4.21.0)(yaml@2.8.2)
 
+  '@tanstack/devtools-client@0.0.5':
+    dependencies:
+      '@tanstack/devtools-event-client': 0.4.0
+
+  '@tanstack/devtools-event-bus@0.4.0':
+    dependencies:
+      ws: 8.18.3
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   '@tanstack/devtools-event-client@0.3.5': {}
 
+  '@tanstack/devtools-event-client@0.4.0': {}
+
+  '@tanstack/devtools-ui@0.4.4(csstype@3.2.3)(solid-js@1.9.10)':
+    dependencies:
+      clsx: 2.1.1
+      goober: 2.1.18(csstype@3.2.3)
+      solid-js: 1.9.10
+    transitivePeerDependencies:
+      - csstype
+
+  '@tanstack/devtools-utils@0.0.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)':
+    dependencies:
+      '@tanstack/devtools-ui': 0.4.4(csstype@3.2.3)(solid-js@1.9.10)
+    optionalDependencies:
+      '@types/react': 19.2.7
+      react: 19.2.3
+      solid-js: 1.9.10
+    transitivePeerDependencies:
+      - csstype
+
+  '@tanstack/devtools@0.10.1(csstype@3.2.3)(solid-js@1.9.10)':
+    dependencies:
+      '@solid-primitives/event-listener': 2.4.3(solid-js@1.9.10)
+      '@solid-primitives/keyboard': 1.3.3(solid-js@1.9.10)
+      '@solid-primitives/resize-observer': 2.1.3(solid-js@1.9.10)
+      '@tanstack/devtools-client': 0.0.5
+      '@tanstack/devtools-event-bus': 0.4.0
+      '@tanstack/devtools-ui': 0.4.4(csstype@3.2.3)(solid-js@1.9.10)
+      clsx: 2.1.1
+      goober: 2.1.18(csstype@3.2.3)
+      solid-js: 1.9.10
+    transitivePeerDependencies:
+      - bufferutil
+      - csstype
+      - utf-8-validate
+
   '@tanstack/form-core@1.27.1':
     dependencies:
       '@tanstack/devtools-event-client': 0.3.5
       '@tanstack/pacer': 0.15.4
       '@tanstack/store': 0.7.7
 
+  '@tanstack/form-core@1.27.6':
+    dependencies:
+      '@tanstack/devtools-event-client': 0.4.0
+      '@tanstack/pacer-lite': 0.1.1
+      '@tanstack/store': 0.7.7
+
+  '@tanstack/form-devtools@0.2.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)':
+    dependencies:
+      '@tanstack/devtools-ui': 0.4.4(csstype@3.2.3)(solid-js@1.9.10)
+      '@tanstack/devtools-utils': 0.0.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)
+      '@tanstack/form-core': 1.27.6
+      clsx: 2.1.1
+      dayjs: 1.11.19
+      goober: 2.1.18(csstype@3.2.3)
+      solid-js: 1.9.10
+    transitivePeerDependencies:
+      - '@types/react'
+      - csstype
+      - react
+      - vue
+
+  '@tanstack/pacer-lite@0.1.1': {}
+
   '@tanstack/pacer@0.15.4':
     dependencies:
       '@tanstack/devtools-event-client': 0.3.5
@@ -11783,6 +12035,30 @@ snapshots:
 
   '@tanstack/query-devtools@5.91.1': {}
 
+  '@tanstack/react-devtools@0.9.0(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(csstype@3.2.3)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(solid-js@1.9.10)':
+    dependencies:
+      '@tanstack/devtools': 0.10.1(csstype@3.2.3)(solid-js@1.9.10)
+      '@types/react': 19.2.7
+      '@types/react-dom': 19.2.3(@types/react@19.2.7)
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+    transitivePeerDependencies:
+      - bufferutil
+      - csstype
+      - solid-js
+      - utf-8-validate
+
+  '@tanstack/react-form-devtools@0.2.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)':
+    dependencies:
+      '@tanstack/devtools-utils': 0.0.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)
+      '@tanstack/form-devtools': 0.2.9(@types/react@19.2.7)(csstype@3.2.3)(react@19.2.3)(solid-js@1.9.10)
+      react: 19.2.3
+    transitivePeerDependencies:
+      - '@types/react'
+      - csstype
+      - solid-js
+      - vue
+
   '@tanstack/react-form@1.27.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@tanstack/form-core': 1.27.1
@@ -14486,6 +14762,10 @@ snapshots:
 
   globrex@0.1.2: {}
 
+  goober@2.1.18(csstype@3.2.3):
+    dependencies:
+      csstype: 3.2.3
+
   got@11.8.6:
     dependencies:
       '@sindresorhus/is': 4.6.0
@@ -15993,6 +16273,13 @@ snapshots:
     dependencies:
       boolbase: 1.0.0
 
+  nuqs@2.8.6(next@15.5.9(@babel/core@7.28.5)(@playwright/test@1.57.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(sass@1.95.0))(react@19.2.3):
+    dependencies:
+      '@standard-schema/spec': 1.0.0
+      react: 19.2.3
+    optionalDependencies:
+      next: 15.5.9(@babel/core@7.28.5)(@playwright/test@1.57.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(sass@1.95.0)
+
   object-assign@4.1.1: {}
 
   object-deep-merge@2.0.0: {}
@@ -17044,8 +17331,6 @@ snapshots:
     dependencies:
       xmlchars: 2.2.0
 
-  scheduler@0.26.0: {}
-
   scheduler@0.27.0: {}
 
   schema-utils@2.7.1:
@@ -17089,6 +17374,12 @@ snapshots:
     dependencies:
       randombytes: 2.1.0
 
+  seroval-plugins@1.3.3(seroval@1.3.2):
+    dependencies:
+      seroval: 1.3.2
+
+  seroval@1.3.2: {}
+
   setimmediate@1.0.5: {}
 
   sha.js@2.4.12:
@@ -17203,6 +17494,12 @@ snapshots:
 
   smol-toml@1.5.2: {}
 
+  solid-js@1.9.10:
+    dependencies:
+      csstype: 3.2.3
+      seroval: 1.3.2
+      seroval-plugins: 1.3.3(seroval@1.3.2)
+
   sortablejs@1.15.6: {}
 
   source-list-map@2.0.1: {}
@@ -17734,10 +18031,10 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.7
 
-  use-context-selector@2.0.0(react@19.2.3)(scheduler@0.26.0):
+  use-context-selector@2.0.0(react@19.2.3)(scheduler@0.27.0):
     dependencies:
       react: 19.2.3
-      scheduler: 0.26.0
+      scheduler: 0.27.0
 
   use-isomorphic-layout-effect@1.2.1(@types/react@19.2.7)(react@19.2.3):
     dependencies:

web/service/knowledge/use-document.ts

@@ -7,7 +7,7 @@ import {
 } from '@tanstack/react-query'
 import { normalizeStatusForQuery } from '@/app/components/datasets/documents/status-filter'
 import { DocumentActionType } from '@/models/datasets'
-import { del, get, patch } from '../base'
+import { del, get, patch, post } from '../base'
 import { pauseDocIndexing, resumeDocIndexing } from '../datasets'
 import { useInvalid } from '../use-base'
 
@@ -163,3 +163,15 @@ export const useDocumentResume = () => {
     },
   })
 }
+
+export const useDocumentBatchRetryIndex = () => {
+  return useMutation({
+    mutationFn: ({ datasetId, documentIds }: { datasetId: string, documentIds: string[] }) => {
+      return post<CommonResponse>(`/datasets/${datasetId}/retry`, {
+        body: {
+          document_ids: documentIds,
+        },
+      })
+    },
+  })
+}

web/utils/index.spec.ts

@@ -1,4 +1,3 @@
-import type { Mock } from 'vitest'
 import {
   asyncRunSafe,
   canFindTool,
@@ -8,7 +7,6 @@ import {
   getPurifyHref,
   getTextWidthWithCanvas,
   randomString,
-  removeSpecificQueryParam,
   sleep,
 } from './index'
 
@@ -231,72 +229,6 @@ describe('canFindTool', () => {
   })
 })
 
-describe('removeSpecificQueryParam', () => {
-  let originalLocation: Location
-  let originalReplaceState: typeof window.history.replaceState
-
-  beforeEach(() => {
-    originalLocation = window.location
-    originalReplaceState = window.history.replaceState
-
-    const mockUrl = new URL('https://example.com?param1=value1&param2=value2&param3=value3')
-
-    // Mock window.location using defineProperty to handle URL properly
-    delete (window as any).location
-    Object.defineProperty(window, 'location', {
-      configurable: true,
-      writable: true,
-      value: {
-        ...originalLocation,
-        href: mockUrl.href,
-        search: mockUrl.search,
-        toString: () => mockUrl.toString(),
-      },
-    })
-
-    window.history.replaceState = vi.fn()
-  })
-
-  afterEach(() => {
-    Object.defineProperty(window, 'location', {
-      configurable: true,
-      writable: true,
-      value: originalLocation,
-    })
-    window.history.replaceState = originalReplaceState
-  })
-
-  it('should remove a single query parameter', () => {
-    removeSpecificQueryParam('param2')
-    expect(window.history.replaceState).toHaveBeenCalledTimes(1)
-    const replaceStateCall = (window.history.replaceState as Mock).mock.calls[0]
-    expect(replaceStateCall[0]).toBe(null)
-    expect(replaceStateCall[1]).toBe('')
-    expect(replaceStateCall[2]).toMatch(/param1=value1/)
-    expect(replaceStateCall[2]).toMatch(/param3=value3/)
-    expect(replaceStateCall[2]).not.toMatch(/param2=value2/)
-  })
-
-  it('should remove multiple query parameters', () => {
-    removeSpecificQueryParam(['param1', 'param3'])
-    expect(window.history.replaceState).toHaveBeenCalledTimes(1)
-    const replaceStateCall = (window.history.replaceState as Mock).mock.calls[0]
-    expect(replaceStateCall[2]).toMatch(/param2=value2/)
-    expect(replaceStateCall[2]).not.toMatch(/param1=value1/)
-    expect(replaceStateCall[2]).not.toMatch(/param3=value3/)
-  })
-
-  it('should handle non-existent parameters gracefully', () => {
-    removeSpecificQueryParam('nonexistent')
-
-    expect(window.history.replaceState).toHaveBeenCalledTimes(1)
-    const replaceStateCall = (window.history.replaceState as Mock).mock.calls[0]
-    expect(replaceStateCall[2]).toMatch(/param1=value1/)
-    expect(replaceStateCall[2]).toMatch(/param2=value2/)
-    expect(replaceStateCall[2]).toMatch(/param3=value3/)
-  })
-})
-
 describe('sleep', () => {
   it('should resolve after specified milliseconds', async () => {
     const start = Date.now()
@@ -560,47 +492,3 @@ describe('canFindTool extended', () => {
     expect(canFindTool('openai', undefined)).toBe(false)
   })
 })
-
-describe('removeSpecificQueryParam extended', () => {
-  beforeEach(() => {
-    // Reset window.location
-    delete (window as any).location
-    window.location = {
-      href: 'https://example.com?param1=value1&param2=value2&param3=value3',
-    } as any
-  })
-
-  it('should remove single query parameter', () => {
-    const mockReplaceState = vi.fn()
-    window.history.replaceState = mockReplaceState
-
-    removeSpecificQueryParam('param1')
-
-    expect(mockReplaceState).toHaveBeenCalled()
-    const newUrl = mockReplaceState.mock.calls[0][2]
-    expect(newUrl).not.toContain('param1')
-  })
-
-  it('should remove multiple query parameters', () => {
-    const mockReplaceState = vi.fn()
-    window.history.replaceState = mockReplaceState
-
-    removeSpecificQueryParam(['param1', 'param2'])
-
-    expect(mockReplaceState).toHaveBeenCalled()
-    const newUrl = mockReplaceState.mock.calls[0][2]
-    expect(newUrl).not.toContain('param1')
-    expect(newUrl).not.toContain('param2')
-  })
-
-  it('should preserve other parameters', () => {
-    const mockReplaceState = vi.fn()
-    window.history.replaceState = mockReplaceState
-
-    removeSpecificQueryParam('param1')
-
-    const newUrl = mockReplaceState.mock.calls[0][2]
-    expect(newUrl).toContain('param2')
-    expect(newUrl).toContain('param3')
-  })
-})

web/utils/index.ts

@@ -90,12 +90,3 @@ export const canFindTool = (providerId: string, oldToolId?: string) => {
     || providerId === `langgenius/${oldToolId}/${oldToolId}`
     || providerId === `langgenius/${oldToolId}_tool/${oldToolId}`
 }
-
-export const removeSpecificQueryParam = (key: string | string[]) => {
-  const url = new URL(window.location.href)
-  if (Array.isArray(key))
-    key.forEach(k => url.searchParams.delete(k))
-  else
-    url.searchParams.delete(key)
-  window.history.replaceState(null, '', url.toString())
-}