73a71f198f
## 当前状态 - 插件界面已完成重命名 (cursorpro → hummingbird) - 双账号池 UI 已实现 (Auto/Pro 卡片) - 后端已切换到 MySQL 数据库 - 添加了 Cursor 官方用量 API 文档 ## 已知问题 (待修复) 1. 激活时检查账号导致无账号时激活失败 2. 未启用无感换号时不应获取账号 3. 账号用量模块不显示 (seamless 未启用时应隐藏) 4. 积分显示为 0 (后端未正确返回) 5. Auto/Pro 双密钥逻辑混乱，状态不同步 6. 账号添加后无自动分析功能 ## 下一版本计划 - 重构数据模型，优化账号状态管理 - 实现 Cursor API 自动分析账号 - 修复激活流程，不依赖账号 - 启用无感时才分配账号 - 完善账号用量实时显示 ## 文件说明 - docs/系统设计文档.md - 完整架构设计 - cursor 官方用量接口.md - Cursor API 文档 - 参考计费/ - Vibeviewer 开源项目参考 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
204 lines
7.9 KiB
Markdown
204 lines
7.9 KiB
Markdown
## Vibeviewer
|
||
|
||
[English](README.md) | 简体中文
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
**标签**: `swift`, `swiftui`, `xcode`, `tuist`, `macos`, `menu-bar`, `release`
|
||
|
||
一个开源的 macOS 菜单栏应用，用来在系统状态栏中快速查看与分享「工作区/团队」的使用与支出概览，并提供登录、设置、自动刷新与分享能力。项目采用模块化的 Swift Package 架构与纯 SwiftUI MV（非 MVVM）范式，专注于清晰的边界与可替换性。
|
||
|
||
### 亮点特性
|
||
- **菜单栏概览**：点击弹窗查看关键指标与最近活动：
|
||
- **计费总览**、**免费额度**（如存在）与 **按需额度**（如存在）
|
||
- **总消耗金额（Total Credits Usage）**，支持数值过渡动画
|
||
- **请求对比（今日 vs 昨日）** 与 **使用事件流水**
|
||
- 顶部快捷操作：**打开 Dashboard**、**退出登录**
|
||
- **登录与设置**：独立的登录与设置窗口，支持持久化凭据与应用偏好。
|
||
- **自动刷新**：基于屏幕电源/活跃状态的智能刷新策略，节能且及时。
|
||
- **模块化架构**：Core ← Model ← API ← Feature 单向依赖，DTO→Domain 映射仅在 API 层完成。
|
||
- **分享组件**：内置字体与图形资源，便捷生成分享视图。
|
||
|
||
### 注意
|
||
- 项目目前仅基于**团队账号**进行开发测试，对于个人会员账号以及 free 版本账号还未经测试，欢迎提交适配与优化。
|
||
- 项目基于模块化分层原则，虽然目前支持 Cursor 作为数据源，对其他相同类型 App 来说，理论上只要实现了数据层的对应方法，即可无缝适配，欢迎 PR。
|
||
- 应用目前没有 Logo，欢迎设计大佬贡献一个 Logo。
|
||
|
||
> 品牌与数据来源仅用于演示。项目不会向 UI 层暴露具体的网络实现，遵循「服务协议 + 默认实现」的封装原则。
|
||
|
||
---
|
||
|
||
## 架构与目录结构
|
||
|
||
项目采用 Workspace + 多个 Swift Packages 的分层设计（单向依赖：Core ← Model ← API ← Feature）：
|
||
|
||
```
|
||
Vibeviewer/
|
||
├─ Vibeviewer.xcworkspace # 打开此工作区进行开发
|
||
├─ Vibeviewer/ # App 外壳（很薄，仅入口）
|
||
├─ Packages/
|
||
│ ├─ VibeviewerCore/ # Core：工具/扩展/通用服务（不依赖业务层）
|
||
│ ├─ VibeviewerModel/ # Model：纯领域实体（值类型/Sendable）
|
||
│ ├─ VibeviewerAPI/ # API：网络/IO + DTO→Domain 映射（对外仅暴露服务协议）
|
||
│ ├─ VibeviewerAppEnvironment/ # 环境注入与跨特性服务入口
|
||
│ ├─ VibeviewerStorage/ # 存储（设置、凭据等）
|
||
│ ├─ VibeviewerLoginUI/ # Feature：登录相关 UI
|
||
│ ├─ VibeviewerMenuUI/ # Feature：菜单栏弹窗 UI（主界面）
|
||
│ ├─ VibeviewerSettingsUI/ # Feature：设置界面 UI
|
||
│ └─ VibeviewerShareUI/ # Feature：分享组件与资源
|
||
└─ Scripts/ & Makefile # Tuist 生成、清理、打包 DMG 的脚本
|
||
```
|
||
|
||
关键原则与约束（强烈建议在提交前阅读 `./.cursor/rules/architecture.mdc`）：
|
||
- **分层与职责**：
|
||
- Core/Shared → 工具与扩展
|
||
- Model → 纯数据/领域实体
|
||
- API/Service → 网络/IO/三方编排以及 DTO→Domain 映射
|
||
- Feature/UI → SwiftUI 视图与交互，仅依赖服务协议和领域模型
|
||
- **依赖方向**：仅允许自上而下（Core ← Model ← API ← Feature），严禁反向依赖。
|
||
- **可替换性**：API 层仅暴露服务协议与默认实现；UI 通过 `@Environment` 注入，不直接引用网络库。
|
||
- **SwiftUI MV 模式**：
|
||
- 使用 `@State`/`@Observable`/`@Environment`/`@Binding` 管理状态
|
||
- 异步副作用使用 `.task`/`.onChange`，自动随视图生命周期取消
|
||
- 不引入默认的 ViewModel 层（避免 MVVM 依赖）
|
||
|
||
---
|
||
|
||
## 开发环境
|
||
|
||
- macOS 14.0+
|
||
- Xcode 15.4+（`SWIFT_VERSION = 5.10`）
|
||
- Tuist（项目生成与管理）
|
||
|
||
安装 Tuist（若未安装）：
|
||
|
||
```bash
|
||
brew tap tuist/tuist && brew install tuist
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
1) 生成 Xcode 工作区：
|
||
|
||
```bash
|
||
make generate
|
||
# 或者
|
||
Scripts/generate.sh
|
||
```
|
||
|
||
2) 打开工作区并运行：
|
||
|
||
```bash
|
||
open Vibeviewer.xcworkspace
|
||
# 在 Xcode 中选择 scheme：Vibeviewer，目标：My Mac（macOS），直接 Run
|
||
```
|
||
|
||
3) 命令行构建/打包（可选）：
|
||
|
||
```bash
|
||
make build # Release 构建（macOS 平台）
|
||
make dmg # 生成 DMG 安装包
|
||
make release # 清理 → 生成 → 构建 → 打包全流程
|
||
make release-full # 完整自动化发版流程（构建 + Tag + GitHub Release）
|
||
```
|
||
|
||
4) 发版流程：
|
||
|
||
详细说明请参考 [Scripts/RELEASE_GUIDE.md](Scripts/RELEASE_GUIDE.md)。
|
||
|
||
快速发版：
|
||
```bash
|
||
./Scripts/release.sh [版本号] # 自动化发版流程
|
||
```
|
||
|
||
---
|
||
|
||
## 运行与调试
|
||
|
||
- 初次运行会在菜单栏显示图标与关键指标，点击打开弹窗查看详细信息。
|
||
- 登录与设置窗口通过依赖注入的窗口管理服务打开（参见 `VibeviewerApp.swift` 中的 `.environment(...)`）。
|
||
- 自动刷新服务将在应用启动与屏幕状态变化时调度执行。
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
各模块包含独立的 Swift Package 测试目标。可在 Xcode 的 Test navigator 直接运行，或使用命令行分别在各包下执行：
|
||
|
||
```bash
|
||
swift test --package-path Packages/VibeviewerCore
|
||
swift test --package-path Packages/VibeviewerModel
|
||
swift test --package-path Packages/VibeviewerAPI
|
||
swift test --package-path Packages/VibeviewerAppEnvironment
|
||
swift test --package-path Packages/VibeviewerStorage
|
||
swift test --package-path Packages/VibeviewerLoginUI
|
||
swift test --package-path Packages/VibeviewerMenuUI
|
||
swift test --package-path Packages/VibeviewerSettingsUI
|
||
swift test --package-path Packages/VibeviewerShareUI
|
||
```
|
||
|
||
> 提示：若新增/调整包结构，请先执行 `make generate` 以确保工作区最新。
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
欢迎 Issue 与 PR！为保持一致性与可维护性，请遵循以下约定：
|
||
|
||
1) 分支与提交
|
||
- 建议使用形如 `feat/short-topic`、`fix/short-topic` 的分支命名。
|
||
- 提交信息尽量遵循 Conventional Commits（如 `feat: add dashboard refresh service`）。
|
||
|
||
2) 架构约定
|
||
- 变更前阅读 `./.cursor/rules/architecture.mdc` 与本 README 的分层说明。
|
||
- 新增类型放置到对应层中：UI/Service/Model/Core，每个文件仅承载一个主要类型。
|
||
- API 层仅暴露「服务协议 + 默认实现」，DTO 仅在 API 内部，UI 层只能看到领域实体。
|
||
|
||
3) 开发自检清单
|
||
- `make generate` 能通过且工作区可成功打开
|
||
- `make build` 通过（或 Xcode Release 构建成功）
|
||
- 相关包的 `swift test` 通过
|
||
- 没有反向依赖或 UI 直接依赖网络实现
|
||
|
||
4) 提交 PR
|
||
- 在 PR 描述中简述变更动机、涉及模块与影响面
|
||
- 如涉及 UI，建议附带截图/录屏
|
||
- 小而聚焦的 PR 更容易被审阅与合并
|
||
|
||
---
|
||
|
||
## 常见问题（FAQ）
|
||
|
||
- Q: Xcode 打不开或 Targets 缺失？
|
||
- A: 先运行 `make generate`（或 `Scripts/generate.sh`）重新生成工作区。
|
||
|
||
- Q: 提示找不到 Tuist 命令？
|
||
- A: 参考上文用 Homebrew 安装 Tuist 后重试。
|
||
|
||
- Q: 构建失败提示 Swift 版本不匹配？
|
||
- A: 请使用 Xcode 15.4+（Swift 5.10）。若升级后仍失败，执行清理脚本 `Scripts/clear.sh` 再 `make generate`。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT License 开源。详情参见 `LICENSE` 文件。
|
||
|
||
---
|
||
|
||
## 致谢
|
||
|
||
感谢所有为模块化 Swift 包架构、SwiftUI 生态与开发者工具做出贡献的社区成员。也感谢你对 Vibeviewer 的关注与改进！
|
||
|
||
UI 灵感来自 X 用户 @hi_caicai 的作品：[Minto: Vibe Coding Tracker](https://apps.apple.com/ca/app/minto-vibe-coding-tracker/id6749605275?mt=12)。
|
||
|
||
|