@lark-apaas/client-toolkit 1.2.28-alpha.7 → 1.2.28-alpha.71

package/lib/apis/udt-types.d.ts

@@ -9,6 +9,10 @@ export type IUserProfile = {
      * inactive 2
      */
     status?: number;
+    /**
+     * 飞书 user_id
+     */
+    lark_user_id?: string;
 };
 export type IFileAttachment = {
     bucket_id: string;

package/lib/auth.d.ts

@@ -1 +1,2 @@
-export { CanRole, AbilityContext, ROLE_SUBJECT } from '@lark-apaas/auth-sdk';
+export { AuthProvider, useAuth, Can, CanRole, useCan, AbilityContext, useUserPermissions, PermissionClient, ROLE_SUBJECT, } from '@lark-apaas/auth-sdk';
+export type { AuthProviderProps, PermissionApiResponse, PermissionApiConfig, PermissionPointData, AuthSdkConfig, } from '@lark-apaas/auth-sdk';

package/lib/auth.js

@@ -1,2 +1,2 @@
-import { AbilityContext, CanRole, ROLE_SUBJECT } from "@lark-apaas/auth-sdk";
-export { AbilityContext, CanRole, ROLE_SUBJECT };
+import { AbilityContext, AuthProvider, Can, CanRole, PermissionClient, ROLE_SUBJECT, useAuth, useCan, useUserPermissions } from "@lark-apaas/auth-sdk";
+export { AbilityContext, AuthProvider, Can, CanRole, PermissionClient, ROLE_SUBJECT, useAuth, useCan, useUserPermissions };

package/lib/components/AppContainer/index.js

@@ -1,5 +1,5 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import react, { Suspense, useEffect, useMemo, useState } from "react";
 import { ConfigProvider } from "antd";
 import { MiaodaInspector } from "@lark-apaas/miaoda-inspector";
 import zh_CN from "antd/locale/zh_CN";
@@ -9,20 +9,34 @@ import { PageHoc } from "./PageHoc.js";
 import { reportTeaEvent } from "./utils/tea.js";
 import { useAppInfo } from "../../hooks/index.js";
 import { TrackKey } from "../../types/tea.js";
-import safety from "./safety.js";
+import { slardar } from "@lark-apaas/internal-slardar";
 import { getAppId } from "../../utils/getAppId.js";
 import { isNewPathEnabled } from "../../utils/apiPath.js";
 import QueryProvider from "../QueryProvider/index.js";
 import { AuthProvider } from "@lark-apaas/auth-sdk";
 import "../../runtime/index.js";
+const Safety = /*#__PURE__*/ react.lazy(()=>import("./safety.js"));
 const isMiaodaPreview = window.IS_MIAODA_PREVIEW;
-const readCssVarColor = (varName, fallback)=>{
+const readAllCssVarColors = ()=>{
     try {
-        if ('undefined' == typeof document) return fallback;
-        const value = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
-        return value || fallback;
+        if ('undefined' == typeof document) return {};
+        const styles = getComputedStyle(document.documentElement);
+        const read = (name)=>styles.getPropertyValue(name).trim() || void 0;
+        return {
+            background: read('--background'),
+            destructive: read('--destructive'),
+            primary: read('--primary'),
+            foreground: read('--foreground'),
+            warning: read('--warning'),
+            success: read('--success'),
+            muted: read('--muted'),
+            mutedForeground: read('--muted-foreground'),
+            border: read('--border'),
+            popover: read('--popover'),
+            accent: read('--accent')
+        };
     } catch  {
-        return fallback;
+        return {};
     }
 };
 const appFlags = process.env.APP_FLAGS || {};
@@ -38,24 +52,47 @@ const App = (props)=>{
         });
     }, []);
     useEffect(()=>{
-        if ('production' === process.env.NODE_ENV) reportTeaEvent({
-            trackKey: TrackKey.VIEW,
-            trackParams: {
-                artifact_uid: getAppId(),
-                agent_id: 'agent_miaoda',
-                url: window.location.href
-            }
-        });
+        if ('production' === process.env.NODE_ENV) {
+            reportTeaEvent({
+                trackKey: TrackKey.VIEW,
+                trackParams: {
+                    artifact_uid: getAppId(),
+                    agent_id: 'agent_miaoda',
+                    url: window.location.href
+                }
+            });
+            const appId = getAppId();
+            const firstRenderTime = Math.round(performance.now());
+            const navEntry = performance.getEntriesByType('navigation')[0];
+            const pageLoadTime = navEntry && navEntry.loadEventEnd > 0 ? Math.round(navEntry.loadEventEnd - navEntry.startTime) : void 0;
+            slardar.sendEvent({
+                name: 'app-first-render',
+                metrics: {
+                    firstRenderTime,
+                    ...null != pageLoadTime ? {
+                        pageLoadTime
+                    } : {}
+                },
+                categories: {
+                    appId: appId ?? 'unknown',
+                    mode: isMiaodaPreview ? 'preview' : 'runtime'
+                }
+            });
+        }
     }, []);
     const appId = getAppId();
     const permissionApiUrl = isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/permissions/roles` : `/spark/app/${appId}/runtime/api/v1/permissions/roles`;
-    return /*#__PURE__*/ jsxs(AuthProvider, {
-        config: {
+    const authConfig = useMemo(()=>({
             enable: enableAuth,
             permissionApi: {
                 url: permissionApiUrl
             }
-        },
+        }), [
+        enableAuth,
+        permissionApiUrl
+    ]);
+    return /*#__PURE__*/ jsxs(AuthProvider, {
+        config: authConfig,
         children: [
             !disableToaster && true !== appFlags.customToaster && /*#__PURE__*/ jsx(Toaster, {}),
             'production' !== process.env.NODE_ENV && /*#__PURE__*/ jsx(MiaodaInspector, {}),
@@ -68,19 +105,7 @@ const App = (props)=>{
 };
 const AppContainer_AppContainer = (props)=>{
     const { children } = props;
-    const [cssColors, setCssColors] = useState(()=>({
-            background: readCssVarColor('--background'),
-            destructive: readCssVarColor('--destructive'),
-            primary: readCssVarColor('--primary'),
-            foreground: readCssVarColor('--foreground'),
-            warning: readCssVarColor('--warning'),
-            success: readCssVarColor('--success'),
-            muted: readCssVarColor('--muted'),
-            mutedForeground: readCssVarColor('--muted-foreground'),
-            border: readCssVarColor('--border'),
-            popover: readCssVarColor('--popover'),
-            accent: readCssVarColor('--accent')
-        }));
+    const [cssColors, setCssColors] = useState(readAllCssVarColors);
     useEffect(()=>{
         if ('production' === process.env.NODE_ENV) return ()=>{};
         const observer = new MutationObserver((mutations)=>{
@@ -99,19 +124,7 @@ const AppContainer_AppContainer = (props)=>{
                     const maxRetries = 10;
                     const retryDelay = 400;
                     const updateColors = ()=>{
-                        const newColors = {
-                            background: readCssVarColor('--background'),
-                            destructive: readCssVarColor('--destructive'),
-                            primary: readCssVarColor('--primary'),
-                            foreground: readCssVarColor('--foreground'),
-                            warning: readCssVarColor('--warning'),
-                            success: readCssVarColor('--success'),
-                            muted: readCssVarColor('--muted'),
-                            mutedForeground: readCssVarColor('--muted-foreground'),
-                            border: readCssVarColor('--border'),
-                            popover: readCssVarColor('--popover'),
-                            accent: readCssVarColor('--accent')
-                        };
+                        const newColors = readAllCssVarColors();
                         setCssColors((currentColors)=>{
                             if (JSON.stringify(currentColors) !== JSON.stringify(newColors)) {
                                 retryCount = 0;
@@ -183,7 +196,10 @@ const AppContainer_AppContainer = (props)=>{
     };
     return /*#__PURE__*/ jsxs(Fragment, {
         children: [
-            /*#__PURE__*/ jsx(safety, {}),
+            /*#__PURE__*/ jsx(Suspense, {
+                fallback: null,
+                children: /*#__PURE__*/ jsx(Safety, {})
+            }),
             /*#__PURE__*/ jsx(QueryProvider, {
                 children: /*#__PURE__*/ jsx(ConfigProvider, {
                     locale: zh_CN,

package/lib/components/AppContainer/safety.js

@@ -1,59 +1,33 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
-import { getCsrfToken } from "../../utils/getCsrfToken.js";
 import { getAppId } from "../../utils/getAppId.js";
-import { isNewPathEnabled } from "../../utils/apiPath.js";
 import { useIsMobile } from "../../hooks/index.js";
 import { X } from "lucide-react";
 import { Sheet, SheetContent, SheetTrigger } from "../ui/drawer.js";
+import { t } from "../../locales/index.js";
 const Component = ()=>{
     const HasClosedKey = `miaoda-creatByMiaoda-has-closed-${getAppId()}`;
     const [visible, setVisible] = useState(!window.localStorage?.getItem(HasClosedKey));
     const [open, setOpen] = useState(false);
     const isMobile = useIsMobile();
-    const [userinfo, setUserinfo] = useState(null);
-    const [isInternetVisible, setIsInternetVisible] = useState(false);
-    const [showBadge, setShowBadge] = useState(true);
-    const [badgeLoaded, setBadgeLoaded] = useState(false);
     const timeoutRef = useRef(null);
-    useEffect(()=>{
-        const appId = getAppId();
-        const csrfHeaders = {
-            'X-Suda-Csrf-Token': getCsrfToken()
-        };
-        const tenantInfoUrl = isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/studio/tenant_info` : `/spark/b/${appId}/tenant_info`;
-        fetch(tenantInfoUrl, {
-            headers: csrfHeaders
-        }).then((res)=>res.json()).then((data)=>{
-            setUserinfo(data?.data?.tenant_info);
-            setIsInternetVisible(data?.data?.is_internet_visible);
-        }).catch(()=>{});
-        const getPublishedUrl = isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/studio/get_published` : `/spark/b/${appId}/get_published`;
-        fetch(getPublishedUrl, {
-            headers: csrfHeaders
-        }).then((res)=>res.json()).then((data)=>{
-            const badge = data?.data?.app_info?.show_badge;
-            setShowBadge(false !== badge);
-        }).catch(()=>{
-            setShowBadge(true);
-        }).finally(()=>{
-            setBadgeLoaded(true);
-        });
-    }, []);
+    const platformData = window.__platform__ ?? {};
+    const tenantName = platformData.tenantName ?? '';
+    const isInternetVisible = platformData.isInternetVisible ?? false;
+    const showBadge = false !== platformData.showBadge;
     useEffect(()=>{
         if (isMobile) {
             const link = document.createElement('link');
             link.rel = 'preload';
             link.as = 'image';
-            link.href = 'https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover-mobile.png';
+            link.href = t('safety.cover.mobile');
             document.head.appendChild(link);
         }
     }, [
         isMobile
     ]);
     if ('production' !== process.env.NODE_ENV) return null;
-    if (!badgeLoaded) return null;
     if (!showBadge) return null;
     if (!visible) return null;
     if (isMobile) return /*#__PURE__*/ jsxs(Sheet, {
@@ -74,7 +48,7 @@ const Component = ()=>{
                         }),
                         /*#__PURE__*/ jsx("p", {
                             className: "shrink-0 min-w-[28px] m-0! text-[#EBEBEB]",
-                            children: "妙搭"
+                            children: t('safety.badge.label')
                         })
                     ]
                 })
@@ -90,7 +64,7 @@ const Component = ()=>{
                             onClick: ()=>setOpen(false)
                         }),
                         /*#__PURE__*/ jsx("img", {
-                            src: "https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover-mobile.png",
+                            src: t('safety.cover.mobile'),
                             alt: "",
                             className: "w-full h-full",
                             onClick: ()=>{
@@ -110,12 +84,11 @@ const Component = ()=>{
                                                     src: "https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/icon/icon_company_outlined.svg",
                                                     className: "shrink-0 w-[14px] h-[14px]"
                                                 }),
-                                                /*#__PURE__*/ jsxs("p", {
+                                                /*#__PURE__*/ jsx("p", {
                                                     className: "shrink-0 min-w-[96px] m-0! text-[#646A73] text-sm",
-                                                    children: [
-                                                        userinfo?.name,
-                                                        "运营"
-                                                    ]
+                                                    children: t('safety.tenant.operated', {
+                                                        name: tenantName
+                                                    })
                                                 })
                                             ]
                                         }),
@@ -128,7 +101,7 @@ const Component = ()=>{
                                                 }),
                                                 /*#__PURE__*/ jsx("p", {
                                                     className: "shrink-0 min-w-[163px] m-0! text-[#646A73] text-sm",
-                                                    children: "包含 AI 生成内容，请注意甄别"
+                                                    children: t('safety.ai.disclaimer')
                                                 })
                                             ]
                                         })
@@ -146,14 +119,14 @@ const Component = ()=>{
                                                 setTimeout(()=>setVisible(false), 200);
                                                 window.localStorage?.setItem(HasClosedKey, 'true');
                                             },
-                                            children: "不再展示"
+                                            children: t('safety.button.dontShowAgain')
                                         }),
                                         /*#__PURE__*/ jsx("div", {
                                             className: "flex-1 flex rounded-[99px] items-center justify-center border-[0.5px] border-black bg-black text-white cursor-pointer text-lg py-[12px]",
                                             onClick: ()=>{
                                                 window.open('https://miaoda.feishu.cn/landing', '_blank');
                                             },
-                                            children: "了解更多"
+                                            children: t('safety.button.learnMore')
                                         })
                                     ]
                                 })
@@ -186,7 +159,7 @@ const Component = ()=>{
                         }),
                         /*#__PURE__*/ jsx("p", {
                             className: "shrink-0 min-w-[60px] m-0! text-[#EBEBEB]",
-                            children: "由妙搭搭建"
+                            children: t('safety.badge.builtWith')
                         })
                     ]
                 })
@@ -210,7 +183,7 @@ const Component = ()=>{
                     className: "flex flex-col bg-[#1A1A1A]",
                     children: [
                         /*#__PURE__*/ jsx("img", {
-                            src: "https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover.png",
+                            src: t('safety.cover.pc'),
                             alt: "",
                             className: "w-[286px] h-[128px] cursor-pointer",
                             onClick: ()=>{
@@ -230,12 +203,11 @@ const Component = ()=>{
                                                     src: "https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/icon/icon_company_outlined.svg",
                                                     className: "shrink-0 w-[12px] h-[12px]"
                                                 }),
-                                                /*#__PURE__*/ jsxs("p", {
+                                                /*#__PURE__*/ jsx("p", {
                                                     className: "shrink-0 min-w-[96px] m-0! text-[#a6a6a6]",
-                                                    children: [
-                                                        userinfo?.name,
-                                                        "运营"
-                                                    ]
+                                                    children: t('safety.tenant.operated', {
+                                                        name: tenantName
+                                                    })
                                                 })
                                             ]
                                         }),
@@ -248,7 +220,7 @@ const Component = ()=>{
                                                 }),
                                                 /*#__PURE__*/ jsx("p", {
                                                     className: "shrink-0 min-w-[163px] m-0! text-[#a6a6a6]",
-                                                    children: "包含 AI 生成内容，请注意甄别"
+                                                    children: t('safety.ai.disclaimer')
                                                 })
                                             ]
                                         })
@@ -266,7 +238,7 @@ const Component = ()=>{
                                                 setVisible(false);
                                                 window.localStorage?.setItem(HasClosedKey, 'true');
                                             },
-                                            children: "不再展示"
+                                            children: t('safety.button.dontShowAgain')
                                         }),
                                         /*#__PURE__*/ jsx("div", {
                                             className: "flex-1 flex rounded-[8px] items-center justify-center h-[34px] border-[0.5px] border-solid border-[#ffffff1c] hover:border-[#ffffff33] bg-[#ffffff08] hover:bg-[#ffffff14] cursor-pointer text-[#ebebeb]",
@@ -274,7 +246,7 @@ const Component = ()=>{
                                             onClick: ()=>{
                                                 window.open('https://miaoda.feishu.cn/landing', '_blank');
                                             },
-                                            children: "了解更多"
+                                            children: t('safety.button.learnMore')
                                         })
                                     ]
                                 })

package/lib/hooks/useCurrentUserProfile.d.ts

@@ -1,5 +1,11 @@
 import { IUserProfile } from '../apis/udt-types';
-export interface ICompatibilityUserProfile extends IUserProfile {
+/**
+ * useCurrentUserProfile 的返回类型。
+ * 初始状态为空对象 `{}`（所有字段均为 undefined），异步获取用户信息后字段才会被填充。
+ * 使用时必须通过可选链或空值合并进行安全访问，如 `userInfo?.user_id`。
+ * 判断是否已加载完成应使用 `if (!userInfo?.user_id)` 而非 `if (!userInfo)`（因为空对象是 truthy）。
+ */
+export type ICompatibilityUserProfile = Partial<IUserProfile & {
     /**
      * @deprecated please use `name`
      */
@@ -8,5 +14,14 @@ export interface ICompatibilityUserProfile extends IUserProfile {
      * @deprecated please use `avatar`
      */
     userAvatar: string;
-}
-export declare const useCurrentUserProfile: () => ICompatibilityUserProfile;
+}>;
+export declare const useCurrentUserProfile: () => Partial<IUserProfile & {
+    /**
+     * @deprecated please use `name`
+     */
+    userName: string;
+    /**
+     * @deprecated please use `avatar`
+     */
+    userAvatar: string;
+}>;

package/lib/hooks/useCurrentUserProfile.js

@@ -3,11 +3,25 @@ import { logger } from "../logger/index.js";
 import { getCurrentUserProfile } from "../integrations/getCurrentUserProfile.js";
 import { getDataloom } from "../integrations/dataloom.js";
 import { isSparkRuntime } from "../utils/utils.js";
+import { getAxiosForBackend } from "../utils/getAxiosForBackend.js";
 function getNameFromArray(nameArray) {
     if (!nameArray || 0 === nameArray.length) return;
     const chineseName = nameArray.find((item)=>2052 === item.language_code);
     return chineseName?.text ?? nameArray[0]?.text;
 }
+let _larkUserIdCache = null;
+let _larkUserIdPromise = null;
+function fetchLarkUserId() {
+    if (null !== _larkUserIdCache) return Promise.resolve(_larkUserIdCache);
+    if (_larkUserIdPromise) return _larkUserIdPromise;
+    _larkUserIdPromise = getAxiosForBackend().get('/api/authnpaas/lark-user-id').then(({ data })=>{
+        _larkUserIdCache = data?.lark_user_id || null;
+        return _larkUserIdCache;
+    }).catch(()=>null).finally(()=>{
+        _larkUserIdPromise = null;
+    });
+    return _larkUserIdPromise;
+}
 function getCompatibilityUserProfile() {
     const userInfo = getCurrentUserProfile();
     return {
@@ -34,6 +48,8 @@ const useCurrentUserProfile = ()=>{
                 userName: userName,
                 userAvatar: info?.avatar?.image?.large
             };
+            const larkUserId = await fetchLarkUserId();
+            if (larkUserId) newUserInfo.lark_user_id = larkUserId;
             if ('development' === process.env.NODE_ENV) logger.info('MiaoDaMetaInfoChanged', newUserInfo);
             setUserInfo(newUserInfo);
         };

package/lib/integrations/getCurrentUserProfile.d.ts

@@ -1,5 +1,11 @@
 import { IUserProfile } from '../apis/udt-types';
-export declare function getCurrentUserProfile(): IUserProfile;
+/**
+ * 获取当前用户信息。
+ * 返回 Partial<IUserProfile>，因为初始值来自 window._userInfo，
+ * 该值在运行时始终为空对象 {}，所有字段均为 undefined。
+ * 异步获取用户信息后才会被填充为完整的 IUserProfile。
+ */
+export declare function getCurrentUserProfile(): Partial<IUserProfile>;
 /**
  * @deprecated 请使用 getCurrentUserProfile 代替
  */

package/lib/integrations/services/UserService.d.ts

@@ -1,12 +1,14 @@
-import type { BatchGetUsersResponse, SearchUsersParams, SearchUsersResponse } from './types';
+import type { BatchGetUsersResponse, ConvertExternalContactResponse, SearchUsersParams, SearchUsersResponse } from './types';
 export type UserServiceConfig = {
     getAppId?: () => string | null | undefined;
     searchUserUrl?: (appId: string) => string;
     listUsersUrl?: (appId: string) => string;
+    convertExternalContactUrl?: (appId: string) => string;
 };
 export declare class UserService {
     private config;
     constructor(config?: UserServiceConfig);
     searchUsers(params: SearchUsersParams): Promise<SearchUsersResponse>;
     listUsersByIds(userIds: string[]): Promise<BatchGetUsersResponse>;
+    convertExternalContact(larkUserID: string): Promise<ConvertExternalContactResponse>;
 }

package/lib/integrations/services/UserService.js

@@ -3,7 +3,8 @@ import { isNewPathEnabled } from "../../utils/apiPath.js";
 const DEFAULT_CONFIG = {
     getAppId: ()=>getAppId(),
     searchUserUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/search_user` : `/af/app/${appId}/runtime/api/v1/account/search_user`,
-    listUsersUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/list_users` : `/af/app/${appId}/runtime/api/v1/account/list_users`
+    listUsersUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/list_users` : `/af/app/${appId}/runtime/api/v1/account/list_users`,
+    convertExternalContactUrl: (appId)=>isNewPathEnabled() ? `/app/${appId}/__runtime__/api/v1/account/convert_lark_user` : `/af/app/${appId}/runtime/api/v1/account/convert_lark_user`
 };
 class UserService {
     config;
@@ -43,5 +44,23 @@ class UserService {
         if (!response.ok) throw new Error('Failed to fetch users by ids');
         return response.json();
     }
+    async convertExternalContact(larkUserID) {
+        const appId = this.config.getAppId();
+        if (!appId) throw new Error('Failed to get appId');
+        const response = await fetch(this.config.convertExternalContactUrl(appId), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                larkUserID
+            }),
+            credentials: 'include'
+        });
+        if (!response.ok) throw new Error('Failed to convert external contact');
+        const data = await response.json();
+        if (!data?.data?.userInfo?.userID) throw new Error('Invalid response from convert external contact');
+        return data;
+    }
 }
 export { UserService };

package/lib/integrations/services/types.d.ts

@@ -15,6 +15,7 @@ export type UserInfo = {
     userType: '_employee' | '_externalUser' | '_anonymousUser';
     department: DepartmentBasic;
     email?: string;
+    tenantName?: string;
 };
 export type DepartmentInfo = {
     departmentID: string;
@@ -33,6 +34,7 @@ export type SearchUsersParams = {
     query?: string;
     offset?: number;
     pageSize?: number;
+    searchExternalContact?: boolean;
 };
 export type SearchUsersResponse = {
     data: {
@@ -41,6 +43,14 @@ export type SearchUsersResponse = {
     };
     status_code: string;
 };
+export type ConvertExternalContactResponse = {
+    data: {
+        userInfo: {
+            tenantID: number;
+            userID: number;
+        };
+    };
+};
 export type BatchGetUsersResponse = {
     data: {
         userInfoMap: Record<string, UserInfo & SearchAvatar>;

package/lib/locales/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 获取当前语言环境下的翻译文案。
+ *
+ * 支持 `{key}` 形式的变量替换：
+ * ```ts
+ * t('safety.tenant.operated', { name: '字节' })
+ * // zh → "字节运营"
+ * // en → "Operated by 字节"
+ * ```
+ *
+ * 如果 key 不存在，fallback 到中文；中文也没有则返回 key 本身。
+ */
+export declare function t(key: string, params?: Record<string, string>): string;
+export { getLocale } from '../utils/locale';
+export type { Locale } from '../utils/locale';

package/lib/locales/index.js

@@ -0,0 +1,10 @@
+import messages from "./messages.js";
+import { getLocale } from "../utils/locale.js";
+function t(key, params) {
+    const locale = getLocale();
+    const entry = messages[key];
+    let text = entry?.[locale] ?? entry?.zh ?? key;
+    if (params) for (const [k, v] of Object.entries(params))text = text.replace(`{${k}}`, v);
+    return text;
+}
+export { getLocale, t };

package/lib/locales/messages.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 中英文文案源（统一管理）。
+ *
+ * 每条文案同时包含 zh 和 en，方便对照和维护。
+ * Key 规则：`{组件}.{区域}.{标识}`
+ * 文案来源：https://bytedance.larkoffice.com/wiki/BJCQwv9auiP9erkudMfcVIIGnRg
+ */
+declare const messages: Record<string, {
+    zh: string;
+    en: string;
+}>;
+export default messages;

package/lib/locales/messages.js

@@ -0,0 +1,36 @@
+const messages_messages = {
+    'safety.badge.label': {
+        zh: '妙搭',
+        en: 'Spark'
+    },
+    'safety.badge.builtWith': {
+        zh: '由妙搭搭建',
+        en: 'Built with Spark'
+    },
+    'safety.ai.disclaimer': {
+        zh: '包含 AI 生成内容，请注意甄别',
+        en: 'AI-generated content. Use with care.'
+    },
+    'safety.tenant.operated': {
+        zh: '{name}运营',
+        en: 'Operated by {name}'
+    },
+    'safety.button.dontShowAgain': {
+        zh: '不再展示',
+        en: "Don't show again"
+    },
+    'safety.button.learnMore': {
+        zh: '了解更多',
+        en: 'Learn more'
+    },
+    'safety.cover.pc': {
+        zh: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover.png',
+        en: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover-pcen.png'
+    },
+    'safety.cover.mobile': {
+        zh: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover-mobile.png',
+        en: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/LMfspH/ljhwZthlaukjlkulzlp/logo/miaodacover-weben.png'
+    }
+};
+const messages = messages_messages;
+export { messages as default };

package/lib/utils/axiosConfig.js

@@ -372,7 +372,18 @@ function initAxiosConfig(axiosInstance) {
                     name: 'toolkit_axios_403_downgrade',
                     categories: {
                         url: String(error.config?.url || ''),
-                        method: String(error.config?.method || '')
+                        method: String(error.config?.method || ''),
+                        ...'production' !== process.env.NODE_ENV && {
+                            responseData: (()=>{
+                                try {
+                                    const data = error.response?.data;
+                                    if (!data) return '';
+                                    return 'string' == typeof data ? data.slice(0, 512) : JSON.stringify(data).slice(0, 512);
+                                } catch  {
+                                    return '';
+                                }
+                            })()
+                        }
                     }
                 });
                 return error.response;
@@ -383,7 +394,19 @@ function initAxiosConfig(axiosInstance) {
             categories: {
                 url: String(error.config?.url || ''),
                 method: String(error.config?.method || ''),
-                status: String(error.response?.status || '')
+                status: String(error.response?.status || ''),
+                ...'production' !== process.env.NODE_ENV && {
+                    errorMessage: String(error.message || ''),
+                    responseData: (()=>{
+                        try {
+                            const data = error.response?.data;
+                            if (!data) return '';
+                            return 'string' == typeof data ? data.slice(0, 512) : JSON.stringify(data).slice(0, 512);
+                        } catch  {
+                            return '';
+                        }
+                    })()
+                }
             }
         });
         return Promise.reject(error);

package/lib/utils/getInitialInfo.js

@@ -24,10 +24,24 @@ async function getAppPublished() {
         console.error('Error fetching published app info:', error);
     }
 }
+function getPreloadedInfo() {
+    try {
+        const platformData = window.__platform__?.appPublished;
+        if (platformData && 'object' == typeof platformData) return platformData;
+    } catch  {}
+}
 let initialInfo;
 let pendingPromise = null;
 function getInitialInfo(refresh = false) {
     if (initialInfo && !refresh) return Promise.resolve(initialInfo);
+    if (!initialInfo && !refresh) {
+        const preloaded = getPreloadedInfo();
+        if (preloaded) {
+            initialInfo = preloaded;
+            if (initialInfo) window._bucket_id = initialInfo.app_runtime_extra?.bucket?.default_bucket_id;
+            return Promise.resolve(initialInfo);
+        }
+    }
     if (pendingPromise && !refresh) return pendingPromise;
     pendingPromise = getAppPublished().then((info)=>{
         initialInfo = info;

package/lib/utils/hmr-api.d.ts

@@ -9,6 +9,12 @@
  * @see docs/RFC_HMR_API.md
  */
 export interface HmrApi {
+    /**
+     * 注册 HMR 更新前回调（模块替换之前触发）
+     * @param callback 回调函数
+     * @returns cleanup 函数，用于取消注册
+     */
+    onBeforeApply?(callback: () => void): () => void;
     /**
      * 注册 HMR 成功回调
      * @param callback 成功回调函数
@@ -24,7 +30,7 @@ export interface HmrApi {
 }
 declare global {
     interface Window {
-        __VITE_HMR__?: HmrApi;
+        __VITE_HMR__?: Required<HmrApi>;
     }
 }
 /**

package/lib/utils/locale.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 统一的语言判断方法。
+ *
+ * 基于浏览器 Accept-Language（navigator.language）判断。
+ * 返回标准化的 locale code：'zh' | 'en'。
+ * 目前只区分中英文，未来需要更多语言时在此扩展。
+ */
+export type Locale = 'zh' | 'en';
+export declare function getLocale(): Locale;

package/lib/utils/locale.js

@@ -0,0 +1,5 @@
+function getLocale() {
+    const lang = navigator.language || 'zh';
+    return lang.startsWith('zh') ? 'zh' : 'en';
+}
+export { getLocale };

package/lib/utils/safeStringify.js

@@ -12,6 +12,11 @@ function safeStringify(obj) {
             if (value instanceof Set) return Array.from(value);
             if (void 0 === value) return 'undefined';
             if ('symbol' == typeof value) return value.toString();
+            if (value instanceof Error) return {
+                name: value.name,
+                message: value.message,
+                stack: value.stack
+            };
             return value;
         });
     } catch  {

package/lib/utils/safeStringify.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/safeStringify.spec.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { mapLogLevel, processLogParams, safeStringify } from "./safeStringify.js";
+describe('safeStringify', ()=>{
+    it('should serialize a plain string', ()=>{
+        expect(safeStringify('hello')).toBe('"hello"');
+    });
+    it('should serialize a plain object', ()=>{
+        expect(safeStringify({
+            a: 1
+        })).toBe('{"a":1}');
+    });
+    it('should handle circular references', ()=>{
+        const obj = {
+            a: 1
+        };
+        obj.self = obj;
+        expect(safeStringify(obj)).toBe('{"a":1,"self":"[Circular]"}');
+    });
+    it('should serialize BigInt as string', ()=>{
+        expect(safeStringify(BigInt(123))).toBe('"123"');
+    });
+    it('should serialize Date as ISO string', ()=>{
+        const date = new Date('2024-01-01T00:00:00.000Z');
+        expect(safeStringify(date)).toBe('"2024-01-01T00:00:00.000Z"');
+    });
+    it('should serialize Map as object', ()=>{
+        const map = new Map([
+            [
+                'key',
+                'value'
+            ]
+        ]);
+        expect(safeStringify(map)).toBe('{"key":"value"}');
+    });
+    it('should serialize Set as array', ()=>{
+        const set = new Set([
+            1,
+            2,
+            3
+        ]);
+        expect(safeStringify(set)).toBe('[1,2,3]');
+    });
+    it('should serialize undefined as string', ()=>{
+        expect(safeStringify({
+            a: void 0
+        })).toBe('{"a":"undefined"}');
+    });
+    it('should serialize Symbol as string', ()=>{
+        expect(safeStringify({
+            s: Symbol('test')
+        })).toBe('{"s":"Symbol(test)"}');
+    });
+    it('should serialize Error with name, message and stack', ()=>{
+        const err = new Error('something went wrong');
+        const result = JSON.parse(safeStringify(err));
+        expect(result.name).toBe('Error');
+        expect(result.message).toBe('something went wrong');
+        expect(result.stack).toContain('something went wrong');
+    });
+    it('should serialize Error subclass with correct name', ()=>{
+        const err = new TypeError('bad type');
+        const result = JSON.parse(safeStringify(err));
+        expect(result.name).toBe('TypeError');
+        expect(result.message).toBe('bad type');
+    });
+    it('should serialize Error nested in object', ()=>{
+        const err = new Error('inner error');
+        const result = JSON.parse(safeStringify({
+            err
+        }));
+        expect(result.err.name).toBe('Error');
+        expect(result.err.message).toBe('inner error');
+    });
+    it('should return empty string on unexpected failure', ()=>{
+        const bad = {
+            toJSON () {
+                throw new Error('fail');
+            }
+        };
+        expect(safeStringify(bad)).toBe('');
+    });
+});
+describe('processLogParams', ()=>{
+    it('should serialize single argument directly', ()=>{
+        expect(processLogParams([
+            'hello'
+        ])).toBe('"hello"');
+    });
+    it('should serialize single object argument', ()=>{
+        expect(processLogParams([
+            {
+                a: 1
+            }
+        ])).toBe('{"a":1}');
+    });
+    it('should serialize multiple arguments as indexed object', ()=>{
+        const result = JSON.parse(processLogParams([
+            'msg',
+            {
+                key: 'val'
+            }
+        ]));
+        expect(result['0']).toBe('msg');
+        expect(result['1']).toEqual({
+            key: 'val'
+        });
+    });
+});
+describe('mapLogLevel', ()=>{
+    it('should map error to ERROR', ()=>{
+        expect(mapLogLevel('error')).toBe('ERROR');
+    });
+    it('should map info to INFO', ()=>{
+        expect(mapLogLevel('info')).toBe('INFO');
+    });
+    it('should map success to INFO', ()=>{
+        expect(mapLogLevel('success')).toBe('INFO');
+    });
+    it('should map warn to WARN', ()=>{
+        expect(mapLogLevel('warn')).toBe('WARN');
+    });
+    it('should default unknown level to INFO', ()=>{
+        expect(mapLogLevel('debug')).toBe('INFO');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/client-toolkit",
-  "version": "1.2.28-alpha.7",
+  "version": "1.2.28-alpha.71",
   "types": "./lib/index.d.ts",
   "main": "./lib/index.js",
   "files": [
@@ -98,13 +98,13 @@
   "dependencies": {
     "@ant-design/colors": "^7.2.1",
     "@ant-design/cssinjs": "^1.24.0",
-    "@data-loom/js": "0.4.11",
-    "@lark-apaas/aily-web-sdk": "^0.0.7",
-    "@lark-apaas/auth-sdk": "^0.1.2",
+    "@data-loom/js": "0.4.13",
+    "@lark-apaas/aily-web-sdk": "^0.0.9",
+    "@lark-apaas/auth-sdk": "^0.1.4",
     "@lark-apaas/client-capability": "^0.1.6",
     "@lark-apaas/internal-slardar": "^0.0.3",
-    "@lark-apaas/miaoda-inspector": "^1.0.20",
-    "@lark-apaas/observable-web": "^1.0.5",
+    "@lark-apaas/miaoda-inspector": "^1.0.23",
+    "@lark-apaas/observable-web": "^1.0.6",
     "@radix-ui/react-avatar": "^1.1.10",
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-slot": "^1.2.3",