Vorssaint: Bộ tiện ích menu bar macOS Native

Tóm tắt nhanh

Vorssaint là bộ tiện ích hệ thống macOS native theo định hướng local-first, phát hành theo giấy phép GPL-3.0-or-later tại kho lưu trữ vorssaint/vorssaint-utils (tên gọi và nhận diện thương hiệu được bảo hộ riêng theo TRADEMARKS.md). Được viết bằng Swift và C cho máy Mac Apple Silicon chạy macOS 14 Sonoma trở lên, Vorssaint hợp nhất 80 module (AppFeature) thuộc 8 nhóm công cụ: bộ trộn âm lượng từng ứng dụng hỗ trợ boost 200% không cần audio driver, giám sát phần cứng kèm điều khiển quạt qua XPC, quản lý cửa sổ và Dock, tùy biến chuột/bàn phím HID, lịch sử clipboard, chụp/quay màn hình kèm OCR ngoại tuyến, và Dynamic Island theo dõi các AI agent cục bộ (Claude Code, Codex, OpenCode, GitHub Copilot).

Nhờ liên kết closure khởi tạo trễ trong Sources/Vorssaint/App/FeatureRuntime.swift, các tính năng đã gỡ không tiêu tốn bộ nhớ hay đánh thức CPU. Hạn chế chính: bắt buộc chip Apple Silicon (arm64-apple-macosx14.0), trộn âm lượng từng ứng dụng cần macOS 14.4+, Fan Control đang ở bản beta, và Mic Mute chỉ là phím tắt điều khiển đầu vào chứ không phải khóa bảo mật phần cứng.

Bài toán phân mảnh tiện ích trên thanh menu macOS

Để thiết lập một môi trường làm việc hiệu quả trên macOS, lập trình viên và người dùng chuyên nghiệp thường phải mua hoặc cài đặt hàng chục ứng dụng đơn năng riêng lẻ: một ứng dụng để chỉnh âm lượng từng phần mềm, một công cụ chia bố cục cửa sổ và xem trước cửa sổ trên Dock, một phần mềm theo dõi nhiệt độ CPU/GPU và chỉnh tốc độ quạt, một trình đảo chiều cuộn chuột và gán phím tắt chuột, cùng hàng loạt tiện ích cho lịch sử clipboard, khu vực tai thỏ (Notch) và chụp màn hình.

Việc duy trì mười tiến trình chạy nền độc lập gây ra nhiều hệ lụy kỹ thuật rõ rệt:

• Trùng lặp Event Tap và đánh thức CPU (Wakeups): Nhiều ứng dụng cùng đăng ký CGEventTap và IOHIDManager độc lập, làm nhân lên số lần chuyển ngữ cảnh (context switch) ở mỗi thao tác gõ phím hoặc lăn chuột.
• Rác hệ thống từ Virtual Audio Driver: Các bộ trộn âm lượng truyền thống thường cài đặt plugin HAL ảo của bên thứ ba vào /Library/Audio/Plug-Ins/HAL, dễ để lại thiết bị âm thanh “ma” khi gỡ cài đặt không sạch hoặc sau khi nâng cấp hệ điều hành.
• Phình đại quyền hạn TCC và Telemetry: Mỗi ứng dụng riêng lẻ đều yêu cầu quyền Accessibility, Screen Recording hoặc Full Disk Access, đồng thời nhúng kèm SDK phân tích hành vi, trình gửi báo cáo lỗi tự động hoặc cơ chế kiểm tra thuê bao định kỳ.

Qua rà soát mã nguồn tĩnh (static source inspection) ở phiên bản 3.4.3, Vorssaint giải quyết sự phân mảnh này bằng cách đóng gói 80 công cụ độc lập vào một binary native duy nhất (com.vorssaint.utils), biên dịch trực tiếp bằng Xcode Command Line Tools thông qua script build.sh mà không phụ thuộc vào bất kỳ gói thư viện Swift bên ngoài nào, không yêu cầu tài khoản và không thu thập telemetry.

[Mô hình cài đặt rời rạc truyền thống trên macOS]
  ├── App trộn âm lượng riêng ──────> Cài đặt HAL audio driver ảo vào /Library/Audio
  ├── Tiện ích cửa sổ & Dock ───────> Tạo thêm CGEventTap và bộ đếm Screen Recording trùng lặp
  ├── App theo dõi nhiệt độ & quạt ─> Chạy daemon riêng để đọc cảm biến SMC & Mach VM
  └── Công cụ AI Usage & Clipboard ─> Tốn nhiều icon menu bar, tài khoản & SDK theo dõi

========================================== VS ==========================================

[Kiến trúc Mô-đun Đơn Binary của Vorssaint]
  ├── Lazy FeatureRuntime ─────────> Tính năng đã gỡ được bỏ qua hoàn toàn khi khởi chạy
  ├── CoreAudio Process Taps ──────> Chỉnh âm lượng từng app & boost 200% trên macOS 14.4+
  ├── Cầu nối C/Swift thống nhất ──> Dùng chung VMStatisticsCompat, HIDEventSystem & cgif
  ├── Dynamic Island AI Telemetry ─> Đọc log cục bộ của Claude, Codex, OpenCode & Copilot
  └── Quản lý quyền TCC theo nhu cầu -> Chỉ kiểm tra quyền khi cần & cảnh báo quyền dư thừa

Kiến trúc FeatureRuntime khởi tạo trễ: “chỉ cài những gì bạn dùng”

Một bộ công cụ gồm 80 tính năng sẽ trở nên cồng kềnh nếu mọi dịch vụ đều tự khởi tạo khi mở máy. Vorssaint khắc phục triệt để vấn đề này bằng cách tách biệt tầng khả dụng (availability)—quyết định một tính năng có được cài đặt trong Features Hub hay không—khỏi tầng kích hoạt (enablement) của từng tính năng.

Tại Sources/Vorssaint/Core/FeatureCatalog.swift, kiểu liệt kê AppFeature định nghĩa 80 tính năng được phân bổ vào 8 nhóm FeatureGroup:

Trong Sources/Vorssaint/App/FeatureRuntime.swift, mỗi liên kết tính năng được khai báo dưới dạng một closure thay vì khởi tạo sẵn các đối tượng singleton. Khi hàm syncAtLaunch() thực thi lúc mở ứng dụng, toàn bộ các tính năng đang ở trạng thái không khả dụng sẽ bị bỏ qua—đồng nghĩa với việc dịch vụ của chúng không bao giờ được cấp phát trong bộ nhớ hay gắn bộ lắng nghe sự kiện.

Ở lần cài đặt mới đầu tiên, hàm FeaturePreset.prepareFirstRunAvailability() trong Sources/Vorssaint/Core/FeaturePresets.swift chỉ bật sẵn gói .essential gồm 8 tính năng cơ bản (mixer, keepAwake và 6 chỉ số giám sát hệ thống) trước khi các closure chạy. Người dùng có thể chuyển đổi nhanh giữa 3 gói cấu hình mẫu (.essential, .windows, .battery) hoặc bật/tắt từng tính năng riêng lẻ. Mỗi tính năng trong Hub đều gắn nhãn FeatureEnergyProfile minh bạch (idle, mouse, pointer, keyboard, inputs hoặc periodic) để phản ánh chính xác tài nguyên mà tính năng đó giữ hoạt động khi bật.

Nếu người dùng gỡ một tính năng đã được nạp trong phiên hiện tại, FeatureRuntime sẽ ngắt dịch vụ ngay lập tức và bật cờ needsRestartToUnload = true. Khi chọn khởi động lại ứng dụng, hàm relaunchApp() khởi chạy một tiến trình /bin/sh tách rời qua DetachedProcess.spawn, chờ tối đa 20 giây (kill -0) để tiến trình chính ghi xong lịch sử clipboard và cấu hình xuống đĩa rồi mới mở lại phiên bản sạch không chứa các singleton cũ.

Bộ trộn âm lượng CoreAudio không cần driver và thuật toán Lookahead Limiter

macOS mặc định không cung cấp thanh trượt âm lượng riêng cho từng ứng dụng. Thay vì cài đặt kernel extension hoặc driver âm thanh HAL ảo, Sources/Vorssaint/Services/Audio/AppVolumeMixer.swift khai thác trực tiếp API CoreAudio process tap có mặt từ macOS 14.4 (AudioHardwareCreateProcessTap và CATapDescription).

1. Tương thích động cho các bản macOS Sonoma 14.0–14.3

Dù header SDK của Apple đánh dấu các hàm khởi tạo tiện ích của CATapDescription khả dụng từ macOS 14.0, các bản Sonoma đời đầu (14.0 đến 14.3) thực tế lại thiếu các symbol Swift này, dễ gây lỗi sập ứng dụng ngay khi khởi chạy (dyld symbol crash). Vorssaint xử lý vấn đề này trong Sources/CoreAudioTapCompat/include/CoreAudioTapCompat.h bằng cách tra cứu lớp Objective-C động qua NSClassFromString(@"CATapDescription") bên trong hàm inline được bảo vệ bởi API_AVAILABLE(macos(14.4)):

// Sources/CoreAudioTapCompat/include/CoreAudioTapCompat.h (kiểm tra mã nguồn tĩnh)
static inline CATapDescription * _Nullable VorssaintPrivateTapDescription(
    VorssaintTapMode mode, NSArray<NSNumber *> *processes, NSString * _Nullable deviceUID,
    NSString * _Nullable name, CATapMuteBehavior muteBehavior)
    API_AVAILABLE(macos(14.4)) {
    Class tapClass = NSClassFromString(@"CATapDescription");
    // Khởi tạo động stereo mixdown, global-excluding hoặc device stream tap

Khi người dùng thay đổi âm lượng của một ứng dụng khác mức 1.0 (100%) hoặc định tuyến âm thanh của ứng dụng đó sang thiết bị đầu ra riêng (bao gồm cả phát AirPlay riêng cho từng ứng dụng qua AirPlayRouteManager.swift), AppVolumeMixer sẽ tạo một process tap tắt tiếng gốc (privateTap = YES) để tách âm thanh khỏi đầu ra mặc định, sau đó kết xuất lại luồng âm thanh qua một aggregate device với mức khuếch đại mong muốn (0.0 đến 2.0, tương đương 0%–200%). Các ứng dụng đang phát ở mức 100% trên thiết bị mặc định hoàn toàn không bị can thiệp.

2. Chống vỡ tiếng ở mức 200% với BoostLimiter không cấp phát bộ nhớ

Khi khuếch đại nguồn âm thanh nhỏ lên tới 200% (AppVolumeMixer.maxVolume = 2.0), các đỉnh sóng âm lớn sẽ vượt ngưỡng toàn thang (1.0). Nếu chỉ cắt ngọn (hard clamp) từng mẫu âm thanh, tín hiệu sẽ bị bẹt đỉnh và gây tiếng rè gắt (issue #326). Trong Sources/Vorssaint/Services/Audio/BoostLimiter.swift, cấu trúc BoostLookaheadLimiter và BoostLimiter triển khai bộ giới hạn đỉnh nhìn trước (lookahead peak limiter) ngay trên luồng âm thanh thời gian thực:

• Zero-Allocation trên luồng Realtime: Hàm process(_:frames:release:) xử lý trực tiếp trên UnsafeMutableAudioBufferListPointer mà không cấp phát bộ nhớ heap.
• Giảm khuếch đại đồng bộ đa kênh: Toàn bộ các kênh trong cùng một khung âm thanh dùng chung một hệ số giảm gain tính theo ngưỡng BoostLimiter.ceiling, hạ mượt qua cửa sổ trễ BoostLookaheadLimiter.lookaheadFrames và phục hồi theo hàm mũ khi tín hiệu nhỏ dần, giữ nguyên âm hình stereo mà không làm méo tiếng.

Cầu nối C cấp thấp, adapter Perl cho MediaRemote và điều khiển quạt qua XPC

Kiểm tra Package.swift và build.sh cho thấy cách Vorssaint giao tiếp với các tầng hệ thống sâu của macOS mà không cần thư viện bên thứ ba:

• Thống kê bộ nhớ Mach VM rev3 (Sources/VMStatisticsCompat/include/VMStatisticsCompat.h): Định nghĩa cấu trúc C vorssaint_vm_statistics64_rev3_t (kích thước 248 byte, căn chỉnh 64-bit) kèm hàng loạt kiểm tra _Static_assert ở thời điểm biên dịch nhằm khớp chính xác bố cục ABI của vm_statistics64_data_t. Nhờ đó, hàm vorssaint_read_vm_statistics64() đọc được cả các trường bộ nhớ gắn thẻ (tagged storage) mới trên macOS 26 (HOST_VM_INFO64 rev3) lẫn các nhân Sonoma/Sequoia cũ hơn, đồng thời giải phóng cổng Mach host ngay sau mỗi lần gọi.
• Vượt rào cản chữ ký MediaRemote trên macOS 15.4+ (Sources/NowPlayingAdapter/NowPlayingAdapter.swift): Từ macOS 15.4, framework MediaRemote từ chối trả về thông tin bài hát đang phát (MRMediaRemoteGetNowPlayingInfo) nếu tiến trình gọi không mang chữ ký platform của chính Apple. Vorssaint biên dịch NowPlayingAdapter.swift thành một thư viện động được ký riêng (Contents/Frameworks/libVorssaintNowPlaying.dylib) và nạp nó vào /usr/bin/perl (binary có chữ ký platform của Apple) thông qua module DynaLoader trong Resources/now-playing.pl. Adapter này giới hạn ảnh bìa giải mã ở mức 12 MiB (maximumArtworkBytes = 12 * 1_024 * 1_024) và lọc bỏ các giá trị số thực NaN hoặc Inf trước khi xuất chuỗi JSON trên một dòng duy nhất.
• Helper XPC có đặc quyền cho điều khiển quạt (Sources/FanControlHelper/main.swift): Tính năng chỉnh tốc độ quạt và biểu đồ nhiệt (đang ở bản beta) hoạt động thông qua dịch vụ LaunchServices chạy quyền root (com.vorssaint.utils.fan-control). Tiến trình helper bắt buộc xác thực chữ ký ứng dụng mẹ qua listener.setConnectionCodeSigningRequirement(FanControlIdentifiers.appCodeRequirement), khóa tệp /var/run/vorssaint-fan-control.lock (0600) với cờ O_NOFOLLOW, mã hóa giá trị SMC định dạng flt qua SMCValueCodec, yêu cầu tín hiệu heartbeat định kỳ từ ứng dụng, và tự động trả quyền điều khiển quạt tự động về cho hệ thống khi nhận tín hiệu tắt (SIGTERM/SIGINT) hoặc mất kết nối trước khi tự thoát sau 1 giây nhàn rỗi.

Theo dõi AI Agent cục bộ ngay trên Dynamic Island

Một tính năng đặc biệt hữu ích cho giới lập trình viên là module notchAgents (Sources/Vorssaint/Services/AgentUsage/), biến khu vực camera cutout trên MacBook (hoặc vùng Dynamic Island mô phỏng trên màn hình rời) thành bảng điều khiển theo dõi thời gian thực cho 4 công cụ lập trình AI: Claude Code, Codex, OpenCode và GitHub Copilot.

Trong Sources/Vorssaint/Services/AgentUsage/AgentUsageService.swift và Harness/AgentHarnessReader.swift, bốn bộ đọc chuyên biệt (ClaudeReader, CodexReader, OpenCodeReader, CopilotReader) phân tích gia tăng (incremental parsing) các tệp nhật ký phiên làm việc và cơ sở dữ liệu cục bộ trong phạm vi 13 tuần (91 ngày):

• Đọc gia tăng theo con trỏ byte (AgentLogCursor): AgentUsageService ghi nhớ vị trí byte đã đọc của từng tệp log, kiểm tra mỗi 2 giây đối với các phiên đang hoạt động (có ghi dữ liệu trong 30 phút gần nhất) và gộp các đợt cập nhật giao diện với độ trễ 1 giây. Nội dung câu lệnh (prompt) gốc không bao giờ bị sao chép hay tải lên mạng; chỉ các bộ đếm token và chi phí ước tính mới được lưu cục bộ mỗi 5 phút.
• Đa tài khoản CODEX_HOME và Banked Resets (CodexProfileLimitsService.swift, AgentCodexResetService.swift): Lập trình viên sử dụng nhiều thư mục cấu hình Codex (CODEX_HOME, ví dụ ~/.codex-*) có thể gắn thẻ hạn mức riêng cho từng tài khoản trên Dynamic Island và kích hoạt lượt đặt lại hạn mức dự trữ (banked resets) sau khi xác nhận. Trước mỗi lần kiểm tra, Vorssaint chỉ xác minh quyền sở hữu thư mục và quyền tệp auth.json hoặc config.toml chứ không bao giờ đọc khóa xác thực bên trong.
• Chuyển đổi hồ sơ Claude Code (ClaudeAccountProfile.swift, AgentClaudeServer.swift): Hỗ trợ theo dõi ~/.claude, ~/.claude-* hoặc ~/.config/claude thông qua biến môi trường CLAUDE_CONFIG_DIR, chuyển tiếp đúng 7 biến môi trường proxy và cờ tắt telemetry từ settings.json mà không đọc token đăng nhập Anthropic và không kích hoạt MCP server hay hook của người dùng trong lúc kiểm tra hạn mức.

Kiến trúc quyền riêng tư, kiểm soát TCC và quy tắc sudoers theo UID

Toàn bộ cơ chế bảo vệ dữ liệu và kết nối mạng của Vorssaint được công bố chi tiết trong docs/PRIVACY.md và docs/PERMISSIONS.md:

1. Kiểm tra quyền TCC theo nhu cầu thực tế (Sources/Vorssaint/Core/Permissions.swift): Hàm PermissionPollingSupport.interval() chỉ kiểm tra trạng thái Accessibility và Screen Recording mỗi 2.5 giây khi bảng hướng dẫn quyền đang mở hoặc khi một tính năng đang bật bị thiếu quyền, giảm tần suất xuống 60 giây khi đã được cấp quyền, và trả về nil (dừng hẳn bộ đếm chạy nền) khi không có tính năng nào cần đến. Quyền Full Disk Access hoàn toàn không bị quét ngầm. Đặc biệt, nếu bạn gỡ bỏ tính năng cuối cùng sử dụng một quyền macOS đã cấp trước đó, trang Settings sẽ hiển thị cảnh báo quyền dư thừa kèm lối tắt để thu hồi ngay.
2. Quy tắc sudoers định danh bằng UID số học (Sources/Vorssaint/Services/SudoersSupport.swift): Chế độ chống ngủ khi gập màn hình (Closed-lid Keep Awake) sử dụng lệnh /usr/bin/pmset disablesleep. Để tránh hỏi mật khẩu quản trị nhiều lần mà vẫn ngăn chặn nguy cơ lỗi cú pháp hoặc tiêm ký tự đặc biệt trên các máy Mac doanh nghiệp dùng địa chỉ email SSO làm tên người dùng (issue #915), hàm SudoersSupport.clamshellRule(uid:) ràng buộc quy tắc NOPASSWD trực tiếp vào UID số nguyên của người dùng:#501 ALL=(root) NOPASSWD: /usr/bin/pmset disablesleep 1, /usr/bin/pmset disablesleep 0
3. Băm tiền tố tìm kiếm có khóa trong Command Bar (Sources/Vorssaint/Services/CommandBar/CommandBarQueryMemory.swift): Để ghi nhớ thói quen chọn ứng dụng hoặc emoji theo tiền tố gõ phím qua các lần khởi động lại mà không lưu văn bản tìm kiếm thuần, Command Bar giới hạn bảng nhớ tạm trong phiên (queryLimit = 60, idsPerQuery = 4, longestPrefix = 12) và chỉ lưu mã băm có khóa (keyed digests) xuống đĩa. Cả mã băm học được lẫn khóa cục bộ đều bị loại trừ khỏi tệp sao lưu cấu hình trong Sources/Vorssaint/Core/SettingsBackupSupport.swift.
4. 13 luồng kết nối mạng minh bạch: Ứng dụng chỉ chạm tới mạng khi người dùng kích hoạt tính năng tương ứng—chẳng hạn kiểm tra bản cập nhật trên GitHub, đo tốc độ mạng qua speed.cloudflare.com, chạy lệnh brew, tạo liên kết chia sẻ ảnh chụp (tự hủy sau 1/6/24 giờ) hoặc video quay màn hình (1/6 giờ) đã xóa sạch metadata gốc, tra cứu lời bài hát qua LRCLIB/MusicBrainz, hoặc tải bảng giá mô hình AI công khai từ raw.githubusercontent.com tối đa mỗi ngày một lần bằng phiên tạm thời không lưu cookie và từ chối chuyển hướng (redirect).

Cài đặt, tự biên dịch từ mã nguồn và tiêu chí lựa chọn

Lưu ý xác minh: Các lệnh dưới đây được đối chiếu từ README.md, CONTRIBUTING.md, build.sh và Sources/Vorssaint/main.swift ở phiên bản 3.4.3 bằng phương pháp kiểm tra mã nguồn tĩnh; chưa thực thi trực tiếp trên máy host trong phạm vi bài viết này.

Yêu cầu hệ thống và cài đặt

Vorssaint yêu cầu máy Mac dùng chip Apple Silicon (arm64) chạy macOS 14 Sonoma trở lên (riêng bộ trộn âm lượng từng ứng dụng qua CoreAudio process tap cần macOS 14.4+). Các bản phát hành chính thức được ký bằng Apple Developer ID và công chứng (notarized):

# Cài đặt bản phát hành đã ký và công chứng qua Homebrew Cask
brew install --cask vorssaint

# Xuất hoặc nhập tệp sao lưu cấu hình (bao gồm cả text snippets) qua CLI
/Applications/Vorssaint.app/Contents/MacOS/Vorssaint --export-settings ~/vorssaint-backup.json
/Applications/Vorssaint.app/Contents/MacOS/Vorssaint --import-settings ~/vorssaint-backup.json

Tự biên dịch bản Developer song song từ mã nguồn

Quá trình biên dịch chỉ yêu cầu Xcode Command Line Tools (build.sh gọi trực tiếp trình biên dịch Swift/C và đóng gói ứng dụng trong thư mục tạm bên ngoài ~/Documents để tránh các thuộc tính mở rộng của File Provider như com.apple.provenance làm hỏng chữ ký codesign):

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils

# Biên dịch bản "Vorssaint (Developer)" độc lập (bundle ID: com.vorssaint.utils.dev)
./build.sh --dev

# Chạy kiểm tra tự chẩn đoán (selftest), xuất danh sách cảm biến và chạy bộ test
./build/VorssaintDeveloper --selftest
./build/VorssaintDeveloper --sensors
./build.sh --test

# Gỡ cài đặt toàn diện ứng dụng, fan helper, quyền TCC, quy tắc sudoers và journal của Dock
./Tools/uninstall.sh

Khi nào nên chọn Vorssaint và khi nào cần giải pháp khác

• Nên chọn Vorssaint khi: Bạn sử dụng máy Mac Apple Silicon chạy macOS 14+ và muốn thay thế hàng loạt ứng dụng trả phí rời rạc (trộn âm lượng, chia cửa sổ, giám sát phần cứng, quản lý clipboard, tiện ích Dynamic Island và theo dõi hạn mức AI agent) bằng một ứng dụng native GPL-3.0 duy nhất, không cài đặt audio driver ảo và tự động ngắt hoàn toàn các module không sử dụng.
• Nên cân nhắc giải pháp khác khi: Bạn đang dùng máy Mac chip Intel (x86_64) hoặc macOS 13 Ventura trở xuống; bạn cần chuỗi xử lý âm thanh chuyên sâu với bộ lọc EQ tham số đa băng tần và plugin VST/AU (nơi các phần mềm chuyên dụng như SoundSource phù hợp hơn); hoặc bạn muốn phân phối lại bản dựng đã chỉnh sửa dưới tên thương hiệu gốc (điều bị giới hạn bởi TRADEMARKS.md).