# System Extension 手动安装指南

## 当前状态

**.app Bundle已准备好：**
- Location: build/MarkBaseFSKit.app
- Bundle ID: com.momentry.markbase.fskit
- Certificate: Developer ID Application: Accusys,Inc (K3TDMD9Y6B)
- Team ID: K3TDMD9Y6B
- Status: Signed ✅

---

## 安装方法

### 方法1：直接打开（尝试中）

```bash
open build/MarkBaseFSKit.app
```

**预期结果：**
- macOS弹出："MarkBaseFSKit wants to install a system extension"
- System Settings → Privacy & Security → Allow按钮出现
- 点击Allow → 重启Mac → 安装完成

**如果无反应：**
- 需要将.app复制到Applications目录

---

### 方法2：复制到Applications（标准方法）

```bash
# 需要sudo权限
sudo cp -r build/MarkBaseFSKit.app /Applications/

# 打开.app触发安装
open /Applications/MarkBaseFSKit.app
```

**安装流程：**
1. macOS弹出："MarkBaseFSKit wants to install a system extension"
2. 点击"Open System Settings"
3. System Settings → Privacy & Security
4. 找到"System Extension from Accusys,Inc"条目
5. 点击**Allow**按钮
6. macOS要求重启 → Restart
7. 重启后System Extension安装完成

---

## 验证安装成功

```bash
systemextensionsctl list
```

**预期输出：**
```
1 extension(s)
MarkBaseFSKit (com.momentry.markbase.fskit) [active]
```

---

## 如果安装失败

### 可能原因：

**1. .app Bundle结构问题**
- 缺少PkgInfo文件
- Info.plist格式错误
- entitlements配置不正确

**解决方案：**
```bash
# 添加PkgInfo文件
echo -n "APPL????" > build/MarkBaseFSKit.app/Contents/PkgInfo

# 重新签名
codesign --sign "Developer ID Application: Accusys,Inc (K3TDMD9Y6B)" \
  --entitlements entitlements.plist \
  --identifier "com.momentry.markbase.fskit" \
  --options runtime \
  --timestamp \
  build/MarkBaseFSKit.app
```

**2. System Extension类型不支持**
- macOS可能需要特定类型的System Extension
- 当前设置：filesystem类型

**解决方案：**
- 检查Info.plist中NSSystemExtension=true
- 检查entitlements中com.apple.developer.system-extension权限

**3. 证书权限问题**
- Developer ID Application证书可能需要特定权限

**解决方案：**
- 检查证书是否支持System Extension签名
- 查看Portal证书详情

---

## System Extension调试

**检查.app bundle完整性：**
```bash
codesign -d -vv --entitlements - build/MarkBaseFSKit.app
```

**检查Gatekeeper评估：**
```bash
spctl -a -vv build/MarkBaseFSKit.app
```

**检查System Extension日志：**
```bash
log show --predicate 'process == "systemextensionsd"' --last 5m
```

---

## 当前需要用户执行

**步骤1：** 如果直接打开无反应，手动复制到Applications
```bash
sudo cp -r build/MarkBaseFSKit.app /Applications/
```

**步骤2：** 打开.app触发安装
```bash
open /Applications/MarkBaseFSKit.app
```

**步骤3：** System Settings批准
- Privacy & Security → Allow
- 重启Mac

---

**最后更新：** 2026-05-18 20:37