本页内容

架构概览

Mica 将模型、工具、会话和界面分层。终端、自动化与桌面围绕共享能力构建,让不同入口拥有一致的模型连接与工具行为。

需要追踪模块之间的调用关系时,打开 交互式架构图,查看 CLI 与 Desktop 的运行时地图,搜索节点并沿依赖路径定位。

从输入到完成任务

  1. 入口接收任务。终端界面、exec 或 app-server 收到输入,确定工作目录、会话、模型与角色。
  2. 构建模型上下文。加入项目指令、Skills 索引、工具定义和会话历史,通过所选 provider 的协议发送请求。
  3. 迭代调用工具。模型可以读写文件、执行命令或调用 MCP,工具结果进入下一次模型请求。独立的只读调用可并行处理,写入与执行操作保留顺序边界。
  4. 持续反馈和保存。界面或协议接收文本、工具状态与用量;保存的会话可在后续任务中恢复。

交互式终端与 headless 各有面向自身入口的编排层,共享模型适配、工具、会话与运行状态能力。exec 与 app-server 共用 headless 执行层;桌面通过 app-server 驱动模型任务。

模型协议与工具

provider 显式选择 Chat Completions 或 Responses 适配器,由适配器负责请求参数、消息结构、工具调用和用量转换。其他模块不需要直接拼接供应商请求。

内置工具和 MCP 远端工具进入同一个注册入口。MCP 模块管理连接、工具发现与关闭;Skills 提供按需读取的任务知识。两者对接方式见 扩展指南。

上下文、缓存与恢复

保持稳定的上下文前缀

普通任务以追加历史为主,Skills 在系统提示词中只保留索引,完整指南按需读取。这有利于复用供应商的 prompt cache;实际缓存命中和计费由模型服务决定。

明确区分清理与摘要

本地压缩替换冗长工具结果与媒体,保留对话轮次;模型摘要压缩则重新组织历史。压缩不会清零用量统计。选择哪一种,取决于是否仍需依赖完整的历史细节。

保存任务状态,控制并发写入

会话保存模型上下文、展示记录和用量,并在执行过程中保存可恢复状态。同一会话的跨进程执行受到写入锁约束,避免多个客户端同时覆盖历史;这与不同会话并行运行互不冲突。

自动重试只在可安全重放的阶段进行,已经调用具有副作用的工具后不会盲目重跑整轮。恢复、中止与回退都围绕已保存的会话边界处理。

桌面与 Web 的三层结构

层职责
React 页面展示对话、编辑器、Git 和终端,通过 HTTP 调用能力,通过 SSE 接收事件。
Node 运行时与 host托管页面,管理工作区、会话进程、文件、Git 与共享界面状态。
Electron 外壳窗口管理与桌面行为,并提供受控浏览器、终端控制两项主进程能力。

浏览器与 Electron 页面连接同一个运行时。独立 Web 部署仍有对话、文件、Git 和工作区终端,但没有 Electron 提供的两项控制服务。详细启动与访问边界见 桌面与浏览器。

源码导航

官方插件源码位于仓库根目录的 plugins/,通过共享包登记并随产品分发;用户插件位于 $MICA_HOME/plugins/。插件的使用与管理见插件指南。

应用入口

目录职责
apps/cli交互式终端、exec 与 app-server 入口,负责应用装配和会话任务编排。
apps/desktopElectron 外壳、Node Web 运行时与 React 工作区页面。
apps/config-web终端配置页面的浏览器宿主。
apps/website产品网站与使用文档。

共享包

packages 下的包职责
mica-agent模型适配、提示词与工具调用循环,不依赖界面。
mica-runtime运行状态、事件与协议契约,供不同入口协作。
mica-tools / mica-mcp统一工具注册与 MCP 连接生命周期。
mica-config / mica-session配置、模型规则、使用偏好与会话存储。
mica-context本地清理与模型摘要压缩。
mica-commands / mica-builtin-commands命令机制、产品命令与官方运行期扩展。
mica-plugin / mica-skills插件生命周期与 Skills 的发现、解析和缓存。
mica-official-plugins随产品分发的官方插件清单与入口登记。
mica-ui / mica-ptyInk 终端界面与 Node helper 承载的 PTY 能力。
mica-common / mica-web-shared / mica-file-mentions跨入口复用的纯逻辑、Web 状态约定与文件引用。
mica-config-ui终端配置页与桌面设置共用的配置界面。

共享包保持单向依赖:模型层不调用 UI,UI 不直接请求 provider,应用入口负责组合它们。构建自己的集成时优先使用公开包入口,避免依赖应用内部单例。

构建与验证

在仓库根目录执行:

TERMINAL
bun install
bun run dev
bun run typecheck
bun run test -- path/to/relevant.test.ts
bun run build

根测试套件使用 Vitest,需通过 bun run test 调用。CLI 构建会编译程序、生成配置页资源,并安装本机入口;PTY 工具还会通过 Node helper 加载随包的原生依赖。

桌面应用有独立的 npm 构建与验证命令,见 桌面源码启动指南。协议集成见 自动化与协议;深入实现时可阅读 Headless 执行层设计 与 共享包索引。

文档随项目持续更新编辑此页