feat: cache auth file metadata

Author: linhay

docs-linhay/spaces/20260526-auth-file-metadata-cache/README.md

@@ -0,0 +1,55 @@
+# Auth File Metadata Cache
+
+## 背景
+
+当前账号页和用量归因都会触发 auth-file 读取。对于桌面客户端，这类本地文件访问本身不重，但如果每次刷新都重复读原文、重复推断元数据，就会放大 IO、CPU、日志和敏感内容暴露面。
+
+## 目标
+
+1. 把 auth-file 读取拆成“强一致刷新”和“缓存优先返回”两条路径。
+2. 降低账号列表、详情、归因 join 等普通展示场景的重复下载频率。
+3. 保留需要实时读取原文的场景能力，不牺牲用户可见的一致性。
+
+## 范围
+
+1. auth-file 元数据缓存与失效策略。
+2. 账号列表 / 归因 / OAuth 回填等调用链的重复读取收敛。
+3. 对应测试与文档写回。
+
+## 非目标
+
+1. 不把 auth-file 存储从文件迁移到数据库。
+2. 不改变现有 auth-file 作为事实源的边界。
+3. 不在本期引入跨进程共享缓存。
+
+## 验收标准
+
+1. 普通展示场景优先命中进程缓存，不再对同一批 auth-file 反复下载原文。
+2. 文件内容、大小或修改时间变化后，缓存能及时失效并重新读取。
+3. 强一致场景仍能强制走 fresh 读取。
+4. 相关测试通过，且 README / plan / 后续记忆写回可检索。
+
+## 设计稿入口
+
+- 本期设计稿：`（未产出）`
+- 约束：单期只保留一个 HTML 文件；若存在多稿对比，也必须收敛在同一个 HTML 文件内。
+
+## Worktree 映射
+
+- branch：`feat/20260526-auth-file-metadata-cache`
+- worktree：`../GetTokens-worktrees/20260526-auth-file-metadata-cache/`
+
+## 相关链接
+
+## 当前状态
+- 状态：implemented
+- 最近更新：2026-05-27
+
+## 实现记录
+
+### 2026-05-27
+
+- 在 `internal/wailsapp` 增加 auth-file 元数据进程缓存，缓存键为 `name + size + modified`。
+- `ListAuthFiles` 对普通列表场景优先使用缓存；首次 fresh 下载后只缓存展示元数据，不缓存完整 auth 原文。
+- 上传、删除、启停状态修改成功后按文件名失效缓存；文件大小或修改时间变化会自然绕过旧缓存。
+- 补充 sidecar mock 测试，覆盖重复列表不重复下载、元数据仍不完整也不重复下载、fingerprint 变化后重新下载。

docs-linhay/spaces/20260526-auth-file-metadata-cache/plans/20260526-auth-file-metadata-cache-plan-v01.md

@@ -0,0 +1,48 @@
+# Auth File Metadata Cache Plan v01
+
+## 1. 问题定义
+
+auth-file 当前同时承担凭证事实源和展示元数据来源。由于列表刷新、归因 join、OAuth 回填、详情展开等路径都会读取同一批文件，普通交互容易触发重复下载和重复推断。
+
+## 2. 目标
+
+1. 区分强一致读取和缓存优先读取。
+2. 让常规展示尽量命中进程缓存。
+3. 让文件变化时自动失效，避免长期脏数据。
+
+## 3. 方案草图
+
+### 3.1 读取分级
+
+- `fresh`：显式需要原文的场景，先 stat/read/parse，再刷新缓存。
+- `cached`：列表、归因、轻量展示优先读缓存。
+- `cached-then-refresh`：先返回缓存，再后台补读并更新缓存，用于首屏快显。
+
+### 3.2 缓存键
+
+- 以 `name + size + modifiedTime` 作为主失效依据。
+- 缓存内容只放展示元数据，不长期保存完整 auth 原文。
+
+### 3.3 失效来源
+
+- 文件上传、删除、状态修改。
+- 文件内容或修改时间变化。
+- 需要强一致的用户动作显式跳过缓存。
+
+## 4. 实施顺序
+
+1. 梳理重复调用点，确认哪些路径必须 fresh。
+2. 给 auth-file 元数据补一个进程级缓存。
+3. 合并账号页 / 归因路径的重复拉取。
+4. 补回归测试，覆盖缓存命中、失效和强制刷新。
+
+## 5. 验收
+
+1. 账号页反复刷新时，auth-file download 次数显著下降。
+2. 文件被修改后，缓存能在下一轮请求中失效。
+3. 账号详情或回填等强一致路径仍可拿到最新原文。
+4. 相关 Go / 前端测试通过。
+
+## 6. 当前进展
+
+- 2026-05-27：已完成进程级 metadata cache、失效逻辑、重复下载回归测试与 Go 测试验证。

internal/wailsapp/app.go

@@ -26,6 +26,8 @@ type App struct {
 	managementAPI            func() *cliproxyapi.Client
 	sidecarProxyMu           sync.Mutex
 	sidecarProxyPendingApply bool
+	authFileCacheMu          sync.RWMutex
+	authFileMetadataCache    map[string]authFileMetadataCacheEntry
 	localUsageMu             sync.RWMutex
 	localUsage               localUsageRuntimeState
 	claudeLocalUsage         localUsageRuntimeState
@@ -53,12 +55,13 @@ type sidecarRelayRequestFunc func(method string, path string, body io.Reader, co
 
 func New(version string, releaseLabel string, repo string) *App {
 	return &App{
-		sidecar:      sidecar.NewManager(),
-		updater:      updater.New(repo, version),
-		version:      version,
-		releaseLabel: releaseLabel,
-		codexBinary:  codexbinary.NewService(codexbinary.ServiceOptions{}),
-		menuBar:      menubar.NewController(),
+		sidecar:               sidecar.NewManager(),
+		updater:               updater.New(repo, version),
+		version:               version,
+		releaseLabel:          releaseLabel,
+		codexBinary:           codexbinary.NewService(codexbinary.ServiceOptions{}),
+		menuBar:               menubar.NewController(),
+		authFileMetadataCache: map[string]authFileMetadataCacheEntry{},
 	}
 }
 

internal/wailsapp/auth_files.go

@@ -30,7 +30,14 @@ func (a *App) ListAuthFiles() (*AuthFilesResponse, error) {
 
 	for index := range result.Files {
 		file := &result.Files[index]
+		if cached, ok := a.cachedAuthFileMetadata(*file); ok {
+			applyCachedAuthFileMetadata(file, cached)
+			a.storeAuthFileMetadata(*file)
+			continue
+		}
+
 		if !needsAuthFileMetadataInference(*file) {
+			a.storeAuthFileMetadata(*file)
 			continue
 		}
 
@@ -55,6 +62,7 @@ func (a *App) ListAuthFiles() (*AuthFilesResponse, error) {
 			file.PlanType = profile.PlanType
 		}
 		file.Priority = accountsdomain.ExtractAuthFilePriority(body)
+		a.storeAuthFileMetadata(*file)
 	}
 
 	return &result, nil
@@ -93,6 +101,9 @@ func (a *App) SetAuthFileStatus(name string, disabled bool) error {
 		return err
 	}
 	_, _, err = a.SidecarRequest(http.MethodPatch, ManagementAPIPrefix+"/auth-files/status", nil, bytes.NewReader(b), "application/json")
+	if err == nil {
+		a.invalidateAuthFileMetadataCache(name)
+	}
 	return err
 }
 
@@ -105,6 +116,9 @@ func (a *App) DeleteAuthFiles(names []string) error {
 		return err
 	}
 	_, _, err = a.SidecarRequest(http.MethodDelete, ManagementAPIPrefix+"/auth-files", nil, bytes.NewReader(b), "application/json")
+	if err == nil {
+		a.invalidateAuthFileMetadataCache(names...)
+	}
 	return err
 }
 
@@ -120,6 +134,7 @@ func (a *App) UploadAuthFiles(files []UploadFilePayload) error {
 
 	var buf bytes.Buffer
 	w := multipart.NewWriter(&buf)
+	resolvedNames := make([]string, 0, len(files))
 
 	for _, f := range files {
 		if strings.TrimSpace(f.Name) == "" || strings.TrimSpace(f.ContentBase64) == "" {
@@ -133,6 +148,7 @@ func (a *App) UploadAuthFiles(files []UploadFilePayload) error {
 			decoded = normalized
 		}
 		resolvedName := uniqueAuthFileUploadName(f.Name, existingNames)
+		resolvedNames = append(resolvedNames, resolvedName)
 		part, err := w.CreateFormFile("file", resolvedName)
 		if err != nil {
 			return err
@@ -147,6 +163,9 @@ func (a *App) UploadAuthFiles(files []UploadFilePayload) error {
 	}
 
 	_, _, err = a.SidecarRequest(http.MethodPost, ManagementAPIPrefix+"/auth-files", nil, &buf, w.FormDataContentType())
+	if err == nil {
+		a.invalidateAuthFileMetadataCache(resolvedNames...)
+	}
 	return err
 }
 

internal/wailsapp/auth_files_cache.go

@@ -0,0 +1,109 @@
+package wailsapp
+
+import (
+	"fmt"
+	"strings"
+)
+
+type authFileMetadataCacheEntry struct {
+	Name     string
+	Size     int64
+	Modified int64
+	Type     string
+	Provider string
+	Priority int
+	Email    string
+	PlanType string
+}
+
+func authFileMetadataCacheKey(name string, size int64, modified int64) string {
+	return fmt.Sprintf("%s|%d|%d", strings.TrimSpace(name), size, modified)
+}
+
+func (a *App) cachedAuthFileMetadata(file AuthFileItem) (authFileMetadataCacheEntry, bool) {
+	name := strings.TrimSpace(file.Name)
+	if name == "" {
+		return authFileMetadataCacheEntry{}, false
+	}
+	key := authFileMetadataCacheKey(name, file.Size, file.Modified)
+	a.authFileCacheMu.RLock()
+	entry, ok := a.authFileMetadataCache[key]
+	a.authFileCacheMu.RUnlock()
+	if !ok {
+		return authFileMetadataCacheEntry{}, false
+	}
+	return entry, true
+}
+
+func (a *App) storeAuthFileMetadata(file AuthFileItem) {
+	name := strings.TrimSpace(file.Name)
+	if name == "" {
+		return
+	}
+	entry := authFileMetadataCacheEntry{
+		Name:     name,
+		Size:     file.Size,
+		Modified: file.Modified,
+		Type:     strings.TrimSpace(file.Type),
+		Provider: strings.TrimSpace(file.Provider),
+		Priority: file.Priority,
+		Email:    strings.TrimSpace(file.Email),
+		PlanType: strings.TrimSpace(file.PlanType),
+	}
+	key := authFileMetadataCacheKey(name, file.Size, file.Modified)
+	a.authFileCacheMu.Lock()
+	if a.authFileMetadataCache == nil {
+		a.authFileMetadataCache = map[string]authFileMetadataCacheEntry{}
+	}
+	a.authFileMetadataCache[key] = entry
+	a.authFileCacheMu.Unlock()
+}
+
+func applyCachedAuthFileMetadata(file *AuthFileItem, entry authFileMetadataCacheEntry) {
+	if file == nil {
+		return
+	}
+	if needsAuthFileKindInference(*file) {
+		if entry.Provider != "" {
+			file.Provider = entry.Provider
+		}
+		if entry.Type != "" {
+			file.Type = entry.Type
+		}
+	}
+	if strings.TrimSpace(file.Email) == "" {
+		file.Email = entry.Email
+	}
+	if strings.TrimSpace(file.PlanType) == "" {
+		file.PlanType = entry.PlanType
+	}
+	if file.Priority == 0 {
+		file.Priority = entry.Priority
+	}
+}
+
+func (a *App) invalidateAuthFileMetadataCache(names ...string) {
+	a.authFileCacheMu.Lock()
+	defer a.authFileCacheMu.Unlock()
+	if len(a.authFileMetadataCache) == 0 {
+		return
+	}
+	if len(names) == 0 {
+		a.authFileMetadataCache = map[string]authFileMetadataCacheEntry{}
+		return
+	}
+	targets := map[string]struct{}{}
+	for _, name := range names {
+		if trimmed := strings.TrimSpace(name); trimmed != "" {
+			targets[trimmed] = struct{}{}
+		}
+	}
+	if len(targets) == 0 {
+		return
+	}
+	for key, entry := range a.authFileMetadataCache {
+		if _, ok := targets[entry.Name]; ok {
+			delete(a.authFileMetadataCache, key)
+		}
+	}
+}