markbase/docs/SYSTEM_EXTENSION_REGISTRATION_GUIDE.md

# System Extension 注册指南

## 当前状态检查

```bash
# 检查代码签名证书
security find-identity -v -p codesigning
# 输出：0 valid identities found ❌

# 检查已安装的System Extensions
systemextensionsctl list
# 输出：0 extension(s) ❌
```

## 注册流程（3步骤）

### 步骤1：Developer Portal（需要手动操作）

**访问：** https://developer.apple.com/account

**需要完成：**
1. **创建App ID**
   - Bundle ID: `com.momentry.markbase.fskit`
   - Entitlements: `com.apple.developer.system-extension`

2. **创建Developer Certificate**
   - 类型：Mac App Development
   - 下载：`.cer`文件

3. **创建Provisioning Profile**
   - App ID: `com.momentry.markbase.fskit`
   - Certificate: 刚创建的证书
   - Device: 当前Mac（需获取UDID）

**获取Mac UDID：**
```bash
system_profiler SPHardwareDataType | grep "Serial Number" | awk '{print $4}'
```

---

### 步骤2：本地配置（可代为操作）

**2.1 导入证书到Keychain**
```bash
# 导入Developer Certificate
security import ~/Downloads/developer_certificate.cer \
  -k ~/Library/Keychains/login.keychain-db \
  -T /usr/bin/codesign \
  -T /Applications/Xcode.app/Contents/Developer/usr/bin/codesign

# 验证导入成功
security find-identity -v -p codesigning
# 输出：1 valid identities found ✅
```

**2.2 配置Xcode Signing（自动化脚本）**
```bash
# 创建Xcode项目配置
xcodebuild -project MarkBaseFSKit.xcodeproj \
  -scheme MarkBaseFSKit \
  -configuration Release \
  -destination 'platform=macOS' \
  CODE_SIGN_IDENTITY="Apple Development" \
  DEVELOPMENT_TEAM="<YOUR_TEAM_ID>" \
  PRODUCT_BUNDLE_IDENTIFIER="com.momentry.markbase.fskit"
```

**2.3 构建签名应用**
```bash
# 构建Release版本
xcodebuild clean build \
  -project MarkBaseFSKit.xcodeproj \
  -scheme MarkBaseFSKit \
  -configuration Release \
  CODE_SIGN_IDENTITY="Apple Development" \
  DEVELOPMENT_TEAM="<YOUR_TEAM_ID>" \
  PRODUCT_BUNDLE_IDENTIFIER="com.momentry.markbase.fskit"

# 验证签名
codesign -d -vv --entitlements - build/Release/MarkBaseFSKit.app
```

---

### 步骤3：用户批准（需要手动操作）

**安装System Extension：**
```bash
# 使用systemextensionsctl安装
systemextensionsctl install \
  --team <TEAM_ID> \
  --bundleID com.momentry.markbase.fskit \
  --type filesystem \
  build/Release/MarkBaseFSKit.app
```

**用户批准流程：**
1. macOS弹出提示："MarkBaseFSKit wants to install a system extension"
2. 打开 **System Settings → Privacy & Security**
3. 点击 **Allow** 按钮
4. 重启Mac完成安装

**验证安装成功：**
```bash
systemextensionsctl list
# 输出：1 extension(s) ✅
# MarkBaseFSKit (com.momentry.markbase.fskit) [active]
```

---

## 可代为操作的步骤

|步骤 |可自动化 |需要手动 |
|------|---------|----------|
| Developer Portal登录 | ❌ | ✅ 需要Apple ID密码 |
| 创建App ID | ❌ | ✅ 需要手动填写 |
| 创建Certificate | ❌ | ✅ 需要手动操作 |
| 下载.cer文件 | ❌ | ✅ 需要手动下载 |
| 导入证书到Keychain | ✅ | - 脚本自动执行 |
| 配置Xcode Signing | ✅ | - 脚本自动执行 |
| 构建签名应用 | ✅ | - 脚本自动执行 |
| System Settings批准 | ❌ | ✅ 需要用户点击 |
| 重启Mac | ❌ | ✅ 需要用户操作 |

**总结：**
- 60%可自动化（导入证书、构建、签名）
- 40%需手动（Portal操作、用户批准）

---

## 快速开始（假设已有证书）

如果用户已下载证书到 `~/Downloads/`，可以执行：

```bash
# 一键安装脚本（假设证书已下载）
./scripts/install_system_extension.sh
```

**脚本内容：**
```bash
#!/bin/bash
# scripts/install_system_extension.sh

# 1. 导入证书
security import ~/Downloads/developer_certificate.cer \
  -k ~/Library/Keychains/login.keychain-db \
  -T /usr/bin/codesign

# 2. 构建签名应用
xcodebuild -project MarkBaseFSKit.xcodeproj \
  -scheme MarkBaseFSKit \
  -configuration Release \
  CODE_SIGN_IDENTITY="Apple Development" \
  DEVELOPMENT_TEAM="<TEAM_ID>" \
  PRODUCT_BUNDLE_IDENTIFIER="com.momentry.markbase.fskit"

# 3. 安装System Extension
systemextensionsctl install \
  --team <TEAM_ID> \
  --bundleID com.momentry.markbase.fskit \
  --type filesystem \
  build/Release/MarkBaseFSKit.app

echo "✅ System Extension已安装，请到System Settings批准"
```

---

## 下一步

**需要用户提供：**
1. Apple Developer账户状态（是否有账户？）
2. 是否已下载Developer Certificate
3. Team ID（10字符，如：ABC12DEF34）

**我可以提供：**
1. 完整的自动化脚本（`install_system_extension.sh`）
2. Xcode项目模板（`MarkBaseFSKit.xcodeproj`）
3. Entitlements配置文件

---

**最后更新：** 2026-05-18 17:28