蜂鸟Pro v2.0.1 - 基础框架版本 (待完善)

## 当前状态 - 插件界面已完成重命名 (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>
2025-12-18 11:21:52 +08:00
parent f310ca7b97
commit 73a71f198f
202 changed files with 19142 additions and 252 deletions
--- a/参考计费/README.md
+++ b/参考计费/README.md
@@ -0,0 +1,203 @@
+## Vibeviewer
+
+English | [简体中文](README.zh-CN.md)
+
+![Swift](https://img.shields.io/badge/Swift-5.10-orange?logo=swift)
+![Xcode](https://img.shields.io/badge/Xcode-15.4%2B-blue?logo=xcode)
+![macOS](https://img.shields.io/badge/macOS-14%2B-black?logo=apple)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Release](https://img.shields.io/badge/Release-DMG-purple)
+
+![Preview](Images/image.png)
+
+**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).
+
+