ChatFloat for macOS

一个轻量、简洁的 macOS ChatGPT 悬浮窗工具。

核心亮点：不需要 API，只需要你有一个 ChatGPT 的账号

ChatFloat 将 ChatGPT 网页放进一个独立的悬浮窗口。你可以在处理文档、浏览网页或编写代码时，快速打开 ChatGPT，无需频繁切换应用窗口。

轻点悬浮球，即可打开 ChatGPT；点击收起按钮，即可回到轻量的悬浮球模式。

功能特性

• 悬浮球交互：提供轻量的圆形悬浮球，点击即可展开 ChatGPT。
• 窗口始终置顶：使用 macOS 浮动窗口层级，让 ChatGPT 更容易保持在其他普通窗口上方。
• 跨桌面显示：支持在多个 Spaces 中显示，并配置全屏辅助窗口行为。
• 自由拖动：可以拖动悬浮球调整位置，也可以通过展开窗口顶部的标题区域移动窗口。
• 窗口尺寸调整：支持调整展开窗口的大小，并记住上次使用的尺寸。
• 位置记忆：保存悬浮球的位置，下次启动时尝试恢复。
• 网页状态持久化：使用 WKWebView 的默认网站数据存储，保留网站数据及登录状态（具体取决于网站的会话策略）。
• 简洁的窗口设计：无标题栏设计，减少系统窗口装饰对使用空间的占用。
• 原生 macOS 技术栈：使用 Swift、SwiftUI、AppKit 和 WebKit 构建。

项目截图

欢迎提交实际运行截图或 GIF，展示悬浮球、展开窗口和拖动操作。

运行环境

• macOS
• Xcode（建议使用当前受支持的稳定版本）
• Swift
• WebKit

当前项目尚未明确声明最低 macOS 版本，请根据实际测试结果补充兼容性要求。

安装与运行

方法一：通过 Xcode 运行

1. 克隆或下载本项目。
2. 使用 Xcode 创建或打开对应的 macOS App 工程。
3. 将 AppMain 目录中的 Swift 源文件添加到工程。
4. 确认应用的入口为 ChatFloatApp，并检查项目的签名与 Bundle Identifier 配置。
5. 选择 My Mac 作为运行目标。
6. 点击 Run，启动 ChatFloat。

首次打开 ChatGPT 时，请根据页面提示登录。

方法二：构建独立 App

下载 release 即可

使用方法

1. 启动悬浮球

启动应用后，屏幕上会出现一个蓝色的圆形悬浮球。

2. 展开 ChatGPT

点击悬浮球，即可打开 ChatGPT 网页窗口。

首次使用时，需要登录 ChatGPT 账号。

3. 移动窗口

• 在悬浮球模式下，按住悬浮球拖动即可调整位置。
• 在展开模式下，拖动窗口顶部的 ChatFloat 标题区域即可移动窗口。

4. 调整窗口大小

展开窗口后，可以使用 macOS 窗口的缩放交互调整大小。窗口尺寸会自动保存，供下次展开时恢复。

5. 收起窗口

点击窗口右上方的 − 按钮，即可收起窗口并返回悬浮球模式。

6. 恢复悬浮球位置

应用会保存悬浮球的位置。重新启动时，会尝试恢复位置，并在当前屏幕可见范围内进行限制。

技术实现

技术	用途
Swift	核心逻辑
SwiftUI	视图与界面布局
AppKit	macOS 窗口管理与鼠标事件
WebKit	加载 ChatGPT 网页
UserDefaults	保存窗口位置与尺寸

核心组件

• ChatFloatApp：应用入口。
• ChatFloatAppDelegate：管理应用启动及悬浮窗口控制器。
• FloatingState：保存展开状态、窗口尺寸和悬浮球位置。
• WebViewStore：统一管理 WKWebView 实例，并避免重复初始化网页加载流程。
• ChatFloatPanel：自定义无标题栏的浮动面板。
• ChatFloatWindowController：负责窗口展开、收起、移动、尺寸恢复和位置约束。
• FloatingRootView：根据当前状态切换悬浮球与网页界面。
• FloatingBallNSView：处理悬浮球的绘制、点击和拖动事件。

隐私与安全

ChatFloat 使用 WebKit 加载官方 ChatGPT 网站：

https://chatgpt.com/

当前实现中：

• 使用 WKWebsiteDataStore.default() 管理网站数据。
• 不包含自行实现的 ChatGPT API 调用逻辑。
• 不包含主动上传用户对话或遥测数据的代码路径（以当前提供的源码为准）。
• 网站登录状态和 Cookie 等数据由 WebKit 的网站数据存储管理。

请注意：

• ChatGPT 的登录状态和会话持久性由网站及其认证策略决定，不能保证永久有效。
• 不建议在不可信设备上登录个人账号。
• 后续版本应继续检查网页导航、外部链接、JavaScript 桥接和网站权限的安全边界。

已知限制与后续计划

以下为可考虑的后续改进方向，并不代表这些功能已经实现：

• 增加全局快捷键，用于显示和隐藏悬浮窗。
• 增加设置界面，支持调整窗口尺寸和悬浮球外观。
• 改进多显示器切换后的窗口位置恢复。
• 增加自动化构建与基础测试。
• 根据实际测试补充常见问题和错误排查指南。

参与贡献

欢迎提交 Issue 和 Pull Request，一起改进 ChatFloat 的功能、兼容性和使用体验。

提交问题时，建议附上：

• macOS 版本
• Mac 芯片型号
• 复现步骤
• 预期行为与实际行为
• 相关截图或日志（请勿包含账号凭据或隐私信息）

许可证

MIT License

---

ChatFloat — 让 ChatGPT 更方便地融入 macOS 工作流。