PROJECT DOSSIER · 2026.11
--:--:--

浮動時鐘

不搶焦點、所有桌面都看得到,會盯 Claude 用量的專注時鐘

Swift 原生 macOS App ・ 11/21 規劃 → 當晚 22:21 排程開工 → 30 分 31 秒交付

SCROLL ↓
fol. 02 / 27

§ 01 ・ 亮點

規劃時估 3–4 小時,
排程實作 30 分 31 秒 交付。

三期一次做完,交付時 10 項驗收過 7 項;另外 3 項沒實測,照實標「未驗證」(見 § 13)。

實際時間取自排程 session 的起訖時間(22:21:34 → 22:52:05)。3–4 小時是規劃當下的人工估計(第 1 期約 2 小時+第 2 期約 1.5 小時+第 3 期),不是量出來的。

fol. 03 / 27

§ 02 ・ 一頁摘要

沒時間的話,看這頁就好

30:31
排程實作時間(分:秒)
1,786
行 Swift,分 10 個檔
7 / 10
驗收通過;1 項部分通過、2 項未驗證
0.6%
閒置 CPU(11/21 驗收量測)
做了什麼

一個浮在所有視窗上的時鐘:倒數、番茄、碼錶、鬧鐘,加上 Claude 5 小時額度列。

為什麼

桌面版 Claude 看不到額度倒數;現成 App 接不上 mini、手機推播和熱鍵。

下一步

補完 3 項實機驗證(約 10 分鐘),用滿一週再看統計決定要不要調整。

fol. 04 / 27

§ 03 ・ 起點

靈感:一則 Threads 貼文

「請 Claude 幫我生成一款漂浮時鐘……功能都是我上課用得到的。」

原版 ・ 上課控時
  • 大字時鐘、日期、星期
  • 10–60 秒倒數鈕
  • 鎖定、縮放、開始、齒輪
  • 今日完成幾個番茄
→
我們 ・ 專注+盯額度
  • 外型沿用,用途改掉
  • 分鐘級預設(5/10/15/25/50)
  • Claude 5 小時額度列
  • 手機推播、熱鍵、紀錄

原貼文只看得到截圖,看不出原作用什麼技術做的。

fol. 05 / 27

§ 04 ・ 背景

網路上明明就有,為什麼還要自己做?

痛點 1

看不到 Claude 額度

桌面版 Claude Code 不跑終端機狀態列,5 小時視窗的倒數平常只存在 mini 的監控程式裡。

痛點 2

現成 App 接不上

mini 的用量快取、Pushover 手機推播、Hammerspoon 熱鍵(BindKey),三樣都接不上。

痛點 3

動畫很耗電

11/18 實測:一個動畫背景讓 Claude 多吃約 56% CPU,整台電腦多耗約 7W。新工具必須幾乎不耗電。

自己做的價值不在時鐘本身,在於能接上自己原本就有的系統。

fol. 06 / 27

§ 05 ・ 目標

成功的標準:五條驗收線

01

不搶焦點

點它、按熱鍵,正在打字的 App 都不會被推到背景。

02

到處都在

每個桌面、全螢幕 App 上都看得到;不出現在 Mission Control。

03

幾乎不耗電

每秒最多更新一次,不跑連續動畫。

04

數字不說謊

拿不到用量就顯示「等 mini」,不顯示假數字。

05

資料留得住

每次計時寫一行紀錄,日後可以接人生 Dashboard。

fol. 07 / 27

§ 06 ・ 市場調查

網路上確實有:比對了 14 款

浮在桌面上的倒數很普遍。最右邊三欄,現成的都沒有。

App浮動置頂超時續數圓盤/色塊多組計時Claude 額度手機推播自訂熱鍵
TinyTimekeeper——————
PinnedTimer——————
ClyTimer—————
Countdown Timer Pro——————
Time Timer——————
Aestu—————
浮動時鐘

● 表示上架頁有寫;— 表示上架頁沒提,不代表沒有這功能。依各 App 的 App Store 頁面整理,沒有實際安裝測試。另比對了 Top Clock、ABTimer、MeetingBar、Soonie、EDUwidgets、Classroomscreen,以及 2 個開源專案。

fol. 08 / 27

§ 07 ・ 借鏡

借來的 5 個點子,各自怎麼做

Aestu

超時續數

歸零後不停,顯示「+02:13」並變紅。

Time Timer

圓盤/色塊

數字、圓盤、色塊三選一,放在設定裡切換。

ABTimer

現在在做什麼

點一下打字,按 Enter 存。

ClyTimer

多組計時

最多 3 組,預設關閉。

MeetingBar/Soonie

行程倒數

暫不做:接行事曆會讓功能變複雜,反而失焦。

fol. 09 / 27

§ 08 ・ 技術路線

三條路,選了最穩的那條

做法得到失去當時估的第 1 期工時
Swift 原生 App
採用
獨立程式,Hammerspoon 重新載入也不會中斷倒數;全螢幕與滑鼠穿透最乾淨多一個要編譯的專案約 2 小時
Hammerspoon 模組最快,熱鍵直接接Hammerspoon 一重新載入,倒數就斷約 1 小時
直接裝現成 App2 分鐘就有接不上用量、推播、熱鍵2 分鐘

第三條路:App 用 Swift 原生做,再開一個 floatclock:// 網址給 Hammerspoon 熱鍵呼叫。程式穩定,也接得上既有的熱鍵系統。

fol. 10 / 27

§ 09 ・ 決策

使用者拍板的四個取捨

取捨 1 ・ 重複的功能

不砍,放進設定讓使用者選

例:剩餘時間用數字、圓盤或色塊顯示。

取捨 2 ・ 秒級預設

留著,但平常藏起來

10–60 秒的按鈕平常看不到;按住 ⌥ 點齒輪才會出現。平常不干擾,要用時多點一下就有。

取捨 3 ・ 外部串接

行事曆、Things 3 都不接

原話:接行事曆「會把功能複雜化,反而失焦」。

取捨 4 ・ 時程

三期一次做完,排程到 22:21

當時 token 快用完,所以先把規格寫好,排程晚上自動開工。

fol. 11 / 27

§ 10 ・ 流程

十個步驟:從截圖到修正

黃框是關鍵:規劃和實作分開,中間只靠一份規格書交接。

看到靈感Threads 截圖兩張
網路調查6 組搜尋,比對 14 款
列功能、猜需求依使用者習慣推測要用哪些
使用者拍板四個取捨(§ 09)
寫規格書唯一的依據,11 段
排程開工11/21 22:21 自動開工
三期實作分期 commit
逐條驗收沒驗到就寫「未驗證」
手機推播「浮動時鐘做好了」
回饋→修正隔天早上:找不到退出鍵
fol. 12 / 27

§ 11 ・ 邏輯

為什麼要先寫規格書,再排程?

排程開工的是一個全新的對話,看不到前面的討論。所有決定都要寫進 規格.md,否則就會遺失。

排程的指示只有三句:先讀完規格、照著做、照驗證清單逐條驗收;沒驗到的就老實寫「未驗證」。

11
規格書段落
8
條驗證清單(驗收時拆成 10 項回報)
規格.md ・ 目錄
  1. 做法(已拍板)
  2. 視窗行為
  3. 顯示
  4. 倒數
  5. 結束提醒
  6. 番茄
  7. Claude 用量列
  8. 熱鍵
  9. 紀錄與統計
  10. 不做(行事曆、Things 3…)
  11. 驗證清單
fol. 13 / 27

§ 12 ・ 實作

三期,一次做完

第 1 期 ・ commit 22:28:13
+1,468 行

面板與倒數

  • 浮動面板、時鐘、日期
  • 分鐘預設、開始/暫停/重設
  • 超時續數,數字/圓盤/色塊
  • 番茄、提醒、設定頁
第 2 期 ・ commit 22:31:24
+323 行

串接既有系統

  • floatclock:// 網址+5 個熱鍵
  • Pushover 手機推播
  • JSONL 計時紀錄
  • Claude 用量列
第 3 期 ・ commit 22:33:01
+221 行

統計

  • 今日/本週專注時間
  • 番茄數、平均超時
  • 最近 7 天長條
  • 重開 App 後計時接著跑
fol. 14 / 27

§ 13 ・ 架構

資料怎麼流

Hammerspoon 熱鍵⌃⌥C/Space/R/U/T → 送 floatclock:// 網址
滑鼠點面板預設鈕、控制列、右鍵選單
mini 用量每 5 分鐘 ssh 查一次
→
浮動時鐘.app
浮動面板不搶焦點、每個桌面都在
SwiftUI 畫面時鐘、計時、用量列
計時核心全 App 只有一個計時器
→
提醒邊框閃爍、macOS 通知、音效
手機Pushover(倒數 ≥ 5 分才推)
紀錄sessions.jsonl,一次計時一行
設定與狀態位置、跑到一半的計時
fol. 15 / 27

§ 14 ・ 邏輯

「不搶焦點、到處都在」是怎麼做到的

需求設定白話
點了不搶焦點nonactivatingPanel可以打字,但不會把正在用的 App 推到背景
每個桌面都在canJoinAllSpaces切換桌面時跟著走
全螢幕也看得到fullScreenAuxiliary疊在全螢幕 App 上面
不進 Mission Controlstationary+ignoresCycle不會跟著縮小,也不會被 ⌘` 輪到
不進 DockLSUIElementDock 不多一個圖示
熱鍵不搶焦點處理完還焦點開網址會把 App 叫到前面,處理完立刻把焦點還給原本的 App(0 秒、0.2 秒各還一次)

全螢幕、切桌面、Mission Control 這三項,程式已照規格設定,但還沒實機驗證(見 § 19)。

fol. 16 / 27

§ 15 ・ 邏輯

省電:全 App 只有一個計時器

要顯示秒,或有計時在跑

每秒觸發一次

其他時候

對準整分,每分鐘一次

不跑連續動畫;邊框閃爍也是搭每秒那一次更新來切換。

0%5%10% CPU
26 MB
記憶體(top 量測)
1.1 MB
App 大小

11/22 的兩次抽量都在碼錶計時中,用 top 量。關掉秒數後改每分鐘更新的耗電還沒量過。

fol. 17 / 27

§ 16 ・ 邏輯

用量數字:寧可說「不知道」,
也不說錯

mini 監控程式手上有真實的額度數字
→
每 5 分鐘 ssh 查一次
寫進本機快取~/.claude/session_window.json
→
面板只讀快取「5h 剩 1:59 · S 6% · W 62%」
不做

不直接打官方的用量 API:會被限流(429),也不偽裝成別的程式繞過限流。

過期就說

快取超過 15 分鐘沒更新,就顯示「⏳ 等 mini」,不顯示舊數字。

單位

百分比一律以 0–100 計。9/29 曾發生過 1% 被當成 100% 的事故。

fol. 18 / 27

§ 17 ・ 成果

實機畫面

浮動時鐘實機截圖:21:20:16,碼錶 1:39:45,Claude 5h 剩 1:59 1 2 3 4 5 6 7
  1. 1大字時鐘+日期星期可切換 12/24 小時制,秒數可關
  2. 2現在在做什麼點一下就能打字
  3. 3計時區截圖當下碼錶 1:39:45
  4. 4分鐘預設 5/10/15/25/50秒級的按鈕藏起來了
  5. 5控制列開始、重設、碼錶、鬧鐘、番茄、鎖定、縮放、設定
  6. 6番茄進度今日完成 0 個 / 目標 8
  7. 7Claude 用量列5 小時視窗剩 1:59 ・ session 6% ・ 週 62%

2026-11-22 21:20 實機截圖(只截這個視窗)。滑鼠移到圖上,畫面會跟著傾斜。

fol. 19 / 27

§ 18 ・ 數據

1,786 行 Swift,介面就占 44%

黃色兩條是畫面程式(411+382=793 行,占 44.4%)。行數用 wc -l 計算,包含註解與空行。

fol. 20 / 27

§ 19 ・ 數據

30 分 31 秒裡,62% 花在驗收

開工 → 第 3 期 commit:11 分 27 秒第 3 期之後的驗收與收尾:19 分 04 秒

每次 commit 新增的行數

+1,468
+323
+221
+19
+14
+9/−9
第 1 期
11/21 22:28
第 2 期
22:31
第 3 期
22:33
推播紀錄
22:51
加退出鍵
11/22 07:50
改安裝位置
09:35

時間軸是以 commit 時間切段,並不是精確的寫程式時間。第 1 期占新增行數的 71%。

fol. 21 / 27

§ 20 ・ 數據

驗收 10 項:7 過、1 部分、2 項沒驗證

01
通過
編譯、開啟、截圖
02
未驗證
全螢幕、切換桌面、Mission Control
03
部分通過
穿透模式能切換;實際點擊底下的東西還沒測
04
通過
超時續數、變色、閃框、圓盤/色塊
05
通過
秒級按鈕平常藏著
06
通過
網址+熱鍵,不搶焦點
07
通過
用量列從 mini 拿到數字
08
通過
閒置 CPU 約 0.6%
09
通過
番茄、重開續跑、統計、紀錄
10
未驗證
App 內推播(設定裡推播被關掉了)

第 10 項:完工通知另外用同一組金鑰發送,已送達(status 1),但 App 自己發的推播還沒測過。隔天補做的「結束」出口:設定頁按鈕已截圖確認,右鍵選單還沒實測。

fol. 22 / 27

§ 21 ・ 數據

上線第一天:碼錶累計 8 小時 08 分

11/22 的紀錄檔(sessions.jsonl):三段碼錶已結束,第四段截圖時還在跑。

  • 08:51 起 46 分
  • 12:18 起 2 時 55 分
  • 15:14 起 4 時 26 分
  • 19:40 起・截圖時進行中(虛線)
29,280 秒
已結束的三段碼錶合計(=8:08:00)
0 顆
番茄完成數;08:51 開的 25 分倒數,12 秒後就改用碼錶
13 / 13
筆紀錄的「在做什麼」都是空白

觀察(待使用者確認):目前主要拿碼錶記一段工作的長度,番茄和「在做什麼」還沒用上。11/21 22:30–22:48 的 8 筆是建置期間的測試紀錄,沒算進這頁的時數。

fol. 23 / 27

§ 22 ・ 問題與解法

隔天早上第一個回報:「我找不到退出的地方」

原因

其實有「結束」,放在選單列的時鐘圖示裡。但 MacBook 的瀏海會把右上角放不下的圖示藏起來,使用者根本看不到。

解法

從原本一個出口,增加到三個:

  • 時鐘上按右鍵 →「結束浮動時鐘」
  • 設定 → 一般 → 最下面的按鈕
  • 選單列圖示(原本就有的)
成本與驗證

+14 行

3 個檔案,commit 時間 07:50。設定頁按鈕已截圖確認;右鍵選單還沒實測。

教訓:逃生口不能只放一個,尤其是放在可能被系統藏起來的地方。

fol. 24 / 27

§ 23 ・ 問題與解法

開工前就先擋掉的六個坑

坑會怎樣怎麼解
桌面版不跑狀態列看不到額度App 自己每 5 分鐘 ssh 問 mini
官方用量 API 會限流429 錯誤、數字斷掉不直接打 API,只讀 mini 的快取
開網址會搶焦點打字打到一半被切走處理完立刻把焦點還給原本的 App
重開 App計時中斷,或同一段被算兩次計時存起來,重開後接著跑;結束 App 時不寫紀錄
Hammerspoon 的指令通道很脆弱曾經整個當掉(10/26)只透過 BindKey 加熱鍵;修改前先備份 init.lua
動畫耗電11/18 實測整機多耗約 7W只用一個每秒更新一次的計時器,不跑連續動畫
fol. 25 / 27

§ 24 ・ 結論

結論

做到了

外型沿用原版,用途改成專注+盯額度。三期 30 分 31 秒交付,閒置 CPU 0.6%。

方法

先調查再拍板;規格書是唯一依據;排程實作;驗收不假裝通過。

還沒做到

3 項實機驗證和右鍵選單還沒測;番茄和「在做什麼」還沒被用上。

真正值錢的不是時鐘,
是它接上了原本就有的系統。

fol. 26 / 27

§ 25 ・ 下一步

下一步(依優先順序)

#事項估計時間
1實機測全螢幕、切換桌面、Mission Control約 5 分鐘
2測穿透模式下點擊底下的東西,以及右鍵「結束」約 2 分鐘
3把 App 內推播打開,測一次約 3 分鐘
4用滿一週後看統計:碼錶和番茄各用多少、要不要讓碼錶也記任務名稱一週後,約 10 分鐘
5暫緩:行程倒數、人生 Dashboard 磚(使用者決定先不做)—

時間都是估計值。1–3 項加起來約 10 分鐘,做完驗收就是 10/10。

fol. 27 / 27

COLOPHON ・ 版權頁

--:--:--
這個時鐘每秒只更新一次,和 App 一樣

浮動時鐘 v1.0

簡報 v1.0 ・ 2026-11-22 ・ 資料截至 2026-11-22 21:20

資料來源:git 紀錄(6 次 commit,最新 c72fa7a)、排程 session 起訖與驗收回報、sessions.jsonl、top 量測、App Store 上架頁面

— 完 —

封面的星空離開畫面後就停止重繪(省電,跟這個專案的原則一樣)