产品哲学 · 04

本地优先原则

UIChat Mira 的数据位置、运行边界、外部依赖与可退出性要求。

原则定义#

Local-first 表示：Mira 的基础工作状态优先由用户自己的设备持有，外部服务作为可配置依赖接入，而不是成为产品唯一运行真相。

本地优先不等于完全离线，也不等于所有模型和工具必须在本机运行。

适用范围#

该原则适用于：

  • 对话、线程与消息；
  • Provider 和模型配置；
  • 知识库、索引与评测记录；
  • 角色与提示词原型；
  • AgentRun、Evidence、审批与 Trace；
  • MicroApp 配置、任务状态和本地产物；
  • 桌面运行时和用户工作目录。

数据边界#

数据类型 默认位置 外部传输条件
应用配置 本地 SQLite 用户显式同步或远端配置接口
对话与任务状态 本地数据库 调用远端模型时发送必要上下文
知识文档与索引 本地文件 / 数据库 用户选择远端解析、Embedding 或模型调用时
Tool / Agent Trace 本地运行记录 明确启用远端观测或集成时
Artifact 本地受管目录 用户主动上传、分享或调用外部服务时
Secret 后端凭据边界 仅注入目标连接，不进入模型正文和普通日志

外部调用必须遵守最小必要原则。不能因为配置了一个 Provider，就默认上传全部对话、知识库或工作区文件。

运行边界#

Mira 当前基础路径为：

Desktop Renderer
→ Desktop Shell
→ Local Fastify Backend
→ SQLite / Local Runtime / Local Artifact

以下能力可以位于外部：

  • 云端模型 Provider；
  • External MCP Server；
  • 企业微信等平台；
  • 用户已登录的外部专家网页；
  • ComfyUI、GPT-SoVITS 等本机独立服务；
  • 其他显式配置的 API。

外部能力不可自动成为本地状态的唯一持有者。

可退出性要求#

本地优先至少需要满足：

  1. 用户可以确认数据存储位置；
  2. 外部连接可以单独停用或移除；
  3. 配置和失败状态可见；
  4. Provider 变化不会使基础工作区不可启动；
  5. 本地数据可以备份和迁移；
  6. 远端调用失败时，系统返回明确错误或降级状态；
  7. 用户可以重新取得执行控制权。

外部连接要求#

接入外部能力时必须区分：

已配置
!= 已连接
!= 当前可用
!= 已获得 Agent Access
!= 已批准本次调用

MCP、GitHub、邮箱、企业集成和外部专家均应分别维护连接状态、可用性和调用权限。

工程影响#

Local-first 带来以下工程责任：

  • 桌面打包与升级；
  • SQLite Schema 与迁移；
  • 跨进程通信边界；
  • 本地 Runtime 发现和安装；
  • Artifact 生命周期；
  • 离线、超时和远端服务不可用处理；
  • 多平台路径差异；
  • 数据备份与恢复。

这些成本不能通过把所有状态迁移到云端来静默规避。

非目标#

本地优先不承诺：

  • 所有模型都能离线运行；
  • 所有外部能力都有本地替代；
  • 当前已经完成跨设备同步；
  • 本地运行天然等于强隔离 Sandbox；
  • 用户不需要理解任何外部传输。

验证问题#

评审涉及数据或连接的功能时，应回答：

  • 状态由谁持有？
  • 哪些数据会离开设备？
  • 外部服务不可用时发生什么？
  • Secret 是否进入模型、Evidence 或日志？
  • 用户如何停用、迁移或删除？
  • 连接是否被错误地等同于授权？

相关文档#