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.4 KiB
Markdown
204 lines
7.4 KiB
Markdown
## Vibeviewer
|
||
|
||
English | [简体中文](README.zh-CN.md)
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
**Tags**: `swift`, `swiftui`, `xcode`, `tuist`, `macos`, `menu-bar`, `release`
|
||
|
||
An open-source macOS menu bar app that surfaces workspace/team usage and spend at a glance, with sign-in, settings, auto-refresh, and sharing capabilities. The project follows a modular Swift Package architecture and a pure SwiftUI MV (not MVVM) approach, emphasizing clear boundaries and replaceability.
|
||
|
||
### Features
|
||
- **Menu bar summary**: Popover shows key metrics and recent activity:
|
||
- **Billing overview**, **Free usage** (when available), **On‑demand** (when available)
|
||
- **Total credits usage** with smooth numeric transitions
|
||
- **Requests compare (Today vs Yesterday)** and **Usage events**
|
||
- Top actions: **Open Dashboard** and **Log out**
|
||
- **Sign-in & Settings**: Dedicated windows with persisted credentials and preferences.
|
||
- **Power-aware refresh**: Smart refresh strategy reacting to screen power/activity state.
|
||
- **Modular architecture**: One-way dependencies Core ← Model ← API ← Feature; DTO→Domain mapping lives in API only.
|
||
- **Sharing components**: Built-in fonts and assets to generate shareable views.
|
||
|
||
### Notes
|
||
- Currently developed and tested against **team accounts** only. Individual/free accounts are not yet verified — contributions for compatibility are welcome.
|
||
- Thanks to the modular layered design, although Cursor is the present data source, other similar apps can be integrated by implementing the corresponding data-layer interfaces — PRs are welcome.
|
||
- The app currently has no logo — designers are welcome to contribute one.
|
||
|
||
> Brand and data sources are for demonstration. The UI never sees concrete networking implementations — only service protocols and default implementations are exposed.
|
||
|
||
---
|
||
|
||
## Architecture & Structure
|
||
|
||
Workspace with multiple Swift Packages (one-way dependency: Core ← Model ← API ← Feature):
|
||
|
||
```
|
||
Vibeviewer/
|
||
├─ Vibeviewer.xcworkspace # Open this workspace
|
||
├─ Vibeviewer/ # Thin app shell (entry only)
|
||
├─ Packages/
|
||
│ ├─ VibeviewerCore/ # Core: utilities/extensions/shared services
|
||
│ ├─ VibeviewerModel/ # Model: pure domain entities (value types/Sendable)
|
||
│ ├─ VibeviewerAPI/ # API: networking/IO + DTO→Domain mapping (protocols exposed)
|
||
│ ├─ VibeviewerAppEnvironment/ # Environment injection & cross-feature services
|
||
│ ├─ VibeviewerStorage/ # Storage (settings, credentials, etc.)
|
||
│ ├─ VibeviewerLoginUI/ # Feature: login UI
|
||
│ ├─ VibeviewerMenuUI/ # Feature: menu popover UI (main)
|
||
│ ├─ VibeviewerSettingsUI/ # Feature: settings UI
|
||
│ └─ VibeviewerShareUI/ # Feature: sharing components & assets
|
||
└─ Scripts/ & Makefile # Tuist generation, clean, DMG packaging
|
||
```
|
||
|
||
Key rules (see also `./.cursor/rules/architecture.mdc`):
|
||
- **Placement & responsibility**
|
||
- Core/Shared → utilities & extensions
|
||
- Model → pure domain data
|
||
- API/Service → networking/IO/3rd-party orchestration and DTO→Domain mapping
|
||
- Feature/UI → SwiftUI views & interactions consuming service protocols and domain models only
|
||
- **Dependency direction**: Core ← Model ← API ← Feature (no reverse dependencies)
|
||
- **Replaceability**: API exposes service protocols + default impl; UI injects via `@Environment`, never references networking libs directly
|
||
- **SwiftUI MV**:
|
||
- Use `@State`/`@Observable`/`@Environment`/`@Binding` for state
|
||
- Side effects in `.task`/`.onChange` (lifecycle-aware cancellation)
|
||
- Avoid default ViewModel layer (no MVVM by default)
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- macOS 14.0+
|
||
- Xcode 15.4+ (`SWIFT_VERSION = 5.10`)
|
||
- Tuist
|
||
|
||
Install Tuist if needed:
|
||
|
||
```bash
|
||
brew tap tuist/tuist && brew install tuist
|
||
```
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
1) Generate the Xcode workspace:
|
||
|
||
```bash
|
||
make generate
|
||
# or
|
||
Scripts/generate.sh
|
||
```
|
||
|
||
2) Open and run:
|
||
|
||
```bash
|
||
open Vibeviewer.xcworkspace
|
||
# In Xcode: scheme = Vibeviewer, destination = My Mac (macOS), then Run
|
||
```
|
||
|
||
3) Build/package via CLI (optional):
|
||
|
||
```bash
|
||
make build # Release build (macOS)
|
||
make dmg # Create DMG package
|
||
make release # Clean → Generate → Build → Package
|
||
make release-full # Full automated release (build + tag + GitHub release)
|
||
```
|
||
|
||
4) Release process:
|
||
|
||
See [Scripts/RELEASE_GUIDE.md](Scripts/RELEASE_GUIDE.md) for detailed release instructions.
|
||
|
||
Quick release:
|
||
```bash
|
||
./Scripts/release.sh [VERSION] # Automated release workflow
|
||
```
|
||
|
||
---
|
||
|
||
## Run & Debug
|
||
|
||
- The menu bar shows the icon and key metrics; click to open the popover.
|
||
- Sign-in and Settings windows are provided via environment-injected window managers (see `.environment(...)` in `VibeviewerApp.swift`).
|
||
- Auto-refresh starts on app launch and reacts to screen power/activity changes.
|
||
|
||
---
|
||
|
||
## Testing
|
||
|
||
Each package ships its own tests. Run from Xcode or via CLI per package:
|
||
|
||
```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
|
||
```
|
||
|
||
> Tip: after adding/removing packages, run `make generate` first.
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
Issues and PRs are welcome. To keep the codebase consistent and maintainable:
|
||
|
||
1) Branch & commits
|
||
- Use branches like `feat/...` or `fix/...`.
|
||
- Prefer Conventional Commits (e.g., `feat: add dashboard refresh service`).
|
||
|
||
2) Architecture agreements
|
||
- Read `./.cursor/rules/architecture.mdc` and this README before changes.
|
||
- Place new code in the proper layer (UI/Service/Model/Core). One primary type per file.
|
||
- API layer exposes service protocols + default impl only; DTOs stay internal; UI uses domain models only.
|
||
|
||
3) Self-check
|
||
- `make generate` works and the workspace opens
|
||
- `make build` succeeds (or Release build in Xcode)
|
||
- `swift test` passes for related packages
|
||
- No reverse dependencies; UI never imports networking implementations
|
||
|
||
4) PR
|
||
- Describe motivation, touched modules, and impacts
|
||
- Include screenshots/clips for UI changes
|
||
- Prefer small, focused PRs
|
||
|
||
---
|
||
|
||
## FAQ
|
||
|
||
- Q: Missing targets or workspace won’t open?
|
||
- A: Run `make generate` (or `Scripts/generate.sh`).
|
||
|
||
- Q: Tuist command not found?
|
||
- A: Install via Homebrew as above.
|
||
|
||
- Q: Swift version mismatch during build?
|
||
- A: Use Xcode 15.4+ (Swift 5.10). If issues persist, run `Scripts/clear.sh` then `make generate`.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is open-sourced under the MIT License. See `LICENSE` for details.
|
||
|
||
---
|
||
|
||
## Acknowledgements
|
||
|
||
Thanks to the community for contributions to modular Swift packages, SwiftUI, and developer tooling — and thanks for helping improve Vibeviewer!
|
||
|
||
UI inspiration from X user @hi_caicai — see [Minto: Vibe Coding Tracker](https://apps.apple.com/ca/app/minto-vibe-coding-tracker/id6749605275?mt=12).
|
||
|
||
|