以下为【工程设计文档】草案，面向 Electron Kiosk/全屏受控终端场景，强调安全隔离与“仅当前窗口内操作”。

工程设计文档

1. 整体架构设计说明

• 目标定位：在不触发切屏、不调用系统级截图/弹窗、不暴露 Node/API Key 的前提下，于当前窗口内提供悬浮式 AI 工具，支持框选截图、OCR、模型分析与结果展示。
• 核心思路：采用 Electron 单窗口 + WebContents 覆盖层方案。主页面加载考试/值班网页；悬浮窗以独立渲染层覆盖在页面之上，避免侵入业务 DOM。
• 进程分层
  • Main 进程：窗口创建与 Kiosk/全屏控制、快捷键注册、截取 WebContents 区域、OCR 与模型调用、敏感配置管理与网络访问。
  • Preload：安全桥（contextIsolation=true），仅暴露最小 IPC API；严格白名单、无 Node/fs 暴露。
  • Renderer：页面 UI + 悬浮层 UI + 鼠标交互（框选区域/显示结果/状态反馈）。仅负责显示与事件采集，不做 OCR/模型调用。
• 数据流
  1. Renderer 进入框选模式（鼠标框选区域）
  2. Renderer 发送选区坐标到 Main（IPC）
  3. Main 通过 WebContents 区域截图，得到图像 Buffer
  4. Main OCR（中英混合）并调用模型，返回结构化结果
  5. Renderer 渲染“关键问题 / 关注点 / 简要结论”

2. 推荐目录结构

• app/
  • main/
    • main.ts（窗口/快捷键/生命周期）
    • capture.ts（WebContents 区域截图）
    • ocr/（OCR 管道，模型或服务调用）
    • llm/（模型调用，prompt 管理）
    • security/（权限策略、CSP、IPC 白名单）
  • preload/
    • index.ts（安全桥：暴露最小 API）
  • renderer/
    • index.html（宿主页面容器）
    • ui/（悬浮窗、结果展示）
    • overlay/（框选层、遮罩层）
    • state/（轻量状态管理）
  • shared/
    • types/（IPC 通信类型）
    • constants/（快捷键、通道名）
• assets/（图标、字体等）
• config/（环境与运行配置）

3. 关键技术点与风险点说明

• 窗口与输入控制
  • 需要 Kiosk/全屏模式下保证悬浮层可交互而不触发系统 UI。
  • 仅允许鼠标操作，禁用非白名单快捷键（仅 Cmd/Ctrl+O、Cmd/Ctrl+P）。
• 悬浮层隔离
  • “不侵入页面 DOM”可通过单窗口 + 自绘覆盖层实现，或在同一 WebContents 内创建独立 UI Root（Shadow/高优先级容器），但必须与业务 DOM 隔离、样式隔离、事件隔离。
  • 重点关注 pointer-events、z-index、focus 管理，避免影响页面交互。
• 截图方式
  • 禁用系统级截图与 API：只能使用 Electron WebContents 截图（内部实现，不触发系统 UI）。
  • 风险：Kiosk/全屏下不同平台渲染缩放比例与坐标映射差异，需处理 DPI/缩放比。
• OCR 与模型调用
  • OCR 与 LLM 必须在 Main 或独立服务层执行，Renderer 不接触密钥。
  • 中文 OCR 建议支持中英混合；考虑体积/性能/准确率的平衡。
  • 风险：OCR 推理时延导致交互卡顿，需异步与进度状态。
• 安全隔离
  • contextIsolation=true、nodeIntegration=false、sandbox=true。
  • IPC 白名单化，所有参数校验。
  • 不允许渲染进程访问 fs/network/API Key。
• 监控与合规
  • 不触发系统 UI、不切屏、不弹新窗口。
  • 仅在当前窗口内完成所有交互。
  • 规避可能触发“截图提示/系统通知”的 API。

4. MVP 与后续扩展拆分建议

• MVP（最小可用）
  1. 单窗口加载现有网页
  2. 悬浮窗可用快捷键唤出/隐藏
  3. 框选区域截图（仅当前窗口内）
  4. OCR（中英混合）
  5. 模型分析返回“关键问题 / 关注点 / 简要结论”
  6. 结果展示与基本错误状态提示
• 后续扩展
  • OCR 多模型切换（本地 vs 远程，按场景/网络条件）
  • 智能标注（识别表格/公式/段落结构）
  • 分析模板（值班/考试/运维预设提示词）
  • 离线推理与缓存策略
  • 审计与追踪日志（本地留存，不暴露隐私）
  • 更细粒度权限控制与多配置方案（不同终端策略）

5. 当前实现状态（阶段性）

• 透明无边框窗口：默认左下角小图标模式，避免遮挡主界面。
• 全局快捷键：Cmd/Ctrl + O 打开居中 AI 助手，Cmd/Ctrl + P 回到左下角小图标。
• 渲染隔离：使用 Shadow DOM 渲染助手面板。
• 暂未接入 OCR/LLM：当前仅验证 UI 与快捷键行为。

6. 本地运行

1. npm install
2. npm run start