feat(studio): add reusable Feishu bot setup card

Author: evanlowe

frontend/README.md

@@ -270,6 +270,13 @@ Changing the Feishu channel on the deployment page regenerates the project so
 `app.py`, the `extensions` dependency, and the runtime environment variables
 stay aligned before deployment.
 
+The deployment card supports automatic and manual credential setup without
+changing its footprint in the publish form. Automatic setup uses the reusable
+`frontend.server.feishu_bot_setup` provider interface and keeps App Secret
+values in the mounted Studio process. Set
+`VEADK_STUDIO_FEISHU_SETUP_MOCK=1` only for local UI testing; when no production
+provider is configured, Studio keeps manual credential entry available.
+
 Insight Sandbox requires server-side `VOLCENGINE_ACCESS_KEY`,
 `VOLCENGINE_SECRET_KEY`, `MODEL_AGENT_API_KEY`, and `MODEL_AGENT_NAME` values.
 These credentials and the AgentKit session endpoint remain on the Studio server

frontend/server/feishu_bot_setup/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Reusable Feishu bot setup workflow for Studio deployment surfaces."""
+
+from .routes import mount_feishu_bot_setup_routes
+from .service import FeishuBotSetupService, create_feishu_bot_setup_service
+
+__all__ = [
+    "FeishuBotSetupService",
+    "create_feishu_bot_setup_service",
+    "mount_feishu_bot_setup_routes",
+]

frontend/server/feishu_bot_setup/routes.py

@@ -0,0 +1,67 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""FastAPI transport for the reusable Feishu bot setup service."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import HTTPException, Request
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel, Field
+
+from .service import (
+    FeishuBotSetupNotFound,
+    FeishuBotSetupService,
+    FeishuBotSetupUnavailable,
+)
+
+
+class CreateFeishuBotSetupBody(BaseModel):
+    agent_name: str = Field(alias="agentName", min_length=1, max_length=128)
+
+
+def mount_feishu_bot_setup_routes(
+    app: Any,
+    service: FeishuBotSetupService,
+    owner_resolver: Callable[[Request], str],
+) -> None:
+    async def invoke(call: Callable[[], dict[str, object]]) -> dict[str, object]:
+        try:
+            return await run_in_threadpool(call)
+        except FeishuBotSetupUnavailable as error:
+            raise HTTPException(status_code=503, detail=str(error)) from error
+        except FeishuBotSetupNotFound as error:
+            raise HTTPException(status_code=404, detail=str(error)) from error
+
+    @app.post("/web/feishu-bot-setup/sessions")
+    async def create_session(
+        body: CreateFeishuBotSetupBody, request: Request
+    ) -> dict[str, object]:
+        owner = owner_resolver(request)
+        return await invoke(
+            lambda: service.create(owner=owner, agent_name=body.agent_name)
+        )
+
+    @app.get("/web/feishu-bot-setup/sessions/{session_id}")
+    async def get_session(session_id: str, request: Request) -> dict[str, object]:
+        owner = owner_resolver(request)
+        return await invoke(lambda: service.get(owner=owner, session_id=session_id))
+
+    @app.delete("/web/feishu-bot-setup/sessions/{session_id}")
+    async def cancel_session(session_id: str, request: Request) -> dict[str, object]:
+        owner = owner_resolver(request)
+        return await invoke(lambda: service.cancel(owner=owner, session_id=session_id))

frontend/server/feishu_bot_setup/service.py

@@ -0,0 +1,224 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Provider-independent lifecycle for creating a Feishu bot by QR authorization."""
+
+from __future__ import annotations
+
+import base64
+import os
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Protocol
+from uuid import uuid4
+
+
+class FeishuBotSetupError(RuntimeError):
+    """Base error returned by the Feishu setup workflow."""
+
+
+class FeishuBotSetupUnavailable(FeishuBotSetupError):
+    """Raised when no production QR provider has been configured."""
+
+
+class FeishuBotSetupNotFound(FeishuBotSetupError):
+    """Raised when a setup session does not exist for the current user."""
+
+
+@dataclass(frozen=True)
+class ProviderSession:
+    provider_id: str
+    qr_code_data_url: str
+    expires_at: float
+
+
+@dataclass(frozen=True)
+class ProviderResult:
+    status: str
+    app_id: str = ""
+    app_secret: str = ""
+    message: str = ""
+
+
+class FeishuBotSetupProvider(Protocol):
+    def create(self, *, agent_name: str) -> ProviderSession: ...
+
+    def poll(self, provider_id: str) -> ProviderResult: ...
+
+    def cancel(self, provider_id: str) -> None: ...
+
+
+@dataclass
+class _OwnedSession:
+    owner: str
+    provider_id: str
+    qr_code_data_url: str
+    expires_at: float
+
+
+class FeishuBotSetupService:
+    """Owns user-scoped sessions while delegating vendor calls to a provider."""
+
+    def __init__(self, provider: FeishuBotSetupProvider | None) -> None:
+        self._provider = provider
+        self._sessions: dict[str, _OwnedSession] = {}
+        self._lock = threading.Lock()
+
+    def create(self, *, owner: str, agent_name: str) -> dict[str, object]:
+        if self._provider is None:
+            raise FeishuBotSetupUnavailable(
+                "当前 Studio 尚未配置飞书自动建机器人服务，请使用手动配置。"
+            )
+        provider_session = self._provider.create(agent_name=agent_name)
+        session_id = f"fsbot_{uuid4().hex}"
+        with self._lock:
+            self._sessions[session_id] = _OwnedSession(
+                owner=owner,
+                provider_id=provider_session.provider_id,
+                qr_code_data_url=provider_session.qr_code_data_url,
+                expires_at=provider_session.expires_at,
+            )
+        return self._payload(
+            session_id, self._sessions[session_id], ProviderResult("waiting")
+        )
+
+    def get(self, *, owner: str, session_id: str) -> dict[str, object]:
+        session = self._owned(owner, session_id)
+        if time.time() >= session.expires_at:
+            return self._payload(
+                session_id, session, ProviderResult("expired", message="二维码已失效。")
+            )
+        assert self._provider is not None
+        return self._payload(
+            session_id, session, self._provider.poll(session.provider_id)
+        )
+
+    def cancel(self, *, owner: str, session_id: str) -> dict[str, object]:
+        session = self._owned(owner, session_id)
+        assert self._provider is not None
+        self._provider.cancel(session.provider_id)
+        with self._lock:
+            self._sessions.pop(session_id, None)
+        return self._payload(session_id, session, ProviderResult("cancelled"))
+
+    def _owned(self, owner: str, session_id: str) -> _OwnedSession:
+        with self._lock:
+            session = self._sessions.get(session_id)
+        if session is None or session.owner != owner:
+            raise FeishuBotSetupNotFound("飞书自动配置会话不存在或已结束。")
+        return session
+
+    @staticmethod
+    def _payload(
+        session_id: str, session: _OwnedSession, result: ProviderResult
+    ) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "id": session_id,
+            "status": result.status,
+            "expiresAt": datetime.fromtimestamp(
+                session.expires_at, tz=timezone.utc
+            ).isoformat(),
+            "message": result.message,
+        }
+        if result.status == "waiting":
+            payload["qrCodeDataUrl"] = session.qr_code_data_url
+        if result.status == "success":
+            payload["credentials"] = {
+                "appId": result.app_id,
+                "appSecret": result.app_secret,
+            }
+        return payload
+
+
+class LocalPreviewProvider:
+    """Local-only adapter used to exercise the Studio UI without a vendor mutation."""
+
+    def __init__(self, *, completion_delay: float = 4.0) -> None:
+        self._completion_delay = completion_delay
+        self._created_at: dict[str, float] = {}
+
+    def create(self, *, agent_name: str) -> ProviderSession:
+        provider_id = uuid4().hex
+        self._created_at[provider_id] = time.time()
+        return ProviderSession(
+            provider_id=provider_id,
+            qr_code_data_url=_preview_qr_data_url(provider_id),
+            expires_at=time.time() + 600,
+        )
+
+    def poll(self, provider_id: str) -> ProviderResult:
+        created_at = self._created_at.get(provider_id)
+        if created_at is None:
+            return ProviderResult("failed", message="自动配置会话已结束。")
+        if time.time() - created_at < self._completion_delay:
+            return ProviderResult("waiting")
+        suffix = provider_id[:12]
+        return ProviderResult(
+            "success",
+            app_id=f"cli_preview_{suffix}",
+            app_secret=f"preview_secret_{provider_id}",
+        )
+
+    def cancel(self, provider_id: str) -> None:
+        self._created_at.pop(provider_id, None)
+
+
+def create_feishu_bot_setup_service() -> FeishuBotSetupService:
+    preview = os.getenv("VEADK_STUDIO_FEISHU_SETUP_MOCK", "").strip().lower()
+    provider = LocalPreviewProvider() if preview in {"1", "true", "yes"} else None
+    return FeishuBotSetupService(provider)
+
+
+def _preview_qr_data_url(seed: str) -> str:
+    size = 21
+    cells: list[str] = []
+    for row in range(size):
+        for column in range(size):
+            finder = (
+                _finder_cell(row, column, 0, 0)
+                or _finder_cell(row, column, 0, size - 7)
+                or _finder_cell(row, column, size - 7, 0)
+            )
+            reserved = (
+                (row <= 7 and column <= 7)
+                or (row <= 7 and column >= size - 8)
+                or (row >= size - 8 and column <= 7)
+            )
+            marker = ord(seed[(row * size + column) % len(seed)])
+            data = (
+                not reserved and (row * 11 + column * 7 + row * column + marker) % 5 < 2
+            )
+            if finder or data:
+                cells.append(f'<rect x="{column}" y="{row}" width="1" height="1"/>')
+    svg = (
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="-2 -2 {size + 4} {size + 4}">'
+        '<rect x="-2" y="-2" width="25" height="25" fill="white"/>'
+        f'<g fill="#111">{"".join(cells)}</g></svg>'
+    )
+    encoded = base64.b64encode(svg.encode()).decode()
+    return f"data:image/svg+xml;base64,{encoded}"
+
+
+def _finder_cell(row: int, column: int, top: int, left: int) -> bool:
+    local_row = row - top
+    local_column = column - left
+    if not (0 <= local_row <= 6 and 0 <= local_column <= 6):
+        return False
+    return (
+        local_row in {0, 6}
+        or local_column in {0, 6}
+        or (2 <= local_row <= 4 and 2 <= local_column <= 4)
+    )

frontend/src/adk/feishuBotSetup.ts

@@ -0,0 +1,53 @@
+import { httpErrorMessage, studioFetch } from "./client";
+
+export type FeishuBotSetupStatus =
+  | "waiting"
+  | "success"
+  | "failed"
+  | "expired"
+  | "cancelled";
+
+export interface FeishuBotSetupSession {
+  id: string;
+  status: FeishuBotSetupStatus;
+  expiresAt?: string;
+  qrCodeDataUrl?: string;
+  message?: string;
+  credentials?: { appId: string; appSecret: string };
+}
+
+async function request(
+  path: string,
+  init: RequestInit,
+): Promise<FeishuBotSetupSession> {
+  const response = await studioFetch(path, {
+    ...init,
+    headers: { accept: "application/json", ...init.headers },
+  });
+  if (!response.ok) {
+    throw new Error(await httpErrorMessage(response, "飞书机器人自动配置失败"));
+  }
+  return response.json() as Promise<FeishuBotSetupSession>;
+}
+
+export function createFeishuBotSetup(input: { agentName: string }) {
+  return request("/web/feishu-bot-setup/sessions", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(input),
+  });
+}
+
+export function getFeishuBotSetup(sessionId: string) {
+  return request(
+    `/web/feishu-bot-setup/sessions/${encodeURIComponent(sessionId)}`,
+    { method: "GET" },
+  );
+}
+
+export function cancelFeishuBotSetup(sessionId: string) {
+  return request(
+    `/web/feishu-bot-setup/sessions/${encodeURIComponent(sessionId)}`,
+    { method: "DELETE" },
+  );
+}