浮動時鐘
不搶焦點、所有桌面都看得到,會盯 Claude 用量的專注時鐘
Swift 原生 macOS App ・ 11/21 規劃 → 當晚 22:21 排程開工 → 30 分 31 秒交付
§ 01 ・ 亮點
規劃時估 3–4 小時,
排程實作 30 分 31 秒 交付。
三期一次做完,交付時 10 項驗收過 7 項;另外 3 項沒實測,照實標「未驗證」(見 § 13)。
實際時間取自排程 session 的起訖時間(22:21:34 → 22:52:05)。3–4 小時是規劃當下的人工估計(第 1 期約 2 小時+第 2 期約 1.5 小時+第 3 期),不是量出來的。
§ 02 ・ 一頁摘要
沒時間的話,看這頁就好
一個浮在所有視窗上的時鐘:倒數、番茄、碼錶、鬧鐘,加上 Claude 5 小時額度列。
桌面版 Claude 看不到額度倒數;現成 App 接不上 mini、手機推播和熱鍵。
補完 3 項實機驗證(約 10 分鐘),用滿一週再看統計決定要不要調整。
§ 03 ・ 起點
靈感:一則 Threads 貼文
「請 Claude 幫我生成一款漂浮時鐘……功能都是我上課用得到的。」
- 大字時鐘、日期、星期
- 10–60 秒倒數鈕
- 鎖定、縮放、開始、齒輪
- 今日完成幾個番茄
- 外型沿用,用途改掉
- 分鐘級預設(5/10/15/25/50)
- Claude 5 小時額度列
- 手機推播、熱鍵、紀錄
原貼文只看得到截圖,看不出原作用什麼技術做的。
§ 04 ・ 背景
網路上明明就有,為什麼還要自己做?
看不到 Claude 額度
桌面版 Claude Code 不跑終端機狀態列,5 小時視窗的倒數平常只存在 mini 的監控程式裡。
現成 App 接不上
mini 的用量快取、Pushover 手機推播、Hammerspoon 熱鍵(BindKey),三樣都接不上。
動畫很耗電
11/18 實測:一個動畫背景讓 Claude 多吃約 56% CPU,整台電腦多耗約 7W。新工具必須幾乎不耗電。
自己做的價值不在時鐘本身,在於能接上自己原本就有的系統。
§ 05 ・ 目標
成功的標準:五條驗收線
不搶焦點
點它、按熱鍵,正在打字的 App 都不會被推到背景。
到處都在
每個桌面、全螢幕 App 上都看得到;不出現在 Mission Control。
幾乎不耗電
每秒最多更新一次,不跑連續動畫。
數字不說謊
拿不到用量就顯示「等 mini」,不顯示假數字。
資料留得住
每次計時寫一行紀錄,日後可以接人生 Dashboard。
§ 06 ・ 市場調查
網路上確實有:比對了 14 款
浮在桌面上的倒數很普遍。最右邊三欄,現成的都沒有。
| App | 浮動置頂 | 超時續數 | 圓盤/色塊 | 多組計時 | Claude 額度 | 手機推播 | 自訂熱鍵 |
|---|---|---|---|---|---|---|---|
| TinyTimekeeper | — | — | — | — | — | — | |
| PinnedTimer | — | — | — | — | — | — | |
| ClyTimer | — | — | — | — | — | ||
| Countdown Timer Pro | — | — | — | — | — | — | |
| Time Timer | — | — | — | — | — | — | |
| Aestu | — | — | — | — | — | ||
| 浮動時鐘 |
● 表示上架頁有寫;— 表示上架頁沒提,不代表沒有這功能。依各 App 的 App Store 頁面整理,沒有實際安裝測試。另比對了 Top Clock、ABTimer、MeetingBar、Soonie、EDUwidgets、Classroomscreen,以及 2 個開源專案。
§ 07 ・ 借鏡
借來的 5 個點子,各自怎麼做
超時續數
歸零後不停,顯示「+02:13」並變紅。
圓盤/色塊
數字、圓盤、色塊三選一,放在設定裡切換。
現在在做什麼
點一下打字,按 Enter 存。
多組計時
最多 3 組,預設關閉。
行程倒數
暫不做:接行事曆會讓功能變複雜,反而失焦。
§ 08 ・ 技術路線
三條路,選了最穩的那條
| 做法 | 得到 | 失去 | 當時估的第 1 期工時 |
|---|---|---|---|
| Swift 原生 App 採用 | 獨立程式,Hammerspoon 重新載入也不會中斷倒數;全螢幕與滑鼠穿透最乾淨 | 多一個要編譯的專案 | 約 2 小時 |
| Hammerspoon 模組 | 最快,熱鍵直接接 | Hammerspoon 一重新載入,倒數就斷 | 約 1 小時 |
| 直接裝現成 App | 2 分鐘就有 | 接不上用量、推播、熱鍵 | 2 分鐘 |
第三條路:App 用 Swift 原生做,再開一個 floatclock:// 網址給 Hammerspoon 熱鍵呼叫。程式穩定,也接得上既有的熱鍵系統。
§ 09 ・ 決策
使用者拍板的四個取捨
不砍,放進設定讓使用者選
例:剩餘時間用數字、圓盤或色塊顯示。
留著,但平常藏起來
10–60 秒的按鈕平常看不到;按住 ⌥ 點齒輪才會出現。平常不干擾,要用時多點一下就有。
行事曆、Things 3 都不接
原話:接行事曆「會把功能複雜化,反而失焦」。
三期一次做完,排程到 22:21
當時 token 快用完,所以先把規格寫好,排程晚上自動開工。
§ 10 ・ 流程
十個步驟:從截圖到修正
黃框是關鍵:規劃和實作分開,中間只靠一份規格書交接。
§ 11 ・ 邏輯
為什麼要先寫規格書,再排程?
排程開工的是一個全新的對話,看不到前面的討論。所有決定都要寫進 規格.md,否則就會遺失。
排程的指示只有三句:先讀完規格、照著做、照驗證清單逐條驗收;沒驗到的就老實寫「未驗證」。
- 做法(已拍板)
- 視窗行為
- 顯示
- 倒數
- 結束提醒
- 番茄
- Claude 用量列
- 熱鍵
- 紀錄與統計
- 不做(行事曆、Things 3…)
- 驗證清單
§ 12 ・ 實作
三期,一次做完
面板與倒數
- 浮動面板、時鐘、日期
- 分鐘預設、開始/暫停/重設
- 超時續數,數字/圓盤/色塊
- 番茄、提醒、設定頁
串接既有系統
- floatclock:// 網址+5 個熱鍵
- Pushover 手機推播
- JSONL 計時紀錄
- Claude 用量列
統計
- 今日/本週專注時間
- 番茄數、平均超時
- 最近 7 天長條
- 重開 App 後計時接著跑
§ 13 ・ 架構
資料怎麼流
§ 14 ・ 邏輯
「不搶焦點、到處都在」是怎麼做到的
| 需求 | 設定 | 白話 |
|---|---|---|
| 點了不搶焦點 | nonactivatingPanel | 可以打字,但不會把正在用的 App 推到背景 |
| 每個桌面都在 | canJoinAllSpaces | 切換桌面時跟著走 |
| 全螢幕也看得到 | fullScreenAuxiliary | 疊在全螢幕 App 上面 |
| 不進 Mission Control | stationary+ignoresCycle | 不會跟著縮小,也不會被 ⌘` 輪到 |
| 不進 Dock | LSUIElement | Dock 不多一個圖示 |
| 熱鍵不搶焦點 | 處理完還焦點 | 開網址會把 App 叫到前面,處理完立刻把焦點還給原本的 App(0 秒、0.2 秒各還一次) |
全螢幕、切桌面、Mission Control 這三項,程式已照規格設定,但還沒實機驗證(見 § 19)。
§ 15 ・ 邏輯
省電:全 App 只有一個計時器
每秒觸發一次
對準整分,每分鐘一次
不跑連續動畫;邊框閃爍也是搭每秒那一次更新來切換。
11/22 的兩次抽量都在碼錶計時中,用 top 量。關掉秒數後改每分鐘更新的耗電還沒量過。
§ 16 ・ 邏輯
用量數字:寧可說「不知道」,
也不說錯
不直接打官方的用量 API:會被限流(429),也不偽裝成別的程式繞過限流。
快取超過 15 分鐘沒更新,就顯示「⏳ 等 mini」,不顯示舊數字。
百分比一律以 0–100 計。9/29 曾發生過 1% 被當成 100% 的事故。
§ 17 ・ 成果
實機畫面
- 1大字時鐘+日期星期可切換 12/24 小時制,秒數可關
- 2現在在做什麼點一下就能打字
- 3計時區截圖當下碼錶 1:39:45
- 4分鐘預設 5/10/15/25/50秒級的按鈕藏起來了
- 5控制列開始、重設、碼錶、鬧鐘、番茄、鎖定、縮放、設定
- 6番茄進度今日完成 0 個 / 目標 8
- 7Claude 用量列5 小時視窗剩 1:59 ・ session 6% ・ 週 62%
2026-11-22 21:20 實機截圖(只截這個視窗)。滑鼠移到圖上,畫面會跟著傾斜。
§ 18 ・ 數據
1,786 行 Swift,介面就占 44%
黃色兩條是畫面程式(411+382=793 行,占 44.4%)。行數用 wc -l 計算,包含註解與空行。
§ 19 ・ 數據
30 分 31 秒裡,62% 花在驗收
每次 commit 新增的行數
11/21 22:28
22:31
22:33
22:51
11/22 07:50
09:35
時間軸是以 commit 時間切段,並不是精確的寫程式時間。第 1 期占新增行數的 71%。
§ 20 ・ 數據
驗收 10 項:7 過、1 部分、2 項沒驗證
第 10 項:完工通知另外用同一組金鑰發送,已送達(status 1),但 App 自己發的推播還沒測過。隔天補做的「結束」出口:設定頁按鈕已截圖確認,右鍵選單還沒實測。
§ 21 ・ 數據
上線第一天:碼錶累計 8 小時 08 分
11/22 的紀錄檔(sessions.jsonl):三段碼錶已結束,第四段截圖時還在跑。
- 08:51 起 46 分
- 12:18 起 2 時 55 分
- 15:14 起 4 時 26 分
- 19:40 起・截圖時進行中(虛線)
觀察(待使用者確認):目前主要拿碼錶記一段工作的長度,番茄和「在做什麼」還沒用上。11/21 22:30–22:48 的 8 筆是建置期間的測試紀錄,沒算進這頁的時數。
§ 22 ・ 問題與解法
隔天早上第一個回報:「我找不到退出的地方」
其實有「結束」,放在選單列的時鐘圖示裡。但 MacBook 的瀏海會把右上角放不下的圖示藏起來,使用者根本看不到。
從原本一個出口,增加到三個:
- 時鐘上按右鍵 →「結束浮動時鐘」
- 設定 → 一般 → 最下面的按鈕
- 選單列圖示(原本就有的)
+14 行
3 個檔案,commit 時間 07:50。設定頁按鈕已截圖確認;右鍵選單還沒實測。
教訓:逃生口不能只放一個,尤其是放在可能被系統藏起來的地方。
§ 23 ・ 問題與解法
開工前就先擋掉的六個坑
| 坑 | 會怎樣 | 怎麼解 |
|---|---|---|
| 桌面版不跑狀態列 | 看不到額度 | App 自己每 5 分鐘 ssh 問 mini |
| 官方用量 API 會限流 | 429 錯誤、數字斷掉 | 不直接打 API,只讀 mini 的快取 |
| 開網址會搶焦點 | 打字打到一半被切走 | 處理完立刻把焦點還給原本的 App |
| 重開 App | 計時中斷,或同一段被算兩次 | 計時存起來,重開後接著跑;結束 App 時不寫紀錄 |
| Hammerspoon 的指令通道很脆弱 | 曾經整個當掉(10/26) | 只透過 BindKey 加熱鍵;修改前先備份 init.lua |
| 動畫耗電 | 11/18 實測整機多耗約 7W | 只用一個每秒更新一次的計時器,不跑連續動畫 |
§ 24 ・ 結論
結論
外型沿用原版,用途改成專注+盯額度。三期 30 分 31 秒交付,閒置 CPU 0.6%。
先調查再拍板;規格書是唯一依據;排程實作;驗收不假裝通過。
3 項實機驗證和右鍵選單還沒測;番茄和「在做什麼」還沒被用上。
真正值錢的不是時鐘,
是它接上了原本就有的系統。
§ 25 ・ 下一步
下一步(依優先順序)
| # | 事項 | 估計時間 |
|---|---|---|
| 1 | 實機測全螢幕、切換桌面、Mission Control | 約 5 分鐘 |
| 2 | 測穿透模式下點擊底下的東西,以及右鍵「結束」 | 約 2 分鐘 |
| 3 | 把 App 內推播打開,測一次 | 約 3 分鐘 |
| 4 | 用滿一週後看統計:碼錶和番茄各用多少、要不要讓碼錶也記任務名稱 | 一週後,約 10 分鐘 |
| 5 | 暫緩:行程倒數、人生 Dashboard 磚(使用者決定先不做) | — |
時間都是估計值。1–3 項加起來約 10 分鐘,做完驗收就是 10/10。
COLOPHON ・ 版權頁
浮動時鐘 v1.0
簡報 v1.0 ・ 2026-11-22 ・ 資料截至 2026-11-22 21:20
資料來源:git 紀錄(6 次 commit,最新 c72fa7a)、排程 session 起訖與驗收回報、sessions.jsonl、top 量測、App Store 上架頁面
— 完 —
封面的星空離開畫面後就停止重繪(省電,跟這個專案的原則一樣)