# macOS GUI 使用说明

`CodexProviderSync.app` 是 macOS 桌面版 GUI，使用 Avalonia 构建，复用 `desktop/CodexProviderSync.Core` 的状态、同步、切换、恢复和清理逻辑。

## 构建

需要 .NET 10 SDK。

```bash
./scripts/publish-gui-macos.sh
```

构建 Intel (x86_64) 版本：

```bash
./scripts/publish-gui-macos.sh --runtime osx-x64 --output artifacts/osx-x64
```

默认产物：

```text
artifacts/osx-arm64/CodexProviderSync.app
```

如需指定 SDK：

```bash
DOTNET=/path/to/dotnet ./scripts/publish-gui-macos.sh
```

## 功能

- 选择或输入 Codex Home，默认 `~/.codex`
- `Refresh` 查看当前 provider、rollout provider counts、SQLite provider counts、备份统计、project visibility 和 `encrypted_content` 风险提示
- Provider 列表展示 `config`、`rollout`、`SQLite`、`manual` 来源
- 手动添加或删除 provider
- `Sync Metadata Only`
- `Switch config.toml and sync`
- `Restore Backup`，可选择恢复 `config.toml`、SQLite、rollout metadata
- `Clean Old Backups`
- `Open Backup Folder`
- 执行日志和错误提示

## 安全边界

- App 启动和 `Refresh` 不会修改 Codex Home 下的 session、SQLite 或 `config.toml` 元数据
- 写操作前会弹出确认
- `sync` 和 `switch` 由 Core 先创建 backup，再修改 metadata
- `encrypted_content` 只提示风险，不承诺修复
- 不处理 `auth.json`
- 不登录、不认证
- 不修改对话内容
- 不修改 `updated_at`

## 操作建议

执行 `Sync Metadata Only`、`Switch config.toml and sync`、`Restore Backup` 或 `Clean Old Backups` 前，先关闭：

- Codex CLI
- Codex App
- app-server
- 仍在使用相关 Codex Home 的终端任务

如果看到 `state_5.sqlite is currently in use`，关闭上述进程后重试。

如果日志显示跳过 locked rollout files，通常表示当前会话仍占用 rollout 文件。同步大多已完成；等会话结束后再运行一次 sync 可补齐这些文件。

## 发布说明

`scripts/publish-gui-macos.sh` 默认发布 `osx-arm64` self-contained `.app` bundle，并在本机可用时执行 ad-hoc `codesign`。该脚本不修改 Windows GUI 发布脚本 `scripts/publish-gui.ps1`。

当前 Avalonia 11.3.x 构建可能显示 `Tmds.DBus.Protocol` 的 NuGet advisory warning。该依赖来自 Avalonia 桌面包的跨平台传递依赖；macOS 发布产物可构建运行，但发布前仍应按团队安全策略评估或升级 Avalonia。