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

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 循环流程

关键执行细节:
-
孤儿工具修复:每轮先扫描
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 集成层

-
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/子目录、在 fakefsmeta.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):
-
MinisFsRouter.context(for: sid)为每个 session 分配一个 u64fs_contexttoken; -
ISHShellExecutor.executeExecutable(..., fsContext:)把 token 盖到 iSH 任务组(task->group->fs_context); -
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>"。-0fake 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。协议为小端二进制(magicNOFF/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 0stub 让 PATH 搜索触发拦截。 -
PtyBridge(cpp/pty_bridge.c+PtyBridge.kt):JNI 包装 bionicforkpty(),为 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 拦截机制对比

-
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(小端二进制协议 magicNOFF/NORF)发到 host 端NativeOffloadServer;handler 输出写入 rootfs/tmp/.native-offload-<pid>-<seq>,PRoot 把 execve 重写为/bin/cat <tmpfile>。每个 handler 在/usr/local/bin/装#!/bin/sh\nexit 0stub 让 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 抽象层

-
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 经SwiftAnthropicSDK 的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 bumpauthRevision+ invalidateProviderCredentialCache(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 + OAutherrorfield,不做子串匹配),仅 fatal status 才删 credential。所有 Manager 的validAccessToken()在 token 过期前 5 分钟自动刷新。
4.4.4 模型管理
-
模型发现:每个 Provider 有
*ModelsAPIenum 从 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/)

-
BrowserTabPool.swift:BrowserTabPoolRegistry(进程级单例,全局 tab 上限 8,跨会话回收/驱逐/内存警告响应)+BrowserTabPool(每会话,maxTabs=3,per-tab 串行化acquireSerialSlot60s 等待,15s post-action grace,300s dead-tab 超时重建,空闲 15min 驱逐,URL 持久化恢复)。 -
BrowserUseManager.swift:单 tab 引擎,持有 WKWebView(共享 process pool +minis://scheme handler +window.printbridge)。执行 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-speechCLI。
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);AndroidSpeakOffloadHandler/SpeechOffloadHandler。
4.9 minis:// URL 方案
minis:// 是会话作用域的统一资源定位符,桥接三层——Agent、iSH shell、host app——同一 URL 在工具结果、Markdown 渲染、组件间引用中都可用。
4.9.1 设计原则
-
会话作用域:所有资源访问绑定当前 session。URL 不含 session ID——始终对活跃 session 的存储解析,无跨 session 可见性。
-
Agent 优先:每个工具产生的持久资源必须以
minis://URL 回传模型。 -
可渲染:聊天 UI 内联解析
minis://——图片/音频/视频原生渲染。 -
双向:shell 与 host app 写入的文件都可用同一 URL 寻址。
-
会话内持久:资源在 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 图片语法,按扩展名分派:图片→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 依赖与产物

| 脚本 | 平台 | 产物 |
|---|---|---|
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 路径翻译

不搬数据:切换只设 mountedSessionId + 分配新 token——per-session 目录不重新挂载、不清空、不在 meta.db 注册(ISHExecutionCoordinator.swift:419-423)。
隔离与崩溃安全:各 session 数据本就在各自 host 目录(minis/<sid>/...),无搬运→无崩溃窗口;进程死于任意时刻,下次启动重新分配 token 即可恢复。跨会话并发:不同 session 的 shell 各自盖自己 token,内核按 token 路由,互不可见。
8.3 模型组 fallback 路由

8.4 iCloud 同步流(V2)

同步类型(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)。

