feat: manually mirror opencoze's code from bytedance

Change-Id: I09a73aadda978ad9511264a756b2ce51f5761adf

frontend/packages/agent-ide/chat-background-shared/.storybook/main.js

@@ -0,0 +1,31 @@
+import { mergeConfig } from 'vite';
+import svgr from 'vite-plugin-svgr';
+
+/** @type { import('@storybook/react-vite').StorybookConfig } */
+const config = {
+  stories: ['../stories/**/*.mdx', '../stories/**/*.stories.tsx'],
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-essentials',
+    '@storybook/addon-onboarding',
+    '@storybook/addon-interactions',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+  viteFinal: config =>
+    mergeConfig(config, {
+      plugins: [
+        svgr({
+          svgrOptions: {
+            native: false,
+          },
+        }),
+      ],
+    }),
+};
+export default config;

frontend/packages/agent-ide/chat-background-shared/.storybook/preview.js

@@ -0,0 +1,14 @@
+/** @type { import('@storybook/react').Preview } */
+const preview = {
+  parameters: {
+    actions: { argTypesRegex: "^on[A-Z].*" },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

frontend/packages/agent-ide/chat-background-shared/.stylelintrc.js

@@ -0,0 +1,5 @@
+const { defineConfig } = require('@coze-arch/stylelint-config');
+
+module.exports = defineConfig({
+  extends: [],
+});

frontend/packages/agent-ide/chat-background-shared/README.md

@@ -0,0 +1,16 @@
+# @coze-agent-ide/chat-background-shared
+
+> Project template for react component with storybook.
+
+## Features
+
+- [x] eslint & ts
+- [x] esm bundle
+- [x] umd bundle
+- [x] storybook
+
+## Commands
+
+- init: `rush update`
+- dev: `npm run dev`
+- build: `npm run build`

frontend/packages/agent-ide/chat-background-shared/__tests__/hook/use-background-content.test.ts

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { renderHook } from '@testing-library/react-hooks';
+import { useBotInfoStore } from '@coze-studio/bot-detail-store/bot-info';
+import {
+  DotStatus,
+  useGenerateImageStore,
+} from '@coze-studio/bot-detail-store';
+
+import { useBackgroundContent } from '../../src/hooks/use-background-content';
+
+vi.mock('@coze-studio/bot-detail-store', () => ({
+  useGenerateImageStore: vi.fn(),
+  DotStatus: vi.fn(),
+}));
+vi.mock('@coze-studio/bot-detail-store', () => ({
+  useGenerateImageStore: vi.fn(),
+  DotStatus: vi.fn(),
+}));
+vi.mock('@coze-studio/components', () => ({
+  GenerateType: vi.fn(),
+}));
+vi.mock('@coze-studio/bot-detail-store/bot-info', () => ({
+  useBotInfoStore: vi.fn(),
+}));
+vi.mock('@coze-arch/bot-api', () => ({
+  PlaygroundApi: {
+    CancelGenerateGif: vi.fn().mockResolvedValueOnce({
+      code: 0,
+    }),
+    MarkReadNotice: vi.fn().mockResolvedValueOnce({
+      code: 0,
+    }),
+  },
+}));
+
+describe('useBackgroundContent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  const openConfig = vi.fn();
+
+  (useBotInfoStore as unknown as Mock).mockReturnValue('xxx');
+  it('handleEdit should call openConfig', () => {
+    (useGenerateImageStore as unknown as Mock).mockReturnValue({
+      imageDotStatus: DotStatus.None,
+      gifDotStatus: DotStatus.None,
+    });
+    DotStatus;
+    const { result } = renderHook(() => useBackgroundContent({ openConfig }));
+    const { handleEdit } = result.current;
+    handleEdit();
+    expect(openConfig).toHaveBeenCalled();
+  });
+
+  it('showDot & showDotStatus', () => {
+    const { result } = renderHook(() => useBackgroundContent({ openConfig }));
+    const { showDotStatus, showDot } = result.current;
+    (useGenerateImageStore as unknown as Mock).mockReturnValueOnce({
+      imageDotStatus: DotStatus.None,
+      gifDotStatus: DotStatus.None,
+      setGenerateBackgroundModalByImmer: vi.fn(),
+    });
+    expect(showDotStatus).toBe(DotStatus.None);
+    expect(showDot).toBe(false);
+  });
+});

frontend/packages/agent-ide/chat-background-shared/__tests__/util.test.ts

@@ -0,0 +1,184 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import '@testing-library/jest-dom';
+
+import React from 'react';
+
+import { describe, it, expect, vi } from 'vitest';
+import { type BackgroundImageInfo } from '@coze-arch/bot-api/developer_api';
+
+import {
+  computePosition,
+  getInitBackground,
+  getOriginImageFromBackgroundInfo,
+} from '../src/utils';
+
+vi.mock('@coze-arch/bot-semi', () => ({
+  UIToast: {
+    error: vi.fn(),
+  },
+}));
+
+vi.mock('@coze-common/chat-uikit', () => ({
+  MODE_CONFIG: {
+    pc: {
+      size: {
+        width: 486,
+        height: 346,
+      },
+      centerWidth: 346,
+    },
+    mobile: {
+      size: {
+        width: 248,
+        height: 346,
+      },
+      centerWidth: 206,
+    },
+  },
+}));
+
+vi.mock('@coze-arch/coze-design', () => ({
+  Avatar: vi.fn(),
+  Tag: vi.fn(),
+}));
+vi.mock('@coze-arch/bot-error', () => ({
+  CustomError: vi.fn(() => Error),
+}));
+
+vi.mock('@coze-arch/bot-error', () => ({
+  CustomError: vi.fn(() => Error),
+}));
+
+describe('should compute position correctly', () => {
+  const cropperRef = React.createRef();
+  const cropperMock = {
+    getCanvasData: vi.fn(() => ({
+      left: 10,
+    })),
+    getImageData: vi.fn(() => ({
+      left: 5,
+      width: 20,
+    })),
+  };
+  // 使用 vi.spyOn 模拟 createRef 的行为
+  const createRefSpy = vi.spyOn(React, 'createRef').mockReturnValue(cropperRef);
+  // 手动设置 cropperRef.current 的值
+  cropperRef.current = {
+    cropper: cropperMock,
+  };
+  cropperRef.current = {
+    cropper: {
+      getCanvasData: vi.fn(() => ({
+        left: 10,
+      })),
+      getImageData: vi.fn(() => ({
+        left: 5,
+        width: 20,
+      })),
+    },
+  };
+
+  const mode = 'pc';
+  const result = computePosition(mode, cropperRef);
+  expect(result.left).toBe(0.03);
+  expect(result.right).toBe(0.92);
+  // 恢复 createRef 的原始行为
+  createRefSpy.mockRestore();
+});
+
+describe('getOriginImageFromBackgroundInfo', () => {
+  it('should return origin image info', () => {
+    const value: BackgroundImageInfo[] = [
+      {
+        web_background_image: {
+          origin_image_uri: '123',
+          origin_image_url: '234',
+        },
+      },
+    ];
+    const info = getOriginImageFromBackgroundInfo(value);
+    expect(info).toMatchObject({
+      uri: '123',
+      url: '234',
+    });
+  });
+});
+
+describe('getInitBackground', () => {
+  it('should return origin image', () => {
+    const value: BackgroundImageInfo[] = [
+      {
+        web_background_image: {
+          origin_image_uri: '123',
+          origin_image_url: '234',
+        },
+      },
+    ];
+    const info = getInitBackground({
+      isGenerateSuccess: false,
+      originBackground: value,
+      selectedImageInfo: {
+        tar_uri: '222',
+        tar_url: '111',
+      },
+    });
+    expect(info).toMatchObject({
+      uri: '123',
+      url: '234',
+    });
+  });
+
+  it('should return selected image', () => {
+    const value: BackgroundImageInfo[] = [
+      {
+        web_background_image: {
+          origin_image_uri: '123',
+          origin_image_url: '234',
+        },
+      },
+    ];
+    const info = getInitBackground({
+      isGenerateSuccess: true,
+      originBackground: value,
+      selectedImageInfo: {
+        tar_uri: '222',
+        tar_url: '111',
+      },
+    });
+    expect(info).toMatchObject({
+      url: '111',
+    });
+  });
+
+  it('should return empty image', () => {
+    const value: BackgroundImageInfo[] = [
+      {
+        web_background_image: {},
+      },
+    ];
+    const info = getInitBackground({
+      isGenerateSuccess: false,
+      originBackground: value,
+      selectedImageInfo: {
+        tar_uri: '222',
+        tar_url: '111',
+      },
+    });
+    expect(info).toMatchObject({});
+  });
+});

frontend/packages/agent-ide/chat-background-shared/config/rush-project.json

@@ -0,0 +1,12 @@
+{
+  "operationSettings": [
+    {
+      "operationName": "test:cov",
+      "outputFolderNames": ["coverage"]
+    },
+    {
+      "operationName": "ts-check",
+      "outputFolderNames": ["dist"]
+    }
+  ]
+}

frontend/packages/agent-ide/chat-background-shared/eslint.config.js

@@ -0,0 +1,7 @@
+const { defineConfig } = require('@coze-arch/eslint-config');
+
+module.exports = defineConfig({
+  packageRoot: __dirname,
+  preset: 'web',
+  rules: {},
+});

frontend/packages/agent-ide/chat-background-shared/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@coze-agent-ide/chat-background-shared",
+  "version": "0.0.1",
+  "description": "agent ide chat background shared",
+  "license": "Apache-2.0",
+  "author": "gaoyuanhan.duty@bytedance.com",
+  "maintainers": [],
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "exit 0",
+    "lint": "eslint ./ --cache",
+    "test": "vitest --run --passWithNoTests",
+    "test:cov": "npm run test -- --coverage"
+  },
+  "dependencies": {
+    "@coze-arch/bot-api": "workspace:*",
+    "@coze-arch/bot-error": "workspace:*",
+    "@coze-arch/bot-flags": "workspace:*",
+    "@coze-arch/bot-semi": "workspace:*",
+    "@coze-arch/bot-utils": "workspace:*",
+    "@coze-arch/i18n": "workspace:*",
+    "@coze-arch/logger": "workspace:*",
+    "@coze-common/chat-uikit": "workspace:*",
+    "@coze-studio/bot-audit-adapter": "workspace:*",
+    "@coze-studio/bot-detail-store": "workspace:*",
+    "@coze-studio/bot-utils": "workspace:*",
+    "@coze-studio/components": "workspace:*",
+    "ahooks": "^3.7.8",
+    "classnames": "^2.3.2",
+    "colorthief": "~2.4.0",
+    "lodash-es": "^4.17.21",
+    "nanoid": "^4.0.2",
+    "react-cropper": "^2.3.3",
+    "zustand": "^4.4.7"
+  },
+  "devDependencies": {
+    "@coze-arch/bot-typings": "workspace:*",
+    "@coze-arch/eslint-config": "workspace:*",
+    "@coze-arch/stylelint-config": "workspace:*",
+    "@coze-arch/ts-config": "workspace:*",
+    "@coze-arch/vitest-config": "workspace:*",
+    "@testing-library/jest-dom": "^6.1.5",
+    "@testing-library/react": "^14.1.2",
+    "@testing-library/react-hooks": "^8.0.1",
+    "@types/lodash-es": "^4.17.10",
+    "@types/react": "18.2.37",
+    "@types/react-dom": "18.2.15",
+    "@vitest/coverage-v8": "~3.0.5",
+    "react": "~18.2.0",
+    "react-dom": "~18.2.0",
+    "stylelint": "^15.11.0",
+    "vite-plugin-svgr": "~3.3.0",
+    "vitest": "~3.0.5"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-dom": ">=18.2.0"
+  }
+}
+

frontend/packages/agent-ide/chat-background-shared/src/constants/index.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+export const MAX_IMG_SIZE = 10 * 1024;
+
+export const FIRST_GUIDE_KEY_PREFIX = '__first_drag_guide__';
+
+export const MAX_AI_LIST_LENGTH = 10;

frontend/packages/agent-ide/chat-background-shared/src/hooks/use-background-content.ts

@@ -0,0 +1,164 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { useShallow } from 'zustand/react/shallow';
+import { useRequest } from 'ahooks';
+import { GenerateType } from '@coze-studio/components';
+import { useBotInfoStore } from '@coze-studio/bot-detail-store/bot-info';
+import {
+  DotStatus,
+  useGenerateImageStore,
+} from '@coze-studio/bot-detail-store';
+import { PicType } from '@coze-arch/bot-api/playground_api';
+import { type BackgroundImageInfo } from '@coze-arch/bot-api/developer_api';
+import { PlaygroundApi } from '@coze-arch/bot-api';
+
+export interface UseBackgroundContentProps {
+  openConfig?: () => void;
+  setBackgroundImageInfoList?: (value: BackgroundImageInfo[]) => void;
+}
+
+const getShowDot = (imageDotStatus: DotStatus, gifDotStatus: DotStatus) =>
+  imageDotStatus !== DotStatus.None || gifDotStatus !== DotStatus.None;
+
+const getGeneratingType = (
+  imageDotStatus: DotStatus,
+  gifDotStatus: DotStatus,
+) =>
+  imageDotStatus === DotStatus.Generating
+    ? PicType.BackgroundStatic
+    : gifDotStatus === DotStatus.Generating
+    ? PicType.BackgroundGif
+    : undefined;
+
+export const useBackgroundContent = (props?: UseBackgroundContentProps) => {
+  const { openConfig, setBackgroundImageInfoList } = props ?? {};
+  const {
+    messageList,
+    imageDotStatus,
+    gifDotStatus,
+    setGenerateBackgroundModalByImmer,
+  } = useGenerateImageStore(
+    useShallow(state => ({
+      messageList: state.imageList,
+      imageDotStatus: state.generateBackGroundModal.image.dotStatus,
+      gifDotStatus: state.generateBackGroundModal.gif.dotStatus,
+      setGenerateBackgroundModalByImmer:
+        state.setGenerateBackgroundModalByImmer,
+      selectedImage: state.generateBackGroundModal.selectedImage,
+    })),
+  );
+
+  const botId = useBotInfoStore(s => s.botId);
+  //最新的 静图与动图 未读 - 生成中/成功/失败，展示原点状态
+  const showDot = getShowDot(imageDotStatus, gifDotStatus);
+
+  const hasDotType =
+    imageDotStatus !== DotStatus.None
+      ? PicType.BackgroundStatic
+      : PicType.BackgroundGif;
+
+  const generatingType = getGeneratingType(imageDotStatus, gifDotStatus);
+
+  const { runAsync: markReadNotice } = useRequest(
+    async () =>
+      await PlaygroundApi.MarkReadNotice({
+        pic_type: hasDotType,
+        bot_id: botId,
+      }),
+    {
+      manual: true,
+    },
+  );
+  const imageReadExpression = (status: DotStatus) =>
+    status !== DotStatus.None && status !== DotStatus.Generating;
+
+  const markRead = async () => {
+    if (showDot) {
+      setGenerateBackgroundModalByImmer(state => {
+        // 设置当前tab
+        state.activeKey =
+          imageDotStatus !== DotStatus.None
+            ? GenerateType.Static
+            : GenerateType.Gif;
+        // 设置已读状态：失败/成功需要设置已读，进行中/无状态 不需要
+        if (
+          imageReadExpression(imageDotStatus) &&
+          hasDotType === PicType.BackgroundStatic
+        ) {
+          state.image.dotStatus = DotStatus.None;
+        }
+        if (
+          imageReadExpression(gifDotStatus) &&
+          hasDotType === PicType.BackgroundGif
+        ) {
+          state.gif.dotStatus = DotStatus.None;
+        }
+      });
+
+      if (
+        imageReadExpression(imageDotStatus) ||
+        imageReadExpression(gifDotStatus)
+      ) {
+        await markReadNotice();
+      }
+    }
+  };
+
+  const handleEdit = () => {
+    // 打开编辑弹窗
+    openConfig?.();
+  };
+
+  const handleRemove = async () => {
+    // 存在进行中的任务时
+    if (generatingType) {
+      // 取消继续生成
+      const generatingTaskId = messageList.find(
+        item => item.type === generatingType,
+      )?.id;
+      await PlaygroundApi.CancelGenerateGif({
+        task_id: generatingTaskId,
+      });
+      setGenerateBackgroundModalByImmer(state => {
+        if (generatingType === PicType.BackgroundGif) {
+          state.gif.loading = false;
+          state.gif.dotStatus = DotStatus.None;
+        }
+        if (generatingType === PicType.BackgroundStatic) {
+          state.image.loading = false;
+          state.image.dotStatus = DotStatus.None;
+        }
+        state.generatingTaskId = '';
+      });
+    }
+    // 有状态的标记已读
+    await markRead();
+    // 清空当前渲染的背景图
+    setBackgroundImageInfoList?.([]);
+  };
+
+  const showDotStatus =
+    imageDotStatus !== DotStatus.None ? imageDotStatus : gifDotStatus;
+
+  return {
+    handleEdit,
+    showDot,
+    showDotStatus,
+    handleRemove,
+    markRead,
+  };
+};

frontend/packages/agent-ide/chat-background-shared/src/hooks/use-crop-image.ts

@@ -0,0 +1,174 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { type ReactCropperElement } from 'react-cropper';
+import { type RefObject, useState, useEffect, useRef } from 'react';
+
+import { ceil, floor } from 'lodash-es';
+import { MODE_CONFIG } from '@coze-common/chat-uikit';
+import {
+  type BackgroundImageDetail,
+  type GradientPosition,
+} from '@coze-arch/bot-api/developer_api';
+
+import { computePosition, getImageThemeColor } from '../utils';
+
+export const useCropperImg = ({
+  cropperRef,
+  url,
+  mode,
+  setLoading,
+  backgroundInfo,
+}: {
+  cropperRef: RefObject<ReactCropperElement>;
+  url: string;
+  mode: 'pc' | 'mobile';
+  setLoading: (loading: boolean) => void;
+  backgroundInfo?: BackgroundImageDetail;
+}) => {
+  const [gradientPosition, setGradientPosition] = useState<GradientPosition>({
+    left: 0,
+    right: 0,
+  });
+  const [themeColor, setThemeColor] = useState(
+    backgroundInfo?.theme_color ?? '#fff',
+  );
+  const currentUrl = useRef(url);
+  const { size, centerWidth } = MODE_CONFIG[mode];
+  useEffect(() => {
+    currentUrl.current = url;
+    if (!url) {
+      setThemeColor('#fff');
+    }
+    handleGradientPosition();
+  }, [url]);
+
+  // 设置最大缩放比例
+  const onZoom = () => {
+    const {
+      width = 0,
+      height = 0,
+      naturalWidth = 0,
+      naturalHeight = 0,
+    } = cropperRef.current?.cropper?.getCanvasData() ?? {};
+
+    if (naturalWidth > naturalHeight) {
+      if (height >= size.height * 2) {
+        cropperRef.current?.cropper.setCanvasData({
+          height: size.width * 2,
+        });
+      }
+    } else {
+      if (width > size.width * 2) {
+        cropperRef.current?.cropper.setCanvasData({
+          width: size.width * 2,
+        });
+      }
+    }
+    // TODO:因没有缩放end事件，缩放实时获取主题色大图卡顿严重，故此场景临时先不获取主题色，修改交互or尝试webworker解决此问题
+    // await handleThemeColor();
+  };
+
+  const handleGradientPosition = () => {
+    const position = computePosition(mode, cropperRef);
+    setGradientPosition(position);
+  };
+
+  const handleDragLimit = (y: number) => {
+    const cropperObj = cropperRef?.current?.cropper;
+
+    if (!cropperObj) {
+      return;
+    }
+    const canvasData = cropperObj?.getCanvasData();
+    const imgData = cropperObj?.getImageData();
+    // 图片下边缘 距离 裁剪区下边缘的偏移距离
+    const scaleTop = imgData.height + canvasData.top - size.height;
+    // 图片左边缘 距离 裁剪区左 边缘的偏移距离
+    const scaleLeft = ceil(imgData.left + canvasData?.left, 2);
+
+    // 图片上下拖拽不能有超出图片容器外
+    if (y < 0) {
+      cropperRef.current?.cropper.setCanvasData({
+        top: 0,
+      });
+    }
+    if (scaleTop < 0) {
+      cropperRef.current?.cropper.setCanvasData({
+        top: size.height - imgData.height,
+      });
+    }
+
+    // 产品需求： 左右拖动不能超过 固定“对话气泡容器” left or right 80%
+    const maxRightOffset = floor(
+      (size.width - centerWidth) / 2 + centerWidth * 0.4,
+      2,
+    );
+    const maxLeftOffset = floor(size.width - imgData.width - maxRightOffset, 2);
+    if (scaleLeft > maxRightOffset || scaleLeft < maxLeftOffset) {
+      cropperRef.current?.cropper.setCanvasData({
+        left: scaleLeft > maxRightOffset ? maxRightOffset : maxLeftOffset,
+      });
+    }
+  };
+
+  const handleCrop = (detail: Cropper.CropEvent) => {
+    handleGradientPosition();
+    handleDragLimit(detail.detail.y);
+  };
+
+  const cropEnd = async () => {
+    await handleThemeColor();
+    handleGradientPosition();
+  };
+
+  const handleThemeColor = async () => {
+    const cropperObj = cropperRef.current?.cropper;
+    // 大图move卡顿优化方案：move停止时获取到主题色前 禁止移动
+    cropperObj?.disable();
+    // 为了加载快一些，设置图片质量中等
+    const corp = cropperObj?.getCroppedCanvas()?.toDataURL('image/webp', 0.7);
+    if (corp) {
+      const color = await getImageThemeColor(corp);
+      setThemeColor(color);
+      cropperObj?.enable();
+    }
+  };
+
+  const handleReady = async () => {
+    const cropperObj = cropperRef.current?.cropper;
+    if (
+      backgroundInfo?.canvas_position &&
+      currentUrl.current === backgroundInfo.origin_image_url
+    ) {
+      cropperObj?.setCanvasData(backgroundInfo?.canvas_position);
+    }
+    await handleThemeColor();
+
+    setLoading(false);
+  };
+
+  return {
+    gradientPosition,
+    handleReady,
+    handleThemeColor,
+    handleCrop,
+    cropEnd,
+    onZoom,
+    themeColor,
+    size,
+  };
+};

frontend/packages/agent-ide/chat-background-shared/src/hooks/use-drag-image.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import type React from 'react';
+import { type DragEventHandler, useRef, useState } from 'react';
+
+const checkHasFileOnDrag = (e: React.DragEvent<HTMLDivElement>) =>
+  Boolean(e.dataTransfer?.types.includes('Files'));
+
+export const useDragImage = () => {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const [isDragIn, setIsDragIn] = useState(false);
+
+  const clearTimer = () => {
+    if (!timer.current) {
+      return;
+    }
+    clearTimeout(timer.current);
+    timer.current = null;
+  };
+  const onDragEnter: DragEventHandler<HTMLDivElement> = e => {
+    clearTimer();
+    if (!checkHasFileOnDrag(e)) {
+      return;
+    }
+    setIsDragIn(true);
+  };
+
+  const onDragEnd = () => {
+    clearTimer();
+    timer.current = setTimeout(() => {
+      setIsDragIn(false);
+    }, 100);
+  };
+
+  const onDragOver: DragEventHandler<HTMLDivElement> = e => {
+    e.preventDefault();
+    clearTimer();
+    if (!checkHasFileOnDrag(e)) {
+      return;
+    }
+    setIsDragIn(true);
+  };
+
+  return {
+    isDragIn,
+    setIsDragIn,
+    onDragEnter,
+    onDragEnd,
+    onDragOver,
+  };
+};

frontend/packages/agent-ide/chat-background-shared/src/hooks/use-submit-cropped-image.ts

@@ -0,0 +1,162 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { type ReactCropperElement } from 'react-cropper';
+import { useRef, type RefObject } from 'react';
+
+import { logger } from '@coze-arch/logger';
+import { type FileItem } from '@coze-arch/bot-semi/Upload';
+import {
+  type BackgroundImageDetail,
+  type BackgroundImageInfo,
+} from '@coze-arch/bot-api/developer_api';
+import { useBotInfoAuditor } from '@coze-studio/bot-audit-adapter';
+
+import { canvasPosition, computePosition, computeThemeColor } from '../utils';
+import { useUploadImage } from './use-upload-img';
+
+export interface SubmitCroppedImageParams {
+  cropperWebRef: RefObject<ReactCropperElement>;
+  cropperMobileRef: RefObject<ReactCropperElement>;
+  setLoading: (loading: boolean) => void;
+  getUserId: () => {
+    userId: string;
+  };
+  onSuccess: (value: BackgroundImageInfo[]) => void;
+  currentOriginImage: Partial<FileItem>;
+  handleCancel: () => void;
+  onAuditCheck: (notPass: boolean) => void;
+}
+
+export interface FileValue {
+  uri: string;
+  url: string;
+}
+
+interface GetBackgroundInfoItemParams {
+  mode: 'pc' | 'mobile';
+  originImageInfo: {
+    origin_image_uri: string;
+    origin_image_url: string;
+  };
+  themeColorList: string[];
+}
+export const useSubmitCroppedImage = ({
+  cropperWebRef,
+  cropperMobileRef,
+  setLoading,
+  getUserId,
+  onSuccess,
+  currentOriginImage,
+  handleCancel,
+  onAuditCheck,
+}: SubmitCroppedImageParams) => {
+  const fileList = useRef<File[]>([]);
+  const { check } = useBotInfoAuditor();
+
+  const getBackgroundInfoItem = ({
+    mode,
+    originImageInfo,
+    themeColorList,
+  }: GetBackgroundInfoItemParams): BackgroundImageDetail => {
+    const cropperRef = mode === 'pc' ? cropperWebRef : cropperMobileRef;
+    return {
+      ...originImageInfo,
+      theme_color: mode === 'pc' ? themeColorList[0] : themeColorList[1],
+      gradient_position: computePosition(mode, cropperRef),
+      canvas_position: canvasPosition(cropperRef),
+    };
+  };
+
+  const handleUploadAllSuccess = async (croppedImageList?: FileValue[]) => {
+    setLoading(false);
+
+    const themeColorList = await computeThemeColor([
+      cropperWebRef,
+      cropperMobileRef,
+    ]);
+
+    if (!currentOriginImage?.url) {
+      return;
+    }
+
+    const originImageInfo = {
+      origin_image_uri: croppedImageList?.[0]?.uri || currentOriginImage.uri,
+      origin_image_url: croppedImageList?.[0]?.url || currentOriginImage.url,
+    };
+    const info = {
+      themeColorList,
+      originImageInfo,
+    };
+    const backgroundImageList = [
+      {
+        web_background_image: getBackgroundInfoItem({
+          mode: 'pc',
+          ...info,
+        }),
+        mobile_background_image: getBackgroundInfoItem({
+          mode: 'mobile',
+          ...info,
+        }),
+      },
+    ];
+    fileList.current = [];
+
+    const res = await check({
+      background_images_struct: backgroundImageList?.[0],
+    });
+    const notPass = Boolean(res?.check_not_pass);
+    onAuditCheck(notPass);
+    if (notPass) {
+      // 机审未通过，就不执行下面回调
+      return;
+    }
+
+    onSuccess(backgroundImageList);
+    handleCancel();
+  };
+  const { uploadFileList } = useUploadImage({
+    onUploadAllSuccess: handleUploadAllSuccess,
+    getUserId: () => getUserId().userId,
+    onUploadError: () => {
+      setLoading(false);
+    },
+    onAuditError: () => onAuditCheck(true),
+  });
+
+  const handleSubmit = () => {
+    setLoading(true);
+
+    try {
+      if (
+        currentOriginImage?.fileInstance &&
+        currentOriginImage?.fileInstance instanceof File
+      ) {
+        fileList.current = [currentOriginImage.fileInstance];
+        uploadFileList(fileList.current);
+      } else {
+        // 回填文件时 不需要存原图
+        handleUploadAllSuccess();
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        logger.error({ error });
+      }
+    }
+  };
+
+  return { handleSubmit };
+};

frontend/packages/agent-ide/chat-background-shared/src/hooks/use-upload-img.ts

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { useEffect, useRef } from 'react';
+
+import { nanoid } from 'nanoid';
+import { withSlardarIdButton } from '@coze-studio/bot-utils';
+import { I18n } from '@coze-arch/i18n';
+import { Toast } from '@coze-arch/bot-semi';
+
+// import { type UploadState } from '../type';
+
+import { UploadController } from '../service/upload-controller';
+
+export const useUploadImage = ({
+  getUserId,
+  onUploadError,
+  onUploadAllSuccess,
+  onAuditError,
+}: {
+  getUserId: () => string;
+  onUploadAllSuccess: (param: { url: string; uri: string }[]) => void;
+  onUploadError: () => void;
+  onAuditError?: () => void;
+}) => {
+  const uploadControllerMap = useRef<Record<string, UploadController>>({});
+
+  const deleteUploadControllerById = (id: string) => {
+    delete uploadControllerMap.current[id];
+  };
+  const cancelUploadById = (id: string) => {
+    const controller = uploadControllerMap.current[id];
+    if (!controller) {
+      return;
+    }
+    controller.cancel();
+    deleteUploadControllerById(id);
+  };
+
+  const handleError = (_e: unknown, controllerId: string) => {
+    cancelUploadById(controllerId);
+    onUploadError();
+    Toast.error({
+      content: withSlardarIdButton(I18n.t('Upload_failed')),
+      showClose: false,
+    });
+  };
+
+  const onAuditFailed = () => {
+    if (onAuditError) {
+      onAuditError();
+    } else {
+      Toast.error({
+        content: I18n.t('inappropriate_contents'),
+        showClose: false,
+      });
+    }
+    onUploadError();
+  };
+
+  const uploadFileList = (fileList: File[]) => {
+    const controllerId = nanoid();
+
+    if (!fileList.length) {
+      return;
+    }
+
+    uploadControllerMap.current[controllerId] = new UploadController({
+      fileList,
+      controllerId,
+      userId: getUserId(),
+      onComplete: event => {
+        onUploadAllSuccess(event);
+      },
+      onUploadError: handleError,
+      onGetTokenError: handleError,
+      onGetUploadInstanceError: handleError,
+      onAuditFailed,
+    });
+  };
+
+  const clearAllSideEffect = () => {
+    Object.entries(uploadControllerMap.current).forEach(([, controller]) =>
+      controller.cancel(),
+    );
+    uploadControllerMap.current = {};
+  };
+
+  useEffect(() => clearAllSideEffect, []);
+
+  return {
+    uploadFileList,
+  };
+};

frontend/packages/agent-ide/chat-background-shared/src/index.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+export {
+  useBackgroundContent,
+  type UseBackgroundContentProps,
+} from './hooks/use-background-content';
+export { useSubmitCroppedImage } from './hooks/use-submit-cropped-image';
+export { useUploadImage } from './hooks/use-upload-img';
+export { useDragImage } from './hooks/use-drag-image';
+export { useCropperImg } from './hooks/use-crop-image';
+
+export { UploadMode } from './types';
+
+export {
+  checkImageWidthAndHeight,
+  getModeInfo,
+  getOriginImageFromBackgroundInfo,
+  getInitBackground,
+  computePosition,
+  canvasPosition,
+  computeThemeColor,
+  getImageThemeColor,
+} from './utils';
+
+export {
+  MAX_AI_LIST_LENGTH,
+  MAX_IMG_SIZE,
+  FIRST_GUIDE_KEY_PREFIX,
+} from './constants';

frontend/packages/agent-ide/chat-background-shared/src/service/upload-controller.ts

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import {
+  uploadFileV2,
+  type EventPayloadMaps as BaseEventPayloadMap,
+  type UploaderInstance,
+  type UploadFileV2Param,
+  type FileItem,
+} from '@coze-arch/bot-utils/upload-file-v2';
+import { GetImageScene } from '@coze-arch/bot-api/playground_api';
+import { PlaygroundApi } from '@coze-arch/bot-api';
+
+export type EventPayloadMap = BaseEventPayloadMap & {
+  ready: boolean;
+};
+
+export interface UploadControllerProps {
+  controllerId: string;
+  fileList: File[];
+  userId: string;
+  onProgress?: (
+    event: EventPayloadMap['progress'],
+    controllerId: string,
+  ) => void;
+  onComplete?: (
+    event: {
+      url: string;
+      uri: string;
+    }[],
+    controllerId: string,
+  ) => void;
+  onUploadError?: (event: Error, controllerId: string) => void;
+  onUploaderReady?: (
+    event: EventPayloadMap['ready'],
+    controllerId: string,
+  ) => void;
+  onStartUpload?: (
+    param: Parameters<Required<UploadFileV2Param>['onStartUpload']>[number],
+    controllerId: string,
+  ) => void;
+  onGetUploadInstanceError?: (error: Error, controllerId: string) => void;
+  onGetTokenError?: (error: Error, controllerId: string) => void;
+  onAuditFailed?: (controllerId: string) => void;
+}
+
+const isImage = (file: File) => file.type.startsWith('image/');
+
+export class UploadController {
+  controllerId: string;
+  abortController: AbortController;
+  uploader: UploaderInstance | null;
+  fileItemList: FileItem[];
+
+  constructor({
+    controllerId,
+    fileList,
+    userId,
+    onProgress,
+    onComplete,
+    onUploadError,
+    onUploaderReady,
+    onStartUpload,
+    onGetTokenError,
+    onGetUploadInstanceError,
+    onAuditFailed,
+  }: UploadControllerProps) {
+    this.fileItemList = fileList.map(file => ({
+      file,
+      fileType: isImage(file) ? 'image' : 'object',
+    }));
+    this.controllerId = controllerId;
+    this.abortController = new AbortController();
+    this.uploader = null;
+
+    uploadFileV2({
+      fileItemList: this.fileItemList,
+      userId,
+      signal: this.abortController.signal,
+      timeout: undefined,
+      onUploaderReady: uploader => {
+        this.uploader = uploader;
+        onUploaderReady?.(true, controllerId);
+      },
+      onProgress: event => onProgress?.(event, controllerId),
+      onUploadAllSuccess: async event => {
+        const uris = event.map(item => {
+          const uri = item.uploadResult.Uri;
+          if (!uri) {
+            throw new Error(`failed to get uri, item: ${item}`);
+          }
+          return uri;
+        });
+        try {
+          if (!uris || !uris.length) {
+            throw new Error(`upload success without uri, uploadID ${event}`);
+          }
+
+          const result = await PlaygroundApi.GetImagexShortUrl({
+            uris,
+            scene: GetImageScene.BackgroundImage,
+          });
+
+          const list = uris.map(item => {
+            if (!item) {
+              throw new Error(`failed to get url, uri: ${item}`);
+            }
+            return {
+              url: result.data?.url_info?.[item].url as string,
+              uri: item,
+            };
+          });
+
+          if (!list) {
+            throw new Error(`failed to get urls, list: ${list}`);
+          }
+          if (!list.some(i => i.url)) {
+            onAuditFailed?.(controllerId);
+          } else {
+            onComplete?.(list, controllerId);
+          }
+        } catch (e) {
+          onUploadError?.(
+            e instanceof Error ? e : new Error(String(e)),
+            controllerId,
+          );
+        }
+      },
+      onUploadError: event => onUploadError?.(event.extra.error, controllerId),
+      onStartUpload: event => onStartUpload?.(event, controllerId),
+      onGetUploadInstanceError: error =>
+        onGetUploadInstanceError?.(error, controllerId),
+      onGetTokenError: error => onGetTokenError?.(error, controllerId),
+    });
+  }
+
+  cancel = () => {
+    this.abortController.abort();
+  };
+
+  pause = () => {
+    this.uploader?.pause();
+  };
+}

frontend/packages/agent-ide/chat-background-shared/src/types/index.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+export enum UploadMode {
+  Manual,
+  Generate,
+}

frontend/packages/agent-ide/chat-background-shared/src/typings.d.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+/// <reference types='@coze-arch/bot-typings' />

frontend/packages/agent-ide/chat-background-shared/src/utils/index.ts

@@ -0,0 +1,191 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { type ReactCropperElement } from 'react-cropper';
+import { type RefObject } from 'react';
+
+import { floor, pick } from 'lodash-es';
+import ColorThief from 'colorthief';
+import { MODE_CONFIG } from '@coze-common/chat-uikit';
+import { I18n } from '@coze-arch/i18n';
+import { UIToast } from '@coze-arch/bot-semi';
+import { CustomError } from '@coze-arch/bot-error';
+import { type PicTask } from '@coze-arch/bot-api/playground_api';
+import {
+  type BackgroundImageInfo,
+  type CanvasPosition,
+  type GradientPosition,
+} from '@coze-arch/bot-api/developer_api';
+
+const MIN_HEIGHT = 640;
+// 图片上传限制宽高的函数，如果符合条件返回true，否者返回false
+export const checkImageWidthAndHeight = (file: Blob): Promise<boolean> =>
+  new Promise((resolve, reject) => {
+    const fileReader = new FileReader();
+    fileReader.onload = event => {
+      const result = event.target?.result;
+      if (!result || typeof result !== 'string') {
+        reject(
+          new CustomError('checkImageWidthAndHeight', 'file read invalid'),
+        );
+        return;
+      }
+      const image = new Image();
+      image.src = result;
+      image.onload = function () {
+        if (image.height < MIN_HEIGHT) {
+          UIToast.error(I18n.t('bgi_upload_image_format_requirement'));
+          resolve(false);
+        } else if (image.complete) {
+          resolve(true);
+        }
+      };
+    };
+    fileReader.onerror = () => {
+      reject(new CustomError('checkImageWidthAndHeight', 'file read fail'));
+    };
+    fileReader.onabort = () => {
+      reject(new CustomError('checkImageWidthAndHeight', 'file read abort'));
+    };
+    fileReader.readAsDataURL(file);
+  });
+
+export const getModeInfo = (mode: 'pc' | 'mobile') => MODE_CONFIG[mode];
+
+export const getOriginImageFromBackgroundInfo = (
+  value: BackgroundImageInfo[],
+): {
+  url: string;
+  uri: string;
+} => ({
+  url: value[0]?.web_background_image?.origin_image_url ?? '',
+  uri: value[0]?.web_background_image?.origin_image_uri ?? '',
+});
+
+export const getInitBackground = ({
+  isGenerateSuccess,
+  selectedImageInfo,
+  originBackground,
+}: {
+  isGenerateSuccess: boolean;
+  originBackground: BackgroundImageInfo[];
+  selectedImageInfo: PicTask['img_info'];
+}) => {
+  if (isGenerateSuccess && selectedImageInfo?.tar_url) {
+    return {
+      url: selectedImageInfo.tar_url,
+      uri: selectedImageInfo.tar_uri,
+    };
+  }
+  if (getOriginImageFromBackgroundInfo(originBackground).url) {
+    return getOriginImageFromBackgroundInfo(originBackground);
+  }
+
+  return {};
+};
+
+// 计算阴影位置
+export const computePosition = (
+  mode: 'pc' | 'mobile',
+  cropperRef: RefObject<ReactCropperElement>,
+): GradientPosition => {
+  const cropperObj = cropperRef?.current?.cropper;
+  if (!cropperObj) {
+    return {
+      left: 0,
+      right: 0,
+    };
+  }
+  const { size } = getModeInfo(mode);
+  const cropperWidth = size.width;
+  const canvasData = cropperObj?.getCanvasData();
+  const imgData = cropperObj?.getImageData();
+
+  // 图片左边缘 距离 裁剪区左 边缘的偏移距离
+  const imgToScreenLeft = imgData.left + canvasData?.left;
+  // 图片距离右侧屏幕的距离， > 0 时，右侧未充满图片
+  const imgToScreenRight = cropperWidth - imgData.width - imgToScreenLeft;
+
+  // 左侧渲染的渐变需要的left值: 左侧有空隙时渲染left，否则无需
+  const leftPercent = floor(imgToScreenLeft / cropperWidth, 2);
+
+  // 右侧渲染的渐变需要的right值
+  const rightPercent = floor(imgToScreenRight / cropperWidth, 2);
+
+  return {
+    left: leftPercent,
+    right: rightPercent,
+  };
+};
+
+export const canvasPosition = (
+  cropperRef: RefObject<ReactCropperElement>,
+): CanvasPosition =>
+  pick(cropperRef.current?.cropper.getCanvasData(), [
+    'left',
+    'top',
+    'width',
+    'height',
+  ]);
+
+// 计算主题色
+export const computeThemeColor = (
+  cropperRefList: RefObject<ReactCropperElement>[],
+): Promise<string[]> =>
+  new Promise((resolve, reject) => {
+    const promises: Promise<string>[] = [];
+    // 处理每个canvas元素
+    cropperRefList.forEach(cropperEle => {
+      promises.push(
+        new Promise<string>((resolveColor, rejectColor) => {
+          const cropperObj = cropperEle.current?.cropper;
+          const corp = cropperObj
+            ?.getCroppedCanvas()
+            ?.toDataURL('image/webp', 0.7);
+          if (!corp) {
+            rejectColor(
+              new CustomError('computeThemeColor', 'cropper not exist'),
+            );
+          } else {
+            getImageThemeColor(corp).then((res: string) => {
+              resolveColor(res);
+            });
+          }
+        }),
+      );
+    });
+    Promise.all(promises)
+      .then(colors => resolve(colors))
+      .catch(error => reject(error));
+  });
+
+export function getImageThemeColor(url: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const colorThief = new ColorThief();
+    const img = new Image();
+    img.src = url;
+    img.onload = () => {
+      const thiefColor = colorThief.getColor(img);
+      if (thiefColor) {
+        const [a, b, c] = thiefColor;
+        const color = `rgba(${a}, ${b}, ${c})`;
+        resolve(color);
+      } else {
+        reject(new CustomError('getImageThemeColor', 'not get theme color'));
+      }
+    };
+  });
+}

frontend/packages/agent-ide/chat-background-shared/tsconfig.build.json

@@ -0,0 +1,69 @@
+{
+  "extends": "@coze-arch/ts-config/tsconfig.web.json",
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "jsx": "react-jsx",
+    "lib": ["DOM", "ESNext"],
+    "module": "ESNext",
+    "target": "ES2020",
+    "moduleResolution": "bundler",
+    "tsBuildInfoFile": "dist/tsconfig.build.tsbuildinfo"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "references": [
+    {
+      "path": "../../arch/bot-api/tsconfig.build.json"
+    },
+    {
+      "path": "../../arch/bot-error/tsconfig.build.json"
+    },
+    {
+      "path": "../../arch/bot-flags/tsconfig.build.json"
+    },
+    {
+      "path": "../../arch/bot-typings/tsconfig.build.json"
+    },
+    {
+      "path": "../../arch/bot-utils/tsconfig.build.json"
+    },
+    {
+      "path": "../../arch/i18n/tsconfig.build.json"
+    },
+    {
+      "path": "../../arch/logger/tsconfig.build.json"
+    },
+    {
+      "path": "../bot-audit-adapter/tsconfig.build.json"
+    },
+    {
+      "path": "../../common/chat-area/chat-uikit/tsconfig.build.json"
+    },
+    {
+      "path": "../../components/bot-semi/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/eslint-config/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/stylelint-config/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/ts-config/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/vitest-config/tsconfig.build.json"
+    },
+    {
+      "path": "../../studio/bot-utils/tsconfig.build.json"
+    },
+    {
+      "path": "../../studio/components/tsconfig.build.json"
+    },
+    {
+      "path": "../../studio/stores/bot-detail/tsconfig.build.json"
+    }
+  ]
+}

frontend/packages/agent-ide/chat-background-shared/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "exclude": ["**/*"],
+  "compilerOptions": {
+    "composite": true
+  },
+  "references": [
+    {
+      "path": "./tsconfig.build.json"
+    },
+    {
+      "path": "./tsconfig.misc.json"
+    }
+  ]
+}

frontend/packages/agent-ide/chat-background-shared/tsconfig.misc.json

@@ -0,0 +1,20 @@
+{
+  "extends": "@coze-arch/ts-config/tsconfig.web.json",
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "rootDir": "./",
+    "outDir": "./dist",
+    "jsx": "react-jsx",
+    "lib": ["DOM", "ESNext"],
+    "module": "ESNext",
+    "target": "ES2020",
+    "moduleResolution": "bundler"
+  },
+  "include": ["__tests__", "vitest.config.ts", "stories"],
+  "exclude": ["./dist"],
+  "references": [
+    {
+      "path": "./tsconfig.build.json"
+    }
+  ]
+}

frontend/packages/agent-ide/chat-background-shared/vitest.config.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * 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.
+ */
+ 
+import { defineConfig } from '@coze-arch/vitest-config';
+
+export default defineConfig({
+  dirname: __dirname,
+  preset: 'web',
+});