SDK 下载与示例 App

#下载

两个下载都处于内测阶段（0.1.0）。示例 App 只用于演示和联调，请只使用测试条目。

提示 如果打开已构建的示例 App 时 macOS 提示无法验证开发者，请在「访达」中右键点按 App，选择「打开」。

#把 SDK 加入你的项目

1. 解压 mimikey-swift-sdk-0.1.0.zip，得到 MimiKeySDK 与 Examples 两个目录。
2. 在 Xcode 中选择 File → Add Package Dependencies…，点左下角的 Add Local…，选择 MimiKeySDK 目录。
3. 把产品 MimiKeySDK 添加到你的 App target。

之后的配置（Info.plist、回调、API）见 Swift SDK。

#从源码运行示例 App

示例 App 是一个 iOS 与 macOS 共用的 SwiftUI 工程，用 XcodeGen 描述（Examples/MimiKeyDemo/project.yml）。工程以相对路径引用 SDK 包，请保持解压后的目录结构不变。

brew install xcodegen
cd Examples/MimiKeyDemo
xcodegen generate
open MimiKeyDemo.xcodeproj

macOS： 选择 scheme MimiKeyDemo 与目标 My Mac，直接运行。工程默认使用本机临时签名，无需开发者账号。

iOS： 在 target 的 Signing & Capabilities 中选择你的 Team（如有冲突，把 Bundle ID 改成你自己的前缀），选择一台装有 MimiKey 的真机运行。iOS 模拟器上通常没有 MimiKey，示例 App 会提示「未安装 MimiKey」。

也可以用命令行只做编译检查：

xcodebuild -project MimiKeyDemo.xcodeproj -scheme MimiKeyDemo \
  -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO build

#示例 App 界面

示例 App 只有一个表单页，从上到下分为六个分区：

等待 MimiKey 时，页面中央会出现等待层：一行等待提示、到期时间，以及「重试（再次打开 MimiKey）」和「取消」两个按钮。

#完整演练

以下以 Mac 为例；在 iPhone 上步骤相同，只是 MimiKey 与示例 App 之间是整屏切换。

#1. 登记公开客户端

1. 打开 MimiKey for Mac 并登录，在侧栏点「开发者接入」。
2. 点「新建应用」，填写：
   • 名称：例如「MimiKey Demo」；
   • 类型：「公开客户端 · App 内 SDK，无 secret」；
   • 平台：勾选 iOS 和 macOS；
   • 回调地址：mimikeydemo://mimikey/callback。
3. 点「登记」，复制显示的 client_id（pmc_…）。

#2. 填写设置

打开示例 App，在「设置」分区粘贴 client_id。连接正式服务时「服务器」保持默认值即可。

#3. 授权

1. 在「授权」分区点「授权」。示例 App 显示等待层「等你在 MimiKey 里确认授权」，并切换到 MimiKey。
2. MimiKey 若处于锁定状态，先用 Touch ID / 面容 ID 或主密码解锁。
3. MimiKey 显示同意卡：应用名称、「将能做什么」四行、要授权的库（默认勾选个人库）、审批策略（默认「每次询问」）和审批钥指纹。
4. 点「允许」。MimiKey 打开 mimikeydemo://mimikey/callback?mk=authorize&code=…&state=…，示例 App 回到前台并换取令牌。

预期结果： 状态显示「已授权：grant 1a2b3c4d…，审批钥指纹 d1984a0a3442c41c」；「授权」分区显示 grant、审批钥指纹（与同意卡上的一致）和授权的库名。

#4. 选一个条目

1. 在「选一个条目」分区保留或修改提示网址，点「选一个条目」。等待层显示「等你在 MimiKey 里选一个条目」。
2. MimiKey 显示选条目卡：标题「MimiKey Demo 请你选一个条目」，候选按提示网址排序，可以搜索；列表不显示密码。
3. 选中一条，点「用这条」。MimiKey 打开 …?mk=request&request_id=…&state=…&status=completed。

预期结果： 状态显示「已拿到『示例银行』（修订 1）」；分区里出现标题、用户名、被遮挡的密码（点「显示」查看）、网址与「login / 1」。「修改密码」分区的「库 ID」会自动填入本授权的第一个库。

#5. 新建

1. 在「新建（登录）」分区填写标题、网址和可选的用户名提示，点「新建」。等待层显示「等你在 MimiKey 的安全卡里填写并保存」。
2. MimiKey 显示安全卡：一张登录条目的编辑表单，已预填你提供的标题、网址和用户名，密码为空；底部可以选择保存到哪个库。
3. 在 MimiKey 里输入密码，点「保存并用于本次任务」。

预期结果： 存入授权的库时，状态显示「已新建并返回『示例银行』」，「选一个条目」分区显示新条目。若在卡上选择了授权范围之外的库，状态显示「已保存到授权范围之外的库，本次拿不到明文」。

#6. 修改密码

1. 先完成第 4 或第 5 步，使「选一个条目」分区有一条已选条目。
2. 确认「库 ID」是该条目所在的库，输入「新密码」，点「修改密码」。等待层显示「等你在 MimiKey 里确认修改」。
3. MimiKey 显示修改卡：标题「MimiKey Demo 想修改『示例银行』」，列出「原」与「新」两行（密码默认遮挡，可点「显示」），以及当前修订号。
4. 点「保存修改」。

预期结果： 状态显示「已修改，新修订 2」，已选条目被清空（示例 App 不会收到修改后的明文；需要时重新选择即可）。

#7. 撤销授权

在「授权」分区点「撤销授权」。示例 App 调用撤销接口并清空本机钥匙串。

预期结果： 状态显示「已撤销」，「授权」分区回到未授权状态。在 MimiKey「第三方授权」中，这条授权不再显示为有效授权。

#回调与状态对照

回调只携带 ID 与状态。真正的结果由 SDK 用签名请求取回，再用本机的 seal 私钥解开。

#故障排查