Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(desktop): 用户头像选图后支持拖动、缩放与实时圆形预览 (#5980)

Dash7b00740b4efd
diff --git a/apps/desktop/src/main/__tests__/profileEdit.test.ts b/apps/desktop/src/main/__tests__/profileEdit.test.ts
index ed37c33531..0221585be6 100644
--- a/apps/desktop/src/main/__tests__/profileEdit.test.ts
+++ b/apps/desktop/src/main/__tests__/profileEdit.test.ts
@@ -1,20 +1,26 @@
/**
* profileEdit.test.ts — 个人资料编辑业务体单测(规则 14:全依赖注入,内存直测)。
* 覆盖:未登录 / 非法参数拒绝、名字收敛(留空/一致 = 不改)、头像三态
- * (keep / set / reset)的 OSS 直传与 PATCH 组装、体积与扩展名校验、
- * 上传 / PATCH 失败的错误码映射、无变化零请求、HDR 头像先转 SDR 再预览 / 上传。
+ * (keep / set / reset)的 OSS 直传与 PATCH 组装、导出字节的类型 / 文件头 / 体积 / 尺寸 / 解码校验、
+ * 选图的扩展名与源图体积校验、HDR 头像在取景前转 SDR、保存途中切换账号、
+ * 上传 / PATCH 失败的错误码映射、无变化零请求。
*/
-import { describe, it, expect, vi } from 'vitest';
-import { readFileSync } from 'node:fs';
+import fs from 'node:fs';
import path from 'node:path';
+
+import { describe, it, expect, vi } from 'vitest';
+
import { toSdrAvatarImage, readPngHdrChunks } from '../hdrAvatarToSdr';
import {
AVATAR_MAX_BYTES,
+ AVATAR_SOURCE_MAX_BYTES,
+ AVATAR_UPLOAD_MAX_EDGE_PX,
chooseAvatarFile,
cleanupLegacyProfileOverride,
getProfileEditState,
+ readAvatarDimensions,
updateProfile,
type LegacyOverrideCleanupDeps,
type ProfileEditDeps,
@@ -24,6 +30,26 @@ type ProfilePatch = { displayName?: string; avatarUrl?: string | null };
const PUBLIC_URL = 'https://oss.example.invalid/cindy/public/avatar/u1/x.png';
+// 头像编辑器导出的字节:只认 PNG / JPEG,文件头必须与声明的 mime 一致,且带可读尺寸。
+const PNG_HEADER = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const u16 = (n: number) => [(n >> 8) & 0xff, n & 0xff];
+const u32 = (n: number) => [(n >>> 24) & 0xff, (n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+const pngBytes = (size = 64, width = 256, height = 256) => {
+ const data = new Uint8Array(size);
+ data.set([...PNG_HEADER, ...u32(13), 0x49, 0x48, 0x44, 0x52, ...u32(width), ...u32(height)]);
+ return data;
+};
+// SOI + JFIF APP0 + SOF0(高在宽前)。
+const jpegBytes = (width = 256, height = 256) =>
+ Uint8Array.from([
+ 0xff, 0xd8,
+ 0xff, 0xe0, ...u16(16), 0x4a, 0x46, 0x49, 0x46, 0x00, 1, 1, 0, 0, 1, 0, 1, 0, 0,
+ 0xff, 0xc0, ...u16(17), 8, ...u16(height), ...u16(width), 3, 1, 0x22, 0, 2, 0x11, 1, 3, 0x11, 1,
+ 0xff, 0xda,
+ ]);
+const resourceBytes = (name: string) =>
+ new Uint8Array(fs.readFileSync(path.resolve(__dirname, '../../../resources', name)));
+
function makeDeps(overrides: Partial<ProfileEditDeps> = {}): {
deps: ProfileEditDeps;
patches: ProfilePatch[];
@@ -36,6 +62,10 @@ function makeDeps(overrides: Partial<ProfileEditDeps> = {}): {
showAvatarOpenDialog: vi.fn(async () => null),
readFile: vi.fn(async () => Buffer.from([1, 2, 3])),
toSdrAvatar: vi.fn(async (image) => image),
+ // 默认模拟解码成功:像素尺寸与文件头声明一致。
+ decodeAvatarImage: vi.fn(({ buffer, mimeType }: { buffer: Uint8Array; mimeType: string }) =>
+ readAvatarDimensions(buffer, mimeType),
+ ),
uploadAvatar: vi.fn(async () => ({ ok: true as const, publicUrl: PUBLIC_URL })),
patchProfile: vi.fn(async (patch: ProfilePatch) => {
patches.push(patch);
@@ -108,19 +138,21 @@ describe('名字收敛(留空 / 与当前一致 = 不改名)', () => {
});
describe('头像三态', () => {
- it('set:读文件 → OSS 直传 → PATCH avatarUrl=publicUrl', async () => {
+ it('set:导出字节原样 OSS 直传 → PATCH avatarUrl=publicUrl(不再读任何文件路径)', async () => {
const { deps, patches } = makeDeps();
- await updateProfile(deps, { name: null, avatar: { type: 'set', filePath: 'C:\\pics\\me.PNG' } });
- expect(deps.uploadAvatar).toHaveBeenCalledWith({
- buffer: expect.any(Buffer),
- mimeType: 'image/png',
- });
+ const data = pngBytes();
+ await updateProfile(deps, { name: null, avatar: { type: 'set', data, mimeType: 'image/png' } });
+ expect(deps.uploadAvatar).toHaveBeenCalledWith({ buffer: data, mimeType: 'image/png' });
+ expect(deps.readFile).not.toHaveBeenCalled();
expect(patches).toEqual([{ avatarUrl: PUBLIC_URL }]);
});
it('set + 改名:一次 PATCH 同时带两个字段', async () => {
const { deps, patches } = makeDeps();
- await updateProfile(deps, { name: 'Lizi', avatar: { type: 'set', filePath: '/a/b.webp' } });
+ await updateProfile(deps, {
+ name: 'Lizi',
+ avatar: { type: 'set', data: jpegBytes(), mimeType: 'image/jpeg' },
+ });
expect(patches).toEqual([{ displayName: 'Lizi', avatarUrl: PUBLIC_URL }]);
});
@@ -131,29 +163,66 @@ describe('头像三态', () => {
expect(deps.uploadAvatar).not.toHaveBeenCalled();
});
- it('set:扩展名不在白名单(含已退役的 gif)/ 超限 / 空文件 → INVALID_PARAMS,不触发上传', async () => {
+ it('set:类型不在导出白名单 / 文件头与 mime 不符 / 超限 / 空字节 / 非字节数组 → INVALID_PARAMS,不触发上传', async () => {
const { deps } = makeDeps();
- for (const filePath of ['/a/b.svg', '/a/b.gif']) {
+ const oversized = pngBytes(AVATAR_MAX_BYTES + 1);
+ const bad: unknown[] = [
+ { type: 'set', data: pngBytes(), mimeType: 'image/webp' },
+ { type: 'set', data: pngBytes(), mimeType: 'image/gif' },
+ { type: 'set', data: pngBytes(), mimeType: 'image/jpeg' },
+ { type: 'set', data: jpegBytes(), mimeType: 'image/png' },
+ { type: 'set', data: Uint8Array.from([0x89, 0x50]), mimeType: 'image/png' },
+ { type: 'set', data: oversized, mimeType: 'image/png' },
+ { type: 'set', data: new Uint8Array(0), mimeType: 'image/png' },
+ { type: 'set', data: [...PNG_HEADER], mimeType: 'image/png' },
+ { type: 'set', filePath: '/a/b.png' },
+ ];
+ for (const avatar of bad) {
+ await expect(updateProfile(deps, { name: null, avatar })).rejects.toSatisfy(
+ (e) => ipcCode(e) === 'INVALID_PARAMS',
+ );
+ }
+ expect(deps.uploadAvatar).not.toHaveBeenCalled();
+ expect(deps.readFile).not.toHaveBeenCalled();
+ });
+
+ it('set:文件头尺寸缺失 / 为 0 / 超过导出边长 → INVALID_PARAMS,不解码也不上传', async () => {
+ const { deps } = makeDeps();
+ const noIhdr = pngBytes();
+ noIhdr.set([0x67, 0x41, 0x4d, 0x41], 12); // 第一个 chunk 不是 IHDR
+ const max = AVATAR_UPLOAD_MAX_EDGE_PX;
+ const bad: Array<{ data: Uint8Array; mimeType: string }> = [
+ { data: noIhdr, mimeType: 'image/png' },
+ { data: Uint8Array.from([...PNG_HEADER, 0, 0, 0, 13]), mimeType: 'image/png' },
+ { data: pngBytes(64, 0, 256), mimeType: 'image/png' },
+ { data: pngBytes(64, max + 1, 16), mimeType: 'image/png' },
+ { data: pngBytes(64, 0x7fffffff, 0x7fffffff), mimeType: 'image/png' },
+ { data: jpegBytes(16, max + 1), mimeType: 'image/jpeg' },
+ { data: Uint8Array.from([0xff, 0xd8, 0xff, 0xda, 0, 2, 0, 0]), mimeType: 'image/jpeg' },
+ { data: Uint8Array.from([0xff, 0xd8, 0xff, 0xe0, 0, 0, 0, 0]), mimeType: 'image/jpeg' },
+ { data: resourceBytes('bgicon.jpg'), mimeType: 'image/jpeg' },
+ ];
+ for (const { data, mimeType } of bad) {
await expect(
- updateProfile(deps, { name: null, avatar: { type: 'set', filePath } }),
+ updateProfile(deps, { name: null, avatar: { type: 'set', data, mimeType } }),
).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
}
-
- (deps.readFile as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
- Buffer.alloc(AVATAR_MAX_BYTES + 1),
- );
- await expect(
- updateProfile(deps, { name: null, avatar: { type: 'set', filePath: '/a/b.png' } }),
- ).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
-
- (deps.readFile as ReturnType<typeof vi.fn>).mockResolvedValueOnce(Buffer.alloc(0));
- await expect(
- updateProfile(deps, { name: null, avatar: { type: 'set', filePath: '/a/b.png' } }),
- ).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
-
+ expect(deps.decodeAvatarImage).not.toHaveBeenCalled();
expect(deps.uploadAvatar).not.toHaveBeenCalled();
});
+ it('set:main 完整解码失败或像素尺寸与文件头不符 → INVALID_PARAMS,不上传', async () => {
+ for (const decoded of [null, { width: 128, height: 256 }]) {
+ const { deps } = makeDeps({ decodeAvatarImage: vi.fn(() => decoded) });
+ const data = pngBytes();
+ await expect(
+ updateProfile(deps, { name: null, avatar: { type: 'set', data, mimeType: 'image/png' } }),
+ ).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
+ expect(deps.decodeAvatarImage).toHaveBeenCalledWith({ buffer: data, mimeType: 'image/png' });
+ expect(deps.uploadAvatar).not.toHaveBeenCalled();
+ }
+ });
+
it('上传失败 → PROFILE_AVATAR_UPLOAD_FAILED,不触发 PATCH', async () => {
const { deps } = makeDeps({
uploadAvatar: vi.fn(async () => ({
@@ -163,7 +232,10 @@ describe('头像三态', () => {
})),
});
await expect(
- updateProfile(deps, { name: null, avatar: { type: 'set', filePath: '/a/b.png' } }),
+ updateProfile(deps, {
+ name: null,
+ avatar: { type: 'set', data: pngBytes(), mimeType: 'image/png' },
+ }),
).rejects.toSatisfy((e) => ipcCode(e) === 'PROFILE_AVATAR_UPLOAD_FAILED');
expect(deps.patchProfile).not.toHaveBeenCalled();
});
@@ -178,20 +250,10 @@ describe('头像三态', () => {
});
});
-describe('HDR 头像转 SDR 后再预览 / 上传', () => {
- const hdrPng = readFileSync(path.join(__dirname, 'fixtures', 'hdr-avatar', 'pq-bt2100.png'));
-
- it('set:上传的是真实转换后的 SDR 字节,而不是原 HDR 文件', async () => {
- const { deps } = makeDeps({ readFile: vi.fn(async () => hdrPng), toSdrAvatar: toSdrAvatarImage });
- await updateProfile(deps, { name: null, avatar: { type: 'set', filePath: '/pics/hdr.png' } });
- const [[uploaded]] = (deps.uploadAvatar as ReturnType<typeof vi.fn>).mock.calls as [[{ buffer: Buffer; mimeType: string }]];
- expect(uploaded.mimeType).toBe('image/png');
- expect(uploaded.buffer.equals(hdrPng)).toBe(false);
- expect(readPngHdrChunks(hdrPng).cicp?.transfer).toBe(16);
- expect(readPngHdrChunks(uploaded.buffer).cicp).toBeNull();
- });
+describe('HDR 头像在取景前转 SDR', () => {
+ const hdrPng = fs.readFileSync(path.join(__dirname, 'fixtures', 'hdr-avatar', 'pq-bt2100.png'));
- it('chooseAvatarFile:预览与将要上传的字节一致(同为 SDR)', async () => {
+ it('chooseAvatarFile:取景源就是真实转换后的 SDR 字节', async () => {
const { deps } = makeDeps({
showAvatarOpenDialog: vi.fn(async () => '/pics/hdr.png'),
readFile: vi.fn(async () => hdrPng),
@@ -200,27 +262,29 @@ describe('HDR 头像转 SDR 后再预览 / 上传', () => {
const result = await chooseAvatarFile(deps);
const preview = Buffer.from(result.previewDataUrl!.split(',')[1]!, 'base64');
expect(result.previewDataUrl!.startsWith('data:image/png;base64,')).toBe(true);
+ expect(readPngHdrChunks(hdrPng).cicp?.transfer).toBe(16);
expect(readPngHdrChunks(preview).cicp).toBeNull();
expect(preview.equals((await toSdrAvatarImage({ buffer: hdrPng, mimeType: 'image/png' })).buffer)).toBe(true);
});
- it('转换结果超出体积上限 → INVALID_PARAMS,不触发上传', async () => {
- const { deps } = makeDeps({
- toSdrAvatar: vi.fn(async () => ({ buffer: Buffer.alloc(AVATAR_MAX_BYTES + 1), mimeType: 'image/png' })),
- });
- await expect(
- updateProfile(deps, { name: null, avatar: { type: 'set', filePath: '/a/b.png' } }),
- ).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
- expect(deps.uploadAvatar).not.toHaveBeenCalled();
- });
-
- it('chooseAvatarFile:转换结果超出体积上限 → 选图阶段就 INVALID_PARAMS', async () => {
+ it('chooseAvatarFile:转换结果超出源图上限 → 选图阶段就 INVALID_PARAMS', async () => {
const { deps } = makeDeps({
showAvatarOpenDialog: vi.fn(async () => '/pics/hdr.png'),
- toSdrAvatar: vi.fn(async () => ({ buffer: Buffer.alloc(AVATAR_MAX_BYTES + 1), mimeType: 'image/png' })),
+ toSdrAvatar: vi.fn(async () => ({
+ buffer: Buffer.alloc(AVATAR_SOURCE_MAX_BYTES + 1),
+ mimeType: 'image/png',
+ })),
});
await expect(chooseAvatarFile(deps)).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
});
+
+ it('set:上传的就是编辑器导出的字节,不在裁剪后二次转换', async () => {
+ const { deps } = makeDeps();
+ const data = pngBytes();
+ await updateProfile(deps, { name: null, avatar: { type: 'set', data, mimeType: 'image/png' } });
+ expect(deps.toSdrAvatar).not.toHaveBeenCalled();
+ expect(deps.uploadAvatar).toHaveBeenCalledWith({ buffer: data, mimeType: 'image/png' });
+ });
});
describe('保存途中切换账号', () => {
@@ -229,13 +293,13 @@ describe('保存途中切换账号', () => {
let count = 0;
return () => (++count <= reads ? 'cloud:u1:1' : next);
};
+ const setAvatar = () => ({ type: 'set' as const, data: pngBytes(), mimeType: 'image/png' });
- it('HDR 转换(或排队)期间切号 → PRECONDITION_FAILED,不上传也不 PATCH', async () => {
+ it('上传前切号 → PRECONDITION_FAILED,不上传也不 PATCH', async () => {
const { deps } = makeDeps({ getAccountScopeKey: switchAfter(1) });
await expect(
- updateProfile(deps, { name: 'Lizi', avatar: { type: 'set', filePath: '/a/b.png' } }),
+ updateProfile(deps, { name: 'Lizi', avatar: setAvatar() }),
).rejects.toSatisfy((e) => ipcCode(e) === 'PRECONDITION_FAILED');
- expect(deps.toSdrAvatar).toHaveBeenCalledTimes(1);
expect(deps.uploadAvatar).not.toHaveBeenCalled();
expect(deps.patchProfile).not.toHaveBeenCalled();
});
@@ -243,7 +307,7 @@ describe('保存途中切换账号', () => {
it('上传期间切号 → PRECONDITION_FAILED,不把头像与旧名字 PATCH 到新账号', async () => {
const { deps } = makeDeps({ getAccountScopeKey: switchAfter(2) });
await expect(
- updateProfile(deps, { name: 'Lizi', avatar: { type: 'set', filePath: '/a/b.png' } }),
+ updateProfile(deps, { name: 'Lizi', avatar: setAvatar() }),
).rejects.toSatisfy((e) => ipcCode(e) === 'PRECONDITION_FAILED');
expect(deps.uploadAvatar).toHaveBeenCalledTimes(1);
expect(deps.patchProfile).not.toHaveBeenCalled();
@@ -253,18 +317,43 @@ describe('保存途中切换账号', () => {
// getCurrentUserId 始终是 u1:只比较用户 id 的检查会放行。
const { deps } = makeDeps({ getAccountScopeKey: switchAfter(2, 'cloud:u1:2') });
await expect(
- updateProfile(deps, { name: 'Lizi', avatar: { type: 'set', filePath: '/a/b.png' } }),
+ updateProfile(deps, { name: 'Lizi', avatar: setAvatar() }),
).rejects.toSatisfy((e) => ipcCode(e) === 'PRECONDITION_FAILED');
expect(deps.patchProfile).not.toHaveBeenCalled();
});
it('账号不变时照常上传并 PATCH', async () => {
const { deps, patches } = makeDeps({ getAccountScopeKey: switchAfter(Infinity) });
- await updateProfile(deps, { name: 'Lizi', avatar: { type: 'set', filePath: '/a/b.png' } });
+ await updateProfile(deps, { name: 'Lizi', avatar: setAvatar() });
expect(patches).toEqual([{ displayName: 'Lizi', avatarUrl: PUBLIC_URL }]);
});
});
+describe('readAvatarDimensions(文件头尺寸)', () => {
+ it('读出真实 PNG / JPEG 的像素尺寸', () => {
+ expect(readAvatarDimensions(resourceBytes('icon.png'), 'image/png')).toEqual({
+ width: 512,
+ height: 512,
+ });
+ expect(readAvatarDimensions(resourceBytes('bgicon.jpg'), 'image/jpeg')).toEqual({
+ width: 1024,
+ height: 1024,
+ });
+ expect(readAvatarDimensions(jpegBytes(300, 200), 'image/jpeg')).toEqual({
+ width: 300,
+ height: 200,
+ });
+ });
+
+ it('边长恰为上限的真实 PNG 可以上传,字节原样', async () => {
+ const { deps, patches } = makeDeps();
+ const data = resourceBytes('icon.png');
+ await updateProfile(deps, { name: null, avatar: { type: 'set', data, mimeType: 'image/png' } });
+ expect(deps.uploadAvatar).toHaveBeenCalledWith({ buffer: data, mimeType: 'image/png' });
+ expect(patches).toEqual([{ avatarUrl: PUBLIC_URL }]);
+ });
+});
+
describe('chooseAvatarFile(选图预校验,不上传)', () => {
it('取消选择返回 canceled,不读文件', async () => {
const { deps } = makeDeps();
@@ -272,18 +361,33 @@ describe('chooseAvatarFile(选图预校验,不上传)', () => {
expect(deps.readFile).not.toHaveBeenCalled();
});
- it('合法图片返回路径 + data URL 预览;不触发上传', async () => {
+ it('合法图片返回 data URL 取景源(不回传本机路径);不触发上传', async () => {
const { deps } = makeDeps({
showAvatarOpenDialog: vi.fn(async () => '/pics/me.webp'),
readFile: vi.fn(async () => Buffer.from('abc')),
});
const result = await chooseAvatarFile(deps);
expect(result.canceled).toBe(false);
- expect(result.filePath).toBe('/pics/me.webp');
+ expect(result).not.toHaveProperty('filePath');
expect(result.previewDataUrl).toBe(`data:image/webp;base64,${Buffer.from('abc').toString('base64')}`);
expect(deps.uploadAvatar).not.toHaveBeenCalled();
});
+ it('源图体积按选图上限(20MB)校验:超过上传上限但在源图上限内的原片可选', async () => {
+ const { deps } = makeDeps({
+ showAvatarOpenDialog: vi.fn(async () => '/pics/photo.jpg'),
+ readFile: vi.fn(async () => Buffer.alloc(AVATAR_MAX_BYTES + 1)),
+ });
+ await expect(chooseAvatarFile(deps)).resolves.toMatchObject({ canceled: false });
+
+ (deps.readFile as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
+ Buffer.alloc(AVATAR_SOURCE_MAX_BYTES + 1),
+ );
+ await expect(chooseAvatarFile(deps)).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
+ (deps.readFile as ReturnType<typeof vi.fn>).mockResolvedValueOnce(Buffer.alloc(0));
+ await expect(chooseAvatarFile(deps)).rejects.toSatisfy((e) => ipcCode(e) === 'INVALID_PARAMS');
+ });
+
it('白名单外扩展名拒绝(gif 已随 OSS 场景白名单退役)', async () => {
for (const filePath of ['/pics/me.bmp', '/pics/me.gif']) {
const { deps } = makeDeps({ showAvatarOpenDialog: vi.fn(async () => filePath) });
diff --git a/apps/desktop/src/main/bootstrap-electron.ts b/apps/desktop/src/main/bootstrap-electron.ts
index 68c74ea4ec..ab9f2d6dfd 100644
--- a/apps/desktop/src/main/bootstrap-electron.ts
+++ b/apps/desktop/src/main/bootstrap-electron.ts
@@ -6051,6 +6051,10 @@ const registerIpcHandlers = () => {
},
readFile: (filePath) => fs.promises.readFile(filePath),
toSdrAvatar: toSdrAvatarImage,
+ decodeAvatarImage: ({ buffer }) => {
+ const image = nativeImage.createFromBuffer(Buffer.from(buffer));
+ return image.isEmpty() ? null : image.getSize();
+ },
uploadAvatar: async ({ buffer, mimeType }) => {
const result = await uploadPublicAsset(
{
diff --git a/apps/desktop/src/main/profileEdit.ts b/apps/desktop/src/main/profileEdit.ts
index d031d9b1a7..81e25ea22f 100644
--- a/apps/desktop/src/main/profileEdit.ts
+++ b/apps/desktop/src/main/profileEdit.ts
@@ -15,8 +15,13 @@ import { throwIpcError } from './utils/ipcValidate';
// ── 常量 ────────────────────────────────────────────────────────────────────
-/** 头像源文件体积上限——与 oss-server avatar 场景的 5MB 上限对齐。 */
+/** 上传头像体积上限——与 oss-server avatar 场景的 5MB 上限对齐。 */
export const AVATAR_MAX_BYTES = 5 * 1024 * 1024;
+/**
+ * 选图源文件体积上限。上传的是 renderer 裁剪导出的 ≤512px 头像,不再是原图,
+ * 所以源图可以放宽到常见手机原片(4800 万像素 JPEG 可达 10MB+)。
+ */
+export const AVATAR_SOURCE_MAX_BYTES = 20 * 1024 * 1024;
/** 显示名长度上限(码点数;服务端上限 100,客户端收紧到 40 保持既有体验)。 */
export const NAME_MAX_LENGTH = 40;
@@ -35,6 +40,21 @@ const AVATAR_MIME_BY_EXT: Record<string, string> = {
/** 文件选择器 filter 用的扩展名清单(不含点)。 */
export const AVATAR_FILE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp'];
+/**
+ * 上传字节允许的 mime → 文件头签名。renderer 的头像编辑器只导出 PNG(含透明)
+ * 或 JPEG,这里按导出契约收紧,并用文件头核对 mime,不信任 renderer 自报的类型。
+ */
+const AVATAR_UPLOAD_SIGNATURES: Record<string, readonly number[]> = {
+ 'image/png': [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+ 'image/jpeg': [0xff, 0xd8, 0xff],
+};
+
+/**
+ * 上传头像边长上限(像素),与 renderer 头像编辑器的导出上限 AVATAR_OUTPUT_MAX_PX
+ * 一致。main 先按文件头声明的尺寸拦截,再完整解码,解压炸弹到不了解码器。
+ */
+export const AVATAR_UPLOAD_MAX_EDGE_PX = 512;
+
// ── 依赖注入面 ──────────────────────────────────────────────────────────────
export interface ProfileEditDeps {
@@ -53,6 +73,14 @@ export interface ProfileEditDeps {
readFile(filePath: string): Promise<Buffer>;
/** HDR 头像转 SDR(hdrAvatarToSdr.toSdrAvatarImage);SDR 原样返回。 */
toSdrAvatar(image: { buffer: Buffer; mimeType: string }): Promise<{ buffer: Buffer; mimeType: string }>;
+ /**
+ * 完整解码上传字节(nativeImage.createFromBuffer),返回像素尺寸;解码失败返回 null。
+ * 调用前已按文件头尺寸限过边长。
+ */
+ decodeAvatarImage(params: { buffer: Uint8Array; mimeType: string }): {
+ width: number;
+ height: number;
+ } | null;
/** 头像直传 OSS(ossPublicUpload.uploadPublicAsset 的 avatar 场景特化)。 */
uploadAvatar(params: { buffer: Uint8Array; mimeType: string }): Promise<
| { ok: true; publicUrl: string }
@@ -76,14 +104,17 @@ export interface ProfileEditState {
export interface ChooseAvatarResult {
canceled: boolean;
- filePath?: string;
- /** 弹窗内预览用 data URL(一次性,不落任何缓存)。 */
+ /** 头像编辑器的取景源(data URL,一次性,不落任何缓存)。 */
previewDataUrl?: string;
}
+/**
+ * set 携带的是头像编辑器按取景导出的最终字节(而不是源文件路径):预览与上传是
+ * 同一份像素,main 也不再读取 renderer 传来的任意路径。
+ */
export type AvatarAction =
| { type: 'keep' }
- | { type: 'set'; filePath: string }
+ | { type: 'set'; data: Uint8Array; mimeType: string }
| { type: 'reset' };
export interface UpdateProfileParams {
@@ -118,11 +149,70 @@ function requireSameAccount(deps: ProfileEditDeps, accountScope: string): void {
function parseAvatarAction(value: unknown): AvatarAction | null {
if (value === null || typeof value !== 'object') return null;
- const action = value as { type?: unknown; filePath?: unknown };
+ const action = value as { type?: unknown; data?: unknown; mimeType?: unknown };
if (action.type === 'keep') return { type: 'keep' };
if (action.type === 'reset') return { type: 'reset' };
- if (action.type === 'set' && typeof action.filePath === 'string' && action.filePath !== '') {
- return { type: 'set', filePath: action.filePath };
+ if (
+ action.type === 'set' &&
+ action.data instanceof Uint8Array &&
+ typeof action.mimeType === 'string'
+ ) {
+ return { type: 'set', data: action.data, mimeType: action.mimeType };
+ }
+ return null;
+}
+
+/** 文件头是否与声明的 mime 一致(只认上传白名单里的类型)。 */
+function avatarBytesMatchMime(data: Uint8Array, mimeType: string): boolean {
+ const signature = AVATAR_UPLOAD_SIGNATURES[mimeType];
+ if (!signature || data.byteLength < signature.length) return false;
+ return signature.every((byte, index) => data[index] === byte);
+}
+
+/** JPEG 帧头(SOF0–SOF15,除 DHT/JPG/DAC)标记,紧跟高宽字段。 */
+const JPEG_SOF_MARKERS = new Set([
+ 0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+]);
+
+/**
+ * 读文件头声明的像素尺寸(PNG IHDR / JPEG 首个 SOF);结构不完整返回 null。
+ * 调用前已核对过文件头签名。
+ */
+export function readAvatarDimensions(
+ data: Uint8Array,
+ mimeType: string,
+): { width: number; height: number } | null {
+ const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+ if (mimeType === 'image/png') {
+ // 签名 8 字节后第一个 chunk 必须是 IHDR:长度(4) 类型(4) 宽(4) 高(4)。
+ if (data.byteLength < 24) return null;
+ const type = String.fromCharCode(data[12], data[13], data[14], data[15]);
+ if (type !== 'IHDR') return null;
+ return { width: view.getUint32(16), height: view.getUint32(20) };
+ }
+ if (mimeType === 'image/jpeg') {
+ let offset = 2;
+ while (offset + 4 <= data.byteLength) {
+ if (data[offset] !== 0xff) return null;
+ const marker = data[offset + 1];
+ if (marker === 0xff) {
+ offset += 1; // 填充字节
+ continue;
+ }
+ if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+ offset += 2; // 无长度字段的独立标记
+ continue;
+ }
+ if (marker === 0xd9 || marker === 0xda) return null; // 帧头之前就结束 / 开始扫描
+ const length = view.getUint16(offset + 2);
+ if (length < 2) return null;
+ if (JPEG_SOF_MARKERS.has(marker)) {
+ // 长度(2) 精度(1) 高(2) 宽(2)
+ if (offset + 9 > data.byteLength) return null;
+ return { width: view.getUint16(offset + 7), height: view.getUint16(offset + 5) };
+ }
+ offset += 2 + length;
+ }
}
return null;
}
@@ -138,9 +228,9 @@ export function getProfileEditState(deps: ProfileEditDeps): ProfileEditState {
}
/**
- * 选头像文件:系统选择器 → 扩展名 / 体积校验 → HDR 转 SDR → 返回路径 + 预览 data URL。
- * 预览即转换后的 SDR 像素,与「保存」时上传的字节一致。
- * 这里**不**上传——用户点「保存」才走 OSS 直传,取消弹窗零副作用。
+ * 选头像文件:系统选择器 → 扩展名 / 体积校验 → HDR 转 SDR → 返回取景源 data URL。
+ * 取景源即转换后的 SDR 像素;编辑器从它导出上传字节,updateProfile 不再二次转换。
+ * 这里**不**上传——renderer 调整好取景、用户点「保存」才走 OSS 直传,取消弹窗零副作用。
*/
export async function chooseAvatarFile(deps: ProfileEditDeps): Promise<ChooseAvatarResult> {
requireUserId(deps);
@@ -156,17 +246,16 @@ export async function chooseAvatarFile(deps: ProfileEditDeps): Promise<ChooseAva
} catch {
throwIpcError('INVALID_PARAMS', 'avatar file is not readable');
}
- if (buffer.byteLength === 0 || buffer.byteLength > AVATAR_MAX_BYTES) {
+ if (buffer.byteLength === 0 || buffer.byteLength > AVATAR_SOURCE_MAX_BYTES) {
throwIpcError('INVALID_PARAMS', `avatar file size out of range: ${buffer.byteLength}`);
}
const preview = await deps.toSdrAvatar({ buffer, mimeType: mime });
- // 选图阶段就拒绝转换后超限的头像,不让用户在保存时才看到失败。
- if (preview.buffer.byteLength > AVATAR_MAX_BYTES) {
+ // 转换后的取景源同样受源图上限约束(上传的是编辑器导出的小图,另有 5MB 上限)。
+ if (preview.buffer.byteLength > AVATAR_SOURCE_MAX_BYTES) {
throwIpcError('INVALID_PARAMS', `avatar file size out of range: ${preview.buffer.byteLength}`);
}
return {
canceled: false,
- filePath,
previewDataUrl: `data:${preview.mimeType};base64,${preview.buffer.toString('base64')}`,
};
}
@@ -174,7 +263,8 @@ export async function chooseAvatarFile(deps: ProfileEditDeps): Promise<ChooseAva
/**
* 保存资料:name 与 avatar 各自收敛成 PATCH 字段,一次提交服务端。
* - name:trim 后为空或与当前一致 → 不改;否则 displayName;
- * - avatar keep:不动;set:校验 → HDR 转 SDR → OSS 直传拿 publicUrl;reset:avatarUrl null;
+ * - avatar keep:不动;set:校验导出字节(类型 / 文件头 / 体积 / 尺寸 / 完整解码)→ 原样 OSS 直传
+ * 拿 publicUrl(取景源已在选图时转成 SDR,这里不二次转换);reset:avatarUrl null;
* - 两个字段都没变化 → 直接成功返回,零网络请求。
* 上传成功但 PATCH 失败时,已传对象成为孤儿(bucket 生命周期规则兜底清理,
* 契约见 oss-server 文档),客户端无需补偿删除。
@@ -212,25 +302,33 @@ export async function updateProfile(
// ── 头像收敛(set 时先直传 OSS 拿公开地址) ──
let nextAvatarUrl: string | null | undefined;
if (avatarAction.type === 'set') {
- const mime = avatarMimeForPath(avatarAction.filePath);
- if (!mime) {
- throwIpcError('INVALID_PARAMS', `unsupported avatar file type: ${avatarAction.filePath}`);
+ const { data, mimeType } = avatarAction;
+ if (data.byteLength === 0 || data.byteLength > AVATAR_MAX_BYTES) {
+ throwIpcError('INVALID_PARAMS', `avatar data size out of range: ${data.byteLength}`);
}
- let buffer: Buffer;
- try {
- buffer = await deps.readFile(avatarAction.filePath);
- } catch {
- throwIpcError('INVALID_PARAMS', 'avatar file is not readable');
+ if (!avatarBytesMatchMime(data, mimeType)) {
+ throwIpcError('INVALID_PARAMS', `avatar data does not match type: ${mimeType}`);
}
- if (buffer.byteLength === 0 || buffer.byteLength > AVATAR_MAX_BYTES) {
- throwIpcError('INVALID_PARAMS', `avatar file size out of range: ${buffer.byteLength}`);
+ // renderer 不是安全边界:先按文件头限尺寸,再在 main 完整解码,尺寸一致才上传。
+ const declared = readAvatarDimensions(data, mimeType);
+ if (
+ !declared ||
+ declared.width < 1 ||
+ declared.height < 1 ||
+ declared.width > AVATAR_UPLOAD_MAX_EDGE_PX ||
+ declared.height > AVATAR_UPLOAD_MAX_EDGE_PX
+ ) {
+ throwIpcError(
+ 'INVALID_PARAMS',
+ `avatar dimensions out of range: ${declared ? `${declared.width}x${declared.height}` : '<unreadable>'}`,
+ );
}
- const image = await deps.toSdrAvatar({ buffer, mimeType: mime });
- if (image.buffer.byteLength > AVATAR_MAX_BYTES) {
- throwIpcError('INVALID_PARAMS', `avatar file size out of range: ${image.buffer.byteLength}`);
+ const decoded = deps.decodeAvatarImage({ buffer: data, mimeType });
+ if (!decoded || decoded.width !== declared.width || decoded.height !== declared.height) {
+ throwIpcError('INVALID_PARAMS', 'avatar data failed to decode');
}
requireSameAccount(deps, accountScope);
- const uploaded = await deps.uploadAvatar(image);
+ const uploaded = await deps.uploadAvatar({ buffer: data, mimeType });
if (!uploaded.ok) {
throwIpcError(
'PROFILE_AVATAR_UPLOAD_FAILED',
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index ef28085c2a..f77410ec5e 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -2123,12 +2123,14 @@ contextBridge.exposeInMainWorld('electronAPI', {
}> => ipcRenderer.invoke('profile:get-state'),
profileChooseAvatar: (): Promise<{
canceled: boolean;
- filePath?: string;
previewDataUrl?: string;
}> => ipcRenderer.invoke('profile:choose-avatar'),
profileUpdate: (params: {
name: string | null;
- avatar: { type: 'keep' } | { type: 'set'; filePath: string } | { type: 'reset' };
+ avatar:
+ | { type: 'keep' }
+ | { type: 'set'; data: Uint8Array; mimeType: 'image/png' | 'image/jpeg' }
+ | { type: 'reset' };
}): Promise<{ ok: true }> => ipcRenderer.invoke('profile:update', params),
onAuthStateChange: fanOutAuthStateChange,
onAuthSessionExpired: fanOutAuthSessionExpired,
diff --git a/apps/desktop/src/renderer/components/settings/AvatarCropEditor.tsx b/apps/desktop/src/renderer/components/settings/AvatarCropEditor.tsx
new file mode 100644
index 0000000000..ae67c6276e
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/AvatarCropEditor.tsx
@@ -0,0 +1,387 @@
+import { forwardRef, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { ZoomIn, ZoomOut } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Slider } from '@/components/ui/slider';
+import { Tip } from '@/components/ui/tooltip';
+import {
+ createWheelSourceTracker,
+ normalizeWheelDelta,
+ wheelZoomFactor,
+} from '@/components/chat/lightboxGestures';
+
+import {
+ AVATAR_CROP_MAX_ZOOM,
+ AVATAR_CROP_ZOOM_STEP,
+ AVATAR_ZOOM_SLIDER_MAX,
+ avatarCropZoom,
+ avatarSliderToZoom,
+ avatarStageTransform,
+ avatarZoomToSlider,
+ panAvatarCrop,
+ zoomAvatarCrop,
+ type AvatarCrop,
+ type AvatarViewPoint,
+} from './avatarCropGeometry';
+import type { AvatarSource } from './avatarCropImage';
+
+/**
+ * AvatarCropEditor — 头像「移动和缩放」编辑台(受控:取景状态由调用方持有)。
+ *
+ * 画面:整张图画在 stage 画布上,正中一个固定直径的取景圆,圆外用模态遮罩色压暗——
+ * 圆内就是最终头像,圆外保留上下文方便判断构图。
+ *
+ * 输入(全部只作用于 stage 自身,不劫持弹窗或页面滚动):
+ * - 指针拖动平移;两指(触屏)捏合缩放并跟随中点;
+ * - 触控板捏合 / ⌘·Ctrl+滚轮 / 鼠标滚轮以光标为焦点缩放,触控板双指滑动平移
+ * (设备推断与 wheel 数学复用图片 lightbox 的 lightboxGestures);
+ * - 聚焦 stage 后方向键平移(Shift 大步),+ / - 缩放;滑杆与两侧按钮以圆心缩放。
+ * 直接操纵不加缓动(DESIGN §14.4:跟手即反馈),所以没有需要 reduced-motion 关闭的动效。
+ */
+
+/** 取景圆在屏幕上的直径(CSS px)。 */
+const VIEW_SIDE = 240;
+/** 取景圆与 stage 边缘至少留出的距离,stage 被压窄时取景圆随之缩小。 */
+const VIEW_MIN_GUTTER = 24;
+const KEY_PAN_STEP = 8;
+const KEY_PAN_STEP_LARGE = 40;
+// 到达缩放边界时用 aria-disabled 而不是 disabled:真 disabled 会把正在连点的按钮
+// 焦点甩到 body;边界处点击本就是 no-op(zoomAvatarCrop 会夹住倍率)。
+const ZOOM_BUTTON_CLASS = 'w-8 shrink-0 px-0 aria-disabled:cursor-default aria-disabled:opacity-60';
+
+interface AvatarCropEditorProps {
+ source: AvatarSource;
+ crop: AvatarCrop;
+ onCropChange: (crop: AvatarCrop) => void;
+ /** 弹窗内 Tooltip 需要盖过宿主弹窗的层级(DESIGN §4 Dialog & Modal)。 */
+ tipClassName?: string;
+}
+
+interface StageSize {
+ width: number;
+ height: number;
+}
+
+function viewSideFor(stage: StageSize) {
+ return Math.max(
+ 0,
+ Math.min(VIEW_SIDE, stage.width - VIEW_MIN_GUTTER * 2, stage.height - VIEW_MIN_GUTTER * 2),
+ );
+}
+
+export const AvatarCropEditor = forwardRef<HTMLDivElement, AvatarCropEditorProps>(
+ function AvatarCropEditor({ source, crop, onCropChange, tipClassName }, forwardedRef) {
+ const { t } = useTranslation();
+ const stageRef = useRef<HTMLDivElement | null>(null);
+ const canvasRef = useRef<HTMLCanvasElement | null>(null);
+ const [stage, setStage] = useState<StageSize>({ width: 0, height: 0 });
+ const [dragging, setDragging] = useState(false);
+ // 原生 wheel listener 与 pointer handler 读最新值,不受闭包过期影响。
+ const cropRef = useRef(crop);
+ cropRef.current = crop;
+ const onCropChangeRef = useRef(onCropChange);
+ onCropChangeRef.current = onCropChange;
+ const viewSide = viewSideFor(stage);
+ const viewSideRef = useRef(viewSide);
+ viewSideRef.current = viewSide;
+ const pointersRef = useRef(new Map<number, { x: number; y: number }>());
+
+ const setStageNode = useCallback(
+ (node: HTMLDivElement | null) => {
+ stageRef.current = node;
+ if (typeof forwardedRef === 'function') forwardedRef(node);
+ else if (forwardedRef) forwardedRef.current = node;
+ },
+ [forwardedRef],
+ );
+
+ // stage 尺寸:首帧同步量一次(避免空白帧),之后跟随 ResizeObserver。
+ useLayoutEffect(() => {
+ const node = stageRef.current;
+ if (!node) return;
+ const measure = () => {
+ const rect = node.getBoundingClientRect();
+ setStage((prev) =>
+ prev.width === rect.width && prev.height === rect.height
+ ? prev
+ : { width: rect.width, height: rect.height },
+ );
+ };
+ measure();
+ if (typeof ResizeObserver === 'undefined') return;
+ const observer = new ResizeObserver(measure);
+ observer.observe(node);
+ return () => observer.disconnect();
+ }, []);
+
+ // 每次取景 / 尺寸变化同步重画(layout effect:与本帧 DOM 一起提交,拖动不拖影)。
+ useLayoutEffect(() => {
+ const canvas = canvasRef.current;
+ if (!canvas || stage.width === 0 || viewSide === 0) return;
+ const dpr = window.devicePixelRatio || 1;
+ const width = Math.round(stage.width * dpr);
+ const height = Math.round(stage.height * dpr);
+ if (canvas.width !== width) canvas.width = width;
+ if (canvas.height !== height) canvas.height = height;
+ const ctx = canvas.getContext('2d', { colorSpace: 'srgb' });
+ if (!ctx) return;
+ const { scale, x, y } = avatarStageTransform(crop, viewSide, stage.width, stage.height);
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.clearRect(0, 0, width, height);
+ ctx.imageSmoothingEnabled = true;
+ ctx.imageSmoothingQuality = 'high';
+ ctx.setTransform(scale * dpr, 0, 0, scale * dpr, x * dpr, y * dpr);
+ ctx.drawImage(source.bitmap, 0, 0);
+ }, [crop, source, stage, viewSide]);
+
+ const emit = useCallback((next: AvatarCrop) => {
+ const current = cropRef.current;
+ if (next.cx === current.cx && next.cy === current.cy && next.side === current.side) return;
+ cropRef.current = next;
+ onCropChangeRef.current(next);
+ }, []);
+
+ const zoomTo = useCallback(
+ (zoom: number, focal?: AvatarViewPoint) => {
+ emit(zoomAvatarCrop(cropRef.current, source.size, zoom, viewSideRef.current, focal));
+ },
+ [emit, source.size],
+ );
+
+ const panBy = useCallback(
+ (dx: number, dy: number) => {
+ emit(panAvatarCrop(cropRef.current, source.size, dx, dy, viewSideRef.current));
+ },
+ [emit, source.size],
+ );
+
+ /** 屏幕坐标 → 相对取景圆心(= stage 中心)的视图坐标。 */
+ const toViewPoint = useCallback((clientX: number, clientY: number): AvatarViewPoint => {
+ const rect = stageRef.current?.getBoundingClientRect();
+ if (!rect) return { x: 0, y: 0 };
+ return { x: clientX - rect.left - rect.width / 2, y: clientY - rect.top - rect.height / 2 };
+ }, []);
+
+ // 滚轮 / 触控板:native listener + passive:false 才能 preventDefault,事件只在
+ // stage 上被消费,指针在 stage 外时弹窗照常滚动。
+ useEffect(() => {
+ const node = stageRef.current;
+ if (!node) return;
+ const trackWheelSource = createWheelSourceTracker();
+ const onWheel = (e: WheelEvent) => {
+ e.preventDefault();
+ const modifierZoom = e.ctrlKey || e.metaKey;
+ const device = modifierZoom
+ ? 'mouse'
+ : trackWheelSource(
+ {
+ deltaMode: e.deltaMode,
+ deltaX: e.deltaX,
+ deltaY: e.deltaY,
+ shiftKey: e.shiftKey,
+ wheelDeltaY: (e as WheelEvent & { wheelDeltaY?: number }).wheelDeltaY,
+ },
+ e.timeStamp,
+ );
+ if (modifierZoom || device === 'mouse') {
+ if (e.deltaY === 0) return;
+ const zoom = avatarCropZoom(cropRef.current, source.size);
+ zoomTo(zoom * wheelZoomFactor(e.deltaY, e.deltaMode), toViewPoint(e.clientX, e.clientY));
+ return;
+ }
+ // 触控板双指滑动:内容跟手走(与 lightbox 放大后的平移方向一致)。
+ panBy(
+ -normalizeWheelDelta(e.deltaX, e.deltaMode),
+ -normalizeWheelDelta(e.deltaY, e.deltaMode),
+ );
+ };
+ node.addEventListener('wheel', onWheel, { passive: false });
+ return () => node.removeEventListener('wheel', onWheel);
+ }, [panBy, source.size, toViewPoint, zoomTo]);
+
+ const handlePointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+ if (e.pointerType === 'mouse' && e.button !== 0) return;
+ // 抑制文字选区与原生拖拽;焦点仍交给 stage,方便随后用键盘微调。
+ e.preventDefault();
+ e.currentTarget.focus({ preventScroll: true });
+ e.currentTarget.setPointerCapture(e.pointerId);
+ pointersRef.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+ setDragging(true);
+ };
+
+ const handlePointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+ const pointers = pointersRef.current;
+ const prev = pointers.get(e.pointerId);
+ if (!prev) return;
+ const next = { x: e.clientX, y: e.clientY };
+ if (pointers.size === 1) {
+ pointers.set(e.pointerId, next);
+ panBy(next.x - prev.x, next.y - prev.y);
+ return;
+ }
+ // 两指:中点位移 → 平移,指间距比例 → 以新中点为焦点缩放。
+ const others = [...pointers.entries()].filter(([id]) => id !== e.pointerId);
+ const other = others[0]?.[1];
+ pointers.set(e.pointerId, next);
+ if (!other) return;
+ const prevMid = { x: (prev.x + other.x) / 2, y: (prev.y + other.y) / 2 };
+ const nextMid = { x: (next.x + other.x) / 2, y: (next.y + other.y) / 2 };
+ const prevDist = Math.hypot(prev.x - other.x, prev.y - other.y);
+ const nextDist = Math.hypot(next.x - other.x, next.y - other.y);
+ const panned = panAvatarCrop(
+ cropRef.current,
+ source.size,
+ nextMid.x - prevMid.x,
+ nextMid.y - prevMid.y,
+ viewSideRef.current,
+ );
+ const ratio = prevDist > 0 ? nextDist / prevDist : 1;
+ emit(
+ zoomAvatarCrop(
+ panned,
+ source.size,
+ avatarCropZoom(panned, source.size) * ratio,
+ viewSideRef.current,
+ toViewPoint(nextMid.x, nextMid.y),
+ ),
+ );
+ };
+
+ const endPointer = (e: React.PointerEvent<HTMLDivElement>) => {
+ const pointers = pointersRef.current;
+ if (!pointers.delete(e.pointerId)) return;
+ if (pointers.size === 0) setDragging(false);
+ };
+
+ const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+ if (e.metaKey || e.ctrlKey || e.altKey) return;
+ const step = e.shiftKey ? KEY_PAN_STEP_LARGE : KEY_PAN_STEP;
+ const zoom = avatarCropZoom(cropRef.current, source.size);
+ switch (e.key) {
+ case 'ArrowLeft':
+ panBy(-step, 0);
+ break;
+ case 'ArrowRight':
+ panBy(step, 0);
+ break;
+ case 'ArrowUp':
+ panBy(0, -step);
+ break;
+ case 'ArrowDown':
+ panBy(0, step);
+ break;
+ case '+':
+ case '=':
+ zoomTo(zoom * AVATAR_CROP_ZOOM_STEP);
+ break;
+ case '-':
+ case '_':
+ zoomTo(zoom / AVATAR_CROP_ZOOM_STEP);
+ break;
+ default:
+ return;
+ }
+ e.preventDefault();
+ };
+
+ const zoom = avatarCropZoom(crop, source.size);
+ // 浮点误差容差:避免 1.0000001 让「缩小」按钮停在可点状态。
+ const atMinZoom = zoom <= 1 + 1e-6;
+ const atMaxZoom = zoom >= AVATAR_CROP_MAX_ZOOM - 1e-6;
+ const zoomPercent = Math.round(zoom * 100);
+
+ return (
+ <div className="flex flex-col gap-3">
+ <div
+ ref={setStageNode}
+ role="group"
+ tabIndex={0}
+ aria-label={t('settings.userProfile.edit.crop.stageLabel')}
+ aria-keyshortcuts="ArrowLeft ArrowRight ArrowUp ArrowDown + -"
+ onPointerDown={handlePointerDown}
+ onPointerMove={handlePointerMove}
+ onPointerUp={endPointer}
+ onPointerCancel={endPointer}
+ onLostPointerCapture={endPointer}
+ onKeyDown={handleKeyDown}
+ className={cn(
+ 'group relative h-[288px] w-full shrink-0 touch-none select-none overflow-hidden rounded-xl',
+ 'bg-[var(--surface-chip)] outline-none',
+ dragging ? 'cursor-grabbing' : 'cursor-grab',
+ )}
+ >
+ <canvas ref={canvasRef} aria-hidden className="absolute inset-0 h-full w-full" />
+ {/* 取景圆:圆外由超大 spread 的阴影压暗,圆内即最终头像;内侧一圈半透白细线
+ 让圆边在花哨照片上也清晰(恒定浅色,同 lightbox 浮在暗底上的 chrome)。
+ 压暗是「看图」语义,取跨主题恒定的 lightbox 暗底并减淡到约 60%,保留圆外
+ 构图上下文;--overlay-modal 专属模态遮罩,这里不能用(modalSurfaceContract)。 */}
+ <div
+ aria-hidden
+ className="pointer-events-none absolute left-1/2 top-1/2 rounded-full"
+ style={{
+ width: viewSide,
+ height: viewSide,
+ marginLeft: -viewSide / 2,
+ marginTop: -viewSide / 2,
+ boxShadow:
+ '0 0 0 9999px color-mix(in srgb, var(--overlay-lightbox) 70%, transparent), inset 0 0 0 1px color-mix(in srgb, var(--lightbox-toolbar-fg-hover) 55%, transparent)',
+ }}
+ />
+ {/* 焦点环单独一层:画在画布之上,且不会被弹窗滚动区裁掉。 */}
+ <div
+ aria-hidden
+ className={cn(
+ 'pointer-events-none absolute inset-0 rounded-xl',
+ 'group-focus-visible:ring-2 group-focus-visible:ring-inset group-focus-visible:ring-[var(--focus-ring-soft)]',
+ )}
+ />
+ </div>
+
+ <div className="flex items-center gap-1">
+ <Tip text={t('settings.userProfile.edit.crop.zoomOut')} contentClassName={tipClassName}>
+ <Button
+ type="button"
+ variant="secondary"
+ tone="quiet"
+ size="md"
+ className={ZOOM_BUTTON_CLASS}
+ aria-label={t('settings.userProfile.edit.crop.zoomOut')}
+ aria-disabled={atMinZoom}
+ onClick={() => zoomTo(zoom / AVATAR_CROP_ZOOM_STEP)}
+ >
+ <ZoomOut size={16} aria-hidden />
+ </Button>
+ </Tip>
+ <Slider
+ className="mx-1 flex-1"
+ min={0}
+ max={AVATAR_ZOOM_SLIDER_MAX}
+ step={1}
+ value={[avatarZoomToSlider(zoom)]}
+ onValueChange={([value]) => {
+ if (value !== undefined) zoomTo(avatarSliderToZoom(value));
+ }}
+ aria-label={t('settings.userProfile.edit.crop.zoomLabel')}
+ aria-valuetext={t('settings.userProfile.edit.crop.zoomValue', { percent: zoomPercent })}
+ />
+ <Tip text={t('settings.userProfile.edit.crop.zoomIn')} contentClassName={tipClassName}>
+ <Button
+ type="button"
+ variant="secondary"
+ tone="quiet"
+ size="md"
+ className={ZOOM_BUTTON_CLASS}
+ aria-label={t('settings.userProfile.edit.crop.zoomIn')}
+ aria-disabled={atMaxZoom}
+ onClick={() => zoomTo(zoom * AVATAR_CROP_ZOOM_STEP)}
+ >
+ <ZoomIn size={16} aria-hidden />
+ </Button>
+ </Tip>
+ </div>
+ </div>
+ );
+ },
+);
diff --git a/apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx b/apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx
index c37dd4ee63..7f64ba4762 100644
--- a/apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx
+++ b/apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx
@@ -6,6 +6,15 @@ import { cn } from '@/lib/utils';
import { toast } from '@/lib/toast';
import { ConfirmDialog } from '@/components/ui/confirm-dialog';
+import { AvatarCropEditor } from './AvatarCropEditor';
+import { initialAvatarCrop, type AvatarCrop } from './avatarCropGeometry';
+import {
+ exportAvatarCrop,
+ loadAvatarSource,
+ type AvatarExport,
+ type AvatarSource,
+} from './avatarCropImage';
+
/**
* ProfileEditDialog — 设置页用户卡片的「编辑名字 / 头像」弹窗。
*
@@ -14,9 +23,15 @@ import { ConfirmDialog } from '@/components/ui/confirm-dialog';
* 预签名直传),跨设备生效;保存成功后 main 重广播 auth:state-change,
* 卡片 / 侧边栏经 AuthContext 自动刷新。
*
- * 头像动作三态:keep(没动)/ set(选了新图,预览用 data URL)/ reset(清除
- * 自定义头像,回落产品默认)。名字输入预填当前名字,留空 = 不改名
- * (服务端不允许清空名字)。
+ * 两个步骤共用同一个弹窗(不叠第二层遮罩):
+ * - 资料表单:名字 + 头像预览;
+ * - 调整头像:选图后进入,拖动 / 缩放取景(AvatarCropEditor)。「完成」把取景
+ * 导出成最终字节回到表单;「取消」/ Esc 回到表单且不动草稿。
+ * 只有表单的「保存资料」才会上传;关闭弹窗零副作用。
+ *
+ * 头像动作三态:keep(没动)/ set(已调整好的新头像,预览直接用将要上传的字节)/
+ * reset(清除自定义头像,回落产品默认)。名字输入预填当前名字,留空 = 不改名
+ * (服务端不允许清空名字)。保存失败时草稿原样保留,可直接重试或继续调整。
*/
interface ProfileEditDialogProps {
open: boolean;
@@ -25,29 +40,121 @@ interface ProfileEditDialogProps {
type AvatarDraft =
| { type: 'keep' }
- | { type: 'set'; filePath: string; previewDataUrl: string }
+ | {
+ type: 'set';
+ exported: AvatarExport;
+ /** exported.blob 的 object URL:表单预览即上传内容本身。 */
+ previewUrl: string;
+ /** 保留取景源与位置,「调整」可接着上次的构图继续改。 */
+ source: AvatarSource;
+ crop: AvatarCrop;
+ }
| { type: 'reset' };
+/** 调整头像步骤的进行中状态。source 可能来自新选的图,也可能复用草稿的源。 */
+interface CropSession {
+ source: AvatarSource;
+ crop: AvatarCrop;
+}
+
interface ProfileState {
name: string;
avatarUrl: string | null;
}
+// Tooltip 默认 z-[60],会被 z-[10000] 的弹窗盖住(DESIGN §4 Dialog & Modal)。
+const DIALOG_TIP_CLASS = 'z-[10001]';
+
export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps) {
const { t } = useTranslation();
const [state, setState] = useState<ProfileState | null>(null);
const [name, setName] = useState('');
- const [avatarDraft, setAvatarDraft] = useState<AvatarDraft>({ type: 'keep' });
+ const [avatarDraft, setAvatarDraftState] = useState<AvatarDraft>({ type: 'keep' });
+ const [cropSession, setCropSessionState] = useState<CropSession | null>(null);
const [saving, setSaving] = useState(false);
// Radix AlertDialog.Action 在点击的同一事件里**同步**触发 onOpenChange(false),
// 彼时 setSaving(true) 还没重渲染、闭包里的 saving 仍是 false——守卫必须走 ref
// 才拦得住(同款踩坑与修法见 WindowControls.tsx 的 closingRef)。
const savingRef = useRef(false);
+ // 同理:「完成」导出是异步的,紧随其后的同步 onOpenChange(false) 不能被当成「取消调整」。
+ const exportingRef = useRef(false);
+ const choosingRef = useRef(false);
+ // 选图请求的代次:关闭弹窗或卸载时 +1,让还在系统选择器 / 解码中的旧请求作废——
+ // 否则关掉再重开时,旧请求返回会把已放弃的图片带回调整步骤。
+ const chooseGenerationRef = useRef(0);
+ const openRef = useRef(open);
+ openRef.current = open;
+ // 位图 / object URL 的所有权跟踪:ref 始终是最新值,释放逻辑不依赖渲染时机。
+ const draftRef = useRef<AvatarDraft>(avatarDraft);
+ const sessionRef = useRef<CropSession | null>(cropSession);
+ const stageRef = useRef<HTMLDivElement | null>(null);
+ const changeAvatarRef = useRef<HTMLButtonElement | null>(null);
+ const focusAfterFormRef = useRef(false);
+ // 只在两个步骤之间切换时淡入新内容;首次打开交给弹窗自己的入场动效,不叠加。
+ const [stepSwitched, setStepSwitched] = useState(false);
+
+ /** 替换头像草稿并释放旧草稿独占的资源(仍被调整会话或新草稿复用的源不释放)。 */
+ const setAvatarDraft = useCallback((next: AvatarDraft) => {
+ const prev = draftRef.current;
+ if (prev.type === 'set') {
+ if (next.type !== 'set' || next.previewUrl !== prev.previewUrl) {
+ URL.revokeObjectURL(prev.previewUrl);
+ }
+ const reused =
+ (next.type === 'set' && next.source === prev.source) ||
+ sessionRef.current?.source === prev.source;
+ if (!reused) prev.source.bitmap.close();
+ }
+ draftRef.current = next;
+ setAvatarDraftState(next);
+ }, []);
+
+ /** 结束调整会话;源若既不属于草稿也不再被使用就释放。 */
+ const endCropSession = useCallback(() => {
+ const session = sessionRef.current;
+ sessionRef.current = null;
+ setCropSessionState(null);
+ const draft = draftRef.current;
+ if (session && !(draft.type === 'set' && draft.source === session.source)) {
+ session.source.bitmap.close();
+ }
+ }, []);
+
+ const startCropSession = useCallback(
+ (session: CropSession) => {
+ // 正在调整中又选了新图(理论上不会,入口在表单里)时先收掉旧会话。
+ if (sessionRef.current && sessionRef.current.source !== session.source) endCropSession();
+ sessionRef.current = session;
+ setCropSessionState(session);
+ setStepSwitched(true);
+ },
+ [endCropSession],
+ );
+
+ const updateCrop = useCallback((crop: AvatarCrop) => {
+ const session = sessionRef.current;
+ if (!session) return;
+ const next = { ...session, crop };
+ sessionRef.current = next;
+ setCropSessionState(next);
+ }, []);
+
+ /** 关闭 / 卸载时释放全部位图与 object URL。 */
+ const releaseAll = useCallback(() => {
+ endCropSession();
+ setAvatarDraft({ type: 'keep' });
+ }, [endCropSession, setAvatarDraft]);
// 打开时拉预填数据并复位草稿(异步取数期间不渲染内容,避免半空帧;
// 数据都在本地 main,毫秒级返回,无需 loading 态 —— 规则 7)。
useEffect(() => {
- if (!open) return;
+ if (!open) {
+ chooseGenerationRef.current += 1;
+ choosingRef.current = false;
+ releaseAll();
+ return;
+ }
+ setStepSwitched(false);
let stale = false;
void window.electronAPI
.profileGetState()
@@ -55,7 +162,7 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
if (stale) return;
setState(s);
setName(s.name);
- setAvatarDraft({ type: 'keep' });
+ releaseAll();
})
.catch(() => {
if (!stale) onOpenChange(false);
@@ -63,21 +170,84 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
return () => {
stale = true;
};
- }, [open, onOpenChange]);
+ }, [open, onOpenChange, releaseAll]);
+
+ useEffect(
+ () => () => {
+ chooseGenerationRef.current += 1;
+ releaseAll();
+ },
+ [releaseAll],
+ );
+
+ // 步骤切换后的焦点:进入调整 → 聚焦取景区(方向键即可微调);回到表单 → 回到触发按钮。
+ const inCrop = cropSession !== null;
+ useEffect(() => {
+ if (inCrop) {
+ stageRef.current?.focus({ preventScroll: true });
+ } else if (focusAfterFormRef.current) {
+ focusAfterFormRef.current = false;
+ changeAvatarRef.current?.focus({ preventScroll: true });
+ }
+ }, [inCrop]);
const handleChooseAvatar = useCallback(async () => {
+ if (choosingRef.current) return;
+ choosingRef.current = true;
+ const generation = chooseGenerationRef.current;
+ const isCurrent = () => generation === chooseGenerationRef.current && openRef.current;
try {
const result = await window.electronAPI.profileChooseAvatar();
- if (result.canceled || !result.filePath || !result.previewDataUrl) return;
+ if (!isCurrent() || result.canceled || !result.previewDataUrl) return;
+ // 先解码再切到调整步骤:编辑台第一帧就有图,解码失败则留在表单提示。
+ const source = await loadAvatarSource(result.previewDataUrl);
+ if (!isCurrent()) {
+ source.bitmap.close();
+ return;
+ }
+ startCropSession({ source, crop: initialAvatarCrop(source.size) });
+ } catch {
+ if (isCurrent()) toast.error(t('settings.userProfile.edit.avatarInvalid'));
+ } finally {
+ // 作废的请求不动守卫:关闭时已复位,新一轮打开可能已在选图。
+ if (generation === chooseGenerationRef.current) choosingRef.current = false;
+ }
+ }, [startCropSession, t]);
+
+ const handleAdjustAvatar = useCallback(() => {
+ const draft = draftRef.current;
+ if (draft.type !== 'set') return;
+ startCropSession({ source: draft.source, crop: draft.crop });
+ }, [startCropSession]);
+
+ const leaveCrop = useCallback(() => {
+ focusAfterFormRef.current = true;
+ setStepSwitched(true);
+ endCropSession();
+ }, [endCropSession]);
+
+ const handleCropDone = useCallback(async () => {
+ const session = sessionRef.current;
+ if (!session || exportingRef.current) return;
+ exportingRef.current = true; // await 之前同步置位,拦住 Radix Action 的同步关闭
+ try {
+ const exported = await exportAvatarCrop(session.source, session.crop);
+ // 期间弹窗被关闭(会话已收掉、位图已释放)就丢弃结果;导出的是点「完成」那一刻的取景。
+ if (sessionRef.current?.source !== session.source) return;
setAvatarDraft({
type: 'set',
- filePath: result.filePath,
- previewDataUrl: result.previewDataUrl,
+ exported,
+ previewUrl: URL.createObjectURL(exported.blob),
+ source: session.source,
+ crop: session.crop,
});
+ leaveCrop();
} catch {
- toast.error(t('settings.userProfile.edit.avatarInvalid'));
+ toast.error(t('settings.userProfile.edit.crop.exportFailed'));
+ } finally {
+ exportingRef.current = false;
}
- }, [t]);
+ }, [leaveCrop, setAvatarDraft, t]);
const handleSave = useCallback(async () => {
if (!state || savingRef.current) return;
@@ -85,12 +255,13 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
setSaving(true);
try {
const trimmed = name.trim();
+ const draft = draftRef.current;
await window.electronAPI.profileUpdate({
name: trimmed === '' ? null : trimmed,
avatar:
- avatarDraft.type === 'set'
- ? { type: 'set', filePath: avatarDraft.filePath }
- : { type: avatarDraft.type },
+ draft.type === 'set'
+ ? { type: 'set', data: draft.exported.bytes, mimeType: draft.exported.mimeType }
+ : { type: draft.type },
});
savingRef.current = false;
setSaving(false);
@@ -100,14 +271,53 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
setSaving(false);
toast.error(t('settings.userProfile.edit.saveFailed'));
}
- }, [state, name, avatarDraft, onOpenChange, t]);
+ }, [state, name, onOpenChange, t]);
if (!state) return null;
- // 预览优先级:新选的图 > 现有头像(reset 时回首字母兜底)。
+ const handleOpenChange = (next: boolean) => {
+ if (next) {
+ onOpenChange(true);
+ return;
+ }
+ if (savingRef.current) return; // 保存中不允许关(ref 守卫,见 savingRef 注释)
+ // 调整步骤里的「取消」/ Esc 只回到表单;「完成」由 handleCropDone 自己收尾。
+ if (sessionRef.current) {
+ if (!exportingRef.current) leaveCrop();
+ return;
+ }
+ onOpenChange(false);
+ };
+
+ if (cropSession) {
+ return (
+ <ConfirmDialog
+ open={open}
+ onOpenChange={handleOpenChange}
+ title={t('settings.userProfile.edit.crop.title')}
+ description={t('settings.userProfile.edit.crop.description')}
+ confirmText={t('settings.userProfile.edit.crop.done')}
+ cancelText={t('settings.userProfile.edit.cancel')}
+ onConfirm={() => void handleCropDone()}
+ content={
+ <div className={cn(stepSwitched && 'animate-fade-in')}>
+ <AvatarCropEditor
+ ref={stageRef}
+ source={cropSession.source}
+ crop={cropSession.crop}
+ onCropChange={updateCrop}
+ tipClassName={DIALOG_TIP_CLASS}
+ />
+ </div>
+ }
+ />
+ );
+ }
+
+ // 预览优先级:新调整好的图 > 现有头像(reset 时回首字母兜底)。
const previewUrl =
avatarDraft.type === 'set'
- ? avatarDraft.previewDataUrl
+ ? avatarDraft.previewUrl
: avatarDraft.type === 'reset'
? null
: state.avatarUrl;
@@ -116,14 +326,16 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
const initial = effectiveName.charAt(0).toUpperCase();
const canResetAvatar =
avatarDraft.type === 'set' || (avatarDraft.type === 'keep' && state.avatarUrl !== null);
+ const linkClass = cn(
+ 'px-1 text-12 text-[var(--text-tertiary)] transition-colors',
+ 'hover:text-[var(--text-primary)]',
+ 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring-soft)]',
+ );
return (
<ConfirmDialog
open={open}
- onOpenChange={(next) => {
- if (savingRef.current && !next) return; // 保存中不允许关(ref 守卫,见 savingRef 注释)
- onOpenChange(next);
- }}
+ onOpenChange={handleOpenChange}
title={t('settings.userProfile.edit.title')}
confirmText={t('settings.userProfile.edit.save')}
cancelText={t('settings.userProfile.edit.cancel')}
@@ -131,8 +343,8 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
loading={saving}
onConfirm={() => void handleSave()}
content={
- <div className="flex flex-col gap-4">
- {/* 头像行:预览 + 更换 / 清除自定义 */}
+ <div className={cn('flex flex-col gap-4', stepSwitched && 'animate-fade-in')}>
+ {/* 头像行:预览 + 更换 / 调整(共享 Button)+ 清除自定义(沿用既有文字动作) */}
<div className="flex items-center gap-4">
{previewUrl ? (
<img
@@ -156,24 +368,37 @@ export function ProfileEditDialog({ open, onOpenChange }: ProfileEditDialogProps
</div>
)}
<div className="flex flex-col items-start gap-1.5">
- <Button
- variant="secondary"
- size="sm"
- compact
- type="button"
- onClick={() => void handleChooseAvatar()}
- >
- {t('settings.userProfile.edit.changeAvatar')}
- </Button>
+ <div className="flex items-center gap-2">
+ <Button
+ ref={changeAvatarRef}
+ variant="secondary"
+ size="sm"
+ compact
+ type="button"
+ disabled={saving}
+ onClick={() => void handleChooseAvatar()}
+ >
+ {t('settings.userProfile.edit.changeAvatar')}
+ </Button>
+ {avatarDraft.type === 'set' && (
+ <Button
+ variant="secondary"
+ size="sm"
+ compact
+ type="button"
+ disabled={saving}
+ onClick={handleAdjustAvatar}
+ >
+ {t('settings.userProfile.edit.adjustAvatar')}
+ </Button>
+ )}
+ </div>
{canResetAvatar && (
<button
type="button"
+ disabled={saving}
onClick={() => setAvatarDraft({ type: 'reset' })}
- className={cn(
- 'px-1 text-12 text-[var(--text-tertiary)] transition-colors',
- 'hover:text-[var(--text-primary)]',
- 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring-soft)]',
- )}
+ className={linkClass}
>
{t('settings.userProfile.edit.resetAvatar')}
</button>
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/ProfileEditDialog.avatarCrop.test.tsx b/apps/desktop/src/renderer/components/settings/__tests__/ProfileEditDialog.avatarCrop.test.tsx
new file mode 100644
index 0000000000..b0f83cf337
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/__tests__/ProfileEditDialog.avatarCrop.test.tsx
@@ -0,0 +1,262 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { AvatarCrop } from '../avatarCropGeometry';
+import type { AvatarSource } from '../avatarCropImage';
+
+const image = vi.hoisted(() => ({
+ loadAvatarSource: vi.fn(),
+ exportAvatarCrop: vi.fn(),
+}));
+const toastError = vi.hoisted(() => vi.fn());
+
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+vi.mock('@/lib/toast', () => ({ toast: { error: toastError } }));
+vi.mock('../avatarCropImage', () => image);
+
+import { ProfileEditDialog } from '../ProfileEditDialog';
+
+const EXPORTED = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, 1]);
+
+function makeSource(width = 1200, height = 800): AvatarSource {
+ return {
+ bitmap: { width, height, close: vi.fn() } as unknown as ImageBitmap,
+ size: { width, height },
+ };
+}
+
+const api = {
+ profileGetState: vi.fn(),
+ profileChooseAvatar: vi.fn(),
+ profileUpdate: vi.fn(),
+};
+
+function renderDialog() {
+ const onOpenChange = vi.fn();
+ const view = render(<ProfileEditDialog open onOpenChange={onOpenChange} />);
+ return { onOpenChange, ...view };
+}
+
+async function chooseImage() {
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' }),
+ );
+ return screen.findByRole('group', { name: 'settings.userProfile.edit.crop.stageLabel' });
+}
+
+let source: AvatarSource;
+let objectUrlCount = 0;
+
+beforeEach(() => {
+ source = makeSource();
+ objectUrlCount = 0;
+ api.profileGetState.mockResolvedValue({ name: 'Dash', avatarUrl: 'https://cdn.example/old.png' });
+ api.profileChooseAvatar.mockResolvedValue({
+ canceled: false,
+ previewDataUrl: 'data:image/jpeg;base64,AAAA',
+ });
+ api.profileUpdate.mockResolvedValue({ ok: true });
+ image.loadAvatarSource.mockImplementation(async () => source);
+ image.exportAvatarCrop.mockImplementation(async () => ({
+ blob: new Blob([EXPORTED], { type: 'image/jpeg' }),
+ bytes: EXPORTED,
+ mimeType: 'image/jpeg',
+ }));
+ Object.assign(window, { electronAPI: api });
+ URL.createObjectURL = vi.fn(() => `blob:avatar-${++objectUrlCount}`);
+ URL.revokeObjectURL = vi.fn();
+ // jsdom 不做布局:给编辑台一个真实尺寸,否则取景圆直径为 0,平移 / 缩放全是 no-op。
+ vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
+ x: 0,
+ y: 0,
+ left: 0,
+ top: 0,
+ right: 368,
+ bottom: 288,
+ width: 368,
+ height: 288,
+ toJSON: () => ({}),
+ } as DOMRect);
+ // Radix Slider 量尺寸用 ResizeObserver,jsdom 没有。
+ globalThis.ResizeObserver ??= class {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+ } as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+ cleanup();
+ vi.clearAllMocks();
+ vi.restoreAllMocks();
+});
+
+describe('ProfileEditDialog 头像调整', () => {
+ it('选图后进入调整步骤;取消回到表单且不改旧头像,保存不上传', async () => {
+ const { onOpenChange } = renderDialog();
+ await chooseImage();
+ expect(screen.getByText('settings.userProfile.edit.crop.title')).toBeTruthy();
+
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.cancel' }));
+
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' });
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+ expect(image.exportAvatarCrop).not.toHaveBeenCalled();
+ expect((screen.getByRole('img') as HTMLImageElement).src).toBe('https://cdn.example/old.png');
+ // 新选的源没有被草稿接管,取消时立即释放。
+ expect(source.bitmap.close).toHaveBeenCalled();
+
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.save' }));
+ await waitFor(() => expect(api.profileUpdate).toHaveBeenCalledTimes(1));
+ expect(api.profileUpdate).toHaveBeenCalledWith({ name: 'Dash', avatar: { type: 'keep' } });
+ });
+
+ it('调整步骤里 Esc 只回到表单,不关闭弹窗', async () => {
+ const { onOpenChange } = renderDialog();
+ const stage = await chooseImage();
+ fireEvent.keyDown(stage, { key: 'Escape' });
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' });
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+ });
+
+ it('键盘平移 / 缩放后「完成」:导出当时的取景,预览即导出字节,保存上传同一份字节', async () => {
+ const { onOpenChange } = renderDialog();
+ const stage = await chooseImage();
+ // 横图铺满时可左右移动;放大后上下也能移动。
+ fireEvent.keyDown(stage, { key: 'ArrowRight', shiftKey: true });
+ fireEvent.keyDown(stage, { key: '+' });
+
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.crop.done' }));
+
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.adjustAvatar' });
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+ expect(image.exportAvatarCrop).toHaveBeenCalledTimes(1);
+ const [exportedFrom, crop] = image.exportAvatarCrop.mock.calls[0] as [AvatarSource, AvatarCrop];
+ expect(exportedFrom).toBe(source);
+ expect(crop.side).toBeCloseTo(800 / 1.2, 9);
+ expect(crop.cx).toBeLessThan(600);
+ expect((screen.getByRole('img') as HTMLImageElement).src).toBe('blob:avatar-1');
+
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.save' }));
+ await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+ expect(api.profileUpdate).toHaveBeenCalledWith({
+ name: 'Dash',
+ avatar: { type: 'set', data: EXPORTED, mimeType: 'image/jpeg' },
+ });
+ });
+
+ it('保存失败保留调整结果,可继续调整(沿用上次构图)或直接重试', async () => {
+ const { onOpenChange } = renderDialog();
+ const stage = await chooseImage();
+ fireEvent.keyDown(stage, { key: '+' });
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.crop.done' }));
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.adjustAvatar' });
+ const firstCrop = image.exportAvatarCrop.mock.calls[0]?.[1] as AvatarCrop;
+
+ api.profileUpdate.mockRejectedValueOnce(new Error('network'));
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.save' }));
+ await waitFor(() =>
+ expect(toastError).toHaveBeenCalledWith('settings.userProfile.edit.saveFailed'),
+ );
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+ expect((screen.getByRole('img') as HTMLImageElement).src).toBe('blob:avatar-1');
+ expect(source.bitmap.close).not.toHaveBeenCalled();
+
+ // 再次调整:回到上次的取景,而不是重新居中。
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.adjustAvatar' }));
+ await screen.findByRole('group', { name: 'settings.userProfile.edit.crop.stageLabel' });
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.crop.done' }));
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.adjustAvatar' });
+ expect(image.exportAvatarCrop.mock.calls[1]?.[1]).toEqual(firstCrop);
+ expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:avatar-1');
+
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.save' }));
+ await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+ expect(api.profileUpdate).toHaveBeenCalledTimes(2);
+ });
+
+ it('解码失败留在表单并提示;导出失败留在调整步骤并提示', async () => {
+ renderDialog();
+ image.loadAvatarSource.mockRejectedValueOnce(new Error('corrupt'));
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' }),
+ );
+ await waitFor(() =>
+ expect(toastError).toHaveBeenCalledWith('settings.userProfile.edit.avatarInvalid'),
+ );
+ expect(screen.queryByRole('group')).toBeNull();
+
+ await chooseImage();
+ image.exportAvatarCrop.mockRejectedValueOnce(new Error('encode'));
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.crop.done' }));
+ });
+ expect(toastError).toHaveBeenCalledWith('settings.userProfile.edit.crop.exportFailed');
+ expect(
+ screen.getByRole('group', { name: 'settings.userProfile.edit.crop.stageLabel' }),
+ ).toBeTruthy();
+ });
+
+ it('重新选图从新图的居中铺满开始,替换旧草稿并释放旧位图', async () => {
+ renderDialog();
+ const stage = await chooseImage();
+ fireEvent.keyDown(stage, { key: '+' });
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.crop.done' }));
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.adjustAvatar' });
+ const first = source;
+
+ source = makeSource(600, 900);
+ await chooseImage();
+ fireEvent.click(screen.getByRole('button', { name: 'settings.userProfile.edit.crop.done' }));
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.adjustAvatar' });
+
+ expect(image.exportAvatarCrop.mock.calls[1]).toEqual([source, { cx: 300, cy: 450, side: 600 }]);
+ expect(first.bitmap.close).toHaveBeenCalled();
+ expect(source.bitmap.close).not.toHaveBeenCalled();
+ });
+
+ it('选图解码期间关闭再重开:旧请求作废,不把已放弃的图片带回调整步骤并释放其位图', async () => {
+ let resolveDecode: (value: AvatarSource) => void = () => {};
+ image.loadAvatarSource.mockImplementationOnce(
+ () => new Promise<AvatarSource>((resolve) => (resolveDecode = resolve)),
+ );
+ const { rerender } = renderDialog();
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' }),
+ );
+ await waitFor(() => expect(image.loadAvatarSource).toHaveBeenCalledTimes(1));
+
+ rerender(<ProfileEditDialog open={false} onOpenChange={vi.fn()} />);
+ rerender(<ProfileEditDialog open onOpenChange={vi.fn()} />);
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' });
+
+ const stale = makeSource();
+ await act(async () => resolveDecode(stale));
+
+ expect(screen.queryByRole('group')).toBeNull();
+ expect(stale.bitmap.close).toHaveBeenCalled();
+ expect(toastError).not.toHaveBeenCalled();
+ // 新一轮打开可以正常选图,不被旧请求的守卫挡住。
+ await chooseImage();
+ });
+
+ it('选图解码期间卸载:返回的位图被释放,不进入调整步骤', async () => {
+ let resolveDecode: (value: AvatarSource) => void = () => {};
+ image.loadAvatarSource.mockImplementationOnce(
+ () => new Promise<AvatarSource>((resolve) => (resolveDecode = resolve)),
+ );
+ const { unmount } = renderDialog();
+ fireEvent.click(
+ await screen.findByRole('button', { name: 'settings.userProfile.edit.changeAvatar' }),
+ );
+ await waitFor(() => expect(image.loadAvatarSource).toHaveBeenCalledTimes(1));
+ unmount();
+ const stale = makeSource();
+ await act(async () => resolveDecode(stale));
+ expect(stale.bitmap.close).toHaveBeenCalled();
+ });
+});
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/avatarCropGeometry.test.ts b/apps/desktop/src/renderer/components/settings/__tests__/avatarCropGeometry.test.ts
new file mode 100644
index 0000000000..4c63424eef
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/__tests__/avatarCropGeometry.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ AVATAR_CROP_MAX_ZOOM,
+ AVATAR_OUTPUT_MAX_PX,
+ AVATAR_OUTPUT_MIN_PX,
+ AVATAR_ZOOM_SLIDER_MAX,
+ avatarCropDrawRect,
+ avatarCropZoom,
+ avatarOutputSize,
+ avatarSliderToZoom,
+ avatarStageTransform,
+ avatarZoomToSlider,
+ clampAvatarCrop,
+ initialAvatarCrop,
+ panAvatarCrop,
+ zoomAvatarCrop,
+ type AvatarCrop,
+ type AvatarImageSize,
+} from '../avatarCropGeometry';
+
+const VIEW = 240;
+const LANDSCAPE: AvatarImageSize = { width: 4000, height: 3000 };
+const PORTRAIT: AvatarImageSize = { width: 1080, height: 1920 };
+const TINY: AvatarImageSize = { width: 48, height: 40 };
+
+/** 取景正方形完整落在图内、边长在合法范围:导出不会采到图外(透明 / 空白)。 */
+function expectInside(crop: AvatarCrop, size: AvatarImageSize) {
+ const { sx, sy, sw, sh } = avatarCropDrawRect(crop);
+ const eps = 1e-9;
+ expect(sx).toBeGreaterThanOrEqual(-eps);
+ expect(sy).toBeGreaterThanOrEqual(-eps);
+ expect(sx + sw).toBeLessThanOrEqual(size.width + eps);
+ expect(sy + sh).toBeLessThanOrEqual(size.height + eps);
+ expect(sw).toBeCloseTo(sh, 12);
+ const zoom = avatarCropZoom(crop, size);
+ expect(zoom).toBeGreaterThanOrEqual(1 - eps);
+ expect(zoom).toBeLessThanOrEqual(AVATAR_CROP_MAX_ZOOM + eps);
+}
+
+/** 视图坐标(相对圆心)下方对应的源图点。 */
+function sourceUnder(crop: AvatarCrop, point: { x: number; y: number }) {
+ const scale = VIEW / crop.side;
+ return { x: crop.cx + point.x / scale, y: crop.cy + point.y / scale };
+}
+
+describe('avatarCropGeometry', () => {
+ it('初始构图铺满并居中:横图左右留余量、竖图上下留余量、小图同样铺满', () => {
+ expect(initialAvatarCrop(LANDSCAPE)).toEqual({ cx: 2000, cy: 1500, side: 3000 });
+ expect(initialAvatarCrop(PORTRAIT)).toEqual({ cx: 540, cy: 960, side: 1080 });
+ expect(initialAvatarCrop(TINY)).toEqual({ cx: 24, cy: 20, side: 40 });
+ for (const size of [LANDSCAPE, PORTRAIT, TINY]) {
+ expect(avatarCropZoom(initialAvatarCrop(size), size)).toBe(1);
+ expectInside(initialAvatarCrop(size), size);
+ }
+ });
+
+ it('平移跟手:视图拖动 1px = 图片在屏幕上同向移动 1px', () => {
+ const crop = zoomAvatarCrop(initialAvatarCrop(LANDSCAPE), LANDSCAPE, 2, VIEW);
+ const before = avatarStageTransform(crop, VIEW, 368, 288);
+ const moved = panAvatarCrop(crop, LANDSCAPE, 12, -7, VIEW);
+ const after = avatarStageTransform(moved, VIEW, 368, 288);
+ expect(after.x - before.x).toBeCloseTo(12, 9);
+ expect(after.y - before.y).toBeCloseTo(-7, 9);
+ });
+
+ it('平移越界被夹住,永远不露出图外空白', () => {
+ let crop = initialAvatarCrop(LANDSCAPE);
+ // 横图铺满时只能左右移动:纵向拖动是 no-op。
+ expect(panAvatarCrop(crop, LANDSCAPE, 0, 500, VIEW)).toEqual(crop);
+ crop = panAvatarCrop(crop, LANDSCAPE, 1e6, 1e6, VIEW);
+ expect(crop.cx).toBe(crop.side / 2);
+ expectInside(crop, LANDSCAPE);
+ crop = panAvatarCrop(crop, LANDSCAPE, -1e6, -1e6, VIEW);
+ expect(crop.cx).toBe(LANDSCAPE.width - crop.side / 2);
+ expectInside(crop, LANDSCAPE);
+ });
+
+ it('以焦点缩放:光标下的源图点在缩放前后保持不动(未触边时)', () => {
+ const crop = zoomAvatarCrop(initialAvatarCrop(LANDSCAPE), LANDSCAPE, 1.5, VIEW);
+ const focal = { x: 40, y: -30 };
+ const before = sourceUnder(crop, focal);
+ const zoomed = zoomAvatarCrop(crop, LANDSCAPE, 2.5, VIEW, focal);
+ const after = sourceUnder(zoomed, focal);
+ expect(after.x).toBeCloseTo(before.x, 9);
+ expect(after.y).toBeCloseTo(before.y, 9);
+ expect(avatarCropZoom(zoomed, LANDSCAPE)).toBeCloseTo(2.5, 12);
+ });
+
+ it('缩放倍率夹在 [1, 最大倍率];缩小到边界时中心被推回图内', () => {
+ const base = initialAvatarCrop(PORTRAIT);
+ expect(avatarCropZoom(zoomAvatarCrop(base, PORTRAIT, 0.2, VIEW), PORTRAIT)).toBe(1);
+ expect(avatarCropZoom(zoomAvatarCrop(base, PORTRAIT, 99, VIEW), PORTRAIT)).toBeCloseTo(
+ AVATAR_CROP_MAX_ZOOM,
+ 12,
+ );
+ // 放大后挪到右下角,再以左上焦点缩回 1x:不能露空白。
+ let crop = zoomAvatarCrop(base, PORTRAIT, 3, VIEW);
+ crop = panAvatarCrop(crop, PORTRAIT, -1e6, -1e6, VIEW);
+ crop = zoomAvatarCrop(crop, PORTRAIT, 1, VIEW, { x: -120, y: -120 });
+ expectInside(crop, PORTRAIT);
+ });
+
+ it('连续缩放无跳变:细步缩放与一步到位结果一致', () => {
+ const base = initialAvatarCrop(LANDSCAPE);
+ const focal = { x: 10, y: 20 };
+ let stepped = base;
+ for (let i = 1; i <= 50; i += 1) {
+ stepped = zoomAvatarCrop(stepped, LANDSCAPE, 1 + i * 0.02, VIEW, focal);
+ }
+ const direct = zoomAvatarCrop(base, LANDSCAPE, 2, VIEW, focal);
+ expect(stepped.side).toBeCloseTo(direct.side, 9);
+ expect(stepped.cx).toBeCloseTo(direct.cx, 6);
+ expect(stepped.cy).toBeCloseTo(direct.cy, 6);
+ });
+
+ it('stage 尚未量出尺寸(viewSide=0)时平移 / 缩放是 no-op,不产生 NaN', () => {
+ const crop = initialAvatarCrop(LANDSCAPE);
+ expect(panAvatarCrop(crop, LANDSCAPE, 10, 10, 0)).toBe(crop);
+ expect(zoomAvatarCrop(crop, LANDSCAPE, 2, 0)).toBe(crop);
+ });
+
+ it('clamp 修正任意非法取景(过大、过小、越界)', () => {
+ expectInside(clampAvatarCrop({ cx: -50, cy: 9e9, side: 9e9 }, LANDSCAPE), LANDSCAPE);
+ expectInside(clampAvatarCrop({ cx: 0, cy: 0, side: 1 }, TINY), TINY);
+ });
+
+ it('编辑台摆放与导出源矩形同源:取景圆在屏幕上恰好覆盖导出区域', () => {
+ const crop = panAvatarCrop(
+ zoomAvatarCrop(initialAvatarCrop(PORTRAIT), PORTRAIT, 2.2, VIEW, { x: 30, y: 50 }),
+ PORTRAIT,
+ -15,
+ 40,
+ VIEW,
+ );
+ const stage = { width: 368, height: 288 };
+ const { scale, x, y } = avatarStageTransform(crop, VIEW, stage.width, stage.height);
+ const { sx, sy, sw } = avatarCropDrawRect(crop);
+ // 导出矩形左上角映射回 stage 上就是取景圆的外接正方形左上角。
+ expect(x + sx * scale).toBeCloseTo((stage.width - VIEW) / 2, 9);
+ expect(y + sy * scale).toBeCloseTo((stage.height - VIEW) / 2, 9);
+ expect(sw * scale).toBeCloseTo(VIEW, 9);
+ });
+
+ it('导出边长按取景源像素取整并夹在上下限,不拉伸(始终正方形)', () => {
+ expect(avatarOutputSize(initialAvatarCrop(LANDSCAPE))).toBe(AVATAR_OUTPUT_MAX_PX);
+ expect(avatarOutputSize(initialAvatarCrop(TINY))).toBe(AVATAR_OUTPUT_MIN_PX);
+ expect(avatarOutputSize({ cx: 200, cy: 200, side: 300.4 })).toBe(300);
+ });
+
+ it('滑杆对数映射可逆,两端对应 1x 与最大倍率', () => {
+ expect(avatarZoomToSlider(1)).toBe(0);
+ expect(avatarZoomToSlider(AVATAR_CROP_MAX_ZOOM)).toBeCloseTo(AVATAR_ZOOM_SLIDER_MAX, 12);
+ expect(avatarSliderToZoom(0)).toBe(1);
+ expect(avatarSliderToZoom(AVATAR_ZOOM_SLIDER_MAX)).toBeCloseTo(AVATAR_CROP_MAX_ZOOM, 12);
+ for (const zoom of [1.1, 1.7, 2, 3.3]) {
+ expect(avatarSliderToZoom(avatarZoomToSlider(zoom))).toBeCloseTo(zoom, 12);
+ }
+ // 中点 = 几何平均 2x(4x 上限下),而不是线性的 2.5x。
+ expect(avatarSliderToZoom(AVATAR_ZOOM_SLIDER_MAX / 2)).toBeCloseTo(2, 12);
+ });
+});
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/avatarCropImage.test.ts b/apps/desktop/src/renderer/components/settings/__tests__/avatarCropImage.test.ts
new file mode 100644
index 0000000000..1231d3bcca
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/__tests__/avatarCropImage.test.ts
@@ -0,0 +1,171 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { avatarCropDrawRect, avatarOutputSize, type AvatarCrop } from '../avatarCropGeometry';
+import {
+ AVATAR_SOURCE_MAX_EDGE,
+ avatarExportMime,
+ exportAvatarCrop,
+ fitAvatarSourceSize,
+ hasTransparentPixel,
+ loadAvatarSource,
+ type AvatarSource,
+} from '../avatarCropImage';
+
+function makeSource(width: number, height: number): AvatarSource {
+ return {
+ bitmap: { width, height, close: vi.fn() } as unknown as ImageBitmap,
+ size: { width, height },
+ };
+}
+
+const DATA_URL = 'data:image/jpeg;base64,AAAA';
+
+/**
+ * 替身:`<img>` 只报告(已转正的)尺寸、不解码像素;createImageBitmap 按传入的
+ * resize 选项产出对应尺寸的位图并记录调用,用来断言解码次数与目标尺寸。
+ */
+function stubDecoder(natural: { width: number; height: number } | 'error') {
+ URL.createObjectURL = vi.fn(() => 'blob:avatar-probe');
+ URL.revokeObjectURL = vi.fn();
+ class FakeImage {
+ naturalWidth = natural === 'error' ? 0 : natural.width;
+ naturalHeight = natural === 'error' ? 0 : natural.height;
+ onload: (() => void) | null = null;
+ onerror: (() => void) | null = null;
+ set src(_value: string) {
+ queueMicrotask(() => (natural === 'error' ? this.onerror?.() : this.onload?.()));
+ }
+ }
+ vi.stubGlobal('Image', FakeImage);
+ const created: ImageBitmap[] = [];
+ const createImageBitmapMock = vi.fn(async (_source: unknown, options?: ImageBitmapOptions) => {
+ const size = natural === 'error' ? { width: 0, height: 0 } : natural;
+ const bitmap = {
+ width: options?.resizeWidth ?? size.width,
+ height: options?.resizeHeight ?? size.height,
+ close: vi.fn(),
+ } as unknown as ImageBitmap;
+ created.push(bitmap);
+ return bitmap;
+ });
+ vi.stubGlobal('createImageBitmap', createImageBitmapMock);
+ return { createImageBitmapMock, created };
+}
+
+/** 记录 drawImage 调用的最小 2D context 替身,getImageData 返回指定 alpha。 */
+function stubCanvas(alpha: number) {
+ const drawImage = vi.fn();
+ const getImageData = vi.fn((_x: number, _y: number, w: number, h: number) => {
+ const data = new Uint8ClampedArray(w * h * 4).fill(255);
+ data[3] = alpha;
+ return { data };
+ });
+ const ctx = {
+ drawImage,
+ getImageData,
+ clearRect: vi.fn(),
+ } as unknown as CanvasRenderingContext2D;
+ vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockImplementation(
+ () => ctx as unknown as RenderingContext,
+ );
+ const toBlob = vi.spyOn(HTMLCanvasElement.prototype, 'toBlob').mockImplementation(function (
+ this: HTMLCanvasElement,
+ callback,
+ type,
+ ) {
+ callback(new Blob([new Uint8Array([1, 2, 3])], { type }));
+ });
+ return { ctx, drawImage, getImageData, toBlob };
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+});
+
+describe('avatarCropImage', () => {
+ it('超大源图按长边等比缩到上限,小图原样保留', () => {
+ expect(fitAvatarSourceSize({ width: 8000, height: 6000 })).toEqual({
+ width: AVATAR_SOURCE_MAX_EDGE,
+ height: 3072,
+ });
+ expect(fitAvatarSourceSize({ width: 3000, height: 9000 })).toEqual({
+ width: 1365,
+ height: AVATAR_SOURCE_MAX_EDGE,
+ });
+ const small = { width: 640, height: 480 };
+ expect(fitAvatarSourceSize(small)).toBe(small);
+ });
+
+ it('透明判定:任一像素 alpha < 255 即视为透明', () => {
+ expect(hasTransparentPixel(new Uint8ClampedArray([1, 2, 3, 255, 4, 5, 6, 255]))).toBe(false);
+ expect(hasTransparentPixel(new Uint8ClampedArray([1, 2, 3, 255, 4, 5, 6, 254]))).toBe(true);
+ });
+
+ it('导出格式只看导出像素:有透明像素才导出 PNG,与文件扩展名无关', () => {
+ expect(avatarExportMime(new Uint8ClampedArray([0, 0, 0, 255]))).toBe('image/jpeg');
+ expect(avatarExportMime(new Uint8ClampedArray([0, 0, 0, 0]))).toBe('image/png');
+ });
+
+ it('超大原片只解码一次,直接解到长边上限(不先留一张全尺寸位图)', async () => {
+ const { createImageBitmapMock, created } = stubDecoder({ width: 8000, height: 6000 });
+ const source = await loadAvatarSource(DATA_URL);
+ expect(createImageBitmapMock).toHaveBeenCalledTimes(1);
+ expect(createImageBitmapMock.mock.calls[0]?.[1]).toEqual({
+ imageOrientation: 'from-image',
+ resizeWidth: AVATAR_SOURCE_MAX_EDGE,
+ resizeHeight: 3072,
+ resizeQuality: 'high',
+ });
+ expect(source.size).toEqual({ width: AVATAR_SOURCE_MAX_EDGE, height: 3072 });
+ expect(source.bitmap).toBe(created[0]);
+ expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:avatar-probe');
+ });
+
+ it('普通尺寸按原尺寸解码并转正;无法解码或零尺寸时不创建位图', async () => {
+ const small = stubDecoder({ width: 1200, height: 2000 });
+ const source = await loadAvatarSource(DATA_URL);
+ expect(small.createImageBitmapMock.mock.calls[0]?.[1]).toEqual({
+ imageOrientation: 'from-image',
+ });
+ expect(source.size).toEqual({ width: 1200, height: 2000 });
+
+ const broken = stubDecoder('error');
+ await expect(loadAvatarSource(DATA_URL)).rejects.toThrow();
+ expect(broken.createImageBitmapMock).not.toHaveBeenCalled();
+
+ const empty = stubDecoder({ width: 0, height: 0 });
+ await expect(loadAvatarSource(DATA_URL)).rejects.toThrow();
+ expect(empty.createImageBitmapMock).not.toHaveBeenCalled();
+ });
+
+ it('导出把取景源矩形原样画进正方形输出画布(与编辑台同一映射,无二次裁剪 / 拉伸)', async () => {
+ const { drawImage, getImageData, toBlob } = stubCanvas(255);
+ const source = makeSource(4000, 3000);
+ const crop: AvatarCrop = { cx: 1700.5, cy: 1400.25, side: 1200 };
+
+ const result = await exportAvatarCrop(source, crop);
+
+ const out = avatarOutputSize(crop);
+ const { sx, sy, sw, sh } = avatarCropDrawRect(crop);
+ expect(drawImage).toHaveBeenCalledTimes(1);
+ expect(drawImage).toHaveBeenCalledWith(source.bitmap, sx, sy, sw, sh, 0, 0, out, out);
+ // 透明判定读的是导出画布本身。
+ expect(getImageData).toHaveBeenCalledWith(0, 0, out, out);
+ expect(toBlob).toHaveBeenCalledWith(expect.any(Function), 'image/jpeg', 0.92);
+ expect(result.mimeType).toBe('image/jpeg');
+ expect(Array.from(result.bytes)).toEqual([1, 2, 3]);
+ });
+
+ it('导出画布有透明像素时导出 PNG,保留透明(含扩展名写错的透明图)', async () => {
+ const { toBlob } = stubCanvas(0);
+ const result = await exportAvatarCrop(makeSource(800, 800), {
+ cx: 400,
+ cy: 400,
+ side: 800,
+ });
+ expect(result.mimeType).toBe('image/png');
+ expect(toBlob).toHaveBeenCalledWith(expect.any(Function), 'image/png', undefined);
+ });
+});
diff --git a/apps/desktop/src/renderer/components/settings/avatarCropGeometry.ts b/apps/desktop/src/renderer/components/settings/avatarCropGeometry.ts
new file mode 100644
index 0000000000..846326985a
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/avatarCropGeometry.ts
@@ -0,0 +1,164 @@
+/**
+ * avatarCropGeometry — 头像取景的纯几何(无 DOM、无副作用,可直接单测)。
+ *
+ * 唯一的状态是**源图像素坐标系**里的一块正方形 `AvatarCrop`(中心 + 边长)。
+ * 编辑台画布、确认后的小预览和最终导出都从这同一块矩形推导:编辑台用
+ * `avatarStageTransform` 把整张图按它摆放,导出用 `avatarCropDrawRect` 把它
+ * 原样画进输出画布——两条路径共享同一组数,所以「看到的圈内」与「上传的像素」
+ * 不可能各算各的、出现二次裁剪或拉伸。
+ *
+ * 不变量(`clampAvatarCrop` 保证):
+ * - 正方形完整落在源图内 → 平移 / 缩放都不会露出图外空白,导出不含透明边;
+ * - 边长 ∈ [短边 / 最大倍率, 短边] → zoom 1 = 恰好铺满(cover),不允许缩到露底。
+ */
+
+/** 已按 EXIF 方向转正后的源图尺寸(px)。 */
+export interface AvatarImageSize {
+ width: number;
+ height: number;
+}
+
+/** 源图坐标系里的正方形取景:中心点与边长(px,可为小数)。 */
+export interface AvatarCrop {
+ cx: number;
+ cy: number;
+ side: number;
+}
+
+/** 相对取景圆心的视图坐标(CSS px),用于以光标 / 双指中点为焦点缩放。 */
+export interface AvatarViewPoint {
+ x: number;
+ y: number;
+}
+
+/** 最大放大倍率(相对铺满)。4x 时 4000px 照片的取景仍有 ~750px,高于输出边长。 */
+export const AVATAR_CROP_MAX_ZOOM = 4;
+/** 按钮 / 快捷键每步缩放倍率,与图片 lightbox 的步进一致。 */
+export const AVATAR_CROP_ZOOM_STEP = 1.2;
+/** 导出边长上限:足够 Retina 下的大头像展示,又远低于服务端 5MB 上限。 */
+export const AVATAR_OUTPUT_MAX_PX = 512;
+/** 导出边长下限:极小的源图也放大到可用清晰度,避免上传 20px 头像。 */
+export const AVATAR_OUTPUT_MIN_PX = 128;
+
+function clamp(value: number, min: number, max: number) {
+ return Math.min(max, Math.max(min, value));
+}
+
+function shortSide(size: AvatarImageSize) {
+ return Math.min(size.width, size.height);
+}
+
+/** 当前放大倍率:1 = 铺满,`AVATAR_CROP_MAX_ZOOM` = 最大。 */
+export function avatarCropZoom(crop: AvatarCrop, size: AvatarImageSize) {
+ return shortSide(size) / crop.side;
+}
+
+/** 把取景收回合法范围(见文件头不变量)。 */
+export function clampAvatarCrop(crop: AvatarCrop, size: AvatarImageSize): AvatarCrop {
+ const min = shortSide(size);
+ const side = clamp(crop.side, min / AVATAR_CROP_MAX_ZOOM, min);
+ const half = side / 2;
+ return {
+ side,
+ cx: clamp(crop.cx, half, size.width - half),
+ cy: clamp(crop.cy, half, size.height - half),
+ };
+}
+
+/**
+ * 初始构图:铺满并居中。横图左右留出可平移余量,竖图上下留出,方图正好填满。
+ * 不做「人脸偏上」之类的猜测——可预测比偶尔猜中更重要,用户一拖即可修正。
+ */
+export function initialAvatarCrop(size: AvatarImageSize): AvatarCrop {
+ return { cx: size.width / 2, cy: size.height / 2, side: shortSide(size) };
+}
+
+/**
+ * 跟手平移:视图里拖动 (dx, dy) 个 CSS px,图片跟着手走同样的视觉距离。
+ * `viewSide` 是取景圆在屏幕上的直径。越界部分被夹住(手继续走、图停在边上)。
+ */
+export function panAvatarCrop(
+ crop: AvatarCrop,
+ size: AvatarImageSize,
+ dx: number,
+ dy: number,
+ viewSide: number,
+): AvatarCrop {
+ if (!(viewSide > 0)) return crop; // stage 尚未量出尺寸
+ const scale = viewSide / crop.side;
+ return clampAvatarCrop({ ...crop, cx: crop.cx - dx / scale, cy: crop.cy - dy / scale }, size);
+}
+
+/**
+ * 缩放到 `zoom`(会被夹到 [1, 最大倍率]),并保持 `focal` 下方的那个源图点在屏幕上不动;
+ * 不给 focal 时以取景圆心为焦点(滑杆 / 按钮 / 键盘)。缩小时若焦点附近已贴边,
+ * clamp 会把中心推回图内——这是「不露空白」优先于「焦点绝对不动」的有意取舍。
+ */
+export function zoomAvatarCrop(
+ crop: AvatarCrop,
+ size: AvatarImageSize,
+ zoom: number,
+ viewSide: number,
+ focal: AvatarViewPoint = { x: 0, y: 0 },
+): AvatarCrop {
+ if (!(viewSide > 0)) return crop; // stage 尚未量出尺寸
+ const nextZoom = clamp(zoom, 1, AVATAR_CROP_MAX_ZOOM);
+ const scale = viewSide / crop.side;
+ const sourceX = crop.cx + focal.x / scale;
+ const sourceY = crop.cy + focal.y / scale;
+ const side = shortSide(size) / nextZoom;
+ const nextScale = viewSide / side;
+ return clampAvatarCrop(
+ { side, cx: sourceX - focal.x / nextScale, cy: sourceY - focal.y / nextScale },
+ size,
+ );
+}
+
+/**
+ * 编辑台画布上整张源图的摆放:先按 `scale` 缩放,再把左上角放到 (x, y)(stage CSS px)。
+ * 取景圆固定在 stage 正中,直径 `viewSide`。
+ */
+export function avatarStageTransform(
+ crop: AvatarCrop,
+ viewSide: number,
+ stageWidth: number,
+ stageHeight: number,
+) {
+ const scale = viewSide / crop.side;
+ return {
+ scale,
+ x: stageWidth / 2 - crop.cx * scale,
+ y: stageHeight / 2 - crop.cy * scale,
+ };
+}
+
+/** 导出边长:按取景实际覆盖的源像素取整,夹在 [下限, 上限],不做无意义的放大。 */
+export function avatarOutputSize(crop: AvatarCrop) {
+ return clamp(Math.round(crop.side), AVATAR_OUTPUT_MIN_PX, AVATAR_OUTPUT_MAX_PX);
+}
+
+/** 导出时 drawImage 的源矩形(源图 px)。编辑台、预览、导出的唯一共享映射。 */
+export function avatarCropDrawRect(crop: AvatarCrop) {
+ return {
+ sx: crop.cx - crop.side / 2,
+ sy: crop.cy - crop.side / 2,
+ sw: crop.side,
+ sh: crop.side,
+ };
+}
+
+/**
+ * 滑杆值 ⇄ 倍率:对数映射,让滑杆每一格带来相同的「视觉放大感」
+ * (线性映射会让 1x→1.5x 挤在最左边一小段,手感前紧后松)。
+ */
+export const AVATAR_ZOOM_SLIDER_MAX = 100;
+
+export function avatarZoomToSlider(zoom: number) {
+ const ratio = Math.log(clamp(zoom, 1, AVATAR_CROP_MAX_ZOOM)) / Math.log(AVATAR_CROP_MAX_ZOOM);
+ return ratio * AVATAR_ZOOM_SLIDER_MAX;
+}
+
+export function avatarSliderToZoom(value: number) {
+ const ratio = clamp(value, 0, AVATAR_ZOOM_SLIDER_MAX) / AVATAR_ZOOM_SLIDER_MAX;
+ return AVATAR_CROP_MAX_ZOOM ** ratio;
+}
diff --git a/apps/desktop/src/renderer/components/settings/avatarCropImage.ts b/apps/desktop/src/renderer/components/settings/avatarCropImage.ts
new file mode 100644
index 0000000000..bc53651168
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/avatarCropImage.ts
@@ -0,0 +1,159 @@
+/**
+ * avatarCropImage — 头像编辑的解码与导出(依赖 Canvas / ImageBitmap,几何见 avatarCropGeometry)。
+ *
+ * 色彩约定(与头像 HDR→SDR 转换的整合点):
+ * - 源图只解码一次成 ImageBitmap(按 EXIF 方向转正、超大图预缩到 4096px 长边);
+ * - 编辑台与导出都把它画进**默认的 sRGB 8-bit 2D 画布**,两者走同一条绘制路径,
+ * 所以编辑台显示的像素与导出的像素一致;
+ * - 导出经 canvas 重新编码成 PNG / JPEG,输出是 8-bit sRGB,不写入 gain map 等
+ * HDR 附加数据。
+ * 这里**不做** HDR→SDR 色调映射:HDR 源画进 sRGB 画布时如何压缩高光由 Chromium
+ * 决定(可能只是裁切),画面观感是否合格不由本模块保证。正确的色调映射由上游
+ * 选图转换负责;转换后的 SDR 源交给 loadAvatarSource 即可,本模块无需改动。
+ */
+
+import {
+ avatarCropDrawRect,
+ avatarOutputSize,
+ type AvatarCrop,
+ type AvatarImageSize,
+} from './avatarCropGeometry';
+
+/** 解码后的编辑源:转正、限尺寸后的位图 + 尺寸。 */
+export interface AvatarSource {
+ bitmap: ImageBitmap;
+ size: AvatarImageSize;
+}
+
+/** 导出结果:即将上传的字节本身,预览也直接用它,保证所见即所传。 */
+export interface AvatarExport {
+ blob: Blob;
+ bytes: Uint8Array;
+ mimeType: AvatarExportMime;
+}
+
+export type AvatarExportMime = 'image/png' | 'image/jpeg';
+
+/** 解码后长边上限:4x 放大时仍有充足源像素,同时把 48MP 照片的显存压到可控范围。 */
+export const AVATAR_SOURCE_MAX_EDGE = 4096;
+const JPEG_QUALITY = 0.92;
+
+function dataUrlToBlob(dataUrl: string): Blob {
+ const comma = dataUrl.indexOf(',');
+ const header = dataUrl.slice(0, comma);
+ const mime = /^data:([^;,]+)/.exec(header)?.[1] ?? 'application/octet-stream';
+ const binary = atob(dataUrl.slice(comma + 1));
+ const bytes = new Uint8Array(binary.length);
+ for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+ return new Blob([bytes], { type: mime });
+}
+
+/** 按长边上限算缩放后的尺寸(不放大)。 */
+export function fitAvatarSourceSize(size: AvatarImageSize, maxEdge = AVATAR_SOURCE_MAX_EDGE) {
+ const longEdge = Math.max(size.width, size.height);
+ if (longEdge <= maxEdge) return size;
+ const ratio = maxEdge / longEdge;
+ return {
+ width: Math.max(1, Math.round(size.width * ratio)),
+ height: Math.max(1, Math.round(size.height * ratio)),
+ };
+}
+
+/**
+ * 读出图片按 EXIF 转正后的尺寸,不解码像素:`<img>` 加载完成只解析文件头,
+ * 像素解码要等绘制或 decode() 才发生;naturalWidth/Height 已计入 EXIF 方向。
+ */
+function probeAvatarImageSize(blob: Blob): Promise<AvatarImageSize> {
+ const url = URL.createObjectURL(blob);
+ return new Promise<AvatarImageSize>((resolve, reject) => {
+ const img = new Image();
+ img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+ img.onerror = () => reject(new Error('avatar image is not decodable'));
+ img.src = url;
+ }).finally(() => URL.revokeObjectURL(url));
+}
+
+/**
+ * 解码选中的图片。失败(损坏、格式不符)时抛错,由调用方提示并留在原界面。
+ * 解码在切到编辑台**之前**完成,编辑台第一帧就有图,不出现空白帧。
+ *
+ * 先探尺寸、再**一次** createImageBitmap 直接解码到目标尺寸:超大原片不会先留一张
+ * 全尺寸位图再缩出第二张,失败路径也没有需要额外释放的中间位图。
+ */
+export async function loadAvatarSource(dataUrl: string): Promise<AvatarSource> {
+ const blob = dataUrlToBlob(dataUrl);
+ const natural = await probeAvatarImageSize(blob);
+ if (natural.width === 0 || natural.height === 0) {
+ throw new Error('avatar image has no pixels');
+ }
+ const fitted = fitAvatarSourceSize(natural);
+ const bitmap = await createImageBitmap(
+ blob,
+ fitted === natural
+ ? { imageOrientation: 'from-image' }
+ : {
+ imageOrientation: 'from-image',
+ resizeWidth: fitted.width,
+ resizeHeight: fitted.height,
+ resizeQuality: 'high',
+ },
+ );
+ return { bitmap, size: { width: bitmap.width, height: bitmap.height } };
+}
+
+/** 把取景画进一块 outSize × outSize 的目标区域。编辑后预览与导出共用。 */
+export function drawAvatarCrop(
+ ctx: CanvasRenderingContext2D,
+ source: AvatarSource,
+ crop: AvatarCrop,
+ outSize: number,
+) {
+ const { sx, sy, sw, sh } = avatarCropDrawRect(crop);
+ ctx.imageSmoothingEnabled = true;
+ ctx.imageSmoothingQuality = 'high';
+ ctx.clearRect(0, 0, outSize, outSize);
+ ctx.drawImage(source.bitmap, sx, sy, sw, sh, 0, 0, outSize, outSize);
+}
+
+/** RGBA 像素里是否有任何非完全不透明的点。 */
+export function hasTransparentPixel(rgba: Uint8ClampedArray) {
+ for (let i = 3; i < rgba.length; i += 4) {
+ if (rgba[i] !== 255) return true;
+ }
+ return false;
+}
+
+/**
+ * 透明图沿用既有约定(保留透明,导出 PNG);其余导出 JPEG,体积更小。
+ * 按导出画布的实际像素判断,不看文件扩展名——改了扩展名的透明 PNG 也保留透明。
+ */
+export function avatarExportMime(rgba: Uint8ClampedArray): AvatarExportMime {
+ return hasTransparentPixel(rgba) ? 'image/png' : 'image/jpeg';
+}
+
+function canvasToBlob(canvas: HTMLCanvasElement, mime: AvatarExportMime): Promise<Blob> {
+ return new Promise((resolve, reject) => {
+ canvas.toBlob(
+ (blob) => (blob ? resolve(blob) : reject(new Error('avatar encode failed'))),
+ mime,
+ mime === 'image/jpeg' ? JPEG_QUALITY : undefined,
+ );
+ });
+}
+
+/** 按当前取景导出最终上传的头像字节。 */
+export async function exportAvatarCrop(
+ source: AvatarSource,
+ crop: AvatarCrop,
+): Promise<AvatarExport> {
+ const outSize = avatarOutputSize(crop);
+ const canvas = document.createElement('canvas');
+ canvas.width = outSize;
+ canvas.height = outSize;
+ const ctx = canvas.getContext('2d', { colorSpace: 'srgb' });
+ if (!ctx) throw new Error('avatar canvas unavailable');
+ drawAvatarCrop(ctx, source, crop, outSize);
+ const mimeType = avatarExportMime(ctx.getImageData(0, 0, outSize, outSize).data);
+ const blob = await canvasToBlob(canvas, mimeType);
+ return { blob, bytes: new Uint8Array(await blob.arrayBuffer()), mimeType };
+}
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index a8d4bf9061..cf013c7eec 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -1868,11 +1868,23 @@
"nameHint": "Leave empty to keep the current name",
"changeAvatar": "Change avatar",
"resetAvatar": "Restore default avatar",
+ "adjustAvatar": "Adjust avatar",
"save": "Save Profile",
"cancel": "Cancel",
"syncHint": "Your name and avatar are saved to your account and synced across your devices.",
- "avatarInvalid": "Please choose a PNG / JPG / WebP image under 5MB",
- "saveFailed": "Failed to save, please try again"
+ "avatarInvalid": "Please choose a PNG / JPG / WebP image under 20MB",
+ "saveFailed": "Failed to save, please try again",
+ "crop": {
+ "title": "Adjust avatar",
+ "description": "Drag to reposition. Scroll or pinch to zoom.",
+ "done": "Apply Avatar Crop",
+ "stageLabel": "Avatar framing area. Use the arrow keys to move and plus or minus to zoom.",
+ "zoomLabel": "Zoom",
+ "zoomValue": "{{percent}}%",
+ "zoomIn": "Zoom in",
+ "zoomOut": "Zoom out",
+ "exportFailed": "Couldn't export the adjusted avatar"
+ }
}
},
"help": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index 95a1a18756..1fdf1121f0 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -1845,11 +1845,23 @@
"nameHint": "空欄にすると現在の名前を維持します",
"changeAvatar": "アバターを変更",
"resetAvatar": "デフォルトのアバターに戻す",
+ "adjustAvatar": "アバターを調整",
"save": "プロフィールを保存",
"cancel": "キャンセル",
"syncHint": "名前とアバターはアカウントに保存され、すべてのデバイスに同期されます。",
- "avatarInvalid": "5MB 以下の PNG / JPG / WebP 画像を選択してください",
- "saveFailed": "保存に失敗しました。もう一度お試しください"
+ "avatarInvalid": "20MB 以下の PNG / JPG / WebP 画像を選択してください",
+ "saveFailed": "保存に失敗しました。もう一度お試しください",
+ "crop": {
+ "title": "アバターを調整",
+ "description": "ドラッグで位置を調整し、スクロールまたはピンチで拡大・縮小します",
+ "done": "アバターの調整を完了",
+ "stageLabel": "アバターの表示範囲。矢印キーで移動し、プラスまたはマイナスキーで拡大・縮小します",
+ "zoomLabel": "ズーム",
+ "zoomValue": "{{percent}}%",
+ "zoomIn": "拡大",
+ "zoomOut": "縮小",
+ "exportFailed": "調整したアバターを書き出せませんでした"
+ }
}
},
"help": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index b1dd02f6bf..200640e044 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -1845,11 +1845,23 @@
"nameHint": "비워 두면 현재 이름이 유지됩니다",
"changeAvatar": "아바타 변경",
"resetAvatar": "기본 아바타로 복원",
+ "adjustAvatar": "아바타 조정",
"save": "프로필 저장",
"cancel": "취소",
"syncHint": "이름과 아바타는 계정에 저장되고 모든 기기에 동기화됩니다.",
- "avatarInvalid": "5MB 이하의 PNG / JPG / WebP 이미지를 선택해 주세요",
- "saveFailed": "저장에 실패했습니다. 다시 시도해 주세요"
+ "avatarInvalid": "20MB 이하의 PNG / JPG / WebP 이미지를 선택해 주세요",
+ "saveFailed": "저장에 실패했습니다. 다시 시도해 주세요",
+ "crop": {
+ "title": "아바타 조정",
+ "description": "드래그해 위치를 조정하고, 스크롤하거나 핀치해 확대·축소하세요",
+ "done": "아바타 조정 완료",
+ "stageLabel": "아바타 표시 영역. 화살표 키로 이동하고 더하기 또는 빼기 키로 확대·축소합니다",
+ "zoomLabel": "확대/축소",
+ "zoomValue": "{{percent}}%",
+ "zoomIn": "확대",
+ "zoomOut": "축소",
+ "exportFailed": "조정한 아바타를 내보내지 못했습니다"
+ }
}
},
"help": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index 60cc217afe..62f35a2e73 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -1845,11 +1845,23 @@
"nameHint": "留空则保持当前名字",
"changeAvatar": "更换头像",
"resetAvatar": "恢复默认头像",
+ "adjustAvatar": "调整头像",
"save": "保存资料",
"cancel": "取消",
"syncHint": "名字和头像会保存到账号,并同步到你的所有设备",
- "avatarInvalid": "请选择 5MB 以内的 PNG / JPG / WebP 图片",
- "saveFailed": "保存失败,请重试"
+ "avatarInvalid": "请选择 20MB 以内的 PNG / JPG / WebP 图片",
+ "saveFailed": "保存失败,请重试",
+ "crop": {
+ "title": "调整头像",
+ "description": "拖动调整位置,滚动或双指缩放",
+ "done": "完成头像调整",
+ "stageLabel": "头像取景区域:用方向键移动,用加号或减号缩放",
+ "zoomLabel": "缩放",
+ "zoomValue": "{{percent}}%",
+ "zoomIn": "放大",
+ "zoomOut": "缩小",
+ "exportFailed": "未能导出调整后的头像"
+ }
}
},
"help": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index c4ad7c08bc..065c56fbc9 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -1845,11 +1845,23 @@
"nameHint": "留空則保持當前名字",
"changeAvatar": "更換頭像",
"resetAvatar": "恢復預設頭像",
+ "adjustAvatar": "調整頭像",
"save": "儲存資料",
"cancel": "取消",
"syncHint": "名字和頭像會儲存到帳號,並同步到你的所有裝置",
- "avatarInvalid": "請選擇 5MB 以內的 PNG / JPG / WebP 圖片",
- "saveFailed": "儲存失敗,請重試"
+ "avatarInvalid": "請選擇 20MB 以內的 PNG / JPG / WebP 圖片",
+ "saveFailed": "儲存失敗,請重試",
+ "crop": {
+ "title": "調整頭像",
+ "description": "拖曳調整位置,捲動或雙指縮放",
+ "done": "完成頭像調整",
+ "stageLabel": "頭像取景區域:用方向鍵移動,用加號或減號縮放",
+ "zoomLabel": "縮放",
+ "zoomValue": "{{percent}}%",
+ "zoomIn": "放大",
+ "zoomOut": "縮小",
+ "exportFailed": "未能匯出調整後的頭像"
+ }
}
},
"help": {
diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.ts
index dfabcb7065..aa37ae49c3 100644
--- a/apps/desktop/src/renderer/vite-env.d.ts
+++ b/apps/desktop/src/renderer/vite-env.d.ts
@@ -2179,12 +2179,14 @@ interface ElectronAPI {
}>;
profileChooseAvatar: () => Promise<{
canceled: boolean;
- filePath?: string;
previewDataUrl?: string;
}>;
profileUpdate: (params: {
name: string | null;
- avatar: { type: 'keep' } | { type: 'set'; filePath: string } | { type: 'reset' };
+ avatar:
+ | { type: 'keep' }
+ | { type: 'set'; data: Uint8Array; mimeType: 'image/png' | 'image/jpeg' }
+ | { type: 'reset' };
}) => Promise<{ ok: true }>;
// Slack 官方 MCP(slackOfficial)已于 2026-07-15 退役(能力迁入内置意识 cindy-slack);
diff --git a/docs/design-rules/design-inventory.md b/docs/design-rules/design-inventory.md
index ce6c526897..f32dada2be 100644
--- a/docs/design-rules/design-inventory.md
+++ b/docs/design-rules/design-inventory.md
@@ -38,7 +38,7 @@
| `desktop.overlay.toast` | desktop | Toast | App 常驻 ToastContainer(用户可见出口,不展开业务逻辑) | Toast, ToastContainer | apps/desktop/src/renderer/components/ui/toast/Toast.tsx, apps/desktop/src/renderer/components/ui/toast/ToastContainer.tsx, apps/desktop/src/renderer/components/ui/toast/index.ts | 5 | 4 | 3 |
| `desktop.plugins.app-main` | desktop | 插件主视图 | hash `/apps/:ghostId`(GhostMainViewFeatureLayout) | GhostMainViewFeatureLayout, GhostMainViewHost | apps/desktop/src/renderer/features/plugin/GhostMainViewFeatureLayout.tsx, apps/desktop/src/renderer/features/plugin/GhostMainViewHost.tsx | 0 | 0 | 0 |
| `desktop.plugins.installed` | desktop | 已装插件 | hash `/plugins`(GhostPluginPage) | AddMarketplaceDialog, GhostPluginDetailView, GhostPluginPage, MarketPluginDetailView, MyPublishesSection, PluginManagementLayout, PluginScopePicker, UpdateAllDialog | apps/desktop/src/renderer/features/plugin/AddMarketplaceDialog.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginDetailView.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginPage.tsx, apps/desktop/src/renderer/features/plugin/MarketPluginDetailView.tsx, apps/desktop/src/renderer/features/plugin/MyPublishesSection.tsx, apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/plugin/PluginScopePicker.tsx, apps/desktop/src/renderer/features/plugin/UpdateAllDialog.tsx, apps/desktop/src/renderer/features/plugin/plugin-motion.css | 28 | 0 | 49 |
-| `desktop.settings` | desktop | 设置 | hash `/settings`(SettingsView;tab 含 general / personalization / providers / billing / usage / voice-input / im-bot / shortcuts / agent-island / import / remote-control / ghosts / builtin-tools / computer-use / help / about) | SettingsView | apps/desktop/src/renderer/components/settings/AboutSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AboutSection.tsx, apps/desktop/src/renderer/components/settings/AccountDeletionSection.tsx, apps/desktop/src/renderer/components/settings/AddProviderWizard.tsx, apps/desktop/src/renderer/components/settings/AgentIslandSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AgentIslandSection.tsx, apps/desktop/src/renderer/components/settings/AgentResourceSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AgentResourceSection.tsx, apps/desktop/src/renderer/components/settings/AppearanceSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AppearanceSection.tsx, apps/desktop/src/renderer/components/settings/AuxiliaryModelSection.tsx, apps/desktop/src/renderer/components/settings/BetaChannelCell.tsx, apps/desktop/src/renderer/components/settings/BillingSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx, apps/desktop/src/renderer/components/settings/BrowserRealProfileSubsection.tsx, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.tsx, apps/desktop/src/renderer/components/settings/ChatEmbeddingCell.tsx, apps/desktop/src/renderer/components/settings/ChipMetricsSection.tsx, apps/desktop/src/renderer/components/settings/CindyMakeSection.settings-search.ts, apps/desktop/src/renderer/components/settings/CindyMakeSection.tsx, apps/desktop/src/renderer/components/settings/CollaborationSection.settings-search.ts, apps/desktop/src/renderer/components/settings/CollaborationSection.tsx, apps/desktop/src/renderer/components/settings/CompactionSection.tsx, apps/desktop/src/renderer/components/settings/ComposerSendShortcutSection.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionRow.tsx, apps/desktop/src/renderer/components/settings/ComputerUseSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx, apps/desktop/src/renderer/components/settings/CustomProviderRuntimeFillOverlay.tsx, apps/desktop/src/renderer/components/settings/DefaultOverrideControls.tsx, apps/desktop/src/renderer/components/settings/DialogueDirectorySection.tsx, apps/desktop/src/renderer/components/settings/DingTalkBotSection.tsx, apps/desktop/src/renderer/components/settings/DiscordBotSection.tsx, apps/desktop/src/renderer/components/settings/DownloadMeter.tsx, apps/desktop/src/renderer/components/settings/ExperimentalSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotNotificationSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotSection.tsx, apps/desktop/src/renderer/components/settings/FontFamilyPicker.tsx, apps/desktop/src/renderer/components/settings/GeneralSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/GenericGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/GitSafetySection.settings-search.ts, apps/desktop/src/renderer/components/settings/GitSafetySection.tsx, apps/desktop/src/renderer/components/settings/HarnessVersionMenuRow.tsx, apps/desktop/src/renderer/components/settings/HelpAssistantPanel.tsx, apps/desktop/src/renderer/components/settings/HelpSection.settings-search.ts, apps/desktop/src/renderer/components/settings/HelpSection.tsx, apps/desktop/src/renderer/components/settings/HelpThreadView.tsx, apps/desktop/src/renderer/components/settings/HookConnectionsSection.tsx, apps/desktop/src/renderer/components/settings/HookWorkspacePrefsEditor.tsx, apps/desktop/src/renderer/components/settings/ImBotSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ImBotSection.tsx, apps/desktop/src/renderer/components/settings/ImChannelSettingsCard.tsx, apps/desktop/src/renderer/components/settings/ImDefaultSettingsSection.tsx, apps/desktop/src/renderer/components/settings/ImLifecycleAnnouncementSection.tsx, apps/desktop/src/renderer/components/settings/InputDeviceConnectionStatus.tsx, apps/desktop/src/renderer/components/settings/JoyConGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx, apps/desktop/src/renderer/components/settings/LanguageSection.tsx, apps/desktop/src/renderer/components/settings/LayoutResetControl.tsx, apps/desktop/src/renderer/components/settings/LinkOpenSection.tsx, apps/desktop/src/renderer/components/settings/LlamaCppCandidates.tsx, apps/desktop/src/renderer/components/settings/LlamaCppProviderDetail.tsx, apps/desktop/src/renderer/components/settings/LocalModelDownloadUI.tsx, apps/desktop/src/renderer/components/settings/LocalOllamaInstall.tsx, apps/desktop/src/renderer/components/settings/LocalPackagingTag.tsx, apps/desktop/src/renderer/components/settings/LogoutSection.tsx, apps/desktop/src/renderer/components/settings/LspBetaCell.tsx, apps/desktop/src/renderer/components/settings/McpServerDialog.tsx, apps/desktop/src/renderer/components/settings/McpServersSection.tsx, apps/desktop/src/renderer/components/settings/MemorySection.tsx, apps/desktop/src/renderer/components/settings/MessageNavRailCell.tsx, apps/desktop/src/renderer/components/settings/ModelAdvancedDrawer.tsx, apps/desktop/src/renderer/components/settings/ModelPriceOverrideDialog.tsx, apps/desktop/src/renderer/components/settings/MyDevicesPanel.tsx, apps/desktop/src/renderer/components/settings/NotificationSection.settings-search.ts, apps/desktop/src/renderer/components/settings/NotificationSection.tsx, apps/desktop/src/renderer/components/settings/OAuthDeviceCodeCard.tsx, apps/desktop/src/renderer/components/settings/OllamaProviderDetail.tsx, apps/desktop/src/renderer/components/settings/OwnRemoteProviders.tsx, apps/desktop/src/renderer/components/settings/PersonalizationDetails.settings-search.ts, apps/desktop/src/renderer/components/settings/PersonalizationSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/PiKernelVersionRow.tsx, apps/desktop/src/renderer/components/settings/PiPackagesSection.tsx, apps/desktop/src/renderer/components/settings/PlayStationGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderImportDialog.tsx, apps/desktop/src/renderer/components/settings/ProvidersSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ProvidersSection.tsx, apps/desktop/src/renderer/components/settings/ReadOnlyProviderModels.tsx, apps/desktop/src/renderer/components/settings/RemoteControlSection.settings-search.ts, apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopPermissions.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopSetting.tsx, apps/desktop/src/renderer/components/settings/RemoteHostDetail.tsx, apps/desktop/src/renderer/components/settings/RemoteSection.tsx, apps/desktop/src/renderer/components/settings/SessionImportSection.settings-search.ts, apps/desktop/src/renderer/components/settings/SessionImportSection.tsx, apps/desktop/src/renderer/components/settings/SessionRuntimeFallbackCell.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.settings-search.ts, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.tsx, apps/desktop/src/renderer/components/settings/SettingsSearchBox.tsx, apps/desktop/src/renderer/components/settings/SettingsSearchNavigation.ts, apps/desktop/src/renderer/components/settings/SettingsSidebarNav.tsx, apps/desktop/src/renderer/components/settings/SettingsTextInput.tsx, apps/desktop/src/renderer/components/settings/SettingsView.tsx, apps/desktop/src/renderer/components/settings/SharedTasks.settings-search.ts, apps/desktop/src/renderer/components/settings/SilentEncryptedRetryCell.tsx, apps/desktop/src/renderer/components/settings/SshKeySetupDialog.tsx, apps/desktop/src/renderer/components/settings/StorageManagementCard.settings-search.ts, apps/desktop/src/renderer/components/settings/StorageManagementCard.tsx, apps/desktop/src/renderer/components/settings/StreamFadeSection.tsx, apps/desktop/src/renderer/components/settings/SubagentModelSection.settings-search.ts, apps/desktop/src/renderer/components/settings/SubagentModelSection.tsx, apps/desktop/src/renderer/components/settings/SwitchProGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/TelegramBehaviorSettings.tsx, apps/desktop/src/renderer/components/settings/TelegramBotSection.tsx, apps/desktop/src/renderer/components/settings/TelegramRemoteDevices.tsx, apps/desktop/src/renderer/components/settings/TerminalShellSection.tsx, apps/desktop/src/renderer/components/settings/TipsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/TipsSection.tsx, apps/desktop/src/renderer/components/settings/UnifiedModelList.tsx, apps/desktop/src/renderer/components/settings/UserProfileCard.tsx, apps/desktop/src/renderer/components/settings/UserPromptSection.tsx, apps/desktop/src/renderer/components/settings/VisionBridgeSection.settings-search.ts, apps/desktop/src/renderer/components/settings/VisionBridgeSection.tsx, apps/desktop/src/renderer/components/settings/VoiceInputSection.settings-search.ts, apps/desktop/src/renderer/components/settings/VoiceInputSection.tsx, apps/desktop/src/renderer/components/settings/WallpaperSection.tsx, apps/desktop/src/renderer/components/settings/WechatBotSection.tsx, apps/desktop/src/renderer/components/settings/WecomBotSection.tsx, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.settings-search.ts, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeyboardLayout.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeycapGlyphs.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexSettings.tsx, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.settings-search.ts, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx, apps/desktop/src/renderer/components/settings/XUsageGuide.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadSettings.tsx, apps/desktop/src/renderer/components/settings/androidStatusPresentation.ts, apps/desktop/src/renderer/components/settings/billingVisibility.ts, apps/desktop/src/renderer/components/settings/browserOpenForLoginError.ts, apps/desktop/src/renderer/components/settings/cindyMakeVisibility.ts, apps/desktop/src/renderer/components/settings/computerPermissionFlow.ts, apps/desktop/src/renderer/components/settings/contacts/ContactDetailPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsImportDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsListPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsManagerDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsSection.tsx, apps/desktop/src/renderer/components/settings/contacts/startContactsAiSession.ts, apps/desktop/src/renderer/components/settings/dialogueDirectoryDisplay.ts, apps/desktop/src/renderer/components/settings/dualSenseSilhouette.ts, apps/desktop/src/renderer/components/settings/feishuBotPresentation.ts, apps/desktop/src/renderer/components/settings/fontFamilyValue.ts, apps/desktop/src/renderer/components/settings/gamepadLayoutPrimitives.tsx, apps/desktop/src/renderer/components/settings/gamepadSilhouetteGeom.ts, apps/desktop/src/renderer/components/settings/hookWorkspacePrefsLogic.ts, apps/desktop/src/renderer/components/settings/imBotVisibility.ts, apps/desktop/src/renderer/components/settings/imDefaultSettingsLogic.ts, apps/desktop/src/renderer/components/settings/joyConSilhouette.ts, apps/desktop/src/renderer/components/settings/modelManagementPresentation.ts, apps/desktop/src/renderer/components/settings/modelManagementState.ts, apps/desktop/src/renderer/components/settings/myDevicesModel.ts, apps/desktop/src/renderer/components/settings/providerAssetModule.ts, apps/desktop/src/renderer/components/settings/realProfilePermissionGuide.ts, apps/desktop/src/renderer/components/settings/settingsSearchCatalog.ts, apps/desktop/src/renderer/components/settings/settingsSearchTypes.ts, apps/desktop/src/renderer/components/settings/switchProSilhouette.ts, apps/desktop/src/renderer/components/settings/ultimateC1Silhouette.ts, apps/desktop/src/renderer/components/settings/usage/UsageBarsTooltip.tsx, apps/desktop/src/renderer/components/settings/usage/UsageBreakdownTables.tsx, apps/desktop/src/renderer/components/settings/usage/UsageDeviceSelect.tsx, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.settings-search.ts, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.tsx, apps/desktop/src/renderer/components/settings/usage/UsageStatRow.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTaskTable.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTokenBars.tsx, apps/desktop/src/renderer/components/settings/usage/formatUsagePercent.ts, apps/desktop/src/renderer/components/settings/usage/usageCharts.css, apps/desktop/src/renderer/components/settings/usage/usageHistoryColors.ts, apps/desktop/src/renderer/components/settings/usage/usageHistoryStats.ts, apps/desktop/src/renderer/components/settings/usageVisibility.ts, apps/desktop/src/renderer/components/settings/useProviderSubscriptionCard.ts, apps/desktop/src/renderer/components/settings/useSettingsEscape.ts, apps/desktop/src/renderer/components/settings/useSettingsSectionTarget.ts, apps/desktop/src/renderer/components/settings/wizardRecommend.ts, apps/desktop/src/renderer/components/settings/workLouderCodexCommandCopy.ts, apps/desktop/src/renderer/components/settings/xboxSeriesSilhouette.ts, apps/desktop/src/renderer/styles/sortable.css | 137 | 100 | 542 |
+| `desktop.settings` | desktop | 设置 | hash `/settings`(SettingsView;tab 含 general / personalization / providers / billing / usage / voice-input / im-bot / shortcuts / agent-island / import / remote-control / ghosts / builtin-tools / computer-use / help / about) | SettingsView | apps/desktop/src/renderer/components/settings/AboutSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AboutSection.tsx, apps/desktop/src/renderer/components/settings/AccountDeletionSection.tsx, apps/desktop/src/renderer/components/settings/AddProviderWizard.tsx, apps/desktop/src/renderer/components/settings/AgentIslandSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AgentIslandSection.tsx, apps/desktop/src/renderer/components/settings/AgentResourceSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AgentResourceSection.tsx, apps/desktop/src/renderer/components/settings/AppearanceSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AppearanceSection.tsx, apps/desktop/src/renderer/components/settings/AuxiliaryModelSection.tsx, apps/desktop/src/renderer/components/settings/AvatarCropEditor.tsx, apps/desktop/src/renderer/components/settings/BetaChannelCell.tsx, apps/desktop/src/renderer/components/settings/BillingSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx, apps/desktop/src/renderer/components/settings/BrowserRealProfileSubsection.tsx, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.tsx, apps/desktop/src/renderer/components/settings/ChatEmbeddingCell.tsx, apps/desktop/src/renderer/components/settings/ChipMetricsSection.tsx, apps/desktop/src/renderer/components/settings/CindyMakeSection.settings-search.ts, apps/desktop/src/renderer/components/settings/CindyMakeSection.tsx, apps/desktop/src/renderer/components/settings/CollaborationSection.settings-search.ts, apps/desktop/src/renderer/components/settings/CollaborationSection.tsx, apps/desktop/src/renderer/components/settings/CompactionSection.tsx, apps/desktop/src/renderer/components/settings/ComposerSendShortcutSection.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionRow.tsx, apps/desktop/src/renderer/components/settings/ComputerUseSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx, apps/desktop/src/renderer/components/settings/CustomProviderRuntimeFillOverlay.tsx, apps/desktop/src/renderer/components/settings/DefaultOverrideControls.tsx, apps/desktop/src/renderer/components/settings/DialogueDirectorySection.tsx, apps/desktop/src/renderer/components/settings/DingTalkBotSection.tsx, apps/desktop/src/renderer/components/settings/DiscordBotSection.tsx, apps/desktop/src/renderer/components/settings/DownloadMeter.tsx, apps/desktop/src/renderer/components/settings/ExperimentalSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotNotificationSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotSection.tsx, apps/desktop/src/renderer/components/settings/FontFamilyPicker.tsx, apps/desktop/src/renderer/components/settings/GeneralSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/GenericGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/GitSafetySection.settings-search.ts, apps/desktop/src/renderer/components/settings/GitSafetySection.tsx, apps/desktop/src/renderer/components/settings/HarnessVersionMenuRow.tsx, apps/desktop/src/renderer/components/settings/HelpAssistantPanel.tsx, apps/desktop/src/renderer/components/settings/HelpSection.settings-search.ts, apps/desktop/src/renderer/components/settings/HelpSection.tsx, apps/desktop/src/renderer/components/settings/HelpThreadView.tsx, apps/desktop/src/renderer/components/settings/HookConnectionsSection.tsx, apps/desktop/src/renderer/components/settings/HookWorkspacePrefsEditor.tsx, apps/desktop/src/renderer/components/settings/ImBotSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ImBotSection.tsx, apps/desktop/src/renderer/components/settings/ImChannelSettingsCard.tsx, apps/desktop/src/renderer/components/settings/ImDefaultSettingsSection.tsx, apps/desktop/src/renderer/components/settings/ImLifecycleAnnouncementSection.tsx, apps/desktop/src/renderer/components/settings/InputDeviceConnectionStatus.tsx, apps/desktop/src/renderer/components/settings/JoyConGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx, apps/desktop/src/renderer/components/settings/LanguageSection.tsx, apps/desktop/src/renderer/components/settings/LayoutResetControl.tsx, apps/desktop/src/renderer/components/settings/LinkOpenSection.tsx, apps/desktop/src/renderer/components/settings/LlamaCppCandidates.tsx, apps/desktop/src/renderer/components/settings/LlamaCppProviderDetail.tsx, apps/desktop/src/renderer/components/settings/LocalModelDownloadUI.tsx, apps/desktop/src/renderer/components/settings/LocalOllamaInstall.tsx, apps/desktop/src/renderer/components/settings/LocalPackagingTag.tsx, apps/desktop/src/renderer/components/settings/LogoutSection.tsx, apps/desktop/src/renderer/components/settings/LspBetaCell.tsx, apps/desktop/src/renderer/components/settings/McpServerDialog.tsx, apps/desktop/src/renderer/components/settings/McpServersSection.tsx, apps/desktop/src/renderer/components/settings/MemorySection.tsx, apps/desktop/src/renderer/components/settings/MessageNavRailCell.tsx, apps/desktop/src/renderer/components/settings/ModelAdvancedDrawer.tsx, apps/desktop/src/renderer/components/settings/ModelPriceOverrideDialog.tsx, apps/desktop/src/renderer/components/settings/MyDevicesPanel.tsx, apps/desktop/src/renderer/components/settings/NotificationSection.settings-search.ts, apps/desktop/src/renderer/components/settings/NotificationSection.tsx, apps/desktop/src/renderer/components/settings/OAuthDeviceCodeCard.tsx, apps/desktop/src/renderer/components/settings/OllamaProviderDetail.tsx, apps/desktop/src/renderer/components/settings/OwnRemoteProviders.tsx, apps/desktop/src/renderer/components/settings/PersonalizationDetails.settings-search.ts, apps/desktop/src/renderer/components/settings/PersonalizationSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/PiKernelVersionRow.tsx, apps/desktop/src/renderer/components/settings/PiPackagesSection.tsx, apps/desktop/src/renderer/components/settings/PlayStationGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderImportDialog.tsx, apps/desktop/src/renderer/components/settings/ProvidersSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ProvidersSection.tsx, apps/desktop/src/renderer/components/settings/ReadOnlyProviderModels.tsx, apps/desktop/src/renderer/components/settings/RemoteControlSection.settings-search.ts, apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopPermissions.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopSetting.tsx, apps/desktop/src/renderer/components/settings/RemoteHostDetail.tsx, apps/desktop/src/renderer/components/settings/RemoteSection.tsx, apps/desktop/src/renderer/components/settings/SessionImportSection.settings-search.ts, apps/desktop/src/renderer/components/settings/SessionImportSection.tsx, apps/desktop/src/renderer/components/settings/SessionRuntimeFallbackCell.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.settings-search.ts, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.tsx, apps/desktop/src/renderer/components/settings/SettingsSearchBox.tsx, apps/desktop/src/renderer/components/settings/SettingsSearchNavigation.ts, apps/desktop/src/renderer/components/settings/SettingsSidebarNav.tsx, apps/desktop/src/renderer/components/settings/SettingsTextInput.tsx, apps/desktop/src/renderer/components/settings/SettingsView.tsx, apps/desktop/src/renderer/components/settings/SharedTasks.settings-search.ts, apps/desktop/src/renderer/components/settings/SilentEncryptedRetryCell.tsx, apps/desktop/src/renderer/components/settings/SshKeySetupDialog.tsx, apps/desktop/src/renderer/components/settings/StorageManagementCard.settings-search.ts, apps/desktop/src/renderer/components/settings/StorageManagementCard.tsx, apps/desktop/src/renderer/components/settings/StreamFadeSection.tsx, apps/desktop/src/renderer/components/settings/SubagentModelSection.settings-search.ts, apps/desktop/src/renderer/components/settings/SubagentModelSection.tsx, apps/desktop/src/renderer/components/settings/SwitchProGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/TelegramBehaviorSettings.tsx, apps/desktop/src/renderer/components/settings/TelegramBotSection.tsx, apps/desktop/src/renderer/components/settings/TelegramRemoteDevices.tsx, apps/desktop/src/renderer/components/settings/TerminalShellSection.tsx, apps/desktop/src/renderer/components/settings/TipsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/TipsSection.tsx, apps/desktop/src/renderer/components/settings/UnifiedModelList.tsx, apps/desktop/src/renderer/components/settings/UserProfileCard.tsx, apps/desktop/src/renderer/components/settings/UserPromptSection.tsx, apps/desktop/src/renderer/components/settings/VisionBridgeSection.settings-search.ts, apps/desktop/src/renderer/components/settings/VisionBridgeSection.tsx, apps/desktop/src/renderer/components/settings/VoiceInputSection.settings-search.ts, apps/desktop/src/renderer/components/settings/VoiceInputSection.tsx, apps/desktop/src/renderer/components/settings/WallpaperSection.tsx, apps/desktop/src/renderer/components/settings/WechatBotSection.tsx, apps/desktop/src/renderer/components/settings/WecomBotSection.tsx, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.settings-search.ts, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeyboardLayout.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeycapGlyphs.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexSettings.tsx, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.settings-search.ts, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx, apps/desktop/src/renderer/components/settings/XUsageGuide.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadSettings.tsx, apps/desktop/src/renderer/components/settings/androidStatusPresentation.ts, apps/desktop/src/renderer/components/settings/avatarCropGeometry.ts, apps/desktop/src/renderer/components/settings/avatarCropImage.ts, apps/desktop/src/renderer/components/settings/billingVisibility.ts, apps/desktop/src/renderer/components/settings/browserOpenForLoginError.ts, apps/desktop/src/renderer/components/settings/cindyMakeVisibility.ts, apps/desktop/src/renderer/components/settings/computerPermissionFlow.ts, apps/desktop/src/renderer/components/settings/contacts/ContactDetailPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsImportDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsListPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsManagerDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsSection.tsx, apps/desktop/src/renderer/components/settings/contacts/startContactsAiSession.ts, apps/desktop/src/renderer/components/settings/dialogueDirectoryDisplay.ts, apps/desktop/src/renderer/components/settings/dualSenseSilhouette.ts, apps/desktop/src/renderer/components/settings/feishuBotPresentation.ts, apps/desktop/src/renderer/components/settings/fontFamilyValue.ts, apps/desktop/src/renderer/components/settings/gamepadLayoutPrimitives.tsx, apps/desktop/src/renderer/components/settings/gamepadSilhouetteGeom.ts, apps/desktop/src/renderer/components/settings/hookWorkspacePrefsLogic.ts, apps/desktop/src/renderer/components/settings/imBotVisibility.ts, apps/desktop/src/renderer/components/settings/imDefaultSettingsLogic.ts, apps/desktop/src/renderer/components/settings/joyConSilhouette.ts, apps/desktop/src/renderer/components/settings/modelManagementPresentation.ts, apps/desktop/src/renderer/components/settings/modelManagementState.ts, apps/desktop/src/renderer/components/settings/myDevicesModel.ts, apps/desktop/src/renderer/components/settings/providerAssetModule.ts, apps/desktop/src/renderer/components/settings/realProfilePermissionGuide.ts, apps/desktop/src/renderer/components/settings/settingsSearchCatalog.ts, apps/desktop/src/renderer/components/settings/settingsSearchTypes.ts, apps/desktop/src/renderer/components/settings/switchProSilhouette.ts, apps/desktop/src/renderer/components/settings/ultimateC1Silhouette.ts, apps/desktop/src/renderer/components/settings/usage/UsageBarsTooltip.tsx, apps/desktop/src/renderer/components/settings/usage/UsageBreakdownTables.tsx, apps/desktop/src/renderer/components/settings/usage/UsageDeviceSelect.tsx, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.settings-search.ts, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.tsx, apps/desktop/src/renderer/components/settings/usage/UsageStatRow.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTaskTable.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTokenBars.tsx, apps/desktop/src/renderer/components/settings/usage/formatUsagePercent.ts, apps/desktop/src/renderer/components/settings/usage/usageCharts.css, apps/desktop/src/renderer/components/settings/usage/usageHistoryColors.ts, apps/desktop/src/renderer/components/settings/usage/usageHistoryStats.ts, apps/desktop/src/renderer/components/settings/usageVisibility.ts, apps/desktop/src/renderer/components/settings/useProviderSubscriptionCard.ts, apps/desktop/src/renderer/components/settings/useSettingsEscape.ts, apps/desktop/src/renderer/components/settings/useSettingsSectionTarget.ts, apps/desktop/src/renderer/components/settings/wizardRecommend.ts, apps/desktop/src/renderer/components/settings/workLouderCodexCommandCopy.ts, apps/desktop/src/renderer/components/settings/xboxSeriesSilhouette.ts, apps/desktop/src/renderer/styles/sortable.css | 139 | 100 | 545 |
| `desktop.shell.main-layout` | desktop | 主窗口壳(标题栏 / 左右栏 / 内容区) | main BrowserWindow → renderer/index.tsx → main-entry.tsx → App → MainLayout (`#/` 受保护壳) | ChromeActions, DeviceSectionHeader, FeishuConflictDialogHost, GhostMediaLightboxHost, MainLayout, ProjectsSection, RightSidebar, RightSidebarShell, SessionShareImportWizard, Sidebar, UpdateNoticeDialog, WindowControls | apps/desktop/src/renderer/cindy-brain/GhostMediaLightboxHost.tsx, apps/desktop/src/renderer/components/UpdateNoticeDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialogHost.tsx, apps/desktop/src/renderer/components/layout/AppBadgeAttentionSync.tsx, apps/desktop/src/renderer/components/layout/BrowserWebviewPool.tsx, apps/desktop/src/renderer/components/layout/ChromeActions.tsx, apps/desktop/src/renderer/components/layout/ContentHeader.tsx, apps/desktop/src/renderer/components/layout/CredentialStoreBanner.tsx, apps/desktop/src/renderer/components/layout/FadeSwitcher.tsx, apps/desktop/src/renderer/components/layout/GhostPanelWindowLayout.tsx, apps/desktop/src/renderer/components/layout/GlobalDropImportListener.tsx, apps/desktop/src/renderer/components/layout/MainEntryRedirect.tsx, apps/desktop/src/renderer/components/layout/MainLayout.tsx, apps/desktop/src/renderer/components/layout/RightSidebar.tsx, apps/desktop/src/renderer/components/layout/RightSidebarDetach.tsx, apps/desktop/src/renderer/components/layout/RightSidebarMaximize.tsx, apps/desktop/src/renderer/components/layout/RightSidebarToggle.tsx, apps/desktop/src/renderer/components/layout/SidebarWindowLayout.tsx, apps/desktop/src/renderer/components/layout/WallpaperVideo.tsx, apps/desktop/src/renderer/components/layout/chromeActionsGeometry.ts, apps/desktop/src/renderer/components/layout/chromeActionsLayout.ts, apps/desktop/src/renderer/components/layout/railChromeActions.ts, apps/desktop/src/renderer/components/layout/windowDrag.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/sidebar/AccountSwitcherDialog.tsx, apps/desktop/src/renderer/components/sidebar/AttentionDot.tsx, apps/desktop/src/renderer/components/sidebar/DatabaseSizeWarningBanner.tsx, apps/desktop/src/renderer/components/sidebar/GhostMainViewNavEntries.tsx, apps/desktop/src/renderer/components/sidebar/MobileDownloadDialog.tsx, apps/desktop/src/renderer/components/sidebar/NavigationCountBadge.tsx, apps/desktop/src/renderer/components/sidebar/Sidebar.tsx, apps/desktop/src/renderer/components/sidebar/SidebarIconButton.tsx, apps/desktop/src/renderer/components/sidebar/SidebarNavigationCustomize.tsx, apps/desktop/src/renderer/components/sidebar/SidebarTopNav.tsx, apps/desktop/src/renderer/components/sidebar/SortableList.tsx, apps/desktop/src/renderer/components/sidebar/UpdateBanner.tsx, apps/desktop/src/renderer/components/sidebar/UserInfoSection.tsx, apps/desktop/src/renderer/components/sidebar/VendorIcon.tsx, apps/desktop/src/renderer/components/sidebar/VendorReadinessBadge.tsx, apps/desktop/src/renderer/components/sidebar/WorktreeBadge.tsx, apps/desktop/src/renderer/components/sidebar/sidebarNavigationPrefs.ts, apps/desktop/src/renderer/components/sidebar/useHoverOpenMenu.ts, apps/desktop/src/renderer/components/title-bar/ChromeIconButton.tsx, apps/desktop/src/renderer/components/title-bar/MenuButton.tsx, apps/desktop/src/renderer/components/title-bar/WindowControls.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/DeviceSectionHeader.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/sections/ProjectsSection.tsx, apps/desktop/src/renderer/features/right-sidebar/AddTabDropdown.tsx, apps/desktop/src/renderer/features/right-sidebar/EmptyState.tsx, apps/desktop/src/renderer/features/right-sidebar/RightSidebarShell.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBar.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBodyErrorBoundary.tsx, apps/desktop/src/renderer/features/right-sidebar/hooks/useBrowserWebview.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useNativePopupSurface.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserPartition.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts, apps/desktop/src/renderer/features/right-sidebar/lib/detachedSidebarRouting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/executeSidebarCommand.ts, apps/desktop/src/renderer/features/right-sidebar/lib/lastTurnChangedFiles.ts, apps/desktop/src/renderer/features/right-sidebar/lib/nativePopupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBackgroundTasksTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBotWorkbenchTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarFileBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openRoutinesTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSubagentsTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTerminalShortcut.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTurnReview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupRouter.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/rsbBrowserBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarCommands.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarHostSession.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/BackgroundTasksBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowAgentStrip.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowProgressTree.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/chatTaskFocusIntent.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/listSessionTasks.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/workflowProgressModel.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/bot-workbench/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/CindyMakeTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.css, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/dropExternalFile.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/fileTreeImagePreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/useSessionScopedTreeWidth.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/index.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersAttentionIcon.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/actions.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/closeDecision.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/ResourceUsageBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/resource-usage.css, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/subscription.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/retired-feature/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/ImageDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/MarkdownDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/PlainUnifiedDiff.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/diffRows.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/highlight.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/inlineDiff.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/useDiffHighlights.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/ReviewTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/diffExpansionPreference.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/fileTree.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/gitApplyCommand.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/markdownPreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useLastTurnFilter.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewGitState.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewSource.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/routines/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/ConversationStream.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/DetailView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/RunList.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentToolCard.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentsBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentChangeFence.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentConversation.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentFormat.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/TerminalTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/lib/xtermPool.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserCommentPopover.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/browserCommentEditorDraft.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/lib/parseOmnibox.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useBrowserComment.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useLocalHtmlAutoReload.ts, apps/desktop/src/renderer/features/right-sidebar/registry.ts, apps/desktop/src/renderer/features/right-sidebar/store.ts, apps/desktop/src/renderer/features/right-sidebar/tabAvailability.ts, apps/desktop/src/renderer/features/right-sidebar/types.ts, apps/desktop/src/renderer/layout/LayoutRoot.tsx, apps/desktop/src/renderer/layout/PanelDragController.tsx, apps/desktop/src/renderer/layout/PanelDragPrototype.tsx, apps/desktop/src/renderer/layout/collapsePrefs.ts, apps/desktop/src/renderer/layout/layoutDevTools.ts, apps/desktop/src/renderer/layout/panePlacement.tsx, apps/desktop/src/renderer/layout/paneWidths.tsx, apps/desktop/src/renderer/layout/panelMaximize.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 144 | 46 | 200 |
| `desktop.skillhub.local` | desktop | SkillHub 本地技能 | hash `/skillhub/local` 及统一详情 `/skillhub/detail`(旧详情链接重定向) | InstallTargetPicker, PluginManagementLayout, SkillDetailLayout, SkillhubDetailRoute, SkillhubDetailView, SkillhubFeatureLayout, SkillhubHomeView, SkillhubLocalLayout, SkillhubMarketDetailView | apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailRoute.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubFeatureLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubLocalLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketDetailView.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillDetailLayout.tsx | 35 | 0 | 43 |
| `desktop.skillhub.market` | desktop | SkillHub 市场 | hash `/skillhub/market`(SkillhubMarketListView) | InstallTargetPicker, MarketCard, MarketInfoEditDialog, SkillhubMarketDetailView, SkillhubMarketListView, VisibilityEditorDialog | apps/desktop/src/renderer/features/skillhub/SkillhubMarketDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx, apps/desktop/src/renderer/features/skillhub/components/HomeMarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/LocalSkillControls.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInfoEditDialog.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInstallStatus.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketListError.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketLocalSkills.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketPreviewTree.tsx, apps/desktop/src/renderer/features/skillhub/components/OfficialSkillBadge.tsx, apps/desktop/src/renderer/features/skillhub/components/PlatformTagSelector.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillCategoryFilterBar.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillDetailLayout.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillIcon.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillTagList.tsx, apps/desktop/src/renderer/features/skillhub/components/TeamScopePicker.tsx, apps/desktop/src/renderer/features/skillhub/components/VisibilityEditorDialog.tsx | 43 | 0 | 37 |