CoreBox 窗口行为与 UI View 缓存

CoreBox 高度与窗口缩放

CoreBox 的高度由渲染进程结果列表驱动，并通过主进程应用到窗口。

• 窗口位置固定（仅高度变化）。
• 开启动画时，主进程对窗口 bounds 变化做平滑过渡。

高度分发链路（renderer -> main）

• 渲染侧 useResize 计算高度：headerHeight + scrollHeight + padding，并 clamp 到 64–600。
• 发送 CoreBoxEvents.layout.update，包含 height/resultCount/loading/recommendationPending/activationCount/source。
• 主进程合并 16ms 内的布局请求：CoreBoxModule.queueLayoutUpdate → applyLayoutUpdate。

收缩判定与覆盖逻辑

• resultCount === 0 && !loading && !recommendationPending → shrink()。
• activationCount > 0 && resultCount > 0 → expand({ forceMax: true })。
• 其他情况：按 height 调整 setHeight()。
• UI Mode 下直接跳过布局更新（避免 UI View 附着时频繁缩放）。

手动控制入口

• CoreBoxEvents.ui.expand 支持 collapse/max/length。
• core-box:set-height 支持前端指定高度（60–650，主进程再 clamp）。

相关设置

• appSetting.animation.coreBoxResize
  • true: 开启 CoreBox 窗口伸缩动画
  • false: 直接设置 bounds

空输入的推荐结果

当输入为空且没有激活 provider 时，CoreBox 会向主进程请求推荐结果。

为避免推荐结果还在返回途中导致窗口“先收起再展开”，渲染进程在推荐请求期间保持 pending 状态（或短超时）。

推荐触发与回写流程

• 触发条件：输入为空 + 无激活 provider。
• appSetting.recommendation.enabled === false 时直接 resetSearchState() 并刷新布局。
• 推荐请求期间 recommendationPending = true，超时 400ms 仍无结果则重置状态。
• 主进程空查询触发 RecommendationEngine.recommend(limit=10)。
• 若推荐结果为空，主进程会发 CoreBoxEvents.search.noResults({ shouldShrink: true })，但窗口收缩仍依赖布局更新链路。

AutoPaste / AutoClear（CoreBox 显示阶段）

AutoPaste

• 仅在“快捷键唤起 CoreBox”时自动触发；显式粘贴与用户主动执行插件动作保留 manual 语义。
• 新鲜度判断：autoPaste.time（秒），0 为无限制，-1 关闭；隐式输入填充、clipboard tag 与 query input 统一经过同一门禁。
• 主进程提供 autoPasteEligible、observedAt 与 freshnessBaseAt；renderer 的 visibility、clipboard、search hooks 复用同一判定函数。
• CoreBox 隐藏期间只在主进程记录最新剪贴板，不直接激活 renderer 状态；重新显示时再按新鲜度决定是否带入。
• 文本 <= 80 字会直接填入输入框；超长文本只作为 tag；文件/图片走专用模式。
• 使用 autoPastedClipboardIdentities 去重（TTL 1h），并通过 clearClipboard(remember) 避免重复触发。

AutoClear

• 仅在 CoreBox 再次显示 时检测 lastHidden 与 autoClear 时间差。
• 超时后清空输入、模式、文件/布局、剪贴板缓存，并停用 provider。
• 不是后台定时器：窗口一直保持可见时不会触发。

插件 attachUIView 缓存

对于 webcontent 类型 feature，CoreBox 通过 Electron WebContentsView attach 插件 UI。

目标

复用最近使用的 view，减少重复 load 带来的白屏与启动开销。

缓存配置

• appSetting.viewCache.maxCachedViews
  • 0: 禁用（每次都重新创建/销毁）
  • > 0: 启用 LRU 缓存
• appSetting.viewCache.hotCacheDurationMs
  • 用于 stale cleanup。

说明

• 缓存 key: pluginName:featureId。
• 缓存是 best-effort：如果 view 被销毁会自动从缓存移除。

Resume 事件

每次 CoreBox attach 插件 UI view 时，都会向插件进程发送 core-box:ui-resume 事件，插件可以自行决定是否处理（例如刷新数据、恢复焦点等）。

Payload:

• source: attach | cache
• featureId: 可选
• url: attach 的 URL

常见问题排查（近期反馈）

1) 空输入且无推荐结果时不收缩

• 关注 recommendationPending 是否一直为 true（applyLayoutUpdate 会跳过收缩）。
• search.noResults 事件本身不会改变窗口高度，仍需 layout.update 才会收缩。
• 确认是否处于 UI Mode，主进程会直接跳过布局更新。
• 确认 activeActivations 是否非空（有激活时会强制展开）。

2) 超过 autoPaste 时间仍自动粘贴

• autoPaste.time = 0 是无限制；若需要时间窗，请选择 1 秒、3 秒、5 秒或更长的显式秒数。
• ClipboardEvents.getLatest 会在快捷键唤起时刷新剪贴板快照；自动粘贴以 freshnessBaseAt / observedAt 判定新鲜度，不以 item.timestamp 作为新鲜度基准。
• 若旧内容仍被带入，确认配置值是否落地：appSetting.tools.autoPaste.time 为秒，-1 为关闭。

3) 激活插件后过久，autoClear 不生效

• autoClear 只在 CoreBox 再次显示时检查；UI 一直保持可见不会触发。
• lastHidden 在 onHide 写入，UI Mode 长时间保持可见时不会更新。