架构概览
Mica 将模型、工具、会话和界面分层。终端、自动化与桌面围绕共享能力构建,让不同入口拥有一致的模型连接与工具行为。
需要追踪模块之间的调用关系时,打开 交互式架构图,查看 CLI 与 Desktop 的运行时地图,搜索节点并沿依赖路径定位。
从输入到完成任务
- 入口接收任务。终端界面、
exec或 app-server 收到输入,确定工作目录、会话、模型与角色。 - 构建模型上下文。加入项目指令、Skills 索引、工具定义和会话历史,通过所选 provider 的协议发送请求。
- 迭代调用工具。模型可以读写文件、执行命令或调用 MCP,工具结果进入下一次模型请求。独立的只读调用可并行处理,写入与执行操作保留顺序边界。
- 持续反馈和保存。界面或协议接收文本、工具状态与用量;保存的会话可在后续任务中恢复。
交互式终端与 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/desktop | Electron 外壳、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-pty | Ink 终端界面与 Node helper 承载的 PTY 能力。 |
mica-common / mica-web-shared / mica-file-mentions | 跨入口复用的纯逻辑、Web 状态约定与文件引用。 |
mica-config-ui | 终端配置页与桌面设置共用的配置界面。 |
共享包保持单向依赖:模型层不调用 UI,UI 不直接请求 provider,应用入口负责组合它们。构建自己的集成时优先使用公开包入口,避免依赖应用内部单例。
构建与验证
在仓库根目录执行:
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 执行层设计 与 共享包索引。