managing-macos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

macOS 관리 (nix-darwin)

macOS 管理（nix-darwin）

nix-darwin 및 macOS 시스템 설정 가이드입니다.

这是一份nix-darwin及macOS系统设置指南。

빠른 참조

快速参考

Rebuild 명령어

重建命令

bash

undefined

bash

undefined

설정 적용 (미리보기 + 적용)

应用配置（预览+应用）

nrs

오프라인 rebuild (캐시만 사용, 빠름)

离线重建（仅使用缓存，速度快）

nrs --offline

NO_CHANGES 스킵 우회 (activation scripts 강제 재실행)

跳过NO_CHANGES检测（强制重新执行激活脚本）

nrs --force

미리보기만

仅预览

nrp


**nrs 안전 기능:**
- launchd 에이전트 정리 (setupLaunchAgents 멈춤 방지)
- Hammerspoon 재시작 (HOME 오염 방지)

> nrs/nrp 스크립트는 `~/.local/lib/rebuild-common.sh`를 source하여 공통 함수(로깅, 인수 파싱, worktree 감지, 빌드 미리보기, 아티팩트 정리)를 사용합니다.
> 소스: `modules/shared/scripts/rebuild-common.sh`, 플랫폼별: `modules/darwin/scripts/{nrs,nrp}.sh`

**Git Worktree 지원:**

git worktree에서 `nrs`/`nrp` 실행 시 자동 감지하여 worktree의 flake를 빌드합니다.

- 감지: `detect_worktree()` (rebuild-common.sh source 시 자동 실행)
- 메커니즘: `FLAKE_PATH`만 worktree 경로로 전환 (`--flake <worktree>`로 빌드)
- 심링크 타깃(`nixosConfigPath`)은 항상 메인 레포 — worktree 빌드 후에도 심링크가 안정적

nrp


**nrs安全功能：**
- 清理launchd代理（防止setupLaunchAgents卡住）
- 重启Hammerspoon（避免HOME环境变量污染）

> nrs/nrp脚本通过引入`~/.local/lib/rebuild-common.sh`来使用公共函数（日志记录、参数解析、工作区检测、构建预览、清理 artifacts）。
> 源码：`modules/shared/scripts/rebuild-common.sh`，平台专属脚本：`modules/darwin/scripts/{nrs,nrp}.sh`

**Git Worktree支持：**

在Git worktree中执行`nrs`/`nrp`时，会自动检测并构建worktree中的flake。

- 检测：`detect_worktree()`（引入rebuild-common.sh时自动执行）
- 机制：仅将`FLAKE_PATH`切换为worktree路径（通过`--flake <worktree>`进行构建）
- 符号链接目标(`nixosConfigPath`)始终指向主仓库 — 即使在worktree构建后，符号链接依然稳定

주요 설정 파일

主要配置文件

파일	용도
`modules/darwin/configuration.nix`	macOS 시스템 설정
`modules/darwin/home.nix`	Home Manager (macOS)
`modules/darwin/programs/`	macOS 전용 프로그램

文件	用途
`modules/darwin/configuration.nix`	macOS系统设置
`modules/darwin/home.nix`	Home Manager（macOS）
`modules/darwin/programs/`	macOS专属程序配置

Nix CLI 패키지 (darwin-only)

Nix CLI软件包（仅Darwin）

libraries/packages.nix

의

darwinOnly

리스트에서 관리:

nix

undefined

在

libraries/packages.nix

的

darwinOnly

列表中进行管理：

nix

undefined

패키지 추가

添加软件包

darwinOnly = [ ... pkgs.패키지명 ];


자세한 내용: [references/features.md](references/features.md#nix-cli-패키지-darwin-only)

darwinOnly = [ ... pkgs.패키지명 ];


详细内容：[references/features.md](references/features.md#nix-cli-packages-darwin-only)

macOS 시스템 설정

Homebrew管理

설정	파일	설명
Dock	`configuration.nix`	자동 숨김, 크기, 최근 앱
Finder	`configuration.nix`	숨김 파일, 확장자, 네트워크 .DS_Store 방지
키보드	`configuration.nix`	키 반복 속도
트랙패드	`configuration.nix`	탭 클릭, 자연스러운 스크롤

在

modules/darwin/programs/homebrew.nix

中进行声明式管理（仅适用于个人主机）。

nix

undefined

Homebrew 관리

cleanup = "none" — 不删除未声明的应用（保护手动安装的cask）

—

upgrade = true + greedyCasks = true — 防止自带更新器的应用出现版本漂移

modules/darwin/programs/homebrew.nix

에서 선언적으로 관리됩니다 (personal 호스트만 적용).

nix

undefined

homebrew.casks = [ "codex" "ghostty" "raycast" "rectangle" "hammerspoon" "homerow" "docker" "fork" "monitorcontrol" ]; homebrew.brews = [ "laishulu/homebrew/macism" ]; # Neovim韩英切换

cleanup = "none" — 선언되지 않은 앱을 삭제하지 않음 (수동 설치 cask 보호)

shottr → 通过Nix软件包管理（libraries/packages.nix的darwinOnly列表）

upgrade = true + greedyCasks = true — 자체 업데이터 앱의 버전 드리프트 방지

figma → 从Homebrew移除（自带更新器会修改版本，导致适配时版本冲突）

—

slack → 从Homebrew移除（偏好手动安装，交由自带更新器处理）

homebrew.casks = [ "codex" "ghostty" "raycast" "rectangle" "hammerspoon" "homerow" "docker" "fork" "monitorcontrol" ]; homebrew.brews = [ "laishulu/homebrew/macism" ]; # Neovim 한영 전환


**新Mac设置时**：手动安装的应用需要通过`brew install --cask --adopt <应用>`转换为Homebrew管理。

详细内容：[references/features.md](references/features.md#gui-apps-homebrew-casks)

shottr → Nix 패키지로 관리 (libraries/packages.nix darwinOnly)

Shottr声明式管理（Nix + agenix）

figma → Homebrew에서 제거 (자체 업데이터가 버전을 변경하여 adopt 시 버전 충돌)

—

slack → Homebrew에서 제거 (수동 설치 선호, 자체 업데이터에 위임)

—


**새 Mac 세팅 시**: 직접 설치된 앱은 `brew install --cask --adopt <앱>`으로 Homebrew 관리로 전환 필요.

자세한 내용: [references/features.md](references/features.md#gui-앱-homebrew-casks)

对Shottr的设置和许可证进行声明式管理。

文件	用途
`modules/darwin/programs/shottr/default.nix`	Shottr应用专属设置 + 许可证预填充
`modules/darwin/configuration.nix`	符号热键（截图快捷键） + activateSettings + Shottr重启
`libraries/constants.nix`	Shottr默认保存路径相对路径常量
`secrets/shottr-license.age`	agenix加密的许可证密钥（ `KC_LICENSE` + `KC_VAULT` ）
`modules/shared/programs/secrets/default.nix`	分发 `~/.config/shottr/license`

架构说明：符号热键和Shottr重启在
configuration.nix
的postActivation中处理。这是因为HM activation的
activateSettings -u
无法在
launchctl asuser + sudo
上下文下与WindowServer通信。

操作流程：

bash

undefined

Shottr 선언 관리 (Nix + agenix)

应用配置（包含许可证预填充）

Shottr 설정과 라이센스를 선언적으로 관리합니다.

파일	용도
`modules/darwin/programs/shottr/default.nix`	Shottr 앱 고유 설정 + 라이센스 pre-fill
`modules/darwin/configuration.nix`	symbolic hotkeys (스크린샷 단축키) + activateSettings + Shottr 재시작
`libraries/constants.nix`	Shottr 기본 저장경로 상대 경로 상수
`secrets/shottr-license.age`	agenix 암호화 라이센스 키 ( `KC_LICENSE` + `KC_VAULT` )
`modules/shared/programs/secrets/default.nix`	`~/.config/shottr/license` 배포

아키텍처 노트: symbolic hotkeys와 Shottr 재시작은
configuration.nix
의 postActivation에서 처리합니다. HM activation의
activateSettings -u
가
launchctl asuser + sudo
컨텍스트에서 WindowServer와 통신하지 못하기 때문입니다.

운영 순서:

bash

undefined

nrs

설정 적용 (라이센스 pre-fill 포함)

新Mac：启动Shottr后点击一次Activate按钮

nrs

undefined

새 맥북: Shottr 실행 후 Activate 버튼 1회 클릭

Shottr凭据管理（详细）

undefined

沙箱应用结构：Shottr是macOS沙箱应用，其plist存储在

~/Library/Containers/cc.ffitch.shottr/Data/Library/Preferences/cc.ffitch.shottr.plist

中，不存在于

~/Library/Preferences/

。不过

defaults read/write cc.ffitch.shottr ...

可以通过

cfprefsd

透明访问容器内的plist，因此无需指定额外路径即可正常工作。

许可证双重存储结构：

存储位置	密钥	用途
macOS Keychain	`Shottr-license` , `Shottr-vault`	主存储（服务器验证后记录）
defaults（plist）	`kc-license` , `kc-vault`	辅助存储（用于UI预填充）

删除Keychain → defaults中的许可证会在UI中预填充，但需要点击一次"Activate"按钮
删除defaults → 会从Keychain自动恢复（许可证保留）
两者都删除 → 回到未注册状态
"Registered to:"邮箱从Keychain（
```
Shottr-vault
```
）读取 — 与defaults中的
```
kc-vault
```
无关
```
kc-vault
```
(defaults)的确切作用未知（推测是激活时服务器通信数据的缓存）。为了安全起见，两者都会记录。

Nix管理策略：通过

defaults write kc-license + kc-vault

预填充许可证。虽然无法完全自动激活（Keychain无法通过Nix管理），但新Mac上无需记住/输入许可证密钥，只需点击一次Activate按钮即可激活。

HM activation注意事项：

Home Manager激活脚本在最小PATH环境下执行 → macOS系统命令必须使用绝对路径（
```
/usr/bin/defaults
```
,
```
/usr/bin/killall
```
）
```
defaults write
```
中的
```
{...}
```
模式会被尝试解析为plist字典 → JSON格式的字符串必须明确指定
```
-string
```
标志

示例：

/usr/bin/defaults write cc.ffitch.shottr KeyboardShortcuts_area -string '{"carbonKeyCode":20,"carbonModifiers":768}'

defaults测试时SIGTERM vs SIGKILL：

使用
```
killall Shottr
```
(SIGTERM)关闭时，Shottr会在退出时将内存缓存重新写入plist
测试defaults操作时，必须先使用
```
kill -9 $(pgrep -x Shottr)
```
（SIGKILL），再执行
```
defaults delete/write
```

测试环境：Shottr 1.9.1（build 128, versionCode 10901），macOS Darwin 24.6.0，2026-02-18

Shottr 크레덴셜 관리 (상세)

Folder Actions（launchd WatchPaths）

샌드박스 앱 구조: Shottr는 macOS 샌드박스 앱이며 plist가

~/Library/Containers/cc.ffitch.shottr/Data/Library/Preferences/cc.ffitch.shottr.plist

에 저장됩니다.

~/Library/Preferences/

에는 존재하지 않습니다. 다만

defaults read/write cc.ffitch.shottr ...

는

cfprefsd

를 통해 Container plist에 투명하게 접근하므로, 추가 경로 지정 없이 정상 동작합니다.

라이센스 이중 저장 구조:

저장소	키	용도
macOS Keychain	`Shottr-license` , `Shottr-vault`	Primary (서버 검증 후 기록)
defaults (plist)	`kc-license` , `kc-vault`	Secondary (UI pre-fill용)

Keychain 삭제 → defaults에서 라이센스를 UI에 pre-fill하되, "Activate" 버튼 1회 클릭 필요
defaults 삭제 → Keychain에서 자동 복원 (라이센스 유지)
양쪽 모두 삭제 → 미등록 상태
"Registered to:" 이메일은 Keychain (
```
Shottr-vault
```
)에서 읽힘 — defaults의
```
kc-vault
```
와 무관
```
kc-vault
```
(defaults)의 정확한 역할은 불명 (Activate 시 서버 통신 데이터 캐시로 추정). 안전을 위해 둘 다 기록

Nix 관리 전략:

defaults write kc-license + kc-vault

로 라이센스를 pre-fill합니다. 완전 자동 활성화는 불가능하지만(Keychain은 Nix로 관리 불가), 새 맥북에서 라이센스 키를 기억/입력할 필요 없이 Activate 버튼 1회 클릭만으로 활성화할 수 있습니다.

HM activation에서의 주의사항:

Home Manager activation 스크립트는 최소한의 PATH로 실행 → macOS 시스템 명령어는 절대 경로 필수 (
```
/usr/bin/defaults
```
,
```
/usr/bin/killall
```
)
```
defaults write
```
에서
```
{...}
```
패턴은 plist dictionary로 해석 시도 → JSON 형태 문자열은 반드시
```
-string
```
플래그 명시

예:

/usr/bin/defaults write cc.ffitch.shottr KeyboardShortcuts_area -string '{"carbonKeyCode":20,"carbonModifiers":768}'

defaults 테스트 시 SIGTERM vs SIGKILL:

```
killall Shottr
```
(SIGTERM)로 종료하면 Shottr가 종료 시점에 메모리 캐시를 plist에 재기록
defaults 조작 테스트 시에는 반드시
```
kill -9 $(pgrep -x Shottr)
```
(SIGKILL) 사용 후
```
defaults delete/write
```
실행

테스트 환경: Shottr 1.9.1 (build 128, versionCode 10901), macOS Darwin 24.6.0, 2026-02-18

在

modules/darwin/programs/folder-actions/default.nix

中管理基于launchd WatchPaths的文件夹监控自动化。

操作	监控文件夹	用途
compress-rar	`~/FolderActions/compress-rar`	RAR压缩
compress-video	`~/FolderActions/compress-video`	FFmpeg视频压缩
rename-asset	`~/FolderActions/rename-asset`	文件重命名
convert-video-to-gif	`~/FolderActions/convert-video-to-gif`	FFmpeg视频转GIF
upload-immich	Shottr截图文件夹	Immich自动上传（仅个人主机）

日志：

~/Library/Logs/folder-actions/

Folder Actions (launchd WatchPaths)

iOS Shortcuts / Cherri DSL

modules/darwin/programs/folder-actions/default.nix

에서 launchd WatchPaths 기반 폴더 감시 자동화를 관리합니다.

액션	감시 폴더	용도
compress-rar	`~/FolderActions/compress-rar`	RAR 압축
compress-video	`~/FolderActions/compress-video`	FFmpeg 비디오 압축
rename-asset	`~/FolderActions/rename-asset`	파일 이름 변경
convert-video-to-gif	`~/FolderActions/convert-video-to-gif`	FFmpeg 비디오→GIF 변환
upload-immich	Shottr 스크린샷 폴더	Immich 자동 업로드 (personal 전용)

로그:

~/Library/Logs/folder-actions/

iOS Shortcuts构建流水线（Cherri DSL）、prompt-render CLI、移动提示工作流，请参考

managing-shortcuts

技能。

iOS Shortcuts / Cherri DSL

常见问题

iOS Shortcuts 빌드 파이프라인(Cherri DSL), prompt-render CLI, 모바일 프롬프트 워크플로우는

managing-shortcuts

스킬을 참조하세요.

자주 발생하는 문제

参考资料

sudo 권한 필요: darwin-rebuild는 시스템 파일 수정에 sudo 필요
/etc/bashrc 충돌: 기존 설정 파일과 nix-darwin 충돌
스크롤 방향 롤백: cfprefsd 재시작 시 설정 초기화

故障排除：references/troubleshooting.md
功能列表：references/features.md

레퍼런스

—

트러블슈팅: references/troubleshooting.md
기능 목록: references/features.md

—