Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
feat(desktop): 用户头像选图后支持拖动、缩放与实时圆形预览 (#5980)
Dash7b00740b4efd
diff --git a/apps/desktop/src/main/__tests__/profileEdit.test.ts b/apps/desktop/src/main/__tests__/profileEdit.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxnew file mode 100644index 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.tsxindex 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 }: ProfileEditDialogPropsif (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 }: ProfileEditDialogPropsreturn () => {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 }: ProfileEditDialogPropssetSaving(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 }: ProfileEditDialogPropssetSaving(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 }: ProfileEditDialogPropsconst 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 (<ConfirmDialogopen={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 }: ProfileEditDialogPropsloading={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 && (<buttontype="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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.tsindex 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.mdindex 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 |