大模型

OpenMinis 架构分析

自我介绍大家好,我是Aaron。OpenMinis 是一款完全运行在设备端的开源 AI Agent 应用,覆盖 iOS 与 Android 双平台。一个跑在 App 进程内的完整 Linux 沙箱、浏览器自动化、可扩展的 Skills、跨会话持久记忆及深度的系统集成。本文重点介绍其实现细节。

OpenMinis 架构分析

OpenMinis 架构分析

本文档按”总—分”结构组织:从项目定位与顶层架构出发,逐层下钻到核心子系统、双平台实现、构建系统与关键交互流程,辅以架构图与流程图。 源码对应仓库 OpenMinis/OpenMinis:iOS 端 363 个 Swift 文件(Swift/SwiftUI,iOS 26.2 / Swift 6.0);Android 端 454 个 Kotlin 文件 + JNI 原生代码(Kotlin/Compose,minSdk 26,arm64-v8a)。


目录

  1. 项目概览

  2. 顶层架构

  3. 仓库布局

  4. 核心子系统详解

  • 4.1 Agent 运行时

  • 4.2 Linux 沙箱(iSH / PRoot + Alpine)

  • 4.3 原生卸载系统(Native Offloads)

  • 4.4 LLM Provider 系统

  • 4.5 Skills 系统

  • 4.6 Memory 持久化

  • 4.7 浏览器自动化

  • 4.8 语音(Speech)

  • 4.9 minis:// URL 方案

  1. 平台实现对比

  2. 设备集成与扩展

  3. 构建系统

  4. 关键交互流程

  5. 调试与可观测性

  6. 已知限制与优化建议


1. 项目概览

OpenMinis 是一款完全运行在设备端(on-device)的开源 AI Agent 应用,覆盖 iOS 与 Android 双平台。它把主流大模型(Claude / GPT / Gemini / xAI / Kimi / OpenRouter 等)接入原生移动体验,并给模型配上一台”真正的电脑”来干活——一个跑在 App 进程内的完整 Linux 沙箱、浏览器自动化、可扩展的 Skills、跨会话持久记忆,以及深度的系统集成。

维度 说明
定位 私有、端侧的 AI Agent——数据不出设备(除非主动调用云上模型 API)
平台 iOS(Swift / SwiftUI,iOS 26.2,Swift 6.0)/ Android(Kotlin / Compose,minSdk 26,arm64-v8a)
许可证 GPLv3(因链接 iSH GPLv3 与 PRoot GPLv2,组合工作以 GPLv3 分发)
模型接入 自带 API Key 或账号 OAuth 登录;支持自定义 Base URL(OpenAI 兼容端点,可接 DeepSeek 等中转)
核心能力 Linux Shell、浏览器自动化、设备集成(Health/Calendar/Contacts/HomeKit/…)、Skills、Memory、Workspaces、原生卸载
沙箱内核 iOS 用 iSH(ARM64 用户态 Linux 模拟);Android 用 PRoot(ptrace 系统调用拦截 + bind mount);均启动 Alpine Linux aarch64

产品哲学(README):“在 AI 时代,技术设计与代码不再是产品的优势所在。最好的 Agent 源于与使用者的紧密反馈闭环——他们的期望与反馈共同收敛于产品。” 因此主仓库不接受 PR(是私有开发树的镜像),通过 Issues、AwesomeMinis(用例集)与 MinisSkills(Skill 集)接收社区贡献。

典型用法

  • 拍一张饭菜照片 → 识别菜品、估算卡路里与宏量营养素 → 写入 Apple Health

  • Shortcuts 触发 → 抓取 X 时间线、摘要、合成语音 → 作为闹钟播放

  • 从 Telegram 群拉消息 → 抽取 bug 与待办、去重 → 写入 Apple Reminders

  • 挂载 Obsidian vault → 研究、清理并写回 Markdown 笔记(作为普通 workspace)

  • 通过 iOS Share Sheet 发送页面/消息 → 自动创建日历事件(含时间地点)


2. 顶层架构

OpenMinis 是一个分层 + 桥接的端侧 Agent 系统。自上而下分四层:UI 与交互层、Agent 运行时层、能力层(LLM Provider + Linux 沙箱 + 原生卸载 + Skills/Memory/Browser/Speech)、持久化与同步层。层与层之间通过明确的协议/接口解耦,使 LLM Provider 可互换、沙箱实现可平台替换(iOS 用 iSH,Android 用 PRoot)。

2.1 整体分层架构图

图片 1

2.2 设计要点

  • Agent-first:一切持久产物以 minis:// URL 回传模型,模型可在后续轮次直接引用(图片内联渲染、文件可点击预览)。

  • 沙箱是产品的心脏:iOS 在 App 进程内跑一个完整 Alpine Linux(iSH 用户态内核),Android 用 PRoot 在用户态 chroot 出同样的环境。模型由此获得 apk/pip/node 等真实工具链,而非被关在玩具沙箱里。

  • 原生卸载桥接:guest 进程对 /usr/local/bin/apple-*(或 android-*)调用 execve 时被拦截,路由到原生 iOS/Android Framework——让 guest 命令能访问 HealthKit、相册、日历等硬件/系统能力。传输分两套:iOS 是进程内 execve 钩子(handler 直接函数调用,结果经 noff_emit_json 写 guest 的 stdout fd,无 IPC);Android 经 abstract Unix socket(二进制帧 NOFF/NORF),handler 输出写 rootfs tmpfile、PRoot 把 execve 重写为 /bin/cat <tmpfile>。

  • Provider 可互换:LLMProvider / AgentProvider 协议统一所有模型后端;xAI、Kimi、OpenRouter 直接复用 OpenAIProvider,仅靠自定义 Base URL + 凭证区分,几乎零重复代码。

  • 跨平台共享语义:系统提示词、工具 schema、bashism 检测规则(assets/bashism/bashism_rules.json)双平台单一真相源,保证同一 prompt 在两平台行为一致。


3. 仓库布局

OpenMinis/
├── src/
│   ├── ios/              iOS App(Swift / SwiftUI)+ Share/Widget/FileProvider 扩展
│   ├── android/          Android App(Kotlin / Compose)+ JNI 原生代码
│   └── shared/           双平台共享资产(bashism 规则等)
├── deps/                 原生依赖构建脚本 + vendored 源(iSH / PRoot / FFmpeg / LAME / talloc)
├── docs/specs/          架构与接口规范(沙箱摘要 / URL scheme / debug server API)
├── scripts/             rootfs 准备与开发者工具
├── assets/              截图、应用商店徽章
├── BUILDING.md          首次构建指南
└── README.md

文件规模(按类型)

类型 数量 所属
Kotlin 454 Android
Swift 363 iOS
C/C++/H 61 原生桥接(iSH、JNI、崩溃处理、jieba)
Python 18 脚本与工具
Shell 多个 deps/ 与 scripts/

iOS 关键目录

目录 职责
Agent/Chat/ Agent 运行时核心:AIChatViewModel、Agent 循环、工具调度、SSE 流处理、SQLite 会话存储
Agent/Session/ 会话级状态:SkillStore、MCPStore、SoulStore(人格文件)、SessionLockStore、SessionForkManager
Agent/ISH/ iSH 命令执行协调:ISHExecutionCoordinator、MinisFsRouter(fakefs 路由)、命令环形缓冲
Agent/Shell/ Shell 工具:OnDemandBash(按需装 bash)、BashismDetector、BashismReminder
Agent/Offload/ 卸载权限管理:OffloadPermissionManager(敏感命令三级权限)
Agent/Markdown/ Markdown 渲染、KaTeX、minis:// URL 内联渲染、MinisImageProvider
Agent/BrowserUse/ 浏览器自动化:BrowserTabPool、WKWebView、get_readable、截图
Agent/Speech/ 语音:STT / TTS / VAD
Agent/Sync/ , Agent/Sync/V2/ iCloud 同步
Agent/Intents/ Apple Shortcuts / AppIntents(SendPromptIntent 等)
iSH/ iSH 内核桥接:ISHKernel(Obj-C 单例)、RootfsManager、ISHShellExecutor
Providers/ LLM Provider 系统(8 个后端)+ 模型管理(ProviderConfigStore、ModelEntry、ModelGroup)
NativeOffloads/ 22 个 apple-* 原生卸载处理器(Obj-C + Swift bridge)
Shared/ 跨子系统基础设施:TextSegmenter、BPETokenizer、EnvVarStore、AppLogger、Config 体系、DeepLink 路由
ShareExtension/ iOS Share Sheet 扩展
AgentWidget/ 桌面小组件 / Live Activity
FileProvider/ 文件 provider 扩展(vault 挂载)
WebApp/ PWA / “添加到主屏幕” 元数据
Diagnostics/ 崩溃报告、浏览器资源监控

Android 关键包(com.openminis.app.*)

包 职责
ui.chat ChatViewModel (Agent 循环核心,约 9000 行)、ChatScreen、Markdown、流式 UI
provider + 子包 LLMProvider 接口、ProviderFactory、anthropic/openai/gemini 实现
sandbox + sandbox.offload PRootKernel、ExecutionCoordinator、PersistentShell、NativeOffloadServer、PtyBridge、20+ android-* handler
tools AgentTools 注册表、FileRead/Write/EditTool、ReadImageTool、BrowserUseTool、MemoryTools
agent ToolLoopDetector、SoulStore、shell/BashismDetector、shell/OnDemandBash
offload ShizukuManager /ShizukuBackend、OffloadPermissionManager、设备管理器
browser BrowserUseManager、BrowserTabPool、BrowserAction
data + data.db Room DB(AppDatabase)、各 Repository
auth 各 Provider OAuth 管理器
config ConfigRegistry、minis-config CLI 层
service AgentForegroundService、SessionActivityTracker、ToolOverlayController
accessibility MinisAccessibilityService (UI 自动化后端)
crash NativeCrashHandler、CrashFrequencyDetector(安全模式)
mcp MCP OAuth 集成

4. 核心子系统详解

4.1 Agent 运行时

Agent 运行时是 OpenMinis 的核心:把用户 prompt 驱动为一个多轮 Agent 循环——调用 LLM 生成文本与工具调用、并发执行工具(shell 命令、文件操作、浏览器操作、记忆读写)、把工具结果回传 LLM、最终产出完整回复。

4.1.1 关键文件与类型(iOS)
文件 主要类型 职责
Agent/Chat/AIChatViewModel.swift AIChatViewModel (@MainActor ObservableObject) 核心视图模型;持有 messages/agentHistory/isProcessing;send() 入口、runAgentLoop() 主循环、baseSystemPrompt 系统提示组装
Agent/Chat/AIChatViewModel+ToolDefinitions.swift AgentToolDefinition / AgentToolParam 工具 schema 定义,由 makeAgentTools() 返回
Agent/Chat/AIChatViewModel+ConcurrentTools.swift BatchImageBudget (actor)、executeSingleToolUse() 并发工具调度:TaskGroup 最多 10 个工具并发,按原始 tool_use 顺序拼接结果
Agent/Chat/AIChatViewModel+SSEStream.swift processStreamEvents() SSE 流式解析(后台线程),分发批量 UI 更新到 MainActor
Agent/Chat/AIChatViewModel+ISHCommand.swift executeCommand() shell 命令桥接:检测 bashism、按需装 bash、委托 ISHExecutionCoordinator
Agent/Chat/AIChatViewModel+FileTools.swift executeFileRead/Write/Edit() 文件工具:直接经 FileManager 操作 iSH fakefs
Agent/Chat/AIChatViewModel+MemoryTools.swift loadGlobalMemoryFragment() 等 记忆注入:GLOBAL.md + 最近 3 天日志注入系统提示
Agent/Chat/AIChatViewModel+Compaction.swift compactBefore()、effectiveAgentHistory() 上下文压缩:旧消息摘要化,推理时合成有效历史
Agent/Chat/AIChatViewModel+Offloading.swift offloadContextIfNeeded()、offloadToolOutput() 大输出卸载:超过阈值的工具结果写入 /var/minis/offloads/ 并替换为截断摘要
Agent/Chat/AIChatViewModel+Fallback.swift streamWithGroupFallback()、streamWithAutoRetry() 模型降级:自动重试 + 模型组内 fallback
Agent/Chat/ChatStore.swift ChatStore (actor)、ChatSession、RawMessage SQLite 持久化层(WAL 模式)
Agent/Chat/ContextPolicy.swift ContextPolicy 按模型上下文窗口分 4 层决定 offload/compact/exhausted 阈值
Agent/ISH/ISHExecutionCoordinator.swift ISHExecutionCoordinator (actor) iSH 命令协调器:fork /bin/sh、per-session in-flight PID、完全并发
Agent/ToolLoopDetector.swift ToolLoopDetector 工具循环检测,防止 Agent 陷入无进展的重复调用

Android 对应为 ui/chat/ChatViewModel.kt(约 9000 行),方法链一致:sendMessage() → runAgentLoop() → executeTool() → executeShellCommand()。

4.1.2 Agent 循环流程

图片 2

关键执行细节:

  • 孤儿工具修复:每轮先扫描 agentHistory,为无配对 tool_result 的 tool_use 注入占位结果,移除无配对的孤儿 tool_result——防止协议错位导致 Provider 拒绝请求。

  • 流式节流:文本 delta 按累积长度分层刷新 UI(<500 字 200ms … ≥128K 字 2s),新行快速路径;thinking delta 自适应节流。Markdown 解析在后台线程完成,仅赋值在 MainActor。

  • 空响应恢复:工具调用后若 LLM 返回空内容,注入 system-reminder 重试一次;可重试错误(5xx/network)自动重试;重试耗尽则在模型组内循环切换 entry 直到获得非空内容(fallback 时重新组装系统提示)。

  • 上下文管理:ContextPolicy 按模型窗口分 4 层(<32K / 32–64K / 64–128K / ≥128K),触发 offload(旧工具输出替换为文件路径)、compact(旧消息摘要化)、trim(保留最近 20 张图,旧图替换为文本占位);全请求图片字节总量上限 25MB。

  • 流式 TTS:从 textDelta 按句末标记(。!?.!?; + 换行)切句送 TTS,跳过代码块,数字内部分隔符不切割。

4.1.3 工具清单
工具 实现位置 说明
shell_execute +ISHCommand.swift / Android executeShellCommand 在沙箱中执行 shell,支持 timeout/delay
file_read +FileTools.swift / FileReadTool 直读 fakefs 文件,支持 offset/lines/direction
file_write +FileTools.swift / FileWriteTool 写文件,支持 append/create_dirs;路径在 /var/minis/ 下时附 minis_url
file_edit +FileTools.swift / FileEditTool 精确字符串替换,支持 replace_all
browser_use +ConcurrentTools.swift / BrowserUseTool 控制 WebKit/WebView(≤3 tab):navigate/screenshot/click/type/scroll/execute_js/fetch 等
memory_write +MemoryTools.swift / MemoryTools 写今日日志(YYYY-MM-DD.md)
memory_get +MemoryTools.swift / MemoryTools 关键词模糊搜索记忆
read_image +ConcurrentTools.swift / ReadImageTool 读图片给模型做视觉分析(仅 imageInput 模型注册)

系统提示还向 LLM 暴露大量 CLI 工具(经 shell_execute 调用):apple-*/android-* 设备集成、minis-open(预览资源)、minis-sessions-cli(管会话)、minis-model-use(调其他模型)、minis-browser-use(CLI 版浏览器)、minis-config(读写配置)。

4.1.4 会话与持久化
  • 存储引擎:iOS ChatStore(actor,原生 SQLite3 C API,WAL,Library/MinisChat/minis.db);Android Room(AppDatabase)。

  • 数据模型:ChatSession(会话元信息)、RawMessage(parts_json 序列化 AgentContentPart:text/toolUse/toolResult/imageData)、ToolSnapshot(工具执行快照)、MediaRef(媒体引用,存于 Library/MinisChat/minis/<sessionId>/)。

  • 持久化时机:用户消息即时落库;每轮工具执行完成后批量持久化 assistant + tool_result(单事务);首轮后异步生成会话标题。

  • 会话生命周期:loadSession() 重建 messages 与 agentHistory → 切换会话时由 fs_context 路径翻译切换可见目录,无 mount/unmount 数据搬运(见 4.2.3)。

  • per-session 状态:SessionLockStore(Face ID 锁)、SessionForkManager(会话分叉)、SkillStore/MCPStore(session 级 override)。


4.2 Linux 沙箱(iSH / PRoot + Alpine)

沙箱是产品的心脏:在 App 进程内跑一个完整的 Alpine Linux,让模型获得 apk/pip/node 等真实工具链。iOS 与 Android 用不同的用户态技术实现同一语义。

4.2.1 双平台沙箱对比
维度 iOS(iSH) Android(PRoot)
技术 用户态 Linux 内核模拟(Asbestos JIT 翻译 ARM64) PRoot(ptrace 系统调用拦截 + bind mount)
Guest Alpine Linux aarch64 Alpine Linux aarch64
持久内核 是(ISHKernel 持续运行于独立 pthread) 否(PRoot 进程级,每会话一个持久 /bin/sh)
文件系统 fakefs(SQLite 元数据 meta.db + data/ 目录) 直接 bind mount 到 host 目录
设备集成 apple-* offload(execve 拦截 → Obj-C handler) android-* offload(--native-offload 扩展 → Unix socket)
交叉编译 Meson 交叉编译 iOS arm64 NDK r28+ 交叉编译
4.2.2 iOS iSH 集成层

图片 3

  • ISHKernel(src/ios/iSH/ISHKernel.m,Obj-C 单例):包装 C 内核。启动序列:挂载 rootfs → init PID 1 → 创建设备节点 → 挂 procfs/devpts → 配 DNS → 注册 TTY 驱动 → 注册原生卸载 handler。对外暴露 executeCommand(PTY 交互)、executeCommandAndWait(跑到完成)、sendInput、setTerminalSize、bindMountPath、refreshDns。

  • RootfsManager(src/ios/iSH/RootfsManager.swift):Alpine rootfs 生命周期——解压到 ~/Documents/alpine-rootfs/、架构标签跟踪、重置(可选用户数据备份)、预建 /var/minis/ 子目录、在 fakefs meta.db 注册元数据使 bind mount 可见。

  • ISHShellExecutor(.m):进程级执行——逐行输出回调、退出码与耗时、超时与 SIGKILL、同步/异步模式、自定义环境变量注入。

  • ISHExecutionCoordinator(Agent/ISH/,actor):串行化、session 感知的命令调度器——per-session 完全并发、按 session 挂载/重挂 /var/minis/、正则检测 prompt($ 、# 、user@host:path$ 等)、超 10 分钟且有等待者时抢占、100KB 输出缓冲上限、echo 去除。

内核能力:100+ Linux 系统调用(mmap/brk/poll/epoll/pipes/eventfd/inotify)、AF_INET/AF_INET6/AF_LOCAL 全栈网络、TTY/PTY 设备、SIGSEGV/SIGBUS JIT 崩溃恢复。

4.2.3 挂载系统与 per-session 隔离(fs_context 路径翻译)

agent 与 shell 永远只看到 /var/minis/,URL 与路径中不含 session ID。但”同一时刻只有一个 session 可见”是早期 spec 的说法——实现实际支持跨会话并发,隔离靠 MinisFsRouter 的 fs_context 路径翻译,而非 per-session 换挂载:

Guest 路径 Host 路径 路由方式
/var/minis/attachments/ minis/<sessionId>/attachments/ fs_context 翻译(per-session)
/var/minis/offloads/ minis/<sessionId>/offloads/ fs_context 翻译(per-session)
/var/minis/workspace/ minis/<sessionId>/workspace/ fs_context 翻译(per-session)
/var/minis/browser/ minis/<sessionId>/browser/ fs_context 翻译(per-session)
/var/minis/memory/ minis/memory/ (全局) 静态 bind mount(首次启动注册 meta.db)
/var/minis/skills/ minis/skills/ (全局) 静态 bind mount

机制(MinisFsRouter.swift + ISHExecutionCoordinator.swift):

  1. MinisFsRouter.context(for: sid) 为每个 session 分配一个 u64 fs_context token;

  2. ISHShellExecutor.executeExecutable(..., fsContext:) 把 token 盖到 iSH 任务组(task->group->fs_context);

  3. iSH 内核翻译 fakefs 路径时回调 MinisFsRouter.translate(guestPath, fsContext),把 /var/minis/offloads/foo 重写到 ~/Library/.../minis/<sid>/offloads/foo。

会话切换 = 换 token,不搬数据:切换只设 mountedSessionId + 分配新 token,per-session 目录不重新挂载、不清空、不在 meta.db 注册(ISHExecutionCoordinator.swift:419-423 注释明确)。后果:

  • 崩溃天然安全——无数据搬运,各 session 数据本就在各自 host 目录,进程死于任意时刻,下次启动重新分配 token 即可恢复;

  • 跨会话并发——不同 session 的 shell 各自盖自己的 token,内核按 token 路由到各自目录,互不可见;

  • meta.db 注册只在首次启动对 4 个全局静态目录做一次(batchEnsureFakefsMetadata,单事务批量,ISHExecutionCoordinator.swift:784-851);per-session 目录不经 meta.db。

⚠️ 早期 spec(docs/specs/ios-sandbox-ish-summary.md)描述的 “Harvest→Clear→Mount→Register” 生命周期在当前实现中不存在;本文档此前版本沿用了该 spec 的说法,现按源码更正。

4.2.4 Android PRoot 集成层
  • PRootKernel(sandbox/PRootKernel.kt):boot() 解压 Alpine rootfs + PRoot 二进制、应用 default_mount/ overlay、注册全局 bind mount(/var/minis/{memory,skills,shared,mcp-servers})、启动 NativeOffloadServer、安装 handler stub 到 /usr/local/bin/。buildProotCommand() 构建命令行:proot -0 --link2symlink -r <rootfs> -b /dev -b /proc -b /sys ... --native-offload=<socket>:<handlers> /bin/sh -c "<cmd>"。-0 fake root;--link2symlink 把 hardlink 转 symlink(Android 文件系统拒绝跨目录硬链接);--native-offload 是 PRoot fork 扩展,拦截 execve 路由到 NativeOffloadServer。

  • ExecutionCoordinator(sandbox/):每会话一个 PersistentShell(长期 PRoot /bin/sh),ConcurrentHashMap 管理;每会话一个 Mutex,同 session 串行、跨 session 并行。execute() 自动 boot → 取/建 shell → 注入环境变量快照 → 执行。

  • PersistentShell:长期 PRoot /bin/sh 进程,stdin 发命令,用唯一 marker(__MINIS_DONE_<uuid>_EXIT_<code>__)检测命令边界,后台 reader 解析 exit code;环境变量全量快照注入(新增 export、删除 unset)模拟每命令独立进程隔离。

  • NativeOffloadServer(sandbox/NativeOffload.kt):PRoot 的 --native-offload 拦截 guest 的 execve("<handler>", argv, envp),经 abstract Unix socket(native-offload)发到 host 端 server。协议为小端二进制(magic NOFF/NORF),handler 输出写入 rootfs /tmp/.native-offload-<pid>-<seq>,回复 (exit_code, guest_tmpfile_path),PRoot 把 execve 重写为 /bin cat <tmpfile>。每个 handler 在 /usr/local/bin/ 装一个 #!/bin/sh\nexit 0 stub 让 PATH 搜索触发拦截。

  • PtyBridge(cpp/pty_bridge.c + PtyBridge.kt):JNI 包装 bionic forkpty(),为 PRoot 进程提供真实 TTY(支持 Ctrl-C/D/Z),供交互式终端使用。

4.2.5 安全与隔离
  • iSH 跑在独立 pthread,线程局部 current 任务指针做进程隔离;JIT 异常 handler 防 guest 崩溃拖垮 App。

  • fakefs 提供与 host 的文件系统隔离;bind mount 显式且限于 /var/minis/。

  • 环境变量存 Keychain(iOS SecureEnclave / Android EncryptedSharedPreferences)。

  • guest 进程不能访问任意 host 路径,仅 bind 挂载目录。

  • 100KB 输出缓冲 + 10 分钟命令超时(有等待者时抢占)防内存耗尽。


4.3 原生卸载系统(Native Offloads)

沙箱里的 guest 进程是纯 Linux,无法直接访问 iOS/Android 的 HealthKit、相册、日历等硬件/系统能力。原生卸载机制在 guest 调用 /usr/local/bin/apple-*(或 android-*)时拦截 execve,路由到原生框架。传输分两套:iOS 进程内钩子(无 IPC),Android 经 abstract Unix socket。

4.3.1 拦截机制对比

图片 4

  • iOS:iSH 内核在 execve 时检查 native_offload_add_handler 注册的命令路径,命中则进程内派发到 Obj-C handler(iSH 是嵌入 App 的模拟器,非独立进程),handler 调 iOS Framework,结果经 noff_emit_json 直接写 guest 的 stdout fd——无 pipe/socket IPC。需主线程的 Framework 用 noff_dispatch_main_sync 同步派发(阻塞 guest 线程直至完成)。

  • Android:PRoot 的 --native-offload=<socket>:<handlers> 扩展拦截 execve,经 abstract Unix socket(小端二进制协议 magic NOFF/NORF)发到 host 端 NativeOffloadServer;handler 输出写入 rootfs /tmp/.native-offload-<pid>-<seq>,PRoot 把 execve 重写为 /bin/cat <tmpfile>。每个 handler 在 /usr/local/bin/ 装 #!/bin/sh\nexit 0 stub 让 PATH 搜索触发拦截。

4.3.2 iOS 原生卸载处理器(22 个,src/ios/NativeOffloads/)
类别 Handler(guest 命令) iOS Framework 能力
媒体与音频 ffmpeg (FFmpegOffload) FFmpeg.framework 音视频编码/转码/网络流
apple-media (MediaOffload) AVFoundation 录音/播放
apple-speak (SpeakOffload) AVSpeechSynthesizer TTS
apple-speech (SpeechOffload) SFSpeechRecognizer STT
apple-player (PlayerOffload) AVFoundation 高级媒体播放
Apple 服务 apple-calendar EventKit 日历读写
apple-contacts Contacts 联系人
apple-maps MapKit 地图/导航/定位搜索
apple-photos Photos 相册访问
apple-health HealthKit 健康数据读写
apple-home HomeKit 智能家居
系统访问 apple-location CoreLocation GPS
apple-device UIKit 等 电量/型号/系统信息
apple-clipboard UIPasteboard 复制粘贴
apple-weather WeatherKit 天气
apple-notification UserNotifications 本地通知
apple-alarm EventKit(Reminders) 闹钟/提醒
智能 apple-vision Vision 图像识别/OCR
apple-nlp NaturalLanguage 语言检测/情感/分词
工具 apple-open UIApplication 打开 URL/App
其他 apple-bluetooth、apple-nfc、apple-config(minis-config)、apple-model-use、apple-browser-use 各框架 蓝牙/NFC/配置/模型调用/浏览器

共享工具 NativeOffloadUtils:参数解析(命名/位置/flag)、日期解析(ISO 8601/相对/--today)、JSON envelope 构造、异步派发主线程、guest stub 创建、host 路径解析(/var/minis/... → host)、stdin 读取。

权限管控:OffloadPermissionManager 对敏感命令(apple-health/apple-photos 等)做三级权限——bypass / askOnce / notAllowed,避免 Agent 未授权读取隐私数据。

4.3.3 Android 原生卸载与 Shizuku(sandbox.offload + offload/)

Android 等价物是经 NativeOffloadServer 注册的 20+ android-* CLI handler(在 MinisApp.onCreate 注册):

Handler 实现类 能力
android-alarm AlarmOffloadHandler 闹钟/计时器(AlarmClock API)
android-calendar / android-contacts / android-clipboard / android-photos 各 handler 日历/联系人/剪贴板/相册
android-device / android-location / android-weather 各 handler 设备信息/定位/天气
android-notification NotificationOffloadHandler 通知发送/读取(NotificationListenerService)
android-open / android-player / android-speak / android-speech 各 handler 打开/播放/TTS/STT
android-a11y-cli AccessibilityOffloadHandler 无障碍服务 UI 自动化
android-shizuku-cli ShizukuOffloadHandler 特权系统 API(见下)
minis-model-use / minis-config / minis-browser-use / minis-sessions-cli / minis-scheduled / minis-debug 各 handler 模型调用/配置/浏览器/会话/定时/调试

Shizuku 特权后端(offload/ShizukuManager.kt + ShizukuBackend.kt):Shizuku 是跑在 adb shell(uid=2000)或 root 的用户态服务,经 binder 暴露特权 API。ShizukuBackend 同时支持官方 Shizuku 与 AXManager/Axeron(同一协议,共享 binder slot)。状态机 NOT_INSTALLED → NOT_RUNNING → NEED_PERMISSION → READY;runProcess() 反射调用 Shizuku.newProcess() 执行特权命令(pm/am/cmd/settings/dumpsys/input/wm/appops),等同 adb shell。ShizukuOffloadHandler 暴露 12 个子命令组,经 OffloadGate 三态权限管控。此外还通过 MinisAccessibilityService(Android AccessibilityService)实现 UI 自动化。


4.4 LLM Provider 系统

位于 src/ios/Providers/(Android 对应 provider/ 包)。核心设计目标:Provider 可互换(统一协议)、模型自动发现与刷新、多模型编组与路由、凭证安全存储、OAuth 全流程。

4.4.1 抽象层

图片 5

  • LLMProvider(LLMProvider.swift):最底层统一接口,提供同步 sendMessage 与流式 streamMessage,返回 LLMStreamChunk(started/text/usage/finished)。

  • AgentProvider(AgentProvider.swift):在 LLMProvider 之上增加工具调用(接收 AgentToolDefinition,返回含 toolCallComplete 的 AgentStreamEvent)与推理(Thinking)(接收 ThinkingLevel,协议扩展自动 clamp 到模型上限 catalogMaxThinkingLevel)。每个具体 Provider 有一个 *AgentProvider 包装类,持有对应 *Provider 实例,负责把统一 AgentMessage 转为原生格式、把原生 SSE 映射回统一 AgentStreamEvent。

  • SSE 流式:各 Provider 用 URLSession(非第三方 SDK),流式请求独立 session(timeoutIntervalForRequest=600s),URLSession.bytes(for:) 按行读 SSE。Anthropic 经 SwiftAnthropic SDK 的 RequestBodyPatcher 注入 thinking 配置与工具结果图片;OpenAI 手动解析 data: {...} 行,区分 Chat Completions 与 Responses API;Gemini 调 streamGenerateContent?alt=sse 经 GeminiWireFormat 转换。

  • 错误分类(LLMError.swift):invalidAPIKey/networkError/providerError/transientError(5xx/529,同模型重试)/decodingError/rateLimited/cancelled。isRetryable 驱动同模型重试,fallbackReason 驱动组级 fallback。

4.4.2 各 Provider 实现
Provider 关键文件 特性
Anthropic Anthropic/AnthropicProvider.swift、AnthropicAgentProvider.swift、AnthropicModelsAPI.swift、OAuth/ClaudeOAuthManager.swift SwiftAnthropic SDK;API Key + Claude Code OAuth(PKCE,console.anthropic.com);Claude 4.6+ adaptive thinking;isOfficialAnthropicEndpoint 区分代理与官方端点
OpenAI OpenAI/OpenAIProvider.swift、OpenAIAgentProvider.swift、OpenAIModelsAPI.swift、OAuth/CodexOAuthManager.swift 双模式:API Key→Chat Completions,OAuth→Responses API(codex);Azure 模式;Mistral 兼容;ReasoningEcho 跨轮加密推理回放
Gemini Gemini/GeminiProvider.swift、GeminiAgentProvider.swift、GeminiModelsAPI.swift、GeminiWireFormat.swift、OAuth/GeminiOAuthManager.swift 直接 REST(无 SDK);API Key→generativelanguage.googleapis.com,OAuth→Cloud Code Assist;GeminiWireFormat 处理 content parts 与 thought signatures
xAI (Grok) xAI/OAuth/XAIOAuthManager.swift、xAIModelsAPI.swift OpenAI 兼容(api.x.ai/v1),复用 OpenAIProvider;OIDC discovery;内置 12 个 Grok 模型
Kimi Code Kimi/OAuth/KimiOAuthManager.swift、KimiDeviceFlow.swift、KimiOAuthRefreshCoordinator.swift RFC 8628 Device Authorization Grant(无浏览器重定向);OpenAI 兼容上游;复用 OpenAIProvider;compare-before-delete 单航次去重
OpenRouter OpenRouter/OpenRouterModelsAPI.swift、OpenRouterOAuthManager.swift OAuth 产出永久 API Key(存 Keychain);复用 OpenAIProvider;useOpenRouterCompat(用 max_tokens 而非 max_completion_tokens);发 HTTP-Referer/X-Title 归属头
Antigravity Antigravity/AntigravityProvider.swift、AntigravityAgentProvider.swift、AntigravityModelsAPI.swift Google Cloud Code 代理;envelope 包裹 Gemini 兼容请求;仅 OAuth
Voice Voice/VoiceProvider.swift、VoiceProvider+System.swift、VoiceProvider+Vendors.swift、VoiceProviderFactory.swift 独立 ASR/TTS 子系统;系统语音 + 第三方 Provider(DashScope/MiMo);模板化种子模型

关键复用模式:xAI、Kimi、OpenRouter 均复用 OpenAIProvider,仅靠自定义 Base URL + OAuth bearer/API key 区分,几乎零重复代码。

4.4.3 凭证与认证
  • ProviderKeychainHelper(enum,iOS):所有凭证统一入口,用 Security 框架直接操作 Keychain。API Key service=com.openminis.app.provider.{instanceId},account=api-key,启用 kSecAttrSynchronizable(iCloud Keychain 同步)+ kSecAttrAccessibleAfterFirstUnlock;UserDefaults 记 apiKeySavedAt 用于 iCloud LWW 冲突解决。OAuth token 以 JSON 编码的 Codable struct 存(account=oauth-token)。每次 save/delete bump authRevision + invalidate ProviderCredentialCache(L2 缓存,15s TTL,精确失效)。

  • OAuth 流程:所有 OAuth Manager 为 @MainActor 单例,遵循统一模式——Authorization Code + PKCE(SFSafariViewController + localhost callback server)或 Device Code Grant(Kimi)。各 Provider 用不同 localhost 端口(Claude 54545、Codex 1455、Gemini 8085、Antigravity 8086、xAI 56121、OpenRouter 3000)。

  • Refresh 竞态保护(T-oauth-refresh-race):Anthropic refresh token 每次 rotate,并发 refresh 会导致 invalid_grant。OAuthRefreshSingleFlight<T> 做 per-instance 单航次去重(并发 caller 复用同一 Task);OAuthRefreshCoordinator + OAuthRefreshErrorClassifier 结构化错误分类(读 HTTP status + OAuth error field,不做子串匹配),仅 fatal status 才删 credential。所有 Manager 的 validAccessToken() 在 token 过期前 5 分钟自动刷新。

4.4.4 模型管理
  • 模型发现:每个 Provider 有 *ModelsAPI enum 从 API 获取模型列表(如 AnthropicModelsAPI→{base}/v1/models?limit=512,OpenAIModelsAPI→{base}/v1/models 过滤 chat 模型)。models.dev 回退(ModelsDevAPI.swift):从 models.dev/api.json 取 Provider 注册表(48h TTL),API 失败或返回空时按 Base URL 匹配回退,并填充 modality/context window/max output tokens/supportsReasoning。

  • 刷新流程:手动 refreshModels(for:) + 每日 refreshAllModelsIfNeeded();三步回退 API→models.dev→内置列表;replaceEntries 保留用户 overrides/isHidden/自定义模型,仅替换 baseModel;返回列表大幅缩水(<50%)时跳过组引用清理。

  • ModelEntry(ModelEntry.swift)双层设计:baseModel(API 报告,刷新覆盖)+ overrides: ModelOverrides(用户编辑,跨刷新保留 displayName/maxOutputTokens/modality/contextWindow/supportsReasoning/maxThinkingLevel)。model 计算属性合并两者。id={providerInstanceId}/{baseModel.id} 跨设备稳定。

  • ModelGroup 与路由(ModelGroup.swift + ModelGroupRouter.swift):编组多模型 + 路由策略。fallback(按序尝试,失败前进;FallbackStrategy.limited 仅 Provider 级错误才 fallback,瞬态/网络先同模型重试;.always 任何错误都 fallback);loadBalance(sessionId.hashValue % available.count 确定性分配)。ModelGroupRouter.resolve() 解析初始模型,nextFallback() wrap-around 遍历可用成员,过滤 hidden/disabled/无凭证。

  • ProviderConfigStore(@MainActor 单例):配置中心。持久化 JSON(provider-config.json)+ SQLite DB(V3 权威源,per-record iCloud 同步)。ProviderConfig 含 instances/modelEntries/modelGroups/sessionBindings/agentLoop 配置/voice 配置/墓碑。iCloud 同步用 V3 per-record markDirty,墓碑防 resurrect,addedMembers/removedMembers 时间戳驱动 union merge。支持导入/导出(base64 编码 API key + OAuth token + 模型列表)。

4.4.5 Provider 类型枚举(ProviderTypes.swift)

ProviderType:openAI/anthropic/gemini/antigravity/openRouter/openAIResponses/xAI/kimiCode/unsupported(前向兼容哨兵)。ProviderCredential:apiKey/oauth。decoded(_:) 非抛式解码——未知 raw 值映射到 .unsupported 并保留 unknownProviderTypeRaw 忠实往返。builtInModels 为各 Provider 静态列表(如 7 个 Claude、9 个 GPT、13 个 Codex OAuth 专属模型)。


4.5 Skills 系统

Skill 是一个带 SKILL.md 的文件夹——指令、可选脚本、引用与资产——当请求匹配时由 Agent 按需加载。元数据留在上下文用于触发,body 与打包资源仅在实际使用时加载。Minis 不要求 Skill 专为自己编写:为 Claude/Codex/OpenClaw/Hermes Agent 写的 Skill 通常可直接运行。

4.5.1 存储(iOS)

src/ios/Agent/Session/SkillStore.swift — SkillStore(@MainActor ObservableObject 单例)+ Skill 结构体 + SkillImportSource(url/file/bundled/session)+ ParsedSkillMD。

双层存储:元数据在 SQLite(skills.db:skills 表 + session_skill_overrides 表),SKILL.md 文件在磁盘 skillId/SKILL.md 子目录。parse(skillMD:) 解析 YAML frontmatter(支持标准 fence + headless + block scalars)。

导入流程 importSkill():解析→slugify→写盘(仅内容变化时)→存 DB(ON CONFLICT 保留 use_count)→同步 rootfs→标记 iCloud 脏。内置 skill-creator(v2.1.0)。Bundle 文件(scripts/references/assets)经 collectRelativePaths 收集,一次性迁移标记脏。

4.5.2 三级渐进加载
层级 何时加载 体量
metadata(描述) 始终在 prompt ~100 字
SKILL.md body 触发后加载 <5k 字
bundled resources(脚本/引用/资产) 按需加载 按需

触发机制:description 字段是主要触发器——Agent(LLM)看到所有启用 Skill 的元数据后自行判断是否需要加载完整 body。SkillStore.shared.skillPromptFragment(for: sid) 注入已启用 Skill 元数据到系统提示。file_write/file_edit 写入 SKILL.md 后自动触发 skillRepository.reloadFromDisk()(Android)。

4.5.3 Android 对应

data/repository/SkillRepository.kt — 管理 skills.db 元数据 + SKILL.md 文件(minis-global/skills/<id>/SKILL.md)。支持 URL 导入、文件导入、bundled 技能、session 级覆盖。Skill prompt fragment 注入系统提示(Top-N + 描述截断)。


4.6 Memory 持久化

跨会话持久记忆。两类记忆文件存于 /var/minis/memory/(host:minis/memory/,全局跨 session 共享):

  • GLOBAL.md:只读,用户维护,作为长期背景上下文注入系统提示。

  • YYYY-MM-DD.md:每日日志,Agent 写入,记录当天发生的事。

4.6.1 iOS 实现(Agent/Chat/AIChatViewModel+MemoryTools.swift)
  • loadGlobalMemoryFragment()(静态):加载 GLOBAL.md 全文注入系统提示(memoryEnabled 时)。

  • loadRecentDailyMemoryFragment()(静态):加载最近 3 天有内容的每日日志(每天前 200 行)注入提示,标注为过去任务记忆。

  • executeMemoryWrite():在今日日志(YYYY-MM-DD.md)前 prepend 时间戳条目,注册 iSH 可见性,标记 iCloud 脏。

  • executeMemoryGet():按关键词置信度模糊搜索 GLOBAL.md + 所有日志文件(500 行总预算)。

  • 受 memoryEnabled 开关控制(纵深防御:关闭时注入与工具都禁用);memoryStatusFragment 注入 ENABLED/DISABLED 尾注。

4.6.2 Android 对应(data/repository/MemoryRepository.kt)

管理持久化目录 minis-global/memory/。memory_write 追加时间戳条目到当日日志;memory_get 模糊关键词搜索,支持 daily/all scope。输出限制:30KB 字节上限、500 行 dump 上限、60 行搜索上限。MemoryGlobalPrefs 控制全局开关。

4.6.3 SOUL.md 人格文件(Agent/Session/SoulStore.swift)

SoulStore(enum) + SoulMDParser + SoulMetadata + SoulFile。SOUL.md = YAML frontmatter(name/style/lang)+ Markdown body。body 注入系统提示 Layer 1(2000 token 上限),渲染为 “You are , a capable AI assistant running on an iOS device…”。存于同 memory 目录。

4.6.4 iCloud 同步
  • SyncedMemoryGlobal(MemoryGlobalV2):单例记录,GLOBAL.md 全文,LWW by updatedAt。

  • SyncedMemoryDaily(MemoryDailyV2):每天一条记录,JSON 数组,Set Union by timestamp 合并,仅推送最近 30 天。


4.7 浏览器自动化

让 Agent 能代替用户浏览、交互网页。

4.7.1 iOS(src/ios/Agent/BrowserUse/)

图片 6

  • BrowserTabPool.swift:BrowserTabPoolRegistry(进程级单例,全局 tab 上限 8,跨会话回收/驱逐/内存警告响应)+ BrowserTabPool(每会话,maxTabs=3,per-tab 串行化 acquireSerialSlot 60s 等待,15s post-action grace,300s dead-tab 超时重建,空闲 15min 驱逐,URL 持久化恢复)。

  • BrowserUseManager.swift:单 tab 引擎,持有 WKWebView(共享 process pool + minis:// scheme handler + window.print bridge)。执行 22 种动作:navigate、screenshot(full_page 支持整页截图 32768px 上限)、click、type、get_text、scroll、scroll_and_collect、get_page_info、execute_js、find_elements、hover、get_readable(JS Readability 提取)、set_user_agent、set_viewport、get_backbone、fetch、new_tab、close_tab、list_tabs、get_cookies(导出 env 文件)、set_cookies(WKHTTPCookieStore 写入)、wait_for_dom_stable。含 evaluateJavaScriptBounded(GCD timer 超时保护)、collectDomChangeSummary(MutationObserver DOM 变化追踪)、BrowserDownloadCenter(会话级下载注册表)。

  • BrowserUseActions.swift:BrowserAction(enum, 22 cases)、BrowserActionInput、BrowserActionResult(含 text/base64Image/imageFilePath/tabId)、UserAgentProfile(mobile_safari/desktop_safari/custom)。

  • BrowserUseJavaScript.swift:JS 注入脚本集合,提供各动作的 JavaScript 实现。

  • MinisURLSchemeHandler:实现 WKURLSchemeHandler,把 minis:// 协议请求映射到本地文件(经 AIChatViewModel.resolveMinisURL),支持 HTML/CSS/JS/图片/音视频/字体/wasm 等 MIME。所有浏览器 tab 共享单例。

4.7.2 Android(browser/)

BrowserUseManager.kt 基于 Android WebView。BrowserTabPool 多标签管理(≤3,Application 级共享 pool + 每 session 独立 pool)。BrowserAction 支持动作与 iOS 一致:navigate/screenshot/click/type/get_text/get_readable/scroll/scroll_and_collect/find_elements/get_page_info/get_backbone/fetch/new_tab/close_tab/list_tabs/execute_js/set_viewport/get_cookies/set_cookies/wait_for_dom_stable。BrowserUseOffloadHandler 让 shell 内 minis-browser-use CLI 路由到 NativeOffloadServer。


4.8 语音(Speech)

4.8.1 STT(语音转文字)
  • iOS SpeechRecognitionManager.swift:SpeechRecognitionManager 单例,iOS 系统 STT,用 SFSpeechRecognizer + AVAudioEngine。支持所有 iOS locale(按用户偏好排序)、权限请求、permissionsAlreadyGranted 无提示探测、inputModePreference 记忆 voice/text 模式。

  • VoiceActivityDetector.swift(Providers/Voice/):Silero VAD v5 + WebRTC APM(RealTimeCutVADLibrary)。事件:voiceStarted/voiceEnded(16kHz WAV)/voiceDidContinue(PCM 波形)。自适应增益(noise-floor AGC)、1.5s pre-roll back-fill、5min 回退缓冲、系统 ASR 60s/段限制。

  • VoiceCorrectionEngine.swift(actor 单例):LLM 语音转写纠错——分词→语音键归一化→并发多源检索(ConfusionDictionary + TypedVocabulary)→加权融合→LLM 纠错→结果验证。短 TTL memo cache(300s),所有失败路径 fallback 到原始转写。warmUp() 预加载 jieba 词典。

  • Android:speech/ 包,系统 + Provider,SpeechOffloadHandler 暴露 android-speech CLI。

4.8.2 TTS(文字转语音)
  • 流式 TTS:从 Agent 流式响应的 textDelta 中按句末标记(。!?.!?; + 换行)切句送 TTS,累积到动态窗口后送;首次 textDelta 清除前一轮 TTS 队列(per-session scoped);跳过代码块;数字内部分隔符(如 28.98 的 .)不切割。

  • VoiceOutputPlayer.swift(Providers/Voice/,单例):有序流式 TTS 队列——文本按序入队,音频预生成(pipeline 并发 synthesize)但严格按入队顺序播放。支持 fail-over 候选轮换、速度倍率(1.0/1.25/1.5/2.0)、浮动胶囊 UI 位置持久化。

  • VoiceProvider.swift:OpenAI 兼容的 STT(/v1/audio/transcriptions)和 TTS(/v1/audio/speech)基类,Vendor 子类覆盖 hook 适配不同 API,支持 chat-based ASR(多模态模型)。

  • shell 内 TTS/STT:iOS SpeakOffload(apple-speak,AVSpeechSynthesizer)+ SpeechOffload(apple-speech,SFSpeechRecognizer);Android SpeakOffloadHandler/SpeechOffloadHandler。


4.9 minis:// URL 方案

minis:// 是会话作用域的统一资源定位符,桥接三层——Agent、iSH shell、host app——同一 URL 在工具结果、Markdown 渲染、组件间引用中都可用。

4.9.1 设计原则
  1. 会话作用域:所有资源访问绑定当前 session。URL 不含 session ID——始终对活跃 session 的存储解析,无跨 session 可见性。

  2. Agent 优先:每个工具产生的持久资源必须以 minis:// URL 回传模型。

  3. 可渲染:聊天 UI 内联解析 minis://——图片/音频/视频原生渲染。

  4. 双向:shell 与 host app 写入的文件都可用同一 URL 寻址。

  5. 会话内持久:资源在 app 重启后存活,session 隔离在持久存储,session 加载时挂载到 /var/minis/。

4.9.2 URL 格式与命名空间
minis://<namespace>/<path>
命名空间 Linux 路径 用途 内联渲染
attachments /var/minis/attachments/<path> 图片/音频/视频等媒体 是(图片 .png/.jpg/.gif/.webp、音频 .mp3/.m4a/.wav、视频 .mp4/.mov/.m4v)
workspace /var/minis/workspace/<path> 脚本/数据/配置/项目文件 否(文本链接)
offloads /var/minis/offloads/<filename> 超 kMaxToolResultChars(15000 字符,硬编码 AIChatViewModel.swift:18)自动保存的截断输出 否
browser /var/minis/browser/<filename> browser_use 截图与可读文本抽取 是(图片)
4.9.3 路径解析与工具结果契约
  • minis:// → Linux 路径:minis://<namespace>/<path> → /var/minis/<namespace>/<path>。

  • Linux 路径 → host:/var/minis/<n>/<path> → <dataPath>/var/minis/<n>/<path>(dataPath=~/Documents/alpine-rootfs/data/)。resolveHostPath 拒绝含 .. 的路径防穿越。

  • 路径路由:per-session 目录(attachments/offloads/workspace/browser)由 MinisFsRouter 的 fs_context 路径翻译 hook 路由,不经 meta.db;仅 4 个全局静态目录(memory/skills/shared/mcp-servers)在首次启动经 batchEnsureFakefsMetadata 批量注册进 meta.db(单事务)。

  • 工具结果契约:file_write 写 /var/minis/ 下文件时附 minis_url:;shell_execute 执行后扫描 /var/minis/ 新增/修改文件附其 URL;browser_use 截图存 /var/minis/browser/ 并附 URL;用户附件经 saveAttachment() 返回 minis://attachments/<filename> 注入用户消息上下文。

4.9.4 渲染(iOS)
  • MinisImageProvider(AIChatView.swift)处理 Markdown 图片语法 ![](minis://...),按扩展名分派:图片→UIImage(点击全屏,6 次重试)、音频→MinisAudioPlayerView(播放/暂停/进度)、视频→MinisVideoPlayerView(缩略图+全屏播放器)。

  • MinisURLSchemeHandler(BrowserUseManager.swift):实现 WKURLSchemeHandler,让浏览器 tab 内的 minis:// 请求映射到本地文件。

  • MinisURLPathDecoding.swift:处理双重百分号编码的 minis:// 路径解码,以磁盘存在性为判别依据。

4.9.5 安全

会话隔离(fs_context 路径翻译在文件系统层强制——每进程只路由到自己 session 的 host 目录,无 mount/unmount 搬运)、路径穿越拒绝(resolveHostPath 拒绝 ..)、URL 中永不暴露 session ID。注意:resolveMinisURL(+RequestBudget.swift:293-337)未对命名空间做白名单校验——未知 host 被当作目录名尝试解析,最终以 file-not-found 软拒绝;不能逃逸 session 沙箱(host 始终是 minisPersistentBase/<sid>/<host>/ 下的单段路径),但缺纵深防御,建议补白名单。


5. 平台实现对比

OpenMinis 双平台共享同一套 Agent 工具协议、系统提示词与 bashism 规则(assets/bashism/bashism_rules.json 单一真相源),但沙箱实现、UI 框架、持久化、特权后端各异。

维度 iOS Android
语言/UI Swift / SwiftUI(iOS 26.2, Swift 6.0) Kotlin / Jetpack Compose(minSdk 26, compileSdk 36)
沙箱 iSH(ARM64 用户态内核模拟)+ fakefs(SQLite 元数据) PRoot(ptrace 拦截 + bind mount)
rootfs Alpine aarch64,fakefs 格式 Alpine aarch64 minirootfs tar.gz
持久内核 是(ISHKernel 独立 pthread 常驻) 否(PRoot 进程级,每会话持久 shell)
命令执行 ISHExecutionCoordinator (actor,per-session 并发) ExecutionCoordinator + PersistentShell(per-session Mutex 串行)
原生卸载 iSH 内核 execve 拦截 → Obj-C handler(22 个 apple-*) PRoot --native-offload 扩展 → Unix socket → NativeOffloadServer(20+ android-*)
特权后端 (iOS 沙箱即够) Shizuku(adb shell/root binder)+ AccessibilityService
TTY iSH 内置 TTY 驱动 PtyBridge JNI(bionic forkpty)
持久化 SQLite3 C API(WAL,minis.db) Room(AppDatabase)
同步 iCloud(CloudKit CKSyncEngine,V2 SyncCore) (暂无跨设备同步)
凭证 Keychain(iCloud Keychain 同步) EncryptedSharedPreferences
浏览器 WKWebView(共享 process pool) Android WebView
后台保活 BackgroundKeepAliveManager (位置/音频保活腿)+ CacheKeepAliveManager(prompt cache 预热) AgentForegroundService (mediaPlayback 类型绕过 6h 上限)+ WAKE_LOCK
动态展示 Live Activity / Dynamic Island(AgentLiveActivityManager) Dynamic Island(Android 16 Live Updates)+ Tool Overlay 浮动胶囊
崩溃 CrashReporter NativeCrashHandler + CrashFrequencyDetector(安全模式)
分词 TextSegmenter (CppJieba + NLTokenizer)+ BPETokenizer(cl100k_base) CppJieba JNI(jieba_jni)
架构目标 arm64(device) arm64-v8a only
扩展 ShareExtension / AgentWidget / FileProvider Share activity / Widget /(无独立 FileProvider)

关键差异解读:

  • iOS iSH 是”在 App 里跑一个 Linux 内核”,常驻、并发更强,但需 JIT 翻译;Android PRoot 是”用 ptrace 把 syscall 转发到 host”,无需模拟指令但进程级、需 --link2symlink 规避文件系统限制。

  • Android 多了 Shizuku + AccessibilityService 两条特权路径——因为 PRoot 用户态无法直接访问需 system 权限的 API,而 iOS 沙箱本身在 App 进程内可直接调框架。

  • Android AgentForegroundService 用 mediaPlayback 类型(而非 dataSync)绕过 Android 14+ 的 6h/24h 累计上限,sideload 场景下 AOSP 不强制 MediaStyle 规则。


6. 设备集成与扩展

6.1 入口扩展

扩展 平台 文件 作用
Share Sheet iOS ShareExtension/ShareViewController.swift、ShareViewModel.swift 从任意 App 分享页面/消息/文件给 Minis,自动创建会话或日历事件
Widget / Live Activity iOS AgentWidget/AgentLiveActivityWidget.swift、AgentWidgetBundle.swift 桌面小组件 + Lock Screen/Dynamic Island 实时显示 Agent 进度
File Provider iOS FileProvider/FileProviderExtension.swift、FileProviderEnumerator.swift、FileProviderItem.swift 把 workspace 作为可挂载的文件 provider,其他 App 可直接读写
PWA / Add to Home iOS WebApp/WebAppWebViewController.swift、WebAppPathResolver.swift、WebAppIconCache.swift “添加到主屏幕”的 PWA 元数据抓取与管理
Shortcuts / AppIntents iOS Agent/Intents/MinisShortcutsProvider.swift、SendPromptIntent.swift 等 SendPromptIntent /RetryRunIntent/GetSessionStatusIntent/ListSessionsIntent/FollowUpSessionIntent,支持后台执行与等结果
Deep Link 双平台 iOS Shared/DeepLinkCoordinator.swift、DeepLinkRouter.swift;Android deeplink/ minis:// scheme 路由到会话/工作区
Share activity Android share/ 接收其他 App 的分享

6.2 设备集成范围

通过原生卸载暴露给 Agent 的系统能力(双平台合并):

  • 健康与运动:Apple Health / HealthKit(读写健康数据)、Health(Android)

  • 日程与提醒:Calendar、Alarms、Reminders

  • 通讯录:Contacts

  • 智能家居:HomeKit(iOS)

  • 媒体:Photos 相册、Media 录音、Player 播放、FFmpeg 转码

  • 感知:Location GPS、Weather 天气、Bluetooth 蓝牙、NFC

  • 视觉与语言:Vision 图像识别/OCR、NLP 自然语言

  • 系统:Device 设备信息、Clipboard 剪贴板、Notification 通知、Open 打开 URL/App

  • 语音:Speak TTS、Speech STT、VAD

6.3 MCP 集成

支持 Model Context Protocol——Agent 可调用外部 MCP 服务器扩展能力。

  • iOS Agent/Session/MCPStore.swift(MCPStore + MCPServerConfig):CRUD、per-session override、Top-20 元数据注入系统提示。

  • Android data/repository/MCPRepository.kt:配置文件 minis-global/mcp-servers/servers.json(Claude Desktop 兼容格式),PRoot 内 minis-mcp-cli 读写同一文件;支持 HTTP/SSE 与 STDIO 两种传输。


7. 构建系统

Minis 在 App 内内置 Linux 沙箱,原生依赖(iSH/PRoot/FFmpeg/LAME)与 Alpine rootfs 由源码构建而非提交二进制。首次构建约 30–60 分钟,之后缓存。

7.1 依赖与产物

图片 7

脚本 平台 产物
deps/build_lame.sh iOS LAME 3.100 静态库 libmp3lame.a(FFmpeg MP3 编码依赖)
deps/build_ffmpeg.sh iOS FFmpeg 6.1.2 per-library .framework + umbrella(LGPL 配置,禁加 --enable-gpl/nonfree)
deps/build_ish.sh iOS libish /libish_emu/libfakefs + headers + VDSO(Meson 交叉编译 iOS arm64)
deps/prepare_alpine_rootfs.sh iOS Alpine aarch64 minirootfs → iSH fakefs 格式
deps/build_proot.sh Android 静态 libtalloc + proot → assets/proot-aarch64 + jniLibs/arm64-v8a/*.so
scripts/prepare_android_sandbox.sh Android Alpine 3.21.3 aarch64 minirootfs → assets/alpine-minirootfs.tar.gz

子模块:deps/ish(OpenMinis/ish-arm64)、deps/proot(OpenMinis/proot),须 git clone --recurse-submodules。

7.2 构建命令

# iOS(顺序敏感:FFmpeg 链接 LAME)
./deps/build_lame.sh && ./deps/build_ffmpeg.sh
./deps/build_ish.sh && ./deps/prepare_alpine_rootfs.sh
open src/ios/Minis.xcodeproj          # 或 xcodebuild ... CODE_SIGNING_ALLOWED=NO build

# Android(需 NDK r28+)
./deps/build_proot.sh && ./scripts/prepare_android_sandbox.sh
cd src/android && ./gradlew :app:assembleDebug

7.3 构建时定制

复制模板(值留空也能编译运行,仅对应功能在运行时大声失败):

  • iOS src/ios/Configs/ProviderCustomization.xcconfig(含 ANTHROPIC_OAUTH_IDENTIFIER_PROMPT——Claude OAuth 登录所需,API Key 不需要)

  • Android src/android/app/provider-customization.properties

7.4 关键配置

项 iOS Android
目标 iOS 26.2 / Swift 6.0 compileSdk 36 / targetSdk 35 / minSdk 26 / JDK 17
架构 arm64(device) arm64-v8a only
原生构建 Meson + Ninja NDK r28+ + CMake 3.22.1
原生库 libish/libish_emu/libfakefs pty_bridge (C)、minis_crash_handler(C)、jieba_jni(C)
Targets Minis、MinisShare、AgentWidgetExtension、MinisFileProvider、MinisTests/UITests :app(release 用 debug 签名,免 keystore)

8. 关键交互流程

本节给出跨越多个子系统的端到端流程图,作为前文细节的串联。

8.1 端到端:用户照片 → 营养分析 → 写入健康

sequenceDiagram     actor U as 用户     participant VM as AIChatViewModel     participant Prov as Anthropic Provider     participant Shell as ISHExecutionCoordinator     participant Off as Native Offload (apple-vision/health)     participant Store as ChatStore + /var/minis     U->>VM: [图片] 识别这道菜并记录营养     VM->>Store: saveAttachment → minis://attachments/meal.jpg     VM->>Prov: streamAgentMessage(history + 图片, tools)     Prov-->>VM: tool_use: shell_execute("apple-vision ...meal.jpg")     VM->>Shell: executeCommand     Shell->>Off: execve 拦截 apple-vision     Off->>Off: Vision 识别菜品 + 估算卡路里     Off-->>Shell: JSON 结果     Shell-->>VM: 工具结果     VM->>Prov: 回传 tool_result,继续     Prov-->>VM: tool_use: shell_execute("apple-health --add ...")     VM->>Shell: executeCommand     Shell->>Off: execve 拦截 apple-health     Off->>Off: HealthKit 写入     Off-->>Shell: 成功     Shell-->>VM: 工具结果     VM->>Prov: 回传 tool_result     Prov-->>VM: 文本回复(已记录)     VM-->>U: 已写入 Apple Health

8.2 会话切换:fs_context 路径翻译

图片 8

不搬数据:切换只设 mountedSessionId + 分配新 token——per-session 目录不重新挂载、不清空、不在 meta.db 注册(ISHExecutionCoordinator.swift:419-423)。

隔离与崩溃安全:各 session 数据本就在各自 host 目录(minis/<sid>/...),无搬运→无崩溃窗口;进程死于任意时刻,下次启动重新分配 token 即可恢复。跨会话并发:不同 session 的 shell 各自盖自己 token,内核按 token 路由,互不可见。

8.3 模型组 fallback 路由

图片 9

8.4 iCloud 同步流(V2)

图片 10

同步类型(SyncedTypesBootstrap.registerAll()):SessionV2、MessageV2、CompactMarkerV2、SessionFileV2、SkillV2(SKILL.md + bundle ZIP)、ProviderConfigV2/InstanceV3/EntryV3/GroupV3(含加密密钥)、EnvVarV2、MCPServersV2、SyncDeviceV2、SoulV2、MemoryGlobalV2、MemoryDailyV2(Set Union 合并)。V2 门控于 cloudSync.v2.enabled(默认 OFF,从 v1 toggle 继承),支持热启用。


9. 调试与可观测性

9.1 JSON-RPC 调试服务器(DEBUG 构建)

内置 JSON-RPC 2.0 server,监听 http://localhost:8321,仅接受 POST application/json。涵盖视图检查、文件系统、LLM 请求、浏览器、日志、Provider/模型管理、聊天自动化。

方法组 方法 用途
视图检查 debug.viewTree /search/inspect/highlight UIKit 视图树导出/搜索/检视/高亮
Agent 调试 debug.agentTrace 获取 Agent 请求 trace
文件系统 debug.ls /readFile/appInfo 列目录/读文件/路径与磁盘用量
截图 debug.screenshot 整屏 PNG
LLM 请求 debug.llmRequests 近期 LLM 请求/响应(URLProtocol 层捕获,排除 Authorization 头)
浏览器调试 debug.browser.listTabs /pageInfo/executeJS/getReadable/getText/screenshot 远程检查与操作浏览器 tab
日志 debug.logs.list /read/setEnabled 日志文件列表/读取/开关
Provider 管理 provider.types /instances.{list,create,update,delete,test} Provider 实例 CRUD + 凭证测试(凭证 write-only)
模型管理 provider.models.{list,add,update,delete,refresh,setAgentLoop} 模型条目 CRUD + 刷新 + Agent loop 可见性
模型组 provider.groups.{list,create,update,delete,setDefault,setAgentLoop} 模型组 CRUD + 默认组 + 路由策略
聊天自动化 chat.sessions.{list,get,usage} /messages.list/models.list/prompt/retry/session.{status,cancel,delete} 远程驱动聊天(与 Shortcuts intents 同底层)

错误码:-32700 parse / -32600 invalid request / -32601 method not found / -32602 invalid params / -32000 internal。

9.2 日志与崩溃

  • LoggingManager / AppLogger:结构化日志,按 category 分类,日志文件按日轮转(minis-YYYY-MM-dd.log,存 Library/Logs/),运行时可开关。

  • iOS Diagnostics/CrashReporter.swift + CrashSignalHandler:崩溃报告与信号处理。

  • Android crash/:NativeCrashHandler(NDK 信号处理 SIGSEGV/SIGABRT)+ CrashFileReporter + CrashFrequencyDetector(频繁崩溃时进安全模式,跳过全部子系统初始化,仅弹崩溃分享对话框)+ LaunchCycleBeacon(检测 LMK/MIUI 强杀)+ HangDetector(主线程 1s 心跳,3s 无响应 dump 栈)。ACRA 本地崩溃报告(无网络发送)。

  • scripts/symbolicate_hang.py:符号化 native 崩溃栈。


10. 已知限制与优化建议

下表按影响排序,均经源码核验(括注 file:line)。结构性代价(双沙箱)与设计亮点单列于后。

优先级 问题 证据 风险/代价 建议
🔴 高 offloads/workspace 文件永不清理,会话删除后仍残留 ChatStore.swift:2491-2499 deleteSessionMedia 只删 ["browser","attachments","images"] 存储单调增长;删会话≠清数据 加入删除清单;加会话级配额或 TTL
🔴 高 GLOBAL.md 全量注入 system prompt,无大小上限 AIChatViewModel+MemoryTools.swift:10-16 整文件直拼 token 成本 + 上下文污染,随 GLOBAL 增长线性放大 注入前按 token/行截断或分段摘要
🟡 中 调度器(≤10 并发)与 BrowserTabPool(3 tab)无背压协调 +ConcurrentTools.swift:25 (cap=10) + BrowserTabPool.swift:193(maxTabs=3)/:258(serialWaitTimeout=60s) 10 个并发 browser_use 仅 3 个拿到 tab,其余等 60s 后报错;不 deadlock 但 UX 报错 调度器感知资源池,超额 browser 任务入队而非超时报错
🟡 中 meta.db 无 WAL + 每次注册新建连接 + 内核/Swift 双层并发 RootfsManager.swift:299 (per-call sqlite3_open_v2);无 PRAGMA journal_mode 默认 rollback journal→写锁阻塞所有读;批量注册期间 iSH FS 操作卡顿 开 WAL;复用持久连接;批量注册分片释放锁
🟡 中 ModelGroup fallback 无真正熔断(无失败计数/冷却/健康探针) AIChatViewModel+Fallback.swift:172-222 fallbackable 错误立即切下一个 sticky binding(:148-155)缓解跨轮但无持久健康状态;手动重选会立即重试已知失败 provider 加失败计数 + 冷却窗口
🟢 低 minis:// 解析无命名空间白名单 resolveMinisURL +RequestBudget.swift:293-337 把 host 直接当目录名 不能逃逸沙箱(单段路径)但无显式拒绝 加白名单校验,纵深防御
🟢 低 Android Offload 每命令新建 socket + tmpfile+cat 回写 NativeOffload.kt:136-217 每命令一次连接 + 文件系统开销 持久连接 + 直写 stdout
🟢 低 kMaxToolResultChars=15000 硬编码 AIChatViewModel.swift:18 不可运行时调 进 ConfigRegistry

10.1 结构性代价(非缺陷)

双沙箱:iOS iSH(用户态 ARM64 内核模拟 + fakefs)/ Android PRoot(ptrace 拦截 + bind mount)——两套完全不同的虚拟化栈,语义不同,连原生卸载传输都分两套(进程内钩子 vs socket+tmpfile)。平台强制:iOS 禁 ptrace 用不了 PRoot,Android 上 iSH 全模拟太重。无法消除,是本项目最大的长期维护负担,新增功能常需双平台各写一遍。

10.2 设计亮点(实测后确认优于预期)

  • fs_context 路径翻译做会话隔离——零数据搬运、崩溃天然安全、支持跨会话并发,比早期 spec 的”换挂载”模型更优雅(MinisFsRouter.swift:83-110)。

  • LLM Provider 用行为 flag 注入而非类型 switch——xAI/Kimi/OpenRouter/OpenAIResponses 复用同一 OpenAIProvider 类,12+ 行为 flag 在构造时注入,零 if provider=="kimi" 型判断(LLMProviderFactory.swift:20-39、OpenAIProvider.swift)。

  • iCloud 同步冲突显式策略——ConflictPolicy 枚举 + 按类型 LWW(updatedAt/serverEtag),冲突时合并 server record + 本地重入队,不静默丢(Syncable.swift:25-41、ICloudSharedZoneTransport.swift:1562-1581)。

  • iOS 原生卸载进程内钩子——handler 直接函数调用,近零 IPC 开销(ISHKernel.m:414-445)。

  • Memory 日注入有界——最近 3 篇、每篇前 200 行、30 天回溯(AIChatViewModel+MemoryTools.swift:20-53)。


附录:关键设计取舍小结

取舍 选择 理由
沙箱技术 iOS iSH / Android PRoot(用户态) 无需越狱/root,可上架/侧载;App 进程内即可跑完整 Linux
模型接入 统一协议 + 工厂,OpenAI 兼容端点复用 Provider 可互换,新增 OpenAI 兼容厂商几乎零代码
资源寻址 会话作用域 minis://(无 session ID) 简洁 + 强制隔离——Agent 无跨 session 概念,无法越权
设备集成 原生卸载(execve 拦截) guest 命令行即可调原生框架,无需为每个能力写专用工具
持久化 SQLite(WAL/Room)+ 文件 + Keychain 会话/消息结构化、媒体走文件、凭证进安全存储
同步 CloudKit V2 声明式 + 3 zone 含密钥的 secret zone 与普通数据隔离;声明式字段降低同步类型维护成本
后台 iOS 位置/音频保活腿;Android mediaPlayback FGS 绕过移动 OS 后台限制,保证长任务不被杀
构建 原生依赖源码构建 合规(GPL/LGPL 配置)+ 体积可控 + 可审计

本文档基于仓库源码(iOS 363 Swift + Android 454 Kotlin 文件)、docs/specs/ 规范与 BUILDING.md 整理,并经第二轮源码实证核验(沙箱会话切换 / Native Offload 传输 / Provider 复用 / 同步冲突 / 资源回收等接缝)。文中文件路径相对仓库根目录。凡与早期 spec 不一致处以源码为准(见 §4.2.3、§8.2、§10)。

本文首发于微信公众号。原文:查看原文
微信搜一搜 AI拆解猿