AI Skills
cmux-dev-workflow

cmux-dev-workflow

熱門

適用於 cmux 環境設定、Xcode 專案正規化、標籤化側邊欄 ExtensionKit 開發與開發版建置的貢獻者工作流程規範。當需要初始化 cmux 儲存庫、修改 Xcode 專案檔案、新增側邊欄擴充功能或處理帶有標籤的 Debug 建置時使用。

2.5萬星標
2120分支
更新於 2026/8/1
獲取技能源代碼

相關技能

hermes-tweet3.9萬pr-triage8.1萬agent-base-template-generator7.2萬
SKILL.md
唯讀
名稱
cmux-dev-workflow
描述

適用於 cmux 環境設定、Xcode 專案正規化、標籤化側邊欄 ExtensionKit 開發與開發版建置的貢獻者工作流程規範。當需要初始化 cmux 儲存庫、修改 Xcode 專案檔案、新增側邊欄擴充功能或處理帶有標籤的 Debug 建置時使用。

cmux 開發工作流程

初步設定

./scripts/setup.sh 會初始化 submodule、建置 GhosttyKit，並安裝用來正規化 pbxproj 的 pre-commit hook。

帶標籤的本機開發

每次修改程式碼後，請建置 Debug 應用程式：

./scripts/reload.sh --tag <short-tag>

該腳本僅會執行建置而不會直接啟動；只有在需要開啟應用程式時才加上 --launch。切勿直接執行未加參數的 xcodebuild 或開啟未標籤化的 cmux DEV.app：未標籤化的建置版本會與其他 Agent 共用預設的 debug socket 和 bundle ID，從而導致衝突並搶走視窗焦點。

若要針對帶標籤的 Debug 應用程式進行 CLI 或 socket 的 dogfood 測試：

CMUX_TAG=<tag> scripts/cmux-debug-cli.sh list-workspaces

進行帶標籤的 dogfood 測試時，請勿使用 /tmp/cmux-cli；該符號連結（symlink）永遠指向最新重新載入的建置版本。詳情請參閱 references/tagged-builds.md。

Xcode 工具鏈

團隊固定使用 Xcode 26.x 版本。.xcode-version 是主要版本的唯一真實來源（single source of truth）；cmux.xcodeproj/project.pbxproj 包含 objectVersion = 60，這也是 Xcode 26 預設寫入的版本。（objectVersion = 77 專用於同步資料夾群組，cmux 並未採用。）

scripts/setup.sh 會安裝受版本控制的 scripts/git-hooks/pre-commit。當 project.pbxproj 被加入暫存區（staged）時，該 hook 會對其執行 scripts/normalize-pbxproj.py，確保 Xcode 的非確定性排序（nondeterministic reordering）不會進入 commit 中。此 hook 具備等冪性（idempotent）。CI 則會執行 scripts/check-pbxproj.sh 來強制檢查 objectVersion 的版本固定與正規化結果，因此若跳過 hook 將會導致 PR 明確報錯失敗。升級固定的 Xcode 版本屬於團隊的重大決定，詳情請參閱 references/xcode-project-normalization.md。

側邊欄擴充點（開發版標籤化）

每個帶標籤的開發建置版本都會獲得獨立的 ExtensionKit 側邊欄擴充點（extension point），確保多個同時執行的開發版本不會發生衝突。主要由以下三項建置設定控制：

  • CMUX_SIDEBAR_EXTENSION_POINT_ID（預設為 com.cmuxterm.app.cmux.sidebar）：在建置時寫入 Info.plist 的擴充點識別碼（identifier）。
  • CMUX_BUNDLE_ID_SUFFIX（預設為空）：會插入到應用程式與 appex 的 bundle ID 中，讓帶標籤的擴充功能擁有獨立身份，以便 pkd 能單獨記錄。
  • CMUX_DISPLAY_NAME_SUFFIX（預設為空）：會附加至 appex 的 CFBundleDisplayName 後方。作業系統會依據顯示名稱（display name）對側邊欄擴充功能進行分組，供 Host 讀取啟用/停用狀態與可用數量；因此若並排安裝兩個同名的 appex，系統會將其視為同一個邏輯擴充功能，切換其中一個便會干擾另一個。

Host 在執行階段會透過 CmuxSidebarExtensionPoint.identifier(in:) 從 Info.plist 的 CMUXSidebarExtensionPointIdentifier 鍵值解析出其點 ID。./scripts/reload.sh --tag <tag> 會將 Host 點的作用域限縮為 com.cmuxterm.app.debug.<tag>.cmux.sidebar。若要建置對應標籤作用域的範例擴充功能，請執行：

./scripts/reload-extension.sh --tag <tag> [--host-bundle-id <id>] [--example sample|tabs|both]

關於傳遞的設定、禁止重新簽署（no-re-signing）規則以及撰寫相容標籤的範例擴充功能檢查清單，請參閱 references/sidebar-extension-tagging.md。