markbase/docs/IMPLEMENTATION_PLAN.md

MarkBaseFS System Extension Installer 实施方案

日期: 2026-05-24 状态: 阶段9暂停，待重新规划 问题: App Bundle结构不完整导致启动失败(错误163)

---

实施进度总结

已完成 ✅

1. xcode-select配置

   • 配置成功: /Applications/Xcode.app/Contents/Developer（Xcode 26.5）
   • 更新时间: 2026-05-24（已从Volume 1的Xcode 16.2更新）

2. App Store Connect API Key创建

   • Key ID: 94FCMLS254
   • Issuer ID: 69a6de72-d392-47e3-e053-5b8c7c11a4d1
   • Private Key: ~/.appstoreconnect/AuthKey_94FCMLS254.p8

3. Notarization流程验证

   • Submission ID: 155b81b3-6f37-43c8-bcb7-75e3dd3ef3d2
   • 状态: Accepted ✅
   • 验证: source=Notarized Developer ID

4. Staple公证结果

   • 执行成功: xcrun stapler staple
   • 验证通过: Gatekeeper accepted

---

失败项 ❌

1. App启动失败(错误163)

   • 原因: App Bundle缺少必要的资源文件
   • Resources目录为空(缺少Assets.xcassets等)

2. 使用VPN模板编译失败

   • getlantern/systemextensiondemo是VPN项目(不适用)
   • 缺少provisioning profile和XCFramework

---

关键发现

Notarization完整流程(已验证成功)

# 1. 创建API Key(App Store Connect网页操作)
# 2. 配置API Key文件
mkdir -p ~/.appstoreconnect
mv ~/Downloads/AuthKey_*.p8 ~/.appstoreconnect/

# 3. 创建配置文件
cat > ~/.appstoreconnect/api_key.json << 'EOF'
{
  "key_id": "94FCMLS254",
  "issuer_id": "69a6de72-d392-47e3-e053-5b8c7c11a4d1",
  "key_filepath": "~/.appstoreconnect/AuthKey_94FCMLS254.p8"
}
EOF

# 4. 打包App
zip -r MarkBaseInstaller.zip MarkBaseInstaller.app

# 5. 提交Notarization
xcrun notarytool submit MarkBaseInstaller.zip \
  --key-id 94FCMLS254 \
  --issuer 69a6de72-d392-47e3-e053-5b8c7c11a4d1 \
  --key ~/.appstoreconnect/AuthKey_94FCMLS254.p8 \
  --wait

# 6. Staple公证结果
xcrun stapler staple MarkBaseInstaller.app

# 7. 验证
spctl -a -t exec -vv MarkBaseInstaller.app

错误163根本原因

结论: App Bundle结构不完整

缺失文件:

• Assets.xcassets(App图标等资源)
• MainMenu.xib或Storyboard(GUI配置)
• 正确的NSApplication初始化代码

---

解决方案对比

方案A: 使用Xcode GUI创建项目(推荐)

优势:

• ✅ 业界标准流程
• ✅ 自动生成完整App Bundle结构
• ✅ 自动处理签名和entitlements
• ✅ 内置System Extension capability
• ✅ 可直接Archive → Notarize → Staple

步骤:

1. 创建Xcode项目(5分钟)

打开Xcode
→ File → New → Project
→ macOS → App
→ 配置:
  - Product Name: MarkBaseInstaller
  - Team: K3TDMD9Y6B
  - Organization Identifier: com.momentry.markbase
  - Bundle ID: com.momentry.markbase.installer(自动生成)
  - Language: Swift
  - Interface: SwiftUI(推荐)或Storyboard

2. 配置System Extension Capability(2分钟)

Target → Signing & Capabilities
→ + Capability → System Extension
→ 自动添加entitlements:
  - com.apple.developer.system-extension.install = true

3. 修改Bundle ID(可选，若需要)

Target → General
→ Bundle Identifier: com.momentry.markbase.installer

4. 复制Swift代码(3分钟)

AppDelegate.swift(若使用Storyboard):

import Cocoa
import SystemExtensions

class AppDelegate: NSObject, NSApplicationDelegate {
    var window: NSWindow!
    var statusLabel: NSTextField!
    var installButton: NSButton!
    
    func applicationDidFinishLaunching(_ aNotification: Notification) {
        createWindow()
        setupUI()
    }
    
    func createWindow() {
        window = NSWindow(
            contentRect: NSRect(x: 0, y: 0, width: 480, height: 300),
            styleMask: [.titled, .closable, .miniaturizable],
            backing: .buffered,
            defer: false
        )
        window.title = "MarkBase Installer"
        window.center()
        window.makeKeyAndOrderFront(nil)
    }
    
    func setupUI() {
        let contentView = window.contentView!
        
        statusLabel = NSTextField(labelWithString: "Ready to install MarkBaseFS System Extension")
        statusLabel.alignment = .center
        contentView.addSubview(statusLabel)
        
        installButton = NSButton(title: "Install System Extension", target: self, action: #selector(installExtension(_:)))
        contentView.addSubview(installButton)
        
        // Layout constraints...
    }
    
    @objc func installExtension(_ sender: NSButton) {
        let request = OSSystemExtensionRequest.activationRequest(
            forExtensionWithIdentifier: "com.momentry.markbase.fskit",
            queue: .main
        )
        request.delegate = self
        OSSystemExtensionManager.shared.submitRequest(request)
    }
}

extension AppDelegate: OSSystemExtensionRequestDelegate {
    func request(_ request: OSSystemExtensionRequest, didFinishWithResult result: OSSystemExtensionRequest.Result) {
        // 处理成功
    }
    
    func request(_ request: OSSystemExtensionRequest, didFailWithError error: Error) {
        // 处理失败
    }
    
    func requestNeedsUserApproval(_ request: OSSystemExtensionRequest) {
        // 提示用户批准
    }
    
    func request(_ request: OSSystemExtensionRequest, actionForReplacingExtension existing: OSSystemExtensionProperties, withExtension ext: OSSystemExtensionProperties) -> OSSystemExtensionReplacementAction {
        return .replace
    }
}

ContentView.swift(若使用SwiftUI):

import SwiftUI
import SystemExtensions

struct ContentView: View {
    @State private var statusMessage = "Ready to install MarkBaseFS System Extension"
    @State private var isInstalling = false
    
    var body: some View {
        VStack(spacing: 20) {
            Text(statusMessage)
                .font(.headline)
                .multilineTextAlignment(.center)
            
            Button(action: installExtension) {
                if isInstalling {
                    ProgressView()
                        .scaleEffect(0.8)
                } else {
                    Text("Install System Extension")
                }
            }
            .disabled(isInstalling)
            .buttonStyle(.borderedProminent)
        }
        .padding()
        .frame(width: 480, height: 300)
    }
    
    func installExtension() {
        isInstalling = true
        statusMessage = "Requesting installation..."
        
        let request = OSSystemExtensionRequest.activationRequest(
            forExtensionWithIdentifier: "com.momentry.markbase.fskit",
            queue: .main
        )
        // Delegate implementation...
    }
}

5. Build → Archive → Notarize(10分钟)

# Build
xcodebuild -project MarkBaseInstaller.xcodeproj \
  -scheme MarkBaseInstaller \
  -configuration Release \
  clean build

# Archive
xcodebuild -project MarkBaseInstaller.xcodeproj \
  -scheme MarkBaseInstaller \
  -archivePath build/MarkBaseInstaller.xcarchive \
  archive

# Export
xcodebuild -exportArchive \
  -archivePath build/MarkBaseInstaller.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions.plist

# ExportOptions.plist内容:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>developer-id</string>
    <key>teamID</key>
    <string>K3TDMD9Y6B</string>
</dict>
</plist>

# Notarize
xcrun notarytool submit build/export/MarkBaseInstaller.zip \
  --key-id 94FCMLS254 \
  --issuer 69a6de72-d392-47e3-e053-5b8c7c11a4d1 \
  --key ~/.appstoreconnect/AuthKey_94FCMLS254.p8 \
  --wait

# Staple
xcrun stapler staple build/export/MarkBaseInstaller.app

# 验证
spctl -a -t exec -vv build/export/MarkBaseInstaller.app

6. 测试安装(2分钟)

# 启动App
open build/export/MarkBaseInstaller.app

# 点击Install按钮 → 用户批准

# 验证安装
systemextensionsctl list
# 预期输出:
# com.momentry.markbase.fskit (version 1.0) [activated]

预估总时间: 20-25分钟

---

方案B: 修复现有MarkBaseInstaller.app(困难)

需要手动添加:

1. Assets.xcassets

   • 创建App图标资源
   • 配置AppIcon.appiconset

2. MainMenu.xib或Storyboard

   • 创建GUI界面
   • 配置NSApplication初始化

3. 修复Info.plist

   • 添加NSMainNibFile配置

预估时间: 30-40分钟

风险: 高(可能仍遇到其他结构性问题)

---

方案C: 使用命令行创建最小App Bundle(实验性)

步骤:

# 1. 创建目录结构
mkdir -p MarkBaseInstaller_New.app/Contents/{MacOS,Resources}

# 2. 编译Swift代码
swiftc -o MarkBaseInstaller_New.app/Contents/MacOS/MarkBaseInstaller \
  -target arm64-apple-macos14 \
  -framework Cocoa \
  -framework SystemExtensions \
  AppDelegate.swift

# 3. 创建Info.plist
cat > MarkBaseInstaller_New.app/Contents/Info.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIdentifier</key>
    <string>com.momentry.markbase.installer</string>
    <key>CFBundleName</key>
    <string>MarkBase Installer</string>
    <key>CFBundleExecutable</key>
    <string>MarkBaseInstaller</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>LSMinimumSystemVersion</key>
    <string>14.0</string>
    <key>NSPrincipalClass</key>
    <string>NSApplication</string>
</dict>
</plist>
EOF

# 4. 创建PkgInfo
echo -n "APPL????" > MarkBaseInstaller_New.app/Contents/PkgInfo

# 5. 签名
codesign --force --sign "Developer ID Application: Accusys,Inc (K3TDMD9Y6B)" \
  --entitlements entitlements.plist \
  --deep --options runtime \
  MarkBaseInstaller_New.app

# 6. Notarize + Staple(流程同上)

预估时间: 15-20分钟

风险: 中(可能仍缺少GUI资源)

---

推荐选择

推荐: 方案A(使用Xcode GUI)

理由:

1. 最可靠(业界标准流程)
2. 最快速(自动处理所有配置)
3. 最安全(避免结构性问题)
4. 可维护(未来修改方便)

---

API Key配置信息(已创建，可复用)

Key ID: 94FCMLS254 Issuer ID: 69a6de72-d392-47e3-e053-5b8c7c11a4d1 Private Key路径: ~/.appstoreconnect/AuthKey_94FCMLS254.p8

配置文件路径: ~/.appstoreconnect/api_key.json

---

开发者证书信息

证书: Developer ID Application: Accusys,Inc (K3TDMD9Y6B) Team ID: K3TDMD9Y6B 证书ID: EC458E4414308FDFE98616D2C0D90B684B5BD973

---

Xcode配置信息（已更新）

Xcode路径: /Applications/Xcode.app（主系统盘） Xcode版本: 26.5 (Build 17F42) xcode-select: 已配置到Xcode 26.5 xcrun版本: 72 Swift版本: 6.3.2 Clang版本: 21.0.0 Target平台: arm64-apple-macosx26.0

更新说明:

• 从Volume 1的Xcode 16.2更新到主系统盘的Xcode 26.5
• 与macOS 26.5完美匹配
• 内置最新FSKit支持和System Extension模板

---

磁盘配置信息

卷宗名称	挂载点	设备	类型	大小
KX_macOS_2T	/	disk6s1s1	启动盘(外部2TB NVMe)	1.9TB
Volume 1	/Volumes/Volume 1	disk2s3	内部SSD分区	122GB
Volume 2	/Volumes/Volume 2	disk3s3	内部SSD分区	122GB

---

下次实施建议

开始步骤:

1. 打开Xcode GUI(方案A)
2. 创建新项目
3. 配置System Extension Capability
4. 复制Swift代码
5. Build → Archive → Notarize → Staple
6. 测试安装

预估总时间:

• 方案A: 20-25分钟
• 方案B: 30-40分钟
• 方案C: 15-20分钟

---

注意事项

⚠️ API Key已创建，无需重新创建

重要:

• API Key配置已完成(Key ID + Issuer ID + Private Key)
• Private Key只能下载一次，已保存
• 下次实施时直接使用现有配置

⚠️ Notarization流程已验证成功

重要:

• Notarization流程正确(Submission ID已记录)
• Staple流程正确(验证通过)
• 下次实施时无需重新验证流程

⚠️ 错误163根本原因已明确

重要:

• 问题不是Notarization(公证成功)
• 问题不是签名(签名正确)
• 问题: App Bundle结构不完整

---

参考文档

Apple官方文档:

• System Extensions: https://developer.apple.com/documentation/systemextensions
• Notarization: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution

开源参考:

• getlantern/systemextensiondemo(VPN项目，流程参考)
• knightsc/USBApp(DriverKit项目，结构参考)

---

实施记录详情

Notarization提交记录

Submission ID: 155b81b3-6f37-43c8-bcb7-75e3dd3ef3d2 提交时间: 2026-05-24 00:17 处理状态: Accepted ✅ 处理时间: 约1分钟

输出日志:

Conducting pre-submission checks for MarkBaseInstaller.zip...
Initiating connection to the Apple notary service...
Successfully uploaded package
  id: 155b81b3-6f37-43c8-bcb7-75e3dd3ef3d2
  path: /Users/accusys/markbase/build/MarkBaseInstaller.zip
Waiting for processing to complete...
Current status: In Progress....Current status: In Progress....Current status: Accepted.....Processing complete!
  id: 155b81b3-6f37-43c8-bcb7-75e3dd3ef3d2
  status: Accepted

---

错误163详细记录

错误代码: POSIX error 163 错误描述: "Unknown error: 163" / "Launchd job spawn failed" 触发场景: 执行 open MarkBaseInstaller.app

诊断过程:

1. 检查二进制文件: otool -L

   • 结果: 链接正确(SystemExtensions.framework存在)

2. 检查main函数: nm | grep main

   • 结果: _main存在

3. 检查签名: codesign -dv

   • 结果: 签名正确(Developer ID Application)

4. 检查公证: spctl -a -t exec -vv

   • 结果: 公证正确(Notarized Developer ID)

5. 检查Resources目录: ls Contents/Resources/

   • 结果: 空目录 ❌

根本原因: App Bundle缺少必要的资源文件和GUI初始化配置

---

文件路径记录

文件类型	路径
API Key配置	~/.appstoreconnect/api_key.json
Private Key	~/.appstoreconnect/AuthKey_94FCMLS254.p8
打包文件	/Users/accusys/markbase/build/MarkBaseInstaller.zip
App Bundle	/Users/accusys/markbase/tools/MarkBaseInstaller.app
模板项目	/Users/accusys/markbase/tools/systemextensiondemo/
Xcode路径	/Applications/Xcode.app（Xcode 26.5）
本实施方案	/Users/accusys/markbase/docs/IMPLEMENTATION_PLAN.md

---

---

xcode-select配置记录（更新）

配置时间: 2026-05-24 之前配置: /Volumes/Volume 1/Applications/Xcode_16.2.app（Xcode 16.2） 当前配置: /Applications/Xcode.app（Xcode 26.5）

配置命令:

sudo xcode-select --switch /Applications/Xcode.app

验证结果:

xcode-select -p
/Applications/Xcode.app/Contents/Developer

xcodebuild -version
Xcode 26.5
Build version 17F42

xcrun --version
xcrun version 72

swift --version
swift-driver version: 1.148.6 Apple Swift version 6.3.2
Target: arm64-apple-macosx26.0

关键变化:

项目	之前	现在
Xcode版本	16.2	26.5 ✅
xcrun版本	70	72 ✅
Swift版本	-	6.3.2 ✅
Target	-	macOS 26.0 ✅

---

文档生成时间: 2026-05-24 00:30 状态: 已更新xcode-select配置，待明天继续实施