Repository navigation
FAQ zh HK
English version: FAQ
唔係。任何 macOS 14 (Sonoma) 支援嘅 Mac 都 work：MacBook Air / Pro 2018+、iMac 2019+、Mac mini 2018+、iMac Pro、Mac Studio、Mac Pro 2019+。Repo 名係歷史遺留——code 冇用任何 MacBook 特有 API。
V0.4 分發嘅 DMG 淨係 Apple Silicon（arm64）。macOS 14+ 嘅機絕大部分都係 Apple Silicon；想出 universal，喺 scripts/build-dmg.sh 加返 ARCHS="arm64 x86_64" 再 build。
macOS 已經佔住 ⌘⇧3 / ⌘⇧4 / ⌘⇧5 做截圖，所以 V0.1–V0.3 嘅 ⌘⇧1–7 default 踩住系統 shortcut。V0.4 將 10 個 layout preset 全部由 Shift 移去 Control：
| Layout | 舊（V0.1–V0.3） | 新（V0.4） |
|---|---|---|
| Full | ⌘⇧1 | ⌘⌃1 |
| Halves | ⌘⇧2 | ⌘⌃2 |
| Thirds | ⌘⇧3 | ⌘⌃3 |
| Quads | ⌘⇧4 | ⌘⌃4 |
| Main + Side | ⌘⇧5 | ⌘⌃5 |
| LeftSplit + Right | ⌘⇧6 | ⌘⌃6 |
| Left + RightSplit | ⌘⇧7 | ⌘⌃7 |
| Main + Side Vertical | — | ⌘⌃8 |
| Halves Vertical | — | ⌘⌃9 |
| Thirds Vertical | — | ⌘⌃0 |
Workspaces 用 ⌘⌥1–4（第三個 namespace，唔會撞 Layouts 同 macOS 截圖）。
如果你 V0.1–V0.3 已經有自訂 hotkey 用 ⌘⇧，Setpiece upgrade 時唔會改你嘅 binding——user 設嘅 binding 保留。呢個 default 改動只影響 seed。
呢個係 TCC cdhash trap。Ad-hoc signed app（冇 Apple Developer ID）嘅 Accessibility 授權綁住 binary 嘅 code-directory hash。每次 rebuild 出新 cdhash，所以：
- System Settings → Privacy & Security → Accessibility 嘅 Setpiece toggle 仲係 ON。
- 但
AXIsProcessTrusted()return false——因為授權對應嘅係上一次個 binary，唔係家陣行緊嗰個。 - Hotkey 靜靜噉唔 work。
兩個 fix（揀一樣）：
- System Settings 裡面 OFF 完再 ON（Privacy & Security → Accessibility 嘅 Setpiece entry）。呢個動作會重新綁授權落當前 cdhash。
-
Reset TCC：
tccutil reset Accessibility com.hillman.SceneApp—— force macOS 下次 AX call 時重新 prompt。
Setpiece 自己 fix 唔到——呢個係 macOS 特登唔信 ad-hoc signing 跨 rebuild。Developer ID signature + notarize 就會解決晒（V0.5 deferred）。
Setpiece 要控制其他 app 嘅窗口，需要 Accessibility permission + 關 App Sandbox。Mac App Store 唔畀呢個組合。所有認真嘅 macOS window manager（Rectangle、Magnet、Amethyst、yabai）都喺 Store 以外分發。
DMG 係 ad-hoc signed——冇用 Apple Developer account 簽 / notarize。macOS Gatekeeper 將冇 sign 嘅 app 標做不可信，直到用戶明確 trust 一次。Right-click → Open 係一次性 trust，之後 launch 唔再問。
Setpiece 將來拎到 Developer ID 簽證 + notarize（V0.5 deferred）之後，呢個 step 會消失。
Apple System Settings.app 有 hard minimum 尺寸，AX setSize 低過 minimum 會 silent ignore。Setpiece 照 set position，所以窗口會去正確 quadrant，但 size 縮唔細。唔係 Setpiece bug，係 macOS 限制。 Finder Get Info 同 Calculator 都一樣。
Zero external dependency 係硬規矩。Carbon RegisterEventHotKey 得 ~50 行 direct code，冇 runtime cost。V0.2 嘅 hotkey-capture UI（HotkeyCaptureView）由零起寫，因為借 library 唔值得加個 dep。V0.4 將同一個 capture UI 延伸去 Workspaces。
V0.1 spec 記錄嘅設計決定。「唔理佢」會令背景窗口浮喺 grid 之上，破壞「一 click，乾淨」嘅 primary use case。用戶想要返 window 可以 ⌘Tab + Dock restore；留背景 overlay 比用戶體驗差。Drag-to-swap（V0.3）係自動分配錯咗嘅逃生口。
揀要摩擦。最近 focus 嘅窗口幾乎一定係用戶想放 primary 嗰個。Menu 同 hotkey trigger 一致：你啱啱 interact 嗰個窗口永遠入 primary slot。Drag-to-swap（V0.3）係自動分配錯咗嘅逃生口。
得，由 V0.2 已經得。開 Settings → Layouts 可以 rename、改比例、重綁 hotkey、刪走 10 個 seed layout 任何一個，仲可以用 Layout Editor 整新 layout（11 種 grid template：columns / rows / 2×2 / 3×2 / 4 種 L-shape）。刪咗嘅 seed 升級 Setpiece 都唔會突然塞返。
得——Workspaces 係 V0.4 嘅頭條 feature。Settings → Workspaces 可以編輯 4 個 seed（Coding / Meeting / Reading / Streaming）、加新嘅、刪走任何一個。每個 Workspace 有 layout reference、要開 / 要閂嘅 app list、optional Focus mode pair（靠 Shortcuts 驅動）、optional hotkey、0+ 個 auto-trigger（manual / monitor connect / monitor disconnect / 時間 / 日曆 event）。
未得。Setpiece 仍係只做滑鼠所在嗰個 screen。Per-display 獨立 layout 係 V0.5 deferred。
輕手處理。appsToQuit 用 NSRunningApplication.terminate()（等於 Cmd-Q），畀 5 秒 grace，仲活住嘅 app 就出「無法關閉 Cursor、Pages — 可能有未儲存檔案」嘅通知。Setpiece 永遠唔 force-terminate。 呢個係特登咁設計——一次 force-kill 失咗未儲存嘅 work 就永久破壞用戶對 appsToQuit 嘅信任。
唔會。Calendar trigger watcher 用 EventKit 本地讀 event title，做 substring match，fire Workspace——冇 network call、冇 cloud service、冇 analytics。Setpiece lazy request Calendar 權限，只喺用戶加第一個 .calendarEvent trigger 嗰陣先問。
暫時 TBD。現時 code 由 repo owner 原創。加 LICENSE file 之前預設 copyright 適用（保留所有權利），fork-and-redistribute formally 唔 OK。預期目標：MIT 或 Apache-2.0。
零 network call。os.Logger 只寫本機 Console。冇 analytics、冇 crash reporting、冇 update check。
睇 Contributing-zh-HK。TL;DR：fork → feature branch → PR。Test 要 pass（swift test = 157 個 test），commit style 係 Conventional Commits，冇 discuss 過唔好加新 external dep。AI 實際有貢獻嘅 commit 加 Co-Authored-By: Claude <noreply@anthropic.com> trailer。
V0.4 spec（docs/superpowers/specs/2026-04-19-scene-v0.4-workspaces-and-i18n-design.md）住喺本地 gitignored folder——唔公開。決定 capture 咗落 Architecture-zh-HK 同呢個 wiki。新 proposal 開 GitHub Discussion 或 issue。
English
繁體中文（香港）